@opengeni/contracts 0.19.0 → 0.19.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/contracts",
-  "version": "0.19.0",
+  "version": "0.19.4",
   "description": "Shared zod schemas and wire-contract types for the OpenGeni API.",
   "license": "Apache-2.0",
   "repository": {

package/src/index.ts

@@ -478,8 +478,10 @@ export type ErrorCode = z.infer<typeof ErrorCode>;
 
 export const ErrorEnvelope = z.object({
   error: z.object({
+    status: z.number().int().min(400).max(599),
     code: ErrorCode,
     message: z.string(),
+    retryable: z.boolean(),
     requestId: z.string().optional(),
     details: z.record(z.string(), z.unknown()).optional(),
   }),
@@ -2176,11 +2178,22 @@ export type ConnectionCredentialsPort = {
 
 export type GitHubInstallationSummary = {
   installationId: number;
+  accountId: number;
   accountLogin: string | null;
   accountType: string | null;
   suspended: boolean;
 };
 
+export type GitHubInstallationAuthorityKind = "personal_owner" | "organization_owner";
+
+export interface GitHubInstallationBindingProof {
+  actorId: number;
+  actorLogin: string;
+  authorityKind: GitHubInstallationAuthorityKind;
+  installation: GitHubInstallationSummary;
+  repositories: GitHubRepository[];
+}
+
 export type GitHubRepositoryPermissions = {
   admin: boolean;
   maintain: boolean;
@@ -2198,6 +2211,18 @@ export type GitHubUserInstallationAccess = GitHubInstallationSummary & {
 };
 
 export type GitHubAppApiPort = {
+  /**
+   * Exchange one fresh GitHub user-authorization code and prove current
+   * installation authority. Implementations must accept only exact personal
+   * ownership or active organization ownership; installation visibility,
+   * repository permission bits, and App Manager metadata are not authority.
+   * Organization ownership must be revalidated after repository discovery,
+   * immediately before returning the proof used by the durable bind.
+   */
+  authorizeInstallationBinding?: (input: {
+    code: string;
+    installationId: number;
+  }) => Promise<GitHubInstallationBindingProof>;
   authorizeUser?: (input: { code: string }) => Promise<GitHubUserInstallationAccess[]>;
   verifyInstallationAccessForUser?: (input: {
     code: string;
@@ -2491,6 +2516,37 @@ export type KnowledgeSourceKind = z.infer<typeof KnowledgeSourceKind>;
 export const DocumentSearchMode = z.enum(["hybrid", "vector", "keyword"]);
 export type DocumentSearchMode = z.infer<typeof DocumentSearchMode>;
 
+// 'workspace' documents are readable by anyone with workspace access;
+// 'private' documents are readable only by the grant subject that created them.
+export const DocumentVisibility = z.enum(["workspace", "private"]);
+export type DocumentVisibility = z.infer<typeof DocumentVisibility>;
+
+// Knowledge-drop auto-curation lifecycle. 'none' = ordinary caller-described add
+// (never auto-curated). 'pending' = dropped, curation runs during indexing.
+// 'suggested' = curated but the base move was NOT applied (low confidence or
+// conflict) — the suggestion lives in Document.curation. 'auto_filed' = curated
+// and moved into the suggested base. 'failed' = curation errored (fail-soft;
+// the document still indexes and stays searchable).
+export const DocumentCurationStatus = z.enum([
+  "none",
+  "pending",
+  "suggested",
+  "auto_filed",
+  "failed",
+]);
+export type DocumentCurationStatus = z.infer<typeof DocumentCurationStatus>;
+
+// Curator audit blob persisted on the document.
+export const DocumentCuration = z.object({
+  suggestedBaseId: z.string().uuid().nullable(),
+  suggestedBaseName: z.string().nullable(),
+  confidence: z.number().min(0).max(1),
+  reason: z.string().nullable(),
+  originalTitle: z.string().nullable(),
+  model: z.string().nullable(),
+});
+export type DocumentCuration = z.infer<typeof DocumentCuration>;
+
 export const DocumentBase = z.object({
   id: z.string().uuid(),
   workspaceId: z.string().uuid(),
@@ -2520,6 +2576,13 @@ export const Document = z.object({
   sourceUpdatedAt: z.string().nullable(),
   sourceVersion: z.string().nullable(),
   aclTags: z.array(z.string()),
+  visibility: DocumentVisibility,
+  createdBy: z.string().nullable(),
+  agentAccess: z.boolean(),
+  summary: z.string().nullable(),
+  topics: z.array(z.string()),
+  curationStatus: DocumentCurationStatus,
+  curation: DocumentCuration.nullable(),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
@@ -2569,9 +2632,37 @@ export const AddDocumentRequest = z.object({
   sourceUpdatedAt: z.string().datetime({ offset: true }).optional(),
   sourceVersion: z.string().min(1).optional(),
   aclTags: z.array(z.string().min(1)).optional(),
+  visibility: DocumentVisibility.optional(),
+  agentAccess: z.boolean().optional(),
 });
 export type AddDocumentRequest = z.infer<typeof AddDocumentRequest>;
 
+// A knowledge drop: raw text or an already-uploaded file, with no required
+// metadata. The server files it into the workspace Default base. When a
+// curation provider is enabled, it may name, summarize, categorize, and
+// (confidence permitting) move the document; provider=none leaves caller
+// metadata and Default placement unchanged.
+export const CreateKnowledgeDropRequest = z
+  .object({
+    text: z.string().min(1).max(2_000_000).optional(),
+    fileId: z.string().uuid().optional(),
+    filename: z.string().min(1).optional(),
+    title: z.string().min(1).optional(),
+    visibility: DocumentVisibility.optional(),
+    agentAccess: z.boolean().optional(),
+  })
+  .refine((value) => (value.text === undefined) !== (value.fileId === undefined), {
+    message: "provide exactly one of text or fileId",
+  });
+export type CreateKnowledgeDropRequest = z.infer<typeof CreateKnowledgeDropRequest>;
+
+// Move a document (and its indexed chunks) to another base. With no explicit
+// targetBaseId, applies the document's stored curation suggestion.
+export const MoveDocumentRequest = z.object({
+  targetBaseId: z.string().uuid().optional(),
+});
+export type MoveDocumentRequest = z.infer<typeof MoveDocumentRequest>;
+
 export const DocumentSearchRequest = z.object({
   query: z.string().min(1),
   baseIds: z.array(z.string().uuid()).optional(),
@@ -3134,6 +3225,29 @@ export const UpdateSessionRequest = z.object({
 });
 export type UpdateSessionRequest = z.infer<typeof UpdateSessionRequest>;
 
+/**
+ * Replace an existing session's durable tool policy, or explicitly opt back in
+ * to the current workspace defaults. The mode-less explicit shape is retained
+ * for compatibility with clients released before workspace-default adoption
+ * was supported.
+ */
+export const UpdateSessionToolPolicyRequest = z.union([
+  z
+    .object({
+      mode: z.literal("workspace_default"),
+      expectedVersion: z.number().int().positive(),
+    })
+    .strict(),
+  z
+    .object({
+      mode: z.literal("explicit").optional(),
+      tools: z.array(ToolRef).max(64),
+      expectedVersion: z.number().int().positive(),
+    })
+    .strict(),
+]);
+export type UpdateSessionToolPolicyRequest = z.infer<typeof UpdateSessionToolPolicyRequest>;
+
 /**
  * A member's personal pin preference for a session. `expectedVersion` is
  * optional: ordinary pin/unpin actions are idempotent last-write-wins, while a
@@ -3275,6 +3389,7 @@ export const SessionAuthorizationOperation = z.enum([
   "session.human_input.write",
   "session.title.write",
   "session.mcp.approval_policy.write",
+  "session.tool_policy.write",
   "session.goal.read",
   "session.goal.write",
   "session.child.create",
@@ -3569,6 +3684,8 @@ export const NewSessionDraft = z.object({
   text: z.string(),
   resources: z.array(ResourceRef),
   tools: z.array(ToolRef),
+  /** False means the workspace-default MCP policy is still inherited. */
+  toolsProvided: z.boolean().default(false),
   model: z.string().min(1),
   reasoningEffort: ReasoningEffort,
   options: NewSessionDraftOptions,
@@ -3580,6 +3697,7 @@ export const SaveNewSessionDraftRequest = NewSessionDraft.pick({
   text: true,
   resources: true,
   tools: true,
+  toolsProvided: true,
   model: true,
   reasoningEffort: true,
   options: true,
@@ -4853,6 +4971,10 @@ export const Session = z.object({
   // Origin of the persisted tool allow-list. Optional for rolling client
   // compatibility; current servers emit it and legacy rows map to `legacy`.
   toolPolicy: SessionToolPolicy.optional(),
+  // Optimistic-concurrency fence for durable policy mutations. Optional for
+  // older clients/fixtures; current servers always emit the authoritative
+  // value.
+  toolPolicyVersion: z.number().int().positive().optional(),
   // Secret-safe current resolution, computed at an API/read or execution
   // boundary from IDs only. Optional because internal DB readers need not load
   // the workspace runtime registry.
@@ -5103,6 +5225,7 @@ export const SessionEventType = z.enum([
   "terminal.pty.exited", // PTY session ended (exitCode/reason)
   "session.title_set",
   "session.mcp.approval_policy.updated",
+  "session.tool_policy.updated",
   // Multi-account Codex (P1): the account a session's turn runs on changed
   // (manual switch in P1; failover/rotation in P3 reuse the same event). Drives
   // the in-session "Running on:" indicator's live flip.
@@ -5268,6 +5391,7 @@ export const SESSION_EVENT_SEMANTIC_CLASS_TYPES = {
     "session.queue.changed",
     "session.queue.prompt.cancelled",
     "session.mcp.approval_policy.updated",
+    "session.tool_policy.updated",
   ],
   terminal: [
     "turn.completed",
@@ -7468,10 +7592,18 @@ export type GitHubRepository = z.infer<typeof GitHubRepository>;
 export const GitHubRepositoryScope = z.enum(["all", "selected"]);
 export type GitHubRepositoryScope = z.infer<typeof GitHubRepositoryScope>;
 
+export const GitHubBindingStatus = z.enum(["disabled", "unbound", "bound"]);
+export type GitHubBindingStatus = z.infer<typeof GitHubBindingStatus>;
+
+export const GitHubInstallationLifecycle = z.enum(["active", "suspended", "deleted", "unverified"]);
+export type GitHubInstallationLifecycle = z.infer<typeof GitHubInstallationLifecycle>;
+
 export const GitHubInstallationBinding = z.object({
   installationId: z.number().int().positive(),
+  githubAccountId: z.number().int().positive().nullable(),
   accountLogin: z.string().nullable(),
   accountType: z.string().nullable(),
+  lifecycle: GitHubInstallationLifecycle,
   repositoryScope: GitHubRepositoryScope,
   repositoryCount: z.number().int().nonnegative(),
   createdAt: z.string(),
@@ -7481,6 +7613,7 @@ export type GitHubInstallationBinding = z.infer<typeof GitHubInstallationBinding
 
 export const GitHubAppInfo = z.object({
   configured: z.boolean(),
+  status: GitHubBindingStatus,
   appId: z.string().nullable(),
   clientId: z.string().nullable(),
   appSlug: z.string().nullable(),
@@ -8473,6 +8606,8 @@ export type WorkspaceModelCatalogResponse = z.infer<typeof WorkspaceModelCatalog
  */
 export const OPENGENI_API_CONTRACT_REVISION = "2026-07-turn-instructions-v1" as const;
 export const OPENGENI_API_CONTRACT_HEADER = "x-opengeni-api-contract" as const;
+/** Bounded request/response identifier shared by browser, ingress, and API diagnostics. */
+export const OPENGENI_CORRELATION_HEADER = "x-opengeni-correlation-id" as const;
 
 export const ClientConfig = /* @__PURE__ */ defineModelContractSchema(() =>
   z.object({
@@ -8594,3 +8729,4 @@ export function evaluateWorkspaceModelPolicy(
 }
 
 export * from "./codex-fleet-policy";
+export * from "./secret-redaction";

package/src/secret-redaction.ts

@@ -0,0 +1,364 @@
+const MIN_REDACTABLE_VALUE_LENGTH = 6;
+const REDACTED = "[redacted]";
+const MAX_REDACTION_DEPTH = 64;
+const CYCLE_MARKER = "[OpenGeni omitted cyclic value during secret redaction]";
+const DEPTH_MARKER = "[OpenGeni omitted value beyond secret-redaction depth]";
+
+export type SecretForRedaction = {
+  name: string;
+  value: string;
+};
+
+type PreparedSecret = {
+  marker: string;
+  value: string;
+};
+
+const SENSITIVE_FIELD_NAMES = new Set([
+  "authorization",
+  "proxyauthorization",
+  "cookie",
+  "setcookie",
+  "accesstoken",
+  "refreshtoken",
+  "idtoken",
+  "apikey",
+  "secret",
+  "clientsecret",
+  "password",
+  "passwd",
+  "privatekey",
+  "credential",
+  "credentials",
+  "credentialencrypted",
+  "encryptedcredential",
+  "headersencrypted",
+  "encryptedpkceverifier",
+  "codeverifier",
+  "signingkey",
+]);
+
+const CREDENTIAL_HEADER_PATTERNS = [
+  /^(?:proxy-)?authorization$/i,
+  /^(?:set-)?cookie$/i,
+  /^(?:x[-_])?api[-_]?key$/i,
+  /^(?:x[-_])?(?:access|refresh|id)[-_]?token$/i,
+  /^(?:x[-_])?(?:auth|session)[-_]?(?:token|key|secret)$/i,
+  /^(?:x[-_])?(?:client|app|consumer)[-_]?secret$/i,
+  /^x-opengeni-access-key$/i,
+] as const;
+
+const SECRET_KEY_SOURCE =
+  "(?:proxy[-_ ]?authorization|authorization|set[-_ ]?cookie|cookie|access[-_ ]?token|refresh[-_ ]?token|id[-_ ]?token|api[-_ ]?key|client[-_ ]?secret|secret|password|passwd|private[-_ ]?key|credential(?:s|[-_ ]?encrypted)?|encrypted[-_ ]?credential|encrypted[-_ ]?pkce[-_ ]?verifier|code[-_ ]?verifier|signing[-_ ]?key)";
+const UNQUOTED_SECRET_KEY_SOURCE =
+  "(?:access[-_ ]?token|refresh[-_ ]?token|id[-_ ]?token|api[-_ ]?key|client[-_ ]?secret|secret|password|passwd|private[-_ ]?key|credential(?:s|[-_ ]?encrypted)?|encrypted[-_ ]?credential|encrypted[-_ ]?pkce[-_ ]?verifier|code[-_ ]?verifier|signing[-_ ]?key)";
+
+const AUTHORIZATION_HEADER_PATTERN =
+  /(\b(?:proxy-)?authorization[^\S\r\n]*:[^\S\r\n]*)([^\r\n'"`]+)/gi;
+const COOKIE_HEADER_PATTERN = /(\b(?:set-cookie|cookie)\s*:\s*)([^\r\n'"`]+)/gi;
+const API_KEY_HEADER_PATTERN = /(\b(?:x[-_])?api[-_]?key[^\S\r\n]*:[^\S\r\n]*)([^\r\n'"`]+)/gi;
+const CURL_USER_PATTERN = /((?:^|\s)(?:-u|--user)(?:=|\s+))(?:("[^"]*")|('[^']*')|([^\s]+))/gm;
+const URL_USERINFO_PATTERN = /(https?:\/\/)[^\s/@]+@/gi;
+const SIGNED_QUERY_PATTERN = new RegExp(
+  `([?&](?:sig|signature|x-amz-signature|x-amz-credential|x-amz-security-token|x-goog-signature|x-goog-credential|access_token|refresh_token|token)=)([^&#\\s'"<>]+)`,
+  "gi",
+);
+const QUOTED_SECRET_ASSIGNMENT_PATTERN = new RegExp(
+  `((?:["']${SECRET_KEY_SOURCE}["']|\\b${SECRET_KEY_SOURCE})\\s*[:=]\\s*)(["'])(.*?)\\2`,
+  "gi",
+);
+const UNQUOTED_SECRET_ASSIGNMENT_PATTERN = new RegExp(
+  `((?:\\b${UNQUOTED_SECRET_KEY_SOURCE})\\s*[:=]\\s*)([^\\s,;}&]+)`,
+  "gi",
+);
+const SECRET_ENV_ASSIGNMENT_PATTERN =
+  /((?:^|[\s;])(?:export\s+)?[A-Za-z_][A-Za-z0-9_]*(?:TOKEN|SECRET|PASSWORD|PASSWD|API_KEY|PRIVATE_KEY|CREDENTIAL|AUTHORIZATION|COOKIE)[A-Za-z0-9_]*\s*=\s*)(?:("[^"]*")|('[^']*')|([^\s;]+))/gim;
+
+const PROVIDER_TOKEN_PATTERNS = [
+  /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g,
+  /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g,
+  /\bglpat-[A-Za-z0-9_-]{20,}\b/g,
+  /\bsk-[A-Za-z0-9_-]{20,}\b/g,
+  /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g,
+  /\bAIza[0-9A-Za-z_-]{30,}\b/g,
+  /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g,
+  /\bogd_[A-Za-z0-9._~-]{10,}\b/g,
+  /\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\b/g,
+] as const;
+
+/**
+ * Returns true only for fields whose value is itself credential material.
+ * Container fields such as `headers` and URL fields are intentionally not
+ * included: their nested/value sanitizers retain useful names, hosts, paths,
+ * and non-sensitive query parameters.
+ */
+export function isSensitiveFieldName(name: string): boolean {
+  return SENSITIVE_FIELD_NAMES.has(normalizeFieldName(name));
+}
+
+/**
+ * Return true only for header names whose values are credential material.
+ * Ordinary protocol metadata (`content-type`, `accept`, `user-agent`, and
+ * pagination/signature headers outside this allowlist) must remain intact.
+ */
+export function isCredentialHeaderName(name: string): boolean {
+  return CREDENTIAL_HEADER_PATTERNS.some((pattern) => pattern.test(name));
+}
+
+/**
+ * Redact only exact known-secret provenance from a structured object key.
+ * Generic field/header heuristics intentionally do not run here: a key is
+ * metadata unless the caller has proved that its bytes are secret material.
+ */
+export function redactSensitiveKey(
+  key: string,
+  knownSecrets: readonly SecretForRedaction[] = [],
+): string {
+  return replacePreparedSecrets(key, prepareSecrets(knownSecrets));
+}
+
+/**
+ * Redact known secret provenance and common credential-bearing text shapes.
+ * This is deliberately a conservative safety boundary, not a promise of
+ * general-purpose DLP. It never includes a matched value in a marker or error.
+ */
+export function redactSensitiveText(
+  text: string,
+  knownSecrets: readonly SecretForRedaction[] = [],
+): string {
+  let redacted = replacePreparedSecrets(text, prepareSecrets(knownSecrets));
+
+  redacted = redacted.replace(
+    AUTHORIZATION_HEADER_PATTERN,
+    (match, prefix: string, rawValue: string) => {
+      const value = rawValue.trimEnd();
+      const trailingWhitespace = rawValue.slice(value.length);
+      const schemeMatch = value.match(/^([A-Za-z][A-Za-z0-9_-]*)(\s+)(.+)$/);
+      if (schemeMatch) {
+        const scheme = schemeMatch[1];
+        const whitespace = schemeMatch[2];
+        const credential = schemeMatch[3];
+        if (scheme && whitespace && credential) {
+          return isRedactionMarker(credential.trim())
+            ? match
+            : `${prefix}${scheme}${whitespace}${REDACTED}${trailingWhitespace}`;
+        }
+      }
+      return isRedactionMarker(value) ? match : `${prefix}${REDACTED}${trailingWhitespace}`;
+    },
+  );
+  redacted = redacted.replace(COOKIE_HEADER_PATTERN, `$1${REDACTED}`);
+  redacted = redacted.replace(API_KEY_HEADER_PATTERN, `$1${REDACTED}`);
+  redacted = redacted.replace(CURL_USER_PATTERN, (_match, prefix: string) => {
+    return `${prefix}${REDACTED}`;
+  });
+  redacted = redacted.replace(URL_USERINFO_PATTERN, `$1${REDACTED}@`);
+  redacted = redacted.replace(SIGNED_QUERY_PATTERN, `$1${REDACTED}`);
+  redacted = redacted.replace(
+    QUOTED_SECRET_ASSIGNMENT_PATTERN,
+    (match, prefix: string, quote: string, value: string) =>
+      isRedactionMarker(value) ? match : `${prefix}${quote}${REDACTED}${quote}`,
+  );
+  redacted = redacted.replace(
+    UNQUOTED_SECRET_ASSIGNMENT_PATTERN,
+    (match, prefix: string, value: string) =>
+      isRedactionMarker(value) ? match : `${prefix}${REDACTED}`,
+  );
+  redacted = redacted.replace(
+    SECRET_ENV_ASSIGNMENT_PATTERN,
+    (
+      match,
+      prefix: string,
+      doubleQuoted: string | undefined,
+      singleQuoted: string | undefined,
+      bare: string | undefined,
+    ) => {
+      const value = doubleQuoted ?? singleQuoted ?? bare ?? "";
+      return isRedactionMarker(stripMatchingQuotes(value)) ? match : `${prefix}${REDACTED}`;
+    },
+  );
+  for (const pattern of PROVIDER_TOKEN_PATTERNS) {
+    redacted = redacted.replace(pattern, REDACTED);
+  }
+  return redacted;
+}
+
+/** Deeply redact plain structured data while retaining its diagnostic shape. */
+export function redactSensitiveData<T>(
+  value: T,
+  knownSecrets: readonly SecretForRedaction[] = [],
+): T {
+  return redactSensitiveDataDeep(value, knownSecrets, new WeakSet<object>(), 0);
+}
+
+/** Build the worker-friendly single-argument redactor used at turn boundaries. */
+export function createSecretRedactor(
+  knownSecrets: readonly SecretForRedaction[],
+): (value: unknown) => unknown {
+  const prepared = prepareSecrets(knownSecrets).map(({ marker, value }) => ({
+    name: marker.slice("[redacted:".length, -1),
+    value,
+  }));
+  return (value: unknown) => redactSensitiveData(value, prepared);
+}
+
+/**
+ * Redact a serialized JSON checkpoint without requiring it to be valid JSON.
+ * Valid JSON retains structure; malformed/opaque text still receives text
+ * classification and exact-known-value replacement.
+ */
+export function redactSerializedJson(
+  serialized: string,
+  knownSecrets: readonly SecretForRedaction[] = [],
+): string {
+  try {
+    return JSON.stringify(redactSensitiveData(JSON.parse(serialized), knownSecrets));
+  } catch {
+    return redactSensitiveText(serialized, knownSecrets);
+  }
+}
+
+export function identityRedactor<T>(value: T): T {
+  return value;
+}
+
+function redactSensitiveDataDeep<T>(
+  value: T,
+  knownSecrets: readonly SecretForRedaction[],
+  seen: WeakSet<object>,
+  depth: number,
+): T {
+  if (typeof value === "string") {
+    return redactSensitiveText(value, knownSecrets) as T;
+  }
+  if (!value || typeof value !== "object" || value instanceof Date) {
+    return value;
+  }
+  if (depth >= MAX_REDACTION_DEPTH) {
+    return DEPTH_MARKER as T;
+  }
+  if (seen.has(value)) {
+    return CYCLE_MARKER as T;
+  }
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return value.map((item) => redactSensitiveDataDeep(item, knownSecrets, seen, depth + 1)) as T;
+    }
+    if (!isPlainObject(value)) {
+      return value;
+    }
+    const usedKeys = new Set<string>();
+    return Object.fromEntries(
+      Object.entries(value).map(([key, child]) => {
+        const safeKey = nextUniqueKey(redactSensitiveKey(key, knownSecrets), usedKeys);
+        if (isSensitiveFieldName(key)) {
+          return [safeKey, REDACTED] as const;
+        }
+        if (normalizeFieldName(key) === "headers") {
+          return [safeKey, redactHeaderMap(child, knownSecrets, seen, depth + 1)] as const;
+        }
+        return [safeKey, redactSensitiveDataDeep(child, knownSecrets, seen, depth + 1)] as const;
+      }),
+    ) as T;
+  } finally {
+    seen.delete(value);
+  }
+}
+
+function redactHeaderMap(
+  value: unknown,
+  knownSecrets: readonly SecretForRedaction[],
+  seen: WeakSet<object>,
+  depth: number,
+): unknown {
+  if (!isPlainObject(value)) {
+    return redactSensitiveDataDeep(value, knownSecrets, seen, depth);
+  }
+  if (depth >= MAX_REDACTION_DEPTH) return DEPTH_MARKER;
+  if (seen.has(value)) return CYCLE_MARKER;
+  seen.add(value);
+  try {
+    const usedKeys = new Set<string>();
+    return Object.fromEntries(
+      Object.entries(value).map(([key, child]) => {
+        const safeKey = nextUniqueKey(redactSensitiveKey(key, knownSecrets), usedKeys);
+        return [
+          safeKey,
+          isCredentialHeaderName(key)
+            ? REDACTED
+            : redactSensitiveDataDeep(child, knownSecrets, seen, depth + 1),
+        ];
+      }),
+    );
+  } finally {
+    seen.delete(value);
+  }
+}
+
+function prepareSecrets(knownSecrets: readonly SecretForRedaction[]): PreparedSecret[] {
+  const unique = new Map<string, string>();
+  for (const secret of knownSecrets) {
+    if (secret.value.length < MIN_REDACTABLE_VALUE_LENGTH || unique.has(secret.value)) {
+      continue;
+    }
+    unique.set(secret.value, `[redacted:${safeSecretName(secret.name)}]`);
+  }
+  return [...unique]
+    .map(([value, marker]) => ({ marker, value }))
+    .sort((a, b) => b.value.length - a.value.length || a.marker.localeCompare(b.marker));
+}
+
+function replacePreparedSecrets(text: string, prepared: readonly PreparedSecret[]): string {
+  let redacted = text;
+  for (const secret of prepared) {
+    if (redacted.includes(secret.value)) {
+      redacted = redacted.split(secret.value).join(secret.marker);
+    }
+  }
+  return redacted;
+}
+
+function nextUniqueKey(base: string, usedKeys: Set<string>): string {
+  let candidate = base;
+  let suffix = 2;
+  while (usedKeys.has(candidate)) {
+    candidate = `${base}#${suffix}`;
+    suffix += 1;
+  }
+  usedKeys.add(candidate);
+  return candidate;
+}
+
+function safeSecretName(name: string): string {
+  const safe = name
+    .toUpperCase()
+    .replace(/[^A-Z0-9_]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  return safe.slice(0, 64) || "KNOWN_SECRET";
+}
+
+function normalizeFieldName(name: string): string {
+  return name.toLowerCase().replace(/[-_\s]/g, "");
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object") return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function isRedactionMarker(value: string): boolean {
+  return /^\[redacted(?::[A-Z0-9_]{1,64})?\]$/.test(value);
+}
+
+function stripMatchingQuotes(value: string): string {
+  if (
+    value.length >= 2 &&
+    ((value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'")))
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}