@cursor/july 0.1.107 → 0.1.109

package/src/channels/gitlab/api.ts

@@ -92,6 +92,35 @@ export interface GitLabClient {
   request<T = unknown>(input: GitLabRequestInput): Promise<T>;
 }
 
+export interface GitLabApiMergeRequest {
+  iid: number;
+  title?: string;
+  description?: string;
+  state?: string;
+  draft?: boolean;
+  webUrl?: string;
+  headSha?: string;
+  sourceBranch?: string;
+  targetBranch?: string;
+  authorUsername?: string;
+  baseSha?: string;
+  changedFilesCount?: number;
+}
+
+export interface GitLabApiMergeRequestDiff {
+  oldPath: string;
+  newPath: string;
+  patch?: string;
+  status: "added" | "modified" | "removed" | "renamed";
+}
+
+/** Project-bound merge-request reads shared by GitLab agents. */
+export interface GitLabApi {
+  getMergeRequest(iid: number): Promise<GitLabApiMergeRequest>;
+  getMergeBaseSha(base: string, headSha: string): Promise<string | undefined>;
+  listMergeRequestDiffs(iid: number): Promise<GitLabApiMergeRequestDiff[]>;
+}
+
 function envValue(value: string | undefined): string | undefined {
   const trimmed = value?.trim();
   return trimmed === undefined || trimmed === "" ? undefined : trimmed;
@@ -136,6 +165,100 @@ export function gitlabProjectPathSegment(project: number | string): string {
     : encodeURIComponent(project.replace(/^\/+|\/+$/g, ""));
 }
 
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+const GITLAB_DIFFS_PER_PAGE = 100;
+
+export function createGitLabApi(
+  client: Pick<GitLabClient, "request">,
+  project: number | string
+): GitLabApi {
+  const projectPath = `/projects/${gitlabProjectPathSegment(project)}`;
+  return {
+    async getMergeRequest(iid) {
+      const raw = await client.request<Record<string, unknown>>({
+        method: "GET",
+        path: `${projectPath}/merge_requests/${iid}`,
+      });
+      const diffRefs = asRecord(raw.diff_refs);
+      const changesCount = nonEmptyString(raw.changes_count);
+      return {
+        iid: (raw.iid as number | null | undefined) ?? iid,
+        title: raw.title as string | undefined,
+        description:
+          raw.description === null
+            ? undefined
+            : (raw.description as string | undefined),
+        state: raw.state as string | undefined,
+        draft:
+          typeof raw.draft === "boolean"
+            ? raw.draft
+            : typeof raw.work_in_progress === "boolean"
+              ? raw.work_in_progress
+              : undefined,
+        webUrl: raw.web_url as string | undefined,
+        headSha:
+          (raw.sha as string | null | undefined) ??
+          (diffRefs?.head_sha as string | undefined),
+        sourceBranch: raw.source_branch as string | undefined,
+        targetBranch: raw.target_branch as string | undefined,
+        authorUsername: asRecord(raw.author)?.username as string | undefined,
+        baseSha: nonEmptyString(diffRefs?.base_sha),
+        changedFilesCount:
+          changesCount !== undefined && /^\d+$/.test(changesCount)
+            ? Number(changesCount)
+            : undefined,
+      };
+    },
+    async getMergeBaseSha(base, headSha) {
+      const data = await client.request<{ id?: string }>({
+        method: "GET",
+        path: `${projectPath}/repository/merge_base?refs[]=${encodeURIComponent(base)}&refs[]=${encodeURIComponent(headSha)}`,
+      });
+      return nonEmptyString(data.id);
+    },
+    async listMergeRequestDiffs(iid) {
+      const files: GitLabApiMergeRequestDiff[] = [];
+      for (let page = 1; ; page += 1) {
+        const diffs = await client.request<Record<string, unknown>[]>({
+          method: "GET",
+          path: `${projectPath}/merge_requests/${iid}/diffs`,
+          query: { page, per_page: GITLAB_DIFFS_PER_PAGE },
+        });
+        for (const diff of diffs) {
+          const status =
+            diff.new_file === true
+              ? "added"
+              : diff.deleted_file === true
+                ? "removed"
+                : diff.renamed_file === true
+                  ? "renamed"
+                  : "modified";
+          const rawPatch =
+            typeof diff.diff === "string" ? diff.diff : undefined;
+          files.push({
+            oldPath: diff.old_path as string,
+            newPath: diff.new_path as string,
+            status,
+            patch: rawPatch?.replace(/\n$/, ""),
+          });
+        }
+        if (diffs.length < GITLAB_DIFFS_PER_PAGE) {
+          return files;
+        }
+      }
+    },
+  };
+}
+
 function buildQuery(query: GitLabRequestInput["query"]): string {
   if (query === undefined) {
     return "";

package/src/channels/gitlab/binding.ts

@@ -176,6 +176,18 @@ export function gitlabMergeRequestUrl(
   return explicit ?? `${project.webUrl}/-/merge_requests/${iid}`;
 }
 
+/**
+ * Whether an `update` payload marks a draft merge request ready. GitLab uses
+ * either `changes.draft` or the legacy `changes.work_in_progress` shape.
+ */
+export function gitlabDraftMarkedReady(
+  payload: Record<string, unknown>
+): boolean {
+  const changes = asRecord(payload.changes);
+  const draft = asRecord(changes?.draft ?? changes?.work_in_progress);
+  return draft?.current === false && draft.previous !== false;
+}
+
 /** Normalize a merge-request record (`object_attributes` or `merge_request`). */
 export function gitlabMergeRequestFromRecord(
   project: GitLabProjectRef,

package/src/channels/gitlab/index.ts

@@ -22,6 +22,7 @@ export * from "./api.js";
 export {
   buildGitLabBinding,
   type GitLabHandle,
+  gitlabDraftMarkedReady,
   gitlabMergeRequestFromRecord,
   gitlabMergeRequestUrl,
   gitlabProjectFromPayload,

package/src/channels/origin/origin-channel.ts

@@ -99,13 +99,20 @@ function asBoolean(value: unknown): boolean | undefined {
 function originActor(value: unknown): OriginActor | undefined {
   const record = asRecord(value);
   if (record === undefined) return undefined;
-  const nestedUser = asRecord(record.user);
-  const nestedApp = asRecord(record.app);
-  const id =
-    asNonEmptyString(nestedUser?.id) ??
-    asNonEmptyString(nestedApp?.id) ??
-    asNonEmptyString(asRecord(record.serviceAccount)?.id) ??
-    asNonEmptyString(record.id);
+
+  const nestedActors = [
+    ["user", asRecord(record.user)],
+    ["app", asRecord(record.app)],
+    ["service_account", asRecord(record.serviceAccount)],
+  ] as const;
+  for (const [kind, actor] of nestedActors) {
+    const id = asNonEmptyString(actor?.id);
+    if (id !== undefined) {
+      return { id, kind };
+    }
+  }
+
+  const id = asNonEmptyString(record.id);
   if (id === undefined) return undefined;
   const kind = asNonEmptyString(record.kind);
   return kind === undefined ? { id } : { id, kind };
@@ -361,16 +368,20 @@ export function defaultOriginAuth(
   ctx: Omit<OriginEventContext, "host" | "artifacts" | "origin">
 ): AuthContext {
   const senderId = ctx.sender?.id;
+  const senderKind = ctx.sender?.kind;
   return {
     authenticator: "origin-webhook",
     principalId: senderId ?? "origin",
-    principalType: ctx.sender?.kind === "app" ? "service" : "user",
+    principalType:
+      senderKind === "app" || senderKind === "service_account"
+        ? "service"
+        : "user",
     attributes: {
       conversation_kind: "pull_request",
       repository: ctx.repository.fullName,
       ...(ctx.deliveryId === undefined ? {} : { delivery_id: ctx.deliveryId }),
       ...(senderId === undefined ? {} : { subject: senderId }),
-      ...(ctx.sender?.kind === undefined ? {} : { user_type: ctx.sender.kind }),
+      ...(senderKind === undefined ? {} : { user_type: senderKind }),
       issuer: `origin:${ctx.repository.owner}`,
     },
   };
@@ -461,17 +472,19 @@ async function startTurn(input: {
   state: OriginChannelState;
 }): Promise<Response> {
   const source = continuationSource(input.options.continuation, "origin");
+  const cloud = input.dispatch.cloud ?? input.cloud;
+  const state = { ...input.dispatch.state, ...input.state };
   const session = await input.args.send(input.message, {
     auth: input.dispatch.auth,
     ...(source === "engine"
       ? { continuationToken: originContinuationKey(input.ctx) }
       : {}),
     title: input.dispatch.title ?? defaultOriginTitle(input.ctx),
-    ...(input.cloud === undefined ? {} : { cloud: input.cloud }),
-    state: input.state as unknown as JsonValue,
+    cloud,
+    state: state as unknown as JsonValue,
     // Resume must refresh the triggering comment / delivery identifiers so
     // reply delivery targets the latest wake, not the session's first.
-    refreshState: input.state as unknown as JsonValue,
+    refreshState: state as unknown as JsonValue,
   });
   return turnStarted(session);
 }
@@ -605,7 +618,10 @@ export async function dispatchOriginWebhook(input: {
       ctx,
       dispatch,
       extra: { event: eventType },
-      message: `Origin comment on ${ctx.repository.fullName}#${ctx.pullRequestNumber}`,
+      message:
+        commentBody.trim() === ""
+          ? `Origin comment on ${ctx.repository.fullName}#${ctx.pullRequestNumber}`
+          : commentBody.trim(),
       triggeringCommentId: commentId,
     });
   }

package/src/channels/origin/types.ts

@@ -7,6 +7,7 @@ import type {
   ChannelEventHandlers,
   ChannelStartArgs,
   HostContext,
+  JsonObject,
   SendMessageFn,
 } from "../../types.js";
 import type { OriginTokenProvider } from "./api.js";
@@ -95,6 +96,10 @@ export type OriginTurnDispatch = {
   message?: string;
   title?: string;
   context?: readonly string[];
+  /** Per-turn cloud options. Overrides the channel-level `cloud` resolver. */
+  cloud?: AgentCloudOptions;
+  /** Extra durable channel state. Provider-owned fields take precedence. */
+  state?: JsonObject;
 };
 
 /** Bound per-delivery helpers passed to an {@link OriginTaskDispatch.task}. */

package/src/channels/slack/dispatch.ts

@@ -8,6 +8,7 @@ import {
   type MailboxContinuation,
   normalizeIdentity,
 } from "../../internal/continuation-identity.js";
+import { isDeferredChannelSession } from "../../internal/deferred-channel-session.js";
 import { routeLocalIngressContinuation } from "../../internal/local-ingress.js";
 import { steeringEnabled } from "../../internal/steering.js";
 import type {
@@ -189,6 +190,14 @@ export interface SlackInboundDispatchDeps extends SlackContinuationProbes {
    */
   suggestedPrompts?: SlackSuggestedPrompt[];
   suggestedPromptsTitle?: string;
+  /**
+   * Rethrow handler failures out of the dispatch promise instead of
+   * swallowing them after the error log. Hosted admission sets this so a
+   * throwing handler rejects `waitUntil` and surfaces as a retryable 503
+   * to the control plane (matching the GitHub/Origin adapters); the
+   * long-lived Socket Mode loop keeps the swallow-and-log default.
+   */
+  propagateHandlerErrors?: boolean;
 }
 
 function triggeringMergeMessage(
@@ -267,6 +276,8 @@ export async function dispatchInboundMessage(args: {
   followUpStatus?: boolean;
   blockExternals?: boolean;
   continuation?: ContinuationIdentity;
+  /** See {@link SlackInboundDispatchDeps.propagateHandlerErrors}. */
+  propagateHandlerErrors?: boolean;
 }): Promise<void> {
   const { message, kind } = args;
   const log = args.log ?? defaultSlackLog;
@@ -399,6 +410,9 @@ export async function dispatchInboundMessage(args: {
       thread_ts: message.threadTs,
       event_id: args.eventId,
     });
+    if (args.propagateHandlerErrors === true) {
+      throw error;
+    }
     return;
   }
   if (decision === null || decision === undefined) {
@@ -527,6 +541,19 @@ export async function dispatchInboundMessage(args: {
 
   try {
     const session = await args.send(prompt, sendOptions);
+    if (isDeferredChannelSession(session)) {
+      // Hosted admission captured the send; the control plane allocates
+      // the session and runs the turn only after this delivery is
+      // acknowledged, so there is nothing to observe or coalesce yet.
+      log.info("session send captured (hosted admission)", {
+        kind,
+        continuation,
+        channel: message.channelId,
+        thread_ts: message.threadTs,
+        event_id: args.eventId,
+      });
+      return;
+    }
     log.info(
       session.coalesced === true ? "session coalesced" : "session start",
       {
@@ -659,6 +686,7 @@ export function dispatchInboundFromEventBody(
         kind: "app_mention",
         message: mention,
         handler: deps.onAppMention,
+        propagateHandlerErrors: deps.propagateHandlerErrors,
         send: deps.send,
         credentials: deps.credentials,
         host: deps.host,
@@ -702,6 +730,7 @@ export function dispatchInboundFromEventBody(
         kind: "direct_message",
         message: dm,
         handler: deps.onDirectMessage,
+        propagateHandlerErrors: deps.propagateHandlerErrors,
         send: deps.send,
         credentials: deps.credentials,
         host: deps.host,
@@ -739,6 +768,7 @@ export function dispatchInboundFromEventBody(
         kind: "reaction_added",
         message: reaction,
         handler: deps.onReactionAdded,
+        propagateHandlerErrors: deps.propagateHandlerErrors,
         send: deps.send,
         credentials: deps.credentials,
         host: deps.host,

package/src/channels/slack/slack-channel.ts

@@ -1,17 +1,29 @@
 /**
- * `slackChannel()` — platform channel pack for Slack (Socket Mode).
+ * `slackChannel()` — platform channel pack for Slack.
  *
- * Inbound events arrive over a WebSocket (`SLACK_APP_TOKEN`); no public
- * Request URL or Events HTTP route is required. When `toolApprovals`
- * is enabled, Approve/Deny buttons arrive as Socket Mode `interactive`
- * envelopes.
+ * Local / self-hosted transport is Socket Mode: inbound events arrive over
+ * a WebSocket (`SLACK_APP_TOKEN`); no public Request URL or Events HTTP
+ * route is required. When `toolApprovals` is enabled, Approve/Deny buttons
+ * arrive as Socket Mode `interactive` envelopes.
+ *
+ * Hosted v2 transport is the control plane's Events API ingest: the CP
+ * verifies the managed app's signature, fans out on the declared
+ * `slackEventTypes` (`app_mention`, `message`), and delivers the full
+ * `event_callback` body through hosted admission — the attached adapter
+ * routes it through the same inbound dispatch as Socket Mode. Without an
+ * app token the socket transport idles, so a hosted pod never needs one.
  */
 
 import { allowAll, defineChannel } from "../../channels.js";
+import {
+  skipped,
+  withPropagatingBackgroundErrors,
+} from "../../internal/channel-dispatch.js";
 import {
   continuationSource,
   normalizeIdentity,
 } from "../../internal/continuation-identity.js";
+import { attachHostedAdmissionAdapter } from "../../internal/hosted-admission-adapter.js";
 import type {
   ArtifactsApi,
   ChannelDefinition,
@@ -51,7 +63,7 @@ import {
   emptySlackChannelState,
   type SlackInboundDispatchDeps,
 } from "./dispatch.js";
-import { createEventIdDedupe } from "./event-id-dedupe.js";
+import { createEventIdDedupe, type EventIdDedupe } from "./event-id-dedupe.js";
 import {
   dispatchBlockAction,
   dispatchInteractiveFromPayload,
@@ -159,6 +171,18 @@ export function slackChannel(
     normalizeBotMentionAllowlist(botMentions.allowFrom);
   }
   const eventIds = createEventIdDedupe();
+  // Hosted v2 event capability, matching what the engagement flags can
+  // dispatch: mentions ride `app_mention`; DMs and watched channel posts
+  // both arrive as `message`. Membership of `slack.thread/v2` admits
+  // exactly these two, so `reaction_added` (hosted follow-up only inside
+  // an existing thread) is deliberately not declared.
+  const slackEventTypes: string[] = [];
+  if (mentionsEnabled) {
+    slackEventTypes.push("app_mention");
+  }
+  if (directMessagesEnabled || channelPosts !== undefined) {
+    slackEventTypes.push("message");
+  }
   const toolApprovals = options.toolApprovals === true;
   const interactivity = options.interactivity === true;
   const onBlockAction = options.onBlockAction;
@@ -201,6 +225,9 @@ export function slackChannel(
     waitUntil: (promise: Promise<unknown>) => void;
     host: HostContext;
     artifacts: ArtifactsApi;
+    /** Override the channel-level dedupe (hosted admission passes a fresh one). */
+    eventIds?: EventIdDedupe;
+    propagateHandlerErrors?: boolean;
     hasContinuationSession?: (continuationToken: string) => Promise<boolean>;
     isContinuationBusy?: (continuationToken: string) => Promise<boolean>;
     getContinuationLastBotMessageTs?: (
@@ -216,7 +243,8 @@ export function slackChannel(
       onDirectMessage,
       ...(onReactionAdded === undefined ? {} : { onReactionAdded }),
       credentials,
-      eventIds,
+      eventIds: args.eventIds ?? eventIds,
+      propagateHandlerErrors: args.propagateHandlerErrors,
       host: args.host,
       artifacts: args.artifacts,
       log: getLog(),
@@ -253,6 +281,10 @@ export function slackChannel(
     routes: [],
     meta: {
       kind: "slack",
+      // Omitted (not empty) when nothing dispatches, so fanout never
+      // materializes a subscription with no event types.
+      slackEventTypes:
+        slackEventTypes.length === 0 ? undefined : slackEventTypes,
       ...(channelPosts === undefined
         ? {}
         : { slackChannelPosts: [...channelPosts.allow] }),
@@ -551,6 +583,36 @@ export function slackChannel(
   });
 
   slackChannelOptionsByDefinition.set(definition, options);
+  attachHostedAdmissionAdapter(definition, {
+    kind: "slack",
+    prepareArgs: withPropagatingBackgroundErrors,
+    // The payload is the full `event_callback` body the CP verified — the
+    // same shape Socket Mode unwraps — so it routes through the same
+    // inbound dispatch. Outcomes: a captured `send` overrides the fallback
+    // tag below, so `skipped` surfaces when the engagement rules declined
+    // (`not_engaged`) or no handler takes the shape (`not_dispatchable`);
+    // a throwing handler rejects `waitUntil` (propagateHandlerErrors) and
+    // hosted admission answers a retryable 503, like the PR adapters.
+    // The channel-level event_id dedupe is deliberately bypassed with a
+    // fresh instance per delivery: the control plane's app-scoped ingress
+    // claim already dedupes Slack retries, and on a warm pod the local set
+    // would otherwise swallow the control plane's own retry of a delivery
+    // that failed after the id was marked handled.
+    dispatch: async ({ payload, args }) => {
+      const dispatched = dispatchInboundFromEventBody(
+        payload,
+        inboundDeps({
+          send: args.send,
+          waitUntil: args.waitUntil,
+          host: args.host,
+          artifacts: args.artifacts,
+          eventIds: createEventIdDedupe(),
+          propagateHandlerErrors: true,
+        })
+      );
+      return skipped(dispatched ? "not_engaged" : "not_dispatchable");
+    },
+  });
 
   return definition;
 }

package/src/channels.ts

@@ -64,9 +64,11 @@ export {
 } from "./channels/checks.js";
 
 import { Buffer } from "node:buffer";
-import { timingSafeEqual } from "node:crypto";
+import { createHmac, timingSafeEqual } from "node:crypto";
 import { brandDefinition } from "./internal/brand.js";
 import { normalizeIdentity } from "./internal/continuation-identity.js";
+import { attachCatchAdmission } from "./internal/hosted-catch.js";
+import { attachHttpControlPlaneAdmission } from "./internal/http-control-plane-session.js";
 import { isLoopbackAddress, isLoopbackHostname } from "./internal/net.js";
 import type {
   AuthContext,
@@ -117,7 +119,16 @@ export type {
 export function defineChannel<TState = JsonValue>(
   config: ChannelConfig<TState>
 ): ChannelDefinition<TState> {
-  return brandDefinition("channel", config);
+  const definition = brandDefinition("channel", config);
+  if (config.routes !== undefined && config.routes.length > 0) {
+    // Hosted: the control plane catches declared routes and replays them
+    // here. Provider packs attach their own admission afterwards.
+    attachCatchAdmission(
+      definition as ChannelDefinition<unknown>,
+      config.routes
+    );
+  }
+  return definition;
 }
 
 /**
@@ -127,13 +138,15 @@ export function defineChannel<TState = JsonValue>(
 export function httpChannel(
   config: HttpChannelConfig = {}
 ): HttpChannelDefinition {
-  if (config.continuation !== undefined) {
-    return brandDefinition("http-channel", {
-      ...config,
-      continuation: normalizeIdentity(config.continuation, "http"),
-    });
-  }
-  return brandDefinition("http-channel", config);
+  const definition =
+    config.continuation !== undefined
+      ? brandDefinition("http-channel", {
+          ...config,
+          continuation: normalizeIdentity(config.continuation, "http"),
+        })
+      : brandDefinition("http-channel", config);
+  attachHttpControlPlaneAdmission(definition);
+  return definition;
 }
 
 // ============================================================================
@@ -432,7 +445,13 @@ export function publicEndpoint(): AuthPolicy {
     principalId: "anonymous",
     principalType: "user",
   });
-  return Object.assign(policy, { [PUBLIC_ENDPOINT_MARKER]: true as const });
+  // On the v2 control plane this also makes the channel's routes catchable
+  // with handler-side verification (the v1 alias posture): the CP admits
+  // every request on a declared route and the handler rejects bad ones.
+  return markCatchAuth(
+    Object.assign(policy, { [PUBLIC_ENDPOINT_MARKER]: true as const }),
+    { kind: "public" }
+  );
 }
 
 /** True when a policy was created by {@link publicEndpoint}. */
@@ -443,3 +462,131 @@ export function isPublicEndpointPolicy(policy: AuthPolicy): boolean {
     ] === true
   );
 }
+
+const CATCH_AUTH_MARKER = Symbol.for("agent-serve.catch-auth");
+
+/**
+ * What `deploy` extracts from a {@link sharedSecretAuth} /
+ * {@link hmacSignatureAuth} policy into the manifest: the control plane runs
+ * the same check with the deployment secret of the same name before any
+ * compute starts. `secret` is a name, never a value.
+ */
+export type CatchAuthDeclaration =
+  | { kind: "header"; header: string; secret: string }
+  | { kind: "hmac-sha256"; header: string; secret: string; prefix?: string }
+  /** `publicEndpoint()`: the handler verifies; the control plane only rate limits. */
+  | { kind: "public" };
+
+function markCatchAuth(
+  policy: AuthPolicy,
+  declaration: CatchAuthDeclaration
+): AuthPolicy {
+  return Object.assign(policy, { [CATCH_AUTH_MARKER]: declaration });
+}
+
+/** The catch declaration a policy carries, if it is a catch-capable policy. */
+export function catchAuthDeclaration(
+  policy: AuthPolicy
+): CatchAuthDeclaration | undefined {
+  const declaration = (policy as { [CATCH_AUTH_MARKER]?: unknown })[
+    CATCH_AUTH_MARKER
+  ];
+  return typeof declaration === "object" && declaration !== null
+    ? (declaration as CatchAuthDeclaration)
+    : undefined;
+}
+
+function presentedHeaderSecret(headerName: string, value: string): string {
+  if (
+    headerName === "authorization" &&
+    value.toLowerCase().startsWith("bearer ")
+  ) {
+    return value.slice("bearer ".length).trim();
+  }
+  return value.trim();
+}
+
+/**
+ * Admit requests whose `header` equals the secret named `secret` (an
+ * `Authorization: Bearer <secret>` header also matches). Locally the value
+ * is `process.env[secret]`; hosted, the deployment secret of that name. On
+ * Cursor hosting this ALSO declares the channel's routes reachable through
+ * the control-plane catch API, which runs the same comparison before any
+ * compute exists. An unset secret admits nothing.
+ */
+export function sharedSecretAuth(options: {
+  header: string;
+  secret: string;
+}): AuthPolicy {
+  const header = options.header.toLowerCase();
+  const policy: AuthPolicy = (request) => {
+    const expected = process.env[options.secret];
+    const presented = request.headers.get(header);
+    if (
+      expected === undefined ||
+      expected.length === 0 ||
+      presented === null ||
+      !constantTimeEquals(presentedHeaderSecret(header, presented), expected)
+    ) {
+      return null;
+    }
+    return {
+      authenticator: "shared-secret",
+      principalId: "webhook",
+      principalType: "service",
+    };
+  };
+  return markCatchAuth(policy, {
+    kind: "header",
+    header,
+    secret: options.secret,
+  });
+}
+
+/**
+ * Admit requests whose `header` carries the hex HMAC-SHA256 of the raw body
+ * under the secret named `secret` (optionally behind a literal `prefix`
+ * such as `sha256=`). Same local / hosted / catch semantics as
+ * {@link sharedSecretAuth}.
+ */
+export function hmacSignatureAuth(options: {
+  header: string;
+  secret: string;
+  prefix?: string;
+}): AuthPolicy {
+  const header = options.header.toLowerCase();
+  const prefix = options.prefix ?? "";
+  const policy: AuthPolicy = async (request) => {
+    const secret = process.env[options.secret];
+    const presented = request.headers.get(header)?.trim();
+    if (
+      secret === undefined ||
+      secret.length === 0 ||
+      presented === undefined ||
+      !presented.startsWith(prefix)
+    ) {
+      return null;
+    }
+    const body = Buffer.from(await request.clone().arrayBuffer());
+    const expected = createHmac("sha256", secret).update(body).digest("hex");
+    if (
+      !constantTimeEquals(
+        presented.slice(prefix.length).toLowerCase(),
+        expected
+      )
+    ) {
+      return null;
+    }
+    return {
+      authenticator: "hmac-signature",
+      principalId: "webhook",
+      principalType: "service",
+    };
+  };
+  return markCatchAuth(policy, {
+    kind: "hmac-sha256",
+    header,
+    secret: options.secret,
+    prefix: options.prefix,
+  });
+}