@pikku/inspector 0.12.50 → 0.12.54

package/src/utils/serialize-inspector-state.ts

@@ -1,3 +1,4 @@
+import type { SecretUsage } from './extract-secret-usage.js'
 import type { JSONValue } from '@pikku/core'
 import type {
   InspectorDiagnostic,
@@ -201,6 +202,7 @@ export interface SerializableInspectorState {
   secrets: {
     definitions: InspectorState['secrets']['definitions']
     files: string[]
+    usage: Record<string, SecretUsage>
   }
   credentials: {
     definitions: InspectorState['credentials']['definitions']
@@ -210,6 +212,14 @@ export interface SerializableInspectorState {
     definitions: InspectorState['scopes']['definitions']
     files: string[]
   }
+  systemRoles: {
+    definitions: InspectorState['systemRoles']['definitions']
+    files: string[]
+  }
+  personas: {
+    definitions: InspectorState['personas']['definitions']
+    files: string[]
+  }
   variables: {
     definitions: InspectorState['variables']['definitions']
     files: string[]
@@ -416,6 +426,7 @@ export function serializeInspectorState(
     secrets: {
       definitions: state.secrets.definitions,
       files: Array.from(state.secrets.files),
+      usage: Object.fromEntries(state.secrets.usage),
     },
     credentials: {
       definitions: state.credentials.definitions,
@@ -425,6 +436,14 @@ export function serializeInspectorState(
       definitions: state.scopes.definitions,
       files: Array.from(state.scopes.files),
     },
+    systemRoles: {
+      definitions: state.systemRoles.definitions,
+      files: Array.from(state.systemRoles.files),
+    },
+    personas: {
+      definitions: state.personas.definitions,
+      files: Array.from(state.personas.files),
+    },
     variables: {
       definitions: state.variables.definitions,
       files: Array.from(state.variables.files),
@@ -611,6 +630,7 @@ export function deserializeInspectorState(
     secrets: {
       definitions: data.secrets?.definitions || [],
       files: new Set(data.secrets?.files || []),
+      usage: new Map(Object.entries(data.secrets?.usage || {})),
     },
     credentials: {
       definitions: data.credentials?.definitions || [],
@@ -620,6 +640,14 @@ export function deserializeInspectorState(
       definitions: data.scopes?.definitions || [],
       files: new Set(data.scopes?.files || []),
     },
+    systemRoles: {
+      definitions: data.systemRoles?.definitions || [],
+      files: new Set(data.systemRoles?.files || []),
+    },
+    personas: {
+      definitions: data.personas?.definitions || [],
+      files: new Set(data.personas?.files || []),
+    },
     variables: {
       definitions: data.variables?.definitions || [],
       files: new Set(data.variables?.files || []),

package/src/utils/serialize-middleware-groups-meta.ts

@@ -13,6 +13,9 @@ const serializeGroupMap = (
       count: meta.count,
       instanceIds: meta.instanceIds,
       isFactory: meta.isFactory,
+      ...(meta.additionalRegistrations && {
+        additionalRegistrations: meta.additionalRegistrations,
+      }),
     }
   }
   return result

package/src/utils/single-declaration.ts

@@ -0,0 +1,57 @@
+import type { ErrorCode } from '../error-codes.js'
+import type { InspectorLogger } from '../types.js'
+
+/**
+ * Claims the one call site a single-declaration construct is allowed.
+ *
+ * `definePersonas` takes a keyed object, so one call already declares as many
+ * entries as you like. Letting the call itself repeat buys nothing and costs
+ * the thing that matters: a single place to read the declared set from, and a
+ * single place to add to it. The same rule `pikkuBetterAuth` has had all along.
+ *
+ * A second call in the SAME file is refused too — "the file" is not an answer
+ * to "where do I add a persona?" when the file holds two calls, so allowing it
+ * would keep the ambiguity the rule exists to remove.
+ *
+ * A generated file is exempt, and never claims the slot either. The rule exists
+ * to name the one place a person adds to, and nobody adds to a file the CLI
+ * rewrites on the next run — `pikku-personas.gen.ts` would otherwise make every
+ * project that scaffolds one unbuildable, and take the app's own declaration
+ * down with it.
+ *
+ * `defineScope` and `defineSystemRole` held this rule too, briefly, and do not
+ * until the `admin` tree stops being app-declared. The exemption above is not
+ * enough for them: the CLI generates a `defineScope` in `user-admin.gen.ts` and
+ * `@pikku/addon-console` spells the same tree out again in a hand-written file,
+ * so two non-generated declarations remain and the build still fails. The fix
+ * is for `admin` to be a default scope nobody declares, and the rule comes back
+ * for scopes and roles once that lands.
+ *
+ * @param files - The construct's `files` set, which doubles as the claim.
+ * @returns true when the caller holds the claim and should carry on.
+ */
+export const claimSingleDeclaration = (
+  logger: InspectorLogger,
+  files: Set<string>,
+  code: ErrorCode,
+  helper: string,
+  sourceFile: string
+): boolean => {
+  if (sourceFile.endsWith('.gen.ts')) {
+    return true
+  }
+
+  const [first] = files
+  if (first === undefined) {
+    files.add(sourceFile)
+    return true
+  }
+
+  logger.critical(
+    code,
+    first === sourceFile
+      ? `Only one ${helper}(...) is allowed per codebase, so there is one place to read the declarations from and one place to add to. Found a second call in ${sourceFile}. Declare them all in one call.`
+      : `Only one ${helper}(...) is allowed per codebase, so there is one place to read the declarations from and one place to add to. Found a second in ${sourceFile} (first: ${first}). Declare them all in one call.`
+  )
+  return false
+}

package/src/utils/validate-exposed-functions-gated.test.ts

@@ -0,0 +1,230 @@
+import assert from 'node:assert/strict'
+import { describe, test, beforeEach } from 'node:test'
+import { ErrorCode } from '../error-codes.js'
+import { validateExposedFunctionsGated } from './validate-exposed-functions-gated.js'
+
+const ADDON_PACKAGE = '@addon/console'
+
+let diagnostics: Array<{ severity: string; code: string; message: string }>
+
+const logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  critical: () => {},
+  diagnostic: (d: any) => diagnostics.push(d),
+  hasCriticalErrors: () => false,
+} as any
+
+/**
+ * The two pieces of state the check reads: every function's meta, and every
+ * wireAddon declaration the inspector found.
+ */
+const stateWith = (
+  meta: Record<string, unknown>,
+  addons: Record<string, unknown> = {}
+) =>
+  ({
+    functions: { meta },
+    rpc: { wireAddonDeclarations: new Map(Object.entries(addons)) },
+  }) as any
+
+/** An exposed sessionless function with no gate of any kind — the bad shape. */
+const ungatedFunction = (overrides: Record<string, unknown> = {}) => ({
+  pikkuFuncId: 'credentialGet',
+  expose: true,
+  sessionless: true,
+  ...overrides,
+})
+
+const run = (state: any) => {
+  validateExposedFunctionsGated(logger, state)
+  return diagnostics
+}
+
+const warning = () => {
+  const found = diagnostics.find(
+    (d) => d.code === ErrorCode.EXPOSED_FUNCTION_HAS_NO_GATE
+  )
+  return found
+}
+
+beforeEach(() => {
+  diagnostics = []
+})
+
+describe('validateExposedFunctionsGated', () => {
+  test('warns about an exposed sessionless function with no gate', () => {
+    run(stateWith({ credentialGet: ungatedFunction() }))
+
+    const found = warning()
+    assert.ok(found, 'expected a diagnostic')
+    assert.equal(found.severity, 'warn')
+    assert.match(found.message, /credentialGet/)
+  })
+
+  test('names every ungated function, not just a count', () => {
+    run(
+      stateWith({
+        credentialGet: ungatedFunction(),
+        installAddon: ungatedFunction({ pikkuFuncId: 'installAddon' }),
+      })
+    )
+
+    assert.match(warning()!.message, /credentialGet/)
+    assert.match(warning()!.message, /installAddon/)
+  })
+
+  test('stays silent for a function that is not exposed', () => {
+    run(stateWith({ credentialGet: ungatedFunction({ expose: undefined }) }))
+
+    assert.equal(warning(), undefined)
+  })
+
+  test('stays silent for a pikkuFunc, which always requires a session', () => {
+    run(stateWith({ credentialGet: ungatedFunction({ sessionless: false }) }))
+
+    assert.equal(warning(), undefined)
+  })
+
+  test('stays silent for a scenario step, which rpcExposed refuses anyway', () => {
+    run(stateWith({ step: ungatedFunction({ scenarioStep: true }) }))
+
+    assert.equal(warning(), undefined)
+  })
+
+  describe('a function that gates itself', () => {
+    test('is silent when it declares auth', () => {
+      run(stateWith({ credentialGet: ungatedFunction({ auth: true }) }))
+
+      assert.equal(warning(), undefined)
+    })
+
+    test('is silent when it declares it authenticates in its own body', () => {
+      // A webhook receiver verifying a signature has a real gate this check
+      // cannot see. Without a way to say so the warning would fire forever on
+      // functions that are fine, and a warning that is usually wrong is one
+      // nobody reads.
+      run(
+        stateWith({
+          stripeWebhook: ungatedFunction({ permissionsInBody: true }),
+        })
+      )
+
+      assert.equal(warning(), undefined)
+    })
+
+    test('still warns when the declaration is explicitly false', () => {
+      run(
+        stateWith({
+          credentialGet: ungatedFunction({ permissionsInBody: false }),
+        })
+      )
+
+      assert.ok(warning())
+    })
+
+    test('is silent when it declares scopes', () => {
+      run(stateWith({ credentialGet: ungatedFunction({ scopes: ['admin'] }) }))
+
+      assert.equal(warning(), undefined)
+    })
+
+    test('is silent when it declares permissions', () => {
+      run(
+        stateWith({
+          credentialGet: ungatedFunction({
+            permissions: [{ type: 'wire', name: 'isAdmin' }],
+          }),
+        })
+      )
+
+      assert.equal(warning(), undefined)
+    })
+
+    test('still warns when scopes is present but empty', () => {
+      run(stateWith({ credentialGet: ungatedFunction({ scopes: [] }) }))
+
+      assert.ok(warning(), 'an empty scopes array gates nothing')
+    })
+  })
+
+  describe('a function gated by its addon', () => {
+    test('is silent when the addon declares scopes', () => {
+      run(
+        stateWith(
+          {
+            credentialGet: ungatedFunction({ packageName: ADDON_PACKAGE }),
+          },
+          { console: { package: ADDON_PACKAGE, scopes: ['admin'] } }
+        )
+      )
+
+      assert.equal(warning(), undefined)
+    })
+
+    test('is silent when the addon declares auth', () => {
+      run(
+        stateWith(
+          {
+            credentialGet: ungatedFunction({ packageName: ADDON_PACKAGE }),
+          },
+          { console: { package: ADDON_PACKAGE, auth: true } }
+        )
+      )
+
+      assert.equal(warning(), undefined)
+    })
+
+    test('warns when the addon is wired without any gate', () => {
+      run(
+        stateWith(
+          {
+            credentialGet: ungatedFunction({ packageName: ADDON_PACKAGE }),
+          },
+          { console: { package: ADDON_PACKAGE } }
+        )
+      )
+
+      assert.ok(warning(), 'wireAddon with no scopes or auth gates nothing')
+    })
+
+    test('warns when the gated addon is a different package', () => {
+      run(
+        stateWith(
+          {
+            credentialGet: ungatedFunction({ packageName: ADDON_PACKAGE }),
+          },
+          { other: { package: '@addon/other', scopes: ['admin'] } }
+        )
+      )
+
+      assert.ok(warning())
+    })
+
+    test('is silent when any one instance of the package is gated', () => {
+      // resolveAddonScopes unions across every instance of the package, so a
+      // second ungated namespace does not open the first.
+      run(
+        stateWith(
+          {
+            credentialGet: ungatedFunction({ packageName: ADDON_PACKAGE }),
+          },
+          {
+            console: { package: ADDON_PACKAGE, scopes: ['admin'] },
+            consoleReadonly: { package: ADDON_PACKAGE },
+          }
+        )
+      )
+
+      assert.equal(warning(), undefined)
+    })
+  })
+
+  test('stays silent when nothing is exposed', () => {
+    run(stateWith({}))
+
+    assert.equal(diagnostics.length, 0)
+  })
+})

package/src/utils/validate-exposed-functions-gated.ts

@@ -0,0 +1,103 @@
+import { ErrorCode } from '../error-codes.js'
+import type { InspectorLogger, InspectorState } from '../types.js'
+
+/**
+ * A function reachable through the generated `POST /rpc/:rpcName` dispatcher
+ * that nothing will stop.
+ *
+ * `rpc.exposed` refuses anything without `expose: true`, so the population is
+ * small and deliberate — someone typed it. What makes one dangerous is the
+ * combination: exposed, sessionless, and carrying no gate of its own or from
+ * the addon it belongs to. The dispatcher cannot help, because it does not know
+ * what it is dispatching to.
+ *
+ * knowledge: decisions/security/console-addon-privileged-functions-gate-themselves.md
+ */
+export function validateExposedFunctionsGated(
+  logger: InspectorLogger,
+  state: InspectorState
+): void {
+  const ungated: string[] = []
+
+  for (const [funcName, meta] of Object.entries(state.functions.meta)) {
+    if (!meta.expose) continue
+
+    // A pikkuFunc always requires a session, on every path.
+    if (meta.sessionless === false) continue
+
+    // Scenario steps are refused by rpcExposed regardless of `expose`.
+    if (meta.scenarioStep) continue
+
+    // The author declared that the body authorizes its own callers — a gate
+    // this check has no way to see. Taking the claim at face value is the
+    // point: without it the warning fires forever on functions that are fine,
+    // and a warning that is usually wrong stops being read.
+    if (meta.permissionsInBody === true) continue
+
+    // The function gates itself.
+    if (meta.auth === true) continue
+    if (meta.scopes && meta.scopes.length > 0) continue
+    if (meta.permissions && meta.permissions.length > 0) continue
+
+    if (isGatedByItsAddon(state, meta.packageName)) continue
+
+    ungated.push(funcName)
+  }
+
+  if (ungated.length === 0) return
+
+  const shown = ungated.slice(0, 10)
+  const rest = ungated.length - shown.length
+
+  const one = ungated.length === 1
+
+  // Every function here is sessionless — that is the population, not the
+  // finding, so the message names it as given rather than reporting it as a
+  // defect. The remedies are the ones that can actually apply to an anonymous
+  // caller: `scopes` cannot, because `verifyScopes` fails closed on a session
+  // that does not exist, and telling someone to add them sends them to a
+  // MissingScopeError on every public request.
+  logger.diagnostic({
+    severity: 'warn',
+    code: ErrorCode.EXPOSED_FUNCTION_HAS_NO_GATE,
+    message:
+      `${ungated.length} exposed sessionless function${one ? '' : 's'} ` +
+      `carr${one ? 'ies' : 'y'} no permission and no addon gate, so ` +
+      `${one ? 'it is' : 'they are'} reachable by anyone through ` +
+      `POST /rpc/:rpcName: ${shown.join(', ')}` +
+      (rest > 0 ? `, and ${rest} more` : '') +
+      `. Add permissions to the function, set \`auth: true\` if a session is ` +
+      `required after all, gate the whole addon with ` +
+      `wireAddon({ auth: true }), or drop \`expose: true\` if ` +
+      `${one ? 'it was' : 'they were'} not meant to be callable from outside.`,
+  })
+}
+
+/**
+ * Whether every function in this package is already gated by its `wireAddon`.
+ * Those gates are applied by `runPikkuFunc` on every wiring path, so a function
+ * with no gate of its own is still covered by them.
+ *
+ * An addon whose `scopes`/`auth` were not statically knowable reads as
+ * unknown, and unknown is treated as gated — a false negative here costs a
+ * missing warning, a false positive costs trust in every warning.
+ *
+ * knowledge: decisions/security/addon-scopes-are-resolved-where-the-function-runs.md
+ */
+function isGatedByItsAddon(
+  state: InspectorState,
+  packageName: string | undefined
+): boolean {
+  if (!packageName) return false
+
+  const declarations = state.rpc?.wireAddonDeclarations
+  if (!declarations) return false
+
+  for (const declaration of declarations.values()) {
+    if (declaration.package !== packageName) continue
+    if (declaration.auth === true) return true
+    if (declaration.scopes && declaration.scopes.length > 0) return true
+  }
+
+  return false
+}

package/src/utils/validate-tags-resolve-to-middleware.test.ts

@@ -0,0 +1,105 @@
+import assert from 'node:assert/strict'
+import { describe, test, beforeEach } from 'node:test'
+import { ErrorCode } from '../error-codes.js'
+import { validateTagsResolveToMiddleware } from './validate-tags-resolve-to-middleware.js'
+
+let diagnostics: Array<{ severity: string; code: string; message: string }>
+
+const logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  critical: () => {},
+  diagnostic: (d: any) => diagnostics.push(d),
+  hasCriticalErrors: () => false,
+} as any
+
+/**
+ * The three pieces of state the check reads: the addon declarations that carry
+ * tags, and the two registries a tag can resolve against.
+ */
+const stateWith = (
+  addons: Record<string, { tags?: string[] }>,
+  httpTags: string[] = [],
+  channelTags: string[] = []
+) =>
+  ({
+    rpc: { wireAddonDeclarations: new Map(Object.entries(addons)) },
+    middleware: { tagMiddleware: new Map(httpTags.map((t) => [t, []])) },
+    channelMiddleware: {
+      tagMiddleware: new Map(channelTags.map((t) => [t, []])),
+    },
+  }) as any
+
+const run = (state: any) => {
+  validateTagsResolveToMiddleware(logger, state)
+  return diagnostics.filter(
+    (d) => d.code === ErrorCode.TAG_RESOLVES_TO_NO_MIDDLEWARE
+  )
+}
+
+beforeEach(() => {
+  diagnostics = []
+})
+
+describe('validateTagsResolveToMiddleware', () => {
+  test('warns about an addon tag no middleware is registered for', () => {
+    const found = run(stateWith({ console: { tags: ['admin'] } }))
+    assert.equal(found.length, 1)
+    assert.match(found[0]!.message, /console/)
+    assert.match(found[0]!.message, /admin/)
+  })
+
+  test('warns rather than fails the build', () => {
+    // The tag may be registered by host code the inspector never sees, so this
+    // has to stay advisory — a false positive must not break codegen.
+    const found = run(stateWith({ console: { tags: ['admin'] } }))
+    assert.equal(found[0]!.severity, 'warn')
+  })
+
+  test('stays quiet when http middleware is registered for the tag', () => {
+    assert.deepEqual(run(stateWith({ console: { tags: ['admin'] } }, ['admin'])), [])
+  })
+
+  test('stays quiet when only channel middleware is registered for the tag', () => {
+    assert.deepEqual(
+      run(stateWith({ console: { tags: ['admin'] } }, [], ['admin'])),
+      []
+    )
+  })
+
+  test('reports each unresolved tag on an addon separately', () => {
+    const found = run(
+      stateWith({ console: { tags: ['admin', 'audited'] } }, ['admin'])
+    )
+    assert.equal(found.length, 1)
+    assert.match(found[0]!.message, /audited/)
+  })
+
+  test('reports the same tag once per addon that declares it', () => {
+    const found = run(
+      stateWith({ console: { tags: ['admin'] }, billing: { tags: ['admin'] } })
+    )
+    assert.equal(found.length, 2)
+  })
+
+  test('stays quiet for an addon with no tags', () => {
+    assert.deepEqual(run(stateWith({ console: {} })), [])
+  })
+
+  test('stays quiet when there are no addons at all', () => {
+    assert.deepEqual(run(stateWith({})), [])
+  })
+
+  test('tolerates rpc state being absent', () => {
+    // Inspection of a package with no RPC surface never populates it.
+    assert.deepEqual(
+      run({
+        middleware: { tagMiddleware: new Map() },
+        channelMiddleware: { tagMiddleware: new Map() },
+      } as any),
+      []
+    )
+  })
+})

package/src/utils/validate-tags-resolve-to-middleware.ts

@@ -0,0 +1,48 @@
+import { ErrorCode } from '../error-codes.js'
+import type { InspectorLogger, InspectorState } from '../types.js'
+
+/**
+ * An addon tag naming middleware nobody registered.
+ *
+ * `wireAddon({ tags: ['admin'] })` reads like a gate and is applied like one —
+ * right up until no `addTagMiddleware('admin', …)` exists, at which point it
+ * resolves to an empty list and every request sails through. Nothing at runtime
+ * distinguishes "this tag runs three middlewares" from "this tag does nothing".
+ *
+ * Only **addon** tags are reported. A tag on a function is just as likely to be
+ * organizational — grouping, documentation, OpenAPI — and warning about every
+ * one of those would bury the case that matters. A tag on `wireAddon` is
+ * different: it is the documented way to apply a gate across a whole addon, so
+ * an inert one is never decorative. An exposed function relying on a tag it
+ * has no other gate behind is already reported by
+ * `validateExposedFunctionsGated`, which does not count tags as a gate.
+ *
+ * knowledge: decisions/security/addon-auth-and-tags-only-tighten.md
+ */
+export function validateTagsResolveToMiddleware(
+  logger: InspectorLogger,
+  state: InspectorState
+): void {
+  const registered = new Set<string>([
+    ...state.middleware.tagMiddleware.keys(),
+    ...state.channelMiddleware.tagMiddleware.keys(),
+  ])
+
+  for (const [namespace, declaration] of state.rpc?.wireAddonDeclarations ??
+    []) {
+    for (const tag of declaration.tags ?? []) {
+      if (registered.has(tag)) continue
+
+      logger.diagnostic({
+        severity: 'warn',
+        code: ErrorCode.TAG_RESOLVES_TO_NO_MIDDLEWARE,
+        message:
+          `wireAddon('${namespace}') declares tag '${tag}', but no ` +
+          `addTagMiddleware('${tag}', …) registers anything for it. The tag ` +
+          `resolves to an empty middleware list, so it applies no gate to the ` +
+          `addon at all. Register middleware for it, or drop the tag if it is ` +
+          `only meant to group and document.`,
+      })
+    }
+  }
+}