[antoinetoussaint-byte]

A captured hop stamp could be moved from a read procedure to a write, and composed workloads could fabricate stamps using the shared run proof. This replaces that admission contract in Go, Python and TypeScript.

The hop signs the exact procedure, audience, token digest, fresh 256-bit nonce and a maximum 30-second validity window using a service-scoped Ed25519 seed. Verifiers authenticate those bindings and the Work Context, then atomically consume the nonce through a mandatory shared durable replay store before entering the handler. HTTP, Connect, unary gRPC and streaming paths are covered. Single-use capabilities are still consumed only by the hop's live Check; downstream consumes the separate admission nonce.

This is intentionally breaking: no shared-proof or method-less admission remains. Advisory policy refusals cannot be signed, and legacy warning mode is refused. The libraries reuse Core's ReplayStore contract, with no implicit per-replica memory fallback.

Merged with main (PR #26)

Both PRs reworked the module-side verifier, and the merge keeps both behaviours rather than choosing one. #26's Connect routing, bare-token verification and typed caller-safe refusals all survive; #28's signed admission replaces the shared hop/PROOF secret everywhere. Concretely: the identity readers lose their proof argument, #26's refusal scheme now covers #28's admission failures (stamp_method, stamp_audience, stamp_window, stamp_issued, stamp_advisory, stamp_replayed, stamp_store), and NewTokenVerifier/VerifyToken remain as the bare-token path — a process that receives no hop calls supplies neither the hop public key nor a replay store, and Verify refuses with configuration. Every Go module keeps one core pin, v0.19.7-0.20261026092055-b23dc13543b2 (canonical base64url decoding).

Security review r164

An independent review of 33c436b found one blocker, two majors and six medium findings. All but the key producer are addressed here.

• Admission window judged at call start. grpc-go decodes a unary request fully before the unary interceptor runs, so a module serving large or slow uploads refused admissions the authority had granted. Verifier.StatsHandler (with grpc.StatsHandler) records the arrival instant when gRPC tags the call and reserves the nonce then, and the window is judged against it — once, in all three languages. (It replaced TapHandle in round 4, see below.)
• A two-second clock allowance (stamp.Skew, SKEW), applied identically in Go, Python and TypeScript. A verifier running behind no longer refuses genuine calls at second boundaries, and being issued too far ahead has its own reason rather than reading as an expiry. The signed span is still capped at 30 seconds exactly.
• REST behind the hop is refused at startup. A REST face transcoded into a module's gRPC or Connect listener can never be admitted: the hop signs VERB /path while that listener observes the full procedure, and a module cannot verify at both layers. routing.Validate refuses such a composition (routing.ErrTranscodedREST) instead of refusing every REST call at runtime. Native HTTP faces are unaffected.
• A deployable replay store. libraries/hop/go/replaypg reserves nonces in a module's own Postgres, and the console composes one (modules/console/services/store). hop-verification/REPLAY_DIRECTORY is gone — Codefly delivers a store, not a shared volume, and an absolute path to per-pod storage looked identical to a shared mount. Outside a local run NewVerifier now refuses a store that does not declare itself shared.
• One identity-only reader per language. AuthenticateToken / authenticate_token / authenticateToken. The header-taking variants are gone: after the proof's removal they accepted any token plus a self-computed digest, so a caller fixing a build break by deleting the argument lost admission silently.

Security review round 3 (073a40e): B1, M1, M2, M3

B1 — the hop's admission key is published through Keys (owner's decision; code first, the handbook proposal follows).

