@pikku/core 0.12.118 → 0.12.121

package/CHANGELOG.md

@@ -1,3 +1,63 @@
+## 0.12.121
+
+### Patch Changes
+
+- e84abd0: Add CredentialRejectedError: an upstream refused the stored per-user credential, so the user must sign in again or reconnect it.
+
+## 0.12.120
+
+### Patch Changes
+
+- 4a9dcd2: `admin:listUsers` now pages, counts and can carry roles.
+
+  `ListUsersInput` gains `offset` and `includeRoles`; `ListUsersOutput` gains `total`, and each `User` gains `roles` and `fields`. `total` is how many users match `search`, which is what a pager counts against — `users.length` never was, because it is capped by `limit`.
+
+  ```typescript
+  const { users, total } = await rpc.invoke('admin:listUsers', {
+    search: 'example.com',
+    limit: 50,
+    offset: 50,
+    includeRoles: true,
+  })
+  ```
+
+  Paging only means something over a stable order, so the query now sorts newest first rather than however the database felt like returning rows.
+
+  Synthetic principals — the platform credential owner, Fabric service users, scenario actors — are excluded by the query instead of dropped from the page afterwards. Filtering after the fact broke both halves of paging: `limit` had already counted the rows it then discarded, so a page came back short, and `offset` skipped synthetic rows as though they were people, so the same person could appear on two pages or on none.
+
+  `includeRoles` is refused without `admin:scopes:read`. `admin:users:list` says who may see the directory; it does not say who may see what each of those users can do.
+
+  `ScopeService` gains `listRolesForUsers(userIds)`, implemented in `@pikku/kysely`. It answers for every id asked for — an empty array for a user holding no roles, so a caller cannot read a missing key as "holds nothing" — and chunks its `in` list to stay inside the bound-parameter cap. A page of users used to cost one query per row, which on a database reached over the network is a round trip per row.
+
+  ```typescript
+  listRolesForUsers(userIds: string[]): Promise<Record<string, string[]>>
+  ```
+
+  Anything implementing `ScopeService` outside this repository has to add it.
+
+- 5ab24ad: Scenario recordings can be followed by eye, at no cost to the run. The encode holds each browser step's starting screen, and the last frame, for two seconds (`E2E_VIDEO_STEP_HOLD_MS`, `0` to turn off). The step offsets in the run record account for the holds. Recordings are made at the viewport's own size instead of Playwright's 800px downscale, and they show a pointer that follows the mouse and jumps to each filled field. Drivers get an optional `ScenarioBrowserProvider.markVideoStep(actor)`, which returns a step's offset in the finished video. It is preferred over `videoStartedAt`.
+- 42b7ac3: The app decides which of an addon's functions `rpc.exposed` reaches
+
+  `wireAddon` takes `expose?: boolean | string[]`, mirroring `mcp`. Unset or
+  `true` keeps the functions the addon declared `expose: true`; `false` exposes
+  none of the instance's functions; a list names exactly the functions to expose,
+  whether or not the addon declared them, typed against the addon's function
+  names. A listed name the addon does not publish fails the build with PKU343, a value that is not written inline fails it with
+  PKU344,
+  and the deploy analyzer's per-addon unit carries only what the wiring exposes.
+
+## 0.12.119
+
+### Patch Changes
+
+- e85f07e: A route declaring a numeric parameter could not be called over a query string. `coerceTopLevelDataFromSchema` converted an `array` from a comma-separated string and a `date-time` from text, but left numbers alone — and because the JSON Schema check runs before zod, `?year=2027` was rejected as `Instance type "string" is invalid. Expected "integer"` before the function ever ran. `z.coerce.number()` does not help: it runs after the schema has already refused. The shipped validator is spec-compliant and has no `coerceTypes` of its own, and `minimum`/`maximum` cannot stand in for one, being value constraints that apply only to instances that are already numbers.
+
+  `integer` and `number` now coerce from a string, on the same path as the two existing cases — so query strings, path params and argv reach a numeric parameter.
+
+  A string converts only when the number it produces prints back as the identical text. That rules out the readings that quietly rewrite the input — `007`, `+5`, `1e3`, `2027.50`, a padded `12` — and the values `Number` invents from nothing, where `''` and `'  '` both become `0`. It also rules out `9007199254740993`, which does not survive a double: a caller who sends an id as a string is usually doing so precisely because it does not, and rounding it silently would be data corruption. `NaN` and `Infinity` are refused for the same reason, and a fraction is refused where `integer` was asked for. Everything refused is left exactly as it arrived, so the validator reports the value the caller actually sent.
+
+  Note that this applies wherever the existing coercions already applied, which includes a JSON body — a string `"2027"` for a numeric field is now accepted there too, consistently with how an array and a `date-time` have always been read. A union `type` such as `['integer', 'null']` is left alone, as the array and `date-time` cases already leave it.
+
 ## 0.12.118
 
 ### Patch Changes

