@pikku/core 0.12.148 → 0.12.151

package/dist/function/function-runner.js

@@ -4,6 +4,8 @@ import { runMiddleware, combineMiddleware } from '../middleware-runner.js';
 import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../channel-middleware-runner.js';
 import { runPermissions } from '../permissions.js';
 import { withoutSecrets } from '../services/secretless.js';
+import { traceQueueService, traceSchedulerService, traceWebhookService, } from './trace-queue-service.js';
+import { createTrace } from '../trace.js';
 import { getCreateWireServices, pikkuState } from '../pikku-state.js';
 import { applyDefaultsFromSchema, coerceTopLevelDataFromSchema, validateSchema, } from '../schema.js';
 import { parseVersionedId } from '../version.js';
@@ -228,6 +230,12 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
     }
     const resolvedAuditConfig = resolveAuditConfig(funcConfig.audit);
     const invocationWire = resolvedWire;
+    // A wire no runner gave a trace is the root of one.
+    const rootTrace = !invocationWire.trace;
+    if (rootTrace) {
+        invocationWire.trace = createTrace(invocationWire.traceId);
+        invocationWire.traceId = invocationWire.trace.traceId;
+    }
     const previousFunctionId = invocationWire.functionId;
     const previousAudit = invocationWire.audit;
     const previousAddonNamespace = invocationWire.addonNamespace;
@@ -344,6 +352,21 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
                 invocationAuditLog = createInvocationAudit(resolvedSingletonServices.audit, invocationWire, resolvedSingletonServices.logger);
                 services = { ...services, auditLog: invocationAuditLog };
             }
