@pikku/core 0.12.71 → 0.12.74

package/src/remote.test.ts

@@ -0,0 +1,172 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert'
+import { buildRemoteHeaders } from './remote.js'
+import { pikkuRemoteAuthMiddleware } from './middleware/remote-auth.js'
+import { resetPikkuState } from './pikku-state.js'
+import { WeakKeyMaterialError } from './errors/errors.js'
+
+beforeEach(() => {
+  resetPikkuState()
+})
+
+const STRONG_SECRET = 'a'.repeat(43)
+const WEAK_SECRET = 'dev-remote-secret'
+
+const createSecrets = (secret: string) => ({
+  getSecret: async (key: string) => {
+    if (key === 'PIKKU_REMOTE_SECRET') return secret
+    throw new Error(`Secret ${key} not found`)
+  },
+})
+
+/**
+ * Signing is deliberately free here so the measurement isolates key derivation.
+ */
+const createJWT = () => ({
+  encode: async (_expiresIn: unknown, payload: unknown) =>
+    Buffer.from(JSON.stringify(payload)).toString('base64url'),
+  decode: async (token: string) =>
+    JSON.parse(Buffer.from(token, 'base64url').toString('utf-8')),
+})
+
+const createRequest = (
+  headers: Record<string, string>,
+  path = '/remote/rpc/myFunc'
+) => ({
+  header: (name: string) => headers[name.toLowerCase()] || headers[name],
+  path: () => path,
+  method: () => 'POST',
+})
+
+const roundTrip = async (secret: string, session: unknown) => {
+  const jwt = createJWT()
+  const secrets = createSecrets(secret)
+
+  const headers = await buildRemoteHeaders(
+    jwt as any,
+    secrets as any,
+    'myFunc',
+    session
+  )
+
+  let received: unknown
+  await pikkuRemoteAuthMiddleware(
+    { secrets, jwt } as any,
+    {
+      http: {
+        request: createRequest({ authorization: headers.authorization! }),
+      },
+      setSession: async (s: unknown) => {
+        received = s
+      },
+    } as any,
+    async () => {}
+  )
+  return received
+}
+
+describe('remote RPC session round trip', () => {
+  test('round-trips the session through header build and middleware verify', async () => {
+    const session = { userId: 'user-1', role: 'admin' }
+    assert.deepStrictEqual(await roundTrip(STRONG_SECRET, session), session)
+  })
+
+  test('a header built with one secret is rejected by a peer holding another', async () => {
+    const jwt = createJWT()
+    const headers = await buildRemoteHeaders(
+      jwt as any,
+      createSecrets(STRONG_SECRET) as any,
+      'myFunc',
+      { userId: 'user-1' }
+    )
+
+    await assert.rejects(() =>
+      pikkuRemoteAuthMiddleware(
+        { secrets: createSecrets('b'.repeat(43)), jwt } as any,
+        {
+          http: {
+            request: createRequest({ authorization: headers.authorization! }),
+          },
+          setSession: async () => {},
+        } as any,
+        async () => {}
+      )
+    )
+  })
+
+  test('a full round trip stays under the per-hop latency budget', async () => {
+    const session = { userId: 'user-1', role: 'admin' }
+
+    // Warm up so the measurement excludes module/JIT startup.
+    await roundTrip(STRONG_SECRET, session)
+
+    const iterations = 5
+    const start = performance.now()
+    for (let i = 0; i < iterations; i++) {
+      await roundTrip(STRONG_SECRET, session)
+    }
+    const perRoundTrip = (performance.now() - start) / iterations
+
+    assert.ok(
+      perRoundTrip < 20,
+      `remote RPC round trip took ${perRoundTrip.toFixed(1)}ms, budget is 20ms`
+    )
+  })
+})
+
+describe('PIKKU_REMOTE_SECRET strength', () => {
+  test('buildRemoteHeaders rejects a secret shorter than 32 characters', async () => {
+    await assert.rejects(
+      () =>
+        buildRemoteHeaders(
+          createJWT() as any,
+          createSecrets(WEAK_SECRET) as any,
+          'myFunc',
+          { userId: 'user-1' }
+        ),
+      (err: unknown) => err instanceof WeakKeyMaterialError
+    )
+  })
+
+  test('buildRemoteHeaders rejects a weak secret even with no session to encrypt', async () => {
+    await assert.rejects(
+      () =>
+        buildRemoteHeaders(
+          createJWT() as any,
+          createSecrets(WEAK_SECRET) as any,
+          'myFunc'
+        ),
+      (err: unknown) => err instanceof WeakKeyMaterialError
+    )
+  })
+
+  test('the middleware rejects a weak secret rather than authenticating with it', async () => {
+    const jwt = createJWT()
+    const headers = await buildRemoteHeaders(
+      jwt as any,
+      createSecrets(STRONG_SECRET) as any,
+      'myFunc',
+      { userId: 'user-1' }
+    )
+
+    await assert.rejects(
+      () =>
+        pikkuRemoteAuthMiddleware(
+          { secrets: createSecrets(WEAK_SECRET), jwt } as any,
+          {
+            http: {
+              request: createRequest({ authorization: headers.authorization! }),
+            },
+            setSession: async () => {},
+          } as any,
+          async () => {}
+        ),
+      (err: unknown) => err instanceof WeakKeyMaterialError
+    )
+  })
+
+  test('a secret of exactly 32 characters is accepted', async () => {
+    const session = { userId: 'user-1' }
+    assert.deepStrictEqual(await roundTrip('x'.repeat(32), session), session)
+  })
+})

