@end-close/relay 0.12.0

package/src/forward/enrich.ts

@@ -0,0 +1,106 @@
+import { hardDenyDeep, keyNameIsSensitive } from '../mask/defaults.js'
+import type { Json } from '../mask/paths.js'
+
+// Host-supplied enrichments: named functions registered via createRelay({ enrichments })
+// and referenced from a route's map with `enrich: <name>`. They run in the host process
+// at dispatch time, after mapping and before the bulk POST. The engine never calls out
+// anywhere on their behalf; whatever a function does with its input is the host's code.
+
+export interface EnrichContext {
+  routeId: string
+  /** The route's processor adapter name, e.g. "payabli". */
+  source: string
+  /** Adapter-derived id, e.g. "ApprovedPayment:txn_1" (or "sha256:…" when unknown). */
+  eventId: string
+  eventType: string | null
+  receivedAt: string
+  /** Output field being computed: "metadata.<key>" or "description". */
+  field: string
+  /** The decrypted webhook payload, for inputs beyond the `source` value. */
+  payload: Json
+}
+
+/**
+ * Compute the value for one enriched field from the value at its `source` (after any
+ * transforms). Return `undefined` to omit the field and still send the record. Throw to
+ * retry the whole event later with backoff (the host's database was unavailable); throw
+ * `EnrichmentError` to park it instead (the input is bad and a retry cannot help).
+ */
+export type Enrichment = (input: Json, ctx: EnrichContext) => Json | undefined | Promise<Json | undefined>
+
+/** Enrichment cannot be applied to this event. Parks the event; never retried. */
+export class EnrichmentError extends Error {}
+
+export class EnrichTimeoutError extends Error {}
+
+function describe(value: unknown): string {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return 'an array'
+  if (typeof value === 'number') return `number ${String(value)}`
+  if (typeof value === 'object') return `a ${value.constructor?.name ?? 'non-plain object'}`
+  return `a ${typeof value}`
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object') return false
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
+
+function assertJson(value: unknown, path: string): void {
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') return
+  if (typeof value === 'number') {
+    if (Number.isFinite(value)) return
+    throw new EnrichmentError(`enriched value at "${path}" is not JSON (${describe(value)})`)
+  }
+  if (Array.isArray(value)) {
+    value.forEach((v, i) => assertJson(v, `${path}[${i}]`))
+    return
+  }
+  if (isPlainObject(value)) {
+    for (const [k, v] of Object.entries(value)) {
+      if (keyNameIsSensitive(k)) {
+        throw new EnrichmentError(
+          `enriched value at "${path}.${k}" matches the hard denylist (cvv/ssn/account number/...) and cannot be forwarded`,
+        )
+      }
+      assertJson(v, `${path}.${k}`)
+    }
+    return
+  }
+  throw new EnrichmentError(`enriched value at "${path}" is not JSON (${describe(value)})`)
+}
+
+/**
+ * Check what an enrichment returned before it may enter a record: JSON only (no
+ * undefined-in-objects, functions, NaN, class instances), no sensitive key names at any
+ * depth, and the hard denylist applied to every string. `undefined` means "omit".
+ */
+export function validateEnrichedValue(value: unknown, field: string): Json | undefined {
+  if (value === undefined) return undefined
+  assertJson(value, field)
+  return hardDenyDeep(value as Json)
+}
+
+/**
+ * Run a host callback under a deadline. A synchronous throw becomes a rejection; the timer
+ * is cleared on settle so it never keeps the process alive. A timed-out call is abandoned,
+ * not cancelled: hosts must treat enrichments as reads that may run more than once.
+ */
+export function withTimeout<T>(run: () => T | Promise<T>, ms: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new EnrichTimeoutError(`timed out after ${ms} ms`)), ms)
+    Promise.resolve()
+      .then(run)
+      .then(
+        (v) => {
+          clearTimeout(timer)
+          resolve(v)
+        },
+        (e: unknown) => {
+          clearTimeout(timer)
+          reject(e)
+        },
+      )
+  })
+}

package/src/forward/mapper.ts

