@pikku/inspector 0.12.49 → 0.12.52

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({ selfAuthenticated: true }),
+        })
+      )
+
+      assert.equal(warning(), undefined)
+    })
+
+    test('still warns when the declaration is explicitly false', () => {
+      run(
+        stateWith({
+          credentialGet: ungatedFunction({ selfAuthenticated: 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,94 @@
+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.selfAuthenticated === 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
+
+  logger.diagnostic({
+    severity: 'warn',
+    code: ErrorCode.EXPOSED_FUNCTION_HAS_NO_GATE,
+    message:
+      `${ungated.length} exposed function${ungated.length === 1 ? '' : 's'} ` +
+      `require neither a session nor any permission or scope, and ` +
+      `${ungated.length === 1 ? 'is' : 'are'} reachable by anyone through ` +
+      `POST /rpc/:rpcName: ${shown.join(', ')}` +
+      (rest > 0 ? `, and ${rest} more` : '') +
+      `. Add scopes or permissions to the function, gate the whole addon with ` +
+      `wireAddon({ scopes: [...] }), or drop \`expose: true\` if it was 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.`,
+      })
+    }
+  }
+}

package/src/visit.ts

@@ -28,6 +28,8 @@ import { addAuth } from './add/add-auth.js'
 import { addSecret } from './add/add-secret.js'
 import { addCredential } from './add/add-credential.js'
 import { addScope } from './add/add-scope.js'
+import { addSystemRole } from './add/add-system-role.js'
+import { addPersonas } from './add/add-personas.js'
 import { addVariable } from './add/add-variable.js'
 import { addWorkflowGraph } from './add/add-workflow-graph.js'
 import { addFeature } from './add/add-feature.js'
@@ -152,6 +154,8 @@ export const visitRoutes = (
   addSecret(logger, node, checker, state, nextOptions)
   addCredential(logger, node, checker, state, nextOptions)
   addScope(logger, node, checker, state, nextOptions)
+  addSystemRole(logger, node, checker, state, nextOptions)
+  addPersonas(logger, node, checker, state, nextOptions)
   addVariable(logger, node, checker, state, nextOptions)
 
   addHTTPRoute(logger, node, checker, state, nextOptions)