@mnemom/mnemom 0.17.32 → 0.17.34-next.1

package/dist/lib/oauth.d.ts

@@ -26,6 +26,13 @@
  * positive integer (capped at 5 min), else the default.
  */
 export declare function oauthHttpTimeoutMs(env?: NodeJS.ProcessEnv): number;
+/**
+ * The longest one refreshTokens() call can legitimately take (ms): discovery
+ * plus REFRESH_MAX_ATTEMPTS token requests, each at the per-request deadline,
+ * plus the backoff sleeps between attempts. lib/auth.ts uses it to bound how
+ * long a process waits on another process's refresh lock (MNE-9232).
+ */
+export declare function refreshWorstCaseMs(env?: NodeJS.ProcessEnv): number;
 /** The name carried by an error thrown when an AS round-trip hit its deadline. */
 export declare const OAUTH_TIMEOUT_ERROR = "OAuthTimeoutError";
 export interface AuthServerMetadata {

package/dist/lib/oauth.js

@@ -86,6 +86,19 @@ export function oauthHttpTimeoutMs(env = process.env) {
     }
     return OAUTH_HTTP_TIMEOUT_MS;
 }
+/**
+ * The longest one refreshTokens() call can legitimately take (ms): discovery
+ * plus REFRESH_MAX_ATTEMPTS token requests, each at the per-request deadline,
+ * plus the backoff sleeps between attempts. lib/auth.ts uses it to bound how
+ * long a process waits on another process's refresh lock (MNE-9232).
+ */
+export function refreshWorstCaseMs(env = process.env) {
+    let backoff = 0;
+    for (let attempt = 0; attempt < REFRESH_MAX_ATTEMPTS - 1; attempt++) {
+        backoff += REFRESH_BACKOFF_BASE_MS * 2 ** attempt;
+    }
+    return oauthHttpTimeoutMs(env) * (1 + REFRESH_MAX_ATTEMPTS) + backoff;
+}
 /** The name carried by an error thrown when an AS round-trip hit its deadline. */
 export const OAUTH_TIMEOUT_ERROR = "OAuthTimeoutError";
 function isTimeout(err) {

package/dist/lib/runner/bundle.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Served phase bundle verification for the thin runner (Doors W-L13, W3.11).
+ *
+ * On each claim the runner fetches one signed `AAP-ServedPhaseBundle/v1` (mnemom-api
+ * src/served-phases, W-L12) and runs nothing it did not verify here: the phase order, each
+ * phase's prompt and its runner code or capability ids all sit inside the signed bytes, and the
+ * CLI package itself holds no prompts.
+ *
+ * This is the runner-side twin of the api's `verifyServedPhaseBundle`. Both replay the same
+ * fixture corpus, so a bundle one side refuses the other refuses too. Checks run in a fixed
+ * order and the first failure is the reason: size cap (before parsing), JSON, typ, strict
+ * schema (an unknown field at any level refuses), key, signature, code sha256 consistency,
+ * clock, then the claim binding.
+ *
+ * - Signature: detached base64url Ed25519 over `canonicalJson` of every field but `signature`
+ *   (keys sorted, no whitespace), the construction `AAP-TransparencyRoot/v1` uses. The key is
+ *   the dedicated served-phase key, resolved by `signing_key_id` from the published JWKS; an
+ *   ambiguous kid, a key with an unknown status, or a key retired at or before `issued_at`
+ *   refuses.
+ * - Binding: the claim is (session_id, lease epoch, executor_id). A genuine bundle lifted from
+ *   another claim still verifies cryptographically, so the caller passes everything it knows
+ *   about its own claim in `expect`, and every field must match.
+ *
+ * Pure apart from `node:crypto`: no I/O, never throws.
+ */
+import { canonicalJson } from "../canonical-json.js";
+export { canonicalJson };
+export declare const SERVED_PHASE_BUNDLE_TYP = "AAP-ServedPhaseBundle/v1";
+/** Upper bound on a served bundle, so the runner never parses or hashes an unbounded body. */
+export declare const MAX_BUNDLE_BYTES: number;
+export declare const MAX_PHASES = 32;
+export declare const MAX_PROMPT_BYTES: number;
+export declare const MAX_CODE_BYTES: number;
+export declare const MAX_CAPABILITIES_PER_PHASE = 32;
+export declare const MAX_BUNDLE_LIFETIME_SECONDS: number;
+export type MergeStrategy = "external" | "merge_on_green";
+export type ServedPhaseRunner = {
+    kind: "capabilities";
+    capability_ids: string[];
+} | {
+    kind: "code";
+    language: string;
+    source: string;
+    sha256: string;
+};
+export interface ServedPhase {
+    order: number;
+    name: string;
+    prompt: string;
+    runner: ServedPhaseRunner;
+}
+export interface ServedPhaseBundle {
+    typ: typeof SERVED_PHASE_BUNDLE_TYP;
+    bundle_id: string;
+    signing_key_id: string;
+    issued_at: string;
+    expires_at: string;
+    org_id: string;
+    claim: {
+        session_id: string;
+        epoch: number;
+        executor_id: string;
+    };
+    contract: {
+        sha256: string;
+        version: number;
+    };
+    workflow: {
+        id: string;
+        version: string;
+    };
+    /** Absent means `external`; `resolveMergeStrategy` (settings.ts) applies the default. */
+    merge_strategy?: MergeStrategy;
+    phases: ServedPhase[];
+    signature: string;
+}
+/** One published key, as `/v1/.well-known/jwks.json` lists it. */
+export interface BundleJwk {
+    kty?: string;
+    crv?: string;
+    x?: string;
+    kid?: string;
+    mnemom_ext?: {
+        status?: string;
+        retired_at?: string;
+    };
+}
+export interface BundleJwks {
+    keys: BundleJwk[];
+}
+export type BundleRefusalReason = "too_large" | "malformed" | "wrong_typ" | "schema" | "unknown_key" | "unusable_key" | "retired_key" | "bad_signature" | "code_digest_mismatch" | "not_yet_valid" | "expired" | "binding_mismatch";
+export type VerifyBundleResult = {
+    valid: true;
+    bundle: ServedPhaseBundle;
+    digest: string;
+    key_id: string;
+} | {
+    valid: false;
+    reason: BundleRefusalReason;
+    detail: string;
+};
+/**
+ * What the runner knows about the claim it holds. All six are required, and every one must match
+ * the bundle: a partial expectation would silently weaken the binding. The runner knows session,
+ * epoch, executor and seal from its claim; it learns org_id only from the server, so the job reads
+ * it off the served body and that field checks shape, not an independent fact.
+ */
+export interface ExpectedBundleBinding {
+    org_id: string;
+    session_id: string;
+    epoch: number;
+    executor_id: string;
+    contract_sha256: string;
+    contract_version: number;
+}
+export interface VerifyBundleOptions {
+    /** Inject a clock (ms since the epoch); defaults to Date.now. */
+    now?: () => number;
+    /** Grace on issued_at and expires_at, seconds. Defaults to 60. */
+    clockSkewSeconds?: number;
+}
+export declare function sha256Hex(text: string): string;
+/** The exact bytes the signature covers: canonical JSON of every field but `signature`. */
+export declare function signedBytes(bundle: Record<string, unknown>): string;
+/**
+ * Verify one served bundle against the published key(s). Never throws: any unexpected failure
+ * is a refusal, never a pass.
+ */
+export declare function verifyServedPhaseBundle(served: string, keyOrJwks: BundleJwk | BundleJwks, expect: ExpectedBundleBinding, options?: VerifyBundleOptions): VerifyBundleResult;

package/dist/lib/runner/bundle.js

@@ -0,0 +1,319 @@
+/**
+ * Served phase bundle verification for the thin runner (Doors W-L13, W3.11).
+ *
+ * On each claim the runner fetches one signed `AAP-ServedPhaseBundle/v1` (mnemom-api
+ * src/served-phases, W-L12) and runs nothing it did not verify here: the phase order, each
+ * phase's prompt and its runner code or capability ids all sit inside the signed bytes, and the
+ * CLI package itself holds no prompts.
+ *
+ * This is the runner-side twin of the api's `verifyServedPhaseBundle`. Both replay the same
+ * fixture corpus, so a bundle one side refuses the other refuses too. Checks run in a fixed
+ * order and the first failure is the reason: size cap (before parsing), JSON, typ, strict
+ * schema (an unknown field at any level refuses), key, signature, code sha256 consistency,
+ * clock, then the claim binding.
+ *
+ * - Signature: detached base64url Ed25519 over `canonicalJson` of every field but `signature`
+ *   (keys sorted, no whitespace), the construction `AAP-TransparencyRoot/v1` uses. The key is
+ *   the dedicated served-phase key, resolved by `signing_key_id` from the published JWKS; an
+ *   ambiguous kid, a key with an unknown status, or a key retired at or before `issued_at`
+ *   refuses.
+ * - Binding: the claim is (session_id, lease epoch, executor_id). A genuine bundle lifted from
+ *   another claim still verifies cryptographically, so the caller passes everything it knows
+ *   about its own claim in `expect`, and every field must match.
+ *
+ * Pure apart from `node:crypto`: no I/O, never throws.
+ */
+import { createHash, createPublicKey, verify as cryptoVerify } from "node:crypto";
+import { canonicalJson } from "../canonical-json.js";
+export { canonicalJson };
+export const SERVED_PHASE_BUNDLE_TYP = "AAP-ServedPhaseBundle/v1";
+/** Upper bound on a served bundle, so the runner never parses or hashes an unbounded body. */
+export const MAX_BUNDLE_BYTES = 256 * 1024;
+export const MAX_PHASES = 32;
+export const MAX_PROMPT_BYTES = 64 * 1024;
+export const MAX_CODE_BYTES = 128 * 1024;
+export const MAX_CAPABILITIES_PER_PHASE = 32;
+export const MAX_BUNDLE_LIFETIME_SECONDS = 24 * 60 * 60;
+const DEFAULT_CLOCK_SKEW_SECONDS = 60;
+const ED25519_SIGNATURE_BYTES = 64;
+/** Key statuses the published JWKS uses. Any other value refuses the key. */
+const USABLE_KEY_STATUSES = new Set([undefined, "active", "retired"]);
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const PHASE_NAME_RE = /^[a-z][a-z0-9_-]{0,63}$/;
+const CAPABILITY_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const LANGUAGE_RE = /^[a-z][a-z0-9-]{0,31}$/;
+const WORKFLOW_VERSION_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/;
+const SHA256_RE = /^[0-9a-f]{64}$/;
+const ISO_UTC_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/;
+const BASE64URL_RE = /^[A-Za-z0-9_-]+$/;
+const TOP_LEVEL_REQUIRED = [
+    "typ",
+    "bundle_id",
+    "signing_key_id",
+    "issued_at",
+    "expires_at",
+    "org_id",
+    "claim",
+    "contract",
+    "workflow",
+    "phases",
+    "signature",
+];
+class ShapeError extends Error {
+}
+export function sha256Hex(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+function utf8Bytes(s) {
+    return Buffer.byteLength(s, "utf8");
+}
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function exactKeys(obj, keys, where) {
+    for (const k of Object.keys(obj)) {
+        if (!keys.includes(k))
+            throw new ShapeError(`${where}: unexpected field ${JSON.stringify(k)}`);
+    }
+    for (const k of keys) {
+        if (!Object.prototype.hasOwnProperty.call(obj, k)) {
+            throw new ShapeError(`${where}: missing field ${JSON.stringify(k)}`);
+        }
+    }
+}
+function str(v, re, where) {
+    if (typeof v !== "string" || !re.test(v))
+        throw new ShapeError(`${where}: invalid value`);
+    return v;
+}
+function boundedText(v, maxBytes, where) {
+    if (typeof v !== "string" || v.length === 0)
+        throw new ShapeError(`${where}: must be a non-empty string`);
+    if (utf8Bytes(v) > maxBytes)
+        throw new ShapeError(`${where}: longer than ${maxBytes} bytes`);
+}
+function timestamp(v, where) {
+    const ms = Date.parse(str(v, ISO_UTC_RE, where));
+    if (!Number.isFinite(ms))
+        throw new ShapeError(`${where}: not a valid timestamp`);
+    return ms;
+}
+function checkRunner(v, where) {
+    if (!isPlainObject(v))
+        throw new ShapeError(`${where}: must be an object`);
+    if (v.kind === "capabilities") {
+        exactKeys(v, ["kind", "capability_ids"], where);
+        const ids = v.capability_ids;
+        if (!Array.isArray(ids) || ids.length === 0 || ids.length > MAX_CAPABILITIES_PER_PHASE) {
+            throw new ShapeError(`${where}.capability_ids: must list 1 to ${MAX_CAPABILITIES_PER_PHASE} ids`);
+        }
+        ids.forEach((id, i) => str(id, CAPABILITY_RE, `${where}.capability_ids[${i}]`));
+        if (new Set(ids).size !== ids.length)
+            throw new ShapeError(`${where}.capability_ids: duplicate id`);
+    }
+    else if (v.kind === "code") {
+        exactKeys(v, ["kind", "language", "source", "sha256"], where);
+        str(v.language, LANGUAGE_RE, `${where}.language`);
+        boundedText(v.source, MAX_CODE_BYTES, `${where}.source`);
+        str(v.sha256, SHA256_RE, `${where}.sha256`);
+    }
+    else {
+        throw new ShapeError(`${where}.kind: must be "capabilities" or "code"`);
+    }
+}
+/** Throws ShapeError unless `v` is exactly a signed v1 bundle (typ is checked by the caller). */
+function assertBundleShape(v) {
+    const allowed = [...TOP_LEVEL_REQUIRED, "merge_strategy"];
+    for (const k of Object.keys(v)) {
+        if (!allowed.includes(k))
+            throw new ShapeError(`bundle: unexpected field ${JSON.stringify(k)}`);
+    }
+    for (const k of TOP_LEVEL_REQUIRED) {
+        if (!Object.prototype.hasOwnProperty.call(v, k))
+            throw new ShapeError(`bundle: missing field ${JSON.stringify(k)}`);
+    }
+    str(v.bundle_id, ID_RE, "bundle.bundle_id");
+    str(v.signing_key_id, ID_RE, "bundle.signing_key_id");
+    str(v.org_id, ID_RE, "bundle.org_id");
+    const issued = timestamp(v.issued_at, "bundle.issued_at");
+    const expires = timestamp(v.expires_at, "bundle.expires_at");
+    if (expires <= issued)
+        throw new ShapeError("bundle.expires_at: must be after issued_at");
+    if (expires - issued > MAX_BUNDLE_LIFETIME_SECONDS * 1000) {
+        throw new ShapeError(`bundle: lifetime longer than ${MAX_BUNDLE_LIFETIME_SECONDS} s`);
+    }
+    if (!isPlainObject(v.claim))
+        throw new ShapeError("bundle.claim: must be an object");
+    exactKeys(v.claim, ["session_id", "epoch", "executor_id"], "bundle.claim");
+    str(v.claim.session_id, ID_RE, "bundle.claim.session_id");
+    const epoch = v.claim.epoch;
+    if (typeof epoch !== "number" || !Number.isSafeInteger(epoch) || epoch < 0) {
+        throw new ShapeError("bundle.claim.epoch: must be a non-negative integer");
+    }
+    str(v.claim.executor_id, ID_RE, "bundle.claim.executor_id");
+    if (!isPlainObject(v.contract))
+        throw new ShapeError("bundle.contract: must be an object");
+    exactKeys(v.contract, ["sha256", "version"], "bundle.contract");
+    str(v.contract.sha256, SHA256_RE, "bundle.contract.sha256");
+    const version = v.contract.version;
+    if (typeof version !== "number" || !Number.isSafeInteger(version) || version < 1) {
+        throw new ShapeError("bundle.contract.version: must be a positive integer");
+    }
+    if (!isPlainObject(v.workflow))
+        throw new ShapeError("bundle.workflow: must be an object");
+    exactKeys(v.workflow, ["id", "version"], "bundle.workflow");
+    str(v.workflow.id, ID_RE, "bundle.workflow.id");
+    str(v.workflow.version, WORKFLOW_VERSION_RE, "bundle.workflow.version");
+    if ("merge_strategy" in v &&
+        v.merge_strategy !== "external" &&
+        v.merge_strategy !== "merge_on_green") {
+        throw new ShapeError('bundle.merge_strategy: must be "external" or "merge_on_green"');
+    }
+    const phases = v.phases;
+    if (!Array.isArray(phases) || phases.length === 0 || phases.length > MAX_PHASES) {
+        throw new ShapeError(`bundle.phases: must list 1 to ${MAX_PHASES} phases`);
+    }
+    const names = new Set();
+    phases.forEach((p, i) => {
+        const where = `bundle.phases[${i}]`;
+        if (!isPlainObject(p))
+            throw new ShapeError(`${where}: must be an object`);
+        exactKeys(p, ["order", "name", "prompt", "runner"], where);
+        if (p.order !== i)
+            throw new ShapeError(`${where}.order: must be ${i}`);
+        const name = str(p.name, PHASE_NAME_RE, `${where}.name`);
+        if (names.has(name))
+            throw new ShapeError(`${where}.name: duplicate phase name`);
+        names.add(name);
+        boundedText(p.prompt, MAX_PROMPT_BYTES, `${where}.prompt`);
+        checkRunner(p.runner, `${where}.runner`);
+    });
+    if (typeof v.signature !== "string")
+        throw new ShapeError("bundle.signature: must be a string");
+}
+/** The exact bytes the signature covers: canonical JSON of every field but `signature`. */
+export function signedBytes(bundle) {
+    const { signature: _signature, ...rest } = bundle;
+    return canonicalJson(rest);
+}
+function locateKey(keyOrJwks, kid) {
+    if ("keys" in keyOrJwks && Array.isArray(keyOrJwks.keys)) {
+        const matches = keyOrJwks.keys.filter((k) => k.kid === kid);
+        // An ambiguous kid is not a key a signature can be attributed to.
+        return matches.length === 1 ? matches[0] : null;
+    }
+    return keyOrJwks.kid === kid ? keyOrJwks : null;
+}
+function refuse(reason, detail) {
+    return { valid: false, reason, detail };
+}
+/**
+ * Verify one served bundle against the published key(s). Never throws: any unexpected failure
+ * is a refusal, never a pass.
+ */
+export function verifyServedPhaseBundle(served, keyOrJwks, expect, options = {}) {
+    try {
+        return verifyInner(served, keyOrJwks, expect, options);
+    }
+    catch (err) {
+        return refuse("malformed", `verifier error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function verifyInner(served, keyOrJwks, expect, options) {
+    if (typeof served !== "string")
+        return refuse("malformed", "bundle must be served as text");
+    if (utf8Bytes(served) > MAX_BUNDLE_BYTES) {
+        return refuse("too_large", `bundle is larger than ${MAX_BUNDLE_BYTES} bytes`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(served);
+    }
+    catch {
+        return refuse("malformed", "bundle is not valid JSON");
+    }
+    if (!isPlainObject(parsed))
+        return refuse("malformed", "bundle is not a JSON object");
+    if (parsed.typ !== SERVED_PHASE_BUNDLE_TYP) {
+        return refuse("wrong_typ", `typ is ${JSON.stringify(parsed.typ ?? null)}`);
+    }
+    try {
+        assertBundleShape(parsed);
+    }
+    catch (err) {
+        // assertBundleShape throws only ShapeError.
+        return refuse("schema", err.message);
+    }
+    const bundle = parsed;
+    // Key.
+    const kid = bundle.signing_key_id;
+    const jwk = locateKey(keyOrJwks, kid);
+    if (!jwk)
+        return refuse("unknown_key", `no single published key has kid ${kid}`);
+    if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || typeof jwk.x !== "string") {
+        return refuse("unusable_key", `key ${kid} is not an Ed25519 OKP key`);
+    }
+    const status = jwk.mnemom_ext?.status;
+    if (!USABLE_KEY_STATUSES.has(status)) {
+        return refuse("unusable_key", `key ${kid} has status ${JSON.stringify(status)}`);
+    }
+    if (status === "retired") {
+        const retiredAt = Date.parse(jwk.mnemom_ext?.retired_at ?? "");
+        if (!Number.isFinite(retiredAt) || Date.parse(bundle.issued_at) >= retiredAt) {
+            return refuse("retired_key", `key ${kid} was retired before this bundle was issued`);
+        }
+    }
+    let publicKey;
+    try {
+        publicKey = createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: jwk.x }, format: "jwk" });
+    }
+    catch {
+        return refuse("unusable_key", `key ${kid} could not be imported`);
+    }
+    // Signature over canonical JSON of every field but `signature`.
+    if (!BASE64URL_RE.test(bundle.signature))
+        return refuse("bad_signature", "signature is not base64url");
+    const sig = Buffer.from(bundle.signature, "base64url");
+    if (sig.length !== ED25519_SIGNATURE_BYTES) {
+        return refuse("bad_signature", `signature is ${sig.length} bytes, not ${ED25519_SIGNATURE_BYTES}`);
+    }
+    const message = Buffer.from(signedBytes(parsed), "utf8");
+    if (!cryptoVerify(null, message, publicKey, sig)) {
+        return refuse("bad_signature", `signature does not verify under key ${kid}`);
+    }
+    // Signed, but internally inconsistent: a runner may cache code by its hash.
+    for (const phase of bundle.phases) {
+        if (phase.runner.kind === "code" && sha256Hex(phase.runner.source) !== phase.runner.sha256) {
+            return refuse("code_digest_mismatch", `phase ${phase.order} code sha256 does not match its source`);
+        }
+    }
+    // Time.
+    const now = options.now ? options.now() : Date.now();
+    const skewMs = (options.clockSkewSeconds ?? DEFAULT_CLOCK_SKEW_SECONDS) * 1000;
+    if (Date.parse(bundle.issued_at) > now + skewMs) {
+        return refuse("not_yet_valid", `issued_at ${bundle.issued_at} is in the future`);
+    }
+    if (Date.parse(bundle.expires_at) + skewMs < now) {
+        return refuse("expired", `expired at ${bundle.expires_at}`);
+    }
+    // Binding to the claim this runner holds.
+    const actual = {
+        org_id: bundle.org_id,
+        session_id: bundle.claim.session_id,
+        epoch: bundle.claim.epoch,
+        executor_id: bundle.claim.executor_id,
+        contract_sha256: bundle.contract.sha256,
+        contract_version: bundle.contract.version,
+    };
+    // An untyped caller may pass no expectation at all: that refuses as a binding miss, the same
+    // reason the API's verifier gives, rather than crashing into the catch-all.
+    if (!isPlainObject(expect)) {
+        return refuse("binding_mismatch", "no expected claim binding was given");
+    }
+    for (const field of Object.keys(actual)) {
+        if (expect[field] !== actual[field]) {
+            return refuse("binding_mismatch", `${field} does not match the claim being checked`);
+        }
+    }
+    return { valid: true, bundle, digest: sha256Hex(signedBytes(parsed)), key_id: kid };
+}

package/dist/lib/runner/contract-header.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The sealed contract on every served-phase model request (Doors W-L13, W3.11).
+ *
+ * Every model request of every served phase carries `x-mnemom-contract` with the job's sealed
+ * version and no other. The runner's own proxy states it: the M1 seat proxy strips client
+ * `x-mnemom-*` headers, and a phase must never choose its own contract.
+ *
+ * The value is the contract file's exact bytes (`.mnemom/contracts/<contract_sha256>.json`: the
+ * canonical JSON of the hash-form contract, no trailing newline, so sha256 of the bytes IS the
+ * contract sha256) as base64url, which the gateway's `parseContractHeader` accepts. The runner
+ * binds those bytes to the claim before any request: their sha256 must equal the claim's
+ * `contract_sha256`, which the verified bundle also cites. A mismatch is a refusal, never a
+ * fallback to another copy.
+ */
+export declare const CONTRACT_HEADER = "x-mnemom-contract";
+/** A card agent's pointer to a contract; a served phase never sends one. */
+export declare const CONTRACT_REF_HEADER = "x-mnemom-contract-ref";
+/** The gateway's CONTRACT_JSON_MAX, through the CLI's contract-hash helper. */
+export declare const CONTRACT_FILE_MAX_BYTES = 8192;
+export type SealedContractHeader = {
+    ok: true;
+    value: string;
+    contract_sha256: string;
+} | {
+    ok: false;
+    reason: "bad_sha" | "too_large" | "sha_mismatch" | "not_a_contract";
+    detail: string;
+};
+/**
+ * The header value for one job, or why there is none. `bytes` is the contract file as stored
+ * or as the job read returned it. Nothing is normalised or re-serialised: the bytes that hash to
+ * the seal are the bytes sent.
+ */
+export declare function sealedContractHeader(bytes: Uint8Array, contractSha256: string): SealedContractHeader;
+/**
+ * One outbound request's headers with the sealed contract set. Any contract or contract-ref
+ * header already present (from the phase, its tools or a stale caller) is dropped, whatever its
+ * case, so exactly one `x-mnemom-contract` leaves the runner.
+ */
+export declare function applySealedContract(headers: Record<string, string | string[] | undefined>, value: string): Record<string, string | string[] | undefined>;
+/**
+ * The sha256 an `x-mnemom-contract` value names, when it is the base64url of a contract file
+ * (what this runner sends); null otherwise. Used by the runner's own self-check and by the
+ * `door2-path` header step to assert no request carried another seal.
+ */
+export declare function contractHeaderSha256(value: string): string | null;

package/dist/lib/runner/contract-header.js

@@ -0,0 +1,85 @@
+/**
+ * The sealed contract on every served-phase model request (Doors W-L13, W3.11).
+ *
+ * Every model request of every served phase carries `x-mnemom-contract` with the job's sealed
+ * version and no other. The runner's own proxy states it: the M1 seat proxy strips client
+ * `x-mnemom-*` headers, and a phase must never choose its own contract.
+ *
+ * The value is the contract file's exact bytes (`.mnemom/contracts/<contract_sha256>.json`: the
+ * canonical JSON of the hash-form contract, no trailing newline, so sha256 of the bytes IS the
+ * contract sha256) as base64url, which the gateway's `parseContractHeader` accepts. The runner
+ * binds those bytes to the claim before any request: their sha256 must equal the claim's
+ * `contract_sha256`, which the verified bundle also cites. A mismatch is a refusal, never a
+ * fallback to another copy.
+ */
+import { createHash } from "node:crypto";
+import { CONTRACT_JSON_MAX } from "../contract-hash.js";
+export const CONTRACT_HEADER = "x-mnemom-contract";
+/** A card agent's pointer to a contract; a served phase never sends one. */
+export const CONTRACT_REF_HEADER = "x-mnemom-contract-ref";
+/** The gateway's CONTRACT_JSON_MAX, through the CLI's contract-hash helper. */
+export const CONTRACT_FILE_MAX_BYTES = CONTRACT_JSON_MAX;
+const SHA256_RE = /^[0-9a-f]{64}$/;
+/**
+ * The header value for one job, or why there is none. `bytes` is the contract file as stored
+ * or as the job read returned it. Nothing is normalised or re-serialised: the bytes that hash to
+ * the seal are the bytes sent.
+ */
+export function sealedContractHeader(bytes, contractSha256) {
+    if (!SHA256_RE.test(contractSha256)) {
+        return { ok: false, reason: "bad_sha", detail: "contract_sha256 must be 64 lowercase hex" };
+    }
+    if (bytes.byteLength > CONTRACT_FILE_MAX_BYTES) {
+        return {
+            ok: false,
+            reason: "too_large",
+            detail: `contract is larger than ${CONTRACT_FILE_MAX_BYTES} bytes`,
+        };
+    }
+    const actual = createHash("sha256").update(bytes).digest("hex");
+    if (actual !== contractSha256) {
+        return {
+            ok: false,
+            reason: "sha_mismatch",
+            detail: "contract bytes do not hash to the sealed contract_sha256",
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(bytes).toString("utf8"));
+    }
+    catch {
+        return { ok: false, reason: "not_a_contract", detail: "contract bytes are not JSON" };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { ok: false, reason: "not_a_contract", detail: "contract is not a JSON object" };
+    }
+    return {
+        ok: true,
+        value: Buffer.from(bytes).toString("base64url"),
+        contract_sha256: contractSha256,
+    };
+}
+/**
+ * One outbound request's headers with the sealed contract set. Any contract or contract-ref
+ * header already present (from the phase, its tools or a stale caller) is dropped, whatever its
+ * case, so exactly one `x-mnemom-contract` leaves the runner.
+ */
+export function applySealedContract(headers, value) {
+    const out = Object.fromEntries(Object.entries(headers).filter(([name]) => {
+        const lower = name.toLowerCase();
+        return lower !== CONTRACT_HEADER && lower !== CONTRACT_REF_HEADER;
+    }));
+    out[CONTRACT_HEADER] = value;
+    return out;
+}
+/**
+ * The sha256 an `x-mnemom-contract` value names, when it is the base64url of a contract file
+ * (what this runner sends); null otherwise. Used by the runner's own self-check and by the
+ * `door2-path` header step to assert no request carried another seal.
+ */
+export function contractHeaderSha256(value) {
+    if (!/^[A-Za-z0-9_-]+$/.test(value))
+        return null;
+    return createHash("sha256").update(Buffer.from(value, "base64url")).digest("hex");
+}