@pikku/core 0.12.62 → 0.12.64

package/src/scopes.test.ts

@@ -0,0 +1,167 @@
+import { describe, test } from 'node:test'
+import * as assert from 'node:assert'
+import { verifyScopes } from './scopes.js'
+import { MissingScopeError } from './errors/errors.js'
+import type { CoreUserSession } from './types/core.types.js'
+
+const session = (scopes?: string[]): CoreUserSession =>
+  ({ userId: 'test-user', scopes }) as CoreUserSession
+
+describe('verifyScopes', () => {
+  test('passes on an exact match', () => {
+    verifyScopes(['invoices:create'], session(['invoices:create']))
+  })
+
+  test('passes when no scopes are required', () => {
+    verifyScopes([], session())
+  })
+
+  test('throws when the session holds none', () => {
+    assert.throws(
+      () => verifyScopes(['invoices:create'], session([])),
+      MissingScopeError
+    )
+  })
+
+  test('holding an unrelated scope does not grant', () => {
+    assert.throws(
+      () => verifyScopes(['invoices:create'], session(['billing:read'])),
+      MissingScopeError
+    )
+  })
+
+  describe('wildcards', () => {
+    test('admin:* satisfies a descendant', () => {
+      verifyScopes(['admin:invoices:create'], session(['admin:*']))
+    })
+
+    test('admin:* satisfies an intermediate descendant', () => {
+      verifyScopes(['admin:invoices'], session(['admin:*']))
+    })
+
+    test('admin:* satisfies the parent itself', () => {
+      verifyScopes(['admin'], session(['admin:*']))
+    })
+
+    test('a bare * satisfies anything', () => {
+      verifyScopes(['admin:invoices:create'], session(['*']))
+    })
+
+    test('a deep wildcard satisfies its own descendants', () => {
+      verifyScopes(['admin:invoices:create'], session(['admin:invoices:*']))
+    })
+
+    test('does not leak across siblings', () => {
+      assert.throws(
+        () => verifyScopes(['billing:read'], session(['admin:*'])),
+        MissingScopeError
+      )
+    })
+
+    test('a required wildcard is not satisfied by one narrow grant', () => {
+      assert.throws(
+        () => verifyScopes(['admin:*'], session(['admin:invoices:create'])),
+        MissingScopeError
+      )
+    })
+
+    test('a required wildcard is satisfied by a broader grant', () => {
+      verifyScopes(['admin:*'], session(['*']))
+    })
+  })
+
+  describe('a plain parent grant covers its descendants', () => {
+    test('holding a parent satisfies a deep descendant', () => {
+      verifyScopes(['admin:invoices:create'], session(['admin']))
+    })
+
+    test('holding a parent satisfies an intermediate descendant', () => {
+      verifyScopes(['admin:invoices'], session(['admin']))
+    })
+
+    test('holding an intermediate parent satisfies its child', () => {
+      verifyScopes(['admin:invoices:create'], session(['admin:invoices']))
+    })
+
+    test('a parent does not leak across siblings', () => {
+      assert.throws(
+        () => verifyScopes(['billing:read'], session(['admin'])),
+        MissingScopeError
+      )
+    })
+  })
+
+  describe('AND semantics', () => {
+    test('passes only when every required scope is held', () => {
+      verifyScopes(
+        ['invoices:read', 'invoices:write'],
+        session(['invoices:read', 'invoices:write'])
+      )
+    })
+
+    test('throws when only one of two is held', () => {
+      assert.throws(
+        () =>
+          verifyScopes(
+            ['invoices:read', 'invoices:write'],
+            session(['invoices:read'])
+          ),
+        MissingScopeError
+      )
+    })
+
+    test('one wildcard can satisfy several requirements', () => {
+      verifyScopes(['admin:read', 'admin:write'], session(['admin:*']))
+    })
+  })
+
+  describe('fails closed', () => {
+    test('throws when the session has no scopes field', () => {
+      assert.throws(
+        () => verifyScopes(['invoices:create'], session(undefined)),
+        MissingScopeError
+      )
+    })
+
+    test('throws when there is no session at all', () => {
+      assert.throws(
+        () => verifyScopes(['invoices:create'], undefined),
+        MissingScopeError
+      )
+    })
+
+    test('a narrower grant does not satisfy a broader requirement', () => {
+      assert.throws(
+        () => verifyScopes(['admin'], session(['admin:invoices'])),
+        MissingScopeError
+      )
+    })
+  })
+
+  describe('a parent grant coexists with a child grant', () => {
+    test('the parent still grants when a child is also held', () => {
+      verifyScopes(
+        ['admin:invoices'],
+        session(['admin:invoices', 'admin:invoices:create'])
+      )
+    })
+
+    test('the child still grants when a parent is also held', () => {
+      verifyScopes(
+        ['admin:invoices:create'],
+        session(['admin:invoices', 'admin:invoices:create'])
+      )
+    })
+  })
+
+  test('names the missing scope', () => {
+    assert.throws(
+      () => verifyScopes(['a:b', 'c:d'], session(['a:b'])),
+      (err: MissingScopeError) => {
+        assert.equal(err.payload.scope, 'c:d')
+        assert.match(err.message, /c:d/)
+        return true
+      }
+    )
+  })
+})

