[security] Reserve spike/system/* from substring policy matches

[v0lkan]

Attribution

Reported by @kanywst, who followed the private disclosure process in SECURITY.md and included a reproduction that ran cleanly against the tree. Their report concerned unanchored policy patterns matching on substrings, which is documented and intended behavior. Assessing it surfaced something that was not: the same matcher gates spike/system/acl, so a pattern like spike reached policy management by accident. This PR takes a different fix than the one proposed, but the finding underneath belongs to them.

Thank you for reporting it carefully and privately.

Reviewer orientation

123 files sounds worse than it is. 99 of them are the regenerated static
site under docs/, which is mechanical output.

Surface	Files	Review?
Code, docs source, specs, examples	24	Yes
Rendered site (docs/, make docs)	99	Skim

The whole review is really four files:

• app/nexus/internal/state/base/reserved.go (new) — the guard
• app/nexus/internal/state/base/policy.go — two call sites
• app/nexus/internal/state/base/reserved_test.go (new) — 11 tests
• docs-src/content/usage/commands/policy.md — the rewritten guidance

This PR contains two independent pieces of work in one commit. They are
unrelated. Part 2 had been sitting uncommitted in the working tree since
2026-07-18, and folding it in beat stranding it further behind an
unrelated branch. Both are described below; review them separately.

---

Part 1: reserved system namespaces

Spec: specs/policy-pattern-anchoring.md · ADR: adr-0033

The problem

Policy patterns are regular expressions matched with MatchString, so an
unanchored pattern is a substring test. That is intended, documented
behavior for ordinary paths and it does not change here.

It was not acceptable for the three paths through which SPIKE authorizes
its own privileged operations. Policy management is gated by
CheckPolicyAccess(peer, "spike/system/acl", [write]). A policy whose
PathPattern was spike, system, or acl therefore matched that gate
by substring and authorized the workload to create and modify any
policy, including one granting itself super on every path.
PathPattern: "spike" is a plausible thing to write when your own
secrets live under a spike/ namespace. The same reached
spike/system/secret and spike/system/cipher/exec. Nothing reserved
those namespaces.

The identity side compounds it: a delegation written for
spiffe://example\.org/admin without anchors also admits
spiffe://example.org/admin-attacker.

The fix

A policy may reach a reserved path only when it describes that path
rather than merely containing it. The test is semantic, not syntactic: a
pattern describes a path when its full-match form, ^(?:pattern)$, still
matches.

Pattern	Reaches spike/system/acl?
^spike/system/acl$	Yes, deliberate
spike/system/acl	Yes, deliberate
^spike/system/.*$	Yes, deliberate
.*	Yes, deliberate
acl	No, substring only
system	No, substring only
spike	No, substring only

The SPIFFE ID pattern must additionally be anchored, or be an
unambiguous catch-all such as .*.

Ordinary paths are untouched and keep plain substring semantics.

Two things worth pushing back on in review

Why the guard is in two places. UpsertPolicy rejects a violating
policy at authoring time, and CheckPolicyAccess declines to honor one
independently. The second is not redundant. The SQLite backend
(sqlite/persist/regex.go) recompiles both patterns from the stored
strings on every access check, so a guard placed only at creation holds
for the in-memory backend and does nothing in production. There is a
regression test that fails without it
(TestCheckPolicyAccess_ReservedGuardHoldsUnderSQLite).

Why not just anchor everything. Blanket-wrapping both patterns in
^(?:...)$ at compile time was the obvious fix and is wrong twice over.
It converts a working prefix policy like ^tenants/acme/ into
^(?:^tenants/acme/)$, which matches nothing usable — a silent access
revocation on upgrade, with no error naming the cause; this repo ships
eight such ^-only patterns. It also redefines PathPattern from "a
regular expression" into "a regular expression that is implicitly
full-match", silently reinterpreting every policy users have written. A
purely syntactic "must start with ^, end with $" variant was
implemented first and also rejected: .* and ^.*$ are the same regular
expression, so accepting one and refusing the other polices spelling
without changing what is granted, and it broke the deliberate wildcard
policies already in the test suite.

Documentation

The guidance was self-contradictory, which is how a careful operator
could land on an unanchored pattern. Of 147 concrete pattern examples in
the repo, 88% were already anchored and three documents taught anchoring
correctly — but the gaps were in the worst places:

• usage/commands/policy.md had a "Path Pattern Examples" block of
  ^-only prefixes, one annotated # Only the specific creds resource
  for a pattern that also matches secrets/database/credsXYZ.
• Its "Common Errors" section offered unanchored patterns as the
  correct remediation.
• CLAUDE.md framed the only correctness axis as regex-versus-glob and
  marked two unanchored patterns as ✅ correct.
• examples/federation/workload-set-policies.sh shipped a literal glob
  (tenants/demo/db/*) with write permission.
• examples/policies/sample-policy.yaml used keys spiffeid:/path:
  that do not exist in PolicySpec; it could never have loaded.

All fixed, plus a new section stating plainly that patterns are matched
as substrings, that supplying anchors is the operator's responsibility,
and that patterns should be narrowed to the smallest workable set.

Rendered site

make docs was run. Beyond this PR's own changes it picks up the
Recipes section and the multi-tenancy page, neither of which had ever
been rendered, and drops ten orphaned pages under
docs/getting-started/ that had no source in docs-src. One of those
orphans was still serving the superseded policy guidance at a live URL.
build-docs.sh does cp -r public/* docs/, a merge that never deletes,
which is how they accumulated.

---

Part 2: live Pilot integration suite (Slice B)

Spec: specs/integration-tests.md

Written 2026-07-18, left uncommitted, unmodified here apart from being
re-verified. Adds app/spike/internal/cmd/integration, which drives the
built spike binary end to end against a running make start
environment rather than importing command internals.

Double-gated so it never runs in the normal suite: the integration
build tag keeps it out of ordinary builds, and TestMain exits early
unless SPIKE_INTEGRATION_TEST=1.

• TestPilotSmokePass — secret put/get/delete, policy create/get by
  name, cipher round trip; asserts data lands on stdout. Cleans up.
• TestPilotWarnsWhenNexusUnreachable — points one invocation at a
  closed port, leaving the running Nexus untouched, and asserts the
  Pilot warns without hanging or panicking. The no-hang assertion
  doubles as a guard on the open SVID-acquisition-timeout task.
• TestPilotDeniesWhenNexusUninitialized — destructive, gated behind a
  second flag SPIKE_INTEGRATION_DESTRUCTIVE=1. Reaching a
  reachable-but-uninitialized Nexus means killing Nexus and every Keeper
  and restarting Nexus alone. It kills the Nexus it spawned, which sits
  outside make start's process table and would otherwise hold the port
  past a Ctrl+C.

Both error paths funnel through stdout.HandleAPIError and exit 0 (the
subcommands use cobra Run, not RunE), so assertions key on the
stderr message and the no-hang property, not the exit code.

Adds make integration-test and make integration-test-destructive.

---

Test plan

• make lint-go — clean.
• make test — full suite, zero failures.
• The 11 new tests in reserved_test.go were verified to fail
  against a neutered guard and pass with it, so they are genuine
  regression tests rather than tautologies. Coverage includes both the
  memory and SQLite backends.
• Part 2 is invisible to both make test and make lint-go because of
  its build tag, so it was checked separately:
  go vet -tags=integration ./... and
  golangci-lint run --build-tags=integration ./..., both clean.

Compatibility

Behavior changes only for policies that reach a reserved system path
through an unanchored pattern. Those now fail loudly: UpsertPolicy
returns an error naming the reserved path and the required form, and the
runtime refusal is logged. Deliberate delegation continues to work,
spelled ^spike/system/acl$ with an anchored SPIFFE ID pattern.
Wildcard policies (.*, ^.*$) are unaffected.

Credit

Reported by kanywst. The substring
behavior they reported is documented and intended; the escalation path
underneath it was not, and was found while assessing the report.

Follow-ups (not in this PR)

• docs/internals/nil-source-handling-and-go-concurrency/index.html is
  also an orphan with no docs-src source. Left alone deliberately.
• CONTRIBUTING_DCO.md is broken: it is a near-duplicate of
  CONTRIBUTING.md that links to itself as "our Developer Certificate
  of Origin" and never states the DCO text or the Signed-off-by
  mechanics. A contributor following CONTRIBUTING.md:23 cannot learn
  what to do from it.
• build-docs.sh merges rather than syncs, so deleted pages linger in
  docs/ until someone notices. Worth an rsync --delete or a clean
  rebuild.

[github-actions]

Full Github Actions output