@pikku/inspector 0.12.74 → 0.12.81

package/src/utils/annotate-http-route-auth.test.ts

@@ -1,161 +0,0 @@
-import assert from 'node:assert/strict'
-import { describe, test } from 'node:test'
-import { annotateHttpRouteAuth } from './annotate-http-route-auth.js'
-
-const ADDON_PACKAGE = '@addon/console'
-
-/**
- * A single GET route plus the function it points at, with the four inputs the
- * resolution reads spread across both.
- */
-const resolve = (
-  route: Record<string, unknown>,
-  meta: Record<string, unknown> = {},
-  addons: Record<string, unknown> = {}
-): boolean | undefined => {
-  const state = {
-    functions: { meta: { handler: { pikkuFuncId: 'handler', ...meta } } },
-    http: {
-      meta: {
-        get: {
-          '/thing': {
-            pikkuFuncId: 'handler',
-            route: '/thing',
-            method: 'get',
-            ...route,
-          },
-        },
-      },
-    },
-    rpc: { wireAddonDeclarations: new Map(Object.entries(addons)) },
-  } as any
-
-  annotateHttpRouteAuth(state)
-  return state.http.meta.get['/thing'].requiresSession
-}
-
-describe('annotateHttpRouteAuth', () => {
-  test('a pikkuFunc always requires a session', () => {
-    assert.equal(resolve({}, { sessionless: false }), true)
-  })
-
-  test('a sessionless function on a plain route does not', () => {
-    assert.equal(resolve({}, { sessionless: true }), false)
-  })
-
-  test("the function's own auth requires one", () => {
-    assert.equal(resolve({}, { sessionless: true, auth: true }), true)
-  })
-
-  test("the route's auth requires one, even of a sessionless function", () => {
-    assert.equal(resolve({ auth: true }, { sessionless: true }), true)
-  })
-
-  test('an explicit auth: false on the route does not undo the function', () => {
-    // Layers only ever tighten. A route cannot open a pikkuFunc back up.
-    assert.equal(resolve({ auth: false }, { sessionless: false }), true)
-  })
-
-  test('function scopes require one', () => {
-    // Scopes are matched against the session's and fail closed, so an
-    // anonymous caller is rejected — reporting the route as open would be a lie.
-    assert.equal(resolve({}, { sessionless: true, scopes: ['admin'] }), true)
-  })
-
-  test("the addon's auth requires one", () => {
-    assert.equal(
-      resolve(
-        { packageName: ADDON_PACKAGE },
-        { sessionless: true },
-        { console: { package: ADDON_PACKAGE, auth: true } }
-      ),
-      true
-    )
-  })
-
-  test("the addon's scopes require one", () => {
-    assert.equal(
-      resolve(
-        { packageName: ADDON_PACKAGE },
-        { sessionless: true },
-        { console: { package: ADDON_PACKAGE, scopes: ['admin'] } }
-      ),
-      true
-    )
-  })
-
-  test("another package's addon gate does not reach this route", () => {
-    assert.equal(
-      resolve(
-        { packageName: '@app/api' },
-        { sessionless: true },
-        { console: { package: ADDON_PACKAGE, auth: true } }
-      ),
-      false
-    )
-  })
-
-  test('an ungated addon leaves the route as its function found it', () => {
-    assert.equal(
-      resolve(
-        { packageName: ADDON_PACKAGE },
-        { sessionless: true },
-        { console: { package: ADDON_PACKAGE } }
-      ),
-      false
-    )
-  })
-
-  test('a ref route resolves against its target', () => {
-    const state = {
-      functions: { meta: {} },
-      addonFunctions: {
-        console: { target: { pikkuFuncId: 'target', sessionless: false } },
-      },
-      http: {
-        meta: {
-          get: {
-            '/thing': {
-              pikkuFuncId: 'console:target',
-              packageName: ADDON_PACKAGE,
-              route: '/thing',
-              method: 'get',
-            },
-          },
-        },
-      },
-      rpc: { wireAddonDeclarations: new Map() },
-    } as any
-
-    annotateHttpRouteAuth(state)
-    assert.equal(state.http.meta.get['/thing'].requiresSession, true)
-  })
-
-  test('a route whose function meta is missing is not reported as open', () => {
-    const state = {
-      functions: { meta: {} },
-      http: {
-        meta: {
-          get: {
-            '/thing': {
-              pikkuFuncId: 'gone',
-              route: '/thing',
-              method: 'get',
-              auth: true,
-            },
-          },
-        },
-      },
-      rpc: { wireAddonDeclarations: new Map() },
-    } as any
-
-    annotateHttpRouteAuth(state)
-    assert.equal(state.http.meta.get['/thing'].requiresSession, true)
-  })
-
-  test('tolerates http state being absent', () => {
-    assert.doesNotThrow(() =>
-      annotateHttpRouteAuth({ functions: { meta: {} } } as any)
-    )
-  })
-})