+            services = {
+                ...services,
+                ...(rootTrace && {
+                    logger: services.logger.scope?.(invocationWire.traceId) ?? services.logger,
+                }),
+                ...(services.queueService && {
+                    queueService: traceQueueService(services.queueService, invocationWire),
+                }),
+                ...(services.schedulerService && {
+                    schedulerService: traceSchedulerService(services.schedulerService, invocationWire),
+                }),
+                ...(services.webhookService && {
+                    webhookService: traceWebhookService(services.webhookService, invocationWire),
+                }),
+            };
             // Unconditional, unlike the audit — every function can record. Built on
             // first access, since most invocations record nothing.
             if (!services.analytics) {

package/dist/function/trace-queue-service.d.ts

@@ -0,0 +1,26 @@
+import { type TraceContext } from '../trace.js';
+import type { SchedulerService } from '../services/scheduler-service.js';
+import type { WebhookService } from '../services/webhook-service.js';
+import type { QueueService } from '../wirings/queue/queue.types.js';
+/**
+ * Stamps every job a function enqueues with the function's trace, so neither
+ * the call site nor the generated `PikkuQueue` has to pass it. Read at `add`
+ * time because an authenticated caller can adopt a trace mid-invocation. A
+ * `traceparent` the caller set wins.
+ *
+ * knowledge: decisions/internals/a-job-inherits-the-trace-of-the-function-that-enqueued-it.md
+ */
+export declare const traceQueueService: <Service extends QueueService>(queueService: Service, wire: {
+    trace?: TraceContext;
+}) => Service;
+/** {@link traceQueueService} for one-off delayed RPCs. */
+export declare const traceSchedulerService: <Service extends SchedulerService>(schedulerService: Service, wire: {
+    trace?: TraceContext;
+}) => Service;
+/**
+ * {@link traceQueueService} for outgoing webhooks. The trace rides on the
+ * delivery job and stays out of the request: the receiver is a third party.
+ */
+export declare const traceWebhookService: <Service extends WebhookService>(webhookService: Service, wire: {
+    trace?: TraceContext;
+}) => Service;

package/dist/function/trace-queue-service.js

@@ -0,0 +1,48 @@
+import { outgoingTraceparent } from '../trace.js';
+const passThrough = (target, property) => {
+    const value = Reflect.get(target, property, target);
+    return typeof value === 'function' ? value.bind(target) : value;
+};
+/**
+ * Stamps every job a function enqueues with the function's trace, so neither
+ * the call site nor the generated `PikkuQueue` has to pass it. Read at `add`
+ * time because an authenticated caller can adopt a trace mid-invocation. A
+ * `traceparent` the caller set wins.
+ *
+ * knowledge: decisions/internals/a-job-inherits-the-trace-of-the-function-that-enqueued-it.md
+ */
+export const traceQueueService = (queueService, wire) => new Proxy(queueService, {
+    get(target, property) {
+        if (property === 'add') {
+            return (queueName, data, options) => {
+                const traceparent = options?.traceparent ?? outgoingTraceparent(wire);
+                return target.add(queueName, data, traceparent ? { ...options, traceparent } : options);
+            };
+        }
+        return passThrough(target, property);
+    },
+});
+/** {@link traceQueueService} for one-off delayed RPCs. */
+export const traceSchedulerService = (schedulerService, wire) => new Proxy(schedulerService, {
+    get(target, property) {
+        if (property === 'scheduleRPC') {
+            return (delay, rpcName, data, session, traceparent) => target.scheduleRPC(delay, rpcName, data, session, traceparent ?? outgoingTraceparent(wire));
+        }
+        return passThrough(target, property);
+    },
+});
+/**
+ * {@link traceQueueService} for outgoing webhooks. The trace rides on the
+ * delivery job and stays out of the request: the receiver is a third party.
+ */
+export const traceWebhookService = (webhookService, wire) => new Proxy(webhookService, {
+    get(target, property) {
+        if (property === 'send') {
+            return (input) => target.send({
+                ...input,
+                traceparent: input.traceparent ?? outgoingTraceparent(wire),
+            });
+        }
+        return passThrough(target, property);
+    },
+});

package/dist/mesh.d.ts

@@ -1,8 +1,8 @@
 import type { JWTService } from './services/jwt-service.js';
 import type { SecretService } from './services/secret-service.js';
 /**
- * Authorization headers carrying a JWT-signed session and traceId for
+ * Authorization headers carrying a JWT-signed session and `traceparent` for
  * `pikkuMeshAuthMiddleware` on the receiving end. Used by every deployment
  * service regardless of transport (HTTP, Lambda Invoke, service bindings).
  */
-export declare function buildMeshHeaders(jwt: JWTService | undefined, secrets: SecretService | undefined, funcName: string, session?: unknown, traceId?: string): Promise<Record<string, string>>;
+export declare function buildMeshHeaders(jwt: JWTService | undefined, secrets: SecretService | undefined, funcName: string, session?: unknown, traceparent?: string): Promise<Record<string, string>>;

package/dist/mesh.js

@@ -19,14 +19,14 @@ const readMeshSecret = async (secrets) => {
     }
 };
 /**
- * Authorization headers carrying a JWT-signed session and traceId for
+ * Authorization headers carrying a JWT-signed session and `traceparent` for
  * `pikkuMeshAuthMiddleware` on the receiving end. Used by every deployment
  * service regardless of transport (HTTP, Lambda Invoke, service bindings).
  */
