@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/service/warehouse-query.d.ts

@@ -0,0 +1,24 @@
+import type { EntityManifest, OntologyManifest } from "../manifest.js";
+import { type Query } from "../query.js";
+import type { StoredRecord } from "../runtime.js";
+export interface WarehouseParameter {
+    readonly name: string;
+    readonly type: "STRING" | "INT64" | "FLOAT64" | "BOOL" | "DATE" | "TIMESTAMP";
+    readonly value?: string;
+    readonly values?: ReadonlyArray<string>;
+}
+export interface WarehouseStatement {
+    readonly sql: string;
+    readonly parameters: ReadonlyArray<WarehouseParameter>;
+    readonly maxRows: number;
+}
+/** Source keys are opaque record identities, including composite and non-UUID keys. */
+export declare function isWarehouseRecordId(value: string): boolean;
+/** A checked entity query compiled only from declared identifiers and bound values. */
+export declare function compileWarehouseQuery(manifest: OntologyManifest, entity: EntityManifest, query: Query): WarehouseStatement & {
+    readonly decode: (rows: ReadonlyArray<StoredRecord>) => {
+        readonly items: ReadonlyArray<StoredRecord>;
+        readonly nextCursor: string | null;
+        readonly projected?: true;
+    };
+};

package/dist/service/warehouse-query.js

