@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/server-api/ci-tokens.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The CI tokens' wire shapes (callback-assertion spec §3). A CI token reads captures in one server
+ * workspace and nothing else; the server keeps only its hash. The server's routes validate with these
+ * and the desktop's main process and the CLI parse answers with them. Plain zod only (ADR-0009).
+ *
+ * The token itself appears in exactly one answer, the create, and is never listed again.
+ */
+import { z } from 'zod';
+export declare const CI_TOKEN_NAME_MAX_LENGTH = 64;
+/**
+ * `POST …/ci-tokens`. The server validates with its own route schema, which trims the name before it
+ * bounds it by `CI_TOKEN_NAME_MAX_LENGTH` and refuses a blank one.
+ */
+export interface CiTokenCreateRequest {
+    readonly name: string;
+}
+/** The one answer that holds the token: the desktop shows it once, with *Copy*. */
+export declare const ciTokenCreatedSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    token: z.ZodString;
+}, z.core.$strip>;
+export type CiTokenCreated = z.infer<typeof ciTokenCreatedSchema>;
+export declare const ciTokenSummarySchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    createdBy: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    lastUsedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type CiTokenSummary = z.infer<typeof ciTokenSummarySchema>;
+/** Unrevoked tokens, by name. */
+export declare const ciTokensResponseSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    createdBy: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    lastUsedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>>;
+export declare const ciTokenParamsSchema: z.ZodObject<{
+    workspaceId: z.ZodString;
+    tokenId: z.ZodString;
+}, z.core.$strip>;
+/** `GET /api/v1/ci/whoami`: which workspace a CI token reads. */
+export declare const ciWhoamiResponseSchema: z.ZodObject<{
+    workspaceId: z.ZodString;
+    workspaceName: z.ZodString;
+    tokenName: z.ZodString;
+}, z.core.$strip>;
+export type CiWhoamiResponse = z.infer<typeof ciWhoamiResponseSchema>;

package/dist/server-api/ci-tokens.js

@@ -0,0 +1,35 @@
+/**
+ * The CI tokens' wire shapes (callback-assertion spec §3). A CI token reads captures in one server
+ * workspace and nothing else; the server keeps only its hash. The server's routes validate with these
+ * and the desktop's main process and the CLI parse answers with them. Plain zod only (ADR-0009).
+ *
+ * The token itself appears in exactly one answer, the create, and is never listed again.
+ */
+import { z } from 'zod';
+import { DEVICE_TOKEN_PATTERN } from './identity.js';
+import { teamsIdSchema } from './teams.js';
+export const CI_TOKEN_NAME_MAX_LENGTH = 64;
+/** The one answer that holds the token: the desktop shows it once, with *Copy*. */
+export const ciTokenCreatedSchema = z.object({
+    id: teamsIdSchema,
+    name: z.string(),
+    token: z.string().regex(DEVICE_TOKEN_PATTERN),
+});
+export const ciTokenSummarySchema = z.object({
+    id: teamsIdSchema,
+    name: z.string(),
+    /** The creator's display name; `null` once that account is gone. */
+    createdBy: z.string().nullable(),
+    createdAt: z.string(),
+    /** Written at most once a minute; `null` until first used. */
+    lastUsedAt: z.string().nullable(),
+});
+/** Unrevoked tokens, by name. */
+export const ciTokensResponseSchema = z.array(ciTokenSummarySchema);
+export const ciTokenParamsSchema = z.object({ workspaceId: teamsIdSchema, tokenId: teamsIdSchema });
+/** `GET /api/v1/ci/whoami`: which workspace a CI token reads. */
+export const ciWhoamiResponseSchema = z.object({
+    workspaceId: teamsIdSchema,
+    workspaceName: z.string(),
+    tokenName: z.string(),
+});

package/dist/server-api/hooks.d.ts

