@greatwait/contracts 0.1.0-alpha.1

package/dist/delivery.js

@@ -0,0 +1,311 @@
+/**
+ * Versioned associated-data contract for encrypted schedule payloads.
+ *
+ * The value is persisted beside the envelope by the portable scheduling
+ * record contract. Changing it requires an explicit reader for the old value;
+ * silently trying another value would turn an authentication failure into a
+ * decryption oracle.
+ */
+export const SCHEDULE_PAYLOAD_AAD_VERSION = "greatwait.schedule-payload.v1";
+/**
+ * What a receiver says about work it acknowledged and then finished.
+ *
+ * Here rather than beside the envelope schema because the scheduler Worker's
+ * completion route reads it and that bundle deliberately carries no Zod — this
+ * module is the Zod-free subpath. `signatures.ts` builds its enum from this
+ * list, so the vocabulary exists once.
+ *
+ * `succeeded` is what an empty body means: the overwhelmingly common report is
+ * "done", and a receiver should not have to compose a document to say it.
+ * `failed` puts the occurrence back on the ordinary retry ladder — the same
+ * place a 500 puts it — so a receiver can distinguish "my job died" from "I
+ * vanished".
+ */
+export const CALLBACK_COMPLETION_OUTCOMES = ["succeeded", "failed"];
+/**
+ * The one status that can mean "I have the work and I am not finished".
+ *
+ * Exactly `202`, and the narrowness is the point. Every other 2xx keeps the
+ * meaning it has had since the first delivery this product sent — success,
+ * now — so a receiver that has never heard of deferral cannot be parked by
+ * accident. A `200` carrying the marker is success, and so is a `204`, because
+ * the discriminator is not the whole rule: the status and the body have to
+ * agree, and only this pair opts in.
+ */
+export const CALLBACK_DEFERRAL_STATUS = 202;
+/**
+ * How much of an acknowledgement body is read before the answer is decided.
+ *
+ * One kibibyte. An acknowledgement is a fixed object of two or three short
+ * members, so the bound is roughly twenty times what a legitimate one needs
+ * and is not a limit a receiver can meet by accident. What it stops is a
+ * receiver — or something in front of one — answering `202` with a body that
+ * is expensive to read: the delivery path reads this many bytes, decides, and
+ * cancels the rest of the stream without buffering it.
+ *
+ * **Exceeding it is not pending.** A body over the bound cannot be shown to
+ * carry the discriminator, and the safe reading of "cannot be shown" is the
+ * one that settles the attempt now rather than the one that parks a customer's
+ * occurrence on a receiver whose answer we did not finish reading.
+ */
+export const CALLBACK_ACKNOWLEDGEMENT_MAX_BYTES = 1_024;
+/**
+ * The media types an acknowledgement may be carried in.
+ *
+ * JSON, in the two spellings a receiver actually sends. A `202` whose body is
+ * HTML or plain text is an ordinary success, because whatever it says it is
+ * not this protocol.
+ */
+export const CALLBACK_ACKNOWLEDGEMENT_CONTENT_TYPES = [
+    "application/json",
+    "application/problem+json",
+];
+/**
+ * What a receiver answers with to keep the work and report later.
+ *
+ * ```json
+ * { "greatwait": { "status": "pending", "completeBy": "2026-08-23T18:00:00Z" } }
+ * ```
+ *
+ * **Namespaced under one key on purpose.** A receiver's `202` body is its own
+ * document — a job id, a queue position, a status URL — and a bare
+ * `{"status":"pending"}` would collide with the most ordinary word in that
+ * vocabulary. Nesting it means an existing receiver has to have chosen the key
+ * `greatwait` for something else before this can misfire.
+ */
+export const CALLBACK_PENDING_DISCRIMINATOR = {
+    key: "greatwait",
+    status: "pending",
+};
+const NOT_PENDING = { pending: false };
+/**
+ * RFC 3339 with an explicit offset, fractional seconds optional.
+ *
+ * **Deliberately wider than `timestampSchema` and deliberately narrower than
+ * `Date.parse`.** This value crosses in from a receiver rather than out from
+ * this service, so demanding the product's own millisecond-and-`Z` spelling
+ * would silently discard a correct instant written the ordinary way. What is
+ * still refused is anything whose meaning depends on where it is read: a bare
+ * date, a local wall clock with no offset, an epoch number, and every other
+ * shape `Date.parse` is willing to guess at.
+ */
+const RFC3339_INSTANT = /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:[Zz]|[+-]\d{2}:\d{2})$/u;
+function readCompleteBy(value) {
+    if (typeof value !== "string" || !RFC3339_INSTANT.test(value)) {
+        return undefined;
+    }
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function isAcknowledgementContentType(value) {
+    if (value === null)
+        return false;
+    // Parameters are the receiver's business; `application/json; charset=utf-8`
+    // is the same media type as `application/json`.
+    const media = value.split(";")[0]?.trim().toLowerCase() ?? "";
+    return CALLBACK_ACKNOWLEDGEMENT_CONTENT_TYPES.includes(media);
+}
+/**
+ * Decide whether one receiver answer is the deferral acknowledgement.
+ *
+ * Every term is required and each one is refused on its own: the status is
+ * exactly {@link CALLBACK_DEFERRAL_STATUS}, the media type is JSON, the body
+ * fits {@link CALLBACK_ACKNOWLEDGEMENT_MAX_BYTES}, it parses, it is a JSON
+ * object rather than an array or a scalar, and it carries the discriminator.
+ * Anything that fails one of them is not pending, which for a 2xx means
+ * ordinary immediate success.
+ *
+ * **It never decides a non-2xx.** The caller classifies the response first and
+ * only asks this about a success; a `500` carrying a perfectly formed pending
+ * marker is a `500`, because a receiver that is failing does not get to park
+ * the occurrence it is failing to handle.
+ *
+ * **There is no `Array.isArray` guard, and there was one.** Mutation testing
+ * showed both — over the parsed body and over the marker — surviving deletion
+ * with every case green, and the reason is that they cannot decide anything: a
+ * JSON array has no named members, so reading the discriminator key off one is
+ * `undefined` and the very next check refuses it. A rule no input can reach
+ * reads like protection and is not, so it is gone and this paragraph is what
+ * it left behind. The array cases in the suite stay — they pin the outcome a
+ * receiver sees, which is unchanged — but they hold by construction rather
+ * than by a guard.
+ */
+export function readCallbackAcknowledgement(response) {
+    if (response.status !== CALLBACK_DEFERRAL_STATUS)
+        return NOT_PENDING;
+    if (response.truncated)
+        return NOT_PENDING;
+    if (!isAcknowledgementContentType(response.contentType))
+        return NOT_PENDING;
+    let parsed;
+    try {
+        parsed = JSON.parse(response.body);
+    }
+    catch {
+        return NOT_PENDING;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return NOT_PENDING;
+    const marker = parsed[CALLBACK_PENDING_DISCRIMINATOR.key];
+    if (typeof marker !== "object" || marker === null)
+        return NOT_PENDING;
+    const fields = marker;
+    if (fields["status"] !== CALLBACK_PENDING_DISCRIMINATOR.status) {
+        return NOT_PENDING;
+    }
+    const completeByMs = readCompleteBy(fields["completeBy"]);
+    return completeByMs === undefined
+        ? { pending: true }
+        : { completeByMs, pending: true };
+}
+/**
+ * The deadline this deferral actually gets, in epoch milliseconds.
+ *
+ * The receiver may bring it forward and may not push it out. `maximumMs` is
+ * the deadline already inside the signed envelope — the schedule's own
+ * duration allowance measured from the attempt — so a receiver asking for
+ * longer is asking to change what its customer bought, and a receiver asking
+ * for an instant that has already passed is asking for something no wait can
+ * satisfy.
+ *
+ * **All three refusals fall back to the maximum rather than to immediate
+ * success.** The acknowledgement itself is what took the work; a malformed
+ * hint about *when* does not unmake that, and settling such an attempt
+ * `succeeded` would record a result the receiver never reported.
+ */
+export function effectiveCompletionDeadlineMs(requestedMs, maximumMs, nowMs) {
+    if (requestedMs === undefined || !Number.isFinite(requestedMs)) {
+        return maximumMs;
+    }
+    if (requestedMs <= nowMs)
+        return maximumMs;
+    return Math.min(requestedMs, maximumMs);
+}
+/** Safe, bounded diagnostics. Never contains a URL, payload, or secret. */
+/**
+ * Safe delivery diagnostics shared by the executor result and the public
+ * attempt timeline.
+ *
+ * Values are deliberately short categories. A URL, response body, payload,
+ * exception message, signing key, or transport trace has no representation in
+ * this vocabulary, so the durable history cannot accidentally turn private
+ * callback material into a public diagnostic.
+ */
+export const CALLBACK_ATTEMPT_DIAGNOSTICS = [
+    "completion_timed_out",
+    "delivered",
+    "duplicate_inflight",
+    "endpoint_unavailable",
+    "endpoint_unsafe",
+    "http_refused",
+    "http_retryable",
+    "http_terminal",
+    "identity_conflict",
+    "network_ambiguous",
+    "payload_unavailable",
+    "rate_limited",
+];
+/**
+ * Statuses where the receiver is refusing *this delivery, right now* rather
+ * than objecting to the message it carries.
+ *
+ * **The line is whether resending the identical bytes could ever get a
+ * different answer.** Every callback attempt re-sends the same signed envelope,
+ * so a receiver that rejects the message itself — malformed, too large, wrong
+ * media type, gone, refused for legal reasons — will reject it identically for
+ * as long as the occurrence lives, and retrying is pure cost on the population
+ * least likely to recover. A receiver that refuses *us* has a cause someone
+ * fixes: an expired or rotated credential, a WAF rule that started matching, a
+ * deploy window where the route is briefly absent.
+ *
+ * | Status | Why it is here |
+ * | ------ | -------------- |
+ * | 401    | credential expired, rotated, or not yet deployed |
+ * | 402    | receiver's own service suspended, restored on payment |
+ * | 403    | WAF or bot rule, revoked permission, IP block |
+ * | 404    | route absent during a deploy or a partial rollout |
+ * | 405    | method absent during a deploy or a partial rollout |
+ * | 407    | an egress proxy in front of the receiver wants credentials |
+ * | 421    | misdirected during a routing or certificate change |
+ * | 423    | the target resource is temporarily locked |
+ * | 424    | the receiver's own dependency failed |
+ * | 425    | the receiver asked us not to risk a replay yet — literally "retry later" |
+ *
+ * **409 is deliberately not here**, though it is a refusal in the plain
+ * reading. From a callback receiver a conflict overwhelmingly means "I already
+ * have this delivery", which the identical retry cannot resolve and which is
+ * the receiver's idempotency working rather than failing.
+ *
+ * **An unrecognised 4xx is not here either.** RFC 7231 says an unknown 4xx must
+ * be treated as a 400, so the default is terminal and this list is the whole of
+ * the exception. Adding to it is a product decision, not a lookup.
+ */
+export const CALLBACK_REFUSAL_STATUSES = [
+    401, 402, 403, 404, 405, 407, 421, 423, 424, 425,
+];
+/** Whether a receiver refused this delivery in a way that may recover. */
+export function isCallbackRefusalStatus(status) {
+    return CALLBACK_REFUSAL_STATUSES.includes(status);
+}
+/**
+ * Response headers worth keeping, in the order one is chosen.
+ *
+ * **A closed list, and short on purpose.** A response header is receiver-
+ * controlled text that lands in durable history and on a support screen, so
+ * the question is not "is this one dangerous" but "does this one earn its
+ * place". Content type explains what the snippet is, `Retry-After` explains a
+ * pacing decision the customer can see, and one receiver-side identifier is
+ * what turns "your receiver refused this" into something an integrator can
+ * look up in their own logs.
+ *
+ * Everything else is absent by construction rather than by filtering: cookies,
+ * `Authorization`, `WWW-Authenticate`, `Set-Cookie` and every vendor header
+ * have no entry here, so no future edit can retain one by forgetting to add a
+ * denial.
+ */
+export const CALLBACK_RESPONSE_HEADER_ALLOWLIST = [
+    "content-type",
+    "retry-after",
+];
+/**
+ * Receiver-side identifiers, most specific first. **At most one is kept.**
+ *
+ * The order is which name a receiver most likely means as "look this up in my
+ * logs". Keeping several would be keeping a header set rather than an
+ * identifier, which is the thing the allowlist above exists to refuse.
+ */
+export const CALLBACK_RESPONSE_REQUEST_ID_HEADERS = [
+    "x-request-id",
+    "request-id",
+    "x-correlation-id",
+    "x-amzn-requestid",
+    "cf-ray",
+];
+/** How much of any retained header value is kept, in bytes. */
+export const CALLBACK_RESPONSE_HEADER_MAX_BYTES = 256;
+/**
+ * How much of a failed response body may be retained, in bytes.
+ *
+ * Four kibibytes of the *start* of the body, read as a bounded prefix and with
+ * the rest of the stream cancelled rather than buffered. It is enough for a
+ * stack trace's first frames or a validation error list, which is what makes a
+ * failing receiver diagnosable without turning this product into a log store.
+ */
+export const CALLBACK_FAILURE_SNIPPET_MAX_BYTES = 4_096;
+/**
+ * Media types whose body may be retained as a failure snippet.
+ *
+ * Text and JSON only. A binary body has nothing a person reads in its first
+ * four kibibytes, and retaining one would mean storing an arbitrary fragment
+ * of an arbitrary file because a receiver set a header.
+ */
+export const CALLBACK_FAILURE_SNIPPET_CONTENT_TYPES = [
+    "application/json",
+    "application/problem+json",
+    "application/xml",
+    "text/",
+];
+/** Whether one network attempt asked to finish later. */
+export function isDeferredAttempt(outcome) {
+    return "deferred" in outcome;
+}

package/dist/endpoints.d.ts

@@ -0,0 +1,305 @@
+import { z } from "zod";
+/**
+ * Reusable callback endpoints.
+ *
+ * The URL belongs to one verified authority tuple for its whole life. The
+ * public resource deliberately has no organization or environment identifier
+ * a caller can use to widen that tuple: `project` and `environmentKind` are
+ * display metadata, while every lookup is scoped by the verified principal.
+ */
+export declare const CALLBACK_ENDPOINT_STATUSES: readonly ["pending", "verified", "disabled"];
+export declare const callbackEndpointStatusSchema: z.ZodEnum<{
+    verified: "verified";
+    pending: "pending";
+    disabled: "disabled";
+}>;
+export type CallbackEndpointStatus = z.infer<typeof callbackEndpointStatusSchema>;
+export declare const CALLBACK_VERIFICATION_FAILURES: readonly ["address_forbidden", "challenge_failed", "connection_failed", "dns_unresolved", "rate_limited", "redirect_refused", "response_too_large", "timed_out", "unexpected_status"];
+export declare const callbackVerificationFailureSchema: z.ZodEnum<{
+    rate_limited: "rate_limited";
+    address_forbidden: "address_forbidden";
+    challenge_failed: "challenge_failed";
+    connection_failed: "connection_failed";
+    dns_unresolved: "dns_unresolved";
+    redirect_refused: "redirect_refused";
+    response_too_large: "response_too_large";
+    timed_out: "timed_out";
+    unexpected_status: "unexpected_status";
+}>;
+export type CallbackVerificationFailure = z.infer<typeof callbackVerificationFailureSchema>;
+/**
+ * A safety ceiling on retained endpoint records, independent of later
+ * commercial plan limits. Disabled records remain readable for audit and count
+ * toward it; changing that lifetime semantic needs a product decision.
+ */
+export declare const CALLBACK_ENDPOINT_LIMIT_PER_ENVIRONMENT = 50;
+/** Verification egress is admitted through both buckets before DNS or fetch. */
+export declare const CALLBACK_VERIFICATION_RATE_LIMITS: {
+    readonly destinationPerMinute: 5;
+    readonly projectPerMinute: 20;
+    readonly windowSeconds: 60;
+};
+/** Total bytes a verification response may return before it is refused. */
+export declare const CALLBACK_VERIFICATION_RESPONSE_BYTES = 1024;
+/** Total DNS + connect + response bound for one verification attempt. */
+export declare const CALLBACK_VERIFICATION_TIMEOUT_MILLISECONDS = 5000;
+/** Longest period during which a receiver may accept current and next keys. */
+export declare const CALLBACK_SIGNING_KEY_ROTATION_OVERLAP_SECONDS = 86400;
+export declare const callbackSigningKeysSchema: z.ZodObject<{
+    current: z.ZodString;
+    next: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        overlapEndsAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type CallbackSigningKeys = z.infer<typeof callbackSigningKeysSchema>;
+/**
+ * A metadata-only endpoint shape. The sealed signing secret has no public
+ * field, so list/get/update/verify/disable cannot accidentally recover it.
+ */
+export declare const callbackEndpointSchema: z.ZodObject<{
+    createdAt: z.ZodString;
+    disabledAt: z.ZodOptional<z.ZodString>;
+    environmentKind: z.ZodEnum<{
+        test: "test";
+        live: "live";
+    }>;
+    id: z.ZodString;
+    lastVerificationAttemptAt: z.ZodOptional<z.ZodString>;
+    lastVerificationFailure: z.ZodOptional<z.ZodEnum<{
+        rate_limited: "rate_limited";
+        address_forbidden: "address_forbidden";
+        challenge_failed: "challenge_failed";
+        connection_failed: "connection_failed";
+        dns_unresolved: "dns_unresolved";
+        redirect_refused: "redirect_refused";
+        response_too_large: "response_too_large";
+        timed_out: "timed_out";
+        unexpected_status: "unexpected_status";
+    }>>;
+    project: z.ZodString;
+    signingKeys: z.ZodObject<{
+        current: z.ZodString;
+        next: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            overlapEndsAt: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    status: z.ZodEnum<{
+        verified: "verified";
+        pending: "pending";
+        disabled: "disabled";
+    }>;
+    updatedAt: z.ZodString;
+    url: z.ZodString;
+    verifiedAt: z.ZodOptional<z.ZodString>;
+    version: z.ZodNumber;
+}, z.core.$strip>;
+export type CallbackEndpoint = z.infer<typeof callbackEndpointSchema>;
+export declare const callbackEndpointPageSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        createdAt: z.ZodString;
+        disabledAt: z.ZodOptional<z.ZodString>;
+        environmentKind: z.ZodEnum<{
+            test: "test";
+            live: "live";
+        }>;
+        id: z.ZodString;
+        lastVerificationAttemptAt: z.ZodOptional<z.ZodString>;
+        lastVerificationFailure: z.ZodOptional<z.ZodEnum<{
+            rate_limited: "rate_limited";
+            address_forbidden: "address_forbidden";
+            challenge_failed: "challenge_failed";
+            connection_failed: "connection_failed";
+            dns_unresolved: "dns_unresolved";
+            redirect_refused: "redirect_refused";
+            response_too_large: "response_too_large";
+            timed_out: "timed_out";
+            unexpected_status: "unexpected_status";
+        }>>;
+        project: z.ZodString;
+        signingKeys: z.ZodObject<{
+            current: z.ZodString;
+            next: z.ZodOptional<z.ZodObject<{
+                id: z.ZodString;
+                overlapEndsAt: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        status: z.ZodEnum<{
+            verified: "verified";
+            pending: "pending";
+            disabled: "disabled";
+        }>;
+        updatedAt: z.ZodString;
+        url: z.ZodString;
+        verifiedAt: z.ZodOptional<z.ZodString>;
+        version: z.ZodNumber;
+    }, z.core.$strip>>;
+    freshness: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"authoritative">;
+    }, z.core.$strip>, z.ZodObject<{
+        asOf: z.ZodString;
+        kind: z.ZodLiteral<"projected">;
+        lagSeconds: z.ZodNumber;
+    }, z.core.$strip>], "kind">;
+    nextCursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CallbackEndpointPage = z.infer<typeof callbackEndpointPageSchema>;
+/** The one response that carries the per-endpoint secret. */
+export declare const callbackEndpointCreatedSchema: z.ZodObject<{
+    createdAt: z.ZodString;
+    disabledAt: z.ZodOptional<z.ZodString>;
+    environmentKind: z.ZodEnum<{
+        test: "test";
+        live: "live";
+    }>;
+    id: z.ZodString;
+    lastVerificationAttemptAt: z.ZodOptional<z.ZodString>;
+    lastVerificationFailure: z.ZodOptional<z.ZodEnum<{
+        rate_limited: "rate_limited";
+        address_forbidden: "address_forbidden";
+        challenge_failed: "challenge_failed";
+        connection_failed: "connection_failed";
+        dns_unresolved: "dns_unresolved";
+        redirect_refused: "redirect_refused";
+        response_too_large: "response_too_large";
+        timed_out: "timed_out";
+        unexpected_status: "unexpected_status";
+    }>>;
+    project: z.ZodString;
+    signingKeys: z.ZodObject<{
+        current: z.ZodString;
+        next: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            overlapEndsAt: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    status: z.ZodEnum<{
+        verified: "verified";
+        pending: "pending";
+        disabled: "disabled";
+    }>;
+    updatedAt: z.ZodString;
+    url: z.ZodString;
+    verifiedAt: z.ZodOptional<z.ZodString>;
+    version: z.ZodNumber;
+    keyId: z.ZodString;
+    secret: z.ZodString;
+    shownOnce: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export type CallbackEndpointCreated = z.infer<typeof callbackEndpointCreatedSchema>;
+export declare const callbackSigningKeyRotationRequestSchema: z.ZodObject<{
+    overlapSeconds: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type CallbackSigningKeyRotationRequest = z.infer<typeof callbackSigningKeyRotationRequestSchema>;
+export declare const callbackEndpointRotatedSchema: z.ZodObject<{
+    endpoint: z.ZodObject<{
+        createdAt: z.ZodString;
+        disabledAt: z.ZodOptional<z.ZodString>;
+        environmentKind: z.ZodEnum<{
+            test: "test";
+            live: "live";
+        }>;
+        id: z.ZodString;
+        lastVerificationAttemptAt: z.ZodOptional<z.ZodString>;
+        lastVerificationFailure: z.ZodOptional<z.ZodEnum<{
+            rate_limited: "rate_limited";
+            address_forbidden: "address_forbidden";
+            challenge_failed: "challenge_failed";
+            connection_failed: "connection_failed";
+            dns_unresolved: "dns_unresolved";
+            redirect_refused: "redirect_refused";
+            response_too_large: "response_too_large";
+            timed_out: "timed_out";
+            unexpected_status: "unexpected_status";
+        }>>;
+        project: z.ZodString;
+        signingKeys: z.ZodObject<{
+            current: z.ZodString;
+            next: z.ZodOptional<z.ZodObject<{
+                id: z.ZodString;
+                overlapEndsAt: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        status: z.ZodEnum<{
+            verified: "verified";
+            pending: "pending";
+            disabled: "disabled";
+        }>;
+        updatedAt: z.ZodString;
+        url: z.ZodString;
+        verifiedAt: z.ZodOptional<z.ZodString>;
+        version: z.ZodNumber;
+    }, z.core.$strip>;
+    keyId: z.ZodString;
+    secret: z.ZodString;
+    shownOnce: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export type CallbackEndpointRotated = z.infer<typeof callbackEndpointRotatedSchema>;
+export declare const callbackEndpointRequestSchema: z.ZodObject<{
+    url: z.ZodString;
+}, z.core.$strip>;
+export type CallbackEndpointRequest = z.infer<typeof callbackEndpointRequestSchema>;
+export declare const CALLBACK_VERIFICATION_PROTOCOL_VERSION = "2026-08-05";
+export declare const CALLBACK_VERIFICATION_TYPE = "callback.endpoint.verification";
+/**
+ * Exact verification bytes sent to the receiver. The receiver validates the
+ * request signature and proves possession of the one-time secret by returning
+ * an HMAC of `challenge` in `Callback-Verification-Response`.
+ */
+export declare const callbackVerificationChallengeSchema: z.ZodObject<{
+    challenge: z.ZodString;
+    endpointId: z.ZodString;
+    type: z.ZodLiteral<"callback.endpoint.verification">;
+    version: z.ZodLiteral<"2026-08-05">;
+}, z.core.$strip>;
+export type CallbackVerificationChallenge = z.infer<typeof callbackVerificationChallengeSchema>;
+export declare const CALLBACK_VERIFICATION_HEADERS: {
+    readonly challenge: "Callback-Verification-Challenge";
+    readonly requestSignature: "Callback-Verification-Signature";
+    readonly responseSignature: "Callback-Verification-Response";
+};
+/**
+ * Machine-readable receiver contract for endpoint ownership verification.
+ *
+ * This is deliberately separate from W3-02's occurrence-delivery signature:
+ * the request proves control of a receiver before the endpoint may be used,
+ * while a delivery signature authenticates an occurrence body later. The
+ * generator publishes this object beside OpenAPI and the JSON Schema.
+ */
+export declare const CALLBACK_VERIFICATION_PROTOCOL: {
+    readonly purpose: "Prove that the receiver possesses the one-time endpoint secret before Greatwait marks the endpoint verified.";
+    readonly request: {
+        readonly bodyEncoding: "UTF-8 bytes of the compact JSON object in schema property order: challenge, endpointId, type, version.";
+        readonly contentType: "application/json";
+        readonly method: "POST";
+        readonly redirectPolicy: "manual; every 3xx response is refused";
+        readonly signature: {
+            readonly algorithm: "HMAC-SHA-256";
+            readonly format: "v1=<64 lowercase hexadecimal characters>";
+            readonly header: "Callback-Verification-Signature";
+            readonly input: "the exact request body bytes";
+            readonly key: "the one-time endpoint secret returned by REST endpoint creation";
+        };
+    };
+    readonly response: {
+        readonly body: "ignored after enforcing the 1024-byte response limit; return an empty body";
+        readonly proof: {
+            readonly algorithm: "HMAC-SHA-256";
+            readonly format: "v1=<64 lowercase hexadecimal characters>";
+            readonly header: "Callback-Verification-Response";
+            readonly input: "the UTF-8 bytes of the challenge string";
+            readonly key: "the same endpoint secret";
+        };
+        readonly status: "any 2xx status";
+    };
+    readonly testVector: {
+        readonly challenge: "cvc_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
+        readonly endpointId: "ep_00000000000000000000000000";
+        readonly exactBodyBase64: "eyJjaGFsbGVuZ2UiOiJjdmNfQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQSIsImVuZHBvaW50SWQiOiJlcF8wMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMCIsInR5cGUiOiJjYWxsYmFjay5lbmRwb2ludC52ZXJpZmljYXRpb24iLCJ2ZXJzaW9uIjoiMjAyNi0wOC0wNSJ9";
+        readonly requestSignature: "v1=0d24c7fed4d752411b88025a9923627b329e0eb9d53978a6ebcf92c0678c731e";
+        readonly responseSignature: "v1=efc690a23f1870930ff3388313162c0e06406902a7a4d3f9273ffe0abcef86bd";
+        readonly secret: "verification-vector-secret";
+    };
+    readonly version: "2026-08-05";
+};