@peac/protocol 0.13.0 → 0.13.2

package/dist/index.mjs

@@ -1,12 +1,634 @@
 import { uuidv7 } from 'uuidv7';
-import { sign, signWire02, decode, verify, jcsHash, sha256Hex, computeJwkThumbprint, jwkToPublicKeyBytes, base64urlDecode } from '@peac/crypto';
+import { sign, decode, verify, jcsHash, sha256Hex, computeJwkThumbprint, jwkToPublicKeyBytes, base64urlDecode, signWire02, base64urlDecodeString, base64urlEncode } from '@peac/crypto';
 export { base64urlDecode, base64urlEncode, computeJwkThumbprint, generateKeypair, jwkToPublicKeyBytes, sha256Bytes, sha256Hex, verify } from '@peac/crypto';
+import { isValidPurposeToken, isCanonicalPurpose, isValidPurposeReason, isValidWorkflowContext, createWorkflowContextInvalidError, hasValidDagSemantics, createWorkflowDagInvalidError, WORKFLOW_EXTENSION_KEY, validateKernelConstraints, createConstraintViolationError, ReceiptClaims, createEvidenceNotJsonError, validateSubjectSnapshot, isCanonicalIss, Wire02ClaimsSchema, PEAC_ISSUER_CONFIG_MAX_BYTES, validateRevokedKeys, PEAC_ISSUER_CONFIG_PATH, PEAC_POLICY_MAX_BYTES, PEAC_POLICY_PATH, PEAC_POLICY_FALLBACK_PATH, WARNING_TYP_MISSING, parseReceiptClaims, checkOccurredAtSkew, REGISTERED_RECEIPT_TYPES, WARNING_TYPE_UNREGISTERED, REGISTERED_EXTENSION_GROUP_KEYS, isValidExtensionKey, WARNING_UNKNOWN_EXTENSION, WARNING_EXTENSION_GROUP_MISSING, WARNING_EXTENSION_GROUP_MISMATCH, verifyPolicyBinding, sortWarnings, PEAC_RECEIPT_HEADER, PEAC_PURPOSE_HEADER, parsePurposeHeader, PEAC_PURPOSE_APPLIED_HEADER, PEAC_PURPOSE_REASON_HEADER, KERNEL_CONSTRAINTS } from '@peac/schema';
+import { VERIFIER_LIMITS, VERIFIER_NETWORK, TYPE_TO_EXTENSION_MAP, HASH, VERIFIER_POLICY_VERSION, VERIFICATION_REPORT_VERSION, WIRE_TYPE, OCCURRED_AT_TOLERANCE_SECONDS, ISS_CANONICAL, EXTENSION_BUDGET } from '@peac/kernel';
 import { ZodError } from 'zod';
-import { isValidPurposeToken, isCanonicalPurpose, isValidPurposeReason, isValidWorkflowContext, createWorkflowContextInvalidError, hasValidDagSemantics, createWorkflowDagInvalidError, WORKFLOW_EXTENSION_KEY, validateKernelConstraints, createConstraintViolationError, ReceiptClaims, createEvidenceNotJsonError, validateSubjectSnapshot, isCanonicalIss, Wire02ClaimsSchema, PEAC_ISSUER_CONFIG_MAX_BYTES, validateRevokedKeys, PEAC_ISSUER_CONFIG_PATH, PEAC_POLICY_MAX_BYTES, PEAC_POLICY_PATH, PEAC_POLICY_FALLBACK_PATH, WARNING_TYP_MISSING, parseReceiptClaims, checkOccurredAtSkew, REGISTERED_RECEIPT_TYPES, WARNING_TYPE_UNREGISTERED, REGISTERED_EXTENSION_GROUP_KEYS, isValidExtensionKey, WARNING_UNKNOWN_EXTENSION, WARNING_EXTENSION_GROUP_MISSING, WARNING_EXTENSION_GROUP_MISMATCH, verifyPolicyBinding, sortWarnings, PEAC_RECEIPT_HEADER, PEAC_PURPOSE_HEADER, parsePurposeHeader, PEAC_PURPOSE_APPLIED_HEADER, PEAC_PURPOSE_REASON_HEADER } from '@peac/schema';
 import { createHash } from 'crypto';
