@north-light/api 0.3.580 → 0.3.588

package/dist/core/command-plugins/transport/http-plan.d.ts

@@ -0,0 +1,75 @@
+import type { InputParam, Field } from '../../help.js';
+import type { RestMapping, ManifestTimeouts } from '../../../api/command-manifest/schema.js';
+import type { LeafRunContext } from '../../command.js';
+export interface HttpInvokerSpec {
+    /** The effective registration: local name, manifest endpoint, optional auth env var. */
+    registration: {
+        name: string;
+        endpoint: string;
+        authEnv?: string;
+    };
+    /** Manifest-level REST base override (§4.2); falls back to the endpoint origin. */
+    baseUrl?: string;
+    /** Manifest-level timeout overrides (§6.6); each clock has a crtr default. */
+    timeouts?: ManifestTimeouts;
+    /** Declared leaf params (authored kebab names), used to resolve descriptors + presence. */
+    params: InputParam[];
+    /** The validated REST mapping for this leaf. */
+    rest: RestMapping;
+    /** Declared output fields — validated against a unary 2xx body before render. */
+    output: Field[];
+    /** Full canonical command path, e.g. ['device', 'reboot'] — for error labels only. */
+    commandPath: string[];
+}
+/** The caller controls credentials and correlation, never a manifest parameter. */
+export interface RequestPlanOptions {
+    authorization: string | null;
+    requestId: string;
+    /** The trace id a provider call carries on as `traceparent: 00-<trace>-<new parent>-00`; absent sends none. */
+    traceId?: string;
+    extraHeaders: Record<string, string>;
+    fileMode: 'read-local' | 'pass-through';
+}
+/** A fully-built request plan — everything needed to open the socket, computed
+ *  before any network I/O so pre-network failures (auth/file/header) surface
+ *  through the ordinary structured error path without a socket ever opening. */
+export interface RequestPlan {
+    url: URL;
+    method: string;
+    /** Case-insensitively deduplicated headers in §6.1 application order. */
+    headers: Record<string, string>;
+    /** JSON request body, or undefined when the assembled body has no keys. */
+    body?: string;
+}
+export declare function buildRequestPlan(spec: HttpInvokerSpec, input: Record<string, unknown>, context: LeafRunContext | undefined, options: RequestPlanOptions): RequestPlan;
+/** Read the local file a `type:"path"` param names (relative paths resolve
+ *  against the caller's cwd) and return its content per the param's `encoding`.
+ *  Shared by the HTTP-plugin plan and the provider-leaf adapter, so every
+ *  transport ships file content and none ships the path string. */
+export declare function readPathParam(commandLabel: string, param: InputParam, value: unknown): unknown;
+/** Map a unary 2xx body to the validated result object, or throw
+ *  cli_protocol_error (GENERAL) for bad JSON / a non-object / an output mismatch. */
+export declare function mapUnary2xx(spec: HttpInvokerSpec, body: string): Record<string, unknown>;
+/** Extract a non-2xx error. A conforming nested `{ error: { code, message,
+ *  field?, next? } }` with an acceptable snake_case, non-reserved code becomes a
+ *  CrtrError carrying that code; a reserved/ill-formed code demotes to
+ *  cli_protocol_error; a missing/malformed/nonconforming envelope becomes
+ *  cli_http_error. The HTTP status supplies the exit code in every case, and
+ *  rides its own `http_status` slot — never `received`, which names the CALLER's
+ *  offending value and would otherwise make the backend look like it was
+ *  complaining about the number 400. A backend that supplies its own `received`
+ *  keeps it. This is error-envelope extraction, not success-envelope
+ *  unwrapping. Always throws. */
+export declare function throwNon2xx(spec: HttpInvokerSpec, status: number, body: string): never;
+/** Parsed provider/backend error body, without any CLI exit policy. */
+export interface HttpErrorEnvelope {
+    code: string;
+    message: string;
+    field?: string;
+    received?: unknown;
+    next?: string;
+    manifestStale: boolean;
+    /** Provider approval payload, preserved for the daemon to validate. */
+    question?: unknown;
+}
+export declare function parseHttpError(body: string): HttpErrorEnvelope | null;

