@pikku/inspector 0.12.50 → 0.12.54

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,93 @@
+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.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, 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/utils/workflow/dsl/extract-dsl-workflow.d.ts

@@ -8,6 +8,12 @@ export interface ExtractionResult {
     steps?: WorkflowStepMeta[];
     /** Workflow context (top-level variables) */
     context?: WorkflowContext;
+    /**
+     * The flow asserts something through an expectation helper rather than a
+     * `then` step. Recorded separately because those helpers are inline steps and
+     * leave no phase behind, so PKU680 has no other way to see them.
+     */
+    asserts?: boolean;
     reason?: string;
 }
 /**

package/dist/utils/workflow/dsl/extract-dsl-workflow.js

@@ -1,7 +1,53 @@
 import * as ts from 'typescript';
-import { isWorkflowDoCall, isWorkflowExpectEventuallyCall, isScenarioStepCall, getScenarioStepPhase, DYNAMIC_SCENARIO_STEP_TARGET, extractActorFromOptions, isWorkflowSleepCall, isWorkflowSuspendCall, isWorkflowApprovalCall, isThrowCancelException, extractCancelReason, isParallelFanout, isParallelGroup, isSequentialFanout, isArrayFilter, isArraySome, isArrayEvery, extractForOfVariable, isArrayType, getSourceText, extractSourcePath, } from './patterns.js';
+import { isWorkflowDoCall, isWorkflowExpectEventuallyCall, isScenarioStepCall, isScenarioExpectationCall, getScenarioStepPhase, DYNAMIC_SCENARIO_STEP_TARGET, extractActorFromOptions, isWorkflowSleepCall, isWorkflowSuspendCall, isWorkflowApprovalCall, isThrowCancelException, extractCancelReason, isParallelFanout, isParallelGroup, isSequentialFanout, isArrayFilter, isArraySome, isArrayEvery, extractForOfVariable, isArrayType, getSourceText, extractSourcePath, } from './patterns.js';
 import { validateNoDisallowedPatterns, validateAwaitedCalls, formatValidationErrors, } from './validation.js';
 import { extractStringLiteral, extractNumberLiteral, } from '../../extract-node-value.js';
+/**
+ * A function the walk must not step into, because nothing here says it runs.
+ *
+ * A callback handed straight to a call — a fanout's `map`, an inline
+ * `workflow.do` step — executes as part of the body and counts. A function that
+ * is merely *declared* or assigned to a name does not: an assertion parked in an
+ * unused helper asserts nothing, and counting it would let a scenario silence
+ * PKU680 with dead code.
+ */
+function isUncalledFunction(node) {
+    if (!ts.isFunctionDeclaration(node) &&
+        !ts.isFunctionExpression(node) &&
+        !ts.isArrowFunction(node)) {
+        return false;
+    }
+    if (ts.isFunctionDeclaration(node))
+        return true;
+    const parent = node.parent;
+    return !(parent &&
+        ts.isCallExpression(parent) &&
+        parent.arguments.some((argument) => argument === node));
+}
+/**
+ * Whether the body calls one of the expectation helpers anywhere it runs.
+ *
+ * A whole-body walk rather than a check inside step extraction: the helpers
+ * produce no step of their own, so there is no extraction result to hang the
+ * answer off, and one nested inside a branch asserts just as much as one at the
+ * top level.
+ */
+function hasScenarioExpectation(body) {
+    let found = false;
+    const visit = (node) => {
+        if (found)
+            return;
+        if (ts.isCallExpression(node) && isScenarioExpectationCall(node)) {
+            found = true;
+            return;
+        }
+        if (node !== body && isUncalledFunction(node))
+            return;
+        ts.forEachChild(node, visit);
+    };
+    visit(body);
+    return found;
+}
 /**
  * Extract DSL workflow metadata from a function declaration
  */
