@pikku/core 0.12.74 → 0.12.78

package/dist/function/functions.types.d.ts

@@ -4,13 +4,14 @@ import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { PikkuError } from '../errors/error-handler.js';
 import type { CoreNodeConfig } from '../wirings/node/node.types.js';
 import type { ScenarioSurface } from '../wirings/workflow/scenario-step.types.js';
+import type { Safe } from '../secret-value.js';
 /**
  * @deprecated Use StandardSchemaV1 from @standard-schema/spec instead.
  * This alias exists only for backward compatibility with generated code.
  */
 export type ZodLike<T = any> = StandardSchemaV1<T, T>;
-export type CorePikkuFunction<In, Out, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession, Wire extends PikkuWire<In, Out, true, Session, PikkuRPC, null, string> = PikkuWire<In, Out, true, Session>> = (services: Services, data: In, wire: Wire) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>;
-export type CorePikkuFunctionSessionless<In, Out, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession, Wire extends PikkuWire<In, Out, false, Session, PikkuRPC, null, string> = PikkuWire<In, Out, false, Session>> = (services: Services, data: In, wire: Wire) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>;
+export type CorePikkuFunction<In, Out, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession, Wire extends PikkuWire<In, Out, true, Session, PikkuRPC, null, string> = PikkuWire<In, Out, true, Session>> = (services: Services, data: In, wire: Wire) => Wire['channel'] extends null ? Promise<Safe<Out>> : Promise<Safe<Out>> | Promise<void>;
+export type CorePikkuFunctionSessionless<In, Out, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession, Wire extends PikkuWire<In, Out, false, Session, PikkuRPC, null, string> = PikkuWire<In, Out, false, Session>> = (services: Services, data: In, wire: Wire) => Wire['channel'] extends null ? Promise<Safe<Out>> : Promise<Safe<Out>> | Promise<void>;
 export type CorePikkuPermission<In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> = PikkuWire<In, never, false, any, PikkuRPC, never, never>> = (services: Services, data: In, wire: Wire) => Promise<boolean>;
 export type CorePikkuPermissionConfig<In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> = PikkuWire<In, never, false, any, PikkuRPC, never, never>> = {
     func: CorePikkuPermission<In, Services, Wire>;
@@ -49,16 +50,18 @@ export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any,
     tags?: string[];
     expose?: boolean;
     /**
-     * The function performs its own authorization in its body — verifying a
+     * The permission check for this function lives in its body — verifying a
      * signed token, checking a webhook signature, matching an invite code — so
-     * it is not open despite carrying no session, scope or permission.
+     * it is not open despite declaring no session, scope or permission.
      *
-     * Purely declarative: nothing at runtime reads it, and it grants nothing. It
-     * exists so the claim is written down where an audit can find it, and so
-     * codegen stops warning about a gate it has no way to see. Asserting it
-     * falsely disables the one check that would have caught the mistake.
+     * A last resort. Prefer `permissions`, which are declared, inspectable, and
+     * reusable; reach for this only when the check cannot be expressed as one.
+     *
+     * Purely declarative — it grants nothing, and asserting it falsely disables
+     * the audit that would have caught the mistake. Requires
+     * `allow.permissionsInBody` in `pikku.config.json`.
      */
-    selfAuthenticated?: boolean;
+    permissionsInBody?: boolean;
     remote?: boolean;
     mcp?: boolean;
     readonly?: boolean;
@@ -103,7 +106,8 @@ export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any,
      * Scopes the session must hold; all are required (AND) and checked before
      * `permissions`, which OR together — a scope can only narrow access.
      * Narrowed to the generated `ScopeId` union, so an undeclared scope is a
-     * compile error.
+     * compile error. Requires a session — see
+     * {@link CorePikkuSessionlessFunctionConfig}.
      */
     scopes?: Scope[];
     permissions?: CorePermissionGroup<PikkuPermission>;
@@ -113,3 +117,12 @@ export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any,
     node?: CoreNodeConfig;
     errors?: Array<typeof PikkuError>;
 };
+/**
+ * {@link CorePikkuFunctionConfig} for a function that runs without a session.
+ *
+ * Identical, minus `scopes`. Scopes are AND-ed and `verifyScopes` fails closed,
+ * so an anonymous caller holds none and satisfies none — a sessionless function
+ * with scopes rejects every caller it exists to serve. Gate it with
+ * `permissions`, which receive the optional session and may pass anonymous.
+ */
+export type CorePikkuSessionlessFunctionConfig<PikkuFunction extends CorePikkuFunctionSessionless<any, any, any, any, any>, PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>, InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined> = Omit<CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware, InputSchema, OutputSchema>, 'scopes'>;

package/dist/function/index.d.ts

