@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/client/credential-source.d.ts

@@ -0,0 +1,142 @@
+/**
+ * The client's port to credentials: who a request acts as, and what that sends.
+ *
+ * Every request names its actor. The client never infers one from headers, never logs in and never
+ * decides placement: it asks the source to resolve the actor against the operation's security, places
+ * what comes back on every attempt, and on a 401 refreshes it once and retries once. A run implements
+ * the source over its credential store (`createCredentialSource`).
+ */
+import type { Sends } from "../credentials/ports.ts";
+import type { Exchange } from "../runtime/exchange.ts";
+import type { PlacedSecrets } from "../security/redact.ts";
+/** Who a request acts as. */
+export type Actor = 
+/** A principal: the operation's resolved security decides the scheme or schemes. */
+{
+    principal: string;
+}
+/** A principal sending one named scheme: a scenario step's `scheme`, or a raw request. */
+ | {
+    principal: string;
+    scheme: string;
+}
+/**
+ * A principal following a URL a response gave it: a next link, a Location, a poll or receipt URL. It
+ * resolves against the operation the URL matches, else sends the schemes `via` recorded, and sends
+ * nothing to another origin.
+ */
+ | {
+    principal: string;
+    via: Exchange;
+}
+/** Nobody: nothing is sent. */
+ | {
+    anonymous: true;
+}
+/**
+ * A value placed exactly like the scheme's credential, though no principal holds it: implicitly a
+ * probe. A `derived` one is built from a held credential (a real JWT with its signature flipped,
+ * another principal's real value), so it is a secret and redacted like one; garbage stays visible.
+ */
+ | {
+    forged: {
+        scheme: string;
+        value: string;
+        derived?: true;
+    };
+}
+/**
+ * A principal sending exactly `value` as the scheme's credential, one it holds or held: the session a
+ * revoke ends. Placed and redacted like its own credential, and never renewed: a 401 is the answer.
+ */
+ | {
+    principal: string;
+    scheme: string;
+    value: string;
+};
+/** What the client knows about a request when it resolves its credential. */
+export interface CredentialRequest {
+    operationId?: string;
+    /** `<METHOD> <path>`, the path below the base, or origin and path for another origin: what a refusal names. */
+    route: string;
+    actor: Actor;
+    /** The request expects a refusal: it is never refreshed and never retried on a 401. */
+    probe?: boolean;
+}
+/** What a request sends, by scheme, in the order its alternative names them. */
+export type SendsByScheme = Readonly<Record<string, Sends>>;
+/** A principal's credentials for the alternative it satisfies, placed and ready to send. */
+export interface Sending {
+    kind: "sends";
+    principal: string;
+    schemes: string[];
+    sends: SendsByScheme;
+    /** The value each scheme carried, which a refresh names so a newer one is not renewed again. */
+    sentValues: Readonly<Record<string, string>>;
+    /** Every name and value placed, for the run's redactor. */
+    secrets: PlacedSecrets;
+    /** Renews what this resolution sent, single-flight across every request that sent it. */
+    refresh(): Promise<Resolution>;
+    /** Whether what it sent is no longer current in the store (renewed since, or stale); never awaits. */
+    lapsed(): boolean;
+    /** BLOCKS every scheme this resolution sent, for the rest of the run, with `reason`. */
+    block(reason: string): void;
+}
+/** A forged value, placed like the scheme's credential. Redacted only when derived from a real one. */
+export interface Forged {
+    kind: "forged";
+    schemes: [string];
+    sends: SendsByScheme;
+    /** What a derived value places, for the run's redactor: absent for garbage, which is no secret. */
+    secrets?: PlacedSecrets;
+}
+/** A value a principal holds, sent as given: a real exchange of that principal's, never renewed. */
+export interface HeldValue {
+    kind: "held";
+    principal: string;
+    schemes: [string];
+    sends: SendsByScheme;
+    secrets: PlacedSecrets;
+}
+export type Resolution = 
+/** The operation's security is `[]` or `{}`, or the actor is anonymous: send nothing. */
+{
+    kind: "anonymous";
+}
+/**
+ * No alternative the principal can satisfy, e.g. "no credential for jwt", or a principal's request that
+ * matches no documented operation and names no scheme.
+ */
+ | {
+    kind: "unsatisfied";
+    reason: string;
+}
+/** The principal is BLOCKED for a scheme it needs: its login or refresh failed. */
+ | {
+    kind: "blocked";
+    reason: string;
+} | Sending | HeldValue | Forged;
+export interface CredentialSource {
+    resolve(request: CredentialRequest): Promise<Resolution>;
+}
+/** A request whose security cannot be met, raised before anything is sent. Callers report it untested or BLOCKED. */
+export declare class UnsatisfiedSecurity extends Error {
+    readonly kind: "unsatisfied" | "blocked";
+    readonly reason: string;
+    name: string;
+    constructor(kind: "unsatisfied" | "blocked", reason: string);
+}
+/** A caller, hook or global value under a name the request's credential is placed in: it would override the scheme. */
+export declare class CredentialCollision extends Error {
+    readonly place: "header" | "query" | "cookie";
+    readonly placed: {
+        name: string;
+        scheme: string;
+    };
+    name: string;
+    constructor(place: "header" | "query" | "cookie", placed: {
+        name: string;
+        scheme: string;
+    });
+}
+//# sourceMappingURL=credential-source.d.ts.map

