@kya-os/checkpoint-wasm-runtime 1.0.0 → 1.1.0

package/dist/orchestrator-node.d.ts

@@ -0,0 +1,49 @@
+import { V as VerifyResult } from './types-D0j85fF0.js';
+import { V as VerifyRequestOpts, I as IncomingHttpLike } from './render-decision-Dsjwt96g.js';
+export { B as BuildAgentRequestOpts, R as RenderedResponse, b as buildAgentRequest, e as extractAgentDid, a as extractCredentialStatusUrl, c as extractIssuer, h as hasMalformedJwsBody, r as renderDecisionAsResponse } from './render-decision-Dsjwt96g.js';
+import '@kya-os/checkpoint-shared';
+import './adapters.js';
+
+/**
+ * `verifyRequest` async orchestrator — Phase C.2.
+ *
+ * The single entry point Phase D (Next.js) and Phase E (Express)
+ * compose. Async pre-fetch on the host side; one sync `engineVerify`
+ * call across the WASM boundary. Sync-engine / async-host invariant
+ * (H-1 § 4.5) preserved.
+ *
+ * Orchestration:
+ *   1. Translate HTTP → AgentRequest (no engine I/O).
+ *   2. Extract identifiers (issuer DID, agent DID, status-list URL).
+ *   3. Conditional Promise.all over the *applicable* adapters —
+ *      anonymous PlainHttp gets no network calls; signed MCP-I gets
+ *      DID + status-list + reputation in parallel.
+ *   4. Translate adapter errors to verdicts where the architect-
+ *      ratified posture says so:
+ *        - DidResolver throw  → Block(ParseError) verdict
+ *        - StatusListCache throw → re-throw (host renders 503)
+ *        - Reputation throw   → impossible (Phase B § 4.5)
+ *   5. Compute the tenant Decision via PolicyEvaluator over the
+ *      resolved reputation.
+ *   6. Build ContextSpec, call `engineVerify`, return VerifyResult.
+ *
+ * Cedar-1 forward-compat: step (5) is the only place the
+ * PolicyEvaluator interface gets exercised. When Cedar-1 swaps
+ * implementations, this orchestrator does not change.
+ */
+
+/**
+ * Factory — constructs a `verifyRequest` closure that remembers the
+ * one-shot Argus-not-configured warning state. Use this when the
+ * host wrapper wants the startup log; call `verifyRequest` directly
+ * (the loose function below) if you don't.
+ */
+declare function makeVerifyRequest(opts: VerifyRequestOpts): (req: IncomingHttpLike) => Promise<VerifyResult>;
+/**
+ * Single-shot async entry. Use [`makeVerifyRequest`] in long-lived
+ * hosts (so the Argus warning is one-shot per process); use this
+ * loose form in tests + one-off invocations.
+ */
+declare function verifyRequest(req: IncomingHttpLike, opts: VerifyRequestOpts): Promise<VerifyResult>;
+
+export { IncomingHttpLike, VerifyRequestOpts, makeVerifyRequest, verifyRequest };

package/dist/orchestrator-node.js

