@pikku/core 0.12.72 → 0.12.77

package/src/secret-value.ts

@@ -0,0 +1,111 @@
+import type { Secret } from './data-classification.js'
+
+declare const secretValueBrand: unique symbol
+
+export const REDACTED = '[secret]'
+
+/** Runtime marker, resilient to duplicate copies of core. */
+const SECRET_VALUE = Symbol.for('pikku.secretValue')
+
+const NODE_INSPECT = Symbol.for('nodejs.util.inspect.custom')
+
+export class SecretCoercionError extends Error {
+  constructor() {
+    super(
+      `A secret was coerced to a string, which would write it out in the clear. Unwrap it deliberately with .reveal() at the point it reaches the wire.`
+    )
+    this.name = 'SecretCoercionError'
+  }
+}
+
+/**
+ * A vault secret. Nominal, so it is not assignable to `string` and every
+ * concretely-typed sink rejects it; `.reveal()` is the one way out, and every
+ * call is a deliberate, greppable disclosure.
+ *
+ * The revealed value carries the erasable `Secret<T>` classification brand, so
+ * the inspector can still follow it one hop past the call.
+ *
+ * Structured serialization redacts to `[secret]` — an audit or log write must
+ * stay honest about the field without crashing the request. String coercion
+ * throws, because a template literal or concatenation is always a leak.
+ */
+export class SecretValue<T = string> {
+  declare readonly [secretValueBrand]: true
+  readonly [SECRET_VALUE] = true
+
+  readonly #value: T
+
+  constructor(value: T) {
+    this.#value = value
+  }
+
+  reveal(): Secret<T> {
+    return this.#value as Secret<T>
+  }
+
+  toJSON(): string {
+    return REDACTED
+  }
+
+  [NODE_INSPECT](): string {
+    return REDACTED
+  }
+
+  toString(): never {
+    throw new SecretCoercionError()
+  }
+
+  [Symbol.toPrimitive](): never {
+    throw new SecretCoercionError()
+  }
+}
+
+export const createSecretValue = <T>(value: T): SecretValue<T> =>
+  new SecretValue(value)
+
+export const isSecretValue = (value: unknown): value is SecretValue<unknown> =>
+  typeof value === 'object' && value !== null && SECRET_VALUE in value
+
+type IsAny<T> = 0 extends 1 & T ? true : false
+
+type Passthrough =
+  | Function
+  | Date
+  | RegExp
+  | Error
+  | ArrayBuffer
+  | ArrayBufferView
+
+/**
+ * Rejects a `SecretValue` anywhere in `T`, however deeply nested, by collapsing
+ * it to `never`.
+ *
+ * For sinks whose parameters are `any`, `unknown` or a free generic — loggers,
+ * queue payloads, channel messages — where nominality alone cannot help.
+ * `any` is passed through untouched: it cannot be guarded, and collapsing it
+ * would reject every legitimate call.
+ *
+ * `Promise`, `Map` and `Set` are recursed into rather than passed through. A
+ * mapped type cannot reach what they hold — mapping their keys yields their
+ * methods, not their contents — so treating them as opaque let a secret ride
+ * through inside one. `Promise` is the case that bites: `getSecret()` returns
+ * `Promise<SecretValue<T>>`, so a forgotten `await` would otherwise log a
+ * secret.
+ */
+export type Safe<T> =
+  IsAny<T> extends true
+    ? T
+    : [Extract<T, SecretValue<any>>] extends [never]
+      ? T extends Promise<infer V>
+        ? Promise<Safe<V>>
+        : T extends Map<infer K, infer V>
+          ? Map<Safe<K>, Safe<V>>
+          : T extends Set<infer V>
+            ? Set<Safe<V>>
+            : T extends Passthrough
+              ? T
+              : T extends object
+                ? { [K in keyof T]: Safe<T[K]> }
+                : T
+      : never

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

@@ -4,6 +4,7 @@ import type {
   PikkuWiringTypes,
 } from '../types/core.types.js'
 import type { Logger } from './logger.js'
+import type { Safe } from '../secret-value.js'
 
 export type AuditDurability = 'best-effort' | 'transactional'
 export type AuditOutcome = 'success' | 'failed' | 'denied'
@@ -19,7 +20,19 @@ export type ResolvedAuditConfig = {
   durability: AuditDurability
 }
 