package/dist/core/command-plugins/transport/http-plan.js

@@ -0,0 +1,349 @@
+// Shared HTTP-plugin mapping: request assembly and response decoding only. This
+// module never opens a socket. The CLI supplies local-file mode; the daemon
+// supplies already-uploaded file URLs and its own immutable correlation headers.
+import { readFileSync, statSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { validateDeclaredResult } from '../../../api/command-manifest/result.js';
+import { CrtrError } from '../../errors.js';
+import { envelopeClaimsStale, staleErrorDetails } from '../../manifest-stale.js';
+import { ExitCode } from '../../../types.js';
+import { isRecord } from '../../../shared/predicates.js';
+import { trimHeaderValue } from './sign.js';
+import { outboundTraceparent } from '../../../shared/traceparent.js';
+// Strict snake_case: no leading/trailing underscore, no consecutive underscores.
+const SNAKE = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
+// Codes crtr owns; a backend must not reuse them in a non-2xx error envelope.
+const RESERVED_CODES = new Set(['internal', 'unknown_path', 'command_collision', 'cli_protocol_error']);
+// A provider manifest cannot supply runtime-owned values through header params.
+const DAEMON_HEADERS = new Set([
+    'authorization', 'crtr-request-id', 'crtr-run-id', 'crtr-approval',
+    'crtr-upload-id', 'crtr-upload-link', 'accept', 'content-type',
+    'crtr-caller', 'crtr-signature', 'traceparent',
+]);
+// Names no manifest mapping may set in either file mode: the caller context and
+// signature are runtime-minted, and Crtr-Request-Id is the signature's nonce.
+const NEVER_MAPPED_HEADERS = new Set(['crtr-caller', 'crtr-signature', 'crtr-request-id']);
+// Request construction (§6.1) — pure, no network I/O
+export function buildRequestPlan(spec, input, context, options) {
+    const paramsByName = new Map();
+    for (const p of spec.params)
+        paramsByName.set(p.name, p);
+    const entries = Object.entries(spec.rest.params);
+    // 1 + 2a: base + path placeholder substitution (URL-encoded).
+    const base = spec.baseUrl ?? new URL(spec.registration.endpoint).origin;
+    let pathname = spec.rest.path;
+    for (const [name, mapping] of entries) {
+        if (mapping.in !== 'path')
+            continue;
+        const value = input[paramKey(name)];
+        pathname = pathname.split(`{${name}}`).join(encodePathSegmentValue(value));
+    }
+    const url = new URL(pathname, base);
+    // 2b: query params under `as ?? name`, canonically stringified, absent optionals omitted.
+    for (const [name, mapping] of entries) {
+        if (mapping.in !== 'query')
+            continue;
+        const key = paramKey(name);
+        if (!isPresent(paramsByName.get(name), key, input, context))
+            continue;
+        url.searchParams.append(mapping.as ?? name, String(input[key]));
+    }
+    // 3 + 4: assemble body (with file materialization + coalesced-source precedence).
+    const body = assembleBody(spec, entries, paramsByName, input, context, options.fileMode);
+    const bodyString = Object.keys(body).length > 0 ? JSON.stringify(body) : undefined;
+    // Local mode retains the original order (including manifest last-write-wins).
+    // Provider mode applies runtime-owned headers last and refuses reserved names
+    // in manifest mappings, so untrusted input cannot impersonate the runtime.
+    const headers = {};
+    const setHeader = (name, value) => {
+        // A Record must not carry casing variants that a different HTTP sender
+        // could interpret differently. Keep Node's original last-write-wins order.
+        const previous = Object.keys(headers).find((key) => key.toLowerCase() === name.toLowerCase());
+        if (previous !== undefined)
+            delete headers[previous];
+        // A receiving HTTP parser (Node's included) drops leading and trailing optional whitespace from a header value,
+        // so the plan carries the value as the receiver will see it: what is signed is then exactly what the plugin hashes.
+        headers[name] = trimHeaderValue(value);
+    };
+    setHeader('Accept', 'application/json');
+    setHeader('Crtr-Request-Id', options.requestId);
+    if (options.authorization !== null)
+        setHeader('Authorization', options.authorization);
+    for (const [name, mapping] of entries) {
+        if (mapping.in !== 'header')
+            continue;
+        const key = paramKey(name);
+        if (!isPresent(paramsByName.get(name), key, input, context))
+            continue;
+        const headerName = mapping.as; // schema guarantees `as` on header placement
+        if (NEVER_MAPPED_HEADERS.has(headerName.toLowerCase())
+            || (options.fileMode === 'pass-through' && DAEMON_HEADERS.has(headerName.toLowerCase()))) {
+            throw new CrtrError('invalid_type', `${label(spec)}: header "${headerName}" is reserved for the runtime`, ExitCode.USAGE, { field: name, next: 'Remove the runtime-owned header mapping from the manifest.' });
+        }
+        const value = String(input[key]);
+        if (/[\r\n]/.test(value)) {
+            throw new CrtrError('invalid_type', `${label(spec)}: header "${headerName}" value must not contain a newline`, ExitCode.USAGE, { field: name, received: '(newline in header value)', next: 'Remove newline characters from the value.' });
+        }
+        setHeader(headerName, value);
+    }
+    if (bodyString !== undefined)
+        setHeader('Content-Type', 'application/json');
+    for (const [name, value] of Object.entries(options.extraHeaders)) {
+        if (options.fileMode === 'pass-through' && /[\r\n]/.test(value)) {
+            throw new CrtrError('invalid_type', `${label(spec)}: header "${name}" value must not contain a newline`, ExitCode.USAGE);
+        }
+        setHeader(name, value);
+    }
+    if (options.fileMode === 'pass-through') {
+        // Runtime-owned headers take precedence even if extraHeaders uses a
+        // differently-cased key; Accept/Content-Type are fixed by the wire contract.
+        setHeader('Accept', 'application/json');
+        if (bodyString !== undefined)
+            setHeader('Content-Type', 'application/json');
+        else {
+            const contentType = Object.keys(headers).find((key) => key.toLowerCase() === 'content-type');
+            if (contentType !== undefined)
+                delete headers[contentType];
+        }
+        setHeader('Crtr-Request-Id', options.requestId);
+        if (options.traceId !== undefined)
+            setHeader('traceparent', outboundTraceparent(options.traceId));
+        if (options.authorization !== null)
+            setHeader('Authorization', options.authorization);
+        else {
+            const authorization = Object.keys(headers).find((key) => key.toLowerCase() === 'authorization');
+            if (authorization !== undefined)
+                delete headers[authorization];
+        }
+    }
+    return { url, method: spec.rest.method, headers, ...(bodyString !== undefined ? { body: bodyString } : {}) };
+}
+/** Assemble the JSON body object from `rest.body` constants, `rest.bodyRoot`
+ *  nesting, and `in:"body"` params under `as ?? name`, resolving each coalesced
+ *  group (one stdin + one non-stdin sharing an `as`) by non-stdin-then-stdin
+ *  precedence, and materializing local-file params. */
+function assembleBody(spec, entries, paramsByName, input, context, fileMode) {
+    // Group body params by their effective destination key (`as ?? name`).
+    const groups = new Map();
+    for (const [name, mapping] of entries) {
+        if (mapping.in !== 'body')
+            continue;
+        const asName = mapping.as ?? name;
+        const group = groups.get(asName);
+        if (group !== undefined)
+            group.push(name);
+        else
+            groups.set(asName, [name]);
+    }
+    const paramValues = {};
+    for (const [asName, memberNames] of groups) {
+        const members = memberNames.map((name) => ({ name, param: paramsByName.get(name) }));
+        // A group is either a single source or the validator-approved coalesced pair
+        // (exactly one stdin + one non-stdin). Non-stdin wins when present; else the
+        // stdin value when present (including an intentionally-empty non-TTY stream);
+        // else the key is omitted. This same logic covers the single-source case.
+        const nonStdin = members.find((m) => m.param.kind !== 'stdin');
+        const stdin = members.find((m) => m.param.kind === 'stdin');
+        let chosen;
+        if (nonStdin !== undefined && isPresent(nonStdin.param, paramKey(nonStdin.name), input, context)) {
+            chosen = { param: nonStdin.param, value: input[paramKey(nonStdin.name)] };
+        }
+        else if (stdin !== undefined && isPresent(stdin.param, paramKey(stdin.name), input, context)) {
+            chosen = { param: stdin.param, value: input[paramKey(stdin.name)] };
+        }
+        if (chosen !== undefined)
+            paramValues[asName] = materializeBodyValue(spec, chosen.param, chosen.value, fileMode);
+    }
+    // rest.body constants (e.g. an `op` discriminator) always stay top-level.
+    // Param-sourced values nest under rest.bodyRoot when set (always present as an
+    // object there, even when empty, so a backend dispatching on a constant sees a
+    // consistent shape); absent bodyRoot keeps the pre-existing top-level placement.
+    const body = { ...spec.rest.body };
+    if (spec.rest.bodyRoot !== undefined) {
+        body[spec.rest.bodyRoot] = paramValues;
+    }
+    else {
+        Object.assign(body, paramValues);
+    }
+    return body;
+}
+/** Turn a present body value into what actually ships: a `context-file` value is
+ *  already JSON-parsed by parseArgv and placed unchanged; a `type:"path"` param
+ *  (positional or flag) is a filesystem path resolved against cwd whose FILE is
+ *  read and encoded per the param's `encoding` — UTF-8 text by default, base64 of
+ *  the raw bytes when `encoding: "base64"` (the local path string is never sent,
+ *  so the wire contract is identical to piping the encoded bytes); every other
+ *  value keeps its parsed primitive/value type.
+ *
+ *  Strict: a path that does not exist or is not a regular file fails here, before
+ *  any socket opens. There is no fallback to sending the path string — that is
+ *  exactly the confusion this affordance exists to remove. */
+function materializeBodyValue(spec, param, value, fileMode) {
+    if (fileMode === 'pass-through')
+        return value;
+    if (param.kind === 'context-file')
+        return value;
+    if ((param.kind === 'positional' || param.kind === 'flag') && param.type === 'path')
+        return readPathParam(label(spec), param, value);
+    return value;
+}
+/** Read the local file a `type:"path"` param names (relative paths resolve
+ *  against the caller's cwd) and return its content per the param's `encoding`.
+ *  Shared by the HTTP-plugin plan and the provider-leaf adapter, so every
+ *  transport ships file content and none ships the path string. */
+export function readPathParam(commandLabel, param, value) {
+    if (Array.isArray(value))
+        return value.map((item) => readPathParam(commandLabel, param, item));
+    const filePath = String(value);
+    const resolved = resolvePath(process.cwd(), filePath);
+    let stat;
+    try {
+        stat = statSync(resolved);
+    }
+    catch {
+        throw fileError(commandLabel, param.name, filePath, 'no file exists at that path', 'an existing local file path');
+    }
+    if (!stat.isFile()) {
+        throw fileError(commandLabel, param.name, filePath, 'the path is not a regular file', 'a regular local file (not a directory, socket, or device)');
+    }
+    try {
+        return 'encoding' in param && param.encoding === 'base64'
+            ? readFileSync(resolved).toString('base64')
+            : readFileSync(resolved, 'utf8');
+    }
+    catch {
+        throw fileError(commandLabel, param.name, filePath, 'the file could not be read', 'a readable local file path');
+    }
+}
+function fileError(commandLabel, paramName, filePath, detail, expected) {
+    return new CrtrError('invalid_type', `${commandLabel}: cannot read file for "${paramName}" — ${detail}: ${filePath}`, ExitCode.USAGE, { field: paramName, received: filePath, next: `Pass ${expected}, relative to the current directory or absolute.` });
+}
+/** Presence of an optional input (§6.1: a param the caller did not supply
+ *  contributes nothing, even when it carries a default). The parser's
+ *  provided-set is authoritative for every param kind — it already excludes
+ *  bool-flag/default-seeded values and (for stdin specifically) distinguishes
+ *  an intentionally-empty non-TTY stream from a truly absent TTY. Falls back to
+ *  ordinary own-property/value semantics only when no context was supplied. */
+function isPresent(param, camelKey, input, context) {
+    if (context !== undefined)
+        return context.providedParams.has(camelKey);
+    return Object.prototype.hasOwnProperty.call(input, camelKey) && input[camelKey] !== undefined;
+}
+/** URL-encode a single path-placeholder value. `encodeURIComponent` never
+ *  escapes a literal `.`, so a value of exactly "." or ".." would otherwise
+ *  survive substitution as a dot-segment that `new URL()` normalizes away,
+ *  letting a caller-controlled value climb out of the intended path segment.
+ *  Encode dots only for that exact-match case; every other value is untouched. */
+function encodePathSegmentValue(value) {
+    const raw = String(value);
+    if (raw === '.' || raw === '..')
+        return raw.replace(/\./g, '%2E');
+    return encodeURIComponent(raw);
+}
+/** Convert an authored kebab param name to the camelCase key parseArgv emits.
+ *  Must stay identical to command.ts's flagNameToKey so lookups + the presence
+ *  set line up. */
+function paramKey(name) {
+    return name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+/** Map a unary 2xx body to the validated result object, or throw
+ *  cli_protocol_error (GENERAL) for bad JSON / a non-object / an output mismatch. */
+export function mapUnary2xx(spec, body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        throw protocolError(spec, 'response body was not valid JSON', 'a JSON object matching the declared output');
+    }
+    if (!isRecord(parsed)) {
+        throw protocolError(spec, `response body was not a JSON object (got ${typeName(parsed)})`, 'a JSON object matching the declared output');
+    }
+    const issue = validateDeclaredResult(spec.output, parsed);
+    if (issue !== null) {
+        const field = spec.output.find((f) => f.name === issue.field);
+        const expectedType = field?.type ?? 'unknown';
+        if (issue.receivedType !== undefined) {
+            throw protocolError(spec, `output field "${issue.field}" has the wrong type`, `${issue.field}: ${issue.expected ?? expectedType}`);
+        }
+        throw protocolError(spec, `response is missing required output field "${issue.field}"`, `a "${issue.field}" field of type ${expectedType}`);
+    }
+    return parsed;
+}
+// Error mapping (§6.5)
+/** Extract a non-2xx error. A conforming nested `{ error: { code, message,
+ *  field?, next? } }` with an acceptable snake_case, non-reserved code becomes a
+ *  CrtrError carrying that code; a reserved/ill-formed code demotes to
+ *  cli_protocol_error; a missing/malformed/nonconforming envelope becomes
+ *  cli_http_error. The HTTP status supplies the exit code in every case, and
+ *  rides its own `http_status` slot — never `received`, which names the CALLER's
+ *  offending value and would otherwise make the backend look like it was
+ *  complaining about the number 400. A backend that supplies its own `received`
+ *  keeps it. This is error-envelope extraction, not success-envelope
+ *  unwrapping. Always throws. */
+export function throwNon2xx(spec, status, body) {
+    const exit = deriveExit(status);
+    const err = parseHttpError(body);
+    if (err !== null) {
+        const accepted = SNAKE.test(err.code) && !RESERVED_CODES.has(err.code);
+        throw new CrtrError(accepted ? err.code : 'cli_protocol_error', err.message, exit, {
+            ...(err.received !== undefined ? { received: err.received } : {}),
+            ...(err.field !== undefined ? { field: err.field } : {}),
+            ...(err.manifestStale ? staleErrorDetails(spec.registration.name) : {}),
+            http_status: status,
+            next: err.next ?? 'Inspect the backend response, then retry if appropriate.',
+        });
+    }
+    throw new CrtrError('cli_http_error', `${label(spec)}: request failed with HTTP ${status}`, exit, {
+        http_status: status,
+        next: `Inspect the backend response, then retry if appropriate.`,
+    });
+}
+export function parseHttpError(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(parsed) || !isRecord(parsed['error']))
+        return null;
+    const err = parsed['error'];
+    if (typeof err['code'] !== 'string' || typeof err['message'] !== 'string')
+        return null;
+    return {
+        code: err['code'], message: err['message'],
+        ...(typeof err['field'] === 'string' ? { field: err['field'] } : {}),
+        ...(err['received'] !== undefined ? { received: err['received'] } : {}),
+        ...(typeof err['next'] === 'string' ? { next: err['next'] } : {}),
+        manifestStale: envelopeClaimsStale(err),
+        ...(err['question'] !== undefined ? { question: err['question'] } : {}),
+    };
+}
+/** HTTP status → exit code (§6.5), independent of the error `code`. */
+function deriveExit(status) {
+    if (status === 400 || status === 401 || status === 403 || status === 422)
+        return ExitCode.USAGE;
+    if (status === 404)
+        return ExitCode.NOT_FOUND;
+    if (status === 409)
+        return ExitCode.AMBIGUOUS;
+    return ExitCode.GENERAL; // all other 4xx/5xx and 3xx
+}
+function protocolError(spec, received, expected) {
+    return new CrtrError('cli_protocol_error', `${label(spec)}: ${received}. Expected ${expected}.`, ExitCode.GENERAL, {
+        received,
+        next: `Run \`crtr pkg plugin update ${spec.registration.name}\` or inspect the backend response.`,
+    });
+}
+function label(spec) {
+    return `HTTP-transport plugin "${spec.registration.name}" command \`${spec.commandPath.join(' ')}\``;
+}
+function typeName(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}

