@pikku/core 0.12.62 → 0.12.64

package/CHANGELOG.md

@@ -1,3 +1,156 @@
+## 0.12.64
+
+### Patch Changes
+
+- 7ab5287: Security hardening (follow-up to the #966 C1/C3 fixes):
+  - SSRF (C1): `isPrivateHost` now also rejects alias/encoded forms that resolve to internal targets — trailing-dot FQDNs (`localhost.`), the reserved `*.localhost` name, IPv4-mapped IPv6 (`::ffff:127.0.0.1`), octal/decimal/hex-encoded IPv4 (`0177.0.0.1`, `2130706433`, `0x7f000001`), and the full `fe80::/10` link-local range. `safeFetch` also strips `Authorization` and `Cookie` headers whenever a redirect crosses origin so credentials cannot leak to a redirected host.
+  - Forgeable approval markers (C3): the sub-agent approval marker is now identified by a non-forgeable `Symbol` brand set only by framework code, instead of the plain `__approvalRequired` string key. A delegating tool's LLM-shaped `result.object` (plain JSON) can no longer conjure an approval/suspension even though the tool is allowed to forward approvals.
+
+- e86bc17: Security + feature: bind AI agent thread/run ownership to the authenticated session and add `sessionScope: 'user' | 'org'` to agents. The owner key is now the trusted principal (`session.userId`, or `session.orgId` for org-scoped agents) composed with the client `resourceId` (`principal:resourceId`), so a client-supplied `resourceId` sub-partitions within the caller's own boundary but can never widen access to another user's or org's threads. Resolution is idempotent (safe for sub-agent recursion and resume); org scope with no session org is denied; sessionless `user` wirings fall back to the bare `resourceId`.
+- a9b96a0: Security: only honor the `__approvalRequired` suspension marker from framework sub-agent tools (`forwardsApproval`), so an attacker-influenced ordinary tool result can no longer forge an approval/suspension.
+- 3f7fc54: Security: SSRF-harden outgoing webhook delivery and voice-input audio fetch (validate scheme + block private/internal hosts, re-validate every redirect hop via a shared `safeFetch`); stop the channel stream-middleware cache from reusing an earlier run's per-invocation middleware closures across runs.
+- c478794: Simplify authorization to be session + function based (#972). Permissions are now function-scoped only: global permissions AND together, a function's own permissions OR together, and the two are independent gates that both must pass — a broad global can no longer satisfy an admin-only function. Removed wire-, tag-, and HTTP-route-level permissions (`addTagPermission`, `addHTTPPermission`, wire-level `permissions` on HTTP/channel/MCP wirings). Tags are now organizational only. `auth` (session presence) and tag/HTTP middleware are unchanged.
+- 3f04ae4: Fix `pikku dev` hot-reload memory leak (#975). Changed user files were re-imported under a fresh URL on every reload (a `data:` URL on Node, a uniquely-named temp sibling on Bun), which permanently leaked a record in the native ESM loader map — the dev server climbed to `JavaScript heap out of memory` during long editing sessions (worse on Bun, which the sandbox dev server runs on). Reloading now goes through an evictable module runner that transpiles the source and runs it via `vm.compileFunction`, holding exports under a stable path key so each edit overwrites one slot and the previous module is collected. Heap stays bounded on both runtimes.
+- 90d9f04: Scope `console:getAddonInstalledPackage` to the addon's own `.pikku` metadata.
+
+  Previously every addon returned the _app's_ secrets/wirings (read from the app's
+  `.pikku` root), so the installed-package view couldn't show what a given addon
+  actually requires. `MetaService` gains optional `readPackageFile`/`readPackageDir`
+  helpers (implemented by `LocalMetaService`, which resolves the addon package's
+  root from node_modules), and `getAddonInstalledPackage` now reads secrets,
+  variables, wirings, schemas, README and package.json from the addon package
+  itself. It also reads and returns the addon's `credentials` meta (OAuth2 + wire
+  credentials), which was never surfaced before — entries with an `oauth2` field
+  are the OAuth integrations to connect.
+
+- cb079cc: A workflow-graph node's `func` can now reference a registered AI agent by name, dispatched as an agent run like sub-workflows, with `ref()` resolving the agent's output keys.
+- cb079cc: `pikkuAIAgent` gains a `workflows: []` capability: a referenced workflow is exposed to the LLM as a tool that runs inline and returns its output.
+- 0a7db82: AI agent tool `execute()` failures are now logged via `logger.error` unconditionally (then rethrown), instead of only surfacing when a tool-call middleware hook is registered.
+- 981c4db: Add a model-baked `AIEmbeddingService` interface and optional `aiEmbedding` slot on `CoreSingletonServices`, with separate `embedDocuments`/`embedQuery` methods for vector-store addons.
+- 13474a6: Generate a `ScopeId` union from `wireScope` declarations.
+
+  `pikku all` now emits `.pikku/scopes/pikku-scopes.gen.ts` with a `ScopeId` union
+  of every declared scope, plus a wildcard form for each node that has
+  descendants. A project's generated `pikkuFunc` narrows `scopes` to that union,
+  so an undeclared scope is a compile error with editor autocomplete:
+
+  ```ts
+  wireScope({ admin: { scopes: { invoices: { scopes: { create: {} } } } } })
+
+  pikkuFunc({
+    scopes: ['admin:invoices:create'],  // ✓ autocompleted
+    func: ...,
+  })
+
+  pikkuFunc({
+    scopes: ['admin:invoice:create'],   // ✗ compile error (typo)
+    func: ...,
+  })
+  ```
+
+  The inspector independently rejects undeclared scopes, so a cast that defeats
+  the compiler is still caught at build time.
+
+  Also fixes `getArrayPropertyValue` dropping any array behind a cast — idiomatic
+  `tags: ['a'] as const` was previously invisible to the inspector and silently
+  omitted from meta.
+
+- 5a2b0d5: Prune removed addons on `pikku dev` hot-reload. Deleting an addon wiring (`*.addon.ts`) regenerated `.pikku` on disk but left its `wireAddon` entry stranded in the live `pikkuState(null,'addons','packages')` map until a full restart (the reimport path is add-only), so `getInstalledAddons` kept reporting deleted addons. `reloadGeneratedMeta`'s sibling `reconcileAddonRegistry(declaredNamespaces)` now drops any addon namespace the fresh inspection no longer declares, and the dev watcher calls it with `inspectorState.rpc.wireAddonDeclarations`. Routes already reconcile (http meta is replaced wholesale + router reset); function-impl entries are intentionally left since the workflow service registers framework internals there that aren't in the generated set.
+- 13474a6: feat(scopes): grant scopes directly to a user, not only through roles
+
+  A scope can now be granted to a user directly, outside of any role.
+  `resolveScopes` returns the union of a user's role-derived scopes and their
+  direct grants, so a one-off capability no longer requires inventing a role.
+  - `@pikku/core`: `ScopeService` gains `addScopeToUser` / `removeScopeFromUser` /
+    `listUserScopes`.
+  - `@pikku/kysely`: a new `pikku_user_scope` table (FK into `pikku_scopes`, so the
+    database still refuses an undeclared grant; `ON DELETE CASCADE` from `user`,
+    so deleting a user takes their direct grants with it). `resolveScopes` unions
+    it with the role join.
+  - `@pikku/addon-console`: `scopeAddScopeToUser` / `scopeRemoveScopeFromUser`
+    (gated by `pikku:scopes:manage`), and `scopeListUserRoles` now also returns
+    `directScopes`.
+  - `@pikku/console`: a **Direct scopes** section in the user roles drawer to grant
+    and revoke scopes directly, showing them distinctly from the resolved union.
+
+  Also: the Scopes page now distinguishes a permission error (a console admin
+  without `pikku:scopes:read`) from an actual scope-service outage, instead of
+  showing "the scope service may be unavailable" for both.
+
+- ee040dc: fix(ai-agent): resolve addon-scoped services when generating a tool's approval description. The `approvalDescription` for an addon function ran against a cold per-package services cache and silently fell back to root services, so descriptions reading addon-only services (e.g. a todo store) threw and the approval `reason` never reached the client. It now builds the addon's singleton services the same way the tool's `execute` path does (#971).
+- cb079cc: `pikkuWorkflowGraph` nodes accept an optional `notes?: string` and the graph an optional `notes?: string[]`; notes are documentation only and excluded from `graphHash`.
+- 13474a6: feat: ScopeService.listScopes
+
+  Exposes the scope vocabulary held in the store — everything a role can be
+  composed from — flagging any scope that is still present but no longer declared
+  in code (inert, and awaiting `pikku scopes prune`).
+
+- 9f0d0eb: Migrate the `--oauth` addon scaffold off `OAuth2Client`. A scaffolded OAuth2
+  addon service used to construct `new OAuth2Client(config, appCredentialSecretId,
+secrets)` and do its own token exchange/refresh — the responsibility better-auth
+  now owns via the credential service. The `pikku new addon --oauth` scaffold (and
+  the OpenAPI `--openapi` generator) now emit a service that receives a ready
+  access token: `services.ts` uses `createWireServices` + `wire.getCredential<{
+accessToken: string }>(name)` and the service does a plain `fetch` with
+  `Authorization: Bearer ${accessToken}`, matching the existing per-user
+  bearer/apikey credential scaffold. With no remaining consumers, `OAuth2Client`
+  (`@pikku/core/oauth2`) and its test are removed; the `./oauth2` export keeps the
+  `OAuth2AppCredential` / `OAuth2Token` types.
+- 13474a6: Add scopes: declared, statically-checked authorization scopes on pikkuFunc.
+
+  A scope is a capability string the session must hold. Unlike `permissions` —
+  which OR together across global/wire/tag/function levels — scopes are an AND
+  gate that runs before them, so adding one can only ever narrow access.
+
+  ```ts
+  wireScope({
+    admin: {
+      scopes: { invoices: { scopes: { create: {} } } },
+    },
+  })
+
+  export const createInvoice = pikkuFunc({
+    scopes: ['admin:invoices:create'],
+    func: async (services, data) => { ... },
+  })
+  ```
+
+  The gate runs after the auth check and before the request body is evaluated,
+  since scopes depend only on the session. A session lacking a required scope
+  gets a `MissingScopeError` (403) naming it. Wildcards grant subtrees:
+  `admin:*` satisfies `admin` and `admin:invoices:create`.
+
+  `session.scopes` is populated by whoever builds the session — core reads it and
+  never fetches, keeping the runner free of I/O. The new `ScopeService` interface
+  resolves scopes at the session boundary.
+
+- 70fa400: Add outgoing webhooks — `webhookService.send()` enqueues signed deliveries onto a retrying queue, `@pikku/kysely`'s `KyselyWebhookService` persists per-attempt delivery history, and `@pikku/console` gains a read-only `/webhooks` page; also caches resolved secrets in `TypedSecretService` and registers inline-`func` metadata for queue/scheduler/trigger/gateway wirings.
+- 7b2ea23: `wireAddon` can install one addon package as multiple named instances, each with its own per-instance singleton services and `secretOverrides`/`variableOverrides`/`credentialOverrides` that alias logical names to real project secrets/variables/credentials.
+- 1dc77d5: Remove the old, pre-better-auth OAuth2 credential runtime now that the
+  `credentialOAuth` plugin owns credential linking, storage and refresh.
+  - `@pikku/core`: drop the unused `createOAuth2Handler` HTTP-routes flow (and its
+    `CreateOAuth2HandlerOptions`) from the `./oauth2` entrypoint. The credential
+    schema types (`OAuth2AppCredential`, `OAuth2Token`) and the `OAuth2Client`
+    API helper remain exported.
+  - `@pikku/addon-console`: delete the six `oauth-*` console functions
+    (connect/disconnect/status/exchange-tokens/refresh-token/test-token) and the
+    `OAuthService` behind them — credential connections now flow through
+    better-auth's `/credential-oauth/link` + `/callback`.
+  - `@pikku/console`: the credential UI no longer calls the removed
+    `console:oauth*` RPCs. Per-user and singleton (platform) OAuth2 credentials
+    connect via the `/credential-oauth/link` full-page redirect and disconnect via
+    `console:credentialDelete`; the `/oauth/callback` popup page is removed.
+
+- 416606c: Fix a TypeScript 6 `PikkuWire` constraint collapse that made `rpc` a required field: narrow `PikkuRPC` default type params from `any` to `Function` and replace bare `any` TypedRPC args with `PikkuRPC`.
+- d2a6eea: Add `wireRemoteAddon` — consume a hosted addon's `remote: true` RPCs transparently over HTTP, with the addon installed as a devDependency (types only). `rpc('ns:fn', input)` dispatches to the host's `/remote/rpc/:rpcName`, authenticating as a client with a token bound from a local source (`{ credentialId }` per-user, `{ secretId }` platform, or a custom `resolve()`), or omitted for a public surface. This is any-machine → hosted-library client auth, distinct from the trusted mesh (`PIKKU_REMOTE_SECRET`). A new `.remote.gen.d.ts` RPC map exposes only the `remote: true` surface to consumers. `pikku` verify errors if a `wireRemoteAddon` package is a production dependency (or missing) instead of a devDependency, and if a bound `credentialId`/`secretId` isn't wired.
+- 30e62ee: Add `workflow.approval(reason, { schema, expiry })` — a return-valued, expiring human-in-the-loop gate that stays closed until a decision is recorded (via `workflowService.approveStep` or `POST /workflow/:workflowName/approve/:runId`), unlike the one-shot `workflow.suspend()`.
+
+## 0.12.63
+
+### Patch Changes
+
+- ae65588: `fetchData` now defaults `exposeErrors` to `!isProduction()`, so a non-production HTTP server returns the error `message` and `stack` on unexpected 500s instead of a bare `{ errorId }`. A dev/sandbox RPC that 500s is now debuggable from the response alone; production (NODE_ENV=production) still returns only the errorId.
+
 ## 0.12.62
 
 ### Patch Changes

package/dist/dev/hot-reload.js

@@ -1,13 +1,12 @@
 import { watch } from 'node:fs';
-import { stat, readFile, copyFile, rm } from 'node:fs/promises';
-import { basename, dirname, join, resolve, relative } from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { register } from 'tsx/esm/api';
+import { stat } from 'node:fs/promises';
+import { basename, join, resolve, relative } from 'node:path';
 import { pikkuState } from '../pikku-state.js';
 import { clearMiddlewareCache } from '../middleware-runner.js';
 import { clearPermissionsCache } from '../permissions.js';
 import { clearChannelMiddlewareCache } from '../wirings/channel/channel-middleware-runner.js';
 import { httpRouter } from '../wirings/http/routers/http-router.js';
+import { createModuleRunner } from './module-runner.js';
 export * from './reload-meta.js';
 const isFunctionConfig = (value) => {
     return (typeof value === 'object' &&
@@ -33,57 +32,18 @@ const findCompiledFile = async (tsFile, srcDir, pikkuDir) => {
     }
     return null;
 };
-// Use data: URLs to import modules. This bypasses TypeScript loaders
-// (e.g. tsx) that intercept file:// imports and break dynamic ESM loading.
-// Each import gets unique content so there's no module cache to worry about.
-let tsxRegistered = false;
-const ensureTsxRegistered = () => {
-    if (tsxRegistered)
-        return;
-    register();
-    tsxRegistered = true;
-};
-let tempCounter = 0;
-const reimportModule = async (filePath, useTsx = false) => {
-    try {
-        if (useTsx) {
-            // Import a uniquely-named sibling copy: a `?t=` query does NOT bust
-            // the cache on either runtime (Bun keys module identity on the bare
-            // path; tsx's transform cache keys on the file path too), so a fresh
-            // path is the only reliable re-import. Same directory → identical
-            // resolution for relative and package-`imports` (#…) specifiers. The
-            // dot-prefix keeps it out of the watcher.
-            if (!process.versions.bun) {
-                // Node needs tsx's loader to import raw .ts; Bun imports it natively.
-                ensureTsxRegistered();
-            }
-            const abs = resolve(filePath);
-            const tempPath = join(dirname(abs), `.pikku-hot-${++tempCounter}-${basename(abs)}`);
-            await copyFile(abs, tempPath);
-            try {
-                return await import(pathToFileURL(tempPath).href);
-            }
-            finally {
-                await rm(tempPath, { force: true }).catch(() => {
-                    // Best-effort temp cleanup; a leftover dotfile is watcher-ignored.
-                });
-            }
-        }
-        const content = await readFile(resolve(filePath), 'utf-8');
-        const dataUrl = 'data:text/javascript;base64,' + Buffer.from(content).toString('base64');
-        return await import(dataUrl);
-    }
-    catch {
-        return null;
-    }
-};
+// Changed user files are re-run through an evictable module runner keyed by a
+// stable path (createModuleRunner), NOT re-imported under a fresh URL. A
+// fresh-URL import (a `data:` URL on Node, a uniquely-named temp sibling on
+// Bun) permanently leaks a record in the native ESM loader map on every
+// reload, OOMing long editing sessions; the runner overwrites a single slot so
+// the previous module is collected. See ./module-runner.ts.
 const isWatchedTsFile = (filename) => {
     return (filename.endsWith('.ts') &&
         !filename.endsWith('.test.ts') &&
         !filename.endsWith('.d.ts') &&
         !filename.endsWith('.gen.ts') &&
-        // Hidden files: editor/sed atomic-write temps and our own hot-reload
-        // sibling copies must never trigger a reload of themselves.
+        // Hidden files: editor/sed atomic-write temps must never trigger a reload.
         !basename(filename).startsWith('.'));
 };
 export async function pikkuDevReloader(options) {
@@ -92,6 +52,7 @@ export async function pikkuDevReloader(options) {
     const absPikkuDir = resolve(pikkuDir);
     const watchers = [];
     const functionsMap = pikkuState(null, 'function', 'functions');
+    const moduleRunner = createModuleRunner();
     const handleFileChange = async (changedTsFile) => {
         const start = Date.now();
         const reloadedNames = [];
@@ -101,11 +62,7 @@ export async function pikkuDevReloader(options) {
             return;
         const compiledFile = await findCompiledFile(changedTsFile, srcDir, absPikkuDir);
         const importPath = compiledFile ?? changedTsFile;
-        const usedTsxFallback = !compiledFile;
-        if (usedTsxFallback) {
-            logger.debug(`Hot-reload using tsx fallback for: ${relative(process.cwd(), changedTsFile)}`);
-        }
-        const mod = await reimportModule(importPath, usedTsxFallback);
+        const mod = await moduleRunner.run(importPath);
         if (!mod) {
             logger.error(`Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)`);
             return;
@@ -197,6 +154,7 @@ export async function pikkuDevReloader(options) {
             for (const watcher of watchers) {
                 watcher.close();
             }
+            moduleRunner.clear();
         },
         // Drain the queue of recently re-imported files and import them again.
         // A dev-server watcher calls this AFTER its codegen pass has refreshed

package/dist/dev/module-runner.d.ts

@@ -0,0 +1,14 @@
+export interface PikkuModuleRunner {
+    /** Run a user module by absolute path, returning its exports. Repeated runs
+     *  of the same path overwrite a single registry slot (the previous module is
+     *  collected). Returns `null` if transpile/compile/evaluation fails, so the
+     *  caller can keep the previously-loaded code. */
+    run: (absPath: string) => Promise<Record<string, unknown> | null>;
+    /** Drop a single module from the registry. */
+    evict: (absPath: string) => void;
+    /** Drop every module from the registry. */
+    clear: () => void;
+    /** Number of modules currently held. */
+    readonly size: number;
+}
+export declare const createModuleRunner: () => PikkuModuleRunner;

package/dist/dev/module-runner.js

@@ -0,0 +1,59 @@
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { compileFunction } from 'node:vm';
+let transformSync;
+const loadTransform = async () => {
+    if (transformSync)
+        return transformSync;
+    // esbuild is a dev-only dependency, hoisted from @pikku/cli at runtime — the
+    // same lazy pattern the reloader previously used for tsx. It is never loaded
+    // in production runtimes (the `./dev` export is dev-only).
+    const esbuild = await import('esbuild');
+    transformSync = esbuild.transformSync;
+    return transformSync;
+};
+export const createModuleRunner = () => {
+    const registry = new Map();
+    const run = async (filePath) => {
+        const absPath = resolve(filePath);
+        try {
+            const transform = await loadTransform();
+            const source = await readFile(absPath, 'utf-8');
+            // No sourcemap: an inline sourcemap embeds a base64 copy of the source
+            // that the engine retains per compile, reintroducing linear growth on
+            // Node — the exact leak this runner exists to remove. `filename` still
+            // anchors stack traces to the user file.
+            const { code } = transform(source, {
+                loader: absPath.endsWith('.ts') ? 'ts' : 'js',
+                format: 'cjs',
+                sourcefile: absPath,
+            });
+            const fn = compileFunction(code, ['require', 'exports', 'module', '__filename', '__dirname'], { filename: absPath });
+            const require = createRequire(pathToFileURL(absPath));
+            const moduleObj = { exports: {} };
+            fn(require, moduleObj.exports, moduleObj, absPath, dirname(absPath));
+            registry.set(absPath, moduleObj.exports);
+            return moduleObj.exports;
+        }
+        catch {
+            // Transpile/compile/evaluate failure (a bad edit, or the one known
+            // limitation — a file using top-level `await`, which can't be emitted in
+            // `cjs` form). Return null so the caller keeps the previously-loaded code.
+            return null;
+        }
+    };
+    return {
+        run,
+        evict: (filePath) => {
+            registry.delete(resolve(filePath));
+        },
+        clear: () => {
+            registry.clear();
+        },
+        get size() {
+            return registry.size;
+        },
+    };
+};

package/dist/dev/reload-meta.d.ts

@@ -22,3 +22,16 @@ export interface ReloadGeneratedMetaOptions {
  * never imported); those still need a restart.
  */
 export declare function reloadGeneratedMeta(options: ReloadGeneratedMetaOptions): Promise<void>;
+/**
+ * Prunes the live addon registry down to what the current source still declares.
+ *
+ * Dev hot-reload re-imports only changed/added files, so a deleted `*.addon.ts`
+ * leaves its `wireAddon` entry stranded in `pikkuState(null,'addons','packages')`
+ * until a full restart — the reason `getInstalledAddons` reports removed addons.
+ * The Map holds definitions (namespace → package config), not runtime state, so
+ * dropping any namespace the fresh inspection no longer declares is safe.
+ *
+ * `declaredNamespaces` is the set of `wireAddon` names from the just-regenerated
+ * inspection (`inspectorState.rpc.wireAddonDeclarations.keys()`).
+ */
+export declare function reconcileAddonRegistry(declaredNamespaces: Iterable<string>, logger?: Logger): void;

package/dist/dev/reload-meta.js

@@ -97,3 +97,25 @@ export async function reloadGeneratedMeta(options) {
         logger.error(`Hot-reload schema recompilation failed: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
+/**
+ * Prunes the live addon registry down to what the current source still declares.
+ *
+ * Dev hot-reload re-imports only changed/added files, so a deleted `*.addon.ts`
+ * leaves its `wireAddon` entry stranded in `pikkuState(null,'addons','packages')`
+ * until a full restart — the reason `getInstalledAddons` reports removed addons.
+ * The Map holds definitions (namespace → package config), not runtime state, so
+ * dropping any namespace the fresh inspection no longer declares is safe.
+ *
+ * `declaredNamespaces` is the set of `wireAddon` names from the just-regenerated
+ * inspection (`inspectorState.rpc.wireAddonDeclarations.keys()`).
+ */
+export function reconcileAddonRegistry(declaredNamespaces, logger) {
+    const declared = new Set(declaredNamespaces);
+    const addons = pikkuState(null, 'addons', 'packages');
+    for (const namespace of [...addons.keys()]) {
+        if (!declared.has(namespace)) {
+            addons.delete(namespace);
+            logger?.info(`• Removed unwired addon "${namespace}"`);
+        }
+    }
+}

package/dist/errors/errors.d.ts

@@ -60,6 +60,18 @@ export declare class MissingCredentialError extends PikkuError {
     };
     constructor(credentialName: string, credentialType: 'oauth2' | 'apikey', connectUrl?: string);
 }
+/**
+ * The session does not hold a scope required by the function. The payload
+ * names the missing scope so the client can surface what to request.
+ * @group Error
+ */
+export declare class MissingScopeError extends PikkuError {
+    payload: {
+        error: 'missing_scope';
+        scope: string;
+    };
+    constructor(scope: string);
+}
 /**
  * The session is readonly and cannot access a non-readonly function.
  * @group Error

package/dist/errors/errors.js

@@ -105,6 +105,25 @@ addError(MissingCredentialError, {
     status: 403,
     message: 'A required credential is not configured.',
 });
+/**
+ * The session does not hold a scope required by the function. The payload
+ * names the missing scope so the client can surface what to request.
+ * @group Error
+ */
+export class MissingScopeError extends PikkuError {
+    payload;
+    constructor(scope) {
+        super(`Missing required scope: ${scope}`);
+        this.payload = {
+            error: 'missing_scope',
+            scope,
+        };
+    }
+}
+addError(MissingScopeError, {
+    status: 403,
+    message: 'The session does not hold a scope required by this function.',
+});
 /**
  * The session is readonly and cannot access a non-readonly function.
  * @group Error

package/dist/function/function-runner.d.ts

@@ -1,12 +1,13 @@
-import type { CoreUserSession, CorePikkuMiddleware, PikkuWiringTypes, PikkuRawWire, MiddlewareMetadata, PermissionMetadata, CoreSingletonServices, CreateWireServices } from '../types/core.types.js';
+import type { CoreUserSession, CorePikkuMiddleware, PikkuWiringTypes, PikkuRawWire, MiddlewareMetadata, CoreSingletonServices, CreateWireServices } from '../types/core.types.js';
 import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js';
-import type { CorePermissionGroup, CorePikkuFunctionConfig, CorePikkuPermission } from './functions.types.js';
+import type { CorePikkuFunctionConfig } from './functions.types.js';
 import type { SessionService } from '../services/user-session-service.js';
 import { PikkuCredentialWireService } from '../services/credential-wire-service.js';
+import type { AddonInstance } from '../wirings/rpc/addon-runner.js';
 export declare const addFunction: (funcName: string, funcConfig: CorePikkuFunctionConfig<any, any>, packageName?: string | null) => void;
 export declare const getFunctionNames: (packageName?: string | null) => string[];
 export declare const getAllFunctionNames: () => string[];
-export declare const runPikkuFunc: <In = any, Out = any>(wireType: PikkuWiringTypes, wireId: string, funcName: string, { singletonServices, createWireServices, data, auth: wiringAuth, inheritedMiddleware, wireMiddleware, inheritedChannelMiddleware, wireChannelMiddleware, inheritedPermissions, wirePermissions, coerceDataFromSchema, tags, wire, sessionService, credentialWireService, packageName, }: {
+export declare const runPikkuFunc: <In = any, Out = any>(wireType: PikkuWiringTypes, wireId: string, funcName: string, { singletonServices, createWireServices, data, auth: wiringAuth, inheritedMiddleware, wireMiddleware, inheritedChannelMiddleware, wireChannelMiddleware, coerceDataFromSchema, wire, sessionService, credentialWireService, packageName, addonInstance, }: {
     singletonServices: CoreSingletonServices;
     createWireServices?: CreateWireServices;
     data: () => Promise<In> | In;
@@ -15,12 +16,11 @@ export declare const runPikkuFunc: <In = any, Out = any>(wireType: PikkuWiringTy
     wireMiddleware?: CorePikkuMiddleware[];
     inheritedChannelMiddleware?: MiddlewareMetadata[];
     wireChannelMiddleware?: CorePikkuChannelMiddleware[];
-    inheritedPermissions?: PermissionMetadata[];
-    wirePermissions?: CorePermissionGroup | CorePikkuPermission[];
     coerceDataFromSchema?: boolean;
     tags?: string[];
     wire: PikkuRawWire;
     sessionService?: SessionService<CoreUserSession>;
     credentialWireService?: PikkuCredentialWireService;
     packageName?: string | null;
+    addonInstance?: AddonInstance;
 }) => Promise<Out>;