@@ -0,0 +1,280 @@
+import { createHash } from "node:crypto";
+import { queryFields, } from "../query.js";
+import { InvalidQuery } from "../runtime/errors.js";
+const PREFIX = "wr1_";
+const ID = /^wr1_[A-Za-z0-9_-]{1,12000}$/;
+const COLUMN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function invalid(entity, message) {
+    throw new InvalidQuery({ entity, message, issues: [{ path: [], message }] });
+}
+/** Source keys are opaque record identities, including composite and non-UUID keys. */
+export function isWarehouseRecordId(value) {
+    if (!ID.test(value)) {
+        return false;
+    }
+    try {
+        const key = JSON.parse(Buffer.from(value.slice(PREFIX.length), "base64url").toString());
+        return Array.isArray(key) && key.length > 0 && key.every((part) => typeof part === "string");
+    }
+    catch {
+        return false;
+    }
+}
+function identifier(value) {
+    if (!COLUMN.test(value)) {
+        throw new Error("A checked warehouse column was expected.");
+    }
+    return `\`${value}\``;
+}
+function canonical(value) {
+    if (Array.isArray(value)) {
+        return value.map(canonical);
+    }
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => [key, canonical(item)]));
+    }
+    return value;
+}
+function parameterType(field) {
+    switch (field.storage) {
+        case "integer":
+            return "INT64";
+        case "number":
+            return "FLOAT64";
+        case "boolean":
+            return "BOOL";
+        case "date":
+            return "DATE";
+        case "timestamp":
+            return "TIMESTAMP";
+        default:
+            return "STRING";
+    }
+}
+function scalar(field, value) {
+    if (value === null) {
+        return null;
+    }
+    if (field.storage === "integer" || field.storage === "number") {
+        const number = typeof value === "number" ? value : Number(value);
+        if (!Number.isFinite(number) ||
+            (field.storage === "integer" && !Number.isSafeInteger(number))) {
+            throw new Error("The warehouse returned a number outside the record's supported range.");
+        }
+        return number;
+    }
+    if (field.storage === "boolean") {
+        if (value === true || value === "true") {
+            return true;
+        }
+        if (value === false || value === "false") {
+            return false;
+        }
+        throw new Error("The warehouse returned an invalid boolean.");
+    }
+    if (typeof value !== "string") {
+        throw new Error("The warehouse returned an invalid scalar record field.");
+    }
+    return value;
+}
+/** A checked entity query compiled only from declared identifiers and bound values. */
+export function compileWarehouseQuery(manifest, entity, query) {
+    const source = entity.source;
+    if (source === undefined) {
+        throw new Error("A warehouse source was expected.");
+    }
+    const asset = source.asset.split("/").map(identifier).join(".");
+    const fields = queryFields(entity);
+    const byName = new Map(fields.map((field) => [field.name, field]));
+    const mapped = new Map(entity.properties.map((property) => [property.name, property.column]));
+    const key = `TO_JSON_STRING([${source.key.map((column) => `CAST(r.${identifier(column)} AS STRING)`).join(", ")}])`;
+    const id = `CONCAT('${PREFIX}', RTRIM(REPLACE(REPLACE(TO_BASE64(CAST(${key} AS BYTES)), '+', '-'), '/', '_'), '='))`;
+    const column = (name) => name === "id" ? id : `r.${identifier(mapped.get(name))}`;
+    const parameters = [];
+    const bind = (field, value, array = false) => {
+        const name = `p${parameters.length}`;
+        parameters.push({
+            name,
+            type: parameterType(field),
+            ...(array
+                ? { values: value.map(String) }
+                : { value: String(value) }),
+        });
+        return `@${name}`;
+    };
+    const compileField = (field, condition) => {
+        const expression = column(field.name);
+        const filter = condition === null
+            ? { isNull: true }
+            : typeof condition === "object" && !Array.isArray(condition)
+                ? condition
+                : { eq: condition };
+        return (Object.entries(filter)
+            .map(([operator, value]) => {
+            if (operator === "isNull") {
+                return `${expression} IS ${value ? "" : "NOT "}NULL`;
+            }
+            if (operator === "in") {
+                return value.length === 0
+                    ? "FALSE"
+                    : `${expression} IN UNNEST(${bind(field, value, true)})`;
+            }
+            if (operator === "between") {
+                const pair = value;
+                return `${expression} BETWEEN ${bind(field, pair[0])} AND ${bind(field, pair[1])}`;
+            }
+            const parameter = bind(field, value);
+            switch (operator) {
+                case "eq":
+                    return `${expression} = ${parameter}`;
+                case "ne":
+                    return `(${expression} != ${parameter} OR ${expression} IS NULL)`;
+                case "gt":
+                    return `${expression} > ${parameter}`;
+                case "gte":
+                    return `${expression} >= ${parameter}`;
+                case "lt":
+                    return `${expression} < ${parameter}`;
+                case "lte":
+                    return `${expression} <= ${parameter}`;
+                case "contains":
+                    return `STRPOS(LOWER(${expression}), LOWER(${parameter})) > 0`;
+                case "startsWith":
+                    return `STARTS_WITH(LOWER(${expression}), LOWER(${parameter}))`;
+                default:
+                    return invalid(entity.name, `Unsupported warehouse field operator ${operator}.`);
+            }
+        })
+            .map((part) => `(${part})`)
+            .join(" AND ") || "TRUE");
+    };
+    const where = (condition) => Object.entries(condition)
+        .map(([name, value]) => {
+        if (name === "and" || name === "or") {
+            const parts = value.map((part) => `(${where(part)})`);
+            return (parts.join(name === "and" ? " AND " : " OR ") || (name === "and" ? "TRUE" : "FALSE"));
+        }
+        if (name === "not") {
+            return `NOT (${where(value)})`;
+        }
+        const field = byName.get(name);
+        if (field === undefined) {
+            return invalid(entity.name, "Warehouse filters name mapped fields.");
+        }
+        return compileField(field, value);
+    })
+        .map((part) => `(${part})`)
+        .join(" AND ") || "TRUE";
+    const orders = [];
+    for (const entry of [...(query.orderBy ?? []), { field: "id", direction: "asc" }]) {
+        if (!orders.some((order) => order.field.name === entry.field)) {
+            const field = byName.get(entry.field);
+            if (field === undefined) {
+                invalid(entity.name, "Unknown warehouse sort field.");
+            }
+            orders.push({ field, direction: entry.direction ?? "asc" });
+        }
+    }
+    const fingerprint = createHash("sha256")
+        .update(JSON.stringify(canonical([
+        manifest.hash,
+        entity.name,
+        query.where ?? {},
+        orders.map((order) => [order.field.name, order.direction]),
+    ])))
+        .digest("hex");
+    const predicates = [where(query.where ?? {})];
+    if (query.after !== undefined) {
+        let values;
+        try {
+            if (query.after.length > 32000) {
+                throw new Error("oversized");
+            }
+            const cursor = JSON.parse(Buffer.from(query.after, "base64url").toString());
+            if (cursor.v !== 1 ||
+                cursor.fingerprint !== fingerprint ||
+                !Array.isArray(cursor.values) ||
+                cursor.values.length !== orders.length) {
+                throw new Error("mismatch");
+            }
+            values = cursor.values;
+            orders.forEach((order, index) => {
+                const value = values[index];
+                if (value !== null) {
+                    scalar(order.field, value);
+                }
+                if (order.field.name === "id" &&
+                    (typeof value !== "string" || !isWarehouseRecordId(value))) {
+                    throw new Error("invalid key");
+                }
+            });
+        }
+        catch {
+            invalid(entity.name, "This cursor does not belong to the current warehouse query.");
+        }
+        const ties = [];
+        const after = [];
+        orders.forEach((order, index) => {
+            const expression = column(order.field.name);
+            const value = values[index];
+            if (value === null) {
+                ties.push(`${expression} IS NULL`);
+            }
+            else {
+                const parameter = bind(order.field, value);
+                const past = `(${expression} ${order.direction === "asc" ? ">" : "<"} ${parameter} OR ${expression} IS NULL)`;
+                after.push([...ties, past].join(" AND "));
+                ties.push(`${expression} = ${parameter}`);
+            }
+        });
+        predicates.push(after.length === 0 ? "FALSE" : after.map((part) => `(${part})`).join(" OR "));
+    }
+    const selected = [...new Set(["id", ...(query.select ?? fields.map((field) => field.name))])];
+    const limit = query.limit ?? 50;
+    const projection = [
+        ...selected.map((name) => `${column(name)} AS ${identifier(name)}`),
+        ...orders.map((order, index) => `${column(order.field.name)} AS ${identifier(`__order_${index}`)}`),
+    ];
+    const ordering = orders.map((order) => `${column(order.field.name)} ${order.direction.toUpperCase()} NULLS LAST`);
+    const sql = [
+        `SELECT ${projection.join(", ")}`,
+        `FROM ${asset} AS r`,
+        `WHERE ${predicates.map((part) => `(${part})`).join(" AND ")}`,
+        `ORDER BY ${ordering.join(", ")}`,
+        `LIMIT ${bind({ name: "limit", storage: "integer", nullable: false }, limit + 1)}`,
+    ].join("\n");
+    if (parameters.length > 100) {
+        invalid(entity.name, "A warehouse record query accepts at most 100 bound parameters.");
+    }
+    return {
+        sql,
+        parameters,
+        maxRows: limit + 1,
+        decode: (rows) => {
+            const seen = new Set();
+            for (const row of rows) {
+                if (typeof row.id !== "string" || !isWarehouseRecordId(row.id) || seen.has(row.id)) {
+                    invalid(entity.name, "Warehouse source keys must be non-null and unique.");
+                }
+                seen.add(row.id);
+            }
+            const page = rows.slice(0, limit);
+            const items = page.map((row) => Object.fromEntries(selected.map((name) => [name, scalar(byName.get(name), row[name])])));
+            const last = page.at(-1);
+            const nextCursor = rows.length > limit && last !== undefined
+                ? Buffer.from(JSON.stringify({
+                    v: 1,
+                    fingerprint,
+                    values: orders.map((order, index) => scalar(order.field, last[`__order_${index}`])),
+                })).toString("base64url")
+                : null;
+            return {
+                items,
+                nextCursor,
+                ...(query.select === undefined ? {} : { projected: true }),
+            };
+        },
+    };
+}

