@pikku/inspector 0.12.74 → 0.12.81

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

@@ -1,230 +0,0 @@
-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

@@ -1,103 +0,0 @@
-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

@@ -1,108 +0,0 @@
-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

@@ -1,48 +0,0 @@
-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/utils/workflow/derive-workflow-plan.test.ts

@@ -1,178 +0,0 @@
-import { strict as assert } from 'assert'
-import { describe, test } from 'node:test'
-import type { WorkflowStepMeta } from '@pikku/core/workflow'
-import { deriveWorkflowPlan } from './derive-workflow-plan.js'
-
-const rpc = (stepName: string, rpcName = 'rpc.fn'): WorkflowStepMeta =>
-  ({ type: 'rpc', stepName, rpcName }) as WorkflowStepMeta
-const sleep = (stepName: string): WorkflowStepMeta =>
-  ({ type: 'sleep', stepName }) as WorkflowStepMeta
-const inline = (stepName: string): WorkflowStepMeta =>
-  ({ type: 'inline', stepName }) as WorkflowStepMeta
-
-describe('deriveWorkflowPlan', () => {
-  test('linear workflow is deterministic with every step listed in order', () => {
-    const plan = deriveWorkflowPlan([rpc('a'), sleep('b'), inline('c')])
-    assert.equal(plan.deterministic, true)
-    assert.deepEqual(plan.plannedSteps, [
-      { stepName: 'a' },
-      { stepName: 'b' },
-      { stepName: 'c' },
-    ])
-  })
-
-  test('parallel group lists each child step', () => {
-    const plan = deriveWorkflowPlan([
-      rpc('a'),
-      {
-        type: 'parallel',
-        children: [rpc('p1'), rpc('p2')],
-      } as WorkflowStepMeta,
-    ])
-    assert.equal(plan.deterministic, true)
-    assert.deepEqual(plan.plannedSteps, [
-      { stepName: 'a' },
-      { stepName: 'p1' },
-      { stepName: 'p2' },
-    ])
-  })
-
-  test('branch is loopless: plannedSteps cover every arm but not deterministic', () => {
-    const plan = deriveWorkflowPlan([
-      rpc('start'),
-      {
-        type: 'branch',
-        branches: [{ condition: 'x', steps: [rpc('left')] }],
-        elseSteps: [rpc('right')],
-      } as WorkflowStepMeta,
-      rpc('end'),
-    ])
-    assert.equal(plan.deterministic, false, 'a branch picks a path at runtime')
-    assert.deepEqual(plan.plannedSteps, [
-      { stepName: 'start' },
-      { stepName: 'left' },
-      { stepName: 'right' },
-      { stepName: 'end' },
-    ])
-  })
-
-  test('switch is loopless: cases + default contribute steps, not deterministic', () => {
-    const plan = deriveWorkflowPlan([
-      {
-        type: 'switch',
-        expression: 'kind',
-        cases: [{ steps: [rpc('caseA')] }, { steps: [rpc('caseB')] }],
-        defaultSteps: [rpc('fallback')],
-      } as WorkflowStepMeta,
-    ])
-    assert.equal(plan.deterministic, false)
-    assert.deepEqual(plan.plannedSteps, [
-      { stepName: 'caseA' },
-      { stepName: 'caseB' },
-      { stepName: 'fallback' },
-    ])
-  })
-
-  test('fanout (loop) yields no plannedSteps and is not deterministic', () => {
-    const plan = deriveWorkflowPlan([
-      rpc('before'),
-      {
-        type: 'fanout',
-        stepName: 'each',
-        child: rpc('child'),
-        mode: 'parallel',
-      } as WorkflowStepMeta,
-    ])
-    assert.equal(plan.deterministic, false)
-    assert.equal(
-      plan.plannedSteps,
-      undefined,
-      'loop count is runtime-dependent'
-    )
-  })
-
-  test('a fanout nested inside a branch still suppresses the plan', () => {
-    const plan = deriveWorkflowPlan([
-      {
-        type: 'branch',
-        branches: [
-          {
-            condition: 'x',
-            steps: [
-              {
-                type: 'fanout',
-                stepName: 'each',
-                child: rpc('child'),
-                mode: 'serial',
-              } as WorkflowStepMeta,
-            ],
-          },
-        ],
-      } as WorkflowStepMeta,
-    ])
-    assert.equal(plan.deterministic, false)
-    assert.equal(plan.plannedSteps, undefined)
-  })
-
-  test('non-named steps (set/return/cancel) are skipped', () => {
-    const plan = deriveWorkflowPlan([
-      { type: 'set' } as WorkflowStepMeta,
-      rpc('a'),
-      { type: 'return' } as WorkflowStepMeta,
-    ])
-    assert.equal(plan.deterministic, true)
-    assert.deepEqual(plan.plannedSteps, [{ stepName: 'a' }])
-  })
-
-  test('suspend steps appear in the plan with __workflow_suspend: key and sentence-case displayName', () => {
-    const plan = deriveWorkflowPlan([
-      rpc('build'),
-      { type: 'suspend', reason: 'building' } as WorkflowStepMeta,
-      rpc('publish'),
-      { type: 'suspend', reason: 'awaiting_approval' } as WorkflowStepMeta,
-      { type: 'suspend', reason: 'building-image' } as WorkflowStepMeta,
-    ])
-    assert.equal(plan.deterministic, true)
-    assert.deepEqual(plan.plannedSteps, [
-      { stepName: 'build' },
-      { stepName: '__workflow_suspend:building', displayName: 'Building' },
-      { stepName: 'publish' },
-      {
-        stepName: '__workflow_suspend:awaiting_approval',
-        displayName: 'Awaiting approval',
-      },
-      {
-        stepName: '__workflow_suspend:building-image',
-        displayName: 'Building image',
-      },
-    ])
-  })
-
-  test('approval steps appear in the plan with __workflow_approval: key and sentence-case displayName', () => {
-    const plan = deriveWorkflowPlan([
-      rpc('build'),
-      { type: 'approval', reason: 'awaiting_approval' } as WorkflowStepMeta,
-      rpc('publish'),
-    ])
-    assert.equal(plan.deterministic, true)
-    assert.deepEqual(plan.plannedSteps, [
-      { stepName: 'build' },
-      {
-        stepName: '__workflow_approval:awaiting_approval',
-        displayName: 'Awaiting approval',
-      },
-      { stepName: 'publish' },
-    ])
-  })
-
-  test('an approval is namespaced apart from a suspend sharing its reason', () => {
-    const plan = deriveWorkflowPlan([
-      { type: 'suspend', reason: 'sign_off' } as WorkflowStepMeta,
-      { type: 'approval', reason: 'sign_off' } as WorkflowStepMeta,
-    ])
-    assert.deepEqual(
-      plan.plannedSteps.map((s) => s.stepName),
-      ['__workflow_suspend:sign_off', '__workflow_approval:sign_off']
-    )
-  })
-})