-export async function buildMeshHeaders(jwt, secrets, funcName, session, traceId) {
+export async function buildMeshHeaders(jwt, secrets, funcName, session, traceparent) {
     const headers = {
         'content-type': 'application/json',
-        ...(traceId && { 'x-request-id': traceId }),
+        ...(traceparent && { traceparent }),
     };
     const secret = await readMeshSecret(secrets);
     if (secret && jwt) {

package/dist/middleware/index.d.ts

@@ -5,7 +5,7 @@ export { addonScopeCap, ADDON_HEADER } from './addon-scope-cap.js';
 export { remoteJobsSecret } from './remote-jobs-secret.js';
 export { pikkuMeshAuthMiddleware } from './mesh-auth.js';
 export { cors } from './cors.js';
-export { requireOrigin, isAllowedOrigin, toOrigin } from './require-origin.js';
+export { requireOrigin, isAllowedOrigin, toOrigin, hostOriginOf, allowedOriginsFromVariables, } from './require-origin.js';
 export { telemetryOuter, telemetryInner } from './telemetry.js';
 export { addTagMiddleware, addGlobalMiddleware, runMiddleware, } from '../middleware-runner.js';
 export { addGlobalPermission } from '../permissions.js';

package/dist/middleware/index.js

@@ -5,7 +5,7 @@ export { addonScopeCap, ADDON_HEADER } from './addon-scope-cap.js';
 export { remoteJobsSecret } from './remote-jobs-secret.js';
 export { pikkuMeshAuthMiddleware } from './mesh-auth.js';
 export { cors } from './cors.js';
-export { requireOrigin, isAllowedOrigin, toOrigin } from './require-origin.js';
+export { requireOrigin, isAllowedOrigin, toOrigin, hostOriginOf, allowedOriginsFromVariables, } from './require-origin.js';
 export { telemetryOuter, telemetryInner } from './telemetry.js';
 export { addTagMiddleware, addGlobalMiddleware, runMiddleware, } from '../middleware-runner.js';
 export { addGlobalPermission } from '../permissions.js';

package/dist/middleware/mesh-auth.d.ts

@@ -3,7 +3,8 @@
  * mesh-RPC route. Once `PIKKU_MESH_SECRET` is set it requires a
  * `Bearer` JWT with audience `pikku-mesh`; a token bound to a function (`fn`)
  * is only accepted on that function's `/mesh/rpc/<fn>` path, and any session
- * it carries is decrypted with the secret and set on the wire.
+ * it carries is decrypted with the secret and set on the wire. A verified caller's
+ * `traceparent` is continued, so the trace survives the hop.
  *
  * Without the secret it lets non-mesh paths through and refuses
  * `/mesh/rpc/*`, so the mesh surface fails closed.
@@ -18,7 +19,7 @@ export declare const pikkuMeshAuthMiddleware: import("./middleware.types.js").Co
     secrets?: {
         requireAllowedHosts?: boolean;
     };
-    workflow?: import("../wirings/workflow/workflow.types.js").WorkflowServiceConfig;
+    workflow?: Partial<import("../wirings/workflow/workflow.types.js").WorkflowServiceConfig>;
     webhook?: import("../services/webhook-service.js").WebhookServiceConfig;
     postgres?: import("../types/core.types.js").PostgresConfig;
 }>, import("../types/core.types.js").CoreUserSession>;

package/dist/middleware/mesh-auth.js

@@ -1,5 +1,6 @@
 import { UnauthorizedError } from '../errors/errors.js';
 import { pikkuMiddleware } from './middleware-factories.js';
+import { adoptTraceparent } from '../trace.js';
 import { assertStrongKeyMaterial, decryptWithKeyMaterial, MESH_SESSION_INFO, } from '../crypto-utils.js';
 const MESH_RPC_PREFIX = '/mesh/rpc/';
 /**
@@ -15,7 +16,8 @@ const isMeshRpcPath = (path) => path.toLowerCase().startsWith(MESH_RPC_PREFIX);
  * mesh-RPC route. Once `PIKKU_MESH_SECRET` is set it requires a
  * `Bearer` JWT with audience `pikku-mesh`; a token bound to a function (`fn`)
  * is only accepted on that function's `/mesh/rpc/<fn>` path, and any session
- * it carries is decrypted with the secret and set on the wire.
+ * it carries is decrypted with the secret and set on the wire. A verified caller's
+ * `traceparent` is continued, so the trace survives the hop.
  *
  * Without the secret it lets non-mesh paths through and refuses
  * `/mesh/rpc/*`, so the mesh surface fails closed.
@@ -25,7 +27,8 @@ const isMeshRpcPath = (path) => path.toLowerCase().startsWith(MESH_RPC_PREFIX);
  * @throws {WeakKeyMaterialError} When the secret is too short to use.
  * @throws {Error} When the secret is set but no JWT service is configured.
  */
-export const pikkuMeshAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt }, { http, setInitialSession }, next) => {
+export const pikkuMeshAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt }, wire, next) => {
+    const { http, setInitialSession } = wire;
     if (!http?.request || !secrets) {
         return next();
     }
@@ -81,5 +84,7 @@ export const pikkuMeshAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt },
             throw new UnauthorizedError();
         }
     }