@@ -74,6 +120,7 @@ export function extractDSLWorkflow(funcNode, checker, options) {
             status: 'ok',
             steps,
             context: Object.keys(workflowContext).length > 0 ? workflowContext : undefined,
+            asserts: hasScenarioExpectation(arrowFunc.body) || undefined,
         };
     }
     catch (error) {

package/dist/utils/workflow/dsl/patterns.d.ts

@@ -20,12 +20,12 @@ export declare function isWorkflowDoCall(node: ts.CallExpression, checker: ts.Ty
  * hit repeatedly on workflow graph round-trips.
  */
 export declare const DYNAMIC_SCENARIO_STEP_TARGET = "<dynamic>";
-declare const SCENARIO_STEP_PHASES: readonly ["step", "given", "when", "then"];
+declare const SCENARIO_STEP_PHASES: readonly ["given", "when", "then"];
 export type ScenarioStepPhaseName = (typeof SCENARIO_STEP_PHASES)[number];
 /**
- * Check if a call expression is scenario.step()/given()/when()/then() — a
- * declared `pikkuScenarioStep` invoked by name. `given`/`when`/`then` are pure
- * sugar over `step`: the phase only changes the prose a reporter renders.
+ * Check if a call expression is scenario.given()/when()/then() — a declared
+ * `pikkuScenarioStep` invoked by name. `given`/`when` are pure sugar for each
+ * other; `then` additionally makes the step's bindings witnesses.
  */
 export declare function isScenarioStepCall(node: ts.CallExpression): boolean;
 /**
@@ -33,6 +33,11 @@ export declare function isScenarioStepCall(node: ts.CallExpression): boolean;
  * isn't one.
  */
 export declare function getScenarioStepPhase(node: ts.CallExpression): ScenarioStepPhaseName | undefined;
+/**
+ * Check if a call expression is one of the scenario expectation helpers —
+ * `scenario.expectService()`, `.expectError()` or `.expectEventually()`.
+ */
+export declare function isScenarioExpectationCall(node: ts.CallExpression): boolean;
 /**
  * Check if a call expression is workflow.expectEventually()
  */

package/dist/utils/workflow/dsl/patterns.js

@@ -31,11 +31,11 @@ export function isWorkflowDoCall(node, checker) {
  * hit repeatedly on workflow graph round-trips.
  */
 export const DYNAMIC_SCENARIO_STEP_TARGET = '<dynamic>';
-const SCENARIO_STEP_PHASES = ['step', 'given', 'when', 'then'];
+const SCENARIO_STEP_PHASES = ['given', 'when', 'then'];
 /**
- * Check if a call expression is scenario.step()/given()/when()/then() — a
- * declared `pikkuScenarioStep` invoked by name. `given`/`when`/`then` are pure
- * sugar over `step`: the phase only changes the prose a reporter renders.
+ * Check if a call expression is scenario.given()/when()/then() — a declared
+ * `pikkuScenarioStep` invoked by name. `given`/`when` are pure sugar for each
+ * other; `then` additionally makes the step's bindings witnesses.
  */
 export function isScenarioStepCall(node) {
     return getScenarioStepPhase(node) !== undefined;
@@ -54,6 +54,28 @@ export function getScenarioStepPhase(node) {
     }
     return SCENARIO_STEP_PHASES.find((phase) => phase === propAccess.name.text);
 }
+/**
+ * The expectation helpers that assert without being a `then`.
+ *
+ * `expectService` and `expectError` are inline steps rather than scenario
+ * steps, so they carry no phase and never reach the step meta — but each one is
+ * a witness: a recorded service call, or a refusal. PKU680 has to see them, or
+ * a scenario whose only assertion is one of these reads as asserting nothing.
+ */
+const SCENARIO_EXPECTATION_CALLS = [
+    'expectService',
+    'expectError',
+    'expectEventually',
+];
+/**
+ * Check if a call expression is one of the scenario expectation helpers —
+ * `scenario.expectService()`, `.expectError()` or `.expectEventually()`.
+ */
+export function isScenarioExpectationCall(node) {
+    return (ts.isPropertyAccessExpression(node.expression) &&
+        SCENARIO_EXPECTATION_CALLS.some((name) => name === node.expression.name.text) &&
+        isWorkflowWireIdentifier(node.expression.expression));
+}
 /**
  * Check if a call expression is workflow.expectEventually()
  */

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.54",
   "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.76"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.72",
+    "@pikku/core": "^0.12.76",
     "@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
   }