@agilno-tech/rivet 0.1.0-alpha.0

package/src/state/lock.js

@@ -0,0 +1,266 @@
+import { constants } from 'node:fs';
+import { lstat, open, unlink } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { randomUUID } from 'node:crypto';
+
+const MAX_LOCK_BYTES = 4 * 1024;
+const DEFAULT_STALE_AFTER_MS = 5 * 60 * 1000;
+const MAX_INITIALIZATION_GRACE_MS = 5_000;
+const NOFOLLOW = constants.O_NOFOLLOW ?? 0;
+
+export class LockBusyError extends Error {
+  constructor(message = 'State lock is held by another owner') {
+    super(message);
+    this.name = 'LockBusyError';
+    this.code = 'ERR_STATE_LOCKED';
+  }
+}
+
+export class StaleLockError extends Error {
+  constructor() {
+    super('Stale state lock requires an explicit recovery command');
+    this.name = 'StaleLockError';
+    this.code = 'ERR_STALE_STATE_LOCK';
+  }
+}
+
+function sameIdentity(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+function privateRegularFile(metadata) {
+  return metadata.isFile()
+    && !metadata.isSymbolicLink()
+    && metadata.nlink === 1
+    && (metadata.mode & 0o777) === 0o600;
+}
+
+function validOwner(record) {
+  return record
+    && typeof record === 'object'
+    && Object.keys(record).length === 4
+    && Number.isSafeInteger(record.pid)
+    && record.pid > 0
+    && typeof record.host === 'string'
+    && record.host.length > 0
+    && record.host.length <= 255
+    && typeof record.timestamp === 'string'
+    && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(record.timestamp)
+    && Number.isFinite(Date.parse(record.timestamp))
+    && typeof record.ownerId === 'string'
+    && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(record.ownerId);
+}
+
+async function readBoundedUtf8(handle, maximumBytes) {
+  const buffer = Buffer.alloc(maximumBytes + 1);
+  let offset = 0;
+  while (offset < buffer.length) {
+    const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, null);
+    if (bytesRead === 0) break;
+    offset += bytesRead;
+  }
+  if (offset > maximumBytes) throw new Error('Unsafe state lock file');
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, offset));
+  } catch {
+    throw new Error('Unsafe state lock file');
+  }
+}
+
+function validateTiming(options = {}) {
+  const staleAfterMs = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+  const now = options.now ?? Date.now;
+  if (!Number.isSafeInteger(staleAfterMs) || staleAfterMs <= 0 || staleAfterMs > 24 * 60 * 60 * 1000) {
+    throw new TypeError('Invalid state lock expiry');
+  }
+  if (typeof now !== 'function') throw new TypeError('Invalid state lock clock');
+  const nowMs = now();
+  if (!Number.isSafeInteger(nowMs) || nowMs < 0) throw new TypeError('Invalid state lock clock');
+  return { staleAfterMs, nowMs };
+}
+
+async function inspectLock(path) {
+  let before;
+  try {
+    before = await lstat(path);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+  if (!privateRegularFile(before) || before.size <= 0 || before.size > MAX_LOCK_BYTES) {
+    throw new Error('Unsafe state lock file');
+  }
+
+  let handle;
+  try {
+    handle = await open(path, constants.O_RDONLY | NOFOLLOW);
+    const opened = await handle.stat();
+    if (!sameIdentity(before, opened) || !privateRegularFile(opened)) throw new Error('Unsafe state lock file');
+    const source = await readBoundedUtf8(handle, MAX_LOCK_BYTES);
+    const after = await lstat(path);
+    if (!privateRegularFile(after) || !sameIdentity(opened, after) || after.size !== opened.size) {
+      throw new Error('State lock identity changed');
+    }
+    let owner;
+    try {
+      owner = JSON.parse(source);
+    } catch {
+      throw new Error('Unsafe state lock file');
+    }
+    if (!validOwner(owner)) throw new Error('Unsafe state lock file');
+    return { owner, metadata: after };
+  } finally {
+    await handle?.close();
+  }
+}
+
+async function initializingLock(path, staleAfterMs) {
+  try {
+    const metadata = await lstat(path);
+    const ageMs = Date.now() - metadata.mtimeMs;
+    return privateRegularFile(metadata)
+      && metadata.size <= MAX_LOCK_BYTES
+      && ageMs >= -1_000
+      && ageMs < Math.min(staleAfterMs, MAX_INITIALIZATION_GRACE_MS);
+  } catch (error) {
+    return error.code === 'ENOENT' ? null : false;
+  }
+}
+
+function stale(record, nowMs, staleAfterMs) {
+  const timestamp = Date.parse(record.timestamp);
+  if (timestamp > nowMs + 1_000) throw new Error('Unsafe state lock timestamp');
+  return nowMs - timestamp >= staleAfterMs;
+}
+
+async function removeOwnedLock(path, expectedOwnerId, expectedMetadata) {
+  const inspected = await inspectLock(path);
+  if (!inspected
+    || inspected.owner.ownerId !== expectedOwnerId
+    || !sameIdentity(inspected.metadata, expectedMetadata)) {
+    throw new Error('State lock ownership changed');
+  }
+  await unlink(path);
+}
+
+async function removeIfIdentityMatches(path, expectedMetadata) {
+  try {
+    const metadata = await lstat(path);
+    if (privateRegularFile(metadata) && sameIdentity(metadata, expectedMetadata)) await unlink(path);
+  } catch {}
+}
+
+export async function acquireLock(path, options = {}) {
+  const { staleAfterMs, nowMs } = validateTiming(options);
+  const owner = {
+    pid: process.pid,
+    host: hostname().slice(0, 255) || 'unknown-host',
+    timestamp: new Date(nowMs).toISOString(),
+    ownerId: randomUUID(),
+  };
+  let handle;
+  try {
+    handle = await open(
+      path,
+      constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | NOFOLLOW,
+      0o600,
+    );
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    let inspected;
+    try {
+      inspected = await inspectLock(path);
+    } catch (inspectionError) {
+      const initializing = await initializingLock(path, staleAfterMs);
+      if (initializing === null) return acquireLock(path, options);
+      if (initializing) throw new LockBusyError('State lock is initializing');
+      throw inspectionError;
+    }
+    if (!inspected) return acquireLock(path, options);
+    if (stale(inspected.owner, nowMs, staleAfterMs)) throw new StaleLockError();
+    throw new LockBusyError();
+  }
+
+  let created;
+  try {
+    created = await handle.stat();
+    await handle.chmod(0o600);
+    await handle.writeFile(`${JSON.stringify(owner)}\n`, { encoding: 'utf8' });
+    await handle.sync();
+    const metadata = await handle.stat();
+    if (!privateRegularFile(metadata)) throw new Error('Unsafe state lock file');
+    let released = false;
+    return Object.freeze({
+      owner: Object.freeze({ ...owner }),
+      async release() {
+        if (released) return;
+        await removeOwnedLock(path, owner.ownerId, metadata);
+        released = true;
+      },
+    });
+  } catch (error) {
+    if (created) await removeIfIdentityMatches(path, created);
+    throw error;
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function recoverStaleLock(path, options = {}) {
+  const { staleAfterMs, nowMs } = validateTiming(options);
+  const inspected = await inspectLock(path);
+  if (!inspected) return false;
+  if (!stale(inspected.owner, nowMs, staleAfterMs)) throw new LockBusyError();
+  await removeOwnedLock(path, inspected.owner.ownerId, inspected.metadata);
+  return true;
+}
+
+function requireDeadLocalOwner(owner) {
+  if (owner.host !== hostname()) throw new LockBusyError('Cannot recover a lock from another host');
+  try {
+    process.kill(owner.pid, 0);
+  } catch (error) {
+    if (error.code === 'ESRCH') return;
+    throw new LockBusyError('Cannot establish that the lock owner exited');
+  }
+  throw new LockBusyError('State lock owner is still running');
+}
+
+/**
+ * Recover only an abandoned local lock. Unlike legacy recoverStaleLock, age alone
+ * never grants recovery. The permanent per-owner claim serializes all recoverers
+ * that observed that owner, including a recoverer delayed past a new acquisition.
+ * An interrupted claim deliberately needs manual investigation; do not remove it
+ * automatically. This assumes participants use this recovery protocol (not legacy
+ * age-only recovery) and a private directory, not arbitrary external replacement.
+ */
+export async function recoverAbandonedLock(path, options = {}) {
+  const { nowMs } = validateTiming({ now: options.now });
+  const inspected = await inspectLock(path);
+  if (!inspected) return false;
+  if (!stale(inspected.owner, nowMs, DEFAULT_STALE_AFTER_MS)) throw new LockBusyError();
+  requireDeadLocalOwner(inspected.owner);
+  const claimPath = `${path}.recovered-${inspected.owner.ownerId}`;
+  let claim;
+  try {
+    claim = await open(claimPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | NOFOLLOW, 0o600);
+  } catch (error) {
+    if (error.code === 'EEXIST') throw new LockBusyError('Lock recovery was already claimed; manual investigation required');
+    throw error;
+  }
+  try {
+    await claim.chmod(0o600);
+    await claim.writeFile(`${JSON.stringify(inspected.owner)}\n`, { encoding: 'utf8' });
+    await claim.sync();
+  } finally {
+    await claim.close();
+  }
+  // Recheck identity, owner, file safety and liveness after winning the claim.
+  // No other conforming recoverer can unlink this owner, and its process is dead.
+  const current = await inspectLock(path);
+  if (!current || current.owner.ownerId !== inspected.owner.ownerId
+      || !sameIdentity(current.metadata, inspected.metadata)) throw new Error('State lock ownership changed');
+  requireDeadLocalOwner(current.owner);
+  await removeOwnedLock(path, inspected.owner.ownerId, inspected.metadata);
+  return true;
+}

package/src/state/paths.js

@@ -0,0 +1,274 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, realpath, readdir } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+
+import { runArgv } from '../discovery/tools.js';
+
+const INSTANCE_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const resolvedStatePaths = new WeakSet();
+const statePathIdentities = new WeakMap();
+const NOFOLLOW = constants.O_NOFOLLOW ?? 0;
+const DIRECTORY = constants.O_DIRECTORY ?? 0;
+
+export class UnsupportedStatePlatformError extends Error {
+  constructor(platform) {
+    super('Private orchestration state requires enforceable owner-only filesystem permissions');
+    this.name = 'UnsupportedStatePlatformError';
+    this.code = 'ERR_PRIVATE_STATE_UNSUPPORTED_PLATFORM';
+    this.platform = platform;
+  }
+}
+
+function isWithin(parent, candidate) {
+  const path = relative(parent, candidate);
+  return path === '' || (!path.startsWith('..') && !isAbsolute(path));
+}
+
+async function createPrivateDirectory(candidate, gitCommonDir) {
+  try {
+    await mkdir(candidate, { mode: 0o700 });
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+  }
+
+  const resolved = await realpath(candidate);
+  if (!isWithin(gitCommonDir, resolved)) {
+    throw new Error('Private state path resolves outside the Git common directory');
+  }
+  const metadata = await lstat(candidate);
+  if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+    throw new Error('Private state path is unsafe');
+  }
+  let handle;
+  try {
+    handle = await open(candidate, constants.O_RDONLY | DIRECTORY | NOFOLLOW);
+    const opened = await handle.stat();
+    if (opened.dev !== metadata.dev || opened.ino !== metadata.ino || !opened.isDirectory()) {
+      throw new Error('Private state path identity changed');
+    }
+    await handle.chmod(0o700);
+    const secured = await handle.stat();
+    const after = await lstat(candidate);
+    if (
+      secured.dev !== opened.dev
+      || secured.ino !== opened.ino
+      || after.dev !== secured.dev
+      || after.ino !== secured.ino
+      || (secured.mode & 0o777) !== 0o700
+    ) {
+      throw new Error('Private state path identity changed');
+    }
+  } finally {
+    await handle?.close();
+  }
+  return resolved;
+}
+
+async function existingPrivateDirectory(candidate, gitCommonDir) {
+  let metadata;
+  try { metadata = await lstat(candidate); }
+  catch (error) { if (error?.code === 'ENOENT') return false; throw error; }
+  if (!metadata.isDirectory() || metadata.isSymbolicLink() || (metadata.mode & 0o777) !== 0o700
+    || !isWithin(gitCommonDir, await realpath(candidate))) {
+    throw new Error('Private state path is unsafe');
+  }
+  return true;
+}
+
+async function resolveGitCommonDirectory(projectRoot, options, platformError) {
+  const platform = process.platform === 'win32' ? 'win32' : (options.platform ?? process.platform);
+  if (platform === 'win32') throw new UnsupportedStatePlatformError(platform);
+  const cwd = resolve(projectRoot);
+  const runner = options.runner ?? runArgv;
+  const result = await runner('git', ['rev-parse', '--git-common-dir'], {
+    cwd,
+    shell: false,
+    timeoutMs: 3_000,
+    maxOutputBytes: 4 * 1024,
+  });
+  const output = typeof result?.stdout === 'string' ? result.stdout.trim() : '';
+  if (result?.code !== 0 || result?.timedOut || result?.truncated?.stdout || !output || output.includes('\0') || /[\r\n]/.test(output)) {
+    throw new Error(platformError);
+  }
+  const unresolvedCommonDir = isAbsolute(output) ? output : resolve(cwd, output);
+  const gitCommonDir = await realpath(unresolvedCommonDir);
+  const commonMetadata = await lstat(gitCommonDir);
+  if (!commonMetadata.isDirectory()) throw new Error('Git common directory is unsafe');
+  return gitCommonDir;
+}
+
+function registerPaths(paths) {
+  resolvedStatePaths.add(paths);
+  return Promise.all([lstat(paths.stateRoot), lstat(paths.instanceDir)]).then(([stateRoot, instanceDir]) => {
+    statePathIdentities.set(paths, { stateRoot, instanceDir });
+    return paths;
+  });
+}
+
+export async function resolveStatePaths(projectRoot, instance, options = {}) {
+  if (typeof instance !== 'string' || instance.length > 64 || !INSTANCE_ID.test(instance)) {
+    throw new TypeError('Invalid state instance identifier');
+  }
+  const gitCommonDir = await resolveGitCommonDirectory(projectRoot, options, 'Unable to resolve the Git common directory');
+
+  const stateRoot = await createPrivateDirectory(join(gitCommonDir, 'rivet'), gitCommonDir);
+  const instanceDir = await createPrivateDirectory(join(stateRoot, instance), gitCommonDir);
+  if (!isWithin(stateRoot, instanceDir)) throw new Error('Private state path is unsafe');
+
+  const paths = Object.freeze({
+    gitCommonDir,
+    stateRoot,
+    instanceDir,
+    eventsPath: join(instanceDir, 'events.jsonl'),
+    snapshotPath: join(instanceDir, 'snapshot.json'),
+    lockPath: join(instanceDir, 'state.lock'),
+    runtimeLockPath: join(instanceDir, 'runtime.lock'),
+  });
+  return registerPaths(paths);
+}
+
+export async function resolveFeatureRunPaths(projectRoot, runId, options = {}) {
+  if (typeof runId !== 'string' || runId.length > 64 || !INSTANCE_ID.test(runId)) {
+    throw new TypeError('Invalid feature run identifier');
+  }
+  const gitCommonDir = await resolveGitCommonDirectory(projectRoot, options, 'Unable to resolve the Git common directory');
+  const featureRoot = await createPrivateDirectory(join(gitCommonDir, 'rivet'), gitCommonDir);
+  const featureRunsRoot = await createPrivateDirectory(join(featureRoot, 'feature-runs'), gitCommonDir);
+  const runDir = await createPrivateDirectory(join(featureRunsRoot, runId), gitCommonDir);
+  if (!isWithin(featureRunsRoot, runDir)) throw new Error('Private feature run path is unsafe');
+  const paths = Object.freeze({
+    gitCommonDir,
+    featureRoot,
+    featureRunsRoot,
+    runId,
+    runDir,
+    stateRoot: featureRunsRoot,
+    instanceDir: runDir,
+    snapshotPath: join(runDir, 'run.json'),
+    lockPath: join(runDir, 'run.lock'),
+  });
+  return registerPaths(paths);
+}
+
+export async function resolveExistingFeatureRunPaths(projectRoot, runId, options = {}) {
+  if (typeof runId !== 'string' || runId.length > 64 || !INSTANCE_ID.test(runId)) {
+    throw new TypeError('Invalid feature run identifier');
+  }
+  const gitCommonDir = await resolveGitCommonDirectory(projectRoot, options, 'Unable to resolve the Git common directory');
+  const featureRoot = join(gitCommonDir, 'rivet');
+  const featureRunsRoot = join(featureRoot, 'feature-runs');
+  const runDir = join(featureRunsRoot, runId);
+  for (const path of [featureRoot, featureRunsRoot, runDir]) {
+    if (!(await existingPrivateDirectory(path, gitCommonDir))) return null;
+  }
+  return registerPaths(Object.freeze({
+    gitCommonDir, featureRoot, featureRunsRoot, runId, runDir,
+    stateRoot: featureRunsRoot, instanceDir: runDir,
+    snapshotPath: join(runDir, 'run.json'), lockPath: join(runDir, 'run.lock'),
+  }));
+}
+
+export async function listExistingFeatureRunPaths(projectRoot, options = {}) {
+  const gitCommonDir = await resolveGitCommonDirectory(projectRoot, options, 'Unable to resolve the Git common directory');
+  const featureRoot = join(gitCommonDir, 'rivet');
+  const featureRunsRoot = join(featureRoot, 'feature-runs');
+  if (!(await existingPrivateDirectory(featureRoot, gitCommonDir))
+    || !(await existingPrivateDirectory(featureRunsRoot, gitCommonDir))) return Object.freeze([]);
+  const entries = await readdir(featureRunsRoot);
+  if (entries.length > 256 || entries.some(name => !INSTANCE_ID.test(name) || name.length > 64)) {
+    throw new Error('Private feature-run directory contains invalid or excessive entries');
+  }
+  const paths = [];
+  for (const name of entries.sort()) {
+    const value = await resolveExistingFeatureRunPaths(projectRoot, name, options);
+    if (value === null) throw new Error('Private feature-run state changed during discovery');
+    paths.push(value);
+  }
+  return Object.freeze(paths);
+}
+
+export async function resolveExistingStatePaths(projectRoot, instance, options = {}) {
+  if (typeof instance !== 'string' || instance.length > 64 || !INSTANCE_ID.test(instance)) {
+    throw new TypeError('Invalid state instance identifier');
+  }
+  const gitCommonDir = await resolveGitCommonDirectory(projectRoot, options, 'Unable to resolve the Git common directory');
+  const stateRoot = join(gitCommonDir, 'rivet');
+  const instanceDir = join(stateRoot, instance);
+  for (const path of [stateRoot, instanceDir]) {
+    if (!(await existingPrivateDirectory(path, gitCommonDir))) return null;
+  }
+  return registerPaths(Object.freeze({
+    gitCommonDir, stateRoot, instanceDir,
+    eventsPath: join(instanceDir, 'events.jsonl'),
+    snapshotPath: join(instanceDir, 'snapshot.json'),
+    lockPath: join(instanceDir, 'state.lock'),
+    runtimeLockPath: join(instanceDir, 'runtime.lock'),
+  }));
+}
+
+export function verificationReportPaths(featurePaths) {
+  assertResolvedStatePaths(featurePaths);
+  if (featurePaths.runDir !== featurePaths.instanceDir) throw new TypeError('Invalid feature run paths');
+  return registerPaths(Object.freeze({
+    ...featurePaths,
+    snapshotPath: join(featurePaths.runDir, 'verification.json'),
+    lockPath: join(featurePaths.runDir, 'verification.lock'),
+  }));
+}
+
+export function deliveryRecordPaths(featurePaths) {
+  assertResolvedStatePaths(featurePaths);
+  if (featurePaths.runDir !== featurePaths.instanceDir) throw new TypeError('Invalid feature run paths');
+  return registerPaths(Object.freeze({
+    ...featurePaths,
+    snapshotPath: join(featurePaths.runDir, 'delivery.json'),
+    lockPath: join(featurePaths.runDir, 'delivery.lock'),
+    operationLockPath: join(featurePaths.runDir, 'delivery-operation.lock'),
+  }));
+}
+
+export function acceptedIntegrationPaths(featurePaths) {
+  assertResolvedStatePaths(featurePaths);
+  if (featurePaths.runDir !== featurePaths.instanceDir) throw new TypeError('Invalid feature run paths');
+  return registerPaths(Object.freeze({
+    ...featurePaths,
+    snapshotPath: join(featurePaths.runDir, 'accepted-integration.json'),
+    lockPath: join(featurePaths.runDir, 'accepted-integration.lock'),
+  }));
+}
+
+export function assertResolvedStatePaths(paths) {
+  if (!paths || typeof paths !== 'object' || !resolvedStatePaths.has(paths)) {
+    throw new TypeError('State storage requires verified private state paths');
+  }
+}
+
+function sameIdentity(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+export async function verifyResolvedStatePaths(paths) {
+  assertResolvedStatePaths(paths);
+  const expected = statePathIdentities.get(paths);
+  const [stateRoot, instanceDir, resolvedRoot, resolvedInstance] = await Promise.all([
+    lstat(paths.stateRoot),
+    lstat(paths.instanceDir),
+    realpath(paths.stateRoot),
+    realpath(paths.instanceDir),
+  ]);
+  if (
+    !stateRoot.isDirectory()
+    || stateRoot.isSymbolicLink()
+    || !instanceDir.isDirectory()
+    || instanceDir.isSymbolicLink()
+    || (stateRoot.mode & 0o777) !== 0o700
+    || (instanceDir.mode & 0o777) !== 0o700
+    || !sameIdentity(stateRoot, expected.stateRoot)
+    || !sameIdentity(instanceDir, expected.instanceDir)
+    || resolvedRoot !== paths.stateRoot
+    || resolvedInstance !== paths.instanceDir
+    || !isWithin(paths.gitCommonDir, resolvedInstance)
+  ) {
+    throw new Error('Private state path identity changed');
+  }
+}

package/src/state/redact.js

@@ -0,0 +1,106 @@
+export const REDACTED = '[REDACTED]';
+
+const SENSITIVE_KEY = /(?:^|[-_])(?:password|passwd|secret|api[-_]?key|access[-_]?key|private[-_]?key|authorization|cookie|credential|access[-_]?token|api[-_]?token|auth[-_]?token|token)(?:$|[-_])/i;
+const SENSITIVE_ENVIRONMENT_KEY = /(?:^|_)(?:API_KEY|ACCESS_KEY|PRIVATE_KEY|KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIALS?|AUTH(?:ORIZATION)?)(?:_|$)/i;
+const SAFE_KEYS = new Set(['token_limit', 'api_token_env', 'access_token_env', 'token_env', 'username_env']);
+// Gemini usage metadata is numeric accounting, never credential content. Exact
+// keys and integer values only; configured secret keys always take precedence.
+const NUMERIC_USAGE_KEYS = new Set(['promptTokenCount', 'candidatesTokenCount', 'thoughtsTokenCount']);
+const TOKEN_PATTERNS = [
+  /\b(?:Bearer|Basic)\s+[A-Za-z0-9+/_.:=-]+/gi,
+  /\bgithub_pat_[A-Za-z0-9_]{8,}\b/g,
+  /\bgh[pousr]_[A-Za-z0-9]{8,}\b/g,
+  /\bxox[baprs]-[A-Za-z0-9-]{8,}\b/g,
+  /\bsk-[A-Za-z0-9_-]{8,}\b/g,
+  /\bAKIA[0-9A-Z]{16}\b/g,
+];
+
+function normalizedKey(key) {
+  return String(key)
+    .normalize('NFKC')
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .toLowerCase();
+}
+
+function sensitiveEnvironmentValues(environment) {
+  return [...new Set(Object.entries(environment ?? {})
+    .filter(([key, value]) => (
+      SENSITIVE_ENVIRONMENT_KEY.test(key)
+      && typeof value === 'string'
+      && value.length > 0
+    ))
+    .map(([, value]) => value))]
+    .sort((left, right) => right.length - left.length);
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function redactString(value, environmentValues) {
+  let result = value;
+  if (environmentValues.length > 0) {
+    result = result.replace(new RegExp(environmentValues.map(escapeRegExp).join('|'), 'g'), REDACTED);
+  }
+  for (const pattern of TOKEN_PATTERNS) result = result.replace(pattern, REDACTED);
+  return result;
+}
+
+function isSensitiveKey(key, configuredKeys) {
+  const normalized = normalizedKey(key);
+  if (configuredKeys.has(normalized)) return true;
+  if (SAFE_KEYS.has(normalized)) return false;
+  return SENSITIVE_KEY.test(normalized);
+}
+
+function redactValue(value, context, active) {
+  if (value === null || typeof value === 'boolean') return value;
+  if (typeof value === 'string') return redactString(value, context.environmentValues);
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new TypeError('State values must be JSON-compatible');
+    return value;
+  }
+  if (typeof value !== 'object') throw new TypeError('State values must be JSON-compatible');
+  if (active.has(value)) throw new TypeError('Cannot redact a cyclic value');
+
+  const prototype = Object.getPrototypeOf(value);
+  if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) {
+    throw new TypeError('State values must be JSON-compatible');
+  }
+
+  active.add(value);
+  try {
+    if (Array.isArray(value)) return value.map(item => redactValue(item, context, active));
+    const result = {};
+    for (const key of Reflect.ownKeys(value)) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (typeof key !== 'string' || !descriptor?.enumerable || !Object.hasOwn(descriptor, 'value')) {
+        throw new TypeError('State values must be JSON-compatible');
+      }
+      const safeUsageCount = NUMERIC_USAGE_KEYS.has(key)
+        && Number.isSafeInteger(descriptor.value) && descriptor.value >= 0
+        && !context.configuredKeys.has(normalizedKey(key));
+      const child = isSensitiveKey(key, context.configuredKeys) && !safeUsageCount
+        ? REDACTED
+        : redactValue(descriptor.value, context, active);
+      Object.defineProperty(result, key, {
+        value: child,
+        enumerable: true,
+        configurable: true,
+        writable: true,
+      });
+    }
+    return result;
+  } finally {
+    active.delete(value);
+  }
+}
+
+export function redactSecrets(value, options = {}) {
+  const configuredKeys = new Set((options.secretKeys ?? []).map(normalizedKey));
+  const environment = options.environment ?? process.env;
+  return redactValue(value, {
+    configuredKeys,
+    environmentValues: sensitiveEnvironmentValues(environment),
+  }, new WeakSet());
+}