package/src/remote.ts

@@ -1,13 +1,15 @@
 import type { JWTService } from './services/jwt-service.js'
 import type { SecretService } from './services/secret-service.js'
-import { encryptJSON } from './crypto-utils.js'
+import {
+  assertStrongKeyMaterial,
+  encryptWithKeyMaterial,
+  REMOTE_SESSION_INFO,
+} from './crypto-utils.js'
 
 /**
- * Build Authorization headers with JWT-signed session and traceId for
- * pikkuRemoteAuthMiddleware on the receiving end.
- *
- * Used by all deployment services (Kysely, Redis, MongoDB, Lambda, CF, Azure)
- * regardless of transport (HTTP, Lambda Invoke, service bindings).
+ * Authorization headers carrying a JWT-signed session and traceId for
+ * `pikkuRemoteAuthMiddleware` on the receiving end. Used by every deployment
+ * service regardless of transport (HTTP, Lambda Invoke, service bindings).
  */
 export async function buildRemoteHeaders(
   jwt: JWTService | undefined,
@@ -27,8 +29,16 @@ export async function buildRemoteHeaders(
   } catch {}
 
   if (secret && jwt) {
+    assertStrongKeyMaterial('PIKKU_REMOTE_SECRET', secret)
     const sessionEnc = session
-      ? await encryptJSON(secret, { session })
+      ? await encryptWithKeyMaterial(
+          'PIKKU_REMOTE_SECRET',
+          secret,
+          REMOTE_SESSION_INFO,
+          {
+            session,
+          }
+        )
       : undefined
     const token = await jwt.encode(
       { value: 5, unit: 'minute' },

package/src/schema.test.ts

@@ -3,6 +3,7 @@ import * as assert from 'assert'
 import {
   addSchema,
   getSchema,
+  applyDefaultsFromSchema,
   coerceTopLevelDataFromSchema,
   validateSchema,
   compileAllSchemas,
@@ -111,6 +112,108 @@ describe('Schema', () => {
     })
   })
 
+  describe('applyDefaultsFromSchema', () => {
+    before(() => {
+      addSchema('defaultsSchema', {
+        properties: {
+          page: { type: 'number', default: 1 },
+          limit: { type: 'number', default: 50 },
+          addons: { type: 'array', default: [] },
+          mode: { type: 'string', default: 'manual' },
+          enabled: { type: 'boolean', default: true },
+          name: { type: 'string' },
+        },
+      })
+
+      addSchema('noDefaultsSchema', {
+        properties: { name: { type: 'string' } },
+      })
+
+      addSchema('booleanPropSchema', {
+        properties: { isActive: true, page: { type: 'number', default: 1 } },
+      })
+    })
+
+    test('should fill in absent properties from their default', () => {
+      const data = applyDefaultsFromSchema('defaultsSchema', {})
+      assert.strictEqual(data.page, 1)
+      assert.strictEqual(data.limit, 50)
+      assert.strictEqual(data.mode, 'manual')
+      assert.strictEqual(data.enabled, true)
+    })
+
+    test('should not overwrite a supplied value', () => {
+      const data = applyDefaultsFromSchema('defaultsSchema', {
+        page: 7,
+        limit: 200,
+      })
+      assert.strictEqual(data.page, 7)
+      assert.strictEqual(data.limit, 200)
+    })
+
+    // `false` and `0` are the values a truthiness check silently replaces, and
+    // the reason this tests presence rather than falsiness.
+    test('should not overwrite a supplied falsy value', () => {
+      const data = applyDefaultsFromSchema('defaultsSchema', {
+        page: 0,
+        enabled: false,
+      })
+      assert.strictEqual(data.page, 0)
+      assert.strictEqual(data.enabled, false)
+    })
+
+    test('should fill defaults into nullish data', () => {
+      assert.strictEqual(
+        applyDefaultsFromSchema('defaultsSchema', undefined).page,
+        1
+      )
+      assert.strictEqual(
+        applyDefaultsFromSchema('defaultsSchema', null).limit,
+        50
+      )
+    })
+
+    test('should leave properties without a default absent', () => {
+      const data = applyDefaultsFromSchema('defaultsSchema', {})
+      assert.ok(!('name' in data))
+    })
+
+    // Two requests sharing one array default would let the first request's
+    // pushes show up in the second.
+    test('should clone object and array defaults per call', () => {
+      const first = applyDefaultsFromSchema('defaultsSchema', {})
+      const second = applyDefaultsFromSchema('defaultsSchema', {})
+      first.addons.push('leaked')
+      assert.deepStrictEqual(second.addons, [])
+    })
+
+    test('should return the same data when the schema has no defaults', () => {
+      const data = { name: 'x' }
+      assert.strictEqual(
+        applyDefaultsFromSchema('noDefaultsSchema', data),
+        data
+      )
+    })
+
+    test('should return data untouched for an unknown schema', () => {
+      const data = { name: 'x' }
+      assert.strictEqual(applyDefaultsFromSchema('nonExistent', data), data)
+    })
+
+    test('should leave a primitive body for the validator to reject', () => {
+      assert.strictEqual(
+        applyDefaultsFromSchema('defaultsSchema', 'nope'),
+        'nope'
+      )
+    })
+
+    test('should skip boolean schema properties', () => {
+      const data = applyDefaultsFromSchema('booleanPropSchema', {})
+      assert.strictEqual(data.page, 1)
+      assert.ok(!('isActive' in data))
+    })
+  })
+
   describe('validateSchema', () => {
     beforeEach(() => {
       resetPikkuState()

package/src/schema.ts

@@ -9,13 +9,6 @@ import { pikkuState, getAllPackageStates } from './pikku-state.js'
 const schemaKey = (name: string, packageName: string | null): string =>
   packageName ? `${packageName}:${name}` : name
 
-/**
- * Adds a schema to the schemas map for a specific package.
- * @param name - The name of the schema.
- * @param value - The schema value.
- * @param packageName - The package name (null for main package, '@scope/package' for addon packages).
- * @ignore
- */
 export const addSchema = (
   name: string,
   value: any,
@@ -25,13 +18,6 @@ export const addSchema = (
   pikkuState(packageName, 'misc', 'schemas').set(name, schema)
 }
 
-/**
- * Retrieves a schema from the schemas map for a specific package.
- * @param name - The name of the schema.
- * @param packageName - The package name (null for main package, '@scope/package' for addon packages).
- * @returns The schema value or undefined if not found.
- * @ignore
- */
 export const getSchema = (
   name: string,
   packageName: string | null = null
@@ -39,10 +25,6 @@ export const getSchema = (
   return pikkuState(packageName, 'misc', 'schemas').get(name)
 }
 
-/**
- * Loads a schema and compiles it into a validator.
- * @param logger - A logger for logging information.
- */
 export const compileAllSchemas = (
   logger: Logger,
   schemaService?: SchemaService
@@ -94,6 +76,41 @@ const validateAllSchemasLoaded = (
   }
 }
 
+/**
+ * Fills in absent top-level properties from their schema `default`. Applied
+ * unconditionally: a default belongs to the schema, not to the transport the
+ * call arrived on, and runs before coercion so a defaulted and a supplied
+ * value are treated identically from here on. Values are cloned so an object
+ * or array default is never shared as one mutable instance across requests.
+ */
+export const applyDefaultsFromSchema = (
+  schemaName: string,
+  data: any,
+  packageName: string | null = null
+) => {
+  const schema = pikkuState(packageName, 'misc', 'schemas').get(schemaName)
+  if (!schema?.properties) return data
+
+  // A primitive body cannot carry named properties; leave it for the validator
+  // to reject rather than reshaping it into something that would pass.
+  if (data != null && typeof data !== 'object') return data
+
+  let result = data
+  for (const key in schema.properties) {
+    const property = schema.properties[key]
+    if (typeof property === 'boolean' || !('default' in property)) {
+      continue
+    }
+    // Allocated only once a default is actually found, so a schema without any
+    // leaves the caller's data (and its absence) exactly as it was.
+    result ??= {}
+    if (result[key] === undefined) {
+      result[key] = structuredClone(property.default)
+    }
+  }
+  return result
+}
+
 export const coerceTopLevelDataFromSchema = (
   schemaName: string,
   data: any,

package/src/scopes.ts

@@ -5,13 +5,9 @@ const SEPARATOR = ':'
 const WILDCARD = '*'
 
 /**
- * Builds every grant that would satisfy `scope`: the scope itself, a wildcard
+ * 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
+ * ancestor id.
  */
 const satisfyingGrants = (scope: string): string[] => {
   const segments = scope.split(SEPARATOR)
@@ -25,28 +21,10 @@ const satisfyingGrants = (scope: string): string[] => {
   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))
 
-/**
- * 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.
- */
+/** The first required scope `held` does not satisfy, or `null`. Fails closed. */
 const firstUnsatisfied = (
   required: readonly string[] | undefined,
   held: Iterable<string> | undefined
@@ -65,17 +43,8 @@ const firstUnsatisfied = (
 }
 
 /**
- * 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.
+ * than enforcing. Fails closed; an empty `required` is satisfied by anything.
  */
 export const hasScopes = (
   required: readonly string[] | undefined,
@@ -83,19 +52,9 @@ export const hasScopes = (
 ): boolean => firstUnsatisfied(required, held) === null
 
 /**
- * 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.
+ * Throws {@link MissingScopeError} naming the first scope the session does not
+ * hold. Fails closed: no session, or a session without `scopes`, satisfies
+ * nothing.
  */
 export const verifyScopes = (
   required: readonly string[] | undefined,

package/src/services/ai-agent-runner-service.ts

@@ -19,6 +19,26 @@ export type AIAgentRunnerParams = {
   /** Pikku agent function name — forwarded to the LLM proxy (LiteLLM) as
    *  request-level metadata so usage can be broken down per agent. */
   agentId?: string
+  /**
+   * Cancels the model call itself, not just delivery of its output. Set by
+   * `streamAIAgent` from the run's interrupt handle so a voice barge-in stops
+   * generation upstream rather than leaving tokens being billed into a stream
+   * nobody reads. A runner that ignores it degrades to "the caller stops
+   * listening", which is the behaviour before this field existed.
+   */
+  abortSignal?: AbortSignal
+  /**
+   * Per-provider settings passed to the model untouched — the escape hatch for
+   * anything the shared params above cannot express because only one vendor
+   * has it.
+   *
+   * The setting that motivated it is `reasoningEffort`. A voice turn is heard
+   * rather than read, so the wait before the first word is most of the
+   * experience: `{ openai: { reasoningEffort: 'minimal' } }` on gpt-5-mini
+   * measured 0.9s to first token against 2.5s at the default, and 1.6s of
+   * silence is a long time to sit through having just finished speaking.
+   */
+  providerOptions?: AIProviderOptions
 }
 
 export type AIAgentRunnerResult = {

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

@@ -1,31 +1,9 @@
-/**
- * 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.
- */
+// knowledge: decisions/internals/the-embedding-model-is-pinned-per-service-and-doc-query-embedding-is-split.md
 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. */
+  /** Index time. Preserves input order. */
   embedDocuments(values: string[]): Promise<number[][]>
-  /** Embed a search query (query time) into a vector. */
+  /** Query time. */
   embedQuery(value: string): Promise<number[]>
 }

package/src/services/audit-service.ts

@@ -76,8 +76,7 @@ class DisabledInvocationAudit implements AuditLog {
   async write(_event: AuditLogWriteInput): Promise<void> {
     if (!this.warned) {
       this.warned = true
-      // Fall back to the singleton logger — wires rarely carry their own, and
-      // a dropped audit write must never be invisible.
+      // knowledge: decisions/security/a-dropped-audit-write-is-always-logged.md
       const logger = (this.wire as any).logger ?? this.logger
       logger?.warn?.(
         `audit.write() dropped for '${this.wire.functionId ?? 'unknown function'}' — the function has no audit config (set audit: true on it)`

package/src/services/content-service.ts

@@ -1,6 +1,3 @@
-/**
- * Arguments for signing a content key into a time-limited URL.
- */
 export interface SignContentKeyArgs<TBucket extends string = string> {
   bucket: TBucket
   contentKey: string
@@ -8,18 +5,12 @@ export interface SignContentKeyArgs<TBucket extends string = string> {
   dateGreaterThan?: Date
 }
 
-/**
- * Arguments for signing an arbitrary URL.
- */
 export interface SignURLArgs {
   url: string
   dateLessThan: Date
   dateGreaterThan?: Date
 }
 
-/**
- * Arguments for minting a presigned upload URL.
- */
 export interface GetUploadURLArgs<TBucket extends string = string> {
   bucket: TBucket
   fileKey: string
@@ -28,9 +19,6 @@ export interface GetUploadURLArgs<TBucket extends string = string> {
   visibility?: 'private' | 'public'
 }
 
-/**
- * Result of minting a presigned upload URL.
- */
 export interface UploadURLResult {
   uploadUrl: string
   assetKey: string
@@ -38,26 +26,17 @@ export interface UploadURLResult {
   uploadMethod?: 'PUT' | 'POST'
 }
 
-/**
- * Arguments for an operation that targets a single object by key.
- */
 export interface BucketKeyArgs<TBucket extends string = string> {
   bucket: TBucket
   key: string
 }
 
-/**
- * Arguments for writing a stream to storage.
- */
 export interface WriteFileArgs<
   TBucket extends string = string,
 > extends BucketKeyArgs<TBucket> {
   stream: ReadableStream | NodeJS.ReadableStream
 }
 
-/**
- * Arguments for copying a local file into storage.
- */
 export interface CopyFileArgs<
   TBucket extends string = string,
 > extends BucketKeyArgs<TBucket> {
@@ -65,46 +44,22 @@ export interface CopyFileArgs<
 }
 
 export interface ContentService<TBucket extends string = string> {
-  /**
-   * Signs a content key to generate a secure, time-limited access URL.
-   */
   signContentKey(args: SignContentKeyArgs<TBucket>): Promise<string>
 
-  /**
-   * Signs an arbitrary URL to generate a secure, time-limited access URL.
-   */
   signURL(args: SignURLArgs): Promise<string>
 
-  /**
-   * Generates a signed URL for uploading a file directly to storage.
-   * Bucket policy (size limits, MIME allowlist) is enforced by the implementation.
-   */
+  /** Bucket policy (size limits, MIME allowlist) is enforced by the implementation, not the caller. */
   getUploadURL(args: GetUploadURLArgs<TBucket>): Promise<UploadURLResult>
 
-  /**
-   * Deletes a file from the storage backend.
-   */
   deleteFile(args: BucketKeyArgs<TBucket>): Promise<boolean>
 
-  /**
-   * Uploads a file stream to storage under the specified bucket + key.
-   */
   writeFile(args: WriteFileArgs<TBucket>): Promise<boolean>
 
-  /**
-   * Copies a file from a local absolute path into storage.
-   */
   copyFile(args: CopyFileArgs<TBucket>): Promise<boolean>
 
-  /**
-   * Reads a file from storage as a readable stream.
-   */
   readFile(
     args: BucketKeyArgs<TBucket>
   ): Promise<ReadableStream | NodeJS.ReadableStream>
 
-  /**
-   * Reads an entire file from storage into a Buffer.
-   */
   readFileAsBuffer(args: BucketKeyArgs<TBucket>): Promise<Buffer>
 }