toolroll 0.9.63 → 0.9.65

package/dist/flow-share.js

@@ -24,7 +24,7 @@ import { addFlowTriggerTo, describeTrigger, HOOK_PATH, readHooksBase, triggerCon
 import { durationMinutes, durationWords, FlowContractError, flowTerms, inStepWords, LANGUAGE_WORDS, validateFlowDefinition } from "./flows.js";
 import { stageReferenceProblems } from "./contracts/stage-output.js";
 import { readVersioned } from "./contracts/contract.js";
-import { FLOW_ALIASES, FLOW_FILE_FORMAT, legacyFlowNeed, legacySubagentStep, FLOW_FILE_VERSION, flowFileSchema, PARAMETER_ID } from "./contracts/flow.js";
+import { FLOW_ALIASES, WEBHOOK_SENDERS, FLOW_FILE_FORMAT, legacyFlowNeed, legacySubagentStep, FLOW_FILE_VERSION, flowFileSchema, PARAMETER_ID } from "./contracts/flow.js";
 import { parseSchedule } from "./flow-schedule.js";
 export { FLOW_FILE_FORMAT, FLOW_FILE_VERSION };
 /** The largest flow file Toolroll reads or fetches. */
@@ -111,7 +111,13 @@ function triggerOf(config, ask) {
             ...(config.state === null ? {} : { state: config.state }),
             ...(config.label === null ? {} : { label: ask({ id: "linear-label", about: "The Linear label issues need", default: config.label }) }),
             delivery: config.delivery, ...zone };
-        case "webhook": return { kind: "webhook", title: config.title, ...(config.titleField === null ? {} : { titleField: config.titleField }), ...(config.bodyField === null ? {} : { bodyField: config.bodyField }), ...zone };
+        // v126: who signs it travels (never its secret or address: an imported signed webhook isn't set up until its
+        // secret is made or pasted there); the project and team it is scoped to are asked again, as another install's own.
+        case "webhook": return { kind: "webhook", title: config.title, ...(config.titleField == null ? {} : { titleField: config.titleField }), ...(config.bodyField == null ? {} : { bodyField: config.bodyField }),
+            ...((config.sender ?? "none") === "none" ? {} : { sender: config.sender }),
+            ...(config.project == null ? {} : { project: ask({ id: "webhook-project", about: "The project the signed webhook's deliveries must come from", default: config.project }) }),
+            ...(config.team == null ? {} : { team: ask({ id: "webhook-team", about: "The Vercel team the deliveries must come from", default: config.team }) }),
+            ...(config.idField == null ? {} : { idField: config.idField }), ...(config.urlField == null ? {} : { urlField: config.urlField }), ...zone };
         case "email": return { kind: "email", folder: config.folder,
             ...(config.sender === null ? {} : { sender: ask({ id: "email-sender", about: "Whose mail starts cards: addresses or domains, comma-separated (left empty: anyone's)", optional: true }) }),
             ...(config.subject === null ? {} : { subject: config.subject }), ...zone };
@@ -192,8 +198,13 @@ function scrubDeep(value, scrub, key, inScripts) {
         return key !== null && (STRUCTURAL.has(key) || (inScripts && key === "name")) ? value : scrub(value);
     if (Array.isArray(value))
         return value.map(one => scrubDeep(one, scrub, key, inScripts));
-    if (value !== null && typeof value === "object")
-        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, scrubDeep(v, scrub, k, inScripts || k === "scripts")]));
+    if (value !== null && typeof value === "object") {
+        // v126: a webhook's sender is one of a fixed few words (who signs it), never prose: kept as it is, even when an
+        // account happens to share its name. An email trigger's sender is people's addresses, and is still scrubbed.
+        const record = value;
+        const webhookSender = record["kind"] === "webhook" && typeof record["sender"] === "string" && WEBHOOK_SENDERS.includes(record["sender"]);
+        return Object.fromEntries(Object.entries(record).map(([k, v]) => [k, webhookSender && k === "sender" ? v : scrubDeep(v, scrub, k, inScripts || k === "scripts")]));
+    }
     return value;
 }
 /** A flow as a file: its zones and paths, its triggers' settings and the scripts it runs, nothing of this installation's. */
