@pikku/inspector 0.12.50 → 0.12.52

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)