@pikku/core 0.12.72 → 0.12.77

package/dist/schema.d.ts

@@ -1,48 +1,14 @@
 import type { Logger } from './services/logger.js';
 import type { SchemaService } from './services/schema-service.js';
-/**
- * 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 declare const addSchema: (name: string, value: any, packageName?: string | null) => void;
-/**
- * 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 declare const getSchema: (name: string, packageName?: string | null) => Record<string, unknown> | undefined;
-/**
- * Loads a schema and compiles it into a validator.
- * @param logger - A logger for logging information.
- */
 export declare const compileAllSchemas: (logger: Logger, schemaService?: SchemaService) => void;
 /**
- * Fill in absent top-level properties from their schema `default`.
- *
- * A `default` reaches the generated JSON Schema and keeps the property out of
- * `required`, so omitting it validates — but nothing was ever filling it in.
- * JSON Schema validators are pure by specification and none of the ones Pikku
- * ships with (`@cfworker/json-schema`, and Ajv unless `useDefaults` is set)
- * annotate the instance, so the function received `undefined` for a property
- * its generated type declares as present. That is the worst shape a mismatch
- * can take: validation permits the omission, the type says the value is there,
- * and the body reads `undefined`.
- *
- * Applied unconditionally rather than alongside `coerceTopLevelDataFromSchema`,
- * whose `coerceDataFromSchema` flag is about decoding transport-encoded values
- * (a query string's `"1,2"` into an array). Defaults are a property of the
- * schema, not of how the call arrived, so gating them on that flag would apply
- * them over HTTP and skip them on a direct RPC invocation.
- *
- * Returns the data to use, which is a new object only when defaults had to be
- * added to a nullish input — a call made with no arguments at all still gets
- * them. Values are cloned so an object or array default (`[]`, `{}`) is never
- * shared as one mutable instance across every request.
+ * 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 declare const applyDefaultsFromSchema: (schemaName: string, data: any, packageName?: string | null) => any;
 export declare const coerceTopLevelDataFromSchema: (schemaName: string, data: any, packageName?: string | null) => void;

package/dist/schema.js

@@ -1,31 +1,13 @@
 import { MissingSchemaError, UnprocessableContentError, } from './errors/errors.js';
 import { pikkuState, getAllPackageStates } from './pikku-state.js';
 const schemaKey = (name, packageName) => 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, value, packageName = null) => {
     const schema = value?.default ?? value;
     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, packageName = null) => {
     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, schemaService) => {
     if (!schemaService) {
         schemaService = pikkuState(null, 'package', 'singletonServices')?.schema;
@@ -66,27 +48,11 @@ const validateAllSchemasLoaded = (logger, schemaService) => {
     }
 };
 /**
- * Fill in absent top-level properties from their schema `default`.
- *
- * A `default` reaches the generated JSON Schema and keeps the property out of
- * `required`, so omitting it validates — but nothing was ever filling it in.
- * JSON Schema validators are pure by specification and none of the ones Pikku
- * ships with (`@cfworker/json-schema`, and Ajv unless `useDefaults` is set)
- * annotate the instance, so the function received `undefined` for a property
- * its generated type declares as present. That is the worst shape a mismatch
- * can take: validation permits the omission, the type says the value is there,
- * and the body reads `undefined`.
- *
- * Applied unconditionally rather than alongside `coerceTopLevelDataFromSchema`,
- * whose `coerceDataFromSchema` flag is about decoding transport-encoded values
- * (a query string's `"1,2"` into an array). Defaults are a property of the
- * schema, not of how the call arrived, so gating them on that flag would apply
- * them over HTTP and skip them on a direct RPC invocation.
- *
- * Returns the data to use, which is a new object only when defaults had to be
- * added to a nullish input — a call made with no arguments at all still gets
- * them. Values are cloned so an object or array default (`[]`, `{}`) is never
- * shared as one mutable instance across every request.
+ * 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, data, packageName = null) => {
     const schema = pikkuState(packageName, 'misc', 'schemas').get(schemaName);

package/dist/scopes.d.ts

@@ -1,31 +1,12 @@
 import type { CoreUserSession } from './types/core.types.js';
 /**
- * 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 declare const hasScopes: (required: readonly string[] | undefined, held: Iterable<string> | undefined) => boolean;
 /**
- * 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 declare const verifyScopes: (required: readonly string[] | undefined, session: CoreUserSession | undefined) => void;

package/dist/scopes.js

@@ -2,13 +2,9 @@ import { MissingScopeError } from './errors/errors.js';
 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) => {
     const segments = scope.split(SEPARATOR);
@@ -21,26 +17,8 @@ const satisfyingGrants = (scope) => {
     }
     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, scope) => 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, held) => {
     if (!required || required.length === 0) {
         return null;
@@ -54,33 +32,14 @@ const firstUnsatisfied = (required, held) => {
     return null;
 };
 /**
- * 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, held) => 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, session) => {
     const missing = firstUnsatisfied(required, session?.scopes);

package/dist/secret-value.d.ts

@@ -0,0 +1,56 @@
+import type { Secret } from './data-classification.js';
+declare const secretValueBrand: unique symbol;
+export declare const REDACTED = "[secret]";
+/** Runtime marker, resilient to duplicate copies of core. */
+declare const SECRET_VALUE: unique symbol;
+declare const NODE_INSPECT: unique symbol;
+export declare class SecretCoercionError extends Error {
+    constructor();
+}
+/**
+ * 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 declare class SecretValue<T = string> {
+    #private;
+    readonly [secretValueBrand]: true;
+    readonly [SECRET_VALUE] = true;
+    constructor(value: T);
+    reveal(): Secret<T>;
+    toJSON(): string;
+    [NODE_INSPECT](): string;
+    toString(): never;
+    [Symbol.toPrimitive](): never;
+}
+export declare const createSecretValue: <T>(value: T) => SecretValue<T>;
+export declare const isSecretValue: (value: unknown) => value is SecretValue<unknown>;
+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;
+export {};

package/dist/secret-value.js

@@ -0,0 +1,46 @@
+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 {
+    [SECRET_VALUE] = true;
+    #value;
+    constructor(value) {
+        this.#value = value;
+    }
+    reveal() {
+        return this.#value;
+    }
+    toJSON() {
+        return REDACTED;
+    }
+    [NODE_INSPECT]() {
+        return REDACTED;
+    }
+    toString() {
+        throw new SecretCoercionError();
+    }
+    [Symbol.toPrimitive]() {
+        throw new SecretCoercionError();
+    }
+}
+export const createSecretValue = (value) => new SecretValue(value);
+export const isSecretValue = (value) => typeof value === 'object' && value !== null && SECRET_VALUE in value;

package/dist/services/ai-agent-runner-service.d.ts

@@ -12,6 +12,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 = {
     text: string;

package/dist/services/ai-embedding-service.d.ts

@@ -1,31 +1,8 @@
-/**
- * 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. */
+    /** 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/dist/services/audit-service.d.ts

@@ -1,5 +1,6 @@
 import type { CoreUserSession, PikkuWire, 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';
 export type AuditSource = 'auto' | 'explicit';
@@ -9,7 +10,19 @@ export type AuditConfig = boolean | {
 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;
@@ -26,26 +39,83 @@ 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 declare class NoopAuditService implements AuditService {
     audit(_event: AuditEvent): Promise<void>;
     write(_batch: AuditEventBatch): Promise<void>;
 }
 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>;
 }
 export declare const resolveAuditConfig: (config?: AuditConfig) => ResolvedAuditConfig | undefined;
 export declare const createInvocationAudit: (service: AuditService, wire: PikkuWire<any, any, any, CoreUserSession>, logger?: Logger) => AuditLog;
-export declare const resolveAuditActorFromWire: (wire: PikkuWire<any, any, any, CoreUserSession>) => AuditActor | undefined;
+export declare const resolveAuditUserIdentityFromWire: (wire: PikkuWire<any, any, any, CoreUserSession>) => AuditUserIdentity | undefined;

package/dist/services/audit-service.js

@@ -14,8 +14,7 @@ class DisabledInvocationAudit {
     async write(_event) {
         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.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)`);
         }
@@ -76,7 +75,7 @@ class InvocationAuditLog {
             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(),
         };
@@ -99,15 +98,17 @@ export const createInvocationAudit = (service, wire, logger) => {
     }
     return new InvocationAuditLog(wire.audit, service, wire, logger);
 };
-export const resolveAuditActorFromWire = (wire) => {
+export const resolveAuditUserIdentityFromWire = (wire) => {
     const session = wire.session;
-    const actor = {
+    const userIdentity = {
         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/dist/services/content-service.d.ts

@@ -1,23 +1,14 @@
-/**
- * Arguments for signing a content key into a time-limited URL.
- */
 export interface SignContentKeyArgs<TBucket extends string = string> {
     bucket: TBucket;
     contentKey: string;
     dateLessThan: Date;
     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;
@@ -25,66 +16,30 @@ export interface GetUploadURLArgs<TBucket extends string = string> {
     size?: number;
     visibility?: 'private' | 'public';
 }
-/**
- * Result of minting a presigned upload URL.
- */
 export interface UploadURLResult {
     uploadUrl: string;
     assetKey: string;
     uploadHeaders?: Record<string, string>;
     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> {
     fromAbsolutePath: string;
 }
 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>;
 }