@pikku/core 0.12.130 → 0.12.133

package/dist/testing/service-tests/lease-service-tests.js

@@ -0,0 +1,138 @@
+import { describe, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { holdLease, } from '../../services/lease-service.js';
+const HOUR = 60 * 60 * 1000;
+/**
+ * A lease a test lets lapse, and the lease `holdLease` renews. Both leave room
+ * for a real database's round-trips: a lease has to outlive the statement that
+ * writes it and the one that reads it back.
+ */
+const SHORT = 500;
+const RENEWED = 1_000;
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Conformance suite for `leaseService`. Each test gets a fresh service. */
+export const defineLeaseServiceTests = (name, create) => {
+    describe(`LeaseService [${name}]`, () => {
+        test('one holder at a time', async () => {
+            const leases = await create();
+            const a = await leases.acquire('stage', 'a', HOUR);
+            assert.equal(a?.holder, 'a');
+            assert.equal(a?.token, 1);
+            assert.equal(await leases.acquire('stage', 'b', HOUR), null);
+            assert.equal((await leases.get('stage'))?.holder, 'a');
+        });
+        test('keys are independent', async () => {
+            const leases = await create();
+            await leases.acquire('one', 'a', HOUR);
+            assert.equal((await leases.acquire('two', 'b', HOUR))?.holder, 'b');
+        });
+        test('the holder re-acquires under the same token', async () => {
+            const leases = await create();
+            const first = await leases.acquire('stage', 'a', SHORT);
+            const again = await leases.acquire('stage', 'a', HOUR);
+            assert.equal(again?.token, first?.token);
+            assert.ok(again.expiresAt > first.expiresAt);
+        });
+        test('a lapsed lease passes to the next holder with a higher token', async () => {
+            const leases = await create();
+            const a = await leases.acquire('stage', 'a', SHORT);
+            await wait(2 * SHORT);
+            const b = await leases.acquire('stage', 'b', HOUR);
+            assert.equal(b?.holder, 'b');
+            assert.equal(b?.token, a.token + 1);
+            assert.equal(await leases.refresh(a, HOUR), null);
+        });
+        test('release frees the key and the token keeps rising', async () => {
+            const leases = await create();
+            const a = await leases.acquire('stage', 'a', HOUR);
+            await leases.release(a);
+            assert.equal(await leases.get('stage'), null);
+            const b = await leases.acquire('stage', 'b', HOUR);
+            assert.equal(b?.token, a.token + 1);
+        });
+        test('a stale lease cannot refresh or release the new holder', async () => {
+            const leases = await create();
+            const a = await leases.acquire('stage', 'a', SHORT);
+            await wait(2 * SHORT);
+            await leases.acquire('stage', 'b', HOUR);
+            await leases.release(a);
+            assert.equal((await leases.get('stage'))?.holder, 'b');
+        });
+        test('refresh extends a live lease', async () => {
+            const leases = await create();
+            const a = await leases.acquire('stage', 'a', SHORT);
+            const refreshed = await leases.refresh(a, HOUR);
+            assert.equal(refreshed?.token, a.token);
+            await wait(2 * SHORT);
+            assert.equal(await leases.acquire('stage', 'b', HOUR), null);
+        });
+        test('concurrent acquires admit exactly one holder', async () => {
+            const leases = await create();
+            const results = await Promise.all(['a', 'b', 'c', 'd', 'e'].map((holder) => leases.acquire('stage', holder, HOUR)));
+            assert.equal(results.filter(Boolean).length, 1);
+        });
+        test('holdLease hands the body its lease and frees the key', async () => {
+            const leases = await create();
+            let seen;
+            const result = await holdLease(leases, 'stage', async (lease) => {
+                seen = lease;
+                return 42;
+            });
+            assert.equal(result, 42);
+            assert.equal(seen?.key, 'stage');
+            assert.equal(await leases.get('stage'), null);
+        });
+        test('holdLease refuses a taken key', async () => {
+            const leases = await create();
+            await leases.acquire('stage', 'a', HOUR);
+            await assert.rejects(holdLease(leases, 'stage', async () => { }), (err) => err.name === 'LeaseTakenError');
+        });
+        test('holdLease frees the key when the body throws', async () => {
+            const leases = await create();
+            await assert.rejects(holdLease(leases, 'stage', async () => {
+                throw new Error('boom');
+            }), /boom/);
+            assert.equal(await leases.get('stage'), null);
+        });
+        test('holdLease refuses to vouch for a body that outlived its lease', async () => {
+            const leases = await create();
+            await assert.rejects(holdLease(leases, 'stage', async (lease) => {
+                await leases.release(lease);
+                assert.ok(await leases.acquire('stage', 'other', HOUR));
+                await wait(RENEWED);
+                return 'unprotected';
+            }, RENEWED), (err) => err.name === 'LeaseLostError');
+            assert.equal((await leases.get('stage'))?.holder, 'other');
+        });
+        test('holdLease notices a lease lost after its last renewal', async () => {
+            const leases = await create();
+            await assert.rejects(holdLease(leases, 'stage', async (lease) => {
+                await leases.release(lease);
+                assert.ok(await leases.acquire('stage', 'other', HOUR));
+                return 'finished before any renewal ran';
+            }), (err) => err.name === 'LeaseLostError');
+            assert.equal((await leases.get('stage'))?.holder, 'other');
+        });
+        test('holdLease aborts the body once its lease is lost', async () => {
+            const leases = await create();
+            let aborted = false;
+            await assert.rejects(holdLease(leases, 'stage', async (lease, signal) => {
+                await leases.release(lease);
+                assert.ok(await leases.acquire('stage', 'other', HOUR));
+                await new Promise((resolve) => {
+                    signal.addEventListener('abort', () => resolve());
+                    setTimeout(resolve, 5 * RENEWED);
+                });
+                aborted = signal.aborted;
+            }, RENEWED), (err) => err.name === 'LeaseLostError');
+            assert.equal(aborted, true, 'the body was never told its lease was gone');
+        });
+        test('holdLease keeps the lease alive past its ttl', async () => {
+            const leases = await create();
+            await holdLease(leases, 'stage', async () => {
+                await wait(2 * RENEWED);
+                assert.ok(await leases.get('stage'), 'the lease lapsed mid-body');
+            }, RENEWED);
+        });
+    });
+};

package/dist/testing/service-tests/workflow-fencing-tests.d.ts

@@ -0,0 +1,18 @@
+import type { PikkuWorkflowService } from '../../wirings/workflow/pikku-workflow-service.js';
+/** A workflow service under test, and the means to kill the worker holding a step. */
+export type WorkflowFencingHarness = {
+    service: PikkuWorkflowService;
+    /**
+     * Make the step's lease read as lapsed, as it would once its worker died, on
+     * whichever clock the store judges leases by.
+     */
+    lapseLease: (runId: string, stepName: string) => Promise<void>;
+};
+/**
+ * Conformance suite for a workflow service that fences a step's writes to the
+ * claim that made them. Each test gets a fresh harness.
+ *
+ * Every scenario has a stale attempt — claimed, then its lease lapsed and the
+ * step claimed again — and the attempt that replaced it.
+ */
+export declare const defineWorkflowFencingTests: (name: string, create: () => Promise<WorkflowFencingHarness>) => void;

package/dist/testing/service-tests/workflow-fencing-tests.js

@@ -0,0 +1,216 @@
+import { describe, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { RPCNotFoundError } from '../../wirings/rpc/rpc-runner.js';
+import { pikkuState } from '../../pikku-state.js';
+import { ConsoleLogger } from '../../services/logger-console.js';
+import { LogLevel } from '../../services/logger.js';
+const STEP = 'charge';
+const RPC = 'charge:card';
+const LEASE_MS = 60_000;
+const RACES = 25;
+const createSilentLogger = () => {
+    const logger = new ConsoleLogger();
+    logger.setLevel(LogLevel.critical);
+    return logger;
+};
+const superseded = (e) => e.name === 'WorkflowStepSupersededError';
+/**
+ * Conformance suite for a workflow service that fences a step's writes to the
+ * claim that made them. Each test gets a fresh harness.
+ *
+ * Every scenario has a stale attempt — claimed, then its lease lapsed and the
+ * step claimed again — and the attempt that replaced it.
+ */
+export const defineWorkflowFencingTests = (name, create) => {
+    describe(`WorkflowService fencing [${name}]`, () => {
+        const claim = ({ service }, runId) => service['claimStepForExecution'](runId, STEP, RPC, LEASE_MS);
+        const startRun = async ({ service }) => {
+            const runId = await service.createRun('fenced', {}, false, 'hash', {
+                type: 'test',
+            });
+            await service.insertStepState(runId, STEP, RPC, {}, { retries: 5 });
+            return runId;
+        };
+        /** Claim the step, lose its worker, and claim it again. */
+        const supersede = async (h, runId) => {
+            const stale = await claim(h, runId);
+            assert.ok(stale, 'the first dispatch did not get the step');
+            await h.lapseLease(runId, STEP);
+            const current = await claim(h, runId);
+            assert.ok(current, 'the lapsed step was not claimed again');
+            assert.equal(current.attemptCount, stale.attemptCount + 1);
+            return { stale, current };
+        };
+        const stepOf = (h, runId) => h.service.getStepState(runId, STEP);
+        const leaseOf = async (h, runId) => (await stepOf(h, runId)).leaseExpiresAt?.getTime();
+        /** Runs `fn` with the engine's singletons quiet, then puts back what was there. */
+        const quietly = async (fn) => {
+            const previous = pikkuState(null, 'package', 'singletonServices');
+            pikkuState(null, 'package', 'singletonServices', {
+                ...previous,
+                logger: createSilentLogger(),
+            });
+            try {
+                return await fn();
+            }
+            finally {
+                pikkuState(null, 'package', 'singletonServices', previous);
+            }
+        };
+        /**
+         * Dispatch the step through the engine, with an RPC that loses the step to
+         * a newer claim while it runs and then does `outcome`.
+         */
+        const dispatchStale = (h, runId, outcome) => quietly(async () => {
+            let current = null;
+            const staleWorker = {
+                rpcWithWire: async () => {
+                    await h.lapseLease(runId, STEP);
+                    current = await claim(h, runId);
+                    return outcome();
+                },
+            };
+            const surfaced = await h.service
+                .executeWorkflowStep(runId, STEP, RPC, {}, staleWorker)
+                .then(() => undefined, (e) => e);
+            assert.ok(current, 'the step was never claimed from under the worker');
+            return { surfaced, current: current };
+        });
+        test("a stale attempt's result is refused and the current attempt's lands", async () => {
+            const h = await create();
+            const runId = await startRun(h);
+            const { stale, current } = await supersede(h, runId);
+            await assert.rejects(h.service.setStepResult(stale.stepId, 'stale', stale.attemptCount), superseded);
+            await h.service.setStepResult(current.stepId, 'fresh', current.attemptCount);
+            const step = await stepOf(h, runId);
+            assert.equal(step.status, 'succeeded');
+            assert.equal(step.result, 'fresh');
+            assert.equal(step.attemptCount, current.attemptCount);
+            const history = (await h.service.getRunHistory(runId)).filter((attempt) => attempt.stepName === STEP);
+            assert.equal(history.length, 2, 'each claim keeps its own attempt');
+            assert.equal(history[0].status, 'running', 'the stale attempt was recorded with an outcome it was refused');
+            assert.notEqual(history[0].result, 'stale');
+            assert.equal(history[1].status, 'succeeded');
+            assert.equal(history[1].result, 'fresh');
+        });
+        test("a stale attempt's error is refused and does not fail the step", async () => {
+            const h = await create();
+            const runId = await startRun(h);
+            const { stale, current } = await supersede(h, runId);
+            await assert.rejects(h.service.setStepError(stale.stepId, new Error('stale'), stale.attemptCount), superseded);
+            const step = await stepOf(h, runId);
+            assert.equal(step.status, 'running', 'the stale attempt failed the step');
+            assert.equal(step.error, undefined);
+            assert.equal(step.attemptCount, current.attemptCount);
+        });
+        test('a stale attempt cannot renew the lease, nor move the one that replaced it', async () => {
+            const h = await create();
+            const runId = await startRun(h);
+            const { stale, current } = await supersede(h, runId);
+            const held = await leaseOf(h, runId);
+            assert.equal(await h.service.refreshStepLease(stale.stepId, 10 * LEASE_MS, stale.attemptCount), false, 'the stale attempt was told it still holds the step');
+            assert.equal(await leaseOf(h, runId), held, 'the stale renewal landed');
+            assert.equal(await h.service.refreshStepLease(stale.stepId, null, stale.attemptCount), false);
+            assert.equal(await leaseOf(h, runId), held, 'the stale release landed');
+            assert.equal(await h.service.refreshStepLease(current.stepId, 10 * LEASE_MS, current.attemptCount), true);
+        });
+        test('a stale attempt cannot overwrite a step the current attempt already succeeded', async () => {
+            const h = await create();
+            const runId = await startRun(h);
+            const { stale, current } = await supersede(h, runId);
+            await h.service.setStepResult(current.stepId, 'fresh', current.attemptCount);
+            await assert.rejects(h.service.setStepResult(stale.stepId, 'stale', stale.attemptCount), superseded);
+            await assert.rejects(h.service.setStepError(stale.stepId, new Error('stale'), stale.attemptCount), superseded);
+            const step = await stepOf(h, runId);
+            assert.equal(step.status, 'succeeded');
+            assert.equal(step.result, 'fresh');
+            assert.equal(step.error, undefined);
+        });
+        test('a stale attempt cannot overwrite a step the current attempt already failed', async () => {
+            const h = await create();
+            const runId = await startRun(h);
+            const { stale, current } = await supersede(h, runId);
+            await h.service.setStepError(current.stepId, new Error('fresh'), current.attemptCount);
+            await assert.rejects(h.service.setStepResult(stale.stepId, 'stale', stale.attemptCount), superseded);
+            const step = await stepOf(h, runId);
+            assert.equal(step.status, 'failed');
+            assert.equal(step.error?.message, 'fresh');
+            assert.equal(step.result, undefined);
+        });
+        test('when both attempts write at once, only the current one ever lands', async () => {
+            const h = await create();
+            for (let i = 0; i < RACES; i++) {
+                const runId = await startRun(h);
+                const { stale, current } = await supersede(h, runId);
+                const staleWrite = () => i % 2 === 0
+                    ? h.service.setStepResult(stale.stepId, 'stale', stale.attemptCount)
+                    : h.service.setStepError(stale.stepId, new Error('stale'), stale.attemptCount);
+                const currentWrite = () => h.service.setStepResult(current.stepId, 'fresh', current.attemptCount);
+                const [staleOutcome, currentOutcome] = i % 3 === 0
+                    ? (await Promise.allSettled([currentWrite(), staleWrite()])).reverse()
+                    : await Promise.allSettled([staleWrite(), currentWrite()]);
+                assert.equal(staleOutcome.status, 'rejected', `race ${i}`);
+                assert.ok(superseded(staleOutcome.reason), `race ${i}: ${staleOutcome.reason}`);
+                assert.equal(currentOutcome.status, 'fulfilled', `race ${i}`);
+                const step = await stepOf(h, runId);
+                assert.equal(step.status, 'succeeded', `race ${i}`);
+                assert.equal(step.result, 'fresh', `race ${i}`);
+            }
+        });
+        test('a third claim fences out both attempts before it', async () => {
+            const h = await create();
+            const runId = await startRun(h);
+            const { stale: first, current: second } = await supersede(h, runId);
+            await h.lapseLease(runId, STEP);
+            const third = await claim(h, runId);
+            assert.ok(third);
+            assert.equal(third.attemptCount, second.attemptCount + 1);
+            const held = await leaseOf(h, runId);
+            for (const stale of [first, second]) {
+                await assert.rejects(h.service.setStepResult(stale.stepId, 'stale', stale.attemptCount), superseded, `attempt ${stale.attemptCount} recorded a result`);
+                await assert.rejects(h.service.setStepError(stale.stepId, new Error('stale'), stale.attemptCount), superseded, `attempt ${stale.attemptCount} recorded an error`);
+                assert.equal(await h.service.refreshStepLease(stale.stepId, 10 * LEASE_MS, stale.attemptCount), false, `attempt ${stale.attemptCount} renewed the lease`);
+            }
+            assert.equal(await leaseOf(h, runId), held);
+            await h.service.setStepResult(third.stepId, 'third', third.attemptCount);
+            const step = await stepOf(h, runId);
+            assert.equal(step.status, 'succeeded');
+            assert.equal(step.result, 'third');
+        });
+        test('a superseded dispatch whose RPC is missing neither fails the step nor suspends the run', async () => {
+            const h = await create();
+            const runId = await startRun(h);
+            const { surfaced, current } = await dispatchStale(h, runId, () => {
+                throw new RPCNotFoundError(RPC);
+            });
+            const step = await stepOf(h, runId);
+            assert.equal(step.status, 'running', 'the stale attempt failed the step');
+            assert.equal(step.attemptCount, current.attemptCount);
+            assert.equal((await h.service.getRun(runId))?.status, 'running', 'the stale attempt suspended the run');
+            assert.equal(surfaced, undefined, 'a superseded dispatch ends quietly');
+        });
+        test('a superseded dispatch whose RPC throws ends quietly and leaves the step to its new owner', async () => {
+            const h = await create();
+            const runId = await startRun(h);
+            const { surfaced, current } = await dispatchStale(h, runId, () => {
+                throw new Error('the card was declined');
+            });
+            assert.equal(surfaced, undefined, 'the stale failure surfaced');
+            const step = await stepOf(h, runId);
+            assert.equal(step.status, 'running', 'the stale attempt failed the step');
+            assert.equal(step.error, undefined);
+            assert.equal(step.attemptCount, current.attemptCount);
+            assert.equal((await h.service.getRun(runId))?.status, 'running');
+        });
+        test('a superseded dispatch whose RPC succeeds does not record its result', async () => {
+            const h = await create();
+            const runId = await startRun(h);
+            const { surfaced, current } = await dispatchStale(h, runId, () => 'stale');
+            assert.equal(surfaced, undefined);
+            const step = await stepOf(h, runId);
+            assert.equal(step.status, 'running', 'the stale result landed');
+            assert.equal(step.result, undefined);
+            assert.equal(step.attemptCount, current.attemptCount);
+        });
+    });
+};

package/dist/testing/service-tests.d.ts

@@ -9,6 +9,8 @@ import type { SecretService } from '../services/secret-service.js';
 import type { CredentialService } from '../services/credential-service.js';
 import type { AgentRunService } from '../wirings/agent/agent.types.js';
 import type { SessionStore } from '../services/session-store.js';
+import type { LeaseService } from '../services/lease-service.js';
+import type { WorkflowFencingHarness } from './service-tests/workflow-fencing-tests.js';
 export interface ServiceTestConfig {
     name: string;
     services: {
@@ -36,6 +38,9 @@ export interface ServiceTestConfig {
             rotateKEK?(): Promise<number>;
         }>;
         sessionStore?: () => Promise<SessionStore>;
+        leaseService?: () => Promise<LeaseService>;
+        /** A workflow service that fences each step write to the claim that made it. */
+        workflowFencing?: () => Promise<WorkflowFencingHarness>;
     };
 }
 /**

package/dist/testing/service-tests.js

@@ -8,6 +8,8 @@ import { defineSecretServiceTests } from './service-tests/secret-service-tests.j
 import { defineCredentialServiceTests } from './service-tests/credential-service-tests.js';
 import { defineAgentRunServiceTests } from './service-tests/agent-run-service-tests.js';
 import { defineSessionStoreTests } from './service-tests/session-store-tests.js';
+import { defineLeaseServiceTests } from './service-tests/lease-service-tests.js';
+import { defineWorkflowFencingTests } from './service-tests/workflow-fencing-tests.js';
 /**
  * The shared conformance suite every storage backend runs.
  *
@@ -46,4 +48,10 @@ export function defineServiceTests(config) {
     if (services.sessionStore) {
         defineSessionStoreTests(name, services.sessionStore);
     }
+    if (services.leaseService) {
+        defineLeaseServiceTests(name, services.leaseService);
+    }
+    if (services.workflowFencing) {
+        defineWorkflowFencingTests(name, services.workflowFencing);
+    }
 }

package/dist/types/core.types.d.ts

@@ -1,5 +1,6 @@
 import type { IncomingWebhookService } from '../services/incoming-webhook-service.js';
 import type { TriggerSourceStore } from '../services/trigger-source-store.js';
+import type { LeaseService } from '../services/lease-service.js';
 import type { Logger, LogLevel } from '../services/logger.js';
 import type { VariablesService } from '../services/variables-service.js';
 import type { SecretService } from '../services/secret-service.js';
@@ -139,6 +140,7 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
     incomingWebhookService?: IncomingWebhookService;
     /** Which trigger sources an operator enabled, and what enabling registered. */
     triggerSourceStore?: TriggerSourceStore;
+    leaseService?: LeaseService;
     metaService?: MetaService;
     /**
      * Where virtual-user runs are recorded. A run is dispatched and answered for
@@ -199,19 +201,25 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
 /**
  * Reads a single credential. The first signature resolves the value type from
  * the project's generated `CredentialsMap`; the second keeps a name the map
- * does not know callable with an explicit type.
+ * does not know callable with an explicit type. Without a map, every name is a
+ * key, so the first signature would swallow an explicit type argument; only
+ * the second is offered then.
  *
  * `TCredentials` is unconstrained because the generated map is an interface,
  * which has no implicit index signature and so cannot satisfy
  * `Record<string, unknown>`.
  */
-export type GetCredential<TCredentials = Record<string, unknown>> = {
+export type GetCredential<TCredentials = Record<string, unknown>> = string extends keyof TCredentials ? <T = unknown>(name: string) => NoInfer<T> | null | Promise<NoInfer<T> | null> : {
     <K extends keyof TCredentials & string>(name: K): TCredentials[K] | null | Promise<TCredentials[K] | null>;
     <T = unknown>(name: string): T | null | Promise<T | null>;
 };
 export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boolean = false, UserSession extends CoreUserSession = CoreUserSession, TypedRPC extends PikkuRPC = PikkuRPC, IsChannel extends true | null = null, MCPTools extends string | never = never, TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire, TriggerOutput = unknown, TypedScenario extends PikkuScenarioWire<any> | never = PikkuScenarioWire<any>, TypedActors extends ScenarioPersonas = ScenarioPersonas, TypedCredentials = Record<string, unknown>> = {
     /** Always present — lazily initialised on first access for every function invocation */
     rpc: TypedRPC;
+    /** Get a single credential by name — lazy-loads from CredentialService on first call, sync thereafter */
+    getCredential: GetCredential<TypedCredentials>;
+    /** Get all resolved credentials — lazy-loads from CredentialService on first call, sync thereafter */
+    getCredentials: () => Record<string, unknown> | Promise<Record<string, unknown>>;
 } & Partial<{
     wireType: PikkuWiringTypes;
     wireId: string;
@@ -260,10 +268,6 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
     pikkuUserId: string;
     /** Set a credential value (available in middleware) */
     setCredential: (name: string, value: unknown) => void;
-    /** Get a single credential by name — lazy-loads from CredentialService on first call, sync thereafter */
-    getCredential: GetCredential<TypedCredentials>;
-    /** Get all resolved credentials — lazy-loads from CredentialService on first call, sync thereafter */
-    getCredentials: () => Record<string, unknown> | Promise<Record<string, unknown>>;
     audit: {
         durability: AuditDurability;
     };
@@ -282,8 +286,8 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
      */
     beginChanges: () => Promise<void>;
 }>;
-/** Wire as constructed by runners, before the function runner lazily adds `rpc`. */
-export type PikkuRawWire = Omit<PikkuWire, 'rpc'>;
+/** Wire as constructed by runners, before the function runner adds `rpc` and the credential readers. */
+export type PikkuRawWire = Omit<PikkuWire, 'rpc' | 'getCredential' | 'getCredentials'> & Partial<Pick<PikkuWire, 'getCredential' | 'getCredentials'>>;
 export type CoreServices<SingletonServices = CoreSingletonServices> = SingletonServices;
 /** Strips `secrets` from a services type. */
 export type SecretlessServices<Services> = Omit<Services, 'secrets'>;

package/dist/utils/hmac.d.ts

@@ -9,18 +9,22 @@ export declare function hmacSha256Hex(secret: string, payload: string): string;
  * where `timingSafeEqual` itself throws.
  */
 export declare function timingSafeStringEqual(a: string, b: string): boolean;
-type WebhookPayload = string | Uint8Array;
-type HmacAlgorithm = 'sha1' | 'sha256' | 'sha512';
-type SecretEncoding = 'utf8' | 'hex' | 'base64';
+export type WebhookPayload = string | Uint8Array;
+export type HmacAlgorithm = 'sha1' | 'sha256' | 'sha512';
+export type SecretEncoding = 'utf8' | 'hex' | 'base64';
 type SecretSource = string | null | (() => Promise<string | null>);
+/** The HMAC of `payload` under `secret`, for handshakes that answer with a digest. */
+export declare function hmacDigest(secret: string, algorithm: HmacAlgorithm, payload: WebhookPayload, encoding: 'hex' | 'base64', secretEncoding?: SecretEncoding): string;
+/** Whether `signature` is the HMAC of `payload` under `secret`, compared in constant time. */
+export declare function verifyHmacSignature(secret: string, signature: string | undefined, algorithm: HmacAlgorithm, payload: WebhookPayload, encoding: 'hex' | 'base64', secretEncoding?: SecretEncoding): boolean;
+/** Whether `signature` (base64) is `payload` signed by the private half of `publicKey` (PEM). */
+export declare function verifyPublicKeySignature(publicKey: string, signature: string | undefined, payload: WebhookPayload, options?: {
+    algorithm?: string;
+    dsaEncoding?: 'der' | 'ieee-p1363';
+}): boolean;
 /**
- * A provider's webhook signing secret, held by a singleton service so a
- * webhook `receive` step can check signatures without reading it. Built with
- * null when the app never provisioned the secret: every check then refuses, so
- * an unconfigured receiver accepts nothing.
- *
- * Built with a lookup, as `fromCredential` does, it checks nothing until
- * `load()` reads the current value.
+ * @deprecated Declare `credential` and `verify` on `wireTriggerWebhookSource`,
+ * which checks every request before `receive` runs, or use the functions above.
  */
 export declare class WebhookSigningSecret {
     private readonly provider;

package/dist/utils/hmac.js

@@ -19,14 +19,33 @@ export function timingSafeStringEqual(a, b) {
         return false;
     }
 }
+/** The HMAC of `payload` under `secret`, for handshakes that answer with a digest. */
+export function hmacDigest(secret, algorithm, payload, encoding, secretEncoding = 'utf8') {
+    return createHmac(algorithm, Buffer.from(secret, secretEncoding))
+        .update(payload)
+        .digest(encoding);
+}
+/** Whether `signature` is the HMAC of `payload` under `secret`, compared in constant time. */
+export function verifyHmacSignature(secret, signature, algorithm, payload, encoding, secretEncoding = 'utf8') {
+    return (!!signature &&
+        timingSafeStringEqual(signature, hmacDigest(secret, algorithm, payload, encoding, secretEncoding)));
+}
+/** Whether `signature` (base64) is `payload` signed by the private half of `publicKey` (PEM). */
+export function verifyPublicKeySignature(publicKey, signature, payload, options = {}) {
+    if (!signature)
+        return false;
+    try {
+        return createVerify(options.algorithm ?? 'sha256')
+            .update(payload)
+            .verify({ key: publicKey, dsaEncoding: options.dsaEncoding }, signature, 'base64');
+    }
+    catch {
+        return false;
+    }
+}
 /**
- * A provider's webhook signing secret, held by a singleton service so a
- * webhook `receive` step can check signatures without reading it. Built with
- * null when the app never provisioned the secret: every check then refuses, so
- * an unconfigured receiver accepts nothing.
- *
- * Built with a lookup, as `fromCredential` does, it checks nothing until
- * `load()` reads the current value.
+ * @deprecated Declare `credential` and `verify` on `wireTriggerWebhookSource`,
+ * which checks every request before `receive` runs, or use the functions above.
  */
 export class WebhookSigningSecret {
     provider;
@@ -54,14 +73,11 @@ export class WebhookSigningSecret {
     }
     /** For handshakes that answer with a digest, such as Zoom's URL validation. */
     hmac(algorithm, payload, encoding, secretEncoding = 'utf8') {
-        return createHmac(algorithm, Buffer.from(this.require(), secretEncoding))
-            .update(payload)
-            .digest(encoding);
+        return hmacDigest(this.require(), algorithm, payload, encoding, secretEncoding);
     }
     /** Throws unless `signature` is the HMAC of `payload` under the secret. */
     verifyHmac(signature, algorithm, payload, encoding, secretEncoding = 'utf8') {
-        const expected = this.hmac(algorithm, payload, encoding, secretEncoding);
-        if (!signature || !timingSafeStringEqual(signature, expected)) {
+        if (!verifyHmacSignature(this.require(), signature, algorithm, payload, encoding, secretEncoding)) {
             throw this.rejected();
         }
     }
@@ -73,19 +89,7 @@ export class WebhookSigningSecret {
     }
     /** For providers that sign with a private key: the secret is their public key, as PEM. */
     verifyPublicKey(signature, payload, options = {}) {
-        const key = this.require();
-        let valid = false;
-        try {
-            valid =
-                !!signature &&
-                    createVerify(options.algorithm ?? 'sha256')
-                        .update(payload)
-                        .verify({ key, dsaEncoding: options.dsaEncoding }, signature, 'base64');
-        }
-        catch {
-            valid = false;
-        }
-        if (!valid) {
+        if (!verifyPublicKeySignature(this.require(), signature, payload, options)) {
             throw this.rejected();
         }
     }

package/dist/wirings/http/pikku-fetch-http-response.js

@@ -7,6 +7,7 @@ export class PikkuFetchHTTPResponse {
     #responseMode = null;
     #send = null;
     #close = null;
+    #cancelStream = null;
     setMode(mode) {
         this.#responseMode = 'stream';
         if (mode === 'stream') {
@@ -107,16 +108,28 @@ export class PikkuFetchHTTPResponse {
         const encoder = new TextEncoder();
         return new ReadableStream({
             start: (controller) => {
+                let closed = false;
                 const send = (data) => {
+                    if (closed)
+                        return;
                     controller.enqueue(encoder.encode(`data: ${data}\n\n`));
                 };
                 const close = () => {
+                    if (closed)
+                        return;
+                    closed = true;
                     controller.close();
                 };
+                this.#cancelStream = () => {
+                    closed = true;
+                };
                 this.#send = send;
                 this.#close = close;
                 controller.enqueue(encoder.encode(':\n\n'));
             },
+            cancel: () => {
+                this.#cancelStream?.();
+            },
         });
     }
 }

package/dist/wirings/secret/derive-oauth2-app-secrets.js

@@ -37,6 +37,7 @@ export const deriveOAuth2AppSecrets = (credentials, declared) => {
                 authorizationUrl: oauth2.authorizationUrl,
                 tokenUrl: oauth2.tokenUrl,
                 scopes: oauth2.scopes,
+                scopeSeparator: oauth2.scopeSeparator,
                 pkce: oauth2.pkce,
                 additionalParams: oauth2.additionalParams,
             },

package/dist/wirings/secret/secret.types.d.ts

@@ -31,6 +31,12 @@ export type OAuth2CredentialConfig = {
     authorizationUrl: string;
     tokenUrl: string;
     scopes: string[];
+    /**
+     * What joins `scopes` in the authorization URL. RFC 6749 says a space, which
+     * is the default; a few providers (Twist) document a comma. An empty `scopes`
+     * omits the parameter altogether.
+     */
+    scopeSeparator?: string;
     pkce?: boolean;
     /** Appended to the authorization URL's query string. */
     additionalParams?: Record<string, string>;