@pikku/core 0.12.64 → 0.12.67

package/CHANGELOG.md

@@ -1,3 +1,314 @@
+## 0.12.67
+
+### Patch Changes
+
+- ae4f59a: Gate admin capabilities on scopes, and scaffold user management
+
+  Admin capabilities were gated on `user.role === 'admin'` — a single text column
+  meaning "can do everything". Impersonating a user, rebinding a shared
+  credential and reading the user directory are distinct capabilities that one
+  user can hold independently, so they are now scopes on an `admin` tree:
+
+  | Gate                                   | Scope                    |
+  | -------------------------------------- | ------------------------ |
+  | impersonation                          | `admin:impersonate`      |
+  | `credentialOAuth`'s `canLinkSingleton` | `admin:credentials:link` |
+  | reading the user directory             | `admin:users:list`       |
+  | creating a user out of band            | `admin:users:create`     |
+  | ban / unban                            | `admin:users:ban`        |
+  | delete a user                          | `admin:users:remove`     |
+  | revoke a user's sessions               | `admin:users:sessions`   |
+  | set a user's password                  | `admin:users:password`   |
+
+  Holding the bare `admin` scope satisfies all of them via pikku's existing
+  parent-grant rule, so it is a one-for-one replacement for the old role.
+
+  better-auth's `admin()` plugin is still what implements ban, delete,
+  session-revocation and set-password, so it stays. Its `user.role` column is no
+  longer something pikku grants: it is _projected_ from the scope store when a
+  session is built, and only from the scopes whose capability better-auth's own
+  endpoints gate on the caller's role. Someone granted `admin:users:list` can read
+  the directory — which goes straight to the auth adapter — without gaining the
+  power to ban, and revoking a scope demotes the role on the next sign-in. Scopes
+  remain the single source of truth.
+
+  New `scaffold.userAdmin` in `pikku.config.json` generates the whole set —
+  `pikkuAdminListUsers`, `pikkuAdminCreateUser`, `pikkuAdminSetUserBanned`,
+  `pikkuAdminRemoveUser`, `pikkuAdminRevokeUserSessions` and
+  `pikkuAdminSetUserPassword` — into your project. Listing or banning a user is
+  ordinary application behaviour and must not require installing the console.
+  Codegen fails with an actionable error if better-auth is wired without
+  `admin()`. The console's Users page calls these same functions, showing each
+  action only where the caller holds its scope.
+
+  Every scaffold now emits a directory named for its domain — `scaffold/admin/`,
+  `scaffold/rpc/`, `scaffold/agent/`, `scaffold/auth/`, `scaffold/console/`,
+  `scaffold/graph/`, `scaffold/realtime/`, `scaffold/scenarios/`,
+  `scaffold/webhook/`, `scaffold/workflow/` — holding its wiring file beside a
+  `*.schemas.gen.ts` sibling, and every generated payload is a zod schema instead
+  of a TypeScript generic. The schemas have to stand alone: the inspector reads a
+  zod schema by importing the module that declares it, which it cannot do for a
+  wiring file whose relative pikku-types import per-unit deploy codegen rewrites.
+
+  Resolving a schema by reference rather than by name also fixes the agent HTTP
+  surface. `agentCaller` and `agentStreamCaller` take the same payload but had to
+  repeat the type literal verbatim in each generic position, because the extractor
+  synthesised the schema name from the _function_ name and so recorded an
+  `inputSchemaName` with no schema behind it whenever the two shared a named
+  alias — every agent call through that alias failed with `MissingSchemaError`.
+  One `AgentCall` schema now backs both.
+
+  Where a payload's shape belongs to `@pikku/core` (`WorkflowRunStatus`,
+  `FunctionCoverageReport`, `StubCall[]`) the generated function carries no
+  `output` schema and the inspector infers it from the handler's return type;
+  re-declaring a core type in zod would be a second definition free to drift.
+
+  Upgrading rewrites the layout in place: codegen prunes the pre-directory copy of
+  each scaffold file before it inspects the source tree, since the old flat file
+  still wires the same routes and leaving it behind would wire everything twice.
+
+  `@pikku/core` gains `hasScopes(required, held)`, the non-throwing counterpart to
+  `verifyScopes`, and declares `auth` on `CoreSingletonServices` — the auth
+  instance the generated `pikkuServices` wrapper already injected but never typed.
+  A scope root declared twice (an addon and its host both contributing the same
+  `admin` tree) now flattens to one entry per id instead of emitting it twice.
+
+  BREAKING: there is no role fallback for the scope-gated capabilities. An app
+  that relied on the old default must register a `ScopeService` and grant `admin`
+  (or a narrower `admin:*` scope). Every gate fails closed and warns when no
+  `ScopeService` is registered. `delegatedAuth`'s `defaultRole`/`mapRole` now
+  grant a pikku role through the `ScopeService` instead of writing better-auth's
+  `role` column, and the `credentialOAuth` platform user no longer sets `banned`.
+
+  BREAKING: the console reads its user directory over the scaffolded
+  `pikkuAdminListUsers` RPC (gated on `admin:users:list`, backed by better-auth's
+  `$context.adapter`) instead of `client.admin.listUsers`, and
+  `UsersTableUser`/`UsersTableLabels` no longer carry `role` — there is no role
+  column to render. `@pikku/addon-console` no longer ships a `console:listUsers`
+  function: user management is not the console's job, so a host that wants the
+  Users page must enable `scaffold.userAdmin`.
+
+## 0.12.66
+
+### Patch Changes
+
+- 5f19016: Widen the generated agent HTTP surface, and guard attachment downloads against SSRF.
+
+  `agentCaller` and `agentStreamCaller` declared only `message`, `threadId` and
+  `resourceId` (plus `context` on the stream route), so `attachments`, `model`,
+  `temperature` — all accepted by `AIAgentInput` — were unreachable over the
+  shipped HTTP contract. No deployed app could send an attachment or a per-request
+  model override. Both callers now share an `AgentCallerInput` type covering every
+  optional field and forward each one to the RPC.
+
+  Both callers declare that shape **inline** in the generic position rather than
+  behind a shared named alias: the schema extractor only reads type literals there
+  and synthesises the schema name from the function name. Behind an alias it
+  records an `inputSchemaName` with no schema generated for it, and every agent
+  HTTP call then fails at runtime with `MissingSchemaError`.
+
+  Widening that surface makes caller-supplied attachment URLs reachable, which is
+  an SSRF vector: the AI SDK downloads attachment URLs **server-side** whenever the
+  model cannot consume them natively, using an unguarded `fetch`. A caller could
+  point an attachment at the cloud metadata endpoint or another internal host and
+  have the response relayed into the model's context. `VercelAIAgentRunner` now
+  passes an `experimental_download` implementation backed by `safeFetch` (which
+  refuses private/internal hosts and non-HTTP schemes, and re-validates every
+  redirect hop) to both `streamText` and `generateText`. URLs the model supports
+  natively are passed through untouched, so the provider still fetches those
+  itself.
+
+  The runner takes an optional `allowedAttachmentHosts` allowlist, carried across
+  `withApiKey`. `safeFetch` is now exported from `@pikku/core/safe-fetch`.
+
+- 78e4778: Stop a failed message persist during an agent stream from killing the process.
+
+  The persisting channel flushes from inside `send`, which is synchronous and so cannot await the flush. Any rejection — a dropped storage connection, or a model reusing a `toolCallId`, which is a primary key in AI storage — escaped as an unhandled rejection and took the whole server down. Persistence from `send` is now best-effort and logged; the awaited `flush()` on the suspend paths still surfaces failures to its caller.
+
+- 4324652: Scope AI agent thread reads to the calling session.
+
+  The generated thread-management functions (`getAgentThreads`,
+  `getAgentThreadMessages`, `getAgentThreadRuns`, `deleteAgentThread`) keyed purely
+  off a caller-supplied `threadId` and treated `resourceId` as an optional filter,
+  so omitting it enumerated every tenant's threads.
+  - `listThreads` gains an `owners` **authorization constraint** (distinct from the
+    `resourceId` filter): an empty array matches nothing, and it is always derived
+    from the session, never from input. Implemented across the Kysely, Redis and
+    MongoDB agent run services, with LIKE/regex metacharacter escaping so an owner
+    id containing `_` or `%` cannot match a foreign owner.
+  - The three `threadId`-keyed functions are now guarded by an `isThreadOwner`
+    `pikkuPermission` rather than an in-body check. A thread that does not exist is
+    denied rather than 404'd, so it is indistinguishable from one owned by someone
+    else.
+  - New `@pikku/core/ai-agent` helpers: `canAccessThread`, `threadOwnerConstraint`,
+    `sessionPrincipals`, `isOwnedByPrincipal`.
+
+  Services destructured by a wired function are now non-optional inside it.
+
+  The inspector already aggregated the services used by every wired `func`,
+  `permissions` and `middleware` into `RequiredSingletonServices`, but the
+  generated function types defaulted their service parameter to the raw `Services`
+  — so a service declared `foo?: Foo` still arrived as possibly-undefined, forcing
+  `if (!foo) throw new MissingServiceError(...)` guards that could never fire.
+  Generated types now expose `WiredSingletonServices` / `WiredServices`
+  (`RequiredSingletonServices & Services`) and default the `RequiredServices`
+  generic of functions, permissions, middleware, auth and approval-description
+  helpers to them. Optionality now means only what it should: "this service may
+  not be created, because nothing uses it".
+
+- de044f8: Fix the agent tool-list permission filter failing open.
+
+  `buildToolDefs` filtered permission-gated tools by resolving `checkAuthPermissions` from a function's _metadata_ — a by-name lookup into the `misc/permissions` state that nothing ever populates. It therefore collected no predicate and returned `true`, so every auth-gated tool was offered to the model regardless of session (its input schema and description leaked, and the model could attempt calls that then failed at invocation).
+
+  `checkAuthPermissions` now takes the live `CorePermissionGroup` from the function/agent config, where the `pikkuAuth` brand actually survives — matching how the agent's own gate and the function runner already resolve permissions by reference. The dead by-name lookup (`getPermissionByName`) is removed. Enforcement on invocation was never affected; this closes the exposure gap in the offered tool list.
+
+- cd1a811: warn instead of silently ignoring unknown long CLI options
+
+  An unknown long option (`--sektion functions` or `--sektion=functions`) was parsed
+  into the options object and then silently dropped by the command's input schema —
+  the command ran with the real option at its default and produced plausible-but-wrong
+  output. Unknown long options are still accepted (forward compatibility is preserved),
+  but the parser now records a warning that the runner prints to stderr, e.g.
+  `Warning: Unknown option: --sektion (ignored) Did you mean --section?`.
+
+- 19fa6f0: Fix `HTTPRouteConfig` and `HTTPRoutesGroupConfig`'s default `PikkuPermission`/`PikkuMiddleware` type parameters under-specifying their own generic arguments (e.g. `CorePikkuPermission<any>` instead of `CorePikkuPermission<any, any, any>`). The missing arguments silently fell back to `CorePikkuPermission`'s own defaults (`CoreServices`, with `schema` optional) instead of `any`, so a project whose generated services type guarantees `schema` is always present (any project using `WiredServices`-style non-optional services) failed to type-check against `defineHTTPRoutes`/`wireHTTPRoutes` with a misleading `index signature` error.
+- b501612: Enforce authorization consistently across `pikku*` primitives.
+  - `pikkuAIAgent` now enforces `permissions` (previously accepted but never
+    checked) and gains `auth` and `scopes`. Scopes are checked before permissions.
+    `auth` defaults to `false`, matching `pikkuSessionlessFunc`, since agents are
+    typically invoked from an already-authenticated function or from sessionless
+    contexts such as crons and queue workers.
+  - `pikkuWorkflowFunc` / `pikkuWorkflowComplexFunc` schema config gains `auth`
+    and `scopes` alongside `permissions`.
+  - `pikkuScenario` no longer accepts `auth`, `scopes`, or `permissions` —
+    scenarios drive the app as actors and authorize per step.
+  - `wireGateway` no longer accepts `permissions`. A gateway proxies to an agent,
+    so access is governed by normal auth plus the target agent's own rules.
+  - Removed the dead `permissions` field from `CoreWorkflow`, which was never read.
+
+  Closed two paths that reached user code without authorization:
+  - Gateway handlers were invoked directly, so a handler's own `auth`, `scopes`
+    and `permissions` were never evaluated. Webhook, websocket and listener
+    gateways now invoke the handler through the function runner. Handlers are
+    sessionless by default (inbound gateway traffic is platform-authenticated by
+    the adapter, not session-bearing); declare `auth: true` to require a session.
+    A gateway's own `auth` field is now honoured too — it was previously ignored.
+    Gateway middleware runs before the gate, so `wire.setSession()` in gateway
+    middleware — the idiomatic way to map a verified platform sender to a user —
+    is visible to the handler's `auth` and `scopes`.
+  - Resuming a suspended agent run (`resumeAIAgentSync`, `resumeAIAgent`) checked
+    run ownership but never re-ran the agent's own gate, so a scope or permission
+    revoked while a run was suspended did not prevent the caller from resuming it
+    and approving its pending tool calls. Both now re-run `assertAgentAuthorized`
+    before any state is mutated.
+
+- eb37b1e: Fix `voiceInput` middleware losing the runner receiver: it grabbed
+  `aiAgentRunner.transcribe` as a bare method reference, so calling it left `this`
+  undefined and threw `Cannot read properties of undefined (reading 'getModel')`
+  on the first audio attachment. It now calls `aiAgentRunner.transcribe(...)`
+  directly, preserving the receiver.
+
+## 0.12.65
+
+### Patch Changes
+
+- 1a86d3f: Fix a fanout collapsing into a single step, and preserve graph node config.
+  - A fanout took its `stepName` from the first step of its body. Node ids _are_
+    step names, so the loop and that step got the same id and the step overwrote
+    the loop: `await Promise.all(users.map(...))` rendered as one plain call, and
+    everything after the loop became unreachable. A fanout is not itself a cached
+    step, so it no longer borrows a name.
+  - A `workflow.sleep` or `workflow.suspend` inside a fanout body was dropped at
+    extraction — `FanoutStepMeta.body` was typed RPC-only. It now admits sleep and
+    suspend, and the regenerated body emits them.
+  - Regenerating a `pikkuWorkflowGraph` dropped `onError`, `retries` and
+    `retryDelay` from every node, and graph-level `notes`. All four are honoured
+    at runtime, so the round trip silently changed behaviour.
+
+- 1a86d3f: Support multi-step fanout bodies in DSL workflows.
+
+  A `Promise.all(array.map(...))` (or `for...of`) body containing more than one
+  `workflow.do` call previously extracted only a single step: `const`-captured
+  steps were skipped entirely by the parallel extractor, so a body like
+
+  ```ts
+  await Promise.all(
+    users.map(async (u) => {
+      const digestData = await workflow.do('Get pipeline', 'getDigestData', {
+        userId: u.id,
+      })
+      await workflow.do('Send digest', 'sendDigestEmail', { ...digestData })
+    })
+  )
+  ```
+
+  produced a graph with `getDigestData` missing and `sendDigestEmail` referencing
+  an unregistered variable. `FanoutStepMeta.child` is replaced by
+  `FanoutStepMeta.body: RpcStepMeta[]`, holding the per-iteration steps inline in
+  the same workflow — no sub-workflow boundary. Per-iteration `const` bindings are
+  now registered so later steps in the same iteration can reference them, and the
+  sequential path no longer hard-errors on bodies with more than one step.
+
+- 1a86d3f: Add `onError` compensation to DSL workflows.
+
+  A DSL workflow had no way to express error handling at all — `try/catch` is not
+  an allowed statement, and step options carried only `retries`/`retryDelay`. A
+  step can now name a compensation RPC:
+
+  ```ts
+  await workflow.do(
+    'Charge',
+    'chargeCard',
+    { id },
+    {
+      retries: 3,
+      onError: 'refundOrder',
+    }
+  )
+  ```
+
+  Semantics mirror a graph node's `onError` exactly: once the step's retries are
+  exhausted the handler is invoked with `{ error: { message } }` and the original
+  error is still thrown. This is compensation, not recovery — the workflow fails
+  either way. The handler runs as its own durable step, so a replay cannot
+  compensate twice, and it does not inherit `onError` itself.
+
+  The handler is materialised as a real graph node, so it is wired like any other
+  RPC and the console draws a dashed red "on error" edge to it rather than the
+  route being invisible.
+
+- 1a86d3f: Stop silently dropping switch cases and spread returns from workflow graphs.
+  - A fall-through case (`case 'a': case 'b': ...`) recorded only the last value.
+    A run entering on `'a'` therefore appeared to match no case at all. Empty
+    clauses now carry through to the entry they fall into — the next non-empty
+    case, otherwise `default`, otherwise the switch exit.
+  - `return { ...r, extra: 1 }` produced a return node listing only `extra`, so
+    the graph claimed an output shape the workflow does not have, with no
+    diagnostic. `return r` produced no return node at all. `ReturnStepMeta` now
+    records a `spread` list, and the regenerated code emits it.
+
+- 1a86d3f: Stop corrupting values when regenerating a workflow from its graph.
+  - A numeric `workflow.sleep('Wait', 5000)` came back as `'5000'`, and a numeric
+    `retryDelay` likewise. Durations are `string | number`; only strings are
+    quoted now.
+  - An assignment to a context variable was stored as an opaque `value`, so
+    `count = count + 1` regenerated as `count = 'count + 1'` — an expression
+    turned into a string literal. `SetStepMeta` now carries a separate
+    `expression` field (mirroring `SwitchCaseMeta`), so a string literal and a
+    code expression are no longer indistinguishable in the meta.
+  - A `next` that was not a single node id was coerced with a string cast: an
+    array became the bogus id `'a,b'` and a branch-key record became
+    `'[object Object]'`, severing every downstream node. Arrays, key-based
+    routing tables and condition lists now each render in their own shape.
+  - A `filter`/`some`/`every` node with no `outputVar` emitted
+    `const undefined = ...`, which does not parse.
+
+- 1a86d3f: Keep a `workflow.sleep` whose duration is only known at runtime (a loop
+  variable, a field off the input). The closure evaluates it, so it is legal DSL;
+  its source text is recorded as an `expression` and emitted raw when regenerating
+  code, as a set step already does.
+- 3d76f51: Add an optional `docsUrl` to `wireSecret`, `wireVariable`, and `wireCredential`, so a console or deploy UI reporting a missing value can link the user to where they obtain it instead of showing a bare identifier.
+
 ## 0.12.64
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * @module @pikku/core
  */
