@fungi.computer/oyster 0.2.0 → 0.3.1

package/dist/webhook-custody.d.ts

@@ -0,0 +1,144 @@
+import { z } from "zod";
+import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
+import { type ArmedWorkflowTrigger } from "@fungi.computer/braid/runtime";
+import type { WebhookDelivery } from "./webhook-ingress.js";
+export declare const workflowWebhookVerifierSchema: z.ZodEnum<{
+    "fungi-v1": "fungi-v1";
+    github: "github";
+    "standard-webhooks": "standard-webhooks";
+}>;
+export type WorkflowWebhookVerifier = z.output<typeof workflowWebhookVerifierSchema>;
+/**
+ * This owner lives INSIDE the Team DO / standalone store. Only verification is
+ * handed to ingress. No read-existing-secret method, master key or generation
+ * derivation exists. Host authentication supplies the principal; owner() must
+ * resolve CURRENT server-side ownership, not trust a caller-supplied role.
+ */
+export declare function workflowWebhookCustody<Principal>(options: {
+    sql: WatchdogSqliteOwner["sql"];
+    transactionSync: WatchdogSqliteOwner["transactionSync"];
+    now(): number;
+    owner(principal: Principal): Promise<string | null>;
+}): {
+    create(principal: Principal, bindingId: string, verifier: WorkflowWebhookVerifier, rawBinding: ArmedWorkflowTrigger): Promise<{
+        readonly kind: "refused";
+    } | {
+        kind: "created";
+        bindingId: string;
+        installationId: string;
+        secret: string | null;
+    }>;
+    rotate(principal: Principal, bindingId: string): Promise<{
+        readonly kind: "refused";
+    } | {
+        kind: "rotated";
+        secret: string | null;
+    }>;
+    retirePrevious(principal: Principal, bindingId: string): Promise<{
+        readonly kind: "refused";
+    } | {
+        kind: "retired";
+    }>;
+    revoke(principal: Principal, bindingId: string): Promise<{
+        readonly kind: "refused";
+    } | {
+        kind: "revoked";
+    }>;
+    list(principal: Principal, after?: string | null): Promise<{
+        bindings: {
+            bindingId: string;
+            verifier: "fungi-v1" | "github" | "standard-webhooks";
+            creator: string;
+            generation: number;
+            previousExpiresAt: number | null;
+        }[];
+        next: string | null;
+    }>;
+    verification: {
+        /** Final owner-store check for an already verified durable reservation. */
+        isActive(bindingId: string): boolean;
+        /** Always does six maintained verifier checks, including unknown IDs. */
+        verify(delivery: WebhookDelivery): {
+            status: "refused";
+            eventId?: undefined;
+            binding?: undefined;
+        } | {
+            status: "ok";
+            eventId: string;
+            binding: {
+                installationId: string;
+                workflowId: string;
+                commit: string;
+                digest: string & {
+                    readonly appReleaseKind: "Sha256Digest";
+                };
+                triggerId: string;
+                bindings: Record<string, string | {
+                    kind: "team-source";
+                }>;
+                armedBy: string;
+                armedVia: {
+                    kind: "connector";
+                    agentId: string;
+                    attachmentId: string;
+                    attachmentVersion: number;
+                } | {
+                    kind: "policy";
+                    agentId: string;
+                    policyRevision: string;
+                    grantorMemberId: string;
+                } | null;
+                grantorMembershipVersion: number;
+                installationAuthority: {
+                    selection: {
+                        instanceId: string;
+                        owner: {
+                            kind: "installation" | "deployment";
+                            id: string;
+                        };
+                        appId: string & {
+                            readonly appReleaseKind: "AppId";
+                        };
+                        releaseId: string & {
+                            readonly appReleaseKind: "ReleaseId";
+                        };
+                        authorityVersion: number;
+                    };
+                    artifactDigest: string & {
+                        readonly appReleaseKind: "Sha256Digest";
+                    };
+                };
+                computerId: string;
+                delivery?: {
+                    readonly agentId: string;
+                    readonly sessionId: string;
+                } | undefined;
+                nodeGitAccess?: readonly {
+                    readonly nodeId: string;
+                    readonly gitAccess: {
+                        repository: {
+                            kind: "installation";
+                            installationId: string;
+                            repository: string;
+                        } | {
+                            kind: "team-source";
+                            repository: string;
+                        };
+                        branches: string[];
+                    } | {
+                        repository: {
+                            kind: "installation";
+                            installationId: string;
+                            repository: string;
+                        } | {
+                            kind: "team-source";
+                            repository: string;
+                        };
+                        access: "read";
+                    };
+                    readonly graphId?: string;
+                }[] | undefined;
+            };
+        };
+    };
+};