-import { VERIFIER_LIMITS, VERIFIER_NETWORK, TYPE_TO_EXTENSION_MAP, HASH, VERIFIER_POLICY_VERSION, VERIFICATION_REPORT_VERSION, WIRE_TYPE } from '@peac/kernel';
 
 // src/issue.ts
+
+// src/_internal/record-core/codec/types.ts
+var CodecError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "CodecError";
+  }
+};
+
+// src/_internal/record-core/codec/jws-jwt.ts
+var JwsJwtCodec = class {
+  name = "jws-jwt";
+  async encode(payload, privateKey, kid) {
+    return signWire02(payload, privateKey, kid);
+  }
+  async decode(serialized, publicKey) {
+    return verify(serialized, publicKey);
+  }
+  peekHeader(serialized) {
+    const segments = serialized.split(".");
+    if (segments.length !== 3) {
+      throw new CodecError(
+        "CODEC_PEEK_MALFORMED",
+        `jws-jwt: malformed compact JWS (expected 3 segments, got ${segments.length})`
+      );
+    }
+    const [headerB64, payloadB64, signatureB64] = segments;
+    if (headerB64.length === 0) {
+      throw new CodecError(
+        "CODEC_PEEK_MALFORMED",
+        "jws-jwt: malformed compact JWS (empty header segment)"
+      );
+    }
+    if (payloadB64.length === 0) {
+      throw new CodecError(
+        "CODEC_PEEK_MALFORMED",
+        "jws-jwt: malformed compact JWS (empty payload segment)"
+      );
+    }
+    if (signatureB64.length === 0) {
+      throw new CodecError(
+        "CODEC_PEEK_MALFORMED",
+        "jws-jwt: malformed compact JWS (empty signature segment)"
+      );
+    }
+    let header;
+    try {
+      const headerJson = base64urlDecodeString(headerB64);
+      header = JSON.parse(headerJson);
+    } catch (err) {
+      throw new CodecError(
+        "CODEC_PEEK_INVALID_HEADER",
+        `jws-jwt: protected header JSON parse failed: ${err.message}`
+      );
+    }
+    if (typeof header.typ !== "string") {
+      throw new CodecError(
+        "CODEC_PEEK_MISSING_TYP",
+        'jws-jwt: protected header missing required field "typ" (string)'
+      );
+    }
+    if (typeof header.alg !== "string") {
+      throw new CodecError(
+        "CODEC_PEEK_MISSING_ALG",
+        'jws-jwt: protected header missing required field "alg" (string)'
+      );
+    }
+    return {
+      typ: header.typ,
+      alg: header.alg,
+      kid: typeof header.kid === "string" ? header.kid : void 0,
+      raw: header
+    };
+  }
+};
+var defaultCodec = new JwsJwtCodec();
+function validateKernelConstraintsInternal(claims) {
+  const violations = [];
+  if (claims === null || claims === void 0 || typeof claims !== "object") {
+    return { valid: true, violations };
+  }
+  let totalNodes = 0;
+  const stack = [
+    { value: claims, depth: 0, path: "" }
+  ];
+  while (stack.length > 0) {
+    const item = stack.pop();
+    totalNodes++;
+    if (totalNodes > KERNEL_CONSTRAINTS.MAX_TOTAL_NODES) {
+      violations.push({
+        constraint: "MAX_TOTAL_NODES",
+        actual: totalNodes,
+        limit: KERNEL_CONSTRAINTS.MAX_TOTAL_NODES,
+        path: item.path
+      });
+      break;
+    }
+    if (item.depth > KERNEL_CONSTRAINTS.MAX_NESTED_DEPTH) {
+      violations.push({
+        constraint: "MAX_NESTED_DEPTH",
+        actual: item.depth,
+        limit: KERNEL_CONSTRAINTS.MAX_NESTED_DEPTH,
+        path: item.path
+      });
+      continue;
+    }
+    if (item.value === null || typeof item.value !== "object") {
+      if (typeof item.value === "string") {
+        if (item.value.length > KERNEL_CONSTRAINTS.MAX_STRING_LENGTH) {
+          violations.push({
+            constraint: "MAX_STRING_LENGTH",
+            actual: item.value.length,
+            limit: KERNEL_CONSTRAINTS.MAX_STRING_LENGTH,
+            path: item.path
+          });
+        }
+      }
+      continue;
+    }
+    if (Array.isArray(item.value)) {
+      if (item.value.length > KERNEL_CONSTRAINTS.MAX_ARRAY_LENGTH) {
+        violations.push({
+          constraint: "MAX_ARRAY_LENGTH",
+          actual: item.value.length,
+          limit: KERNEL_CONSTRAINTS.MAX_ARRAY_LENGTH,
+          path: item.path
+        });
+      }
+      for (let i = item.value.length - 1; i >= 0; i--) {
+        stack.push({
+          value: item.value[i],
+          depth: item.depth + 1,
+          path: `${item.path}[${i}]`
+        });
+      }
+      continue;
+    }
+    const keys = Object.keys(item.value);
+    if (keys.length > KERNEL_CONSTRAINTS.MAX_OBJECT_KEYS) {
+      violations.push({
+        constraint: "MAX_OBJECT_KEYS",
+        actual: keys.length,
+        limit: KERNEL_CONSTRAINTS.MAX_OBJECT_KEYS,
+        path: item.path
+      });
+    }
+    for (let i = keys.length - 1; i >= 0; i--) {
+      const key = keys[i];
+      const childPath = item.path ? `${item.path}.${key}` : key;
+      stack.push({
+        value: item.value[key],
+        depth: item.depth + 1,
+        path: childPath
+      });
+    }
+  }
+  return { valid: violations.length === 0, violations };
+}
+function escapeJsonPointerSegment(segment) {
+  return segment.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function classifyExpectedGroup(kind, type, extensions) {
+  if (kind === "challenge") return "skip";
+  const expectedGroup = TYPE_TO_EXTENSION_MAP.get(type);
+  if (expectedGroup === void 0) return "skip";
+  if (extensions !== void 0 && Object.prototype.hasOwnProperty.call(extensions, expectedGroup)) {
+    return "ok";
+  }
+  if (extensions !== void 0) {
+    for (const key of Object.keys(extensions)) {
+      if (key !== expectedGroup && REGISTERED_EXTENSION_GROUP_KEYS.has(key)) {
+        return "mismatch";
+      }
+    }
+  }
+  return "missing";
+}
+function validateTypeExtensionMappingInternal(input) {
+  const warnings = [];
+  if (!REGISTERED_RECEIPT_TYPES.has(input.type)) {
+    warnings.push({ code: WARNING_TYPE_UNREGISTERED, pointer: "/type" });
+  }
+  if (input.extensions !== void 0) {
+    for (const key of Object.keys(input.extensions)) {
+      if (!REGISTERED_EXTENSION_GROUP_KEYS.has(key) && isValidExtensionKey(key)) {
+        warnings.push({
+          code: WARNING_UNKNOWN_EXTENSION,
+          pointer: `/extensions/${escapeJsonPointerSegment(key)}`
+        });
+      }
+    }
+  }
+  const status = classifyExpectedGroup(input.kind, input.type, input.extensions);
+  if (status === "missing") {
+    warnings.push({ code: WARNING_EXTENSION_GROUP_MISSING, pointer: "/type" });
+  } else if (status === "mismatch") {
+    warnings.push({ code: WARNING_EXTENSION_GROUP_MISMATCH, pointer: "/type" });
+  }
+  return warnings;
+}
+
+// src/_internal/record-core/validators/jose-hardening.ts
+var KID_MAX_LENGTH = 256;
+var ACCEPTED = { accepted: true };
+function rejected(errorCode) {
+  return { accepted: false, errorCode };
+}
+function validateJoseHardeningInternal(header) {
+  if (!header.kid || typeof header.kid !== "string" || header.kid.length === 0 || header.kid.length > KID_MAX_LENGTH) {
+    return rejected("CRYPTO_JWS_MISSING_KID");
+  }
+  if (header.jwk !== void 0 || header.x5c !== void 0 || header.x5u !== void 0 || header.jku !== void 0) {
+    return rejected("CRYPTO_JWS_EMBEDDED_KEY");
+  }
+  if (header.crit !== void 0) {
+    return rejected("CRYPTO_JWS_CRIT_REJECTED");
+  }
+  if (header.b64 === false) {
+    return rejected("CRYPTO_JWS_B64_REJECTED");
+  }
+  if (header.zip !== void 0) {
+    return rejected("CRYPTO_JWS_ZIP_REJECTED");
+  }
+  return ACCEPTED;
+}
+var ACCEPTED2 = { accepted: true };
+var REJECTED = { accepted: false, errorCode: "E_ISS_NOT_CANONICAL" };
+var DID_PATTERN = /^did:[a-z0-9]+:[^#?/]+$/;
+function validateIssuerFormInternal(iss) {
+  if (typeof iss !== "string" || iss.length === 0 || iss.length > ISS_CANONICAL.maxLength) {
+    return REJECTED;
+  }
+  if (iss.startsWith("did:")) {
+    return DID_PATTERN.test(iss) ? ACCEPTED2 : REJECTED;
+  }
+  let url;
+  try {
+    url = new URL(iss);
+  } catch {
+    return REJECTED;
+  }
+  if (url.protocol !== "https:") return REJECTED;
+  if (!url.hostname) return REJECTED;
+  if (url.username !== "" || url.password !== "") return REJECTED;
+  const origin = `${url.protocol}//${url.host}`;
+  return iss === origin ? ACCEPTED2 : REJECTED;
+}
+var ACCEPTED3 = { accepted: true };
+function validateTemporalInternal(occurredAt, iat, now, tolerance = OCCURRED_AT_TOLERANCE_SECONDS) {
+  if (occurredAt === void 0) return ACCEPTED3;
+  const ts = Date.parse(occurredAt) / 1e3;
+  if (isNaN(ts)) return ACCEPTED3;
+  if (ts > now + tolerance) {
+    return {
+      accepted: false,
+      errorCode: "E_OCCURRED_AT_FUTURE",
+      pointer: "/occurred_at"
+    };
+  }
+  if (ts > iat) {
+    return {
+      accepted: true,
+      warnings: [{ code: "occurred_at_skew", pointer: "/occurred_at" }]
+    };
+  }
+  return ACCEPTED3;
+}
+var ACCEPTED4 = { accepted: true, violations: [] };
+var SIZE_EXCEEDED = "E_EXTENSION_SIZE_EXCEEDED";
+var textEncoder = new TextEncoder();
+function jsonUtf8ByteLength(value) {
+  try {
+    return textEncoder.encode(JSON.stringify(value)).byteLength;
+  } catch {
+    return Infinity;
+  }
+}
+function escapeJsonPointerSegment2(segment) {
+  return segment.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function validateExtensionBudgetInternal(extensions) {
+  if (extensions === void 0) return ACCEPTED4;
+  const totalBytes = jsonUtf8ByteLength(extensions);
+  if (totalBytes > EXTENSION_BUDGET.maxTotalBytes) {
+    return {
+      accepted: false,
+      violations: [{ code: SIZE_EXCEEDED, path: "/extensions" }]
+    };
+  }
+  const violations = [];
+  for (const key of Object.keys(extensions)) {
+    const groupBytes = jsonUtf8ByteLength(extensions[key]);
+    if (groupBytes > EXTENSION_BUDGET.maxGroupBytes) {
+      violations.push({
+        code: SIZE_EXCEEDED,
+        path: `/extensions/${escapeJsonPointerSegment2(key)}`
+      });
+    }
+  }
+  if (violations.length === 0) return ACCEPTED4;
+  return { accepted: false, violations };
+}
+
+// src/_internal/record-core/bounded-validator.ts
+function runBoundedValidatorShadow(input) {
+  const violations = [];
+  const warnings = [];
+  const kernelRes = validateKernelConstraintsInternal(input.claims);
+  if (!kernelRes.valid) {
+    for (const v of kernelRes.violations) {
+      violations.push({
+        layer: "kernel-constraints",
+        code: v.constraint,
+        path: v.path || void 0
+      });
+    }
+  }
+  const issRes = validateIssuerFormInternal(input.claims.iss);
+  if (!issRes.accepted) {
+    violations.push({ layer: "issuer-form", code: issRes.errorCode });
+  }
+  if (input.header !== void 0) {
+    const joseRes = validateJoseHardeningInternal(input.header);
+    if (!joseRes.accepted) {
+      violations.push({ layer: "jose-header-hardening", code: joseRes.errorCode });
+    }
+  }
+  const typeExtWarnings = validateTypeExtensionMappingInternal({
+    kind: input.claims.kind,
+    type: input.claims.type,
+    extensions: input.claims.extensions
+  });
+  for (const w of typeExtWarnings) {
+    warnings.push({ layer: "type-extension-mapping", code: w.code, path: w.pointer });
+  }
+  if (input.claims.kind === "evidence") {
+    const temporalRes = validateTemporalInternal(
+      input.claims.occurred_at,
+      input.claims.iat,
+      input.now
+    );
+    if (!temporalRes.accepted) {
+      violations.push({
+        layer: "temporal",
+        code: temporalRes.errorCode,
+        path: temporalRes.pointer
+      });
+    } else if (temporalRes.warnings) {
+      const list = temporalRes.warnings;
+      for (const w of list) {
+        warnings.push({ layer: "temporal", code: w.code, path: w.pointer });
+      }
+    }
+  }
+  const budgetRes = validateExtensionBudgetInternal(input.claims.extensions);
+  if (!budgetRes.accepted) {
+    const list = budgetRes.violations;
+    for (const v of list) {
+      violations.push({ layer: "extension-budget", code: v.code, path: v.path });
+    }
+  }
+  return {
+    accepted: violations.length === 0,
+    violations,
+    warnings
+  };
+}
+var SECRET_PATTERNS = [
+  // Compact JWS / JWT (header.payload.signature with eyJ-prefixed header).
+  /eyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g,
+  // PEM-encoded blocks. Covers RSA / EC / OPENSSH / generic PRIVATE KEY
+  // header variants in a single pattern.
+  /-----BEGIN [A-Z0-9 ]+-----[\s\S]+?-----END [A-Z0-9 ]+-----/g,
+  // Long base64 runs (>=40 chars). The character class is the standard
+  // base64 alphabet only (no `_` or `-`) so that kebab-case and
+  // snake_case identifier strings do not collateral-match. base64url
+  // payloads carrying credentials are reached via more specific patterns
+  // (compact JWS, Bearer, URL query token) and via the wrapper headers
+  // they appear in.
+  /\b[A-Za-z0-9+/]{40,}={0,2}\b/g,
+  // Bearer token (Authorization header value with Bearer scheme).
+  /Bearer\s+[A-Za-z0-9._\-/+=]+/gi,
+  // Generic Authorization header line (any scheme, including Basic /
+  // Digest / Negotiate). Multiline-anchored.
+  /^authorization:\s*[^\r\n]+/gim,
+  // Generic auth-token header line (X-Auth-Token, X-API-Key).
+  /^x-(?:auth-token|api-key):\s*[^\r\n]+/gim,
+  // Cookie request header line (raw client cookies).
+  /^cookie:\s*[^\r\n]+/gim,
+  // Set-Cookie response header line (server-issued sessions).
+  /^set-cookie:\s*[^\r\n]+/gim,
+  // URL query token / API key / secret / access_token.
+  /[?&](?:token|key|secret|access_token|api_key|apikey)=[^&\s#]+/gi,
+  // AWS access key ID (AKIA + 16 alphanumeric).
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  // Email address (PII).
+  /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g,
+  // Phone numbers. Three explicit forms (E.164 + parenthesized NA + dashed
+  // NA / international) so plain consecutive-digit runs (sequence
+  // numbers, hashes, identifiers) do not collateral-match.
+  /\+\d[\d\s().-]{6,}\d/g,
+  /\(\d{3}\)\s*\d{3}[\s.-]?\d{4}/g,
+  /\b\d{3}[\s.-]\d{3}[\s.-]\d{4}\b/g
+];
+var REDACTION_MARKER = "[REDACTED]";
+var TEXT_ENCODER = /* @__PURE__ */ new TextEncoder();
+var TEXT_DECODER = /* @__PURE__ */ new TextDecoder("utf-8", { fatal: false });
+var REDACTION_MARKER_BYTES = TEXT_ENCODER.encode(REDACTION_MARKER).length;
+function utf8ByteLength(value) {
+  return TEXT_ENCODER.encode(value).length;
+}
+function redactNote(input, maxBytes) {
+  if (typeof input !== "string") return REDACTION_MARKER;
+  let redacted = input;
+  for (const pattern of SECRET_PATTERNS) {
+    redacted = redacted.replace(pattern, REDACTION_MARKER);
+  }
+  const bytes = TEXT_ENCODER.encode(redacted);
+  if (bytes.length <= maxBytes) return redacted;
+  if (maxBytes <= REDACTION_MARKER_BYTES) {
+    return REDACTION_MARKER.slice(0, maxBytes);
+  }
+  const headBytes = maxBytes - REDACTION_MARKER_BYTES;
+  return safeUtf8Slice(bytes, headBytes) + REDACTION_MARKER;
+}
+async function canonicalHashOf(value) {
+  return sha256Hex(canonicalStringify(value));
+}
+async function hashJws(jws) {
+  return sha256Hex(jws);
+}
+function canonicalStringify(value) {
+  if (value === null) return "null";
+  if (typeof value === "undefined") return "null";
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? String(value) : "null";
+  }
+  if (typeof value === "boolean") return String(value);
+  if (typeof value === "bigint") return String(value);
+  if (Array.isArray(value)) {
+    return "[" + value.map(canonicalStringify).join(",") + "]";
+  }
+  if (value instanceof Uint8Array) {
+    return JSON.stringify(base64urlEncode(value));
+  }
+  if (typeof value === "object") {
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalStringify(obj[k])).join(",") + "}";
+  }
+  return "null";
+}
+function safeUtf8Slice(bytes, byteLen) {
+  if (byteLen <= 0) return "";
+  if (bytes.length <= byteLen) return TEXT_DECODER.decode(bytes);
+  let end = byteLen;
+  while (end > 0 && (bytes[end] & 192) === 128) {
+    end -= 1;
+  }
+  return TEXT_DECODER.decode(bytes.subarray(0, end));
+}
+
+// src/_internal/shadow.ts
+var MAX_LOG_ENTRIES = 1e3;
+var MAX_NOTE_BYTES = 128;
+var RETENTION_MS = 7 * 24 * 60 * 60 * 1e3;
+var SHADOW_TIMEOUT_MS = 250;
+var SHADOW_LOG = [];
+var PENDING_SHADOW_TASKS = /* @__PURE__ */ new Set();
+function isShadowEnabled(options) {
+  if (options?._internal?.shadowCore === true) return true;
+  return readEnvFlag();
+}
+function readEnvFlag() {
+  if (typeof process === "undefined" || process === null) return false;
+  const env = process.env;
+  return env?.PEAC_INTERNAL_SHADOW_CORE === "1";
+}
+function scheduleShadow(args) {
+  setTimeout(() => {
+    const task = runShadowTask(args);
+    PENDING_SHADOW_TASKS.add(task);
+    const removeFromPending = () => {
+      PENDING_SHADOW_TASKS.delete(task);
+    };
+    void task.then(removeFromPending, removeFromPending);
+  }, 0);
+}
+async function runShadowTask(args) {
+  const recordRefHash = await hashJws(args.recordRef);
+  let shadowResult;
+  let shadowErrorCode;
+  try {
+    shadowResult = await runWithTimeout(args.shadowFn, SHADOW_TIMEOUT_MS);
+  } catch (err) {
+    shadowErrorCode = extractErrorCode(err);
+    appendDivergence({
+      kind: shadowErrorCode === "SHADOW_TIMEOUT" ? "timing-diff" : "shadow-error",
+      call: args.call,
+      recordRefHash,
+      realErrorCode: args.realError?.code,
+      shadowErrorCode,
+      notes: redactNote(`shadow threw ${shadowErrorCode}`, MAX_NOTE_BYTES),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    return;
+  }
+  const divergence = await compareResults(args, shadowResult, recordRefHash);
+  if (divergence) appendDivergence(divergence);
+}
+function runWithTimeout(fn, ms) {
+  const controller = new AbortController();
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      controller.abort();
+      reject(new Error("SHADOW_TIMEOUT"));
+    }, ms);
+    fn(controller.signal).then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      }
+    );
+  });
+}
+async function compareResults(args, shadowResult, recordRefHash) {
+  const ts = (/* @__PURE__ */ new Date()).toISOString();
+  if (!args.realError && shadowResult !== void 0 && args.realResult !== void 0) {
+    const realHash = await canonicalHashOf(args.realResult);
+    const shadowHash = await canonicalHashOf(shadowResult);
+    if (realHash !== shadowHash) {
+      return {
+        kind: "output-byte-diff",
+        call: args.call,
+        recordRefHash,
+        realResultHash: realHash,
+        shadowResultHash: shadowHash,
+        realByteLen: byteLenOf(args.realResult),
+        shadowByteLen: byteLenOf(shadowResult),
+        notes: "canonical-hash-mismatch",
+        timestamp: ts
+      };
+    }
+    return null;
+  }
+  if (args.realError && shadowResult === void 0) {
+    return null;
+  }
+  return {
+    kind: "error-code-diff",
+    call: args.call,
+    recordRefHash,
+    realErrorCode: args.realError?.code,
+    notes: args.realError ? "real-errored-shadow-succeeded" : "real-succeeded-shadow-errored",
+    timestamp: ts
+  };
+}
+function byteLenOf(value) {
+  if (typeof value === "string") return utf8ByteLength(value);
+  if (value instanceof Uint8Array) return value.byteLength;
+  return utf8ByteLength(JSON.stringify(value) ?? "");
+}
+function extractErrorCode(err) {
+  if (err && typeof err === "object") {
+    const candidate = err.code;
+    if (typeof candidate === "string" && candidate.length > 0) return candidate;
+    const message = err.message;
+    if (typeof message === "string" && /^[A-Z_][A-Z0-9_]*$/.test(message)) return message;
+  }
+  return "SHADOW_UNKNOWN_ERROR";
+}
+function appendDivergence(d) {
+  pruneStale();
+  if (SHADOW_LOG.length >= MAX_LOG_ENTRIES) SHADOW_LOG.shift();
+  SHADOW_LOG.push(d);
+}
+function pruneStale() {
+  const cutoffIso = new Date(Date.now() - RETENTION_MS).toISOString();
+  while (SHADOW_LOG.length > 0 && SHADOW_LOG[0].timestamp < cutoffIso) SHADOW_LOG.shift();
+}
+
+// src/_internal/shadow-observe.ts
+function realObservationForIssue() {
+  return EMPTY_ACCEPTED;
+}
+function realObservationForVerifyLocalSuccess(warnings) {
+  if (!warnings || warnings.length === 0) return EMPTY_ACCEPTED;
+  return {
+    accepted: true,
+    violationCodes: [],
+    warningCodes: sortedDedupedCodes(warnings.map((w) => w.code))
+  };
+}
+function shadowObservationFromBounded(bounded) {
+  return {
+    accepted: bounded.accepted,
+    violationCodes: sortedDedupedCodes(bounded.violations.map((v) => v.code)),
+    warningCodes: sortedDedupedCodes(bounded.warnings.map((w) => w.code))
+  };
+}
+function shadowObservationFromBoundedAcceptedOnly(bounded) {
+  return {
+    accepted: bounded.accepted,
+    violationCodes: sortedDedupedCodes(bounded.violations.map((v) => v.code)),
+    warningCodes: []
+  };
+}
+var EMPTY_ACCEPTED = Object.freeze({
+  accepted: true,
+  violationCodes: Object.freeze([]),
+  warningCodes: Object.freeze([])
+});
+function sortedDedupedCodes(codes) {
+  if (codes.length === 0) return [];
+  return Array.from(new Set(codes)).sort();
+}
 function fireTelemetryHook(fn, input) {
   if (!fn) return;
   try {
@@ -224,7 +846,28 @@ async function issueWire02(options) {
       }
     });
   }
