@fungi.computer/oyster 0.4.1 → 0.6.0

package/README.md

@@ -62,6 +62,10 @@ Workers AI, Workflows and media.
 
 ## Quick start: deploy your own Oyster
 
+Deciding what to run?
+[Is Oyster for you?](https://docs.fungi.computer/is-oyster-for-you/) compares
+agent Computers and App builds with Cloudflare Workers Builds.
+
 You need:
 
 - a Cloudflare account on Workers Paid, with Containers, Artifacts, Workers AI,
@@ -69,11 +73,12 @@ You need:
 - Docker, which Wrangler uses to build the Computer's container image;
 - Node 24, pnpm 11 or newer and Git.
 
-The first install takes about 15 to 20 minutes, most of it the seven App builds
-on the Computer, one after another. Start a project, add Oyster, its Computer
-and Wrangler, and copy the example Worker out of the package. The local pnpm
-policy allows esbuild and workerd to install their native binaries and disables
-unneeded optional dependency scripts, so a fresh install exits successfully:
+The first install takes about 15 to 20 minutes, mostly building the seven Apps
+on the Computer. By default, Oyster builds two Apps at a time. Start a project,
+add Oyster, its Computer and Wrangler, and copy the example Worker out of the
+package. The local pnpm policy allows esbuild and workerd to install their
+native binaries and disables unneeded optional dependency scripts, so a fresh
+install exits successfully:
 
 ```sh
 mkdir my-oyster && cd my-oyster
@@ -462,10 +467,43 @@ the Computer. `examples/standalone/wrangler.jsonc` declares every binding it
 uses. Set the owner key as a secret (`OYSTER_OWNER_KEY`, 24+ characters) and
 deploy with `wrangler deploy`. Sign in at `/login`.
 
+Hosts may supply the optional `OYSTER_KEY_SESSIONS` binding, implementing
+`OysterKeySessionResolver` from `@fungi.computer/oyster/auth`. Its
+`resolve(value)` returns `{ keyId }` for a live host-owned session, or `null`.
+The host mints and expires opaque sessions and sets the `keySessionCookieName`
+cookie; it is not a named key's bearer secret. Hosts should use `Path=/`,
+`HttpOnly`, `Secure` and `SameSite=Lax` (or stricter) as defense in depth.
+Oyster independently checks request provenance. Cookie-only GET/HEAD navigation
+is allowed. Other methods require `Origin` to be present and equal the request
+URL's origin, and refuse `Sec-Fetch-Site: cross-site`. Missing `Origin` is
+refused, using the same strict predicate as the channel's POST routes. Oyster
+stores no browser sessions. `keySessionAuth` wraps ordinary `ownerOrKeyAuth` at
+the standalone tenancy composition root. Each cookie admission reopens the live
+key and checks its canonical owner; every authenticated door still uses that
+key's current grants. App pages refuse keys without App access, even when the
+App is public to visitors. Explicit header authentication is unchanged, and a
+failed Authorization header cannot fall back to a named-key cookie. The owner
+cookie and owner-only management API are unchanged; without the binding
+named-key cookies admit nobody.
+
+The celld example is a limited trial, not the full Cloudflare setup above. It
+requires access to Fungi's private celld fork and Botanical source repository.
+Use `examples/standalone/wrangler.celld.jsonc` beside `worker.ts`, not the
+Cloudflare-only config. The published `0.5.0` tarball does not yet contain this
+celld example; copy it from your authorized Botanical source checkout until a
+package including it is released.
+
 The layers it is built from stay exported for hosts that compose their own:
-`@fungi.computer/oyster/workers` (Releases, Instances, MCP and App storage) and
-`@fungi.computer/oyster/workers-git` (the git door), with `oysterAppMethods`
-supplying the installed App catalog to an Agent runtime.
+`@fungi.computer/oyster/turnstile` owns Cloudflare challenge configuration and
+token verification. Hosts supply their origin, verification timeout and safe
+error reporter; they retain their own challenged routes and HTTP responses.
+Configuration keeps the explicit `TURNSTILE=off` opt-out and fails closed on
+HTTPS hosts without both keys. Hub retains its five-second verification policy.
+
+Other host building blocks: `@fungi.computer/oyster/workers` (Releases,
+Instances, MCP and App storage) and `@fungi.computer/oyster/workers-git` (the
+git door), with `oysterAppMethods` supplying the installed App catalog to an
+Agent runtime.
 
 Pack and install an App with `@fungi.computer/oyster/pack`: `packRelease` turns
 an exact Git commit and a canonical build recipe into a Release with immutable

package/dist/agents.d.ts

@@ -7,6 +7,7 @@
  * transport (`/browser/…`), served by the adapter behind the same App grants.
  */
 import { Hono } from "hono";
+import { type LiveOysterKey } from "./keys.js";
 import type { AppToolPolicy } from "./apps/tools.js";
 import * as Schema from "effect/Schema";
 import { type OysterCapability, type OysterEnv, type OysterPrincipal } from "./host.js";
@@ -125,7 +126,7 @@ export type OysterAgents = Readonly<{
     visit(agentId: string, sessionId: string): Promise<boolean>;
 }>;
 /** Agent adapters admitted against each App's declared capabilities. */
-export declare function agentCapabilities(agents: OysterAgents): readonly OysterCapability[];
+export declare function agentCapabilities(agents: OysterAgents, liveKey: (keyId: string) => Promise<LiveOysterKey | null>): readonly OysterCapability[];
 /** Host-owned direct approval under the admitted owner; never an App capability. */
 export declare function agentApprovalRoutes(agents: OysterAgents): Hono<OysterEnv>;
 /**

package/dist/agents.js

@@ -7,10 +7,12 @@
  * transport (`/browser/…`), served by the adapter behind the same App grants.
  */
 import { Hono } from "hono";
+import { keyAgentAccess } from "./keys.js";
 import * as Schema from "effect/Schema";
 import { z } from "zod";
 import { oysterPrincipalIsOwner, } from "./host.js";
 import { agentAvatarSchema } from "./agent-avatars.js";
+import { computerTargetParam } from "./computer-target.js";
 import { agentAvatar, agentList, agentManage, agentRename, agentSessionRead, agentSessionWrite, agentToolPolicy, } from "@fungi.computer/agar/agents";
 /** At most this many MCP servers per Agent. */
 export const maxAgentMcpServers = 16;
@@ -51,8 +53,8 @@ function refusal(status, error) {
     return Response.json({ error }, { status });
 }
 /** Agent adapters admitted against each App's declared capabilities. */
-export function agentCapabilities(agents) {
-    const routes = createAgentRoutes(agents);
+export function agentCapabilities(agents, liveKey) {
+    const routes = createAgentRoutes(agents, liveKey);
     const shared = { base: "/", routes };
     return [
         {
@@ -134,9 +136,41 @@ export function agentCapabilities(agents) {
         },
     ];
 }
-function createAgentRoutes(agents) {
+function createAgentRoutes(agents, liveKey) {
     const routes = new Hono();
-    routes.get("/agents", async () => Response.json(await agents.list()));
+    // Every Agent and Session lookup shares this live principal-scoped door.
+    const access = async (principal, agentId) => {
+        if (oysterPrincipalIsOwner(principal))
+            return true;
+        if (principal.actor.kind !== "team-key")
+            return false;
+        const key = await liveKey(principal.actor.keyId);
+        return key !== null && keyAgentAccess(key, agentId);
+    };
+    routes.use("/agents/:agentId/*", async (context, next) => {
+        if (!(await access(context.env.principal, context.req.param("agentId"))))
+            return refusal(403, "Agent access denied");
+        await next();
+        return undefined;
+    });
+    routes.use("/agent-policies/:agentId", async (context, next) => {
+        if (!(await access(context.env.principal, context.req.param("agentId"))))
+            return refusal(403, "Agent access denied");
+        await next();
+        return undefined;
+    });
+    routes.get("/agents", async (context) => {
+        const listed = await agents.list();
+        const actor = context.env.principal.actor;
+        if (oysterPrincipalIsOwner(context.env.principal))
+            return Response.json(listed);
+        if (actor.kind !== "team-key")
+            return Response.json([]);
+        const key = await liveKey(actor.keyId);
+        return Response.json(key === null
+            ? []
+            : listed.filter((agent) => keyAgentAccess(key, agent.agentId)));
+    });
     routes.post("/agents", async (context) => {
         const { principal } = context.env;
         if (!oysterPrincipalIsOwner(principal))
@@ -213,22 +247,43 @@ function createAgentRoutes(agents) {
         if (length > maxAgentRequestBytes)
             return refusal(413, "Request too large");
         const target = new URL(`https://agent.internal${path}${url.search}`);
+        // A desk window's Computer routing hint is the host's to admit; the
+        // Agent's Session routes decode a closed query that refuses it.
+        target.searchParams.delete(computerTargetParam);
         const response = await agents.fetch(agentId, new Request(target, incoming));
         return response ?? refusal(404, "No such agent");
     });
