@pikku/core 0.12.74 → 0.12.78

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

package/src/services/audit-service.ts

@@ -4,6 +4,7 @@ import type {
   PikkuWiringTypes,
 } from '../types/core.types.js'
 import type { Logger } from './logger.js'
+import type { Safe } from '../secret-value.js'
 
 export type AuditDurability = 'best-effort' | 'transactional'
 export type AuditOutcome = 'success' | 'failed' | 'denied'
@@ -19,7 +20,19 @@ export type ResolvedAuditConfig = {
   durability: AuditDurability
 }
 
-export type AuditActor = {
+/**
+ * Who an event happened under.
+ *
+ * A user, not an "actor": in pikku an actor is a synthetic person a scenario
+ * drives, flagged `actor` on the user row, and the overwhelming majority of
+ * audited events are caused by ordinary customers. Naming this `actor` made the
+ * synthetic case unsayable — `actor.actor === true` — and implied every
+ * recorded action was a test.
+ *
+ * `pikkuUserId` is the identity pikku resolves for every wire, so it is the one
+ * field a signed-out caller still leaves behind.
+ */
+export type AuditUserIdentity = {
   userId?: string
   orgId?: string
   pikkuUserId?: string
@@ -37,16 +50,67 @@ export type AuditEvent = {
   traceId?: string
   transactionId?: string | null
   queryId?: string | null
-  actor?: AuditActor
+  userIdentity?: AuditUserIdentity
   input?: unknown
   metadata?: Record<string, unknown>
 }
 
 export type AuditEventBatch = AuditEvent[]
 
+/**
+ * A page of the trail, newest first, narrowed by the filters a reader picked.
+ *
+ * Every field is a conjunction, and an empty array is not a filter — it is
+ * "match nothing", which would otherwise read as "match everything" and quietly
+ * widen a scoped query.
+ */
+export type AuditQuery = {
+  /** Restrict to these users. */
+  userIds?: string[]
+  /** Restrict to these `AuditEvent['type']` values. */
+  types?: string[]
+  /** Restrict to one organisation. */
+  orgId?: string
+  /** Inclusive lower bound on `occurredAt` (ISO 8601). */
+  from?: string
+  /** Exclusive upper bound on `occurredAt` (ISO 8601). */
+  to?: string
+  limit?: number
+  offset?: number
+}
+
+/**
+ * The distinct values present in the trail, for populating filter controls.
+ *
+ * Computed over the whole trail rather than the current page — a filter list
+ * that only offered what the current page happens to show could never be used
+ * to reach anything else.
+ */
+export type AuditFacets = {
+  userIds: string[]
+  types: string[]
+}
+
+export type AuditQueryResult = {
+  events: AuditEvent[]
+  /** Offset of the next page, or `null` at the end. */
+  nextCursor: number | null
+  /** Present only when the caller asked for it — it costs two extra scans. */
+  facets?: AuditFacets
+}
+
 export interface AuditService {
   audit(event: AuditEvent): Promise<void>
   write?(batch: AuditEventBatch): Promise<void>
+  /**
+   * The read side. Optional because a sink can legitimately be write-only — a
+   * queue producer that hands events to another system has nothing to read
+   * back. A reader that finds this absent should say the trail is not readable
+   * here rather than that it is empty; the two are very different answers.
+   */
+  query?(query: AuditQuery): Promise<AuditQueryResult>
+  /** Distinct users and types across the whole trail. Paired with {@link query}. */
+  facets?(): Promise<AuditFacets>
 }
 
 export class NoopAuditService implements AuditService {
@@ -57,9 +121,18 @@ export class NoopAuditService implements AuditService {
 
 export type AuditLogWriteInput = Omit<AuditEvent, 'occurredAt'>
 
+/**
+ * The audit an invocation writes to. `write` is `Safe<>`-guarded like the
+ * logger: an audit event carries `input` and `metadata` as `unknown`, so
+ * nominality alone cannot stop a `SecretValue` landing in one. A secret
+ * anywhere in the event, however deeply nested, collapses to `never`.
+ *
+ * An unrevealed `SecretValue` would serialize as `[secret]` anyway; the guard
+ * is what makes that an explicit choice rather than a near miss.
+ */
 export interface AuditLog {
   readonly config: ResolvedAuditConfig | undefined
-  write(event: AuditLogWriteInput): Promise<void>
+  write<E extends AuditLogWriteInput>(event: Safe<E>): Promise<void>
   flush(): Promise<void>
   close(): Promise<void>
 }
@@ -149,7 +222,8 @@ class InvocationAuditLog implements AuditLog {
       wireType: this.wire.wireType,
       wireId: this.wire.wireId,
       traceId: this.wire.traceId,
-      actor: event.actor ?? resolveAuditActorFromWire(this.wire),
+      userIdentity:
+        event.userIdentity ?? resolveAuditUserIdentityFromWire(this.wire),
       ...event,
       occurredAt: new Date().toISOString(),
     }
@@ -184,19 +258,23 @@ export const createInvocationAudit = (
   return new InvocationAuditLog(wire.audit, service, wire, logger)
 }
 
-export const resolveAuditActorFromWire = (
+export const resolveAuditUserIdentityFromWire = (
   wire: PikkuWire<any, any, any, CoreUserSession>
-): AuditActor | undefined => {
+): AuditUserIdentity | undefined => {
   const session = wire.session as CoreUserSession | undefined
-  const actor: AuditActor = {
+  const userIdentity: AuditUserIdentity = {
     userId: session?.userId,
     orgId: session?.orgId,
     pikkuUserId: wire.pikkuUserId,
   }
 
-  if (!actor.userId && !actor.orgId && !actor.pikkuUserId) {
+  if (
+    !userIdentity.userId &&
+    !userIdentity.orgId &&
+    !userIdentity.pikkuUserId
+  ) {
     return undefined
   }
 
-  return actor
+  return userIdentity
 }

package/src/services/credential-wire-service.ts

@@ -1,3 +1,4 @@
+import { isSecretValue } from '../secret-value.js'
 import type { CredentialService } from './credential-service.js'
 import { defaultPikkuUserIdResolver } from './pikku-user-id.js'
 import type { PikkuRawWire } from '../types/core.types.js'
@@ -17,8 +18,15 @@ export class PikkuCredentialWireService {
     return this.aliases?.[name] ?? name
   }
 
+  /**
+   * A credential is one of the few places vault material is meant to end up, so
+   * a `SecretValue` is unwrapped here rather than rejected — `get` promises the
+   * raw material, and storing the wrapper would make that a lie.
+   */
   set(name: string, value: unknown): void {
-    this.credentials[this.resolveName(name)] = value
+    this.credentials[this.resolveName(name)] = isSecretValue(value)
+      ? value.reveal()
+      : value
   }
 
   get<T = unknown>(name: string): T | null | Promise<T | null> {

package/src/services/email-service.ts

@@ -1,3 +1,5 @@
+import type { Safe } from '../secret-value.js'
+
 export interface EmailTemplateReference {
   name: string
   locale?: string
@@ -42,5 +44,5 @@ export interface SendEmailResult {
 }
 
 export interface EmailService {
-  send(input: SendEmailInput): Promise<SendEmailResult>
+  send<T extends SendEmailInput>(input: Safe<T>): Promise<SendEmailResult>
 }

package/src/services/in-memory-workflow-service.ts

@@ -301,6 +301,35 @@ export class InMemoryWorkflowService
     return newStep
   }
 
+  protected async findStalledRunIds(
+    before: Date,
+    limit: number
+  ): Promise<string[]> {
+    const stalled: string[] = []
+    for (const [runId, run] of this.runs) {
+      if (run.status !== 'running') continue
+      const steps = this.stepHistory.get(runId) ?? []
+      if (
+        steps.some(
+          (step) =>
+            step.status === 'running' ||
+            step.status === 'scheduled' ||
+            step.status === 'suspended'
+        )
+      ) {
+        continue
+      }
+      const lastActivity = steps.reduce(
+        (latest, step) => (step.updatedAt > latest ? step.updatedAt : latest),
+        run.updatedAt
+      )
+      if (lastActivity >= before) continue
+      stalled.push(runId)
+      if (stalled.length >= limit) break
+    }
+    return stalled
+  }
+
   async listRuns(options?: {
     workflowName?: string
     status?: string

package/src/services/index.ts

@@ -75,7 +75,7 @@ export {
   type WebhookServiceConfig,
 } from './webhook-service.js'
 export type { Logger } from './logger.js'
-export type { SecretService } from './secret-service.js'
+export type { SecretService, SecretValues } from './secret-service.js'
 export type { VariablesService } from './variables-service.js'
 export type { SchemaService } from './schema-service.js'
 export type { SessionService } from './user-session-service.js'
@@ -141,11 +141,10 @@ export type { IsSystemRole } from './system-role-guard.js'
 export {
   NoopAuditService,
   createInvocationAudit,
-  resolveAuditActorFromWire,
   resolveAuditConfig,
+  resolveAuditUserIdentityFromWire,
 } from './audit-service.js'
 export type {
-  AuditActor,
   AuditConfig,
   AuditDurability,
   AuditEvent,
@@ -155,6 +154,7 @@ export type {
   AuditOutcome,
   AuditService,
   AuditSource,
+  AuditUserIdentity,
   ResolvedAuditConfig,
 } from './audit-service.js'
 export { InMemorySessionStore } from './in-memory-session-store.js'