@pikku/core 0.12.107 → 0.12.111

package/src/classification/secret-value.test.ts

@@ -1,204 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-import {
-  createSecretValue,
-  isSecretValue,
-  REDACTED,
-  SecretCoercionError,
-  type Safe,
-  type SecretValue,
-} from './secret-value.js'
-import type { Logger } from '../services/logger.js'
-import type { AuditLog } from '../services/audit-service.js'
-
-const VALUE = 'sk-live-DEADBEEF'
-
-describe('SecretValue', () => {
-  test('reveals the value', () => {
-    assert.equal(createSecretValue(VALUE).reveal(), VALUE)
-  })
-
-  test('unwraps object secrets whole', () => {
-    const creds = createSecretValue({ apiKey: 'k', apiSecret: 's' })
-    assert.deepEqual(creds.reveal(), { apiKey: 'k', apiSecret: 's' })
-  })
-
-  test('is recognisable at runtime', () => {
-    assert.equal(isSecretValue(createSecretValue(VALUE)), true)
-    assert.equal(
-      isSecretValue(() => VALUE),
-      false
-    )
-    assert.equal(isSecretValue(VALUE), false)
-    assert.equal(isSecretValue(undefined), false)
-  })
-})
-
-describe('structured serialization redacts', () => {
-  test('JSON.stringify renders [secret] rather than dropping the key', () => {
-    const event = {
-      type: 'fn.call',
-      input: { user: 'ada', token: createSecretValue(VALUE) },
-    }
-    assert.equal(
-      JSON.stringify(event),
-      '{"type":"fn.call","input":{"user":"ada","token":"[secret]"}}'
-    )
-  })
-
-  test('a bare secret serializes to [secret]', () => {
-    assert.equal(JSON.stringify(createSecretValue(VALUE)), `"${REDACTED}"`)
-  })
-
-  test('node inspect renders [secret]', () => {
-    const inspect = Symbol.for('nodejs.util.inspect.custom')
-    const secret = createSecretValue(VALUE) as unknown as Record<
-      symbol,
-      () => string
-    >
-    assert.equal(secret[inspect]!(), REDACTED)
-  })
-
-  test('structuredClone carries no secret material across the boundary', () => {
-    // The value lives in a private field, so a clone is an empty object rather
-    // than a copy — it crosses a worker or postMessage boundary carrying nothing.
-    const clone = structuredClone({ token: createSecretValue(VALUE) })
-    assert.equal(JSON.stringify(clone), '{"token":{}}')
-    assert.equal(Object.keys(clone.token).length, 0)
-  })
-})
-
-describe('string coercion throws', () => {
-  const secret = createSecretValue(VALUE)
-
-  test('template literal', () => {
-    assert.throws(() => `Bearer ${secret}`, SecretCoercionError)
-  })
-
-  test('concatenation', () => {
-    assert.throws(() => ('Bearer ' + secret) as string, SecretCoercionError)
-  })
-
-  test('String()', () => {
-    assert.throws(() => String(secret), SecretCoercionError)
-  })
-
-  test('explicit toString()', () => {
-    assert.throws(
-      () => (secret as unknown as { toString(): string }).toString(),
-      SecretCoercionError
-    )
-  })
-
-  test('the thrown error never contains the secret', () => {
-    try {
-      String(secret)
-      assert.fail('expected a throw')
-    } catch (error) {
-      assert.equal((error as Error).message.includes(VALUE), false)
-    }
-  })
-})
-
-// ── Type-level assertions ────────────────────────────────────────────────────
-// The point of the exercise: these fail `yarn tsc`, not `yarn test`. Held in a
-// function that is never called so the runtime never evaluates them.
-//
-// `tsconfig.json` excludes `**/*.test.ts`, so this file is only reached through
-// `tsconfig.type-tests.json`, which lists it under `files` — `exclude` filters
-// `include` but not `files`. Both run from this package's `tsc` script. Without
-// that second pass the assertions below type-check nothing at all.
-
-const _typeAssertions = (
-  secret: SecretValue<string>,
-  creds: SecretValue<{ token: string }>,
-  anything: any,
-  sink: <T>(value: Safe<T>) => void,
-  secretPromise: Promise<SecretValue<string>>,
-  secretMap: Map<string, SecretValue<string>>,
-  secretSet: Set<SecretValue<string>>
-) => {
-  // Nominal: not assignable to what it wraps.
-  // @ts-expect-error a secret is not a string
-  const _notAString: string = secret
-  void _notAString
-
-  // Unwrapping composes with plain types, so call sites need no cast.
-  const _unwrapped: string = secret.reveal()
-  const _unwrappedField: string = creds.reveal().token
-  void _unwrapped
-  void _unwrappedField
-
-  // @ts-expect-error a secret cannot reach a guarded sink
-  sink(secret)
-  // @ts-expect-error nor nested inside an object
-  sink({ config: { token: secret } })
-  // @ts-expect-error nor inside an array
-  sink([secret])
-  // @ts-expect-error nor as one branch of a union
-  sink(true ? secret : 'plain')
-
-  // Unwrapped values pass — disclosure is deliberate and visible.
-  sink(secret.reveal())
-  sink({ config: { token: secret.reveal() } })
-
-  // Ordinary values must not trip the guard.
-  sink('plain')
-  sink(42)
-  sink(null)
-  sink(undefined)
-  sink({ nested: { deep: [1, 2, 3] } })
-  sink(() => 'an ordinary function')
-  sink(new Date())
-  sink(new Error('boom'))
-  sink(Buffer.from('bytes'))
-  sink(new Map([['k', 'v']]))
-  sink([{ a: 1 }, { a: 2 }])
-
-  // A container is not a hiding place: a mapped type cannot reach what a
-  // `Promise`, `Map` or `Set` holds, so `Safe` recurses into them explicitly.
-  // @ts-expect-error nor awaiting later — `getSecret()` returns exactly this
-  sink(secretPromise)
-  // @ts-expect-error nor as a map value
-  sink(secretMap)
-  // @ts-expect-error nor as a set member
-  sink(secretSet)
-
-  // The same containers holding ordinary values must still pass.
-  sink(Promise.resolve('plain'))
-  sink(new Map([['k', 'v']]))
-  sink(new Set(['plain']))
-
-  // `any` cannot be guarded and must stay usable rather than collapsing to never.
-  sink(anything)
-}
-void _typeAssertions
-
-// The assertions above prove `Safe<>` works against a stand-in sink. These prove
-// the real interfaces are actually wired to it — the two can drift apart, and a
-// sink that forgot the guard is exactly the leak this design exists to stop.
-
-const _sinkAssertions = (
-  secret: SecretValue<string>,
-  logger: Logger,
-  auditLog: AuditLog
-) => {
-  // @ts-expect-error a secret cannot be logged
-  logger.info(secret)
-  // @ts-expect-error nor nested in a log message
-  logger.info({ token: secret })
-  // @ts-expect-error nor in the log metadata
-  logger.info('using', { token: secret })
-
-  // @ts-expect-error nor written into an audit input
-  auditLog.write({ type: 'used', source: 'explicit', input: { token: secret } })
-  const metadata = { token: secret }
-  // @ts-expect-error nor into audit metadata
-  auditLog.write({ type: 'used', source: 'explicit', metadata })
-
-  // Ordinary logging and auditing must still compile.
-  logger.info({ msg: 'fine' })
-  logger.info('fine', { count: 1 })
-  auditLog.write({ type: 'used', source: 'explicit', input: { userId: 'u1' } })
-}
-void _sinkAssertions

