@relayflows/sdk 2.0.8 → 2.0.10

package/src/slack-writeback.ts

@@ -0,0 +1,63 @@
+import { slackClient } from '@relayfile/relay-helpers';
+import type { RelayTransport } from '@relayfile/relay-helpers/transport';
+import type { SlackHelper } from '@relayflows/surface';
+import { helperTransport } from './helper-writeback.js';
+export { atomicJson, receiptPath, readHelperReceipt as readSlackReceipt } from './helper-storage.js';
+
+export type SlackCall =
+  | { type: 'effect'; provider: 'slack'; verb: 'post'; params: { channel: string; text: Parameters<SlackHelper['post']>[1]; opts?: Parameters<SlackHelper['post']>[2] } }
+  | { type: 'effect'; provider: 'slack'; verb: 'dm'; params: { user: string; text: string } }
+  | { type: 'effect'; provider: 'slack'; verb: 'reply'; params: { channel: string; threadTs: string; text: string } }
+  | { type: 'effect'; provider: 'slack'; verb: 'react'; params: { channel: string; messageTs: string; emoji: string } };
+
+interface SlackPostBodyExtras { text?: string; dropText: boolean; blocks?: unknown; attachments?: unknown }
+
+// Slice Y widened SlackPostMessage to carry blocks/attachments; the transport
+// body is otherwise built by slackClient, which only sees the flattened text.
+// Reconstruct the intended body by projecting from the original call.params.
+function slackPostBodyExtras(params: Extract<SlackCall, { verb: 'post' }>['params']): SlackPostBodyExtras {
+  const extras: SlackPostBodyExtras = { dropText: false };
+  const t = params.text;
+  const opts = params.opts as { blocks?: unknown; attachments?: unknown } | undefined;
+  if (typeof t === 'object' && t !== null) {
+    if ('text' in t && typeof t.text === 'string') extras.text = t.text;
+    else extras.dropText = true;
+    if ('blocks' in t && t.blocks !== undefined) extras.blocks = t.blocks;
+    if ('attachments' in t && t.attachments !== undefined) extras.attachments = t.attachments;
+  }
+  if (opts?.blocks !== undefined) extras.blocks = opts.blocks;
+  if (opts?.attachments !== undefined) extras.attachments = opts.attachments;
+  return extras;
+}
+
+function wrapSlackPostTransport(transport: RelayTransport, extras: SlackPostBodyExtras): RelayTransport {
+  return {
+    read: transport.read.bind(transport),
+    list: transport.list.bind(transport),
+    async write(request) {
+      const body = { ...request.body as Record<string, unknown> };
+      if (extras.dropText) delete body.text;
+      else if (extras.text !== undefined) body.text = extras.text;
+      if (extras.blocks !== undefined) body.blocks = extras.blocks;
+      if (extras.attachments !== undefined) body.attachments = extras.attachments;
+      return transport.write({ ...request, body });
+    },
+  };
+}
+
+export async function slackWriteback(
+  call: SlackCall, dataDir: string, runId: string, stepId: string, signal: AbortSignal,
+): Promise<unknown> {
+  const { transport, deliveredRef } = helperTransport(call, dataDir, runId, stepId, signal);
+  const effectiveTransport = call.verb === 'post'
+    ? wrapSlackPostTransport(transport, slackPostBodyExtras(call.params))
+    : transport;
+  const client = slackClient({ transport: effectiveTransport });
+  switch (call.verb) {
+    case 'post': return client.post(call.params.channel,
+      typeof call.params.text === 'string' ? call.params.text : call.params.text.text ?? '', call.params.opts);
+    case 'dm': return client.dm(call.params.user, call.params.text);
+    case 'reply': return { ...await client.reply(call.params.channel, call.params.threadTs, call.params.text), ref: deliveredRef() };
+    case 'react': await client.react(call.params.channel, call.params.messageTs, call.params.emoji); return null;
+  }
+}

package/src/spec.ts

@@ -15,11 +15,24 @@ export type { JsonOutputSchema } from './output-schema.js';
 /** The three rungs of the ladder (RFC §1; AGENTS.md rule 7). */
 export type StepType = 'deterministic' | 'llm' | 'agent';
 
