zooid 0.13.0 → 0.14.1

package/src/daemon/webhook-routes.test.ts

@@ -0,0 +1,104 @@
+import { createHmac } from 'node:crypto'
+import { describe, expect, it, vi } from 'vitest'
+import { Hono } from 'hono'
+import { loadZooidConfig } from '@zooid/core'
+import { eventNameFor, mountWebhookRoutes } from './webhook-routes.js'
+
+const secret = 'route-secret'
+const body = JSON.stringify({ action: 'opened' })
+const signature = `sha256=${createHmac('sha256', secret).update(body).digest('hex')}`
+const yaml = `
+runtime: local
+transports:
+  matrix:
+    type: matrix
+    homeserver: http://localhost:8448
+    as_token: t
+    hs_token: h
+    user_namespace: '@.*:example.org'
+agents:
+  product:
+    acp: { preset: opencode }
+    matrix: { rooms: ['#product:example.org'] }
+triggers:
+  triage:
+    webhook:
+      provider: github
+      secret: ${secret}
+    as: '@hook:example.org'
+    room: '!product:example.org'
+    mention: product
+    text: Triage.
+`
+
+function makeApp() {
+  const sent: Array<Record<string, unknown>> = []
+  const app = new Hono()
+  mountWebhookRoutes(app, {
+    triggers: loadZooidConfig(yaml).triggers,
+    agentUserIds: { product: '@product:example.org' },
+    resolveRoom: async (room) => room,
+    ensureBot: async () => {},
+    sendMessage: async (message: Record<string, unknown>) => {
+      sent.push(message)
+      return { event_id: '$event' }
+    },
+  })
+  return { app, sent }
+}
+
+function post(app: Hono, path: string) {
+  return app.request(path, {
+    method: 'POST',
+    body,
+    headers: {
+      'x-hub-signature-256': signature,
+      'x-github-event': 'issues',
+      'x-github-delivery': crypto.randomUUID(),
+    },
+  })
+}
+
+describe('webhook route contract', () => {
+  it('accepts a signed delivery at /_zooid/webhooks/:name', async () => {
+    const { app, sent } = makeApp()
+    expect((await post(app, '/_zooid/webhooks/triage')).status).toBe(202)
+    await vi.waitFor(() => expect(sent).toHaveLength(1))
+  })
+
+  it('does not expose the retired /webhook/:name route', async () => {
+    const { app, sent } = makeApp()
+    expect((await post(app, '/webhook/triage')).status).toBe(404)
+    expect(sent).toHaveLength(0)
+  })
+})
+
+describe('event name binding', () => {
+  const headers = { 'x-github-event': 'pull_request' }
+
+  it('reads GitHub from the header, not the payload', () => {
+    expect(eventNameFor('github', headers, { type: 'ignored' })).toBe('pull_request')
+  })
+
+  it('reads stripe and standard-webhooks from body.type', () => {
+    expect(eventNameFor('stripe', {}, { type: 'invoice.payment_failed' })).toBe(
+      'invoice.payment_failed',
+    )
+    expect(eventNameFor('standard', {}, { type: 'user.created' })).toBe('user.created')
+  })
+
+  it('reads slack from body.event.type', () => {
+    expect(eventNameFor('slack', {}, { event: { type: 'app_mention' } })).toBe('app_mention')
+  })
+
+  it('leaves custom unbound — only the operator knows their service shape', () => {
+    expect(eventNameFor('custom', headers, { type: 'anything' })).toBeUndefined()
+  })
+
+  it('yields undefined rather than throwing on a missing or wrong-typed path', () => {
+    expect(eventNameFor('stripe', {}, undefined)).toBeUndefined()
+    expect(eventNameFor('stripe', {}, { type: 42 })).toBeUndefined()
+    expect(eventNameFor('slack', {}, { event: null })).toBeUndefined()
+    expect(eventNameFor('github', {}, {})).toBeUndefined()
+  })
+})

package/src/daemon/webhook-routes.ts