@@ -0,0 +1,191 @@
+import { createHmac } from 'node:crypto'
+import {
+  refEnrichment,
+  refSource,
+  refTransforms,
+  type DateRef,
+  type EnrichableFieldRef,
+  type RouteConfig,
+  type TransformName,
+} from '../config/schema.js'
+import { hardDenyDeep } from '../mask/defaults.js'
+import { getAtPath, leafPaths, type Json } from '../mask/paths.js'
+import { escapeRe } from '../util/strings.js'
+
+export interface EndCloseRecord {
+  date: string
+  data_stream_key: string
+  amount: number
+  currency?: string
+  direction: 'credit' | 'debit'
+  description?: string
+  external_id: string
+  metadata: Record<string, Json>
+}
+
+export interface MapReport {
+  /** output field -> source path (values marked when transformed) */
+  mapped: Record<string, string>
+  hashed: string[]
+  /** output fields whose value comes from a host enrichment, filled at dispatch time */
+  enriched: string[]
+  /** payload leaf paths that do NOT leave the network */
+  not_forwarded: string[]
+}
+
+/** An enriched field mapEvent could not fill: the dispatcher runs the host function. */
+export interface PendingEnrichment {
+  /** "metadata.<key>" or "description" */
+  field: string
+  enrichment: string
+  /** The source value after transforms; what the enrichment receives. */
+  input: Json
+  source: string
+}
+
+export class MappingError extends Error {}
+
+/** "3,762.87" | "3762.87" | "$38.00" | 3762.87 → integer cents. */
+export function toCents(value: Json): number {
+  let s: string
+  if (typeof value === 'number') s = String(value)
+  else if (typeof value === 'string') s = value.replace(/[$,\s]/g, '')
+  else throw new MappingError(`amount is not a string or number: ${JSON.stringify(value)}`)
+  if (!/^-?\d+(\.\d{1,2})?$/.test(s)) throw new MappingError(`unparseable amount: ${s}`)
+  const negative = s.startsWith('-')
+  if (negative) s = s.slice(1)
+  const [whole = '0', frac = ''] = s.split('.')
+  const cents = Number(whole) * 100 + Number(frac.padEnd(2, '0') || '0')
+  return negative ? -cents : cents
+}
+
+/** Payabli transferTime arrives as "M/D/YYYY H:mm:ss"; End Close wants an ISO date. */
+export function parseDate(value: Json, format: 'iso8601' | 'mdy_hms'): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new MappingError(`date is not a string: ${JSON.stringify(value)}`)
+  }
+  if (format === 'mdy_hms') {
+    const m = value.match(/^(\d{1,2})\/(\d{1,2})\/(\d{4})(?:\s|$)/)
+    if (!m) throw new MappingError(`unparseable M/D/YYYY date: ${value}`)
+    return `${m[3]}-${m[1]!.padStart(2, '0')}-${m[2]!.padStart(2, '0')}`
+  }
+  const parsed = new Date(value)
+  if (Number.isNaN(parsed.getTime())) throw new MappingError(`unparseable date: ${value}`)
+  return parsed.toISOString().slice(0, 10)
+}
+
+function hashValue(maskingKey: Buffer, value: Json): string {
+  const raw = typeof value === 'string' ? value : JSON.stringify(value)
+  return 'hmac256:' + createHmac('sha256', maskingKey).update(raw, 'utf8').digest('hex')
+}
+
+/** trim/lowercase act on strings (elementwise over arrays from wildcard paths); hash consumes anything. */
+function applyTransform(name: TransformName, value: Json, maskingKey: Buffer): Json {
+  if (name === 'hash') return hashValue(maskingKey, value)
+  if (Array.isArray(value)) return value.map((v) => applyTransform(name, v, maskingKey))
+  if (typeof value !== 'string') return value
+  return name === 'trim' ? value.trim() : value.toLowerCase()
+}
+
+function resolve(ref: EnrichableFieldRef, payload: Json, maskingKey: Buffer): Json | undefined {
+  let value = getAtPath(payload, refSource(ref))
+  if (value === undefined) return undefined
+  for (const t of refTransforms(ref)) value = applyTransform(t, value, maskingKey)
+  return value
+}
+
+function dateSource(ref: DateRef): { source: string; format: 'iso8601' | 'mdy_hms' } {
+  return typeof ref === 'string' ? { source: ref, format: 'iso8601' } : ref
+}
+
+export interface MappedEvent {
+  /** Enriched fields are absent here until the dispatcher fills them. */
+  record: EndCloseRecord
+  report: MapReport
+  pending: PendingEnrichment[]
+}
+
+/**
+ * Map a webhook payload to an End Close record. Only fields named in the route's `map`
+ * block are forwarded — the map IS the allowlist. Every mapped value additionally passes
+ * through the hard denylist (PAN/SSN redaction), so no configuration can forward those
+ * in clear. This is the only place payload data crosses toward the network path.
+ */
+export function mapEvent(
+  route: RouteConfig,
+  payload: Json,
+  receivedAt: string,
+  maskingKey: Buffer,
+): MappedEvent {
+  const { map: m } = route
+  const report: MapReport = { mapped: {}, hashed: [], enriched: [], not_forwarded: [] }
+  const pending: PendingEnrichment[] = []
+  const usedPaths = new Set<string>()
+
+  const use = (field: string, ref: EnrichableFieldRef): Json | undefined => {
+    const value = resolve(ref, payload, maskingKey)
+    if (value === undefined) return undefined
+    const source = refSource(ref)
+    usedPaths.add(source)
+    const enrichment = refEnrichment(ref)
+    if (enrichment !== undefined) {
+      // The host fills this field later; the record leaves here without it.
+      report.mapped[field] = `${source} → enrich:${enrichment}`
+      report.enriched.push(field)
+      pending.push({ field, enrichment, input: value, source })
+      return undefined
+    }
+    report.mapped[field] = source
+    if (refTransforms(ref).includes('hash')) report.hashed.push(field)
+    return value
+  }
+
+  const externalId = use('external_id', m.external_id)
+  if (typeof externalId !== 'string' && typeof externalId !== 'number') {
+    throw new MappingError(`missing external id at ${refSource(m.external_id)}`)
+  }
+
+  const amount = toCents(use('amount', m.amount) ?? null)
+
+  let date: string
+  if (m.date) {
+    const { source, format } = dateSource(m.date)
+    date = parseDate(getAtPath(payload, source) ?? null, format)
+    report.mapped['date'] = source
+    usedPaths.add(source)
+  } else {
+    date = receivedAt.slice(0, 10)
+    report.mapped['date'] = '(receive time)'
+  }
+
+  const metadata: Record<string, Json> = {}
+  for (const [outputKey, ref] of Object.entries(m.metadata)) {
+    const value = use(`metadata.${outputKey}`, ref)
+    if (value !== undefined) metadata[outputKey] = hardDenyDeep(value)
+  }
+
+  const record: EndCloseRecord = {
+    date,
+    data_stream_key: m.data_stream_key,
+    amount,
+    direction: m.direction,
+    external_id: String(externalId),
+    metadata,
+  }
+  if (m.currency) record.currency = m.currency
+  if (m.description) {
+    const desc = use('description', m.description)
+    if (typeof desc === 'string') record.description = hardDenyDeep(desc)
+  }
+
+  // Everything in the payload that was not explicitly mapped stays local.
+  const wildcardPrefixes = [...usedPaths]
+    .filter((p) => p.includes('*'))
+    .map((p) => new RegExp('^' + p.split('.').map((s) => (s === '*' ? '[^.]+' : escapeRe(s))).join('\\.') + '$'))
+  report.not_forwarded = leafPaths(payload).filter(
+    (leaf) => !usedPaths.has(leaf) && !wildcardPrefixes.some((re) => re.test(leaf)),
+  )
+
+  return { record, report, pending }
+}
+

