@pikku/inspector 0.12.50 → 0.12.52

package/src/utils/secret-alias-services.test.ts

@@ -0,0 +1,146 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import ts from 'typescript'
+import {
+  findSecretAliasServices,
+  isSecretServiceType,
+} from './secret-alias-services.js'
+
+const SECRET_SERVICE = `
+interface SecretService {
+  getSecret(key: string): Promise<string>
+  hasSecret(key: string): Promise<boolean>
+  setSecret(key: string, value: unknown): Promise<void>
+  deleteSecret(key: string): Promise<void>
+  getSecrets(keys: string[]): Promise<Record<string, unknown>>
+}
+`
+
+const singletonServicesTypeOf = (source: string) => {
+  const fileName = '/services.ts'
+  const host: ts.CompilerHost = {
+    ...ts.createCompilerHost({}),
+    getSourceFile: (name, languageVersion) =>
+      name === fileName
+        ? ts.createSourceFile(name, source, languageVersion, true)
+        : undefined,
+    fileExists: (name) => name === fileName,
+    readFile: (name) => (name === fileName ? source : undefined),
+  }
+  const program = ts.createProgram([fileName], { noLib: true }, host)
+  const checker = program.getTypeChecker()
+  const sourceFile = program.getSourceFile(fileName)!
+  const declaration = sourceFile.statements.find(
+    (statement): statement is ts.InterfaceDeclaration =>
+      ts.isInterfaceDeclaration(statement) &&
+      statement.name.text === 'SingletonServices'
+  )!
+  return {
+    checker,
+    type: checker.getTypeAtLocation(declaration),
+  }
+}
+
+describe('findSecretAliasServices', () => {
+  test('finds a secret service exposed under another name', () => {
+    const { type, checker } = singletonServicesTypeOf(`
+      ${SECRET_SERVICE}
+      interface SingletonServices {
+        secrets: SecretService
+        cfg: SecretService
+      }
+    `)
+    assert.deepEqual(findSecretAliasServices(type, checker), ['cfg'])
+  })
+
+  test('never reports `secrets` itself', () => {
+    const { type, checker } = singletonServicesTypeOf(`
+      ${SECRET_SERVICE}
+      interface SingletonServices {
+        secrets: SecretService
+      }
+    `)
+    assert.deepEqual(findSecretAliasServices(type, checker), [])
+  })
+
+  test('leaves ordinary services alone', () => {
+    const { type, checker } = singletonServicesTypeOf(`
+      ${SECRET_SERVICE}
+      interface Logger { info(message: string): void }
+      interface SingletonServices {
+        secrets: SecretService
+        logger: Logger
+      }
+    `)
+    assert.deepEqual(findSecretAliasServices(type, checker), [])
+  })
+
+  test('is not fooled by a service that only has getSecret', () => {
+    const { type, checker } = singletonServicesTypeOf(`
+      ${SECRET_SERVICE}
+      interface Partialish { getSecret(key: string): Promise<string> }
+      interface SingletonServices {
+        secrets: SecretService
+        partialish: Partialish
+      }
+    `)
+    assert.deepEqual(findSecretAliasServices(type, checker), [])
+  })
+
+  test('sees through an optional service', () => {
+    const { type, checker } = singletonServicesTypeOf(`
+      ${SECRET_SERVICE}
+      interface SingletonServices {
+        secrets: SecretService
+        cfg?: SecretService
+      }
+    `)
+    assert.deepEqual(findSecretAliasServices(type, checker), ['cfg'])
+  })
+
+  test('finds a subtype that adds methods', () => {
+    const { type, checker } = singletonServicesTypeOf(`
+      ${SECRET_SERVICE}
+      interface Scoped extends SecretService { getAllStatus(): Promise<void> }
+      interface SingletonServices {
+        secrets: SecretService
+        scoped: Scoped
+      }
+    `)
+    assert.deepEqual(findSecretAliasServices(type, checker), ['scoped'])
+  })
+
+  test('reports every alias, sorted', () => {
+    const { type, checker } = singletonServicesTypeOf(`
+      ${SECRET_SERVICE}
+      interface SingletonServices {
+        secrets: SecretService
+        zed: SecretService
+        alpha: SecretService
+      }
+    `)
+    assert.deepEqual(findSecretAliasServices(type, checker), ['alpha', 'zed'])
+  })
+})
+
+describe('isSecretServiceType', () => {
+  test('refuses a type whose members are not callable', () => {
+    const { type, checker } = singletonServicesTypeOf(`
+      ${SECRET_SERVICE}
+      interface Lookalike {
+        getSecret: string
+        hasSecret: string
+        setSecret: string
+        deleteSecret: string
+        getSecrets: string
+      }
+      interface SingletonServices { lookalike: Lookalike }
+    `)
+    const property = type.getProperty('lookalike')!
+    const propertyType = checker.getTypeOfSymbolAtLocation(
+      property,
+      property.valueDeclaration!
+    )
+    assert.equal(isSecretServiceType(propertyType, checker), false)
+  })
+})