@@ -1,4 +1,4 @@
 export { addFunction, getAllFunctionNames } from './function-runner.js';
 export { pikkuAuth, pikkuPermission, pikkuPermissionFactory, pikkuApprovalDescription, } from './functions.types.js';
-export type { CorePikkuFunction, CorePikkuFunctionSessionless, CorePikkuFunctionConfig, CorePikkuAuth, CorePikkuAuthConfig, CorePikkuPermission, } from './functions.types.js';
+export type { CorePikkuFunction, CorePikkuFunctionSessionless, CorePikkuFunctionConfig, CorePikkuSessionlessFunctionConfig, CorePikkuAuth, CorePikkuAuthConfig, CorePikkuPermission, } from './functions.types.js';
 export type { ListInput, ListOutput, Filter, LeafFilter, LeafValue, } from './list.types.js';

package/dist/index.d.ts

@@ -36,8 +36,8 @@ export type { GatewayService } from './services/gateway-service.js';
 export type { TriggerService } from './services/trigger-service.js';
 export type { SchemaService } from './services/schema-service.js';
 export type { SessionService } from './services/user-session-service.js';
-export { NoopAuditService, createInvocationAudit, resolveAuditActorFromWire, resolveAuditConfig, } from './services/audit-service.js';
-export type { AuditActor, AuditConfig, AuditDurability, AuditEvent, AuditEventBatch, AuditLog, AuditLogWriteInput, AuditOutcome, AuditService, AuditSource, ResolvedAuditConfig, } from './services/audit-service.js';
+export { NoopAuditService, createInvocationAudit, resolveAuditConfig, resolveAuditUserIdentityFromWire, } from './services/audit-service.js';
+export type { AuditConfig, AuditDurability, AuditEvent, AuditEventBatch, AuditFacets, AuditLog, AuditLogWriteInput, AuditOutcome, AuditQuery, AuditQueryResult, AuditService, AuditSource, AuditUserIdentity, ResolvedAuditConfig, } from './services/audit-service.js';
 export type { AIAgentRunnerService, AIEmbedManyParams, AIEmbedManyResult, AIEmbedParams, AIEmbedResult, AIGenerateImageParams, AIGenerateImagePrompt, AIGenerateImageResult, AIGenerateSpeechParams, AIGenerateSpeechResult, AIProviderOptions, AIRerankParams, AIRerankResult, AITranscriptionParams, AITranscriptionResult, } from './services/ai-agent-runner-service.js';
 export type { AIEmbeddingService } from './services/ai-embedding-service.js';
 export type { AIRunStateService } from './services/ai-run-state-service.js';
@@ -59,4 +59,7 @@ export { getSingletonServices, getCreateWireServices, setSingletonServices, } fr
 export { clearPikkuRuntimeState } from './test-utils.js';
 export { type ScheduledTaskInfo, type ScheduledTaskSummary, } from './services/scheduler-service.js';
 export { SchedulerService } from './services/scheduler-service.js';
-export type { Private, Pii, Secret, Classification, AnonymizeStrategy, ColumnClassification, ClassificationManifest, } from './data-classification.js';
+export type { Private, Pii, Secret, Classification, AnonymizeStrategy, ColumnClassification, ClassificationManifest, ColumnForm, WrappedValue, SealedValue, HashedValue, } from './data-classification.js';
+export { hashToken, unsafeAsWrapped, unsafeAsSealed, unsafeAsHashed, } from './column-form.js';
+export type { SecretValue, Safe } from './secret-value.js';
+export { createSecretValue, isSecretValue, SecretCoercionError, REDACTED, } from './secret-value.js';

package/dist/index.js