package/src/index.ts

@@ -0,0 +1,47 @@
+// @end-close/relay — the embeddable store-and-forward engine behind the End Close relay.
+
+export { createRelay, parseRoutes, assertKnownSources, assertKnownEnrichments, routeEnrichments } from './engine/relay.js'
+export type { Relay, RelayOptions, DispatchOnceResult, FlushResult } from './engine/relay.js'
+export type { DispatchCounts } from './forward/dispatcher.js'
+export { DEFAULT_DISPATCH, DEFAULT_RETENTION } from './engine/settings.js'
+export type { DispatchSettings, RetentionSettings } from './engine/settings.js'
+export type { IngestResult, IngestResultOutcome } from './engine/ingest.js'
+export { eventIdempotencyKey } from './engine/ingest.js'
+
+export * from './engine/store.js'
+export { MemoryEventStore, memoryStore } from './engine/memory-store.js'
+export { aesGcmCodec, plainCodec } from './engine/codec.js'
+export type { PayloadCodec } from './engine/codec.js'
+export { RelayHooks } from './engine/hooks.js'
+export type {
+  RelayEvents,
+  RelayEventName,
+  RelayHandler,
+  IngestOutcome,
+  ForwardResult,
+  EnrichOutcome,
+  EngineErrorKind,
+} from './engine/hooks.js'
+export { envSecrets, staticSecrets, hasSecret, requireSecret, SecretUnavailableError } from './engine/secrets.js'
+export type { SecretResolver } from './engine/secrets.js'
+export { noopLogger, consoleLogger } from './logger.js'
+export type { Logger, LogMeta } from './logger.js'
+
+export * from './config/schema.js'
+export { mapEvent, toCents, parseDate, MappingError } from './forward/mapper.js'
+export type { EndCloseRecord, MapReport, MappedEvent, PendingEnrichment } from './forward/mapper.js'
+export { EnrichmentError, EnrichTimeoutError, validateEnrichedValue, withTimeout } from './forward/enrich.js'
+export type { Enrichment, EnrichContext } from './forward/enrich.js'
+export { EndCloseClient, TransientHttpError, PermanentHttpError } from './forward/endclose-client.js'
+export type { BulkRequestSummary, BulkResultItem } from './forward/endclose-client.js'
+export { adapterFor, hasAdapter } from './ingest/adapters/registry.js'
+export { payabliAdapter } from './ingest/adapters/payabli.js'
+export { genericHmacAdapter } from './ingest/adapters/generic-hmac.js'
+export { headerValue } from './ingest/adapters/types.js'
+export type { ProcessorAdapter, RawRequest, VerifyContext, VerifyResult } from './ingest/adapters/types.js'
+export { hardDenyValue, hardDenyDeep, keyNameIsSensitive, REDACTED } from './mask/defaults.js'
+export { getAtPath, leafPaths } from './mask/paths.js'
+export type { Json } from './mask/paths.js'
+export { encrypt, decrypt } from './crypto/at-rest.js'
+export { deriveKey } from './crypto/keys.js'
+export { jsonTopLevelKeys, requestHeaderNames } from './util/payload-shape.js'

