@huynle/hub 0.9.2 → 0.10.1

package/packages/protocol/src/app-front.ts

@@ -0,0 +1,293 @@
+// The app-front contract (AF0, docs/plans/2026-11-08-app-front-contracts.md; schema
+// packages/protocol/schema/app-front/v1.schema.json): what an external app (a server-side BFF) uses to make Hub its
+// AI layer — connect with consent (AF1), speech (AF2), a conversation stream (AF3), answering its own sessions'
+// confirm-tier Decisions (AF4) and the voice-client transport (AF5/AF6). Pure: names, units, limits, codes and the
+// few rules both the hub and apps need (redirect URIs, the scope parameter, PKCE shapes, token formats). Nothing
+// here is specific to any one app (Hub decision kvtvodrn); user answers in Hub decisions w6lfbfaq and nixct956.
+
+/** Version of the app-front contract and its schema; additive changes keep 1. */
+export const APP_FRONT_VERSION = 1
+
+// ---------- scopes and features ----------
+
+/** The scopes the app front adds to APP_SCOPES (src/central/agent/app-tokens.ts), each shipped by its AF task. */
+export const APP_FRONT_SCOPES = ["speech:use", "conversation:read", "conversation:write", "decisions:answer"] as const
+export type AppFrontScope = (typeof APP_FRONT_SCOPES)[number]
+
+/** `/.well-known/hub` `features` flags: a hub lists one only once the task that ships it is merged. */
+export const APP_FRONT_FEATURES = ["app-connect", "app-speech", "app-conversation", "app-decisions"] as const
+export type AppFrontFeature = (typeof APP_FRONT_FEATURES)[number]
+
+/** The task that ships each flag, and the scope that flag brings (app-connect brings none: it is the flow). */
+export const APP_FRONT_FEATURE_TASK: Readonly<Record<AppFrontFeature, { readonly task: string; readonly scopes: readonly AppFrontScope[] }>> = {
+  "app-connect": { task: "AF1", scopes: [] },
+  "app-speech": { task: "AF2", scopes: ["speech:use"] },
+  "app-conversation": { task: "AF3", scopes: ["conversation:read", "conversation:write"] },
+  "app-decisions": { task: "AF4", scopes: ["decisions:answer"] },
+}
+
+/**
+ * What this source tree ships. Each AF task flips its flag in the same commit that ships it (the schema test then
+ * expects the hub to advertise it and its routes to answer); until then the feature is contract-only.
+ */
+export const APP_FRONT_SHIPPED: Readonly<Record<AppFrontFeature, boolean>> = {
+  "app-connect": true,
+  "app-speech": true,
+  "app-conversation": true,
+  "app-decisions": true,
+}
+
+// ---------- connect (AF1): OAuth 2.1-style authorization code + PKCE ----------
+
+/** Endpoints of the connect flow. `/connect/*` and the metadata are top level (never behind the console gate). */
+export const CONNECT_PATHS = {
+  /** RFC 8414 authorization server metadata (public). */
+  metadata: "/.well-known/oauth-authorization-server",
+  /** GET, browser: validates the request, opens a flow, redirects to the consent page. */
+  authorize: "/connect/authorize",
+  /** The console's consent page (signed-in user). */
+  consentPage: "/connect/consent/:flow",
+  /** POST, app server (form-encoded, client authentication): code → tokens, refresh → tokens. */
+  token: "/connect/token",
+  /** POST, app server (RFC 7009): ends the connection the token belongs to. */
+  revoke: "/connect/revoke",
+  /** Console routes behind the gate (cookie, same origin): read, approve, deny a flow. */
+  flow: "/api/connect/flows/:flow",
+  flowApprove: "/api/connect/flows/:flow/approve",
+  flowDeny: "/api/connect/flows/:flow/deny",
+  /** /api/agent, user actors only: registered clients (admins write) and the user's connections. */
+  clients: "/api/agent/app-clients",
+  client: "/api/agent/app-clients/:id",
+  clientSecret: "/api/agent/app-clients/:id/secret",
+  connections: "/api/agent/connections",
+  connection: "/api/agent/connections/:id",
+} as const
+
+/** Token and ID prefixes ("hc": hub connect). Hand-made app tokens keep `hat_` (unchanged, never expire). */
+export const CONNECT_PREFIXES = {
+  clientID: "hcl_",
+  clientSecret: "hcs_",
+  flow: "hcf_",
+  code: "hco_",
+  access: "hca_",
+  refresh: "hcr_",
+} as const
+
+/** Anchored formats; secrets are 32 random bytes in base64url (43 characters). Connection IDs are 16 hex. */
+export const CONNECT_TOKEN_PATTERNS = {
+  clientID: /^hcl_[0-9a-f]{16}$/,
+  clientSecret: /^hcs_[A-Za-z0-9_-]{43}$/,
+  flow: /^hcf_[0-9a-f]{24}$/,
+  code: /^hco_[A-Za-z0-9_-]{43}$/,
+  access: /^hca_([0-9a-f]{16})_[A-Za-z0-9_-]{43}$/,
+  refresh: /^hcr_([0-9a-f]{16})_[A-Za-z0-9_-]{43}$/,
+  connectionID: /^[0-9a-f]{16}$/,
+} as const
+
+/** Lifetimes (ms). */
+export const ACCESS_TOKEN_TTL_MS = 60 * 60_000
+/** Sliding: every refresh issues a refresh token valid this long from then; unused this long, the connection lapses. */
+export const REFRESH_TOKEN_IDLE_MS = 30 * 24 * 60 * 60_000
+export const AUTHORIZATION_CODE_TTL_MS = 60_000
+/**
+ * After a refresh, presenting the just-rotated refresh token again this long answers the same new pair (a lost answer
+ * can be retried); after it, that is reuse and revokes the connection (Hub decision nixct956 3).
+ */
+export const REFRESH_GRACE_MS = 30_000
+/** From authorize to approve/deny (like CLI_LOGIN_TTL_MS). */
+export const CONNECT_FLOW_TTL_MS = 10 * 60_000
+
+export const CONNECT_LIMITS = {
+  /** Hub-wide (admin-registered) clients per hub. */
+  clients: 50,
+  /** Personal clients per user (decision nixct956 5). */
+  personalClientsPerUser: 10,
+  redirectURIsPerClient: 10,
+  clientNameMax: 100,
+  /** `state` is opaque to the hub and echoed back. */
+  stateMax: 1024,
+  /** Connections per user (one per client). */
+  connectionsPerUser: 50,
+  /** Authorize requests per client and client address a minute (an open flow is cheap but bounded). */
+  authorizePerMinute: 20,
+  /** Authenticated token-endpoint requests per client and minute. */
+  tokenPerMinute: 60,
+  /**
+   * Failed client authentications per client and client address a minute; beyond, that address's failures get 429
+   * (a caller with the right secret is never refused for them).
+   */
+  failedClientAuthPerMinute: 10,
+} as const
+
+/**
+ * Who may use a registered client (Hub decision nixct956 5): `hub` (hub-wide, admin-registered: every user of the hub
+ * may connect) or `user` (personal: only the user who registered it sees and uses it).
+ */
+export const CLIENT_AUDIENCES = ["hub", "user"] as const
+export type ClientAudience = (typeof CLIENT_AUDIENCES)[number]
+
+export const CODE_CHALLENGE_METHODS = ["S256"] as const
+export const RESPONSE_TYPES = ["code"] as const
+export const GRANT_TYPES = ["authorization_code", "refresh_token"] as const
+export const TOKEN_ENDPOINT_AUTH_METHODS = ["client_secret_basic", "client_secret_post"] as const
+
+/** RFC 6749 §4.1.2.1 errors the authorize endpoint redirects with (only once client_id and redirect_uri are valid). */
+export const AUTHORIZE_ERRORS = ["invalid_request", "unauthorized_client", "access_denied", "unsupported_response_type", "invalid_scope", "server_error", "temporarily_unavailable"] as const
+/** RFC 6749 §5.2 errors of the token endpoint, with their HTTP status (`temporarily_unavailable` 429: rate limit). */
+export const TOKEN_ERROR_STATUS = {
+  invalid_request: 400,
+  invalid_client: 401,
+  invalid_grant: 400,
+  unauthorized_client: 400,
+  unsupported_grant_type: 400,
+  invalid_scope: 400,
+  temporarily_unavailable: 429,
+} as const
+export type TokenError = keyof typeof TOKEN_ERROR_STATUS
+
+// ---------- speech (AF2) ----------
+
+export const SPEECH_PATHS = { transcribe: "/api/agent/speech/transcribe", speak: "/api/agent/speech/speak" } as const
+
+/** Per app credential (a connection, or a hand-made token): 429 rate_limited with retryAfter beyond these. */
+export const SPEECH_RATE_LIMITS = {
+  transcribe: { perMinute: 20, perHour: 300 },
+  speak: { perMinute: 60, perHour: 1000, charsPerHour: 100_000 },
+} as const
+
+// ---------- conversation (AF3) ----------
+
+export const CONVERSATION_PATHS = {
+  stream: "/api/agent/sessions/:addr/stream",
+  conversation: "/api/agent/sessions/:addr/conversation",
+  utterance: "/api/agent/sessions/:addr/utterance",
+  interrupt: "/api/agent/sessions/:addr/interrupt",
+  /** Typed turns: the existing act prompt, also admitted with conversation:write. */
+  turn: "/api/agent/sessions/:addr/prompt",
+  /** Re-read after a reset: the existing log, also admitted with conversation:read for the app's sessions. */
+  log: "/api/agent/sessions/:addr/log",
+} as const
+
+export const APP_STREAM_FRAME_TYPES = ["ready", "delta", "say", "heard", "status", "conversation", "reset", "end"] as const
+export type AppStreamFrameType = (typeof APP_STREAM_FRAME_TYPES)[number]
+
+/** Why the hub ended an app stream (the last frame, `end`). */
+export const APP_STREAM_END_REASONS = ["token_expired", "revoked", "grant", "gone", "slow"] as const
+export type AppStreamEndReason = (typeof APP_STREAM_END_REASONS)[number]
+
+/** What a `reset` frame asks the app to re-read. */
+export const APP_STREAM_REFRESH = ["log", "status", "conversation", "decisions"] as const
+
+export const APP_STREAM_LIMITS = {
+  heartbeatMs: 20_000,
+  /** Draining: `retry:` sent before the stream ends. */
+  retryMs: 2_000,
+  /** How often an open stream re-checks its credential, grant and session (and ends with `end`). */
+  recheckMs: 30_000,
+  /** Unsent bytes a slow reader may hold before the hub ends the stream (`end` reason slow). */
+  bufferMaxBytes: 1 << 20,
+  /** Concurrent streams per app credential, and per user over all apps (429 rate_limited beyond). */
+  streamsPerApp: 4,
+  streamsPerUser: 20,
+} as const
+
+// ---------- decisions (AF4) ----------
+
+export const DECISION_PATHS = { list: "/api/agent/decisions", answer: "/api/agent/decisions/:id/answer" } as const
+/** The only tier an app answers (decision w6lfbfaq 1). */
+export const APP_ANSWERABLE_TIERS = ["confirm"] as const
+
+// ---------- voice-client transport (AF5 interface, AF6 app adapter) ----------
+
+/** What the voice loop hears about its session (the app stream's frames it uses). */
+export type VoiceEvent =
+  | { readonly type: "say"; readonly sessionID: string; readonly messageID: string; readonly ordinal: number; readonly seq?: number; readonly text: string }
+  | { readonly type: "heard"; readonly sessionID: string; readonly inboxID: string }
+  | { readonly type: "conversation"; readonly sessionID: string; readonly on: boolean; readonly front?: boolean; readonly reason?: "front_failed" }
+  | { readonly type: "status"; readonly sessionID: string; readonly state: "idle" | "working" | "blocked" | "error" }
+  | { readonly type: "reset" }
+
+/**
+ * The transport the voice loop (packages/voice-client) talks through. The console implements it with its cookie
+ * routes; an app implements it against its own server, which calls the AF2/AF3 routes with its token. The package
+ * never holds a hub token and never calls the hub itself.
+ */
+export interface VoiceTransport {
+  /** Conversation mode on/off for the session (front: the voice front). */
+  conversation(on: boolean, options?: { readonly front?: boolean }): Promise<{ readonly on: boolean; readonly front?: boolean }>
+  /** A final transcript, to the session (or its front). */
+  utterance(text: string): Promise<{ readonly inboxID: string }>
+  /** Barge-in: stops the front (or the session's turn). */
+  interrupt(): Promise<void>
+  transcribe(audio: Blob, options?: { readonly signal?: AbortSignal }): Promise<{ readonly text: string }>
+  /** audio/mpeg, streamed when the provider streams. */
+  speak(text: string, options?: { readonly signal?: AbortSignal }): Promise<ReadableStream<Uint8Array>>
+  /** Subscribes to the session's voice events; returns the unsubscribe. */
+  events(listener: (event: VoiceEvent) => void): () => void
+}
+
+// ---------- rules ----------
+
+export const REDIRECT_URI_MAX = 2048
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "[::1]", "localhost"])
+
+/**
+ * Why `uri` cannot be a registered redirect URI, or undefined: an absolute https URL (http only on a loopback host),
+ * at most REDIRECT_URI_MAX characters, without user info, fragment, wildcard or surrounding whitespace.
+ */
+export function redirectUriProblem(uri: unknown): string | undefined {
+  if (typeof uri !== "string" || uri === "") return "a redirect URI is a non-empty string"
+  if (uri.length > REDIRECT_URI_MAX) return `a redirect URI is at most ${REDIRECT_URI_MAX} characters`
+  if (uri.trim() !== uri || /\s/.test(uri)) return "a redirect URI has no whitespace"
+  if (uri.includes("*")) return "a redirect URI has no wildcard"
+  let url: URL
+  try {
+    url = new URL(uri)
+  } catch {
+    return "a redirect URI is an absolute URL"
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return "a redirect URI uses https (http only on a loopback host)"
+  if (url.protocol === "http:" && !LOOPBACK_HOSTS.has(url.hostname)) return "http is allowed only on a loopback host (127.0.0.1, [::1], localhost)"
+  if (url.username || url.password) return "a redirect URI has no user info"
+  if (uri.includes("#")) return "a redirect URI has no fragment"
+  return undefined
+}
+
+/** Exact string comparison against the registered URIs (no normalisation of any kind). */
+export function redirectUriMatches(registered: readonly string[], uri: unknown): boolean {
+  return typeof uri === "string" && registered.includes(uri)
+}
+
+/** The OAuth `scope` parameter: scopes separated by single spaces, each known; duplicates dropped, order kept. */
+export function parseScopeParam(value: unknown, known: readonly string[]): { scopes: string[] } | { problem: string } {
+  if (typeof value !== "string" || value === "") return { problem: "scope lists at least one scope" }
+  const parts = value.split(" ")
+  if (parts.some((part) => part === "")) return { problem: "scope separates scopes with single spaces" }
+  const unknown = parts.find((part) => !known.includes(part))
+  if (unknown !== undefined) return { problem: `unknown scope: ${unknown.slice(0, 64)}` }
+  return { scopes: [...new Set(parts)] }
+}
+
+const VERIFIER = /^[A-Za-z0-9._~-]{43,128}$/
+const CHALLENGE = /^[A-Za-z0-9_-]{43}$/
+
+/** RFC 7636 §4.1: 43–128 unreserved characters. */
+export function pkceVerifierProblem(verifier: unknown): string | undefined {
+  return typeof verifier === "string" && VERIFIER.test(verifier) ? undefined : "code_verifier is 43–128 characters of A-Z a-z 0-9 - . _ ~"
+}
+
+/** S256 only: the challenge is base64url(SHA-256(verifier)) without padding (43 characters). */
+export function pkceChallengeProblem(challenge: unknown, method: unknown): string | undefined {
+  if (method !== "S256") return "code_challenge_method must be S256"
+  return typeof challenge === "string" && CHALLENGE.test(challenge) ? undefined : "code_challenge is 43 base64url characters"
+}
+
+/** A connected app's access or refresh token, with the connection it belongs to; anything else undefined. */
+export function parseConnectToken(token: unknown): { kind: "access" | "refresh"; connectionID: string } | undefined {
+  if (typeof token !== "string") return undefined
+  const access = CONNECT_TOKEN_PATTERNS.access.exec(token)
+  if (access) return { kind: "access", connectionID: access[1]! }
+  const refresh = CONNECT_TOKEN_PATTERNS.refresh.exec(token)
+  if (refresh) return { kind: "refresh", connectionID: refresh[1]! }
+  return undefined
+}

package/packages/protocol/src/concierge.ts

@@ -101,8 +101,10 @@ export const CONCIERGE_LIMITS = {
 /**
  * The keys of the parts a session context carries. The spoke appends instructions then notes to the session's system
  * prompt (stable between turns) and sends the board after the conversation (it changes: V-01, the prompt cache).
+ * "frontBoard" (voice front P2, sent only to spokes announcing "conciergeFront"): the compact board for the
+ * Concierge's voice front; never part of the Concierge's own prompt.
  */
-export const SESSION_CONTEXT_KEYS = ["instructions", "board", "notes"] as const
+export const SESSION_CONTEXT_KEYS = ["instructions", "board", "notes", "frontBoard"] as const
 export type SessionContextKey = (typeof SESSION_CONTEXT_KEYS)[number]
 
 export const SESSION_CONTEXT_LIMITS = { partChars: 40_000, denyGlobs: 50, globChars: 100, allowTools: 50 } as const
@@ -272,6 +274,11 @@ export interface ConciergeBoardSession {
   readonly project?: string
   /** Machine name (sanitised label). */
   readonly machine?: string
+  /**
+   * (Concierge grant requests) The verbs an active @@concierge grant allows in this session's project folder (the
+   * acting engine's grant lookup for the current Concierge; [] = none). Absent: unknown (no Concierge, no folder).
+   */
+  readonly projectGrant?: readonly string[]
   readonly state: ConciergeBoardState
   /** When the current state began, as far as the hub knows (activity, last result, or lastSeen when offline). */
   readonly since?: number
@@ -283,6 +290,8 @@ export interface ConciergeBoardSession {
   readonly intent?: { readonly text: string; readonly source: IntentSource }
   /** The non-placeholder title (at most 80 characters), untrusted; only when there is no intent. */
   readonly title?: string
+  /** The primary context card's headline (at most 90 characters), untrusted: where the work stands (docs/context-cards.md). */
+  readonly pickup?: string
   readonly lastResult?: { readonly at: number; readonly outcome: ConciergeResultOutcome }
   readonly reasons: readonly WatchReason[]
 }

package/packages/protocol/src/context-cards.ts

@@ -0,0 +1,59 @@
+// Context cards (decision 9604b0a1, docs/context-cards.md): short, auto-updated cards beside a session that help
+// the user and the Concierge pick its work back up. Each card comes from a PROVIDER (the hub's registry, e.g.
+// `pickup`, `changes`); one provider is primary: its headline is the session list's second line. Shared by the
+// hub (src/central/context-cards) and the console (web/src/core/context-cards-core.ts).
+
+/** What makes a provider run: a turn ended, the session went blocked, the user came back, the leader's sweep, a refresh. */
+export const CONTEXT_CARD_TRIGGERS = ["turn-end", "blocked", "user-return", "sweep", "manual"] as const
+export type ContextCardTrigger = (typeof CONTEXT_CARD_TRIGGERS)[number]
+
+/** Bounds of a stored card (characters, code points). */
+export const CONTEXT_CARD_LIMITS = {
+  title: 60,
+  headline: 90,
+  body: 400,
+  fields: 6,
+  fieldLabel: 24,
+  fieldValue: 120,
+  model: 100,
+} as const
+
+export interface ContextCardField {
+  readonly label: string
+  readonly value: string
+}
+
+export interface ContextCard {
+  /** The provider's id (`pickup`, `changes`, …). */
+  readonly provider: string
+  readonly sessionID: string
+  /** The card's title ("Pick up where you left off"). */
+  readonly title: string
+  /** One line (≤ 90 characters): the primary card's is the session list's second line. */
+  readonly headline: string
+  /** Markdown-lite text (≤ 400 characters; may be empty). Untrusted: render as text. */
+  readonly body: string
+  readonly fields?: readonly ContextCardField[]
+  /** Epoch ms. */
+  readonly generatedAt: number
+  /** The model that wrote it (model providers only). */
+  readonly model?: string
+  /** Hash of the inputs it was made from (unchanged inputs are not regenerated). */
+  readonly inputsHash: string
+  /** The provider's version when it was made. */
+  readonly version: number
+  readonly trigger: ContextCardTrigger
+  /** The inputs it was made from (an offline spoke's weaker inputs never replace a richer card). */
+  readonly basis?: readonly string[]
+  /** The primary card (its headline is the list's second line). */
+  readonly primary?: true
+}
+
+/** A provider as clients see it. */
+export interface ContextCardProviderInfo {
+  readonly id: string
+  readonly label: string
+  readonly primary: boolean
+  /** It calls the context card model (needs it configured, counts against the daily budget). */
+  readonly usesModel: boolean
+}

package/packages/protocol/src/credentials.ts

@@ -1,9 +1,16 @@
 // Literal credentials in free text (tokens, keys, private keys): found, or replaced with "[redacted: <kind>]". Voice
 // recordings scrub every text field with it; spoken and pushed failure reasons and voice-front wakes do too.
 
+/**
+ * A private key block of any type (PEM, OpenSSH, encrypted, PGP): BEGIN through END; without an END (a cut text), the
+ * header, the base64 chunks after it on the same line (after spaces or a literal "\n", as in JSON or env strings) and
+ * the key-material lines after it. Prose after a bare header ("… KEY----- and …") is kept.
+ */
+const PRIVATE_KEY = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----(?:[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----|(?:(?:[ \t]+|\\n)[A-Za-z0-9+/=]{8,})*(?:\r?\n[A-Za-z0-9+/=:,. -]*)*)/
+
 /** Distinctive credential formats; prose about secrets ("set API_KEY=…") is not matched. */
 export const CREDENTIALS: readonly (readonly [string, RegExp])[] = [
-  ["private key", /-----BEGIN [A-Z ]*PRIVATE KEY-----/],
+  ["private key", PRIVATE_KEY],
   ["hub app token", /\bhat_[0-9a-f]{16}_[A-Za-z0-9_-]{43,}/],
   ["github token", /\bgh[pousr]_[A-Za-z0-9]{36,}/],
   ["github token", /\bgithub_pat_[A-Za-z0-9_]{22,}/],
@@ -15,6 +22,31 @@ export const CREDENTIALS: readonly (readonly [string, RegExp])[] = [
   ["bearer token", /\b[Bb]earer\s+[A-Za-z0-9._~+/=-]{20,}/],
 ]
 
+/** Names whose value is a secret: ending in password, passwd, pwd, passphrase, secret, token, api key, or AWS key names. */
+const NAME = String.raw`[A-Za-z0-9_.-]*(?:password|passwd|pwd|passphrase|secret|token|api[_-]?key|secret_?access_?key|access_?key_?id)`
+/** Between a name and its value: an optional closing quote, then = or :. */
+const SEP = String.raw`["']?\s*[:=]\s*`
+/** Placeholder values in docs and prose ("API_KEY=your-key-here", "<token>", "…", "xxx", "changeme") are not secrets. */
+const PLACEHOLDER = String.raw`(?!(?:your[-_ ]|<|\.\.\.|…|x{3,}(?![A-Za-z0-9])|\*{3,}|changeme|example|placeholder)[^\s"']*(?:["'\s&;,<>]|$))`
+
+/**
+ * Secrets by context, redacted by redactCredentials after CREDENTIALS (the name stays, the value goes):
+ *   aws secret key: a 40-character key after aws_secret_access_key / aws_secret_key / secret_access_key (any case)
+ *   url password:   scheme://user:<password>@host (the user may be empty; the password may hold "/"; a port is not one)
+ *   authorization:  the credentials after Authorization: Basic | Bearer | Token | Digest
+ *   secret:         <name>=value, <name>: value and "<name>": "value" (NAME, any case, e.g. GITHUB_TOKEN, client_secret,
+ *                   OPENAI_API_KEY, apiKey, SecretAccessKey, SessionToken, AccessKeyId); a quoted value goes whole
+ *                   (spaces, commas, semicolons included), an unquoted one runs to whitespace, a quote or & ; , < >;
+ *                   placeholders (your-…, <…>, …, xxx, ***, changeme, example, placeholder) are left alone
+ */
+const CONTEXTUAL: readonly (readonly [string, RegExp, string])[] = [
+  ["aws secret key", /\b((?:aws_)?secret(?:_access)?_key["']?\s*[:=]\s*["']?)(?!\[redacted)[A-Za-z0-9/+=]{40}(?![A-Za-z0-9/+=])/gi, "$1[redacted: aws secret key]"],
+  ["url password", /\b([a-z][a-z0-9+.-]*:\/\/[^\s:@/]*:)(?!\[redacted)(?!\d+(?:[/?#\s]|$))[^\s@]+(@)/gi, "$1[redacted: url password]$2"],
+  ["authorization", /\b(authorization["']?\s*[:=]\s*["']?(?:basic|bearer|token|digest)\s+)(?!\[redacted)[^\s"',;]+/gi, "$1[redacted: authorization]"],
+  ["secret", new RegExp(String.raw`\b(${NAME}${SEP})(["'])(?!\[redacted)${PLACEHOLDER}(?:(?!\2)[^\\\n]|\\.)*\2`, "gi"), "$1$2[redacted: secret]$2"],
+  ["secret", new RegExp(String.raw`\b(${NAME}${SEP})(?!["'\[])${PLACEHOLDER}(?=[^\s"'&;,<>]*[A-Za-z0-9])[^\s"'&;,<>]+`, "gi"), "$1[redacted: secret]"],
+]
+
 /** The kind of literal credential in a text, or undefined. */
 export function credentialFinding(text: string): string | undefined {
   for (const [kind, pattern] of CREDENTIALS) if (pattern.test(text)) return kind
@@ -22,7 +54,7 @@ export function credentialFinding(text: string): string | undefined {
 }
 
 /**
- * (REC-01) Replaces every literal credential in a text with `[redacted: <kind>]` (the CREDENTIALS table, applied
+ * (REC-01) Replaces every literal credential (CREDENTIALS, then the CONTEXTUAL secrets: names kept, values replaced) in a text with `[redacted: <kind>]` (the CREDENTIALS table, applied
  * globally) and lists the kinds removed, each once, in table order. Voice recordings scrub every text field with it.
  */
 export function redactCredentials(text: string): { text: string; kinds: string[] } {
@@ -34,5 +66,10 @@ export function redactCredentials(text: string): { text: string; kinds: string[]
     if (next !== out && !kinds.includes(kind)) kinds.push(kind)
     out = next
   }
+  for (const [kind, pattern, replacement] of CONTEXTUAL) {
+    const next = out.replace(pattern, replacement)
+    if (next !== out && !kinds.includes(kind)) kinds.push(kind)
+    out = next
+  }
   return { text: out, kinds }
 }