@@ -15,7 +15,7 @@ export { AIProviderAuthError, AIProviderNotConfiguredError, BadGatewayError, Bad
 export { PikkuError, isExpectedError } from './errors/error-handler.js';
 export { SecretAccessDeniedError, withoutSecrets, } from './services/secretless.js';
 export { SecretHostNotAllowedError, assertSecretAllowedForHost, } from './services/secret-host-binding.js';
-export { NoopAuditService, createInvocationAudit, resolveAuditActorFromWire, resolveAuditConfig, } from './services/audit-service.js';
+export { NoopAuditService, createInvocationAudit, resolveAuditConfig, resolveAuditUserIdentityFromWire, } from './services/audit-service.js';
 export { createGraph } from './wirings/workflow/graph/graph-node.js';
 export { wireAddon } from './wirings/rpc/wire-addon.js';
 export { wireRemoteAddon } from './wirings/rpc/wire-remote-addon.js';
@@ -26,3 +26,5 @@ export { isSerializable, stopSingletonServices, pikkuServerLifecycle, } from './
 export { getSingletonServices, getCreateWireServices, setSingletonServices, } from './pikku-state.js';
 export { clearPikkuRuntimeState } from './test-utils.js';
 export { SchedulerService } from './services/scheduler-service.js';
+export { hashToken, unsafeAsWrapped, unsafeAsSealed, unsafeAsHashed, } from './column-form.js';
+export { createSecretValue, isSecretValue, SecretCoercionError, REDACTED, } from './secret-value.js';

package/dist/middleware/auth-bearer.js

@@ -33,9 +33,10 @@ export const authBearer = pikkuMiddlewareFactory(({ token } = {}) => pikkuMiddle
             }
             else {
                 // An unset secret means the feature is off — never a request error.
-                expected = await secrets
+                const stored = await secrets
                     ?.getSecret(token.secretId)
                     .catch(() => undefined);
+                expected = stored?.reveal();
             }
             if (expected && constantTimeEqual(bearerToken, expected)) {
                 userSession = token.userSession;

package/dist/middleware/remote-auth.js

@@ -7,7 +7,7 @@ export const pikkuRemoteAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt }
     }
     let secret;
     try {
-        secret = await secrets.getSecret('PIKKU_REMOTE_SECRET');
+        secret = (await secrets.getSecret('PIKKU_REMOTE_SECRET')).reveal();
     }
     catch {
         if (http.request.path().startsWith('/remote/rpc/')) {

package/dist/remote.js

@@ -11,7 +11,7 @@ export async function buildRemoteHeaders(jwt, secrets, funcName, session, traceI
     };
     let secret;
     try {
-        secret = await secrets?.getSecret('PIKKU_REMOTE_SECRET');
+        secret = (await secrets?.getSecret('PIKKU_REMOTE_SECRET'))?.reveal();
     }
     catch { }
     if (secret && jwt) {

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

@@ -75,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(),
         };
@@ -98,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/credential-wire-service.d.ts

@@ -9,6 +9,11 @@ export declare class PikkuCredentialWireService {
     private loadPromise;
     constructor(credentialService?: CredentialService | undefined, wire?: PikkuRawWire | undefined, aliases?: Record<string, string> | undefined);
     private resolveName;
+    /**
+     * 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;
     get<T = unknown>(name: string): T | null | Promise<T | null>;
     getAll(): Record<string, unknown> | Promise<Record<string, unknown>>;

package/dist/services/credential-wire-service.js

@@ -1,3 +1,4 @@
+import { isSecretValue } from '../secret-value.js';
 import { defaultPikkuUserIdResolver } from './pikku-user-id.js';
 export class PikkuCredentialWireService {
     credentialService;
@@ -14,8 +15,15 @@ export class PikkuCredentialWireService {
     resolveName(name) {
         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, value) {
-        this.credentials[this.resolveName(name)] = value;
+        this.credentials[this.resolveName(name)] = isSecretValue(value)
+            ? value.reveal()
+            : value;
     }
     get(name) {
         const key = this.resolveName(name);

package/dist/services/email-service.d.ts

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

package/dist/services/in-memory-workflow-service.d.ts

@@ -29,6 +29,7 @@ export declare class InMemoryWorkflowService extends PikkuWorkflowService implem
     protected setStepErrorImpl(stepId: string, error: Error): Promise<void>;
     protected setStepChildRunIdImpl(stepId: string, childRunId: string): Promise<void>;
     protected createRetryAttemptImpl(failedStepId: string, status: 'pending' | 'running'): Promise<StepState>;
+    protected findStalledRunIds(before: Date, limit: number): Promise<string[]>;
     listRuns(options?: {
         workflowName?: string;
         status?: string;

package/dist/services/in-memory-workflow-service.js

@@ -199,6 +199,26 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         this.stepHistory.set(runId, history);
         return newStep;
     }
+    async findStalledRunIds(before, limit) {
+        const stalled = [];
+        for (const [runId, run] of this.runs) {
+            if (run.status !== 'running')
+                continue;
+            const steps = this.stepHistory.get(runId) ?? [];
+            if (steps.some((step) => step.status === 'running' ||
+                step.status === 'scheduled' ||
+                step.status === 'suspended')) {
+                continue;
+            }
+            const lastActivity = steps.reduce((latest, step) => (step.updatedAt > latest ? step.updatedAt : latest), run.updatedAt);
+            if (lastActivity >= before)
+                continue;
+            stalled.push(runId);
+            if (stalled.length >= limit)
+                break;
+        }
+        return stalled;
+    }
     async listRuns(options) {
         let runs = Array.from(this.runs.values());
         if (options?.workflowName) {

package/dist/services/index.d.ts

@@ -22,7 +22,7 @@ export type { JWTService } from './jwt-service.js';
 export type { EmailService, EmailTemplateReference, SendEmailInput, SendEmailResult, SendHTMLEmailInput, 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 { SecretService, SecretValues } from './secret-service.js';
 export type { VariablesService } from './variables-service.js';
 export type { SchemaService } from './schema-service.js';
 export type { SessionService } from './user-session-service.js';
@@ -44,8 +44,8 @@ export type { SessionStore } from './session-store.js';
 export type { ScopeService, Role } from './scope-service.js';
 export { assertRoleIsMutable, assertRoleNameAvailable, roleLockReason, } from './system-role-guard.js';
 export type { IsSystemRole } from './system-role-guard.js';
-export { NoopAuditService, createInvocationAudit, resolveAuditActorFromWire, resolveAuditConfig, } from './audit-service.js';
-export type { AuditActor, AuditConfig, AuditDurability, AuditEvent, AuditEventBatch, AuditLog, AuditLogWriteInput, AuditOutcome, AuditService, AuditSource, ResolvedAuditConfig, } from './audit-service.js';
+export { NoopAuditService, createInvocationAudit, resolveAuditConfig, resolveAuditUserIdentityFromWire, } from './audit-service.js';
+export type { AuditConfig, AuditDurability, AuditEvent, AuditEventBatch, AuditLog, AuditLogWriteInput, AuditOutcome, AuditService, AuditSource, AuditUserIdentity, ResolvedAuditConfig, } from './audit-service.js';
 export { InMemorySessionStore } from './in-memory-session-store.js';
 export type { MCPMeta, RPCMetaRecord, ServiceMeta, ServicesMetaRecord, MiddlewareDefinitionMeta, MiddlewareInstanceMeta, GroupMeta, MiddlewareGroupsMeta, PermissionDefinitionMeta, PermissionsGroupsMeta, FunctionsMeta, FunctionMeta, MiddlewareMeta, PermissionMeta, AgentsMeta, AgentMeta, EmailsMeta, EmailTemplateMeta, EmailTemplateLocaleMeta, EmailTemplateAssets, } from './meta-service.js';
 export type { CoverageService, CoverageSnapshot, LineHits, ScriptCoverage, FunctionCoverage, CoverageRange, CoverageStatus, FunctionCoverageEntry, FunctionCoverageReport, CoverageFunctionMeta, } from './v8-coverage-service.js';

package/dist/services/index.js

@@ -18,7 +18,7 @@ export { LocalGatewayService } from './local-gateway-service.js';
 export { DEFAULT_WEBHOOK_RETRIES, DEFAULT_WEBHOOK_SIGNATURE_HEADER, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, } from './webhook-service.js';
 export { TypedCredentialService } from './typed-credential-service.js';
 export { assertRoleIsMutable, assertRoleNameAvailable, roleLockReason, } from './system-role-guard.js';
-export { NoopAuditService, createInvocationAudit, resolveAuditActorFromWire, resolveAuditConfig, } from './audit-service.js';
+export { NoopAuditService, createInvocationAudit, resolveAuditConfig, resolveAuditUserIdentityFromWire, } from './audit-service.js';
 export { InMemorySessionStore } from './in-memory-session-store.js';
 export { StubTracker, createStubProxy, getStubTracker, isTestRun, stub, spy, } from './stub-tracker.js';
 export { SecretHostNotAllowedError, assertSecretAllowedForHost, } from './secret-host-binding.js';

package/dist/services/local-content-request-handler.d.ts

@@ -0,0 +1,29 @@
+import type { JWTService, Logger } from '@pikku/core/services';
+import { type LocalContentConfig } from './local-content.js';
+/**
+ * The server half of {@link LocalContent}.
+ *
+ * `LocalContent` hands out `PUT <uploadUrlPrefix>/<key>` upload URLs and signed
+ * `GET <assetUrlPrefix>/<key>` read URLs, but it cannot answer either: it is a
+ * `ContentService`, not a transport. Something in the serving path has to, and
+ * until now only `@pikku/node-http-server` did — so the very same project served
+ * under Bun handed the browser upload URLs that 404ed, with nothing naming the
+ * cause.
+ *
+ * Expressed in Web `Request`/`Response` so every runtime can share one
+ * implementation rather than each re-deriving the signature check. Returns
+ * `null` for anything that is not a content request, which is the caller's
+ * signal to carry on with its normal routing.
+ */
+export type LocalContentRequestHandler = (request: Request) => Promise<Response | null>;
+export type LocalContentRequestHandlerOptions = {
+    content: LocalContentConfig;
+    logger: Logger;
+    /**
+     * Resolved per request rather than passed by value: a runtime may only be
+     * able to reach the signing service through `singletonServices`, which is not
+     * populated until after the server is constructed.
+     */
+    getJWT: () => JWTService | undefined;
+};
+export declare const createLocalContentRequestHandler: ({ content, logger, getJWT, }: LocalContentRequestHandlerOptions) => LocalContentRequestHandler;