@gate-forge/witness 0.0.0-stage → 0.8.0

package/dist/witness/env-attestation.d.ts

@@ -0,0 +1,98 @@
+import { type PinDnsLookup } from './loopback-pins.js';
+/** One failed attestation, carrying the actionable diagnostic. */
+export declare class AttestationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Whether a base URL is loopback. Accepts the standard loopback
+ * hostnames/IPs (localhost, 127.0.0.0/8, ::1).
+ *
+ * Args:
+ *   baseUrl: absolute http(s) URL.
+ *
+ * Returns:
+ *   boolean: true when the host is a recognized loopback host.
+ */
+export declare function isLoopbackUrl(baseUrl: string): boolean;
+/**
+ * Asserts the attestation subject is loopback (GF-10). Called at witness
+ * startup for the target and before EVERY adapter read for the read
+ * base. Hostnames that are not literally loopback are resolved through
+ * the OS resolver (hosts file + DNS): a name whose addresses are ALL
+ * loopback (127.0.0.0/8, ::1) is loopback by construction — the
+ * disposable-stack pattern of tenant subdomains mapped to 127.0.0.1.
+ * Mixed records, unresolvable names, and lookup failures all reject
+ * (fail closed). Approved addresses are PINNED per hostname for the
+ * process lifetime (see `loopback-pins.ts`): later DNS changes never
+ * move established connections — the check validates
+ * OPERATOR-provided bases (never suite input — suites cannot set
+ * target/adapter bases), and every egress binds to the startup
+ * approval.
+ *
+ * Args:
+ *   baseUrl: the base to verify.
+ *   what: human label for diagnostics ("attestation subject", "adapter 'x'").
+ *
+ * Throws:
+ *   AttestationError: when the base is not loopback — the run is BLOCKED
+ *   before any request is constructed (plan invariant 5).
+ */
+export declare function assertLoopback(baseUrl: string, what: string): Promise<void>;
+/** Signature of the DNS lookup injected for tests (defaults to the OS resolver). */
+export type DnsLookup = PinDnsLookup;
+/** Clears the pin store (tests only — production paths pin once and bind). */
+export declare function clearLoopbackCacheForTests(): void;
+/**
+ * Whether a base URL is loopback, resolving non-literal hostnames. The
+ * sync string check (`isLoopbackUrl`) runs first; only names it rejects
+ * reach the resolver, which pins all-loopback answers (see
+ * `loopback-pins.ts` — first resolution wins, later DNS changes never
+ * replace the pins).
+ *
+ * Args:
+ *   baseUrl: absolute http(s) URL.
+ *   lookupFn: DNS lookup (default: OS resolver via `node:dns/promises`).
+ *
+ * Returns:
+ *   Promise<boolean>: true when literally loopback or ALL resolved
+ *   addresses are loopback. False on mixed records, unresolvable names,
+ *   lookup failures, and non-http(s) URLs.
+ */
+export declare function isLoopbackUrlResolving(baseUrl: string, lookupFn?: DnsLookup): Promise<boolean>;
+/** The observed fingerprint + attestation scope of one target probe. */
+export interface EnvProbe {
+    /** Fingerprint marker value, or null when the target presents none. */
+    fingerprint: string | null;
+    /** Attestation-scope marker value, or null. */
+    scope: string | null;
+}
+/**
+ * Probes a target's env fingerprint: GET the base and read the marker
+ * header. Any transport failure probes as `{fingerprint: null, scope:
+ * null}` — absence is a mismatch, never a pass (fail closed).
+ *
+ * Args:
+ *   baseUrl: target base to probe.
+ *   timeoutMs: per-request timeout.
+ *
+ * Returns:
+ *   EnvProbe: observed markers (null when absent/unreachable).
+ */
+export declare function probeEnvFingerprint(baseUrl: string, timeoutMs: number): Promise<EnvProbe>;
+/**
+ * The same-environment rule for one adapter read (GF-13). The adapter
+ * base must present a marker EQUAL to the adapter's declared
+ * environmentFingerprint, and (when the run pins one) that fingerprint
+ * must equal the run's target fingerprint — the adapter may not read a
+ * different environment than the UI under test.
+ *
+ * Args:
+ *   probe: observed markers at the adapter base.
+ *   adapterFingerprint: the adapter's declared environmentFingerprint.
+ *   targetFingerprint: the run's pinned fingerprint, or null when unset.
+ *
+ * Returns:
+ *   string | null: mismatch description, or null when attested.
+ */
+export declare function envFingerprintMismatch(probe: EnvProbe, adapterFingerprint: string, targetFingerprint: string | null): string | null;
+//# sourceMappingURL=env-attestation.d.ts.map