package/src/ingest/adapters/generic-hmac.ts

@@ -0,0 +1,70 @@
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto'
+import type { RouteConfig } from '../../config/schema.js'
+import { getAtPath, type Json } from '../../mask/paths.js'
+import {
+  headerValue,
+  type ProcessorAdapter,
+  type RawRequest,
+  type VerifyContext,
+  type VerifyResult,
+} from './types.js'
+
+// Generic HMAC-signature adapter: covers processors that sign `body` or `timestamp.body`
+// with a shared secret. Configuration lives entirely in the route's auth block, so most
+// future processors need no code.
+
+export const genericHmacAdapter: ProcessorAdapter = {
+  name: 'generic_hmac',
+
+  verify(req: RawRequest, route: RouteConfig, ctx: VerifyContext): VerifyResult {
+    if (route.auth.mode !== 'hmac') return { ok: false, reason: 'route auth mode mismatch' }
+    const auth = route.auth
+
+    let signedContent: Buffer = req.rawBody
+    if (auth.signed_content === 'timestamp.body') {
+      if (!auth.timestamp_header) return { ok: false, reason: 'timestamp_header not configured' }
+      const ts = headerValue(req.headers, auth.timestamp_header)
+      if (!ts) return { ok: false, reason: `missing ${auth.timestamp_header} header` }
+      const skew = Math.abs(Date.now() / 1000 - Number(ts))
+      if (!Number.isFinite(skew) || skew > auth.tolerance_seconds) {
+        return { ok: false, reason: 'stale timestamp' }
+      }
+      signedContent = Buffer.concat([Buffer.from(`${ts}.`, 'utf8'), req.rawBody])
+    }
+
+    const presented = headerValue(req.headers, auth.header)
+    if (!presented) return { ok: false, reason: `missing ${auth.header} header` }
+
+    const expectedHex = createHmac(auth.algorithm, ctx.secret).update(signedContent).digest('hex')
+    // Accept optional "sha256=" style prefixes.
+    const presentedHex = (presented.includes('=') && !/^[0-9a-f]+$/i.test(presented)
+      ? presented.slice(presented.indexOf('=') + 1)
+      : presented
+    ).toLowerCase()
+
+    const a = Buffer.from(expectedHex, 'utf8')
+    const b = Buffer.from(presentedHex, 'utf8')
+    if (a.length !== b.length) {
+      timingSafeEqual(a, a)
+      return { ok: false, reason: 'bad signature' }
+    }
+    if (!timingSafeEqual(a, b)) return { ok: false, reason: 'bad signature' }
+    return { ok: true }
+  },
+
+  extractEventId(body: Json, req: RawRequest, route: RouteConfig): string {
+    if (route.auth.mode === 'hmac' && route.auth.event_id) {
+      const id = getAtPath(body, route.auth.event_id)
+      if ((typeof id === 'string' && id.length > 0) || typeof id === 'number') return String(id)
+    }
+    return 'sha256:' + createHash('sha256').update(req.rawBody).digest('hex')
+  },
+
+  extractEventType(body: Json, _req: RawRequest, route: RouteConfig): string | null {
+    if (route.auth.mode === 'hmac' && route.auth.event_type) {
+      const t = getAtPath(body, route.auth.event_type)
+      return typeof t === 'string' ? t : null
+    }
+    return null
+  },
+}

