@pikku/core 0.12.63 → 0.12.64

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

@@ -21,15 +21,18 @@ import type { AIStorageService } from '../services/ai-storage-service.js';
 import type { ContentService } from '../services/content-service.js';
 import type { ScenarioActors } from '../services/scenario-actors-service.js';
 import type { AIAgentRunnerService } from '../services/ai-agent-runner-service.js';
+import type { AIEmbeddingService } from '../services/ai-embedding-service.js';
 import type { AIRunStateService } from '../services/ai-run-state-service.js';
 import type { AgentRunService } from '../wirings/ai-agent/ai-agent.types.js';
 import type { PikkuAIMiddlewareHooks } from '../wirings/ai-agent/ai-agent.types.js';
 import type { WorkflowRunService } from '../wirings/workflow/workflow.types.js';
 import type { CredentialService } from '../services/credential-service.js';
 import type { EmailService } from '../services/email-service.js';
+import type { WebhookService, WebhookServiceConfig } from '../services/webhook-service.js';
 import type { MetaService } from '../services/meta-service.js';
 import type { CoverageService } from '../services/v8-coverage-service.js';
 import type { SessionStore } from '../services/session-store.js';
+import type { ScopeService } from '../services/scope-service.js';
 import type { AuditDurability, AuditLog, AuditService } from '../services/audit-service.js';
 export type PikkuWiringTypes = 'http' | 'scheduler' | 'trigger' | 'channel' | 'rpc' | 'queue' | 'mcp' | 'cli' | 'workflow' | 'agent' | 'gateway';
 export interface FunctionServicesMeta {
@@ -63,13 +66,13 @@ export type MiddlewareMetadata = {
  * - type: 'tag' = Tag-based permission group (references tagGroup in pikkuState)
  * - type: 'wire' = Wire-level individual permission
  */
+/**
+ * A reference to a permission function a function declares, resolved by name.
+ * Used at filter time (e.g. listing agent tools) to run the session-only
+ * (pikkuAuth) predicates without request data. Permissions are function-scoped
+ * only — there are no wire- or tag-level permission references.
+ */
 export type PermissionMetadata = {
-    type: 'http';
-    route: string;
-} | {
-    type: 'tag';
-    tag: string;
-} | {
     type: 'wire';
     name: string;
     inline?: boolean;
@@ -78,6 +81,8 @@ export type FunctionRuntimeMeta = {
     pikkuFuncId: string;
     inputSchemaName: string | null;
     outputSchemaName: string | null;
+    /** Scopes the session must hold to run this function. All are required (AND). */
+    scopes?: string[];
     expose?: boolean;
     remote?: boolean;
     mcp?: boolean;
@@ -184,6 +189,8 @@ export type CoreConfig<Config extends Record<string, unknown> = {}> = {
     /** Secrets used by the application (optional). */
     secrets?: {};
     workflow?: WorkflowServiceConfig;
+    /** Default retry and signing settings for outgoing webhooks. */
+    webhook?: WebhookServiceConfig;
     /** Runtime Postgres adapter options (pool sizing). */
     postgres?: PostgresConfig;
 } & Config;
@@ -195,6 +202,12 @@ export interface CoreUserSession {
     orgId?: string;
     /** True when the session belongs to a synthetic scenario actor — lets audits/analytics address synthetic traffic */
     actor?: boolean;
+    /**
+     * Scopes granted to this session, checked against a function's `scopes`.
+     * Populated by whoever builds the session (e.g. better-auth's `mapSession`
+     * resolving them via a ScopeService) — core reads them and never fetches.
+     */
+    scopes?: string[];
 }
 /**
  * Interface for core singleton services provided by Pikku.
@@ -228,6 +241,8 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
     content?: ContentService;
     /** AI agent runner service (model calls + tool loop) */
     aiAgentRunner?: AIAgentRunnerService;
+    /** Dedicated embedding service (vector stores use it at index & query time) */
+    aiEmbedding?: AIEmbeddingService;
     /** AI run state service (run lifecycle + approval persistence) */
     aiRunState?: AIRunStateService;
     /** Agent run service (listing threads, runs, steps) */
@@ -238,6 +253,12 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
     credentialService?: CredentialService;
     /** Email service for outbound messages and template-backed delivery */
     emailService?: EmailService;
+    /**
+     * Webhook service for outgoing webhook delivery via a queue. A store-backed
+     * implementation (e.g. `KyselyWebhookService`) additionally records delivery
+     * history; the queue-only default throws on the delivery-read methods.
+     */
+    webhookService?: WebhookService;
     /** Meta service for reading .pikku metadata files (filesystem on Node, R2/KV on CF) */
     metaService?: MetaService;
     /** V8 precise-coverage collector (`pikku dev --coverage` only) */
@@ -254,6 +275,11 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
     auditLog?: AuditLog;
     /** Session store for persisting user sessions keyed by pikkuUserId */
     sessionStore?: SessionStore;
+    /**
+     * Resolves and administers user scopes. Called when building a session (e.g.
+     * better-auth's `mapSession`), never by the function runner.
+     */
+    scopeService?: ScopeService;
 }
 /**
  * Represents different forms of wire within Pikku and the outside world.
@@ -268,6 +294,8 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
     traceId: string;
     /** Function id for the current invocation */
     functionId: string;
+    /** The addon instance namespace (wireAddon name) currently executing, if any */
+    addonNamespace: string;
     http: PikkuHTTP<In>;
     mcp: PikkuMCP<MCPTools>;
     channel: [IsChannel] extends [null] ? PikkuChannel<unknown, Out> : PikkuChannel<unknown, Out> | undefined;

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

@@ -35,6 +35,26 @@ export interface PikkuPackageState {
             rpcEndpoint?: string;
             auth?: boolean;
             tags?: string[];
+            /** Per-instance name-aliases: logical name the addon reads -> actual project secret name */
+            secretOverrides?: Record<string, string>;
+            /** Per-instance name-aliases: logical name the addon reads -> actual project variable name */
+            variableOverrides?: Record<string, string>;
+            /** Per-instance name-aliases: logical name the addon reads -> actual project credential name */
+            credentialOverrides?: Record<string, string>;
+            /** Set by `wireRemoteAddon`: this namespace is consumed remotely over HTTP, not bundled */
+            remote?: boolean;
+            /** Remote host base URL (wireRemoteAddon) — string or resolver over singleton services */
+            serverUrl?: string | ((services: any) => string | Promise<string>);
+            /** Consumer-side auth binding for the hosted addon (wireRemoteAddon) */
+            remoteAuth?: {
+                credentialId: string;
+            } | {
+                secretId: string;
+            } | {
+                resolve: (services: any, wire: any) => string | Promise<string>;
+            };
+            /** Map consumer-facing fn name → remote fn name (wireRemoteAddon) */
+            remoteName?: (fn: string) => string;
         }>;
     };
     http: {
@@ -94,8 +114,6 @@ export interface PikkuPackageState {
         tagGroup: Record<string, CorePikkuChannelMiddleware[]>;
     };
     permissions: {
-        tagGroup: Record<string, CorePermissionGroup | CorePikkuPermission[]>;
-        httpGroup: Record<string, CorePermissionGroup | CorePikkuPermission[]>;
         global: (CorePermissionGroup | CorePikkuPermission)[];
     };
     misc: {

package/dist/utils/hmac.d.ts

@@ -0,0 +1,16 @@
+/**
+ * HMAC-SHA256 a payload, hex-encoded.
+ *
+ * Senders wrap this in their own scheme prefix (`sha256=`, `v0=`, …).
+ *
+ * @param secret - The signing key shared with the other side
+ * @param payload - The exact bytes that were signed
+ */
+export declare function hmacSha256Hex(secret: string, payload: string): string;
+/**
+ * Compare two signatures without leaking their contents through timing.
+ *
+ * Returns false rather than throwing on a length mismatch, which is what
+ * `timingSafeEqual` does when the buffers differ in size.
+ */
+export declare function timingSafeStringEqual(a: string, b: string): boolean;

package/dist/utils/hmac.js

@@ -0,0 +1,26 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/**
+ * HMAC-SHA256 a payload, hex-encoded.
+ *
+ * Senders wrap this in their own scheme prefix (`sha256=`, `v0=`, …).
+ *
+ * @param secret - The signing key shared with the other side
+ * @param payload - The exact bytes that were signed
+ */
+export function hmacSha256Hex(secret, payload) {
+    return createHmac('sha256', secret).update(payload).digest('hex');
+}
+/**
+ * Compare two signatures without leaking their contents through timing.
+ *
+ * Returns false rather than throwing on a length mismatch, which is what
+ * `timingSafeEqual` does when the buffers differ in size.
+ */
+export function timingSafeStringEqual(a, b) {
+    try {
+        return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utils/safe-fetch.d.ts

@@ -0,0 +1,51 @@
+/**
+ * SSRF-aware fetch helpers.
+ *
+ * `@pikku/core` runs in edge runtimes (Cloudflare Workers) with no Node `dns`,
+ * so we cannot resolve hostnames to check for private targets. We reject the
+ * obvious internal literals and, crucially, re-validate every redirect hop —
+ * a public URL that 302s to `169.254.169.254` is the common bypass. This does
+ * NOT defend against a public hostname that itself resolves to a private IP
+ * (DNS rebinding), which is out of reach without DNS resolution.
+ */
+/**
+ * Whether a hostname is an obvious internal/private target (loopback, private
+ * IPv4 ranges, link-local incl. the cloud metadata endpoint, or private IPv6).
+ *
+ * Alias/encoded forms that resolve to the same targets are also rejected: a
+ * trailing-dot FQDN (`localhost.`), the `*.localhost` reserved name, IPv4-mapped
+ * IPv6 (`::ffff:127.0.0.1`), and octal/decimal/hex-encoded IPv4. This is
+ * best-effort literal matching only — it cannot catch a public hostname that
+ * *resolves* to a private IP (DNS rebinding), which needs DNS resolution
+ * unavailable in edge runtimes.
+ */
+export declare function isPrivateHost(hostname: string): boolean;
+export interface SafeFetchOptions {
+    /**
+     * When set, the host of every hop must appear in this allowlist. When omitted,
+     * any host that is not {@link isPrivateHost} is permitted.
+     */
+    allowedHosts?: string[];
+    /** Maximum redirect hops to follow (each re-validated). Defaults to 3. */
+    maxRedirects?: number;
+}
+/**
+ * Parse and validate a URL for outbound fetching: only http(s), and — unless an
+ * `allowedHosts` allowlist is supplied — not an obvious private/internal host.
+ * Returns the parsed URL or throws.
+ */
+export declare function assertFetchableUrl(url: string, options?: SafeFetchOptions): URL;
+/**
+ * `fetch` with SSRF protection. The initial URL and every redirect target are
+ * validated with {@link assertFetchableUrl}. Redirects are followed manually
+ * (`redirect: 'manual'`) so an unsafe `Location` can never be followed into the
+ * internal network; only the redirect statuses in {@link REDIRECT_STATUSES} are
+ * followed, and the method/body are transformed per {@link redirectInit}. Each
+ * intermediate redirect response body is cancelled before the next hop so it is
+ * not left dangling. When a redirect cannot or should not be followed (no
+ * `Location`, or the hop budget is exhausted) the raw redirect response is
+ * returned for the caller to handle by status. Credential headers
+ * (`Authorization`, `Cookie`) are stripped whenever a redirect crosses origin,
+ * so they never leak to a redirected host.
+ */
+export declare function safeFetch(url: string, init?: RequestInit, options?: SafeFetchOptions): Promise<Response>;

package/dist/utils/safe-fetch.js

@@ -0,0 +1,192 @@
+/**
+ * SSRF-aware fetch helpers.
+ *
+ * `@pikku/core` runs in edge runtimes (Cloudflare Workers) with no Node `dns`,
+ * so we cannot resolve hostnames to check for private targets. We reject the
+ * obvious internal literals and, crucially, re-validate every redirect hop —
+ * a public URL that 302s to `169.254.169.254` is the common bypass. This does
+ * NOT defend against a public hostname that itself resolves to a private IP
+ * (DNS rebinding), which is out of reach without DNS resolution.
+ */
+/**
+ * Parse the many textual encodings of an IPv4 address that `fetch`/`undici`
+ * (and `inet_aton`-style parsers) accept — a dotted quad whose octets may be
+ * decimal, octal (`0177`) or hex (`0x7f`), or the whole address as a single
+ * 32-bit integer (decimal `2130706433`, hex `0x7f000001`). Returns the four
+ * octets, or `null` when the host is not a numeric IPv4 literal.
+ */
+function parseIPv4Octets(host) {
+    const toInt = (part) => {
+        let n;
+        if (/^0x[0-9a-f]+$/.test(part))
+            n = parseInt(part, 16);
+        else if (/^0[0-7]+$/.test(part))
+            n = parseInt(part, 8);
+        else if (/^\d+$/.test(part))
+            n = parseInt(part, 10);
+        else
+            return null;
+        return Number.isInteger(n) ? n : null;
+    };
+    if (!host.includes('.')) {
+        const n = toInt(host);
+        if (n === null || n < 0 || n > 0xffffffff)
+            return null;
+        return [(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff];
+    }
+    const parts = host.split('.');
+    if (parts.length !== 4)
+        return null;
+    const octets = [];
+    for (const part of parts) {
+        const n = toInt(part);
+        if (n === null || n < 0 || n > 0xff)
+            return null;
+        octets.push(n);
+    }
+    return octets;
+}
+/**
+ * Whether a hostname is an obvious internal/private target (loopback, private
+ * IPv4 ranges, link-local incl. the cloud metadata endpoint, or private IPv6).
+ *
+ * Alias/encoded forms that resolve to the same targets are also rejected: a
+ * trailing-dot FQDN (`localhost.`), the `*.localhost` reserved name, IPv4-mapped
+ * IPv6 (`::ffff:127.0.0.1`), and octal/decimal/hex-encoded IPv4. This is
+ * best-effort literal matching only — it cannot catch a public hostname that
+ * *resolves* to a private IP (DNS rebinding), which needs DNS resolution
+ * unavailable in edge runtimes.
+ */
+export function isPrivateHost(hostname) {
+    const host = hostname
+        .replace(/^\[|\]$/g, '')
+        .replace(/\.$/, '')
+        .toLowerCase();
+    if (host === '' || host === 'localhost' || host.endsWith('.localhost'))
+        return true;
+    if (host.includes(':')) {
+        if (host === '::' || host === '::1')
+            return true;
+        const mappedV4 = host.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+        if (mappedV4)
+            return isPrivateHost(mappedV4[1]);
+        const mappedHex = host.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+        if (mappedHex) {
+            const hi = parseInt(mappedHex[1], 16);
+            const lo = parseInt(mappedHex[2], 16);
+            return isPrivateHost(`${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`);
+        }
+        if (/^fe[89ab]/.test(host))
+            return true; // link-local fe80::/10
+        if (host.startsWith('fc') || host.startsWith('fd'))
+            return true; // unique-local fc00::/7
+        return false;
+    }
+    const v4 = parseIPv4Octets(host);
+    if (v4) {
+        const [a, b] = v4;
+        if (a === 127 || a === 10 || a === 0)
+            return true;
+        if (a === 169 && b === 254)
+            return true; // link-local incl. cloud metadata
+        if (a === 172 && b >= 16 && b <= 31)
+            return true;
+        if (a === 192 && b === 168)
+            return true;
+    }
+    return false;
+}
+/**
+ * Parse and validate a URL for outbound fetching: only http(s), and — unless an
+ * `allowedHosts` allowlist is supplied — not an obvious private/internal host.
+ * Returns the parsed URL or throws.
+ */
+export function assertFetchableUrl(url, options = {}) {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        throw new Error(`Refusing to fetch non-HTTP(S) URL: ${parsed.protocol}`);
+    }
+    if (options.allowedHosts) {
+        if (!options.allowedHosts.includes(parsed.hostname)) {
+            throw new Error(`URL host is not in the allowlist: ${parsed.hostname}`);
+        }
+    }
+    else if (isPrivateHost(parsed.hostname)) {
+        throw new Error(`Refusing to fetch from a private/internal host: ${parsed.hostname}`);
+    }
+    return parsed;
+}
+/**
+ * The only 3xx statuses that request a redirect be followed. `300` (Multiple
+ * Choices), `304` (Not Modified), `305` (Use Proxy) and `306` are returned to
+ * the caller as-is rather than followed.
+ */
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/**
+ * Drop credential-bearing headers (`Authorization`, `Cookie`) so they are not
+ * replayed to a different origin across a redirect.
+ */
+function stripCredentialHeaders(init) {
+    if (!init.headers)
+        return init;
+    const headers = new Headers(init.headers);
+    headers.delete('authorization');
+    headers.delete('cookie');
+    return { ...init, headers };
+}
+/**
+ * Apply the WHATWG-fetch method/body transform for a redirect: a `303` (and a
+ * `301`/`302` on a `POST`) becomes a bodyless `GET`; `307`/`308` preserve the
+ * original method and body. When the method changes to `GET` the request body
+ * and its `Content-*` headers are dropped.
+ */
+function redirectInit(status, init) {
+    const method = (init.method ?? 'GET').toUpperCase();
+    const toGet = (status === 303 && method !== 'GET' && method !== 'HEAD') ||
+        ((status === 301 || status === 302) && method === 'POST');
+    if (!toGet)
+        return init;
+    const headers = new Headers(init.headers);
+    headers.delete('content-length');
+    headers.delete('content-type');
+    return { ...init, method: 'GET', body: undefined, headers };
+}
+/**
+ * `fetch` with SSRF protection. The initial URL and every redirect target are
+ * validated with {@link assertFetchableUrl}. Redirects are followed manually
+ * (`redirect: 'manual'`) so an unsafe `Location` can never be followed into the
+ * internal network; only the redirect statuses in {@link REDIRECT_STATUSES} are
+ * followed, and the method/body are transformed per {@link redirectInit}. Each
+ * intermediate redirect response body is cancelled before the next hop so it is
+ * not left dangling. When a redirect cannot or should not be followed (no
+ * `Location`, or the hop budget is exhausted) the raw redirect response is
+ * returned for the caller to handle by status. Credential headers
+ * (`Authorization`, `Cookie`) are stripped whenever a redirect crosses origin,
+ * so they never leak to a redirected host.
+ */
+export async function safeFetch(url, init = {}, options = {}) {
+    const maxRedirects = options.maxRedirects ?? 3;
+    let currentUrl = assertFetchableUrl(url, options).toString();
+    let currentInit = init;
+    for (let hop = 0;; hop++) {
+        const response = await fetch(currentUrl, {
+            ...currentInit,
+            redirect: 'manual',
+        });
+        if (!REDIRECT_STATUSES.has(response.status)) {
+            return response;
+        }
+        const location = response.headers.get('location');
+        if (!location || hop >= maxRedirects) {
+            return response;
+        }
+        const nextUrl = assertFetchableUrl(new URL(location, currentUrl).toString(), options).toString();
+        await response.body?.cancel();
+        let nextInit = redirectInit(response.status, currentInit);
+        if (new URL(nextUrl).origin !== new URL(currentUrl).origin) {
+            nextInit = stripCredentialHeaders(nextInit);
+        }
+        currentInit = nextInit;
+        currentUrl = nextUrl;
+    }
+}

package/dist/wirings/ai-agent/ai-agent-agui.d.ts

@@ -0,0 +1,84 @@
+import type { AIStreamChannel } from './ai-agent.types.js';
+type AGUIEvent = {
+    type: 'TEXT_MESSAGE_START';
+    messageId: string;
+} | {
+    type: 'TEXT_MESSAGE_CONTENT';
+    messageId: string;
+    delta: string;
+} | {
+    type: 'TEXT_MESSAGE_END';
+    messageId: string;
+} | {
+    type: 'TOOL_CALL_START';
+    toolCallId: string;
+    toolCallName: string;
+} | {
+    type: 'TOOL_CALL_ARGS';
+    toolCallId: string;
+    delta: string;
+} | {
+    type: 'TOOL_CALL_END';
+    toolCallId: string;
+    toolCallName: string;
+} | {
+    type: 'TOOL_CALL_RESULT';
+    messageId: string;
+    toolCallId: string;
+    role: 'tool';
+    content: string;
+} | {
+    type: 'THINKING_START';
+} | {
+    type: 'THINKING_TEXT_MESSAGE_START';
+    messageId: string;
+} | {
+    type: 'THINKING_TEXT_MESSAGE_CONTENT';
+    messageId: string;
+    delta: string;
+} | {
+    type: 'THINKING_TEXT_MESSAGE_END';
+    messageId: string;
+} | {
+    type: 'THINKING_END';
+} | {
+    type: 'RUN_STARTED';
+    threadId: string;
+    runId: string;
+} | {
+    type: 'RUN_FINISHED';
+    threadId: string;
+    runId: string;
+    model?: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+} | {
+    type: 'RUN_ERROR';
+    message: string;
+    code?: string;
+} | {
+    type: 'STEP_STARTED';
+    stepName: string;
+} | {
+    type: 'STEP_FINISHED';
+    stepName: string;
+} | {
+    type: 'CUSTOM';
+    name: string;
+    value: unknown;
+};
+export type { AGUIEvent };
+export type AGUIChannelOptions = {
+    threadId?: string;
+    runId?: string;
+    /**
+     * Late-bound runId source, resolved when the run is opened (first event).
+     * Lets the stream path report the AIRunStateService runId on RUN_STARTED
+     * even though that id is only created after the channel is wrapped.
+     */
+    getRunId?: () => string | undefined;
+};
+export declare function wrapChannelWithAGUI(inner: AIStreamChannel, options?: AGUIChannelOptions): AIStreamChannel;