@jami-studio/orchestra 0.1.0

package/src/oauth.mjs

@@ -0,0 +1,731 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { SignJWT, jwtVerify, errors as joseErrors } from "jose";
+import { createSealedSecretVault } from "./index.mjs";
+
+const OAUTH_SCHEMA_VERSION = "2026-06-22.oauth-token-security";
+
+// JWS algorithms B4 will verify link tokens against. `none`/unsecured JWTs are never
+// allowed: a link token without a real signature is treated as forged.
+const ALLOWED_LINK_TOKEN_ALGS = Object.freeze([
+  "HS256",
+  "HS384",
+  "HS512",
+  "RS256",
+  "RS384",
+  "RS512",
+  "PS256",
+  "PS384",
+  "PS512",
+  "ES256",
+  "ES384",
+  "ES512",
+  "EdDSA",
+]);
+const ALLOWED_LINK_TOKEN_ALG_SET = new Set(ALLOWED_LINK_TOKEN_ALGS);
+const HMAC_ALG_PREFIX = "HS";
+
+// jose link-token source lock — re-verified against the official npm registry record.
+export const JOSE_SOURCE_LOCK = Object.freeze({
+  schemaVersion: OAUTH_SCHEMA_VERSION,
+  packageName: "jose",
+  version: "6.2.3",
+  license: "MIT",
+  evidenceDate: "2026-06-23",
+  npmIntegrity: "sha512-YYVDInQKFJfR/xa3ojUTl8c2KoTwiL1R5Wg9YCydwH0x0B9grbzlg5HC7mMjCtUJjbQ/YnGEZIhI5tCgfTb4Hw==",
+  repository: "https://github.com/panva/jose",
+  officialUrl: "https://www.npmjs.com/package/jose/v/6.2.3",
+  exportsVerified: ["SignJWT", "jwtVerify", "errors"],
+  apiEvidence:
+    "jose@6.2.3 exports SignJWT (compact JWS sign builder), jwtVerify (signature + registered-claim validation with audience/issuer/currentDate), and the errors namespace used to classify rejections.",
+  refreshTrigger: "Any jose version change or SignJWT/jwtVerify signature/claim-validation API change.",
+});
+
+// Field names that carry raw secret material when they appear inline in a
+// model-facing payload. Mirrors the policy engine's leak detector so the token
+// path and the policy path agree on what "inlined raw secret" means.
+const RAW_SECRET_KEYS = new Set([
+  "value",
+  "plaintext",
+  "tokenvalue",
+  "token",
+  "accesstoken",
+  "refreshtoken",
+  "apikey",
+  "secret",
+  "clientsecret",
+  "password",
+  "privatekey",
+  "bearer",
+]);
+
+const SECRET_REF_KEYS = new Set([
+  "secretref",
+  "secretrefs",
+]);
+
+function isRawSecretKey(key) {
+  if (typeof key !== "string") return false;
+  const norm = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+  return RAW_SECRET_KEYS.has(norm);
+}
+
+function isSecretRefKey(key) {
+  if (typeof key !== "string") return false;
+  const norm = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+  return SECRET_REF_KEYS.has(norm);
+}
+
+// Keys that carry the model-visible context of a run. Secret material must never
+// be inlined into any of these — it must arrive out-of-band by reference only.
+const MODEL_CONTEXT_KEYS = ["prompt", "messages", "input", "context", "payload", "system", "tools", "instructions"];
+
+const TOKEN_STATUS = new Set(["active", "rotated", "revoked", "expired"]);
+
+export class OAuthTokenSecurityError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "OAuthTokenSecurityError";
+    this.code = code;
+  }
+}
+
+/**
+ * OAuth/link-token security authority.
+ *
+ * Stores OAuth tokens encrypted at rest in the orchestra sealed vault and binds every
+ * token to an owner, org, audience, and resource. `getOAuthTokens` will only return
+ * plaintext to a requester whose ownerId/orgId matches the token's owner and whose
+ * requested audience/resource matches the token binding — closing the cross-tenant
+ * scoped-read vulnerability. Tokens rotate/revoke on schedule and on scope change.
+ *
+ * The records are sealed-secret-shaped (secretId/keyVersionId/sealedPayload/metadata) so
+ * they persist additively into the existing `orchestra_secrets` table without adding a
+ * new control-plane table.
+ */
+export function createOAuthTokenAuthority(options = {}) {
+  const now = options.now ?? (() => new Date());
+  const vault = options.vault ?? createSealedSecretVault({ now, key: options.key });
+  const auditSink = options.auditSink;
+  const defaultRotationDays = Number.isFinite(options.rotationAfterDays) ? options.rotationAfterDays : 30;
+  const tokens = new Map();
+
+  function audit(event) {
+    const record = {
+      schemaVersion: OAUTH_SCHEMA_VERSION,
+      recordedAt: now().toISOString(),
+      ...event,
+    };
+    auditSink?.write?.(record);
+    return record;
+  }
+
+  function storeOAuthToken(input = {}) {
+    const tokenId = normalizeTokenId(input.tokenId);
+    const ownerId = requireString(input.ownerId, "ownerId");
+    const orgId = requireString(input.orgId, "orgId");
+    const audience = requireString(input.audience, "audience");
+    const resource = requireString(input.resource, "resource");
+    const value = requireString(input.value, "value");
+    const scopes = normalizeScopes(input.scopes);
+
+    // A token whose own metadata inlines a second raw secret is rejected: secrets
+    // never travel as plaintext inside other records.
+    const inlineLeaks = findInlinedSecretPaths({ metadata: input.metadata, audience, resource });
+    if (inlineLeaks.length > 0) {
+      audit({ eventType: "oauth.token.store_denied", outcome: "deny", tokenId, ownerId, orgId, reason: "inlined_secret_in_metadata" });
+      throw new OAuthTokenSecurityError("inlined_secret_in_metadata", `token metadata inlines raw secret material at ${inlineLeaks.join(", ")}`);
+    }
+
+    const aad = `${tokenId}:${ownerId}:${orgId}:${audience}:${resource}`;
+    const sealedPayload = vault.seal(value, { secretId: tokenId, aad });
+    const issuedAt = input.issuedAt ?? now().toISOString();
+    const record = {
+      schemaVersion: OAUTH_SCHEMA_VERSION,
+      secretId: tokenId,
+      tokenId,
+      name: input.name ?? tokenId,
+      ownerId,
+      orgId,
+      audience,
+      resource,
+      scopes,
+      keyVersionId: sealedPayload.keyVersionId,
+      sealedPayload,
+      status: "active",
+      issuedAt,
+      expiresAt: input.expiresAt,
+      rotateAfter: input.rotateAfter ?? rotationDeadline(issuedAt),
+      rotatedAt: undefined,
+      revokedAt: undefined,
+      revokedReason: undefined,
+      fingerprint: sha256(value),
+      metadata: { kind: "oauth_token", ...sanitizeMetadata(input.metadata) },
+    };
+    tokens.set(tokenId, record);
+    audit({ eventType: "oauth.token.sealed", outcome: "allow", tokenId, ownerId, orgId, audience, resource });
+    return publicTokenRecord(record);
+  }
+
+  /**
+   * Scoped read — the headline B4 fix.
+   *
+   * Requires the caller's ownerId/orgId AND a target audience. Only tokens whose owner
+   * AND org match the requester, whose audience/resource binding matches the request,
+   * and that are still active are returned in plaintext. A caller scoped to a different
+   * owner/org cannot read another tenant's tokens; an explicit cross-owner tokenId read
+   * is denied and audited rather than silently empty.
+   */
+  function getOAuthTokens(query = {}) {
+    const requesterOwnerId = requireString(query.requesterOwnerId, "requesterOwnerId");
+    const requesterOrgId = requireString(query.requesterOrgId, "requesterOrgId");
+    // Audience binding is mandatory: a token is only ever returned for the audience it
+    // was bound to, so the caller must name the audience it intends to use the token for.
+    const audience = requireString(query.audience, "audience");
+    const resource = query.resource === undefined ? undefined : requireString(query.resource, "resource");
+    const targetTokenId = query.tokenId === undefined ? undefined : normalizeTokenId(query.tokenId);
+    const asOf = query.now ? new Date(query.now) : now();
+    // Optional least-privilege filter: when the caller declares the scopes it needs, a
+    // token is only returned if it actually covers ALL of them. A token minted for a
+    // narrower scope is never handed to a caller that needs a broader one (fail-closed).
+    const requiredScopes = query.scopes === undefined ? undefined : (Array.isArray(query.scopes) ? query.scopes : [query.scopes]);
+
+    if (targetTokenId) {
+      const target = tokens.get(targetTokenId);
+      if (target && !ownerMatches(target, requesterOwnerId, requesterOrgId)) {
+        audit({ eventType: "oauth.token.read_denied", outcome: "deny", tokenId: targetTokenId, requesterOwnerId, requesterOrgId, reason: "owner_org_mismatch" });
+        throw new OAuthTokenSecurityError("cross_owner_read_denied", `requester ${requesterOwnerId}/${requesterOrgId} cannot read token owned by another owner/org`);
+      }
+    }
+
+    const results = [];
+    for (const record of tokens.values()) {
+      if (targetTokenId && record.tokenId !== targetTokenId) continue;
+      if (!ownerMatches(record, requesterOwnerId, requesterOrgId)) continue;
+      if (record.audience !== audience) continue;
+      if (resource !== undefined && record.resource !== resource) continue;
+      if (requiredScopes !== undefined) {
+        const recordScopes = new Set(record.scopes);
+        if (!requiredScopes.every((s) => recordScopes.has(s))) continue;
+      }
+      if (record.status !== "active") continue;
+      if (isExpired(record, asOf)) {
+        record.status = "expired";
+        audit({ eventType: "oauth.token.expired", outcome: "deny", tokenId: record.tokenId, ownerId: record.ownerId, orgId: record.orgId });
+        continue;
+      }
+      const aad = `${record.tokenId}:${record.ownerId}:${record.orgId}:${record.audience}:${record.resource}`;
+      const value = vault.open(record.sealedPayload, { aad });
+      if (record.keyVersionId !== vault.activeKeyVersionId) {
+        const resealed = vault.seal(value, { secretId: record.tokenId, aad });
+        record.keyVersionId = resealed.keyVersionId;
+        record.sealedPayload = resealed;
+        tokens.set(record.tokenId, record);
+        audit({ eventType: "oauth.token.resealed", outcome: "allow", tokenId: record.tokenId, ownerId: record.ownerId, orgId: record.orgId });
+      }
+      audit({ eventType: "oauth.token.read", outcome: "allow", tokenId: record.tokenId, ownerId: record.ownerId, orgId: record.orgId, audience, resource: record.resource });
+      results.push({
+        tokenId: record.tokenId,
+        ownerId: record.ownerId,
+        orgId: record.orgId,
+        audience: record.audience,
+        resource: record.resource,
+        scopes: [...record.scopes],
+        value,
+        expiresAt: record.expiresAt,
+      });
+    }
+    return results;
+  }
+
+  function rotateOAuthToken(input = {}) {
+    const tokenId = normalizeTokenId(input.tokenId);
+    const record = requireToken(tokenId);
+    assertRequesterOwnsToken(record, input, "rotate");
+    const value = requireString(input.value, "value");
+    const rotatedAt = input.rotatedAt ?? now().toISOString();
+    const aad = `${tokenId}:${record.ownerId}:${record.orgId}:${record.audience}:${record.resource}`;
+    const sealedPayload = vault.seal(value, { secretId: tokenId, aad });
+    const next = {
+      ...record,
+      keyVersionId: sealedPayload.keyVersionId,
+      sealedPayload,
+      status: "active",
+      rotatedAt,
+      rotateAfter: input.rotateAfter ?? rotationDeadline(rotatedAt),
+      revokedAt: undefined,
+      revokedReason: undefined,
+      fingerprint: sha256(value),
+    };
+    tokens.set(tokenId, next);
+    audit({ eventType: "oauth.token.rotated", outcome: "allow", tokenId, ownerId: record.ownerId, orgId: record.orgId });
+    return publicTokenRecord(next);
+  }
+
+  function revokeOAuthToken(input = {}) {
+    const tokenId = normalizeTokenId(input.tokenId);
+    const record = requireToken(tokenId);
+    assertRequesterOwnsToken(record, input, "revoke");
+    return revokeRecord(record, input);
+  }
+
+  // Trusted system revoke used by scope-change and lifecycle flows that have already
+  // established the owner/org context; never owner/org-gated against a caller.
+  function revokeRecord(record, input = {}) {
+    const next = {
+      ...record,
+      status: "revoked",
+      revokedAt: input.revokedAt ?? now().toISOString(),
+      revokedReason: input.reason ?? "revoked",
+    };
+    tokens.set(next.tokenId, next);
+    audit({ eventType: "oauth.token.revoked", outcome: "deny", tokenId: next.tokenId, ownerId: record.ownerId, orgId: record.orgId, reason: next.revokedReason });
+    return publicTokenRecord(next);
+  }
+
+  /**
+   * Revoke every active token for an owner/org whose scopes are no longer covered by the
+   * new scope grant. A scope downgrade must immediately invalidate tokens minted under the
+   * broader scope.
+   */
+  function revokeOnScopeChange(input = {}) {
+    const ownerId = requireString(input.ownerId, "ownerId");
+    const orgId = requireString(input.orgId, "orgId");
+    const newScopes = new Set(normalizeScopes(input.newScopes));
+    const revoked = [];
+    for (const record of tokens.values()) {
+      if (record.status !== "active") continue;
+      if (record.ownerId !== ownerId || record.orgId !== orgId) continue;
+      const dropped = record.scopes.filter((scope) => !newScopes.has(scope));
+      if (dropped.length === 0) continue;
+      revoked.push(revokeRecord(record, { reason: `scope_change:${dropped.join(",")}`, revokedAt: input.revokedAt }));
+    }
+    return revoked;
+  }
+
+  /**
+   * Schedule sweep: expire tokens past `expiresAt` and surface tokens past their rotation
+   * deadline so a scheduler can rotate them. Returns the actioned/flagged tokens.
+   */
+  function enforceLifecycle(input = {}) {
+    const asOf = input.now ? new Date(input.now) : now();
+    const expired = [];
+    const dueForRotation = [];
+    for (const record of tokens.values()) {
+      if (record.status !== "active") continue;
+      if (isExpired(record, asOf)) {
+        const next = { ...record, status: "expired", revokedAt: asOf.toISOString(), revokedReason: "expired" };
+        tokens.set(record.tokenId, next);
+        audit({ eventType: "oauth.token.expired", outcome: "deny", tokenId: record.tokenId, ownerId: record.ownerId, orgId: record.orgId });
+        expired.push(publicTokenRecord(next));
+        continue;
+      }
+      if (record.rotateAfter && Date.parse(record.rotateAfter) <= asOf.getTime()) {
+        dueForRotation.push(publicTokenRecord(record));
+      }
+    }
+    return { expired, dueForRotation };
+  }
+
+  function listTokenRecords() {
+    return [...tokens.values()].map(publicTokenRecord);
+  }
+
+  function rotationDeadline(fromIso) {
+    const base = Date.parse(fromIso);
+    const ms = (Number.isFinite(base) ? base : now().getTime()) + defaultRotationDays * 24 * 60 * 60 * 1000;
+    return new Date(ms).toISOString();
+  }
+
+  function requireToken(tokenId) {
+    const record = tokens.get(tokenId);
+    if (!record) throw new OAuthTokenSecurityError("unknown_token", `oauth token ${tokenId} does not exist`);
+    return record;
+  }
+
+  // Fail-closed write guard: a mutation (rotate/revoke) must carry the requester's
+  // ownerId/orgId, and they must match the token's owner. This stops a caller that knows
+  // (or guesses) another tenant's tokenId from poisoning it via rotate or DoS-ing it via
+  // revoke — the write boundary is enforced just like the read boundary.
+  function assertRequesterOwnsToken(record, input, action) {
+    const requesterOwnerId = requireString(input.requesterOwnerId, "requesterOwnerId");
+    const requesterOrgId = requireString(input.requesterOrgId, "requesterOrgId");
+    if (!ownerMatches(record, requesterOwnerId, requesterOrgId)) {
+      audit({ eventType: `oauth.token.${action}_denied`, outcome: "deny", tokenId: record.tokenId, requesterOwnerId, requesterOrgId, reason: "owner_org_mismatch" });
+      throw new OAuthTokenSecurityError("cross_owner_write_denied", `requester ${requesterOwnerId}/${requesterOrgId} cannot ${action} a token owned by another owner/org`);
+    }
+  }
+
+  return {
+    schemaVersion: OAUTH_SCHEMA_VERSION,
+    storeOAuthToken,
+    getOAuthTokens,
+    rotateOAuthToken,
+    revokeOAuthToken,
+    revokeOnScopeChange,
+    enforceLifecycle,
+    listTokenRecords,
+    get vault() {
+      return vault;
+    },
+  };
+}
+
+/**
+ * Sign a link token (compact JWS) with jose. Audience binding is mandatory — a link token
+ * is only ever valid for the resource/audience it is minted for.
+ */
+export async function signLinkToken(claims = {}, options = {}) {
+  const alg = options.algorithm ?? "HS256";
+  assertAllowedAlg(alg);
+  const audience = options.audience ?? claims.aud;
+  if (!audience) throw new OAuthTokenSecurityError("missing_audience", "link token must be bound to an audience");
+  const issuer = options.issuer ?? claims.iss;
+  const subject = options.subject ?? claims.sub;
+  const key = await resolveKeyMaterial(options.key ?? options.secret, alg, "sign");
+
+  const builder = new SignJWT(stripReservedClaims(claims))
+    .setProtectedHeader({ alg, typ: "JWT" })
+    .setAudience(audience);
+  if (issuer) builder.setIssuer(issuer);
+  if (subject) builder.setSubject(subject);
+  if (options.jti) builder.setJti(options.jti);
+
+  const issuedAt = epochSeconds(options.issuedAt ?? options.now?.() ?? new Date());
+  builder.setIssuedAt(issuedAt);
+  const expiresAt = options.expiresAt ?? options.expiresInSeconds;
+  if (expiresAt !== undefined) {
+    builder.setExpirationTime(typeof expiresAt === "number" && expiresAt < 1_000_000_000 ? issuedAt + expiresAt : epochSeconds(expiresAt));
+  }
+  return builder.sign(key);
+}
+
+/**
+ * Verify a link token with jose. Rejects missing/invalid signatures, `alg:none`, expired
+ * tokens, and audience/issuer mismatches. Returns the verified payload on success.
+ */
+export async function verifyLinkToken(token, options = {}) {
+  if (typeof token !== "string" || token.length === 0) {
+    throw new OAuthTokenSecurityError("malformed_token", "link token must be a non-empty compact JWS string");
+  }
+  const algorithms = normalizeAlgList(options.algorithms);
+  if (!options.audience) {
+    throw new OAuthTokenSecurityError("missing_audience", "link token verification requires an expected audience");
+  }
+  // A single alg is enough to pick symmetric vs asymmetric key handling.
+  const key = await resolveKeyMaterial(options.key ?? options.secret, algorithms[0], "verify");
+  try {
+    const { payload, protectedHeader } = await jwtVerify(token, key, {
+      algorithms,
+      audience: options.audience,
+      issuer: options.issuer,
+      subject: options.subject,
+      maxTokenAge: options.maxTokenAge,
+      clockTolerance: options.clockTolerance ?? 0,
+      requiredClaims: options.requiredClaims,
+      currentDate: options.now ? new Date(options.now()) : undefined,
+    });
+    return { valid: true, payload, protectedHeader };
+  } catch (error) {
+    throw mapJoseError(error);
+  }
+}
+
+/**
+ * Assert that a run's model-facing context contains no inlined raw secret material or raw
+ * secret references. Secret material must arrive out-of-band by `{ secretId }` reference
+ * only. Fails closed (throws) by default; pass `{ throwOnViolation: false }` to inspect.
+ */
+export function assertSecretContextIsolation(run = {}, options = {}) {
+  const throwOnViolation = options.throwOnViolation !== false;
+  const violations = [];
+  for (const key of MODEL_CONTEXT_KEYS) {
+    if (run[key] === undefined) continue;
+    for (const path of findInlinedSecretPaths(run[key], `${key}`)) {
+      violations.push({ path, kind: "inlined_secret_value" });
+    }
+    for (const path of findInlinedSecretRefPaths(run[key], `${key}`)) {
+      violations.push({ path, kind: "inlined_secret_ref" });
+    }
+    for (const path of findTokenShapedStrings(run[key], `${key}`)) {
+      violations.push({ path, kind: "token_shaped_string" });
+    }
+  }
+  const ok = violations.length === 0;
+  if (!ok && throwOnViolation) {
+    throw new OAuthTokenSecurityError(
+      "inlined_secret_in_context",
+      `run model context inlines secret material: ${violations.map((violation) => `${violation.path} (${violation.kind})`).join(", ")}`,
+    );
+  }
+  return { ok, violations };
+}
+
+/**
+ * Resolve a run's secret references out-of-band, isolated from the model context.
+ *
+ * Enforces context isolation first (fail closed), then resolves each `{ secretId }` ref via
+ * the provided async/sync resolver into a separate `resolvedSecrets` channel that is NOT
+ * merged back into the model-visible context. Refs that carry inlined raw values are rejected.
+ */
+export async function resolveSecretRefsForRun(run = {}, resolver, options = {}) {
+  if (typeof resolver !== "function") {
+    throw new OAuthTokenSecurityError("missing_resolver", "secret ref resolution requires a resolver function");
+  }
+  assertSecretContextIsolation(run, options);
+  const refs = collectSecretRefs(run.secretRefs ?? run.secret_refs ?? run.secretRef ?? run.secret_ref ?? []);
+  const resolvedSecrets = {};
+  for (const ref of refs) {
+    const hasInlined = Object.keys(ref).some((k) => isRawSecretKey(k) && ref[k] !== undefined && ref[k] !== null && ref[k] !== "");
+    if (hasInlined) {
+      throw new OAuthTokenSecurityError("inlined_secret_ref", `secret ref ${ref.secretId ?? "<unknown>"} inlines a raw value; pass a reference only`);
+    }
+    if (!ref.secretId || typeof ref.secretId !== "string") {
+      throw new OAuthTokenSecurityError("invalid_secret_ref", "secret ref requires a string secretId");
+    }
+    resolvedSecrets[ref.secretId] = await resolver(ref);
+  }
+  return { modelContext: stripSecretChannel(run), resolvedSecrets };
+}
+
+// ---------------------------------------------------------------------------
+// internals
+// ---------------------------------------------------------------------------
+
+function ownerMatches(record, ownerId, orgId) {
+  return safeEqual(record.ownerId, ownerId) && safeEqual(record.orgId, orgId);
+}
+
+function safeEqual(a, b) {
+  if (typeof a !== "string" || typeof b !== "string") return false;
+  const bufferA = Buffer.from(a, "utf8");
+  const bufferB = Buffer.from(b, "utf8");
+  if (bufferA.length !== bufferB.length) return false;
+  return timingSafeEqual(bufferA, bufferB);
+}
+
+function isExpired(record, asOf) {
+  if (!record.expiresAt) return false;
+  const expiry = Date.parse(record.expiresAt);
+  return Number.isFinite(expiry) && expiry <= asOf.getTime();
+}
+
+function publicTokenRecord(record) {
+  const { sealedPayload, ...rest } = record;
+  return {
+    ...structuredClone(rest),
+    sealedPayload: {
+      schemaVersion: sealedPayload.schemaVersion,
+      algorithm: sealedPayload.algorithm,
+      keyVersionId: sealedPayload.keyVersionId,
+      iv: sealedPayload.iv,
+      tag: sealedPayload.tag,
+      aadHash: sealedPayload.aadHash,
+      ciphertext: "[sealed]",
+    },
+  };
+}
+
+function findInlinedSecretPaths(value, path = "$") {
+  if (Array.isArray(value)) return value.flatMap((child, index) => findInlinedSecretPaths(child, `${path}[${index}]`));
+  if (value === null || typeof value !== "object") return [];
+  const matches = [];
+  for (const [key, child] of Object.entries(value)) {
+    const childPath = `${path}.${key}`;
+    if (isRawSecretKey(key) && child !== undefined && child !== null && child !== "") {
+      matches.push(childPath);
+      continue;
+    }
+    matches.push(...findInlinedSecretPaths(child, childPath));
+  }
+  return matches;
+}
+
+function findInlinedSecretRefPaths(value, path = "$") {
+  if (Array.isArray(value)) return value.flatMap((child, index) => findInlinedSecretRefPaths(child, `${path}[${index}]`));
+  if (value === null || typeof value !== "object") return [];
+  const matches = [];
+  for (const [key, child] of Object.entries(value)) {
+    const childPath = `${path}.${key}`;
+    if (isSecretRefKey(key)) {
+      for (const ref of asRefArray(child)) {
+        if (ref && typeof ref === "object") {
+          const hasInlinedSecret = Object.keys(ref).some((k) => isRawSecretKey(k) && ref[k] !== undefined && ref[k] !== null && ref[k] !== "");
+          if (hasInlinedSecret) {
+            matches.push(childPath);
+            break;
+          }
+        }
+      }
+      continue;
+    }
+    matches.push(...findInlinedSecretRefPaths(child, childPath));
+  }
+  return matches;
+}
+
+function findTokenShapedStrings(value, path = "$") {
+  if (typeof value === "string") return isTokenShaped(value) ? [path] : [];
+  if (Array.isArray(value)) return value.flatMap((child, index) => findTokenShapedStrings(child, `${path}[${index}]`));
+  if (value === null || typeof value !== "object") return [];
+  return Object.entries(value).flatMap(([key, child]) => findTokenShapedStrings(child, `${path}.${key}`));
+}
+
+// Detect bearer tokens and JWT-shaped strings inlined into model context.
+function isTokenShaped(value) {
+  if (/\bBearer\s+[A-Za-z0-9._~+/=-]{16,}/.test(value)) return true;
+  if (/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/.test(value)) return true;
+
+  // Try decoding base64 if it looks like base64
+  if (value.length >= 24 && /^[A-Za-z0-9+/=]+$/.test(value)) {
+    try {
+      const decoded = Buffer.from(value, "base64").toString("utf8");
+      if (/\bBearer\s+[A-Za-z0-9._~+/=-]{16,}/.test(decoded) || /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/.test(decoded)) {
+        return true;
+      }
+    } catch {}
+  }
+
+  // Try decoding hex if it looks like hex
+  if (value.length >= 32 && /^[a-fA-F0-9]+$/.test(value)) {
+    try {
+      const decoded = Buffer.from(value, "hex").toString("utf8");
+      if (/\bBearer\s+[A-Za-z0-9._~+/=-]{16,}/.test(decoded) || /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/.test(decoded)) {
+        return true;
+      }
+    } catch {}
+  }
+
+  // Try decoding URL encoding
+  if (value.includes("%")) {
+    try {
+      const decoded = decodeURIComponent(value);
+      if (decoded !== value && (/\bBearer\s+[A-Za-z0-9._~+/=-]{16,}/.test(decoded) || /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/.test(decoded))) {
+        return true;
+      }
+    } catch {}
+  }
+
+  return false;
+}
+
+function collectSecretRefs(refs) {
+  return asRefArray(refs).filter((ref) => ref && typeof ref === "object");
+}
+
+function asRefArray(value) {
+  if (Array.isArray(value)) return value;
+  if (value && typeof value === "object") return [value];
+  return [];
+}
+
+function stripSecretChannel(run) {
+  if (!run || typeof run !== "object") return run;
+  const result = {};
+  for (const [key, val] of Object.entries(run)) {
+    if (!isSecretRefKey(key)) {
+      result[key] = val;
+    }
+  }
+  return result;
+}
+
+function normalizeScopes(value) {
+  return [
+    ...new Set(
+      (Array.isArray(value) ? value : [])
+        .filter((scope) => typeof scope === "string" && /^[a-z][a-z0-9:*_.-]*$/.test(scope)),
+    ),
+  ].sort();
+}
+
+function sanitizeMetadata(metadata) {
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) return {};
+  return Object.fromEntries(
+    Object.entries(metadata).filter(([key]) => !isRawSecretKey(key) && !isSecretRefKey(key)),
+  );
+}
+
+function normalizeTokenId(value) {
+  const raw = typeof value === "string" && value.length > 0 ? value : `oauth_${randomBytes(8).toString("hex")}`;
+  const body = raw
+    .toLowerCase()
+    .replace(/^oauth_/, "")
+    .replace(/[^a-z0-9_-]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 72);
+  return `oauth_${body || randomBytes(6).toString("hex")}`;
+}
+
+function assertAllowedAlg(alg) {
+  if (typeof alg !== "string" || !ALLOWED_LINK_TOKEN_ALG_SET.has(alg)) {
+    throw new OAuthTokenSecurityError("unsupported_alg", `link token algorithm ${String(alg)} is not allowed`);
+  }
+}
+
+function normalizeAlgList(value) {
+  const list = Array.isArray(value) && value.length > 0 ? value : ["HS256"];
+  for (const alg of list) assertAllowedAlg(alg);
+  return [...list];
+}
+
+async function resolveKeyMaterial(key, alg, _mode) {
+  if (key === undefined || key === null) {
+    throw new OAuthTokenSecurityError("missing_key", "link token signing/verification requires a key or secret");
+  }
+  if (typeof alg === "string" && alg.startsWith(HMAC_ALG_PREFIX)) {
+    if (typeof key === "string") return createHash("sha256").update(key).digest();
+    if (key instanceof Uint8Array) return key;
+    throw new OAuthTokenSecurityError("invalid_symmetric_key", `${alg} requires a string or byte secret`);
+  }
+  // Asymmetric: jose accepts CryptoKey / KeyObject / JWK directly.
+  return key;
+}
+
+function mapJoseError(error) {
+  if (error instanceof OAuthTokenSecurityError) return error;
+  const code = error?.code;
+  if (error instanceof joseErrors.JWSSignatureVerificationFailed || code === "ERR_JWS_SIGNATURE_VERIFICATION_FAILED") {
+    return new OAuthTokenSecurityError("invalid_signature", "link token signature verification failed");
+  }
+  if (error instanceof joseErrors.JWTExpired || code === "ERR_JWT_EXPIRED") {
+    return new OAuthTokenSecurityError("token_expired", "link token is expired");
+  }
+  if (error instanceof joseErrors.JWTClaimValidationFailed || code === "ERR_JWT_CLAIM_VALIDATION_FAILED") {
+    return new OAuthTokenSecurityError("claim_validation_failed", error.message ?? "link token claim validation failed");
+  }
+  if (
+    error instanceof joseErrors.JWSInvalid ||
+    error instanceof joseErrors.JWTInvalid ||
+    error instanceof joseErrors.JOSEAlgNotAllowed ||
+    code === "ERR_JWS_INVALID" ||
+    code === "ERR_JWT_INVALID" ||
+    code === "ERR_JOSE_ALG_NOT_ALLOWED"
+  ) {
+    return new OAuthTokenSecurityError("malformed_token", error.message ?? "link token is malformed or uses a disallowed algorithm");
+  }
+  return new OAuthTokenSecurityError("link_token_verification_failed", error?.message ?? "link token verification failed");
+}
+
+function stripReservedClaims(claims) {
+  if (!claims || typeof claims !== "object") return {};
+  const { aud, iss, sub, iat, exp, nbf, jti, ...rest } = claims;
+  return rest;
+}
+
+function epochSeconds(value) {
+  if (typeof value === "number") return value > 1_000_000_000_000 ? Math.floor(value / 1000) : Math.floor(value);
+  const ms = value instanceof Date ? value.getTime() : Date.parse(value);
+  if (!Number.isFinite(ms)) throw new OAuthTokenSecurityError("invalid_time", "expected a Date, epoch, or ISO timestamp");
+  return Math.floor(ms / 1000);
+}
+
+function requireString(value, field) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new OAuthTokenSecurityError("invalid_input", `${field} is required`);
+  }
+  return value;
+}
+
+function sha256(value) {
+  return `sha256:${createHash("sha256").update(String(value)).digest("hex")}`;
+}