-  const jws = await signWire02(claims, options.privateKey, options.kid);
+  const jws = await defaultCodec.encode(claims, options.privateKey, options.kid);
+  if (isShadowEnabled(options)) {
+    scheduleShadow({
+      call: "issue",
+      realResult: realObservationForIssue(),
+      realError: void 0,
+      shadowFn: async () => shadowObservationFromBoundedAcceptedOnly(
+        runBoundedValidatorShadow({
+          claims: {
+            kind: claims.kind,
+            type: claims.type,
+            iss: claims.iss,
+            iat: claims.iat,
+            occurred_at: claims.occurred_at,
+            extensions: claims.extensions
+          },
+          now: iat
+        })
+      ),
+      recordRef: jws
+    });
+  }
   return { jws };
 }
 function parseIssuerConfig(json) {
@@ -236,8 +879,8 @@ function parseIssuerConfig(json) {
     }
     try {
       config = JSON.parse(json);
-    } catch {
-      throw new Error("Issuer config is not valid JSON");
+    } catch (err) {
+      throw new Error("Issuer config is not valid JSON", { cause: err });
     }
   } else {
     config = json;
@@ -260,8 +903,8 @@ function parseIssuerConfig(json) {
   }
   try {
     new URL(obj.jwks_uri);
-  } catch {
-    throw new Error("jwks_uri must be a valid URL");
+  } catch (err) {
+    throw new Error("jwks_uri must be a valid URL", { cause: err });
   }
   if (obj.verify_endpoint !== void 0) {
     if (typeof obj.verify_endpoint !== "string") {
@@ -354,8 +997,8 @@ function parsePolicyManifest(text, contentType) {
   if (isJsonContent(text, contentType)) {
     try {
       manifest = JSON.parse(text);
-    } catch {
-      throw new Error("Policy manifest is not valid JSON");
+    } catch (err) {
+      throw new Error("Policy manifest is not valid JSON", { cause: err });
     }
   } else {
     manifest = parseSimpleYaml(text);
@@ -1435,6 +2078,11 @@ function checkTypeExtensionMapping(kind, type, extensions, typeToExtensionMap, r
   };
 }
 
+// src/_internal/record-core/shadow-hook.ts
+function maybeRunShadowValidation(input) {
+  return void 0;
+}
+
 // src/verify-local.ts
 function isCryptoError(err) {
   return err !== null && typeof err === "object" && "name" in err && err.name === "CryptoError" && "code" in err && typeof err.code === "string" && err.code.startsWith("CRYPTO_") && "message" in err && typeof err.message === "string";
@@ -1471,7 +2119,7 @@ async function verifyLocal(jws, publicKey, options = {}) {
   } = options;
   const now = options.now ?? Math.floor(Date.now() / 1e3);
   try {
-    const result = await verify(jws, publicKey);
+    const result = await defaultCodec.decode(jws, publicKey);
     if (!result.valid) {
       return {
         valid: false,
@@ -1516,6 +2164,7 @@ async function verifyLocal(jws, publicKey, options = {}) {
     }
     if (pr.wireVersion === "0.2") {
       const claims = pr.claims;
+      maybeRunShadowValidation({ mode: "disabled", claims });
       if (issuer !== void 0 && claims.iss !== issuer) {
         return {
           valid: false,
@@ -1623,13 +2272,37 @@ async function verifyLocal(jws, publicKey, options = {}) {
         ...callerBindings?.terms !== void 0 && { terms: callerBindings.terms },
         ...callerBindings?.documents !== void 0 && callerBindings.documents.length > 0 && { documents: callerBindings.documents }
       };
+      const sortedWarnings = sortWarnings(accumulatedWarnings);
+      if (isShadowEnabled(options)) {
+        const headerSnapshot = { ...result.header };
+        scheduleShadow({
+          call: "verifyLocal",
+          realResult: realObservationForVerifyLocalSuccess(sortedWarnings),
+          realError: void 0,
+          shadowFn: async () => shadowObservationFromBounded(
+            runBoundedValidatorShadow({
+              claims: {
+                kind: claims.kind,
+                type: claims.type,
+                iss: claims.iss,
+                iat: claims.iat,
+                occurred_at: claims.occurred_at,
+                extensions: claims.extensions
+              },
+              header: headerSnapshot,
+              now
+            })
+          ),
+          recordRef: jws
+        });
+      }
       return {
         valid: true,
         variant: "wire-02",
         claims,
         kid: result.header.kid,
         wireVersion: "0.2",
-        warnings: sortWarnings(accumulatedWarnings),
+        warnings: sortedWarnings,
         policy_binding: bindingStatus,
         bindings
       };