@pikku/inspector 0.12.50 → 0.12.52

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
@@ -530,6 +556,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 +621,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 +632,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/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

package/src/utils/extract-secret-usage.test.ts

@@ -0,0 +1,81 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import ts from 'typescript'
+import { extractSecretUsage } from './extract-secret-usage.js'
+
+const usageOf = (source: string) =>
+  extractSecretUsage(
+    ts.createSourceFile('/services.ts', source, ts.ScriptTarget.ESNext, true)
+  )
+
+describe('extractSecretUsage', () => {
+  test('collects a literal getSecret key', () => {
+    const usage = usageOf(`await secrets.getSecret('STRIPE_KEY')`)
+    assert.deepEqual(usage.keys, ['STRIPE_KEY'])
+    assert.deepEqual(usage.dynamic, [])
+  })
+
+  test('collects hasSecret and template literals with no substitutions', () => {
+    const usage = usageOf(
+      'await secrets.hasSecret(`NOTION_TOKEN`)\nawait secrets.getSecret("A")'
+    )
+    assert.deepEqual(usage.keys, ['A', 'NOTION_TOKEN'])
+  })
+
+  test('collects every key of a getSecrets array', () => {
+    const usage = usageOf(`await secrets.getSecrets(['B', 'A'])`)
+    assert.deepEqual(usage.keys, ['A', 'B'])
+  })
+
+  test('flags a computed key as dynamic', () => {
+    const usage = usageOf(`await secrets.getSecret(name)`)
+    assert.deepEqual(usage.keys, [])
+    assert.equal(usage.dynamic.length, 1)
+    assert.match(usage.dynamic[0]!, /^1:name$/)
+  })
+
+  test('flags a template literal with a substitution as dynamic', () => {
+    const usage = usageOf('await secrets.getSecret(`PREFIX_${suffix}`)')
+    assert.deepEqual(usage.keys, [])
+    assert.equal(usage.dynamic.length, 1)
+  })
+
+  test('flags a non-array getSecrets argument as dynamic', () => {
+    const usage = usageOf(`await secrets.getSecrets(keys)`)
+    assert.equal(usage.dynamic.length, 1)
+  })
+
+  test('records both the literal and the dynamic keys of one call', () => {
+    const usage = usageOf(`await secrets.getSecrets(['A', other])`)
+    assert.deepEqual(usage.keys, ['A'])
+    assert.equal(usage.dynamic.length, 1)
+  })
+
+  test('finds reads nested inside a factory body', () => {
+    const usage = usageOf(`
+      export const createSingletonServices = async ({ secrets }) => {
+        const key = await secrets.getSecret('DEEP_KEY')
+        return { thing: new Thing(key) }
+      }
+    `)
+    assert.deepEqual(usage.keys, ['DEEP_KEY'])
+  })
+
+  test('deduplicates a key read twice', () => {
+    const usage = usageOf(
+      `await secrets.getSecret('A'); await secrets.getSecret('A')`
+    )
+    assert.deepEqual(usage.keys, ['A'])
+  })
+
+  test('ignores unrelated calls', () => {
+    const usage = usageOf(`await variables.get('HOME'); logger.info('hi')`)
+    assert.deepEqual(usage.keys, [])
+    assert.deepEqual(usage.dynamic, [])
+  })
+
+  test('reports the line a dynamic read is on', () => {
+    const usage = usageOf(`const a = 1\nconst b = 2\nsecrets.getSecret(name)`)
+    assert.match(usage.dynamic[0]!, /^3:/)
+  })
+})

package/src/utils/extract-secret-usage.ts