@@ -0,0 +1,237 @@
+import type { Context, Hono } from 'hono'
+import type { MatchContext, TriggerConfig, WebhookTriggerConfig } from '@zooid/core'
+import { evaluateMatch, renderTemplate } from '@zooid/core'
+import { fireTrigger, type FireTriggerDeps } from './trigger-runner.js'
+import { verifySignature, verifyCustomSignature, type CustomVerifier } from './webhook-verify.js'
+import { DeliveryCache } from './delivery-cache.js'
+
+// GitHub's delivery times out at 10s; a 1MB cap leaves headroom to hash and
+// respond well inside that even on a slow box. Checked before hashing, per
+// [[ZOD082]] §Design 4 rule 5.
+const MAX_BODY = 1_000_000
+// `${output}` is a chat message body, not a blob store — cap it well under
+// Matrix's ~64KiB event-size ceiling once the surrounding `text:` is added.
+const MAX_OUTPUT_CHARS = 60_000
+const TRUNCATION_MARKER = '\n\n… (truncated)'
+// Comfortably past any provider's redelivery window.
+const DELIVERY_CACHE_TTL_MS = 24 * 60 * 60 * 1000
+
+/**
+ * Where each provider puts its event name. GitHub is the only one that uses
+ * a header; the rest carry it in the payload. Reading it per provider is the
+ * point — it keeps provider knowledge in code (the same knowledge the
+ * signature table encodes) so `event` means the same thing in an operator's
+ * `match:` whatever the sender. `custom` is absent on purpose: only the
+ * operator knows their service's shape, so their predicate reads `body`.
+ */
+const EVENT_SOURCE_BY_PROVIDER: Partial<
+  Record<WebhookTriggerConfig['provider'], { header: string } | { path: readonly string[] }>
+> = {
+  github: { header: 'x-github-event' },
+  stripe: { path: ['type'] },
+  standard: { path: ['type'] },
+  slack: { path: ['event', 'type'] },
+}
+
+/** Follow a dotted path through a parsed payload, yielding a string or nothing. */
+function stringAt(body: unknown, path: readonly string[]): string | undefined {
+  let cursor: unknown = body
+  for (const key of path) {
+    if (typeof cursor !== 'object' || cursor === null) return undefined
+    cursor = (cursor as Record<string, unknown>)[key]
+  }
+  return typeof cursor === 'string' ? cursor : undefined
+}
+
+/** The `event` binding for `match:` and `${...}`, per provider. */
+export function eventNameFor(
+  provider: WebhookTriggerConfig['provider'],
+  headers: Record<string, string | undefined>,
+  body: unknown,
+): string | undefined {
+  const source = EVENT_SOURCE_BY_PROVIDER[provider]
+  if (!source) return undefined
+  return 'header' in source ? headers[source.header] : stringAt(body, source.path)
+}
+
+const DELIVERY_ID_HEADER_BY_PROVIDER: Partial<Record<WebhookTriggerConfig['provider'], string>> = {
+  github: 'x-github-delivery',
+  standard: 'webhook-id',
+}
+
+// Headers any supported provider might send, gathered once per request.
+const RELEVANT_HEADERS = [
+  'x-hub-signature-256',
+  'x-github-event',
+  'x-github-delivery',
+  'stripe-signature',
+  'x-slack-signature',
+  'x-slack-request-timestamp',
+  'webhook-signature',
+  'webhook-id',
+  'webhook-timestamp',
+] as const
+
+export interface WebhookDeps {
+  triggers: Record<string, TriggerConfig>
+  /**
+   * Verifier function per `provider: custom` trigger name, imported at
+   * daemon start by `loadCustomVerifiers`. A custom trigger with no entry
+   * here rejects every delivery — fail closed.
+   */
+  customVerifiers?: Record<string, CustomVerifier>
+  agentUserIds: Record<string, string>
+  resolveRoom: FireTriggerDeps['resolveRoom']
+  ensureBot: FireTriggerDeps['ensureBot']
+  sendMessage: FireTriggerDeps['sendMessage']
+}
+
+/**
+ * Gather the headers verification might need. Named providers read a fixed
+ * set; `provider: custom` gets every header, lower-cased, since only the
+ * operator's verifier knows which ones its service sends.
+ */
+function headersOf(
+  c: { req: { header: (name: string) => string | undefined; raw: Request } },
+  all: boolean,
+): Record<string, string | undefined> {
+  const out: Record<string, string | undefined> = {}
+  if (all) {
+    c.req.raw.headers.forEach((value, key) => {
+      out[key.toLowerCase()] = value
+    })
+    return out
+  }
+  for (const h of RELEVANT_HEADERS) out[h] = c.req.header(h)
+  return out
+}
+
+/** Headers as a dense record, for handing to an operator's verifier. */
+function definedHeaders(headers: Record<string, string | undefined>): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [k, v] of Object.entries(headers)) {
+    if (v !== undefined) out[k] = v
+  }
+  return out
+}
+
+function renderPayload(raw: string): string {
+  let pretty: string
+  try {
+    pretty = JSON.stringify(JSON.parse(raw), null, 2)
+  } catch {
+    pretty = raw
+  }
+  if (pretty.length <= MAX_OUTPUT_CHARS) return pretty
+  return pretty.slice(0, MAX_OUTPUT_CHARS) + TRUNCATION_MARKER
+}
+
+async function handleDelivery(
+  deps: WebhookDeps,
+  name: string,
+  trigger: TriggerConfig,
+  raw: string,
+  headers: Record<string, string | undefined>,
+  cache: DeliveryCache,
+  customDeliveryId: string | undefined,
+): Promise<void> {
+  try {
+    const webhook = trigger.webhook
+    if (!webhook) return
+
+    const idHeader = DELIVERY_ID_HEADER_BY_PROVIDER[webhook.provider]
+    // A custom verifier reports its own delivery id, since only it knows
+    // where the service puts one.
+    const deliveryId = customDeliveryId ?? (idHeader ? headers[idHeader] : undefined)
+    if (deliveryId !== undefined && cache.seen(`${name}:${deliveryId}`)) return
+
+    let body: unknown
+    try {
+      body = JSON.parse(raw)
+    } catch {
+      body = undefined
+    }
+
+    // After parsing: every provider but GitHub carries its event name in the
+    // payload, not a header.
+    const event = eventNameFor(webhook.provider, headers, body)
+
+    const ctx: MatchContext = {
+      event,
+      body,
+      headers: definedHeaders(headers),
+      output: renderPayload(raw),
+    }
+
+    for (const message of trigger.messages) {
+      if (message.match !== undefined && !evaluateMatch(message.match, ctx)) continue
+
+      const agentUserId = deps.agentUserIds[message.mention]
+      if (!agentUserId) {
+        console.warn(`[webhook:${name}] unknown agent "${message.mention}" — skipping`)
+        continue
+      }
+
+      await fireTrigger({
+        name,
+        as: trigger.as,
+        message: { ...message, text: renderTemplate(message.text, ctx) },
+        agentUserId,
+        resolveRoom: deps.resolveRoom,
+        ensureBot: deps.ensureBot,
+        sendMessage: deps.sendMessage,
+      })
+    }
+  } catch (err) {
+    // Never throw: the response has already been sent, and one bad delivery
+    // must not take down the daemon.
+    console.warn(`[webhook:${name}] failed:`, (err as Error).message)
+  }
+}
+
+export const WEBHOOK_ROUTE_PREFIX = '/_zooid/webhooks'
+
+export function mountWebhookRoutes(app: Hono, deps: WebhookDeps): void {
+  const cache = new DeliveryCache(DELIVERY_CACHE_TTL_MS)
+
+  const receive = async (c: Context<any, '/:name'>) => {
+    const name = c.req.param('name')
+    const trigger = deps.triggers[name]
+
+    // Read the RAW body first. Parsing and re-serializing changes the bytes
+    // and breaks every signature — the classic webhook bug.
+    const raw = await c.req.text()
+    if (raw.length > MAX_BODY) return c.text('too large', 413)
+
+    // Unknown trigger and bad signature return the identical response, so
+    // the endpoint cannot be probed to discover which triggers exist.
+    if (!trigger?.webhook) return c.text('unauthorized', 401)
+    const webhook = trigger.webhook
+    const headers = headersOf(c, webhook.provider === 'custom')
+
+    let customDeliveryId: string | undefined
+    if (webhook.provider === 'custom') {
+      const v = await verifyCustomSignature(deps.customVerifiers?.[name], {
+        rawBody: raw,
+        headers: definedHeaders(headers),
+        secret: webhook.secret,
+      })
+      if (!v.ok) return c.text('unauthorized', 401)
+      customDeliveryId = v.deliveryId
+    } else {
+      const v = verifySignature(webhook.provider, {
+        rawBody: raw,
+        headers,
+        secret: webhook.secret,
+      })
+      if (!v.ok) return c.text('unauthorized', 401)
+    }
+
+    // Accepted. Everything below is fire-and-forget: GitHub times out at
+    // 10s and an agent turn does not fit in that.
+    void handleDelivery(deps, name, trigger, raw, headers, cache, customDeliveryId)
+    return c.text('accepted', 202)
+  }
+
+  app.post(`${WEBHOOK_ROUTE_PREFIX}/:name`, receive)
+}