package/src/ingest/adapters/payabli.ts

@@ -0,0 +1,67 @@
+import { createHash, timingSafeEqual } from 'node:crypto'
+import type { RouteConfig } from '../../config/schema.js'
+import { getAtPath, type Json } from '../../mask/paths.js'
+import {
+  headerValue,
+  type ProcessorAdapter,
+  type RawRequest,
+  type VerifyContext,
+  type VerifyResult,
+} from './types.js'
+
+// Payabli does not sign webhooks. Trust boundary: a customer-defined static header
+// (configured on the Payabli notification via webHeaderParameters) compared in constant
+// time, plus an optional source-IP allowlist (Payabli publishes one static IP per env:
+// sandbox 52.3.204.115, production 54.166.54.170).
+
+function constantTimeEquals(a: string, b: string): boolean {
+  const ab = Buffer.from(a, 'utf8')
+  const bb = Buffer.from(b, 'utf8')
+  if (ab.length !== bb.length) {
+    // Compare against self to keep timing independent of the mismatch position.
+    timingSafeEqual(ab, ab)
+    return false
+  }
+  return timingSafeEqual(ab, bb)
+}
+
+// Stable-ID field per payload Event type, per Payabli's OpenAPI webhook schemas.
+const EVENT_ID_PATHS: Record<string, string> = {
+  TransferFunded: 'transferId', // payout_batch_settlement_funded
+  PayOutBatchPaid: 'BatchId', // payout_batch_paid
+  ApprovedPayment: 'TransactionId', // transaction-level; field names pending the customer's sample
+}
+
+export const payabliAdapter: ProcessorAdapter = {
+  name: 'payabli',
+
+  verify(req: RawRequest, route: RouteConfig, ctx: VerifyContext): VerifyResult {
+    if (route.auth.mode !== 'static_header') {
+      return { ok: false, reason: 'route auth mode mismatch' }
+    }
+    if (route.auth.allowed_ips.length > 0 && !route.auth.allowed_ips.includes(req.remoteIp)) {
+      return { ok: false, reason: 'source ip not allowed' }
+    }
+    const presented = headerValue(req.headers, route.auth.header)
+    if (!presented) return { ok: false, reason: `missing ${route.auth.header} header` }
+    if (!constantTimeEquals(presented, ctx.secret)) return { ok: false, reason: 'bad auth header' }
+    return { ok: true }
+  },
+
+  extractEventId(body: Json, req: RawRequest): string {
+    const eventType = getAtPath(body, 'Event')
+    if (typeof eventType === 'string') {
+      const path = EVENT_ID_PATHS[eventType]
+      if (path) {
+        const id = getAtPath(body, path)
+        if (typeof id === 'string' && id.length > 0) return `${eventType}:${id}`
+      }
+    }
+    return 'sha256:' + createHash('sha256').update(req.rawBody).digest('hex')
+  },
+
+  extractEventType(body: Json): string | null {
+    const t = getAtPath(body, 'Event')
+    return typeof t === 'string' ? t : null
+  },
+}

