@sentropic/h2a 0.85.24 → 0.86.0

package/dist/runtime/enrollment/ceremony.js

@@ -0,0 +1,777 @@
+/**
+ * h2a's side of the PRINCIPAL↔AGENT enrollment ceremony (P1, step 3).
+ *
+ * Implements Part B of the ratified contract
+ * `docs/superpowers/specs/2026-07-24-h2a-feed-contract-for-sentropic.md`
+ * (RATIFIED by the sentropic architect 2026-07-24, amended 2026-07-25 and again
+ * 2026-07-25 by the SIGNED-COMPOSITE amendment recorded in Part B), and step 3 of
+ * `docs/specs/2026-07-25-p1-joint-plan-h2a-sessions-in-sentropic-ui.md`.
+ *
+ * AUTHORITY MODEL — read this before touching anything below.
+ * ----------------------------------------------------------
+ * **The 39-auth PRINCIPAL is the authorizing authority. This module only
+ * proves that the local agent controls its ed25519 key.** A valid signature
+ * proves *authorship* (this key produced this payload); it NEVER proves
+ * *authorization* (this key may appear in this principal's feed). Those are two
+ * different checks and the code keeps them structurally separate:
+ *
+ * - h2a produces a proof of key control. That is the whole of h2a's part.
+ * - sentropic decides what the proof authorizes, by looking up an ACTIVE
+ *   `(principalSub, agentPubKey)` binding row in ITS OWN store.
+ *
+ * **SIGNED ≠ AUTHORIZED.** The signature now covers `instance` as well as the
+ * nonce and the key (see {@link enrollmentProofSignedPayload}). That makes the
+ * *provenance* of `instance` trustworthy — it does **NOT** make `instance` an
+ * authorization input, and nothing downstream may start treating it as one.
+ * Authorization stays the active-binding lookup on
+ * `(principalSub, agentPubKey)`, with the instance re-resolved live at read time
+ * (Part B: `agentInstanceIdAtBinding` is "provenance only — NEVER re-used as
+ * authority at read time"). This is the same line as authorship ≠ authorization,
+ * one field further in: a signature widens what you may *believe about the
+ * payload*, never what the payload may *reach*.
+ *
+ * Four consequences that are load-bearing, not stylistic:
+ *
+ * 1. **No binding store here.** h2a has no concept of a 39-auth principal, so
+ *    it cannot own the binding record (`H2APrincipalAgentBinding` — Part B,
+ *    "Binding record": owned and stored by sentropic). Nothing in this module
+ *    writes, caches or reads a binding.
+ * 2. **The agent never receives a principal identifier at all.** The challenge
+ *    type has no `principalSub`, and the CLI refuses a challenge document that
+ *    carries one. The agent signs a nonce; it has no functional need for the
+ *    principal's id, and putting one into an agent process and context window
+ *    buys nothing. *Minimal disclosure beats verified non-retention* — so this
+ *    is enforced at receipt, not merely proven absent from the output.
+ * 3. **Every field the proof carries is signed.** A proof must attest to
+ *    everything it carries: a reader sees a signature and reasonably infers it
+ *    covers the payload, so an unsigned-but-present field is a claim wider than
+ *    its evidence — in the one artifact whose whole job is to be exactly as wide
+ *    as its evidence. If a field does not deserve signing, it must be REMOVED
+ *    from the proof rather than carried unsigned. Pinned by a test that derives
+ *    the covered set from the proof's own keys.
+ * 4. **No outward transport.** This module never opens a socket. Not behind a
+ *    flag, not behind a default-off flag. The proof is returned to the caller;
+ *    delivering it to the gateway is the gateway lane's step, and the seam for
+ *    it ({@link EnrollmentProofSubmitter}) has NO default implementation — an
+ *    unsupplied submitter is reported as such, never silently attempted.
+ *
+ * Per the amendment accepted after ratification (joint plan, finding 2),
+ * enrollment on the AUTH side requires an active **first-party session** and is
+ * deliberately unreachable by bearer tokens — otherwise any relying party the
+ * owner ever consented to could mint a durable binding for its own key,
+ * escalating "read the owner's data" into "permanently be the owner's agent".
+ * That gate is the auth lane's. Nothing here assumes, carries or accepts a
+ * bearer token; there is no credential input to this module at all.
+ *
+ * REUSE, not new crypto: `signCanonical` / `verifyCanonical`
+ * (`packages/h2a/src/signature.ts`) over the existing identity keypair at
+ * `<root>/keys/<instance>.key.pem` — the same primitive already used for reclaim
+ * proof-of-possession (`runtime/identity/live.ts` `provesLocalKey`,
+ * `runtime/identity/bindings.ts` `verifyReclaimProof`). `signCanonical` already
+ * takes `unknown`, so signing a composite is the same primitive with a different
+ * argument: no new key, no new algorithm, no new file, no extra round-trip.
+ *
+ * ONE EXCEPTION CONSIDERED AND REFUSED — recorded so nobody re-litigates it.
+ * -------------------------------------------------------------------------
+ * A natural-looking proposal is to WARN when a challenge has an inherited
+ * `expiresAt` it does not carry —
+ * `!Object.hasOwn(c, "expiresAt") && "expiresAt" in c` — on the grounds that it is
+ * diagnostic only and never control flow. **It was considered and REFUSED.**
+ *
+ * A diagnostic-only prototype-chain read is exactly the shape of harmless-looking
+ * thing that a later refactor promotes into control flow, and the module's rule is
+ * stronger as an ABSOLUTE — *this module never reads through the prototype chain* —
+ * than as *"never, except for warnings"*. An absolute is verifiable by reading the
+ * file; an exception has to be policed forever. Refusing the exception once is
+ * cheaper than guarding it indefinitely, so it is refused here rather than
+ * admitted and watched. Do not add it back without reopening this with the
+ * approver.
+ */
+import { createPrivateKey } from "node:crypto";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+// Siblings and leaf primitives are imported RELATIVELY. `index.ts` re-exports
+// this barrel, so importing `@sentropic/h2a` here would close a self-referential
+// cycle through the package root.
+import { signCanonical, verifyCanonical } from "../../signature.js";
+import { H2A_CLI_DECLARED_CAPABILITIES, publicKeyFingerprint, resolveLiveIdentity } from "../identity/live.js";
+import { createLocalStore } from "../local-files/store.js";
+/**
+ * THE NONCE BRACKET — four bounds, each labelled with what it is FOR.
+ * =================================================================
+ *
+ * The general form, which is the correction to the first draft of this contract:
+ * **a positive specification does not mean a single value — it means every
+ * accepted-set boundary is stated, and each one says what it is for.** A floor
+ * that protects strength and a ceiling that protects against blobs are different
+ * parameters and must not be described in the same breath. The first attempt
+ * specified `fixed ~43`, which pinned an issuer that DOES NOT EXIST YET to an
+ * entropy choice made on its behalf: if the auth lane later picks 384 or 512 bits
+ * — the *safer* choice — a fixed verifier turns their improvement into our
+ * outage.
+ *
+ * 1. {@link H2A_ENROLLMENT_NONCE_PATTERN} — alphabet base64url.
+ *    **POSITIVE, SECURITY-BEARING.**
+ * 2. {@link H2A_ENROLLMENT_NONCE_MIN_BITS} / {@link H2A_ENROLLMENT_NONCE_MIN_LENGTH}
+ *    — minimum 256 bits. **POSITIVE, SECURITY-BEARING.**
+ * 3. {@link H2A_ENROLLMENT_NONCE_MAX_BITS} / {@link H2A_ENROLLMENT_NONCE_MAX_LENGTH}
+ *    — maximum 1024 bits. **SANITY CEILING, EXPLICITLY NOT A SECURITY
+ *    PARAMETER.** It means *"beyond this it is not a nonce"*. It must NEVER be
+ *    read as *"this much entropy is enough"* — the floor is the only bound that
+ *    speaks about strength.
+ * 4. {@link H2A_ENROLLMENT_MAX_NONCE_LENGTH} — 4096 chars, pre-parse DoS guard
+ *    only. Not a definition of anything.
+ */
+/**
+ * Minimum entropy a gateway nonce must carry. **POSITIVE, SECURITY-BEARING.**
+ * Below this a "nonce" is guessable, and a guessable challenge is one an attacker
+ * can pre-compute a proof for.
+ */
+export const H2A_ENROLLMENT_NONCE_MIN_BITS = 256;
+/**
+ * Upper end of the bracket. **SANITY CEILING — NOT A SECURITY PARAMETER.**
+ *
+ * It says "beyond this it is not a nonce", nothing about sufficiency.
+ *
+ * Set at 1024 rather than 512 for HEADROOM — and the arithmetic has to be stated
+ * correctly, because an earlier draft of this comment said "88 base64url
+ * characters" and then drew a conclusion that only the wrong number supports.
+ * Base64url packs 6 bits per character, so a perfectly reasonable 64-byte nonce is
+ * 512 bits / **86** characters — and a 512-bit ceiling derives to `ceil(512 / 6) =
+ * 86` as well. It would therefore land EXACTLY on such a nonce and ACCEPT it, not
+ * reject it. So "512 would reject a 64-byte nonce" was never true; the real
+ * objection is that it leaves ZERO margin. A bound never meant to bound entropy
+ * must not sit flush against a legitimate value, where one more byte of issuer
+ * entropy — or base64 padding the issuer does not strip — turns a sanity bound
+ * into an outage. 1024 buys that margin. The corrected number does not weaken the
+ * choice; it removes a justification that misreported its own arithmetic, which is
+ * the defect class this module exists to argue against.
+ */
+export const H2A_ENROLLMENT_NONCE_MAX_BITS = 1024;
+/**
+ * The nonce's accepted alphabet, stated POSITIVELY: base64url characters only.
+ * **POSITIVE, SECURITY-BEARING** — it is what refuses free text, JSON, a URL, or
+ * a message borrowed from some other protocol, rather than enumerating those.
+ */
+export const H2A_ENROLLMENT_NONCE_PATTERN = /^[A-Za-z0-9_-]+$/;
+/**
+ * Minimum nonce length, DERIVED not asserted: base64url packs 6 bits per
+ * character, so `ceil(256 / 6) = 43` characters is the 256-bit floor.
+ * **POSITIVE, SECURITY-BEARING.**
+ *
+ * A MINIMUM, never an exact length — see the bracket note above for why pinning
+ * an as-yet-unbuilt issuer to one value is the error this replaces.
+ */
+export const H2A_ENROLLMENT_NONCE_MIN_LENGTH = Math.ceil(H2A_ENROLLMENT_NONCE_MIN_BITS / 6);
+/**
+ * Maximum nonce length, derived the same way: `ceil(1024 / 6) = 171` characters.
+ * **SANITY CEILING, NOT A SECURITY PARAMETER** — see
+ * {@link H2A_ENROLLMENT_NONCE_MAX_BITS}.
+ */
+export const H2A_ENROLLMENT_NONCE_MAX_LENGTH = Math.ceil(H2A_ENROLLMENT_NONCE_MAX_BITS / 6);
+/**
+ * Cheap PRE-PARSE cap, and nothing more.
+ *
+ * A DoS sanity bound, not a definition of a nonce — the definition is the
+ * alphabet plus the floor, with the ceiling as a separate sanity bound. Kept
+ * distinct so none of the four is mistaken for another.
+ */
+export const H2A_ENROLLMENT_MAX_NONCE_LENGTH = 4096;
+/**
+ * The ONLY keys a challenge document may carry. An ALLOWLIST, not a blocklist.
+ *
+ * The nonce was specified positively while the challenge *object* was left
+ * specified negatively — a blocklist of one key, `principalSub`. That control did
+ * not cover the harm it was written for: the harm is *"a principal id reaching an
+ * agent process and context window"*, and `{ nonce, meta: { principalSub } }` or
+ * `{ nonce, "__proto__": { principalSub } }` both do exactly that while passing a
+ * top-level `"principalSub" in challenge` check. A blocklist of one key stops one
+ * spelling of one field; nesting is a different spelling.
+ *
+ * So the same positive-specification move is applied one level up: only `nonce`
+ * and `expiresAt` may appear, both must be strings, and anything else is refused
+ * without needing to know what it means. No nesting is reachable, so no
+ * deep scan for a forbidden name is needed — that would be the blocklist again,
+ * one level deeper.
+ */
+export const H2A_ENROLLMENT_CHALLENGE_KEYS = ["nonce", "expiresAt"];
+/**
+ * The domain-separation tag carried and signed by every proof — see
+ * {@link H2AEnrollmentProof.type}.
+ *
+ * Versioned so a format change is distinguishable rather than silently
+ * reinterpreted. Bump this and the verifier stops accepting the old shape, which
+ * is the entire point of it being here.
+ */
+export const H2A_ENROLLMENT_PROOF_TYPE = "h2a-enrollment-proof-v1";
+/**
+ * The exact object the signature covers: **every field the proof carries except
+ * the signature itself**.
+ *
+ * Single definition on purpose. The gateway's verification (Part B flow step 5b,
+ * as amended) is `verifyCanonical(enrollmentProofSignedPayload(proof),
+ * proof.signature, proof.publicKeyPem)`, and field ordering is irrelevant
+ * because `canonicalize` normalizes it — so an independent implementation cannot
+ * disagree about what was signed by guessing at key order.
+ *
+ * The rule is STRUCTURAL, not asserted. Coverage is a rest-spread that removes
+ * exactly one field, so "every field except the signature" is what the code
+ * *does* rather than a list that has to be kept in step — the same shape as
+ * `envelope.ts` `envelopeSigningView` (`const { signatures: _omit, ...rest }`).
+ * Three things follow, and the third is why this beats an enumeration:
+ *
+ * 1. `Omit<…, "signature">` on the parameter makes **tsc** reject a caller that
+ *    does not hold every non-signature field, so a new required field on
+ *    {@link H2AEnrollmentProof} is a compile error, not a test failure.
+ * 2. A new field flows into the signature automatically. There is no second list
+ *    to forget.
+ * 3. A field carried on the proof but NOT signed becomes impossible to emit:
+ *    signing sees the unsigned view, verification re-derives it from the finished
+ *    proof, so any extra field makes the two disagree and
+ *    {@link signEnrollmentChallenge}'s self-verification throws. The rule holds
+ *    even with every test deleted.
+ *
+ * The keys test is kept anyway — it documents the intent and costs nothing.
+ */
+export function enrollmentProofSignedPayload(
+// `Omit<…, "signature">` states the rule in the type itself: the signature is
+// the ONE field a signature cannot cover, and the only field this function is
+// allowed not to see. A full proof satisfies this parameter too, which is why
+// `signature` is accepted-and-stripped rather than merely absent: verification
+// hands in the finished proof.
+proof) {
+    const { signature: _omit, ...rest } = proof;
+    return rest;
+}
+/**
+ * Verify a proof the way the gateway must: the signature over the whole
+ * composite, checked against the key the proof ships.
+ *
+ * **This answers "did this key produce this payload", and NOTHING else.** It is
+ * not an authorization check and must never be used as one: a `true` here on a
+ * key with no active binding row still authorizes nothing (Part B, fail-closed
+ * item 3 — "verifying the signature must never, by itself, cause any row to be
+ * returned"). Provided so the two lanes verify the same bytes, not so a caller
+ * can shortcut a binding lookup.
+ */
+export function verifyEnrollmentProof(proof) {
+    // CHECK THE TAG, or it is decoration. A signature over a payload whose `type`
+    // says something else is a valid signature over a DIFFERENT message, and this
+    // verifier speaks v1 only — a `-v2` proof must fail here rather than be
+    // reinterpreted as v1. That is what versioning the tag is for.
+    if (proof.type !== H2A_ENROLLMENT_PROOF_TYPE)
+        return false;
+    return verifyCanonical(enrollmentProofSignedPayload(proof), proof.signature, proof.publicKeyPem);
+}
+/**
+ * Refuse to prove control of a key h2a itself does not list as ACTIVE.
+ *
+ * h2a-side key validity is *necessary but not sufficient* for exposure — the
+ * binding governs that (Part B, fail-closed item 4) — but a key h2a considers
+ * revoked must never be offered up for a NEW binding.
+ *
+ * This is DEFENCE IN DEPTH, and its call site is unreachable in practice: when
+ * the live key has been revoked, `resolveLiveIdentity`'s reclaim proof
+ * (`provesLocalKey`, which requires at least one active key) fails, so it MINTS
+ * a fresh identity instead of returning the revoked one — verified by the
+ * "a locally revoked key is never the key proved" test. The guard exists so that
+ * remains a CHECKED fact rather than a relied-upon one, and it is exported so it
+ * can be exercised directly instead of sitting untested behind a path that
+ * cannot reach it.
+ *
+ * An empty key list is an ERROR here, never a silent pass: "no active keys" is
+ * not the fact "this key is fine".
+ */
+export function assertKeyIsLocallyActive(input) {
+    if (input.activeKeys.length === 0) {
+        throw new Error(`h2a enrollment: instance "${input.instance}" has NO active key in the local registry — ` +
+            "refusing to prove control of a key h2a itself does not list as active");
+    }
+    if (!input.activeKeys.includes(input.publicKeyPem)) {
+        throw new Error(`h2a enrollment: the resolved public key of "${input.instance}" is not active in the local ` +
+            "registry (revoked, or superseded) — re-run `h2a connect` before enrolling");
+    }
+}
+/**
+ * Resolve the CURRENT live identity and load its keypair.
+ *
+ * Why this resolves live, every single time, and takes no instance id:
+ * **a memory that names an instance-id ROTS.** That is a documented failure in
+ * this project (a stale recorded mapping sent a consultation to the wrong
+ * instance), and it is the same failure the identity re-anchor of 2026-06-07
+ * created for enrollment: the stability unit moved from `(host, workspaceId)`
+ * to the provider conversation UUID, so an agent enrolled before it now
+ * presents a DIFFERENT instance handle and a DIFFERENT keypair (Part B,
+ * "Re-enrollment of a post-re-anchor key"). The previously enrolled
+ * `agentPubKey` is simply no longer produced by any live agent — which is why a
+ * push today is rejected 401.
+ *
+ * So there is deliberately **no `instance` parameter anywhere in this module's
+ * public surface**. The id cannot be passed in, therefore a stale one cannot be
+ * used. `resolveLiveIdentity` is called without `explicitInstance` (which would
+ * short-circuit before any keypair exists — `identity/live.ts`), and the key is
+ * then read from the paths THAT resolution returned.
+ *
+ * WHAT ACTUALLY HAPPENS WHEN THE LOCAL KEY IS UNUSABLE — stated because the
+ * obvious reading ("it fails closed") is wrong, and an overstated guard comment
+ * is worse than none:
+ *
+ * - **Corrupt, truncated or passphrase-protected private key** → `provesLocalKey`
+ *   catches its own failure and returns `false`, so `resolveLiveIdentity` MINTS a
+ *   fresh identity. The ceremony then succeeds, with exit 0, proving control of a
+ *   BRAND-NEW key — the corrupt file is left on disk and the old instance stays
+ *   listed active. It does not fail, and it does not prove the damaged key. The
+ *   mint is the same self-healing mechanism as the revoked-key case, but here it
+ *   would MASK TAMPERING, so silence is the defect: the CLI names any unusable
+ *   key file on stderr before this runs (see {@link listUnusablePrivateKeys}),
+ *   and `identityAction` reports the mint. Pinned by an OBSERVED BEHAVIOUR test.
+ * - **Unreadable private key (EACCES)** → `readKeypair` reads the same file
+ *   earlier, inside `resolveLiveIdentity` and outside any `try`, so the raw errno
+ *   escapes from there rather than from the guard below. That is why the whole
+ *   resolution call is wrapped: the failure is re-thrown with the root named,
+ *   instead of surfacing as a bare `EACCES` with no indication of which store it
+ *   came from.
+ * - **The two guards below are NARROWING, not behaviour.** The
+ *   `privateKeyPath === undefined` branch exists because the type is optional
+ *   (`explicitInstance` is the only resolution path that omits the paths, and
+ *   this function never passes one), and the `readFileSync` branch is belt and
+ *   braces behind the earlier read. Neither is reachable on this path; they are
+ *   not the reason a broken key is safe. {@link assertKeyIsLocallyActive} is in
+ *   the same position and says so itself.
+ *
+ * DOCUMENTED LIMIT on what the returned `instance` contains: an instance id is
+ * `<host>:<label>:<uuid>` and its label is the host-native session name or the
+ * workspace directory's BASENAME (`identity/live.ts` `deriveInstanceId`). So the
+ * proof carries a workspace *label*, which Part A's opacity boundary explicitly
+ * permits ("never a filesystem path beyond a human label") — but never a path.
+ * It is free text the owner controls, so a consumer must escape it like any
+ * user content; see joint plan §9.
+ */
+export function resolveEnrollmentIdentity(input) {
+    let identity;
+    try {
+        identity = resolveLiveIdentity({
+            root: input.root,
+            host: input.host,
+            cwd: input.cwd,
+            // Display-only list, exactly as `h2a connect` declares it. Never an
+            // authorization input (feed contract ratification condition #3).
+            declaredCapabilities: H2A_CLI_DECLARED_CAPABILITIES
+            // No `explicitInstance`: see the doc comment. A named id is the rot.
+        });
+    }
+    catch (error) {
+        // `resolveLiveIdentity` reads the keypair internally, outside any try, so an
+        // unreadable key surfaces HERE as a bare errno. Name the source rather than
+        // letting an `EACCES` escape with no indication of which store produced it.
+        throw new Error(`h2a enrollment: live identity resolution failed under root "${input.root}" ` +
+            `(${error.message})`);
+    }
+    // NARROWING, not a fail-closed behaviour: the paths are optional on the type
+    // because `explicitInstance` resolution omits them, and this function never
+    // passes one. See the doc comment for what actually happens to a broken key.
+    if (identity.privateKeyPath === undefined || identity.publicKeyPath === undefined) {
+        throw new Error(`h2a enrollment: live identity resolution for "${identity.instance}" returned no keypair ` +
+            `(action=${identity.action})`);
+    }
+    let privateKeyPem;
+    let publicKeyPem;
+    try {
+        privateKeyPem = readFileSync(identity.privateKeyPath, "utf8");
+        publicKeyPem = readFileSync(identity.publicKeyPath, "utf8");
+    }
+    catch (error) {
+        // Belt and braces behind the read that already happened inside the
+        // resolution above; unreachable on this path.
+        throw new Error(`h2a enrollment: cannot read the identity keypair of "${identity.instance}" ` +
+            `(${error.message})`);
+    }
+    assertKeyIsLocallyActive({
+        instance: identity.instance,
+        publicKeyPem,
+        activeKeys: createLocalStore({ root: input.root }).listInstanceKeys(identity.instance)
+    });
+    return {
+        instance: identity.instance,
+        privateKeyPem,
+        publicKeyPem,
+        identityAction: identity.action
+    };
+}
+/**
+ * Every private key file under `<root>/keys` that exists but cannot be loaded as
+ * a private key — corrupt, truncated, or passphrase-protected.
+ *
+ * This exists because of what does NOT happen when the live key is one of those:
+ * live resolution's reclaim proof fails silently and MINTS a fresh identity, so
+ * the ceremony succeeds with exit 0 on a brand-new key while a damaged file sits
+ * on disk. The mint is defensible; doing it silently is not, because it is
+ * indistinguishable from tampering. So the caller can name the file.
+ *
+ * Read-only and total: it never throws, and a missing `keys` directory yields an
+ * empty list from an EXPLICIT branch — "there is no key directory" is an
+ * established fact, not a default.
+ */
+export function listUnusablePrivateKeys(root) {
+    const keysDir = join(root, "keys");
+    if (!existsSync(keysDir))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(keysDir);
+    }
+    catch {
+        // The directory exists but cannot be listed: report nothing rather than
+        // claim health. The caller's real check is the ceremony itself.
+        return [];
+    }
+    const unusable = [];
+    for (const entry of entries) {
+        if (!entry.endsWith(".key.pem"))
+            continue;
+        const path = join(keysDir, entry);
+        try {
+            createPrivateKey({ key: readFileSync(path, "utf8"), format: "pem" });
+        }
+        catch {
+            unusable.push(path);
+        }
+    }
+    return unusable.sort();
+}
+/**
+ * What a challenge document actually CARRIES: its allowlisted OWN properties,
+ * copied once into a fresh null-prototype object.
+ *
+ * WHY OWN-NESS IS ESTABLISHED HERE AND NOT AT EACH CONSUMER — this is the
+ * generalisation of a defect that was first fixed one field at a time, and the
+ * reason it is now structural.
+ *
+ * `Object.keys` (the allowlist) cannot see an inherited field, but plain property
+ * access (`challenge.expiresAt`) walks the prototype chain. So the allowlist and
+ * the consumers can disagree about what the document says. Guarding each consumer
+ * with `Object.hasOwn` only fixes the consumers you remembered: the first version
+ * of this code remembered `nonce` and forgot `expiresAt`, so an own `nonce` plus an
+ * INHERITED `expiresAt` was read by the validator *and* copied in as an own field
+ * by the sanitizer. **An allowlist is only as strong as the accessor the consumer
+ * uses afterwards** — and a rule applied to one of two allowlisted fields is a
+ * habit, not a guarantee.
+ *
+ * The durable fix is therefore not a second `hasOwn` at the second consumer. It is
+ * to make own-ness a property of the OBJECT everything downstream reads. The two
+ * reads below are the only prototype-chain-capable reads of a challenge left in
+ * this module, each immediately gated by the `Object.hasOwn` above it; after this
+ * function returns, its result has no prototype, so no later read — including one
+ * a future edit adds — can walk a chain. Validation and consumption cannot diverge
+ * again because there is only one object left for them to disagree about.
+ *
+ * Refuses rather than trims: an unexpected key, or a `nonce` that is not the
+ * document's own, throws here. Field VALUES are not checked yet — that is
+ * {@link assertCarriedChallengeIsSignable}, which reads only this copy.
+ */
+function carriedChallengeFields(challenge) {
+    // ALLOWLIST FIRST, over OWN ENUMERABLE KEYS — `Object.keys`, never `in`.
+    //
+    // `in` walks the prototype chain, so an allowlist built on it would ask the
+    // wrong question twice over: it would miss an own `"__proto__"` key (which
+    // `JSON.parse` DEFINES as an own property rather than reassigning the
+    // prototype) while being confused by inherited names. `Object.keys` sees
+    // exactly what a parsed document actually carries. That makes the
+    // `__proto__` case — a prototype-pollution vector on a `JSON.parse` result, not
+    // merely a disclosure one — refused rather than ignored.
+    //
+    // REFUSE-THE-REST MEANS REFUSE, NOT IGNORE. Silently dropping unknown fields
+    // would let a document that says something we do not understand be treated as
+    // one that says nothing.
+    //
+    // This runs on the LIBRARY path, not only in the CLI: a TS caller cannot add an
+    // excess key to a typed literal, but a parsed document can, and every entry
+    // point validates its own input rather than assuming an upstream check.
+    const unexpected = Object.keys(challenge).filter((key) => !H2A_ENROLLMENT_CHALLENGE_KEYS.includes(key));
+    if (unexpected.length > 0) {
+        const named = unexpected.map((key) => `"${key}"`).join(", ");
+        throw new Error(`h2a enrollment: challenge carries unexpected field(s) ${named} — only ` +
+            `${H2A_ENROLLMENT_CHALLENGE_KEYS.join(" and ")} are accepted. The agent signs a nonce; ` +
+            "any other field is refused so that a principal identifier (or anything else) cannot ride " +
+            "in nested inside one, which is what a top-level principalSub check alone would miss" +
+            (unexpected.includes("principalSub")
+                ? ". principalSub in particular MUST NOT be sent to the agent: the gateway already knows " +
+                    "which session it issued the nonce to"
+                : ""));
+    }
+    // An inherited nonce carries nothing of its own: it sails through the allowlist
+    // (`Object.keys` is empty) and would then be signed anyway. Refused by name
+    // here, before the copy, so the message says what is actually wrong rather than
+    // surfacing later as "no nonce" on a copy that never received one.
+    if (!Object.hasOwn(challenge, "nonce")) {
+        throw new Error("h2a enrollment: the challenge carries no nonce of its own — an inherited value is not a " +
+            "carried field, and only carried fields are signed");
+    }
+    const carried = Object.create(null);
+    carried.nonce = challenge.nonce;
+    // THE SAME QUESTION, asked of the other allowlisted field — this is the field the
+    // one-at-a-time fix missed. An inherited `expiresAt` is not carried, so it is not
+    // copied, so nothing downstream can see it. The extra `!== undefined` keeps an
+    // own-but-undefined `expiresAt` from becoming a key, preserving the "absent
+    // optional stays absent" property of the sanitized object.
+    //
+    // THE FRAMING THIS BEHAVIOUR MUST BE READ IN. Two inputs now pass that once threw:
+    // an inherited PAST `expiresAt` (once refused as expired) and an inherited
+    // non-string `expiresAt` (once refused as not an instant). This is the line a
+    // future auditor will try to "restore", so the correct description is recorded at
+    // the field rather than left to be rediscovered. It is NOT *"used to refuse, now
+    // accepts"*. It is: **an inherited field is not carried, therefore not present; the
+    // behaviour follows from the carriage rule and is not a special case for
+    // `expiresAt`.** Nothing was relaxed about expiry — the set of fields that exist
+    // got smaller, and every rule about expiry still applies in full to every expiry
+    // that is actually there.
+    //
+    // THE CONSEQUENCE OF RESTORING THE REFUSAL, stated explicitly because it is the
+    // whole cost: **restoring the refusal means reintroducing a second reader.** To
+    // refuse an inherited value you must first look at it, and looking at it is a
+    // prototype-chain read of the caller's object — precisely the divergence between
+    // the allowlist and its consumers that this function exists to remove. You cannot
+    // say *"I never read inherited fields, except to reject them"* without being two
+    // readers again. The refusal and the guarantee cannot both be had; this module
+    // keeps the guarantee.
+    //
+    // THE SECURITY CHECK, on the record because this flip is TOWARD ACCEPTANCE and
+    // that direction earns one. The agent-side expiry check is ADVISORY by the
+    // architect's own ruling, and the GATEWAY REMAINS THE TTL AUTHORITY (Part B flow
+    // step 5a). An attacker who suppresses the advisory check by hanging `expiresAt`
+    // on a prototype must ALREADY CONTROL the challenge object, and the authoritative
+    // check is server-side and wholly unaffected by anything reachable from here. So
+    // the trade is: one bypassable defence-in-depth layer, against a party who already
+    // owns the input, in exchange for eliminating an entire defect class — validator
+    // and consumer disagreeing about what a document says.
+    //
+    // THE ASYMMETRY WITH `nonce` IS PRINCIPLED, NOT INCONSISTENT. An inherited `nonce`
+    // throws just above; an inherited `expiresAt` is ignored here. Both fields collapse
+    // *inherited* to *absent* — that is one rule, applied identically. The only thing
+    // that differs is REQUIREDNESS, never the rule: `nonce` is required, so absence is
+    // an error however it arose; `expiresAt` is optional, so absence is legal. Read the
+    // two branches as a single carriage rule meeting two different obligations.
+    if (Object.hasOwn(challenge, "expiresAt") && challenge.expiresAt !== undefined) {
+        carried.expiresAt = challenge.expiresAt;
+    }
+    return carried;
+}
+/**
+ * Reject a challenge we must not sign, reading ONLY the carried copy. Narrowing
+ * only — this can refuse a signature, never authorize one.
+ *
+ * The parameter is deliberately {@link CarriedChallengeFields} and not
+ * `H2AEnrollmentChallenge`: every read below is then own-by-construction, and the
+ * validator has no access to the caller's object to accidentally read through.
+ */
+function assertCarriedChallengeIsSignable(carried, nowMs) {
+    if (carried.expiresAt !== undefined && typeof carried.expiresAt !== "string") {
+        throw new Error("h2a enrollment: challenge expiresAt must be an ISO-8601 STRING — a non-string cannot be an " +
+            "instant, and would be a place for structure to hide");
+    }
+    if (typeof carried.nonce !== "string" || carried.nonce.length === 0) {
+        throw new Error("h2a enrollment: the challenge carries no nonce — nothing to prove key control over");
+    }
+    // Cheap pre-parse bound first, so a hostile blob is dropped before any regex
+    // walks it. This is a DoS cap, NOT the nonce's definition.
+    if (carried.nonce.length > H2A_ENROLLMENT_MAX_NONCE_LENGTH) {
+        throw new Error(`h2a enrollment: challenge nonce is ${carried.nonce.length} chars, over the ` +
+            `${H2A_ENROLLMENT_MAX_NONCE_LENGTH}-char pre-parse cap — refusing to read an unbounded blob`);
+    }
+    // The definition, stated positively: base64url of at least 256 bits. Free
+    // text, JSON, a URL, or a message borrowed from another protocol all fail here
+    // because they are not the specified shape — not because they were enumerated.
+    if (!H2A_ENROLLMENT_NONCE_PATTERN.test(carried.nonce)) {
+        throw new Error("h2a enrollment: challenge nonce is not base64url ([A-Za-z0-9_-]) — a nonce is a random " +
+            "value of a specified shape, and anything else is refused rather than signed");
+    }
+    // FLOOR — the only bound here that speaks about strength.
+    if (carried.nonce.length < H2A_ENROLLMENT_NONCE_MIN_LENGTH) {
+        throw new Error(`h2a enrollment: challenge nonce is ${carried.nonce.length} base64url chars, under the ` +
+            `${H2A_ENROLLMENT_NONCE_MIN_LENGTH} needed for ${H2A_ENROLLMENT_NONCE_MIN_BITS} bits — ` +
+            "a guessable challenge is one an attacker can pre-compute a proof for");
+    }
+    // CEILING — a SANITY bound, not a security one. It says "beyond this it is not
+    // a nonce"; it says nothing about how much entropy is enough.
+    if (carried.nonce.length > H2A_ENROLLMENT_NONCE_MAX_LENGTH) {
+        throw new Error(`h2a enrollment: challenge nonce is ${carried.nonce.length} base64url chars, over the ` +
+            `${H2A_ENROLLMENT_NONCE_MAX_LENGTH}-char sanity ceiling (${H2A_ENROLLMENT_NONCE_MAX_BITS} ` +
+            "bits) — beyond this it is not a nonce. This is NOT a statement that less entropy is enough");
+    }
+    if (carried.expiresAt !== undefined) {
+        const expiresAtMs = Date.parse(carried.expiresAt);
+        if (Number.isNaN(expiresAtMs)) {
+            throw new Error(`h2a enrollment: challenge expiresAt "${carried.expiresAt}" is not an ISO-8601 instant`);
+        }
+        if (expiresAtMs <= nowMs) {
+            throw new Error(`h2a enrollment: challenge expired at ${carried.expiresAt} — ask the gateway for a new one`);
+        }
+    }
+}
+/**
+ * Reject a challenge we must not sign. Narrowing only — this can refuse a
+ * signature, never authorize one. Throws with a message naming the reason.
+ *
+ * Exported so a caller that classifies errors (the CLI, which owes a distinct
+ * exit code for "your challenge is bad" vs "my local key state is bad") can
+ * check the input it was handed BEFORE touching any identity.
+ * {@link signEnrollmentChallenge} validates again regardless: each entry point
+ * validates its own input, and an upstream check is never assumed.
+ *
+ * IMPLEMENTED AS the sanitize path with the result discarded, deliberately. The
+ * validator and the sanitizer used to be two independent readers of the caller's
+ * object, which is precisely how `expiresAt` came to be validated *through the
+ * prototype chain* while the allowlist looked only at own keys. One reader means
+ * they cannot disagree.
+ */
+export function assertSignableEnrollmentChallenge(challenge, nowMs) {
+    sanitizeEnrollmentChallenge(challenge, nowMs);
+}
+/**
+ * Validate a parsed challenge document and return a FRESH, NULL-PROTOTYPE object
+ * carrying only the allowlisted keys.
+ *
+ * Three distinct jobs, all load-bearing:
+ *
+ * 1. It takes the OWN-ONLY view first ({@link carriedChallengeFields}), so what is
+ *    validated and what is returned are the same object. An inherited field is
+ *    invisible to both.
+ * 2. It refuses ({@link assertCarriedChallengeIsSignable}). Refuse-the-rest means
+ *    refuse, not ignore.
+ * 3. What flows onward is a **new object with `null` prototype**, so the
+ *    `JSON.parse` result — which may carry an own `"__proto__"` key, a
+ *    prototype-pollution vector the moment anything spreads or assigns it into
+ *    another object — never propagates past this boundary. Even though such a
+ *    document is already refused above, nothing downstream has to depend on that
+ *    having happened.
+ *
+ * Order matters and is the point: sanitize-then-validate, never validate-then-copy.
+ * The copy is what removes the second accessor, so validating the caller's object
+ * first would put the bug back.
+ *
+ * Use this at any boundary where the challenge came from parsed input. The CLI
+ * does, and so does {@link signEnrollmentChallenge}.
+ */
+export function sanitizeEnrollmentChallenge(challenge, nowMs) {
+    const carried = carriedChallengeFields(challenge);
+    assertCarriedChallengeIsSignable(carried, nowMs);
+    return carried;
+}
+/**
+ * Sign a gateway-issued challenge with the agent's identity key and return the
+ * Part B proof payload. PURE apart from the injected clock: no I/O, no network,
+ * no store.
+ *
+ * The signed message is the CANONICAL COMPOSITE
+ * {@link enrollmentProofSignedPayload} — `{ type, nonce, instance, publicKeyPem }`
+ * — per the signed-composite amendment. The earlier shape signed the bare nonce
+ * (Part B flow steps 3 and 5b as originally written), which was safe only
+ * because nothing yet consumed `instance`: safety derived from the *absence* of a
+ * consumer, which expires the moment someone adds one.
+ *
+ * The rule, in its amended form: **a proof must attest to everything it carries
+ * AND to what it is.** Content-completeness plus context-binding — the first
+ * without the second leaves the interpretation attacker-chosen.
+ *
+ * A structural consequence worth knowing, because it removes a whole finding
+ * rather than guarding against it: the reclaim proof-of-possession signs a
+ * STRING (`identity-reclaim:<instance>:<fingerprint>`), and this signs an
+ * OBJECT. `canonicalize` type-tags the two differently, so no enrollment
+ * signature can ever satisfy `verifyReclaimProof` — the signing-oracle collision
+ * is impossible by construction, not by refusal. There is deliberately no guard
+ * against it: a guard that cannot fire is the defect this PR spent its time
+ * finding. The property is pinned by a regression test instead.
+ *
+ * Note that that separation was ACCIDENTAL — it held because the two payload
+ * types differ, not because either said what it was. The signed `type` field is
+ * what makes it deliberate, and it generalizes: no h2a signing site can collide
+ * with this one now, whatever shape it later adopts.
+ *
+ * Before returning, the proof is VERIFIED against the public key it ships. A
+ * proof we cannot verify ourselves is never emitted: that is what catches a
+ * mismatched keypair locally instead of at the gateway, where the failure is
+ * indistinguishable from an attack.
+ */
+export function signEnrollmentChallenge(input) {
+    const now = input.now ?? Date.now;
+    // Validate and take the own-only view in ONE step, then sign what THAT view says.
+    // Reading `input.challenge.nonce` below instead would be another accessor on the
+    // caller's object — own today only because the validator happens to have rejected
+    // an inherited nonce first, i.e. correct by ordering rather than by construction.
+    // The signed nonce comes off the sanitized copy so the ordering cannot matter.
+    const challenge = sanitizeEnrollmentChallenge(input.challenge, now());
+    const { instance, privateKeyPem, publicKeyPem } = input.identity;
+    // Build the unsigned proof first, then sign the payload DERIVED from it, so the
+    // signed bytes and the shipped fields cannot drift apart.
+    //
+    // `type` sits INSIDE this object — the spread SOURCE — so it is covered by the
+    // very same mechanism as every other field. A tag added after the spread, or
+    // carried on the proof but excluded from it, would be an UNSIGNED field
+    // asserting the message's own identity: the worst possible field to leave
+    // unsigned, and worse than having no tag at all.
+    const unsigned = {
+        type: H2A_ENROLLMENT_PROOF_TYPE,
+        nonce: challenge.nonce,
+        instance,
+        publicKeyPem
+    };
+    const signature = signCanonical(enrollmentProofSignedPayload(unsigned), {
+        by: instance,
+        privateKeyPem
+    });
+    const proof = { ...unsigned, signature };
+    if (!verifyEnrollmentProof(proof)) {
+        throw new Error(`h2a enrollment: the proof for "${instance}" does not verify against its own public key ` +
+            "(private/public key mismatch) — refusing to emit an unverifiable proof");
+    }
+    return proof;
+}
+/**
+ * Resolve the live identity, sign the challenge, return the proof.
+ *
+ * SYNCHRONOUS and network-free by construction: there is no transport in this
+ * function at all, so the CLI path (`h2a keys prove-control`) cannot reach one.
+ * Re-enrollment needs no separate entry point — this IS the re-enrollment path,
+ * because it resolves the current identity every time and can therefore only
+ * ever produce a proof for the key that is live now. A changed controlling key
+ * means the owner re-runs this and the gateway mints a NEW binding, revoking the
+ * old row (Part B, "Re-enrollment of a post-re-anchor key"); nothing here
+ * reuses or rotates anything.
+ */
+export function buildEnrollmentProof(options) {
+    const resolveIdentity = options.resolveIdentityImpl ?? resolveEnrollmentIdentity;
+    const identity = resolveIdentity({
+        root: options.root,
+        host: options.host,
+        cwd: options.cwd
+    });
+    const proof = signEnrollmentChallenge({
+        challenge: options.challenge,
+        identity,
+        ...(options.now !== undefined ? { now: options.now } : {})
+    });
+    return {
+        proof,
+        instance: proof.instance,
+        publicKeyFingerprint: publicKeyFingerprint(proof.publicKeyPem),
+        ...(identity.identityAction !== undefined
+            ? { identityAction: identity.identityAction }
+            : {})
+    };
+}
+/**
+ * Run the ceremony end to end: resolve the live identity, sign the challenge,
+ * and — only if a transport was injected — hand the proof over.
+ *
+ * With no `submitImpl` this makes NO network call of any kind. That is not a
+ * default-off flag; there is no hosted endpoint in this file to turn on.
+ */
+export async function runEnrollmentCeremony(options) {
+    const built = buildEnrollmentProof(options);
+    if (options.submitImpl === undefined) {
+        return { ...built, submission: { attempted: false, reason: "no-transport-configured" } };
+    }
+    const response = await options.submitImpl(built.proof);
+    return { ...built, submission: { attempted: true, response } };
+}
+//# sourceMappingURL=ceremony.js.map