package/src/daemon/webhook-verify.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect } from 'vitest'
+import { createHmac } from 'node:crypto'
+import { verifySignature, verifyCustomSignature, type CustomVerifierInput } from './webhook-verify.js'
+
+const secret = 'shh'
+const body = '{"action":"closed","number":42}'
+
+const githubSig = (b = body, s = secret) =>
+  `sha256=${createHmac('sha256', s).update(b).digest('hex')}`
+
+describe('verifySignature — github', () => {
+  it('accepts a correct signature over the raw body', () => {
+    expect(
+      verifySignature('github', { rawBody: body, headers: { 'x-hub-signature-256': githubSig() }, secret }),
+    ).toEqual({ ok: true })
+  })
+
+  it('rejects a signature computed over different bytes', () => {
+    expect(
+      verifySignature('github', {
+        rawBody: '{"action":"opened","number":42}',
+        headers: { 'x-hub-signature-256': githubSig() },
+        secret,
+      }).ok,
+    ).toBe(false)
+  })
+
+  it('rejects a signature made with a different secret', () => {
+    expect(
+      verifySignature('github', {
+        rawBody: body,
+        headers: { 'x-hub-signature-256': githubSig(body, 'wrong') },
+        secret,
+      }).ok,
+    ).toBe(false)
+  })
+
+  it('rejects a missing signature header — fail closed', () => {
+    expect(verifySignature('github', { rawBody: body, headers: {}, secret }).ok).toBe(false)
+  })
+
+  it('rejects a malformed header without throwing', () => {
+    for (const h of ['', 'sha256=', 'garbage', 'sha256=zzzz', 'sha1=abcd']) {
+      expect(() =>
+        verifySignature('github', { rawBody: body, headers: { 'x-hub-signature-256': h }, secret }),
+      ).not.toThrow()
+      expect(
+        verifySignature('github', { rawBody: body, headers: { 'x-hub-signature-256': h }, secret }).ok,
+      ).toBe(false)
+    }
+  })
+
+  it('rejects a signature of the wrong length without throwing (timingSafeEqual throws on length mismatch)', () => {
+    expect(
+      verifySignature('github', {
+        rawBody: body,
+        headers: { 'x-hub-signature-256': 'sha256=abcd' },
+        secret,
+      }).ok,
+    ).toBe(false)
+  })
+})
+
+describe('verifyCustomSignature', () => {
+  const shopifyish = ({ rawBody, headers, secret: sec }: CustomVerifierInput) => {
+    const expected = createHmac('sha256', sec).update(rawBody).digest('base64')
+    return { ok: headers['x-shopify-hmac-sha256'] === expected, deliveryId: headers['x-delivery'] }
+  }
+  const input = (headers: Record<string, string>) => ({ rawBody: body, headers, secret })
+  const sigOf = (b = body, s = secret) => createHmac('sha256', s).update(b).digest('base64')
+
+  it('accepts what the operator function accepts, and passes back its delivery id', async () => {
+    expect(
+      await verifyCustomSignature(shopifyish, input({ 'x-shopify-hmac-sha256': sigOf(), 'x-delivery': 'd9' })),
+    ).toEqual({ ok: true, deliveryId: 'd9' })
+  })
+
+  it('rejects what the operator function rejects', async () => {
+    expect(
+      (await verifyCustomSignature(shopifyish, input({ 'x-shopify-hmac-sha256': sigOf(body, 'wrong') }))).ok,
+    ).toBe(false)
+  })
+
+  it('accepts a verifier that returns a bare boolean', async () => {
+    expect(await verifyCustomSignature(() => true, input({}))).toEqual({ ok: true })
+    expect(await verifyCustomSignature(() => false, input({}))).toEqual({ ok: false })
+  })
+
+  it('awaits an async verifier', async () => {
+    expect(await verifyCustomSignature(async () => ({ ok: true, deliveryId: 'a1' }), input({}))).toEqual({
+      ok: true,
+      deliveryId: 'a1',
+    })
+  })
+
+  it('fails closed when no verifier is loaded — never "no verifier, so accept"', async () => {
+    expect(await verifyCustomSignature(undefined, input({}))).toEqual({ ok: false })
+  })
+
+  it('fails closed when the verifier throws or rejects', async () => {
+    expect(
+      (
+        await verifyCustomSignature(() => {
+          throw new Error('boom')
+        }, input({}))
+      ).ok,
+    ).toBe(false)
+    expect((await verifyCustomSignature(async () => Promise.reject(new Error('boom')), input({}))).ok).toBe(
+      false,
+    )
+  })
+
+  it('fails closed on a junk return value, rather than coercing it to true', async () => {
+    for (const junk of ['yes', 1, {}, { ok: 'true' }, null, undefined]) {
+      expect((await verifyCustomSignature((() => junk) as never, input({}))).ok).toBe(false)
+    }
+  })
+})
+
+describe('verifySignature — providers with a timestamp', () => {
+  const slackSig = (ts: string, b = body, s = secret) =>
+    `v0=${createHmac('sha256', s).update(`v0:${ts}:${b}`).digest('hex')}`
+
+  it('accepts a fresh slack signature over v0:ts:body', () => {
+    const ts = String(Math.floor(Date.now() / 1000))
+    expect(
+      verifySignature('slack', {
+        rawBody: body,
+        headers: { 'x-slack-signature': slackSig(ts), 'x-slack-request-timestamp': ts },
+        secret,
+      }),
+    ).toEqual({ ok: true })
+  })
+
+  it('rejects a slack signature outside the freshness window — replay defence', () => {
+    const old = String(Math.floor(Date.now() / 1000) - 60 * 60)
+    expect(
+      verifySignature('slack', {
+        rawBody: body,
+        headers: { 'x-slack-signature': slackSig(old), 'x-slack-request-timestamp': old },
+        secret,
+      }).ok,
+    ).toBe(false)
+  })
+
+  it('rejects a slack request with no timestamp header', () => {
+    expect(
+      verifySignature('slack', {
+        rawBody: body,
+        headers: { 'x-slack-signature': slackSig('123') },
+        secret,
+      }).ok,
+    ).toBe(false)
+  })
+})

