@whooshbang/contract-mock 1.0.0-rc.16

package/dist/control-surface.js

@@ -0,0 +1,158 @@
+import { parseInteractionControlInput } from "./interaction-control.js";
+const MAX_CONTROL_REQUEST_BYTES = 64 * 1024;
+async function timingSafeTokenEqual(supplied, expected) {
+    try {
+        const encoder = new TextEncoder();
+        const comparisonInput = encoder.encode("whooshbang.contract-mock.control.v1");
+        const [suppliedKey, expectedKey] = await Promise.all([
+            globalThis.crypto.subtle.importKey("raw", encoder.encode(supplied), { hash: "SHA-256", name: "HMAC" }, false, ["sign"]),
+            globalThis.crypto.subtle.importKey("raw", encoder.encode(expected), { hash: "SHA-256", name: "HMAC" }, false, ["verify"]),
+        ]);
+        const suppliedMac = await globalThis.crypto.subtle.sign("HMAC", suppliedKey, comparisonInput);
+        return await globalThis.crypto.subtle.verify("HMAC", expectedKey, suppliedMac, comparisonInput);
+    }
+    catch {
+        return false;
+    }
+}
+async function readControlJson(request) {
+    const reader = request.body?.getReader();
+    if (reader === undefined) {
+        throw new TypeError("A JSON body is required.");
+    }
+    const chunks = [];
+    let length = 0;
+    try {
+        for (;;) {
+            const result = await reader.read();
+            if (result.done) {
+                break;
+            }
+            length += result.value.byteLength;
+            if (length > MAX_CONTROL_REQUEST_BYTES) {
+                await reader.cancel();
+                throw new RangeError("The control request is too large.");
+            }
+            chunks.push(result.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+}
+function asRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new TypeError("The control request must be a JSON object.");
+    }
+    return value;
+}
+function isProviderOutcome(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const record = value;
+    if (!["accepted", "retryable", "terminal", "ambiguous"].includes(String(record.kind))) {
+        return false;
+    }
+    return (record.retryAfterSeconds === undefined ||
+        (record.kind === "retryable" &&
+            typeof record.retryAfterSeconds === "number" &&
+            Number.isInteger(record.retryAfterSeconds) &&
+            record.retryAfterSeconds >= 0 &&
+            record.retryAfterSeconds <= 86_400));
+}
+function controlError(status, detail) {
+    return Response.json({
+        detail,
+        status,
+        title: status === 401
+            ? "Control authentication required"
+            : "Invalid control request",
+        type: "about:blank",
+    }, { status });
+}
+/**
+ * Mounts the CLI-only, test-only HTTP control surface. This module is not
+ * imported by either public package entry point or the Worker entry point.
+ */
+export function mountContractMockControlSurface(target, token) {
+    if (!/^[\u0021-\u007e]{8,4096}$/u.test(token)) {
+        throw new RangeError("The control token must be 8 to 4096 visible ASCII characters.");
+    }
+    target.app.use("/__contract-mock/*", async (context, next) => {
+        const supplied = context.req.header("whooshbang-contract-mock-token");
+        if (supplied === undefined ||
+            !/^[\u0021-\u007e]{8,4096}$/u.test(supplied) ||
+            !(await timingSafeTokenEqual(supplied, token))) {
+            return controlError(401, "Provide the explicit contract-mock control token.");
+        }
+        return next();
+    });
+    target.app.get("/__contract-mock/snapshot", (context) => context.json(target.inspect()));
+    target.app.post("/__contract-mock/reset", async (context) => {
+        try {
+            const body = asRecord(await readControlJson(context.req.raw));
+            if (typeof body.scenario !== "string") {
+                return controlError(400, "A scenario name is required.");
+            }
+            await target.control.reset(body.scenario);
+            return context.json(target.inspect());
+        }
+        catch {
+            return controlError(400, "The reset request is invalid.");
+        }
+    });
+    target.app.post("/__contract-mock/provider-outcomes", async (context) => {
+        try {
+            const body = asRecord(await readControlJson(context.req.raw));
+            if (!Array.isArray(body.outcomes) ||
+                !body.outcomes.every(isProviderOutcome)) {
+                return controlError(400, "The provider outcome script is invalid.");
+            }
+            target.control.setProviderOutcomes(body.outcomes);
+            return context.json({ accepted: true });
+        }
+        catch {
+            return controlError(400, "The provider outcome script is invalid.");
+        }
+    });
+    target.app.post("/__contract-mock/webhook-responses", async (context) => {
+        try {
+            const body = asRecord(await readControlJson(context.req.raw));
+            if (!Array.isArray(body.responses) ||
+                !body.responses.every((value) => value === "network_failure" ||
+                    (typeof value === "number" &&
+                        Number.isInteger(value) &&
+                        value >= 100 &&
+                        value <= 599))) {
+                return controlError(400, "The webhook response script is invalid.");
+            }
+            target.control.setWebhookResponses(body.responses);
+            return context.json({ accepted: true });
+        }
+        catch {
+            return controlError(400, "The webhook response script is invalid.");
+        }
+    });
+    target.app.post("/__contract-mock/interactions", async (context) => {
+        try {
+            const input = parseInteractionControlInput(await readControlJson(context.req.raw));
+            return context.json(await target.control.submitInteraction(input));
+        }
+        catch {
+            return controlError(400, "The interaction request is invalid.");
+        }
+    });
+    target.app.post("/__contract-mock/run-pending", async (context) => {
+        await target.control.runPending();
+        return context.json({ accepted: true });
+    });
+}
+//# sourceMappingURL=control-surface.js.map

package/dist/control-surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-surface.js","sourceRoot":"","sources":["../src/control-surface.ts"],"names":[],"mappings":"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"}

package/dist/core.d.ts

@@ -0,0 +1,33 @@
+import { Hono } from "hono";
+import type { WhooshBangContractMock, WhooshBangContractMockOptions } from "./types.js";
+interface CoreWhooshBangContractMock extends WhooshBangContractMock {
+    readonly app: Hono;
+}
+/**
+ * The synthetic project and environment identifiers the fixture project
+ * credentials authenticate against.
+ *
+ * Environment-scoped paths need an environment identifier that the bearer
+ * token alone does not carry, so consumers building customer-endpoint URLs
+ * read it from here rather than guessing.
+ */
+export declare const CONTRACT_MOCK_FIXTURE_ENVIRONMENTS: Readonly<{
+    readonly liveEnvironmentId: "environment_project_synthetic_live";
+    readonly projectId: "project_synthetic";
+    readonly testEnvironmentId: "environment_project_synthetic_test";
+}>;
+export declare const CONTRACT_MOCK_FIXTURE_CREDENTIALS: Readonly<{
+    readonly grant: "oauth-grant-token";
+    readonly humanSession: "human-session-token";
+    readonly otherGrant: "oauth-grant-other-token";
+    readonly liveProject: "project-live-token";
+    readonly machineA: "machine-a-token";
+    readonly machineB: "machine-b-token";
+    readonly otherHumanSession: "human-other-session-token";
+    readonly projectA: "project-a-token";
+    readonly projectB: "project-b-token";
+    readonly projectTest: "project-test-token";
+    readonly readOnly: "project-read-only-token";
+}>;
+export declare function createWhooshBangContractMockCore(options?: WhooshBangContractMockOptions): CoreWhooshBangContractMock;
+export {};