package/dist/witness/env-attestation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-attestation.d.ts","sourceRoot":"","sources":["../../src/witness/env-attestation.ts"],"names":[],"mappings":"AAuBA,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAK5B,kEAAkE;AAClE,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAatD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQjF;AAED,oFAAoF;AACpF,MAAM,MAAM,SAAS,GAAG,YAAY,CAAC;AAErC,8EAA8E;AAC9E,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,SAAyB,GAClC,OAAO,CAAC,OAAO,CAAC,CAgBlB;AAED,wEAAwE;AACxE,MAAM,WAAW,QAAQ;IACvB,uEAAuE;IACvE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,+CAA+C;IAC/C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,QAAQ,CAAC,CAsBnB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,QAAQ,EACf,kBAAkB,EAAE,MAAM,EAC1B,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAC/B,MAAM,GAAG,IAAI,CAef"}

package/dist/witness/env-attestation.js

@@ -0,0 +1,202 @@
+/**
+ * Minimal v1 environment attestation (GF-10, GF-13; ADR 0002, plan
+ * invariant 5, docs/research/environment_attestation.md L0/L1 spirit).
+ *
+ * Two positive checks, both fail-closed:
+ *
+ * 1. Loopback-only targets (GF-10): the attestation subject (the SUT the
+ *    UI drives) and every adapter read base MUST be a loopback address.
+ *    A non-loopback target blocks the run BEFORE any adapter read is
+ *    constructed — the witness never builds a request against an
+ *    unattested base.
+ * 2. Env-fingerprint marker (GF-13, minimal v1 attestation): every
+ *    adapter base must answer GET `/` with an
+ *    `x-gateforge-env-fingerprint` header equal to the adapter's
+ *    declared `environmentFingerprint`; when the run also pins
+ *    `targetFingerprint`, the adapter must read the SAME environment
+ *    the UI drives (adapter fingerprint === run fingerprint). Absent or
+ *    mismatched markers reject the record — never `satisfied`.
+ *
+ * L2 signed statements are deferred per ADR 0002 ("L2 signing deferred").
+ */
+import { lookup } from 'node:dns/promises';
+import { ATTESTATION_SCOPE_HEADER, ENV_FINGERPRINT_HEADER, LOOPBACK_HOSTS } from '../constants.js';
+import { clearPinnedLoopbackForTests, pinLoopbackIps, pinnedGet, } from './loopback-pins.js';
+/** Default DNS lookup: the OS resolver, all records. */
+const defaultLookup = (host) => lookup(host, { all: true, verbatim: true });
+/** One failed attestation, carrying the actionable diagnostic. */
+export class AttestationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AttestationError';
+    }
+}
+/**
+ * Whether a base URL is loopback. Accepts the standard loopback
+ * hostnames/IPs (localhost, 127.0.0.0/8, ::1).
+ *
+ * Args:
+ *   baseUrl: absolute http(s) URL.
+ *
+ * Returns:
+ *   boolean: true when the host is a recognized loopback host.
+ */
+export function isLoopbackUrl(baseUrl) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+        return false;
+    const host = parsed.hostname;
+    if (LOOPBACK_HOSTS[host])
+        return true;
+    if (/^127(\.\d{1,3}){3}$/.test(host))
+        return true;
+    if (host === '0.0.0.0')
+        return true;
+    return false;
+}
+/**
+ * Asserts the attestation subject is loopback (GF-10). Called at witness
+ * startup for the target and before EVERY adapter read for the read
+ * base. Hostnames that are not literally loopback are resolved through
+ * the OS resolver (hosts file + DNS): a name whose addresses are ALL
+ * loopback (127.0.0.0/8, ::1) is loopback by construction — the
+ * disposable-stack pattern of tenant subdomains mapped to 127.0.0.1.
+ * Mixed records, unresolvable names, and lookup failures all reject
+ * (fail closed). Approved addresses are PINNED per hostname for the
+ * process lifetime (see `loopback-pins.ts`): later DNS changes never
+ * move established connections — the check validates
+ * OPERATOR-provided bases (never suite input — suites cannot set
+ * target/adapter bases), and every egress binds to the startup
+ * approval.
+ *
+ * Args:
+ *   baseUrl: the base to verify.
+ *   what: human label for diagnostics ("attestation subject", "adapter 'x'").
+ *
+ * Throws:
+ *   AttestationError: when the base is not loopback — the run is BLOCKED
+ *   before any request is constructed (plan invariant 5).
+ */
+export async function assertLoopback(baseUrl, what) {
+    if (!(await isLoopbackUrlResolving(baseUrl))) {
+        throw new AttestationError(`${what} base '${baseUrl}' is not loopback; gateforge only attests disposable ` +
+            'loopback environments (plan invariant 5, GF-10). A bare URL with no provider ' +
+            'contract is not a mutation target.');
+    }
+}
+/** Clears the pin store (tests only — production paths pin once and bind). */
+export function clearLoopbackCacheForTests() {
+    clearPinnedLoopbackForTests();
+}
+/**
+ * Whether a base URL is loopback, resolving non-literal hostnames. The
+ * sync string check (`isLoopbackUrl`) runs first; only names it rejects
+ * reach the resolver, which pins all-loopback answers (see
+ * `loopback-pins.ts` — first resolution wins, later DNS changes never
+ * replace the pins).
+ *
+ * Args:
+ *   baseUrl: absolute http(s) URL.
+ *   lookupFn: DNS lookup (default: OS resolver via `node:dns/promises`).
+ *
+ * Returns:
+ *   Promise<boolean>: true when literally loopback or ALL resolved
+ *   addresses are loopback. False on mixed records, unresolvable names,
+ *   lookup failures, and non-http(s) URLs.
+ */
+export async function isLoopbackUrlResolving(baseUrl, lookupFn = defaultLookup) {
+    if (isLoopbackUrl(baseUrl))
+        return true;
+    let host;
+    try {
+        const parsed = new URL(baseUrl);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+            return false;
+        host = parsed.hostname;
+    }
+    catch {
+        return false;
+    }
+    try {
+        await pinLoopbackIps(host, lookupFn);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Probes a target's env fingerprint: GET the base and read the marker
+ * header. Any transport failure probes as `{fingerprint: null, scope:
+ * null}` — absence is a mismatch, never a pass (fail closed).
+ *
+ * Args:
+ *   baseUrl: target base to probe.
+ *   timeoutMs: per-request timeout.
+ *
+ * Returns:
+ *   EnvProbe: observed markers (null when absent/unreachable).
+ */
+export async function probeEnvFingerprint(baseUrl, timeoutMs) {
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            // Pinned egress: attested hostnames connect to their
+            // startup-approved loopback IPs (Host preserved); unpinned names
+            // behave exactly as before.
+            const response = await pinnedGet(baseUrl, {
+                timeoutMs,
+                signal: controller.signal,
+            });
+            return {
+                fingerprint: response.headers.get(ENV_FINGERPRINT_HEADER),
+                scope: response.headers.get(ATTESTATION_SCOPE_HEADER),
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    catch {
+        return { fingerprint: null, scope: null };
+    }
+}
+/**
+ * The same-environment rule for one adapter read (GF-13). The adapter
+ * base must present a marker EQUAL to the adapter's declared
+ * environmentFingerprint, and (when the run pins one) that fingerprint
+ * must equal the run's target fingerprint — the adapter may not read a
+ * different environment than the UI under test.
+ *
+ * Args:
+ *   probe: observed markers at the adapter base.
+ *   adapterFingerprint: the adapter's declared environmentFingerprint.
+ *   targetFingerprint: the run's pinned fingerprint, or null when unset.
+ *
+ * Returns:
+ *   string | null: mismatch description, or null when attested.
+ */
+export function envFingerprintMismatch(probe, adapterFingerprint, targetFingerprint) {
+    if (probe.fingerprint === null) {
+        return `adapter target presents no '${ENV_FINGERPRINT_HEADER}' marker; ` +
+            'the environment is not attested (GF-13)';
+    }
+    if (probe.fingerprint !== adapterFingerprint) {
+        return `adapter target fingerprint '${probe.fingerprint}' does not match the adapter's ` +
+            `declared environmentFingerprint '${adapterFingerprint}' (GF-13)`;
+    }
+    if (targetFingerprint !== null && probe.fingerprint !== targetFingerprint) {
+        return `adapter target fingerprint '${probe.fingerprint}' differs from the run's attested ` +
+            `target fingerprint '${targetFingerprint}': the adapter would read a different ` +
+            'environment than the UI under test (GF-13)';
+    }
+    return null;
+}
+//# sourceMappingURL=env-attestation.js.map

package/dist/witness/env-attestation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-attestation.js","sourceRoot":"","sources":["../../src/witness/env-attestation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACnG,OAAO,EACL,2BAA2B,EAC3B,cAAc,EACd,SAAS,GAEV,MAAM,oBAAoB,CAAC;AAE5B,wDAAwD;AACxD,MAAM,aAAa,GAAiB,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;AAE1F,kEAAkE;AAClE,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9E,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC;IAC7B,IAAI,cAAc,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,IAAI,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAClD,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAe,EAAE,IAAY;IAChE,IAAI,CAAC,CAAC,MAAM,sBAAsB,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,gBAAgB,CACxB,GAAG,IAAI,UAAU,OAAO,uDAAuD;YAC7E,+EAA+E;YAC/E,oCAAoC,CACvC,CAAC;IACJ,CAAC;AACH,CAAC;AAKD,8EAA8E;AAC9E,MAAM,UAAU,0BAA0B;IACxC,2BAA2B,EAAE,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,OAAe,EACf,WAAsB,aAAa;IAEnC,IAAI,aAAa,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;QAChC,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC9E,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC;QACH,MAAM,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACrC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAUD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAe,EACf,SAAiB;IAEjB,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;QAC9D,IAAI,CAAC;YACH,qDAAqD;YACrD,iEAAiE;YACjE,4BAA4B;YAC5B,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,OAAO,EAAE;gBACxC,SAAS;gBACT,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YACH,OAAO;gBACL,WAAW,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC;gBACzD,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC;aACtD,CAAC;QACJ,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAC5C,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAAe,EACf,kBAA0B,EAC1B,iBAAgC;IAEhC,IAAI,KAAK,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;QAC/B,OAAO,+BAA+B,sBAAsB,YAAY;YACtE,yCAAyC,CAAC;IAC9C,CAAC;IACD,IAAI,KAAK,CAAC,WAAW,KAAK,kBAAkB,EAAE,CAAC;QAC7C,OAAO,+BAA+B,KAAK,CAAC,WAAW,iCAAiC;YACtF,oCAAoC,kBAAkB,WAAW,CAAC;IACtE,CAAC;IACD,IAAI,iBAAiB,KAAK,IAAI,IAAI,KAAK,CAAC,WAAW,KAAK,iBAAiB,EAAE,CAAC;QAC1E,OAAO,+BAA+B,KAAK,CAAC,WAAW,oCAAoC;YACzF,uBAAuB,iBAAiB,wCAAwC;YAChF,4CAA4C,CAAC;IACjD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/witness/fixture-provider.d.ts

@@ -0,0 +1,89 @@
+/** One leased actor: identity/tenant/roles plus a private credential handle. */
+export interface ActorLease {
+    /** Stable principal id within the fixture recipe. */
+    principalId: string;
+    /** Owning tenant, or null for tenant-less principals. */
+    tenantId: string | null;
+    /** Role names the actor holds for this lease. */
+    roles: string[];
+    /**
+     * Private engine-side credential reference (opaque handle). NEVER token
+     * bytes, NEVER suite-visible.
+     */
+    credentialRef: string;
+}
+/** One isolated fixture lease for a single required case. */
+export interface FixtureLease {
+    /** Witness-issued lease id (UUID). */
+    leaseId: string;
+    /** Unique isolated namespace for this case execution. */
+    namespace: string;
+    /** Authoritative generated subject identities, keyed by recipe name. */
+    subjects: Record<string, unknown>;
+    /** Leased actors, keyed by recipe profile name. */
+    actors: Record<string, ActorLease>;
+}
+/** Input to {@link FixtureProvider.prepare}. */
+export interface FixturePrepareInput {
+    /** Approved fixture recipe key (never a suite-supplied callback). */
+    recipe: string;
+    /** Run id the lease belongs to. */
+    runId: string;
+    /** Required case id the lease belongs to. */
+    caseId: string;
+}
+/** Engine-side credential material (never suite-visible, never logged). */
+export interface CredentialMaterial {
+    /** Headers the engine driver attaches to the principal request. */
+    headers: Record<string, string>;
+}
+/** Trusted fixture/actor provider interface. */
+export interface FixtureProvider {
+    /** Mints a fresh isolated lease for one required case. */
+    prepare(input: FixturePrepareInput): Promise<FixtureLease> | FixtureLease;
+    /** Releases a lease namespace (idempotent; errors never flip verdicts). */
+    release(leaseId: string): Promise<void> | void;
+    /**
+     * Resolves a lease credentialRef to request material, engine-side
+     * only. Returns null for unknown/expired references. The bytes never
+     * leave the controller/engine boundary.
+     */
+    resolveCredential?(credentialRef: string): Promise<CredentialMaterial | null> | CredentialMaterial | null;
+}
+/**
+ * Loads the approved fixture provider from the engine-owned bundle
+ * (a `fixture-provider.mjs` default export implementing the
+ * interface). `bundleDir` may be the bundle DIRECTORY or the provider
+ * MODULE itself, so the operator variable can name either. Returns null
+ * when no provider exists — strong cases then block with a
+ * missing-provider cause instead of falling back to suite-supplied
+ * fixtures.
+ *
+ * Args:
+ *   bundleDir: absolute engine-owned bundle directory or provider
+ *     module path, or null.
+ *
+ * Returns:
+ *   Promise<FixtureProvider | null>: the approved provider or null.
+ *
+ * Throws:
+ *   Error: when the module exists but does not implement the interface
+ *   (fail closed — a half-shaped provider is never used).
+ */
+export declare function loadFixtureProvider(bundleDir: string | null): Promise<FixtureProvider | null>;
+/** In-memory provider for witness tests (engine-side only, never a worker API). */
+export declare function createMemoryFixtureProvider(options?: {
+    /** Actor profiles available to recipes: profile name → lease template. */
+    actors?: Record<string, {
+        principalId: string;
+        tenantId: string | null;
+        roles: string[];
+    }>;
+    /** Engine-side credential headers per actor profile (test secrets, never suite-visible). */
+    credentials?: Record<string, Record<string, string>>;
+    /** Fixture subjects per recipe: recipe name → subject key → value. */
+    subjects?: Record<string, Record<string, unknown>>;
+}): FixtureProvider & {
+    leases(): FixtureLease[];
+};
+//# sourceMappingURL=fixture-provider.d.ts.map

package/dist/witness/fixture-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixture-provider.d.ts","sourceRoot":"","sources":["../../src/witness/fixture-provider.ts"],"names":[],"mappings":"AAqBA,gFAAgF;AAChF,MAAM,WAAW,UAAU;IACzB,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,iDAAiD;IACjD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACpC;AAED,gDAAgD;AAChD,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,OAAO,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC;IAC1E,2EAA2E;IAC3E,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC/C;;;;OAIG;IACH,iBAAiB,CAAC,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,GAAG,kBAAkB,GAAG,IAAI,CAAC;CAC3G;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAqBnG;AAED,mFAAmF;AACnF,wBAAgB,2BAA2B,CAAC,OAAO,GAAE;IACnD,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAC3F,4FAA4F;IAC5F,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACrD,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC/C,GAAG,eAAe,GAAG;IAAE,MAAM,IAAI,YAAY,EAAE,CAAA;CAAE,CAmDtD"}

package/dist/witness/fixture-provider.js

@@ -0,0 +1,116 @@
+/**
+ * Trusted fixture/actor provider (plan 2026-09-19 §4.5): the ONLY source
+ * of fixture namespaces, authoritative subject identities, and actor
+ * credentials for strong behavior cases. Loaded ONLY from the approved
+ * engine-owned bundle — never from suite-supplied callbacks, never from
+ * `AdapterContext.get` or `probeServer`.
+ *
+ * - `prepare` mints a fresh isolated lease per case (unique namespace);
+ *   sequence steps share only their own case lease.
+ * - Actor material resolves privately inside the controller/engine
+ *   request driver. Cookie/header bytes never appear in suite-visible
+ *   results, signed public reports, argv, or logs — the lease carries a
+ *   `credentialRef` (an engine-side handle), never token bytes.
+ * - `release` cleans the lease namespace; cleanup runs on errors without
+ *   flipping the case verdict to success.
+ */
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/**
+ * Loads the approved fixture provider from the engine-owned bundle
+ * (a `fixture-provider.mjs` default export implementing the
+ * interface). `bundleDir` may be the bundle DIRECTORY or the provider
+ * MODULE itself, so the operator variable can name either. Returns null
+ * when no provider exists — strong cases then block with a
+ * missing-provider cause instead of falling back to suite-supplied
+ * fixtures.
+ *
+ * Args:
+ *   bundleDir: absolute engine-owned bundle directory or provider
+ *     module path, or null.
+ *
+ * Returns:
+ *   Promise<FixtureProvider | null>: the approved provider or null.
+ *
+ * Throws:
+ *   Error: when the module exists but does not implement the interface
+ *   (fail closed — a half-shaped provider is never used).
+ */
+export async function loadFixtureProvider(bundleDir) {
+    if (bundleDir === null)
+        return null;
+    // Runtime-selected module specifier: the provider path is operator
+    // input resolved at startup, never known at author time.
+    const entry = bundleDir.endsWith('.mjs') || bundleDir.endsWith('.js')
+        ? bundleDir
+        : join(bundleDir, 'fixture-provider.mjs');
+    if (!existsSync(entry))
+        return null;
+    const module = (await import(pathToFileURL(entry).href));
+    const provider = module.default;
+    if (provider === undefined ||
+        typeof provider.prepare !== 'function' ||
+        typeof provider.release !== 'function') {
+        throw new Error('approved fixture provider is malformed: default export must implement {prepare, release} (fail closed)');
+    }
+    return provider;
+}
+/** In-memory provider for witness tests (engine-side only, never a worker API). */
+export function createMemoryFixtureProvider(options = {}) {
+    const live = new Map();
+    let counter = 0;
+    const actors = options.actors ?? {};
+    const credentials = options.credentials ?? {};
+    const subjects = options.subjects ?? {};
+    const credentialFor = (credentialRef) => {
+        const match = /^credref:([^:]+):(.+)$/.exec(credentialRef);
+        if (match === null)
+            return null;
+        const profile = match[2];
+        if (!live.has(match[1]))
+            return null;
+        const headers = credentials[profile];
+        if (headers === undefined)
+            return null;
+        return { headers: { ...headers } };
+    };
+    return {
+        prepare(input) {
+            counter += 1;
+            const leaseId = randomUUID();
+            const namespace = `fixture-${input.runId}-${input.caseId}-${String(counter)}`
+                .toLowerCase()
+                .replace(/[^a-z0-9-]/g, '-');
+            const leasedActors = {};
+            for (const [name, template] of Object.entries(actors)) {
+                leasedActors[name] = {
+                    principalId: template.principalId,
+                    tenantId: template.tenantId,
+                    roles: [...template.roles],
+                    credentialRef: `credref:${leaseId}:${name}`,
+                };
+            }
+            const recipeSubjects = subjects[input.recipe];
+            const lease = {
+                leaseId,
+                namespace,
+                subjects: recipeSubjects === undefined ? {} : JSON.parse(JSON.stringify(recipeSubjects)),
+                actors: leasedActors,
+            };
+            live.set(leaseId, lease);
+            return lease;
+        },
+        release(leaseId) {
+            live.delete(leaseId);
+        },
+        resolveCredential(credentialRef) {
+            return credentialFor(credentialRef);
+        },
+        leases() {
+            return [...live.values()];
+        },
+    };
+}
+//# sourceMappingURL=fixture-provider.js.map

package/dist/witness/fixture-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixture-provider.js","sourceRoot":"","sources":["../../src/witness/fixture-provider.ts"],"names":[],"mappings":"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"}

package/dist/witness/loopback-pins.d.ts

@@ -0,0 +1,79 @@
+/** DNS lookup signature (injectable for tests; default: OS resolver). */
+export type PinDnsLookup = (host: string) => Promise<ReadonlyArray<{
+    address: string;
+    family: number;
+}>>;
+/** Whether one address is loopback (127.0.0.0/8 or ::1). */
+export declare function isLoopbackAddress(address: string): boolean;
+/** Clears all pins (tests only — production paths pin once and bind). */
+export declare function clearPinnedLoopbackForTests(): void;
+/**
+ * Resolves a hostname and pins ALL-loopback addresses, or rejects.
+ * The first successful pinning wins for the process lifetime: later
+ * resolutions (including hostile mid-run DNS changes) never replace
+ * it — connections bind to the startup-approved set.
+ *
+ * Args:
+ *   hostname: the operator-provided hostname to attest.
+ *   lookupFn: DNS lookup (default: OS resolver, all records).
+ *
+ * Returns:
+ *   The pinned loopback IP list (IPv4 first, then IPv6, stable order).
+ *
+ * Throws:
+ *   Error: on empty/mixed/public/unresolvable answers.
+ */
+export declare function pinLoopbackIps(hostname: string, lookupFn?: PinDnsLookup): Promise<string[]>;
+/**
+ * Snapshot copy of current pins (hostname → approved IPs).
+ *
+ * Returns:
+ *   A detached copy for launch-arg construction.
+ */
+export declare function pinnedLoopbackIps(): Map<string, string[]>;
+/**
+ * Builds the Chromium `--host-resolver-rules` value binding every
+ * pinned hostname to its approved IPs (`MAP host ip`, comma-separated,
+ * deterministic order). IP literals are emitted bare (brackets are URL
+ * syntax and would break rule parsing).
+ *
+ * Args:
+ *   pins: hostname → approved IPs (default: live snapshot).
+ *
+ * Returns:
+ *   The rules string, or null when nothing is pinned (no flag then).
+ */
+export declare function hostResolverRules(pins?: ReadonlyMap<string, readonly string[]>): string | null;
+/** Pinned GET result (fetch-compatible subset used by adapter/probe reads). */
+export interface PinnedGetResult {
+    status: number;
+    headers: Headers;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}
+/**
+ * GET through the startup pins: when the URL's hostname is pinned, the
+ * TCP connection goes to the pinned IP while the original Host header
+ * (host + non-default port) and path are preserved — tenant routing
+ * intact, destination bound. Unpinned hostnames use plain global fetch
+ * (previous behavior, unchanged).
+ *
+ * Args:
+ *   url: absolute http(s) URL.
+ *   options: timeout, headers, abort signal, redirect budget.
+ *
+ * Returns:
+ *   Status + headers + body readers.
+ *
+ * Throws:
+ *   Error: on transport failure, redirect overflow, or (https) the
+ *   pinned IP failing certificate verification — fail closed, never
+ *   plaintext fallback.
+ */
+export declare function pinnedGet(url: string, options: {
+    timeoutMs: number;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    maxRedirects?: number;
+}): Promise<PinnedGetResult>;
+//# sourceMappingURL=loopback-pins.d.ts.map

package/dist/witness/loopback-pins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback-pins.d.ts","sourceRoot":"","sources":["../../src/witness/loopback-pins.ts"],"names":[],"mappings":"AA4BA,yEAAyE;AACzE,MAAM,MAAM,YAAY,GAAG,CACzB,IAAI,EAAE,MAAM,KACT,OAAO,CAAC,aAAa,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAAC;AAEjE,4DAA4D;AAC5D,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE1D;AAKD,yEAAyE;AACzE,wBAAgB,2BAA2B,IAAI,IAAI,CAElD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,YAAoE,GAC7E,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBnB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAEzD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAuB,GAAG,MAAM,GAAG,IAAI,CAQnH;AAED,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IACP,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GACA,OAAO,CAAC,eAAe,CAAC,CAgC1B"}