package/dist/service/webhooks.d.ts

@@ -0,0 +1,106 @@
+import { Effect, Redacted } from "effect";
+import type { HttpServerRequest } from "effect/unstable/http";
+import type { WebhookSignatureScheme } from "../webhooks.js";
+/**
+ * The pieces of the webhook route that do not need the router: reading the body, the signature
+ * schemes, the backend's verification and the throttle on refused signatures.
+ */
+/** What SegmentStream's backend answered about a delivery's signature. */
+export type WebhookVerification = {
+    readonly outcome: "valid";
+} | {
+    readonly outcome: "invalid";
+}
+/** The workspace secret the webhook names does not exist. */
+ | {
+    readonly outcome: "secret_missing";
+}
+/** The backend could not answer; the provider retries. `cause` is for operator logs only. */
+ | {
+    readonly outcome: "unavailable";
+    readonly status?: number;
+    readonly cause?: unknown;
+};
+/** A signature check the ontology service asks the backend for: the secret never leaves it. */
+export interface WebhookVerifyRequest {
+    /** The workspace secret's name. */
+    readonly secret: string;
+    readonly algorithm: "sha256";
+    readonly encoding: "hex";
+    /** The bytes the provider signed. */
+    readonly message: Uint8Array;
+    /** The signatures the delivery carried; any that matches is enough. */
+    readonly signatures: ReadonlyArray<string>;
+    /** The deployment's Vercel OIDC token, which proves the workspace application. */
+    readonly identityToken: string | undefined;
+    readonly requestId: string;
+}
+/** Checks webhook signatures. The service calls SegmentStream's backend by default. */
+export type WebhookVerifier = (request: WebhookVerifyRequest) => Promise<WebhookVerification>;
+/** Registration checks return only a match; the stored verify token never leaves the backend. */
+export type WebhookTokenVerifyRequest = Omit<WebhookVerifyRequest, "algorithm" | "encoding" | "message" | "signatures"> & {
+    readonly token: string;
+};
+export type WebhookTokenVerifier = (request: WebhookTokenVerifyRequest) => Promise<WebhookVerification>;
+/** How long the service waits for the backend's answer before answering 503. */
+export declare const WEBHOOK_VERIFY_TIMEOUT_MS = 3000;
+/**
+ * The verifier of a deployed ontology service: `POST
+ * /api/internal/v1/workspaces/{id}/secrets/{name}/verify-hmac` on SegmentStream with the request's
+ * Vercel OIDC token, admitted only for the secrets the deployed ontology's webhooks name.
+ */
+export declare function deployedWebhookVerifier(environment: {
+    readonly segmentstreamUrl: string;
+    readonly workspaceId: string;
+    readonly organizationId: string;
+    readonly deploymentId?: string | undefined;
+    readonly previewCredential?: Redacted.Redacted<string> | undefined;
+}, fetchImpl?: typeof fetch): WebhookVerifier;
+/** Meta registration token comparison, authenticated by the deployment identity like HMAC checks. */
+export declare function deployedWebhookTokenVerifier(environment: {
+    readonly segmentstreamUrl: string;
+    readonly workspaceId: string;
+    readonly organizationId: string;
+    readonly deploymentId?: string | undefined;
+    readonly previewCredential?: Redacted.Redacted<string> | undefined;
+}, fetchImpl?: typeof fetch): WebhookTokenVerifier;
+/** The bytes a scheme's signatures cover and the signatures to compare, or why it refused. */
+export type SignedContent = {
+    readonly ok: true;
+    readonly message: Uint8Array;
+    readonly signatures: ReadonlyArray<string>;
+} | {
+    readonly ok: false;
+    readonly reason: "signature_missing" | "signature_malformed" | "signature_stale";
+};
+/** A scheme: what was signed and with which signatures, read from the request alone. */
+export type SignatureScheme = (headers: Readonly<Record<string, string | undefined>>, body: Uint8Array, receivedAt: Date) => SignedContent;
+/** How far Stripe's `t` may be from the time the delivery arrived, in seconds. */
+export declare const STRIPE_TOLERANCE_SECONDS = 300;
+/**
+ * Stripe's `Stripe-Signature`: `t=<unix seconds>` and one or more `v1=<hex>`. The signed bytes are
+ * `<t>.` followed by the raw body; the HMAC is SHA-256 keyed with the whole `whsec_…` string.
+ */
+export declare const stripeSignature: SignatureScheme;
+/** Meta signs exactly the raw body; its app secret stays in the backend. */
+export declare const metaSignature: SignatureScheme;
+/** Every scheme the SDK checks, by the name a declaration uses. */
+export declare const SIGNATURE_SCHEMES: Readonly<Record<WebhookSignatureScheme, SignatureScheme>>;
+/**
+ * The request's body, read up to `limit` bytes: `too_large` without reading further, or
+ * `unreadable` when the client went away.
+ */
+export declare function readWebhookBody(request: HttpServerRequest.HttpServerRequest, limit: number): Effect.Effect<Uint8Array | "too_large" | "unreadable">;
+/** The body as UTF-8 text, or `undefined` when it is not valid UTF-8. */
+export declare function utf8Text(body: Uint8Array): string | undefined;
+/** Refused signatures one client address may send a webhook per minute before it is throttled. */
+export declare const MAX_REFUSED_SIGNATURES_PER_MINUTE = 20;
+/**
+ * Counts refused signatures per client address and webhook in this instance's memory. Once a
+ * client is over the limit it is answered 429 until its window ends, without a backend call.
+ */
+export declare function signatureRefusals(now?: () => number): {
+    /** Seconds the client must wait, or `undefined` when it may be checked. */
+    blocked(key: string): number | undefined;
+    refused(key: string): void;
+};

