@pikku/core 0.12.74 → 0.12.77

package/src/data-classification.ts

@@ -11,9 +11,53 @@ export type AnonymizeStrategy =
   | 'keep'
   | null
 
+// knowledge: decisions/internals/core-column-form-is-an-axis-of-its-own.md
+
+/**
+ * How a column's bytes are represented at rest, as distinct from how sensitive
+ * the value is (`Classification`). The two are independent: a token hash is
+ * `secret` + `hashed` and must never be encrypted, because the hash *is* the
+ * lookup key; a live bearer token is `secret` + `plain` today and should not be.
+ *
+ * `wrapped` and `sealed` are siblings rather than one being "encrypted": both
+ * are ciphertext, and what separates them is who can read it back. Wrapped is
+ * symmetric and the application holds the key. Sealed is asymmetric and the
+ * application holds only the public half, so it can write the value and never
+ * read it. Storing one where the other is expected is silent, permanent data
+ * loss, which is why they are not collapsed into a single `encrypted`.
+ */
+export type ColumnForm = 'plain' | 'hashed' | 'wrapped' | 'sealed'
+
+declare const wrappedBrand: unique symbol
+declare const sealedBrand: unique symbol
+declare const hashedBrand: unique symbol
+
+/**
+ * Ciphertext under a symmetric key the application holds — the output of
+ * `envelopeEncrypt`, `wrapDEK` or `envelopeRewrap`.
+ *
+ * Unlike `Secret<T>` the brand is REQUIRED, so a plain `string` is not
+ * assignable and a column declared `form: 'wrapped'` cannot be written with
+ * anything but genuine ciphertext. It stays assignable *to* `string`, so it
+ * still works as a query operand and serializes normally — the constraint is on
+ * construction, not on use.
+ */
+export type WrappedValue = string & { readonly [wrappedBrand]: true }
+
+/** Ciphertext under a public key whose private half the application does not
+ *  hold. Deliberately not assignable to `WrappedValue`: writing one where the
+ *  other belongs produces a row nobody can ever open. */
+export type SealedValue = string & { readonly [sealedBrand]: true }
+
+/** A one-way digest of a secret input. The brand's job is narrow — stop a *raw*
+ *  credential being written into the column that should hold its hash. */
+export type HashedValue = string & { readonly [hashedBrand]: true }
+
 export interface ColumnClassification {
   classification: Classification
   anonymize_strategy: AnonymizeStrategy
+  /** At-rest representation. Absent means `plain`. */
+  form?: ColumnForm
   description?: string
 }
 

package/src/function/functions.types.ts

@@ -12,6 +12,7 @@ import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { PikkuError } from '../errors/error-handler.js'
 import type { CoreNodeConfig } from '../wirings/node/node.types.js'
 import type { ScenarioSurface } from '../wirings/workflow/scenario-step.types.js'
+import type { Safe } from '../secret-value.js'
 
 /**
  * @deprecated Use StandardSchemaV1 from @standard-schema/spec instead.
@@ -31,7 +32,9 @@ export type CorePikkuFunction<
   services: Services,
   data: In,
   wire: Wire
-) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>
+) => Wire['channel'] extends null
+  ? Promise<Safe<Out>>
+  : Promise<Safe<Out>> | Promise<void>
 
 export type CorePikkuFunctionSessionless<
   In,
@@ -45,7 +48,9 @@ export type CorePikkuFunctionSessionless<
   services: Services,
   data: In,
   wire: Wire
-) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>
+) => Wire['channel'] extends null
+  ? Promise<Safe<Out>>
+  : Promise<Safe<Out>> | Promise<void>
 
 export type CorePikkuPermission<
   In = any,
@@ -192,16 +197,18 @@ export type CorePikkuFunctionConfig<
   tags?: string[]
   expose?: boolean
   /**
-   * The function performs its own authorization in its body — verifying a
+   * The permission check for this function lives in its body — verifying a
    * signed token, checking a webhook signature, matching an invite code — so
-   * it is not open despite carrying no session, scope or permission.
+   * it is not open despite declaring no session, scope or permission.
    *
-   * Purely declarative: nothing at runtime reads it, and it grants nothing. It
-   * exists so the claim is written down where an audit can find it, and so
-   * codegen stops warning about a gate it has no way to see. Asserting it
-   * falsely disables the one check that would have caught the mistake.
+   * A last resort. Prefer `permissions`, which are declared, inspectable, and
+   * reusable; reach for this only when the check cannot be expressed as one.
+   *
+   * Purely declarative — it grants nothing, and asserting it falsely disables
+   * the audit that would have caught the mistake. Requires
+   * `allow.permissionsInBody` in `pikku.config.json`.
    */
