Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CONFORMANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,3 +94,7 @@ Pages avoid full-log/category/sales-history copies, but sparse filters can scan
the remaining catalogue. Existing unpaged reads remain unbounded; in-memory,
single-writer and witnessing limitations remain unchanged. See
`docs/marketplace-browse.md` for query syntax and compatibility limits.

### Witness key-file custody

`witnessd -seed-file` checks regular-file type, effective-user ownership, owner-only permissions, and macOS extended ACLs on the opened file before reading a bounded hexadecimal seed. Unsupported platform/build access checks fail closed. `TestWitnessSeedFileIdentity`, `TestWitnessSeedFileRejectsUnsafeInput`, `TestWitnessSeedFileRejectsSymlink`, `TestWitnessSeedFileRejectsACL` (macOS), and `TestWitnessSeedCompatibility` bind stable public identity, startup refusal, private-material exclusion from diagnostics, and legacy/demo behavior. This persists key identity only: rollback memory remains ephemeral, trust on first checkpoint remains, and no federation or registry is introduced.
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -165,3 +165,5 @@ independent witnessing.
AGPL-3.0-or-later.

*Network Theory Applied Research Institute, Inc. — 501(c)(3) — EIN 92-3047136 — info@ntari.org*

Witness operators: use [`witnessd -seed-file`](docs/witness-seed-files.md) for persistent identity without placing private seed material in process arguments.
33 changes: 16 additions & 17 deletions cmd/witnessd/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,6 @@
package main