package/src/utils/secret-alias-services.ts

@@ -0,0 +1,58 @@
+import type ts from 'typescript'
+
+const SECRET_SERVICE_METHODS = [
+  'getSecret',
+  'hasSecret',
+  'setSecret',
+  'deleteSecret',
+  'getSecrets',
+]
+
+/** Whether a type structurally satisfies `SecretService`. */
+export const isSecretServiceType = (
+  type: ts.Type,
+  checker: ts.TypeChecker
+): boolean => {
+  const nonNullable = checker.getNonNullableType(type)
+  return SECRET_SERVICE_METHODS.every((method) => {
+    const property = nonNullable.getProperty(method)
+    if (!property) {
+      return false
+    }
+    const declaration = property.valueDeclaration ?? property.declarations?.[0]
+    if (!declaration) {
+      return false
+    }
+    const propertyType = checker.getTypeOfSymbolAtLocation(
+      property,
+      declaration
+    )
+    return propertyType.getCallSignatures().length > 0
+  })
+}
+
+/**
+ * Singleton service names, other than `secrets`, whose type is a
+ * `SecretService`.
+ */
+export const findSecretAliasServices = (
+  singletonServicesType: ts.Type,
+  checker: ts.TypeChecker
+): string[] => {
+  const aliases: string[] = []
+  for (const property of singletonServicesType.getProperties()) {
+    const name = property.getName()
+    if (name === 'secrets') {
+      continue
+    }
+    const declaration = property.valueDeclaration ?? property.declarations?.[0]
+    if (!declaration) {
+      continue
+    }
+    const type = checker.getTypeOfSymbolAtLocation(property, declaration)
+    if (isSecretServiceType(type, checker)) {
+      aliases.push(name)
+    }
+  }
+  return aliases.sort()
+}

package/src/utils/secret-brokers.test.ts

@@ -0,0 +1,53 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { isSecretBrokerFunction } from './secret-brokers.js'
+import { computeSecretBrokers } from './post-process.js'
+import type { InspectorState } from '../types.js'
+
+describe('isSecretBrokerFunction', () => {
+  test('admits the console secret-admin functions', () => {
+    assert.ok(isSecretBrokerFunction('pikkuConsoleGetSecret'))
+    assert.ok(isSecretBrokerFunction('pikkuConsoleSetSecret'))
+    assert.ok(isSecretBrokerFunction('pikkuConsoleHasSecret'))
+  })
+
+  test('admits them when namespaced by an addon', () => {
+    assert.ok(isSecretBrokerFunction('pikku:pikkuConsoleGetSecret'))
+  })
+
+  test('admits nothing else', () => {
+    assert.equal(isSecretBrokerFunction('pikkuConsoleGetVariable'), false)
+    assert.equal(isSecretBrokerFunction('httpRequest'), false)
+    assert.equal(isSecretBrokerFunction('myFunction'), false)
+  })
+
+  test('is not fooled by a name that merely contains a broker name', () => {
+    assert.equal(isSecretBrokerFunction('notPikkuConsoleGetSecret'), false)
+    assert.equal(isSecretBrokerFunction('pikkuConsoleGetSecretly'), false)
+  })
+})
+
+describe('computeSecretBrokers', () => {
+  const stateWith = (meta: Record<string, any>) =>
+    ({ functions: { meta } }) as unknown as InspectorState
+
+  test('flags a broker so the runner keeps its secrets', () => {
+    const state = stateWith({
+      pikkuConsoleGetSecret: { pikkuFuncId: 'pikkuConsoleGetSecret' },
+    })
+    computeSecretBrokers(state)
+    assert.equal(state.functions.meta.pikkuConsoleGetSecret!.secretBroker, true)
+  })
+
+  test('leaves an ordinary function unflagged', () => {
+    const state = stateWith({ createTodo: { pikkuFuncId: 'createTodo' } })
+    computeSecretBrokers(state)
+    assert.equal(state.functions.meta.createTodo!.secretBroker, undefined)
+  })
+
+  test('falls back to the meta key when there is no pikkuFuncId', () => {
+    const state = stateWith({ pikkuConsoleSetSecret: {} })
+    computeSecretBrokers(state)
+    assert.equal(state.functions.meta.pikkuConsoleSetSecret!.secretBroker, true)
+  })
+})

package/src/utils/secret-brokers.ts

@@ -0,0 +1,11 @@
+/** The console's secret administration functions, and nothing else. */
+const SECRET_BROKER_FUNCTIONS = new Set([
+  'pikkuConsoleSetSecret',
+  'pikkuConsoleGetSecret',
+  'pikkuConsoleHasSecret',
+])
+
+/** Whether this function keeps the full `SecretService`. */
+export const isSecretBrokerFunction = (functionId: string): boolean =>
+  SECRET_BROKER_FUNCTIONS.has(functionId) ||
+  SECRET_BROKER_FUNCTIONS.has(functionId.split(':').pop() ?? '')

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/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
+}