package/src/scopes.ts

@@ -0,0 +1,69 @@
+import type { CoreUserSession } from './types/core.types.js'
+import { MissingScopeError } from './errors/errors.js'
+
+const SEPARATOR = ':'
+const WILDCARD = '*'
+
+/**
+ * Builds every grant that would satisfy `scope`: the scope itself, a wildcard
+ * directly beneath it, a wildcard at each ancestor level, and each plain
+ * ancestor id — holding a parent scope grants everything nested beneath it.
+ *
+ * For `admin:invoices:create` that is:
+ *   admin:invoices:create, admin:invoices:create:*, *, admin:*, admin:invoices:*,
+ *   admin, admin:invoices
+ */
+const satisfyingGrants = (scope: string): string[] => {
+  const segments = scope.split(SEPARATOR)
+  const grants = [scope, `${scope}${SEPARATOR}${WILDCARD}`]
+  for (let i = 0; i < segments.length; i++) {
+    grants.push([...segments.slice(0, i), WILDCARD].join(SEPARATOR))
+  }
+  for (let i = 1; i < segments.length; i++) {
+    grants.push(segments.slice(0, i).join(SEPARATOR))
+  }
+  return grants
+}
+
+/**
+ * Checks whether `held` satisfies a single required scope.
+ *
+ * A grant satisfies a requirement when it is the scope itself, a plain ancestor
+ * (`admin` covers `admin:invoices:create`), a wildcard at or above it (`admin:*`
+ * covers `admin` and `admin:invoices:create`), or the bare `*`. A narrower grant
+ * never satisfies a broader requirement — `admin:invoices` does not grant
+ * `admin`.
+ */
+const holds = (held: ReadonlySet<string>, scope: string): boolean =>
+  satisfyingGrants(scope).some((grant) => held.has(grant))
+
+/**
+ * Verifies that a session holds every required scope, throwing on the first
+ * one it does not.
+ *
+ * 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: a session without a `scopes` field, or no session at all,
+ * satisfies nothing.
+ *
+ * @param required - Scopes the function declares. Empty means no gate.
+ * @param session - The session to check. May be undefined.
+ * @throws {MissingScopeError} Naming the first unsatisfied scope.
+ */
+export const verifyScopes = (
+  required: readonly string[] | undefined,
+  session: CoreUserSession | undefined
+): void => {
+  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)
+    }
+  }
+}

package/src/services/ai-embedding-service.ts