package/dist/webhook-custody.js

@@ -0,0 +1,222 @@
+import { createHash, randomBytes } from "node:crypto";
+import { Base64Url } from "effect/encoding";
+import { z } from "zod";
+import { armedWorkflowTriggerSchema, } from "@fungi.computer/braid/runtime";
+import { verifyFungiV1, verifyGithub, verifyStandardWebhooks, standardWebhookSecret, } from "@fungi.computer/veil/event-verifiers";
+export const workflowWebhookVerifierSchema = z.enum([
+    "fungi-v1",
+    "github",
+    "standard-webhooks",
+]);
+const idSchema = z.string().min(1).max(256);
+const keySchema = z.strictObject({
+    secret: z.string().regex(/^[A-Za-z0-9_-]{43}$/u),
+    generation: z.number().int().positive(),
+});
+const rowSchema = z.strictObject({
+    id: idSchema,
+    creator: idSchema,
+    binding: armedWorkflowTriggerSchema,
+    verifier: workflowWebhookVerifierSchema,
+    current: keySchema,
+    previous: keySchema
+        .extend({ expiresAt: z.number().int().nonnegative() })
+        .nullable(),
+});
+const refused = { kind: "refused" };
+const DAY = 24 * 60 * 60 * 1000;
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const verifiers = {
+    "fungi-v1": verifyFungiV1,
+    github: verifyGithub,
+    "standard-webhooks": verifyStandardWebhooks,
+};
+function matchingEvent(row, scheme, current, previous, now) {
+    if (row?.verifier !== scheme)
+        return null;
+    if (current.status === "ok")
+        return current.eventId;
+    if (previous.status === "ok" &&
+        row.previous !== null &&
+        row.previous.expiresAt > now())
+        return previous.eventId;
+    return null;
+}
+/** Evaluate both slots for EVERY scheme; never short-circuit on success. */
+function verifiedEvent(row, request, dummy, now) {
+    let eventId = null;
+    for (const scheme of workflowWebhookVerifierSchema.options) {
+        const current = verifiers[scheme](row?.current.secret ?? dummy, request);
+        const previous = verifiers[scheme](row?.previous?.secret ?? dummy, request);
+        const match = matchingEvent(row, scheme, current, previous, now);
+        if (match !== null)
+            eventId = match;
+    }
+    return eventId;
+}
+function deliveryIdentity(verifier, eventId, body) {
+    // GitHub deliberately retains its unsigned ID plus body hash: accepted
+    // weaker freshness. Neither signatures nor key bytes enter the identity.
+    switch (verifier) {
+        case "github":
+            return hash(JSON.stringify([eventId, hash(body)]));
+        case "fungi-v1":
+            return hash(body);
+        case "standard-webhooks":
+            return hash(eventId);
+    }
+}
+/**
+ * This owner lives INSIDE the Team DO / standalone store. Only verification is
+ * handed to ingress. No read-existing-secret method, master key or generation
+ * derivation exists. Host authentication supplies the principal; owner() must
+ * resolve CURRENT server-side ownership, not trust a caller-supplied role.
+ */
+export function workflowWebhookCustody(options) {
+    const { sql } = options;
+    sql.exec(`CREATE TABLE IF NOT EXISTS oyster_workflow_webhook_keys (
+    id TEXT PRIMARY KEY, record TEXT NOT NULL
+  ) STRICT`);
+    sql.exec(`CREATE TABLE IF NOT EXISTS oyster_workflow_webhook_revoked (
+    id TEXT PRIMARY KEY
+  ) STRICT`);
+    const read = (id) => {
+        const raw = sql
+            .exec("SELECT record FROM oyster_workflow_webhook_keys WHERE id=?", id)
+            .toArray()[0];
+        if (raw === undefined)
+            return null;
+        const envelope = z.object({ record: z.string() }).parse(raw);
+        return rowSchema.parse(JSON.parse(envelope.record));
+    };
+    const write = (row) => {
+        sql.exec("INSERT INTO oyster_workflow_webhook_keys(id,record) VALUES(?,?) ON CONFLICT(id) DO UPDATE SET record=excluded.record", row.id, JSON.stringify(row));
+    };
+    const newKey = (generation) => ({
+        secret: Base64Url.encode(randomBytes(32)),
+        generation,
+    });
+    const dummy = Base64Url.encode(randomBytes(32));
+    const disclosure = (row, actor) => actor !== row.creator
+        ? null
+        : row.verifier === "standard-webhooks"
+            ? standardWebhookSecret(row.current.secret)
+            : row.current.secret;
+    const withOwnedBinding = async (principal, bindingId, update) => {
+        const actor = await options.owner(principal);
+        if (actor === null)
+            return refused;
+        return options.transactionSync(() => {
+            const row = read(idSchema.parse(bindingId));
+            return row === null ? refused : update(row, actor);
+        });
+    };
+    return {
+        async create(principal, bindingId, verifier, rawBinding) {
+            const creator = await options.owner(principal);
+            if (creator === null)
+                return refused;
+            const id = idSchema.parse(bindingId);
+            const scheme = workflowWebhookVerifierSchema.parse(verifier);
+            // Supplied only by the host's existing trigger-arm owner, never ingress.
+            const binding = armedWorkflowTriggerSchema.parse(rawBinding);
+            if (binding.armedBy !== creator || binding.armedVia !== null)
+                return refused;
+            return options.transactionSync(() => {
+                if (read(id) !== null ||
+                    sql
+                        .exec("SELECT id FROM oyster_workflow_webhook_revoked WHERE id=?", id)
+                        .toArray().length > 0)
+                    return refused;
+                const row = rowSchema.parse({
+                    id,
+                    creator,
+                    binding,
+                    verifier: scheme,
+                    current: newKey(1),
+                    previous: null,
+                });
+                write(row);
+                return {
+                    kind: "created",
+                    bindingId: row.id,
+                    installationId: row.binding.installationId,
+                    secret: disclosure(row, creator),
+                };
+            });
+        },
+        async rotate(principal, bindingId) {
+            return withOwnedBinding(principal, bindingId, (row, actor) => {
+                if (row.previous !== null && row.previous.expiresAt > options.now())
+                    return refused;
+                row.previous = { ...row.current, expiresAt: options.now() + DAY };
+                row.current = newKey(row.current.generation + 1);
+                write(row);
+                return { kind: "rotated", secret: disclosure(row, actor) };
+            });
+        },
+        async retirePrevious(principal, bindingId) {
+            return withOwnedBinding(principal, bindingId, (row) => {
+                row.previous = null;
+                write(row);
+                return { kind: "retired" };
+            });
+        },
+        async revoke(principal, bindingId) {
+            return withOwnedBinding(principal, bindingId, (row) => {
+                // Delete ALL key bytes immediately; the tombstone prevents redisclosure.
+                sql.exec("DELETE FROM oyster_workflow_webhook_keys WHERE id=?", row.id);
+                sql.exec("INSERT INTO oyster_workflow_webhook_revoked(id) VALUES(?) ON CONFLICT DO NOTHING", row.id);
+                return { kind: "revoked" };
+            });
+        },
+        async list(principal, after = null) {
+            if ((await options.owner(principal)) === null)
+                return { bindings: [], next: null };
+            const cursor = after === null ? "" : idSchema.parse(after);
+            const rows = sql
+                .exec("SELECT record FROM oyster_workflow_webhook_keys WHERE id>? ORDER BY id LIMIT 101", cursor)
+                .toArray();
+            const bindings = rows.slice(0, 100).map((raw) => {
+                const row = rowSchema.parse(JSON.parse(z.object({ record: z.string() }).parse(raw).record));
+                return {
+                    bindingId: row.id,
+                    verifier: row.verifier,
+                    creator: row.creator,
+                    generation: row.current.generation,
+                    previousExpiresAt: row.previous?.expiresAt ?? null,
+                };
+            });
+            return {
+                bindings,
+                next: rows.length > 100 ? (bindings.at(-1)?.bindingId ?? null) : null,
+            };
+        },
+        verification: {
+            /** Final owner-store check for an already verified durable reservation. */
+            isActive(bindingId) {
+                return read(idSchema.parse(bindingId)) !== null;
+            },
+            /** Always does six maintained verifier checks, including unknown IDs. */
+            verify(delivery) {
+                const row = idSchema.safeParse(delivery.bindingId).success
+                    ? read(delivery.bindingId)
+                    : null;
+                const request = {
+                    headers: delivery.headers,
+                    body: delivery.body,
+                    urlToken: null,
+                    nowSeconds: Math.floor(options.now() / 1000),
+                };
+                const eventId = verifiedEvent(row, request, dummy, () => options.now());
+                if (eventId === null || row === null)
+                    return { status: "refused" };
+                return {
+                    status: "ok",
+                    eventId: deliveryIdentity(row.verifier, eventId, delivery.body),
+                    binding: row.binding,
+                };
+            },
+        },
+    };
+}

