import { G as SignalsEnvelope, L as ResourceOutcome, R as RootNeedsResult, W as SessionVelocitySignal, _ as DirectedVerifyResult, a as AgentRequest, f as ContextSpec, j as Need, l as ClientIntegrityInput, m as DelegationVerifyInput, tt as VerifyResult, v as EnforcementMode, x as EngineWasmSource, y as EngineConfig } from "./types-CsUMEPQx.js"; import { c as EngineRenderOptions, n as StatusListVerifier } from "./status-list-cache-tv7hgtri.js"; import { HeaderEntry } from "@kya-os/checkpoint-shared"; //#region src/engine/adapters/reputation-oracle.d.ts /** * ReputationOracle adapter — sub-phase B.3. * * Resolves a per-DID reputation score in `[0.0, 1.0]`. Phase 1 wires * an optional HTTP endpoint (Argus). Unavailable / misconfigured / * out-of-range responses degrade to a baseline score so infrastructure * blips can't silently DOS Adobe-class traffic. The orchestrators hand the * engine each agent DID's score; a tenant rule over reputation is Cedar. * * **Degrade-to-trust** (Phase B § 4.5). Reputation is best-effort; * Argus outages do not block traffic. The adapter returns the * configured baseline (default 1.0 = "no signal, treat as trusted") * and logs loudly, so no traffic is rejected just because Argus went down. */ interface ReputationOracleAdapter { /** * Return the agent's reputation in `[0.0, 1.0]`. Higher is better. * * **Does not throw.** Network / parse / range failures degrade to * the baseline + log; the engine should never see a thrown error * from this adapter. */ score(agentDid: string): Promise; } //#endregion //#region src/engine/adapters/clock.d.ts /** * Clock adapter — sub-phase B.5. * * Provides the Unix-seconds timestamp the engine's `Clock` trait needs * for Stage 4 expiration checks. Trivial; the trait shape exists so * tests can inject a frozen clock (and so the engine's sync-trait * surface is satisfied without a JS callback crossing the WASM * boundary — `ContextSpec.nowUnix` carries the value). */ interface ClockAdapter { nowUnix(): number; } //#endregion //#region src/engine/adapters/resolution-host.d.ts /** The engine call a host needs to answer a status-list need. */ interface ResolutionEngine { verifyStatusList: StatusListVerifier; } type ResolutionMode = 'inline' | 'cache-only'; /** * The verification a host answers for. The engine judges every answer with the * verify call's clock (`opts.clock`), which need not be the host's: a replay or * a conformance run pins it to an instant of its own. So what the host hands * the engine is in that clock: a resource's fetch time is the call's `nowUnix` * less the resource's real age, and a status list fetched for the call is * verified, and its expiry judged, at the call's `nowUnix`. The host's own * timing (retry delays, budgets, refresh points) stays on its clock. */ interface ResolutionCall { /** The `nowUnix` the engine is called with for this request. */ nowUnix: number; /** * Keeps the call's background work alive after the response (Cloudflare * Workers' `ctx.waitUntil`). Without it, background fetches run detached. */ waitUntil?: (promise: Promise) => void; } interface ResolutionHost { readonly mode: ResolutionMode; /** * The answers already held for configured roots that an engine would * accept, to send with a request's first call so a request that needs only * roots is decided in one call. Without `call`, in the host's clock. */ rootAnswers(call?: ResolutionCall): Record; /** * One outcome per need, from the cache, a fetch, or `pending`. Never throws. * Without `call`, in the host's clock. */ answer(needs: readonly Need[], engine: ResolutionEngine, call?: ResolutionCall): Promise>; /** Track needs without answering them (the configured roots at startup). */ register(needs: readonly Need[]): void; /** Keep only these root needs pinned; a root no longer configured is dropped. */ setRoots(needs: readonly Need[]): void; /** * Fetch every tracked need that is due, DID documents before status lists, * within the budgets, reading the store first when there is one. Never * throws. */ refresh(engine: ResolutionEngine): Promise; } //#endregion //#region src/engine/adapters/resolution-warmer.d.ts /** The engine calls a warmer makes: the roots' needs, and status-list verification. */ interface ResolutionWarmerEngine extends ResolutionEngine { rootNeeds(contextJson: string): RootNeedsResult | Promise; } //#endregion //#region src/engine/orchestrator/types.d.ts /** * Framework-agnostic HTTP request shape. * * Next.js / Express / Cloudflare Workers / Hono adapters marshal * their native request type into this shape before calling * `verifyRequest`. The shape is intentionally minimal — only what * the engine needs to make a verdict. */ interface IncomingHttpLike { method: string; /** Path + query string (no scheme + host). */ url: string; headers: Record; /** * Parsed body if the framework has already parsed it (Next.js * with `await req.json()`, Express with `body-parser`). Falsy if * the caller hasn't materialised the body — the orchestrator * treats that as "no KYA-OS envelope present" and routes to * PlainHttp. */ body?: Uint8Array | string | object | null; /** * The request body bytes exactly as received, before any parsing. Hosts * set this when they hold the wire bytes: a cloned Fetch `Request`, an * Express `express.raw()` body, or a body-parser `verify` hook that saved * `req.rawBody`. A KYA HTTP Binding (kya-http/2) signature covers these * bytes through `Content-Digest`, so they must be byte-identical to what * the client signed. Set it only after reading the body to its end: an * empty value says the body was empty, which makes a chunked body count * as delivered. A body the host has no stream for is not empty; omit it. When omitted, the orchestrator derives the bytes from * `body`: exact for binary or a string, re-serialised JSON for a parsed * object (which verifies only when the client sent compact JSON). */ rawBody?: Uint8Array | string | null; /** Client IP if the framework surfaces one (Express `req.ip`). */ remoteAddress?: string; /** * Transport/client/behavioural entropy signals, when the host * collected any (e.g. the gateway's TLS fingerprint, or the pixel * beacon's client-collected attributes). Threaded through to * `PlainHttpRequest.signals` or `HttpSignedRequest.signals` untouched; * see `types.ts`. */ signals?: SignalsEnvelope | null; /** * Edge-computed request-velocity heuristic for this client (e.g. the * gateway's in-isolate `SessionVelocityTracker` — see * `apps/web/workers/gateway/src/detection/session-velocity.ts`). * Threaded through to `PlainHttpRequest.sessionVelocity` or * `HttpSignedRequest.sessionVelocity` untouched. * Deliberately separate from `signals` above — see * `SessionVelocitySignal`'s doc comment in `../types.ts`. */ sessionVelocity?: SessionVelocitySignal | null; /** * Host-verified client-integrity facts (the pixel and beacon ingest's nonce * check and interaction-integrity verdict). Threaded through to * `PlainHttpRequest.clientIntegrity` untouched; never sent on a signed * request. See `ClientIntegrityInput` in `../types.ts`. */ clientIntegrity?: ClientIntegrityInput | null; } /** * Options the host wrapper passes per-`verifyRequest`-construction. * The five adapters + clock + tenant identifier + enforcement mode. */ interface VerifyRequestOpts { /** * Answers the DID documents and status lists the engine names in * engine-directed mode. Defaults to one inline host per process * (`makeResolutionHost({ mode: 'inline' })`); a persistent host passes its * warmer's cache-only host so the request path never fetches. */ resolutionHost?: ResolutionHost; reputationOracle: ReputationOracleAdapter; clock: ClockAdapter; /** * @deprecated No longer used; will be removed. Nothing reads it: the engine * makes the tenant decision. */ tenantHost?: string; enforcementMode: EnforcementMode; /** * **Envelope-1 (#2537) coordination flag.** Pre-Envelope-1 the TS * bouncer ships KYA-OS proofs as `{protected,payload,signature}` JSON * in a `KYA-Delegation` header. Post-Envelope-1 they ship compact * JWS in `_meta.proof.jws` of the body. When this flag is true the * orchestrator also accepts the legacy header form. **Default off.** */ legacyEnvelopeFallback?: boolean; /** * Argus URL — passed only so the orchestrator can detect "Argus * not configured" at construction time and log the one-shot * warning. The actual reputation fetch goes through `reputationOracle`. */ argusUrl?: string; /** Injectable for the once-only Argus configuration warning. */ logger?: (msg: string) => void; /** * Override the engine WASM-bridge function used during the sync * `verify()` call. Defaults to the wasm-bindgen `--target bundler` * variant imported by `./verify-request.ts` from `'../index'`. * * The `./orchestrator/node` subpath (SDK-Next.js-Integration-Audit-1 * / #2618 safety net) injects the `--target nodejs` variant here so * Webpack-without-asyncWebAssembly consumers don't transitively pull * the bundler artifact through the orchestrator's verify call. */ engineVerifyFn?: (input: AgentRequest, ctx: ContextSpec) => DirectedVerifyResult; /** * Override for the standalone Layer-2 bearer delegation verifier. Hosts rarely * set this; tests use it to assert the bearer path reaches the correct engine * export instead of demoting to PlainHttp. */ engineVerifyDelegationFn?: (input: DelegationVerifyInput, ctx: ContextSpec) => DirectedVerifyResult | Promise; /** * Override for the engine's status-list verifier (`verifyStatusList`). * Defaults to the export of the engine build this orchestrator entry binds; * tests use it to observe the request the status-list cache sends. */ engineVerifyStatusListFn?: StatusListVerifier; /** * Engine-default behaviour knobs forwarded onto every composed * `ContextSpec`. Defaults to `{ tier3Action: 'monitor' }` so a host * installing `@kya-os/checkpoint-*` with minimal config preserves * 1.3.0 behaviour — tenant policy is the arbiter, the engine does * not short-circuit known-agent UAs with an engine-default Block. * * Host wrappers that want the calibrated engine-default block opt * into `{ tier3Action: 'block' }`. The bench harness is the * canonical opt-in consumer. See the wasm-runtime 1.4.0 CHANGELOG. */ engineConfig?: EngineConfig; /** * Host-injected allow-list of trusted Layer-2 delegation root DIDs, * forwarded verbatim onto every composed `ContextSpec.trustedDelegationRoots`. * Omit (or pass `[]`) and the engine rejects every presented delegation * (fail closed). The host resolves this from its own org context (e.g. * `resolveTrustedDelegationRoots({ slug })`); the stateless runtime never * derives it. */ trustedDelegationRoots?: string[]; /** * Resource server org DID for `Authorization: Bearer `. * The standalone verifier checks the credential's `aud` against this value. */ resourceOrgDid?: string; httpDelegation?: ContextSpec['httpDelegation']; /** * Scopes required by this request for standalone bearer delegation checks. * Omit to verify identity/audience/revocation only. */ requiredScopes?: string[]; } /** * Transport-agnostic response shape `renderDecisionAsResponse` * produces. Host wrappers adapt this to their framework's response * type (NextResponse / Express `res` / Cloudflare Response). * * `status === null` means "pass through" — the request continues to * the next handler. Happens in two cases: * 1. `Decision::Permit` (no block in Enforce mode). * 2. **Any verdict in Observe mode** — Observe never blocks, but * the response headers still carry the would-have-been verdict. */ interface RenderedResponse { status: number | null; headers: Record; /** * Ordered repeatable HTTP fields. Host adapters append these after applying * `headers`; unlike a record, this preserves two `WWW-Authenticate` fields. */ headerEntries?: readonly HeaderEntry[]; body?: string | object; } //#endregion //#region src/engine/orchestrator/render-engine.d.ts /** Per-request host settings for {@link makeRenderDecision}'s renderer. */ type RenderDecisionOptions = EngineRenderOptions; /** The renderer the host adapters call. */ type RenderDecision = (result: VerifyResult, options?: RenderDecisionOptions) => RenderedResponse; //#endregion //#region src/engine-load-error.d.ts /** * Thrown when the engine cannot be loaded: its glue or `.wasm` is missing from * the deployment, or the module fails to instantiate. The `./orchestrator` * Node entries load the engine lazily, inside `initEngine` and * `verifyRequest`, so this reaches the host as a failed verification it * answers fail-closed, never as an error thrown while importing the package. */ export declare class EngineLoadError extends Error { readonly code: "engine_load_failed"; constructor(message: string, options?: { cause?: unknown; }); } //#endregion //#region src/engine/orchestrator/build-agent-request.d.ts interface BuildAgentRequestOpts { /** See `VerifyRequestOpts.legacyEnvelopeFallback`. */ legacyEnvelopeFallback?: boolean; } interface CredentialStatusRef { /** URL the host should fetch from the StatusList cache. */ fetchUrl: string; /** Exact key the engine will query in `ContextSpec.revoked`. */ mapUrl: string; /** * The issuer of the credential carrying the status entry: the list must be * signed by it. Null when the credential names none (the list then fails * closed). */ issuer: string | null; /** * The credential's `statusListIndex`, or null when it is not a * non-negative integer. An index outside the list fails closed. */ index: number | null; } /** * The `iss` a presented DelegationCredential names, read before any signature * check. Null when the credential has no string `iss`. */ interface DelegationIssuerRef { issuer: string | null; } interface BearerDelegationCredentialRef extends DelegationIssuerRef { /** The compact VC-JWT presented as a standalone bearer delegation. */ credential: string; /** Decoded JWT payload claims. Signature verification happens in the engine. */ claims: Record; agentDid: string | null; credentialStatus: CredentialStatusRef | null; } /** * Translate an HTTP-like request into the engine's `AgentRequest`. * * Detection order (conservative — never escalate ambiguous input): * 1. KYA-OS L2 detached proof in `_meta.proof.jws` (spec form). * 2. (Legacy, opt-in) KYA-OS in `KYA-Delegation` header * (Envelope-1 #2537 transition window only). * 3. RFC 9421 HTTP Message Signatures (`Signature-Input` header). * 4. PlainHttp (default — anonymous traffic). */ export declare function buildAgentRequest(req: IncomingHttpLike, opts?: BuildAgentRequestOpts): AgentRequest; /** * Preflight check — does the request body carry a `_meta.proof.jws` * string that `parseJwsPayloadStruct` cannot project into a typed * `McpIPayload`? * * The caller declared intent (an KYA-OS envelope) by including the * JWS field; structural failure to extract the payload means the * envelope is malformed, not absent. Without this preflight, the * orchestrator would silently fall through to PlainHttp — pre-#2560 * that happened to also Block (engine returned `Block(ParseError)` * for every PlainHttp), so the regression was invisible; post-#2560 * the engine's Stage 1 + stub policy returns `Permit` for anonymous * PlainHttp and tampered envelopes would be silently accepted. * * Returns `true` when the orchestrator should synthesize * `Block(ParseError)` BEFORE calling `buildAgentRequest`. */ export declare function hasMalformedJwsBody(req: IncomingHttpLike): boolean; /** * Issuer DID — Stage 1 (identity resolution) targets this. `null` * for PlainHttp (anonymous → no DID to resolve) and for an McpI envelope, * which the engine refuses without resolving anything. * * For `HttpSigned`, this is the KYA HTTP Binding `kya=` signature's base * DID (see [[extractKyaHttpDid]]) — the #3362 gap this closes: without a * pre-fetched `did_doc`, the engine cannot resolve the `keyid` and blocks * a validly-signed request with `kyaos/did-unresolvable`. * A generic RFC 9421 signature (e.g. ChatGPT's `sig1=` profile) has no * `kya` label and stays `null` here, unaffected. */ export declare function extractIssuer(request: AgentRequest): string | null; /** * Agent DID — used by ReputationOracle. For `HttpSigned`, the KYA signer IS * the subject (no separate `sub` claim on a bare L1 signature), so this * returns the same DID as [[extractIssuer]]. `null` otherwise. */ export declare function extractAgentDid(request: AgentRequest): string | null; /** * Standalone draft-kya-http bearer delegation (`Authorization: Bearer `) * plus its explicit fallback header (`KYA-Delegation`). This intentionally does * NOT consume `KYA-OS-Delegation-Credential` when the request is RFC-9421 signed; * that path must stay on `HttpSigned` so holder binding is verified. */ export declare function extractBearerDelegationCredential(req: IncomingHttpLike): BearerDelegationCredentialRef | null; //#endregion //#region src/engine/orchestrator/node.d.ts export declare function verifyRequest(req: IncomingHttpLike, opts: VerifyRequestOpts): Promise; export declare function makeVerifyRequest(opts: VerifyRequestOpts): (req: IncomingHttpLike) => Promise; /** Render a `VerifyResult` as the kya-os/http answer, in the Node engine. */ export declare const renderDecisionAsResponse: RenderDecision; /** * The engine calls a resolution warmer makes (`makeResolutionWarmer`), on the * same engine instance `verifyRequest` uses. Each call loads the engine first, * so a warmer can prime before the first request. */ export declare const resolutionEngine: ResolutionWarmerEngine; /** * Load the engine now rather than on the first request. `wasmModule` is * ignored: this build reads its own wasm (the edge build needs the module). * Rejects with {@link EngineLoadError} when the engine cannot be loaded; a * later call tries again. */ export declare function initEngine(_wasmModule?: EngineWasmSource): Promise; //#endregion export type { BearerDelegationCredentialRef, BuildAgentRequestOpts, EngineWasmSource, IncomingHttpLike, RenderedResponse, VerifyRequestOpts }; //# sourceMappingURL=orchestrator-node.d.ts.map