@pikku/inspector 0.12.50 → 0.12.52

package/dist/utils/serialize-inspector-state.d.ts

@@ -1,3 +1,4 @@
+import type { SecretUsage } from './extract-secret-usage.js';
 import type { JSONValue } from '@pikku/core';
 import type { InspectorDiagnostic, InspectorFeature, InspectorState } from '../types.js';
 /**
@@ -228,6 +229,7 @@ export interface SerializableInspectorState {
     secrets: {
         definitions: InspectorState['secrets']['definitions'];
         files: string[];
+        usage: Record<string, SecretUsage>;
     };
     credentials: {
         definitions: InspectorState['credentials']['definitions'];
@@ -237,6 +239,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[];

package/dist/utils/serialize-inspector-state.js

@@ -112,6 +112,7 @@ export function serializeInspectorState(state) {
         secrets: {
             definitions: state.secrets.definitions,
             files: Array.from(state.secrets.files),
+            usage: Object.fromEntries(state.secrets.usage),
         },
         credentials: {
             definitions: state.credentials.definitions,
@@ -121,6 +122,14 @@ export function serializeInspectorState(state) {
             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),
@@ -276,6 +285,7 @@ export function deserializeInspectorState(data) {
         secrets: {
             definitions: data.secrets?.definitions || [],
             files: new Set(data.secrets?.files || []),
+            usage: new Map(Object.entries(data.secrets?.usage || {})),
         },
         credentials: {
             definitions: data.credentials?.definitions || [],
@@ -285,6 +295,14 @@ export function deserializeInspectorState(data) {
             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/dist/utils/serialize-middleware-groups-meta.js

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

package/dist/utils/validate-exposed-functions-gated.d.ts

@@ -0,0 +1,14 @@
+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 declare function validateExposedFunctionsGated(logger: InspectorLogger, state: InspectorState): void;

package/dist/utils/validate-exposed-functions-gated.js

@@ -0,0 +1,85 @@
+import { ErrorCode } from '../error-codes.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, state) {
+    const ungated = [];
+    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, packageName) {
+    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/dist/utils/validate-tags-resolve-to-middleware.d.ts

@@ -0,0 +1,20 @@
+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 declare function validateTagsResolveToMiddleware(logger: InspectorLogger, state: InspectorState): void;

package/dist/utils/validate-tags-resolve-to-middleware.js

@@ -0,0 +1,41 @@
+import { ErrorCode } from '../error-codes.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, state) {
+    const registered = new Set([
+        ...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/dist/visit.js

@@ -23,6 +23,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';
@@ -69,6 +71,8 @@ export const visitRoutes = (logger, checker, node, state, options) => {
     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);
     addHTTPRoutes(logger, node, checker, state, nextOptions);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.50",
+  "version": "0.12.52",
   "description": "TypeScript inspector for Pikku — discovers functions and wirings to drive code generation",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
@@ -45,10 +45,10 @@
     "zod-to-ts": "^2.1.0"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.72"
+    "@pikku/core": "^0.12.74"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.72",
+    "@pikku/core": "^0.12.74",
     "@types/node": "^24.11.0"
   },
   "engines": {

package/src/add/add-auth.test.ts

@@ -13,8 +13,10 @@ const makeLogger = (criticals: Array<{ code: ErrorCode; message: string }>) =>
     info: () => {},
     warn: () => {},
     error: () => {},
-    diagnostic: ({ code, message }) => {
-      criticals.push({ code, message })
+    diagnostic: ({ severity, code, message }) => {
+      if (severity !== 'warn') {
+        criticals.push({ code, message })
+      }
     },
     critical: (code: ErrorCode, message: string) => {
       criticals.push({ code, message })
@@ -111,7 +113,7 @@ describe('addAuth inspector', () => {
         'export const auth = pikkuBetterAuth(() =>',
         '  betterAuth({',
         '    session: { cookieCache: { enabled: true } },',
-        "    emailAndPassword: { enabled: true },",
+        '    emailAndPassword: { enabled: true },',
         '  })',
         ')',
       ].join('\n')

package/src/add/add-auth.ts

@@ -139,7 +139,7 @@ const isInsideGlobalMiddlewareRegistration = (node: ts.Node): boolean => {
  *
  * The pikku CLI discovers that single export and generates a catch-all
  * `auth.gen.ts` that wires `${basePath}/**` to one shared handler, registers the
- * better-auth session middleware, and emits a `wireSecret` for every configured
+ * better-auth session middleware, and emits a `defineSecret` for every configured
  * social provider — so the auth routes and secret requirements flow through
  * normal inspection into the deploy manifest.
  *

package/src/add/add-cli.ts

@@ -153,6 +153,14 @@ function processCLIConfig(
         // Already handled in first pass
         break
 
+      case 'auth': {
+        const value = getPropertyValue(node, 'auth')
+        if (typeof value === 'boolean') {
+          programMeta.auth = value
+        }
+        break
+      }
+
       case 'commands':
         if (ts.isObjectLiteralExpression(prop.initializer)) {
           programMeta.commands = processCommands(

package/src/add/add-credential.ts

@@ -24,7 +24,7 @@ export const addCredential: AddWiring = (
   const firstArg = args[0]
   const expression = node.expression
 
-  if (!ts.isIdentifier(expression) || expression.text !== 'wireCredential') {
+  if (!ts.isIdentifier(expression) || expression.text !== 'defineCredential') {
     return
   }
 

package/src/add/add-functions.test.ts

@@ -1,6 +1,6 @@
 import { strict as assert } from 'assert'
 import { describe, test } from 'node:test'
-import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { inspect } from '../inspector.js'
@@ -381,3 +381,265 @@ describe('pikkuChannelConnectionFunc generic mapping', () => {
     }
   })
 })
+
+describe('pikkuRemoteChannelFunc', () => {
+  const quietLogger = (): InspectorLogger & {
+    errors: string[]
+    criticals: Array<{ code: ErrorCode; message: string }>
+  } => {
+    const errors: string[] = []
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    return {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: (message: string) => {
+        errors.push(message)
+      },
+      diagnostic: ({ code, message }) => {
+        criticals.push({ code, message })
+      },
+      critical: (code: ErrorCode, message: string) => {
+        criticals.push({ code, message })
+      },
+      hasCriticalErrors: () => criticals.length > 0,
+      errors,
+      criticals,
+    } as any
+  }
+
+  /**
+   * The vendor check keys off the declaration file's path, so a stub under
+   * `node_modules/zod` is indistinguishable from the real thing and costs this
+   * suite no dependency.
+   */
+  const writeZodStub = async (rootDir: string) => {
+    const dir = join(rootDir, 'node_modules', 'zod')
+    await mkdir(dir, { recursive: true })
+    await writeFile(
+      join(dir, 'package.json'),
+      JSON.stringify({ name: 'zod', version: '3.0.0', types: 'index.d.ts' })
+    )
+    await writeFile(
+      join(dir, 'index.d.ts'),
+      [
+        'export interface ZodType<Output = unknown> {',
+        '  _output: Output',
+        '}',
+        'export declare const z: {',
+        '  object(shape: Record<string, ZodType>): ZodType<Record<string, unknown>>',
+        '  string(): ZodType<string>',
+        '}',
+        '',
+      ].join('\n')
+    )
+  }
+
+  const DECLARE_WRAPPER = [
+    "import { z } from 'zod'",
+    'declare function pikkuRemoteChannelFunc(config: any): any',
+    'declare function pikkuSessionlessFunc(config: any): any',
+  ]
+
+  const withProject = async (
+    label: string,
+    files: Record<string, string[]>,
+    assertions: (
+      state: Awaited<ReturnType<typeof inspect>>,
+      logger: ReturnType<typeof quietLogger>
+    ) => void
+  ) => {
+    const rootDir = await mkdtemp(join(tmpdir(), `pikku-${label}-`))
+    await writeZodStub(rootDir)
+    const paths: string[] = []
+    for (const [name, lines] of Object.entries(files)) {
+      const path = join(rootDir, name)
+      await writeFile(path, [...DECLARE_WRAPPER, ...lines, ''].join('\n'))
+      paths.push(path)
+    }
+    const logger = quietLogger()
+    try {
+      assertions(await inspect(logger, paths, { rootDir }), logger)
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  }
+
+  test('a declaration with no func is registered rather than rejected', async () => {
+    await withProject(
+      'remote-channel-registers',
+      {
+        'capabilities.ts': [
+          'export const localCheckoutOutput = z.object({ sha: z.string() })',
+          'export const localCheckout = pikkuRemoteChannelFunc({',
+          "  title: 'localCheckout',",
+          "  description: 'Read the current commit of your working tree',",
+          '  output: localCheckoutOutput,',
+          '})',
+        ],
+      },
+      (state, logger) => {
+        // The ordinary path logs "No valid 'func' property" for a config with
+        // no callable func, which is what a contract-only declaration is.
+        assert.deepStrictEqual(logger.errors, [])
+        assert.deepStrictEqual(logger.criticals, [])
+
+        const meta = state.functions.meta['localCheckout']
+        assert.ok(meta, 'the declaration should be registered')
+        assert.strictEqual(meta!.functionType, 'remote')
+        assert.strictEqual(meta!.funcWrapper, 'pikkuRemoteChannelFunc')
+        assert.strictEqual(
+          meta!.description,
+          'Read the current commit of your working tree'
+        )
+      }
+    )
+  })
+
+  test('the declared schemas are what each side gets checked against', async () => {
+    await withProject(
+      'remote-channel-schemas',
+      {
+        'capabilities.ts': [
+          'export const runCommandInput = z.object({ argv: z.string() })',
+          'export const runCommandOutput = z.object({ stdout: z.string() })',
+          'export const runCommand = pikkuRemoteChannelFunc({',
+          '  input: runCommandInput,',
+          '  output: runCommandOutput,',
+          '})',
+        ],
+      },
+      (state) => {
+        const meta = state.functions.meta['runCommand']
+        assert.strictEqual(meta!.inputSchemaName, 'RunCommandInput')
+        assert.strictEqual(meta!.outputSchemaName, 'RunCommandOutput')
+        assert.deepStrictEqual(meta!.outputs, ['RunCommandOutput'])
+        assert.strictEqual(
+          state.schemaLookup.get('RunCommandOutput')?.variableName,
+          'runCommandOutput'
+        )
+      }
+    )
+  })
+
+  test('the name resolves through the RPC map, which is what channel.remote reads', async () => {
+    await withProject(
+      'remote-channel-rpc-map',
+      {
+        'capabilities.ts': [
+          'export const localCheckoutOutput = z.object({ sha: z.string() })',
+          'export const localCheckout = pikkuRemoteChannelFunc({',
+          '  output: localCheckoutOutput,',
+          '})',
+        ],
+      },
+      (state) => {
+        // Both validators look the name up here and skip validation on a miss,
+        // so an unregistered name silently disables the schema check.
+        assert.strictEqual(
+          state.rpc.internalMeta['localCheckout'],
+          'localCheckout'
+        )
+        // Imported, so a local call reaches the factory's thrower rather than
+        // missing the registry.
+        assert.strictEqual(
+          state.rpc.internalFiles.get('localCheckout')?.exportedName,
+          'localCheckout'
+        )
+      }
+    )
+  })
+
+  test('an unexported declaration is skipped, the way any unexported function is', async () => {
+    await withProject(
+      'remote-channel-unexported',
+      {
+        'capabilities.ts': [
+          'const localCheckoutOutput = z.object({ sha: z.string() })',
+          'const localCheckout = pikkuRemoteChannelFunc({',
+          '  output: localCheckoutOutput,',
+          '})',
+          'void localCheckout',
+        ],
+      },
+      (state) => {
+        // No export and no `override` leaves nothing to name it by, so it is
+        // dropped upstream and never reaches the remote-channel path.
+        assert.strictEqual(state.rpc.internalMeta['localCheckout'], undefined)
+        assert.strictEqual(state.functions.meta['localCheckout'], undefined)
+      }
+    )
+  })
+
+  test('a name claimed by override still has to be exported for the server to import it', async () => {
+    await withProject(
+      'remote-channel-override-unexported',
+      {
+        'capabilities.ts': [
+          'const localCheckoutOutput = z.object({ sha: z.string() })',
+          'const localCheckout = pikkuRemoteChannelFunc({',
+          "  override: 'localCheckout',",
+          '  output: localCheckoutOutput,',
+          '})',
+          'void localCheckout',
+        ],
+      },
+      (state, logger) => {
+        assert.strictEqual(
+          logger.errors.length,
+          1,
+          `expected one error, got ${JSON.stringify(logger.errors)}`
+        )
+        assert.match(logger.errors[0]!, /not exported/)
+        assert.strictEqual(state.rpc.internalMeta['localCheckout'], undefined)
+      }
+    )
+  })
+
+  test('two capabilities cannot share a name', async () => {
+    await withProject(
+      'remote-channel-duplicate',
+      {
+        'a.ts': [
+          'export const aOutput = z.object({ sha: z.string() })',
+          'export const localCheckout = pikkuRemoteChannelFunc({',
+          '  output: aOutput,',
+          '})',
+        ],
+        'b.ts': [
+          'export const bOutput = z.object({ sha: z.string() })',
+          'export const localCheckout = pikkuRemoteChannelFunc({',
+          '  output: bOutput,',
+          '})',
+        ],
+      },
+      (_state, logger) => {
+        const collision = logger.criticals.find(
+          (entry) => entry.code === ErrorCode.DUPLICATE_FUNCTION_NAME
+        )
+        assert.ok(collision, 'a name collision should be reported')
+        assert.match(collision!.message, /not unique/)
+      }
+    )
+  })
+
+  test('the ordinary path still rejects a config with no callable func', async () => {
+    await withProject(
+      'remote-channel-ordinary-path',
+      {
+        'capabilities.ts': [
+          'export const broken = pikkuSessionlessFunc({ auth: false })',
+        ],
+      },
+      (state, logger) => {
+        assert.strictEqual(
+          logger.errors.length,
+          1,
+          `expected one error, got ${JSON.stringify(logger.errors)}`
+        )
+        assert.match(logger.errors[0]!, /No valid 'func' property/)
+        assert.strictEqual(state.functions.meta['broken']?.functionType, 'user')
+      }
+    )
+  })
+})