@@ -0,0 +1,337 @@
+/**
+ * The webhook-capture module's wire shapes (webhook-capture spec §3.5, §3.7). The server's routes
+ * validate with them through `jsonSchema()` and the desktop's main process parses answers with them,
+ * so a drift between the two fails typecheck. Plain zod only (ADR-0009).
+ *
+ * A catch URL is owned by a workspace. Its secret is the only credential on the public route, so it
+ * appears only inside `url`, which only workspace viewers and up can read (§5). The renderer never
+ * imports a value from here: main parses, and the renderer takes the inferred types.
+ *
+ * JSON Schema cannot count UTF-8 bytes or trim, so two checks stay in the handler: a name is trimmed
+ * and re-checked, and a response body is measured in bytes (`HOOKS_LIMITS.maxResponseBodyBytes`). The
+ * `max` on `body` here is in characters, which is only a cheap first bound.
+ */
+import { z } from 'zod';
+/** §3.5's validation limits and page sizes, shared so the desktop never sends what the server refuses. */
+export declare const HOOKS_LIMITS: {
+    /** A catch URL's name, after trimming. */
+    readonly maxNameLength: 100;
+    readonly maxContentTypeLength: 255;
+    /** A configured response body, in UTF-8 bytes. */
+    readonly maxResponseBodyBytes: 65536;
+    /** The configured delay before the answer; no database connection is held meanwhile (§5). */
+    readonly maxDelayMs: 30000;
+    readonly defaultPageSize: 50;
+    readonly maxPageSize: 200;
+};
+/** The public route's prefix on the server's origin: `<publicUrl>/hooks/<secret>[/<subpath>]`. */
+export declare const CATCH_URL_PATH_PREFIX = "/hooks/";
+/**
+ * 128 random bits in Crockford base32: 26 upper-case characters. A minted secret starts 0–7; the
+ * pattern does not insist, since Crockford base32 also allows 8–9 as a leading digit for the last two
+ * bits of a full 130-bit range and this pattern only bounds the character set and length.
+ */
+export declare const CATCH_SECRET_PATTERN: RegExp;
+/**
+ * A configured `Content-Type`: printable ASCII only. A CR or LF would let a stored value split the
+ * public route's response header, and Node would throw at send time rather than answer.
+ */
+export declare const CATCH_CONTENT_TYPE_PATTERN: RegExp;
+/** What `/meta` reports (§3.7): whether the Webhooks node shows, and the limits that explain truncation and retention. */
+export declare const hooksMetaSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    bodyLimitBytes: z.ZodNumber;
+    keep: z.ZodNumber;
+    maxAgeDays: z.ZodNumber;
+}, z.core.$strip>;
+export type HooksMeta = z.infer<typeof hooksMetaSchema>;
+/** The one fixed answer a catch URL gives every sender (§3.3 step 6). */
+export declare const catchUrlResponseSchema: z.ZodObject<{
+    status: z.ZodNumber;
+    contentType: z.ZodNullable<z.ZodString>;
+    body: z.ZodNullable<z.ZodString>;
+    delayMs: z.ZodNumber;
+}, z.core.$strip>;
+export type CatchUrlResponse = z.infer<typeof catchUrlResponseSchema>;
+/** What a new catch URL answers until an editor changes it: the database's column defaults. */
+export declare const CATCH_URL_DEFAULT_RESPONSE: CatchUrlResponse;
+/** A catch URL's signature secret, in characters (webhook-signatures §3.4). */
+export declare const SIGNATURE_SECRET_MAX_LENGTH = 512;
+/** What a read shows of a catch URL's signature: the scheme, and only that a secret is set (§3.4). */
+export declare const catchUrlSignatureSchema: z.ZodObject<{
+    scheme: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"hmac">;
+        algorithm: z.ZodEnum<{
+            sha256: "sha256";
+            sha1: "sha1";
+            sha512: "sha512";
+        }>;
+        encoding: z.ZodEnum<{
+            base64: "base64";
+            hex: "hex";
+        }>;
+        header: z.ZodString;
+        prefix: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"timestamped">;
+        header: z.ZodString;
+        toleranceSec: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"standard">;
+        toleranceSec: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>], "kind">;
+    secret: z.ZodObject<{
+        set: z.ZodLiteral<true>;
+        hint: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type CatchUrlSignature = z.infer<typeof catchUrlSignatureSchema>;
+/** A capture's verdict, fixed on receipt (§3.3); `null` on the capture means not checked. */
+export declare const captureSignatureSchema: z.ZodObject<{
+    verdict: z.ZodEnum<{
+        verified: "verified";
+        failed: "failed";
+    }>;
+    reason: z.ZodOptional<z.ZodEnum<{
+        "missing-header": "missing-header";
+        "malformed-header": "malformed-header";
+        mismatch: "mismatch";
+        "stale-timestamp": "stale-timestamp";
+        "key-error": "key-error";
+    }>>;
+}, z.core.$strip>;
+export type CaptureSignature = z.infer<typeof captureSignatureSchema>;
+export declare const catchUrlSchema: z.ZodObject<{
+    id: z.ZodString;
+    workspaceId: z.ZodString;
+    name: z.ZodString;
+    url: z.ZodString;
+    enabled: z.ZodBoolean;
+    response: z.ZodObject<{
+        status: z.ZodNumber;
+        contentType: z.ZodNullable<z.ZodString>;
+        body: z.ZodNullable<z.ZodString>;
+        delayMs: z.ZodNumber;
+    }, z.core.$strip>;
+    captureCount: z.ZodNumber;
+    newestCaptureId: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    signature: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        scheme: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"hmac">;
+            algorithm: z.ZodEnum<{
+                sha256: "sha256";
+                sha1: "sha1";
+                sha512: "sha512";
+            }>;
+            encoding: z.ZodEnum<{
+                base64: "base64";
+                hex: "hex";
+            }>;
+            header: z.ZodString;
+            prefix: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"timestamped">;
+            header: z.ZodString;
+            toleranceSec: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"standard">;
+            toleranceSec: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>], "kind">;
+        secret: z.ZodObject<{
+            set: z.ZodLiteral<true>;
+            hint: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>>;
+    rejectUnverified: z.ZodOptional<z.ZodBoolean>;
+    signatureAvailable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type CatchUrl = z.infer<typeof catchUrlSchema>;
+export declare const catchUrlsResponseSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    workspaceId: z.ZodString;
+    name: z.ZodString;
+    url: z.ZodString;
+    enabled: z.ZodBoolean;
+    response: z.ZodObject<{
+        status: z.ZodNumber;
+        contentType: z.ZodNullable<z.ZodString>;
+        body: z.ZodNullable<z.ZodString>;
+        delayMs: z.ZodNumber;
+    }, z.core.$strip>;
+    captureCount: z.ZodNumber;
+    newestCaptureId: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    signature: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        scheme: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"hmac">;
+            algorithm: z.ZodEnum<{
+                sha256: "sha256";
+                sha1: "sha1";
+                sha512: "sha512";
+            }>;
+            encoding: z.ZodEnum<{
+                base64: "base64";
+                hex: "hex";
+            }>;
+            header: z.ZodString;
+            prefix: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"timestamped">;
+            header: z.ZodString;
+            toleranceSec: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"standard">;
+            toleranceSec: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>], "kind">;
+        secret: z.ZodObject<{
+            set: z.ZodLiteral<true>;
+            hint: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>>;
+    rejectUnverified: z.ZodOptional<z.ZodBoolean>;
+    signatureAvailable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>>;
+export declare const catchUrlCreateRequestSchema: z.ZodObject<{
+    name: z.ZodString;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    response: z.ZodOptional<z.ZodObject<{
+        status: z.ZodOptional<z.ZodNumber>;
+        contentType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        body: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        delayMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type CatchUrlCreateRequest = z.infer<typeof catchUrlCreateRequestSchema>;
+/** Every field optional; `response.contentType` or `response.body` set to `null` clears it. */
+export declare const catchUrlUpdateRequestSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    response: z.ZodOptional<z.ZodObject<{
+        status: z.ZodOptional<z.ZodNumber>;
+        contentType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        body: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        delayMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    signature: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        scheme: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"hmac">;
+            algorithm: z.ZodEnum<{
+                sha256: "sha256";
+                sha1: "sha1";
+                sha512: "sha512";
+            }>;
+            encoding: z.ZodEnum<{
+                base64: "base64";
+                hex: "hex";
+            }>;
+            header: z.ZodString;
+            prefix: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"timestamped">;
+            header: z.ZodString;
+            toleranceSec: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"standard">;
+            toleranceSec: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>], "kind">;
+        secret: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    rejectUnverified: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type CatchUrlUpdateRequest = z.infer<typeof catchUrlUpdateRequestSchema>;
+export declare const catchUrlParamsSchema: z.ZodObject<{
+    workspaceId: z.ZodString;
+    hookId: z.ZodString;
+}, z.core.$strip>;
+export declare const captureParamsSchema: z.ZodObject<{
+    workspaceId: z.ZodString;
+    hookId: z.ZodString;
+    captureId: z.ZodString;
+}, z.core.$strip>;
+/**
+ * `GET …/captures?before=&after=&limit=`. Fastify's Ajv coerces the querystring, so the handler reads a
+ * number. `before` pages back from an id; `after` returns the `limit` captures right after an id (the
+ * gap fill, §4.1). Both at once is refused by the handler (`hooks-cursor-conflict`).
+ */
+export declare const capturesQuerySchema: z.ZodObject<{
+    before: z.ZodOptional<z.ZodString>;
+    after: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type CapturesQuery = z.infer<typeof capturesQuerySchema>;
+export declare const captureSummarySchema: z.ZodObject<{
+    id: z.ZodString;
+    receivedAt: z.ZodString;
+    method: z.ZodString;
+    subpath: z.ZodString;
+    bodySize: z.ZodNumber;
+    truncated: z.ZodBoolean;
+    sourceIp: z.ZodString;
+    signature: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        verdict: z.ZodEnum<{
+            verified: "verified";
+            failed: "failed";
+        }>;
+        reason: z.ZodOptional<z.ZodEnum<{
+            "missing-header": "missing-header";
+            "malformed-header": "malformed-header";
+            mismatch: "mismatch";
+            "stale-timestamp": "stale-timestamp";
+            "key-error": "key-error";
+        }>>;
+    }, z.core.$strip>>>;
+    rejected: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type CaptureSummary = z.infer<typeof captureSummarySchema>;
+/** Newest first. */
+export declare const capturesResponseSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    receivedAt: z.ZodString;
+    method: z.ZodString;
+    subpath: z.ZodString;
+    bodySize: z.ZodNumber;
+    truncated: z.ZodBoolean;
+    sourceIp: z.ZodString;
+    signature: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        verdict: z.ZodEnum<{
+            verified: "verified";
+            failed: "failed";
+        }>;
+        reason: z.ZodOptional<z.ZodEnum<{
+            "missing-header": "missing-header";
+            "malformed-header": "malformed-header";
+            mismatch: "mismatch";
+            "stale-timestamp": "stale-timestamp";
+            "key-error": "key-error";
+        }>>;
+    }, z.core.$strip>>>;
+    rejected: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>>;
+export declare const captureSchema: z.ZodObject<{
+    id: z.ZodString;
+    receivedAt: z.ZodString;
+    method: z.ZodString;
+    subpath: z.ZodString;
+    bodySize: z.ZodNumber;
+    truncated: z.ZodBoolean;
+    sourceIp: z.ZodString;
+    signature: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        verdict: z.ZodEnum<{
+            verified: "verified";
+            failed: "failed";
+        }>;
+        reason: z.ZodOptional<z.ZodEnum<{
+            "missing-header": "missing-header";
+            "malformed-header": "malformed-header";
+            mismatch: "mismatch";
+            "stale-timestamp": "stale-timestamp";
+            "key-error": "key-error";
+        }>>;
+    }, z.core.$strip>>>;
+    rejected: z.ZodOptional<z.ZodBoolean>;
+    query: z.ZodString;
+    headers: z.ZodArray<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
+    body: z.ZodString;
+}, z.core.$strip>;
+export type Capture = z.infer<typeof captureSchema>;

package/dist/server-api/hooks.js

@@ -0,0 +1,152 @@
+/**
+ * The webhook-capture module's wire shapes (webhook-capture spec §3.5, §3.7). The server's routes
+ * validate with them through `jsonSchema()` and the desktop's main process parses answers with them,
+ * so a drift between the two fails typecheck. Plain zod only (ADR-0009).
+ *
+ * A catch URL is owned by a workspace. Its secret is the only credential on the public route, so it
+ * appears only inside `url`, which only workspace viewers and up can read (§5). The renderer never
+ * imports a value from here: main parses, and the renderer takes the inferred types.
+ *
+ * JSON Schema cannot count UTF-8 bytes or trim, so two checks stay in the handler: a name is trimmed
+ * and re-checked, and a response body is measured in bytes (`HOOKS_LIMITS.maxResponseBodyBytes`). The
+ * `max` on `body` here is in characters, which is only a cheap first bound.
+ */
+import { z } from 'zod';
+import { SIGNATURE_FAILURES, signatureSchemeSchema } from '../http/webhook-signature.js';
+import { teamsIdSchema } from './teams.js';
+/** §3.5's validation limits and page sizes, shared so the desktop never sends what the server refuses. */
+export const HOOKS_LIMITS = {
+    /** A catch URL's name, after trimming. */
+    maxNameLength: 100,
+    maxContentTypeLength: 255,
+    /** A configured response body, in UTF-8 bytes. */
+    maxResponseBodyBytes: 65_536,
+    /** The configured delay before the answer; no database connection is held meanwhile (§5). */
+    maxDelayMs: 30_000,
+    defaultPageSize: 50,
+    maxPageSize: 200,
+};
+/** The public route's prefix on the server's origin: `<publicUrl>/hooks/<secret>[/<subpath>]`. */
+export const CATCH_URL_PATH_PREFIX = '/hooks/';
+/**
+ * 128 random bits in Crockford base32: 26 upper-case characters. A minted secret starts 0–7; the
+ * pattern does not insist, since Crockford base32 also allows 8–9 as a leading digit for the last two
+ * bits of a full 130-bit range and this pattern only bounds the character set and length.
+ */
+export const CATCH_SECRET_PATTERN = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+/**
+ * A configured `Content-Type`: printable ASCII only. A CR or LF would let a stored value split the
+ * public route's response header, and Node would throw at send time rather than answer.
+ */
+export const CATCH_CONTENT_TYPE_PATTERN = /^[\x20-\x7e]+$/;
+/** What `/meta` reports (§3.7): whether the Webhooks node shows, and the limits that explain truncation and retention. */
+export const hooksMetaSchema = z.object({
+    enabled: z.boolean(),
+    bodyLimitBytes: z.number().int().positive(),
+    keep: z.number().int().positive(),
+    maxAgeDays: z.number().int().positive(),
+});
+/** The one fixed answer a catch URL gives every sender (§3.3 step 6). */
+export const catchUrlResponseSchema = z.object({
+    status: z.number().int().min(200).max(599),
+    contentType: z.string().max(HOOKS_LIMITS.maxContentTypeLength).regex(CATCH_CONTENT_TYPE_PATTERN).nullable(),
+    body: z.string().max(HOOKS_LIMITS.maxResponseBodyBytes).nullable(),
+    delayMs: z.number().int().min(0).max(HOOKS_LIMITS.maxDelayMs),
+});
+/** What a new catch URL answers until an editor changes it: the database's column defaults. */
+export const CATCH_URL_DEFAULT_RESPONSE = Object.freeze({
+    status: 200,
+    contentType: null,
+    body: null,
+    delayMs: 0,
+});
+/** A catch URL's signature secret, in characters (webhook-signatures §3.4). */
+export const SIGNATURE_SECRET_MAX_LENGTH = 512;
+/** What a read shows of a catch URL's signature: the scheme, and only that a secret is set (§3.4). */
+export const catchUrlSignatureSchema = z.object({
+    scheme: signatureSchemeSchema,
+    /** Write-only: never the secret, only that one is set and, to editors, its last four characters. */
+    secret: z.object({ set: z.literal(true), hint: z.string().nullable() }),
+});
+/** A capture's verdict, fixed on receipt (§3.3); `null` on the capture means not checked. */
+export const captureSignatureSchema = z.object({
+    verdict: z.enum(['verified', 'failed']),
+    reason: z.enum(SIGNATURE_FAILURES).optional(),
+});
+const nameSchema = z.string().min(1).max(HOOKS_LIMITS.maxNameLength);
+export const catchUrlSchema = z.object({
+    id: teamsIdSchema,
+    workspaceId: teamsIdSchema,
+    name: z.string(),
+    /** `publicUrl` + `/hooks/` + the secret. Rotating replaces it. */
+    url: z.string(),
+    enabled: z.boolean(),
+    response: catchUrlResponseSchema,
+    captureCount: z.number().int().min(0),
+    /** The newest capture's id, `null` with none: the desktop's unseen badge compares it with the last one seen. */
+    newestCaptureId: teamsIdSchema.nullable(),
+    createdAt: z.string(),
+    /** webhook-signatures §3.4; absent from an older server. */
+    signature: catchUrlSignatureSchema.nullable().optional(),
+    rejectUnverified: z.boolean().optional(),
+    /** `false` while `WIREBENCH_SERVER_HOOKS_SECRET_KEY` is unset, so the desktop can explain why. */
+    signatureAvailable: z.boolean().optional(),
+});
+export const catchUrlsResponseSchema = z.array(catchUrlSchema);
+export const catchUrlCreateRequestSchema = z.object({
+    name: nameSchema,
+    enabled: z.boolean().optional(),
+    response: catchUrlResponseSchema.partial().optional(),
+});
+/** Every field optional; `response.contentType` or `response.body` set to `null` clears it. */
+export const catchUrlUpdateRequestSchema = z.object({
+    name: nameSchema.optional(),
+    enabled: z.boolean().optional(),
+    response: catchUrlResponseSchema.partial().optional(),
+    /** `null` clears; a scheme without `secret` keeps the stored one (§3.4). */
+    signature: z
+        .object({ scheme: signatureSchemeSchema, secret: z.string().min(1).max(SIGNATURE_SECRET_MAX_LENGTH).optional() })
+        .nullable()
+        .optional(),
+    rejectUnverified: z.boolean().optional(),
+});
+export const catchUrlParamsSchema = z.object({ workspaceId: teamsIdSchema, hookId: teamsIdSchema });
+export const captureParamsSchema = z.object({
+    workspaceId: teamsIdSchema,
+    hookId: teamsIdSchema,
+    captureId: teamsIdSchema,
+});
+/**
+ * `GET …/captures?before=&after=&limit=`. Fastify's Ajv coerces the querystring, so the handler reads a
+ * number. `before` pages back from an id; `after` returns the `limit` captures right after an id (the
+ * gap fill, §4.1). Both at once is refused by the handler (`hooks-cursor-conflict`).
+ */
+export const capturesQuerySchema = z.object({
+    before: teamsIdSchema.optional(),
+    after: teamsIdSchema.optional(),
+    limit: z.number().int().min(1).max(HOOKS_LIMITS.maxPageSize).optional(),
+});
+export const captureSummarySchema = z.object({
+    /** A ULID: captures sort by arrival. */
+    id: teamsIdSchema,
+    receivedAt: z.string(),
+    method: z.string(),
+    /** What followed `/hooks/<secret>`: `''` or `/…`, still percent-encoded as it arrived. */
+    subpath: z.string(),
+    /** The size that arrived, before truncation. */
+    bodySize: z.number().int().min(0),
+    truncated: z.boolean(),
+    sourceIp: z.string(),
+    signature: captureSignatureSchema.nullable().optional(),
+    rejected: z.boolean().optional(),
+});
+/** Newest first. */
+export const capturesResponseSchema = z.array(captureSummarySchema);
+export const captureSchema = captureSummarySchema.extend({
+    /** The raw query string, without `?`. */
+    query: z.string(),
+    /** `[name, value]` pairs in arrival order, repeats kept, names as the sender spelled them. */
+    headers: z.array(z.tuple([z.string(), z.string()])),
+    /** The stored bytes (at most the server's body limit), base64. */
+    body: z.string(),
+});