@substrat-run/contracts 0.158.0 → 0.160.0

package/dist/wire-signing.js

@@ -0,0 +1,734 @@
+/**
+ * The signed envelope the router and the control plane put on a call to a vertical (RFC
+ * wire-signing, K-58 proposed). Each signs only while its `sign` flag is on and its key is set
+ * (RFC §9, step 2), beside the legacy headers, which stay. The platform's entry module verifies
+ * one, inert until a deployment is given key lists (step 1), and the shared-secret checks in
+ * `wire-auth.ts` and vertical-host's `readRoutedNode` are unchanged.
+ *
+ * Ed25519 over a canonical encoding, the scheme the scope-store envelope already uses (K-52),
+ * with its conventions reused rather than restated: the key id, the raw public key lists, the
+ * strict PKCS8 form, the small-order and canonical-spelling refusals and base64url all come
+ * from `scope-store-envelope.ts`, so a key one module accepts the other accepts too. A vertical
+ * would hold only public keys, a list per issuer, so a key can rotate without a moment where no
+ * key verifies.
+ *
+ * The encoding is fifteen lines joined by `\n`, with no trailing newline, so a verifier in
+ * another language can rebuild it (`test/vectors/wire-envelope.json` is the shared vector):
+ *
+ * ```
+ * substrat-wire/1
+ * router|platform                  iss: which signer, so which key list
+ * route|call                       kind: a routed request, or a call to an internal endpoint
+ * <kid>                            as the store's: base64url of SHA-256's first 8 bytes
+ * <aud>                            the target deployment (the dispatch script name), opaque
+ * <tenant id>                      a ULID, or empty on a call that names no scope
+ * <scope id>                       a ULID, empty exactly when the tenant is
+ * <surface>                        a route's surface; empty on a call
+ * <vertical>                       the vertical slug, or empty
+ * <METHOD>                         upper-case
+ * <sha256 hex of the target>       the request's pathname + search, as UTF-8
+ * <sha256 hex of the body>         a call's exact body bytes; empty on a route
+ * <iat, unix seconds>
+ * <exp, unix seconds>
+ * <nonce, base64url of 16 bytes>
+ * ```
+ *
+ * Which fields a (iss, kind) pair carries is a closed table, {@link wireEnvelopeShape}. The
+ * first line names the protocol, so no message signed under another protocol (a store
+ * envelope's first line is `1`) parses as one of these, whatever key signed it.
+ *
+ * Every refusal of a caller is the same value, {@link WIRE_REFUSED}: a caller cannot tell a wrong
+ * audience from a bad signature, and neither can whoever it answers. The reason goes to
+ * `onRefusal`, for metrics only. A fault of the deployment's own throws instead: a key set it
+ * built some other way, a call expectation with no replay policy (or a cache with no pinned
+ * scope), and a nonce cache that cannot answer.
+ *
+ * Imports nothing but its siblings `scope-store-envelope.ts` and `invocation-record.ts`, which
+ * import nothing, so an entry bundle that imports this subpath pulls in no schema and no zod.
+ */
+import { FIELD_COVERAGE_HEADER, PARENT_REQUEST_ID_HEADER, parentRequestIdOf } from './invocation-record.js';
+import { base64UrlToBytes, bytesToBase64Url, parseScopeStorePublicKeys, ScopeStoreKeyError, scopeStoreKeyId, scopeStoreSignerPublicKey, verifyScopeStoreEnvelope, } from './scope-store-envelope.js';
+export const WIRE_ENVELOPE_VERSION = 1;
+/** The first line of every wire envelope: the protocol and its version. */
+export const WIRE_ENVELOPE_TAG = `substrat-wire/${WIRE_ENVELOPE_VERSION}`;
+/** The request header carrying base64url of the canonical bytes. */
+export const WIRE_ENVELOPE_HEADER = 'x-substrat-wire-envelope';
+/** The request header carrying the base64url signature. */
+export const WIRE_SIGNATURE_HEADER = 'x-substrat-wire-signature';
+/** What a signer gives an envelope when it is not told: `exp = iat + 60`. */
+export const WIRE_ENVELOPE_LIFETIME_SECONDS = 60;
+/** The longest `exp - iat` a verifier accepts, and a signer mints. */
+export const WIRE_ENVELOPE_MAX_LIFETIME_SECONDS = 120;
+/** How far a verifier's clock may be from the signer's, on either side of `[iat, exp]`. */
+export const WIRE_CLOCK_SKEW_SECONDS = 30;
+/**
+ * The (iss, kind) pairs version 1 admits and what each carries. Closed: a pair not here is
+ * refused, so the control plane can never assert a routed request, and a route never claims
+ * to bind a body it does not.
+ */
+const SHAPES = {
+    router: {
+        // An end user's request the router resolved: always a tenant, a scope and a surface. The
+        // body is a stream the router does not buffer, so a route binds none.
+        route: { scope: 'required', surface: 'required', vertical: 'optional', body: 'absent' },
+        // An internal call the router makes itself, such as a peer invocation.
+        call: { scope: 'optional', surface: 'absent', vertical: 'optional', body: 'required' },
+    },
+    platform: {
+        call: { scope: 'optional', surface: 'absent', vertical: 'absent', body: 'required' },
+    },
+};
+/** What an (iss, kind) pair carries, or undefined when version 1 does not admit the pair. */
+export function wireEnvelopeShape(iss, kind) {
+    const byKind = Object.hasOwn(SHAPES, iss) ? SHAPES[iss] : undefined;
+    return byKind && Object.hasOwn(byKind, kind) ? byKind[kind] : undefined;
+}
+const LINES = 15;
+/** The ULID grammar the router asserts and vertical-host's `ROUTED_ID` reads. */
+const ULID = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+/**
+ * An HTTP method token (RFC 9110 `tchar`) with its letters upper-cased, as `wireRequestBinding` gives
+ * it. At most 32 characters: the longest registered method, UPDATEREDIRECTREF, is 17, and the bound
+ * only keeps an unregistered token from making the line unbounded.
+ */
+const METHOD = /^[!#$%&'*+.^_`|~0-9A-Z-]{1,32}$/;
+const DIGEST = /^[0-9a-f]{64}$/;
+// At most 15 digits, no sign and no leading zero: the text `String(n)` gives for an integer below 10^15.
+const SECONDS = /^(0|[1-9]\d{0,14})$/;
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f]/;
+/** Half a surrogate pair: UTF-8 cannot carry it, so the bytes signed would name another string. */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+/** The longest opaque field (aud, surface, vertical), in UTF-16 code units. */
+const MAX_TEXT = 255;
+/** An opaque field: every other field's grammar is ASCII, so this is the one place well-formedness is judged. */
+const isText = (value) => value.length <= MAX_TEXT && !CONTROL.test(value) && !LONE_SURROGATE.test(value);
+/** An envelope's audience, the deployment's script name: present, and text the encoder carries. */
+const isWireAudience = (value) => value !== '' && isText(value);
+/**
+ * Whether `text` is the canonical base64url of exactly `length` bytes, as the store module judges
+ * it: so a kid is 11 characters and a nonce 22, with their unused trailing bits zero.
+ */
+function isCanonicalBase64Url(text, length) {
+    const bytes = base64UrlToBytes(text);
+    return bytes?.length === length && bytesToBase64Url(bytes) === text;
+}
+/** Whether one line's text is what `presence` allows: empty, or a non-empty value `valid` accepts. */
+function admits(presence, value, valid) {
+    if (value === '')
+        return presence !== 'required';
+    return presence !== 'absent' && valid(value);
+}
+/** The claims those bytes name, or undefined when they are not exactly what the encoder emits. */
+export function parseWireEnvelope(canonical) {
+    const lines = canonical.split('\n');
+    if (lines.length !== LINES)
+        return undefined;
+    const [tag, iss, kind, kid, aud, tenantId, scopeId, surface, vertical, method, targetDigest, bodyDigest, iat, exp, nonce] = lines;
+    if (tag !== WIRE_ENVELOPE_TAG)
+        return undefined;
+    const shape = wireEnvelopeShape(iss, kind);
+    if (!shape)
+        return undefined;
+    if (!isCanonicalBase64Url(kid, 8) || !isCanonicalBase64Url(nonce, 16))
+        return undefined;
+    if (!isWireAudience(aud))
+        return undefined;
+    if ((tenantId === '') !== (scopeId === ''))
+        return undefined;
+    if (!admits(shape.scope, tenantId, (id) => ULID.test(id)) || !admits(shape.scope, scopeId, (id) => ULID.test(id)))
+        return undefined;
+    if (!admits(shape.surface, surface, isText) || !admits(shape.vertical, vertical, isText))
+        return undefined;
+    if (!METHOD.test(method) || !DIGEST.test(targetDigest) || !admits(shape.body, bodyDigest, (d) => DIGEST.test(d)))
+        return undefined;
+    if (!SECONDS.test(iat) || !SECONDS.test(exp))
+        return undefined;
+    const orNull = (value) => (value === '' ? null : value);
+    return {
+        v: 1,
+        iss: iss,
+        kind: kind,
+        kid,
+        aud,
+        tenantId: orNull(tenantId),
+        scopeId: orNull(scopeId),
+        surface: orNull(surface),
+        vertical: orNull(vertical),
+        method,
+        targetDigest,
+        bodyDigest: orNull(bodyDigest),
+        iat: Number(iat),
+        exp: Number(exp),
+        nonce,
+    };
+}
+/**
+ * The canonical text a header carries and the claims it names, or undefined when the header is not
+ * base64url of exactly what the encoder emits. Nothing is verified here: the verifier decodes with
+ * this, and an entry may read the claims beforehand only to choose what to verify them against.
+ */
+export function decodeWireEnvelope(header) {
+    const bytes = base64UrlToBytes(header);
+    if (!bytes)
+        return undefined;
+    let canonical;
+    try {
+        // Fatal and BOM-keeping, so decoding and re-encoding gives back exactly these bytes.
+        canonical = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+    const claims = parseWireEnvelope(canonical);
+    return claims ? { canonical, claims } : undefined;
+}
+/**
+ * The encoder's refusal of claims no verifier would accept: a field the parser would refuse, a body
+ * where the pair binds none or none where it binds one, a lifetime past the maximum. Its own class, so
+ * a signer counts it as `claims` and every other throw as `error` (RFC §8).
+ */
+export class WireClaimsError extends Error {
+    name = 'WireClaimsError';
+}
+/** Fifteen lines, no trailing newline. Throws {@link WireClaimsError} on a field the parser would refuse. */
+export function canonicalWireEnvelope(claims) {
+    if (claims.v !== WIRE_ENVELOPE_VERSION)
+        throw new WireClaimsError(`unknown wire envelope version ${claims.v}`);
+    for (const time of [claims.iat, claims.exp]) {
+        if (!Number.isSafeInteger(time) || time < 0)
+            throw new WireClaimsError('a wire envelope time is not a non-negative integer');
+    }
+    const optional = (value) => {
+        if (value === '')
+            throw new WireClaimsError('a wire envelope field is empty: an absent field is null');
+        return value ?? '';
+    };
+    const lines = [
+        WIRE_ENVELOPE_TAG,
+        claims.iss,
+        claims.kind,
+        claims.kid,
+        claims.aud,
+        optional(claims.tenantId),
+        optional(claims.scopeId),
+        optional(claims.surface),
+        optional(claims.vertical),
+        claims.method,
+        claims.targetDigest,
+        optional(claims.bodyDigest),
+        String(claims.iat),
+        String(claims.exp),
+        claims.nonce,
+    ];
+    if (lines.some((line) => line.includes('\n')))
+        throw new WireClaimsError('a wire envelope field contains a newline');
+    const canonical = lines.join('\n');
+    if (!parseWireEnvelope(canonical))
+        throw new WireClaimsError('a wire envelope field is malformed');
+    return canonical;
+}
+function bytesOf(data) {
+    if (typeof data === 'string')
+        return new TextEncoder().encode(data);
+    const view = ArrayBuffer.isView(data) ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) : new Uint8Array(data);
+    // Web Crypto copies what it is given, so only a shared buffer needs copying here, to type as one.
+    return view.buffer instanceof ArrayBuffer ? view : view.slice();
+}
+/** SHA-256 of the exact bytes, lowercase hex: for a string, the store's body digest. */
+export async function wireDigest(data) {
+    const hash = await crypto.subtle.digest('SHA-256', bytesOf(data));
+    return [...new Uint8Array(hash)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * What an envelope binds of a request, read the same way by the signer (from the request it is
+ * about to send) and the verifier (from the request it received): the method, upper-cased, and
+ * the target, the URL's pathname plus its search as the URL API serializes them. The fragment
+ * never travels, and an empty `?` reads as no query on both ends.
+ */
+export function wireRequestBinding(request) {
+    const url = new URL(request.url);
+    return { method: request.method.toUpperCase(), target: `${url.pathname}${url.search}` };
+}
+/** A signing key that is present but cannot be used. Its message never carries the key. */
+export class WireKeyError extends Error {
+    reason;
+    name = 'WireKeyError';
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+    }
+}
+/**
+ * Import a PKCS8 Ed25519 private key (base64url) for signing. The key is judged by the store
+ * module's own check (only the 48-byte PKCS8 v1 form, never a small-order point), so the store
+ * key tooling's `generate` and `doctor` accept and refuse the same values. Throws
+ * {@link WireKeyError} when it is unusable.
+ */
+export async function importWireSigningKey(pkcs8) {
+    let signer;
+    try {
+        signer = await scopeStoreSignerPublicKey(pkcs8);
+    }
+    catch (error) {
+        if (error instanceof ScopeStoreKeyError) {
+            throw new WireKeyError(`the wire signing key is unusable (${error.reason})`, error.reason);
+        }
+        throw error;
+    }
+    // Accepted above, so it decodes. Not extractable: nothing reads it back out of the isolate.
+    const key = await crypto.subtle.importKey('pkcs8', bytesOf(base64UrlToBytes(pkcs8)), { name: 'Ed25519' }, false, ['sign']);
+    return Object.freeze({ kid: signer.kid, publicKey: signer.publicKey, key });
+}
+/** Build, digest and sign one envelope. Throws {@link WireClaimsError} on an input no verifier would accept. */
+export async function signWireEnvelope(key, input) {
+    // A pair the table does not admit fails in the encoder below, as malformed.
+    const body = wireEnvelopeShape(input.iss, input.kind)?.body;
+    if (body === 'absent' && input.body !== undefined)
+        throw new WireClaimsError(`a ${input.kind} envelope binds no body`);
+    // `== null`, as the verifier reads it: a null body is a read that failed, never the empty body.
+    if (body === 'required' && input.body == null)
+        throw new WireClaimsError(`a ${input.kind} envelope binds its body: pass it, empty or not`);
+    const iat = input.iat ?? Math.floor(Date.now() / 1000);
+    const exp = input.exp ?? iat + WIRE_ENVELOPE_LIFETIME_SECONDS;
+    if (!lifetimeAdmitted(iat, exp))
+        throw new WireClaimsError('a wire envelope lives for at most the maximum lifetime, and ends after it starts');
+    const claims = {
+        v: 1,
+        iss: input.iss,
+        kind: input.kind,
+        kid: key.kid,
+        aud: input.aud,
+        tenantId: input.tenantId ?? null,
+        scopeId: input.scopeId ?? null,
+        surface: input.surface ?? null,
+        vertical: input.vertical ?? null,
+        method: input.method,
+        targetDigest: await wireDigest(input.target),
+        bodyDigest: input.body === undefined ? null : await wireDigest(input.body),
+        iat,
+        exp,
+        nonce: input.nonce ?? bytesToBase64Url(crypto.getRandomValues(new Uint8Array(16))),
+    };
+    const canonical = canonicalWireEnvelope(claims);
+    const bytes = new TextEncoder().encode(canonical);
+    const signature = await crypto.subtle.sign('Ed25519', key.key, bytes);
+    return { claims, canonical, header: bytesToBase64Url(bytes), signature: bytesToBase64Url(new Uint8Array(signature)) };
+}
+function lifetimeAdmitted(iat, exp) {
+    return exp > iat && exp - iat <= WIRE_ENVELOPE_MAX_LIFETIME_SECONDS;
+}
+/**
+ * The verifier's own copy of each key set it was handed, by the object returned. The returned maps
+ * are for reading; a caller that mutates one (`keys.platform.set(…)`) changes nothing the verifier
+ * uses, so the both-issuers refusal cannot be undone after the fact.
+ */
+const PREPARED = new WeakMap();
+/**
+ * Each issuer's public keys, from the configured lists: raw Ed25519 keys, base64url, separated
+ * by commas, as the store's lists are and refused for the same faults. An unset or blank list is
+ * no keys, which verifies nothing. Throws on a key listed for both issuers: whoever holds the
+ * router's private key could then sign as the platform.
+ */
+export async function wireVerificationKeys(config) {
+    const listed = (text) => (text?.trim() ? parseScopeStorePublicKeys(text) : []);
+    const router = listed(config.router);
+    const platform = listed(config.platform);
+    if (router.some((key) => platform.includes(key)))
+        throw new Error('a wire public key is listed for both issuers');
+    // The list parser refused a key listed twice, and canonical spelling makes equal text equal bytes.
+    const byKid = async (keys) => new Map(await Promise.all(keys.map(async (key) => [await scopeStoreKeyId(key), key])));
+    const own = Object.freeze({ router: await byKid(router), platform: await byKid(platform) });
+    const keys = Object.freeze({ router: new Map(own.router), platform: new Map(own.platform) });
+    PREPARED.set(keys, own);
+    return keys;
+}
+/** Why an envelope was refused, in the order the verifier checks. For metrics only. */
+export const WIRE_REFUSAL_REASONS = [
+    'missing',
+    'malformed',
+    'issuer',
+    'kind',
+    'kid',
+    'signature',
+    'audience',
+    'lifetime',
+    'not-yet-valid',
+    'expired',
+    'method',
+    'target',
+    'body',
+    'scope',
+    'claim-after-until',
+    'replay',
+];
+export const WIRE_REFUSED = Object.freeze({ ok: false });
+/**
+ * Every check a deployment makes on an envelope, in one fixed order: present, well-formed, the
+ * expected issuer and kind, a listed key id, the signature, then (all over signed bytes) the
+ * audience, the lifetime, the clock, the method, the target, a call's body, any pinned tenant
+ * and scope, and last a call's nonce when its policy keeps them, so an envelope that fails anything
+ * else never spends a cache entry. A route keeps no nonces. `nowSeconds` is the time the request
+ * arrived, not when its body finished reading.
+ *
+ * Returns {@link WIRE_REFUSED} for every failure of the caller's. `onRefusal` hears the reason; a
+ * throw or a rejection from it is ignored. The deployment's own faults throw instead, so no counter
+ * files them under a caller, and they are checked before anything else: a key set
+ * {@link wireVerificationKeys} did not build, a call expectation whose replay policy is neither
+ * `'none'` nor a cache, a cache with no pinned `scopeId` (a cache lives in one scope's object, so
+ * the endpoint pins the scope it claims through), and a cache with no `clockSeconds` function. Two
+ * more are found only when a nonce is about to be claimed, and throw then: a claim clock that reads
+ * something other than a finite, non-negative number of seconds (a promise from an async clock
+ * included), before the cache is asked; and a throw from the cache.
+ */
+export async function verifyWireEnvelope(input) {
+    const refuse = (reason) => {
+        try {
+            // Metrics never decide a verdict, and an async counter that rejects must not crash the isolate.
+            void Promise.resolve(input.onRefusal?.(reason)).catch(() => { });
+        }
+        catch {
+            // A synchronous throw, likewise ignored.
+        }
+        return WIRE_REFUSED;
+    };
+    const { expected, keys, nowSeconds } = input;
+    const own = PREPARED.get(keys);
+    if (!own)
+        throw new TypeError('verifyWireEnvelope takes the key set wireVerificationKeys built');
+    const replay = expected.kind === 'call' ? expected.replay : 'none';
+    if (replay !== 'none' && typeof replay?.claim !== 'function') {
+        throw new TypeError("a call's expectation states its replay policy: 'none' or a nonce cache");
+    }
+    // `== null`: an untyped `scopeId: null` pins nothing, so it is the same fault as leaving it out.
+    if (replay !== 'none' && expected.scopeId == null) {
+        throw new TypeError('a call that keeps nonces pins the scope whose object holds them');
+    }
+    // The claim clock is the deployment's, like `nowSeconds`; a default would mix an injected clock
+    // with the wall clock, so a call that keeps nonces must hand it over, and it is checked here.
+    if (replay !== 'none' && typeof input.clockSeconds !== 'function') {
+        throw new TypeError('a call that keeps nonces takes a clockSeconds function to time its claim');
+    }
+    const header = input.headers.get(WIRE_ENVELOPE_HEADER);
+    const signature = input.headers.get(WIRE_SIGNATURE_HEADER);
+    if (!header || !signature)
+        return refuse('missing');
+    const decoded = decodeWireEnvelope(header);
+    if (!decoded)
+        return refuse('malformed');
+    const { canonical, claims } = decoded;
+    if (claims.iss !== expected.iss)
+        return refuse('issuer');
+    if (claims.kind !== expected.kind)
+        return refuse('kind');
+    const publicKey = own[claims.iss].get(claims.kid);
+    if (!publicKey)
+        return refuse('kid');
+    if (!(await verifyScopeStoreEnvelope(publicKey, canonical, signature)))
+        return refuse('signature');
+    if (claims.aud !== expected.aud)
+        return refuse('audience');
+    if (!lifetimeAdmitted(claims.iat, claims.exp))
+        return refuse('lifetime');
+    // Negated, so a clock that is not a number fails both instead of passing both.
+    if (!(nowSeconds >= claims.iat - WIRE_CLOCK_SKEW_SECONDS))
+        return refuse('not-yet-valid');
+    if (!(nowSeconds <= claims.exp + WIRE_CLOCK_SKEW_SECONDS))
+        return refuse('expired');
+    if (claims.method !== expected.method)
+        return refuse('method');
+    if (claims.targetDigest !== (await wireDigest(expected.target)))
+        return refuse('target');
+    if (expected.kind === 'call') {
+        // A reader is read here and nowhere earlier. The type requires a call's body; an untyped caller
+        // that leaves it out, or hands over the null of a body read that failed, is refused, never read
+        // as an empty body.
+        const body = typeof expected.body === 'function' ? await expected.body() : expected.body;
+        if (body == null || claims.bodyDigest !== (await wireDigest(body)))
+            return refuse('body');
+    }
+    if (expected.tenantId !== undefined && claims.tenantId !== expected.tenantId)
+        return refuse('scope');
+    if (expected.scopeId !== undefined && claims.scopeId !== expected.scopeId)
+        return refuse('scope');
+    if (replay !== 'none') {
+        const until = claims.exp + WIRE_CLOCK_SKEW_SECONDS;
+        const claimedAt = input.clockSeconds();
+        // The claim clock is the deployment's: a reading that is not a time is its fault, never a
+        // caller's reason, and a negative one never reaches the cache. `Number.isFinite` does not coerce,
+        // so it refuses a string, null or a promise as well as NaN and the infinities.
+        if (!Number.isFinite(claimedAt) || claimedAt < 0) {
+            throw new TypeError('clockSeconds read something other than a time in seconds');
+        }
+        // A cache may forget the nonce after `until`, so a claim made later could not see a replay. Its
+        // own reason, so a slow body is not counted as one.
+        if (!(claimedAt <= until))
+            return refuse('claim-after-until');
+        if ((await replay.claim(claims.nonce, until)) !== true)
+            return refuse('replay');
+    }
+    return { ok: true, claims };
+}
+/*
+ * What a deployment is given at upload (RFC §5, §6) and what its entry writes per request (§8).
+ * Named here, beside the envelope, so the entry that reads them and the uploader and readiness
+ * report that will write and read them spell them one way.
+ */
+/** The router's public keys, a comma-separated list. Plain configuration: public keys are not secret. */
+export const WIRE_ROUTER_KEYS_VAR = 'SUBSTRAT_WIRE_ROUTER_KEYS';
+/** The control plane's public keys, a comma-separated list. */
+export const WIRE_PLATFORM_KEYS_VAR = 'SUBSTRAT_WIRE_PLATFORM_KEYS';
+/** The deployment's own dispatch name, which an envelope's `aud` must equal. */
+export const WIRE_AUDIENCE_VAR = 'SUBSTRAT_WIRE_AUDIENCE';
+/** The environment's down-channel state, one of {@link WIRE_STATES}. */
+export const WIRE_STATE_VAR = 'SUBSTRAT_WIRE_STATE';
+/** What a deployment accepts on a call down (RFC §5). */
+export const WIRE_STATES = ['legacy-only', 'dual', 'signed-only'];
+/**
+ * A deployment's state from what its upload carries (RFC §5, Q3). No key list at all is
+ * `legacy-only` whatever the setting says, so a deployment no upload gave keys behaves as it
+ * did before the verifier existed. With keys, an explicit `legacy-only` or `signed-only` is
+ * taken as said, and anything else (missing, unknown) reads as `dual`: a wrong value fails
+ * toward accepting what is accepted today.
+ */
+export function wireStateOf(config) {
+    const listed = (value) => typeof value === 'string' && value.trim() !== '';
+    if (!listed(config.routerKeys) && !listed(config.platformKeys))
+        return 'legacy-only';
+    return config.state === 'legacy-only' || config.state === 'signed-only' ? config.state : 'dual';
+}
+/**
+ * The only state an upload gives a deployment in step 2 (RFC §9): `dual`. Moving a deployment to
+ * `signed-only` is a later, separate step (the flip, follow-on 7), a person's act behind its own
+ * gate, so no code that injects settings here can name it.
+ */
+export const WIRE_UPLOAD_STATE = 'dual';
+/**
+ * What one upload gives the deployment it uploads as `audience` (RFC §5, §6, step 2), as the settings
+ * the entry reads: both key lists, its own name for the audience check, and the state
+ * {@link WIRE_UPLOAD_STATE}. The uploader writes them as plain configuration. The lists are judged first
+ * by {@link wireVerificationKeys}, the very function the entry loads them with, so an upload never gives
+ * a deployment lists its verifier would refuse: it throws instead, and the caller gives nothing. Each
+ * list must hold at least one key, and the audience must be one the encoder admits. Answers the kids
+ * each list names, for the capability record (RFC §7, Q8).
+ */
+export async function wireUploadSettings(input) {
+    if (!isWireAudience(input.audience))
+        throw new Error('a wire audience is a script name of 1 to 255 characters');
+    const keys = await wireVerificationKeys({ router: input.routerKeys, platform: input.platformKeys });
+    const routerKids = [...keys.router.keys()];
+    const platformKids = [...keys.platform.keys()];
+    if (routerKids.length === 0 || platformKids.length === 0)
+        throw new Error('each wire issuer lists at least one key');
+    return {
+        settings: [
+            { name: WIRE_ROUTER_KEYS_VAR, text: input.routerKeys.trim() },
+            { name: WIRE_PLATFORM_KEYS_VAR, text: input.platformKeys.trim() },
+            { name: WIRE_AUDIENCE_VAR, text: input.audience },
+            { name: WIRE_STATE_VAR, text: WIRE_UPLOAD_STATE },
+        ],
+        routerKids,
+        platformKids,
+    };
+}
+const ROUTE_ENDPOINT = Object.freeze({ kind: 'route', issuers: Object.freeze(['router']) });
+const CALL_ENDPOINT = Object.freeze({ kind: 'call', issuers: Object.freeze(['platform']) });
+const PEER_INVOKE_ENDPOINT = Object.freeze({ kind: 'call', issuers: Object.freeze(['platform', 'router']) });
+/** Decode `path` with `decoder`, skipping any run of escapes it cannot decode: Hono's `tryDecode`. */
+function tryDecode(path, decoder) {
+    try {
+        return decoder(path);
+    }
+    catch {
+        return path.replace(/(?:%[0-9A-Fa-f]{2})+/g, (run) => {
+            try {
+                return decoder(run);
+            }
+            catch {
+                return run;
+            }
+        });
+    }
+}
+/** Empty and `.` segments dropped and `..` resolved, as a lenient router could read the path. */
+function collapsed(path) {
+    const segments = [];
+    for (const segment of path.split('/')) {
+        if (segment === '..')
+            segments.pop();
+        else if (segment !== '' && segment !== '.')
+            segments.push(segment);
+    }
+    return `/${segments.join('/')}`;
+}
+const INTERNAL = /^\/internal(?:\/|$)/i;
+/**
+ * Which envelope a deployment's endpoint accepts (RFC §3.4, check 3), by the request's path. The
+ * internal surface vertical-host's `mountPlatformSurface` gates (`/internal/*`) takes calls from
+ * the control plane, and its peer invocation (`/internal/vertical-invoke`) from the router too,
+ * which makes those calls. Every other path is a routed request. A verifier judges by this, and a
+ * signer signs what it says.
+ *
+ * The surface is matched on the path its router decodes (Hono's `getPath`: `decodeURI`, with `%25`
+ * kept escaped), so the path is judged in every form a router could read it: as sent, decoded that
+ * way, decoded fully, each with empty and dot segments collapsed, in any letter case. Any form under
+ * `/internal` makes it a call: the stricter reading wins. Only the exact path the router sends a peer
+ * invocation to admits the router.
+ */
+export function wireEndpoint(pathname) {
+    const routed = tryDecode(pathname.includes('%25') ? pathname.replace(/%25/g, '%2525') : pathname, decodeURI);
+    const forms = [pathname, routed, tryDecode(pathname, decodeURIComponent)];
+    if (!forms.some((form) => INTERNAL.test(form) || INTERNAL.test(collapsed(form))))
+        return ROUTE_ENDPOINT;
+    return pathname === '/internal/vertical-invoke' ? PEER_INVOKE_ENDPOINT : CALL_ENDPOINT;
+}
+/**
+ * The internal calls that take a body but change nothing, so a call to one keeps no nonce memory
+ * (RFC §4): each only reads the scope it names. Named by the exact path the platform calls, so any
+ * other spelling of one keeps nonces.
+ */
+export const WIRE_REPLAY_FREE_CALLS = Object.freeze([
+    '/internal/query',
+    '/internal/redrain-count',
+    '/internal/lifecycle-flow',
+    '/internal/operation-series',
+    '/internal/connector-grants',
+]);
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+/**
+ * A call's replay policy as its endpoint states it (RFC §4), never inferred from what an envelope
+ * names: `'none'` for a safe method or a call {@link WIRE_REPLAY_FREE_CALLS} lists, and `'nonce'`
+ * for every other call, a new endpoint included, whether or not its envelope names a scope. A call
+ * that keeps nonces and names no scope has no store to spend one in, which is its deployment's fault.
+ */
+export function wireReplayOf(method, pathname) {
+    return SAFE_METHODS.has(method.toUpperCase()) || WIRE_REPLAY_FREE_CALLS.includes(pathname) ? 'none' : 'nonce';
+}
+/**
+ * How one request fared (RFC §8). `legacy-accepted` is an envelope refused beside a legacy
+ * credential that was valid, and carries the refusal's reason; `refused` is an envelope refused
+ * with no valid legacy credential beside it.
+ */
+export const WIRE_OUTCOMES = ['signed-accepted', 'legacy-accepted', 'dual-mismatch', 'refused', 'fault'];
+/**
+ * Which of the deployment's own faults a `fault` was: its key lists could not be loaded, it has
+ * no nonce store for a call that needs one, its nonce store threw or did not answer in time, or
+ * the verifier threw for any other reason.
+ */
+export const WIRE_FAULTS = ['keys', 'no-nonce-store', 'nonce-store', 'verifier'];
+/*
+ * The signers (RFC §5, §9 step 2): the router signs a route and its own calls, the control plane
+ * signs its calls. Both decide through {@link wireSignerOf}, so they read their flag and their key,
+ * put an envelope on a request and fall back when they cannot in exactly one way. The legacy
+ * headers stay.
+ */
+/**
+ * Whether a signer's `sign` flag (RFC §5) is on: exactly `on`, around whitespace. Absent, empty or
+ * anything else is off, so a signer nobody configured adds nothing to any request.
+ */
+export function wireSigningOn(value) {
+    return typeof value === 'string' && value.trim() === 'on';
+}
+/** One isolate's signing key, imported once per configured value. */
+let importedKey;
+/**
+ * {@link importWireSigningKey}, once per isolate for a given value: the signer's key is imported on
+ * the first request that needs it and reused after. A value that will not import keeps rejecting,
+ * with the same {@link WireKeyError}, until the value changes.
+ */
+export function wireSigningKeyOf(pkcs8) {
+    if (importedKey?.pkcs8 !== pkcs8)
+        importedKey = { pkcs8, key: importWireSigningKey(pkcs8) };
+    return importedKey.key;
+}
+/**
+ * The request with one fresh envelope on it ({@link WIRE_ENVELOPE_HEADER} and
+ * {@link WIRE_SIGNATURE_HEADER}), every other header kept as it was. The method and target are read
+ * with {@link wireRequestBinding}, as the verifier reads them. A call binds the request's exact body,
+ * read whole here and handed on as the same bytes (an absent body is the empty one, as the verifier
+ * reads it); a route binds none, and its body is not read. Sign each attempt: a resend carries a
+ * spent nonce (RFC §4).
+ */
+export async function signWireRequest(key, request, claims) {
+    return signedWith(key, request, claims, await bodyToBind(request, claims.kind));
+}
+/** A call's body, read once to be bound; a route binds none and its body is not read. */
+const bodyToBind = async (request, kind) => (kind === 'call' && request.body !== null ? request.arrayBuffer() : undefined);
+/** {@link signWireRequest} over a body already read (`undefined` for a route, or an absent body). */
+async function signedWith(key, request, claims, body) {
+    const { method, target } = wireRequestBinding(request);
+    const issued = await signWireEnvelope(key, { ...claims, method, target, ...(claims.kind === 'call' ? { body: body ?? '' } : {}) });
+    const headers = new Headers(request.headers);
+    headers.set(WIRE_ENVELOPE_HEADER, issued.header);
+    headers.set(WIRE_SIGNATURE_HEADER, issued.signature);
+    return new Request(request, body === undefined ? { headers } : { headers, body });
+}
+/**
+ * A signer's whole decision (RFC §5, §8): `null` while its `sign` flag is off, which is the default,
+ * so nothing is read and nothing is signed. On, each request is signed afresh with the key, imported
+ * once per isolate. A signer that cannot sign never fails the request: it is handed back with its
+ * legacy headers and its whole body (a call's body is read once, and the request rebuilt from those
+ * bytes when signing fails after reading it), and the result says why, never with the key.
+ */
+export function wireSignerOf(settings) {
+    if (!wireSigningOn(settings.sign))
+        return null;
+    const pkcs8 = settings.key;
+    if (!pkcs8)
+        return async (request) => ({ request, outcome: 'failed', reason: 'unset' });
+    return async (request, claims, named) => {
+        let key;
+        try {
+            key = await wireSigningKeyOf(pkcs8);
+        }
+        catch (error) {
+            return { request, outcome: 'failed', reason: error instanceof WireKeyError ? error.reason : 'error' };
+        }
+        let body;
+        try {
+            body = await bodyToBind(request, claims.kind);
+            return { request: await signedWith(key, request, { ...claims, ...named?.(request, body) }, body), outcome: 'signed' };
+        }
+        catch (error) {
+            // `claims` only for the encoder's own refusal; a body that cannot be read, a throw from
+            // `named`, the rebuild or the signing call is `error`. A body read before the failure goes
+            // back on the request, so it is sent whole.
+            const reason = error instanceof WireClaimsError ? 'claims' : 'error';
+            return { request: body === undefined ? request : new Request(request, { body }), outcome: 'failed', reason };
+        }
+    };
+}
+/**
+ * The headers the router adds that the envelope does not sign, listed by name as carrying no
+ * authority (RFC §5, decided in step 2), with the kind of request each rides on and the check its
+ * own reader applies: the field-coverage sample on a route (the dispatch id that arms the
+ * per-response field walk, one ULID as vertical-host reads it) and a peer call's parent request id
+ * on a call (which links the target's line to the request that made it, read by
+ * {@link parentRequestIdOf}). Each is a claim its reader already treats as one: the walk's report
+ * counts only when the router's own line names its dispatch id, and the parent id only relates two
+ * lines. So when the envelope alone admits a request, the entry hands each on, on its own kind of
+ * request, when its value passes that check, and drops it otherwise, as it drops every other
+ * `x-substrat-*` header the envelope did not sign. Signing them instead would take a new envelope
+ * version (`substrat-wire/2`).
+ */
+const UNSIGNED = Object.freeze([
+    [FIELD_COVERAGE_HEADER, 'route', (value) => ULID.test(value)],
+    [PARENT_REQUEST_ID_HEADER, 'call', (value) => parentRequestIdOf(value) !== undefined],
+]);
+/** The listed headers by name, each with the kind of request it rides on. */
+export const WIRE_UNSIGNED_HEADERS = Object.freeze(Object.fromEntries(UNSIGNED.map(([name, kind]) => [name, kind])));
+/**
+ * The listed headers ({@link WIRE_UNSIGNED_HEADERS}) a request of `kind` hands on, as name and value:
+ * only those listed for that kind, and only a value its reader's check accepts. A header sent twice
+ * reads as both values joined, which is not one id, so it is dropped whole.
+ */
+export function wireUnsignedHeadersOf(kind, headers) {
+    const kept = [];
+    for (const [name, on, valid] of UNSIGNED) {
+        const value = on === kind ? headers.get(name) : null;
+        if (value !== null && valid(value))
+            kept.push([name, value]);
+    }
+    return kept;
+}
+//# sourceMappingURL=wire-signing.js.map