@datalayer/agent-runtimes 1.5.44 → 1.5.46

package/lib/portable/hosts/client.js

@@ -0,0 +1,174 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The ai-agents host client every chat host calls (moved from the Slack
+ * service, plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/client
+ */
+import { z } from 'zod';
+import { bindSchema, decisionSchema, deliveryOfOutbox, HOST_KEY_HEADER, linkCodeSchema, linkStateSchema, handoffSchema, presentationSchema, selfSchema, webhookSchema, } from './contracts';
+/** What ai-agents refused, with its status and its sentence. */
+export class HostRefusedError extends Error {
+    status;
+    detail;
+    what;
+    constructor(status, detail, what) {
+        super(`${what} (${status}): ${detail}`);
+        this.status = status;
+        this.detail = detail;
+        this.what = what;
+    }
+}
+/**
+ * The generic host routes of ai-agents (plans/SLACK.md §4.3, plans/DISCORD.md
+ * §4.3) a host calls besides the credential exchange: as the installation,
+ * with its key in `X-Datalayer-Host-Key`, or as a person, with the host token
+ * the exchange answered. Any host speaks them.
+ */
+export class DatalayerHostClient {
+    apiUrl;
+    fetchImplementation;
+    constructor(apiUrl, fetchImplementation = fetch) {
+        this.apiUrl = apiUrl;
+        this.fetchImplementation = fetchImplementation;
+    }
+    #url(path) {
+        return `${this.apiUrl}/api/ai-agents/v1${path}`;
+    }
+    async #call(what, path, init, schema) {
+        const headers = {};
+        if (init.body !== undefined)
+            headers['content-type'] = 'application/json';
+        if (init.hostKey)
+            headers[HOST_KEY_HEADER] = init.hostKey;
+        if (init.token)
+            headers.authorization = `Bearer ${init.token}`;
+        const response = await this.fetchImplementation(this.#url(path), {
+            body: init.body === undefined ? undefined : JSON.stringify(init.body),
+            headers,
+            method: init.method ?? 'GET',
+        });
+        const body = (await response.json().catch(() => ({})));
+        if (!response.ok || body.success === false)
+            throw new HostRefusedError(response.status, typeof body.detail === 'string' ? body.detail : 'refused', what);
+        return schema.parse(body);
+    }
+    /** Bind the installation its owner set up, with the code their browser carried (§3.1). */
+    async bind(input) {
+        const bound = await this.#call('Datalayer did not bind the installation', '/apps/hosts/bind', {
+            body: {
+                code: input.code,
+                external_id: input.externalId,
+                name: input.name ?? '',
+            },
+            method: 'POST',
+        }, bindSchema);
+        return {
+            defaultDeployment: bound.host.default_deployment || undefined,
+            hostKey: bound.host_key,
+            hostUid: bound.host.uid,
+            name: bound.host.name,
+        };
+    }
+    /** The installation was removed from its host: it ends at Datalayer (revocation). */
+    async uninstalled(hostKey) {
+        await this.#call('Datalayer did not end the installation', '/apps/hosts/self', { hostKey, method: 'DELETE' }, z.unknown());
+    }
+    /**
+     * The installation as Datalayer keeps it: the deployments it allows (with
+     * their application's name and whether each is kept on), the default, the
+     * channel policy and whether it is paused.
+     */
+    async self(hostKey) {
+        const answered = await this.#call('Datalayer did not answer the installation', '/apps/hosts/self', { hostKey }, selfSchema);
+        const host = answered.host;
+        return {
+            accountUid: host.account_uid ?? '',
+            channels: (host.channels ?? []).map(one => ({
+                deployment: one.deployment ?? '',
+                id: one.id,
+                state: one.state,
+            })),
+            defaultDeployment: host.default_deployment || undefined,
+            deployments: host.deployments.map(one => ({
+                appName: one.app_name ?? '',
+                kept: one.kept ?? false,
+                uid: one.uid,
+            })),
+            directOnly: host.direct_only ?? [],
+            paused: host.paused ?? false,
+        };
+    }
+    /** The host unlinks one of its users: how many links ended. */
+    async unlink(hostKey, externalUserId) {
+        const answered = await this.#call('Datalayer did not unlink the account', `/apps/hosts/self/links/${encodeURIComponent(externalUserId)}`, { hostKey, method: 'DELETE' }, z.object({ revoked: z.number().int() }));
+        return answered.revoked;
+    }
+    /** A one-use code a host user redeems, signed in to Datalayer, to link their account. */
+    async linkCode(hostKey, externalUserId, externalUserName = '') {
+        const answered = await this.#call('Datalayer did not answer a link code', '/apps/hosts/self/link-codes', {
+            body: {
+                external_user_id: externalUserId,
+                external_user_name: externalUserName,
+            },
+            hostKey,
+            method: 'POST',
+        }, linkCodeSchema);
+        return { code: answered.code, expiresIn: answered.expires_in };
+    }
+    /** Whether a host user is linked, and to which principal. */
+    async linkState(hostKey, externalUserId) {
+        const state = await this.#call('Datalayer did not say whether the account is linked', `/apps/hosts/self/links/${encodeURIComponent(externalUserId)}`, { hostKey }, linkStateSchema);
+        return { linked: state.linked, principalUid: state.principal_uid };
+    }
+    /** Where deliveries are pushed: answered the secret they are signed with, once. */
+    async setWebhook(hostKey, url) {
+        const hook = await this.#call('Datalayer did not register the delivery address', '/apps/hosts/self/delivery', {
+            body: {
+                events: ['approval.requested', 'approval.decided', 'turn.completed'],
+                url,
+            },
+            hostKey,
+            method: 'PUT',
+        }, webhookSchema);
+        return { signingSecret: hook.signing_secret, version: hook.version };
+    }
+    /** What the installation has not acknowledged, oldest first: pushed or not. */
+    async outbox(hostKey, limit = 100) {
+        const listed = await this.#call('Datalayer did not answer the outbox', `/apps/hosts/self/deliveries?limit=${limit}`, { hostKey }, z.object({ deliveries: z.array(z.unknown()) }));
+        return listed.deliveries.map(deliveryOfOutbox);
+    }
+    async acknowledge(hostKey, deliveryUid) {
+        await this.#call('Datalayer did not take the acknowledgement', `/apps/hosts/self/deliveries/${encodeURIComponent(deliveryUid)}/ack`, { hostKey, method: 'POST' }, z.unknown());
+    }
+    /**
+     * *Open in Datalayer* (S-305): a one-use code for the host token's person
+     * that opens one session or approval after sign-in. Answers the landing's
+     * path that redeems it; never a bearer token in a URL.
+     */
+    async handoff(token, kind, target) {
+        const made = await this.#call('Datalayer did not make the link', '/apps/hosts/handoffs', { body: { kind, target }, method: 'POST', token }, handoffSchema);
+        return { expiresIn: made.expires_in, path: made.path };
+    }
+    /** How an approval is shown, read as the person it waits on (their host token). */
+    async presentation(token, approvalId) {
+        const answered = await this.#call('Datalayer did not answer the approval', `/tool-approvals/${encodeURIComponent(approvalId)}/presentation`, { token }, z.object({ presentation: presentationSchema }));
+        return answered.presentation;
+    }
+    /** Decide an approval as its person, on the very presentation shown (its digest). */
+    async decide(token, approvalId, decision) {
+        const answered = await this.#call('Datalayer did not take the decision', `/apps/hosts/approvals/${encodeURIComponent(approvalId)}/decision`, {
+            body: {
+                approve: decision.approve,
+                digest: decision.digest,
+                note: decision.note || null,
+            },
+            method: 'POST',
+            token,
+        }, decisionSchema);
+        return { status: answered.approval.status };
+    }
+}