package/dist/webhook-ingress.d.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+declare const limitsSchema: z.ZodObject<{
+    bodyBytes: z.ZodNumber;
+    headerBytes: z.ZodNumber;
+    headerCount: z.ZodNumber;
+    readMilliseconds: z.ZodNumber;
+}, z.core.$strict>;
+/** A private defensive ceiling, not a sender-controlled policy or spend cap. */
+export type WebhookIngressLimits = z.output<typeof limitsSchema>;
+export type WebhookDelivery = Readonly<{
+    bindingId: string;
+    headers: Headers;
+    body: Uint8Array;
+}>;
+export type WebhookAdmission = Readonly<{
+    status: "accepted";
+    deliveryId: string;
+}> | Readonly<{
+    status: "refused";
+}>;
+export declare const workflowWebhookRefusal: () => Response;
+/**
+ * The public representation boundary. Rate admission and streaming limits run
+ * before ANY binding access. The private owner verifies and durably admits;
+ * this port cannot read, disclose or choose a key, actor or Computer.
+ */
+export declare function workflowWebhookIngress(options: {
+    limits: WebhookIngressLimits;
+    hostLease(): Promise<null | (() => void)>;
+    deliver(delivery: WebhookDelivery): Promise<WebhookAdmission>;
+    /** Count a fixed failure category; never log producer-controlled error text. */
+    reportReadFailure(kind: "aborted" | "read_failed"): void;
+    /** Fixed operational counter only; private owner errors may contain secrets. */
+    reportOwnerFailure(): void;
+}): (bindingId: string, request: Request) => Promise<Response>;
+export {};