package/src/utils/annotate-http-route-auth.ts

@@ -1,53 +0,0 @@
-import type { InspectorState } from '../types.js'
-import { resolveFunctionMeta } from './resolve-function-meta.js'
-
-/**
- * Resolve, per HTTP route, whether reaching it requires a session.
- *
- * Four separate places can demand one — the function's `sessionless`, the
- * function's own `auth`, the route's (or its group's) `auth`, and the addon the
- * function belongs to — and they combine with OR: any of them is enough. Until
- * this was written down, "which routes are open?" could only be answered by
- * joining all four by hand, and getting the join wrong reads an open route as a
- * closed one, which is the direction that costs something.
- *
- * A scope gate counts as requiring a session. Scopes are checked against the
- * session's and fail closed, so an anonymous caller is rejected either way; not
- * counting them would mark a route open that nobody can reach anonymously.
- *
- * Anything not statically knowable resolves to requiring a session, matching
- * `validateExposedFunctionsGated`: an over-cautious `true` costs a route that
- * looks stricter than it is, a wrong `false` costs an audit.
- *
- * knowledge: decisions/security/addon-auth-and-tags-only-tighten.md
- */
-export function annotateHttpRouteAuth(state: InspectorState): void {
-  const gatedPackages = packagesGatedByTheirAddon(state)
-
-  for (const routes of Object.values(state.http?.meta ?? {})) {
-    for (const route of Object.values(routes)) {
-      const meta = resolveFunctionMeta(state, route.pikkuFuncId)
-
-      route.requiresSession =
-        // A pikkuFunc always requires a session, on every path.
-        meta?.sessionless === false ||
-        meta?.auth === true ||
-        (meta?.scopes?.length ?? 0) > 0 ||
-        route.auth === true ||
-        (route.packageName !== undefined &&
-          gatedPackages.has(route.packageName))
-    }
-  }
-}
-
-/** Packages whose `wireAddon` demands a session from everything inside them. */
-function packagesGatedByTheirAddon(state: InspectorState): Set<string> {
-  const gated = new Set<string>()
-  for (const declaration of state.rpc?.wireAddonDeclarations?.values() ?? []) {
-    if (!declaration.package) continue
-    if (declaration.auth === true || (declaration.scopes?.length ?? 0) > 0) {
-      gated.add(declaration.package)
-    }
-  }
-  return gated
-}

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

@@ -1,215 +0,0 @@
-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/check-pii-output.ts