@@ -0,0 +1,73 @@
+import ts from 'typescript'
+
+export type SecretUsage = {
+  /** Secret ids read with a string literal, so statically known. */
+  keys: string[]
+  /** Reads whose key could not be resolved statically, as `line:source`. */
+  dynamic: string[]
+}
+
+const SINGLE_KEY_METHODS = new Set(['getSecret', 'hasSecret'])
+const KEY_LIST_METHODS = new Set(['getSecrets'])
+
+const literalKey = (node: ts.Expression): string | undefined => {
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+    return node.text
+  }
+  return undefined
+}
+
+/** Secret reads in a file, whether the key is statically known or not. */
+export const extractSecretUsage = (sourceFile: ts.SourceFile): SecretUsage => {
+  const keys = new Set<string>()
+  const dynamic = new Set<string>()
+
+  const record = (node: ts.CallExpression, argument?: ts.Expression) => {
+    const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart())
+    dynamic.add(`${line + 1}:${(argument ?? node).getText()}`)
+  }
+
+  const visit = (node: ts.Node): void => {
+    if (
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression)
+    ) {
+      const method = node.expression.name.text
+      const [firstArgument] = node.arguments
+
+      if (SINGLE_KEY_METHODS.has(method)) {
+        if (!firstArgument) {
+          record(node)
+        } else {
+          const key = literalKey(firstArgument)
+          if (key === undefined) {
+            record(node, firstArgument)
+          } else {
+            keys.add(key)
+          }
+        }
+      } else if (KEY_LIST_METHODS.has(method)) {
+        if (firstArgument && ts.isArrayLiteralExpression(firstArgument)) {
+          for (const element of firstArgument.elements) {
+            const key = literalKey(element)
+            if (key === undefined) {
+              record(node, element)
+            } else {
+              keys.add(key)
+            }
+          }
+        } else {
+          record(node, firstArgument)
+        }
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+
+  visit(sourceFile)
+
+  return {
+    keys: [...keys].sort(),
+    dynamic: [...dynamic].sort(),
+  }
+}

package/src/utils/literal-properties.ts

@@ -0,0 +1,97 @@
+import * as ts from 'typescript'
+
+/**
+ * Readers for object-literal properties that must be statically knowable.
+ *
+ * Declarations extracted this way are never evaluated — the CLI reads them from
+ * source and writes them to JSON that a deployed stage carries without the app.
+ * So a computed value is not "unsupported", it is unreadable, and every reader
+ * here returns `undefined` for one rather than guessing.
+ */
+
+export const getProperty = (
+  config: ts.ObjectLiteralExpression,
+  name: string
+): ts.Expression | undefined => {
+  const property = config.properties.find(
+    (p) =>
+      ts.isPropertyAssignment(p) &&
+      (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+      p.name.text === name
+  )
+  return property && ts.isPropertyAssignment(property)
+    ? property.initializer
+    : undefined
+}
+
+export const stringProperty = (
+  config: ts.ObjectLiteralExpression,
+  name: string
+): string | undefined => {
+  const value = getProperty(config, name)
+  return value && ts.isStringLiteralLike(value) ? value.text : undefined
+}
+
+export const numberProperty = (
+  config: ts.ObjectLiteralExpression,
+  name: string
+): number | undefined => {
+  const value = getProperty(config, name)
+  if (!value) {
+    return undefined
+  }
+  // `-1` parses as a unary minus over a literal, not as a literal. Reading it
+  // rather than ignoring it is what lets a negative be *rejected* by the caller
+  // instead of silently dropped and defaulted.
+  if (
+    ts.isPrefixUnaryExpression(value) &&
+    value.operator === ts.SyntaxKind.MinusToken &&
+    ts.isNumericLiteral(value.operand)
+  ) {
+    return -Number(value.operand.text)
+  }
+  return ts.isNumericLiteral(value) ? Number(value.text) : undefined
+}
+
+export const booleanProperty = (
+  config: ts.ObjectLiteralExpression,
+  name: string
+): boolean | undefined => {
+  const value = getProperty(config, name)
+  if (!value) {
+    return undefined
+  }
+  if (value.kind === ts.SyntaxKind.TrueKeyword) {
+    return true
+  }
+  if (value.kind === ts.SyntaxKind.FalseKeyword) {
+    return false
+  }
+  return undefined
+}
+
+/**
+ * All-or-nothing: an array with one computed entry reads as unreadable rather
+ * than as the entries that happened to be literals. A half-read `roles` or
+ * `scopes` array is worse than none — it typechecks, runs, and grants less
+ * than the source says.
+ */
+export const stringArrayProperty = (
+  config: ts.ObjectLiteralExpression,
+  name: string
+): string[] | undefined => {
+  const value = getProperty(config, name)
+  if (!value || !ts.isArrayLiteralExpression(value)) {
+    return undefined
+  }
+  const values = value.elements
+    .filter(ts.isStringLiteralLike)
+    .map((e) => e.text)
+  return values.length === value.elements.length ? values : undefined
+}
+
+/** Unwraps `x as const` / `x satisfies T` so a cast is still extracted. */
+export const unwrapAs = (node: ts.Expression): ts.Expression =>
+  ts.isAsExpression(node) || ts.isSatisfiesExpression(node)
+    ? unwrapAs(node.expression)
+    : node

package/src/utils/load-addon-functions-meta.ts

@@ -118,6 +118,29 @@ const applyPackageToChannelContracts = (
   }
 }
 
+/**
+ * Resolves an addon's generated metadata, preferring the verbose copy.
+ *
+ * An addon publishes both: the minimal one its own bootstrap imports, and the
+ * verbose one for anything that needs the fields stripped out of it. A consumer
+ * is squarely in the second category — it is reading the addon to describe it,
+ * not to run it.
+ */
+const resolveAddonMeta = (
+  require: NodeRequire,
+  packageName: string,
+  baseName: string
+): string | null => {
+  for (const suffix of ['-verbose.gen.json', '.gen.json']) {
+    try {
+      return require.resolve(`${packageName}/.pikku/${baseName}${suffix}`)
+    } catch {
+      continue
+    }
+  }
+  return null
+}
+
 /**
  * After the setup sweep discovers wireAddon() declarations, load each addon
  * package's function metadata so that wiring handlers (channels, HTTP routes,
@@ -138,9 +161,16 @@ export async function loadAddonFunctionsMeta(
     // HOST that runs them — never load or require any of that here.
     if (decl.remote) continue
     try {
-      const metaPath = require.resolve(
-        `${decl.package}/.pikku/function/pikku-functions-meta.gen.json`
+      // Verbose first. `description` is one of the fields stripped from the
+      // minimal copy, and it is what an addon's function is offered to a model
+      // under — both as an MCP tool below and as an agent tool. Read the minimal
+      // one and every addon function looks undescribed.
+      const metaPath = resolveAddonMeta(
+        require,
+        decl.package,
+        'function/pikku-functions-meta'
       )
+      if (!metaPath) throw new Error('no function metadata')
       const raw = await readFile(metaPath, 'utf-8')
       const meta = JSON.parse(raw)
       state.addonFunctions[namespace] = meta