@fungi.computer/oyster 0.0.0-stage → 0.1.0

package/dist/standalone/app-source.js

@@ -0,0 +1,59 @@
+import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import * as Schema from "effect/Schema";
+import { AppInstanceError } from "../index.js";
+import { catalogFrameMethods, oysterAppCatalog, appForkInputSchema, appForkResultSchema, } from "../catalog-frame.js";
+import { parseTemplateSeedClaim, TEMPLATE_SEED_CLAIM_MAX_BYTES, } from "../source/index.js";
+/** `catalogFrameMethods.APPS`'s descriptors already decode to
+ * `OysterBindingResult` at their owner (`catalog-frame.ts`); no re-typing
+ * is needed here. */
+export const appSourceFrameMethods = catalogFrameMethods;
+/** Serve `APPS.catalog`/`APPS.fork`; `fork` is admitted only for the tenant owner,
+ * re-checked here (never trusted from a stale captured frame). */
+export async function dispatchAppSourceBinding(env, scope, frame, method, args) {
+    const registry = env.REGISTRY.getByName(scope.durableName("registry"));
+    if (method === "catalog")
+        return oysterAppCatalog(await registry.directory());
+    if (method !== "fork")
+        throw new AppInstanceError("revoked");
+    if (frame.facts.subject.kind !== "call" ||
+        frame.facts.subject.context.actor.kind !== "member" ||
+        frame.facts.subject.context.role !== "owner")
+        throw new AppInstanceError("revoked");
+    const [input] = Schema.decodeUnknownSync(Schema.Tuple([appForkInputSchema]))(args);
+    const installationId = frame.facts.selection.owner.id;
+    const result = await registry.forkApp({
+        teamId: scope.tenantId,
+        platformAppId: input.platformAppId,
+        installationId,
+        repositoryPrefix: scope.repositoryPrefix(installationId),
+        name: input.name,
+    });
+    return Schema.decodeUnknownSync(appForkResultSchema)(result);
+}
+/** Operator-only: seed one App's editable source template (`install-apps.mjs`).
+ * Mounted under `host.ownerRoutes`, already owner-key-gated for every `/api/*`
+ * path before this handler runs (`host.ts`'s `oysterPrincipalIsOwner` check).
+ * The operator `git push`es the projected source to
+ * `/api/apps/:appId/source.git`, then claims that head here. */
+export function appSourceOwnerRoutes(env, scope) {
+    const routes = new Hono();
+    const registry = () => env.REGISTRY.getByName(scope.durableName("registry"));
+    routes.on(["GET", "POST"], "/api/apps/:appId/source.git/:suffix{info/refs|git-upload-pack|git-receive-pack}", (context) => registry().exchangeTemplateSource(context.req.param("appId"), context.req.param("suffix"), context.req.raw));
+    routes.put("/api/apps/:appId/source", bodyLimit({
+        maxSize: TEMPLATE_SEED_CLAIM_MAX_BYTES,
+        onError: (context) => context.json({ kind: "invalid" }, 413),
+    }), async (context) => {
+        const claim = parseTemplateSeedClaim(await context.req.text());
+        if (claim === null)
+            return context.json({ kind: "invalid" }, 400);
+        const result = await registry().publishSource(context.req.param("appId"), claim, scope.tenantId);
+        const status = result.kind === "recorded" || result.kind === "existing"
+            ? 200
+            : result.kind === "conflict"
+                ? 409
+                : 503;
+        return Response.json(result, { status });
+    });
+    return routes;
+}