package/dist/service/webhooks.js

@@ -0,0 +1,233 @@
+import { Effect, Redacted } from "effect";
+import { fixedWindowLimiter } from "./rate-limit.js";
+/** How long the service waits for the backend's answer before answering 503. */
+export const WEBHOOK_VERIFY_TIMEOUT_MS = 3_000;
+/**
+ * The verifier of a deployed ontology service: `POST
+ * /api/internal/v1/workspaces/{id}/secrets/{name}/verify-hmac` on SegmentStream with the request's
+ * Vercel OIDC token, admitted only for the secrets the deployed ontology's webhooks name.
+ */
+export function deployedWebhookVerifier(environment, fetchImpl = fetch) {
+    const verify = deployedSecretVerifier(environment, "verify-hmac", fetchImpl);
+    return (request) => verify(request, {
+        algorithm: request.algorithm,
+        encoding: request.encoding,
+        message: Buffer.from(request.message).toString("base64"),
+        signatures: request.signatures,
+    });
+}
+/** Meta registration token comparison, authenticated by the deployment identity like HMAC checks. */
+export function deployedWebhookTokenVerifier(environment, fetchImpl = fetch) {
+    const verify = deployedSecretVerifier(environment, "verify-token", fetchImpl);
+    return (request) => verify(request, { token: request.token });
+}
+function deployedSecretVerifier(environment, operation, fetchImpl) {
+    const base = `${environment.segmentstreamUrl}/api/internal/v1/workspaces/` +
+        `${encodeURIComponent(environment.workspaceId)}/secrets/`;
+    return async (request, payload) => {
+        if (request.identityToken === undefined || request.identityToken === "") {
+            return {
+                outcome: "unavailable",
+                cause: new Error("The request carries no Vercel OIDC token for webhook verification."),
+            };
+        }
+        try {
+            const response = await fetchImpl(`${base}${encodeURIComponent(request.secret)}/${operation}`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    "x-segmentstream-runtime-identity": request.identityToken,
+                    "x-segmentstream-organization-id": environment.organizationId,
+                    "x-segmentstream-request-id": request.requestId,
+                    ...(environment.deploymentId
+                        ? { "x-segmentstream-ontology-deployment-id": environment.deploymentId }
+                        : {}),
+                    ...(environment.previewCredential
+                        ? {
+                            "x-segmentstream-preview-credential": Redacted.value(environment.previewCredential),
+                        }
+                        : {}),
+                },
+                body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(WEBHOOK_VERIFY_TIMEOUT_MS),
+            });
+            const text = await response.text();
+            let body;
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                body = undefined;
+            }
+            const answer = typeof body === "object" && body !== null ? body : {};
+            if (response.status === 404 && answer.error === "secret_not_found") {
+                return { outcome: "secret_missing" };
+            }
+            if (response.ok && typeof answer.valid === "boolean") {
+                return { outcome: answer.valid ? "valid" : "invalid" };
+            }
+            return {
+                outcome: "unavailable",
+                status: response.status,
+                cause: new Error(`SegmentStream answered ${response.status} to the signature check: ${text.slice(0, 500)}`),
+            };
+        }
+        catch (cause) {
+            return { outcome: "unavailable", cause };
+        }
+    };
+}
+/** How far Stripe's `t` may be from the time the delivery arrived, in seconds. */
+export const STRIPE_TOLERANCE_SECONDS = 300;
+/** The most signatures of one delivery that are sent to the backend. */
+const MAX_SIGNATURES = 5;
+/**
+ * Stripe's `Stripe-Signature`: `t=<unix seconds>` and one or more `v1=<hex>`. The signed bytes are
+ * `<t>.` followed by the raw body; the HMAC is SHA-256 keyed with the whole `whsec_…` string.
+ */
+export const stripeSignature = (headers, body, receivedAt) => {
+    const header = headers["stripe-signature"];
+    if (header === undefined || header.trim() === "") {
+        return { ok: false, reason: "signature_missing" };
+    }
+    let timestamp;
+    const signatures = [];
+    for (const part of header.split(",")) {
+        const separator = part.indexOf("=");
+        if (separator <= 0) {
+            continue;
+        }
+        const key = part.slice(0, separator).trim();
+        const value = part.slice(separator + 1).trim();
+        if (key === "t") {
+            timestamp = value;
+        }
+        else if (key === "v1" &&
+            /^[0-9a-f]{64}$/i.test(value) &&
+            signatures.length < MAX_SIGNATURES) {
+            signatures.push(value.toLowerCase());
+        }
+    }
+    if (timestamp === undefined || !/^\d{1,12}$/.test(timestamp) || signatures.length === 0) {
+        return { ok: false, reason: "signature_malformed" };
+    }
+    if (Math.abs(receivedAt.getTime() / 1000 - Number(timestamp)) > STRIPE_TOLERANCE_SECONDS) {
+        return { ok: false, reason: "signature_stale" };
+    }
+    const prefix = new TextEncoder().encode(`${timestamp}.`);
+    const message = new Uint8Array(prefix.length + body.length);
+    message.set(prefix);
+    message.set(body, prefix.length);
+    return { ok: true, message, signatures };
+};
+/** Meta signs exactly the raw body; its app secret stays in the backend. */
+export const metaSignature = (headers, body) => {
+    const header = headers["x-hub-signature-256"];
+    if (header === undefined || header === "") {
+        return { ok: false, reason: "signature_missing" };
+    }
+    if (!/^sha256=[0-9a-f]{64}$/i.test(header)) {
+        return { ok: false, reason: "signature_malformed" };
+    }
+    return { ok: true, message: body, signatures: [header.slice(7).toLowerCase()] };
+};
+/** Every scheme the SDK checks, by the name a declaration uses. */
+export const SIGNATURE_SCHEMES = {
+    stripe: stripeSignature,
+    meta: metaSignature,
+};
+/**
+ * The request's body, read up to `limit` bytes: `too_large` without reading further, or
+ * `unreadable` when the client went away.
+ */
+export function readWebhookBody(request, limit) {
+    const declared = Number(request.headers["content-length"]);
+    if (Number.isFinite(declared) && declared > limit) {
+        return Effect.succeed("too_large");
+    }
+    const source = request.source;
+    if (source instanceof Request) {
+        return Effect.promise(() => readCapped(source, limit));
+    }
+    return request.arrayBuffer.pipe(Effect.map((buffer) => buffer.byteLength > limit ? "too_large" : new Uint8Array(buffer)), Effect.orElseSucceed(() => "unreadable"));
+}
+async function readCapped(request, limit) {
+    if (request.body === null) {
+        return new Uint8Array();
+    }
+    const reader = request.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            size += value.byteLength;
+            if (size > limit) {
+                await reader.cancel().catch(() => undefined);
+                return "too_large";
+            }
+            chunks.push(value);
+        }
+    }
+    catch {
+        return "unreadable";
+    }
+    const body = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return body;
+}
+/** The body as UTF-8 text, or `undefined` when it is not valid UTF-8. */
+export function utf8Text(body) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(body);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Refused signatures one client address may send a webhook per minute before it is throttled. */
+export const MAX_REFUSED_SIGNATURES_PER_MINUTE = 20;
+/**
+ * Counts refused signatures per client address and webhook in this instance's memory. Once a
+ * client is over the limit it is answered 429 until its window ends, without a backend call.
+ */
+export function signatureRefusals(now = Date.now) {
+    const limiter = fixedWindowLimiter({
+        limit: MAX_REFUSED_SIGNATURES_PER_MINUTE,
+        windowMs: 60_000,
+        maxKeys: 10_000,
+    });
+    const blockedUntil = new Map();
+    return {
+        /** Seconds the client must wait, or `undefined` when it may be checked. */
+        blocked(key) {
+            const until = blockedUntil.get(key);
+            const current = now();
+            if (until === undefined) {
+                return undefined;
+            }
+            if (until <= current) {
+                blockedUntil.delete(key);
+                return undefined;
+            }
+            return Math.max(1, Math.ceil((until - current) / 1000));
+        },
+        refused(key) {
+            const current = now();
+            const wait = limiter.take(key, current);
+            if (wait !== undefined) {
+                if (blockedUntil.size >= 10_000) {
+                    blockedUntil.clear();
+                }
+                blockedUntil.set(key, current + wait * 1000);
+            }
+        },
+    };
+}