-export type { CommonWireMeta, CoreConfig, CorePikkuMiddleware, CorePikkuMiddlewareConfig, CorePikkuMiddlewareFactory, CorePikkuMiddlewareGroup, CoreServices, CoreSingletonServices, CoreUserSession, CreateConfig, ServerLifecycle, FunctionMeta, FunctionRuntimeMeta, FunctionServicesMeta, FunctionWiresMeta, FunctionsMeta, FunctionsRuntimeMeta, JSONPrimitive, JSONValue, MakeRequired, MiddlewareMetadata, MiddlewarePriority, PermissionMetadata, PickOptional, PickRequired, PikkuAIMiddlewareHooks, PikkuWire, PikkuRawWire, PikkuWiringTypes, PostgresConfig, RequireAtLeastOne, SecurityAuditIssue, SecurityAuditReport, SecurityAuditSummary, SecurityAuditUpdate, SecuritySeverity, SecurityUpdateLevel, SerializedError, WireServices, } from './types/core.types.js';
+export type { AuthInstance, CommonWireMeta, CoreConfig, CorePikkuMiddleware, CorePikkuMiddlewareConfig, CorePikkuMiddlewareFactory, CorePikkuMiddlewareGroup, CoreServices, CoreSingletonServices, CoreUserSession, CreateConfig, ServerLifecycle, FunctionMeta, FunctionRuntimeMeta, FunctionServicesMeta, FunctionWiresMeta, FunctionsMeta, FunctionsRuntimeMeta, JSONPrimitive, JSONValue, MakeRequired, MiddlewareMetadata, MiddlewarePriority, PermissionMetadata, PickOptional, PickRequired, PikkuAIMiddlewareHooks, PikkuWire, PikkuRawWire, PikkuWiringTypes, PostgresConfig, RequireAtLeastOne, SecurityAuditIssue, SecurityAuditReport, SecurityAuditSummary, SecurityAuditUpdate, SecuritySeverity, SecurityUpdateLevel, SerializedError, WireServices, } from './types/core.types.js';
 export { pikkuAIMiddleware, pikkuChannelMiddleware, pikkuChannelMiddlewareFactory, pikkuMiddleware, pikkuMiddlewareFactory, } from './types/core.types.js';
 export type { CorePikkuAuth, CorePikkuAuthConfig, CorePikkuFunction, CorePikkuFunctionConfig, CorePikkuPermission, CorePikkuPermissionConfig, CorePikkuPermissionFactory, CorePikkuApprovalDescription, CorePermissionGroup, ZodLike, } from './function/functions.types.js';
 export { pikkuAuth, pikkuPermission, pikkuPermissionFactory, pikkuApprovalDescription, } from './function/functions.types.js';