package/dist/standalone/builds.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Owner routes for App builds on the standalone's Computer. They run after
+ * the host's owner guard; the build owner is the registry.
+ *
+ * - `PUT /api/apps/:appId/build-source` records an installation repository
+ *   and recipe an App builds from (the recipe is normalized and pinned here).
+ *   Publishing an App's source (`PUT /api/apps/:appId/source`) instead makes
+ *   its template the build source, buildable at the returned seed revision.
+ * - `POST /api/builds` starts a build of that source at one exact commit.
+ * - `GET /api/builds/:jobId` reads it; a finished build carries its Release,
+ *   which the owner installs or selects through the installation routes.
+ */
+import { Hono } from "hono";
+import { type OysterEnv } from "../host.js";
+import type { StandaloneRegistry } from "./registry.js";
+/** The build routes over the tenant registry that owns builds, resolved per
+ * request so mounting the routes reaches no registry. */
+export declare function standaloneBuildRoutes(registryFor: () => DurableObjectStub<StandaloneRegistry>): Hono<OysterEnv>;

package/dist/standalone/builds.js

@@ -0,0 +1,101 @@
+/**
+ * Owner routes for App builds on the standalone's Computer. They run after
+ * the host's owner guard; the build owner is the registry.
+ *
+ * - `PUT /api/apps/:appId/build-source` records an installation repository
+ *   and recipe an App builds from (the recipe is normalized and pinned here).
+ *   Publishing an App's source (`PUT /api/apps/:appId/source`) instead makes
+ *   its template the build source, buildable at the returned seed revision.
+ * - `POST /api/builds` starts a build of that source at one exact commit.
+ * - `GET /api/builds/:jobId` reads it; a finished build carries its Release,
+ *   which the owner installs or selects through the installation routes.
+ */
+import { Hono } from "hono";
+import * as Schema from "effect/Schema";
+import { capturedPinnedRecipeSchema, normalizeAppPublisherRecipe, pinnedRecipeSchema, } from "../build-contract.js";
+import { oysterBuildSourceSchema } from "../app-builds.js";
+import { oysterPrincipalIsOwner } from "../host.js";
+import { appIdSchema, releaseSchema, sourceRevisionSchema, } from "@fungi.computer/puffball/effect";
+const sourceInput = Schema.Struct({
+    installationId: Schema.String,
+    repository: Schema.String,
+    recipe: pinnedRecipeSchema,
+});
+const buildInput = Schema.Struct({
+    appId: appIdSchema,
+    sourceRevision: sourceRevisionSchema,
+});
+/** The build routes over the tenant registry that owns builds, resolved per
+ * request so mounting the routes reaches no registry. */
+export function standaloneBuildRoutes(registryFor) {
+    const routes = new Hono();
+    routes.use("/api/builds/*", async (context, next) => oysterPrincipalIsOwner(context.get("principal"))
+        ? next()
+        : Response.json({ error: "Owner only" }, { status: 403 }));
+    routes.put("/api/apps/:appId/build-source", async (context) => {
+        if (!oysterPrincipalIsOwner(context.get("principal")))
+            return Response.json({ error: "Owner only" }, { status: 403 });
+        let source;
+        try {
+            const appId = Schema.decodeUnknownSync(appIdSchema)(context.req.param("appId"));
+            const input = Schema.decodeUnknownSync(sourceInput, {
+                onExcessProperty: "error",
+            })(await context.req.json());
+            const pinned = normalizeAppPublisherRecipe({
+                appId,
+                recipe: Schema.encodeSync(pinnedRecipeSchema)(input.recipe),
+            });
+            source = Schema.decodeUnknownSync(oysterBuildSourceSchema)({
+                appId,
+                location: {
+                    kind: "installation",
+                    installationId: input.installationId,
+                    repository: input.repository,
+                },
+                recipe: Schema.encodeSync(capturedPinnedRecipeSchema)(pinned.recipe),
+                buildRecipeDigest: pinned.buildRecipeDigest,
+            });
+        }
+        catch {
+            return Response.json({ error: "Invalid build source" }, { status: 400 });
+        }
+        await registryFor().registerBuildSource(source);
+        return new Response(null, { status: 204 });
+    });
+    routes.post("/api/builds", async (context) => {
+        const principal = context.get("principal");
+        if (!oysterPrincipalIsOwner(principal))
+            return Response.json({ error: "Owner only" }, { status: 403 });
+        let input;
+        try {
+            input = Schema.decodeUnknownSync(buildInput, {
+                onExcessProperty: "error",
+            })(await context.req.json());
+        }
+        catch {
+            return Response.json({ error: "Invalid build" }, { status: 400 });
+        }
+        try {
+            const build = await registryFor().startBuild({
+                ...input,
+                requestedBy: principal.actor.memberId,
+            });
+            return Response.json(build, { status: 202 });
+        }
+        catch {
+            return Response.json({ error: "App has no build source" }, { status: 409 });
+        }
+    });
+    routes.get("/api/builds/:jobId", async (context) => {
+        const build = await registryFor().readBuild(context.req.param("jobId"));
+        return build === null
+            ? Response.json({ error: "Not found" }, { status: 404 })
+            : Response.json({
+                ...build,
+                release: build.release === null
+                    ? null
+                    : Schema.encodeUnknownSync(releaseSchema)(build.release),
+            });
+    });
+    return routes;
+}

