@fungi.computer/oyster 0.6.0 → 0.8.0

package/docs/api/authorization.md

@@ -0,0 +1,1300 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](README.md)
+
+---
+
+[@fungi.computer/oyster](modules.md) / authorization
+
+# authorization
+
+## Classes
+
+### Requirement
+
+One route's declared requirement: an opaque, frozen value only this module
+mints. Its label and decision live in private fields that only this module
+reads, so a copy, a look-alike, an overridden method or a relabelled field
+changes nothing a route serves, and registering a non-minted value throws.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `Admitted`     |
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new Requirement<Admitted>(
+   token,
+   declared,
+   admit
+): Requirement<Admitted>;
+```
+
+Module-private: use the requirement constructors below.
+
+###### Parameters
+
+| Parameter  | Type                                               |
+| ---------- | -------------------------------------------------- |
+| `token`    | `symbol`                                           |
+| `declared` | [`DeclaredRequirement`](#declaredrequirement)      |
+| `admit`    | (`facts`) => `Promise`\<`Response` \| `Admitted`\> |
+
+###### Returns
+
+[`Requirement`](#requirement)\<`Admitted`\>
+
+#### Properties
+
+##### admitted?
+
+```ts
+readonly optional admitted?: Admitted;
+```
+
+Type-only: what the requirement admits. Never present at run time.
+
+---
+
+### Routes
+
+A declared route table: a frozen, opaque value only [routes](#routes-1) builds.
+Its routes live in a private record; including or serving reads only that
+record, never a method a copy could override. A table cannot serve itself: only
+[serveHost](#servehost), [serveDoors](#servedoors) and
+[serveCapability](#servecapability) do, each with the principal its composition
+root admits. There is no `use`: a path-wide middleware could serve a path no
+route declares.
+
+#### Type Parameters
+
+| Type Parameter      |
+| ------------------- |
+| `E` _extends_ `Env` |
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new Routes<E>(token): Routes<E>;
+```
+
+Module-private: use [routes](#routes-1).
+
+###### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `token`   | `symbol` |
+
+###### Returns
+
+[`Routes`](#routes)\<`E`\>
+
+#### Methods
+
+##### get()
+
+```ts
+get<P, A>(
+   path,
+   requirement,
+   handler,
+   options?
+): this;
+```
+
+Register one GET route.
+
+###### Type Parameters
+
+| Type Parameter         |
+| ---------------------- |
+| `P` _extends_ `string` |
+| `A`                    |
+
+###### Parameters
+
+| Parameter     | Type                                                                                        |
+| ------------- | ------------------------------------------------------------------------------------------- |
+| `path`        | `P`                                                                                         |
+| `requirement` | [`Requirement`](#requirement)\<`A`\>                                                        |
+| `handler`     | [`Handler`](#handler)\<`E`, `P`, `A`\>                                                      |
+| `options?`    | `Readonly`\<\{ `middleware?`: readonly `MiddlewareHandler`\<`E`, `NoInfer`\<`P`\>\>[]; \}\> |
+
+###### Returns
+
+`this`
+
+##### post()
+
+```ts
+post<P, A>(
+   path,
+   requirement,
+   handler,
+   options?
+): this;
+```
+
+Register one POST route.
+
+###### Type Parameters
+
+| Type Parameter         |
+| ---------------------- |
+| `P` _extends_ `string` |
+| `A`                    |
+
+###### Parameters
+
+| Parameter     | Type                                                                                        |
+| ------------- | ------------------------------------------------------------------------------------------- |
+| `path`        | `P`                                                                                         |
+| `requirement` | [`Requirement`](#requirement)\<`A`\>                                                        |
+| `handler`     | [`Handler`](#handler)\<`E`, `P`, `A`\>                                                      |
+| `options?`    | `Readonly`\<\{ `middleware?`: readonly `MiddlewareHandler`\<`E`, `NoInfer`\<`P`\>\>[]; \}\> |
+
+###### Returns
+
+`this`
+
+##### put()
+
+```ts
+put<P, A>(
+   path,
+   requirement,
+   handler,
+   options?
+): this;
+```
+
+Register one PUT route.
+
+###### Type Parameters
+
+| Type Parameter         |
+| ---------------------- |
+| `P` _extends_ `string` |
+| `A`                    |
+
+###### Parameters
+
+| Parameter     | Type                                                                                        |
+| ------------- | ------------------------------------------------------------------------------------------- |
+| `path`        | `P`                                                                                         |
+| `requirement` | [`Requirement`](#requirement)\<`A`\>                                                        |
+| `handler`     | [`Handler`](#handler)\<`E`, `P`, `A`\>                                                      |
+| `options?`    | `Readonly`\<\{ `middleware?`: readonly `MiddlewareHandler`\<`E`, `NoInfer`\<`P`\>\>[]; \}\> |
+
+###### Returns
+
+`this`
+
+##### delete()
+
+```ts
+delete<P, A>(
+   path,
+   requirement,
+   handler,
+   options?
+): this;
+```
+
+Register one DELETE route.
+
+###### Type Parameters
+
+| Type Parameter         |
+| ---------------------- |
+| `P` _extends_ `string` |
+| `A`                    |
+
+###### Parameters
+
+| Parameter     | Type                                                                                        |
+| ------------- | ------------------------------------------------------------------------------------------- |
+| `path`        | `P`                                                                                         |
+| `requirement` | [`Requirement`](#requirement)\<`A`\>                                                        |
+| `handler`     | [`Handler`](#handler)\<`E`, `P`, `A`\>                                                      |
+| `options?`    | `Readonly`\<\{ `middleware?`: readonly `MiddlewareHandler`\<`E`, `NoInfer`\<`P`\>\>[]; \}\> |
+
+###### Returns
+
+`this`
+
+##### all()
+
+```ts
+all<P, A>(
+   path,
+   requirement,
+   handler,
+   options?
+): this;
+```
+
+Register one route for every method.
+
+###### Type Parameters
+
+| Type Parameter         |
+| ---------------------- |
+| `P` _extends_ `string` |
+| `A`                    |
+
+###### Parameters
+
+| Parameter     | Type                                                                                        |
+| ------------- | ------------------------------------------------------------------------------------------- |
+| `path`        | `P`                                                                                         |
+| `requirement` | [`Requirement`](#requirement)\<`A`\>                                                        |
+| `handler`     | [`Handler`](#handler)\<`E`, `P`, `A`\>                                                      |
+| `options?`    | `Readonly`\<\{ `middleware?`: readonly `MiddlewareHandler`\<`E`, `NoInfer`\<`P`\>\>[]; \}\> |
+
+###### Returns
+
+`this`
+
+##### on()
+
+```ts
+on<P, A>(
+   methods,
+   path,
+   requirement,
+   handler,
+   options?
+): this;
+```
+
+Register one route for several methods.
+
+###### Type Parameters
+
+| Type Parameter         |
+| ---------------------- |
+| `P` _extends_ `string` |
+| `A`                    |
+
+###### Parameters
+
+| Parameter     | Type                                                                                        |
+| ------------- | ------------------------------------------------------------------------------------------- |
+| `methods`     | readonly [`Method`](#method)[]                                                              |
+| `path`        | `P`                                                                                         |
+| `requirement` | [`Requirement`](#requirement)\<`A`\>                                                        |
+| `handler`     | [`Handler`](#handler)\<`E`, `P`, `A`\>                                                      |
+| `options?`    | `Readonly`\<\{ `middleware?`: readonly `MiddlewareHandler`\<`E`, `NoInfer`\<`P`\>\>[]; \}\> |
+
+###### Returns
+
+`this`
+
+##### include()
+
+```ts
+include(other): this;
+```
+
+Serve another table's routes at this position, keeping its own error handler.
+
+###### Parameters
+
+| Parameter | Type                       |
+| --------- | -------------------------- |
+| `other`   | [`Routes`](#routes)\<`E`\> |
+
+###### Returns
+
+`this`
+
+##### onError()
+
+```ts
+onError(handler): this;
+```
+
+Answer an error thrown by this table's own handlers.
+
+###### Parameters
+
+| Parameter | Type                  |
+| --------- | --------------------- |
+| `handler` | `ErrorHandler`\<`E`\> |
+
+###### Returns
+
+`this`
+
+##### declarations()
+
+```ts
+declarations(): readonly Readonly<{
+  methods: readonly Method[] | "ALL";
+  path: string;
+  requirement: DeclaredRequirement;
+}>[];
+```
+
+Every route this table and its included tables declare, in serving order.
+
+###### Returns
+
+readonly `Readonly`\<\{ `methods`: readonly [`Method`](#method)[] \| `"ALL"`;
+`path`: `string`; `requirement`: [`DeclaredRequirement`](#declaredrequirement);
+\}\>[]
+
+## Type Aliases
+
+### OwnerPrincipal
+
+```ts
+type OwnerPrincipal = Readonly<{
+  actor: Extract<
+    HostActor,
+    {
+      kind: "member";
+    }
+  >;
+  role: "owner";
+}>;
+```
+
+The owner, as every owner route receives it.
+
+---
+
+### MemberPrincipal
+
+```ts
+type MemberPrincipal = Extract<
+  TenantPrincipal,
+  {
+    role: "owner" | "member";
+  }
+>;
+```
+
+A member, owner or not, as member routes receive it.
+
+---
+
+### AuthorityPorts
+
+```ts
+type AuthorityPorts = Readonly<{
+  liveKey: (keyId) => Promise<LiveOysterKey | null>;
+  appToolPolicy: (
+    actor,
+  ) => AppToolPolicy | null | Promise<AppToolPolicy | null>;
+}>;
+```
+
+The live facts this module reads to decide; every host supplies the same ports.
+
+---
+
+### Authority
+
+```ts
+type Authority =
+  | Readonly<{
+      kind: "owner";
+      principal: OwnerPrincipal;
+    }>
+  | Readonly<{
+      kind: "member";
+      principal: MemberPrincipal;
+    }>
+  | Readonly<{
+      kind: "key";
+      principal: TenantPrincipal;
+      key: LiveOysterKey | null;
+    }>
+  | Readonly<{
+      kind: "agent";
+      principal: TenantPrincipal;
+      actor: Extract<
+        HostActor,
+        {
+          kind: "agent";
+        }
+      >;
+    }>;
+```
+
+One request's authority, resolved once from its principal. A key carries its
+live grants, or `null` once it is no longer live, which reaches nothing.
+
+---
+
+### ReachableInstallation
+
+```ts
+type ReachableInstallation = Readonly<{
+  installationId: string;
+}>;
+```
+
+One installation as reach decisions see it.
+
+---
+
+### RequestFacts
+
+```ts
+type RequestFacts = Readonly<{
+  request: Request;
+  param: (name) => string | undefined;
+  body: <T>(schema) => Promise<T | null>;
+  principal: () => Promise<OysterAuthResult>;
+  mediated: boolean;
+  ports: AuthorityPorts;
+}>;
+```
+
+The request facts a requirement reads.
+
+---
+
+### RequirementKind
+
+```ts
+type RequirementKind =
+  | "public"
+  | "door"
+  | "owner"
+  | "member"
+  | "app"
+  | "apps"
+  | "agent"
+  | "agents"
+  | "computer";
+```
+
+Every requirement kind; the law test proves each has both outcomes.
+
+---
+
+### DeclaredRequirement
+
+```ts
+type DeclaredRequirement = Readonly<{
+  kind: RequirementKind;
+  via?: "direct" | "direct-or-app";
+  reason?: string;
+}>;
+```
+
+How the law and the host table read one route's requirement.
+
+---
+
+### OwnerOrigin
+
+```ts
+type OwnerOrigin = "owner-direct" | "app";
+```
+
+Where an owner request came from: the owner directly, or an App acting through
+the shell.
+
+---
+
+### OwnerAdmission
+
+```ts
+type OwnerAdmission = Readonly<{
+  principal: OwnerPrincipal;
+  origin: OwnerOrigin;
+}>;
+```
+
+What an owner route receives.
+
+---
+
+### CollectionAdmission
+
+```ts
+type CollectionAdmission<Item> = Readonly<{
+  authority: Authority;
+  reaches: (item) => Promise<boolean>;
+}>;
+```
+
+What a collection route receives: the authority and its reach over each item.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `Item`         |
+
+---
+
+### AgentAdmission
+
+```ts
+type AgentAdmission = Readonly<{
+  authority: Authority;
+  principal: TenantPrincipal;
+  agentId: string;
+}>;
+```
+
+What an Agent route receives.
+
+---
+
+### Method
+
+```ts
+type Method = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
+```
+
+An HTTP method a route may declare.
+
+---
+
+### RouteDeclaration
+
+```ts
+type RouteDeclaration = Readonly<{
+  methods: readonly Method[] | "ALL";
+  path: string;
+  requirement: DeclaredRequirement;
+}>;
+```
+
+One declared route, as the law test and the host's table read it.
+
+---
+
+### Handler
+
+```ts
+type Handler<E, P, Admitted> = (
+  context,
+  admitted,
+) => Response | Promise<Response>;
+```
+
+A handler receives the request and exactly what its requirement admitted.
+
+#### Type Parameters
+
+| Type Parameter         |
+| ---------------------- |
+| `E` _extends_ `Env`    |
+| `P` _extends_ `string` |
+| `Admitted`             |
+
+#### Parameters
+
+| Parameter  | Type                  |
+| ---------- | --------------------- |
+| `context`  | `Context`\<`E`, `P`\> |
+| `admitted` | `Admitted`            |
+
+#### Returns
+
+`Response` \| `Promise`\<`Response`\>
+
+---
+
+### RouteOptions
+
+```ts
+type RouteOptions<E, P> = Readonly<{
+  middleware?: readonly MiddlewareHandler<E, P>[];
+}>;
+```
+
+Per-route options; middleware runs after the requirement admits.
+
+#### Type Parameters
+
+| Type Parameter         |
+| ---------------------- |
+| `E` _extends_ `Env`    |
+| `P` _extends_ `string` |
+
+---
+
+### ResponseView
+
+```ts
+type ResponseView = Readonly<{
+  status: number;
+  headers: Headers;
+}>;
+```
+
+What a header hook may read of a finished response: never its body or request.
+
+---
+
+### ResponseHeaders
+
+```ts
+type ResponseHeaders = (response) => Readonly<Record<string, string>> | null;
+```
+
+One header hook: the headers to add to a finished response, if any.
+
+#### Parameters
+
+| Parameter  | Type                            |
+| ---------- | ------------------------------- |
+| `response` | [`ResponseView`](#responseview) |
+
+#### Returns
+
+`Readonly`\<`Record`\<`string`, `string`\>\> \| `null`
+
+---
+
+### HostServeOptions
+
+```ts
+type HostServeOptions = Readonly<{
+  headers?: readonly ResponseHeaders[];
+  serverTiming?: Readonly<{
+    totalDescription: string;
+  }>;
+}>;
+```
+
+How the host table is served beyond its principal and ports.
+
+---
+
+### ServedTable
+
+```ts
+type ServedTable<E> = Readonly<{
+  fetch: (...request) => Promise<Response>;
+  request: (...request) => Promise<Response>;
+  servedPaths: () => readonly string[];
+}>;
+```
+
+A served table: it answers requests and names what it serves, and is never a
+router.
+
+#### Type Parameters
+
+| Type Parameter      |
+| ------------------- |
+| `E` _extends_ `Env` |
+
+## Functions
+
+### keyAppAccess()
+
+```ts
+function keyAppAccess(
+  key,
+  installationId,
+): {
+  level: "read" | "write";
+  revision: string;
+  grantedBy: string;
+} | null;
+```
+
+One live key's access to one installation: `write` when its grants admit
+`apps.use` there, `read` when they admit `apps.read`, otherwise `null` --
+including for an installation added after the key was issued, unless the key
+holds "All Apps" (`targets: {kind: "all"}`). The same shape as an Agent's stored
+[AppToolPolicy](apps.md#apptoolpolicy); its caller adds `bindingName` (which
+varies by caller: the plain installation id for the gate, the uppercased binding
+name for MCP) to reach the full `AppToolAccess`.
+
+#### Parameters
+
+| Parameter        | Type                                     |
+| ---------------- | ---------------------------------------- |
+| `key`            | [`LiveOysterKey`](keys.md#liveoysterkey) |
+| `installationId` | `string`                                 |
+
+#### Returns
+
+\| \{ `level`: `"read"` \| `"write"`; `revision`: `string`; `grantedBy`:
+`string`; \} \| `null`
+
+---
+
+### keyAgentAccess()
+
+```ts
+function keyAgentAccess(key, agentId): boolean;
+```
+
+Agent access is scoped to the granted Agent ids, never inferred from App grants.
+
+#### Parameters
+
+| Parameter | Type                                     |
+| --------- | ---------------------------------------- |
+| `key`     | [`LiveOysterKey`](keys.md#liveoysterkey) |
+| `agentId` | `string`                                 |
+
+#### Returns
+
+`boolean`
+
+---
+
+### keyAllowsComputerUse()
+
+```ts
+function keyAllowsComputerUse(key): boolean;
+```
+
+Whether a live key's own grants turn its Computer access on. Off by default.
+
+#### Parameters
+
+| Parameter | Type                                     |
+| --------- | ---------------------------------------- |
+| `key`     | [`LiveOysterKey`](keys.md#liveoysterkey) |
+
+#### Returns
+
+`boolean`
+
+---
+
+### oysterPrincipalIsOwner()
+
+```ts
+function oysterPrincipalIsOwner(
+  principal,
+): principal is Readonly<{
+  actor: { kind: "member"; memberId: string };
+  role: "owner";
+}>;
+```
+
+True only for a member admitted with the owner role.
+
+#### Parameters
+
+| Parameter   | Type                                           |
+| ----------- | ---------------------------------------------- |
+| `principal` | [`TenantPrincipal`](tenant.md#tenantprincipal) |
+
+#### Returns
+
+`principal is Readonly<{ actor: { kind: "member"; memberId: string }; role: "owner" }>`
+
+---
+
+### hostAuthorityPorts()
+
+```ts
+function hostAuthorityPorts(host): AuthorityPorts;
+```
+
+A host's own ports: its key store's liveness and its Agents' tool policy.
+
+#### Parameters
+
+| Parameter | Type                                                                        |
+| --------- | --------------------------------------------------------------------------- |
+| `host`    | `Pick`\<[`OysterHost`](host.md#oysterhost), `"keys"` \| `"appToolPolicy"`\> |
+
+#### Returns
+
+[`AuthorityPorts`](#authorityports)
+
+---
+
+### authorityOf()
+
+```ts
+function authorityOf(principal, ports): Promise<Authority>;
+```
+
+Resolve one principal's authority through the live key port.
+
+#### Parameters
+
+| Parameter   | Type                                           |
+| ----------- | ---------------------------------------------- |
+| `principal` | [`TenantPrincipal`](tenant.md#tenantprincipal) |
+| `ports`     | [`AuthorityPorts`](#authorityports)            |
+
+#### Returns
+
+`Promise`\<[`Authority`](#authority)\>
+
+---
+
+### reachesAgent()
+
+```ts
+function reachesAgent(authority, agentId): boolean;
+```
+
+Whether this authority reaches one Agent and its Sessions. Only the owner and
+granted keys do.
+
+#### Parameters
+
+| Parameter   | Type                      |
+| ----------- | ------------------------- |
+| `authority` | [`Authority`](#authority) |
+| `agentId`   | `string`                  |
+
+#### Returns
+
+`boolean`
+
+---
+
+### reachesComputer()
+
+```ts
+function reachesComputer(authority): boolean;
+```
+
+Whether this authority reaches the host's Computer, its workspace files and the
+media written there. Members do; a key only with `computer.use`; Agents reach a
+Computer only through their own attachment owner.
+
+#### Parameters
+
+| Parameter   | Type                      |
+| ----------- | ------------------------- |
+| `authority` | [`Authority`](#authority) |
+
+#### Returns
+
+`boolean`
+
+---
+
+### appToolAccess()
+
+```ts
+function appToolAccess(
+  authority,
+  installationId,
+  ports,
+): Promise<{
+  level: "read" | "write";
+  revision: string;
+  grantedBy: string;
+} | null>;
+```
+
+A key's or Agent's tool access to one installation, in the App gate's policy
+shape; `null` when it reaches none. Members and the owner hold no tool policy:
+the App gate decides them by role.
+
+#### Parameters
+
+| Parameter        | Type                                |
+| ---------------- | ----------------------------------- |
+| `authority`      | [`Authority`](#authority)           |
+| `installationId` | `string`                            |
+| `ports`          | [`AuthorityPorts`](#authorityports) |
+
+#### Returns
+
+`Promise`\< \| \{ `level`: `"read"` \| `"write"`; `revision`: `string`;
+`grantedBy`: `string`; \} \| `null`\>
+
+---
+
+### reachesInstallation()
+
+```ts
+function reachesInstallation(
+  authority,
+  installation,
+  access,
+  ports,
+): Promise<boolean>;
+```
+
+Whether this authority may see or open one installation at all (the home list,
+Git). A key needs `apps.read` there; `use` needs `apps.use`. Nothing anonymous
+reaches one.
+
+#### Parameters
+
+| Parameter      | Type                                              |
+| -------------- | ------------------------------------------------- |
+| `authority`    | [`Authority`](#authority)                         |
+| `installation` | [`ReachableInstallation`](#reachableinstallation) |
+| `access`       | `"read"` \| `"use"`                               |
+| `ports`        | [`AuthorityPorts`](#authorityports)               |
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+---
+
+### allowsMachineEnrollment()
+
+```ts
+function allowsMachineEnrollment(key): boolean;
+```
+
+Whether a live key's grants permit a one-use device enrollment.
+
+#### Parameters
+
+| Parameter | Type                                     |
+| --------- | ---------------------------------------- |
+| `key`     | [`LiveOysterKey`](keys.md#liveoysterkey) |
+
+#### Returns
+
+`boolean`
+
+---
+
+### unauthenticated()
+
+```ts
+function unauthenticated(request, result): Response;
+```
+
+A browser page asks to sign in; every other refused request gets its status.
+
+#### Parameters
+
+| Parameter | Type                                                                                    |
+| --------- | --------------------------------------------------------------------------------------- |
+| `request` | `Request`                                                                               |
+| `result`  | `Extract`\<[`OysterAuthResult`](host.md#oysterauthresult), \{ `kind`: `"refused"`; \}\> |
+
+#### Returns
+
+`Response`
+
+---
+
+### publicRoute()
+
+```ts
+function publicRoute(reason): Requirement<null>;
+```
+
+Served without any principal: sandboxed App bytes, page assets, sign-in.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `reason`  | `string` |
+
+#### Returns
+
+[`Requirement`](#requirement)\<`null`\>
+
+---
+
+### door()
+
+```ts
+function door(reason): Requirement<null>;
+```
+
+The route verifies its own credential (MCP, Git, signed webhook delivery, device
+enrollment); `reason` names that credential. A door that reads an Oyster
+principal decides its reach through this module's functions.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `reason`  | `string` |
+
+#### Returns
+
+[`Requirement`](#requirement)\<`null`\>
+
+---
+
+### owner()
+
+```ts
+function owner(via): Requirement<
+  Readonly<{
+    principal: OwnerPrincipal;
+    origin: OwnerOrigin;
+  }>
+>;
+```
+
+The owner only. `direct` also refuses an App-mediated request (one the page
+bridge sends with `X-Oyster-Installation`, and every request a capability table
+serves): consent and secrets never ride an App.
+
+#### Parameters
+
+| Parameter | Type                            |
+| --------- | ------------------------------- |
+| `via`     | `"direct"` \| `"direct-or-app"` |
+
+#### Returns
+
+[`Requirement`](#requirement)\<`Readonly`\<\{ `principal`:
+[`OwnerPrincipal`](#ownerprincipal); `origin`: [`OwnerOrigin`](#ownerorigin);
+\}\>\>
+
+---
+
+### member()
+
+```ts
+function member(deny?): Requirement<
+  Readonly<{
+    principal: MemberPrincipal;
+  }>
+>;
+```
+
+Any member, owner or not; never a key or Agent. `deny` shapes the refusal for a
+contract whose wire already names one.
+
+#### Parameters
+
+| Parameter | Type             |
+| --------- | ---------------- |
+| `deny`    | () => `Response` |
+
+#### Returns
+
+[`Requirement`](#requirement)\<`Readonly`\<\{ `principal`:
+[`MemberPrincipal`](#memberprincipal); \}\>\>
+
+---
+
+### app()
+
+```ts
+function app(): Requirement<
+  Readonly<{
+    principal: TenantPrincipal;
+  }>
+>;
+```
+
+An App route: any signed-in principal, decided per call by the App gate, which
+reads this module's [appToolAccess](#apptoolaccess).
+
+#### Returns
+
+[`Requirement`](#requirement)\<`Readonly`\<\{ `principal`:
+[`TenantPrincipal`](tenant.md#tenantprincipal); \}\>\>
+
+---
+
+### apps()
+
+```ts
+function apps(): Requirement<
+  Readonly<{
+    authority: Authority;
+    reaches: (item) => Promise<boolean>;
+  }>
+>;
+```
+
+The installation list (the home page): the owner sees all, keys their granted
+ones.
+
+#### Returns
+
+[`Requirement`](#requirement)\<`Readonly`\<\{ `authority`:
+[`Authority`](#authority); `reaches`: (`item`) => `Promise`\<`boolean`\>; \}\>\>
+
+---
+
+### agent()
+
+```ts
+function agent(id?): Requirement<
+  Readonly<{
+    authority: Authority;
+    principal: TenantPrincipal;
+    agentId: string;
+  }>
+>;
+```
+
+One Agent, named by the route's `:agentId` (or by `id` from the request): the
+owner, or a key granted `agents.use` for that Agent id.
+
+#### Parameters
+
+| Parameter | Type                                         |
+| --------- | -------------------------------------------- |
+| `id`      | (`facts`) => `Promise`\<`string` \| `null`\> |
+
+#### Returns
+
+[`Requirement`](#requirement)\<`Readonly`\<\{ `authority`:
+[`Authority`](#authority); `principal`:
+[`TenantPrincipal`](tenant.md#tenantprincipal); `agentId`: `string`; \}\>\>
+
+---
+
+### agents()
+
+```ts
+function agents(): Requirement<
+  Readonly<{
+    authority: Authority;
+    reaches: (item) => Promise<boolean>;
+  }>
+>;
+```
+
+Agents (and their inbox rows): the owner sees all, a key its granted Agents.
+
+#### Returns
+
+[`Requirement`](#requirement)\<`Readonly`\<\{ `authority`:
+[`Authority`](#authority); `reaches`: (`item`) => `Promise`\<`boolean`\>; \}\>\>
+
+---
+
+### computer()
+
+```ts
+function computer(): Requirement<
+  Readonly<{
+    principal: TenantPrincipal;
+  }>
+>;
+```
+
+The host's Computer, its workspace files and media: see
+[reachesComputer](#reachescomputer).
+
+#### Returns
+
+[`Requirement`](#requirement)\<`Readonly`\<\{ `principal`:
+[`TenantPrincipal`](tenant.md#tenantprincipal); \}\>\>
+
+---
+
+### routes()
+
+```ts
+function routes<E>(): Routes<E>;
+```
+
+Start a declared route table.
+
+#### Type Parameters
+
+| Type Parameter      |
+| ------------------- |
+| `E` _extends_ `Env` |
+
+#### Returns
+
+[`Routes`](#routes)\<`E`\>
+
+---
+
+### serveHost()
+
+```ts
+function serveHost<E>(table, authenticate, ports, options?): ServedTable<E>;
+```
+
+Serve a tenant host's table: the composition root (`oysterRouteTable`) supplies
+how a request authenticates. An option this function does not know is refused
+rather than ignored.
+
+#### Type Parameters
+
+| Type Parameter      |
+| ------------------- |
+| `E` _extends_ `Env` |
+
+#### Parameters
+
+| Parameter      | Type                                                                       |
+| -------------- | -------------------------------------------------------------------------- |
+| `table`        | [`Routes`](#routes)\<`E`\>                                                 |
+| `authenticate` | (`request`) => `Promise`\<[`OysterAuthResult`](host.md#oysterauthresult)\> |
+| `ports`        | [`AuthorityPorts`](#authorityports)                                        |
+| `options`      | [`HostServeOptions`](#hostserveoptions)                                    |
+
+#### Returns
+
+[`ServedTable`](#servedtable)\<`E`\>
+
+---
+
+### serveDoors()
+
+```ts
+function serveDoors<E>(table): ServedTable<E>;
+```
+
+Serve a table of doors and public routes only (a Worker's top-level dispatch,
+before any tenant is selected): a route that needs an Oyster principal is
+refused, never admitted.
+
+#### Type Parameters
+
+| Type Parameter      |
+| ------------------- |
+| `E` _extends_ `Env` |
+
+#### Parameters
+
+| Parameter | Type                       |
+| --------- | -------------------------- |
+| `table`   | [`Routes`](#routes)\<`E`\> |
+
+#### Returns
+
+[`ServedTable`](#servedtable)\<`E`\>
+
+---
+
+### serveCapability()
+
+```ts
+function serveCapability(table, ports): ServedTable<CapabilityEnv>;
+```
+
+Serve one capability's declared table under the host dispatcher's admission,
+read from `c.env`: the App already holds the capability, and each route still
+decides its own resource. Every request here is App-mediated, however it was
+admitted (a header or a browser socket's query), so `owner("direct")` always
+refuses inside a capability.
+
+#### Parameters
+
+| Parameter | Type                                                            |
+| --------- | --------------------------------------------------------------- |
+| `table`   | [`Routes`](#routes)\<[`CapabilityEnv`](host.md#capabilityenv)\> |
+| `ports`   | [`AuthorityPorts`](#authorityports)                             |
+
+#### Returns
+
+[`ServedTable`](#servedtable)\<[`CapabilityEnv`](host.md#capabilityenv)\>