@@ -0,0 +1,31 @@
+/**
+ * A narrow, dedicated embedding service.
+ *
+ * Vector stores (Qdrant, Pinecone, Supabase/pgvector, …) depend on this to turn
+ * text into vectors, at BOTH index time (ingest) and query time (search). The
+ * embedding model is fixed at construction so those two moments cannot drift
+ * into different vector spaces — a mismatch would silently break similarity
+ * search. Provider addons (e.g. `@pikku/addon-openai`) implement it; the app
+ * wires a single instance into `singletonServices.aiEmbedding`.
+ *
+ * This is deliberately smaller than {@link AIAgentRunnerService} (whose optional
+ * `embed`/`embedMany` take a per-call model): a vector store should not have to
+ * pull in the whole agent-runner tool loop just to embed, and pinning the model
+ * to the service is what guarantees index/query consistency.
+ *
+ * Documents (ingested corpus) and queries (search text) are embedded through
+ * separate methods because some models are asymmetric — Cohere's `input_type`,
+ * E5's `query:`/`passage:` prefixes, BGE's query instruction — and must know
+ * which side they are embedding to produce comparable vectors. Symmetric
+ * providers (e.g. OpenAI) point both methods at the same call.
+ */
+export interface AIEmbeddingService {
+  /** The embedding model backing this service. Index and query share it. */
+  readonly model: string
+  /** The vector dimensionality this model produces, when known. */
+  readonly dimensions?: number
+  /** Embed corpus documents (index time), preserving input order. */
+  embedDocuments(values: string[]): Promise<number[][]>
+  /** Embed a search query (query time) into a vector. */
+  embedQuery(value: string): Promise<number[]>
+}

package/src/services/credential-wire-service.ts