import (
"crypto/ed25519"
"crypto/rand"
"encoding/hex"
"flag"
"log"
Expand All @@ -28,23 +26,24 @@ func main() {
relayURL := flag.String("relay", "http://localhost:8090", "witness relay base URL")
intakeAddr := flag.String("intake", ":8091", "listen address for the filing intake")
interval := flag.Duration("interval", 30*time.Second, "poll interval")
seedHex := flag.String("seed", "", "hex ed25519 seed (32 bytes); ephemeral when empty — ephemeral witnesses forget, use a persistent seed in anything but a demo")
seedHex := flag.String("seed", "", "DEPRECATED: hex ed25519 seed; use -seed-file to keep secrets out of process arguments")
seedFile := flag.String("seed-file", "", "protected file containing 64 hex seed digits; Linux/macOS owner-only permissions required")
flag.Parse()

var priv ed25519.PrivateKey
if *seedHex == "" {
_, p, err := ed25519.GenerateKey(rand.Reader)
if err != nil {
log.Fatalf("witnessd: generating key: %v", err)
}
priv = p
log.Printf("witnessd: EPHEMERAL key (amnesia on restart is total); pass -seed for anything beyond a demo")
} else {
seed, err := hex.DecodeString(*seedHex)
if err != nil || len(seed) != ed25519.SeedSize {
log.Fatalf("witnessd: -seed must be %d hex bytes", ed25519.SeedSize)
flag.Visit(func(f *flag.Flag) {
if f.Name == "seed-file" && f.Value.String() == "" {
log.Fatal("witnessd: -seed-file must not be empty")
}
priv = ed25519.NewKeyFromSeed(seed)
})

priv, err := witnessKey(*seedHex, *seedFile)
if err != nil {
log.Fatalf("witnessd: %v", err)
}
if *seedHex != "" {
log.Print("witnessd: -seed is deprecated; migrate to -seed-file to avoid process-argument and shell-history exposure")
}
if *seedHex == "" && *seedFile == "" {
log.Print("witnessd: EPHEMERAL key (amnesia on restart is total); use -seed-file for a persistent identity beyond a demo")
}

w := witnesskit.NewWorker(priv, *relayURL)
Expand Down
50 changes: 50 additions & 0 deletions cmd/witnessd/seed.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
package main

import (
"crypto/ed25519"
"crypto/rand"
"encoding/hex"
"errors"
"io"
"strings"
)

// witnessKey never includes input bytes or paths in diagnostics.
func witnessKey(seedHex, seedPath string) (ed25519.PrivateKey, error) {
if seedHex != "" && seedPath != "" {
return nil, errors.New("-seed and -seed-file are mutually exclusive")
}
if seedPath != "" {
var err error
seedHex, err = readSeedHex(seedPath)
if err != nil {
return nil, err
}
}

if seedHex == "" && seedPath == "" {
_, priv, err := ed25519.GenerateKey(rand.Reader)
return priv, err
}
seed, err := hex.DecodeString(seedHex)
if err != nil || len(seed) != ed25519.SeedSize {
return nil, errors.New("seed must contain exactly 64 hex digits")
}
return ed25519.NewKeyFromSeed(seed), nil
}

func readSeedHex(path string) (string, error) {
file, err := openSeedFile(path)
if err != nil {
return "", err
}
defer func() { _ = file.Close() }()
data, err := io.ReadAll(io.LimitReader(file, 67))
if err != nil {
return "", errors.New("cannot read -seed-file")
}
if len(data) > 66 {
return "", errors.New("-seed-file must contain 64 hex digits with optional newline")
}
return strings.TrimSuffix(strings.TrimSuffix(string(data), "\n"), "\r"), nil
}
38 changes: 38 additions & 0 deletions cmd/witnessd/seed_acl_darwin.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
//go:build cgo

package main

/*
#include <sys/acl.h>
*/
import "C"

import (
"errors"
"os"
"syscall"
"unsafe"
)

// Darwin mode bits omit ACL read grants. Query the opened descriptor directly;
// reject all extended ACLs rather than interpret inherited grants.
func checkSeedACL(file *os.File) error {

acl, err := C.acl_get_fd_np(C.int(file.Fd()), C.ACL_TYPE_EXTENDED)
if acl == nil {
if errors.Is(err, syscall.ENOENT) {
return nil
}
return errors.New("cannot verify -seed-file macOS ACL")
}
defer func() { _, _ = C.acl_free(unsafe.Pointer(acl)) }()
var entry C.acl_entry_t
status, err := C.acl_get_entry(acl, C.ACL_FIRST_ENTRY, &entry)
if status == 0 {
return errors.New("-seed-file must have no extended ACL; remove grants with chmod -N")
}
if errors.Is(err, syscall.EINVAL) {
return nil
} // Valid ACL with no first entry.
return errors.New("cannot inspect -seed-file macOS ACL")
}
19 changes: 19 additions & 0 deletions cmd/witnessd/seed_acl_darwin_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
package main

import (
"os/exec"
"strings"
"testing"
)

// macOS ACL read grants are not reflected in mode bits.
func TestWitnessSeedFileRejectsACL(t *testing.T) {
path := writeSeed(t, testSeed, 0600)
if out, err := exec.Command("/bin/chmod", "+a", "everyone allow read", path).CombinedOutput(); err != nil {
t.Fatalf("set fixture ACL: %v %s", err, out)
}
out := startup(t, seedDaemon(t), "-seed-file", path)
if strings.Contains(out, "witness key ") || !strings.Contains(out, "ACL") {
t.Fatalf("readable ACL accepted: %s", out)
}
}
7 changes: 7 additions & 0 deletions cmd/witnessd/seed_acl_linux.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
package main

import "os"

// Linux POSIX ACL permissions are bounded by the group-class mode mask,
// already required to be zero by openSeedFile.
func checkSeedACL(_ *os.File) error { return nil }
12 changes: 12 additions & 0 deletions cmd/witnessd/seed_acl_nocgo_darwin.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
//go:build !cgo

package main

import (
"errors"
"os"
)

func checkSeedACL(_ *os.File) error {
return errors.New("-seed-file requires a cgo-enabled macOS build to check ACLs; refusing unchecked access")
}
12 changes: 12 additions & 0 deletions cmd/witnessd/seed_other.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
//go:build !darwin && !linux

package main

import (
"errors"
"os"
)

func openSeedFile(_ string) (*os.File, error) {
return nil, errors.New("-seed-file permission checks are supported only on Linux and macOS; refusing unchecked access")
}
139 changes: 139 additions & 0 deletions cmd/witnessd/seed_startup_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
package main

import (
"context"
"os"
"os/exec"
"path/filepath"
"runtime"
"strings"
"testing"
"time"
)

const seedFileFlag = "-seed-file"
const keyLogPrefix = "witness key "
const daemonErrorPrefix = "witnessd:"

const testSeed = "9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60"
const testPublicKey = "d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a"

func seedDaemon(t *testing.T) string {
t.Helper()
binary := filepath.Join(t.TempDir(), "witnessd")
if runtime.GOOS == "windows" {
binary += ".exe"
}
if out, err := exec.Command("go", "build", "-o", binary, ".").CombinedOutput(); err != nil {
t.Fatalf("build: %v: %s", err, out)
}
return binary
}

func startup(t *testing.T, binary string, args ...string) string {
t.Helper()
ctx, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()
args = append([]string{"-relay", "http://127.0.0.1:1", "-intake", "127.0.0.1:0", "-interval", "1h"}, args...)
out, _ := exec.CommandContext(ctx, binary, args...).CombinedOutput()
return string(out)
}

func writeSeed(t *testing.T, content string, mode os.FileMode) string {
t.Helper()
path := filepath.Join(t.TempDir(), "witness.seed")
if err := os.WriteFile(path, []byte(content), mode); err != nil {
t.Fatal(err)
}
return path
}

// Catches ignored file input, unstable identity, and secret disclosure at startup.
func TestWitnessSeedFileIdentity(t *testing.T) {
if runtime.GOOS != "darwin" && runtime.GOOS != "linux" {
t.Skip("protected files supported on Linux and macOS")
}
binary := seedDaemon(t)
path := writeSeed(t, testSeed+"\n", 0600)
for i := 0; i < 2; i++ {
out := startup(t, binary, seedFileFlag, path)
if !strings.Contains(out, keyLogPrefix+testPublicKey) {
t.Fatalf("persistent identity missing: %s", out)
}
if strings.Contains(out, testSeed) || strings.Contains(out, "EPHEMERAL") {
t.Fatal("secret leaked or persistent input ignored")
}
}
}

// Catches falling back to an ephemeral key after an invalid persistent input.
func TestWitnessSeedFileRejectsUnsafeInput(t *testing.T) {
binary := seedDaemon(t)
cases := []struct {
name, content string
mode os.FileMode
}{
{"bad hex", strings.Repeat("z", 64), 0600},
{"short", "ab", 0600},
{"oversized", strings.Repeat("a", 4096), 0600},
{"group readable", testSeed, 0640},
{"world readable", testSeed, 0604},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
out := startup(t, binary, seedFileFlag, writeSeed(t, tc.content, tc.mode))
if !strings.Contains(out, daemonErrorPrefix) || strings.Contains(out, keyLogPrefix) || strings.Contains(out, "EPHEMERAL") {
t.Fatalf("expected startup rejection: %s", out)
}
if strings.Contains(out, tc.content) {
t.Fatal("seed content leaked")
}
})
}
for name, path := range map[string]string{"missing": filepath.Join(t.TempDir(), "absent"), "directory": t.TempDir()} {
t.Run(name, func(t *testing.T) {
out := startup(t, binary, seedFileFlag, path)
if !strings.Contains(out, daemonErrorPrefix) || strings.Contains(out, keyLogPrefix) {
t.Fatalf("expected rejection: %s", out)
}
})
}
}

func TestWitnessSeedFileRejectsSymlink(t *testing.T) {
if runtime.GOOS != "darwin" && runtime.GOOS != "linux" {
t.Skip("Unix symlink policy")
}
binary := seedDaemon(t)
path := writeSeed(t, testSeed, 0600)
link := filepath.Join(t.TempDir(), "link")
if err := os.Symlink(path, link); err != nil {
t.Fatal(err)
}
out := startup(t, binary, seedFileFlag, link)
if !strings.Contains(out, daemonErrorPrefix) || strings.Contains(out, keyLogPrefix) {
t.Fatalf("expected symlink rejection: %s", out)
}
}

func TestWitnessSeedCompatibility(t *testing.T) {
binary := seedDaemon(t)
t.Run("legacy", func(t *testing.T) {
out := startup(t, binary, "-seed", testSeed)
if !strings.Contains(out, keyLogPrefix+testPublicKey) || !strings.Contains(out, "deprecated") || strings.Contains(out, testSeed) {
t.Fatalf("legacy migration behavior incorrect: %s", out)
}
})
t.Run("demo", func(t *testing.T) {
out := startup(t, binary)
if !strings.Contains(out, "EPHEMERAL") || !strings.Contains(out, keyLogPrefix) {
t.Fatalf("demo key missing: %s", out)
}
})
t.Run("conflict", func(t *testing.T) {
out := startup(t, binary, "-seed", testSeed, seedFileFlag, writeSeed(t, testSeed, 0600))
if !strings.Contains(out, "mutually exclusive") || strings.Contains(out, testSeed) || strings.Contains(out, keyLogPrefix) {
t.Fatalf("conflicting options accepted: %s", out)
}
})
}
33 changes: 33 additions & 0 deletions cmd/witnessd/seed_unix.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
//go:build darwin || linux

package main

import (
"errors"
"os"
"syscall"
)

// Inspect the opened descriptor so permission checks and reads name the same
// file. Nonblocking/no-follow opens reject FIFOs and final-component symlinks.
func openSeedFile(path string) (*os.File, error) {
file, err := os.OpenFile(path, os.O_RDONLY|syscall.O_NOFOLLOW|syscall.O_NONBLOCK, 0)
if err != nil {
return nil, errors.New("cannot open -seed-file (regular file required; symlinks refused)")
}
info, err := file.Stat()
if err != nil || !info.Mode().IsRegular() || info.Mode().Perm()&0077 != 0 {
_ = file.Close()
return nil, errors.New("-seed-file must be a regular owner-only file (chmod 600)")
}
stat, ok := info.Sys().(*syscall.Stat_t)
if !ok || stat.Uid != uint32(os.Geteuid()) {
_ = file.Close()
return nil, errors.New("-seed-file must be owned by the current user")
}
if err := checkSeedACL(file); err != nil {
_ = file.Close()
return nil, err
}
return file, nil
}
13 changes: 13 additions & 0 deletions docs/witness-seed-files.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Persistent witness identity without secret command arguments

Run `witnessd -seed-file /protected/path/witness.seed`. The file must contain exactly 64 hexadecimal digits encoding a 32-byte Ed25519 seed, optionally followed by LF or CRLF. Provision it through a protected editor or secret-management tool; never paste its contents into a shell command. Keep its directory protected as well.

On Linux and macOS the file must be regular, owned by the effective user, and have no group or other permission bits (`chmod 600`). A read-only owner file (`400`) also works. Final-component symlinks and non-regular files are refused. Validation and bounded reading use the same opened descriptor. Files with malformed or oversized contents fail startup instead of generating a replacement identity. Diagnostics omit both seed contents and paths.

Linux POSIX ACL grants are bounded by the group-class mode mask, which must be zero. On macOS, mode bits alone do not cover extended ACL grants: the daemon queries the native descriptor ACL and rejects any extended ACL. Remove unwanted grants with `chmod -N /protected/path/witness.seed` and recheck permissions. macOS protected loading requires a cgo-enabled build; a build without cgo fails closed. Other operating systems also refuse `-seed-file` until their access-control checks are implemented. No permission changes are made by the daemon.

Loading the same file retains the same public witness identity across restarts. The public key can still appear in startup logs; seed bytes do not.

`-seed` remains available for compatibility but prints a deprecation warning; migrate persistent deployments to `-seed-file`. There is no scheduled removal in this change. Passing both nonempty options is rejected. An explicitly empty `-seed-file` is also rejected. With neither option, the daemon retains its explicitly logged **EPHEMERAL** demo behavior.

Persistent key identity does **not** persist rollback memory or filing records, repair witness amnesia, create federation, or establish a key registry. The existing trust-on-first-checkpoint and single-witness limitations remain.