package/dist/service/workflow-admission-provider.d.ts

@@ -0,0 +1,31 @@
+import { type World } from "@workflow/world";
+export interface WorkflowProviderReservation {
+    readonly runId: string;
+    readonly deploymentId: string;
+    readonly namespace: string;
+    readonly region?: string;
+}
+export interface WorkflowProviderAdmission {
+    readonly reservation: WorkflowProviderReservation;
+    /** Random, immutable identity of the database reservation, allocated under its lock. */
+    readonly admissionId: string;
+    readonly attributes?: Readonly<Record<string, string>>;
+}
+export declare class WorkflowAdmissionBindingError extends Error {
+    readonly runId: string;
+    readonly reason: string;
+    readonly name = "WorkflowAdmissionBindingError";
+    constructor(runId: string, reason: string);
+}
+/** Allocate once, then persist the entire result before any call to startReservedWorkflowRun. */
+export declare function allocateWorkflowRun(world: World, options: Omit<WorkflowProviderReservation, "runId">): Promise<WorkflowProviderReservation>;
+/**
+ * Dispatch the database's immutable reservation through the public World override.
+ * A failed acknowledgement is uncertain: callers must retry this same reservation.
+ * This helper supplies neither a reservation store nor permission to cross a cutover fence.
+ */
+export declare function startReservedWorkflowRun(world: World, workflow: {
+    readonly workflowId: string;
+}, args: ReadonlyArray<unknown>, options: WorkflowProviderAdmission): Promise<{
+    readonly runId: string;
+}>;