• codefly.dev/authority@0.3.2 (additive; consumers declaring >=0.2.0 <0.4.0 admit it): KeysResponse.admission_keys and PublicKey.purpose. Admission keys (purpose hop-admission) are a field of their own beside the Work Context keys (purpose work-context), so a verifier that reads keys alone — an earlier release, or the JSON Web Key Set — can never trust a hop key to sign a Work Context. Regenerated only through Codefly: codefly generate proto in the local service, then codefly generate client --no-facade for authority-client (CLI v0.1.215, whose Python template resolves protovalidate). tools/noproxygate/generated.json records the five regenerated Go files.
• The local authority derives the public half from the hop's own hop-signing/SEED — replaced in round 4 by the hop's registration (below).
• Go, Python and TypeScript verifiers take the admission keys from the Keys read they already cache and refresh. hop-verification/PUBLIC_KEY, the publicKey/public_key constructor arguments and the playground's empty hop-verification.env are deleted. Every published key is trusted, so a rotation overlaps. A stamp signed by no published key is refused as stamp_proof and starts no key read (review r44's "an unauthenticated caller neither reads nor starves the keys" still holds); a verifier holding no trusted keys reads them at most once per keyRetry, as readiness does. An authority that publishes no admission key leaves every call refused as keys_unavailable, and the key error says why (ErrNoAdmissionKeys / NoAdmissionKeys). Each key is used for its own purpose only.
• Tests: TestAVerifierTakesTheHopsKeyFromTheAuthoritysKeysAlone, TestAStampSignedByAnUnpublishedKeyIsRefusedByName, TestARotationsOverlapAdmitsBothKeysUntilTheRetiringOneIsWithdrawn, TestAKeyIsUsedForItsOwnPurposeOnly, TestNoPublishedAdmissionKeyRefusesEveryCallAndSaysWhy (hop/go); TestSignedByNamesThePublishedKeyAProofIsSignedBy, TestAdmissionIsTheSignersStablePublishedEntry (stamp); TestTheHopsAdmissionKeyIsDerivedFromItsSeedAndPublished, TestAMalformedHopSeedRefusesToBoot (local); the console's arrival tests start a verifier from published keys alone; the same five cases in Python and TypeScript.
• (Superseded in round 4: the local authority no longer derives the key; the hop registers it.)

M1 — the window is judged at arrival on the Connect listener too. TapHandle is replaced by Verifier.StatsHandler: gRPC calls TagRPC in handleStream on every transport, including grpc.Server.ServeHTTP, which the generated Connect listener (vanguardgrpc) uses and where no tap handle runs. The console installs it. Tests (console, the real generated server, both listeners): TestALateBodyIsJudgedAtArrivalOnBothListeners (gRPC to the gRPC and to the Connect listener), TestALateConnectBodyIsJudgedAtArrival (Connect protocol), TestOneAdmissionOnBothListenersRunsOnce. With the stats handler removed, all three late-body cases fail as stamp_window.

M2 — crashed holders leave no permanent row. replaypg.Collect deletes every reservation whose expiry plus allowance has passed by the database clock, active or not: Reserve refuses past retention on that clock, so nothing is revived. Tests: TestACrashedHoldersReservationIsCollectedOnTheDatabaseClock (real Postgres; fails on the old statement), TestAReservationIsHeldToItsRetentionWhetherOrNotItsCallFinished, TestCollectingARunningCallsReservationReopensNothing (transport + Postgres).

M3 — Python reservation-store parity. A store is reservation-capable only with both reserve and finish (reserve_async/finish_async on the async path), as TypeScript requires. Test: test_a_store_with_reserve_but_no_finish_is_consumed_not_reserved (fails without the fix).

Merged with main twice: #30 (local setup) and #7 (installation-scoped grants), then #31 (one destination per service; its rule kept, both routing test sets kept).

A codefly run of the playground was not verified in round 3; round 4 below has a live run.

Security review round 4 (2552d5c): B1' and N1

B1' — the hop registers its admission key; the local authority derives nothing (coordinator's decision). The local authority read hop-signing/SEED for the hop, a secret no composed run delivers to it (it cannot depend on the hop, which depends on it), so the playground published no admission key and the console refused every call as keys_unavailable.