@@ -9,16 +9,22 @@ export class PikkuCredentialWireService {
 
   constructor(
     private credentialService?: CredentialService,
-    private wire?: PikkuRawWire
+    private wire?: PikkuRawWire,
+    private aliases?: Record<string, string>
   ) {}
 
+  private resolveName(name: string): string {
+    return this.aliases?.[name] ?? name
+  }
+
   set(name: string, value: unknown): void {
-    this.credentials[name] = value
+    this.credentials[this.resolveName(name)] = value
   }
 
   get<T = unknown>(name: string): T | null | Promise<T | null> {
-    if (this.loaded) return (this.credentials[name] as T) ?? null
-    return this.lazyLoad().then(() => (this.credentials[name] as T) ?? null)
+    const key = this.resolveName(name)
+    if (this.loaded) return (this.credentials[key] as T) ?? null
+    return this.lazyLoad().then(() => (this.credentials[key] as T) ?? null)
   }
 
   getAll(): Record<string, unknown> | Promise<Record<string, unknown>> {

package/src/services/index.ts

@@ -22,6 +22,10 @@ export { LocalCredentialService } from './local-credential-service.js'
 export { LocalVariablesService } from './local-variables.js'
 export { ConsoleLogger, JsonConsoleLogger } from './logger-console.js'
 export { InMemoryWorkflowService } from './in-memory-workflow-service.js'
+export {
+  QueueWebhookService,
+  pikkuWebhookWorkerFunc,
+} from './queue-webhook-service.js'
 export { InMemoryQueueService } from './in-memory-queue-service.js'
 export { InMemoryTriggerService } from './in-memory-trigger-service.js'
 export { InMemoryAIRunStateService } from './in-memory-ai-run-state-service.js'
@@ -56,6 +60,20 @@ export type {
   SendTemplateEmailInput,
   SendTextEmailInput,
 } from './email-service.js'
+export {
+  DEFAULT_WEBHOOK_RETRIES,
+  DEFAULT_WEBHOOK_SIGNATURE_HEADER,
+  PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME,
+  WebhookService,
+  type SendWebhookInput,
+  type SendWebhookResult,
+  type WebhookAttemptRecord,
+  type WebhookAttemptResult,
+  type WebhookDeliveryRecord,
+  type WebhookDeliveryWithAttempts,
+  type WebhookJobData,
+  type WebhookServiceConfig,
+} from './webhook-service.js'
 export type { Logger } from './logger.js'
 export type { SecretService } from './secret-service.js'
 export type { VariablesService } from './variables-service.js'
@@ -95,6 +113,7 @@ export type {
   AITranscriptionResult,
   AIAgentRunnerService,
 } from './ai-agent-runner-service.js'
+export type { AIEmbeddingService } from './ai-embedding-service.js'
 export type {
   CreateRunInput,
   AIRunStateService,
@@ -112,6 +131,7 @@ export type {
 export type { VariableStatus, VariableMeta } from './typed-variables-service.js'
 export type { MetaService } from './meta-service.js'
 export type { SessionStore } from './session-store.js'
+export type { ScopeService, Role } from './scope-service.js'
 export {
   NoopAuditService,
   createInvocationAudit,

package/src/services/meta-service.ts

@@ -1,4 +1,6 @@
 import { readFile, readdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
 import { join } from 'node:path'
 import type { JSONSchema7 } from 'json-schema'
 import type { HTTPWiringsMeta } from '../wirings/http/http.types.js'
@@ -107,8 +109,6 @@ export interface PermissionDefinitionMeta {
 
 export interface PermissionsGroupsMeta {
   definitions: Record<string, PermissionDefinitionMeta>
-  httpGroups: Record<string, GroupMeta>
-  tagGroups: Record<string, GroupMeta>
 }
 
 export interface EmailTemplateLocaleMeta {
@@ -159,6 +159,20 @@ export interface MetaService {
   readDir(relativePath: string): Promise<string[]>
   /** Read a project source file relative to the project root (one level above .pikku). */
   readProjectFile(relativePath: string): Promise<string | null>
+  /**
+   * Read a file from an *installed addon package's* own `.pikku` directory
+   * (resolved from node_modules), NOT the app's `.pikku`. `relativePath` is
+   * relative to that package's `.pikku` root (use `../` to reach the package
+   * root itself, e.g. `../README.md`). Returns null if the package or file is
+   * absent. Only local/Node implementations resolve packages; remote impls omit
+   * this and callers guard with `?.`.
+   */
+  readPackageFile?(
+    packageName: string,
+    relativePath: string
+  ): Promise<string | null>
+  /** List a directory inside an installed addon package's `.pikku`. */
+  readPackageDir?(packageName: string, relativePath: string): Promise<string[]>
 
   // -- Typed metadata accessors --
 
@@ -252,6 +266,57 @@ export class LocalMetaService implements MetaService {
     }
   }
 
+  // Resolve an installed addon package's root dir from the app's node_modules.
+  // The addon packages have no main `exports` entry, so `require.resolve(pkg)`
+  // throws; instead we walk the node_modules search paths (anchored at the app
+  // root, one level above `.pikku`) and pick the first that contains the package.
+  private packageRootCache = new Map<string, string | null>()
+  private resolvePackageRoot(packageName: string): string | null {
+    const cached = this.packageRootCache.get(packageName)
+    if (cached !== undefined) return cached
+    let root: string | null = null
+    try {
+      const require = createRequire(join(this.basePath, '..', 'index.js'))
+      for (const dir of require.resolve.paths(packageName) ?? []) {
+        const candidate = join(dir, packageName)
+        if (existsSync(join(candidate, 'package.json'))) {
+          root = candidate
+          break
+        }
+      }
+    } catch {
+      root = null
+    }
+    this.packageRootCache.set(packageName, root)
+    return root
+  }
+
+  async readPackageFile(
+    packageName: string,
+    relativePath: string
+  ): Promise<string | null> {
+    const root = this.resolvePackageRoot(packageName)
+    if (!root) return null
+    try {
+      return await readFile(join(root, '.pikku', relativePath), 'utf-8')
+    } catch {
+      return null
+    }
+  }
+
+  async readPackageDir(
+    packageName: string,
+    relativePath: string
+  ): Promise<string[]> {
+    const root = this.resolvePackageRoot(packageName)
+    if (!root) return []
+    try {
+      return await readdir(join(root, '.pikku', relativePath))
+    } catch {
+      return []
+    }
+  }
+
   clearCache(): void {
     this.httpMetaCache = null
     this.channelsMetaCache = null
@@ -489,7 +554,7 @@ export class LocalMetaService implements MetaService {
     )
     this.permissionsGroupsMetaCache = content
       ? JSON.parse(content)
-      : { definitions: {}, httpGroups: {}, tagGroups: {} }
+      : { definitions: {} }
     return this.permissionsGroupsMetaCache!
   }