package/dist/standalone/computer-egress.d.ts

@@ -0,0 +1,37 @@
+import { type BuildGitEvent } from "../build-egress.js";
+import type { CandidateObject, CandidateObjectMediaType, TeamAppCandidateManifest } from "../build-contract.js";
+import { type GitDoorTarget } from "../git.js";
+/** Loopback props the ComputerDO sets; a guest cannot choose them. */
+export type OysterComputerEgressProps = Readonly<{
+    computerObjectId: string;
+}>;
+/** The registry's build admission, for the one Computer this egress serves. */
+export type OysterComputerBuildPort = Readonly<{
+    gitPassFor(target: GitDoorTarget): Promise<string | null>;
+    /** One read-only exchange with a template repository a live job names. */
+    exchangeTemplate(repository: string, request: Request): Promise<Response>;
+    admitBuild(jobId: string): Promise<Readonly<{
+        credentialId: string;
+    }> | null>;
+    /** One object upload for a live job's grant, and its size bound. */
+    admitObject(jobId: string, grant: string): Promise<Readonly<{
+        maxObjectBytes: number;
+    }> | null>;
+    /** Stream one admitted object into the host's Release store. */
+    storeObject(object: CandidateObject, body: ReadableStream<Uint8Array> | null, mediaType: CandidateObjectMediaType): Promise<"stored" | "refused">;
+    submitCandidate(jobId: string, manifest: TeamAppCandidateManifest, grant: string, credentialId: string): Promise<Response>;
+    record(event: BuildGitEvent): Promise<void>;
+}>;
+/**
+ * Admit one intercepted guest request. Oyster Git (on `origin`, or a build
+ * clone on the internal Git host) is handed to `forward`, the Oyster
+ * Worker's own fetch, whose door authenticates it as for any other client.
+ */
+export declare function serveOysterComputerEgress(request: Request, options: Readonly<{
+    origin: string;
+    computerId: string;
+    /** `COMPUTER_PUBLIC_EGRESS`; only `disabled` closes the public lane. */
+    publicEgress: string | undefined;
+    build: OysterComputerBuildPort;
+    forward(request: Request): Promise<Response>;
+}>): Promise<Response>;

package/dist/standalone/computer-egress.js