@@ -50,7 +50,7 @@ export type { WireRemoteAddonConfig, RemoteAddonAuth, } from './wirings/rpc/wire
 export type { PikkuPackageState } from './types/state.types.js';
 export { runMiddleware, addTagMiddleware, addTagMiddleware as addMiddleware, addGlobalMiddleware, } from './middleware-runner.js';
 export { addGlobalPermission, checkAuthPermissions } from './permissions.js';
-export { verifyScopes } from './scopes.js';
+export { hasScopes, verifyScopes } from './scopes.js';
 export { isSerializable, stopSingletonServices, pikkuServerLifecycle, } from './utils.js';
 export { getSingletonServices, getCreateWireServices, setSingletonServices, } from './pikku-state.js';
 export { clearPikkuRuntimeState } from './test-utils.js';

package/dist/index.js

@@ -18,7 +18,7 @@ export { wireAddon } from './wirings/rpc/wire-addon.js';
 export { wireRemoteAddon } from './wirings/rpc/wire-remote-addon.js';
 export { runMiddleware, addTagMiddleware, addTagMiddleware as addMiddleware, addGlobalMiddleware, } from './middleware-runner.js';
 export { addGlobalPermission, checkAuthPermissions } from './permissions.js';
-export { verifyScopes } from './scopes.js';
+export { hasScopes, verifyScopes } from './scopes.js';
 export { isSerializable, stopSingletonServices, pikkuServerLifecycle, } from './utils.js';
 export { getSingletonServices, getCreateWireServices, setSingletonServices, } from './pikku-state.js';
 export { clearPikkuRuntimeState } from './test-utils.js';