package/dist/api/client/credential-source.js

@@ -0,0 +1,31 @@
+/**
+ * The client's port to credentials: who a request acts as, and what that sends.
+ *
+ * Every request names its actor. The client never infers one from headers, never logs in and never
+ * decides placement: it asks the source to resolve the actor against the operation's security, places
+ * what comes back on every attempt, and on a 401 refreshes it once and retries once. A run implements
+ * the source over its credential store (`createCredentialSource`).
+ */
+/** A request whose security cannot be met, raised before anything is sent. Callers report it untested or BLOCKED. */
+export class UnsatisfiedSecurity extends Error {
+    kind;
+    reason;
+    name = "UnsatisfiedSecurity";
+    constructor(kind, reason) {
+        super(reason);
+        this.kind = kind;
+        this.reason = reason;
+    }
+}
+/** A caller, hook or global value under a name the request's credential is placed in: it would override the scheme. */
+export class CredentialCollision extends Error {
+    place;
+    placed;
+    name = "CredentialCollision";
+    constructor(place, placed) {
+        super(`${place} "${placed.name}" collides with the ${placed.scheme} credential placement`);
+        this.place = place;
+        this.placed = placed;
+    }
+}
+//# sourceMappingURL=credential-source.js.map

package/dist/api/client/credentials.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The credential source a run's clients use: an actor resolved against the operation's security,
+ * over the run's credential store.
+ *
+ * The first alternative the principal can satisfy, in document order, is sent; `satisfy` decides that
+ * offline from the principal's effective recipes, and the store acquires each scheme of it. A secondary
+ * origin's adapter reads its own document, and `mapping` (the config's `origins[].security`) names the
+ * primary scheme whose credential each origin scheme sends. That value is placed where the origin's
+ * scheme puts it, by the origin scheme's own template: the primary recipe's `format` and `placements`
+ * belong to the primary scheme's place. An origin scheme with no mapping has no credential.
+ */
+import type { PrincipalsConfig, SecurityConfig } from "../config/types/security.ts";
+import type { CredentialKey, Held } from "../credentials/store.ts";
+import type { OperationModel } from "../spec/graph/types.ts";
+import type { SecurityScheme } from "../spec/security/schemes.ts";
+import type { CredentialSource } from "./credential-source.ts";
+/** What the adapter asks of the run's credential store. */
+export interface CredentialStorePort {
+    acquire(key: CredentialKey): Promise<Held>;
+    refresh(request: CredentialKey & {
+        sentValue: string;
+    }): Promise<Held>;
+    block(key: CredentialKey, reason: string): void;
+    /** Whether `value`, placed for `key`, is no longer current; never awaits. */
+    lapsed(key: CredentialKey, value: string): boolean;
+}
+export interface CredentialSourceOptions {
+    store: CredentialStorePort;
+    /** The document this client's requests are operations of. */
+    model: {
+        byOperationId: ReadonlyMap<string, Pick<OperationModel, "security">>;
+        schemes: ReadonlyMap<string, SecurityScheme>;
+    };
+    security: SecurityConfig;
+    principals: PrincipalsConfig;
+    /** A secondary origin's `origins[].security`: origin scheme to the primary scheme whose credential it sends. */
+    mapping?: Readonly<Record<string, string>>;
+    /** The recipes no primary scheme declares: an origin's scheme is theirs, so their format and placements apply there. */
+    originOnly?: ReadonlySet<string>;
+}
+/** A credential source over the run's store, for one document. */
+export declare function createCredentialSource(options: CredentialSourceOptions): CredentialSource;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/api/client/credentials.js