@@ -0,0 +1,111 @@
+/**
+ * Standalone Oyster's Computer egress: the same host policy Hub's
+ * ComputerEgress decides with. It serves three lanes:
+ *
+ * - Oyster's own origin Git, carrying only the guest's own credential;
+ * - the anonymous public download lane (package registries and release hosts
+ *   the policy classifies), so a build can install its dependencies, behind
+ *   the same `COMPUTER_PUBLIC_EGRESS=disabled` kill switch as Hub;
+ * - the internal build hosts: a live App build job's read-only clone on
+ *   `git.team.internal` (an installation repository through the Git door,
+ *   presented with a host-held job pass the guest never sees, or the App's
+ *   template through the registry's read-only template exchange), and its
+ *   `/jobs/:id/*` reports and object uploads on `build.team.internal`, each
+ *   object streamed into the Release store without passing the registry.
+ *
+ * Team Git is refused, because this host serves no such lane.
+ */
+import { anonymousRequest, anonymousResponse, computerEgressDenied, decideComputerEgress, decidePublicLane, originGitRequest, publicEgressEnabled, recordComputerEgress, } from "@fungi.computer/computer/egress";
+import { createBuildEgress } from "../build-egress.js";
+import { oysterBuildGitHost, oysterBuildReportHost } from "../app-builds.js";
+import { gitDoorRoute, smartHttpExchange } from "../git.js";
+const templateRoute = /^\/([a-zA-Z0-9._-]{1,128}?)\.git\/(info\/refs|git-upload-pack|git-receive-pack)$/u;
+/**
+ * Admit one intercepted guest request. Oyster Git (on `origin`, or a build
+ * clone on the internal Git host) is handed to `forward`, the Oyster
+ * Worker's own fetch, whose door authenticates it as for any other client.
+ */
+export async function serveOysterComputerEgress(request, options) {
+    const deny = (host, decision) => computerEgressDenied({
+        computerId: options.computerId,
+        teamId: null,
+        host,
+        method: request.method,
+        status: 403,
+        decision,
+    });
+    let url;
+    try {
+        url = new URL(request.url);
+    }
+    catch {
+        return deny("invalid", "invalid-url");
+    }
+    const decision = decideComputerEgress(request, url, {
+        origin: options.origin,
+        route: (request, url) => gitDoorRoute(request.method, url),
+    });
+    if (decision.kind === "denied")
+        return deny(url.hostname, decision.reason);
+    let response;
+    if (decision.kind === "origin-git")
+        response = await options.forward(originGitRequest(request, url));
+    else if (decision.kind === "public") {
+        const lane = decidePublicLane({
+            publicEgressEnabled: publicEgressEnabled(options.publicEgress),
+            teamDisabled: false,
+            computerInternetAccessEnabled: true,
+        });
+        if (lane.kind === "denied")
+            return deny(url.hostname, lane.reason);
+        response = anonymousResponse(await fetch(anonymousRequest(request, url)));
+    }
+    else if (decision.kind === "internal-git" &&
+        url.hostname === oysterBuildReportHost)
+        response = await createBuildEgress({
+            admitBuild: (jobId) => options.build.admitBuild(jobId),
+            admitObject: (jobId, grant) => options.build.admitObject(jobId, grant),
+            storeObject: (object, body, mediaType) => options.build.storeObject(object, body, mediaType),
+            submitCandidate: (jobId, manifest, grant, credentialId) => options.build.submitCandidate(jobId, manifest, grant, credentialId),
+            record: (event) => options.build.record(event),
+        }).fetch(request, url);
+    else if (decision.kind === "internal-git" &&
+        url.hostname === oysterBuildGitHost) {
+        const target = gitDoorRoute(request.method, url);
+        const template = target === null ? templateRoute.exec(url.pathname) : null;
+        if (template !== null) {
+            const [, repository = "", suffix = ""] = template;
+            if (smartHttpExchange(request.method, url, suffix)?.scope !== "read" ||
+                url.username ||
+                url.password)
+                return deny(url.hostname, "build-git-route");
+            response = await options.build.exchangeTemplate(repository, request);
+            if (response.status === 403)
+                return deny(url.hostname, "no-live-build");
+        }
+        else {
+            if (target?.scope !== "read")
+                return deny(url.hostname, "build-git-route");
+            const pass = await options.build.gitPassFor(target);
+            if (pass === null)
+                return deny(url.hostname, "no-live-build");
+            const forwarded = originGitRequest(request, new URL(url.pathname + url.search, options.origin));
+            forwarded.headers.set("Authorization", `Bearer ${pass}`);
+            response = await options.forward(forwarded);
+        }
+    }
+    else
+        return deny(url.hostname, `lane-not-offered:${decision.kind}`);
+    recordComputerEgress({
+        event: "computer.egress",
+        computerId: options.computerId,
+        teamId: null,
+        lane: decision.kind,
+        host: url.hostname,
+        method: request.method,
+        status: response.status,
+        decision: response.status < 400 ? "allowed" : "denied",
+        contentLength: response.headers.get("content-length"),
+    });
+    return response;
+}