package/lib/portable/hosts/contracts.d.ts

@@ -0,0 +1,199 @@
+import { z } from 'zod';
+/**
+ * The generic Datalayer host contracts (plans/SLACK.md §4.3, plans/DISCORD.md
+ * §4.3), as ai-agents answers them, for every chat host (Slack, Discord).
+ * These shapes are shared with ai-agents through `contracts.json`, beside
+ * this file and byte-identical to ai-agents' `tests/fixtures/hosts/`, which
+ * both sides test. A delivery's `target` stays opaque here: each host
+ * validates its own.
+ *
+ * @module portable/hosts/contracts
+ */
+export declare const HOST_KEY_HEADER = "X-Datalayer-Host-Key";
+export declare const SIGNATURE_HEADER = "X-Datalayer-Signature";
+export declare const TIMESTAMP_HEADER = "X-Datalayer-Timestamp";
+export declare const DELIVERY_HEADER = "X-Datalayer-Delivery";
+export declare const IDEMPOTENCY_HEADER = "Idempotency-Key";
+/** The presentation version the hosts render; another is reviewed in Datalayer. */
+export declare const PRESENTATION_VERSION = 1;
+export declare const bindSchema: z.ZodObject<{
+    host: z.ZodObject<{
+        uid: z.ZodString;
+        state: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        default_deployment: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    host_key: z.ZodString;
+}, z.core.$strip>;
+/** What a link code is redeemed at: the landing's confirm page. */
+export declare const LINK_PAGE_PATH = "/hosts/link";
+/**
+ * `GET /apps/hosts/self`: the installation with its allowed deployments.
+ * `channels`, `direct_only` and `paused` are the installation's channel
+ * policy and pause (S-104, S-105, S-403).
+ */
+export declare const selfSchema: z.ZodObject<{
+    host: z.ZodObject<{
+        uid: z.ZodString;
+        account_uid: z.ZodOptional<z.ZodString>;
+        default_deployment: z.ZodOptional<z.ZodString>;
+        deployments: z.ZodArray<z.ZodObject<{
+            uid: z.ZodString;
+            app_name: z.ZodOptional<z.ZodString>;
+            kept: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+        channels: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            state: z.ZodEnum<{
+                allow: "allow";
+                deny: "deny";
+            }>;
+            deployment: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        direct_only: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        paused: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>;
+}, z.core.$strip>;
+/** `POST /apps/hosts/handoffs`: a one-use code that opens one session or approval (S-305). */
+export declare const handoffSchema: z.ZodObject<{
+    code: z.ZodString;
+    expires_in: z.ZodNumber;
+    path: z.ZodString;
+}, z.core.$strip>;
+export declare const linkStateSchema: z.ZodObject<{
+    linked: z.ZodBoolean;
+    principal_uid: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const webhookSchema: z.ZodObject<{
+    url: z.ZodURL;
+    events: z.ZodArray<z.ZodString>;
+    version: z.ZodNumber;
+    signing_secret: z.ZodString;
+}, z.core.$strip>;
+/** One delivery of the outbox, as `GET …/self/deliveries` lists it. */
+export declare const outboxItemSchema: z.ZodObject<{
+    uid: z.ZodString;
+    event: z.ZodString;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    state: z.ZodString;
+}, z.core.$loose>;
+export declare const decisionSchema: z.ZodObject<{
+    approval: z.ZodObject<{
+        id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        status: z.ZodString;
+    }, z.core.$loose>;
+}, z.core.$strip>;
+export declare const linkCodeSchema: z.ZodObject<{
+    code: z.ZodString;
+    expires_in: z.ZodNumber;
+    confirm: z.ZodString;
+}, z.core.$strip>;
+export declare const exchangeSchema: z.ZodObject<{
+    access_token: z.ZodString;
+    token_type: z.ZodLiteral<"Bearer">;
+    expires_in: z.ZodNumber;
+    exp: z.ZodNumber;
+    principal_uid: z.ZodString;
+    host_uid: z.ZodString;
+    deployment: z.ZodObject<{
+        uid: z.ZodString;
+        app_uid: z.ZodString;
+        app_name: z.ZodString;
+        version: z.ZodNumber;
+    }, z.core.$strip>;
+    session_api: z.ZodObject<{
+        url: z.ZodURL;
+        agent: z.ZodString;
+    }, z.core.$strip>;
+    user_token: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type HostExchange = z.infer<typeof exchangeSchema>;
+export declare const presentationSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    approval_id: z.ZodString;
+    status: z.ZodString;
+    owner_uid: z.ZodString;
+    tool_name: z.ZodString;
+    action_class: z.ZodEnum<{
+        unknown: "unknown";
+        read: "read";
+        write: "write";
+        send: "send";
+        delete: "delete";
+        publish: "publish";
+        execute: "execute";
+        financial: "financial";
+    }>;
+    session_uid: z.ZodString;
+    created_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    expires_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    fields: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        label: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>>;
+    arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    secret_fields: z.ZodArray<z.ZodString>;
+    complete: z.ZodBoolean;
+    host_may_decide: z.ZodBoolean;
+    reasons: z.ZodArray<z.ZodString>;
+    digest: z.ZodString;
+}, z.core.$strip>;
+export type ApprovalPresentation = z.infer<typeof presentationSchema>;
+export declare const deliverySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    delivery: z.ZodString;
+    event: z.ZodLiteral<"approval.requested">;
+    payload: z.ZodObject<{
+        approval_id: z.ZodString;
+        tool_name: z.ZodString;
+        presentation: z.ZodString;
+        session_uid: z.ZodString;
+        deployment_uid: z.ZodString;
+        target: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$loose>;
+}, z.core.$strip>, z.ZodObject<{
+    delivery: z.ZodString;
+    event: z.ZodLiteral<"approval.decided">;
+    payload: z.ZodObject<{
+        approval_id: z.ZodString;
+        status: z.ZodString;
+        decided_by: z.ZodString;
+        session_uid: z.ZodString;
+        deployment_uid: z.ZodString;
+        target: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$loose>;
+}, z.core.$strip>, z.ZodObject<{
+    delivery: z.ZodString;
+    event: z.ZodLiteral<"turn.completed">;
+    payload: z.ZodObject<{
+        record_entry: z.ZodString;
+        session_uid: z.ZodString;
+        deployment_uid: z.ZodString;
+        target: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$loose>;
+}, z.core.$strip>], "event">;
+export type HostDelivery = z.infer<typeof deliverySchema>;
+/** An outbox item read as the delivery a push would have carried. */
+export declare function deliveryOfOutbox(item: unknown): HostDelivery;
+/**
+ * Whether a host may offer Approve and Reject: only what the server says a
+ * host may decide, in a version the hosts render, shown whole, pending, with
+ * no secret field. Anything else gets *Review in Datalayer* (SLACK §2 rule 6,
+ * DISCORD §2 rule 6). Each host also checks the card fits its own limits.
+ */
+export declare function hostMayDecide(presentation: ApprovalPresentation): boolean;
+/** `v1=` HMAC-SHA256 of `"<timestamp>.<raw body>"`, as ai-agents signs a push. */
+export declare function deliverySignature(secret: string, timestamp: number, rawBody: string | Buffer): string;
+/**
+ * Verify a pushed delivery before trusting it: its signature in constant
+ * time, and a timestamp within five minutes, so a captured push cannot be
+ * replayed later.
+ */
+export declare function verifyDelivery(input: {
+    nowSeconds?: number;
+    rawBody: string | Buffer;
+    secret: string;
+    signature: string | undefined;
+    timestamp: string | undefined;
+    toleranceSeconds?: number;
+}): HostDelivery;

package/lib/portable/hosts/contracts.js

@@ -0,0 +1,235 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { z } from 'zod';
+/**
+ * The generic Datalayer host contracts (plans/SLACK.md §4.3, plans/DISCORD.md
+ * §4.3), as ai-agents answers them, for every chat host (Slack, Discord).
+ * These shapes are shared with ai-agents through `contracts.json`, beside
+ * this file and byte-identical to ai-agents' `tests/fixtures/hosts/`, which
+ * both sides test. A delivery's `target` stays opaque here: each host
+ * validates its own.
+ *
+ * @module portable/hosts/contracts
+ */
+export const HOST_KEY_HEADER = 'X-Datalayer-Host-Key';
+export const SIGNATURE_HEADER = 'X-Datalayer-Signature';
+export const TIMESTAMP_HEADER = 'X-Datalayer-Timestamp';
+export const DELIVERY_HEADER = 'X-Datalayer-Delivery';
+export const IDEMPOTENCY_HEADER = 'Idempotency-Key';
+/** The presentation version the hosts render; another is reviewed in Datalayer. */
+export const PRESENTATION_VERSION = 1;
+export const bindSchema = z.object({
+    host: z
+        .object({
+        uid: z.string().min(1),
+        state: z.string(),
+        name: z.string().optional(),
+        default_deployment: z.string().optional(),
+    })
+        .loose(),
+    host_key: z.string().startsWith('dlhk_'),
+});
+/** What a link code is redeemed at: the landing's confirm page. */
+export const LINK_PAGE_PATH = '/hosts/link';
+/**
+ * `GET /apps/hosts/self`: the installation with its allowed deployments.
+ * `channels`, `direct_only` and `paused` are the installation's channel
+ * policy and pause (S-104, S-105, S-403).
+ */
+export const selfSchema = z.object({
+    host: z
+        .object({
+        uid: z.string().min(1),
+        account_uid: z.string().optional(),
+        default_deployment: z.string().optional(),
+        deployments: z.array(z
+            .object({
+            uid: z.string().min(1),
+            app_name: z.string().optional(),
+            kept: z.boolean().optional(),
+        })
+            .loose()),
+        channels: z
+            .array(z.object({
+            id: z.string().min(1),
+            state: z.enum(['allow', 'deny']),
+            deployment: z.string().optional(),
+        }))
+            .optional(),
+        direct_only: z.array(z.string()).optional(),
+        paused: z.boolean().optional(),
+    })
+        .loose(),
+});
+/** `POST /apps/hosts/handoffs`: a one-use code that opens one session or approval (S-305). */
+export const handoffSchema = z.object({
+    code: z.string().startsWith('dlho_'),
+    expires_in: z.number().int().nonnegative(),
+    path: z.string().startsWith('/hosts/open?code='),
+});
+export const linkStateSchema = z.object({
+    linked: z.boolean(),
+    principal_uid: z.string().optional(),
+});
+export const webhookSchema = z.object({
+    url: z.url(),
+    events: z.array(z.string()),
+    version: z.number().int(),
+    signing_secret: z.string().min(32),
+});
+/** One delivery of the outbox, as `GET …/self/deliveries` lists it. */
+export const outboxItemSchema = z
+    .object({
+    uid: z.string().min(1),
+    event: z.string(),
+    payload: z.record(z.string(), z.unknown()),
+    state: z.string(),
+})
+    .loose();
+export const decisionSchema = z.object({
+    approval: z
+        .object({ id: z.string().nullable().optional(), status: z.string() })
+        .loose(),
+});
+export const linkCodeSchema = z.object({
+    code: z.string().startsWith('dlhc_'),
+    expires_in: z.number().int().nonnegative(),
+    confirm: z.string(),
+});
+export const exchangeSchema = z.object({
+    access_token: z.string().min(1),
+    token_type: z.literal('Bearer'),
+    expires_in: z.number().int().nonnegative(),
+    exp: z.number().int(),
+    principal_uid: z.string().min(1),
+    host_uid: z.string().min(1),
+    deployment: z.object({
+        uid: z.string().min(1),
+        app_uid: z.string(),
+        app_name: z.string(),
+        version: z.number().int(),
+    }),
+    session_api: z.object({ url: z.url(), agent: z.string() }),
+    user_token: z.string().optional(),
+});
+const fieldSchema = z.object({
+    name: z.string(),
+    label: z.string(),
+    value: z.string(),
+});
+export const presentationSchema = z.object({
+    version: z.number().int(),
+    approval_id: z.string().min(1),
+    status: z.string(),
+    owner_uid: z.string(),
+    tool_name: z.string(),
+    action_class: z.enum([
+        'read',
+        'send',
+        'write',
+        'execute',
+        'publish',
+        'delete',
+        'financial',
+        'unknown',
+    ]),
+    session_uid: z.string(),
+    created_at: z.string().nullable().optional(),
+    expires_at: z.string().nullable().optional(),
+    fields: z.array(fieldSchema),
+    arguments: z.record(z.string(), z.unknown()),
+    secret_fields: z.array(z.string()),
+    complete: z.boolean(),
+    host_may_decide: z.boolean(),
+    reasons: z.array(z.string()),
+    digest: z.string().regex(/^[0-9a-f]{64}$/),
+});
+export const deliverySchema = z.discriminatedUnion('event', [
+    z.object({
+        delivery: z.string().min(1),
+        event: z.literal('approval.requested'),
+        payload: z
+            .object({
+            approval_id: z.string().min(1),
+            tool_name: z.string(),
+            presentation: z.string(),
+            session_uid: z.string(),
+            deployment_uid: z.string(),
+            target: z.record(z.string(), z.unknown()),
+        })
+            .loose(),
+    }),
+    z.object({
+        delivery: z.string().min(1),
+        event: z.literal('approval.decided'),
+        payload: z
+            .object({
+            approval_id: z.string().min(1),
+            status: z.string(),
+            decided_by: z.string(),
+            session_uid: z.string(),
+            deployment_uid: z.string(),
+            target: z.record(z.string(), z.unknown()),
+        })
+            .loose(),
+    }),
+    z.object({
+        delivery: z.string().min(1),
+        event: z.literal('turn.completed'),
+        payload: z
+            .object({
+            record_entry: z.string(),
+            session_uid: z.string(),
+            deployment_uid: z.string(),
+            target: z.record(z.string(), z.unknown()),
+        })
+            .loose(),
+    }),
+]);
+/** An outbox item read as the delivery a push would have carried. */
+export function deliveryOfOutbox(item) {
+    const { uid, event, payload } = outboxItemSchema.parse(item);
+    return deliverySchema.parse({ delivery: uid, event, payload });
+}
+/**
+ * Whether a host may offer Approve and Reject: only what the server says a
+ * host may decide, in a version the hosts render, shown whole, pending, with
+ * no secret field. Anything else gets *Review in Datalayer* (SLACK §2 rule 6,
+ * DISCORD §2 rule 6). Each host also checks the card fits its own limits.
+ */
+export function hostMayDecide(presentation) {
+    return (presentation.version === PRESENTATION_VERSION &&
+        presentation.host_may_decide &&
+        presentation.complete &&
+        presentation.secret_fields.length === 0 &&
+        presentation.status === 'pending');
+}
+/** `v1=` HMAC-SHA256 of `"<timestamp>.<raw body>"`, as ai-agents signs a push. */
+export function deliverySignature(secret, timestamp, rawBody) {
+    const mac = createHmac('sha256', secret);
+    mac.update(`${timestamp}.`);
+    mac.update(rawBody);
+    return `v1=${mac.digest('hex')}`;
+}
+/**
+ * Verify a pushed delivery before trusting it: its signature in constant
+ * time, and a timestamp within five minutes, so a captured push cannot be
+ * replayed later.
+ */
+export function verifyDelivery(input) {
+    const stamp = Number(input.timestamp);
+    const now = input.nowSeconds ?? Math.floor(Date.now() / 1000);
+    if (!Number.isInteger(stamp) ||
+        Math.abs(now - stamp) > (input.toleranceSeconds ?? 300)) {
+        throw new Error("The delivery's timestamp is missing or too old.");
+    }
+    const expected = Buffer.from(deliverySignature(input.secret, stamp, input.rawBody));
+    const given = Buffer.from(input.signature ?? '');
+    if (expected.length !== given.length || !timingSafeEqual(expected, given)) {
+        throw new Error("The delivery's signature does not match.");
+    }
+    return deliverySchema.parse(JSON.parse(input.rawBody.toString()));
+}