+    // knowledge: decisions/security/inbound-traceparent-is-ignored-until-the-caller-is-authenticated.md
+    adoptTraceparent(wire, http.request.header('traceparent'));
     return next();
 });

package/dist/middleware/remote-jobs-secret.d.ts

@@ -8,7 +8,7 @@ export declare const remoteJobsSecret: import("./middleware.types.js").CorePikku
     secrets?: {
         requireAllowedHosts?: boolean;
     };
-    workflow?: import("../wirings/workflow/workflow.types.js").WorkflowServiceConfig;
+    workflow?: Partial<import("../wirings/workflow/workflow.types.js").WorkflowServiceConfig>;
     webhook?: import("../services/webhook-service.js").WebhookServiceConfig;
     postgres?: import("../types/core.types.js").PostgresConfig;
 }>, import("../types/core.types.js").CoreUserSession>;

package/dist/middleware/require-origin.d.ts

@@ -1,6 +1,25 @@
 import type { CoreSingletonServices } from '../types/core.types.js';
 /** Scheme + host + port, or null for anything unparseable including the literal `"null"` origin. */
 export declare const toOrigin: (value: string | null | undefined) => string | null;
+/**
+ * The origin a request was addressed to, from its `Host` and `X-Forwarded-Proto`.
+ *
+ * With no proxy header the scheme is `http` only when the host is loopback, because a
+ * local dev server speaks plain http and no proxy sits in front of it. Every other host
+ * still defaults to `https`, so a missing header on a real host fails closed.
+ */
+export declare const hostOriginOf: (host: string | null | undefined, forwardedProto?: string | null) => string | null;
+/**
+ * The browser origins an app allows, read from the `variables` service (never
+ * `process.env`, which a Worker does not have): `CORS_ORIGINS` as a comma-separated
+ * list, else `FRONTEND_URL`. Unset means no extra origins, so only the request's own
+ * host is accepted.
+ */
+export declare const allowedOriginsFromVariables: (services: {
+    variables?: {
+        get<T = string>(name: string): Promise<T | undefined> | T | undefined;
+    };
+}) => Promise<string[]>;
 /**
  * Whether a request origin may post to an origin-locked route.
  *

package/dist/middleware/require-origin.js

@@ -12,6 +12,41 @@ export const toOrigin = (value) => {
         return null;
     }
 };
+/** `localhost`, `127.0.0.1` or `[::1]`, with an optional port. Nothing else counts as loopback. */
+const LOOPBACK_HOST = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/i;
+/**
+ * The origin a request was addressed to, from its `Host` and `X-Forwarded-Proto`.
+ *
+ * With no proxy header the scheme is `http` only when the host is loopback, because a
+ * local dev server speaks plain http and no proxy sits in front of it. Every other host
+ * still defaults to `https`, so a missing header on a real host fails closed.
+ */
+export const hostOriginOf = (host, forwardedProto) => {
+    if (!host)
+        return null;
+    const proto = forwardedProto || (LOOPBACK_HOST.test(host) ? 'http' : 'https');
+    return toOrigin(`${proto}://${host}`);
+};
+/**
+ * The browser origins an app allows, read from the `variables` service (never
+ * `process.env`, which a Worker does not have): `CORS_ORIGINS` as a comma-separated
+ * list, else `FRONTEND_URL`. Unset means no extra origins, so only the request's own
+ * host is accepted.
+ */
+export const allowedOriginsFromVariables = async (services) => {
+    const variables = services.variables;
+    if (!variables)
+        return [];
+    const configured = await variables.get('CORS_ORIGINS');
+    if (configured) {
+        return configured
+            .split(',')
+            .map((origin) => origin.trim())
+            .filter(Boolean);
+    }
+    const frontendUrl = await variables.get('FRONTEND_URL');
+    return frontendUrl ? [frontendUrl] : [];
+};
 /**
  * Whether a request origin may post to an origin-locked route.
  *
@@ -46,8 +81,7 @@ export const requireOrigin = pikkuMiddlewareFactory(({ origins = [] } = {}) => p
         const requestOrigin = toOrigin(request.header('origin')) ??
             toOrigin(request.header('referer'));
         const host = request.header('host');
-        const proto = request.header('x-forwarded-proto') ?? 'https';
-        const hostOrigin = host ? toOrigin(`${proto}://${host}`) : null;
+        const hostOrigin = hostOriginOf(host, request.header('x-forwarded-proto'));
         const configured = typeof origins === 'function'
             ? await origins(services)
             : origins;

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

@@ -34,5 +34,5 @@ export interface DeploymentService {
      * (endpoint, service binding), propagating the session (JWT signing,
      * headers) and making the call. Callers supply no transport detail.
      */