@@ -0,0 +1,178 @@
+/**
+ * The credential source a run's clients use: an actor resolved against the operation's security,
+ * over the run's credential store.
+ *
+ * The first alternative the principal can satisfy, in document order, is sent; `satisfy` decides that
+ * offline from the principal's effective recipes, and the store acquires each scheme of it. A secondary
+ * origin's adapter reads its own document, and `mapping` (the config's `origins[].security`) names the
+ * primary scheme whose credential each origin scheme sends. That value is placed where the origin's
+ * scheme puts it, by the origin scheme's own template: the primary recipe's `format` and `placements`
+ * belong to the primary scheme's place. An origin scheme with no mapping has no credential.
+ */
+import { effectiveRecipe, own } from "../credentials/effective.js";
+import { probeOwner } from "../credentials/probe-principal.js";
+import { sendsFor } from "../credentials/placement.js";
+import { satisfy } from "../credentials/satisfy.js";
+import { messageOf } from "../errors/message.js";
+const ANONYMOUS = { kind: "anonymous" };
+/** A credential source over the run's store, for one document. */
+export function createCredentialSource(options) {
+    return { resolve: (request) => resolve(options, request) };
+}
+async function resolve(ctx, request) {
+    const { actor } = request;
+    if ("anonymous" in actor)
+        return ANONYMOUS;
+    if ("forged" in actor)
+        return forge(ctx, actor.forged);
+    if ("value" in actor)
+        return hold(ctx, actor);
+    const offered = alternativesFor(ctx, request, actor);
+    if ("unsatisfied" in offered)
+        return { kind: "unsatisfied", reason: offered.unsatisfied };
+    const recipesFor = (scheme) => recipeOf(ctx, actor.principal, scheme);
+    const chosen = satisfy(offered, recipesFor);
+    if ("unsatisfied" in chosen)
+        return { kind: "unsatisfied", reason: chosen.unsatisfied };
+    if (chosen.alternative.length === 0)
+        return ANONYMOUS;
+    return settle(ctx, { alternative: chosen.alternative, principal: actor.principal });
+}
+/*
+ * What the principal may send: the named scheme, else the operation's security, else for a URL a
+ * response gave it what that response's request sent. A principal's request that matches no operation
+ * and names no scheme is refused rather than sent bare, so a 401 is never graded as the backend's.
+ */
+function alternativesFor(ctx, request, actor) {
+    const { operationId } = request;
+    const operation = operationId === undefined ? undefined : ctx.model.byOperationId.get(operationId);
+    if ("scheme" in actor) {
+        const asked = operation?.security.alternatives.flat().find((requirement) => requirement.scheme === actor.scheme);
+        return { alternatives: [[{ scheme: actor.scheme, scopes: asked?.scopes ?? [] }]] };
+    }
+    if (operation !== undefined)
+        return { alternatives: operation.security.alternatives };
+    if ("via" in actor)
+        return { alternatives: [continued(ctx, actor.via)] };
+    return {
+        unsatisfied: `no documented operation matches ${request.route}: name its scheme with as: { principal, scheme }`,
+    };
+}
+/* The alternative the originating exchange sent, with the scopes its operation asked of it when that is known. */
+function continued(ctx, via) {
+    const schemes = via.schemes ?? [];
+    const origin = via.operationId === undefined ? undefined : ctx.model.byOperationId.get(via.operationId);
+    const sent = origin?.security.alternatives.find((alternative) => alternative.length === schemes.length &&
+        alternative.every((requirement, index) => requirement.scheme === schemes[index]));
+    return sent ?? schemes.map((scheme) => ({ scheme, scopes: [] }));
+}
+/* Acquires, or renews, every scheme of the alternative, and places what the store holds. */
+async function settle(ctx, settling) {
+    const { alternative, principal, renew } = settling;
+    const keys = alternative.map((requirement) => ({
+        principal,
+        scheme: primaryOf(ctx, requirement.scheme),
+        scopes: requirement.scopes,
+    }));
+    const held = await Promise.all(alternative.map((requirement, index) => {
+        const key = keys[index];
+        const sentValue = renew?.[requirement.scheme];
+        return sentValue === undefined ? ctx.store.acquire(key) : ctx.store.refresh({ ...key, sentValue });
+    }));
+    const sending = {
+        block: (reason) => {
+            for (const requirement of alternative) {
+                ctx.store.block({ principal, scheme: primaryOf(ctx, requirement.scheme) }, reason);
+            }
+        },
+        kind: "sends",
+        lapsed: () => keys.some((key, index) => ctx.store.lapsed(key, held[index].value)),
+        /* A dedicated credential is the owner's own account: the exchange names the owner, never the probe. */
+        principal: probeOwner(principal),
+        refresh: () => settle(ctx, { alternative, principal, renew: sending.sentValues }),
+        schemes: alternative.map((requirement) => requirement.scheme),
+        secrets: { cookies: [], headers: [], query: [], values: [] },
+        sends: {},
+        sentValues: {},
+    };
+    for (const [index, requirement] of alternative.entries()) {
+        const credential = held[index];
+        if ("blocked" in credential)
+            return { kind: "blocked", reason: credential.blocked };
+        const placed = placeHeld(ctx, requirement.scheme, credential);
+        if ("unsatisfied" in placed)
+            return { kind: "unsatisfied", reason: placed.unsatisfied };
+        add(sending, requirement.scheme, { ...placed, value: credential.value });
+    }
+    return sending;
+}
+function add(sending, scheme, placed) {
+    const { secrets } = sending;
+    sending.sends = { ...sending.sends, [scheme]: placed.sends };
+    sending.sentValues = { ...sending.sentValues, [scheme]: placed.value };
+    sending.secrets = {
+        cookies: [...secrets.cookies, ...placed.secrets.cookies],
+        headers: [...secrets.headers, ...placed.secrets.headers],
+        query: [...secrets.query, ...placed.secrets.query],
+        values: [...secrets.values, ...placed.secrets.values],
+    };
+}
+/*
+ * The store placed it by the primary scheme; an origin places the same value by its own, with the recipe's
+ * format and placements only when the recipe is for an origin's scheme rather than a primary one.
+ */
+function placeHeld(ctx, scheme, credential) {
+    if (ctx.mapping === undefined)
+        return credential;
+    const primary = primaryOf(ctx, scheme);
+    /* A held credential is one the principal had a recipe for. */
+    const recipe = ctx.originOnly?.has(primary) === true ? own(ctx.security, primary) : {};
+    const placed = place(ctx.model.schemes.get(scheme), { name: scheme, recipe, value: credential.value });
+    if ("unsatisfied" in placed)
+        return placed;
+    const values = [...new Set([...credential.secrets.values, ...placed.secrets.values])];
+    return { secrets: { ...placed.secrets, values }, sends: placed.sends };
+}
+function forge(ctx, forged) {
+    const { scheme } = forged;
+    const placed = placeValue(ctx, forged);
+    if ("unsatisfied" in placed)
+        return { kind: "unsatisfied", reason: placed.unsatisfied };
+    const forging = { kind: "forged", schemes: [scheme], sends: { [scheme]: placed.sends } };
+    return forged.derived === true ? { ...forging, secrets: placed.secrets } : forging;
+}
+/* A value the principal holds, sent as given and placed as the scheme places its credential. */
+function hold(ctx, held) {
+    const { principal, scheme } = held;
+    const placed = placeValue(ctx, held);
+    if ("unsatisfied" in placed)
+        return { kind: "unsatisfied", reason: placed.unsatisfied };
+    return { kind: "held", principal, schemes: [scheme], secrets: placed.secrets, sends: { [scheme]: placed.sends } };
+}
+/* A given value, placed by the scheme and its config format: a secondary origin's own scheme takes none. */
+function placeValue(ctx, given) {
+    const { scheme, value } = given;
+    const recipe = ctx.mapping === undefined ? (own(ctx.security, scheme) ?? {}) : {};
+    return place(ctx.model.schemes.get(scheme), { name: scheme, recipe, value });
+}
+function place(spec, what) {
+    if (spec === undefined)
+        return { unsatisfied: `the document declares no "${what.name}" scheme` };
+    try {
+        return sendsFor(spec, what.recipe, what.value);
+    }
+    catch (error) {
+        return { unsatisfied: messageOf(error) };
+    }
+}
+/* The primary scheme whose recipe and credential `scheme` uses: itself, unless this is an origin's adapter. */
+function primaryOf(ctx, scheme) {
+    return ctx.mapping === undefined ? scheme : own(ctx.mapping, scheme);
+}
+function recipeOf(ctx, principal, scheme) {
+    const primary = primaryOf(ctx, scheme);
+    if (primary === undefined)
+        return undefined;
+    return effectiveRecipe(own(ctx.security, primary), own(ctx.principals, principal)?.security?.[primary]);
+}
+//# sourceMappingURL=credentials.js.map