package/dist/standalone/computer.d.ts

@@ -0,0 +1,122 @@
+import { type AppMethodRefusedReply } from "@fungi.computer/agar/backend";
+import { type WorkflowGitPassResult } from "@fungi.computer/agar/computer-contracts";
+import { type ComputerPorts } from "@fungi.computer/agar/computer";
+import { type PreviewSelector } from "./preview.js";
+import { type StandaloneTenancyEnv } from "./tenancy.js";
+import * as z from "zod";
+import { computerProcessSchema, computerToolResultSchema, readOutputSchema } from "@fungi.computer/computer/operations";
+import { ComputerDO as NativeComputerDO, listOutputSchema, writeOutputSchema, mkdirOutputSchema, computerPortsOutputSchema, computerPortOutputSchema, computerPortRemovalOutputSchema, processListOutputSchema, processKillOutputSchema, computerOperationResultSchema, type AttachedBackend, type ComputerEnv, type ComputerValue } from "@fungi.computer/computer";
+import { type ComputerAction, type ComputerGrant } from "@fungi.computer/computer/fleet";
+import type { InvocationFrame } from "../invocation.js";
+import { type OysterCapability } from "../host.js";
+import type { OysterBindingRow, OysterInvocationHost, OysterWorkerEnv, OysterWorkspace } from "../workers.js";
+import type { OysterKeys, OysterKeysLivePort } from "../workers-git.js";
+import type { StandaloneRegistry } from "./registry.js";
+/** Native bindings selected by the standalone composition, never by an App. */
+export type StandaloneComputerEnv = ComputerEnv & Pick<OysterWorkerEnv, "RELEASES"> & Readonly<{
+    OYSTER_COMPUTER_ID: string;
+    COMPUTER: DurableObjectNamespace<ComputerDO>;
+    /** The registry owns installations and this Computer's App build jobs. */
+    REGISTRY: DurableObjectNamespace<StandaloneRegistry>;
+    /** This single-tenant standalone's own named keys, for the `computer.use` grant check. */
+    KEYS: DurableObjectNamespace<OysterKeys>;
+    OYSTER_ORIGIN?: string;
+    OYSTER_PREVIEW_ORIGIN?: string;
+    OYSTER_OWNER_NAME?: string;
+}>;
+/** Finite native results cross the Workers RPC mapping without recursive JSON types. */
+export type StandaloneComputerResult = WorkflowGitPassResult | z.output<typeof listOutputSchema> | Readonly<{
+    path: string;
+    byteOffset: number;
+    content: string;
+    encoding: "base64";
+    truncated: boolean;
+}> | Readonly<{
+    error: "conflict";
+}> | z.output<typeof writeOutputSchema> | z.output<typeof mkdirOutputSchema> | z.output<typeof computerPortsOutputSchema> | z.output<typeof computerPortOutputSchema> | z.output<typeof computerPortRemovalOutputSchema> | z.output<typeof processListOutputSchema> | z.output<typeof processKillOutputSchema> | z.output<typeof computerProcessSchema> | ComputerPorts["ports"][number] | z.output<typeof computerOperationResultSchema> | z.output<typeof readOutputSchema> | z.output<typeof computerToolResultSchema>;
+/**
+ * A port-preview listing, or the typed refusal the owner route presents with
+ * {@link appMethodRefusalStatus}. A refusal never escapes as a 500.
+ */
+export type ComputerPortPreviewsReply = Readonly<{
+    kind: "ok";
+    value: ComputerPorts;
+}> | AppMethodRefusedReply;
+/**
+ * The Computer owner's bindings: the standalone Computer env plus the tenancy
+ * registry that names the live canonical owner a port preview must belong to.
+ */
+export type StandaloneComputerOwnerEnv = StandaloneComputerEnv & StandaloneTenancyEnv;
+/** Durable workspace and existing backings, with fleet checks at native acceptance. */
+export declare class ComputerDO extends NativeComputerDO {
+    #private;
+    private readonly previewBindings;
+    constructor(state: DurableObjectState, previewBindings: StandaloneComputerOwnerEnv);
+    /**
+     * Run one App build job's fixed command, under the build budget. The
+     * registry that minted the job re-admits it for this Computer first.
+     */
+    runBuild(input: {
+        jobId: string;
+        command: string;
+        timeoutMs: number;
+    }): Promise<Readonly<{
+        output: {
+            exitCode: number | null;
+            stderr: string;
+        } | null;
+    }>>;
+    /** Issue preview tickets for every exposed port, or refuse typed. */
+    portPreviews(authority: ComputerGrant, selectorInput: PreviewSelector): Promise<ComputerPortPreviewsReply>;
+    portPreview(signature: string, port: number, request: Request): Promise<Response>;
+    protected attachedBackends(): readonly AttachedBackend[];
+    /** One advertised Computer tool, accepted against the host-issued grant. */
+    tool(authority: ComputerGrant, capabilityId: string, input: ComputerValue): Promise<StandaloneComputerResult>;
+    /** JSON operations keep the Computer's maintained parsers and execution engine. */
+    value(authority: ComputerGrant, action: ComputerAction, input: ComputerValue): Promise<StandaloneComputerResult>;
+    fileList(authority: ComputerGrant, path: string, limit: number, offset: number): Promise<{
+        path: string;
+        entries: {
+            name: string;
+            size: number;
+            modifiedAt: number;
+            type: "file" | "directory" | "symlink";
+        }[];
+        nextOffset: number | null;
+    } | null>;
+    /** Binary files share the same native filesystem as commands and PTYs. */
+    fileRead(authority: ComputerGrant, path: string): Promise<Uint8Array | null>;
+    fileWrite(authority: ComputerGrant, path: string, bytes: Uint8Array): Promise<void>;
+    fileReplace(authority: ComputerGrant, path: string, expectedContent: string, content: string): Promise<{
+        path: string;
+        bytes: number;
+        kind: "replaced";
+    } | {
+        kind: "conflict";
+    }>;
+    /** WebSocket upgrades use native Fetch, which can return a 101 response. */
+    fetch(request: Request): Promise<Response>;
+}
+/**
+ * Select the fixed native Computer once for the HTTP/MCP host and its
+ * adapters. `keysLive` is the host's own owner-checked `host.keys.live`
+ * port, threaded in by `oysterGitWorkerHost` before this workspace exists;
+ * a caller that only needs `.files` (the Media binding's own dispatch) may
+ * omit it, since a team-key principal then simply never reaches the
+ * Computer, rather than reading `env.KEYS` directly and skipping the check.
+ */
+export declare function standaloneWorkspace(env: StandaloneComputerEnv, keysLive?: OysterKeysLivePort): OysterWorkspace;
+/**
+ * Owner/key capability routes over the selected Computer's native
+ * namespace. `keysLive` is the same owner-checked port `standaloneWorkspace`
+ * takes; a caller with none fails every team-key request closed.
+ */
+export declare function standaloneComputerCapabilities(env: StandaloneComputerEnv, workspace: OysterWorkspace, keysLive?: OysterKeysLivePort): readonly OysterCapability[];
+/** The COMPUTER row's codecs, as the standalone Instance joins them. */
+export type ComputerFrameMethods = Readonly<{
+    COMPUTER: OysterBindingRow<OysterWorkerEnv>["methods"];
+}>;
+/** Closed COMPUTER binding codecs, joined into the standalone Instance. */
+export declare const computerFrameMethods: ComputerFrameMethods;
+/** Dispatch one admitted COMPUTER operation under its captured frame. */
+export declare function computerInvocation(env: StandaloneComputerEnv, frame: InvocationFrame<OysterInvocationHost>, method: string, args: readonly unknown[]): Promise<StandaloneComputerResult>;