@pikku/inspector 0.12.66 → 0.12.68

package/src/add/{secret-sink-check.test.ts → classified-sink-check.test.ts}

@@ -23,11 +23,22 @@ function makeLogger() {
 
 /**
  * Stands in for @pikku/core, which is not importable from a tmp dir. The shapes
- * are what matters: `Secret<T>` is the optional brand `.reveal()` returns, and
- * the service interfaces are matched by name, so these must keep the real names.
+ * are what matters: `Secret<T>` is the optional brand `.reveal()` returns,
+ * `Pii<T>` and `Private<T>` are the brands a generated row type carries, and the
+ * service interfaces are matched by name, so these must keep the real names.
  */
 const PRELUDE = `
 type Secret<T> = T & { readonly __classification__?: 'secret' }
+type Pii<T> = T & { readonly __classification__?: 'pii' }
+type Private<T> = T & { readonly __classification__?: 'private' }
+
+/** What \`db.selectFrom('user')\` hands back once the schema is generated. */
+interface UserRow {
+  userId: string
+  email: Pii<string>
+  internalNote: Private<string>
+}
+declare function getUser(): Promise<UserRow>
 
 declare class SecretValue<T = string> {
   private brand: T
@@ -88,6 +99,9 @@ async function runInspect(source: string) {
 const sinkErrors = (diagnostics: Array<{ code: ErrorCode; message: string }>) =>
   diagnostics.filter((d) => d.code === ErrorCode.SECRET_REVEALED_INTO_SINK)
 
+const piiErrors = (diagnostics: Array<{ code: ErrorCode; message: string }>) =>
+  diagnostics.filter((d) => d.code === ErrorCode.PII_INTO_SINK)
+
 describe('PKU953 — a revealed secret reaching a sink', () => {
   test('flags a secret logged inline', async () => {
     const diagnostics = await runInspect(`
@@ -212,3 +226,122 @@ describe('PKU953 — a revealed secret reaching a sink', () => {
     assert.equal(sinkErrors(diagnostics).length, 0)
   })
 })
+
+/**
+ * PII is not a secret, so the policy is not "never write it down" — it is "not
+ * where it leaves your control". A log ships to an aggregator and a webhook
+ * posts to somebody else's server; an email is addressed to the data subject,
+ * and a queue and an audit stay on the operator's own infrastructure.
+ */
+describe('PKU954 — personal data reaching a sink', () => {
+  test('flags PII logged inline and through a local binding', async () => {
+    const diagnostics = await runInspect(`
+      export const leak = pikkuFunc<void, void>({
+        func: async ({ logger }) => {
+          const user = await getUser()
+          logger.info(user.email)
+          const email = user.email
+          logger.error('send failed', { email })
+        },
+      })
+    `)
+    const errors = piiErrors(diagnostics)
+    assert.equal(errors.length, 2)
+    assert.match(errors[0]!.message, /logger\.info/)
+    assert.match(errors[1]!.message, /logger\.error/)
+    assert.equal(sinkErrors(diagnostics).length, 0)
+  })
+
+  test('flags a whole row logged, since the PII rides along inside it', async () => {
+    const diagnostics = await runInspect(`
+      export const leak = pikkuFunc<void, void>({
+        func: async ({ logger }) => {
+          const user = await getUser()
+          logger.info('loaded', user)
+        },
+      })
+    `)
+    assert.equal(piiErrors(diagnostics).length, 1)
+  })
+
+  test('flags PII on console and in a webhook', async () => {
+    const diagnostics = await runInspect(`
+      export const leak = pikkuFunc<void, void>({
+        func: async ({ webhooks }) => {
+          const user = await getUser()
+          console.log(user.email)
+          await webhooks.send({ url: 'https://x', data: { email: user.email } })
+        },
+      })
+    `)
+    const errors = piiErrors(diagnostics)
+    assert.equal(errors.length, 2)
+    assert.match(errors[0]!.message, /console\.log/)
+    assert.match(errors[1]!.message, /webhooks\.send/)
+  })
+
+  test('stays quiet for an email to the data subject, an audit and a queue', async () => {
+    const diagnostics = await runInspect(`
+      export const fine = pikkuFunc<void, void>({
+        func: async ({ email, audit, auditLog, queueService }) => {
+          const user = await getUser()
+          await email.send({ to: user.email, text: 'Hi ' + user.email })
+          await audit?.audit({ type: 'viewed', input: { email: user.email } })
+          await auditLog?.write({ type: 'viewed', input: user.email })
+          await queueService.add('welcome', { email: user.email })
+        },
+      })
+    `)
+    assert.equal(piiErrors(diagnostics).length, 0)
+    assert.equal(sinkErrors(diagnostics).length, 0)
+  })
+
+  test('stays quiet for private, which is about who may read the row', async () => {
+    const diagnostics = await runInspect(`
+      export const fine = pikkuFunc<void, void>({
+        func: async ({ logger }) => {
+          const user = await getUser()
+          logger.info('note', { note: user.internalNote, id: user.userId })
+        },
+      })
+    `)
+    assert.equal(piiErrors(diagnostics).length, 0)
+  })
+
+  test('stays quiet when an explicit annotation erases the brand', async () => {
+    const diagnostics = await runInspect(`
+      export const documentedLimit = pikkuFunc<void, void>({
+        func: async ({ logger }) => {
+          const user = await getUser()
+          const email: string = user.email
+          logger.info(email)
+        },
+      })
+    `)
+    assert.equal(piiErrors(diagnostics).length, 0)
+  })
+
+  test('does not run without the classification flag', async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), 'pikku-pii-sink-off-'))
+    const file = join(tmpDir, 'funcs.ts')
+    await writeFile(
+      file,
+      PRELUDE +
+        `
+      export const leak = pikkuFunc<void, void>({
+        func: async ({ logger }) => {
+          const user = await getUser()
+          logger.info(user.email)
+        },
+      })
+    `
+    )
+    const { logger, diagnostics } = makeLogger()
+    try {
+      await inspect(logger, [file], { rootDir: tmpDir })
+    } finally {
+      await rm(tmpDir, { recursive: true, force: true })
+    }
+    assert.equal(piiErrors(diagnostics).length, 0)
+  })
+})

