@pikku/inspector 0.12.50 → 0.12.52

package/dist/add/add-system-role.js

@@ -0,0 +1,102 @@
+import * as ts from 'typescript';
+import { getPropertyValue } from '../utils/get-property-value.js';
+import { ErrorCode } from '../error-codes.js';
+const SEPARATOR = ':';
+/**
+ * Unwraps `x as const` / `x satisfies T` so a cast declaration is still
+ * extracted rather than silently skipped.
+ */
+const unwrapAs = (node) => ts.isAsExpression(node) || ts.isSatisfiesExpression(node)
+    ? unwrapAs(node.expression)
+    : node;
+/**
+ * Reads a `scopes: [...]` array of string literals.
+ *
+ * Returns `undefined` rather than an empty array when the property is absent
+ * or unreadable, so the caller can tell "declared no scopes" from "we could
+ * not see the scopes" — the first is a legitimate placeholder role, the second
+ * would silently produce one.
+ */
+const extractScopes = (obj, roleName, logger) => {
+    const prop = obj.properties.find((p) => ts.isPropertyAssignment(p) &&
+        (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+        p.name.text === 'scopes');
+    if (!prop) {
+        logger.critical(ErrorCode.INVALID_VALUE, `System role '${roleName}' has no 'scopes'. A role that grants nothing should say so with 'scopes: []'.`);
+        return undefined;
+    }
+    if (!ts.isPropertyAssignment(prop) ||
+        !ts.isArrayLiteralExpression(prop.initializer)) {
+        logger.critical(ErrorCode.INVALID_VALUE, `System role '${roleName}' must declare 'scopes' as an array literal.`);
+        return undefined;
+    }
+    const scopes = [];
+    for (const element of prop.initializer.elements) {
+        const unwrapped = unwrapAs(element);
+        if (!ts.isStringLiteral(unwrapped)) {
+            logger.critical(ErrorCode.INVALID_VALUE, `System role '${roleName}' lists a scope that is not a string literal. ` +
+                `Scopes are extracted by AST, so a computed value cannot be checked against the declared set.`);
+            continue;
+        }
+        scopes.push(unwrapped.text);
+    }
+    return scopes;
+};
+export const addSystemRole = (logger, node, _checker, state, _options) => {
+    if (!ts.isCallExpression(node)) {
+        return;
+    }
+    const expression = node.expression;
+    if (!ts.isIdentifier(expression) || expression.text !== 'defineSystemRole') {
+        return;
+    }
+    const firstArg = node.arguments[0];
+    if (!firstArg) {
+        return;
+    }
+    const unwrapped = unwrapAs(firstArg);
+    if (!ts.isObjectLiteralExpression(unwrapped)) {
+        return;
+    }
+    const sourceFile = node.getSourceFile().fileName;
+    for (const prop of unwrapped.properties) {
+        if (!ts.isPropertyAssignment(prop)) {
+            continue;
+        }
+        let name;
+        if (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) {
+            name = prop.name.text;
+        }
+        if (name === undefined) {
+            logger.critical(ErrorCode.NON_LITERAL_WIRE_NAME, 'A system role is declared with a key that is not a literal.');
+            continue;
+        }
+        if (name.length === 0) {
+            logger.critical(ErrorCode.INVALID_VALUE, 'A system role is declared with an empty name.');
+            continue;
+        }
+        if (name.includes(SEPARATOR)) {
+            logger.critical(ErrorCode.INVALID_VALUE, `System role '${name}' contains the '${SEPARATOR}' separator. ` +
+                `'${SEPARATOR}' delimits scope ids; a role named like a scope reads as one.`);
+            continue;
+        }
+        if (!ts.isObjectLiteralExpression(prop.initializer)) {
+            logger.critical(ErrorCode.INVALID_VALUE, `System role '${name}' must be an object literal.`);
+            continue;
+        }
+        const scopes = extractScopes(prop.initializer, name, logger);
+        if (scopes === undefined) {
+            continue;
+        }
+        const displayName = getPropertyValue(prop.initializer, 'displayName');
+        const description = getPropertyValue(prop.initializer, 'description');
+        state.systemRoles.files.add(sourceFile);
+        state.systemRoles.definitions.push({
+            name,
+            displayName: displayName || undefined,
+            description: description || undefined,
+            scopes,
+            sourceFile,
+        });
+    }
+};

package/dist/add/add-variable.js

@@ -1,6 +1,6 @@
 import { createAddKeyedWiring } from './add-keyed-wiring.js';
 export const addVariable = createAddKeyedWiring({
-    functionName: 'wireVariable',
+    functionName: 'defineVariable',
     idField: 'variableId',
     label: 'Variable',
     schemaPrefix: 'VariableSchema',

package/dist/add/add-wire-addon.js

@@ -1,4 +1,18 @@
 import * as ts from 'typescript';
+function parseStringArray(node) {
+    if (!ts.isArrayLiteralExpression(node))
+        return undefined;
+    const values = [];
+    for (const element of node.elements) {
+        // A non-literal entry (a spread, a const reference) is not statically
+        // knowable. Dropping the whole array rather than a silent partial keeps a
+        // consumer from reading a short list as the complete set of gates.
+        if (!ts.isStringLiteral(element))
+            return undefined;
+        values.push(element.text);
+    }
+    return values;
+}
 function parseStringRecord(obj) {
     const result = {};
     for (const prop of obj.properties) {
@@ -33,6 +47,9 @@ export function addWireAddon(node, state, logger) {
     let pkg;
     let rpcEndpoint;
     let mcp;
+    let auth;
+    let tags;
+    let scopes;
     let secretOverrides;
     let variableOverrides;
     let credentialOverrides;
@@ -54,6 +71,17 @@ export function addWireAddon(node, state, logger) {
                 prop.initializer.kind === ts.SyntaxKind.FalseKeyword)) {
             mcp = prop.initializer.kind === ts.SyntaxKind.TrueKeyword;
         }
+        else if (key === 'auth' &&
+            (prop.initializer.kind === ts.SyntaxKind.TrueKeyword ||
+                prop.initializer.kind === ts.SyntaxKind.FalseKeyword)) {
+            auth = prop.initializer.kind === ts.SyntaxKind.TrueKeyword;
+        }
+        else if (key === 'tags') {
+            tags = parseStringArray(prop.initializer);
+        }
+        else if (key === 'scopes') {
+            scopes = parseStringArray(prop.initializer);
+        }
         else if (key === 'secretOverrides' &&
             ts.isObjectLiteralExpression(prop.initializer)) {
             secretOverrides = parseStringRecord(prop.initializer);
@@ -74,6 +102,9 @@ export function addWireAddon(node, state, logger) {
         package: pkg,
         rpcEndpoint,
         mcp,
+        auth,
+        tags,
+        scopes,
         secretOverrides,
         variableOverrides,
         credentialOverrides,

package/dist/error-codes.d.ts

@@ -23,6 +23,7 @@ export declare enum ErrorCode {
     SCENARIO_BROWSER_STEP_NEEDS_ACTOR = "PKU677",
     SCENARIO_STEP_TARGET_NOT_STATIC = "PKU678",
     SCENARIO_NOT_EXTRACTABLE = "PKU679",
+    SCENARIO_HAS_NO_ASSERTION = "PKU680",
     WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = "PKU600",
     INVALID_DSL_WORKFLOW = "PKU641",
     WORKFLOW_GRAPH_ADDON_NOT_WIRED = "PKU642",
@@ -39,6 +40,8 @@ export declare enum ErrorCode {
     ROUTE_PARAM_MISMATCH = "PKU571",
     ROUTE_QUERY_MISMATCH = "PKU572",
     AUTH_DISABLED_REQUIRES_SESSIONLESS = "PKU573",
+    EXPOSED_FUNCTION_HAS_NO_GATE = "PKU574",
+    TAG_RESOLVES_TO_NO_MIDDLEWARE = "PKU575",
     DUPLICATE_FUNCTION_VERSION = "PKU850",
     DUPLICATE_FUNCTION_NAME = "PKU851",
     MANIFEST_MISSING = "PKU860",
@@ -49,6 +52,9 @@ export declare enum ErrorCode {
     MANIFEST_INTEGRITY_ERROR = "PKU865",
     MISSING_MODEL = "PKU145",
     INVALID_MODEL = "PKU146",
+    AGENT_TOOL_UNKNOWN_NAMESPACE = "PKU152",
+    AGENT_TOOL_NOT_FOUND = "PKU153",
+    AGENT_TOOL_MISSING_DESCRIPTION = "PKU154",
     SCHEMA_AND_WIRING_COLOCATED = "PKU490",
     SERVICES_NOT_DESTRUCTURED = "PKU410",
     WIRES_NOT_DESTRUCTURED = "PKU411",
@@ -58,7 +64,10 @@ export declare enum ErrorCode {
     PII_IN_OUTPUT = "PKU910",
     ADDON_WIRING_NOT_ALLOWED = "PKU920",
     ADDON_CONTRACT_HANDLERS_NOT_ALLOWED = "PKU921",
-    RPC_INVOCATION_TYPE_CAST = "PKU940"
+    RPC_INVOCATION_TYPE_CAST = "PKU940",
+    SECRET_SERVICE_ALIASED = "PKU950",
+    SECRET_NOT_DECLARED = "PKU951",
+    SECRET_KEY_NOT_STATIC = "PKU952"
 }
 /**
  * Severity of a tracked, coded diagnostic. `critical` always blocks the build;

package/dist/error-codes.js

@@ -25,6 +25,7 @@ export var ErrorCode;
     ErrorCode["SCENARIO_BROWSER_STEP_NEEDS_ACTOR"] = "PKU677";
     ErrorCode["SCENARIO_STEP_TARGET_NOT_STATIC"] = "PKU678";
     ErrorCode["SCENARIO_NOT_EXTRACTABLE"] = "PKU679";
+    ErrorCode["SCENARIO_HAS_NO_ASSERTION"] = "PKU680";
     ErrorCode["WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED"] = "PKU600";
     ErrorCode["INVALID_DSL_WORKFLOW"] = "PKU641";
     ErrorCode["WORKFLOW_GRAPH_ADDON_NOT_WIRED"] = "PKU642";
@@ -47,6 +48,8 @@ export var ErrorCode;
     ErrorCode["ROUTE_PARAM_MISMATCH"] = "PKU571";
     ErrorCode["ROUTE_QUERY_MISMATCH"] = "PKU572";
     ErrorCode["AUTH_DISABLED_REQUIRES_SESSIONLESS"] = "PKU573";
+    ErrorCode["EXPOSED_FUNCTION_HAS_NO_GATE"] = "PKU574";
+    ErrorCode["TAG_RESOLVES_TO_NO_MIDDLEWARE"] = "PKU575";
     // Versioning errors
     ErrorCode["DUPLICATE_FUNCTION_VERSION"] = "PKU850";
     ErrorCode["DUPLICATE_FUNCTION_NAME"] = "PKU851";
@@ -60,6 +63,10 @@ export var ErrorCode;
     // Model configuration errors
     ErrorCode["MISSING_MODEL"] = "PKU145";
     ErrorCode["INVALID_MODEL"] = "PKU146";
+    // Agent tool reference errors
+    ErrorCode["AGENT_TOOL_UNKNOWN_NAMESPACE"] = "PKU152";
+    ErrorCode["AGENT_TOOL_NOT_FOUND"] = "PKU153";
+    ErrorCode["AGENT_TOOL_MISSING_DESCRIPTION"] = "PKU154";
     // File structure errors
     ErrorCode["SCHEMA_AND_WIRING_COLOCATED"] = "PKU490";
     // Optimization diagnostics
@@ -75,4 +82,8 @@ export var ErrorCode;
     ErrorCode["ADDON_WIRING_NOT_ALLOWED"] = "PKU920";
     ErrorCode["ADDON_CONTRACT_HANDLERS_NOT_ALLOWED"] = "PKU921";
     ErrorCode["RPC_INVOCATION_TYPE_CAST"] = "PKU940";
+    // Secret boundary errors
+    ErrorCode["SECRET_SERVICE_ALIASED"] = "PKU950";
+    ErrorCode["SECRET_NOT_DECLARED"] = "PKU951";
+    ErrorCode["SECRET_KEY_NOT_STATIC"] = "PKU952";
 })(ErrorCode || (ErrorCode = {}));

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export { resolveDeployTarget } from './utils/resolve-deploy-target.js';
 export { generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
 export { createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
 export type { ContractEntry, VersionHashEntry, VersionValidateError, VersionManifest, VersionManifestEntry, } from './utils/contract-hashes.js';
-export type { InspectorFeature, InspectorFeatureEntry } from './types.js';
+export type { InspectorFeature, InspectorFeatureEntry, } from './types.js';
 export { serializeMCPJson } from './utils/serialize-mcp-json.js';
 export type { OpenAPISpecInfo } from './utils/serialize-openapi-json.js';
 export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/index.js';

package/dist/inspector.js

@@ -6,13 +6,17 @@ import { TypesMap } from './types-map.js';
 import { getFilesAndMethods } from './utils/get-files-and-methods.js';
 import { findCommonAncestor } from './utils/find-root-dir.js';
 import { createNestedProjectFilter } from './utils/nested-project-filter.js';
-import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, computeDiagnostics, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateWorkflowGraphAddons, } from './utils/post-process.js';
+import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateAgentToolReferences, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, validateSystemRoleScopes, validatePersonaRoles, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, computeSecretBrokers, validateNoSecretAliasServices, validateSecretUsage, computeDiagnostics, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateWorkflowGraphAddons, } from './utils/post-process.js';
+import { validateExposedFunctionsGated } from './utils/validate-exposed-functions-gated.js';
+import { validateTagsResolveToMiddleware } from './utils/validate-tags-resolve-to-middleware.js';
+import { annotateHttpRouteAuth } from './utils/annotate-http-route-auth.js';
 import { generateOpenAPISpec } from './utils/serialize-openapi-json.js';
 import { pikkuState } from '@pikku/core/internal';
 import { resolveLatestVersions } from './utils/resolve-versions.js';
 import { finalizeWorkflows } from './utils/workflow/graph/finalize-workflows.js';
 import { finalizeWorkflowHelperTypes, finalizeWorkflowWires, } from './utils/workflow/graph/finalize-workflow-wires.js';
 import { generateAllSchemas } from './utils/schema-generator.js';
+import { extractSecretUsage } from './utils/extract-secret-usage.js';
 import { loadAddonFunctionsMeta, loadAddonSchemas, } from './utils/load-addon-functions-meta.js';
 import { computeContractHashes, extractContractsFromMeta, updateManifest, createEmptyManifest, validateContracts, } from './utils/contract-hashes.js';
 /**
@@ -132,6 +136,7 @@ export function getInitialInspectorState(rootDir) {
         secrets: {
             definitions: [],
             files: new Set(),
+            usage: new Map(),
         },
         credentials: {
             definitions: [],
@@ -141,6 +146,14 @@ export function getInitialInspectorState(rootDir) {
             definitions: [],
             files: new Set(),
         },
+        systemRoles: {
+            definitions: [],
+            files: new Set(),
+        },
+        personas: {
+            definitions: [],
+            files: new Set(),
+        },
         variables: {
             definitions: [],
             files: new Set(),
@@ -282,6 +295,12 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         .sort((a, b) => a.fileName < b.fileName ? -1 : a.fileName > b.fileName ? 1 : 0);
     logger.debug(`Got source files in ${(performance.now() - startSourceFiles).toFixed(2)}ms`);
     const state = getInitialInspectorState(rootDir);
+    for (const sourceFile of sourceFiles) {
+        const usage = extractSecretUsage(sourceFile);
+        if (usage.keys.length > 0 || usage.dynamic.length > 0) {
+            state.secrets.usage.set(sourceFile.fileName, usage);
+        }
+    }
     // First sweep: add all functions
     const startSetup = performance.now();
     for (const sourceFile of sourceFiles) {
@@ -342,21 +361,34 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         computeResolvedIOTypes(state);
         computeMiddlewareGroupsMeta(state);
         computePermissionsGroupsMeta(state);
+        computeSecretBrokers(state);
+        validateNoSecretAliasServices(logger, checker, state);
+        validateSecretUsage(logger, state);
         computeDiagnostics(state);
         validateSchemaWiringSeparation(logger, state);
         validateWorkflowGraphAddons(logger, state);
         validateScenarioServices(logger, state);
         validateScenarioSteps(logger, state);
+        // Needs every route, every function and every wireAddon declaration
+        // together, so it can only run once the whole program is inspected.
+        annotateHttpRouteAuth(state);
+        // Last of the validators: they read function meta and every wireAddon
+        // declaration together, so they need the whole program inspected.
+        validateExposedFunctionsGated(logger, state);
+        validateTagsResolveToMiddleware(logger, state);
         if (options.openAPI) {
             state.openAPISpec = await generateOpenAPISpec(logger, state.functions.meta, state.http.meta, state.schemas, options.openAPI.additionalInfo, pikkuState(null, 'misc', 'errors'));
         }
         validateAgentModels(logger, state);
+        validateAgentToolReferences(logger, state, options);
         validateSecretOverrides(logger, state);
         validateVariableOverrides(logger, state);
         validateCredentialOverrides(logger, state);
         validateRemoteAddonDependencies(logger, state);
         validateRemoteAddonAuth(logger, state);
         validateScopeReferences(logger, state);
+        validateSystemRoleScopes(logger, state);
+        validatePersonaRoles(logger, state);
     }
     state.program = program;
     return state;

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type * as ts from 'typescript';
+import type { SecretUsage } from './utils/extract-secret-usage.js';
 import type { ChannelMessageMeta, ChannelsMeta } from '@pikku/core/channel';
 import type { GatewaysMeta } from '@pikku/core/gateway';
 import type { HTTPWiringsMeta } from '@pikku/core/http';
@@ -14,6 +15,8 @@ import type { NodesMeta } from '@pikku/core/node';
 import type { SecretDefinitions } from '@pikku/core/secret';
 import type { CredentialDefinitions } from '@pikku/core/credential';
 import type { ScopeDefinitions } from '@pikku/core/scope';
+import type { SystemRoleDefinitions } from '@pikku/core/role';
+import type { PersonaDefinitions } from '@pikku/core/persona';
 import type { VariableDefinitions } from '@pikku/core/variable';
 import type { TypesMap } from './types-map.js';
 import type { FunctionsMeta, FunctionServicesMeta, FunctionWiresMeta, JSONValue } from '@pikku/core';
@@ -31,14 +34,30 @@ export type MetaInputTypes = Map<string, {
     params: string[] | undefined;
     body: string[] | undefined;
 }>;
-export interface MiddlewareGroupMeta {
+/** One `addHTTPMiddleware`/`addTagMiddleware`/`addChannelMiddleware` call. */
+export interface MiddlewareRegistration {
     exportName: string | null;
     sourceFile: string;
     position: number;
+    isFactory: boolean;
+}
+export interface MiddlewareGroupMeta extends MiddlewareRegistration {
     services: FunctionServicesMeta;
     count: number;
     instanceIds: string[];
-    isFactory: boolean;
+    /**
+     * The registrations after the first, when several files add middleware for
+     * the same pattern or tag.
+     *
+     * A group is keyed by its pattern/tag, so without this a second file's call
+     * overwrote the first's and only the survivor got an import emitted into
+     * pikku-middleware.gen.ts — the losing file was never imported, so its
+     * registration never ran. The runtime composes repeated registrations for a
+     * pattern happily; only codegen dropped one, which is how an app could lose
+     * its session-bridge middleware to an unrelated `'*'` group and see nothing
+     * go wrong until a request arrived without a session.
+     */
+    additionalRegistrations?: MiddlewareRegistration[];
 }
 export interface InspectorHTTPState {
     metaInputTypes: MetaInputTypes;
@@ -204,6 +223,12 @@ export type InspectorOptions = Partial<{
     setupOnly: boolean;
     rootDir: string;
     isAddon: boolean;
+    /**
+     * Fail the build on metadata that only an agent needs — currently an agent
+     * tool with no description. Off by default: the runtime falls back to the
+     * tool's own name, so this is a quality gate rather than a correctness one.
+     */
+    strictMeta: boolean;
     sourceFile: ts.SourceFile;
     /**
      * The project's tsconfig, read for its path mappings only. The inspector's
@@ -464,6 +489,15 @@ export interface InspectorState {
             package: string;
             rpcEndpoint?: string;
             mcp?: boolean;
+            /**
+             * The addon's own gates. `runPikkuFunc` applies these to every function
+             * in the package, on every wiring path — not just `namespace:function`.
+             * Absent when the declared value was not a statically-knowable literal,
+             * which must be read as "unknown", never as "ungated".
+             */
+            auth?: boolean;
+            tags?: string[];
+            scopes?: string[];
             /** True when declared via `wireRemoteAddon` — import the addon's `.remote.gen` map, not `.internal.gen` */
             remote?: boolean;
             /** wireRemoteAddon: whether an `auth` binding was supplied (vs a public surface) */
@@ -522,6 +556,8 @@ export interface InspectorState {
     secrets: {
         definitions: SecretDefinitions;
         files: Set<string>;
+        /** Secret reads found per source file, keyed by absolute path. */
+        usage: Map<string, SecretUsage>;
     };
     credentials: {
         definitions: CredentialDefinitions;
@@ -531,6 +567,14 @@ export interface InspectorState {
         definitions: ScopeDefinitions;
         files: Set<string>;
     };
+    systemRoles: {
+        definitions: SystemRoleDefinitions;
+        files: Set<string>;
+    };
+    personas: {
+        definitions: PersonaDefinitions;
+        files: Set<string>;
+    };
     variables: {
         definitions: VariableDefinitions;
         files: Set<string>;

package/dist/utils/annotate-http-route-auth.d.ts

@@ -0,0 +1,22 @@
+import type { InspectorState } from '../types.js';
+/**
+ * Resolve, per HTTP route, whether reaching it requires a session.
+ *
+ * Four separate places can demand one — the function's `sessionless`, the
+ * function's own `auth`, the route's (or its group's) `auth`, and the addon the
+ * function belongs to — and they combine with OR: any of them is enough. Until
+ * this was written down, "which routes are open?" could only be answered by
+ * joining all four by hand, and getting the join wrong reads an open route as a
+ * closed one, which is the direction that costs something.
+ *
+ * A scope gate counts as requiring a session. Scopes are checked against the
+ * session's and fail closed, so an anonymous caller is rejected either way; not
+ * counting them would mark a route open that nobody can reach anonymously.
+ *
+ * Anything not statically knowable resolves to requiring a session, matching
+ * `validateExposedFunctionsGated`: an over-cautious `true` costs a route that
+ * looks stricter than it is, a wrong `false` costs an audit.
+ *
+ * knowledge: decisions/security/addon-auth-and-tags-only-tighten.md
+ */
+export declare function annotateHttpRouteAuth(state: InspectorState): void;

package/dist/utils/annotate-http-route-auth.js

@@ -0,0 +1,48 @@
+/**
+ * Resolve, per HTTP route, whether reaching it requires a session.
+ *
+ * Four separate places can demand one — the function's `sessionless`, the
+ * function's own `auth`, the route's (or its group's) `auth`, and the addon the
+ * function belongs to — and they combine with OR: any of them is enough. Until
+ * this was written down, "which routes are open?" could only be answered by
+ * joining all four by hand, and getting the join wrong reads an open route as a
+ * closed one, which is the direction that costs something.
+ *
+ * A scope gate counts as requiring a session. Scopes are checked against the
+ * session's and fail closed, so an anonymous caller is rejected either way; not
+ * counting them would mark a route open that nobody can reach anonymously.
+ *
+ * Anything not statically knowable resolves to requiring a session, matching
+ * `validateExposedFunctionsGated`: an over-cautious `true` costs a route that
+ * looks stricter than it is, a wrong `false` costs an audit.
+ *
+ * knowledge: decisions/security/addon-auth-and-tags-only-tighten.md
+ */
+export function annotateHttpRouteAuth(state) {
+    const gatedPackages = packagesGatedByTheirAddon(state);
+    for (const routes of Object.values(state.http?.meta ?? {})) {
+        for (const route of Object.values(routes)) {
+            const meta = state.functions.meta[route.refTarget ?? route.pikkuFuncId];
+            route.requiresSession =
+                // A pikkuFunc always requires a session, on every path.
+                meta?.sessionless === false ||
+                    meta?.auth === true ||
+                    (meta?.scopes?.length ?? 0) > 0 ||
+                    route.auth === true ||
+                    (route.packageName !== undefined &&
+                        gatedPackages.has(route.packageName));
+        }
+    }
+}
+/** Packages whose `wireAddon` demands a session from everything inside them. */
+function packagesGatedByTheirAddon(state) {
+    const gated = new Set();
+    for (const declaration of state.rpc?.wireAddonDeclarations?.values() ?? []) {
+        if (!declaration.package)
+            continue;
+        if (declaration.auth === true || (declaration.scopes?.length ?? 0) > 0) {
+            gated.add(declaration.package);
+        }
+    }
+    return gated;
+}

package/dist/utils/extract-function-name.js

@@ -29,15 +29,24 @@ export function funcIdToTypeName(id) {
         .join('');
 }
 /**
- * `pikkuScenarioStep({ name })` is the one wrapper whose `name` is its identity:
- * scenarios reference a step by that string, so it must become the pikkuFuncId
- * (and hence the generated step map's key), not just a cosmetic label the way
+ * The step wrappers, whichever kind of subject acts in them. A scenario calls a
+ * platform or addon step by name exactly as it calls a persona one.
+ */
+const SCENARIO_STEP_WRAPPERS = new Set([
+    'pikkuScenarioStep',
+    'pikkuPlatformScenarioStep',
+    'pikkuAddonScenarioStep',
+]);
+/**
+ * A scenario step is the one wrapper whose `name` is its identity: scenarios
+ * reference a step by that string, so it must become the pikkuFuncId (and hence
+ * the generated step map's key), not just a cosmetic label the way
  * `pikkuMiddleware`/`pikkuAgent` use it.
  */
 function extractScenarioStepName(callExpr, result) {
     if (!ts.isCallExpression(callExpr) ||
         !ts.isIdentifier(callExpr.expression) ||
-        callExpr.expression.text !== 'pikkuScenarioStep') {
+        !SCENARIO_STEP_WRAPPERS.has(callExpr.expression.text)) {
         return;
     }
     const firstArg = callExpr.arguments[0];

package/dist/utils/extract-function-node.js

@@ -1,5 +1,15 @@
 import * as ts from 'typescript';
 import { getPropertyAssignmentInitializer, resolveFunctionDeclaration, } from './type-utils.js';
+/**
+ * Where a config object's implementation can live, in the order it is looked for.
+ *
+ * `func` is the ordinary case. A `pikkuScenarioStep` instead declares one
+ * implementation per surface, and every binding shares the step's input and
+ * output — that is what makes them interchangeable — so any one of them types
+ * the step. `default` is preferred because it is the binding every step is
+ * expected to have.
+ */
+const IMPLEMENTATION_KEYS = ['func', 'default', 'browser', 'cli'];
 /**
  * Extracts the actual function node from a pikkuFunc/pikkuWorkflowFunc call
  * Handles both direct function form and config object form { func: ... }
@@ -10,7 +20,14 @@ export function extractFunctionNode(firstArg, checker) {
     // Check if first argument is a config object with 'func' property
     if (ts.isObjectLiteralExpression(firstArg)) {
         isDirectFunction = false;
-        const funcInitializer = getPropertyAssignmentInitializer(firstArg, 'func', true, checker);
+        let funcInitializer;
+        for (const key of IMPLEMENTATION_KEYS) {
+            funcInitializer =
+                getPropertyAssignmentInitializer(firstArg, key, true, checker) ??
+                    undefined;
+            if (funcInitializer)
+                break;
+        }
         if (funcInitializer) {
             funcNode = funcInitializer;
         }

package/dist/utils/extract-secret-usage.d.ts

@@ -0,0 +1,9 @@
+import ts from 'typescript';
+export type SecretUsage = {
+    /** Secret ids read with a string literal, so statically known. */
+    keys: string[];
+    /** Reads whose key could not be resolved statically, as `line:source`. */
+    dynamic: string[];
+};
+/** Secret reads in a file, whether the key is statically known or not. */
+export declare const extractSecretUsage: (sourceFile: ts.SourceFile) => SecretUsage;

package/dist/utils/extract-secret-usage.js

@@ -0,0 +1,61 @@
+import ts from 'typescript';
+const SINGLE_KEY_METHODS = new Set(['getSecret', 'hasSecret']);
+const KEY_LIST_METHODS = new Set(['getSecrets']);
+const literalKey = (node) => {
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+        return node.text;
+    }
+    return undefined;
+};
+/** Secret reads in a file, whether the key is statically known or not. */
+export const extractSecretUsage = (sourceFile) => {
+    const keys = new Set();
+    const dynamic = new Set();
+    const record = (node, argument) => {
+        const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+        dynamic.add(`${line + 1}:${(argument ?? node).getText()}`);
+    };
+    const visit = (node) => {
+        if (ts.isCallExpression(node) &&
+            ts.isPropertyAccessExpression(node.expression)) {
+            const method = node.expression.name.text;
+            const [firstArgument] = node.arguments;
+            if (SINGLE_KEY_METHODS.has(method)) {
+                if (!firstArgument) {
+                    record(node);
+                }
+                else {
+                    const key = literalKey(firstArgument);
+                    if (key === undefined) {
+                        record(node, firstArgument);
+                    }
+                    else {
+                        keys.add(key);
+                    }
+                }
+            }
+            else if (KEY_LIST_METHODS.has(method)) {
+                if (firstArgument && ts.isArrayLiteralExpression(firstArgument)) {
+                    for (const element of firstArgument.elements) {
+                        const key = literalKey(element);
+                        if (key === undefined) {
+                            record(node, element);
+                        }
+                        else {
+                            keys.add(key);
+                        }
+                    }
+                }
+                else {
+                    record(node, firstArgument);
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return {
+        keys: [...keys].sort(),
+        dynamic: [...dynamic].sort(),
+    };
+};