package/dist/webhook-ingress.js

@@ -0,0 +1,146 @@
+import { z } from "zod";
+const limitsSchema = z.strictObject({
+    bodyBytes: z
+        .number()
+        .int()
+        .positive()
+        .max(1024 * 1024),
+    headerBytes: z
+        .number()
+        .int()
+        .positive()
+        .max(32 * 1024),
+    headerCount: z.number().int().positive().max(128),
+    readMilliseconds: z.number().int().positive().max(30_000),
+});
+const failureResponse = (error) => Response.json({ error }, {
+    status: error === "refused" ? 403 : 503,
+    headers: { "cache-control": "no-store" },
+});
+export const workflowWebhookRefusal = () => failureResponse("refused");
+const readFailureKind = (cause) => cause instanceof Error && cause.name === "AbortError"
+    ? "aborted"
+    : "read_failed";
+function headersWithinLimits(headers, limits) {
+    let count = 0;
+    let bytes = 0;
+    const encoder = new TextEncoder();
+    headers.forEach((value, key) => {
+        count++;
+        bytes += encoder.encode(key).byteLength + encoder.encode(value).byteLength;
+    });
+    return count <= limits.headerCount && bytes <= limits.headerBytes;
+}
+/** null means the producer exhausted its byte or read-time allowance. */
+async function readChunks(reader, expired, maximum) {
+    const chunks = [];
+    let length = 0;
+    for (;;) {
+        const part = await Promise.race([reader.read(), expired]);
+        if (part === null)
+            return null;
+        if (part.done)
+            return chunks;
+        const chunk = z.instanceof(Uint8Array).parse(part.value);
+        length += chunk.byteLength;
+        if (length > maximum)
+            return null;
+        chunks.push(chunk);
+    }
+}
+function joinChunks(chunks) {
+    const body = new Uint8Array(chunks.reduce((length, chunk) => length + chunk.byteLength, 0));
+    let offset = 0;
+    for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return body;
+}
+async function readBoundedBody(request, limits, report) {
+    const reader = request.body?.getReader();
+    if (reader === undefined)
+        return new Uint8Array();
+    let timer;
+    const expired = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            resolve(null);
+        }, limits.readMilliseconds);
+    });
+    let chunks;
+    try {
+        chunks = await readChunks(reader, expired, limits.bodyBytes);
+        if (chunks === null) {
+            // Cancellation is not awaited: an untrusted producer can stall it.
+            void reader.cancel().catch((cause) => {
+                report(readFailureKind(cause));
+            });
+        }
+    }
+    catch (cause) {
+        report(readFailureKind(cause));
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+        reader.releaseLock();
+    }
+    return chunks === null ? null : joinChunks(chunks);
+}
+/**
+ * The public representation boundary. Rate admission and streaming limits run
+ * before ANY binding access. The private owner verifies and durably admits;
+ * this port cannot read, disclose or choose a key, actor or Computer.
+ */
+export function workflowWebhookIngress(options) {
+    const limits = limitsSchema.parse(options.limits);
+    const admitHost = async () => {
+        try {
+            const release = await options.hostLease();
+            return release === null
+                ? { status: "refused" }
+                : { status: "admitted", release };
+        }
+        catch {
+            options.reportOwnerFailure();
+            return { status: "unavailable" };
+        }
+    };
+    const deliver = async (delivery) => {
+        try {
+            return await options.deliver(delivery);
+        }
+        catch {
+            options.reportOwnerFailure();
+            return { status: "unavailable" };
+        }
+    };
+    return async (bindingId, request) => {
+        const admission = await admitHost();
+        if (admission.status !== "admitted")
+            return failureResponse(admission.status);
+        const { release } = admission;
+        try {
+            if (request.method !== "POST")
+                return workflowWebhookRefusal();
+            if (!headersWithinLimits(request.headers, limits))
+                return workflowWebhookRefusal();
+            const body = await readBoundedBody(request, limits, (kind) => {
+                options.reportReadFailure(kind);
+            });
+            if (body === null)
+                return workflowWebhookRefusal();
+            const outcome = await deliver({
+                bindingId,
+                headers: request.headers,
+                body,
+            });
+            if (outcome.status !== "accepted")
+                return failureResponse(outcome.status);
+            return Response.json({ accepted: true, deliveryId: outcome.deliveryId }, { status: 202, headers: { "cache-control": "no-store" } });
+        }
+        finally {
+            release();
+        }
+    };
+}