package/dist/core/command-plugins/transport/sign.d.ts

@@ -0,0 +1,55 @@
+/** Skew the verifier tolerates between the signature's `t` and its own clock. */
+export declare const SIGNATURE_MAX_SKEW_SECONDS = 300;
+/** How long a verifier must remember a `Crtr-Request-Id`. */
+export declare const SIGNATURE_NONCE_TTL_SECONDS = 600;
+/** A header value without its leading and trailing optional whitespace (spaces and tabs): the form every HTTP receiver
+ *  sees, since parsers drop it. Signing and sending both use this form, so the plugin hashes what crtr signed. */
+export declare function trimHeaderValue(value: string): string;
+export interface SignedHeaderDigest {
+    /** Lowercase names of every signed header, sorted. */
+    header_names: string[];
+    /** Lowercase hex sha256 of `<name>:<value>\n` for each name in `header_names`. */
+    headers_sha256: string;
+}
+export interface CrtrSignatureInput extends SignedHeaderDigest {
+    token: string;
+    method: string;
+    /** The request URL, or its path-with-query. */
+    url: URL | string;
+    /** Lowercase hex sha256 of the exact body bytes sent (of "" when none). */
+    body_sha256: string;
+    /** The `Crtr-Caller` value, or '' when none is sent. */
+    caller: string;
+    /** Epoch milliseconds. */
+    now: number;
+}
+export interface VerifyCrtrSignatureInput {
+    token: string;
+    /** The received `Crtr-Signature` header value. */
+    header: string;
+    method: string;
+    /** The received request target (`/path?query`) or absolute URL. */
+    url: URL | string;
+    /** The exact body bytes received; undefined or empty when none. */
+    body: Uint8Array | string | undefined;
+    /** The received `Crtr-Caller` value, or ''. */
+    caller: string;
+    /** Request headers as received (names in any case). */
+    headers: Record<string, string | string[] | undefined>;
+    /** Epoch milliseconds. */
+    now: number;
+    /** Reports whether the nonce was already seen, and records it. */
+    seen: (requestId: string) => boolean;
+}
+export declare function sha256Hex(data: Uint8Array | string | undefined): string;
+/** Names and digest of the headers a signature covers: every header except
+ *  `Crtr-Caller` and `Crtr-Signature`. Each value is hashed without its leading and trailing spaces and tabs, the form a
+ *  receiver gets after its HTTP parser trims them (the request plan sends the same trimmed value). */
+export declare function signedHeaderDigest(headers: Record<string, string>): SignedHeaderDigest;
+/** The `Crtr-Signature` header value. Refuses a header list that is not sorted
+ *  lowercase names including `crtr-request-id`, so a signature always covers the nonce. */
+export declare function crtrSignature(input: CrtrSignatureInput): string;
+/** Reference verifier for a plugin's service. True only when the version, clock
+ *  window, signed header list, MAC and nonce all hold. The nonce is recorded
+ *  only after the MAC verifies, so a forged request cannot poison the cache. */
+export declare function verifyCrtrSignature(input: VerifyCrtrSignatureInput): boolean;