-    invoke(funcName: string, data: unknown, session?: unknown, traceId?: string): Promise<unknown>;
+    invoke(funcName: string, data: unknown, session?: unknown, traceparent?: string): Promise<unknown>;
 }

package/dist/services/incoming-webhook-service.d.ts

@@ -39,13 +39,15 @@ export declare class IncomingWebhookService {
     /** How often a failing trigger is retried before the event is given up on. */
     retries?: number);
     /** Returns how many events were queued. A store-backed service drops ones it has already seen. */
-    accept({ source, events, }: {
+    accept({ source, events, traceparent, }: {
         source: string;
         request: WebhookRequest;
         events: TriggerEvent[];
+        /** The trace of the request that delivered the events. */
+        traceparent?: string;
     }): Promise<number>;
     /** The job id is the provider's event id under its event name, which de-duplicates on queues that honour job ids. */
-    protected enqueue(job: WebhookSourceJob): Promise<string>;
+    protected enqueue(job: WebhookSourceJob, traceparent?: string): Promise<string>;
     /** Keeps nothing by default; a store-backed service records each dispatch. */
     recordAttempt(_receiptId: string, _attempt: IncomingWebhookAttempt): Promise<void>;
     /** Most recent first. Empty when nothing is stored. */

package/dist/services/incoming-webhook-service.js

@@ -18,14 +18,14 @@ export class IncomingWebhookService {
         this.retries = retries;
     }
     /** Returns how many events were queued. A store-backed service drops ones it has already seen. */
-    async accept({ source, events, }) {
+    async accept({ source, events, traceparent, }) {
         for (const event of events) {
-            await this.enqueue({ source, event });
+            await this.enqueue({ source, event }, traceparent);
         }
         return events.length;
     }
     /** The job id is the provider's event id under its event name, which de-duplicates on queues that honour job ids. */
-    async enqueue(job) {
+    async enqueue(job, traceparent) {
         const jobId = job.receiptId ??
             (job.event.id
                 ? `${job.source}:${job.event.name}:${job.event.id}`
@@ -35,6 +35,7 @@ export class IncomingWebhookService {
             attempts: this.retries + 1,
             ...(this.retries > 0 ? { backoff: 'exponential' } : {}),
             ...(jobId ? { jobId } : {}),
+            ...(traceparent ? { traceparent } : {}),
         });
     }
     /** Keeps nothing by default; a store-backed service records each dispatch. */

package/dist/services/queue-webhook-service.js

@@ -57,7 +57,13 @@ export class QueueWebhookService extends WebhookService {
             body,
             headers,
         };
-        return { jobData, options: this.resolveJobOptions(input) };
+        return {
+            jobData,
+            options: {
+                ...this.resolveJobOptions(input),
+                ...(input.traceparent ? { traceparent: input.traceparent } : {}),
+            },
+        };
     }
     // knowledge: decisions/internals/queue-jobs-always-carry-an-explicit-attempts-count.md
     resolveJobOptions(input) {

package/dist/services/remote-jobs.d.ts

@@ -11,7 +11,10 @@ export interface RemoteQueueJobData {
     queueName: string;
     data?: unknown;
     jobId?: string;
-    traceId?: string;
+    /** The W3C trace to continue. Invalid or absent starts a new trace. */
+    traceparent?: string;
+    /** The signed identity claim. {@link runQueueJob} verifies it or drops it. */
+    pikkuUserId?: string;
 }
 /**
  * A scheduled task run delivered over HTTP to {@link
@@ -19,4 +22,6 @@ export interface RemoteQueueJobData {
  */
 export interface RemoteScheduledJobData {
     taskName: string;
+    /** The W3C trace to continue. Invalid or absent starts a new trace. */
+    traceparent?: string;
 }

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

@@ -26,7 +26,9 @@ export interface ScheduledTaskInfo extends ScheduledTaskSummary {
 export declare abstract class SchedulerService {
     abstract init(): Promise<void>;
     /** `delay` is milliseconds as a number, or a duration string such as `"5h"` / `"30m"`. */
-    abstract scheduleRPC(delay: number | string, rpcName: string, data?: any, session?: CoreUserSession): Promise<string>;
+    abstract scheduleRPC(delay: number | string, rpcName: string, data?: any, session?: CoreUserSession, 
+    /** The W3C trace the RPC continues when it fires. */
+    traceparent?: string): Promise<string>;
     abstract unschedule(taskId: string): Promise<boolean>;
     abstract getTask(taskId: string): Promise<ScheduledTaskInfo | null>;
     abstract getAllTasks(): Promise<ScheduledTaskSummary[]>;

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

@@ -14,6 +14,8 @@ export interface SendWebhookInput {
     retryDelay?: string | number;
     /** Persisted only by store-backed implementations; the queue-only default ignores it. */
     organizationId?: string;
+    /** The trace the delivery job runs in. A function's calls are stamped for it. */
+    traceparent?: string;
 }
 /** The queue job that will deliver the webhook. */
 export interface SendWebhookResult {

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

@@ -1,6 +1,6 @@
 import type { CoreUserSession } from '../types/core.types.js';
 import type { SerializedError } from '../errors/serialized-error.js';
-import type { WorkflowRun, WorkflowPlannedStep, WorkflowRunWire, WorkflowRunStatus, StepState, WorkflowStatus, WorkflowVersionStatus } from '../wirings/workflow/workflow.types.js';
+import type { WorkflowRun, WorkflowPlannedStep, WorkflowRunWire, WorkflowRunStatus, StepState, WorkflowRecoveryOptions, WorkflowStatus, WorkflowVersionStatus } from '../wirings/workflow/workflow.types.js';
 import type { RunTimeline, ReconstructedRunState } from '../wirings/workflow/run-timeline.js';
 /**
  * Stores and drives workflow runs, provided as the `workflowService` singleton
@@ -10,6 +10,9 @@ import type { RunTimeline, ReconstructedRunState } from '../wirings/workflow/run
  */
 export interface WorkflowService {
     wireQueueWorkers?(): void;
+    /** Sweep for work a dead process left behind, now and on an interval. */
+    startRecovery?(options?: WorkflowRecoveryOptions | false): void;
+    stopRecovery?(): void;
     createRun(workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire, options?: {
         deterministic?: boolean;
         plannedSteps?: WorkflowPlannedStep[];

package/dist/testing/index.d.ts

@@ -1,4 +1,8 @@
 export { defineServiceTests } from './service-tests.js';
 export type { ServiceTestConfig } from './service-tests.js';
 export type { WorkflowFencingHarness } from './service-tests/workflow-fencing-tests.js';
+export { defineQueueIdentityTransportTests } from './queue-identity-transport-tests.js';
+export type { QueueIdentityTransport } from './queue-identity-transport-tests.js';
 export { clearPikkuRuntimeState } from '../test-utils.js';
+export { defineQueueTraceConformance } from './queue-trace-conformance.js';
+export type { QueueTraceAdapter } from './queue-trace-conformance.js';

package/dist/testing/index.js

@@ -1,2 +1,4 @@
 export { defineServiceTests } from './service-tests.js';
+export { defineQueueIdentityTransportTests } from './queue-identity-transport-tests.js';
 export { clearPikkuRuntimeState } from '../test-utils.js';
+export { defineQueueTraceConformance } from './queue-trace-conformance.js';

package/dist/testing/queue-identity-transport-tests.d.ts

@@ -0,0 +1,18 @@
+import type { CoreSingletonServices } from '../types/core.types.js';
+import type { QueueService } from '../wirings/queue/queue.types.js';
+/** One adapter, cut at the broker: what `queueService` sent, `deliver` consumes. */
+export interface QueueIdentityTransport {
+    queueService: QueueService;
+    /** Runs everything sent so far through the adapter's real consumer path. */
+    deliver: () => Promise<void>;
+}
+/**
+ * Conformance for carrying a job's identity claim through an adapter: a signed
+ * claim reaches the worker with the user's session, and an unsigned, forged or
+ * misbound one leaves the job running as nobody.
+ *
+ * @param name - The adapter, for the test names.
+ * @param create - Builds the adapter. Gets the singleton services its consumer
+ *   has to run under.
+ */
+export declare const defineQueueIdentityTransportTests: (name: string, create: (services: CoreSingletonServices) => QueueIdentityTransport) => void;

package/dist/testing/queue-identity-transport-tests.js

@@ -0,0 +1,162 @@
+import assert from 'node:assert/strict';
+import { before, beforeEach, describe, test } from 'node:test';
+import { createSecretValue } from '../classification/secret-value.js';
+import { pikkuState } from '../pikku-state.js';
+import { QUEUE_IDENTITY_SECRET_NAME, signQueueIdentity, } from '../wirings/queue/queue-identity.js';
+import { wireQueueWorker } from '../wirings/queue/queue-runner.js';
+import { SignedQueueService } from '../wirings/queue/signed-queue-service.js';
+const QUEUE_NAME = 'identity-transport';
+const SECRET = 'a'.repeat(48);
+const OTHER_SECRET = 'b'.repeat(48);
+const USER = 'user-1';
+const SESSION = { userId: USER };
+const DATA = { message: 'hello', nested: { n: 1 } };
+const TRACE_ID = 'a'.repeat(32);
+const TRACEPARENT = `00-${TRACE_ID}-${'b'.repeat(16)}-01`;
+/**
+ * Conformance for carrying a job's identity claim through an adapter: a signed
+ * claim reaches the worker with the user's session, and an unsigned, forged or
+ * misbound one leaves the job running as nobody.
+ *
+ * @param name - The adapter, for the test names.
+ * @param create - Builds the adapter. Gets the singleton services its consumer
+ *   has to run under.
+ */
+export const defineQueueIdentityTransportTests = (name, create) => {
+    describe(`queue identity transport [${name}]`, () => {
+        const runs = [];
+        const logger = {
+            info: () => { },
+            warn: () => { },
+            error: () => { },
+            debug: () => { },
+        };
+        const secrets = {
+            getSecret: async () => createSecretValue(SECRET),
+            hasSecret: async (key) => key === QUEUE_IDENTITY_SECRET_NAME,
+        };
+        const services = {
+            logger,
+            secrets,
+            sessionStore: {
+                get: async (id) => (id === USER ? SESSION : undefined),
+            },
+        };
+        let transport;
+        before(() => {
+            pikkuState(null, 'queue', 'meta')[QUEUE_NAME] = {
+                pikkuFuncId: `queue_${QUEUE_NAME}`,
+                name: QUEUE_NAME,
+            };
+            pikkuState(null, 'function', 'meta')[`queue_${QUEUE_NAME}`] = {
+                pikkuFuncId: `queue_${QUEUE_NAME}`,
+                inputSchemaName: null,
+                outputSchemaName: null,
+                sessionless: true,
+            };
+            wireQueueWorker({
+                name: QUEUE_NAME,
+                func: {
+                    auth: false,
+                    func: async (_services, data, wire) => {
+                        runs.push({
+                            data,
+                            pikkuUserId: wire.pikkuUserId,
+                            session: wire.session,
+                            traceId: wire.traceId,
+                        });
+                    },
+                },
+            });
+            transport = create(services);
+        });
+        beforeEach(() => {
+            runs.length = 0;
+            pikkuState(null, 'package', 'singletonServices', services);
+        });
+        const deliverOne = async () => {
+            await transport.deliver();
+            assert.equal(runs.length, 1, 'the job ran once');
+            return runs[0];
+        };
+        const assertRanAsNobody = async () => {
+            const run = await deliverOne();
+            assert.equal(run.pikkuUserId, undefined);
+            assert.equal(run.session, undefined);
+            return run;
+        };
+        test('a signed claim reaches the worker with the session', async () => {
+            await new SignedQueueService(transport.queueService, secrets, logger).add(QUEUE_NAME, DATA, { pikkuUserId: USER });
+            const run = await deliverOne();
+            assert.equal(run.pikkuUserId, USER);
+            assert.deepEqual(run.session, SESSION);
+            assert.deepEqual(run.data, DATA);
+        });
+        test('the identity and the trace travel together', async () => {
+            await new SignedQueueService(transport.queueService, secrets, logger).add(QUEUE_NAME, DATA, { pikkuUserId: USER, traceparent: TRACEPARENT });
+            const run = await deliverOne();
+            assert.equal(run.pikkuUserId, USER);
+            assert.equal(run.traceId, TRACE_ID);
+            assert.deepEqual(run.data, DATA);
+        });
+        test('a job with no claim runs as nobody', async () => {
+            await transport.queueService.add(QUEUE_NAME, DATA);
+            const run = await assertRanAsNobody();
+            assert.deepEqual(run.data, DATA);
+        });
+        test('an unsigned claim is dropped', async () => {
+            await transport.queueService.add(QUEUE_NAME, DATA, { pikkuUserId: USER });
+            const run = await assertRanAsNobody();
+            assert.deepEqual(run.data, DATA);
+        });
+        test('a claim signed with another secret is dropped', async () => {
+            await transport.queueService.add(QUEUE_NAME, DATA, {
+                pikkuUserId: await signQueueIdentity(OTHER_SECRET, USER, {
+                    queueName: QUEUE_NAME,
+                    data: DATA,
+                }),
+            });
+            await assertRanAsNobody();
+        });
+        test('a tampered claim is dropped', async () => {
+            const [version, , signature] = (await signQueueIdentity(SECRET, 'someone-else', {
+                queueName: QUEUE_NAME,
+                data: DATA,
+            })).split('.');
+            const [, claim] = (await signQueueIdentity(SECRET, USER, {
+                queueName: QUEUE_NAME,
+                data: DATA,
+            })).split('.');
+            await transport.queueService.add(QUEUE_NAME, DATA, {
+                pikkuUserId: `${version}.${claim}.${signature}`,
+            });
+            await assertRanAsNobody();
+        });
+        test('a claim signed for another payload is dropped', async () => {
+            await transport.queueService.add(QUEUE_NAME, DATA, {
+                pikkuUserId: await signQueueIdentity(SECRET, USER, {
+                    queueName: QUEUE_NAME,
+                    data: { message: 'other' },
+                }),
+            });
+            await assertRanAsNobody();
+        });
+        test('a claim signed for another queue is dropped', async () => {
+            await transport.queueService.add(QUEUE_NAME, DATA, {
+                pikkuUserId: await signQueueIdentity(SECRET, USER, {
+                    queueName: 'another-queue',
+                    data: DATA,
+                }),
+            });
+            await assertRanAsNobody();
+        });
+        test('identity fields inside the payload grant nothing', async () => {
+            await transport.queueService.add(QUEUE_NAME, {
+                pikkuUserId: USER,
+                __pikkuUserId: USER,
+                data: DATA,
+            });
+            await assertRanAsNobody();
+        });
+    });
+};