@@ -530,7 +541,7 @@ export function importFlow(store, plan, actor, now, dir) {
         }
         const id = store.createFlow({ repo: plan.repo, name: plan.name, definitionJson: JSON.stringify(plan.definition), by: actor }, now);
         for (const trigger of plan.triggers) {
-            const made = addFlowTriggerTo(store, store.getFlow(id), trigger, actor, now, dir);
+            const made = addFlowTriggerTo(store, store.getFlow(id), trigger, actor, now, dir, { shown: false });
             if (!made.ok)
                 throw new FlowFileError(`A ${String(trigger["kind"])} trigger: ${made.message}`);
             store.updateFlowTrigger(made.id, { state: "paused" }, now);

package/dist/flow-triggers.d.ts

@@ -1,6 +1,7 @@
 import type { Runner } from "./backend.js";
 import { type FlowAct } from "./flow-engine.js";
 import { type FlowDefinition } from "./flows.js";
+import { type DistinctHeaders, type WebhookSender } from "./webhook-signing.js";
 import { type ContractResult } from "./contracts/contract.js";
 import { FLOW_TRIGGER_KINDS, type ChatApp, type FlowTriggerKind, type TriggerConfig, type TriggerInput } from "./contracts/flow.js";
 import { type MailReader } from "./mailbox.js";
@@ -49,11 +50,18 @@ export declare function triggerHeadline(config: TriggerConfig, store: Store): {
 export declare function triggerConfigOf(trigger: FlowTriggerRow): TriggerConfig | null;
 /** A saved trigger's config (`configJson`, which carries no version) read by its one schema, what it leaves out filled. */
 export declare function readTriggerConfig(raw: unknown): ContractResult<TriggerConfig>;
+/** v126: who signs a webhook trigger's deliveries; one saved before senders were chosen is unsigned. */
+export declare const senderOf: (config: Extract<TriggerConfig, {
+    kind: "webhook";
+}>) => WebhookSender;
 /** Whether this trigger takes deliveries at a secret address rather than being checked. */
+/** Whether a raw trigger the caller is about to add would take deliveries (an address): read leniently, before validation. */
+export declare function rawTakesDeliveries(raw: unknown): boolean;
 export declare function takesDeliveries(config: TriggerConfig): boolean;
-/** A webhook's signing secret (GitHub: made here; Linear: pasted from Linear). In the keychain (or an owner-only file where there's none), never a column. */
-export declare function saveHookSecret(dir: string, trigger: number, secret: string): void;
-export declare function readHookSecret(dir: string, trigger: number): string | null;
+/** A webhook's signing secret (made here, or pasted from its sender). In the keychain (or an owner-only file where there's none), never a column. */
+export declare function saveHookSecret(dir: string, trigger: number, secret: string, credential?: string): void;
+/** Exactly this credential's secret, or null: never another's. */
+export declare function readHookSecret(dir: string, trigger: number, credential?: string): string | null;
 export declare const LINEAR_ENV = "TOOLROLL_LINEAR_KEY";
 /** The Linear API key the worker checks Linear with: the environment, or kept by Toolroll (the keychain, or an owner-only file beside the database). */
 export declare function readLinearKey(dir: string | null): string | null;
@@ -89,7 +97,15 @@ export type TriggerMade = {
     message: string;
 };
 /** Add a trigger to a flow. A webhook trigger's address (and GitHub's signing secret) is returned once and never stored readable. */
-export declare function addFlowTriggerTo(store: Store, flow: FlowRow, raw: unknown, actor: string, now: Date, dir: string | null): TriggerMade;
+/**
+ * `ingress: "proved"`: the caller proved a password typed now (a credential act, docs/plans/passwordless.md) — only then
+ * may a trigger that takes deliveries be made with an address. Without it a webhook is made with none (its panel's
+ * set-up, which asks for the password, makes one), and GitHub/Linear webhook delivery is refused.
+ */
+export declare function addFlowTriggerTo(store: Store, flow: FlowRow, raw: unknown, actor: string, now: Date, dir: string | null, options?: {
+    shown?: boolean;
+    ingress?: "proved";
+}): TriggerMade;
 /** A new secret address for a webhook trigger (the old one stops working at once). */
 export declare function renewFlowHook(store: Store, trigger: FlowTriggerRow, now: Date, dir: string): TriggerMade;
 /**
@@ -189,24 +205,77 @@ export declare const LINEAR_QUERY = "query FlowTrigger($filter: IssueFilter) { i
 export declare function linearItem(config: Extract<TriggerConfig, {
     kind: "linear";
 }>, raw: unknown): Found | null;
+/** v126: headers as Node's `headersDistinct` gives them, one value per line they arrived on, so a security header sent
+ * twice is seen twice (Node's `headers` joins repeated custom headers with commas). */
 export type HookDelivery = {
-    headers: Record<string, string | string[] | undefined>;
+    headers: DistinctHeaders;
     body: Buffer;
 };
+/** `retryAfter` (seconds): a 429's Retry-After. */
 export type HookAnswer = {
     status: number;
     said: string;
+    retryAfter?: number;
 };
 /** A webhook delivery at a trigger's secret address: prove it, read it, make at most the cards it names. Nothing runs here. */
 export declare function receiveFlowHook(store: Store, token: string, delivery: HookDelivery, dir: string, now: Date): HookAnswer;
-/** Save Linear's signing secret for a Linear webhook trigger (pasted on the secure panel, never in chat). */
-export declare function saveLinearSigningSecret(trigger: FlowTriggerRow, secret: string, dir: string): {
+/**
+ * v126: make a trigger's held deliveries into their cards while the last hour has room, oldest first. Each card in its
+ * own write transaction, which reads everything it acts on under the write lock: the trigger (still active, still
+ * taking deliveries), the hour's room, the oldest held receipt, the flow; then the same guards intake has (a failing
+ * run already owned by another card in the project is left out). The card and the receipt's move to accepted land
+ * together, or neither does.
+ */
+export declare function drainHeldDeliveries(store: Store, trigger: FlowTriggerRow, now: Date): number;
+/**
+ * v126: a delivery refused before it could be read (too large, a body that wouldn't read): it proves nothing, so it
+ * counts toward its address's minute like any unproven delivery. The answer to give instead when that count is over.
+ */
+export declare function hookRefusedUnread(store: Store, token: string, now: Date): HookAnswer | null;
+/** A signing secret pasted on the secure panel behind the password, never in chat: Linear's, or a signed webhook's
+ * sender's (Sentry's or Vercel's own, or a Standard or GitHub-style one made elsewhere). */
+export declare function saveSigningSecret(store: Store, trigger: FlowTriggerRow, secret: string, now: Date, dir: string): {
     ok: true;
+    said: string;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * v126: a new secret for a webhook whose sender Toolroll makes secrets for (Standard Webhooks, GitHub-style), shown once.
+ * Its address stays as it is (New address is its own action). Sentry's and Vercel's secrets are theirs, pasted instead.
+ * The only place such a secret is made: creating a trigger (from the panel, the gallery or an import) never does.
+ */
+export declare function setUpFlowHook(store: Store, trigger: FlowTriggerRow, now: Date, dir: string): TriggerMade;
+/**
+ * v126: change who signs a webhook's deliveries, in place: the trigger keeps its id, address and what it has received
+ * (keys carry the sender, so nothing received unsigned stands for anything signed). Its credentials move to the next
+ * generation with no secret: it isn't ready until it is set up again. Settings the new sender doesn't read are left out.
+ */
+export declare function changeFlowHookSender(store: Store, trigger: FlowTriggerRow, sender: unknown, actor: string, now: Date, dir: string): {
+    ok: true;
+    said: string;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * v126: which project (and, for Vercel, team) a Sentry or Vercel webhook takes deliveries from, set in place: the
+ * trigger keeps its id, address, secret and history; blank takes any project the secret covers. Only from the settings
+ * read here, so a change racing it doesn't land on top of it.
+ */
+export declare function setFlowHookScope(store: Store, trigger: FlowTriggerRow, scope: {
+    project: unknown;
+    team: unknown;
+}, actor: string, now: Date): {
+    ok: true;
+    said: string;
 } | {
     ok: false;
     message: string;
 };
-/** Whether a webhook trigger can prove its deliveries: GitHub always (its secret is made here), Linear once its secret is pasted. */
+/** Whether a webhook trigger can prove its deliveries: an unsigned webhook always (its address is all it has), the others
+ * once the current generation's secret is saved. */
 export declare function hookReady(trigger: FlowTriggerRow, dir: string | null): boolean;
 export declare const FORM_PATH = "/hooks/form/";
 /** Share a button as a secret link anyone can fill in, without signing in. The link is shown once; only its hash is kept. */