package/dist/core/command-plugins/transport/sign.js

@@ -0,0 +1,115 @@
+// Request signing for local HTTP plugins: `Crtr-Signature`, an HMAC keyed by the
+// plugin's app token over the method, path, body, caller and every runtime-sent
+// header. The CLI computes header digests (`signedHeaderDigest`); crtrd, which
+// alone holds the token, builds the value (`crtrSignature`); the plugin's service
+// checks it (`verifyCrtrSignature`, the reference the plugin docs quote).
+// Pure: `node:crypto` only. `now` is epoch milliseconds (`Date.now()`) everywhere.
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+/** Skew the verifier tolerates between the signature's `t` and its own clock. */
+export const SIGNATURE_MAX_SKEW_SECONDS = 300;
+/** How long a verifier must remember a `Crtr-Request-Id`. */
+export const SIGNATURE_NONCE_TTL_SECONDS = 600;
+const UNSIGNED = new Set(['crtr-caller', 'crtr-signature']);
+const NONCE = 'crtr-request-id';
+/** A header value without its leading and trailing optional whitespace (spaces and tabs): the form every HTTP receiver
+ *  sees, since parsers drop it. Signing and sending both use this form, so the plugin hashes what crtr signed. */
+export function trimHeaderValue(value) {
+    return value.replace(/^[ \t]+|[ \t]+$/g, '');
+}
+export function sha256Hex(data) {
+    return createHash('sha256').update(data ?? '').digest('hex');
+}
+function headersDigest(names, valueOf) {
+    const hash = createHash('sha256');
+    for (const name of names)
+        hash.update(`${name}:${valueOf(name)}\n`);
+    return hash.digest('hex');
+}
+/** Names and digest of the headers a signature covers: every header except
+ *  `Crtr-Caller` and `Crtr-Signature`. Each value is hashed without its leading and trailing spaces and tabs, the form a
+ *  receiver gets after its HTTP parser trims them (the request plan sends the same trimmed value). */
+export function signedHeaderDigest(headers) {
+    const byName = new Map();
+    for (const [name, value] of Object.entries(headers)) {
+        const lower = name.toLowerCase();
+        if (!UNSIGNED.has(lower))
+            byName.set(lower, trimHeaderValue(value));
+    }
+    const header_names = [...byName.keys()].sort();
+    return { header_names, headers_sha256: headersDigest(header_names, (n) => byName.get(n)) };
+}
+function target(url) {
+    if (typeof url !== 'string')
+        return url.pathname + url.search;
+    if (url.startsWith('/'))
+        return url;
+    const parsed = new URL(url);
+    return parsed.pathname + parsed.search;
+}
+function canonical(parts) {
+    return ['v1', String(parts.t), parts.method.toUpperCase(), parts.target, parts.body_sha256, parts.caller, parts.h, parts.headers_sha256].join('\n');
+}
+function mac(token, canonicalString) {
+    return createHmac('sha256', token).update(canonicalString).digest();
+}
+/** The `Crtr-Signature` header value. Refuses a header list that is not sorted
+ *  lowercase names including `crtr-request-id`, so a signature always covers the nonce. */
+export function crtrSignature(input) {
+    const names = input.header_names;
+    if (!names.includes(NONCE))
+        throw new Error('signed headers must include crtr-request-id');
+    for (let i = 0; i < names.length; i++) {
+        const name = names[i];
+        if (name !== name.toLowerCase() || /[;,\s]/.test(name) || UNSIGNED.has(name) || (i > 0 && names[i - 1] >= name)) {
+            throw new Error('signed header names must be unique, sorted, lowercase, and exclude crtr-caller and crtr-signature');
+        }
+    }
+    const t = Math.floor(input.now / 1000);
+    const h = names.join(';');
+    const sig = mac(input.token, canonical({
+        t, method: input.method, target: target(input.url), body_sha256: input.body_sha256,
+        caller: input.caller, h, headers_sha256: input.headers_sha256,
+    })).toString('base64url');
+    return `v1,t=${t},h=${h},sig=${sig}`;
+}
+/** Reference verifier for a plugin's service. True only when the version, clock
+ *  window, signed header list, MAC and nonce all hold. The nonce is recorded
+ *  only after the MAC verifies, so a forged request cannot poison the cache. */
+export function verifyCrtrSignature(input) {
+    const fields = input.header.split(',');
+    if (fields.length !== 4 || fields[0] !== 'v1')
+        return false;
+    const [t, h, sig] = [fields[1], fields[2], fields[3]].map((f, i) => {
+        const prefix = ['t=', 'h=', 'sig='][i];
+        return f.startsWith(prefix) ? f.slice(prefix.length) : null;
+    });
+    if (t === null || h === null || sig === null || !/^\d{1,12}$/.test(t))
+        return false;
+    const seconds = Number(t);
+    if (Math.abs(input.now / 1000 - seconds) > SIGNATURE_MAX_SKEW_SECONDS)
+        return false;
+    const names = h.split(';');
+    if (!names.includes(NONCE))
+        return false;
+    const received = new Map();
+    for (const [name, value] of Object.entries(input.headers)) {
+        if (typeof value !== 'string')
+            continue; // absent, or sent twice: not signable
+        received.set(name.toLowerCase(), value);
+    }
+    for (let i = 0; i < names.length; i++) {
+        const name = names[i];
+        if (name === '' || UNSIGNED.has(name) || !received.has(name))
+            return false;
+        if (i > 0 && names[i - 1] >= name)
+            return false;
+    }
+    const expected = mac(input.token, canonical({
+        t: seconds, method: input.method, target: target(input.url), body_sha256: sha256Hex(input.body),
+        caller: input.caller, h: h, headers_sha256: headersDigest(names, (n) => received.get(n)),
+    }));
+    const given = Buffer.from(sig, 'base64url');
+    if (given.length !== expected.length || !timingSafeEqual(given, expected))
+        return false;
+    return !input.seen(received.get(NONCE));
+}