package/dist/api/client/curl.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Reproducible `curl` for an exchange — the artifact backend teams actually use.
+ *
+ * Quoting matters here: anything holding a shell variable must be double-quoted or the script
+ * silently runs against a literal `$BASE` with a literal `$TOKEN`. Everything else is
+ * single-quoted so JSON bodies and query strings survive untouched.
+ */
+import type { Redactor } from "../security/redact.ts";
+import { type Exchange } from "../runtime/exchange.ts";
+export interface CurlOptions {
+    /** The run's redactor: secret header names, and the values it was issued, never print. */
+    redactor: Redactor;
+    /** Header names whose values are replaced by a shell variable reference, in place of the redactor's names. */
+    redact?: readonly string[];
+    /** Origin to replace with `"$BASE"`, so a script can be pointed at another environment. */
+    origin?: string;
+}
+/**
+ * What follows `base` in `target`, when `target` lies under it: `/api` holds `/api/x` and `/api?q`,
+ * not `/apiv2/x`. `undefined` otherwise.
+ */
+export declare function belowBase(target: string, base: string): string | undefined;
+export declare function toCurl(exchange: Exchange, options: CurlOptions): string;
+//# sourceMappingURL=curl.d.ts.map

package/dist/api/client/curl.js

@@ -0,0 +1,100 @@
+/**
+ * Reproducible `curl` for an exchange — the artifact backend teams actually use.
+ *
+ * Quoting matters here: anything holding a shell variable must be double-quoted or the script
+ * silently runs against a literal `$BASE` with a literal `$TOKEN`. Everything else is
+ * single-quoted so JSON bodies and query strings survive untouched.
+ */
+import { isBodyRef, isFormData, isFormSnapshot, isRawBytes, isURLSearchParams, } from "../runtime/exchange.js";
+/**
+ * What follows `base` in `target`, when `target` lies under it: `/api` holds `/api/x` and `/api?q`,
+ * not `/apiv2/x`. `undefined` otherwise.
+ */
+export function belowBase(target, base) {
+    const prefix = base.replace(/\/$/, "");
+    if (!target.startsWith(prefix))
+        return undefined;
+    const rest = target.slice(prefix.length);
+    return rest === "" || /^[/?#]/.test(rest) ? rest : undefined;
+}
+export function toCurl(exchange, options) {
+    const { redactor } = options;
+    const target = redactor.url(exchange.url);
+    const below = options.origin === undefined ? undefined : belowBase(target, options.origin);
+    const url = below === undefined ? shellQuote(target) : `"$BASE${shellEscapeDouble(below)}"`;
+    const parts = [`curl -i -X ${exchange.method} ${url}`];
+    for (const [key, value] of Object.entries(exchange.requestHeaders))
+        parts.push(headerFlag(key, value, options));
+    if (exchange.requestBody !== undefined)
+        parts.push(...curlBodyFlags(redactBody(exchange.requestBody, redactor)));
+    return parts.join(" \\\n");
+}
+function headerFlag(key, value, { redact, redactor }) {
+    const secret = redact === undefined ? redactor.isSecretHeader(key) : redact.includes(key.toLowerCase());
+    if (!secret)
+        return `  -H ${shellQuote(`${key}: ${redactor.text(value)}`)}`;
+    /* Preserve the scheme prefix ("Bearer ", "ApiKey ") so the variable holds only the secret and
+     * the script stays copy-pasteable. */
+    const scheme = /^(\w+)\s+/.exec(value)?.[1];
+    const rendered = scheme === undefined ? "$TOKEN" : `${scheme} $TOKEN`;
+    return `  -H "${shellEscapeDouble(key)}: ${rendered}"`;
+}
+/** A request body with secrets removed, keeping the shape `curlBodyFlags` understands. */
+function redactBody(body, redactor) {
+    if (typeof body === "string")
+        return redactor.text(body);
+    if (isURLSearchParams(body)) {
+        const out = new URLSearchParams();
+        for (const [key, value] of body)
+            out.append(key, redactor.field(key, value));
+        return out;
+    }
+    if (isFormData(body)) {
+        const out = new FormData();
+        for (const [key, value] of body)
+            out.append(key, typeof value === "string" ? redactor.field(key, value) : value);
+        return out;
+    }
+    if (isFormSnapshot(body)) {
+        return {
+            parts: body.parts.map((part) => "value" in part ? { ...part, value: redactor.field(part.field, part.value) } : part),
+        };
+    }
+    if (isRawBytes(body) || isBodyRef(body))
+        return body;
+    return redactor.json(body);
+}
+function curlBodyFlags(body) {
+    if (isFormData(body))
+        return formDataFlags(body);
+    if (isFormSnapshot(body))
+        return formSnapshotFlags(body);
+    /* Field by field: curl encodes each value itself. Handing it the joined string encoded the
+     * separators too, so the server received one field holding the whole form. */
+    if (isURLSearchParams(body))
+        return [...body].map(([key, value]) => `  --data-urlencode ${shellQuote(`${key}=${value}`)}`);
+    if (typeof body === "string")
+        return [`  -d ${shellQuote(body)}`];
+    if (isRawBytes(body) || isBodyRef(body))
+        return [`  --data-binary @-`];
+    return [`  -d ${shellQuote(JSON.stringify(body))}`];
+}
+function formDataFlags(body) {
+    return [...body.entries()].map(([name, value]) => typeof value === "string"
+        ? `  -F ${shellQuote(`${name}=${value}`)}`
+        : `  -F ${shellQuote(`${name}=@${value.name};type=${value.type || "application/octet-stream"}`)}`);
+}
+function formSnapshotFlags(body) {
+    return body.parts.map((part) => "value" in part
+        ? `  -F ${shellQuote(`${part.field}=${part.value}`)}`
+        : `  -F ${shellQuote(`${part.field}=@${part.filename};type=${part.mediaType}`)}`);
+}
+/** One shell word, whatever it holds: single-quoted, with each `'` closed, escaped and reopened. */
+function shellQuote(text) {
+    return `'${text.replace(/'/g, `'\\''`)}'`;
+}
+/** Escapes the characters that stay special inside double quotes. */
+function shellEscapeDouble(text) {
+    return text.replace(/(["\\`])/g, "\\$1");
+}
+//# sourceMappingURL=curl.js.map