package/dist/webhooks.d.ts

@@ -0,0 +1,111 @@
+import { z } from "zod";
+import { type createTeamWorkflowRuns, type createTeamWorkflowTriggers, type WorkflowInstallationAuthority, type WorkflowTriggerTarget } from "@fungi.computer/braid/runtime";
+import { workflowWebhookCustody, type WorkflowWebhookVerifier } from "./webhook-custody.js";
+import { type WebhookIngressLimits } from "./webhook-ingress.js";
+import { workflowWebhookAbuse } from "./webhook-abuse.js";
+export declare const workflowWebhookCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    operation: z.ZodLiteral<"create">;
+    target: z.ZodObject<{
+        installationId: z.ZodString;
+        workflowId: z.ZodString;
+        commit: z.ZodString;
+        digest: z.ZodString & z.ZodType<string & {
+            readonly appReleaseKind: "Sha256Digest";
+        }, string, z.core.$ZodTypeInternals<string & {
+            readonly appReleaseKind: "Sha256Digest";
+        }, string>>;
+        triggerId: z.ZodString;
+        bindings: z.ZodRecord<z.ZodLazy<z.ZodString>, z.ZodUnion<readonly [z.ZodString, z.ZodLazy<z.ZodObject<{
+            kind: z.ZodLiteral<"team-source">;
+        }, z.core.$strict>>]>>;
+        delivery: z.ZodOptional<z.ZodCustom<{
+            readonly agentId: string;
+            readonly sessionId: string;
+        }, {
+            readonly agentId: string;
+            readonly sessionId: string;
+        }>>;
+    }, z.core.$strict>;
+    computerId: z.ZodString;
+    verifier: z.ZodEnum<{
+        "fungi-v1": "fungi-v1";
+        github: "github";
+        "standard-webhooks": "standard-webhooks";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodEnum<{
+        rotate: "rotate";
+        retirePrevious: "retirePrevious";
+        revoke: "revoke";
+    }>;
+    bindingId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"list">;
+    after: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "operation">;
+/**
+ * Dispatch the hosts' decoded closed control contract. Hosts decode before
+ * resolving installation dependencies; only they supply the current pin and
+ * their captured target.
+ */
+export declare function workflowWebhookControlResponse<Principal>(webhooks: ReturnType<typeof createWorkflowWebhooks<Principal>>, principal: Principal, command: z.output<typeof workflowWebhookCommandSchema>, authorize: (target: WorkflowTriggerTarget, computerId: string) => Promise<{
+    target: WorkflowTriggerTarget;
+    authority: WorkflowInstallationAuthority;
+}>): Promise<Response>;
+/**
+ * Host-owned composition: custody verifies, Braid reserves/maps/starts, and the
+ * host's ordinary idempotent launch ensures its recorded engine instance.
+ * No separate intake state machine or run/settlement store exists here.
+ */
+export declare function createWorkflowWebhooks<Principal>(options: Parameters<typeof workflowWebhookCustody<Principal>>[0] & {
+    scope: Readonly<{
+        host: string;
+        tenant: string;
+    }>;
+    runs: Pick<ReturnType<typeof createTeamWorkflowRuns>, "reserveWebhookDelivery" | "pendingWebhookDeliveries" | "completeWebhookDelivery" | "nextWebhookWake" | "graph">;
+    triggers: Pick<ReturnType<typeof createTeamWorkflowTriggers>, "arm" | "fire">;
+    launch: Parameters<typeof createTeamWorkflowTriggers>[0]["launch"];
+    abuse: Omit<Parameters<typeof workflowWebhookAbuse>[0], "scope">;
+    limits: WebhookIngressLimits;
+    /** Recompute the native alarm from ALL host-owned wake sources. */
+    wake(): Promise<void>;
+    reportFailure(): void;
+}): {
+    receive: (bindingId: string, request: Request) => Promise<Response>;
+    nextWake: () => number | null;
+    create(principal: Principal, target: WorkflowTriggerTarget, computerId: string, authority: WorkflowInstallationAuthority, verifier: WorkflowWebhookVerifier): Promise<{
+        readonly kind: "refused";
+    } | {
+        kind: "created";
+        bindingId: string;
+        installationId: string;
+        secret: string | null;
+    }>;
+    rotate: (principal: Principal, bindingId: string) => Promise<{
+        readonly kind: "refused";
+    } | {
+        kind: "rotated";
+        secret: string | null;
+    }>;
+    retirePrevious: (principal: Principal, bindingId: string) => Promise<{
+        readonly kind: "refused";
+    } | {
+        kind: "retired";
+    }>;
+    revoke: (principal: Principal, bindingId: string) => Promise<{
+        readonly kind: "refused";
+    } | {
+        kind: "revoked";
+    }>;
+    list: (principal: Principal, after?: string | null) => Promise<{
+        bindings: {
+            bindingId: string;
+            verifier: "fungi-v1" | "github" | "standard-webhooks";
+            creator: string;
+            generation: number;
+            previousExpiresAt: number | null;
+        }[];
+        next: string | null;
+    }>;
+    recover(): Promise<void>;
+};