package/src/error-codes.ts

@@ -98,6 +98,9 @@ export enum ErrorCode {
   // File structure errors
   SCHEMA_AND_WIRING_COLOCATED = 'PKU490',
 
+  // Schema authoring errors
+  SCHEMA_TRANSFORM_NOT_SUPPORTED = 'PKU491',
+
   // Optimization diagnostics
   SERVICES_NOT_DESTRUCTURED = 'PKU410',
   WIRES_NOT_DESTRUCTURED = 'PKU411',
@@ -123,6 +126,7 @@ export enum ErrorCode {
   SECRET_NOT_DECLARED = 'PKU951',
   SECRET_KEY_NOT_STATIC = 'PKU952',
   SECRET_REVEALED_INTO_SINK = 'PKU953',
+  PII_INTO_SINK = 'PKU954',
 }
 
 /**

package/src/utils/check-classified-sinks.ts

@@ -0,0 +1,215 @@
+import * as ts from 'typescript'
+import { findPiiPaths } from './check-pii-output.js'
+import { doesTypeExtendsCore } from './does-type-extend-core-type.js'
+
+export type SinkClassification = 'secret' | 'pii'
+
+export type SinkViolation = {
+  /** How the value reaches the outside world, e.g. `logger.info`. */
+  sink: string
+  /** Dotted path to the secret inside the argument, or `<argument>` when bare. */
+  path: string
+  /** Position of the offending argument, for the diagnostic message. */
+  line: number
+  /** Which brand was found, so the caller can pick the diagnostic. */
+  classification: SinkClassification
+}
+
+/**
+ * A method that writes its arguments somewhere a classified value must never
+ * land, keyed by the core interface that owns it. `'*'` means every method on
+ * the type is a sink, which is true of a logger.
+ *
+ * `rejects` differs per sink because the two brands leak differently. A vault
+ * secret is wrong everywhere: no sink has a legitimate reason to receive one.
+ * PII is wrong only where it leaves the operator's control, or lands somewhere
+ * never designed to hold it:
+ *
+ *   - a log is read far more widely than the record it came from, is usually
+ *     shipped to a third-party aggregator, and is retained long past the
+ *     lifetime of any consent — so PII does not belong in one;
+ *   - a webhook posts to somebody else's server, which is the same disclosure
+ *     with a different transport;
+ *   - an email is addressed to the data subject, and their own name in it is
+ *     the point;
+ *   - an audit is a record in the operator's own database, and naming who did
+ *     what is usually the legal requirement rather than a breach of it;
+ *   - a queue payload stays on the operator's own infrastructure and is
+ *     consumed by their own worker.
+ *
+ * `private` is deliberately absent everywhere: it marks a value that is not
+ * public, which is a statement about who may read the row — not a claim that
+ * writing it down is a disclosure.
+ */
+const SINKS: Array<{
+  coreType: string
+  methods: '*' | string[]
+  rejects: SinkClassification[]
+}> = [
+  { coreType: 'Logger', methods: '*', rejects: ['secret', 'pii'] },
+  { coreType: 'WebhookService', methods: ['send'], rejects: ['secret', 'pii'] },
+  { coreType: 'QueueService', methods: ['add'], rejects: ['secret'] },
+  { coreType: 'EmailService', methods: ['send'], rejects: ['secret'] },
+  {
+    coreType: 'AuditService',
+    methods: ['audit', 'write'],
+    rejects: ['secret'],
+  },
+  { coreType: 'AuditLog', methods: ['write'], rejects: ['secret'] },
+]
+
+/** `console` has no Pikku type, and is read as widely as any logger. */
+const CONSOLE_REJECTS: SinkClassification[] = ['secret', 'pii']
+
+/**
+ * Finds revealed vault secrets — and, for the sinks that reject them, PII
+ * columns — that flow into a sink.
+ *
+ * `SecretValue` is nominally typed, so the type system alone stops it reaching
+ * any of these. `.reveal()` is the deliberate escape hatch, and it hands back
+ * `Secret<T>` — the erasable classification brand. That brand is what this scan
+ * follows, which means it catches the revealed value both inline
+ * (`logger.info(s.reveal())`) and through a local binding, because the local's
+ * inferred type carries the brand too.
+ *
+ * PII arrives by the same route without a `.reveal()`: `Pii<T>` is the brand the
+ * generated row types carry, so a column read straight out of the database keeps
+ * it through a local binding and into the call.
+ *
+ * The brand is optional by design, so an explicit annotation (`const t: string =
+ * s.reveal()`, or `const email: string = user.email`) erases it and this scan
+ * goes quiet. That is the documented limit
+ * of a structural marker: it catches the mistake, not someone determined to
+ * silence it.
+ *
+ * Sinks are matched on the receiver's resolved core interface, which means the
+ * scan needs the services parameter to be typed. Real projects get that from
+ * the generated `#pikku` factory; a hand-rolled file that calls the raw core
+ * factory without annotating its services leaves the parameter `any`, and an
+ * `any` receiver matches nothing.
+ */
+export function findClassifiedSinks(
+  checker: ts.TypeChecker,
+  handler: ts.Node
+): SinkViolation[] {
+  const violations: SinkViolation[] = []
+
+  const visit = (node: ts.Node): void => {
+    if (
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression)
+    ) {
+      const sink = describeSink(checker, node.expression)
+      if (sink) {
+        for (const arg of node.arguments) {
+          const found = findClassifiedExpression(checker, arg, sink.rejects)
+          if (found) {
+            violations.push({
+              sink: sink.name,
+              path: found.node.getText(),
+              line:
+                found.node
+                  .getSourceFile()
+                  .getLineAndCharacterOfPosition(found.node.getStart()).line +
+                1,
+              classification: found.classification,
+            })
+          }
+        }
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(handler)
+
+  return violations
+}
+
+/**
+ * Finds the first expression inside a sink argument whose own type carries one
+ * of the brands this sink rejects, and returns it so the diagnostic can quote
+ * it.
+ *
+ * This walks the argument rather than typing it whole, because an object
+ * literal in an argument position is contextually typed by the parameter — for
+ * a guarded sink that parameter is `Safe<M>`, and resolving the literal against
+ * it drops the optional brand before it can be read. Each inner expression
+ * (`token.reveal()`, or a reference to a local holding it) carries its own type
+ * regardless of the surrounding context, so reading those is what actually
+ * sees the secret.
+ */
+function findClassifiedExpression(
+  checker: ts.TypeChecker,
+  node: ts.Node,
+  rejects: SinkClassification[],
+  /**
+   * The node is only being read to reach a property of it, so its own type says
+   * nothing about what the call receives. Without this, `user.userId` reports
+   * the row's `email` column: the walk types the `user` receiver on its way
+   * down, and a row type is branded wherever any of its columns are.
+   */
+  isReceiver = false
+): { node: ts.Expression; classification: SinkClassification } | undefined {
+  // Descend first, so an object literal wrapping the secret reports the
+  // expression that actually holds it (`token.reveal()`) rather than the whole
+  // literal. Nothing inside a `SecretValue` receiver is itself branded, so a
+  // bare `token.reveal()` still falls through to the self-check below.
+  for (const child of node.getChildren()) {
+    // A property name is not a value, and typing it re-resolves the property.
+    if (ts.isPropertyAssignment(node) && child === node.name) continue
+    const childIsReceiver =
+      (ts.isPropertyAccessExpression(node) ||
+        ts.isElementAccessExpression(node)) &&
+      child === node.expression
+    const found = findClassifiedExpression(
+      checker,
+      child,
+      rejects,
+      childIsReceiver
+    )
+    if (found) return found
+  }
+
+  if (!isReceiver && ts.isExpression(node) && !ts.isStringLiteralLike(node)) {
+    const type = checker.getTypeAtLocation(node)
+    /* `secret` outranks `pii` when a value somehow carries both, so the caller
+       reports the more serious of the two rather than whichever came first. */
+    for (const classification of ['secret', 'pii'] as const) {
+      if (!rejects.includes(classification)) continue
+      const hit = findPiiPaths(checker, type).some(
+        (f) => f.classification === classification
+      )
+      if (hit) return { node, classification }
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Names the sink a call writes to, or undefined when the call is not one.
+ * `console` is matched by identifier because it is a global with no Pikku type;
+ * everything else is matched on its resolved core interface so a renamed
+ * service or a decorator still counts.
+ */
+function describeSink(
+  checker: ts.TypeChecker,
+  callee: ts.PropertyAccessExpression
+): { name: string; rejects: SinkClassification[] } | undefined {
+  const method = callee.name.text
+  const receiver = callee.expression
+
+  if (ts.isIdentifier(receiver) && receiver.text === 'console') {
+    return { name: `console.${method}`, rejects: CONSOLE_REJECTS }
+  }
+
+  const receiverType = checker.getTypeAtLocation(receiver)
+  for (const { coreType, methods, rejects } of SINKS) {
+    if (methods !== '*' && !methods.includes(method)) continue
+    if (doesTypeExtendsCore(receiverType, checker, new Set(), coreType)) {
+      return { name: `${receiver.getText()}.${method}`, rejects }
+    }
+  }
+
+  return undefined
+}

package/src/utils/find-zod-transform.test.ts

@@ -0,0 +1,70 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import * as z from 'zod'
+import { findZodTransform } from './find-zod-transform.js'
+
+test('a schema with no transform is reported as clean', () => {
+  assert.equal(findZodTransform(z.object({ id: z.string() })), undefined)
+  assert.equal(findZodTransform(z.string().min(1).trim()), undefined)
+  // a refinement narrows the value, it does not change its shape
+  assert.equal(
+    findZodTransform(z.object({ id: z.string() }).refine(() => true)),
+    undefined
+  )
+})
+
+test('a transform on the schema itself is found at the root', () => {
+  assert.equal(
+    findZodTransform(z.object({ id: z.string() }).transform((v) => v)),
+    ''
+  )
+})
+
+test('a transform on a field is found by path', () => {
+  assert.equal(
+    findZodTransform(
+      z.object({
+        id: z.string(),
+        when: z.string().transform((s) => new Date(s)),
+      })
+    ),
+    '.when'
+  )
+})
+
+test('a transform is found through wrappers, arrays and unions', () => {
+  assert.equal(
+    findZodTransform(
+      z.object({ tags: z.array(z.string().transform((s) => s.trim())) })
+    ),
+    '.tags[]'
+  )
+  assert.equal(
+    findZodTransform(z.object({ n: z.string().transform(Number).optional() })),
+    '.n'
+  )
+  assert.equal(
+    findZodTransform(
+      z.object({ v: z.union([z.string(), z.number().transform(String)]) })
+    ),
+    '.v|1'
+  )
+  assert.equal(
+    findZodTransform(
+      z.object({
+        m: z.record(
+          z.string(),
+          z.string().transform((s) => s)
+        ),
+      })
+    ),
+    '.m[]'
+  )
+})
+
+test('a self-referencing schema terminates instead of recursing forever', () => {
+  const node: z.ZodType = z.lazy(() =>
+    z.object({ name: z.string(), children: z.array(node) })
+  )
+  assert.equal(findZodTransform(node), undefined)
+})

package/src/utils/find-zod-transform.ts

@@ -0,0 +1,103 @@
+/**
+ * Locate a `.transform()` anywhere inside a Zod schema.
+ *
+ * A transform is why a schema cannot be a function's `input`: the value the
+ * caller sends and the value the function receives are different, and a wire
+ * contract has to describe one shape. Zod says so twice, in two different
+ * places, and neither says it usefully on its own — `toJSONSchema` with
+ * `unrepresentable: 'any'` quietly yields `{}`, a schema that accepts
+ * everything, and `zodToTs` throws about TypeScript rather than about the
+ * wiring. Finding it up front lets the diagnostic name the schema, the path,
+ * and the call.
+ *
+ * Zod 4 models `x.transform(fn)` as a `pipe` whose `out` is a `transform`, so
+ * the walk looks for that node rather than for the method.
+ */
+
+/** Max nodes visited, so a pathological or cyclic schema cannot hang the walk. */
+const MAX_NODES = 10_000
+
+interface ZodNode {
+  _zod?: { def?: Record<string, any> }
+}
+
+const isNode = (value: unknown): value is ZodNode =>
+  typeof value === 'object' &&
+  value !== null &&
+  typeof (value as ZodNode)._zod?.def?.type === 'string'
+
+/**
+ * The path to the first `.transform()` found — `''` when the transform is the
+ * schema itself, `'.user.email'` when it is nested — or `undefined` when there
+ * is none.
+ */
+export function findZodTransform(schema: unknown): string | undefined {
+  const seen = new Set<unknown>()
+  let budget = MAX_NODES
+
+  const walk = (node: unknown, path: string): string | undefined => {
+    if (budget-- <= 0 || !isNode(node) || seen.has(node)) return undefined
+    seen.add(node)
+
+    const def = node._zod!.def!
+    if (def.type === 'transform') return path
+
+    const children: Array<[unknown, string]> = []
+    switch (def.type) {
+      case 'object':
+      case 'interface':
+        for (const [key, child] of Object.entries(def.shape ?? {})) {
+          children.push([child, `${path}.${key}`])
+        }
+        break
+      case 'array':
+      case 'set':
+        children.push([def.element, `${path}[]`])
+        break
+      case 'tuple':
+        for (const [i, child] of (def.items ?? []).entries()) {
+          children.push([child, `${path}[${i}]`])
+        }
+        if (def.rest) children.push([def.rest, `${path}[]`])
+        break
+      case 'union':
+        for (const [i, child] of (def.options ?? []).entries()) {
+          children.push([child, `${path}|${i}`])
+        }
+        break
+      case 'intersection':
+        children.push([def.left, path], [def.right, path])
+        break
+      case 'record':
+      case 'map':
+        children.push(
+          [def.keyType, `${path}[key]`],
+          [def.valueType, `${path}[]`]
+        )
+        break
+      case 'pipe':
+        // `.transform()` itself: report the pipe's own path, not `out`'s.
+        children.push([def.in, path], [def.out, path])
+        break
+      default:
+        // optional, nullable, default, prefault, nonoptional, readonly, catch,
+        // promise, lazy, success — every wrapper Zod spells `innerType`.
+        if (def.innerType) children.push([def.innerType, path])
+        if (def.getter) {
+          try {
+            children.push([def.getter(), path])
+          } catch {
+            // A lazy schema that cannot be forced tells us nothing; skip it.
+          }
+        }
+    }
+
+    for (const [child, childPath] of children) {
+      const found = walk(child, childPath)
+      if (found !== undefined) return found
+    }
+    return undefined
+  }
+
+  return walk(schema, '')
+}

package/src/utils/schema-generator.test.ts

@@ -3,6 +3,7 @@ import assert from 'node:assert/strict'
 import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
+import { fileURLToPath } from 'url'
 
 import { getInitialInspectorState } from '../inspector.js'
 import { generateAllSchemas, schemaRuntimeFile } from './schema-generator.js'
@@ -223,3 +224,49 @@ describe('schemaRuntimeFile', () => {
     assert.equal(schemaRuntimeFile(orphan), orphan)
   })
 })
+
+describe('a Zod schema that cannot be a wire contract', () => {
+  test('names .transform() and its own error code, not a downstream one', async () => {
+    // A transform used to surface as PKU724 — the *bad `#pikku/*` import* error
+    // — because the schema failed to convert, its generated leaf never got
+    // written, and the type that leaf feeds resolved to an error type. The
+    // message sent you to an import block that was fine.
+    // Inside the package, so the fixture's `import 'zod'` resolves the same
+    // way a project's would; a tmpdir has no node_modules above it.
+    const dir = mkdtempSync(
+      join(fileURLToPath(new URL('../../', import.meta.url)), '.zod-transform-')
+    )
+    try {
+      const file = join(dir, 'schema.ts')
+      writeFileSync(
+        file,
+        `import * as z from 'zod'\n` +
+          `export const CreateAssessment = z.object({ patientId: z.string(), when: z.string().transform((s) => new Date(s)) })\n`
+      )
+      const state = getInitialInspectorState(dir) as any
+      state.schemaLookup.set('CreateAssessmentInput', {
+        variableName: 'CreateAssessment',
+        sourceFile: file,
+        vendor: 'zod',
+      })
+
+      const errors: string[] = []
+      await assert.rejects(() =>
+        generateAllSchemas(
+          { ...logger, error: (m: string) => errors.push(m) },
+          { tsconfig: join(projectDir, 'tsconfig.json') },
+          state
+        )
+      )
+
+      const reported = errors.join('\n')
+      assert.match(reported, /PKU491/)
+      assert.match(reported, /CreateAssessmentInput/)
+      assert.match(reported, /\.transform\(\)/)
+      assert.match(reported, /\.when/)
+      assert.doesNotMatch(reported, /PKU724/)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})

package/src/utils/schema-generator.ts

@@ -12,6 +12,7 @@ import { createGenerator, RootlessError } from 'ts-json-schema-generator'
 import { register } from 'tsx/esm/api'
 import * as z from 'zod'
 import { zodToTs, createAuxiliaryTypeStore } from 'zod-to-ts'
+import { findZodTransform } from './find-zod-transform.js'
 import type { FunctionsMeta } from '@pikku/core/services'
 import type { JSONValue } from '@pikku/core/utils'
 import type { HTTPWiringsMeta } from '@pikku/core/http'
@@ -508,6 +509,19 @@ function processZodSchema(
   fakeSourceFile: ts.SourceFile,
   logger: InspectorLogger
 ): void {
+  const transformPath = findZodTransform(zodSchema)
+  if (transformPath !== undefined) {
+    const where = transformPath === '' ? 'the schema itself' : transformPath
+    throw new Error(
+      `[${ErrorCode.SCHEMA_TRANSFORM_NOT_SUPPORTED}] '${schemaName}' contains a .transform() at ${where}.\n` +
+        'A transform makes the value sent and the value received two different ' +
+        'shapes, and a wire contract describes one: it cannot be expressed in ' +
+        'JSON Schema or in the generated TypeScript.\n' +
+        'Validate with the plain schema and apply the transform inside the ' +
+        'function, or move it to the output type.'
+    )
+  }
+
   const schema = z.toJSONSchema(zodSchema, {
     unrepresentable: 'any',
     override: ({ zodSchema, jsonSchema }) => {