package/src/classification/secret-value.ts

@@ -1,106 +0,0 @@
-import type { Secret } from './data-classification.js'
-
-declare const secretValueBrand: unique symbol
-
-export const REDACTED = '[secret]'
-
-/** Runtime marker, resilient to duplicate copies of core. */
-const SECRET_VALUE = Symbol.for('pikku.secretValue')
-
-const NODE_INSPECT = Symbol.for('nodejs.util.inspect.custom')
-
-export class SecretCoercionError extends Error {
-  constructor() {
-    super(
-      `A secret was coerced to a string, which would write it out in the clear. Unwrap it deliberately with .reveal() at the point it reaches the wire.`
-    )
-    this.name = 'SecretCoercionError'
-  }
-}
-
-/**
- * A vault secret. Nominal, so it is not assignable to `string` and every
- * concretely-typed sink rejects it; `.reveal()` is the one way out, and every
- * call is a deliberate, greppable disclosure.
- *
- * The revealed value carries the erasable `Secret<T>` classification brand, so
- * the inspector can still follow it one hop past the call.
- *
- * Structured serialization redacts to `[secret]` — an audit or log write must
- * stay honest about the field without crashing the request. String coercion
- * throws, because a template literal or concatenation is always a leak.
- */
-export class SecretValue<T = string> {
-  declare readonly [secretValueBrand]: true
-  readonly [SECRET_VALUE] = true
-
-  readonly #value: T
-
-  constructor(value: T) {
-    this.#value = value
-  }
-
-  reveal(): Secret<T> {
-    return this.#value as Secret<T>
-  }
-
-  toJSON(): string {
-    return REDACTED
-  }
-
-  [NODE_INSPECT](): string {
-    return REDACTED
-  }
-
-  toString(): never {
-    throw new SecretCoercionError()
-  }
-
-  [Symbol.toPrimitive](): never {
-    throw new SecretCoercionError()
-  }
-}
-
-export const createSecretValue = <T>(value: T): SecretValue<T> =>
-  new SecretValue(value)
-
-export const isSecretValue = (value: unknown): value is SecretValue<unknown> =>
-  typeof value === 'object' && value !== null && SECRET_VALUE in value
-
-type IsAny<T> = 0 extends 1 & T ? true : false
-
-type Passthrough =
-  Function | Date | RegExp | Error | ArrayBuffer | ArrayBufferView
-
-/**
- * Rejects a `SecretValue` anywhere in `T`, however deeply nested, by collapsing
- * it to `never`.
- *
- * For sinks whose parameters are `any`, `unknown` or a free generic — loggers,
- * queue payloads, channel messages — where nominality alone cannot help.
- * `any` is passed through untouched: it cannot be guarded, and collapsing it
- * would reject every legitimate call.
- *
- * `Promise`, `Map` and `Set` are recursed into rather than passed through. A
- * mapped type cannot reach what they hold — mapping their keys yields their
- * methods, not their contents — so treating them as opaque let a secret ride
- * through inside one. `Promise` is the case that bites: `getSecret()` returns
- * `Promise<SecretValue<T>>`, so a forgotten `await` would otherwise log a
- * secret.
- */
-export type Safe<T> =
-  IsAny<T> extends true
-    ? T
-    : [Extract<T, SecretValue<any>>] extends [never]
-      ? T extends Promise<infer V>
-        ? Promise<Safe<V>>
-        : T extends Map<infer K, infer V>
-          ? Map<Safe<K>, Safe<V>>
-          : T extends Set<infer V>
-            ? Set<Safe<V>>
-            : T extends Passthrough
-              ? T
-              : T extends object
-                ? { [K in keyof T]: Safe<T[K]> }
-                : T
-      : never