-  selfAuthenticated?: boolean
+  permissionsInBody?: boolean
   remote?: boolean
   mcp?: boolean
   readonly?: boolean
@@ -248,7 +255,8 @@ export type CorePikkuFunctionConfig<
    * Scopes the session must hold; all are required (AND) and checked before
    * `permissions`, which OR together — a scope can only narrow access.
    * Narrowed to the generated `ScopeId` union, so an undeclared scope is a
-   * compile error.
+   * compile error. Requires a session — see
+   * {@link CorePikkuSessionlessFunctionConfig}.
    */
   scopes?: Scope[]
   permissions?: CorePermissionGroup<PikkuPermission>
@@ -258,3 +266,32 @@ export type CorePikkuFunctionConfig<
   node?: CoreNodeConfig
   errors?: Array<typeof PikkuError>
 }
+
+/**
+ * {@link CorePikkuFunctionConfig} for a function that runs without a session.
+ *
+ * Identical, minus `scopes`. Scopes are AND-ed and `verifyScopes` fails closed,
+ * so an anonymous caller holds none and satisfies none — a sessionless function
+ * with scopes rejects every caller it exists to serve. Gate it with
+ * `permissions`, which receive the optional session and may pass anonymous.
+ */
+export type CorePikkuSessionlessFunctionConfig<
+  PikkuFunction extends CorePikkuFunctionSessionless<any, any, any, any, any>,
+  PikkuPermission extends CorePikkuPermission<any, any, any> =
+    CorePikkuPermission<any>,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
+    any,
+    any
+  >,
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined,
+> = Omit<
+  CorePikkuFunctionConfig<
+    PikkuFunction,
+    PikkuPermission,
+    PikkuMiddleware,
+    InputSchema,
+    OutputSchema
+  >,
+  'scopes'
+>

package/src/function/index.ts