-export type AuditActor = {
+/**
+ * Who an event happened under.
+ *
+ * A user, not an "actor": in pikku an actor is a synthetic person a scenario
+ * drives, flagged `actor` on the user row, and the overwhelming majority of
+ * audited events are caused by ordinary customers. Naming this `actor` made the
+ * synthetic case unsayable — `actor.actor === true` — and implied every
+ * recorded action was a test.
+ *
+ * `pikkuUserId` is the identity pikku resolves for every wire, so it is the one
+ * field a signed-out caller still leaves behind.
+ */
+export type AuditUserIdentity = {
   userId?: string
   orgId?: string
   pikkuUserId?: string
@@ -37,16 +50,67 @@ export type AuditEvent = {
   traceId?: string
   transactionId?: string | null
   queryId?: string | null
-  actor?: AuditActor
+  userIdentity?: AuditUserIdentity
   input?: unknown
   metadata?: Record<string, unknown>
 }
 
 export type AuditEventBatch = AuditEvent[]
 
+/**
+ * A page of the trail, newest first, narrowed by the filters a reader picked.
+ *
+ * Every field is a conjunction, and an empty array is not a filter — it is
+ * "match nothing", which would otherwise read as "match everything" and quietly
+ * widen a scoped query.
+ */
+export type AuditQuery = {
+  /** Restrict to these users. */
+  userIds?: string[]
+  /** Restrict to these `AuditEvent['type']` values. */
+  types?: string[]
+  /** Restrict to one organisation. */
+  orgId?: string
+  /** Inclusive lower bound on `occurredAt` (ISO 8601). */
+  from?: string
+  /** Exclusive upper bound on `occurredAt` (ISO 8601). */
+  to?: string
+  limit?: number
+  offset?: number
+}
+
+/**
+ * The distinct values present in the trail, for populating filter controls.
+ *
+ * Computed over the whole trail rather than the current page — a filter list
+ * that only offered what the current page happens to show could never be used
+ * to reach anything else.
+ */
+export type AuditFacets = {
+  userIds: string[]
+  types: string[]
+}
+
+export type AuditQueryResult = {
+  events: AuditEvent[]
+  /** Offset of the next page, or `null` at the end. */
+  nextCursor: number | null
+  /** Present only when the caller asked for it — it costs two extra scans. */
+  facets?: AuditFacets
+}
+
 export interface AuditService {
   audit(event: AuditEvent): Promise<void>
   write?(batch: AuditEventBatch): Promise<void>
+  /**
+   * The read side. Optional because a sink can legitimately be write-only — a
+   * queue producer that hands events to another system has nothing to read
+   * back. A reader that finds this absent should say the trail is not readable
+   * here rather than that it is empty; the two are very different answers.
+   */
+  query?(query: AuditQuery): Promise<AuditQueryResult>
+  /** Distinct users and types across the whole trail. Paired with {@link query}. */
+  facets?(): Promise<AuditFacets>
 }
 
 export class NoopAuditService implements AuditService {
@@ -57,9 +121,18 @@ export class NoopAuditService implements AuditService {
 
 export type AuditLogWriteInput = Omit<AuditEvent, 'occurredAt'>
 
+/**
+ * The audit an invocation writes to. `write` is `Safe<>`-guarded like the
+ * logger: an audit event carries `input` and `metadata` as `unknown`, so
+ * nominality alone cannot stop a `SecretValue` landing in one. A secret
+ * anywhere in the event, however deeply nested, collapses to `never`.
+ *
+ * An unrevealed `SecretValue` would serialize as `[secret]` anyway; the guard
+ * is what makes that an explicit choice rather than a near miss.
+ */
 export interface AuditLog {
   readonly config: ResolvedAuditConfig | undefined
-  write(event: AuditLogWriteInput): Promise<void>
+  write<E extends AuditLogWriteInput>(event: Safe<E>): Promise<void>
   flush(): Promise<void>
   close(): Promise<void>
 }
@@ -76,8 +149,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)`
@@ -150,7 +222,8 @@ class InvocationAuditLog implements AuditLog {
       wireType: this.wire.wireType,
       wireId: this.wire.wireId,
       traceId: this.wire.traceId,
-      actor: event.actor ?? resolveAuditActorFromWire(this.wire),
+      userIdentity:
+        event.userIdentity ?? resolveAuditUserIdentityFromWire(this.wire),
       ...event,
       occurredAt: new Date().toISOString(),
     }
@@ -185,19 +258,23 @@ export const createInvocationAudit = (
   return new InvocationAuditLog(wire.audit, service, wire, logger)
 }
 
-export const resolveAuditActorFromWire = (
+export const resolveAuditUserIdentityFromWire = (
   wire: PikkuWire<any, any, any, CoreUserSession>
-): AuditActor | undefined => {
+): AuditUserIdentity | undefined => {
   const session = wire.session as CoreUserSession | undefined
-  const actor: AuditActor = {
+  const userIdentity: AuditUserIdentity = {
     userId: session?.userId,
     orgId: session?.orgId,
     pikkuUserId: wire.pikkuUserId,
   }
 
-  if (!actor.userId && !actor.orgId && !actor.pikkuUserId) {
+  if (
+    !userIdentity.userId &&
+    !userIdentity.orgId &&
+    !userIdentity.pikkuUserId
+  ) {
     return undefined
   }
 
-  return actor
+  return userIdentity
 }

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>
 }

package/src/services/credential-service.ts

@@ -1,57 +1,20 @@
 /**
- * Interface for managing dynamic/managed credentials.
- * Used for OAuth tokens, per-user API keys, and other credentials
- * that change at runtime (as opposed to SecretService which is for
- * static, developer-configured values).
+ * Dynamic credentials — OAuth tokens, per-user API keys — that change at
+ * runtime, as opposed to `SecretService`'s static developer-configured values.
+ * Throughout, an omitted `userId` means the platform-level credential.
  */
 export interface CredentialService {
-  /**
-   * Retrieves a credential by name and optional user ID.
-   * @param name - The credential name (e.g. 'stripe', 'google-sheets').
-   * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
-   * @returns The credential value, or null if not found.
-   */
   get<T = unknown>(name: string, userId?: string): Promise<T | null>
 
-  /**
-   * Stores a credential.
-   * @param name - The credential name.
-   * @param value - The credential value to store.
-   * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
-   */
   set(name: string, value: unknown, userId?: string): Promise<void>
 
-  /**
-   * Deletes a credential.
-   * @param name - The credential name.
-   * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
-   */
   delete(name: string, userId?: string): Promise<void>
 
-  /**
-   * Checks if a credential exists.
-   * @param name - The credential name.
-   * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
-   */
   has(name: string, userId?: string): Promise<boolean>
 
-  /**
-   * Retrieves all credentials for a user.
-   * @param userId - The user ID.
-   * @returns A record of credential name to value.
-   */
   getAll(userId: string): Promise<Record<string, unknown>>
 
-  /**
-   * Lists all user IDs that have a specific credential configured.
-   * @param name - The credential name.
-   * @returns Array of user IDs.
-   */
   getUsersWithCredential(name: string): Promise<string[]>
 
-  /**
-   * Lists all unique user IDs that have any credential configured.
-   * @returns Array of user IDs.
-   */
   getAllUsers(): Promise<string[]>
 }

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

@@ -29,9 +29,7 @@ describe('PikkuCredentialWireService', () => {
   test('should return sync after first load (no credential service)', async () => {
     const service = new PikkuCredentialWireService()
     service.set('foo', 'bar')
-    // First call triggers lazy load (no-op without credentialService)
     await service.getAll()
-    // Second call should be sync
     const result = service.getAll()
     assert.ok(!(result instanceof Promise), 'expected sync return')
     assert.deepStrictEqual(result, { foo: 'bar' })

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

@@ -1,3 +1,4 @@
+import { isSecretValue } from '../secret-value.js'
 import type { CredentialService } from './credential-service.js'
 import { defaultPikkuUserIdResolver } from './pikku-user-id.js'
 import type { PikkuRawWire } from '../types/core.types.js'
@@ -17,8 +18,15 @@ export class PikkuCredentialWireService {
     return this.aliases?.[name] ?? name
   }
 
+  /**
+   * A credential is one of the few places vault material is meant to end up, so
+   * a `SecretValue` is unwrapped here rather than rejected — `get` promises the
+   * raw material, and storing the wrapper would make that a lie.
+   */
   set(name: string, value: unknown): void {
-    this.credentials[this.resolveName(name)] = value
+    this.credentials[this.resolveName(name)] = isSecretValue(value)
+      ? value.reveal()
+      : value
   }
 
   get<T = unknown>(name: string): T | null | Promise<T | null> {

package/src/services/deployment-service.ts

@@ -19,15 +19,9 @@ export interface DeploymentService {
   start(config: DeploymentConfig): Promise<void>
   stop(): Promise<void>
   /**
-   * Dispatch a remote RPC call to a function.
-   * The deployment service owns the full transport:
-   * - Resolving the target (endpoint, service binding, etc.)
-   * - Session propagation (JWT signing, headers)
-   * - The actual network call
-   *
-   * @param funcName - The function to invoke
-   * @param data - Input data for the function
-   * @param session - User session to propagate (optional)
+   * The implementation owns the whole transport: resolving the target
+   * (endpoint, service binding), propagating the session (JWT signing,
+   * headers) and making the call. Callers supply no transport detail.
    */
   invoke(
     funcName: string,

package/src/services/email-service.ts

@@ -1,3 +1,5 @@
+import type { Safe } from '../secret-value.js'
+
 export interface EmailTemplateReference {
   name: string
   locale?: string
@@ -42,5 +44,5 @@ export interface SendEmailResult {
 }
 
 export interface EmailService {
-  send(input: SendEmailInput): Promise<SendEmailResult>
+  send<T extends SendEmailInput>(input: Safe<T>): Promise<SendEmailResult>
 }

package/src/services/gateway-service.ts

@@ -1,20 +1,5 @@
-/**
- * Abstract GatewayService interface.
- *
- * Implementations manage listener gateway lifecycle — initializing adapters
- * and delivering messages to handler functions.
- *
- * A `LocalGatewayService` starts all listeners unconditionally;
- * a distributed implementation could check leader election first.
- */
 export interface GatewayService {
-  /**
-   * Start all listener gateways
-   */
   start(): Promise<void>
 
-  /**
-   * Stop all listener gateways
-   */
   stop(): Promise<void>
 }