@greatwait/contracts 0.1.0-alpha.1

package/dist/webhooks.js

@@ -0,0 +1,161 @@
+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;
+}

package/dist/workspace.d.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+/**
+ * Repository scaffold contracts.
+ *
+ * These schemas describe the workspace itself — the layer a package occupies
+ * and the scaffold responses the apps expose. The public V1 product contract
+ * (IDs, timestamps, pagination, errors, idempotency, events, signatures) is
+ * defined by W0-02 and does not belong here.
+ */
+export declare const WORKSPACE_LAYERS: readonly ["contract", "platform", "domain", "application", "adapter", "test-support"];
+export declare const workspaceLayerSchema: z.ZodEnum<{
+    contract: "contract";
+    platform: "platform";
+    domain: "domain";
+    application: "application";
+    adapter: "adapter";
+    "test-support": "test-support";
+}>;
+export type WorkspaceLayer = z.infer<typeof workspaceLayerSchema>;
+export declare const workspaceIdentitySchema: z.ZodObject<{
+    layer: z.ZodEnum<{
+        contract: "contract";
+        platform: "platform";
+        domain: "domain";
+        application: "application";
+        adapter: "adapter";
+        "test-support": "test-support";
+    }>;
+    workspace: z.ZodString;
+}, z.core.$strip>;
+export type WorkspaceIdentity = z.infer<typeof workspaceIdentitySchema>;
+/** Shape of `GET /__greatwait/version` on every Greatwait Worker. */
+export declare const scaffoldVersionSchema: z.ZodObject<{
+    buildSha: z.ZodString;
+    environment: z.ZodString;
+    service: z.ZodString;
+}, z.core.$strip>;
+export type ScaffoldVersion = z.infer<typeof scaffoldVersionSchema>;
+/** Shape of the scaffold description an adapter reads from the application. */
+export declare const workspaceScaffoldSchema: z.ZodObject<{
+    dependsOn: z.ZodArray<z.ZodEnum<{
+        contract: "contract";
+        platform: "platform";
+        domain: "domain";
+        application: "application";
+        adapter: "adapter";
+        "test-support": "test-support";
+    }>>;
+    layer: z.ZodEnum<{
+        contract: "contract";
+        platform: "platform";
+        domain: "domain";
+        application: "application";
+        adapter: "adapter";
+        "test-support": "test-support";
+    }>;
+    service: z.ZodString;
+}, z.core.$strip>;
+export type WorkspaceScaffold = z.infer<typeof workspaceScaffoldSchema>;
+/**
+ * The minimal refusal body the scaffold routes return.
+ *
+ * Superseded by `problems.ts`, which W0-02 defined. This remains only for the
+ * scaffold routes in `apps/api` and `apps/contract-mock`; those move to the
+ * real problem document when W1-06 replaces the scaffold with the REST
+ * control plane. New code uses `problem()`.
+ */
+export declare const scaffoldProblemSchema: z.ZodObject<{
+    title: z.ZodString;
+    type: z.ZodLiteral<"about:blank">;
+}, z.core.$strip>;
+export type ScaffoldProblem = z.infer<typeof scaffoldProblemSchema>;
+/**
+ * A transport-neutral tool descriptor. REST and MCP publish the same shape, so
+ * the two surfaces cannot drift into describing tools differently.
+ */
+export declare const toolDescriptorSchema: z.ZodObject<{
+    description: z.ZodString;
+    name: z.ZodString;
+    readOnly: z.ZodBoolean;
+    title: z.ZodString;
+}, z.core.$strip>;
+export type ToolDescriptor = z.infer<typeof toolDescriptorSchema>;
+export declare const toolListSchema: z.ZodObject<{
+    tools: z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        name: z.ZodString;
+        readOnly: z.ZodBoolean;
+        title: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ToolList = z.infer<typeof toolListSchema>;

package/dist/workspace.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+/**
+ * Repository scaffold contracts.
+ *
+ * These schemas describe the workspace itself — the layer a package occupies
+ * and the scaffold responses the apps expose. The public V1 product contract
+ * (IDs, timestamps, pagination, errors, idempotency, events, signatures) is
+ * defined by W0-02 and does not belong here.
+ */
+export const WORKSPACE_LAYERS = [
+    "contract",
+    "platform",
+    "domain",
+    "application",
+    "adapter",
+    "test-support",
+];
+export const workspaceLayerSchema = z.enum(WORKSPACE_LAYERS);
+export const workspaceIdentitySchema = z.object({
+    layer: workspaceLayerSchema,
+    workspace: z.string().min(1),
+});
+/** Shape of `GET /__greatwait/version` on every Greatwait Worker. */
+export const scaffoldVersionSchema = z.object({
+    buildSha: z.string().min(1),
+    environment: z.string().min(1),
+    service: z.string().min(1),
+});
+/** Shape of the scaffold description an adapter reads from the application. */
+export const workspaceScaffoldSchema = z.object({
+    dependsOn: z.array(workspaceLayerSchema),
+    layer: workspaceLayerSchema,
+    service: z.string().min(1),
+});
+/**
+ * The minimal refusal body the scaffold routes return.
+ *
+ * Superseded by `problems.ts`, which W0-02 defined. This remains only for the
+ * scaffold routes in `apps/api` and `apps/contract-mock`; those move to the
+ * real problem document when W1-06 replaces the scaffold with the REST
+ * control plane. New code uses `problem()`.
+ */
+export const scaffoldProblemSchema = z.object({
+    title: z.string().min(1),
+    type: z.literal("about:blank"),
+});
+/**
+ * A transport-neutral tool descriptor. REST and MCP publish the same shape, so
+ * the two surfaces cannot drift into describing tools differently.
+ */
+export const toolDescriptorSchema = z.object({
+    description: z.string().min(1),
+    name: z.string().min(1),
+    readOnly: z.boolean(),
+    title: z.string().min(1),
+});
+export const toolListSchema = z.object({
+    tools: z.array(toolDescriptorSchema),
+});