@pikku/core 0.12.62 → 0.12.64

package/src/services/typed-secret-service.ts

@@ -17,6 +17,15 @@ export type CredentialMeta = {
 export class TypedSecretService<
   TMap = Record<string, unknown>,
 > implements SecretService {
+  /**
+   * In-process cache of resolved secrets, so callers can read naively without
+   * re-hitting the underlying service on every call. Only successful reads are
+   * cached (a miss throws and isn't stored); `setSecret`/`deleteSecret`
+   * invalidate the key. No TTL — a secret rotated out-of-band won't refresh
+   * until restart (see pikkujs/pikku#964).
+   */
+  private cache = new Map<string, unknown>()
+
   constructor(
     private secrets: SecretService,
     private credentialsMeta: Record<string, CredentialMeta>
@@ -25,10 +34,18 @@ export class TypedSecretService<
   async getSecret<K extends keyof TMap & string>(key: K): Promise<TMap[K]>
   async getSecret<T = string>(key: string): Promise<T>
   async getSecret(key: string): Promise<unknown> {
-    return this.secrets.getSecret(key)
+    if (this.cache.has(key)) {
+      return this.cache.get(key)
+    }
+    const value = await this.secrets.getSecret(key)
+    this.cache.set(key, value)
+    return value
   }
 
   async hasSecret(key: string): Promise<boolean> {
+    if (this.cache.has(key)) {
+      return true
+    }
     return this.secrets.hasSecret(key)
   }
 
@@ -36,17 +53,35 @@ export class TypedSecretService<
     key: K,
     value: K extends keyof TMap ? TMap[K] : unknown
   ): Promise<void> {
-    return this.secrets.setSecret(key, value)
+    await this.secrets.setSecret(key, value)
+    this.cache.delete(key)
   }
 
   async deleteSecret(key: string): Promise<void> {
-    return this.secrets.deleteSecret(key)
+    await this.secrets.deleteSecret(key)
+    this.cache.delete(key)
   }
 
   async getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(
     keys: (keyof T & string)[]
   ): Promise<Partial<T>> {
-    return this.secrets.getSecrets<T>(keys)
+    const result: Partial<T> = {}
+    const missing: (keyof T & string)[] = []
+    for (const key of keys) {
+      if (this.cache.has(key)) {
+        result[key] = this.cache.get(key) as T[keyof T & string]
+      } else {
+        missing.push(key)
+      }
+    }
+    if (missing.length > 0) {
+      const fetched = await this.secrets.getSecrets<T>(missing)
+      for (const [key, value] of Object.entries(fetched)) {
+        this.cache.set(key, value)
+        result[key as keyof T & string] = value as T[keyof T & string]
+      }
+    }
+    return result
   }
 
   async getAllStatus(): Promise<CredentialStatus[]> {

package/src/services/webhook-service.ts

@@ -0,0 +1,180 @@
+import { NotImplementedError } from '../errors/errors.js'
+import { hmacSha256Hex, timingSafeStringEqual } from '../utils/hmac.js'
+
+export interface SendWebhookInput {
+  /** The endpoint the webhook is delivered to via HTTP POST. */
+  url: string
+  /** Optional event name, sent as the `X-Pikku-Event` header. */
+  event?: string
+  /** The payload, JSON-serialized into the request body. */
+  data: unknown
+  /** Extra headers merged over the defaults. */
+  headers?: Record<string, string>
+  /**
+   * Raw HMAC signing key for this delivery. Overrides the config-level
+   * secret. When present, the body is signed into the signature header.
+   */
+  secret?: string
+  /** Retry count for failed deliveries. Overrides `config.webhook.retries`. */
+  retries?: number
+  /**
+   * Delay between retries (`30000` or `'30s'`). A concrete value selects a
+   * fixed backoff; when omitted, backoff is exponential.
+   */
+  retryDelay?: string | number
+  /**
+   * Organization this delivery belongs to. Persisted by a store-backed
+   * implementation (e.g. `KyselyWebhookService`) so deliveries can be
+   * queried per org; ignored by the queue-only default.
+   */
+  organizationId?: string
+}
+
+export interface SendWebhookResult {
+  jobId: string
+}
+
+export interface WebhookServiceConfig {
+  /** Default retry count for failed deliveries. */
+  retries?: number
+  /** Default delay between retries; omitted means exponential backoff. */
+  retryDelay?: string | number
+  /**
+   * Name of a secret (resolved through the secret service) used as the
+   * default HMAC signing key for all outgoing webhooks.
+   */
+  secret?: string
+  /**
+   * Header the body signature is sent in. Defaults to
+   * {@link DEFAULT_WEBHOOK_SIGNATURE_HEADER}.
+   */
+  signatureHeader?: string
+  /**
+   * SSRF allowlist of hostnames outgoing webhooks may be delivered to. When set,
+   * a delivery target must be on this list. When omitted, obvious private and
+   * internal hosts (loopback, private ranges, cloud metadata) are blocked and
+   * all other public hosts are permitted.
+   */
+  allowedHosts?: string[]
+}
+
+export interface WebhookJobData {
+  url: string
+  event?: string
+  body: string
+  headers: Record<string, string>
+  /**
+   * Delivery-record id, present when a store-backed implementation enqueued
+   * the job. The worker keys its per-attempt records off this (it doubles as
+   * the queue `jobId`), so it's stable across retries.
+   */
+  deliveryId?: string
+}
+
+/** Outcome of one delivery attempt, recorded against a delivery. */
+export interface WebhookAttemptResult {
+  /** HTTP status of the response, absent if the request never completed. */
+  statusCode?: number
+  /** Response body (truncated) — captured on failure for debugging. */
+  responseBody?: string
+  /** Network/timeout error message, when the request threw. */
+  error?: string
+  /** Whether this attempt was a 2xx success. */
+  delivered: boolean
+}
+
+/** A persisted webhook delivery, as surfaced to the console. */
+export interface WebhookDeliveryRecord {
+  deliveryId: string
+  organizationId: string | null
+  url: string
+  event: string | null
+  status: 'pending' | 'delivered' | 'failed'
+  attempts: number
+  createdAt: Date
+  updatedAt: Date
+  deliveredAt: Date | null
+}
+
+/** A single persisted delivery attempt. */
+export interface WebhookAttemptRecord {
+  attemptId: string
+  deliveryId: string
+  attemptNumber: number
+  statusCode: number | null
+  responseBody: string | null
+  error: string | null
+  createdAt: Date
+}
+
+/** A delivery with its full attempt history. */
+export interface WebhookDeliveryWithAttempts {
+  delivery: WebhookDeliveryRecord
+  attempts: WebhookAttemptRecord[]
+}
+
+export const PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME = 'pikku-outgoing-webhooks'
+
+export const DEFAULT_WEBHOOK_SIGNATURE_HEADER = 'X-Pikku-Signature'
+
+/** Fallback when neither the per-call nor `config.webhook.retries` is set. */
+export const DEFAULT_WEBHOOK_RETRIES = 3
+
+/**
+ * Outgoing webhook delivery. {@link QueueWebhookService} is the default
+ * implementation; apps can extend this to deliver directly, or through a
+ * provider such as Svix.
+ */
+export abstract class WebhookService {
+  abstract send(input: SendWebhookInput): Promise<SendWebhookResult>
+
+  /**
+   * Sign a body with HMAC-SHA256, producing the signature header value
+   * (e.g. `sha256=abc123...`).
+   */
+  protected sign(secret: string, body: string): string {
+    return `sha256=${hmacSha256Hex(secret, body)}`
+  }
+
+  /**
+   * Verify a signature produced by {@link WebhookService.sign} — for
+   * receivers, which share the signing scheme.
+   */
+  public verify(secret: string, signature: string, body: string): boolean {
+    return timingSafeStringEqual(this.sign(secret, body), signature)
+  }
+
+  /**
+   * Record a delivery attempt and roll the delivery's status/attempt-count
+   * forward, keyed by the delivery id carried in {@link WebhookJobData}. The
+   * default queue-only service keeps no history, so this throws — a store-backed
+   * implementation (e.g. `KyselyWebhookService` in `@pikku/kysely`) overrides it.
+   */
+  public recordAttempt(
+    _deliveryId: string,
+    _result: WebhookAttemptResult
+  ): Promise<void> {
+    throw new NotImplementedError(
+      'webhook delivery persistence is not configured'
+    )
+  }
+
+  /** List deliveries, most recent first, optionally scoped to an org. */
+  public listDeliveries(_opts?: {
+    organizationId?: string
+    limit?: number
+  }): Promise<WebhookDeliveryRecord[]> {
+    throw new NotImplementedError(
+      'webhook delivery persistence is not configured'
+    )
+  }
+
+  /** A single delivery with its attempt history, or null if unknown. */
+  public getDelivery(
+    _deliveryId: string
+  ): Promise<WebhookDeliveryWithAttempts | null> {
+    throw new NotImplementedError(
+      'webhook delivery persistence is not configured'
+    )
+  }
+}

package/src/services/workflow-service.ts

@@ -50,6 +50,13 @@ export interface WorkflowService {
 
   // Orchestration operations
   resumeWorkflow(runId: string): Promise<void>
+  /**
+   * Record a human decision against a `workflow.approval()` gate and wake the
+   * run. The payload is stored as given and validated on replay, inside the
+   * workflow body — so an invalid one re-closes the gate rather than failing the
+   * run. `reason` addresses the gate's first reach.
+   */
+  approveStep(runId: string, reason: string, decision: unknown): Promise<void>
   startWorkflow<I>(
     name: string,
     input: I,

package/src/types/core.types.ts

@@ -32,15 +32,21 @@ 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,
@@ -97,25 +103,24 @@ export type MiddlewareMetadata =
  * - type: 'tag' = Tag-based permission group (references tagGroup in pikkuState)
  * - type: 'wire' = Wire-level individual permission
  */
-export type PermissionMetadata =
-  | {
-      type: 'http'
-      route: string // Route pattern (e.g., '*' for all, '/api/*' for specific)
-    }
-  | {
-      type: 'tag'
-      tag: string // Tag name
-    }
-  | {
-      type: 'wire'
-      name: string
-      inline?: boolean // true if inline 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: 'wire'
+  name: string
+  inline?: boolean // true if inline permission
+}
 
 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
@@ -242,6 +247,8 @@ export type CoreConfig<Config extends Record<string, unknown> = {}> = {
   secrets?: {}
 
   workflow?: WorkflowServiceConfig
+  /** Default retry and signing settings for outgoing webhooks. */
+  webhook?: WebhookServiceConfig
   /** Runtime Postgres adapter options (pool sizing). */
   postgres?: PostgresConfig
 } & Config
@@ -254,6 +261,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[]
 }
 
 /**
@@ -289,6 +302,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) */
@@ -299,6 +314,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) */
@@ -315,6 +336,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
 }
 
 /**
@@ -341,6 +367,8 @@ export type PikkuWire<
   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]

package/src/types/state.types.ts

@@ -84,7 +84,29 @@ export interface PikkuPackageState {
   addons: {
     packages: Map<
       string,
-      { package: string; rpcEndpoint?: string; auth?: boolean; tags?: string[] }
+      {
+        package: string
+        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: {
@@ -144,8 +166,6 @@ export interface PikkuPackageState {
     tagGroup: Record<string, CorePikkuChannelMiddleware[]>
   }
   permissions: {
-    tagGroup: Record<string, CorePermissionGroup | CorePikkuPermission[]>
-    httpGroup: Record<string, CorePermissionGroup | CorePikkuPermission[]>
     global: (CorePermissionGroup | CorePikkuPermission)[]
   }
   misc: {

package/src/utils/hmac.ts

@@ -0,0 +1,27 @@
+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: string, payload: string): string {
+  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: string, b: string): boolean {
+  try {
+    return timingSafeEqual(Buffer.from(a), Buffer.from(b))
+  } catch {
+    return false
+  }
+}