@sentropic/h2a 0.85.25 → 0.87.0

package/dist/runtime/enrollment/ceremony.d.ts

@@ -0,0 +1,542 @@
+import type { H2ASignature } from "../../types.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 declare 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 declare 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 declare const H2A_ENROLLMENT_NONCE_PATTERN: RegExp;
+/**
+ * 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 declare const H2A_ENROLLMENT_NONCE_MIN_LENGTH: number;
+/**
+ * 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 declare const H2A_ENROLLMENT_NONCE_MAX_LENGTH: number;
+/**
+ * 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 declare 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 declare const H2A_ENROLLMENT_CHALLENGE_KEYS: readonly ["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 declare const H2A_ENROLLMENT_PROOF_TYPE = "h2a-enrollment-proof-v1";
+/**
+ * A gateway-issued enrollment challenge, as the local agent receives it.
+ *
+ * Part B, flow step 2: *"Gateway issues a challenge: a random nonce, TTL-bound,
+ * scoped to that `sub`."* The `sub`-scoping is a fact the GATEWAY holds and
+ * re-checks at verification time (flow step 5a) and the agent never sees it —
+ * see consequence 2 in the module header.
+ */
+export interface H2AEnrollmentChallenge {
+    /**
+     * The random nonce: base64url, ≥256 bits. It is one of the three signed
+     * fields — see {@link enrollmentProofSignedPayload}.
+     */
+    readonly nonce: string;
+    /**
+     * Optional ISO-8601 expiry, as told to the agent. **Advisory**: the gateway
+     * remains the authority on the TTL (flow step 5a). Present, it lets the agent
+     * refuse to spend a signature on a challenge it can already see is dead —
+     * which can only ever narrow what happens, never widen it.
+     */
+    readonly expiresAt?: string;
+}
+/**
+ * The proof payload the agent returns to the gateway — Part B, flow step 4:
+ * *"The agent returns `{ nonce, signature, publicKeyPem, instance }`."*
+ *
+ * Exactly those four fields, and nothing else. In particular: no private key
+ * material, no filesystem path, no principal identifier, no bearer token, no
+ * capability list. What the gateway does with it is Part B flow step 5.
+ */
+export interface H2AEnrollmentProof {
+    /**
+     * WHAT THIS MESSAGE IS — the domain-separation tag, signed like every other
+     * carried field.
+     *
+     * The rule "a proof must attest to everything it CARRIES" is only
+     * content-completeness. The other half: **a proof must also attest WHAT IT
+     * IS.** Attesting content while leaving the message type unstated is exactly
+     * how cross-protocol attacks work — signature valid, content honest,
+     * *interpretation attacker-chosen*.
+     *
+     * That is precisely the oracle this contract already closed once: moving from a
+     * signed string to a signed object fixed it, but bound the type only
+     * ACCIDENTALLY, via a key set that happens to be unique among h2a's signing
+     * sites today. "Safe because no other site currently signs this shape" is the
+     * same negative property — satisfied by absence, expiring when someone adds the
+     * colliding site. This field makes it positive.
+     *
+     * **VERSIONED deliberately.** A future format change must be
+     * *distinguishable*, not silently reinterpreted; an unversioned tag only defers
+     * the same problem to the next revision. {@link verifyEnrollmentProof} checks
+     * this value, so a `-v2` proof cannot pass a v1 verifier.
+     */
+    readonly type: typeof H2A_ENROLLMENT_PROOF_TYPE;
+    /** The gateway's nonce, echoed verbatim. Signed. */
+    readonly nonce: string;
+    /**
+     * `signCanonical(enrollmentProofSignedPayload(proof), { by: instance,
+     * privateKeyPem })` — an `H2ASignature` `{ by, alg: 'ed25519', value }`
+     * (`types.ts` `H2ASignature`, reused unchanged per Part B's "Reuse vs. new"
+     * table).
+     *
+     * `signature.by` is NOT part of the signed message; it is a routing label that
+     * duplicates the signed `instance`. A verifier must read `instance`, never
+     * `by`.
+     */
+    readonly signature: H2ASignature;
+    /**
+     * The agent's CURRENT public key PEM (SPKI). Public material, not a secret.
+     * Signed — so a payload cannot be re-pointed at another key and still verify
+     * against this signature.
+     */
+    readonly publicKeyPem: string;
+    /**
+     * The agent's CURRENT live instance id. Signed, so its PROVENANCE is
+     * trustworthy. That is emphatically not permission: see SIGNED ≠ AUTHORIZED in
+     * the module header. It maps to Part B's `agentInstanceIdAtBinding`, which the
+     * contract already marks "provenance only — NEVER re-used as authority at read
+     * time".
+     */
+    readonly instance: string;
+}
+/**
+ * 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 declare function enrollmentProofSignedPayload(proof: Omit<H2AEnrollmentProof, "signature"> & {
+    readonly signature?: H2ASignature;
+}): Omit<H2AEnrollmentProof, "signature">;
+/**
+ * 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 declare function verifyEnrollmentProof(proof: H2AEnrollmentProof): boolean;
+/**
+ * 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 declare function assertKeyIsLocallyActive(input: {
+    readonly instance: string;
+    readonly publicKeyPem: string;
+    readonly activeKeys: readonly string[];
+}): void;
+/** The local key material the ceremony proves control of. */
+export interface H2AEnrollmentIdentity {
+    /** The live instance id, resolved at run time — never a recorded value. */
+    readonly instance: string;
+    /** PKCS#8 PEM. Read from disk, used to sign, and NEVER returned outward. */
+    readonly privateKeyPem: string;
+    /** SPKI PEM. Public material; this one does go on the wire. */
+    readonly publicKeyPem: string;
+    /**
+     * How live resolution arrived at this identity: `reclaim` re-proved an existing
+     * local key, `mint` created a NEW one. Reported so a mint is never silent — a
+     * mint the owner did not expect means an earlier keypair was unusable (see
+     * {@link listUnusablePrivateKeys}) or the agent re-anchored. Optional so an
+     * injected resolver need not synthesize a provenance it does not have.
+     */
+    readonly identityAction?: "override" | "reclaim" | "mint";
+}
+/** Where {@link buildEnrollmentProof} looks for the live agent identity. */
+export interface ResolveEnrollmentIdentityInput {
+    /** The h2a store root (`<root>/keys/...`). */
+    readonly root: string;
+    /** The provider host (`claude`, `codex`, ...) — an input to live resolution. */
+    readonly host: string;
+    /** The working directory, for workspace resolution. */
+    readonly cwd: string;
+}
+/**
+ * Seam for the identity resolution. Injected by tests; the default
+ * ({@link resolveEnrollmentIdentity}) is the only production implementation.
+ */
+export type EnrollmentIdentityResolver = (input: ResolveEnrollmentIdentityInput) => H2AEnrollmentIdentity;
+/**
+ * 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 declare function resolveEnrollmentIdentity(input: ResolveEnrollmentIdentityInput): H2AEnrollmentIdentity;
+/**
+ * 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 declare function listUnusablePrivateKeys(root: string): string[];
+/** Input to the pure signing step. No I/O, no clock unless injected. */
+export interface SignEnrollmentChallengeInput {
+    /** The gateway-issued challenge. */
+    readonly challenge: H2AEnrollmentChallenge;
+    /** The identity whose control is being proved. */
+    readonly identity: H2AEnrollmentIdentity;
+    /** Clock, for the advisory expiry check. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * 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 declare function assertSignableEnrollmentChallenge(challenge: H2AEnrollmentChallenge, nowMs: number): void;
+/**
+ * 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 declare function sanitizeEnrollmentChallenge(challenge: H2AEnrollmentChallenge, nowMs: number): H2AEnrollmentChallenge;
+/**
+ * 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 declare function signEnrollmentChallenge(input: SignEnrollmentChallengeInput): H2AEnrollmentProof;
+/** Options for the synchronous, network-free proof build. */
+export interface BuildEnrollmentProofOptions {
+    /** The h2a store root. */
+    readonly root: string;
+    /** The provider host (`claude`, `codex`, ...). */
+    readonly host: string;
+    /** The working directory. */
+    readonly cwd: string;
+    /** The gateway-issued challenge. */
+    readonly challenge: H2AEnrollmentChallenge;
+    /** Clock, for the advisory expiry check. */
+    readonly now?: () => number;
+    /** Identity-resolution seam. Defaults to {@link resolveEnrollmentIdentity}. */
+    readonly resolveIdentityImpl?: EnrollmentIdentityResolver;
+}
+/** What the ceremony produced, plus the owner-facing provenance. */
+export interface EnrollmentProofResult {
+    /** The payload to hand to the gateway. */
+    readonly proof: H2AEnrollmentProof;
+    /** The live instance the proof was produced for (same as `proof.instance`). */
+    readonly instance: string;
+    /**
+     * Short sha256 prefix of the proved public key — the same fingerprint the
+     * reclaim proof uses. For the OWNER to eyeball which key was proved; it is
+     * not part of the proof and carries no authority.
+     */
+    readonly publicKeyFingerprint: string;
+    /**
+     * Provenance of the identity this run proved — see
+     * {@link H2AEnrollmentIdentity.identityAction}. Absent when an injected
+     * resolver did not report one.
+     */
+    readonly identityAction?: "override" | "reclaim" | "mint";
+}
+/**
+ * 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 declare function buildEnrollmentProof(options: BuildEnrollmentProofOptions): EnrollmentProofResult;
+/**
+ * Seam for handing the proof to the gateway.
+ *
+ * **There is no default implementation and h2a ships none.** The gateway's
+ * challenge/verify endpoint is the auth lane's step 2 and is not built yet; the
+ * per-binding push keying is step 4b and carries its own BLOCKING cross-verify
+ * requirement (path-identity vs key-identity). Until then a submitter is
+ * supplied by the caller — in tests, always a fake — and its absence is
+ * REPORTED as a fact, never papered over.
+ */
+export type EnrollmentProofSubmitter = (proof: H2AEnrollmentProof) => Promise<unknown>;
+/**
+ * What happened to the proof, from an EXPLICIT branch on whether a transport
+ * exists — never a defaulted value. "Not attempted" is a fact the caller can
+ * act on; a silent `undefined` would be indistinguishable from a failed send.
+ */
+export type EnrollmentSubmission = {
+    readonly attempted: false;
+    /** No transport was supplied, so nothing was sent anywhere. */
+    readonly reason: "no-transport-configured";
+} | {
+    readonly attempted: true;
+    /** Whatever the injected submitter returned. Opaque to h2a. */
+    readonly response: unknown;
+};
+/** Options for the full ceremony, including the optional injected transport. */
+export interface RunEnrollmentCeremonyOptions extends BuildEnrollmentProofOptions {
+    /**
+     * Injected transport. Omitted (the production default), the proof is returned
+     * for out-of-band delivery and `submission.attempted` is `false`.
+     */
+    readonly submitImpl?: EnrollmentProofSubmitter;
+}
+/** The ceremony's outcome: the proof, plus what was done with it. */
+export interface EnrollmentCeremonyResult extends EnrollmentProofResult {
+    readonly submission: EnrollmentSubmission;
+}
+/**
+ * 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 declare function runEnrollmentCeremony(options: RunEnrollmentCeremonyOptions): Promise<EnrollmentCeremonyResult>;
+//# sourceMappingURL=ceremony.d.ts.map

package/dist/runtime/enrollment/ceremony.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ceremony.d.ts","sourceRoot":"","sources":["../../../src/runtime/enrollment/ceremony.ts"],"names":[],"mappings":"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"}