@pikku/core 0.12.127 → 0.12.128

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 0.12.128
+
+### Patch Changes
+
+- 658f047: A function whose services are all singletons no longer builds wire services, so an addon's credential-bound wire factory does not run for, or fail, a webhook `receive` step that needs no connection. The inspector decides this from the `Services` type and records it as `singletonServicesOnly` on the function's runtime meta; the runner only reads the flag.
+- de63ab2: Store a workflow's graph when a run is created, so a run suspended across a
+  deploy that changes the definition resumes on the graph it started on instead
+  of failing with `VERSION_NOT_FOUND`. Nothing called `registerWorkflowVersions`,
+  so the versions table stayed empty and the replay fallback could never find a
+  version.
+- 658f047: A declared webhook source is a registered one. `reconcileTriggerSources` sets up every declared source with its provider (check, then setup where missing or drifted) and `teardownTriggerSources` removes named ones, recording what was registered in a `TriggerSourceStore` (in-memory, or `KyselyTriggerSourceStore` on `pikku_trigger_source`). The admin addon exposes list, reconcile, teardown and forget under the new `admin:triggers` scopes.
+- 658f047: Webhook signing secrets live in the credential store. `WebhookSigningSecret.fromCredential(provider, credentialService, name)` reads the secret per delivery via `load()`, so a `setup` step (or a handshake) that stores a new one with `credentialService.set` takes effect without a deploy.
+
+  Breaking: `setup` no longer returns `secret`, `wireTriggerWebhookSource` no longer takes `secret`, lifecycle outcomes drop `secretName`/`secret`, and `pikku webhooks setup` drops `--secretsOut`.
+
+- 658f047: `WebhookSigningSecret` in `@pikku/core/hmac`: holds a provider's webhook signing secret in a singleton service and checks HMAC, shared-token and public-key signatures for a `receive` step, refusing everything when the secret was never provisioned.
+- 658f047: A webhook source's `method` may be a list, mounting one route per method, for providers that verify the URL with a GET and deliver events with a POST (WhatsApp, Strava, Onfleet, Mailchimp), or a HEAD (Trello, Mandrill, SurveyMonkey).
+
 ## 0.12.127
 
 ### Patch Changes

package/dist/function/function-meta.types.d.ts

