@fungi.computer/oyster 0.5.0 → 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.js

@@ -12,6 +12,7 @@ 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;
@@ -246,6 +247,9 @@ function createAgentRoutes(agents, liveKey) {
         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");
     });

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;
+        },
+    };
+}