-    routes.get("/member/inbox", async () => {
+    routes.get("/member/inbox", async (context) => {
         const inbox = await agents.inbox();
+        const principal = context.env.principal;
+        if (oysterPrincipalIsOwner(principal))
+            return Response.json({
+                items: inbox.items,
+                next: null,
+                cursor: inbox.revision,
+            });
+        if (principal.actor.kind !== "team-key")
+            return refusal(403, "Agent access denied");
+        const key = await liveKey(principal.actor.keyId);
         return Response.json({
-            items: inbox.items,
+            items: key === null
+                ? []
+                : inbox.items.filter((item) => "agentId" in item && keyAgentAccess(key, item.agentId)),
             next: null,
-            cursor: inbox.revision,
+            // The global revision changes for ungranted Agents too. Key feeds have
+            // no scoped event stream, so expose neither that revision nor its events.
+            cursor: 0,
         });
     });
-    routes.get("/member/inbox/notices", () => Response.json({ items: [], next: null }));
+    routes.get("/member/inbox/notices", (context) => oysterPrincipalIsOwner(context.env.principal)
+        ? Response.json({ items: [], next: null })
+        : refusal(403, "Agent access denied"));
     routes.post("/member/inbox/visits", async (context) => {
         const body = Schema.decodeUnknownOption(visitSchema)(await context.req.json());
         if (body._tag === "None")
             return refusal(400, "Invalid visit");
+        if (!(await access(context.env.principal, body.value.agentId)))
+            return refusal(403, "Agent access denied");
         return (await agents.visit(body.value.agentId, body.value.sessionId))
             ? new Response(null, { status: 204 })
             : refusal(404, "No such Session");
@@ -236,6 +291,10 @@ function createAgentRoutes(agents) {
     // The feed is small (one person's agents), so a change is announced as a
     // `reset` and the client re-reads the whole inbox.
     routes.get("/member/inbox/events", (context) => {
+        // The unscoped revision also changes for other Agents. Do not expose it
+        // until a principal-scoped revision exists.
+        if (!oysterPrincipalIsOwner(context.env.principal))
+            return refusal(403, "Agent access denied");
         const after = Number(context.req.query("after") ?? "0");
         const signal = context.req.raw.signal;
         const encoder = new TextEncoder();

package/dist/apps/gate.d.ts

@@ -36,6 +36,10 @@ export declare const gateRequestSchema: z.ZodLazy<z.ZodDiscriminatedUnion<[z.Zod
     kind: z.ZodLiteral<"capability-route">;
     capability: z.ZodPipe<z.ZodUnknown, z.ZodTransform<"approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "llm.generation" | "media.generation" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage", unknown>>;
     operation: z.ZodString;
+    effect: z.ZodEnum<{
+        read: "read";
+        write: "write";
+    }>;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"binding">;
     binding: z.ZodPipe<z.ZodUnknown, z.ZodTransform<"BACKGROUND" | "GIT" | "EVENTS" | "APPS" | "WORKFLOWS" | "APP_STORAGE" | "MEDIA" | "COMPUTER" | "INBOX" | "AGENTS", unknown>>;

package/dist/apps/gate.js

@@ -26,6 +26,7 @@ export const gateRequestSchema = z.lazy(() => z.discriminatedUnion("kind", [
         kind: z.literal("capability-route"),
         capability: ownerCodec(appCapabilityIdSchema),
         operation: z.string().min(1),
+        effect: z.enum(["read", "write"]),
     }),
     z.strictObject({
         kind: z.literal("binding"),
@@ -259,6 +260,8 @@ export function admits(facts, rawRequest) {
         case "capability-route": {
             if (visitor)
                 return refusal("visitor_read_only");
+            if (request.effect === "write" && facts.access?.level === "read")
+                return refusal("level_too_low");
             if (!request.operation.startsWith("route:") ||
                 !facts.declaration.capabilities.includes(request.capability) ||
                 facts.declaredOperations.capabilities

package/dist/auth.d.ts

@@ -1,7 +1,24 @@
-import type { OysterAuth } from "./host.js";
+import type { OysterAuth, OysterHost } from "./host.js";
 import type { OysterKeyStore } from "./keys.js";
 /** Cookie emitted by ownerKeyAuth, for composing credential-specific adapters. */
 export declare const ownerKeyCookieName = "oyster_session";
+/** Host-minted opaque sessions for named keys, separate from the owner cookie. */
+export declare const keySessionCookieName = "oyster_key_session";
+/**
+ * The host owns session minting, hashing/storage and expiry.
+ * A session resolves only to a key id, never to owner or grant authority.
+ * Hosts should use Path=/, HttpOnly, Secure and SameSite=Lax (or stricter)
+ * as defense in depth; Oyster independently checks request provenance.
+ * Cookie-only admission allows GET/HEAD navigation. Every other method requires
+ * Origin to be present and equal the request URL's origin, and Sec-Fetch-Site
+ * not to be cross-site. Missing Origin is refused.
+ */
+export type OysterKeySessionResolver = Readonly<{
+    /** Resolve an opaque host session to its named key, or null when unavailable. */
+    resolve: (value: string) => Promise<Readonly<{
+        keyId: string;
+    }> | null>;
+}>;
 /**
  * Single-owner sign-in: a bearer token or a session cookie holding the
  * owner key's digest. The key itself is never stored in the browser.
@@ -9,3 +26,9 @@ export declare const ownerKeyCookieName = "oyster_session";
 export declare function ownerKeyAuth(ownerKey: string, ownerId?: string): OysterAuth;
 /** The owner key, or a named key admitted as its canonical Team-key actor. */
 export declare function ownerOrKeyAuth(ownerKey: string, ownerId: string, keys: () => Pick<OysterKeyStore, "verify">): OysterAuth;
+/**
+ * Add host-owned browser sessions to ownerOrKeyAuth. Explicit credentials and
+ * non-401 refusals keep their ordinary result; ambient cookies cannot undo them.
+ * Every cookie admission rechecks the key's liveness and canonical owner.
+ */
+export declare function keySessionAuth(auth: OysterAuth, ownerId: string, keys: () => NonNullable<OysterHost["keys"]>, sessions: OysterKeySessionResolver): OysterAuth;

package/dist/auth.js

@@ -1,9 +1,13 @@
 import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
+import { parse } from "hono/utils/cookie";
 import { presentedGitKey } from "./git-auth.js";
 import { sha256 } from "./release.js";
+import { sameOriginRequest } from "./request-origin.js";
 /** Cookie emitted by ownerKeyAuth, for composing credential-specific adapters. */
 export const ownerKeyCookieName = "oyster_session";
+/** Host-minted opaque sessions for named keys, separate from the owner cookie. */
+export const keySessionCookieName = "oyster_key_session";
 const loginFormSchema = Schema.Struct({ key: Schema.String });
 /** Compare two secrets through their fixed-length digests, in constant time. */
 async function constantTimeEqual(a, b) {
@@ -91,3 +95,37 @@ export function ownerOrKeyAuth(ownerKey, ownerId, keys) {
             Promise.resolve(new Response("Sign-in is not available", { status: 404 })),
     };
 }
+/**
+ * Add host-owned browser sessions to ownerOrKeyAuth. Explicit credentials and
+ * non-401 refusals keep their ordinary result; ambient cookies cannot undo them.
+ * Every cookie admission rechecks the key's liveness and canonical owner.
+ */
+export function keySessionAuth(auth, ownerId, keys, sessions) {
+    return {
+        ...auth,
+        async authenticate(request) {
+            const result = await auth.authenticate(request);
+            if (result.kind === "admitted" ||
+                result.status !== 401 ||
+                request.headers.has("Authorization"))
+                return result;
+            if (request.method !== "GET" &&
+                request.method !== "HEAD" &&
+                !sameOriginRequest(request))
+                return result;
+            const value = parse(request.headers.get("Cookie") ?? "", keySessionCookieName)[keySessionCookieName];
+            if (value === undefined || value.length === 0)
+                return result;
+            const session = await sessions.resolve(value);
+            if (session === null)
+                return result;
+            const key = await keys().live(session.keyId);
+            return key !== null && key.owner === ownerId
+                ? {
+                    kind: "admitted",
+                    principal: { actor: { kind: "team-key", keyId: key.keyId } },
+                }
+                : result;
+        },
+    };
+}