@@ -1,120 +0,0 @@
-import * as ts from 'typescript'
-
-export type ClassifiedField = {
-  path: string
-  classification: 'private' | 'pii' | 'secret' | string
-}
-
-/**
- * Recursively walks a resolved TypeScript type looking for `__classification__` brands —
- * the structural marker emitted by `Private<T>`, `Pii<T>`, and `Secret<T>`.
- *
- * `Private<T> = T & { readonly __classification__: 'private' }` shows up in the TS type
- * system as an intersection whose constituents include a type with a `__classification__`
- * property.  We detect that by checking whether any constituent of an
- * intersection exposes a property named `__classification__`.
- *
- * Returns the list of classified fields found, each with its dotted path and
- * classification level (e.g. `[{ path: 'email', classification: 'private' }]`).
- * An empty array means clean.
- */
-export function findPiiPaths(
-  checker: ts.TypeChecker,
-  type: ts.Type,
-  path = '',
-  depth = 0,
-  seen = new Set<ts.Type>()
-): ClassifiedField[] {
-  if (depth > 8 || seen.has(type)) return []
-  seen.add(type)
-
-  // ── Is this type itself branded? ─────────────────────────────────────────
-  // Private<T> = T & { readonly __classification__?: 'private' }  →  isIntersection()
-  // where one constituent has a `__classification__` property whose type is a
-  // string literal. The marker is OPTIONAL (so plain values stay assignable to
-  // branded columns), which means its resolved type is `'private' | undefined` —
-  // a union, not a bare literal. Read the level union-aware via `literalString`,
-  // otherwise pii/secret silently downgrade to the `'private'` fallback.
-  if (type.isIntersection()) {
-    for (const t of type.types) {
-      const classificationProp = t
-        .getProperties()
-        .find((p) => p.name === '__classification__')
-      if (classificationProp) {
-        const decl =
-          classificationProp.valueDeclaration ??
-          classificationProp.declarations?.[0]
-        const classification = decl
-          ? (literalString(
-              checker.getTypeOfSymbolAtLocation(classificationProp, decl)
-            ) ?? 'private')
-          : 'private'
-        return [{ path: path || '<return value>', classification }]
-      }
-    }
-  }
-
-  const violations: ClassifiedField[] = []
-
-  // ── Union: check every branch ─────────────────────────────────────────────
-  if (type.isUnion()) {
-    for (const branch of type.types) {
-      violations.push(...findPiiPaths(checker, branch, path, depth, seen))
-    }
-    return violations
-  }
-
-  // ── Object: recurse into named properties ─────────────────────────────────
-  if (type.flags & ts.TypeFlags.Object) {
-    const ref = type as ts.TypeReference
-    for (const arg of (ref as any).typeArguments ?? []) {
-      violations.push(...findPiiPaths(checker, arg, path, depth + 1, seen))
-    }
-
-    const numberIndex = checker.getIndexTypeOfType(type, ts.IndexKind.Number)
-    if (numberIndex) {
-      const idxPath = path ? `${path}[]` : '[]'
-      violations.push(
-        ...findPiiPaths(checker, numberIndex, idxPath, depth + 1, seen)
-      )
-    }
-    const stringIndex = checker.getIndexTypeOfType(type, ts.IndexKind.String)
-    if (stringIndex) {
-      const idxPath = path ? `${path}[*]` : '[*]'
-      violations.push(
-        ...findPiiPaths(checker, stringIndex, idxPath, depth + 1, seen)
-      )
-    }
-
-    for (const prop of type.getProperties()) {
-      if (prop.name.startsWith('__')) continue
-      const decl = prop.valueDeclaration ?? prop.declarations?.[0]
-      if (!decl) continue
-      const propType = checker.getTypeOfSymbolAtLocation(prop, decl)
-      const subPath = path ? `${path}.${prop.name}` : prop.name
-      violations.push(
-        ...findPiiPaths(checker, propType, subPath, depth + 1, seen)
-      )
-    }
-  }
-
-  return violations
-}
-
-/**
- * Recover a string-literal value from a type that may be the literal itself or a
- * union containing it (e.g. `'private' | undefined`, produced by the optional
- * `__classification__?` marker). Returns undefined when no string literal is
- * present so the caller can apply its own fallback.
- */
-function literalString(type: ts.Type): string | undefined {
-  const value = (type as { value?: unknown }).value
-  if (typeof value === 'string') return value
-  if (type.isUnion()) {
-    for (const member of type.types) {
-      const found = literalString(member)
-      if (found !== undefined) return found
-    }
-  }
-  return undefined
-}