package/src/daemon/webhook-verify.ts

@@ -0,0 +1,155 @@
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import type { WebhookTriggerConfig } from '@zooid/core'
+
+const FRESHNESS_S = 300
+
+/**
+ * What an operator's `verify:` module is called with. `headers` carries every
+ * request header, lower-cased — a named provider reads a fixed set, but a
+ * custom verifier is the only thing that knows which ones its service sends.
+ */
+export interface CustomVerifierInput {
+  rawBody: string
+  headers: Record<string, string>
+  secret: string
+}
+
+/**
+ * An operator-supplied verifier. Returns a bare boolean, or a result that
+ * also carries the provider's unique delivery id — the id is what replay
+ * dedupe keys on, and only the verifier knows where the service puts it.
+ * Throwing counts as rejection; nothing it does can turn into an accept.
+ */
+export type CustomVerifier = (
+  input: CustomVerifierInput,
+) =>
+  | boolean
+  | { ok: boolean; deliveryId?: string }
+  | Promise<boolean | { ok: boolean; deliveryId?: string }>
+
+/** Providers whose signing scheme is built in. `custom` is verified by the operator's own function. */
+export type NamedProvider = Exclude<WebhookTriggerConfig['provider'], 'custom'>
+
+export interface VerifyInput {
+  rawBody: string
+  headers: Record<string, string | undefined>
+  secret: string
+}
+
+export type VerifyResult = { ok: true } | { ok: false }
+
+// Length-check first: timingSafeEqual throws when buffers differ in length.
+function safeEqual(a: string, b: string): boolean {
+  const ab = Buffer.from(a, 'utf8')
+  const bb = Buffer.from(b, 'utf8')
+  return ab.length === bb.length && timingSafeEqual(ab, bb)
+}
+
+function hmacHex(secret: string, baseString: string): string {
+  return createHmac('sha256', secret).update(baseString).digest('hex')
+}
+
+function verifyGithub(input: VerifyInput): VerifyResult {
+  const header = input.headers['x-hub-signature-256']
+  if (!header) return { ok: false }
+  const [scheme, sig] = header.split('=')
+  if (scheme !== 'sha256' || !sig) return { ok: false }
+  const expected = hmacHex(input.secret, input.rawBody)
+  return safeEqual(sig, expected) ? { ok: true } : { ok: false }
+}
+
+function verifyStripe(input: VerifyInput): VerifyResult {
+  const header = input.headers['stripe-signature']
+  if (!header) return { ok: false }
+  const parts = Object.fromEntries(
+    header
+      .split(',')
+      .map((p) => p.split('=', 2) as [string, string | undefined])
+      .filter(([, v]) => v !== undefined),
+  )
+  const ts = parts.t
+  const sig = parts.v1
+  if (!ts || !sig) return { ok: false }
+  if (!isFresh(ts)) return { ok: false }
+  const expected = hmacHex(input.secret, `${ts}.${input.rawBody}`)
+  return safeEqual(sig, expected) ? { ok: true } : { ok: false }
+}
+
+function verifySlack(input: VerifyInput): VerifyResult {
+  const header = input.headers['x-slack-signature']
+  const ts = input.headers['x-slack-request-timestamp']
+  if (!header || !ts) return { ok: false }
+  if (!header.startsWith('v0=')) return { ok: false }
+  const sig = header.slice('v0='.length)
+  if (!isFresh(ts)) return { ok: false }
+  const expected = hmacHex(input.secret, `v0:${ts}:${input.rawBody}`)
+  return safeEqual(sig, expected) ? { ok: true } : { ok: false }
+}
+
+function verifyStandard(input: VerifyInput): VerifyResult {
+  const header = input.headers['webhook-signature']
+  const id = input.headers['webhook-id']
+  const ts = input.headers['webhook-timestamp']
+  if (!header || !id || !ts) return { ok: false }
+  if (!isFresh(ts)) return { ok: false }
+  const candidate = header
+    .split(' ')
+    .map((p) => (p.startsWith('v1,') ? p.slice('v1,'.length) : undefined))
+    .find((v) => v !== undefined)
+  if (!candidate) return { ok: false }
+  const expected = createHmac('sha256', input.secret)
+    .update(`${id}.${ts}.${input.rawBody}`)
+    .digest('base64')
+  return safeEqual(candidate, expected) ? { ok: true } : { ok: false }
+}
+
+function isFresh(tsRaw: string): boolean {
+  const ts = Number(tsRaw)
+  if (!Number.isFinite(ts)) return false
+  const nowS = Date.now() / 1000
+  return Math.abs(nowS - ts) <= FRESHNESS_S
+}
+
+const VERIFIERS: Record<NamedProvider, (input: VerifyInput) => VerifyResult> = {
+  github: verifyGithub,
+  stripe: verifyStripe,
+  slack: verifySlack,
+  standard: verifyStandard,
+}
+
+/**
+ * Verify a webhook delivery's signature. Every failure path returns
+ * `{ ok: false }` — nothing throws, and no reason is returned to the
+ * caller, since the route must not explain *why* it rejected a request.
+ */
+export function verifySignature(provider: NamedProvider, input: VerifyInput): VerifyResult {
+  try {
+    return VERIFIERS[provider](input)
+  } catch {
+    return { ok: false }
+  }
+}
+
+/**
+ * Run an operator-supplied verifier for `provider: custom`. Fails closed on
+ * every abnormal path — no verifier loaded, a throw, a rejected promise, or
+ * a return value that is not a recognised shape. A verifier can only ever
+ * *grant* acceptance by explicitly returning true.
+ */
+export async function verifyCustomSignature(
+  verifier: CustomVerifier | undefined,
+  input: CustomVerifierInput,
+): Promise<{ ok: boolean; deliveryId?: string }> {
+  if (typeof verifier !== 'function') return { ok: false }
+  try {
+    const result = await verifier(input)
+    if (result === true) return { ok: true }
+    if (result === false || result === null || typeof result !== 'object') return { ok: false }
+    if (result.ok !== true) return { ok: false }
+    return typeof result.deliveryId === 'string'
+      ? { ok: true, deliveryId: result.deliveryId }
+      : { ok: true }
+  } catch {
+    return { ok: false }
+  }
+}