@fungi.computer/oyster 0.0.0-stage → 0.0.1

package/dist/testing/capabilities.js

@@ -0,0 +1,130 @@
+import { Hono } from "hono";
+import * as Schema from "effect/Schema";
+import { releaseSchema } from "@fungi.computer/puffball/effect";
+import { parseArtifactRef, parseSha256Digest } from "@fungi.computer/puffball";
+import { createAppBuild, emptyAppDeclaration, } from "@fungi.computer/puffball/app";
+import { computerList } from "@fungi.computer/agar/computer";
+import { agentApprovalRoutes } from "../agents.js";
+import { fileCapabilities } from "../files.js";
+import { createOyster, } from "../host.js";
+import { instanceIds } from "../index.js";
+import { sha256, verifyRelease } from "../release.js";
+import { approvedInstallation } from "./installation.js";
+/** One Oyster host with a single installation whose capability grants the options shape. */
+export async function capabilityFixture(options = {}) {
+    const artifacts = new Map();
+    async function put(bytes) {
+        const digest = parseSha256Digest(await sha256(bytes));
+        const artifactRef = parseArtifactRef(`artifact:sha256-${digest.slice(7)}`);
+        artifacts.set(artifactRef, bytes);
+        return { artifactRef, digest };
+    }
+    const encode = (text) => new TextEncoder().encode(text);
+    const uiBytes = encode("<!doctype html><title>Capability fixture</title>");
+    const ui = {
+        ...(await put(uiBytes)),
+        version: "fixture",
+        byteLength: uiBytes.length,
+        mediaType: "text/html; charset=utf-8",
+    };
+    async function release(releaseId, capabilities) {
+        const root = await put(encode(JSON.stringify(createAppBuild(ui, null, { capabilities, handlers: [], roles: [] }))));
+        return Schema.decodeUnknownSync(releaseSchema)({
+            releaseId,
+            appId: "app_capability",
+            artifact: {
+                artifactRef: root.artifactRef,
+                artifactDigest: root.digest,
+                provenance: {
+                    sourceRevision: `git:${"a".repeat(40)}`,
+                    sourceTreeDigest: root.digest,
+                    buildRecipeDigest: root.digest,
+                },
+            },
+        });
+    }
+    const routes = new Hono().post("/list", (context) => context.json({ entries: [] }));
+    const capabilities = options.adapters ??
+        (options.fileSource
+            ? fileCapabilities(options.fileSource)
+            : [
+                {
+                    id: computerList.id,
+                    permission: "computer.list",
+                    version: computerList.version,
+                    base: "/probe/",
+                    routes,
+                    methods: { list: { kind: "json", method: "POST", path: "list" } },
+                },
+            ]);
+    const declaredRelease = await release("rel_declared", options.declared === false
+        ? []
+        : (options.capabilities ?? ["computer.list"]));
+    const declaration = (await verifyRelease({
+        get: (ref) => Promise.resolve(artifacts.get(ref) ?? null),
+        put: () => Promise.reject(new Error("Fixture artifacts are read-only")),
+    }, declaredRelease)).declaration;
+    let installation = await approvedInstallation({
+        installationId: "capability-fixture",
+        instanceId: instanceIds.instance.generate(),
+        release: declaredRelease,
+        declaration: declaration ?? emptyAppDeclaration,
+        descriptors: capabilities,
+    });
+    if (options.admitted === false)
+        installation = { ...installation, approvedGrants: [], approval: null };
+    // An anonymous reader reaches only a public App, as the host's visitor.
+    if (options.visitor)
+        installation = { ...installation, visibility: "public" };
+    const readOnly = () => Promise.reject(new Error("Fixture installations are read-only"));
+    const base = {
+        auth: {
+            resolve: () => Promise.reject(new Error("Capability fixture resolves no actor")),
+            authenticate: options.authenticate ??
+                ((request) => Promise.resolve(options.visitor || request.headers.get("x-who") === "visitor"
+                    ? { kind: "refused", status: 401 }
+                    : {
+                        kind: "admitted",
+                        principal: {
+                            actor: { kind: "member", memberId: "owner" },
+                            role: "owner",
+                        },
+                    })),
+        },
+        artifacts: {
+            get: (ref) => Promise.resolve(artifacts.get(ref) ?? null),
+            put: () => Promise.reject(new Error("Fixture artifacts are read-only")),
+        },
+        installations: {
+            list: () => Promise.resolve([installation]),
+            get: (id) => Promise.resolve(id === installation.installationId ? installation : null),
+            put: readOnly,
+            compareAndPut: readOnly,
+        },
+        instances: {
+            get: () => {
+                throw new Error("Capability routes must not execute an App backend");
+            },
+        },
+        capabilities,
+    };
+    const host = options.agents === undefined
+        ? base
+        : { ...base, ownerRoutes: agentApprovalRoutes(options.agents) };
+    const app = createOyster(host);
+    return {
+        app,
+        page: () => app.request("https://oyster.test/apps/capability-fixture/"),
+        request: () => app.request("https://oyster.test/probe/list", {
+            method: "POST",
+            headers: { "X-Oyster-Installation": installation.installationId },
+        }),
+        async removeDeclaration() {
+            installation = {
+                ...installation,
+                release: await release("rel_undeclared", []),
+                authorityVersion: installation.authorityVersion + 1,
+            };
+        },
+    };
+}