+/** Project-owned MCP connections. env contains names, never secret values. */
+export type McpServerConfig =
+  | { command: string; args?: string[]; env?: string[] }
+  | { url: string; headers?: Record<string, string> };
+
+export interface FlowsJson {
+  deploy?: { bucket: string };
+  cli?: string;
+  executors?: string[];
+  models?: string[];
+  mcp?: Record<string, McpServerConfig>;
+}
+
 /**
  * Verification is control flow, not decoration (kernel DESIGN.md §3).
  * v0 gates are deterministic so verification is kernel-side and replayable.
  */
-export type VerificationGateType = 'exit_code' | 'output_contains' | 'json_schema';
+export type VerificationGateType = VerificationSpec['type'];
 
 /**
  * `exit_code == 0` — the implicit gate for deterministic steps. v0 judges
@@ -43,8 +56,35 @@ export interface JsonSchemaGate {
   schema: boolean | Record<string, unknown>;
 }
 
-export type VerificationSpec = ExitCodeGate | OutputContainsGate | JsonSchemaGate;
-export type OutputVerificationSpec = OutputContainsGate | JsonSchemaGate;
+export interface ReferencesInputGate {
+  type: 'references_input';
+  input_key: string;
+  in_output_at?: Array<string | number>;
+}
+
+export interface SubprocessGate {
+  type: 'subprocess_gate';
+  command: string;
+  from_output?: Array<string | number>;
+}
+
+export interface WordCountBoundsGate {
+  type: 'word_count_bounds';
+  min?: number;
+  max?: number;
+}
+
+export interface RegexMatchGate {
+  type: 'regex_match';
+  pattern: string;
+  in_output_at?: Array<string | number>;
+  /** Only i, m, and s; evaluated by a non-backtracking RE2 engine. */
+  flags?: string;
+}
+
+export type NamedDataGate = ReferencesInputGate | SubprocessGate | WordCountBoundsGate | RegexMatchGate;
+export type OutputVerificationSpec = OutputContainsGate | JsonSchemaGate | NamedDataGate;
+export type VerificationSpec = ExitCodeGate | OutputVerificationSpec;
 
 /**
  * Agent-step recovery modes (RFC Appendix A rule 4). Default is `reset`.
@@ -88,6 +128,11 @@ export interface PermissionsSpec {
  * are integers.
  */
 export interface BudgetSpec {
+  /** Set when normalizing the surface budget header. Legacy explicit envelopes accept worker-supplied prices. */
+  pricing?: 'frozen';
+  maxTokens?: number;
+  maxWallclockMs?: number;
+  window?: 'day';
   maxTokensIn?: number;
   maxTokensOut?: number;
   /** Decimal string, e.g. "1.50". */
@@ -124,6 +169,8 @@ export interface KernelPlacementRequirements extends Omit<PlacementRequirements,
 
 /** Fields shared by every step on the ladder. */
 export interface BaseStepSpec {
+  /** Named values selected from earlier steps' declared, verified outputs. */
+  input?: Record<string, OutputBinding>;
   requirements?: PlacementRequirements;
   memory?: MemorySpec;
   /** Stable step identity; journaled as `step_id` and hashed into the idempotency key. */
@@ -135,6 +182,12 @@ export interface BaseStepSpec {
   maxIterations?: number;
 }
 
+export interface OutputBinding {
+  step: string;
+  /** Object keys or array indices; omit to select the whole output. */
+  path?: Array<string | number>;
+}
+
 /**
  * Rung 1 — a pure script. Executed by the `relayflowd` binary: spawn command,
  * capture stdout/exit code. Output = `{exit_code, stdout_tail}`. Gate-1
@@ -145,6 +198,8 @@ export interface DeterministicStepSpec extends BaseStepSpec {
   command: string;
   /** Wall-clock command timeout; worker-backed verbs own their dispatch timeout. */
   timeoutMs?: number;
+  /** Per-invocation deterministic lease in milliseconds (maximum 15 minutes). */
+  lease_ms?: number;
   /** Omit to get the implicit `exit_code` gate. */
   verification?: VerificationSpec;
 }
@@ -192,6 +247,14 @@ export interface AgentStepSpec extends BaseStepSpec {
   surfaces?: AgentSurfaces;
   recoveryMode?: RecoveryMode;
   permissions?: PermissionsSpec;
+  /** Working directory for the CLI subprocess; defaults to the flow-runner's cwd. */
+  cwd?: string;
+  /**
+   * Dispatch transport (flows#385). `'direct'` (default) spawns the CLI as
+   * a local subprocess. `'relay'` posts to agent-relay so the agent
+   * registers as a first-class workspace participant.
+   */
+  transport?: 'direct' | 'relay';
   /**
    * Structured-output authoring sugar. A successful CLI JSON object is the parsed
    * value; the kernel persists it only after `json_schema` verification.
@@ -201,6 +264,33 @@ export interface AgentStepSpec extends BaseStepSpec {
 
 export type StepSpec = DeterministicStepSpec | LlmStepSpec | AgentStepSpec;
 
+/** YAML argument maps use the same pinned client types as the TS helpers. */
+export interface YamlHelperParams {
+  slack: { [V in import('./slack-writeback.js').SlackCall['verb']]:
+    Extract<import('./slack-writeback.js').SlackCall, { verb: V }>['params'] };
+  github: {
+    comment: { target: Parameters<import('@relayfile/relay-helpers').GithubClient['comment']>[0]; body: string };
+    createIssue: Parameters<import('@relayfile/relay-helpers').GithubClient['createIssue']>[0];
+    createPullRequest: Parameters<import('@relayfile/relay-helpers').GithubClient['createPullRequest']>[0];
+    closePullRequest: Parameters<import('@relayfile/relay-helpers').GithubClient['closePullRequest']>[0];
+  };
+  linear: {
+    comment: { issueId: string; body: string };
+    createIssue: Parameters<import('@relayfile/relay-helpers').LinearClient['createIssue']>[0];
+    updateIssue: { issueId: string; args: Parameters<import('@relayfile/relay-helpers').LinearClient['updateIssue']>[1] };
+  };
+}
+
+type OneKey<T> = { [K in keyof T]: Pick<T, K> & Partial<Record<Exclude<keyof T, K>, never>> }[keyof T];
+
+/** Helper sugar is removed before validation of the three kernel step types. */
+export type YamlHelperStepSpec = Pick<BaseStepSpec, 'id' | 'dependsOn' | 'maxIterations'> & {
+  verification?: OutputVerificationSpec;
+  output?: JsonOutputSchema;
+} & OneKey<{ [P in keyof YamlHelperParams]: OneKey<YamlHelperParams[P]> }>;
+
+export type YamlFlowSpec = Omit<FlowSpec, 'steps'> & { steps: Array<StepSpec | YamlHelperStepSpec> };
+
 /**
  * Reusable authoring declaration for an agent CLI/model pair. Both fields are
  * required so selecting a named agent can never inherit a host model. The
@@ -268,7 +358,11 @@ export interface FlowSpec {
   /** Declarations checked by preflight; gate 1 never dispatches them. */
   triggers?: TriggerSpec[];
   steps: StepSpec[];
-  budget?: BudgetSpec;
+  budget?: BudgetSpec | import('./budget.js').HeaderBudget;
+  /** Path-scoped workspace grants — "mount/path: readonly|readwrite|append". Compiled by preflight. */
+  workspace?: string | readonly string[];
+  /** Path-scoped tool grants; `fs` mirrors workspace for shell/deterministic scope. */
+  tools?: { fs?: string | readonly string[] };
 }
 
 /** Current spec schema version emitted by this SDK. */
@@ -302,6 +396,7 @@ export interface KernelVerificationSpec {
 }
 
 export interface KernelStepCommon {
+  input?: Record<string, OutputBinding>;
   requirements?: KernelPlacementRequirements;
   memory?: KernelMemorySpec;
   id: string;
@@ -315,6 +410,7 @@ export interface KernelDeterministicStep extends KernelStepCommon {
   type: 'deterministic';
   command: string;
   timeout_ms?: number;
+  lease_ms?: number;
 }
 
 export interface KernelLlmStep extends KernelStepCommon {
@@ -344,11 +440,23 @@ export interface KernelAgentStep extends KernelStepCommon {
   recovery_mode: RecoveryMode;
   surfaces?: KernelAgentSurfaces;
   permissions?: KernelPermissionsSpec;
+  /** Working directory for the CLI subprocess; kernel passes through untouched. */
+  cwd?: string;
+  /**
+   * Dispatch transport (flows#385). Kernel passes through untouched;
+   * the SDK worker selects between direct-spawn and agent-relay routing.
+   */
+  transport?: 'direct' | 'relay';
 }
 
 export type KernelStepSpec = KernelDeterministicStep | KernelLlmStep | KernelAgentStep;
 
 export interface KernelBudgetSpec {
+  pricing?: 'frozen';
+  prior_spend?: { tokens_in: number; tokens_out: number; dollars: string; wallclock_ms: number; day?: number };
+  max_tokens?: number;
+  max_wallclock_ms?: number;
+  window?: 'day';
   max_tokens_in?: number;
   max_tokens_out?: number;
   max_dollars?: string;

package/src/step-dependencies.ts

@@ -1,3 +1,5 @@
+import { bindingDependencies } from './input-binding.js';
+
 /** Return author-facing dependency errors without assuming parsed step shapes. */
 const MAX_REPORTED_CYCLE_PATH_IDS = 16;
 
@@ -21,7 +23,7 @@ export function stepDependencyErrors(
     }
 
     const id = value['id'];
-    const dependencies = (rawDependencies ?? []) as string[];
+    const dependencies = [...(rawDependencies ?? []) as string[], ...bindingDependencies(value['input'])];
     for (const dependency of dependencies) {
       if (!knownIds.has(dependency)) {
         errors.push(`spec.steps: step "${id}" dependsOn unknown step "${dependency}"`);

package/src/step-fields.ts

@@ -10,6 +10,8 @@ export const FLOW_FIELDS = [
   'triggers',
   'steps',
   'budget',
+  'workspace',
+  'tools',
 ] as const;
 
 /** Closed named-agent declaration schema. */
@@ -20,6 +22,7 @@ export const STEP_COMMON_FIELDS = [
   'id',
   'type',
   'dependsOn',
+  'input',
   'verification',
   'maxIterations',
   'memory',
@@ -32,7 +35,7 @@ export const STEP_COMMON_FIELDS = [
  * per-verb boundary through a second, drifting allowlist.
  */
 export const STEP_FIELDS_BY_TYPE = {
-  deterministic: ['command', 'timeoutMs'],
+  deterministic: ['command', 'timeoutMs', 'lease_ms'],
   llm: ['prompt', 'model', 'cli', 'output'],
-  agent: ['instruction', 'agent', 'cli', 'model', 'surfaces', 'recoveryMode', 'permissions', 'output'],
+  agent: ['instruction', 'agent', 'cli', 'model', 'cwd', 'transport', 'surfaces', 'recoveryMode', 'permissions', 'output'],
 } as const satisfies Record<StepType, readonly string[]>;

package/src/trigger-executor.ts

@@ -0,0 +1,34 @@
+import { providerEventTypes, webhook, type TriggerSource, type WebhookFilter } from '@relayflows/surface';
+import type { TriggerSpec } from './spec.js';
+
+/** Lower a surface subscription to the existing inbox executor contract. */
+export function webhookTriggerSpec(id: string, source: TriggerSource): TriggerSpec {
+  if (source.kind !== 'webhook') throw new TypeError('unsupported trigger kind');
+  const trigger = webhook(source.name, source.filter);
+  return {
+    id,
+    executor: trigger.name,
+    eventType: trigger.name,
+    ...(trigger.filter === undefined ? {} : { pattern: trigger.filter }),
+    // The inbox watcher supplies the durable file ID as the event key.
+    dedupeKeyTemplate: '{{event.type}}',
+  };
+}
+
+/** Provider ingress uses the path as authority; it never trusts a body to reroute. */
+export function providerInboxEvent(provider: string, value: unknown): WebhookFilter {
+  if (!Object.hasOwn(providerEventTypes, provider)) throw new TypeError(`unknown provider: ${provider}`);
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError('provider event must be an object');
+  }
+  const event = value as Record<string, unknown>;
+  const types: readonly string[] = providerEventTypes[provider as keyof typeof providerEventTypes];
+  if (typeof event.type !== 'string' || !types.includes(event.type)) {
+    throw new TypeError(`unknown event type for ${provider}`);
+  }
+  if (event.provider !== undefined && event.provider !== provider) throw new TypeError('provider does not match inbox');
+  if (event.payload === null || typeof event.payload !== 'object' || Array.isArray(event.payload)) {
+    throw new TypeError('provider event payload must be an object');
+  }
+  return webhook(provider, { ...event, provider } as WebhookFilter).filter!;
+}

package/src/validate.ts

@@ -21,6 +21,8 @@ import { validateOutputDeclaration } from './output-schema.js';
 import { modelNameError } from './model-name.js';
 import { unknownKeyErrors } from './unknown-keys.js';
 import { stepDependencyErrors } from './step-dependencies.js';
+import { inputBindingErrors } from './input-binding.js';
+import { NAMED_GATE_KEYS, namedGateErrors } from './named-gates.js';
 import {
   AGENT_DECLARATION_FIELDS,
   FLOW_FIELDS,
@@ -68,8 +70,9 @@ function isCanonicalPathSurface(value: unknown): value is string {
 // unknown keys (AGENTS.md rule 4; RFC covenant 2): a typo'd key like
 // `depends_on` must be an error naming the nearest valid key, never a
 // silently discarded field — silently dropping `dependsOn` loses ordering.
-const BUDGET_KEYS = ['maxTokensIn', 'maxTokensOut', 'maxDollars'] as const;
+const BUDGET_KEYS = ['maxTokensIn', 'maxTokensOut', 'maxDollars', 'maxTokens', 'maxWallclockMs', 'window', 'pricing'] as const;
 const VERIFICATION_KEYS: Record<string, readonly string[]> = {
+  ...NAMED_GATE_KEYS,
   exit_code: ['type', 'expect'],
   output_contains: ['type', 'value'],
   json_schema: ['type', 'schema'],
@@ -163,6 +166,22 @@ class Validator {
 
     if (s['budget'] !== undefined) this.validateBudget(s['budget']);
 
+    if (s['workspace'] !== undefined) this.validateScopeGrants(s['workspace'], 'spec.workspace');
+
+    if (s['tools'] !== undefined) {
+      if (!isObject(s['tools'])) {
+        this.fail('spec.tools: expected an object');
+      } else {
+        const tools = s['tools'] as Record<string, unknown>;
+        for (const key of Object.keys(tools)) {
+          if (key !== 'fs' && key !== 'mcp') {
+            this.fail(`spec.tools: unknown key "${key}" (expected fs or mcp)`);
+          }
+        }
+        if (tools['fs'] !== undefined) this.validateScopeGrants(tools['fs'], 'spec.tools.fs');
+      }
+    }
+
     if (!Array.isArray(s['steps']) || s['steps'].length === 0) {
       this.fail('spec.steps: expected a non-empty array');
       return this.result();
@@ -175,6 +194,7 @@ class Validator {
 
     // Dependents must reference real step ids and form a DAG (no cycles).
     for (const error of stepDependencyErrors(steps, this.ids)) this.fail(error);
+    for (const error of inputBindingErrors(steps)) this.fail(error);
     return this.result();
   }
 
@@ -203,13 +223,28 @@ class Validator {
     }
   }
 
+  private validateScopeGrants(value: unknown, at: string): void {
+    const grants = Array.isArray(value) ? value : [value];
+    for (const grant of grants) {
+      if (typeof grant !== 'string' || grant.length === 0) {
+        this.fail(`${at}: expected a scope-grant string like "mount/path: readonly" (or an array of them)`);
+        return;
+      }
+    }
+  }
+
   private validateBudget(b: unknown, at = 'spec.budget'): void {
     if (!isObject(b)) {
       this.fail(`${at}: expected an object`);
       return;
     }
-    this.checkKeys(b, BUDGET_KEYS, at);
+    this.checkKeys(b, at === 'spec.budget' ? BUDGET_KEYS : ['maxTokensIn', 'maxTokensOut', 'maxDollars'], at);
     const budget = b as BudgetSpec;
+    for (const key of ['maxTokens', 'maxWallclockMs'] as const) {
+      if (budget[key] !== undefined && (!Number.isSafeInteger(budget[key]) || budget[key]! < 0)) this.fail(`${at}.${key}: expected a safe non-negative integer`);
+    }
+    if (budget.pricing !== undefined && budget.pricing !== 'frozen') this.fail(`${at}.pricing: expected frozen`);
+    if (budget.window !== undefined && budget.window !== 'day') this.fail(`${at}.window: expected day`);
     if (
       budget.maxTokensIn !== undefined &&
       !isNonNegInt(budget.maxTokensIn)
@@ -356,7 +391,7 @@ class Validator {
     }
 
     if (st['verification'] !== undefined) {
-      this.validateVerification(st['verification'], `${at}.verification`, type);
+      this.validateVerification(st['verification'], `${at}.verification`, type, st['input']);
     }
 
     if (st['maxIterations'] !== undefined && !isPosInt(st['maxIterations'])) {
@@ -374,13 +409,14 @@ class Validator {
     }
   }
 
-  private validateVerification(v: unknown, at: string, stepType: StepType): void {
+  private validateVerification(v: unknown, at: string, stepType: StepType, input: unknown): void {
     if (!isObject(v)) {
       this.fail(`${at}: expected an object`);
       return;
     }
     const gate = v as unknown as VerificationSpec & { expect?: unknown };
-    const gateKeys = typeof gate.type === 'string' ? VERIFICATION_KEYS[gate.type] : undefined;
+    const gateKeys = typeof gate.type === 'string' && Object.hasOwn(VERIFICATION_KEYS, gate.type)
+      ? VERIFICATION_KEYS[gate.type] : undefined;
     if (gateKeys !== undefined) {
       this.checkKeys(v, gateKeys, at);
     }
@@ -407,8 +443,10 @@ class Validator {
       } catch (error) {
         this.fail(error instanceof Error ? error.message : `${at}.schema: expected JSON-compatible data`);
       }
+    } else if (Object.hasOwn(NAMED_GATE_KEYS, gate.type)) {
+      for (const error of namedGateErrors(v, input, at)) this.fail(error);
     } else {
-      this.fail(`${at}.type: expected exit_code | output_contains | json_schema`);
+      this.fail(`${at}.type: unknown_gate_kind: expected exit_code | output_contains | json_schema | references_input | subprocess_gate | word_count_bounds | regex_match`);
     }
   }
 
@@ -416,6 +454,9 @@ class Validator {
     if (!isNonEmptyString(st.command)) {
       this.fail(`${at}.command: expected a non-empty string`);
     }
+    if (st.lease_ms !== undefined && !isPosInt(st.lease_ms)) {
+      this.fail(`${at}.lease_ms: expected a positive integer`);
+    }
     if (st.timeoutMs !== undefined && !isPosInt(st.timeoutMs)) {
       this.fail(`${at}.timeoutMs: expected a positive integer`);
     }

package/src/webhook-rate-limit.ts

@@ -0,0 +1,69 @@
+/**
+ * In-process token-bucket rate limiter for the local webhook receiver (#304).
+ *
+ * Slice E's receiver binds loopback and is documented as development-only, so
+ * a single-process in-memory bucket is sufficient. Cluster deployments must
+ * layer a shared store in a follow-up slice; the taxonomy stays the same
+ * (`webhook_rate_limited`) so client behavior does not change.
+ */
+export interface RateLimitConfig {
+  /** Tokens replenished per second. */
+  readonly ratePerSecond: number;
+  /** Maximum burst capacity. */
+  readonly burst: number;
+}
+
+export interface RateLimitDecision {
+  readonly allowed: boolean;
+  readonly retryAfterMs: number;
+}
+
+interface Bucket {
+  tokens: number;
+  refilledAtMs: number;
+}
+
+export class TokenBucketLimiter {
+  private readonly buckets = new Map<string, Bucket>();
+
+  constructor(
+    private readonly config: RateLimitConfig,
+    private readonly clock: () => number = Date.now,
+  ) {
+    if (config.burst <= 0 || config.ratePerSecond < 0) {
+      throw new Error('rate limiter: burst > 0 and ratePerSecond >= 0 required');
+    }
+  }
+
+  consume(key: string, cost = 1): RateLimitDecision {
+    const now = this.clock();
+    const bucket = this.buckets.get(key) ?? { tokens: this.config.burst, refilledAtMs: now };
+    const elapsedSeconds = Math.max(0, (now - bucket.refilledAtMs) / 1000);
+    bucket.tokens = Math.min(this.config.burst, bucket.tokens + elapsedSeconds * this.config.ratePerSecond);
+    bucket.refilledAtMs = now;
+    if (bucket.tokens >= cost) {
+      bucket.tokens -= cost;
+      this.buckets.set(key, bucket);
+      return { allowed: true, retryAfterMs: 0 };
+    }
+    this.buckets.set(key, bucket);
+    const missingTokens = cost - bucket.tokens;
+    const retryAfterMs = this.config.ratePerSecond > 0
+      ? Math.ceil((missingTokens / this.config.ratePerSecond) * 1000)
+      : Number.POSITIVE_INFINITY;
+    return { allowed: false, retryAfterMs };
+  }
+
+  /** Test/inspection helper — production code should only call {@link consume}. */
+  size(): number {
+    return this.buckets.size;
+  }
+}
+
+export function keyFor(
+  provider: string | undefined,
+  name: string,
+  sourceAddress: string,
+): string {
+  return `${provider ?? 'raw'}:${name}:${sourceAddress}`;
+}

package/src/webhook-signature.ts

@@ -0,0 +1,74 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+/**
+ * Per-provider HMAC signature schemes for webhook payload authentication (#304).
+ *
+ * The receiver only invokes verification when a secret is configured for the
+ * provider (via `env[WEBHOOK_SECRET_<PROVIDER>]`). When no secret is set the
+ * receiver runs unsigned, matching the initial loopback-only development mode
+ * documented in #301. Callers deploying to public ingress MUST set the secret.
+ */
+export type SignatureScheme = {
+  header: string;
+  compute(rawBody: Buffer, secret: string): string;
+};
+
+const HEX = /^[0-9a-f]+$/i;
+
+const github: SignatureScheme = {
+  header: 'x-hub-signature-256',
+  compute(rawBody, secret) {
+    return 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
+  },
+};
+
+const slack: SignatureScheme = {
+  header: 'x-slack-signature',
+  compute(rawBody, secret) {
+    // Slack's v0 scheme is HMAC(SHA256, secret) over `v0:{ts}:{body}`; a
+    // deployment that wants Slack signature verification must set the secret
+    // to include the timestamp prefix or use provider-specific integration.
+    return 'v0=' + createHmac('sha256', secret).update(rawBody).digest('hex');
+  },
+};
+
+const generic: SignatureScheme = {
+  header: 'x-flows-signature-256',
+  compute(rawBody, secret) {
+    return 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
+  },
+};
+
+export const SIGNATURE_SCHEMES: Record<string, SignatureScheme> = {
+  github,
+  slack,
+};
+
+export function schemeFor(provider: string | undefined): SignatureScheme {
+  if (provider && Object.hasOwn(SIGNATURE_SCHEMES, provider)) {
+    return SIGNATURE_SCHEMES[provider]!;
+  }
+  return generic;
+}
+
+/** Constant-time verification of a hex-encoded signature against the expected. */
+export function verifySignature(
+  provider: string | undefined,
+  rawBody: Buffer,
+  headerValue: string | undefined,
+  secret: string,
+): { ok: true } | { ok: false; reason: 'missing' | 'malformed' | 'mismatch' } {
+  const scheme = schemeFor(provider);
+  const supplied = headerValue?.trim();
+  if (!supplied) return { ok: false, reason: 'missing' };
+  const expected = scheme.compute(rawBody, secret);
+  if (supplied.length !== expected.length) return { ok: false, reason: 'malformed' };
+  const [suppliedHex, expectedHex] = [supplied.replace(/^[^=]+=/, ''), expected.replace(/^[^=]+=/, '')];
+  if (!HEX.test(suppliedHex) || suppliedHex.length !== expectedHex.length) {
+    return { ok: false, reason: 'malformed' };
+  }
+  const suppliedBytes = Buffer.from(suppliedHex, 'hex');
+  const expectedBytes = Buffer.from(expectedHex, 'hex');
+  if (suppliedBytes.length !== expectedBytes.length) return { ok: false, reason: 'malformed' };
+  return timingSafeEqual(suppliedBytes, expectedBytes) ? { ok: true } : { ok: false, reason: 'mismatch' };
+}