@gate-forge/witness 0.0.0-stage → 0.8.0

package/dist/witness/behavior-request.js

@@ -0,0 +1,335 @@
+/**
+ * Witness-owned engine-http request driver (plan 2026-09-19 §4.6, Phase 5):
+ * executes one approved `request` action against the approved subject
+ * origin with approved actor material. The worker never touches the
+ * request — method, path, query, body, and credentials all resolve
+ * engine-side from the supervisor-bound case and the trusted lease.
+ *
+ * Bounds (fail closed, never a hashed prefix):
+ * - request/response bodies are capped (over-limit blocks);
+ * - the origin must be loopback (plan invariant 5, GF-10);
+ * - the `multipart` encoding still needs the Phase 6 file driver and
+ *   blocks here; `raw` bodies are supported ONLY with an engine-side
+ *   signature profile (plan 2026-09-25 Phase 1), because raw bytes are
+ *   exactly what a signature covers;
+ * - resolved path values cannot smuggle segments (`/` rejected).
+ */
+import { createHmac, randomUUID } from 'node:crypto';
+import { BEHAVIOR_SIGNING_SECRET_HEADER, parseBehaviorSignatureProfile, sha256Canonical, } from '@gate-forge/core';
+import { assertLoopback } from './env-attestation.js';
+/** Proof-input bound (request and response bodies alike). */
+export const BEHAVIOR_BODY_LIMIT_BYTES = 256 * 1024;
+/** Typed driver failure (always a blocking diagnostic, never proof). */
+export class BehaviorDriverError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BehaviorDriverError';
+    }
+}
+/** Unsafe fixture-key segments (no prototype-chain traversal). */
+const FORBIDDEN_SEGMENTS = new Set(['__proto__', 'prototype', 'constructor']);
+/** Resolves one InputValue against sealed lease subjects. */
+function resolveValue(raw, subjects, what) {
+    if (raw.from === 'literal')
+        return raw.value ?? null;
+    if (raw.from === 'fixture') {
+        if (typeof raw.key !== 'string')
+            throw new BehaviorDriverError(`${what} fixture reference has no key`);
+        const segments = raw.key.split('.');
+        if (segments.some((segment) => segment.length === 0 || FORBIDDEN_SEGMENTS.has(segment))) {
+            throw new BehaviorDriverError(`${what} fixture key is forbidden`);
+        }
+        let current = subjects;
+        for (const segment of segments) {
+            if (typeof current !== 'object' || current === null || Array.isArray(current)) {
+                throw new BehaviorDriverError(`${what} fixture key '${raw.key}' does not resolve`);
+            }
+            if (!Object.prototype.hasOwnProperty.call(current, segment)) {
+                throw new BehaviorDriverError(`${what} fixture key '${raw.key}' does not resolve`);
+            }
+            current = current[segment];
+        }
+        return current ?? null;
+    }
+    throw new BehaviorDriverError(`${what} uses an unsupported value source '${raw.from}'`);
+}
+/** Reads a bounded body from a fetch response (over-limit aborts). */
+async function readBoundedBody(response, limit) {
+    const reader = response.body?.getReader();
+    if (reader === undefined || reader === null) {
+        const text = await response.text();
+        if (text.length > limit)
+            throw new BehaviorDriverError('response body exceeds the proof bound');
+        return text;
+    }
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > limit) {
+            try {
+                await response.body?.cancel();
+            }
+            catch {
+                // Best-effort cancel; the bound violation below is the verdict.
+            }
+            throw new BehaviorDriverError('response body exceeds the proof bound');
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+/** Parses a body as JSON, falling back to raw text. */
+function parseBody(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return '';
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * Stamps one engine-side signature (plan 2026-09-25 Phase 1).
+ *
+ * The secret is read from the trusted lease and never leaves this
+ * function: the request carries the digest, not the key. The digest
+ * covers the EXACT bytes that go on the wire.
+ *
+ * Args:
+ *   profile: the validated signature profile.
+ *   secret: engine-side signing secret from the actor material.
+ *   bodyText: the exact request body the driver sends.
+ *   headers: request headers to stamp into (mutated in place).
+ *   declaredTimestampMs: a lease-declared stamp (a stale-delivery case),
+ *   or null to stamp the engine clock.
+ *
+ * Returns:
+ *   string: the body text to send (always the declared body).
+ *
+ * Throws:
+ *   BehaviorDriverError: the engine's own stamp is outside the declared
+ *   tolerance — always a blocking diagnostic, never proof.
+ */
+function stampSignature(profile, secret, bodyText, headers, declaredTimestampMs) {
+    const now = Date.now();
+    // The signature covers the EXACT bytes the driver sends. A declared
+    // forgery flips one nibble of the DIGEST, never the body: the engine
+    // binds submitted bytes to the declared fixture, so an altered body
+    // would be refused as evidence rather than graded.
+    let digest = createHmac('sha256', secret).update(bodyText, 'utf8').digest('hex');
+    if (profile.forgery === 'signature') {
+        // The digest is not the secret: flipping one nibble makes it a
+        // signature that cannot verify, deterministically.
+        const last = digest.length - 1;
+        digest = `${digest.slice(0, last)}${digest[last] === '0' ? '1' : '0'}`;
+    }
+    headers[profile.header] = digest;
+    if (profile.timestampHeader !== null) {
+        const stamp = declaredTimestampMs ?? now;
+        if (profile.toleranceMs !== null && Math.abs(now - stamp) > profile.toleranceMs) {
+            throw new BehaviorDriverError(`declared signature timestamp is ${String(Math.abs(now - stamp))}ms from the engine clock, ` +
+                `outside the declared tolerance of ${String(profile.toleranceMs)}ms`);
+        }
+        headers[profile.timestampHeader] = String(stamp);
+    }
+    if (profile.attemptHeader !== null) {
+        headers[profile.attemptHeader] = String(profile.attempt);
+    }
+    return bodyText;
+}
+/**
+ * Drives one approved request and captures the bounded observation.
+ *
+ * Args:
+ *   input: action, lease, actor profile, origin, credential resolver,
+ *   and timeout.
+ *
+ * Returns:
+ *   DrivenRequest: method/path/query/body/status/response plus
+ *   identity digests (headers never leave the driver).
+ *
+ * Throws:
+ *   BehaviorDriverError: unsupported encoding, unresolvable value,
+ *   non-loopback origin, timeout, over-limit body, or transport
+ *   failure — always a blocking diagnostic, never proof.
+ */
+export async function driveBehaviorRequest(input) {
+    const { action, lease } = input;
+    // The declared profile names what the ENGINE does with a secret it
+    // holds; an unknown algorithm or parameter fails closed here, exactly
+    // as the config schema refuses it at parse time.
+    let signature = null;
+    if (action.signatureProfile !== undefined) {
+        const parsed = parseBehaviorSignatureProfile(action.signatureProfile);
+        if (parsed.ok === false)
+            throw new BehaviorDriverError(parsed.error);
+        signature = parsed.profile;
+    }
+    if (action.body.encoding === 'multipart') {
+        throw new BehaviorDriverError(`'multipart' bodies need the Phase 6 file driver`);
+    }
+    if (action.body.encoding === 'raw' && action.signatureProfile === undefined) {
+        throw new BehaviorDriverError(`'raw' bodies require an engine-side signature profile`);
+    }
+    await assertLoopback(input.origin, 'behavior principal').catch((error) => {
+        throw new BehaviorDriverError(error instanceof Error ? error.message : String(error));
+    });
+    const base = input.origin.replace(/\/+$/, '');
+    // Concrete path: every template variable resolves to a segment-safe value.
+    const templateSegments = action.pathTemplate.split('/');
+    const concreteSegments = [];
+    for (const segment of templateSegments) {
+        const match = /^\{([A-Za-z0-9_]+)\}$/.exec(segment);
+        if (match === null) {
+            concreteSegments.push(segment);
+            continue;
+        }
+        const name = match[1];
+        const raw = action.path[name];
+        if (raw === undefined)
+            throw new BehaviorDriverError(`path parameter '${name}' is not declared`);
+        const resolved = resolveValue(raw, lease.subjects, `path parameter '${name}'`);
+        if (typeof resolved !== 'string' && typeof resolved !== 'number') {
+            throw new BehaviorDriverError(`path parameter '${name}' is not a scalar`);
+        }
+        const text = String(resolved);
+        if (text.length === 0 || text.includes('/')) {
+            throw new BehaviorDriverError(`path parameter '${name}' would smuggle path segments`);
+        }
+        concreteSegments.push(encodeURIComponent(text));
+    }
+    const path = concreteSegments.join('/').replace(/\/+/g, '/');
+    // Declared query, resolved exactly (the driver sends the contract).
+    const query = {};
+    for (const [name, raw] of Object.entries(action.query)) {
+        const resolved = resolveValue(raw, lease.subjects, `query parameter '${name}'`);
+        if (typeof resolved !== 'string' && typeof resolved !== 'number' && typeof resolved !== 'boolean') {
+            throw new BehaviorDriverError(`query parameter '${name}' is not a scalar`);
+        }
+        query[name] = resolved;
+    }
+    const queryText = Object.entries(query)
+        .map(([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(String(value))}`)
+        .join('&');
+    // Declared body, resolved exactly. `raw` resolves the fixture-named
+    // EXACT bytes from the trusted lease subjects — the signature (when a
+    // profile is declared) is computed engine-side over those exact bytes,
+    // never over a re-serialization.
+    let bodyFields = {};
+    let bodyText;
+    let contentType;
+    if (action.body.encoding === 'raw') {
+        const fixtureName = action.body.fixture;
+        if (typeof fixtureName !== 'string')
+            throw new BehaviorDriverError('raw body has no fixture reference');
+        const resolved = resolveValue({ from: 'fixture', key: fixtureName }, lease.subjects, 'raw body fixture');
+        if (typeof resolved !== 'string')
+            throw new BehaviorDriverError('raw body fixture is not exact bytes (string)');
+        bodyText = resolved;
+        contentType = 'application/json';
+    }
+    else {
+        for (const [name, raw] of Object.entries(action.body.fields ?? {})) {
+            bodyFields[name] = resolveValue(raw, lease.subjects, `body field '${name}'`);
+        }
+        if (action.body.encoding === 'json') {
+            bodyText = JSON.stringify(bodyFields);
+            contentType = 'application/json';
+        }
+        else {
+            bodyText = new URLSearchParams(Object.entries(bodyFields).map(([name, value]) => [name, typeof value === 'string' ? value : JSON.stringify(value)])).toString();
+            contentType = 'application/x-www-form-urlencoded';
+        }
+    }
+    if (bodyText.length > BEHAVIOR_BODY_LIMIT_BYTES) {
+        throw new BehaviorDriverError('request body exceeds the proof bound');
+    }
+    // Actor material resolves privately, engine-side only.
+    const headers = { 'content-type': contentType };
+    const actor = lease.actors[input.actorProfile];
+    if (actor === undefined) {
+        throw new BehaviorDriverError(`actor profile '${input.actorProfile}' has no lease`);
+    }
+    if (input.action.credentialVariant === 'valid' || input.action.credentialVariant === 'corrupted') {
+        const material = await input.resolveCredential(actor.credentialRef);
+        if (material === null)
+            throw new BehaviorDriverError('actor credential reference does not resolve');
+        if (input.action.credentialVariant === 'valid') {
+            for (const [name, value] of Object.entries(material.headers)) {
+                // The signing secret is consumed by the driver (never sent as a
+                // header); the signature is computed over the exact raw bytes.
+                if (name === BEHAVIOR_SIGNING_SECRET_HEADER)
+                    continue;
+                headers[name] = value;
+            }
+            if (signature !== null) {
+                const secret = material.headers[BEHAVIOR_SIGNING_SECRET_HEADER];
+                if (secret === undefined || secret.length === 0) {
+                    throw new BehaviorDriverError('signing profile declared but no engine-side secret is bound');
+                }
+                const declared = lease.subjects['signatureTimestampMs'];
+                bodyText = stampSignature(signature, secret, bodyText, headers, typeof declared === 'number' && Number.isFinite(declared) ? declared : null);
+            }
+        }
+        else {
+            for (const [name, value] of Object.entries(material.headers)) {
+                if (name === BEHAVIOR_SIGNING_SECRET_HEADER)
+                    continue;
+                headers[name] = value.length > 0 ? `${value.slice(0, -1)}X` : 'X';
+            }
+        }
+    }
+    const engineRequestId = randomUUID();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), input.timeoutMs);
+    let response;
+    try {
+        response = await fetch(`${base}${path}${queryText.length > 0 ? `?${queryText}` : ''}`, {
+            method: action.method.toUpperCase(),
+            headers,
+            body: action.method.toUpperCase() === 'GET' || action.method.toUpperCase() === 'HEAD' ? undefined : bodyText,
+            signal: controller.signal,
+            // Never follow redirects: the observed status is the principal's
+            // own response (a form POST legitimately answers 303).
+            redirect: 'manual',
+        });
+    }
+    catch (error) {
+        throw new BehaviorDriverError(`principal request failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const responseText = await readBoundedBody(response, BEHAVIOR_BODY_LIMIT_BYTES);
+    const responseBody = parseBody(responseText);
+    const bodyValue = action.body.encoding === 'raw'
+        ? bodyText
+        : action.body.encoding === 'json'
+            ? parseBody(bodyText)
+            : Object.fromEntries(new URLSearchParams(bodyText).entries());
+    const requestDigest = sha256Canonical({
+        method: action.method.toUpperCase(),
+        path,
+        query,
+        body: bodyValue,
+    });
+    const responseDigest = sha256Canonical({ status: response.status, body: responseBody });
+    return {
+        engineRequestId,
+        method: action.method.toUpperCase(),
+        path,
+        query,
+        body: bodyValue,
+        status: response.status,
+        responseBody,
+        requestDigest,
+        responseDigest,
+    };
+}
+//# sourceMappingURL=behavior-request.js.map

package/dist/witness/behavior-request.js.map

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

package/dist/witness/behavior.d.ts

@@ -0,0 +1,52 @@
+/** What a snapshot was validated against. */
+export interface SnapshotScopeSpec {
+    /** Approved snapshot scope key. */
+    scope: string;
+    /** Fixture namespace the case lease owns. */
+    fixtureNamespace: string;
+    /** Exact ordered identity columns (tenant included where needed). */
+    identityFields: string[];
+    /** Nonempty relevant field projection. */
+    fields: string[];
+    /** Hard entity cap (bounded memory). */
+    maxEntities?: number;
+}
+/** Default entity cap when the caller names none. */
+export declare const DEFAULT_MAX_SNAPSHOT_ENTITIES = 10000;
+/** Validated snapshot: entities indexed by canonical identity key. */
+export interface ValidatedSnapshot {
+    /** The validated checkpoint. */
+    checkpoint: string;
+    /** Identity key → entity index (canonical order preserved). */
+    index: Map<string, {
+        entityId: unknown;
+        fields: Record<string, unknown>;
+    }>;
+    /** Identity keys in snapshot order. */
+    order: string[];
+}
+export type SnapshotValidation = {
+    ok: true;
+    snapshot: ValidatedSnapshot;
+} | {
+    ok: false;
+    detail: string;
+};
+/**
+ * Canonical identity key: scalars stringify directly; composite keys
+ * serialize the COMPLETE column-keyed object with sorted column names.
+ * Missing identity columns are an unknown identity (null return).
+ */
+export declare function identityKeyOf(entityId: unknown, identityFields: string[]): string | null;
+/**
+ * Validates one trusted scope snapshot against its declared spec.
+ *
+ * Args:
+ *   snapshot: the adapter-produced snapshot (untrusted input).
+ *   spec: the declared scope, namespace, identity, and projection.
+ *
+ * Returns:
+ *   SnapshotValidation: the indexed snapshot, or a blocking detail.
+ */
+export declare function validateScopeSnapshot(snapshot: unknown, spec: SnapshotScopeSpec): SnapshotValidation;
+//# sourceMappingURL=behavior.d.ts.map

package/dist/witness/behavior.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"behavior.d.ts","sourceRoot":"","sources":["../../src/witness/behavior.ts"],"names":[],"mappings":"AAiBA,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,gBAAgB,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qDAAqD;AACrD,eAAO,MAAM,6BAA6B,QAAS,CAAC;AAEpD,sEAAsE;AACtE,MAAM,WAAW,iBAAiB;IAChC,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC3E,uCAAuC;IACvC,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,MAAM,kBAAkB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,iBAAiB,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAS3G;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAexF;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,GAAG,kBAAkB,CAqEpG"}

package/dist/witness/behavior.js

@@ -0,0 +1,118 @@
+/** Default entity cap when the caller names none. */
+export const DEFAULT_MAX_SNAPSHOT_ENTITIES = 10_000;
+/** True for plain data objects (never arrays, null, or class instances). */
+function isRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Canonical identity key: scalars stringify directly; composite keys
+ * serialize the COMPLETE column-keyed object with sorted column names.
+ * Missing identity columns are an unknown identity (null return).
+ */
+export function identityKeyOf(entityId, identityFields) {
+    if (entityId === null || entityId === undefined)
+        return null;
+    if (typeof entityId === 'string' || typeof entityId === 'number' || typeof entityId === 'boolean') {
+        return `${typeof entityId}:${String(entityId)}`;
+    }
+    if (!isRecord(entityId))
+        return null;
+    const parts = [];
+    for (const column of [...identityFields].sort()) {
+        const value = entityId[column];
+        if (value === undefined || value === null)
+            return null;
+        if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean')
+            return null;
+        parts.push(`${column}=${typeof value}:${String(value)}`);
+    }
+    if (parts.length === 0)
+        return null;
+    return `composite:${parts.join('|')}`;
+}
+/**
+ * Validates one trusted scope snapshot against its declared spec.
+ *
+ * Args:
+ *   snapshot: the adapter-produced snapshot (untrusted input).
+ *   spec: the declared scope, namespace, identity, and projection.
+ *
+ * Returns:
+ *   SnapshotValidation: the indexed snapshot, or a blocking detail.
+ */
+export function validateScopeSnapshot(snapshot, spec) {
+    const fail = (detail) => ({ ok: false, detail });
+    if (!isRecord(snapshot))
+        return fail('scope snapshot must be an object');
+    if (snapshot['scope'] !== spec.scope) {
+        return fail(`scope snapshot scope '${String(snapshot['scope'])}' does not match declared scope '${spec.scope}'`);
+    }
+    if (snapshot['fixtureNamespace'] !== spec.fixtureNamespace) {
+        return fail(`scope snapshot namespace '${String(snapshot['fixtureNamespace'])}' does not match the case lease namespace`);
+    }
+    if (snapshot['complete'] !== true) {
+        return fail(`scope '${spec.scope}' collection is incomplete (complete:false) — no partial credit`);
+    }
+    const checkpoint = snapshot['checkpoint'];
+    if (typeof checkpoint !== 'string' || checkpoint.length === 0) {
+        return fail(`scope '${spec.scope}' has no authoritative checkpoint`);
+    }
+    if (snapshot['exhausted'] !== true) {
+        return fail(`scope '${spec.scope}' pagination not exhausted — a one-page snapshot cannot prove the set`);
+    }
+    const entities = snapshot['entities'];
+    if (!Array.isArray(entities))
+        return fail(`scope '${spec.scope}' entities must be an array`);
+    const max = spec.maxEntities ?? DEFAULT_MAX_SNAPSHOT_ENTITIES;
+    if (entities.length > max) {
+        return fail(`scope '${spec.scope}' exceeds the entity bound (${String(entities.length)} > ${String(max)})`);
+    }
+    const totalSize = snapshot['totalSize'];
+    if (totalSize !== undefined) {
+        if (typeof totalSize !== 'number' || !Number.isInteger(totalSize) || totalSize < 0) {
+            return fail(`scope '${spec.scope}' totalSize must be a non-negative integer when present`);
+        }
+        if (entities.length !== totalSize) {
+            return fail(`scope '${spec.scope}' truncated (${String(entities.length)} of ${String(totalSize)}) — never silently sampled`);
+        }
+    }
+    if (spec.fields.length === 0)
+        return fail(`scope '${spec.scope}' declares an empty field projection`);
+    const index = new Map();
+    const order = [];
+    let previous = null;
+    for (let position = 0; position < entities.length; position += 1) {
+        const entity = entities[position];
+        if (!isRecord(entity))
+            return fail(`scope '${spec.scope}' entity ${String(position)} must be an object`);
+        const key = identityKeyOf(entity['entityId'], spec.identityFields);
+        if (key === null) {
+            return fail(`scope '${spec.scope}' entity ${String(position)} has unknown identity (fail closed)`);
+        }
+        if (index.has(key)) {
+            return fail(`scope '${spec.scope}' has a duplicate identity '${key}' — ambiguous, not proof`);
+        }
+        if (previous !== null && key <= previous) {
+            return fail(`scope '${spec.scope}' is not in canonical identity order ('${key}' after '${previous}')`);
+        }
+        previous = key;
+        const fields = entity['fields'];
+        if (!isRecord(fields))
+            return fail(`scope '${spec.scope}' entity ${String(position)} fields must be an object`);
+        for (const name of spec.fields) {
+            if (!(name in fields)) {
+                return fail(`scope '${spec.scope}' entity ${String(position)} omits declared field '${name}'`);
+            }
+        }
+        const projected = {};
+        for (const [name, value] of Object.entries(fields))
+            projected[name] = value;
+        index.set(key, { entityId: entity['entityId'], fields: projected });
+        order.push(key);
+    }
+    return { ok: true, snapshot: { checkpoint, index, order } };
+}
+//# sourceMappingURL=behavior.js.map

package/dist/witness/behavior.js.map

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

package/dist/witness/bin.d.ts

@@ -0,0 +1,21 @@
+import type { WitnessHandle } from './types.js';
+/** One-line usage (the header comment above is the long form). */
+export declare const WITNESS_BIN_USAGE: string;
+/**
+ * Reads env + argv and starts the witness.
+ *
+ * Args:
+ *   argv: CLI flags (see the module header; `--help` prints usage and
+ *     returns a never-started handle).
+ *   env: process environment.
+ *
+ * Returns:
+ *   WitnessHandle once listening (or a handle with an empty `url` for
+ *   `--help`; the wrapper skips its URL banner in that case).
+ *
+ * Throws:
+ *   WitnessStartupError / AttestationError / AdapterRegistryError:
+ *     fail-closed startup problems (exit 2 via the wrapper).
+ */
+export declare function main(argv: readonly string[], env: NodeJS.ProcessEnv): Promise<WitnessHandle>;
+//# sourceMappingURL=bin.d.ts.map

package/dist/witness/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../../src/witness/bin.ts"],"names":[],"mappings":"AAsEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,QAKK,CAAC;AAqGpC;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,IAAI,CACxB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,OAAO,CAAC,aAAa,CAAC,CAiExB"}