@@ -109,6 +109,13 @@ export type FunctionRuntimeMeta = {
     audit?: {
         durability: AuditDurability;
     };
+    /**
+     * Set by the inspector when every service the function destructures is a
+     * singleton, so the runner skips `createWireServices` for it. Absent means
+     * the function reads a wire service, takes `services` whole, or the app's
+     * `Services` type did not resolve — in each case the wire services are built.
+     */
+    singletonServicesOnly?: boolean;
     version?: number;
     approvalRequired?: boolean;
     approvalDescription?: string;

package/dist/function/function-runner.js

@@ -256,7 +256,9 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
         let invocationAuditLog;
         let invocationAnalytics;
         try {
-            wireServices = (await resolvedCreateWireServices?.(resolvedSingletonServices, invocationWire));
+            wireServices = funcMeta.singletonServicesOnly
+                ? undefined
+                : (await resolvedCreateWireServices?.(resolvedSingletonServices, invocationWire));
             let services = wireServices && Object.keys(wireServices).length > 0
                 ? { ...resolvedSingletonServices, ...wireServices }
                 : resolvedSingletonServices;

package/dist/services/index.d.ts

@@ -16,6 +16,7 @@ export { IncomingWebhookService, type IncomingWebhookAttempt, type IncomingWebho
 export { REMOTE_JOBS_SECRET_HEADER, REMOTE_JOBS_SECRET_VARIABLE, REMOTE_QUEUE_JOB_PATH, REMOTE_SCHEDULER_JOB_PATH, pikkuRemoteQueueJobFunc, pikkuRemoteScheduledJobFunc, type RemoteQueueJobData, type RemoteScheduledJobData, } from './remote-jobs.js';
 export { InMemoryQueueService } from './in-memory-queue-service.js';
 export { InMemoryTriggerService } from './in-memory-trigger-service.js';
+export { InMemoryTriggerSourceStore, type DeclaredTriggerSource, type TriggerSourceKind, type TriggerSourceResult, type TriggerSourceRow, type TriggerSourceStore, } from './trigger-source-store.js';
 export { InMemoryAgentRunStateService } from './in-memory-agent-run-state-service.js';
 export { LocalGatewayService } from './local-gateway-service.js';
 export { FileScenarioRunStore, scenarioArtifactContentType, scenarioRunSummary, type FileScenarioRunStoreOptions, } from './file-scenario-run-store.js';

package/dist/services/index.js

@@ -16,6 +16,7 @@ export { IncomingWebhookService, } from './incoming-webhook-service.js';
 export { REMOTE_JOBS_SECRET_HEADER, REMOTE_JOBS_SECRET_VARIABLE, REMOTE_QUEUE_JOB_PATH, REMOTE_SCHEDULER_JOB_PATH, pikkuRemoteQueueJobFunc, pikkuRemoteScheduledJobFunc, } from './remote-jobs.js';
 export { InMemoryQueueService } from './in-memory-queue-service.js';
 export { InMemoryTriggerService } from './in-memory-trigger-service.js';
+export { InMemoryTriggerSourceStore, } from './trigger-source-store.js';
 export { InMemoryAgentRunStateService } from './in-memory-agent-run-state-service.js';
 export { LocalGatewayService } from './local-gateway-service.js';
 export { FileScenarioRunStore, scenarioArtifactContentType, scenarioRunSummary, } from './file-scenario-run-store.js';

package/dist/services/trigger-source-store.d.ts

@@ -0,0 +1,62 @@
+import type { WebhookSourceState } from '../wirings/trigger/webhook-source.types.js';
+export type TriggerSourceKind = 'webhook';
+export type DeclaredTriggerSource = {
+    name: string;
+    kind: TriggerSourceKind;
+};
+/**
+ * What was registered with the provider for one declared trigger source.
+ * `state` is what the last `setup` returned — provider identifiers only; any
+ * secret it issued lives in the credential service.
+ */
+export type TriggerSourceRow = DeclaredTriggerSource & {
+    /** False once the declaration has gone from code without a teardown: an orphan. */
+    declared: boolean;
+    status: string | null;
+    state: WebhookSourceState | null;
+    /** The last step's instructions or error. */
+    detail: string | null;
+    updatedAt: string | null;
+};
+export type TriggerSourceResult = {
+    status: string;
+    state?: WebhookSourceState | null;
+    detail?: string | null;
+};
+/** What each declared trigger source registered with its provider. */
+export interface TriggerSourceStore {
+    /** Upserts the declared sources and marks the rest undeclared. */
+    syncTriggerSources(sources: DeclaredTriggerSource[]): Promise<void>;
+    listTriggerSources(): Promise<TriggerSourceRow[]>;
+    getTriggerSource(name: string): Promise<TriggerSourceRow | null>;
+    recordTriggerSource(name: string, result: TriggerSourceResult): Promise<void>;
+    deleteTriggerSource(name: string): Promise<void>;
+}
+export declare class InMemoryTriggerSourceStore implements TriggerSourceStore {
+    private rows;
+    syncTriggerSources(sources: DeclaredTriggerSource[]): Promise<void>;
+    listTriggerSources(): Promise<{
+        name: string;
+        kind: TriggerSourceKind;
+        /** False once the declaration has gone from code without a teardown: an orphan. */
+        declared: boolean;
+        status: string | null;
+        state: WebhookSourceState | null;
+        /** The last step's instructions or error. */
+        detail: string | null;
+        updatedAt: string | null;
+    }[]>;
+    getTriggerSource(name: string): Promise<{
+        name: string;
+        kind: TriggerSourceKind;
+        /** False once the declaration has gone from code without a teardown: an orphan. */
+        declared: boolean;
+        status: string | null;
+        state: WebhookSourceState | null;
+        /** The last step's instructions or error. */
+        detail: string | null;
+        updatedAt: string | null;
+    } | null>;
+    recordTriggerSource(name: string, result: TriggerSourceResult): Promise<void>;
+    deleteTriggerSource(name: string): Promise<void>;
+}

package/dist/services/trigger-source-store.js

@@ -0,0 +1,47 @@
+export class InMemoryTriggerSourceStore {
+    rows = new Map();
+    async syncTriggerSources(sources) {
+        const names = new Set(sources.map((s) => s.name));
+        for (const row of this.rows.values()) {
+            row.declared = names.has(row.name);
+        }
+        for (const { name, kind } of sources) {
+            const row = this.rows.get(name);
+            if (row) {
+                row.kind = kind;
+                continue;
+            }
+            this.rows.set(name, {
+                name,
+                kind,
+                declared: true,
+                status: null,
+                state: null,
+                detail: null,
+                updatedAt: null,
+            });
+        }
+    }
+    async listTriggerSources() {
+        return [...this.rows.values()]
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map((row) => ({ ...row }));
+    }
+    async getTriggerSource(name) {
+        const row = this.rows.get(name);
+        return row ? { ...row } : null;
+    }
+    async recordTriggerSource(name, result) {
+        const row = this.rows.get(name);
+        if (!row)
+            throw new Error(`Unknown trigger source: ${name}`);
+        row.status = result.status;
+        if (result.state !== undefined)
+            row.state = result.state;
+        row.detail = result.detail ?? null;
+        row.updatedAt = new Date().toISOString();
+    }
+    async deleteTriggerSource(name) {
+        this.rows.delete(name);
+    }
+}

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

@@ -1,4 +1,5 @@
 import type { IncomingWebhookService } from '../services/incoming-webhook-service.js';
+import type { TriggerSourceStore } from '../services/trigger-source-store.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';
@@ -136,6 +137,8 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
     webhookService?: WebhookService;
     /** Queues what webhook trigger sources receive. Required once any `wireTriggerWebhookSource` is wired. */
     incomingWebhookService?: IncomingWebhookService;
+    /** Which trigger sources an operator enabled, and what enabling registered. */
+    triggerSourceStore?: TriggerSourceStore;
     metaService?: MetaService;
     /**
      * Where virtual-user runs are recorded. A run is dispatched and answered for

package/dist/utils/hmac.d.ts

@@ -1,3 +1,4 @@
+import type { CredentialService } from '../services/credential-service.js';
 /**
  * HMAC-SHA256 of a payload, hex-encoded. Senders wrap this in their own scheme
  * prefix (`sha256=`, `v0=`, …).
@@ -8,3 +9,43 @@ 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';
+type SecretSource = string | null | (() => Promise<string | null>);
+/**
+ * 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.
+ */
+export declare class WebhookSigningSecret {
+    private readonly provider;
+    private readonly secret;
+    constructor(provider: string, secret: SecretSource);
+    /**
+     * The secret a `setup` step or a handshake stored in the credential store,
+     * so a new one takes effect without a deploy.
+     */
+    static fromCredential(provider: string, credentials: CredentialService | undefined, name: string): WebhookSigningSecret;
+    get configured(): boolean;
+    /** The secret as it is now, to check one delivery against. */
+    load(): Promise<WebhookSigningSecret>;
+    /** For handshakes that answer with a digest, such as Zoom's URL validation. */
+    hmac(algorithm: HmacAlgorithm, payload: WebhookPayload, encoding: 'hex' | 'base64', secretEncoding?: SecretEncoding): string;
+    /** Throws unless `signature` is the HMAC of `payload` under the secret. */
+    verifyHmac(signature: string | undefined, algorithm: HmacAlgorithm, payload: WebhookPayload, encoding: 'hex' | 'base64', secretEncoding?: SecretEncoding): void;
+    /** For providers that send the shared secret itself rather than a signature. */
+    verifyToken(token: string | undefined): void;
+    /** For providers that sign with a private key: the secret is their public key, as PEM. */
+    verifyPublicKey(signature: string | undefined, payload: WebhookPayload, options?: {
+        algorithm?: string;
+        dsaEncoding?: 'der' | 'ieee-p1363';
+    }): void;
+    private require;
+    private rejected;
+}
+export {};

package/dist/utils/hmac.js

@@ -1,4 +1,5 @@
-import { createHmac, timingSafeEqual } from 'node:crypto';
+import { createHmac, createVerify, timingSafeEqual } from 'node:crypto';
+import { UnauthorizedError } from '../errors/errors.js';
 /**
  * HMAC-SHA256 of a payload, hex-encoded. Senders wrap this in their own scheme
  * prefix (`sha256=`, `v0=`, …).
@@ -18,3 +19,83 @@ export function timingSafeStringEqual(a, b) {
         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.
+ */
+export class WebhookSigningSecret {
+    provider;
+    secret;
+    constructor(provider, secret) {
+        this.provider = provider;
+        this.secret = secret;
+    }
+    /**
+     * The secret a `setup` step or a handshake stored in the credential store,
+     * so a new one takes effect without a deploy.
+     */
+    static fromCredential(provider, credentials, name) {
+        return new WebhookSigningSecret(provider, async () => credentials ? credentials.get(name) : null);
+    }
+    get configured() {
+        return typeof this.secret === 'string';
+    }
+    /** The secret as it is now, to check one delivery against. */
+    async load() {
+        if (typeof this.secret !== 'function') {
+            return this;
+        }
+        return new WebhookSigningSecret(this.provider, await this.secret());
+    }
+    /** 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);
+    }
+    /** 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)) {
+            throw this.rejected();
+        }
+    }
+    /** For providers that send the shared secret itself rather than a signature. */
+    verifyToken(token) {
+        if (!token || !timingSafeStringEqual(token, this.require())) {
+            throw this.rejected();
+        }
+    }
+    /** 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) {
+            throw this.rejected();
+        }
+    }
+    require() {
+        if (typeof this.secret !== 'string') {
+            throw new UnauthorizedError(`The ${this.provider} webhook receiver has no signing secret`);
+        }
+        return this.secret;
+    }
+    rejected() {
+        return new UnauthorizedError(`Invalid ${this.provider} webhook signature`);
+    }
+}

package/dist/wirings/trigger/index.d.ts

@@ -1,7 +1,7 @@
 export { wireTrigger, wireTriggerSource } from './trigger-runner.js';
-export { wireTriggerWebhookSource, receiveWebhookSourceRequest, dispatchWebhookSourceJob, runWebhookSourceLifecycle, subscribedWebhookEvents, } from './webhook-source-runner.js';
+export { wireTriggerWebhookSource, receiveWebhookSourceRequest, dispatchWebhookSourceJob, runWebhookSourceLifecycle, declaredTriggerSources, reconcileTriggerSources, teardownTriggerSources, subscribedWebhookEvents, } from './webhook-source-runner.js';
 export type { WebhookSourceOutcome } from './webhook-source-runner.js';
 export { PIKKU_INCOMING_WEBHOOK_QUEUE_NAME } from './webhook-source.types.js';
-export type { CoreTriggerWebhookSource, TriggerEvent, WebhookCheckResult, WebhookLifecycleInput, WebhookReceiveResult, WebhookRequest, WebhookSetupResult, WebhookSourceJob, WebhookSourceMeta, WebhookSourcesMeta, WebhookSourceState, WebhookTeardownInput, WebhookTeardownResult, } from './webhook-source.types.js';
+export type { CoreTriggerWebhookSource, TriggerEvent, WebhookCheckResult, WebhookLifecycleInput, WebhookReceiveResult, WebhookRequest, WebhookSetupResult, WebhookSourceJob, WebhookSourceMeta, WebhookSourceMethod, WebhookSourcesMeta, WebhookSourceState, WebhookTeardownInput, WebhookTeardownResult, } from './webhook-source.types.js';
 export { PikkuTriggerService } from './pikku-trigger-service.js';
 export type { TriggerMeta, TriggerSourceMeta, CorePikkuTriggerFunction, CorePikkuTriggerFunctionConfig, CoreTrigger, } from './trigger.types.js';

package/dist/wirings/trigger/index.js

@@ -1,4 +1,4 @@
 export { wireTrigger, wireTriggerSource } from './trigger-runner.js';
-export { wireTriggerWebhookSource, receiveWebhookSourceRequest, dispatchWebhookSourceJob, runWebhookSourceLifecycle, subscribedWebhookEvents, } from './webhook-source-runner.js';
+export { wireTriggerWebhookSource, receiveWebhookSourceRequest, dispatchWebhookSourceJob, runWebhookSourceLifecycle, declaredTriggerSources, reconcileTriggerSources, teardownTriggerSources, subscribedWebhookEvents, } from './webhook-source-runner.js';
 export { PIKKU_INCOMING_WEBHOOK_QUEUE_NAME } from './webhook-source.types.js';
 export { PikkuTriggerService } from './pikku-trigger-service.js';

package/dist/wirings/trigger/webhook-source-runner.d.ts

@@ -1,6 +1,7 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { CoreSingletonServices } from '../../types/core.types.js';
 import type { PikkuHTTP } from '../http/http.types.js';
+import type { DeclaredTriggerSource } from '../../services/trigger-source-store.js';
 import type { CoreTriggerWebhookSource, WebhookCheckResult, WebhookSetupResult, WebhookSourceJob, WebhookSourceState, WebhookTeardownResult } from './webhook-source.types.js';
 export declare const wireTriggerWebhookSource: <Events extends Record<string, StandardSchemaV1>>(source: CoreTriggerWebhookSource<Events>) => void;
 /** The declared events some trigger is wired to: what `setup` registers with the provider. */
@@ -23,23 +24,42 @@ export type WebhookSourceOutcome = {
     status: WebhookCheckResult['status'] | WebhookSetupResult['status'] | WebhookTeardownResult['status'] | 'skipped' | 'failed';
     reason?: string;
     state?: WebhookSourceState;
-    /** The name the produced signing secret must be stored under. */
-    secretName?: string;
-    secret?: string;
     instructions?: string;
     error?: string;
 };
+type LifecycleInput = {
+    /** Where the app's routes are served, e.g. `https://shop.example.com/api`. */
+    baseUrl: string;
+    labelPrefix: string;
+};
 /**
  * Runs one lifecycle step for every webhook source, as `pikku webhooks
- * status | setup | teardown` does at deploy. `setup` runs only where `check`
- * does not report `ok`. One failing source does not stop the rest.
+ * status | setup | teardown` does. `setup` runs only where `check` does not
+ * report `ok`. One failing source does not stop the rest.
  */
-export declare const runWebhookSourceLifecycle: ({ action, baseUrl, labelPrefix, previous, singletonServices, }: {
+export declare const runWebhookSourceLifecycle: ({ action, previous, singletonServices, ...input }: LifecycleInput & {
     action: 'check' | 'setup' | 'teardown';
-    /** Where the app's routes are served, e.g. `https://shop.example.com/api`. */
-    baseUrl: string;
-    labelPrefix: string;
     /** What the last `setup` returned as `state`, by source name. */
     previous?: Record<string, WebhookSourceState>;
     singletonServices?: CoreSingletonServices;
 }) => Promise<WebhookSourceOutcome[]>;
+/** The trigger sources this app declares, as the store is synced to. */
+export declare const declaredTriggerSources: () => DeclaredTriggerSource[];
+/**
+ * Registers every declared webhook source with its provider: `check`, then
+ * `setup` where it is missing or drifted, recording what was registered.
+ * Run after a deployment goes live.
+ */
+export declare const reconcileTriggerSources: ({ singletonServices, ...input }: LifecycleInput & {
+    singletonServices?: CoreSingletonServices;
+}) => Promise<WebhookSourceOutcome[]>;
+/**
+ * Removes the named webhook sources from their providers and forgets them.
+ * Run on the outgoing deployment for the sources the next release drops,
+ * since only the code that set a source up can tear it down.
+ */
+export declare const teardownTriggerSources: ({ names, singletonServices, ...input }: LifecycleInput & {
+    names: string[];
+    singletonServices?: CoreSingletonServices;
+}) => Promise<WebhookSourceOutcome[]>;
+export {};

package/dist/wirings/trigger/webhook-source-runner.js

@@ -152,70 +152,121 @@ export const dispatchWebhookSourceJob = async (job) => {
 const recordAttempt = (singletonServices, receiptId, trigger, error) => singletonServices.incomingWebhookService
     ?.recordAttempt(receiptId, { trigger, ...(error ? { error } : {}) })
     .catch((storeError) => singletonServices.logger.error(`Failed to record the attempt for webhook receipt ${receiptId}`, storeError));
+const runSourceLifecycleStep = async (meta, action, { baseUrl, labelPrefix }, previous, singletonServices) => {
+    const url = `${baseUrl.replace(/\/+$/, '')}${meta.route}`;
+    const label = `${labelPrefix}:${meta.name}`;
+    const input = {
+        url,
+        label,
+        events: subscribedWebhookEvents(meta.name),
+        ...(previous ? { previous } : {}),
+    };
+    const outcome = (status, extra = {}) => ({ source: meta.name, url, status, ...extra });
+    try {
+        if (action === 'teardown') {
+            if (!meta.teardown)
+                return outcome('skipped');
+            const result = await runSourceStep(singletonServices, meta.name, meta.teardown, { label, ...(previous ? { previous } : {}) });
+            return outcome(result.status);
+        }
+        if (meta.check) {
+            const checked = await runSourceStep(singletonServices, meta.name, meta.check, input);
+            if (action === 'check' || checked.status === 'ok') {
+                return outcome(checked.status === 'ok' && action === 'setup'
+                    ? 'unchanged'
+                    : checked.status, checked.status === 'drifted' ? { reason: checked.reason } : {});
+            }
+        }
+        else if (action === 'check') {
+            return outcome('skipped');
+        }
+        if (!meta.setup) {
+            return outcome('manual', {
+                instructions: `Register ${url} with the provider for: ${input.events.join(', ') || 'every event'}.`,
+            });
+        }
+        const result = await runSourceStep(singletonServices, meta.name, meta.setup, input);
+        if (result.status === 'manual') {
+            return outcome('manual', { instructions: result.instructions });
+        }
+        return outcome(result.status, result.state ? { state: result.state } : {});
+    }
+    catch (error) {
+        return outcome('failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+};
 /**
  * Runs one lifecycle step for every webhook source, as `pikku webhooks
- * status | setup | teardown` does at deploy. `setup` runs only where `check`
- * does not report `ok`. One failing source does not stop the rest.
+ * status | setup | teardown` does. `setup` runs only where `check` does not
+ * report `ok`. One failing source does not stop the rest.
  */
-export const runWebhookSourceLifecycle = async ({ action, baseUrl, labelPrefix, previous = {}, singletonServices = getSingletonServices(), }) => {
-    const base = baseUrl.replace(/\/+$/, '');
+export const runWebhookSourceLifecycle = async ({ action, previous = {}, singletonServices = getSingletonServices(), ...input }) => {
     const outcomes = [];
     for (const meta of Object.values(pikkuState(null, 'trigger', 'webhookSourceMeta'))) {
-        const url = `${base}${meta.route}`;
-        const label = `${labelPrefix}:${meta.name}`;
-        const input = {
-            url,
-            label,
-            events: subscribedWebhookEvents(meta.name),
-            ...(previous[meta.name] ? { previous: previous[meta.name] } : {}),
-        };
-        const outcome = (status, extra = {}) => outcomes.push({ source: meta.name, url, status, ...extra });
-        try {
-            if (action === 'teardown') {
-                if (!meta.teardown) {
-                    outcome('skipped');
-                    continue;
-                }
-                const result = await runSourceStep(singletonServices, meta.name, meta.teardown, { label, ...(input.previous ? { previous: input.previous } : {}) });
-                outcome(result.status);
-                continue;
-            }
-            if (meta.check) {
-                const checked = await runSourceStep(singletonServices, meta.name, meta.check, input);
-                if (action === 'check' || checked.status === 'ok') {
-                    outcome(checked.status === 'ok' && action === 'setup'
-                        ? 'unchanged'
-                        : checked.status, checked.status === 'drifted' ? { reason: checked.reason } : {});
-                    continue;
-                }
-            }
-            else if (action === 'check') {
-                outcome('skipped');
-                continue;
-            }
-            if (!meta.setup) {
-                outcome('manual', {
-                    instructions: `Register ${url} with the provider for: ${input.events.join(', ') || 'every event'}.`,
+        outcomes.push(await runSourceLifecycleStep(meta, action, input, previous[meta.name], singletonServices));
+    }
+    return outcomes;
+};
+const requireTriggerSourceStore = (singletonServices) => {
+    const store = singletonServices.triggerSourceStore;
+    if (!store) {
+        throw new Error('No triggerSourceStore is configured');
+    }
+    return store;
+};
+/** The trigger sources this app declares, as the store is synced to. */
+export const declaredTriggerSources = () => Object.keys(pikkuState(null, 'trigger', 'webhookSourceMeta')).map((name) => ({
+    name,
+    kind: 'webhook',
+}));
+const detailOf = (outcome) => outcome.instructions ?? outcome.error ?? outcome.reason ?? null;
+/**
+ * Registers every declared webhook source with its provider: `check`, then
+ * `setup` where it is missing or drifted, recording what was registered.
+ * Run after a deployment goes live.
+ */
+export const reconcileTriggerSources = async ({ singletonServices = getSingletonServices(), ...input }) => {
+    const store = requireTriggerSourceStore(singletonServices);
+    await store.syncTriggerSources(declaredTriggerSources());
+    const outcomes = [];
+    for (const meta of Object.values(pikkuState(null, 'trigger', 'webhookSourceMeta'))) {
+        const row = await store.getTriggerSource(meta.name);
+        const outcome = await runSourceLifecycleStep(meta, 'setup', input, row?.state ?? undefined, singletonServices);
+        await store.recordTriggerSource(meta.name, {
+            status: outcome.status,
+            ...(outcome.state ? { state: outcome.state } : {}),
+            detail: detailOf(outcome),
+        });
+        outcomes.push(outcome);
+    }
+    return outcomes;
+};
+/**
+ * Removes the named webhook sources from their providers and forgets them.
+ * Run on the outgoing deployment for the sources the next release drops,
+ * since only the code that set a source up can tear it down.
+ */
+export const teardownTriggerSources = async ({ names, singletonServices = getSingletonServices(), ...input }) => {
+    const store = requireTriggerSourceStore(singletonServices);
+    const outcomes = [];
+    for (const name of names) {
+        const meta = getSourceMeta(name);
+        const row = await store.getTriggerSource(name);
+        const outcome = await runSourceLifecycleStep(meta, 'teardown', input, row?.state ?? undefined, singletonServices);
+        if (outcome.status === 'failed') {
+            if (row) {
+                await store.recordTriggerSource(name, {
+                    status: 'failed',
+                    detail: detailOf(outcome),
                 });
-                continue;
-            }
-            const result = await runSourceStep(singletonServices, meta.name, meta.setup, input);
-            if (result.status === 'manual') {
-                outcome('manual', { instructions: result.instructions });
-                continue;
             }
-            outcome(result.status, {
-                ...(result.state ? { state: result.state } : {}),
-                ...(result.secret && meta.secret
-                    ? { secretName: meta.secret, secret: result.secret }
-                    : {}),
-            });
         }
-        catch (error) {
-            outcome('failed', {
-                error: error instanceof Error ? error.message : String(error),
-            });
+        else {
+            await store.deleteTriggerSource(name);
         }
+        outcomes.push(outcome);
     }
     return outcomes;
 };

package/dist/wirings/trigger/webhook-source.types.d.ts

@@ -28,6 +28,7 @@ export type WebhookReceiveResult = {
         headers?: Record<string, string>;
     };
 };
+export type WebhookSourceMethod = 'post' | 'put' | 'get' | 'head';
 /** Whatever `setup` wants back on the next deploy, for providers whose endpoints cannot be found by label. */
 export type WebhookSourceState = Record<string, unknown>;
 export type WebhookLifecycleInput = {
@@ -50,8 +51,6 @@ export type WebhookCheckResult = {
 export type WebhookSetupResult = {
     status: 'created' | 'updated' | 'unchanged';
     state?: WebhookSourceState;
-    /** Only when the provider issued a new signing secret. */
-    secret?: string;
 }
 /** The provider has no API for this: `instructions` tell a person what to set by hand. */
  | {
@@ -71,11 +70,10 @@ type SourceFunction<In, Out> = CorePikkuFunctionConfig<any, any> & {
 export type CoreTriggerWebhookSource<Events extends Record<string, StandardSchemaV1> = Record<string, StandardSchemaV1>> = {
     /** Triggers subscribe to `<name>:<event>`. Unique across every kind of trigger source. */
     name: string;
-    method?: 'post' | 'put' | 'get';
+    /** Several for providers that verify the URL with a GET and deliver with a POST. */
+    method?: WebhookSourceMethod | WebhookSourceMethod[];
     /** Defaults to `/webhooks/<name>`. */
     route?: string;
-    /** The secret `receive` verifies with, which `setup` produces. */
-    secret?: string;
     /** What the source can produce. Each event's data is validated against its schema before it is queued. */
     events?: Events;
     /** Omitted: the JSON body is one event dispatched to the trigger named `<name>`. */
@@ -86,9 +84,8 @@ export type CoreTriggerWebhookSource<Events extends Record<string, StandardSchem
 };
 export type WebhookSourceMeta = {
     name: string;
-    method: 'post' | 'put' | 'get';
+    method: WebhookSourceMethod | WebhookSourceMethod[];
     route: string;
-    secret?: string;
     events: string[];
     receive?: string;
     check?: string;

package/dist/wirings/workflow/pikku-workflow-service.js

@@ -11,6 +11,7 @@ import { buildRunTimeline, reconstructStateAt, } from './run-timeline.js';
 import { DEFAULT_STEP_RETRIES, WORKFLOW_CHILD_POLL_MAX_MS, WORKFLOW_END_STATES, WORKFLOW_POLL_FACTOR, WORKFLOW_POLL_MIN_MS, WORKFLOW_TERMINAL_STATES, isRunSettled, } from './workflow-constants.js';
 import { WorkflowAsyncException, WorkflowCancelledException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotFoundError, WorkflowStepNameNotString, WorkflowSuspendedException, } from './workflow-errors.js';
 import { resolveWorkflowMeta } from './workflow-meta-resolver.js';
+import { storeWorkflowVersion } from './workflow-version-store.js';
 import { jobGroupFor, orchestratorQueueName, resolveWorkflowConfig, stepDispatchTarget, stepJobOptions, stepWorkerQueueName, } from './workflow-queue-routing.js';
 import { wireWorkflowQueueWorkers } from './workflow-queue-wiring.js';
 import { approvalStepNameFor, evaluateApprovalStep, recordApprovalDecision, } from './workflow-approval.js';
@@ -128,6 +129,7 @@ export class PikkuWorkflowService {
         }
     }
     async createRun(workflowName, input, inline, graphHash, wire, options) {
+        await storeWorkflowVersion(this, workflowName, graphHash);
         return this.mirrored(() => this.createRunImpl(workflowName, input, inline, graphHash, wire, options), (mirror, runId) => mirror.createRun(runId, workflowName, input, inline, graphHash, wire, options));
     }
     async getRunStatus(id) {

package/dist/wirings/workflow/workflow-version-store.d.ts

@@ -0,0 +1,8 @@
+import type { WorkflowService } from '../../services/workflow-service.js';
+type VersionStore = Pick<WorkflowService, 'upsertWorkflowVersion'>;
+/**
+ * Persists the graph a run starts on, so a run suspended across a deploy that
+ * changes the definition can still resume against the graph it began with.
+ */
+export declare const storeWorkflowVersion: (service: VersionStore, name: string, graphHash: string) => Promise<void>;
+export {};

package/dist/wirings/workflow/workflow-version-store.js

@@ -0,0 +1,21 @@
+import { resolveWorkflowMeta } from './workflow-meta-resolver.js';
+const storedVersions = new WeakMap();
+/**
+ * Persists the graph a run starts on, so a run suspended across a deploy that
+ * changes the definition can still resume against the graph it began with.
+ */
+export const storeWorkflowVersion = async (service, name, graphHash) => {
+    const key = `${name}:${graphHash}`;
+    let stored = storedVersions.get(service);
+    if (!stored) {
+        stored = new Set();
+        storedVersions.set(service, stored);
+    }
+    if (stored.has(key))
+        return;
+    const meta = resolveWorkflowMeta(name)?.meta;
+    if (!meta || meta.graphHash !== graphHash)
+        return;
+    await service.upsertWorkflowVersion(name, graphHash, meta, meta.source);
+    stored.add(key);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.127",
+  "version": "0.12.128",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",

package/src/public-surface.json

@@ -182,10 +182,13 @@
   "./trigger": [
     "PIKKU_INCOMING_WEBHOOK_QUEUE_NAME",
     "PikkuTriggerService",
+    "declaredTriggerSources",
     "dispatchWebhookSourceJob",
     "receiveWebhookSourceRequest",
+    "reconcileTriggerSources",
     "runWebhookSourceLifecycle",
     "subscribedWebhookEvents",
+    "teardownTriggerSources",
     "wireTrigger",
     "wireTriggerSource",
     "wireTriggerWebhookSource"
@@ -421,6 +424,7 @@
     "InMemoryQueueService",
     "InMemorySessionStore",
     "InMemoryTriggerService",
+    "InMemoryTriggerSourceStore",
     "InMemoryWorkflowService",
     "IncomingWebhookService",
     "JsonConsoleLogger",
@@ -514,7 +518,7 @@
     "verifyWithKeyMaterial",
     "wrapDEK"
   ],
-  "./hmac": ["hmacSha256Hex", "timingSafeStringEqual"],
+  "./hmac": ["WebhookSigningSecret", "hmacSha256Hex", "timingSafeStringEqual"],
   "./state": [
     "addPackageServiceFactories",
     "getAllPackageStates",