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

package/generated/v1/snippets/usage.read.json

@@ -1,5 +1,6 @@
 {
   "curl": "curl -sS -X GET \"$GREATWAIT_API_URL/v1/usage\" \\\n  --variable %GREATWAIT_API_KEY \\\n  --expand-header \"Authorization: Bearer {{GREATWAIT_API_KEY}}\"",
+  "environments": ["test", "live"],
   "javascript": "import { createGreatwaitClient } from \"@greatwait/api-client\";\n\nconst greatwait = createGreatwaitClient({\n  baseUrl: process.env.GREATWAIT_API_URL,\n  credential: process.env.GREATWAIT_API_KEY,\n  fetch,\n});\n\nconst result = await greatwait.request(\"usage_read\");",
   "mcp": "// Any MCP client, against $GREATWAIT_API_URL/mcp.\n{\n  \"arguments\": {},\n  \"name\": \"usage_read\"\n}"
 }

package/package.json

@@ -25,6 +25,11 @@
       "import": "./dist/callback-ownership.js",
       "default": "./dist/callback-ownership.js"
     },
+    "./callback-receiver": {
+      "types": "./dist/callback-receiver.d.ts",
+      "import": "./dist/callback-receiver.js",
+      "default": "./dist/callback-receiver.js"
+    },
     "./callback-safety": {
       "types": "./dist/callback-safety.d.ts",
       "import": "./dist/callback-safety.js",
@@ -140,7 +145,7 @@
   "name": "@greatwait/contracts",
   "publishConfig": {
     "access": "public",
-    "tag": "alpha"
+    "tag": "latest"
   },
   "repository": {
     "type": "git",
@@ -149,5 +154,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.1.0-alpha.1"
+  "version": "0.1.0-alpha.3"
 }

package/dist/webhooks.d.ts

@@ -1,116 +0,0 @@
-import { z } from "zod";
-/**
- * Inbound webhook authenticity.
- *
- * Clerk delivers organization and membership changes through Svix, which signs
- * `<svix-id>.<svix-timestamp>.<raw body>` with HMAC-SHA256 under a secret minted
- * per endpoint. This module owns the encoding and the header vocabulary; the
- * adapter owns the key material and the constant-time comparison, exactly as
- * `signatures.ts` splits outbound callback signing.
- *
- * The split matters. Keeping the signed-byte construction in the contract layer
- * means every verifier — the Worker, a test, a future replay tool — signs the
- * same bytes, and the reasoning below is stated once instead of being
- * rediscovered by whoever writes the second one.
- */
-export declare const SVIX_HEADERS: {
-    readonly id: "svix-id";
-    readonly signature: "svix-signature";
-    readonly timestamp: "svix-timestamp";
-};
-/**
- * Where Clerk delivers organization and membership changes.
- *
- * Deliberately outside `/v1`. W1-07 enforces REST/MCP parity over every public
- * `/v1` operation, and a webhook ingress is not a customer-facing operation —
- * putting it there would either break that check or require an exception to it.
- * Follows the internal-route convention set by `/__greatwait/version`.
- *
- * **Here rather than in the Worker that serves it, since W4-08.** The smoke
- * asks a hosted stage whether this route is configured to accept a delivery,
- * and a script cannot import the API application. A second spelling of an
- * address Clerk is pointed at is one that can drift while both read as
- * correct.
- */
-export declare const CLERK_WEBHOOK_PATH = "/__greatwait/webhooks/clerk";
-/** Only `v1` exists. A new scheme is added alongside, never in place of. */
-export declare const WEBHOOK_SIGNATURE_SCHEME: "v1";
-/**
- * How far Clerk's clock may differ from ours before a delivery is stale.
- *
- * Svix's own guidance is five minutes, and matching it is deliberate: a tighter
- * window would reject legitimate deliveries during a retry burst, and a wider
- * one lengthens the replay window for a captured request.
- */
-export declare const WEBHOOK_TOLERANCE_SECONDS = 300;
-/**
- * A Svix message id. Deliberately a restricted charset rather than
- * `z.string().min(1)` — see `webhookSigningInput` for why the absence of `.`
- * here is a security property and not a formatting preference.
- */
-export declare const svixIdSchema: z.ZodString;
-/**
- * Seconds since the Unix epoch, as digits. No sign, no decimal point, no
- * exponent — `Number.parseInt` would happily accept `+1e9` and `12.5`, and both
- * would reach the signed bytes in a form we did not intend.
- */
-export declare const svixTimestampSchema: z.ZodString;
-/**
- * One `v1,<base64>` pair. Svix sends a space-delimited list so an endpoint can
- * be verified under both keys during rotation, which is why the verifier must
- * accept a match against *any* entry rather than parsing a single value.
- */
-export declare const svixSignatureEntryPattern: RegExp;
-export declare const svixSignatureHeaderSchema: z.ZodString;
-export declare const svixHeadersSchema: z.ZodObject<{
-    "svix-id": z.ZodString;
-    "svix-signature": z.ZodString;
-    "svix-timestamp": z.ZodString;
-}, z.core.$strip>;
-/**
- * Every `v1` signature offered in the header, base64 still encoded.
- *
- * Entries in other schemes are dropped rather than rejected: Svix may add a
- * scheme before we support it, and a delivery that carries both `v1` and a
- * future `v2` must still verify under `v1` instead of failing closed on the
- * presence of something newer.
- */
-export declare function webhookSignatureCandidates(header: string): readonly string[];
-/**
- * The exact bytes Svix signs: `<id>.<timestamp>.` followed by the raw body,
- * with no re-serialization anywhere in the path.
- *
- * Both prefix fields are validated rather than trusted, and — as with
- * `signingInput` for outbound callbacks — that is a security property. The
- * delimiter is `.`, so if either field could itself contain a `.` the encoding
- * would not be injective: an attacker holding one legitimate signature could
- * shift bytes across a delimiter, lengthening the id header while shortening
- * the body, and still verify.
- *
- * The argument here is slightly different from the outbound one, which relies
- * on both fields being fixed-width. `svixIdSchema` and `svixTimestampSchema`
- * admit no `.` at all, so splitting the signed content on its first two dots
- * recovers the id and the timestamp uniquely whatever their lengths. Variable
- * width is fine; a dot would not be.
- *
- * **Throws** on malformed input. Use `tryWebhookSigningInput` when verifying
- * headers off the wire, or a malformed-header probe becomes a 500.
- */
-export declare function webhookSigningInput(svixId: string, svixTimestamp: string, rawBody: Uint8Array): Uint8Array;
-/**
- * `webhookSigningInput` for untrusted input: `undefined` instead of a throw when
- * the headers are malformed.
- */
-export declare function tryWebhookSigningInput(svixId: string, svixTimestamp: string, rawBody: Uint8Array): Uint8Array | undefined;
-/**
- * Whether a delivery's timestamp is close enough to now.
- *
- * Rejects the future as firmly as the past. A signature dated an hour ahead is
- * not a clock-skew inconvenience — accepting it would hand an attacker who
- * captures one request an hour of replay window, so the comparison is on
- * absolute difference.
- *
- * Replay protection beyond this window belongs to the receiver, keyed on the
- * Svix message id; freshness alone does not make a delivery unique.
- */
-export declare function isWebhookTimestampFresh(svixTimestamp: string, nowMs: number, toleranceSeconds?: number): boolean;

package/dist/webhooks.js

@@ -1,161 +0,0 @@
-import { z } from "zod";
-/**
- * Inbound webhook authenticity.
- *
- * Clerk delivers organization and membership changes through Svix, which signs
- * `<svix-id>.<svix-timestamp>.<raw body>` with HMAC-SHA256 under a secret minted
- * per endpoint. This module owns the encoding and the header vocabulary; the
- * adapter owns the key material and the constant-time comparison, exactly as
- * `signatures.ts` splits outbound callback signing.
- *
- * The split matters. Keeping the signed-byte construction in the contract layer
- * means every verifier — the Worker, a test, a future replay tool — signs the
- * same bytes, and the reasoning below is stated once instead of being
- * rediscovered by whoever writes the second one.
- */
-export const SVIX_HEADERS = {
-    id: "svix-id",
-    signature: "svix-signature",
-    timestamp: "svix-timestamp",
-};
-/**
- * Where Clerk delivers organization and membership changes.
- *
- * Deliberately outside `/v1`. W1-07 enforces REST/MCP parity over every public
- * `/v1` operation, and a webhook ingress is not a customer-facing operation —
- * putting it there would either break that check or require an exception to it.
- * Follows the internal-route convention set by `/__greatwait/version`.
- *
- * **Here rather than in the Worker that serves it, since W4-08.** The smoke
- * asks a hosted stage whether this route is configured to accept a delivery,
- * and a script cannot import the API application. A second spelling of an
- * address Clerk is pointed at is one that can drift while both read as
- * correct.
- */
-export const CLERK_WEBHOOK_PATH = "/__greatwait/webhooks/clerk";
-/** Only `v1` exists. A new scheme is added alongside, never in place of. */
-export const WEBHOOK_SIGNATURE_SCHEME = "v1";
-/**
- * How far Clerk's clock may differ from ours before a delivery is stale.
- *
- * Svix's own guidance is five minutes, and matching it is deliberate: a tighter
- * window would reject legitimate deliveries during a retry burst, and a wider
- * one lengthens the replay window for a captured request.
- */
-export const WEBHOOK_TOLERANCE_SECONDS = 300;
-/**
- * A Svix message id. Deliberately a restricted charset rather than
- * `z.string().min(1)` — see `webhookSigningInput` for why the absence of `.`
- * here is a security property and not a formatting preference.
- */
-export const svixIdSchema = z
-    .string()
-    .regex(/^msg_[A-Za-z0-9]{1,64}$/u, 'must be "msg_" followed by up to 64 alphanumeric characters');
-/**
- * Seconds since the Unix epoch, as digits. No sign, no decimal point, no
- * exponent — `Number.parseInt` would happily accept `+1e9` and `12.5`, and both
- * would reach the signed bytes in a form we did not intend.
- */
-export const svixTimestampSchema = z
-    .string()
-    .regex(/^[0-9]{1,15}$/u, "must be a whole number of seconds since the epoch");
-/**
- * One `v1,<base64>` pair. Svix sends a space-delimited list so an endpoint can
- * be verified under both keys during rotation, which is why the verifier must
- * accept a match against *any* entry rather than parsing a single value.
- */
-export const svixSignatureEntryPattern = /^v1,[A-Za-z0-9+/]+={0,2}$/u;
-export const svixSignatureHeaderSchema = z
-    .string()
-    .min(1)
-    .refine((header) => header
-    .split(" ")
-    .filter((entry) => entry.length > 0)
-    .some((entry) => svixSignatureEntryPattern.test(entry)), "must contain at least one v1,<base64> signature");
-export const svixHeadersSchema = z.object({
-    [SVIX_HEADERS.id]: svixIdSchema,
-    [SVIX_HEADERS.signature]: svixSignatureHeaderSchema,
-    [SVIX_HEADERS.timestamp]: svixTimestampSchema,
-});
-/**
- * Every `v1` signature offered in the header, base64 still encoded.
- *
- * Entries in other schemes are dropped rather than rejected: Svix may add a
- * scheme before we support it, and a delivery that carries both `v1` and a
- * future `v2` must still verify under `v1` instead of failing closed on the
- * presence of something newer.
- */
-export function webhookSignatureCandidates(header) {
-    return header
-        .split(" ")
-        .filter((entry) => svixSignatureEntryPattern.test(entry))
-        .map((entry) => entry.slice(`${WEBHOOK_SIGNATURE_SCHEME},`.length));
-}
-/**
- * The exact bytes Svix signs: `<id>.<timestamp>.` followed by the raw body,
- * with no re-serialization anywhere in the path.
- *
- * Both prefix fields are validated rather than trusted, and — as with
- * `signingInput` for outbound callbacks — that is a security property. The
- * delimiter is `.`, so if either field could itself contain a `.` the encoding
- * would not be injective: an attacker holding one legitimate signature could
- * shift bytes across a delimiter, lengthening the id header while shortening
- * the body, and still verify.
- *
- * The argument here is slightly different from the outbound one, which relies
- * on both fields being fixed-width. `svixIdSchema` and `svixTimestampSchema`
- * admit no `.` at all, so splitting the signed content on its first two dots
- * recovers the id and the timestamp uniquely whatever their lengths. Variable
- * width is fine; a dot would not be.
- *
- * **Throws** on malformed input. Use `tryWebhookSigningInput` when verifying
- * headers off the wire, or a malformed-header probe becomes a 500.
- */
-export function webhookSigningInput(svixId, svixTimestamp, rawBody) {
-    const checkedId = svixIdSchema.parse(svixId);
-    const checkedTimestamp = svixTimestampSchema.parse(svixTimestamp);
-    const prefix = `${checkedId}.${checkedTimestamp}.`;
-    // Both fields are ASCII by construction, now that both have been validated, so
-    // UTF-8 encoding them is byte-identical to their code points.
-    const prefixBytes = new TextEncoder().encode(prefix);
-    const input = new Uint8Array(prefixBytes.length + rawBody.length);
-    input.set(prefixBytes, 0);
-    input.set(rawBody, prefixBytes.length);
-    return input;
-}
-/**
- * `webhookSigningInput` for untrusted input: `undefined` instead of a throw when
- * the headers are malformed.
- */
-export function tryWebhookSigningInput(svixId, svixTimestamp, rawBody) {
-    try {
-        return webhookSigningInput(svixId, svixTimestamp, rawBody);
-    }
-    catch (error) {
-        // Only a validation failure means "malformed headers". Anything else — an
-        // allocation failure on an oversized body, say — is a real fault and must
-        // not be reported to the caller as a bad signature.
-        if (error instanceof z.ZodError) {
-            return undefined;
-        }
-        throw error;
-    }
-}
-/**
- * Whether a delivery's timestamp is close enough to now.
- *
- * Rejects the future as firmly as the past. A signature dated an hour ahead is
- * not a clock-skew inconvenience — accepting it would hand an attacker who
- * captures one request an hour of replay window, so the comparison is on
- * absolute difference.
- *
- * Replay protection beyond this window belongs to the receiver, keyed on the
- * Svix message id; freshness alone does not make a delivery unique.
- */
-export function isWebhookTimestampFresh(svixTimestamp, nowMs, toleranceSeconds = WEBHOOK_TOLERANCE_SECONDS) {
-    if (!svixTimestampSchema.safeParse(svixTimestamp).success) {
-        return false;
-    }
-    const signedMs = Number(svixTimestamp) * 1000;
-    return Math.abs(nowMs - signedMs) <= toleranceSeconds * 1000;
-}