package/dist/permissions.d.ts

@@ -1,4 +1,4 @@
-import type { CoreServices, CoreUserSession, PermissionMetadata, PikkuWire } from './types/core.types.js';
+import type { CoreServices, CoreUserSession, PikkuWire } from './types/core.types.js';
 import type { CorePermissionGroup, CorePikkuPermission } from './function/functions.types.js';
 export declare const clearPermissionsCache: () => void;
 /**
@@ -36,12 +36,14 @@ export declare const addTagPermission: (_tag: string, _permissions: CorePermissi
  * A passing global requirement never contributes to the function gate, so a
  * broad global like `signedIn` can't satisfy an admin-only function.
  */
-export declare const runPermissions: ({ funcPermissions, services, wire, data, packageName, }: {
+export declare const runPermissions: ({ funcPermissions, services, wire, data, packageName, label, }: {
     funcPermissions?: CorePermissionGroup | CorePikkuPermission[];
     services: CoreServices;
     wire: PikkuWire<any, never, any, CoreUserSession, never, never, never>;
     data: any;
     packageName?: string | null;
+    /** What the non-global gate is called in debug logs, e.g. 'function', 'agent'. */
+    label?: string;
 }) => Promise<void>;
 /**
  * Checks whether a session passes the auth checks (pikkuAuth only) for a
@@ -49,10 +51,16 @@ export declare const runPermissions: ({ funcPermissions, services, wire, data, p
  * request data which isn't available at filter time. Global auth requirements
  * are included so a filtered list honours app-wide auth.
  *
- * @param funcPermissions - The PermissionMetadata[] from function or agent metadata
+ * `funcPermissions` is the live {@link CorePermissionGroup} from the function or
+ * agent config, not the metadata form: the `pikkuAuth` brand only survives on
+ * the actual predicate objects, and the by-name registry those metadata entries
+ * would resolve against is never populated. Passing metadata here would silently
+ * collect nothing and let every gated tool through.
+ *
+ * @param funcPermissions - The live permission group from the func/agent config
  * @param session - The user's session
  * @param services - Singleton services
  * @param packageName - Optional package namespace
  * @returns true if the session passes the auth checks (or no auth checks exist)
  */
-export declare const checkAuthPermissions: (funcPermissions: PermissionMetadata[] | undefined, session: CoreUserSession, services: CoreServices, packageName?: string | null) => Promise<boolean>;
+export declare const checkAuthPermissions: (funcPermissions: CorePermissionGroup | undefined, session: CoreUserSession, services: CoreServices, packageName?: string | null) => Promise<boolean>;

package/dist/permissions.js

@@ -40,26 +40,6 @@ const verifyPermissions = async (permissions, services, data, wire) => {
     }
     return false;
 };
-/**
- * Retrieves a registered permission function by its name.
- *
- * This function looks up permissions that was registered with registerPermission.
- * It's used internally by the framework to resolve permission references in metadata.
- *
- * @param {string} name - The unique name (pikkuFuncId) of the permission function.
- * @param {string | null} packageName - Optional package namespace.
- * @returns {CorePikkuPermission | undefined} The permission function, or undefined if not found.
- *
- * @internal
- */
-const getPermissionByName = (name, packageName = null) => {
-    const permissionStore = pikkuState(packageName, 'misc', 'permissions');
-    const permission = permissionStore[name];
-    if (Array.isArray(permission) && permission.length === 1) {
-        return permission[0];
-    }
-    return undefined;
-};
 const globalPermissionsCache = {};
 export const clearPermissionsCache = () => {
     for (const key of Object.keys(globalPermissionsCache)) {
@@ -131,7 +111,7 @@ const asGroup = (entry) => typeof entry === 'function' ? { permission: entry } :
  * A passing global requirement never contributes to the function gate, so a
  * broad global like `signedIn` can't satisfy an admin-only function.
  */
-export const runPermissions = async ({ funcPermissions, services, wire, data, packageName = null, }) => {
+export const runPermissions = async ({ funcPermissions, services, wire, data, packageName = null, label = 'function', }) => {
     const globals = resolveGlobalPermissions(packageName);
     for (const entry of globals) {
         if (!(await verifyPermissions(asGroup(entry), services, data, wire))) {
@@ -145,7 +125,7 @@ export const runPermissions = async ({ funcPermissions, services, wire, data, pa
             : funcPermissions;
         if (group && Object.keys(group).length > 0) {
             if (!(await verifyPermissions(group, services, data, wire))) {
-                services.logger.debug('Permission denied - function permission');
+                services.logger.debug(`Permission denied - ${label} permission`);
                 throw new ForbiddenError('Permission denied');
             }
         }
@@ -157,7 +137,13 @@ export const runPermissions = async ({ funcPermissions, services, wire, data, pa
  * request data which isn't available at filter time. Global auth requirements
  * are included so a filtered list honours app-wide auth.
  *
- * @param funcPermissions - The PermissionMetadata[] from function or agent metadata
+ * `funcPermissions` is the live {@link CorePermissionGroup} from the function or
+ * agent config, not the metadata form: the `pikkuAuth` brand only survives on
+ * the actual predicate objects, and the by-name registry those metadata entries
+ * would resolve against is never populated. Passing metadata here would silently
+ * collect nothing and let every gated tool through.
+ *
+ * @param funcPermissions - The live permission group from the func/agent config
  * @param session - The user's session
  * @param services - Singleton services
  * @param packageName - Optional package namespace
@@ -189,15 +175,8 @@ export const checkAuthPermissions = async (funcPermissions, session, services, p
     for (const entry of resolveGlobalPermissions(packageName)) {
         collect(entry);
     }
-    if (funcPermissions?.length) {
-        for (const meta of funcPermissions) {
-            if (meta.type === 'wire') {
-                const permission = getPermissionByName(meta.name, packageName);
-                if (permission) {
-                    collect(permission);
-                }
-            }
-        }
+    if (funcPermissions) {
+        collect(funcPermissions);
     }
     // No auth permissions = allowed (only data-dependent permissions exist)
     if (authPerms.length === 0)

package/dist/scopes.d.ts

@@ -1,4 +1,18 @@
 import type { CoreUserSession } from './types/core.types.js';
+/**
+ * Whether a set of held grants satisfies every required scope.
+ *
+ * The non-throwing counterpart to {@link verifyScopes}, for deciding rather
+ * than enforcing — an authorization gate that falls back to another check when
+ * it is not satisfied, rather than rejecting the request outright.
+ *
+ * Fails closed: an absent or empty `held` satisfies nothing. An empty
+ * `required` is satisfied by anything.
+ *
+ * @param required - Scopes to check for. Empty means no gate.
+ * @param held - The grants held, e.g. `session.scopes`. May be undefined.
+ */
+export declare const hasScopes: (required: readonly string[] | undefined, held: Iterable<string> | undefined) => boolean;
 /**
  * Verifies that a session holds every required scope, throwing on the first
  * one it does not.

package/dist/scopes.js

@@ -31,6 +31,42 @@ const satisfyingGrants = (scope) => {
  * `admin`.
  */
 const holds = (held, scope) => satisfyingGrants(scope).some((grant) => held.has(grant));
+/**
+ * The first required scope a set of held grants does not satisfy, or `null`
+ * when every one is satisfied.
+ *
+ * Scopes are an AND gate: every entry in `required` must be satisfied. This is
+ * deliberately distinct from `permissions`, which OR together — a scope can
+ * only ever narrow access, so adding one to a function can never widen it.
+ *
+ * Fails closed: an absent `held` satisfies nothing.
+ */
+const firstUnsatisfied = (required, held) => {
+    if (!required || required.length === 0) {
+        return null;
+    }
+    const grants = new Set(held ?? []);
+    for (const scope of required) {
+        if (!holds(grants, scope)) {
+            return scope;
+        }
+    }
+    return null;
+};
+/**
+ * Whether a set of held grants satisfies every required scope.
+ *
+ * The non-throwing counterpart to {@link verifyScopes}, for deciding rather
+ * than enforcing — an authorization gate that falls back to another check when
+ * it is not satisfied, rather than rejecting the request outright.
+ *
+ * Fails closed: an absent or empty `held` satisfies nothing. An empty
+ * `required` is satisfied by anything.
+ *
+ * @param required - Scopes to check for. Empty means no gate.
+ * @param held - The grants held, e.g. `session.scopes`. May be undefined.
+ */
+export const hasScopes = (required, held) => firstUnsatisfied(required, held) === null;
 /**
  * Verifies that a session holds every required scope, throwing on the first
  * one it does not.
@@ -47,13 +83,8 @@ const holds = (held, scope) => satisfyingGrants(scope).some((grant) => held.has(
  * @throws {MissingScopeError} Naming the first unsatisfied scope.
  */
 export const verifyScopes = (required, session) => {
-    if (!required || required.length === 0) {
-        return;
-    }
-    const held = new Set(session?.scopes ?? []);
-    for (const scope of required) {
-        if (!holds(held, scope)) {
-            throw new MissingScopeError(scope);
-        }
+    const missing = firstUnsatisfied(required, session?.scopes);
+    if (missing !== null) {
+        throw new MissingScopeError(missing);
     }
 };

package/dist/testing/service-tests.js

@@ -742,6 +742,43 @@ export function defineServiceTests(config) {
                 const threads = await agentService.listThreads();
                 assert.ok(Array.isArray(threads));
             });
+            if (services.aiStorageService) {
+                const storageFactory = services.aiStorageService;
+                // The `owners` constraint is what keeps the generated thread-management
+                // functions from leaking across tenants: a caller may only list threads
+                // owned by one of their session principals, matching the
+                // `principal:sub-partition` composition resolveOwnerResourceId writes.
+                test('listThreads scopes to the given owners, including sub-partitions', async () => {
+                    const storage = await storageFactory();
+                    await storage.createThread('owner-alice');
+                    await storage.createThread('owner-alice:project-1');
+                    await storage.createThread('owner-bob:secret');
+                    const threads = await agentService.listThreads({
+                        owners: ['owner-alice'],
+                    });
+                    const ids = threads.map((t) => t.resourceId);
+                    assert.ok(ids.includes('owner-alice'));
+                    assert.ok(ids.includes('owner-alice:project-1'));
+                    assert.ok(!ids.some((id) => id.startsWith('owner-bob')), "another owner's threads must not be listed");
+                });
+                test('listThreads with an owner does not match a lookalike prefix', async () => {
+                    const storage = await storageFactory();
+                    await storage.createThread('owner-al');
+                    await storage.createThread('owner-alice-evil:p');
+                    const threads = await agentService.listThreads({
+                        owners: ['owner-al'],
+                    });
+                    const ids = threads.map((t) => t.resourceId);
+                    assert.ok(ids.includes('owner-al'));
+                    assert.ok(!ids.includes('owner-alice-evil:p'));
+                });
+                test('listThreads with an empty owners list returns nothing', async () => {
+                    const storage = await storageFactory();
+                    await storage.createThread('owner-empty-check');
+                    const threads = await agentService.listThreads({ owners: [] });
+                    assert.deepEqual(threads, []);
+                });
+            }
             test('getThread returns null for missing', async () => {
                 const thread = await agentService.getThread('missing-thread');
                 assert.equal(thread, null);

package/dist/types/core.types.d.ts

@@ -209,6 +209,21 @@ export interface CoreUserSession {
      */
     scopes?: string[];
 }
+/**
+ * The shape pikku needs from whatever auth library a project wires: something
+ * that can answer an HTTP request and expose its own endpoints as callable
+ * methods. Kept structural so core stays independent of any one auth package —
+ * `@pikku/better-auth`'s `BetterAuthInstance` is this type.
+ */
+export interface AuthInstance {
+    handler: (request: Request) => Promise<Response>;
+    api: Record<string, any>;
+    /**
+     * The auth library's resolved context. Optional because a hand-built instance
+     * may omit it.
+     */
+    $context?: Promise<any>;
+}
 /**
  * Interface for core singleton services provided by Pikku.
  */
@@ -280,6 +295,13 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
      * better-auth's `mapSession`), never by the function runner.
      */
     scopeService?: ScopeService;
+    /**
+     * The project's resolved auth instance, built once by the factory an auth
+     * package registers (e.g. `pikkuBetterAuth`) and injected by the generated
+     * `pikkuServices` wrapper — which is why service factories are forbidden from
+     * returning it themselves. Absent when the project wires no auth.
+     */
+    auth?: () => Promise<AuthInstance>;
 }
 /**
  * Represents different forms of wire within Pikku and the outside world.