package/dist/errors/errors.d.ts

@@ -28,6 +28,14 @@ export declare class MissingCredentialError extends PikkuError {
     };
     constructor(credentialName: string, credentialType: 'oauth2' | 'apikey', connectUrl?: string);
 }
+export declare class CredentialRejectedError extends PikkuError {
+    payload: {
+        error: 'credential_rejected';
+        credentialName: string;
+        reauth: 'sign-in' | 'connect';
+    };
+    constructor(credentialName: string, reauth: 'sign-in' | 'connect', message?: string);
+}
 export declare class MissingScopeError extends PikkuError {
     payload: {
         error: 'missing_scope';

package/dist/errors/errors.js

@@ -73,6 +73,20 @@ addError(MissingCredentialError, {
     status: 403,
     message: 'A required credential is not configured.',
 });
+export class CredentialRejectedError extends PikkuError {
+    payload;
+    constructor(credentialName, reauth, message) {
+        super(message ??
+            (reauth === 'sign-in'
+                ? `${credentialName} rejected the stored session — sign in again`
+                : `${credentialName} rejected the stored credential — reconnect it`));
+        this.payload = { error: 'credential_rejected', credentialName, reauth };
+    }
+}
+addError(CredentialRejectedError, {
+    status: 403,
+    message: 'The upstream service rejected the stored credential; the user has to sign in again or reconnect it.',
+});
 export class MissingScopeError extends PikkuError {
     payload;
     constructor(scope) {

package/dist/schema.js

@@ -77,6 +77,41 @@ export const applyDefaultsFromSchema = (schemaName, data, packageName = null) =>
     }
     return result;
 };
+/**
+ * A query string and an argv array carry numbers as text, and the JSON Schema
+ * check runs first — so without this a route declaring `year: number` can never
+ * be called at all: `?year=2027` is rejected as `Instance type "string" is
+ * invalid` long before zod or the function body get a look at it. The shipped
+ * validator is spec-compliant and has no `coerceTypes` of its own, so the
+ * conversion has to happen here.
+ *
+ * The rule is that a coerced value must be the *same* value, not merely a
+ * plausible reading of it. So a string converts only if the number it produces
+ * prints back as the identical text. That is a stronger test than it looks: it
+ * is what stops `9007199254740993` from silently becoming ...92, which is the
+ * one failure mode leniency cannot excuse, because a caller who sends an id as
+ * a string is usually doing it precisely because the number does not survive a
+ * double. It also rules out every reading that quietly rewrites the input —
+ * `007`, `+5`, `1e3`, `2027.50`, a padded ` 12 ` — along with the values
+ * `Number` invents out of nothing, where `''` and `'  '` both become 0.
+ *
+ * Anything it rejects is left exactly as it arrived, so the validator reports
+ * the value the caller actually sent rather than one this function made up.
+ * Erring that way costs a loud 422 on an odd-looking but legal input; erring
+ * the other way corrupts data in silence.
+ */
+const coerceNumeric = (value, integer) => {
+    const parsed = Number(value);
+    // Rejects NaN and Infinity, both of which would otherwise round-trip through
+    // String() unchanged, and neither of which JSON can carry anyway.
+    if (!Number.isFinite(parsed))
+        return value;
+    if (String(parsed) !== value)
+        return value;
+    if (integer && !Number.isInteger(parsed))
+        return value;
+    return parsed;
+};
 export const coerceTopLevelDataFromSchema = (schemaName, data, packageName = null) => {
     const schema = pikkuState(packageName, 'misc', 'schemas').get(schemaName);
     if (!schema?.properties)
@@ -96,6 +131,10 @@ export const coerceTopLevelDataFromSchema = (schemaName, data, packageName = nul
         else if (type === 'string' && property.format === 'date-time') {
             data[key] = new Date(data[key]);
         }
+        else if ((type === 'integer' || type === 'number') &&
+            typeof data[key] === 'string') {
+            data[key] = coerceNumeric(data[key], type === 'integer');
+        }
     }
 };
 /**

package/dist/services/scope-service.d.ts

@@ -57,6 +57,19 @@ export interface ScopeService {
     addUserToRole(userId: string, role: string, grantedBy?: string): Promise<void>;
     removeUserFromRole(userId: string, role: string): Promise<void>;
     listUserRoles(userId: string): Promise<string[]>;
+    /**
+     * The roles held by each of `userIds`, keyed by user id.
+     *
+     * Every id asked for comes back as a key, holding an empty array when the
+     * user has no roles — so a caller can index the result directly and cannot
+     * mistake "this user was not in the answer" for "this user holds nothing".
+     *
+     * Exists because listing a page of the user directory otherwise costs one
+     * query per row. Against a database reached over the network — which is the
+     * normal case for a deployed unit — that is a round trip per user, so a page
+     * of fifty is fifty of them.
+     */
+    listRolesForUsers(userIds: string[]): Promise<Record<string, string[]>>;
     /** Grants outside of any role; additive with the user's role-derived scopes. */
     addScopeToUser(userId: string, scope: string, grantedBy?: string): Promise<void>;
     removeScopeFromUser(userId: string, scope: string): Promise<void>;

package/dist/types/state.types.d.ts

@@ -37,6 +37,8 @@ export interface PikkuPackageState {
             rpcEndpoint?: string;
             auth?: boolean;
             tags?: string[];
+            /** Which functions `rpc.exposed` may call: unset/`true` keeps the addon's own `expose`, `false` none, a list exactly those */
+            expose?: boolean | string[];
             /** Required of every function in this package, on top of the function's own */
             scopes?: string[];
             /** Per-instance name-aliases: logical name the addon reads -> actual project secret name */

package/dist/wirings/addon/wire-addon.d.ts

@@ -16,6 +16,16 @@ export type WireAddonConfig = {
      * and is typed against the addon's function names.
      */
     mcp?: boolean | string[];
+    /**
+     * Which of the addon's functions `rpc.exposed` may call, under
+     * `<name>:<function>`. Unset or `true` keeps the functions the addon itself
+     * declared `expose: true`; `false` exposes none of them; a list names exactly
+     * the functions to expose, whether or not the addon declared them, and is
+     * typed against the addon's function names.
+     *
+     * knowledge: decisions/security/wire-addon-expose-selects-the-rpc-surface.md
+     */
+    expose?: boolean | string[];
     /**
      * Serves this addon's MCP tools on an endpoint of their own rather than
      * folding them into the project's single `/mcp`. `true` mounts them at
@@ -62,6 +72,14 @@ export type WireAddonConfig = {
  * @example snippet: addonWiring
  */
 export declare const wireAddon: (config: WireAddonConfig) => void;
+/**
+ * Whether `rpc.exposed` may reach an addon function through the instance that
+ * resolved it. The wiring's `expose` decides when it is `false` or a list;
+ * otherwise the addon's own `expose: true` does.
+ *
+ * knowledge: decisions/security/wire-addon-expose-selects-the-rpc-surface.md
+ */
+export declare const isAddonFunctionExposed: (expose: boolean | string[] | undefined, functionName: string, declaredExpose: boolean | undefined) => boolean;
 /**
  * knowledge: decisions/security/addon-scopes-are-resolved-where-the-function-runs.md
  */

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

@@ -12,6 +12,7 @@ export const wireAddon = (config) => {
         rpcEndpoint: config.rpcEndpoint,
         auth: config.auth,
         tags: config.tags,
+        ...(config.expose !== undefined ? { expose: config.expose } : {}),
         ...(config.scopes ? { scopes: config.scopes } : {}),
         ...(config.secretOverrides
             ? { secretOverrides: config.secretOverrides }
@@ -32,6 +33,22 @@ export const wireAddon = (config) => {
             : {}),
     });
 };
+/**
+ * Whether `rpc.exposed` may reach an addon function through the instance that
+ * resolved it. The wiring's `expose` decides when it is `false` or a list;
+ * otherwise the addon's own `expose: true` does.
+ *
+ * knowledge: decisions/security/wire-addon-expose-selects-the-rpc-surface.md
+ */
+export const isAddonFunctionExposed = (expose, functionName, declaredExpose) => {
+    if (Array.isArray(expose)) {
+        return expose.includes(functionName);
+    }
+    if (expose === false) {
+        return false;
+    }
+    return declaredExpose === true;
+};
 /**
  * The addon configs a running function is governed by: the named instance when
  * the caller resolved one, every instance of the package otherwise.

package/dist/wirings/rpc/rpc-runner.js

@@ -1,5 +1,6 @@
 import { runPikkuFunc } from '../../function/function-runner.js';
 import { addonInstanceForNamespace } from '../addon/addon-runner.js';
+import { isAddonFunctionExposed } from '../addon/wire-addon.js';
 import { pikkuState } from '../../pikku-state.js';
 import { PikkuError, addError } from '../../errors/error-handler.js';
 import { parseVersionedId } from '../../version.js';
@@ -110,10 +111,11 @@ export class ContextAwareRPCService {
     }
     async rpcExposed(funcName, data) {
         let functionMeta;
+        let resolvedAddon = null;
         if (funcName.includes(':')) {
-            const resolved = resolveNamespace(funcName);
-            if (resolved) {
-                functionMeta = pikkuState(resolved.package, 'function', 'meta')[resolved.function];
+            resolvedAddon = resolveNamespace(funcName);
+            if (resolvedAddon) {
+                functionMeta = pikkuState(resolvedAddon.package, 'function', 'meta')[resolvedAddon.function];
             }
         }
         else {
@@ -121,12 +123,24 @@ export class ContextAwareRPCService {
             functionMeta = pikkuState(resolved.packageName, 'function', 'meta')[resolved.pikkuFuncId];
         }
         if (!functionMeta) {
-            if (funcName.includes(':') && this.services.deploymentService) {
+            // The addon runs in another deploy unit, which only carries the
+            // functions the analyzer found exposed. A wiring present here still
+            // gets to narrow what is forwarded.
+            const refusedHere = resolvedAddon &&
+                (resolvedAddon.addonConfig.expose === false ||
+                    (Array.isArray(resolvedAddon.addonConfig.expose) &&
+                        !resolvedAddon.addonConfig.expose.includes(resolvedAddon.function)));
+            if (funcName.includes(':') &&
+                this.services.deploymentService &&
+                !refusedHere) {
                 return await this.rpc(funcName, data);
             }
             throw new RPCNotFoundError(funcName);
         }
-        if (!functionMeta.expose || functionMeta.scenarioStep) {
+        const exposed = resolvedAddon
+            ? isAddonFunctionExposed(resolvedAddon.addonConfig.expose, resolvedAddon.function, functionMeta.expose)
+            : functionMeta.expose;
+        if (!exposed || functionMeta.scenarioStep) {
             throw new RPCNotFoundError(funcName);
         }
         return await this.rpc(funcName, data);

package/dist/wirings/rpc/rpc-types.d.ts

@@ -45,6 +45,8 @@ export interface ResolvedFunction {
         package: string;
         auth?: boolean;
         tags?: string[];
+        /** Set by the consuming app: which functions `rpc.exposed` may call */
+        expose?: boolean | string[];
         rpcEndpoint?: string;
         secretOverrides?: Record<string, string>;
         variableOverrides?: Record<string, string>;

package/dist/wirings/workflow/pikku-scenario-service.d.ts

@@ -204,6 +204,8 @@ export declare class PikkuScenarioService implements WorkflowRunExtension {
      * clear them, and the only moment they are still wanted.
      */
     takeStepVideoOffsets(runId: string): Map<string, ScenarioStepVideoOffset[]>;
+    /** Where a step starting now falls in this actor's recording, if anywhere. */
+    private videoOffsetFor;
     /**
      * Stamp where a step began inside one actor's recording.
      *

package/dist/wirings/workflow/pikku-scenario-service.js

@@ -309,6 +309,17 @@ export class PikkuScenarioService {
         this.runVideoOffsets.delete(runId);
         return offsets ?? new Map();
     }
+    /** Where a step starting now falls in this actor's recording, if anywhere. */
+    videoOffsetFor(actor) {
+        const provider = this.scenarioBrowserProvider;
+        if (provider?.markVideoStep) {
+            return provider.markVideoStep(actor);
+        }
+        const startedAt = provider?.videoStartedAt?.(actor);
+        return startedAt === undefined
+            ? undefined
+            : Math.max(0, Date.now() - startedAt);
+    }
     /**
      * Stamp where a step began inside one actor's recording.
      *
@@ -678,18 +689,19 @@ export class PikkuScenarioService {
                     // The dispatch guard above already refused an actor-less call, and a
                     // browser binding always requires one.
                     wire.browser = await this.scenarioBrowserProvider.sessionFor(actor.name);
-                    const videoStartedAt = this.scenarioBrowserProvider.videoStartedAt?.(actor.name);
-                    if (videoStartedAt !== undefined) {
-                        this.recordVideoOffset(runId, stepName, actor.name, Math.max(0, Date.now() - videoStartedAt));
+                    const offsetMs = this.videoOffsetFor(actor.name);
+                    if (offsetMs !== undefined) {
+                        this.recordVideoOffset(runId, stepName, actor.name, offsetMs);
                     }
                 }
-                return await runPikkuFunc('workflow', workflowName, resolvedStepFunc, {
+                const result = await runPikkuFunc('workflow', workflowName, resolvedStepFunc, {
                     singletonServices: getSingletonServices(),
                     createWireServices: getCreateWireServices(),
                     data: () => data,
                     wire,
                     packageName: packageName ?? undefined,
                 });
+                return result;
             };
             if (resolution.kind === 'action') {
                 if (resolution.fellBack &&

package/dist/wirings/workflow/scenario-step.types.d.ts

@@ -177,6 +177,14 @@ export interface ScenarioScreenshotOptions {
     /** Photograph the whole scrollable page rather than the viewport. */
     fullPage?: boolean;
 }
+/**
+ * One actor's browser session, handed to a step as `wire.browser`.
+ *
+ * Only what every driver can honour is declared here. A driver package adds
+ * the rest by declaration-merging onto this interface — `@pikku/playwright`
+ * contributes `page`, `context` and `locate` — so a step written against the
+ * structural surface keeps working whichever driver runs it.
+ */
 export interface PikkuBrowserWire {
     /** The actor whose browser context this is */
     readonly actor: string;
@@ -244,6 +252,15 @@ export interface ScenarioBrowserProvider {
      * for a run recording nothing — both of which leave the step's offset off.
      */
     videoStartedAt?(actorName: string): number | undefined;
+    /**
+     * Mark a browser step starting in this actor's recording, answering where it
+     * falls in the finished video (ms).
+     *
+     * Preferred over `videoStartedAt` when present: a driver that edits its
+     * footage afterwards — holding each step's screen still, say — is the only
+     * one that knows how far that moves the step. Undefined when nothing records.
+     */
+    markVideoStep?(actorName: string): number | undefined;
     /**
      * Snapshot every open window for a failed scenario. `label` identifies the
      * scenario in artifact filenames. Never throws: a failure to capture must

package/knowledge/decisions/security/index.md

@@ -24,6 +24,7 @@ A rule about who may do what, and which way it fails when it is unsure.
 - [Addon auth and tags only tighten, and resolve where the function runs](addon-auth-and-tags-only-tighten.md) — wireAddon auth and tags are applied in runPikkuFunc like scopes, but auth:false is ignored and tags resolve against the consuming app's tag groups rather than the addon package's
 - [Addon auth and tag gates apply wherever the function runs, including inside the addon](addon-config-gates-apply-only-at-the-namespaced-rpc-boundary.md) — wireAddon's auth and tags moved from the namespaced RPC boundary into runPikkuFunc, so they also apply to direct wirings and to bare intra-addon calls
 - [Addon scopes are resolved where the function runs](addon-scopes-are-resolved-where-the-function-runs.md) — wireAddon scopes are merged inside runPikkuFunc rather than at namespace resolution, because most wirings reach an addon function without ever resolving a namespace
+- [wireAddon expose selects the RPC surface, and a list may widen it](wire-addon-expose-selects-the-rpc-surface.md) — The consuming app decides which addon functions rpc.exposed reaches per instance — unset keeps the addon's own expose, false closes the instance, a list names exactly what is callable — and the deploy analyzer applies the same rule
 - [Only a Symbol-branded framework result can request tool approval](ai-agent-approval-forwarding-requires-a-symbol-brand.md) — Approval markers are trusted from the APPROVAL_REQUIRED Symbol on a forwardsApproval tool, never from a JSON key an LLM could emit
 - [Credential requests are trusted only when Symbol-branded](ai-agent-credential-requests-are-symbol-branded.md) — The string key is a wire field; the Symbol is the capability, and only core can mint it
 - [An agent requires a session only when auth is true, but always enforces scopes and permissions](ai-agent-gate-requires-a-session-only-when-auth-is-true.md) — Agents follow pikkuSessionlessFunc semantics so crons and queue workers can run them; scopes are an AND gate checked before any permission I/O

package/knowledge/decisions/security/wire-addon-expose-selects-the-rpc-surface.md

@@ -0,0 +1,51 @@
+---
+type: decision
+title: wireAddon expose selects the RPC surface, and a list may widen it
+description: The consuming app decides which addon functions rpc.exposed reaches per instance — unset keeps the addon's own expose, false closes the instance, a list names exactly what is callable — and the deploy analyzer applies the same rule
+tags: addon, rpc, expose, authorization
+---
+
+# wireAddon expose selects the RPC surface, and a list may widen it
+
+`rpc.exposed('<name>:<fn>')` — what the generated `POST /rpc/:rpcName` forwards
+to — used to consult only the addon's own `expose: true`. The app installing the
+addon had no say: it could not close an addon whose author marked functions
+exposed, and it could not open one the author had not. `mcp` already worked the
+other way (the wiring decides), and the two now match.
+
+`expose` on `wireAddon` is `boolean | string[]`, resolved per instance by
+`isAddonFunctionExposed`:
+
+- **unset or `true`** — the addon's declaration decides, as before. Keeping the
+  default unchanged means no existing app gains or loses a route on upgrade.
+- **`false`** — nothing in this instance is reachable through `rpc.exposed`.
+- **a list** — exactly those functions, whether or not the addon declared them.
+  The list can widen the addon's surface, the same power `mcp` has, because the
+  app is the one that knows what its deployment should offer. The generated
+  `#pikku/addon` types the list against the package's function names, and a name
+  that survives to the build unpublished fails it with PKU343.
+  The value has to be written inline (`true`, `false` or an array of string
+  literals): the build reads it statically, and a variable or spread fails it
+  with PKU344 rather than being read as unset, which would leave the deploy
+  units disagreeing with the runtime.
+
+The decision is per **instance**, not per package: two `wireAddon` calls for one
+package may expose different things, and the gate reads the config the
+namespace resolved to.
+
+The deploy analyzer's per-addon unit applies the same rule, since that unit is
+what the dispatcher can forward to. A function the wiring refuses gets no unit
+and no dispatch entry, so the `deploymentService` fallback in `rpc.exposed` —
+which forwards namespaced names with no local metadata — has nothing to reach.
+Where the dispatcher does hold the wiring, it also refuses locally before
+forwarding.
+
+`expose` is reachability, not authorization. A listed function still runs
+through `runPikkuFunc` with its own `auth`, permissions and the instance's
+`auth`/`scopes`/`tags` — see
+[addon auth and tags](./addon-auth-and-tags-only-tighten.md). Widening the list
+to a sessionless function makes it public unless one of those gates it.
+
+**What this rules out:** letting the addon's `expose: true` override a wiring's
+`false`; treating an unknown list entry as a silent no-op; and a deploy unit
+that carries functions the runtime gate would refuse.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.118",
+  "version": "0.12.121",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",

package/src/public-surface.json

@@ -371,6 +371,7 @@
     "BadGatewayError",
     "BadRequestError",
     "ConflictError",
+    "CredentialRejectedError",
     "ExpectationFailedError",
     "FeatureUnavailableError",
     "ForbiddenError",