@pikku/inspector 0.12.50 → 0.12.54

package/src/inspector.ts

@@ -15,22 +15,31 @@ import {
   aggregateRequiredServices,
   stampAuthHandlerServices,
   validateAgentModels,
+  validateAgentToolReferences,
   validateSecretOverrides,
   validateVariableOverrides,
   validateCredentialOverrides,
   validateRemoteAddonDependencies,
   validateRemoteAddonAuth,
   validateScopeReferences,
+  validateSystemRoleScopes,
+  validatePersonaRoles,
   computeResolvedIOTypes,
   computeMiddlewareGroupsMeta,
   computePermissionsGroupsMeta,
   computeRequiredSchemas,
+  computeSecretBrokers,
+  validateNoSecretAliasServices,
+  validateSecretUsage,
   computeDiagnostics,
   validateSchemaWiringSeparation,
   validateScenarioServices,
   validateScenarioSteps,
   validateWorkflowGraphAddons,
 } from './utils/post-process.js'
+import { validateExposedFunctionsGated } from './utils/validate-exposed-functions-gated.js'
+import { validateTagsResolveToMiddleware } from './utils/validate-tags-resolve-to-middleware.js'
+import { annotateHttpRouteAuth } from './utils/annotate-http-route-auth.js'
 import { generateOpenAPISpec } from './utils/serialize-openapi-json.js'
 import { pikkuState } from '@pikku/core/internal'
 import { resolveLatestVersions } from './utils/resolve-versions.js'
@@ -40,6 +49,7 @@ import {
   finalizeWorkflowWires,
 } from './utils/workflow/graph/finalize-workflow-wires.js'
 import { generateAllSchemas } from './utils/schema-generator.js'