• codefly.dev/authority@0.3.3 (additive; >=0.2.0 <0.4.0 consumers admit it) adds RegisterAdmissionKey(actor, public_key) → (key, expires_at_unix). Regenerated only through Codefly v0.1.215 (generate proto in the local service, generate client --no-facade for authority-client); tools/noproxygate/generated.json records the five regenerated Go files.
• The hop declares module-identity, so the run vouches for it, and registers its public half under its own workload credential (hop.Registration.Keep, libraries/hop/go/register.go): at boot, then renewing at a quarter of each lease, every 5 s after a failure, logging each change of outcome. The seed never leaves the hop.
• The local authority attests the caller and refuses any workload but authority/hop by name (the caller is console/api, not the hop (authority/hop)), then publishes the key in Keys.admission_keys (purpose hop-admission) until its lease (AdmissionLease, 2 min) lapses. Re-registration renews one entry (a restarted hop is idempotent; a restarted authority learns the key at the next renewal, ≤30 s); a rotation publishes both keys while both are renewed; a key no running hop renews is withdrawn. At most 8 keys are published at once (refused by name past that). stamp.KeyID is the one key-id derivation. hopAdmissionKey, its tests and the seed read are deleted.
• A verifier whose last read published no admission key (it read before the hop registered) re-reads on the next call or readiness check, at most once per keyRetry, instead of waiting out keyMaxAge — Go, Python and TypeScript alike. Callers inside keyRetry still drive no read.
• Tests: TestTheHopsRegisteredKeyIsPublishedInKeys, TestANonHopCallerIsRefusedByName, TestReRegistrationAtRestartIsIdempotent, TestARotationOverlapsUntilTheRetiringKeyLapses, TestThePublishedAdmissionKeysAreBounded (local issuer); TestUnderThePlaygroundsIdentityTheHopsRegisteredKeyAdmitsItsStamps (local, over the wire: the hop's process environment as the playground run gives it — workspace authority-playground, authority/hop, its own seed, its projected credential — and none of it on the authority; Keys is empty before, publishes the hop's key after, a genuine stamp is signed by the published key and checks, an impostor's is not, documents is refused by name); TestTheHopKeepsItsPublicKeyRegisteredUnderItsCredential, TestARefusedRegistrationIsReportedAndRetried, TestAVerifierThatReadBeforeTheHopRegisteredLearnsItsKeyWithinKeyRetry (hop/go; fails without the re-read); the same verifier case in Python and TypeScript (each fails without its fix). The module-side Go verifier links the authority-client bindings of the same protos, which cannot share a test binary with the local service's own, so the verifier half of the end to end is driven from Keys in its module and proven in the live run below.
• Follow-up, not in this PR: SaaS accounts implementing RegisterAdmissionKey (attest the hop's workload, publish what it registers). Until it does, a hop fronting modules on a cell logs that its key is not published and those modules refuse every admission as keys_unavailable. The handbook record of the 0.3.3 interface follows the code.
• Rotation note: a verifier learns a new key within keyMaxAge (a stamp by an unknown key starts no read), so start a hop with the new seed that long before calls are routed to it, while a hop with the retiring seed keeps renewing the retiring key (libraries/hop/README.md).

N1 — collection cannot revive a nonce near expiry. replaypg.Collect deletes only rows CollectMargin (1 min) past their retention by the database clock, so a collection committing between Reserve's clock check and its insert finds nothing to delete. Tests (real Postgres): TestACrashedHoldersReservationIsCollectedOnTheDatabaseClock (a row 61 s past is collected, 30 s past is kept), TestConcurrentCollectionNeverRevivesANonceNearItsExpiry (20 rounds of Collect racing Reserve across expiry: never admitted, never collected inside the margin); both fail on the old statement. The transport regressions age the row by the margin before collecting.

Live run (codefly v0.1.215, --naming-scope fix28r5, 2026-10-26). The repo's playground/ does not load on this CLI, independent of this PR: records 0.5.0 ships no module.contract.codefly.yaml, so generating hop routes fails (hop routes for records: openat module.contract.codefly.yaml), and 0.6.0 renamed the module record-store. So I ran a scratch copy of the playground workspace composing authority and console from this checkout, with the hop fronting the console only and no edge routes (codefly run service console/api authority/hop --local-agents --naming-scope fix28r5); nothing about the hop was configured on the authority. Observed:

• hop log: the authority publishes this hop's admission key; Keys on the local authority: admissionKeys: [hop-67d0eb32a0bbae3a, purpose hop-admission].
• Maya's Work Context, WhoAmI through the hop: maya, human, acme, console.identity:read (the console's verifier accepted the hop's genuine stamp); Version: 0.1.0.
• Maya's Work Context straight to the console: stamp_proof. No Work Context through the hop: refused.
• RegisterAdmissionKey under the console's own projected credential: PermissionDenied: the caller is console/api, not the hop (authority/hop); with no credential: refused; Keys still publishes one key.
• Not observed live: an authority restart (a touched file did not trigger a reload), covered by the unit tests.

Docs updated

• libraries/hop/README.md — the wire contract: the clock allowance, the window judged at arrival (the stats handler, both listeners), the transcoded-REST refusal, the Postgres store, collection and the startup guard, "Delivering the verification key" (published in Keys, rotation overlap, the accounts follow-up), and the adoption order.
• libraries/hop/go/README.md — the module-side example, now with replaypg, no key, and grpc.StatsHandler.
• README.md — the 0.3.2 and 0.3.3 interface notes.
• libraries/authority-client/python/README.md, libraries/authority-client/typescript/README.md — the single identity reader, the admission reason codes, and construction without a hop key or replay store.
• modules/console/services/store/README.md — new: why the console composes a store.
• playground/configurations/README.md — no hop key is configured; the hop registers it; hop-verification.env is deleted.
• libraries/hop/README.md — the hop's registration, the re-read while no key is published, the rotation procedure, the collection margin.
• modules/authority/services/hop/service.codefly.yaml — module-identity: true. modules/authority/services/local/service.codefly.yaml — nothing about the hop is read.
• modules/console/services/api/service.codefly.yaml, modules/console/module.codefly.yaml — the store dependency; the hop-verification group is gone. modules/authority/services/local/service.codefly.yaml — what the local authority reads to publish the hop's key.

Validation

• go vet and go test -race -count=1 pass in all 11 Go modules, including tools/noproxygate, with HOP_TEST_POSTGRES on a local Postgres 17 (the transport and store regressions ran); go mod tidy -diff and gofmt clean (round 4 at b9b716b; the hop service re-run at 655fe4f).
• Python: 332 passed. TypeScript: 178 passed.
• Regression probes cover read-to-delete retargeting, fabricated shared proofs with genuine capabilities, wrong audiences, single-use replay across verifier instances, concurrent replay, expiry, duplicate metadata, replay-store failures, persistent reservations, the arrival-instant window, the clock allowance in three languages, retention past expiry, and the transcoded-REST refusal.

Addresses the admission gap reported in module-robin #512 finding 2 and module-evaluation #91 finding 1; related authority issue #5. Downstream owners must adopt the breaking API (no key argument; install StatsHandler), have their authority implement RegisterAdmissionKey and publish what the hop registers, and supply a durable replay backend shared by every replica.

🤖 Generated with Claude Code

[antoinetoussaint-byte]

lazybox has finished working on this. claude (Opus 5) held it from 2026-11-02 15:18 UTC until 2026-11-02 15:47 UTC. The working label has been removed; this comment is the record.

claim detail

Lazybox-Claim-Device: effacd542b611010656e
Lazybox-Claim-Session: e1b4aa4bd6
Lazybox-Claim-Workspace: github-codefly-dev-authority-28
Lazybox-Claim-Agent: claude
Lazybox-Claim-Model: Opus 5
Lazybox-Claim-Started: 2026-11-02T15:18:53Z
Lazybox-Claim-Heartbeat: 2026-11-02T15:47:54Z
Lazybox-Claim-Expires: 2026-11-02T16:18:53Z
Lazybox-Claim-Released: 2026-11-02T15:47:54Z