package/dist/api/client/declared.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The header and cookie values an operation's required parameters declare, as the bottom layer of
+ * an attempt's headers. Any other layer that sends the name wins, whatever its case. A name the
+ * credential is placed under is never sent as a parameter (ruling A4): the declared value is an
+ * example, the credential is the operation's security. Only what a layer itself sends there still
+ * collides with the credential, as before.
+ */
+import { type Placement } from "./placing.ts";
+import type { ResolvedOperation } from "./types.ts";
+type Layer = Readonly<Record<string, string>>;
+/**
+ * `layers` with the operation's declared header and cookie values under them. Declared cookies join
+ * the Cookie header the topmost layer sends, or start one.
+ */
+export declare function withDeclared(resolved: ResolvedOperation | null, placement: Placement, layers: readonly Layer[]): Layer[];
+export {};
+//# sourceMappingURL=declared.d.ts.map

package/dist/api/client/declared.js

@@ -0,0 +1,57 @@
+/**
+ * The header and cookie values an operation's required parameters declare, as the bottom layer of
+ * an attempt's headers. Any other layer that sends the name wins, whatever its case. A name the
+ * credential is placed under is never sent as a parameter (ruling A4): the declared value is an
+ * example, the credential is the operation's security. Only what a layer itself sends there still
+ * collides with the credential, as before.
+ */
+import { headerValue } from "../runtime/headers.js";
+import { serializeParam } from "./param-style.js";
+import { placedNames } from "./placing.js";
+function cookieNames(header) {
+    return (header ?? "").split(";").map((pair) => pair.replace(/=.*$/s, "").trim());
+}
+/* The declared header values no layer and no placement sends already. */
+function declaredHeaders(resolved, placement, layers) {
+    const styles = resolved.paramStyles?.header ?? {};
+    const taken = new Set([...layers.flatMap((layer) => Object.keys(layer)), ...placedNames(placement).headers].map((name) => name.toLowerCase()));
+    const out = {};
+    for (const [name, value] of Object.entries(resolved.requiredHeaders ?? {})) {
+        if (!taken.has(name.toLowerCase()))
+            out[name] = serializeParam({ ...styles[name], in: "header", name }, value);
+    }
+    return out;
+}
+/* The declared cookie pairs no layer and no placement sends already, as `name=value`. */
+function declaredCookies(resolved, placement, layers) {
+    const styles = resolved.paramStyles?.cookie ?? {};
+    const taken = new Set([
+        ...layers.flatMap((layer) => cookieNames(headerValue(layer, "cookie"))),
+        ...Object.values(placement.sends).flatMap((sends) => Object.keys(sends.cookies)),
+    ]);
+    return Object.entries(resolved.requiredCookies ?? {})
+        .filter(([name]) => !taken.has(name))
+        .flatMap(([name, value]) => serializeParam({ ...styles[name], in: "cookie", name }, value))
+        .map(([name, value]) => `${name}=${value}`);
+}
+/**
+ * `layers` with the operation's declared header and cookie values under them. Declared cookies join
+ * the Cookie header the topmost layer sends, or start one.
+ */
+export function withDeclared(resolved, placement, layers) {
+    if (resolved === null)
+        return [...layers];
+    const headers = { ...declaredHeaders(resolved, placement, layers) };
+    const cookies = declaredCookies(resolved, placement, layers);
+    const out = [...layers];
+    const top = out.findLastIndex((layer) => headerValue(layer, "cookie") !== undefined);
+    if (cookies.length > 0 && top === -1)
+        headers["cookie"] = cookies.join("; ");
+    if (cookies.length > 0 && top !== -1) {
+        const layer = out[top];
+        const name = Object.keys(layer).find((key) => key.toLowerCase() === "cookie");
+        out[top] = { ...layer, [name]: [layer[name], ...cookies].join("; ") };
+    }
+    return [headers, ...out];
+}
+//# sourceMappingURL=declared.js.map