+import { extractSecretUsage } from './utils/extract-secret-usage.js'
 import {
   loadAddonFunctionsMeta,
   loadAddonSchemas,
@@ -169,6 +179,7 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
     secrets: {
       definitions: [],
       files: new Set(),
+      usage: new Map(),
     },
     credentials: {
       definitions: [],
@@ -178,6 +189,14 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       definitions: [],
       files: new Set(),
     },
+    systemRoles: {
+      definitions: [],
+      files: new Set(),
+    },
+    personas: {
+      definitions: [],
+      files: new Set(),
+    },
     variables: {
       definitions: [],
       files: new Set(),
@@ -354,6 +373,13 @@ export const inspect = async (
 
   const state = getInitialInspectorState(rootDir)
 
+  for (const sourceFile of sourceFiles) {
+    const usage = extractSecretUsage(sourceFile)
+    if (usage.keys.length > 0 || usage.dynamic.length > 0) {
+      state.secrets.usage.set(sourceFile.fileName, usage)
+    }
+  }
+
   // First sweep: add all functions
   const startSetup = performance.now()
   for (const sourceFile of sourceFiles) {
@@ -451,11 +477,21 @@ export const inspect = async (
     computeResolvedIOTypes(state)
     computeMiddlewareGroupsMeta(state)
     computePermissionsGroupsMeta(state)
+    computeSecretBrokers(state)
+    validateNoSecretAliasServices(logger, checker, state)
+    validateSecretUsage(logger, state)
     computeDiagnostics(state)
     validateSchemaWiringSeparation(logger, state)
     validateWorkflowGraphAddons(logger, state)
     validateScenarioServices(logger, state)
     validateScenarioSteps(logger, state)
+    // Needs every route, every function and every wireAddon declaration
+    // together, so it can only run once the whole program is inspected.
+    annotateHttpRouteAuth(state)
+    // Last of the validators: they read function meta and every wireAddon
+    // declaration together, so they need the whole program inspected.
+    validateExposedFunctionsGated(logger, state)
+    validateTagsResolveToMiddleware(logger, state)
 
     if (options.openAPI) {
       state.openAPISpec = await generateOpenAPISpec(
@@ -469,12 +505,15 @@ export const inspect = async (
     }
 
     validateAgentModels(logger, state)
+    validateAgentToolReferences(logger, state, options)
     validateSecretOverrides(logger, state)
     validateVariableOverrides(logger, state)
     validateCredentialOverrides(logger, state)
     validateRemoteAddonDependencies(logger, state)
     validateRemoteAddonAuth(logger, state)
     validateScopeReferences(logger, state)
+    validateSystemRoleScopes(logger, state)
+    validatePersonaRoles(logger, state)
   }
 
   state.program = program

package/src/types.ts

@@ -1,4 +1,5 @@
 import type * as ts from 'typescript'
+import type { SecretUsage } from './utils/extract-secret-usage.js'
 import type { ChannelMessageMeta, ChannelsMeta } from '@pikku/core/channel'
 import type { GatewaysMeta } from '@pikku/core/gateway'
 import type { HTTPWiringsMeta } from '@pikku/core/http'
@@ -18,6 +19,8 @@ import type { NodesMeta } from '@pikku/core/node'
 import type { SecretDefinitions } from '@pikku/core/secret'
 import type { CredentialDefinitions } from '@pikku/core/credential'
 import type { ScopeDefinitions } from '@pikku/core/scope'
+import type { SystemRoleDefinitions } from '@pikku/core/role'
+import type { PersonaDefinitions } from '@pikku/core/persona'
 import type { VariableDefinitions } from '@pikku/core/variable'
 import type { TypesMap } from './types-map.js'
 import type {
@@ -48,14 +51,31 @@ export type MetaInputTypes = Map<
   }
 >
 
-export interface MiddlewareGroupMeta {
+/** One `addHTTPMiddleware`/`addTagMiddleware`/`addChannelMiddleware` call. */
+export interface MiddlewareRegistration {
   exportName: string | null // null if not exported
   sourceFile: string
   position: number
+  isFactory: boolean // true if wrapped in () => add...()
+}
+
+export interface MiddlewareGroupMeta extends MiddlewareRegistration {
   services: FunctionServicesMeta
   count: number
   instanceIds: string[]
-  isFactory: boolean // true if wrapped in () => add...()
+  /**
+   * The registrations after the first, when several files add middleware for
+   * the same pattern or tag.
+   *
+   * A group is keyed by its pattern/tag, so without this a second file's call
+   * overwrote the first's and only the survivor got an import emitted into
+   * pikku-middleware.gen.ts — the losing file was never imported, so its
+   * registration never ran. The runtime composes repeated registrations for a
+   * pattern happily; only codegen dropped one, which is how an app could lose
+   * its session-bridge middleware to an unrelated `'*'` group and see nothing
+   * go wrong until a request arrived without a session.
+   */
+  additionalRegistrations?: MiddlewareRegistration[]
 }
 
 export interface InspectorHTTPState {
@@ -272,6 +292,12 @@ export type InspectorOptions = Partial<{
   setupOnly: boolean
   rootDir: string
   isAddon: boolean
+  /**
+   * Fail the build on metadata that only an agent needs — currently an agent
+   * tool with no description. Off by default: the runtime falls back to the
+   * tool's own name, so this is a quality gate rather than a correctness one.
+   */
+  strictMeta: boolean
   sourceFile: ts.SourceFile
   /**
    * The project's tsconfig, read for its path mappings only. The inspector's
@@ -309,6 +335,15 @@ export type InspectorOptions = Partial<{
    * function, which is expensive. Enabled via `pikku all --security`.
    */
   classificationCheck: boolean
+  /**
+   * Escape hatches the project has opted into, from `allow` in
+   * `pikku.config.json`. Absent or false means the feature is refused with a
+   * critical naming the flag that would permit it.
+   */
+  allow: Partial<{
+    permissionsInBody: boolean
+    complexWorkflows: boolean
+  }>
 }>
 
 export interface InspectorLogger {
@@ -530,6 +565,15 @@ export interface InspectorState {
         package: string
         rpcEndpoint?: string
         mcp?: boolean
+        /**
+         * The addon's own gates. `runPikkuFunc` applies these to every function
+         * in the package, on every wiring path — not just `namespace:function`.
+         * Absent when the declared value was not a statically-knowable literal,
+         * which must be read as "unknown", never as "ungated".
+         */
+        auth?: boolean
+        tags?: string[]
+        scopes?: string[]
         /** True when declared via `wireRemoteAddon` — import the addon's `.remote.gen` map, not `.internal.gen` */
         remote?: boolean
         /** wireRemoteAddon: whether an `auth` binding was supplied (vs a public surface) */
@@ -586,6 +630,8 @@ export interface InspectorState {
   secrets: {
     definitions: SecretDefinitions
     files: Set<string>
+    /** Secret reads found per source file, keyed by absolute path. */
+    usage: Map<string, SecretUsage>
   }
   credentials: {
     definitions: CredentialDefinitions
@@ -595,6 +641,14 @@ export interface InspectorState {
     definitions: ScopeDefinitions
     files: Set<string>
   }
+  systemRoles: {
+    definitions: SystemRoleDefinitions
+    files: Set<string>
+  }
+  personas: {
+    definitions: PersonaDefinitions
+    files: Set<string>
+  }
   variables: {
     definitions: VariableDefinitions
     files: Set<string>

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

@@ -0,0 +1,163 @@
+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: {
+          inline: { pikkuFuncId: 'inline', sessionless: true },
+          target: { pikkuFuncId: 'target', sessionless: false },
+        },
+      },
+      http: {
+        meta: {
+          get: {
+            '/thing': {
+              pikkuFuncId: 'inline',
+              refTarget: 'target',
+              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

@@ -0,0 +1,52 @@
+import type { InspectorState } from '../types.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 = state.functions.meta[route.refTarget ?? 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-secret-sinks.ts

@@ -0,0 +1,145 @@
+import * as ts from 'typescript'
+import { findPiiPaths } from './check-pii-output.js'
+import { doesTypeExtendsCore } from './does-type-extend-core-type.js'
+
+export type SecretSinkViolation = {
+  /** 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
+}
+
+/**
+ * A method that writes its arguments somewhere a secret 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.
+ */
+const SINKS: Array<{ coreType: string; methods: '*' | string[] }> = [
+  { coreType: 'Logger', methods: '*' },
+  { coreType: 'QueueService', methods: ['add'] },
+  { coreType: 'EmailService', methods: ['send'] },
+  { coreType: 'WebhookService', methods: ['send'] },
+  { coreType: 'AuditService', methods: ['audit', 'write'] },
+  { coreType: 'AuditLog', methods: ['write'] },
+]
+
+/**
+ * Finds revealed vault secrets 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.
+ *
+ * The brand is optional by design, so an explicit annotation (`const t: string =
+ * s.reveal()`) 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 findRevealedSecretSinks(
+  checker: ts.TypeChecker,
+  handler: ts.Node
+): SecretSinkViolation[] {
+  const violations: SecretSinkViolation[] = []
+
+  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 = findSecretExpression(checker, arg)
+          if (found) {
+            violations.push({
+              sink,
+              path: found.getText(),
+              line:
+                found
+                  .getSourceFile()
+                  .getLineAndCharacterOfPosition(found.getStart()).line + 1,
+            })
+          }
+        }
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(handler)
+
+  return violations
+}
+
+/**
+ * Finds the first expression inside a sink argument whose own type carries the
+ * secret brand, 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 findSecretExpression(
+  checker: ts.TypeChecker,
+  node: ts.Node
+): ts.Expression | 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 found = findSecretExpression(checker, child)
+    if (found) return found
+  }
+
+  if (ts.isExpression(node) && !ts.isStringLiteralLike(node)) {
+    const type = checker.getTypeAtLocation(node)
+    const isSecret = findPiiPaths(checker, type).some(
+      (f) => f.classification === 'secret'
+    )
+    if (isSecret) return node
+  }
+
+  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
+): string | undefined {
+  const method = callee.name.text
+  const receiver = callee.expression
+
+  if (ts.isIdentifier(receiver) && receiver.text === 'console') {
+    return `console.${method}`
+  }
+
+  const receiverType = checker.getTypeAtLocation(receiver)
+  for (const { coreType, methods } of SINKS) {
+    if (methods !== '*' && !methods.includes(method)) continue
+    if (doesTypeExtendsCore(receiverType, checker, new Set(), coreType)) {
+      return `${receiver.getText()}.${method}`
+    }
+  }
+
+  return undefined
+}

package/src/utils/extract-function-name.ts

@@ -46,9 +46,19 @@ export function funcIdToTypeName(id: string): string {
 }
 
 /**
- * `pikkuScenarioStep({ name })` is the one wrapper whose `name` is its identity:
- * scenarios reference a step by that string, so it must become the pikkuFuncId
- * (and hence the generated step map's key), not just a cosmetic label the way
+ * The step wrappers, whichever kind of subject acts in them. A scenario calls a
+ * platform or addon step by name exactly as it calls a persona one.
+ */
+const SCENARIO_STEP_WRAPPERS = new Set([
+  'pikkuScenarioStep',
+  'pikkuPlatformScenarioStep',
+  'pikkuAddonScenarioStep',
+])
+
+/**
+ * A scenario step is the one wrapper whose `name` is its identity: scenarios
+ * reference a step by that string, so it must become the pikkuFuncId (and hence
+ * the generated step map's key), not just a cosmetic label the way
  * `pikkuMiddleware`/`pikkuAgent` use it.
  */
 function extractScenarioStepName(
@@ -58,7 +68,7 @@ function extractScenarioStepName(
   if (
     !ts.isCallExpression(callExpr) ||
     !ts.isIdentifier(callExpr.expression) ||
-    callExpr.expression.text !== 'pikkuScenarioStep'
+    !SCENARIO_STEP_WRAPPERS.has(callExpr.expression.text)
   ) {
     return
   }

package/src/utils/extract-function-node.ts

@@ -4,6 +4,17 @@ import {
   resolveFunctionDeclaration,
 } from './type-utils.js'
 
+/**
+ * Where a config object's implementation can live, in the order it is looked for.
+ *
+ * `func` is the ordinary case. A `pikkuScenarioStep` instead declares one
+ * implementation per surface, and every binding shares the step's input and
+ * output — that is what makes them interchangeable — so any one of them types
+ * the step. `default` is preferred because it is the binding every step is
+ * expected to have.
+ */
+const IMPLEMENTATION_KEYS = ['func', 'default', 'browser', 'cli'] as const
+
 /**
  * Extracts the actual function node from a pikkuFunc/pikkuWorkflowFunc call
  * Handles both direct function form and config object form { func: ... }
@@ -22,12 +33,13 @@ export function extractFunctionNode(
   // Check if first argument is a config object with 'func' property
   if (ts.isObjectLiteralExpression(firstArg)) {
     isDirectFunction = false
-    const funcInitializer = getPropertyAssignmentInitializer(
-      firstArg,
-      'func',
-      true,
-      checker
-    )
+    let funcInitializer: ts.Expression | undefined
+    for (const key of IMPLEMENTATION_KEYS) {
+      funcInitializer =
+        getPropertyAssignmentInitializer(firstArg, key, true, checker) ??
+        undefined
+      if (funcInitializer) break
+    }
 
     if (funcInitializer) {
       funcNode = funcInitializer