@greatwait/contracts 0.1.0-alpha.3 → 0.1.0-alpha.4

package/dist/endpoints.d.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 /**
  * Reusable callback endpoints.
  *
@@ -7,18 +7,28 @@ import { z } from "zod";
  * 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";
+/**
+ * An endpoint is usable the moment it exists (W4-12). `active` is every
+ * endpoint that is not disabled; `disabled` stops delivery until
+ * `endpoints.enable` turns it back on. There is no state in between and
+ * nothing to prove.
+ */
+export declare const CALLBACK_ENDPOINT_STATUSES: readonly ["active", "disabled"];
+export declare const callbackEndpointStatusSchema: import("zod").ZodEnum<{
     disabled: "disabled";
+    active: "active";
 }>;
 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<{
+/**
+ * Why an address could not be resolved or reached: the classification the
+ * DNS inspection at create and update, and the delivery egress, share. It
+ * was the verification-failure vocabulary until W4-12 removed verification;
+ * what remains is what those two paths can still observe.
+ */
+export declare const CALLBACK_EGRESS_FAILURES: readonly ["address_forbidden", "connection_failed", "dns_unresolved", "rate_limited", "redirect_refused", "response_too_large", "timed_out", "unexpected_status"];
+export declare const callbackEgressFailureSchema: import("zod").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";
@@ -26,280 +36,211 @@ export declare const callbackVerificationFailureSchema: z.ZodEnum<{
     timed_out: "timed_out";
     unexpected_status: "unexpected_status";
 }>;
-export type CallbackVerificationFailure = z.infer<typeof callbackVerificationFailureSchema>;
+export type CallbackEgressFailure = z.infer<typeof callbackEgressFailureSchema>;
 /**
  * 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: {
+/**
+ * DNS inspection at create and update is admitted through both buckets
+ * before the first lookup, so an address a caller retypes cannot make this
+ * service resolve names without bound.
+ */
+export declare const CALLBACK_ADMISSION_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 declare const callbackSigningKeysSchema: import("zod").ZodObject<{
+    current: import("zod").ZodString;
+    next: import("zod").ZodOptional<import("zod").ZodObject<{
+        acknowledgedAt: import("zod").ZodOptional<import("zod").ZodString>;
+        id: import("zod").ZodString;
+        overlapEndsAt: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>;
 export type CallbackSigningKeys = z.infer<typeof callbackSigningKeysSchema>;
+/**
+ * An endpoint's name: unique within its project and environment, compared
+ * exactly (W4-14, FXO-2255).
+ *
+ * Generated on save when nobody types one — the whole URL — because an
+ * endpoint appears in a dropdown, and two identical rows in a dropdown are
+ * two rows nobody can choose between. So a second endpoint at an address one
+ * already has is refused unless it is given a name of its own. **Case
+ * matters**: two webhook URLs differing only in the case of a token are two
+ * endpoints and both save unnamed; the cost, accepted knowingly, is that
+ * "Prod receiver" and "prod receiver" are both allowed. Deliberately unlike a
+ * project's name, which ignores case and spacing.
+ */
+export declare const callbackEndpointNameSchema: import("zod").ZodString;
 /**
  * A metadata-only endpoint shape. The sealed signing secret has no public
- * field, so list/get/update/verify/disable cannot accidentally recover it.
+ * field, so list/get/update/disable/enable cannot accidentally recover it.
  */
-export declare const callbackEndpointSchema: z.ZodObject<{
-    createdAt: z.ZodString;
-    disabledAt: z.ZodOptional<z.ZodString>;
-    environmentKind: z.ZodEnum<{
+export declare const callbackEndpointSchema: import("zod").ZodObject<{
+    createdAt: import("zod").ZodString;
+    disabledAt: import("zod").ZodOptional<import("zod").ZodString>;
+    environmentKind: import("zod").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";
+    id: import("zod").ZodString;
+    name: import("zod").ZodOptional<import("zod").ZodString>;
+    project: import("zod").ZodString;
+    signingKeys: import("zod").ZodObject<{
+        current: import("zod").ZodString;
+        next: import("zod").ZodOptional<import("zod").ZodObject<{
+            acknowledgedAt: import("zod").ZodOptional<import("zod").ZodString>;
+            id: import("zod").ZodString;
+            overlapEndsAt: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>>;
+    }, import("zod/v4/core").$strip>;
+    status: import("zod").ZodEnum<{
         disabled: "disabled";
+        active: "active";
     }>;
-    updatedAt: z.ZodString;
-    url: z.ZodString;
-    verifiedAt: z.ZodOptional<z.ZodString>;
-    version: z.ZodNumber;
-}, z.core.$strip>;
+    updatedAt: import("zod").ZodString;
+    url: import("zod").ZodString;
+    version: import("zod").ZodNumber;
+}, import("zod/v4/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<{
+export declare const callbackEndpointPageSchema: import("zod").ZodObject<{
+    data: import("zod").ZodArray<import("zod").ZodObject<{
+        createdAt: import("zod").ZodString;
+        disabledAt: import("zod").ZodOptional<import("zod").ZodString>;
+        environmentKind: import("zod").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";
+        id: import("zod").ZodString;
+        name: import("zod").ZodOptional<import("zod").ZodString>;
+        project: import("zod").ZodString;
+        signingKeys: import("zod").ZodObject<{
+            current: import("zod").ZodString;
+            next: import("zod").ZodOptional<import("zod").ZodObject<{
+                acknowledgedAt: import("zod").ZodOptional<import("zod").ZodString>;
+                id: import("zod").ZodString;
+                overlapEndsAt: import("zod").ZodString;
+            }, import("zod/v4/core").$strip>>;
+        }, import("zod/v4/core").$strip>;
+        status: import("zod").ZodEnum<{
             disabled: "disabled";
+            active: "active";
         }>;
-        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>;
+        updatedAt: import("zod").ZodString;
+        url: import("zod").ZodString;
+        version: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>>;
+    freshness: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+        kind: import("zod").ZodLiteral<"authoritative">;
+    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+        asOf: import("zod").ZodString;
+        kind: import("zod").ZodLiteral<"projected">;
+        lagSeconds: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>], "kind">;
+    nextCursor: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/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<{
+export declare const callbackEndpointCreatedSchema: import("zod").ZodObject<{
+    createdAt: import("zod").ZodString;
+    disabledAt: import("zod").ZodOptional<import("zod").ZodString>;
+    environmentKind: import("zod").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";
+    id: import("zod").ZodString;
+    name: import("zod").ZodOptional<import("zod").ZodString>;
+    project: import("zod").ZodString;
+    signingKeys: import("zod").ZodObject<{
+        current: import("zod").ZodString;
+        next: import("zod").ZodOptional<import("zod").ZodObject<{
+            acknowledgedAt: import("zod").ZodOptional<import("zod").ZodString>;
+            id: import("zod").ZodString;
+            overlapEndsAt: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>>;
+    }, import("zod/v4/core").$strip>;
+    status: import("zod").ZodEnum<{
         disabled: "disabled";
+        active: "active";
     }>;
-    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>;
+    updatedAt: import("zod").ZodString;
+    url: import("zod").ZodString;
+    version: import("zod").ZodNumber;
+    keyId: import("zod").ZodString;
+    secret: import("zod").ZodString;
+    shownOnce: import("zod").ZodLiteral<true>;
+}, import("zod/v4/core").$strip>;
 export type CallbackEndpointCreated = z.infer<typeof callbackEndpointCreatedSchema>;
-export declare const callbackSigningKeyRotationRequestSchema: z.ZodObject<{
-    overlapSeconds: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>;
+export declare const callbackSigningKeyRotationRequestSchema: import("zod").ZodObject<{
+    overlapSeconds: import("zod").ZodOptional<import("zod").ZodNumber>;
+}, import("zod/v4/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<{
+export declare const callbackEndpointRotatedSchema: import("zod").ZodObject<{
+    endpoint: import("zod").ZodObject<{
+        createdAt: import("zod").ZodString;
+        disabledAt: import("zod").ZodOptional<import("zod").ZodString>;
+        environmentKind: import("zod").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";
+        id: import("zod").ZodString;
+        name: import("zod").ZodOptional<import("zod").ZodString>;
+        project: import("zod").ZodString;
+        signingKeys: import("zod").ZodObject<{
+            current: import("zod").ZodString;
+            next: import("zod").ZodOptional<import("zod").ZodObject<{
+                acknowledgedAt: import("zod").ZodOptional<import("zod").ZodString>;
+                id: import("zod").ZodString;
+                overlapEndsAt: import("zod").ZodString;
+            }, import("zod/v4/core").$strip>>;
+        }, import("zod/v4/core").$strip>;
+        status: import("zod").ZodEnum<{
             disabled: "disabled";
+            active: "active";
         }>;
-        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>;
+        updatedAt: import("zod").ZodString;
+        url: import("zod").ZodString;
+        version: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>;
+    keyId: import("zod").ZodString;
+    secret: import("zod").ZodString;
+    shownOnce: import("zod").ZodLiteral<true>;
+}, import("zod/v4/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";
+/** One signing key and the secret behind it, as a signed-in person may see it. */
+export declare const callbackEndpointSigningSecretSchema: import("zod").ZodObject<{
+    keyId: import("zod").ZodString;
+    secret: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
 /**
- * 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.
+ * What `endpoints.revealSigningSecret` answers (FXO-2244).
  *
- * 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.
+ * The same value `endpoints.create` and `endpoints.rotateSigningKey` hand out
+ * once, readable again by a signed-in member. Mirrors `signingKeys`: during a
+ * rotation both keys are here, with the instant the overlap ends, because a
+ * receiver being moved to the new key needs both until then.
  */
-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";
-};
+export declare const callbackEndpointSigningSecretsSchema: import("zod").ZodObject<{
+    current: import("zod").ZodObject<{
+        keyId: import("zod").ZodString;
+        secret: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>;
+    id: import("zod").ZodString;
+    next: import("zod").ZodOptional<import("zod").ZodObject<{
+        keyId: import("zod").ZodString;
+        secret: import("zod").ZodString;
+        overlapEndsAt: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>;
+export type CallbackEndpointSigningSecrets = z.infer<typeof callbackEndpointSigningSecretsSchema>;
+export declare const callbackEndpointRequestSchema: import("zod").ZodObject<{
+    name: import("zod").ZodOptional<import("zod").ZodString>;
+    url: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
+export type CallbackEndpointRequest = z.infer<typeof callbackEndpointRequestSchema>;