@pikku/core 0.12.129 → 0.12.133

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

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

@@ -1,7 +1,7 @@
 export { wireTrigger, wireTriggerSource } from './trigger-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, WebhookSourceMethod, WebhookSourcesMeta, WebhookSourceState, WebhookTeardownInput, WebhookTeardownResult, } from './webhook-source.types.js';
+export { wireTriggerWebhookSource, receiveWebhookSourceRequest, dispatchWebhookSourceJob, runWebhookSourceLifecycle, declaredTriggerSources, reconcileTriggerSources, enableTriggerSource, disableTriggerSource, reconcileWebhookRegistrations, teardownTriggerSources, subscribedWebhookEvents, } from './webhook-source-runner.js';
+export type { OrphanedWebhookRegistration, WebhookRegistration, WebhookRegistrations, WebhookSourceOutcome, } from './webhook-source-runner.js';
+export { PIKKU_INCOMING_WEBHOOK_QUEUE_NAME, webhookSecretCredentialName, } from './webhook-source.types.js';
+export type { CoreTriggerWebhookSource, TriggerEvent, WebhookCheckResult, WebhookLifecycleInput, WebhookReceiveResult, WebhookRequest, WebhookSetupResult, WebhookSourceJob, WebhookSourceMeta, WebhookSourceMethod, WebhookSourcesMeta, WebhookSourceState, WebhookTeardownInput, WebhookTeardownResult, WebhookVerify, } 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, declaredTriggerSources, reconcileTriggerSources, teardownTriggerSources, subscribedWebhookEvents, } from './webhook-source-runner.js';
-export { PIKKU_INCOMING_WEBHOOK_QUEUE_NAME } from './webhook-source.types.js';
+export { wireTriggerWebhookSource, receiveWebhookSourceRequest, dispatchWebhookSourceJob, runWebhookSourceLifecycle, declaredTriggerSources, reconcileTriggerSources, enableTriggerSource, disableTriggerSource, reconcileWebhookRegistrations, teardownTriggerSources, subscribedWebhookEvents, } from './webhook-source-runner.js';
+export { PIKKU_INCOMING_WEBHOOK_QUEUE_NAME, webhookSecretCredentialName, } from './webhook-source.types.js';
 export { PikkuTriggerService } from './pikku-trigger-service.js';

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