@@ -0,0 +1,547 @@
+'use strict';
+
+// src/engine/adapters/outbound-url-policy.ts
+var BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "metadata", "metadata.google.internal"]);
+var UnsafeOutboundUrl = class extends Error {
+  kind = "UnsafeOutboundUrl";
+};
+function assertSafeHttpsUrl(rawUrl, label = "outbound URL") {
+  let parsed;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    throw new UnsafeOutboundUrl(`${label} must be a valid URL: ${rawUrl}`);
+  }
+  if (parsed.protocol !== "https:") {
+    throw new UnsafeOutboundUrl(`${label} must use https: ${rawUrl}`);
+  }
+  if (parsed.username || parsed.password) {
+    throw new UnsafeOutboundUrl(`${label} must not contain credentials: ${rawUrl}`);
+  }
+  const hostname = normalizeHostname(parsed.hostname);
+  if (!hostname || isBlockedHostname(hostname)) {
+    throw new UnsafeOutboundUrl(`${label} targets a local or private host: ${rawUrl}`);
+  }
+  return rawUrl;
+}
+function normalizeHostname(hostname) {
+  let normalized = hostname.trim().toLowerCase();
+  if (normalized.startsWith("[") && normalized.endsWith("]")) {
+    normalized = normalized.slice(1, -1);
+  }
+  while (normalized.endsWith(".")) {
+    normalized = normalized.slice(0, -1);
+  }
+  return normalized;
+}
+function isBlockedHostname(hostname) {
+  if (BLOCKED_HOSTNAMES.has(hostname) || hostname.endsWith(".localhost")) {
+    return true;
+  }
+  const ipv4 = parseIpv4(hostname);
+  if (ipv4) {
+    return isBlockedIpv4(ipv4);
+  }
+  return isBlockedIpv6(hostname);
+}
+function parseIpv4(hostname) {
+  const parts = hostname.split(".");
+  if (parts.length !== 4) return null;
+  const octets = parts.map((part) => {
+    if (!/^\d{1,3}$/.test(part)) return Number.NaN;
+    const value = Number(part);
+    return value >= 0 && value <= 255 ? value : Number.NaN;
+  });
+  if (octets.some(Number.isNaN)) return null;
+  return octets;
+}
+function isBlockedIpv4([a, b]) {
+  return a === 0 || a === 10 || a === 127 || a === 100 && b >= 64 && b <= 127 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168 || a === 198 && (b === 18 || b === 19) || a >= 224;
+}
+function isBlockedIpv6(hostname) {
+  if (!hostname.includes(":")) return false;
+  const ipv4Mapped = hostname.match(/(?:^|:)ffff:(\d{1,3}(?:\.\d{1,3}){3})$/);
+  if (ipv4Mapped) {
+    const ipv4 = parseIpv4(ipv4Mapped[1]);
+    return ipv4 ? isBlockedIpv4(ipv4) : true;
+  }
+  if (hostname === "::" || hostname === "::1" || hostname === "0:0:0:0:0:0:0:1") {
+    return true;
+  }
+  const firstSegment = Number.parseInt(hostname.split(":")[0] || "0", 16);
+  if (Number.isNaN(firstSegment)) return true;
+  return (firstSegment & 65024) === 64512 || // unique local fc00::/7
+  (firstSegment & 65472) === 65152 || // link-local fe80::/10
+  (firstSegment & 65280) === 65280;
+}
+
+// src/engine/index.ts
+function engineVerify(input, ctx) {
+  const result = (void 0)(input, ctx);
+  return result;
+}
+
+// src/engine/adapters/util.ts
+function base64UrlDecode(input) {
+  const padded = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padding = padded.length % 4 === 0 ? "" : "=".repeat(4 - padded.length % 4);
+  return new Uint8Array(Buffer.from(padded + padding, "base64"));
+}
+
+// src/engine/orchestrator/build-agent-request.ts
+function buildAgentRequest(req, opts = {}) {
+  const mcpI = tryBuildMcpIFromBody(req);
+  if (mcpI) {
+    return { protocol: "McpI", request: mcpI };
+  }
+  if (opts.legacyEnvelopeFallback) {
+    const legacyMcpI = tryBuildMcpIFromLegacyHeader(req);
+    if (legacyMcpI) {
+      return { protocol: "McpI", request: legacyMcpI };
+    }
+  }
+  if (getHeader(req, "signature-input")) {
+    return { protocol: "HttpSigned", request: buildHttpSigned(req) };
+  }
+  return { protocol: "PlainHttp", request: buildPlainHttp(req) };
+}
+function hasMalformedJwsBody(req) {
+  const parsed = parseBodyAsObject(req.body);
+  if (!parsed || typeof parsed !== "object") return false;
+  const meta = parsed._meta;
+  if (!meta || typeof meta !== "object") return false;
+  const proof = meta.proof;
+  if (!proof || typeof proof !== "object") return false;
+  const jws = proof.jws;
+  if (typeof jws !== "string" || jws.length === 0) return false;
+  const raw = Array.from(Buffer.from(jws, "utf8"));
+  return parseJwsPayloadStruct(raw) === null;
+}
+function extractIssuer(request) {
+  if (request.protocol === "McpI") return request.request.payload.iss || null;
+  return null;
+}
+function extractAgentDid(request) {
+  if (request.protocol === "McpI") return request.request.payload.sub || null;
+  return null;
+}
+function extractCredentialStatusUrl(request) {
+  if (request.protocol !== "McpI") return null;
+  const raw = decodeJwsPayloadJson(request.request.raw);
+  if (!raw) return null;
+  const vc = raw.vc;
+  if (!vc || typeof vc !== "object") return null;
+  const credentialStatus = vc.credentialStatus;
+  if (!credentialStatus || typeof credentialStatus !== "object") return null;
+  const id = credentialStatus.id;
+  return typeof id === "string" ? id : null;
+}
+function tryBuildMcpIFromBody(req) {
+  const parsed = parseBodyAsObject(req.body);
+  if (!parsed) return null;
+  const meta = parsed._meta;
+  if (!meta || typeof meta !== "object") return null;
+  const proof = meta.proof;
+  if (!proof || typeof proof !== "object") return null;
+  const jws = proof.jws;
+  if (typeof jws !== "string" || jws.length === 0) return null;
+  const raw = Array.from(Buffer.from(jws, "utf8"));
+  const payload = parseJwsPayloadStruct(raw);
+  if (!payload) return null;
+  return { raw, payload };
+}
+function parseBodyAsObject(body) {
+  if (!body) return null;
+  if (Buffer.isBuffer(body)) {
+    try {
+      return JSON.parse(body.toString("utf8"));
+    } catch {
+      return null;
+    }
+  }
+  if (typeof body === "string") {
+    try {
+      return JSON.parse(body);
+    } catch {
+      return null;
+    }
+  }
+  if (typeof body === "object") return body;
+  return null;
+}
+function tryBuildMcpIFromLegacyHeader(req) {
+  const header = getHeader(req, "kya-delegation");
+  if (!header) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(header);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const obj = parsed;
+  const protectedSeg = obj.protected;
+  const payloadSeg = obj.payload;
+  const signatureSeg = obj.signature;
+  if (typeof protectedSeg !== "string" || typeof payloadSeg !== "string" || typeof signatureSeg !== "string") {
+    return null;
+  }
+  const compact = `${protectedSeg}.${payloadSeg}.${signatureSeg}`;
+  const raw = Array.from(Buffer.from(compact, "utf8"));
+  const payload = parseJwsPayloadStruct(raw);
+  if (!payload) return null;
+  return { raw, payload };
+}
+function parseJwsPayloadStruct(rawBytes) {
+  const json = decodeJwsPayloadJson(rawBytes);
+  if (!json || typeof json !== "object") return null;
+  return projectMcpIPayload(json);
+}
+function decodeJwsPayloadJson(rawBytes) {
+  const text = Buffer.from(rawBytes).toString("utf8");
+  const segments = text.split(".");
+  if (segments.length !== 3) return null;
+  let decoded;
+  try {
+    decoded = base64UrlDecode(segments[1]);
+  } catch {
+    return null;
+  }
+  try {
+    return JSON.parse(Buffer.from(decoded).toString("utf8"));
+  } catch {
+    return null;
+  }
+}
+function projectMcpIPayload(raw) {
+  const aud = raw.aud;
+  const iss = raw.iss;
+  const sub = raw.sub;
+  const nonce = raw.nonce;
+  const sessionId = raw.sessionId;
+  const ts = raw.ts;
+  const requestHash = raw.requestHash;
+  const responseHash = raw.responseHash;
+  if (typeof aud !== "string" || typeof iss !== "string" || typeof sub !== "string" || typeof nonce !== "string" || typeof sessionId !== "string" || typeof ts !== "number" || typeof requestHash !== "string" || typeof responseHash !== "string") {
+    return null;
+  }
+  return { aud, iss, sub, nonce, sessionId, ts, requestHash, responseHash };
+}
+function buildHttpSigned(req) {
+  return {
+    raw: bodyAsBytes(req.body),
+    method: req.method,
+    path: req.url,
+    headers: flattenHeaders(req.headers)
+  };
+}
+function buildPlainHttp(req) {
+  return {
+    raw: bodyAsBytes(req.body),
+    method: req.method,
+    path: req.url,
+    headers: flattenHeaders(req.headers),
+    userAgent: getHeader(req, "user-agent") ?? null,
+    remoteIp: req.remoteAddress ?? null
+  };
+}
+function getHeader(req, name) {
+  const lowered = name.toLowerCase();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (key.toLowerCase() !== lowered) continue;
+    if (Array.isArray(value)) return value[0] ?? null;
+    if (typeof value === "string") return value;
+  }
+  return null;
+}
+function flattenHeaders(headers) {
+  const out = [];
+  for (const [key, value] of Object.entries(headers)) {
+    if (value === void 0) continue;
+    if (Array.isArray(value)) {
+      for (const v of value) out.push([key, v]);
+    } else {
+      out.push([key, value]);
+    }
+  }
+  return out;
+}
+function bodyAsBytes(body) {
+  if (!body) return [];
+  if (Buffer.isBuffer(body)) return Array.from(body);
+  if (typeof body === "string") return Array.from(Buffer.from(body, "utf8"));
+  if (typeof body === "object") return Array.from(Buffer.from(JSON.stringify(body), "utf8"));
+  return [];
+}
+
+// src/engine/orchestrator/verify-request.ts
+var DEFAULT_REPUTATION_BASELINE = 1;
+function makeVerifyRequest(opts) {
+  let argusWarningLogged = false;
+  const log = opts.logger ?? defaultLogger;
+  return async function verifyRequest2(req) {
+    if (!argusWarningLogged && !opts.argusUrl) {
+      log(
+        '[Checkpoint] WARNING: Argus URL not configured; reputation will degrade to baseline 1.0 ("trust by default"). Set ARGUS_API_URL to enable.'
+      );
+      argusWarningLogged = true;
+    }
+    return verifyRequest_internal(req, opts);
+  };
+}
+async function verifyRequest(req, opts) {
+  return verifyRequest_internal(req, opts);
+}
+async function verifyRequest_internal(req, opts) {
+  if (hasMalformedJwsBody(req)) {
+    return blockWithParseError("malformed JWS body", opts.enforcementMode);
+  }
+  const agentRequest = buildAgentRequest(req, {
+    legacyEnvelopeFallback: opts.legacyEnvelopeFallback
+  });
+  const issuer = extractIssuer(agentRequest);
+  const agentDid = extractAgentDid(agentRequest);
+  const credentialStatusUrl = extractCredentialStatusUrl(agentRequest);
+  const baseline = opts.reputationBaseline ?? DEFAULT_REPUTATION_BASELINE;
+  const [didResult, statusResult, repResult] = await Promise.allSettled([
+    issuer ? opts.didResolver.resolve(issuer) : Promise.resolve(null),
+    credentialStatusUrl ? fetchCredentialStatus(credentialStatusUrl, opts.statusListCache) : Promise.resolve(null),
+    agentDid ? opts.reputationOracle.score(agentDid) : Promise.resolve(baseline)
+  ]);
+  if (didResult.status === "rejected") {
+    if (isDidResolverError(didResult.reason)) {
+      return blockWithParseError(
+        didResult.reason instanceof Error ? didResult.reason.message : String(didResult.reason),
+        opts.enforcementMode
+      );
+    }
+    throw didResult.reason;
+  }
+  if (statusResult.status === "rejected") {
+    if (statusResult.reason instanceof UnsafeOutboundUrl) {
+      return blockWithParseError(statusResult.reason.message, opts.enforcementMode);
+    }
+    throw statusResult.reason;
+  }
+  if (repResult.status === "rejected") {
+    throw repResult.reason;
+  }
+  const didDoc = didResult.value;
+  const revokedIndices = statusResult.value;
+  const repScore = repResult.value;
+  const tenantDecision = await opts.policyEvaluator.evaluate({
+    tenantHost: opts.tenantHost,
+    reputation: repScore
+  });
+  const ctx = {
+    didDocs: didDoc && issuer ? { [issuer]: didDoc } : {},
+    revoked: revokedIndices !== null && credentialStatusUrl ? { [credentialStatusUrl]: revokedIndices } : {},
+    reputation: agentDid ? { [agentDid]: repScore } : {},
+    tenantDecision,
+    nowUnix: opts.clock.nowUnix(),
+    enforcementMode: opts.enforcementMode
+  };
+  return engineVerify(agentRequest, ctx);
+}
+async function fetchCredentialStatus(credentialStatusUrl, statusListCache) {
+  assertSafeHttpsUrl(credentialStatusUrl, "credential status URL");
+  return statusListCache.fetch(credentialStatusUrl);
+}
+function isDidResolverError(err) {
+  if (!(err instanceof Error)) return false;
+  const kind = err.kind;
+  return kind === "DidNotFound" || kind === "DidResolverTimeout" || kind === "DidResolverError" || kind === "MalformedDid" || kind === "UnsupportedKeyType" || kind === "UnsupportedDidMethod";
+}
+function blockWithParseError(detail, enforcementMode) {
+  return {
+    decision: {
+      kind: "Block",
+      reason: {
+        kind: "ParseError",
+        detail
+      }
+    },
+    enforcementMode,
+    engineInfo: {
+      name: "checkpoint-engine-wasm",
+      version: "0.0.0-host-synth",
+      rulesetHash: "sha256:host-synthesized",
+      rulesetVersion: "0.0.0-host-synth",
+      extras: { synthesized: true }
+    }
+  };
+}
+function defaultLogger(msg) {
+  console.warn(msg);
+}
+
+// src/engine/orchestrator/render-decision.ts
+function renderDecisionAsResponse(result) {
+  const baseHeaders = buildBaseHeaders(result);
+  if (result.enforcementMode === "observe") {
+    return {
+      status: null,
+      headers: {
+        ...baseHeaders,
+        "X-Checkpoint-Mode": "observe",
+        "X-Checkpoint-Would-Have-Been": result.decision.kind,
+        ...wouldHaveBeenReasonHeader(result)
+      }
+    };
+  }
+  switch (result.decision.kind) {
+    case "Permit":
+      return {
+        status: null,
+        headers: { ...baseHeaders, "X-Checkpoint-Decision": "permit" }
+      };
+    case "Block": {
+      const reason = result.decision.reason;
+      return {
+        status: httpStatusForBlockReason(reason),
+        headers: {
+          ...baseHeaders,
+          ...blockHeaders(reason),
+          "X-Checkpoint-Decision": "block",
+          "X-Checkpoint-Reason": reason.kind
+        },
+        body: blockResponseBody(reason)
+      };
+    }
+    case "Challenge": {
+      const params = result.decision.params;
+      return {
+        status: 401,
+        headers: {
+          ...baseHeaders,
+          "X-Checkpoint-Decision": "challenge",
+          "X-Checkpoint-Challenge": params.nonce
+        },
+        body: {
+          challenge: params
+        }
+      };
+    }
+    case "Redirect": {
+      const target = result.decision.target;
+      return {
+        status: 302,
+        headers: {
+          ...baseHeaders,
+          "X-Checkpoint-Decision": "redirect",
+          Location: target.url,
+          "X-Checkpoint-Redirect-Reason": target.reason
+        }
+      };
+    }
+    case "Instruct": {
+      const payload = result.decision.payload;
+      return {
+        status: 422,
+        headers: {
+          ...baseHeaders,
+          "X-Checkpoint-Decision": "instruct",
+          "Content-Type": "application/problem+json"
+        },
+        body: {
+          type: payload.problem,
+          title: payload.title,
+          suggestedActions: payload.suggestedActions
+        }
+      };
+    }
+  }
+}
+function buildBaseHeaders(result) {
+  const headers = {
+    "X-Checkpoint-Engine": result.engineInfo.name,
+    "X-Checkpoint-Engine-Version": result.engineInfo.version
+  };
+  if (result.engineInfo.rulesetHash) {
+    headers["X-Checkpoint-Ruleset-Hash"] = result.engineInfo.rulesetHash;
+  }
+  return headers;
+}
+function httpStatusForBlockReason(reason) {
+  switch (reason.kind) {
+    case "Unauthenticated":
+    case "Expired":
+      return 401;
+    case "ParseError":
+      return 400;
+    case "InvalidSignature":
+    case "Revoked":
+    case "OutOfScope":
+    case "LowReputation":
+    case "PolicyDenied":
+      return 403;
+  }
+}
+function blockHeaders(reason) {
+  if (reason.kind === "Unauthenticated") {
+    return { "WWW-Authenticate": 'KyaProof realm="checkpoint"' };
+  }
+  return {};
+}
+function blockResponseBody(reason) {
+  switch (reason.kind) {
+    case "Revoked":
+    case "InvalidSignature":
+    case "Unauthenticated":
+    case "Expired":
+      return { error: humanError(reason.kind), reason: reason.kind };
+    case "OutOfScope":
+      return {
+        error: "requested scope is not granted",
+        reason: "OutOfScope",
+        requested: reason.requested,
+        granted: reason.granted
+      };
+    case "LowReputation":
+      return {
+        error: "agent reputation below tenant threshold",
+        reason: "LowReputation",
+        score: reason.score,
+        threshold: reason.threshold
+      };
+    case "PolicyDenied":
+      return {
+        error: "tenant policy denied the request",
+        reason: "PolicyDenied",
+        detail: reason.detail
+      };
+    case "ParseError":
+      return {
+        error: "request envelope could not be parsed",
+        reason: "ParseError",
+        detail: reason.detail
+      };
+  }
+}
+function humanError(kind) {
+  switch (kind) {
+    case "Revoked":
+      return "credential has been revoked";
+    case "InvalidSignature":
+      return "request signature failed verification";
+    case "Unauthenticated":
+      return "authentication required";
+    case "Expired":
+      return "credential is expired";
+  }
+}
+function wouldHaveBeenReasonHeader(result) {
+  if (result.decision.kind === "Block") {
+    return { "X-Checkpoint-Would-Have-Been-Reason": result.decision.reason.kind };
+  }
+  return {};
+}
+
+exports.buildAgentRequest = buildAgentRequest;
+exports.extractAgentDid = extractAgentDid;
+exports.extractCredentialStatusUrl = extractCredentialStatusUrl;
+exports.extractIssuer = extractIssuer;
+exports.hasMalformedJwsBody = hasMalformedJwsBody;
+exports.makeVerifyRequest = makeVerifyRequest;
+exports.renderDecisionAsResponse = renderDecisionAsResponse;
+exports.verifyRequest = verifyRequest;