package/dist/api/client/fence.d.ts

@@ -0,0 +1,17 @@
+/** The fence every hop of a request asks before it is sent. */
+import type { Purpose } from "../runtime/exchange.ts";
+import type { Fence } from "../runtime/fence.ts";
+import type { Placement } from "./placing.ts";
+/** Asks the fence about one hop; it throws when the hop is refused. */
+export type FenceAsk = (target: URL, method: string, body: unknown) => Promise<void>;
+export interface Fenced {
+    /** The hop's headers as they are when it is asked: redirects strip and add some. */
+    headers: Record<string, string>;
+    purpose: Purpose | undefined;
+    operationId: string | undefined;
+    /** The attempt's credential: whose, and under which schemes. */
+    placement: Placement;
+}
+/** Asks `fence` with what the request is sending at the time of the ask; no fence lets everything through. */
+export declare function fenceAsker(fence: Fence | undefined, fenced: Fenced): FenceAsk;
+//# sourceMappingURL=fence.d.ts.map

package/dist/api/client/fence.js

@@ -0,0 +1,24 @@
+/** The fence every hop of a request asks before it is sent. */
+/** Asks `fence` with what the request is sending at the time of the ask; no fence lets everything through. */
+export function fenceAsker(fence, fenced) {
+    return async (target, method, body) => {
+        await fence?.check({
+            body,
+            headers: { ...fenced.headers },
+            method,
+            phase: fenced.purpose ?? "request",
+            url: target.toString(),
+            ...(fenced.operationId === undefined ? {} : { operationId: fenced.operationId }),
+            ...whoSends(fenced.placement),
+        });
+    };
+}
+/* Who the credential is, by the names a fence can match without parsing a header; nothing when none is placed. */
+function whoSends({ forged, principal, schemes }) {
+    return {
+        ...(principal === undefined ? {} : { principal }),
+        ...(schemes.length === 0 ? {} : { schemes }),
+        ...(forged ? { forged: true } : {}),
+    };
+}
+//# sourceMappingURL=fence.js.map