package/src/ingest/adapters/registry.ts

@@ -0,0 +1,21 @@
+import type { ProcessorAdapter } from './types.js'
+import { payabliAdapter } from './payabli.js'
+import { genericHmacAdapter } from './generic-hmac.js'
+
+const adapters: Record<string, ProcessorAdapter> = {
+  payabli: payabliAdapter,
+  generic_hmac: genericHmacAdapter,
+}
+
+export function adapterFor(
+  source: string,
+  extra?: Record<string, ProcessorAdapter>,
+): ProcessorAdapter {
+  const adapter = extra?.[source] ?? adapters[source]
+  if (!adapter) throw new Error(`no adapter for source: ${source}`)
+  return adapter
+}
+
+export function hasAdapter(source: string, extra?: Record<string, ProcessorAdapter>): boolean {
+  return Boolean(extra?.[source] ?? adapters[source])
+}

package/src/ingest/adapters/types.ts

@@ -0,0 +1,33 @@
+import type { RouteConfig } from '../../config/schema.js'
+import type { Json } from '../../mask/paths.js'
+
+export interface RawRequest {
+  rawBody: Buffer
+  headers: Record<string, string | string[] | undefined>
+  remoteIp: string
+}
+
+export type VerifyResult = { ok: true } | { ok: false; reason: string }
+
+/** Resolved by the engine before verification so adapters stay pure and synchronous. */
+export interface VerifyContext {
+  /** The value of the route's `auth.secret_env` reference. */
+  secret: string
+}
+
+export interface ProcessorAdapter {
+  name: string
+  /** Verify authenticity over the raw bytes. Must be constant-time on secret comparisons. */
+  verify(req: RawRequest, route: RouteConfig, ctx: VerifyContext): VerifyResult
+  /** Stable per-event ID used for idempotency. Falls back to a raw-body hash. */
+  extractEventId(body: Json, req: RawRequest, route: RouteConfig): string
+  extractEventType(body: Json, req: RawRequest, route: RouteConfig): string | null
+}
+
+export function headerValue(
+  headers: Record<string, string | string[] | undefined>,
+  name: string,
+): string | undefined {
+  const v = headers[name.toLowerCase()]
+  return Array.isArray(v) ? v[0] : v
+}

package/src/logger.ts

@@ -0,0 +1,26 @@
+// Log metadata is restricted to scalars: there is deliberately no way to pass an object
+// (and therefore a payload) into a log line.
+export type LogMeta = Record<string, string | number | boolean | null | undefined>
+
+/** The logging contract the engine depends on. Any host can supply its own implementation. */
+export interface Logger {
+  debug(msg: string, meta?: LogMeta): void
+  info(msg: string, meta?: LogMeta): void
+  warn(msg: string, meta?: LogMeta): void
+  error(msg: string, meta?: LogMeta): void
+}
+
+export const noopLogger: Logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+}
+
+/** console-backed logger at warn level and above. */
+export const consoleLogger: Logger = {
+  debug: () => {},
+  info: () => {},
+  warn: (msg, meta) => console.warn(msg, meta ?? ''),
+  error: (msg, meta) => console.error(msg, meta ?? ''),
+}

package/src/mask/defaults.ts

