@aws-blocks/core 0.1.0

package/src/raw-route.ts

@@ -0,0 +1,316 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { BlocksContext } from './api.js';
+import type { ScopeParent } from './common/index.js';
+import { BLOCKS_NAMESPACE, BLOCKS_RPC_PREFIX } from './constants.js';
+
+// ── Public types ────────────────────────────────────────────────────────────
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+
+export interface RawRouteOptions {
+  method: HttpMethod;
+  /**
+   * URL path pattern. When provided, used exactly as given.
+   * When omitted, derived from the scope-chain IDs.
+   *
+   * - `/health`       — exact match
+   * - `/users/{id}`   — named path parameter (captures one segment)
+   * - `/v1/*`         — wildcard (captures everything after prefix)
+   *
+   * **Scope-chain derivation:** If omitted, the path is built by collecting
+   * each ancestor scope's `id` (excluding the root BlocksStack) and joining
+   * with `/`. For example, `BlocksStack('app') → Scope('v1') → RawRoute('health')`
+   * yields `/v1/health`.
+   */
+  path?: string;
+  handler: (context: BlocksContext) => Promise<void>;
+}
+
+/**
+ * Typed error constants for RawRoute. Use with `isBlocksError()` in catch blocks.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   new RawRoute(scope, 'dup', { method: 'GET', path: '/health', handler });
+ * } catch (e: unknown) {
+ *   if (isBlocksError(e, RawRouteErrors.DuplicateRoute)) {
+ *     // same method+path already registered
+ *   }
+ * }
+ * ```
+ */
+export const RawRouteErrors = {
+  DuplicateRoute: 'DuplicateRouteException',
+} as const;
+
+// ── Scope-chain path derivation ─────────────────────────────────────────────
+
+/**
+ * Derive a URL path from the scope chain.
+ *
+ * Walks the parent chain from `scope` up to (but NOT including) the root
+ * BlocksStack or the top-level user Scope, collects each intermediate scope's
+ * `id`, URL-encodes segments, and joins with `/`. The RawRoute's own `id`
+ * is appended as the final segment.
+ *
+ * A scope is "root-level" if its parent has no `parent` property (i.e., it's
+ * the BlocksStack or the fallback `{ id: ... }` sentinel). Root-level scopes
+ * are excluded from the path — they represent the application boundary, not
+ * a URL segment.
+ *
+ * @example
+ * ```
+ * Scope('app') → RawRoute('health')                    → /health
+ * Scope('app') → Scope('v1') → RawRoute('users')       → /v1/users
+ * Scope('app') → Scope('api') → Scope('v2') → RawRoute('items') → /api/v2/items
+ * ```
+ */
+export function derivePathFromScope(scope: ScopeParent, id: string): string {
+  const segments: string[] = [];
+
+  let current: ScopeParent | undefined = scope;
+  while (current && 'parent' in current && current.parent) {
+    const parentNode: ScopeParent = (current as { parent: ScopeParent }).parent;
+    const parentIsRoot = !('parent' in parentNode) || !(parentNode as any).parent;
+    if (parentIsRoot) break;
+    segments.unshift(encodeURIComponent(current.id));
+    current = parentNode;
+  }
+
+  segments.push(encodeURIComponent(id));
+  return '/' + segments.join('/');
+}
+
+/**
+ * Resolve the effective path for a RawRoute — uses the explicit `path` if
+ * provided, otherwise derives it from the scope chain.
+ */
+export function resolveRoutePath(scope: ScopeParent, id: string, options: RawRouteOptions): string {
+  return options.path ?? derivePathFromScope(scope, id);
+}
+
+// ── Route registry ──────────────────────────────────────────────────────────
+
+export interface RegisteredRoute {
+  method: string;
+  /** Normalized path (trailing slashes removed, double slashes collapsed). */
+  path: string;
+  /** Compiled regex for matching incoming request paths. */
+  pattern: RegExp;
+  /** Extracted parameter names in capture-group order. */
+  paramNames: string[];
+  handler: (context: BlocksContext) => Promise<void>;
+}
+
+const routeRegistry: RegisteredRoute[] = [];
+let registrationLocked = false;
+
+const VALID_METHODS = new Set<string>(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']);
+
+/** Prevent further route registration. Call after initialization is complete. */
+export function lockRouteRegistry(): void {
+  registrationLocked = true;
+}
+
+/** Re-allow route registration (useful in tests after lock). */
+export function unlockRouteRegistry(): void {
+  registrationLocked = false;
+}
+
+/**
+ * Register a raw HTTP route for runtime dispatch.
+ *
+ * **Internal.** The public API is `new RawRoute(scope, id, options)`.
+ * Path must be resolved before calling this function.
+ *
+ * @throws If registration is locked (after handler creation).
+ * @throws If the HTTP method is invalid.
+ * @throws If the path is under the reserved namespace (`/aws-blocks` or `/aws-blocks/api/*`).
+ * @throws {RawRouteErrors.DuplicateRoute} If the same method+path is registered twice.
+ */
+export function registerRoute(options: RawRouteOptions & { path: string }): void {
+  if (registrationLocked) {
+    throw new Error('Routes must be registered during initialization. Cannot register routes after handler creation.');
+  }
+
+  if (!VALID_METHODS.has(options.method)) {
+    throw new Error(`Invalid HTTP method: ${options.method}. Must be one of: ${Array.from(VALID_METHODS).join(', ')}`);
+  }
+
+  const normalizedPath = options.path.replace(/\/+/g, '/').replace(/\/$/, '') || '/';
+  if (normalizedPath === '/') {
+    throw new Error("Cannot register RawRoute at '/' — root path is not supported (API Gateway proxy resource doesn't handle root). Use a sub-path like '/health'.");
+  }
+
+  const lowerPath = normalizedPath.toLowerCase();
+  if (lowerPath === BLOCKS_NAMESPACE || lowerPath === BLOCKS_RPC_PREFIX || lowerPath.startsWith(`${BLOCKS_RPC_PREFIX}/`)) {
+    throw new Error(`Cannot register RawRoute at ${BLOCKS_NAMESPACE} or ${BLOCKS_RPC_PREFIX}/* — these paths are reserved for RPC dispatch`);
+  }
+
+  const existing = routeRegistry.find(
+    (r) => r.method === options.method && r.path === normalizedPath,
+  );
+  if (existing) {
+    const err = new Error(
+      `${RawRouteErrors.DuplicateRoute}: ${options.method} ${normalizedPath} is already registered`,
+    );
+    err.name = RawRouteErrors.DuplicateRoute;
+    throw err;
+  }
+
+  const { pattern, paramNames } = compilePath(normalizedPath);
+
+  routeRegistry.push({
+    method: options.method,
+    path: normalizedPath,
+    pattern,
+    paramNames,
+    handler: options.handler,
+  });
+}
+
+/** Return a read-only snapshot of all registered routes. */
+export function getRegisteredRoutes(): readonly RegisteredRoute[] {
+  return routeRegistry;
+}
+
+/** Remove all registered routes and unlock registration (used by tests). */
+export function clearRouteRegistry(): void {
+  routeRegistry.length = 0;
+  registrationLocked = false;
+}
+
+/**
+ * Match an incoming HTTP request against registered routes.
+ *
+ * @returns The matched route and extracted path parameters, or `null` if no match.
+ */
+export function matchRoute(
+  method: string,
+  path: string,
+): { route: RegisteredRoute; params: Record<string, string> } | null {
+  // Normalize incoming path: collapse double slashes
+  path = path.replace(/\/+/g, '/');
+
+  for (const route of routeRegistry) {
+    if (route.method !== method) continue;
+    const match = route.pattern.exec(path);
+    if (match) {
+      return { route, params: extractParams(route, match) };
+    }
+    // Retry without trailing slash for non-root paths (e.g. /health/ → /health)
+    if (path.length > 1 && path.endsWith('/')) {
+      const trimmed = path.slice(0, -1);
+      const retryMatch = route.pattern.exec(trimmed);
+      if (retryMatch) {
+        return { route, params: extractParams(route, retryMatch) };
+      }
+    }
+  }
+  return null;
+}
+
+function extractParams(route: RegisteredRoute, match: RegExpExecArray): Record<string, string> {
+  const params: Record<string, string> = Object.create(null);
+  route.paramNames.forEach((name, i) => {
+    const raw = match[i + 1];
+
+    if (name === '*') {
+      // Wildcards capture raw paths — no decoding (prevents path traversal)
+      params[name] = raw;
+      return;
+    }
+
+    // Named params get decoded
+    try {
+      params[name] = decodeURIComponent(raw);
+    } catch {
+      // Invalid percent encoding — use raw value
+      params[name] = raw;
+    }
+  });
+  return params;
+}
+
+// ── Path compilation ────────────────────────────────────────────────────────
+
+const REGEX_SPECIAL = new Set(['.', '+', '?', '^', '$', '|', '(', ')', '[', ']', '\\']);
+const BLOCKED_PARAM_NAMES = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Compile a path pattern into a RegExp and extract parameter names.
+ *
+ * Supported syntax:
+ * - `/health`        → exact match
+ * - `/users/{id}`    → captures one path segment as `id`
+ * - `/v1/*`          → captures everything after `/v1/` as `*`
+ * - `/a/{x}/b/{y}`   → multiple named parameters
+ */
+export function compilePath(path: string): { pattern: RegExp; paramNames: string[] } {
+  if (!path.startsWith('/')) {
+    throw new Error('Path must start with /');
+  }
+
+  // Normalize: collapse double slashes
+  path = path.replace(/\/+/g, '/');
+
+  // Remove trailing slash (except root '/')
+  if (path.length > 1 && path.endsWith('/')) {
+    path = path.slice(0, -1);
+  }
+
+  const paramNames: string[] = [];
+  let regexStr = '';
+  let i = 0;
+  let wildcardCount = 0;
+
+  while (i < path.length) {
+    if (path[i] === '{') {
+      const end = path.indexOf('}', i);
+      if (end === -1) {
+        throw new Error(`Unclosed '{' in path pattern: ${path}`);
+      }
+      const name = path.substring(i + 1, end);
+      if (!name || !/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+        throw new Error(
+          `Invalid parameter name '${name}' in path '${path}'. Parameter names must be valid JavaScript identifiers (start with letter or underscore, contain only letters, digits, underscores).`,
+        );
+      }
+      if (BLOCKED_PARAM_NAMES.has(name)) {
+        throw new Error(`Parameter name '${name}' is reserved and cannot be used in path '${path}'.`);
+      }
+      paramNames.push(name);
+      regexStr += '([^/]+)';
+      i = end + 1;
+    } else if (path[i] === '}') {
+      throw new Error(`Unexpected '}' without matching '{' in path pattern: ${path}`);
+    } else if (path[i] === '*') {
+      wildcardCount++;
+      if (wildcardCount > 1) {
+        throw new Error(
+          `Path '${path}' contains multiple wildcards. Only one wildcard (*) is allowed per route, and it must be the last segment.`,
+        );
+      }
+      if (i !== path.length - 1) {
+        throw new Error(
+          `Path '${path}' contains multiple wildcards. Only one wildcard (*) is allowed per route, and it must be the last segment.`,
+        );
+      }
+      paramNames.push('*');
+      regexStr += '(.*)';
+      i++;
+    } else if (REGEX_SPECIAL.has(path[i])) {
+      regexStr += '\\' + path[i];
+      i++;
+    } else {
+      regexStr += path[i];
+      i++;
+    }
+  }
+
+  const fullPattern = '^' + regexStr + '$';
+  return { pattern: new RegExp(fullPattern), paramNames };
+}

package/src/redact.test.ts

@@ -0,0 +1,222 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { redactForLogging, redactToJson, REDACTED } from './redact.js';
+
+describe('redactForLogging', () => {
+  it('redacts a top-level password field', () => {
+    const out = redactForLogging({ username: 'alice', password: 'hunter2' });
+    assert.deepEqual(out, { username: 'alice', password: REDACTED });
+  });
+
+  it('redacts every sensitive credential/token field name', () => {
+    const out = redactForLogging({
+      password: 'p',
+      newPassword: 'np',
+      session: 's',
+      accessToken: 'at',
+      refreshToken: 'rt',
+      idToken: 'it',
+      sharedSecret: 'ss',
+      clientSecret: 'cs',
+      apiKey: 'ak',
+      authorization: 'Bearer x',
+      code: '123456',
+      credentials: 'c',
+    });
+    for (const v of Object.values(out as Record<string, unknown>)) {
+      assert.equal(v, REDACTED);
+    }
+  });
+
+  it('matches field names case-insensitively', () => {
+    const out = redactForLogging({ PassWord: 'x', SESSION: 'y' }) as Record<string, unknown>;
+    assert.equal(out.PassWord, REDACTED);
+    assert.equal(out.SESSION, REDACTED);
+  });
+
+  it('leaves non-sensitive fields untouched', () => {
+    const input = { username: 'bob', email: 'b@example.com', count: 3, ok: true };
+    assert.deepEqual(redactForLogging(input), input);
+  });
+
+  it('walks nested objects', () => {
+    const out = redactForLogging({
+      action: 'confirmSignIn',
+      payload: { session: 'tok', code: '999' },
+    });
+    assert.deepEqual(out, {
+      action: 'confirmSignIn',
+      payload: { session: REDACTED, code: REDACTED },
+    });
+  });
+
+  it('walks arrays (e.g. positional RPC args)', () => {
+    const out = redactForLogging([
+      { action: 'signIn', username: 'a', password: 'secret' },
+      { action: 'confirmSignIn', session: 'tok', code: '111' },
+    ]);
+    assert.deepEqual(out, [
+      { action: 'signIn', username: 'a', password: REDACTED },
+      { action: 'confirmSignIn', session: REDACTED, code: REDACTED },
+    ]);
+  });
+
+  it('preserves null/undefined sensitive fields without masking', () => {
+    const out = redactForLogging({ password: null, session: undefined }) as Record<string, unknown>;
+    assert.equal(out.password, null);
+    assert.equal(out.session, undefined);
+  });
+
+  it('returns primitives unchanged', () => {
+    assert.equal(redactForLogging('just a string'), 'just a string');
+    assert.equal(redactForLogging(42), 42);
+    assert.equal(redactForLogging(null), null);
+  });
+
+  it('does not mutate the input object', () => {
+    const input = { password: 'keep-me', username: 'alice' };
+    redactForLogging(input);
+    assert.equal(input.password, 'keep-me');
+  });
+
+  // Regression: the auth state machine ships secrets as form-field
+  // descriptors `{ name: 'session', defaultValue: '<token>' }`. The secret
+  // sits under `defaultValue`, NOT under a key literally named `session`, so
+  // plain key-name redaction walks past it. These guard the descriptor branch.
+  it('redacts defaultValue of a sensitive AuthField descriptor', () => {
+    const out = redactForLogging({
+      name: 'session',
+      label: 'Session',
+      type: 'hidden',
+      defaultValue: 'COGNITO_SESSION_TOKEN',
+    }) as Record<string, unknown>;
+    assert.equal(out.name, 'session');
+    assert.equal(out.defaultValue, REDACTED);
+  });
+
+  it('redacts session + sharedSecret in a full confirmingSignIn AuthState', () => {
+    const authState = {
+      state: 'confirmingSignIn',
+      actions: [{
+        name: 'confirmSignIn',
+        label: 'Set Up Authenticator',
+        fields: [
+          { name: 'session', label: 'Session', type: 'hidden', required: true, defaultValue: 'SESSION_TOKEN_abc' },
+          { name: 'sharedSecret', label: 'Shared Secret', type: 'hidden', required: true, defaultValue: 'JBSWY3DPEHPK3PXP' },
+          { name: 'code', label: 'Code', type: 'text', required: true },
+        ],
+      }],
+    };
+    const json = JSON.stringify(redactForLogging(authState));
+    assert.ok(!json.includes('SESSION_TOKEN_abc'), 'session token must not leak');
+    assert.ok(!json.includes('JBSWY3DPEHPK3PXP'), 'TOTP shared secret must not leak');
+    // Non-secret descriptor fields are preserved for debuggability.
+    assert.ok(json.includes('confirmSignIn'));
+    assert.ok(json.includes('Set Up Authenticator'));
+  });
+
+  it('leaves defaultValue untouched for a non-sensitive field (e.g. echoed username)', () => {
+    const out = redactForLogging({
+      name: 'username',
+      type: 'hidden',
+      defaultValue: 'alice',
+    }) as Record<string, unknown>;
+    assert.equal(out.defaultValue, 'alice');
+  });
+
+  it('handles circular references', () => {
+    const a: Record<string, unknown> = { username: 'alice' };
+    a.self = a;
+    const out = redactForLogging(a) as Record<string, unknown>;
+    assert.equal(out.username, 'alice');
+    assert.equal(out.self, '[Circular]');
+  });
+
+  it('detects cycles nested deeper than the root', () => {
+    const root: Record<string, unknown> = { level: 1 };
+    const child: Record<string, unknown> = { level: 2, parent: root };
+    root.child = child;
+    const out = redactForLogging(root) as any;
+    assert.equal(out.child.level, 2);
+    assert.equal(out.child.parent, '[Circular]');
+  });
+
+  // Regression: `seen` must track the ancestor PATH, not every node ever
+  // visited. A shared (non-cyclic) reference reached twice via sibling
+  // branches must be emitted in full both times — a visited-set would wrongly
+  // flag the second one as '[Circular]' and drop real data from the log.
+  it('does not flag shared (non-circular) references as circular', () => {
+    const shared = { region: 'us-east-1', count: 2 };
+    const out = redactForLogging({ a: shared, b: shared }) as Record<string, unknown>;
+    assert.deepEqual(out.a, shared);
+    assert.deepEqual(out.b, shared);
+  });
+
+  it('emits a shared reference repeated in an array, not [Circular]', () => {
+    const shared = { id: 'x' };
+    const out = redactForLogging([shared, shared, shared]) as unknown[];
+    assert.deepEqual(out, [shared, shared, shared]);
+  });
+
+  it('still redacts secrets inside a shared reference each time', () => {
+    const shared = { username: 'u', password: 'secret' };
+    const out = redactForLogging({ first: shared, second: shared }) as any;
+    assert.equal(out.first.password, REDACTED);
+    assert.equal(out.second.password, REDACTED);
+    assert.equal(out.second.username, 'u');
+  });
+
+  // Regression: `code` is exact-match only, so substring siblings like
+  // statusCode/errorCode stay visible — they carry no secret and masking them
+  // defeats the debugging purpose of the logs.
+  it('redacts an exact `code` field but not `code`-substring fields', () => {
+    const out = redactForLogging({
+      code: '123456',
+      statusCode: 200,
+      errorCode: 'E_BAD',
+      countryCode: 'US',
+      zipCode: '98101',
+      qrCode: 'data:image/png',
+    }) as Record<string, unknown>;
+    assert.equal(out.code, REDACTED);
+    assert.equal(out.statusCode, 200);
+    assert.equal(out.errorCode, 'E_BAD');
+    assert.equal(out.countryCode, 'US');
+    assert.equal(out.zipCode, '98101');
+    assert.equal(out.qrCode, 'data:image/png');
+  });
+});
+
+describe('redactToJson', () => {
+  it('serializes a redacted copy', () => {
+    const json = redactToJson({ username: 'alice', password: 'hunter2' });
+    assert.equal(json, JSON.stringify({ username: 'alice', password: REDACTED }));
+  });
+
+  it('returns a safe placeholder on serialization failure', () => {
+    // BigInt is not JSON-serializable and survives redaction (not a sensitive key).
+    assert.equal(redactToJson({ big: 10n }), '[unserializable]');
+  });
+
+  it('does not leak secrets even when truncation would apply downstream', () => {
+    const json = redactToJson([{ action: 'signIn', username: 'u', password: 'p'.repeat(50) }]);
+    assert.ok(!json.includes('pppp'));
+    assert.ok(json.includes(REDACTED));
+  });
+
+  it('redacts secrets in a real JSON-RPC request body shape', () => {
+    const body = {
+      jsonrpc: '2.0',
+      method: 'authApi.setAuthState',
+      params: [{ action: 'signIn', username: 'a', password: 'hunter2' }],
+      id: 1,
+    };
+    const json = redactToJson(body);
+    assert.ok(!json.includes('hunter2'));
+    assert.ok(json.includes(REDACTED));
+    assert.ok(json.includes('setAuthState'), 'method name preserved for debugging');
+  });
+});

package/src/redact.ts

@@ -0,0 +1,143 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Sensitive-field redaction for logging.
+ *
+ * The dev server logs RPC request/response bodies to help debug cross-stack
+ * wire-format mismatches. Those bodies carry credentials (sign-in passwords,
+ * new-password challenge responses) and bearer-style secrets (Cognito challenge
+ * `session` tokens, MFA shared secrets, OTP codes). Logging them verbatim puts
+ * plaintext passwords and reusable tokens in the log stream. This module masks
+ * those fields before anything is logged, without mutating the value that
+ * actually flows over the wire.
+ *
+ * Two complementary rules, because auth payloads hide secrets two ways:
+ *
+ *  1. **Direct keys** — `{ password: '...', session: '...' }`. Redacted by
+ *     field NAME, matched case-insensitively (substring).
+ *
+ *  2. **Form-field descriptors** — the auth state machine ships secrets as
+ *     `{ name: 'session', defaultValue: '<token>' }` (see
+ *     `@aws-blocks/auth-common` AuthField). Here the secret sits under the
+ *     innocuous key `defaultValue`; the sensitive word is the *value* of a
+ *     sibling `name`. Rule 1 alone would walk straight past it. So when an
+ *     object carries a sensitive `name`, its `defaultValue` is redacted too.
+ *
+ * The wire payload is never altered — only the logged copy is scrubbed.
+ */
+
+/** The string substituted for any sensitive value. */
+export const REDACTED = '[REDACTED]' as const;
+
+/**
+ * Field-name fragments whose values must never be logged. Matched
+ * case-insensitively as a SUBSTRING, so prefixed/suffixed variants
+ * (`accessToken`, `refreshToken`, `idToken`, `apiKey`, `clientSecret`) all
+ * match without enumerating every spelling. Keep aligned with the auth action
+ * payloads in `@aws-blocks/auth-common` plus the generic credential vocabulary.
+ */
+const SENSITIVE_KEY_PARTS: readonly string[] = [
+  'password',
+  'session',
+  'token',
+  'secret',
+  'credential',
+  'apikey',
+  'authorization',
+];
+
+/**
+ * Field names that are sensitive only as an EXACT match. The OTP / verification
+ * code the auth state machine sends is literally named `code` (see
+ * `@aws-blocks/auth-common` confirmSignIn payloads). Matching it as a substring
+ * would mask innocuous fields like `statusCode`, `errorCode`, `countryCode`,
+ * `zipCode`, `qrCode` — log noise that defeats the debugging purpose of these
+ * logs without protecting anything. So `code` is exact-match only.
+ */
+const SENSITIVE_KEY_EXACT: ReadonlySet<string> = new Set(['code']);
+
+/**
+ * Whether a field name should be redacted: an exact-match against
+ * {@link SENSITIVE_KEY_EXACT}, or a case-insensitive substring match against
+ * {@link SENSITIVE_KEY_PARTS}.
+ */
+function isSensitiveKey(key: string): boolean {
+  const lower = key.toLowerCase();
+  if (SENSITIVE_KEY_EXACT.has(lower)) return true;
+  return SENSITIVE_KEY_PARTS.some((part) => lower.includes(part));
+}
+
+/**
+ * Return a deep copy of `value` with the value of every sensitive field
+ * replaced by {@link REDACTED}. Arrays and nested objects are walked; the
+ * input is never mutated. Circular references are emitted as `'[Circular]'`.
+ *
+ * Primitives are returned unchanged — only object/array *fields* are matched
+ * against the sensitive-key list, since a bare string has no field name to
+ * key off.
+ *
+ * `seen` tracks the current ancestor PATH, not every node ever visited: each
+ * node is added before its children are walked and removed afterwards. A
+ * plain visited-set would flag the second appearance of a *shared* (non-cyclic)
+ * reference as `'[Circular]'` — e.g. `{ a: shared, b: shared }` — silently
+ * dropping real data from the log. Only a reference still open on the stack is
+ * a genuine cycle.
+ */
+export function redactForLogging(value: unknown, seen: WeakSet<object> = new WeakSet()): unknown {
+  if (value === null || typeof value !== 'object') {
+    return value;
+  }
+
+  if (seen.has(value)) {
+    return '[Circular]';
+  }
+  seen.add(value);
+
+  let out: unknown;
+  if (Array.isArray(value)) {
+    out = value.map((item) => redactForLogging(item, seen));
+  } else {
+    const obj = value as Record<string, unknown>;
+
+    // Rule 2: form-field descriptor `{ name: <sensitive>, defaultValue: <secret> }`.
+    // The secret hides under `defaultValue` while the sensitive word is the value
+    // of `name` — so the direct-key pass below never sees it. Detect the shape and
+    // redact `defaultValue` explicitly.
+    const masksDefaultValue =
+      typeof obj.name === 'string'
+      && isSensitiveKey(obj.name)
+      && 'defaultValue' in obj;
+
+    const result: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(obj)) {
+      if (isSensitiveKey(key) || (key === 'defaultValue' && masksDefaultValue)) {
+        // Preserve presence/absence so logs still show the field was sent,
+        // without revealing it. Skip masking explicit null/undefined so an
+        // absent secret doesn't look like a populated one.
+        result[key] = val === null || val === undefined ? val : REDACTED;
+      } else {
+        result[key] = redactForLogging(val, seen);
+      }
+    }
+    out = result;
+  }
+
+  // Pop this node off the ancestor path now that its subtree is fully walked,
+  // so sibling branches can reference the same object without false `[Circular]`.
+  seen.delete(value);
+  return out;
+}
+
+/**
+ * Convenience for log call sites: redact `value` and serialize it to a JSON
+ * string. Returns a safe placeholder instead of throwing if serialization
+ * fails (e.g. a BigInt slips through), so logging can never crash a request.
+ */
+export function redactToJson(value: unknown): string {
+  try {
+    return JSON.stringify(redactForLogging(value));
+  } catch {
+    return '[unserializable]';
+  }
+}