@@ -9,7 +9,8 @@ export declare const subscribedWebhookEvents: (source: string) => string[];
 /**
  * The body of a webhook source's route: `receive`, validate, and queue every
  * event some trigger listens for. Events nobody listens for are answered and
- * dropped, so the provider does not retry them forever.
+ * dropped, so the provider does not retry them forever. With a
+ * `triggerSourceStore`, a source nobody enabled answers 404.
  */
 export declare const receiveWebhookSourceRequest: (sourceName: string, wire: {
     http?: PikkuHTTP;
@@ -44,15 +45,61 @@ export declare const runWebhookSourceLifecycle: ({ action, previous, singletonSe
     singletonServices?: CoreSingletonServices;
 }) => Promise<WebhookSourceOutcome[]>;
 /** The trigger sources this app declares, as the store is synced to. */
-export declare const declaredTriggerSources: () => DeclaredTriggerSource[];
+export declare const declaredTriggerSources: (address?: LifecycleInput) => DeclaredTriggerSource[];
 /**
- * Registers every declared webhook source with its provider: `check`, then
+ * Registers every enabled webhook source with its provider: `check`, then
  * `setup` where it is missing or drifted, recording what was registered.
- * Run after a deployment goes live.
+ * A source nobody enabled is skipped. Run after a deployment goes live.
  */
 export declare const reconcileTriggerSources: ({ singletonServices, ...input }: LifecycleInput & {
     singletonServices?: CoreSingletonServices;
 }) => Promise<WebhookSourceOutcome[]>;
+type SwitchInput = Partial<LifecycleInput> & {
+    name: string;
+    singletonServices?: CoreSingletonServices;
+};
+/**
+ * Turns a declared webhook source on and registers it with its provider, at
+ * the address given or the one the last deployment recorded.
+ */
+export declare const enableTriggerSource: ({ singletonServices, ...input }: SwitchInput) => Promise<WebhookSourceOutcome>;
+/**
+ * Turns a webhook source off: it stops receiving at once, then is removed
+ * from its provider. A failed teardown leaves it off and records the error.
+ */
+export declare const disableTriggerSource: ({ singletonServices, ...input }: SwitchInput) => Promise<WebhookSourceOutcome>;
+/** What one source registered with its provider, as a caller keeps it between runs. */
+export type WebhookRegistration = {
+    url: string;
+    events: string[];
+    status: WebhookSourceOutcome['status'];
+    state?: WebhookSourceState;
+    /** The signing secrets `setup` stored, so a wiped credential store can be refilled without registering again. */
+    credentials?: Record<string, unknown>;
+};
+export type WebhookRegistrations = Record<string, WebhookRegistration>;
+export type OrphanedWebhookRegistration = {
+    source: string;
+    url: string;
+    label: string;
+};
+/**
+ * Registers every declared webhook source against registrations the caller
+ * keeps rather than a `triggerSourceStore`, as `pikku dev` does in a file that
+ * outlives its database. A source whose url and events match what was
+ * registered is left alone without calling the provider, and its signing
+ * secrets are put back if the credential store lost them. Registrations no
+ * source declares any more are returned as orphans and kept, since only the
+ * code that set one up could tear it down.
+ */
+export declare const reconcileWebhookRegistrations: ({ registrations, singletonServices, ...input }: LifecycleInput & {
+    registrations: WebhookRegistrations;
+    singletonServices?: CoreSingletonServices;
+}) => Promise<{
+    registrations: WebhookRegistrations;
+    outcomes: WebhookSourceOutcome[];
+    orphans: OrphanedWebhookRegistration[];
+}>;
 /**
  * Removes the named webhook sources from their providers and forgets them.
  * Run on the outgoing deployment for the sources the next release drops,

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

@@ -1,6 +1,8 @@
 import { getSingletonServices, pikkuState } from '../../pikku-state.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
-import { PikkuMissingMetaError } from '../../errors/errors.js';
+import { PikkuMissingMetaError, UnauthorizedError, } from '../../errors/errors.js';
+import { timingSafeStringEqual, verifyHmacSignature, verifyPublicKeySignature, } from '../../utils/hmac.js';
+import { webhookSecretCredentialName } from './webhook-source.types.js';
 const LIFECYCLE = ['receive', 'check', 'setup', 'teardown'];
 export const wireTriggerWebhookSource = (source) => {
     const meta = pikkuState(null, 'trigger', 'webhookSourceMeta')[source.name];
@@ -59,6 +61,44 @@ const readRequest = async (http) => {
         query,
     };
 };
+const signedWith = async (verify, request, secret, services) => {
+    if (typeof verify === 'function') {
+        return await verify(request, secret, services);
+    }
+    const header = (name, prefix = '') => {
+        const value = request.headers[name.toLowerCase()];
+        return value?.startsWith(prefix) ? value.slice(prefix.length) : undefined;
+    };
+    if ('hmac' in verify) {
+        const { header: name, prefix, algorithm, encoding, secretEncoding } = verify.hmac;
+        return verifyHmacSignature(secret, header(name, prefix), algorithm, request.body, encoding, secretEncoding);
+    }
+    if ('token' in verify) {
+        const token = header(verify.token.header, verify.token.prefix);
+        return !!token && timingSafeStringEqual(token, secret);
+    }
+    const { header: name, ...options } = verify.publicKey;
+    return verifyPublicKeySignature(secret, header(name), request.body, options);
+};
+/**
+ * Whether the request was checked against the source's signing secret. Throws
+ * when it was checked and failed. A source without `verify` checks in its own
+ * `receive`, and a request without a body has nothing signed to check.
+ */
+const verifyRequest = async (source, request, services) => {
+    if (!source?.verify)
+        return true;
+    if (request.body.length === 0)
+        return false;
+    const secret = await services.credentialService?.get(source.credential ?? webhookSecretCredentialName(source.name));
+    if (typeof secret !== 'string' || !secret) {
+        throw new UnauthorizedError(`The ${source.name} webhook source has no signing secret`);
+    }
+    if (!(await signedWith(source.verify, request, secret, services))) {
+        throw new UnauthorizedError(`Invalid ${source.name} webhook signature`);
+    }
+    return true;
+};
 const validateEvents = async (source, events, logger) => {
     const valid = [];
     for (const event of events) {
@@ -79,13 +119,19 @@ const validateEvents = async (source, events, logger) => {
 /**
  * The body of a webhook source's route: `receive`, validate, and queue every
  * event some trigger listens for. Events nobody listens for are answered and
- * dropped, so the provider does not retry them forever.
+ * dropped, so the provider does not retry them forever. With a
+ * `triggerSourceStore`, a source nobody enabled answers 404.
  */
 export const receiveWebhookSourceRequest = async (sourceName, wire) => {
     const singletonServices = getSingletonServices();
     const meta = getSourceMeta(sourceName);
+    const store = singletonServices.triggerSourceStore;
+    if (store && !(await store.getTriggerSource(sourceName))?.enabled) {
+        return new Response(null, { status: 404 });
+    }
     const source = pikkuState(null, 'trigger', 'webhookSources').get(sourceName);
     const request = await readRequest(wire.http);
+    const verified = await verifyRequest(source, request, singletonServices);
     const result = meta.receive
         ? await runSourceStep(singletonServices, sourceName, meta.receive, request)
         : {
@@ -107,6 +153,9 @@ export const receiveWebhookSourceRequest = async (sourceName, wire) => {
                 : JSON.stringify(body);
         return new Response(text, { status, headers });
     }
+    if (!verified && result.events.length > 0) {
+        throw new UnauthorizedError(`The ${sourceName} webhook source received events in an unsigned request`);
+    }
     const triggers = pikkuState(null, 'trigger', 'meta');
     const listened = result.events.filter((event) => triggers[triggerName(sourceName, event.name)]);
     const events = await validateEvents(source, listened, singletonServices.logger);
@@ -152,9 +201,12 @@ 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 sourceAddress = (meta, { baseUrl, labelPrefix }) => ({
+    url: `${baseUrl.replace(/\/+$/, '')}${meta.route}`,
+    label: `${labelPrefix}:${meta.name}`,
+});
+const runSourceLifecycleStep = async (meta, action, lifecycleInput, previous, singletonServices) => {
+    const { url, label } = sourceAddress(meta, lifecycleInput);
     const input = {
         url,
         label,
@@ -217,31 +269,165 @@ const requireTriggerSourceStore = (singletonServices) => {
     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) => ({
+export const declaredTriggerSources = (address) => Object.keys(pikkuState(null, 'trigger', 'webhookSourceMeta')).map((name) => ({
     name,
     kind: 'webhook',
+    ...address,
 }));
 const detailOf = (outcome) => outcome.instructions ?? outcome.error ?? outcome.reason ?? null;
+const registerTriggerSource = async (store, meta, input, previous, singletonServices) => {
+    const outcome = await runSourceLifecycleStep(meta, 'setup', input, previous, singletonServices);
+    await store.recordTriggerSource(meta.name, {
+        status: outcome.status,
+        ...(outcome.state ? { state: outcome.state } : {}),
+        detail: detailOf(outcome),
+    });
+    return outcome;
+};
 /**
- * Registers every declared webhook source with its provider: `check`, then
+ * Registers every enabled webhook source with its provider: `check`, then
  * `setup` where it is missing or drifted, recording what was registered.
- * Run after a deployment goes live.
+ * A source nobody enabled is skipped. Run after a deployment goes live.
  */
 export const reconcileTriggerSources = async ({ singletonServices = getSingletonServices(), ...input }) => {
     const store = requireTriggerSourceStore(singletonServices);
-    await store.syncTriggerSources(declaredTriggerSources());
+    await store.syncTriggerSources(declaredTriggerSources({
+        baseUrl: input.baseUrl,
+        labelPrefix: input.labelPrefix,
+    }));
     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, {
+        if (!row?.enabled) {
+            outcomes.push({
+                source: meta.name,
+                url: sourceAddress(meta, input).url,
+                status: 'skipped',
+                reason: 'disabled',
+            });
+            continue;
+        }
+        outcomes.push(await registerTriggerSource(store, meta, input, row.state ?? undefined, singletonServices));
+    }
+    return outcomes;
+};
+/** The address given, or the one the last deployment synced onto the row. */
+const switchAddress = (row, { baseUrl, labelPrefix, name }) => {
+    const address = {
+        baseUrl: baseUrl ?? row?.baseUrl,
+        labelPrefix: labelPrefix ?? row?.labelPrefix,
+    };
+    if (!address.baseUrl || !address.labelPrefix) {
+        throw new Error(`Trigger source '${name}' has no address yet: pass baseUrl and labelPrefix, or deploy so reconcile records them.`);
+    }
+    return address;
+};
+/**
+ * Turns a declared webhook source on and registers it with its provider, at
+ * the address given or the one the last deployment recorded.
+ */
+export const enableTriggerSource = async ({ singletonServices = getSingletonServices(), ...input }) => {
+    const store = requireTriggerSourceStore(singletonServices);
+    const meta = getSourceMeta(input.name);
+    await store.syncTriggerSources(declaredTriggerSources());
+    const row = await store.getTriggerSource(input.name);
+    const address = switchAddress(row, input);
+    await store.setTriggerSourceEnabled(input.name, true);
+    return registerTriggerSource(store, meta, address, row?.state ?? undefined, singletonServices);
+};
+/**
+ * Turns a webhook source off: it stops receiving at once, then is removed
+ * from its provider. A failed teardown leaves it off and records the error.
+ */
+export const disableTriggerSource = async ({ singletonServices = getSingletonServices(), ...input }) => {
+    const store = requireTriggerSourceStore(singletonServices);
+    const meta = getSourceMeta(input.name);
+    const row = await store.getTriggerSource(input.name);
+    const address = switchAddress(row, input);
+    await store.setTriggerSourceEnabled(input.name, false);
+    const outcome = await runSourceLifecycleStep(meta, 'teardown', address, row?.state ?? undefined, singletonServices);
+    await store.recordTriggerSource(input.name, {
+        status: outcome.status,
+        ...(outcome.status === 'failed' ? {} : { state: null }),
+        detail: detailOf(outcome),
+    });
+    return outcome;
+};
+/** The singleton credentials the package owning a source's `setup` declares: where its signing secret goes. */
+const sourceCredentialNames = (meta) => {
+    if (!meta.setup)
+        return [];
+    const namespace = meta.setup.includes(':') ? meta.setup.split(':')[0] : '';
+    const packageName = pikkuState(null, 'addons', 'packages').get(namespace)?.package ?? null;
+    const declared = pikkuState(packageName, 'package', 'credentialsMeta') ?? {};
+    return Object.entries(declared)
+        .filter(([, credential]) => credential.type === 'singleton' && !credential.oauth2)
+        .map(([name]) => name);
+};
+const sameEvents = (a, b) => a.length === b.length && a.every((event) => b.includes(event));
+/**
+ * Registers every declared webhook source against registrations the caller
+ * keeps rather than a `triggerSourceStore`, as `pikku dev` does in a file that
+ * outlives its database. A source whose url and events match what was
+ * registered is left alone without calling the provider, and its signing
+ * secrets are put back if the credential store lost them. Registrations no
+ * source declares any more are returned as orphans and kept, since only the
+ * code that set one up could tear it down.
+ */
+export const reconcileWebhookRegistrations = async ({ registrations, singletonServices = getSingletonServices(), ...input }) => {
+    const credentialService = singletonServices.credentialService;
+    const sources = pikkuState(null, 'trigger', 'webhookSourceMeta');
+    const next = {};
+    const outcomes = [];
+    for (const meta of Object.values(sources)) {
+        const { url } = sourceAddress(meta, input);
+        const events = subscribedWebhookEvents(meta.name);
+        const previous = registrations[meta.name];
+        const names = sourceCredentialNames(meta);
+        if (credentialService) {
+            for (const [name, value] of Object.entries(previous?.credentials ?? {})) {
+                if (!(await credentialService.has(name))) {
+                    await credentialService.set(name, value);
+                }
+            }
+        }
+        if (previous &&
+            previous.status !== 'failed' &&
+            previous.url === url &&
+            sameEvents(previous.events, events)) {
+            next[meta.name] = previous;
+            outcomes.push({ source: meta.name, url, status: 'unchanged' });
+            continue;
+        }
+        const outcome = await runSourceLifecycleStep(meta, 'setup', input, previous?.state, singletonServices);
+        const credentials = {};
+        for (const name of names) {
+            const value = await credentialService?.get(name);
+            if (value != null)
+                credentials[name] = value;
+        }
+        const state = outcome.state ?? previous?.state;
+        next[meta.name] = {
+            url,
+            events,
             status: outcome.status,
-            ...(outcome.state ? { state: outcome.state } : {}),
-            detail: detailOf(outcome),
-        });
+            ...(state ? { state } : {}),
+            ...(Object.keys(credentials).length ? { credentials } : {}),
+        };
         outcomes.push(outcome);
     }
-    return outcomes;
+    const orphans = [];
+    for (const [source, registration] of Object.entries(registrations)) {
+        if (sources[source])
+            continue;
+        next[source] = registration;
+        orphans.push({
+            source,
+            url: registration.url,
+            label: `${input.labelPrefix}:${source}`,
+        });
+    }
+    return { registrations: next, outcomes, orphans };
 };
 /**
  * Removes the named webhook sources from their providers and forgets them.