@@ -0,0 +1,56 @@
+// Hard denylist: applied to every mapped value in every route, not configurable. If one
+// of these patterns fires on data a customer legitimately needs, the answer is a
+// deliberate code change here — never a config override.
+
+export const REDACTED = '[REDACTED]'
+
+const SENSITIVE_KEY_RE =
+  /(^|_|\b)(cvv2?|cvc|cid|pin|password|passwd|secret|api[-_]?key|private[-_]?key|access[-_]?token|refresh[-_]?token|ssn|social[-_]?security|routing[-_]?number|account[-_]?number)($|_|\b)/i
+
+export function keyNameIsSensitive(key: string): boolean {
+  // Split camelCase so e.g. RoutingNumber / accountNumber match the snake/word patterns.
+  const normalized = key.replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+  return SENSITIVE_KEY_RE.test(normalized)
+}
+
+const SSN_RE = /\b\d{3}-\d{2}-\d{4}\b/g
+// Digit runs (allowing space/dash separators) long enough to be a PAN.
+const PAN_CANDIDATE_RE = /\b\d(?:[ -]?\d){12,18}\b/g
+
+function luhnValid(digits: string): boolean {
+  let sum = 0
+  let double = false
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let d = digits.charCodeAt(i) - 48
+    if (double) {
+      d *= 2
+      if (d > 9) d -= 9
+    }
+    sum += d
+    double = !double
+  }
+  return sum % 10 === 0
+}
+
+/** Redact SSN patterns and Luhn-passing PANs inside string values. Returns the input unchanged when clean. */
+export function hardDenyValue(value: string): string {
+  let out = value.replace(SSN_RE, REDACTED)
+  out = out.replace(PAN_CANDIDATE_RE, (candidate) => {
+    const digits = candidate.replace(/[ -]/g, '')
+    if (digits.length >= 13 && digits.length <= 19 && luhnValid(digits)) return REDACTED
+    return candidate
+  })
+  return out
+}
+
+/** Recursively apply hardDenyValue to every string inside a mapped JSON value. */
+export function hardDenyDeep<T>(value: T): T {
+  if (typeof value === 'string') return hardDenyValue(value) as T
+  if (Array.isArray(value)) return value.map(hardDenyDeep) as T
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([k, v]) => [k, hardDenyDeep(v)]),
+    ) as T
+  }
+  return value
+}

package/src/mask/paths.ts

@@ -0,0 +1,36 @@
+// Dot-notation paths into JSON documents: "batchId", "batch.id", "transactions.*.id".
+// A `*` segment fans out over every array element (or object value) and the result is
+// the array of matches.
+
+export type Json = null | boolean | number | string | Json[] | { [k: string]: Json }
+
+export function getAtPath(doc: Json, path: string): Json | undefined {
+  return getSegments(doc, path.split('.'))
+}
+
+function getSegments(node: Json, segments: string[]): Json | undefined {
+  if (segments.length === 0) return node
+  const [head, ...rest] = segments
+  if (node === null || typeof node !== 'object') return undefined
+  if (head === '*') {
+    const children = Array.isArray(node) ? node : Object.values(node)
+    const out = children
+      .map((c) => getSegments(c, rest))
+      .filter((v): v is Json => v !== undefined)
+    return out
+  }
+  const child = Array.isArray(node)
+    ? node[Number(head)]
+    : (node as { [k: string]: Json })[head!]
+  return child === undefined ? undefined : getSegments(child, rest)
+}
+
+/** All leaf paths of a document, dot-notation — used for the "not forwarded" report. */
+export function leafPaths(doc: Json, prefix = ''): string[] {
+  if (doc === null || typeof doc !== 'object') return prefix ? [prefix] : []
+  const entries = Array.isArray(doc)
+    ? doc.map((v, i) => [String(i), v] as const)
+    : Object.entries(doc)
+  if (entries.length === 0) return prefix ? [prefix] : []
+  return entries.flatMap(([k, v]) => leafPaths(v, prefix ? `${prefix}.${k}` : k))
+}

package/src/util/payload-shape.ts

@@ -0,0 +1,19 @@
+import type { Json } from '../mask/paths.js'
+
+/** Comma-sorted top-level keys of a JSON object — safe for logs (no values). */
+export function jsonTopLevelKeys(value: Json | unknown): string {
+  if (value === null || typeof value !== 'object') return typeof value
+  if (Array.isArray(value)) return '(array)'
+  return Object.keys(value).sort().join(',')
+}
+
+/** Comma-sorted request header names, excluding auth/secret headers. */
+export function requestHeaderNames(headers: Record<string, unknown>): string {
+  return Object.keys(headers)
+    .filter((h) => {
+      const n = h.toLowerCase()
+      return n !== 'authorization' && !n.includes('secret') && !n.includes('api-key')
+    })
+    .sort()
+    .join(',')
+}