package/src/utils/compute-diagnostics.test.ts

@@ -1,106 +0,0 @@
-import { test, describe } from 'node:test'
-import { strict as assert } from 'node:assert'
-import { computeDiagnostics } from './post-process.js'
-import type { InspectorState } from '../types.js'
-import { ErrorCode } from '../error-codes.js'
-
-function stateWithFunctions(
-  meta: InspectorState['functions']['meta'],
-  dynamicImportIds: string[] = []
-): InspectorState {
-  return {
-    functions: { meta, dynamicImportIds: new Set(dynamicImportIds) },
-    middleware: { definitions: {} },
-    permissions: { definitions: {} },
-  } as unknown as InspectorState
-}
-
-describe('computeDiagnostics', () => {
-  test('flags a user-authored function that does not destructure services', () => {
-    const state = stateWithFunctions({
-      myFunc: {
-        pikkuFuncId: 'myFunc',
-        inputSchemaName: null,
-        outputSchemaName: null,
-        sourceFile: '/project/src/my-func.ts',
-        services: { optimized: false, services: ['kysely'] },
-      },
-    })
-    computeDiagnostics(state)
-    assert.equal(state.diagnostics.length, 1)
-    assert.equal(state.diagnostics[0].code, ErrorCode.SERVICES_NOT_DESTRUCTURED)
-  })
-
-  test('does NOT flag a generated .gen.ts function (user cannot edit it)', () => {
-    const state = stateWithFunctions({
-      cliRaw: {
-        pikkuFuncId: 'cliRaw',
-        inputSchemaName: null,
-        outputSchemaName: null,
-        sourceFile: '/project/src/wirings/cli-channel.gen.ts',
-        services: { optimized: false, services: ['kysely'] },
-      },
-      authHandler: {
-        pikkuFuncId: 'authHandler',
-        inputSchemaName: null,
-        outputSchemaName: null,
-        sourceFile: '/project/.pikku/auth.gen.ts',
-        wires: { optimized: false, wires: ['http'] },
-      },
-    })
-    computeDiagnostics(state)
-    assert.equal(state.diagnostics.length, 0)
-  })
-
-  test('does NOT flag a synthetic route bridge with no source file', () => {
-    const state = stateWithFunctions({
-      'http:get:/workflow-run/:runId/stream': {
-        pikkuFuncId: 'http:get:/workflow-run/:runId/stream',
-        inputSchemaName: null,
-        outputSchemaName: null,
-        services: { optimized: false, services: [] },
-      },
-    })
-    computeDiagnostics(state)
-    assert.equal(state.diagnostics.length, 0)
-  })
-
-  test('flags a user-authored function that does a dynamic import in its body', () => {
-    const state = stateWithFunctions(
-      {
-        greedy: {
-          pikkuFuncId: 'greedy',
-          inputSchemaName: null,
-          outputSchemaName: null,
-          sourceFile: '/project/src/greedy.ts',
-          services: { optimized: true, services: ['logger'] },
-        },
-      },
-      ['greedy']
-    )
-    computeDiagnostics(state)
-    assert.equal(
-      state.diagnostics.filter(
-        (d) => d.code === ErrorCode.FUNCTION_DYNAMIC_IMPORT
-      ).length,
-      1
-    )
-  })
-
-  test('does NOT flag a dynamic import in a generated .gen.ts function', () => {
-    const state = stateWithFunctions(
-      {
-        authHandler: {
-          pikkuFuncId: 'authHandler',
-          inputSchemaName: null,
-          outputSchemaName: null,
-          sourceFile: '/project/.pikku/auth.gen.ts',
-          services: { optimized: true, services: [] },
-        },
-      },
-      ['authHandler']
-    )
-    computeDiagnostics(state)
-    assert.equal(state.diagnostics.length, 0)
-  })
-})