@@ -9,6 +9,7 @@ export type {
   CorePikkuFunction,
   CorePikkuFunctionSessionless,
   CorePikkuFunctionConfig,
+  CorePikkuSessionlessFunctionConfig,
   CorePikkuAuth,
   CorePikkuAuthConfig,
   CorePikkuPermission,

package/src/index.ts

@@ -197,20 +197,23 @@ export type { SessionService } from './services/user-session-service.js'
 export {
   NoopAuditService,
   createInvocationAudit,
-  resolveAuditActorFromWire,
   resolveAuditConfig,
+  resolveAuditUserIdentityFromWire,
 } from './services/audit-service.js'
 export type {
-  AuditActor,
   AuditConfig,
   AuditDurability,
   AuditEvent,
   AuditEventBatch,
+  AuditFacets,
   AuditLog,
   AuditLogWriteInput,
   AuditOutcome,
+  AuditQuery,
+  AuditQueryResult,
   AuditService,
   AuditSource,
+  AuditUserIdentity,
   ResolvedAuditConfig,
 } from './services/audit-service.js'
 export type {
@@ -284,4 +287,23 @@ export type {
   AnonymizeStrategy,
   ColumnClassification,
   ClassificationManifest,
+  ColumnForm,
+  WrappedValue,
+  SealedValue,
+  HashedValue,
 } from './data-classification.js'
+
+export {
+  hashToken,
+  unsafeAsWrapped,
+  unsafeAsSealed,
+  unsafeAsHashed,
+} from './column-form.js'
+
+export type { SecretValue, Safe } from './secret-value.js'
+export {
+  createSecretValue,
+  isSecretValue,
+  SecretCoercionError,
+  REDACTED,
+} from './secret-value.js'

package/src/middleware/auth-bearer.test.ts

@@ -8,6 +8,7 @@ import {
   createMiddlewareSessionWireProps,
 } from '../services/user-session-service.js'
 import { InvalidSessionError } from '../errors/errors.js'
+import { createSecretValue } from '../secret-value.js'
 
 beforeEach(() => {
   resetPikkuState()
@@ -429,7 +430,7 @@ describe('authBearer middleware', () => {
     const secrets = {
       getSecret: async (secretId: string) => {
         assert.equal(secretId, 'PIKKU_CONSOLE_TOKEN')
-        return 'secret-token-value'
+        return createSecretValue('secret-token-value')
       },
     }
 
@@ -500,7 +501,7 @@ describe('authBearer middleware', () => {
   test('should not set session when secret-resolved token does not match', async () => {
     const SessionService = new PikkuSessionService<CoreUserSession>()
     const secrets = {
-      getSecret: async () => 'expected-token',
+      getSecret: async () => createSecretValue('expected-token'),
     }
 
     const middleware = authBearer({

package/src/middleware/auth-bearer.ts

@@ -55,9 +55,10 @@ export const authBearer = pikkuMiddlewareFactory<{
             expected = token.value
           } else {
             // An unset secret means the feature is off — never a request error.
-            expected = await secrets
+            const stored = await secrets
               ?.getSecret<string>(token.secretId)
               .catch(() => undefined)
+            expected = stored?.reveal()
           }
           if (expected && constantTimeEqual(bearerToken, expected)) {
             userSession = token.userSession

package/src/middleware/remote-auth.test.ts

@@ -4,6 +4,7 @@ import { pikkuRemoteAuthMiddleware } from './remote-auth.js'
 import { UnauthorizedError } from '../errors/errors.js'
 import { resetPikkuState } from '../pikku-state.js'
 import { encryptWithKeyMaterial, REMOTE_SESSION_INFO } from '../crypto-utils.js'
+import { createSecretValue } from '../secret-value.js'
 
 beforeEach(() => {
   resetPikkuState()
@@ -14,7 +15,7 @@ const TEST_SECRET = 'test-remote-secret-key-with-enough-entropy'
 const createMockSecrets = (secret?: string) => ({
   getSecret: async (key: string) => {
     if (key === 'PIKKU_REMOTE_SECRET' && secret !== undefined) {
-      return secret
+      return createSecretValue(secret)
     }
     throw new Error(`Secret ${key} not found`)
   },

package/src/middleware/remote-auth.ts

@@ -14,7 +14,7 @@ export const pikkuRemoteAuthMiddleware = pikkuMiddleware(
 
     let secret: string
     try {
-      secret = await secrets.getSecret('PIKKU_REMOTE_SECRET')
+      secret = (await secrets.getSecret('PIKKU_REMOTE_SECRET')).reveal()
     } catch {
       if (http.request.path().startsWith('/remote/rpc/')) {
         throw new UnauthorizedError()

package/src/remote.test.ts

@@ -4,6 +4,7 @@ import { buildRemoteHeaders } from './remote.js'
 import { pikkuRemoteAuthMiddleware } from './middleware/remote-auth.js'
 import { resetPikkuState } from './pikku-state.js'
 import { WeakKeyMaterialError } from './errors/errors.js'
+import { createSecretValue } from './secret-value.js'
 
 beforeEach(() => {
   resetPikkuState()
@@ -14,7 +15,7 @@ const WEAK_SECRET = 'dev-remote-secret'
 
 const createSecrets = (secret: string) => ({
   getSecret: async (key: string) => {
-    if (key === 'PIKKU_REMOTE_SECRET') return secret
+    if (key === 'PIKKU_REMOTE_SECRET') return createSecretValue(secret)
     throw new Error(`Secret ${key} not found`)
   },
 })

package/src/remote.ts

@@ -25,7 +25,7 @@ export async function buildRemoteHeaders(
 
   let secret: string | undefined
   try {
-    secret = await secrets?.getSecret('PIKKU_REMOTE_SECRET')
+    secret = (await secrets?.getSecret('PIKKU_REMOTE_SECRET'))?.reveal()
   } catch {}
 
   if (secret && jwt) {

package/src/secret-value.test.ts

@@ -0,0 +1,204 @@
+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/secret-value.ts

@@ -0,0 +1,111 @@
+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