package/dist/testing/catalog.d.ts

@@ -0,0 +1,3 @@
+/** Digest-verifying local catalog shared by native App host proofs. */
+export declare function createFixtureCatalog(encoded: string): import("@fungi.computer/puffball/effect").AppReleaseCore;
+export declare function seedFixtureCatalog(encoded: string, catalog: ReturnType<typeof createFixtureCatalog>): Promise<void>;

package/dist/testing/catalog.js

@@ -0,0 +1,53 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { createAppReleaseCore, createDeterministicMemoryAppReleaseStore, adaptPromiseAppReleaseStore, releaseSchema, adaptPromiseArtifactReader, } from "@fungi.computer/puffball/effect";
+import { parseSha256Digest } from "@fungi.computer/puffball";
+import { appMediaType } from "@fungi.computer/puffball/app";
+import { backendMediaType } from "@fungi.computer/puffball/backend";
+// The Publisher's artifact store: every Release root and child object by ref.
+const fixtureSchema = Schema.Struct({
+    releases: Schema.Array(releaseSchema),
+    objects: Schema.Record(Schema.String, Schema.Struct({
+        mediaType: Schema.Literals([
+            appMediaType,
+            backendMediaType,
+            "text/html; charset=utf-8",
+        ]),
+        body: Schema.String,
+    })),
+});
+const hex = (bytes) => Array.from(new Uint8Array(bytes), (b) => b.toString(16).padStart(2, "0")).join("");
+/** Digest-verifying local catalog shared by native App host proofs. */
+export function createFixtureCatalog(encoded) {
+    const fixture = Schema.decodeUnknownSync(Schema.fromJsonString(fixtureSchema))(encoded);
+    return createAppReleaseCore({
+        store: adaptPromiseAppReleaseStore(createDeterministicMemoryAppReleaseStore()),
+        artifactReader: adaptPromiseArtifactReader({
+            read: async ({ artifactRef, expectedDigest }) => {
+                const object = fixture.objects[artifactRef];
+                if (!object)
+                    return { kind: "missing" };
+                const bytes = new TextEncoder().encode(object.body);
+                const digest = parseSha256Digest(`sha256:${hex(await crypto.subtle.digest("SHA-256", bytes))}`);
+                if (digest !== expectedDigest)
+                    return { kind: "digest-mismatch", actualDigest: digest };
+                return {
+                    kind: "verified",
+                    digest,
+                    mediaType: object.mediaType,
+                    bytes: { byteLength: bytes.length, copy: () => bytes.slice() },
+                    byteLength: bytes.length,
+                };
+            },
+        }),
+        artifactPolicy: { maxBytes: 1024 * 1024 },
+    });
+}
+export async function seedFixtureCatalog(encoded, catalog) {
+    const fixture = Schema.decodeUnknownSync(Schema.fromJsonString(fixtureSchema))(encoded);
+    for (const release of fixture.releases) {
+        await Effect.runPromise(catalog.createApp({ appId: release.appId }));
+        await Effect.runPromise(catalog.createRelease(release));
+        await Effect.runPromise(catalog.verifyReleaseArtifact(release.releaseId));
+    }
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Test kit for Oyster hosts and Apps: fixture installations, a capability
+ * host, a digest-verifying release catalog and the frame binding wire.
+ * The `cloudflare:workers` stand-in lives at `./testing/workers-runtime`.
+ */
+export { approvedInstallation } from "./installation.js";
+export { capabilityFixture, type CapabilityFixtureOptions, } from "./capabilities.js";
+export { createFixtureCatalog, seedFixtureCatalog } from "./catalog.js";
+export { createFrameBindingWire, type FrameBindingReply, type FrameBindingWire, } from "../frame-binding-wire.js";
+export { startNativeWorker, type NativeWorker, type NativeWorkerOptions, } from "./native-worker.js";

package/dist/testing/index.js

@@ -0,0 +1,10 @@
+/**
+ * Test kit for Oyster hosts and Apps: fixture installations, a capability
+ * host, a digest-verifying release catalog and the frame binding wire.
+ * The `cloudflare:workers` stand-in lives at `./testing/workers-runtime`.
+ */
+export { approvedInstallation } from "./installation.js";
+export { capabilityFixture, } from "./capabilities.js";
+export { createFixtureCatalog, seedFixtureCatalog } from "./catalog.js";
+export { createFrameBindingWire, } from "../frame-binding-wire.js";
+export { startNativeWorker, } from "./native-worker.js";

package/dist/testing/installation.d.ts

@@ -0,0 +1,11 @@
+import type { AppDeclaration } from "@fungi.computer/puffball/app";
+import { type CapabilityOperationDescriptor, type Installation } from "../apps/index.js";
+/** Build fixture state through the same approval owner used by installation routes. */
+export declare function approvedInstallation(input: Readonly<{
+    release: Installation["release"];
+    declaration: AppDeclaration;
+    installationId: string;
+    instanceId: Installation["instanceId"];
+    descriptors?: readonly CapabilityOperationDescriptor[];
+    visibility?: Installation["visibility"];
+}>): Promise<Installation>;

package/dist/testing/installation.js

@@ -0,0 +1,25 @@
+import * as Result from "effect/Result";
+import { applyInstallationCommand, deriveDeclaredOperations, } from "../apps/index.js";
+/** Build fixture state through the same approval owner used by installation routes. */
+export async function approvedInstallation(input) {
+    const result = applyInstallationCommand(null, {
+        kind: "install",
+        release: input.release,
+        releasePin: "pinned",
+        grants: "declared",
+    }, {
+        by: { kind: "member", memberId: "fixture-owner" },
+        role: "owner",
+        expectedVersion: null,
+        declaration: input.declaration,
+        declaredOperations: await deriveDeclaredOperations(input.release, input.declaration, input.descriptors ?? []),
+        now: 1000,
+        identity: {
+            installationId: input.installationId,
+            instanceId: input.instanceId,
+        },
+    });
+    if (Result.isFailure(result))
+        throw new Error(result.failure.code);
+    return { ...result.success.next, visibility: input.visibility ?? "private" };
+}

package/dist/testing/native-worker.d.ts

@@ -0,0 +1,21 @@
+/** One `wrangler dev --local` launch: its config, vars and optional fixed port. */
+export type NativeWorkerOptions = Readonly<{
+    /** The Worker's wrangler config. */
+    configPath: string;
+    /** Plain-text vars passed with `--var`. */
+    vars: Readonly<Record<string, string>>;
+    /** A fixed port; 0 (the default) reserves a free one. */
+    port?: number;
+    /** Append the Worker's output to this file, which must have mode 0600. */
+    logFile?: string;
+}>;
+/** A ready local Worker; `stop` ends it and removes its persisted state. */
+export type NativeWorker = Readonly<{
+    port: number;
+    stop: () => Promise<void>;
+}>;
+/**
+ * Start `wrangler dev --local` on 127.0.0.1 with fresh persisted state and
+ * resolve once its root answers, or reject after 60 seconds.
+ */
+export declare function startNativeWorker({ configPath, vars, port: requestedPort, logFile, }: NativeWorkerOptions): Promise<NativeWorker>;

package/dist/testing/native-worker.js

@@ -0,0 +1,106 @@
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { closeSync, fstatSync, openSync } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { createServer } from "node:http";
+import { tmpdir } from "node:os";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import process from "node:process";
+import { setTimeout as delay } from "node:timers/promises";
+import { z } from "zod";
+// The consumer's own wrangler (an optional peer), resolved beside its config.
+const wranglerBin = (configPath) => join(dirname(createRequire(configPath).resolve("wrangler/package.json")), "bin/wrangler.js");
+/**
+ * Start `wrangler dev --local` on 127.0.0.1 with fresh persisted state and
+ * resolve once its root answers, or reject after 60 seconds.
+ */
+export async function startNativeWorker({ configPath, vars, port: requestedPort = 0, logFile, }) {
+    const reservation = createServer();
+    reservation.listen(requestedPort, "127.0.0.1");
+    await once(reservation, "listening");
+    const { port } = z
+        .object({ port: z.number().int().positive() })
+        .parse(reservation.address());
+    await new Promise((resolve) => {
+        reservation.close(() => {
+            resolve();
+        });
+    });
+    const state = await mkdtemp(join(tmpdir(), "oyster-native-worker-"));
+    const logDescriptor = logFile === undefined ? undefined : openSync(logFile, "a", 0o600);
+    const child = (() => {
+        try {
+            if (logDescriptor !== undefined &&
+                (fstatSync(logDescriptor).mode & 0o777) !== 0o600)
+                throw new Error("Worker proof log must have mode 0600");
+            return spawn(process.execPath, [
+                wranglerBin(configPath),
+                "dev",
+                "--config",
+                configPath,
+                "--local",
+                "--ip",
+                "127.0.0.1",
+                "--port",
+                String(port),
+                "--persist-to",
+                state,
+                ...Object.entries(vars).flatMap(([name, value]) => [
+                    "--var",
+                    `${name}:${value}`,
+                ]),
+            ], {
+                stdio: logDescriptor === undefined
+                    ? "ignore"
+                    : ["ignore", logDescriptor, logDescriptor],
+            });
+        }
+        finally {
+            if (logDescriptor !== undefined)
+                closeSync(logDescriptor);
+        }
+    })();
+    const startup = { error: null };
+    child.on("error", (cause) => {
+        startup.error = cause;
+    });
+    const stop = async () => {
+        if (child.exitCode === null &&
+            child.signalCode === null &&
+            startup.error === null) {
+            const exited = once(child, "exit");
+            child.kill("SIGTERM");
+            await exited;
+        }
+        await rm(state, { recursive: true, force: true });
+    };
+    try {
+        const deadline = Date.now() + 60_000;
+        while (Date.now() < deadline) {
+            if (startup.error !== null)
+                throw new Error("Worker proof startup failed", {
+                    cause: startup.error,
+                });
+            if (child.exitCode !== null || child.signalCode !== null)
+                throw new Error(`Worker proof exited before readiness (${String(child.exitCode ?? child.signalCode)})`);
+            try {
+                const response = await fetch(`http://127.0.0.1:${String(port)}/`, {
+                    signal: AbortSignal.timeout(1000),
+                });
+                await response.body?.cancel();
+                return { port, stop };
+            }
+            catch (cause) {
+                if (Date.now() >= deadline)
+                    throw new Error("Worker proof readiness timeout", { cause });
+            }
+            await delay(100);
+        }
+        throw new Error("Worker proof readiness timeout");
+    }
+    catch (cause) {
+        await stop();
+        throw cause;
+    }
+}

package/dist/testing/worker.d.ts

@@ -0,0 +1,18 @@
+import { DurableObject } from "cloudflare:workers";
+export type Env = {
+    LOADER: WorkerLoader;
+    INSTANCES: DurableObjectNamespace<ConfiguredInstance>;
+    CATALOG_FIXTURE: string;
+    OWNER: string;
+};
+export declare class ConfiguredInstance extends DurableObject<Env> {
+    private readonly catalog;
+    private readonly runtime;
+    private readonly gate;
+    constructor(ctx: DurableObjectState, env: Env);
+    fetch(request: Request): Promise<Response>;
+}
+declare const _default: {
+    fetch(request: Request, env: Env): Response | Promise<Response>;
+};
+export default _default;

package/dist/testing/worker.js

@@ -0,0 +1,67 @@
+import { DurableObject } from "cloudflare:workers";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { resolveDurableBackend } from "@fungi.computer/puffball/backend";
+import { createFixtureCatalog, seedFixtureCatalog } from "./catalog.js";
+import { createCloudflareAppInstance, createCloudflareInvocationGate, } from "../cloudflare.js";
+import { invocationFactsSchema, APP_INVOCATION_CEILING_MS, } from "../invocation.js";
+import { selectionSchema, instanceIdSchema } from "../index.js";
+// Configured test admission and catalog persistence stand-ins; not Team/Grant APIs.
+export class ConfiguredInstance extends DurableObject {
+    catalog;
+    runtime;
+    gate;
+    constructor(ctx, env) {
+        super(ctx, env);
+        this.catalog = createFixtureCatalog(env.CATALOG_FIXTURE);
+        this.gate = createCloudflareInvocationGate(ctx, () => Promise.resolve());
+        void ctx.blockConcurrencyWhile(() => seedFixtureCatalog(env.CATALOG_FIXTURE, this.catalog));
+        this.runtime = createCloudflareAppInstance(ctx, env.LOADER, (id) => resolveDurableBackend(this.catalog, id).pipe(Effect.mapError((error) => new Error(String(error)))), () => ({}));
+    }
+    async fetch(request) {
+        const url = new URL(request.url);
+        try {
+            const authority = Schema.decodeUnknownSync(Schema.fromJsonString(selectionSchema))(request.headers.get("x-test-admission"));
+            if (authority.owner.kind !== "deployment" ||
+                authority.owner.id !== this.env.OWNER ||
+                authority.instanceId !== this.ctx.id.name)
+                return new Response("Denied", { status: 403 });
+            if (url.pathname.endsWith("/select"))
+                return Response.json(await Effect.runPromise(this.runtime.apply({ ...authority, status: "enabled" })));
+            if (url.pathname.endsWith("/disable"))
+                return Response.json(await Effect.runPromise(this.runtime.apply({ ...authority, status: "disabled" })));
+            if (url.pathname.endsWith("/delete"))
+                return Response.json(await Effect.runPromise(this.runtime.apply({ ...authority, status: "deleted" })));
+            const backend = await Effect.runPromise(resolveDurableBackend(this.catalog, authority.releaseId));
+            const facts = Schema.decodeUnknownSync(invocationFactsSchema)({
+                instanceId: authority.instanceId,
+                selection: authority,
+                artifactDigest: backend.digest,
+                subject: {
+                    kind: "call",
+                    context: {
+                        computerId: null,
+                        actor: { kind: "member", memberId: this.env.OWNER },
+                    },
+                },
+                grants: [],
+                deadlineAt: Date.now() + APP_INVOCATION_CEILING_MS,
+                ancestry: [],
+            });
+            return await this.gate.run(facts, undefined, (frame) => Effect.runPromise(this.runtime.fetch(frame, request)));
+        }
+        catch {
+            return new Response("Unavailable or denied", { status: 409 });
+        }
+    }
+}
+const route = new URLPattern({ pathname: "/instances/:id/:operation" });
+export default {
+    fetch(request, env) {
+        const match = route.exec(request.url);
+        if (!match)
+            return new Response("Not found", { status: 404 });
+        const id = Schema.decodeUnknownSync(instanceIdSchema)(match.pathname.groups.id);
+        return env.INSTANCES.getByName(id).fetch(request);
+    },
+};

package/dist/testing/workers-runtime.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Node stand-in for `cloudflare:workers` and `cloudflare:workflows`: only the
+ * platform constructors are replaced, so adapters and SQLite run unchanged.
+ * Resolve it with `import.meta.resolve("@fungi.computer/oyster/testing/workers-runtime")`
+ * from a module hook.
+ */
+export declare class DurableObject<Env = unknown> {
+    readonly ctx: DurableObjectState;
+    readonly env: Env;
+    constructor(ctx: DurableObjectState, env: Env);
+}
+export declare class WorkerEntrypoint<Env = unknown> {
+    readonly ctx: ExecutionContext;
+    readonly env: Env;
+    constructor(ctx: ExecutionContext, env: Env);
+}
+export declare class WorkflowEntrypoint<Env = unknown> {
+    readonly ctx: ExecutionContext;
+    readonly env: Env;
+    constructor(ctx: ExecutionContext, env: Env);
+}
+export declare class NonRetryableError extends Error {
+}
+export { RpcTarget } from "@fungi.computer/capnweb";

package/dist/testing/workers-runtime.js

@@ -0,0 +1,33 @@
+/**
+ * Node stand-in for `cloudflare:workers` and `cloudflare:workflows`: only the
+ * platform constructors are replaced, so adapters and SQLite run unchanged.
+ * Resolve it with `import.meta.resolve("@fungi.computer/oyster/testing/workers-runtime")`
+ * from a module hook.
+ */
+export class DurableObject {
+    ctx;
+    env;
+    constructor(ctx, env) {
+        this.ctx = ctx;
+        this.env = env;
+    }
+}
+export class WorkerEntrypoint {
+    ctx;
+    env;
+    constructor(ctx, env) {
+        this.ctx = ctx;
+        this.env = env;
+    }
+}
+export class WorkflowEntrypoint {
+    ctx;
+    env;
+    constructor(ctx, env) {
+        this.ctx = ctx;
+        this.env = env;
+    }
+}
+export class NonRetryableError extends Error {
+}
+export { RpcTarget } from "@fungi.computer/capnweb";

package/dist/webhook-delivery.d.ts

@@ -0,0 +1,14 @@
+/** HTTP refusals and transport failures both remain eligible for owner retries. */
+export declare function attemptWebhook(target: Readonly<{
+    url: string;
+    secret: string;
+}>, delivery: Readonly<{
+    id: string;
+    type: string;
+    body: string;
+}>): Promise<Readonly<{
+    kind: "response";
+    status: number;
+}> | Readonly<{
+    kind: "transport-error";
+}>>;

package/dist/webhook-delivery.js

@@ -0,0 +1,17 @@
+import { webhookHeaders } from "./git.js";
+/** HTTP refusals and transport failures both remain eligible for owner retries. */
+export async function attemptWebhook(target, delivery) {
+    try {
+        const response = await fetch(target.url, {
+            method: "POST",
+            headers: await webhookHeaders(target.secret, delivery.id, delivery.type, Math.floor(Date.now() / 1000), delivery.body),
+            body: delivery.body,
+            signal: AbortSignal.timeout(10_000),
+        });
+        await response.body?.cancel();
+        return { kind: "response", status: response.status };
+    }
+    catch {
+        return { kind: "transport-error" };
+    }
+}