@fungi.computer/oyster 0.6.0 → 0.7.0

package/dist/authorization.d.ts

@@ -0,0 +1,307 @@
+/**
+ * Oyster's one authorization owner. Every Oyster HTTP route is registered
+ * through {@link routes} with a typed {@link Requirement}; a table's `serve`
+ * is the only place those declarations become a Hono router, so an undeclared
+ * route cannot be served and a declared one cannot skip its decision.
+ *
+ * Who may reach what is decided here once, from one {@link Authority}: the
+ * owner reaches everything; a named key reaches exactly its Ear Tag grants
+ * (Apps, Agents, the Computer); an Agent reaches its App tool policy. An
+ * anonymous request reaches only the public routes: sign-in, robots.txt and
+ * digest-pinned assets. The App gate
+ * (`apps/gate.ts`) still owns App-declaration rules; it asks this module for a
+ * principal's App reach.
+ */
+import { Hono, type Context, type Env, type ErrorHandler } from "hono";
+import type { MiddlewareHandler } from "hono/types";
+import * as Schema from "effect/Schema";
+import type { HostActor } from "@fungi.computer/puffball/app";
+import type { AppToolPolicy } from "./apps/tools.js";
+import { type LiveOysterKey } from "./keys.js";
+import type { CapabilityEnv, OysterAuthResult, OysterHost } from "./host.js";
+import type { TenantPrincipal } from "./tenant.js";
+/**
+ * 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 {@link 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`.
+ */
+export declare function keyAppAccess(key: LiveOysterKey, installationId: string): AppToolPolicy | null;
+/** Agent access is scoped to the granted Agent ids, never inferred from App grants. */
+export declare function keyAgentAccess(key: LiveOysterKey, agentId: string): boolean;
+/** Whether a live key's own grants turn its Computer access on. Off by default. */
+export declare function keyAllowsComputerUse(key: LiveOysterKey): boolean;
+/** The owner, as every owner route receives it. */
+export type OwnerPrincipal = Readonly<{
+    actor: Extract<HostActor, {
+        kind: "member";
+    }>;
+    role: "owner";
+}>;
+/** True only for a member admitted with the owner role. */
+export declare function oysterPrincipalIsOwner(principal: TenantPrincipal): principal is OwnerPrincipal;
+/** A member, owner or not, as member routes receive it. */
+export type MemberPrincipal = Extract<TenantPrincipal, {
+    role: "owner" | "member";
+}>;
+/** The live facts this module reads to decide; every host supplies the same ports. */
+export type AuthorityPorts = Readonly<{
+    /** One key's live grants; `null` for an unknown, revoked, expired or suspended key. */
+    liveKey: (keyId: string) => Promise<LiveOysterKey | null>;
+    /** An Agent's host-attested App tool policy; `null` grants no App reach. */
+    appToolPolicy: (actor: Extract<HostActor, {
+        kind: "agent";
+    }>) => AppToolPolicy | null | Promise<AppToolPolicy | null>;
+}>;
+/** A host's own ports: its key store's liveness and its Agents' tool policy. */
+export declare function hostAuthorityPorts(host: Pick<OysterHost, "keys" | "appToolPolicy">): AuthorityPorts;
+/**
+ * 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.
+ */
+export 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";
+    }>;
+}>;
+/** Resolve one principal's authority through the live key port. */
+export declare function authorityOf(principal: TenantPrincipal, ports: AuthorityPorts): Promise<Authority>;
+/** Whether this authority reaches one Agent and its Sessions. Only the owner and granted keys do. */
+export declare function reachesAgent(authority: Authority, agentId: string): 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.
+ */
+export declare function reachesComputer(authority: Authority): boolean;
+/**
+ * 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.
+ */
+export declare function appToolAccess(authority: Authority, installationId: string, ports: AuthorityPorts): Promise<AppToolPolicy | null>;
+/** One installation as reach decisions see it. */
+export type ReachableInstallation = Readonly<{
+    installationId: string;
+}>;
+/**
+ * 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.
+ */
+export declare function reachesInstallation(authority: Authority, installation: ReachableInstallation, access: "read" | "use", ports: AuthorityPorts): Promise<boolean>;
+/** Whether a live key's grants permit a one-use device enrollment. */
+export declare function allowsMachineEnrollment(key: LiveOysterKey): boolean;
+/** The request facts a requirement reads. */
+export type RequestFacts = Readonly<{
+    /** The incoming request. */
+    request: Request;
+    /** One path parameter of the matched route. */
+    param: (name: string) => string | undefined;
+    /** Decode the JSON body (shared with the handler's own read); `null` when it does not match. */
+    body: <T>(schema: Schema.Decoder<T>) => Promise<T | null>;
+    /** The request's principal, authenticated once by the serving table. */
+    principal: () => Promise<OysterAuthResult>;
+    /** Whether an App sent this request (the page bridge, or any capability call). */
+    mediated: boolean;
+    ports: AuthorityPorts;
+}>;
+/** Every requirement kind; the law test proves each has both outcomes. */
+export type RequirementKind = "public" | "door" | "owner" | "member" | "app" | "apps" | "agent" | "agents" | "computer";
+/** How the law and the host table read one route's requirement. */
+export type DeclaredRequirement = Readonly<{
+    kind: RequirementKind;
+    /** An owner route's reach: `direct` refuses App-mediated requests. */
+    via?: "direct" | "direct-or-app";
+    /** Why a route needs no Oyster principal (`public`, `door`). */
+    reason?: string;
+}>;
+/**
+ * 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.
+ */
+export declare class Requirement<Admitted> {
+    #private;
+    /** Type-only: what the requirement admits. Never present at run time. */
+    readonly admitted?: Admitted;
+    /** Module-private: use the requirement constructors below. */
+    constructor(token: symbol, declared: DeclaredRequirement, admit: (facts: RequestFacts) => Promise<Admitted | Response>);
+}
+/** A browser page asks to sign in; every other refused request gets its status. */
+export declare function unauthenticated(request: Request, result: Extract<OysterAuthResult, {
+    kind: "refused";
+}>): Response;
+/** Served without any principal: sandboxed App bytes, page assets, sign-in. */
+export declare function publicRoute(reason: string): 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.
+ */
+export declare function door(reason: string): Requirement<null>;
+/** Where an owner request came from: the owner directly, or an App acting through the shell. */
+export type OwnerOrigin = "owner-direct" | "app";
+/** What an owner route receives. */
+export type OwnerAdmission = 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.
+ */
+export declare function owner(via: "direct" | "direct-or-app"): Requirement<OwnerAdmission>;
+/**
+ * Any member, owner or not; never a key or Agent. `deny` shapes the
+ * refusal for a contract whose wire already names one.
+ */
+export declare function member(deny?: () => Response): Requirement<Readonly<{
+    principal: MemberPrincipal;
+}>>;
+/**
+ * An App route: any signed-in principal, decided per call by the App gate,
+ * which reads this module's {@link appToolAccess}.
+ */
+export declare function app(): Requirement<Readonly<{
+    principal: TenantPrincipal;
+}>>;
+/** What a collection route receives: the authority and its reach over each item. */
+export type CollectionAdmission<Item> = Readonly<{
+    authority: Authority;
+    /** Whether this authority may see one item of the collection. */
+    reaches: (item: Item) => Promise<boolean>;
+}>;
+/** The installation list (the home page): the owner sees all, keys their granted ones. */
+export declare function apps(): Requirement<CollectionAdmission<ReachableInstallation>>;
+/** What an Agent route receives. */
+export type AgentAdmission = 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.
+ */
+export declare function agent(id?: (facts: RequestFacts) => Promise<string | null>): Requirement<AgentAdmission>;
+/** Agents (and their inbox rows): the owner sees all, a key its granted Agents. */
+export declare function agents(): Requirement<CollectionAdmission<string>>;
+/** The host's Computer, its workspace files and media: see {@link reachesComputer}. */
+export declare function computer(): Requirement<Readonly<{
+    principal: TenantPrincipal;
+}>>;
+/** An HTTP method a route may declare. */
+export type Method = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** One declared route, as the law test and the host's table read it. */
+export type RouteDeclaration = Readonly<{
+    methods: readonly Method[] | "ALL";
+    path: string;
+    requirement: DeclaredRequirement;
+}>;
+/** A handler receives the request and exactly what its requirement admitted. */
+export type Handler<E extends Env, P extends string, Admitted> = (context: Context<E, P>, admitted: Admitted) => Response | Promise<Response>;
+/** Per-route options; middleware runs after the requirement admits. */
+export type RouteOptions<E extends Env, P extends string> = Readonly<{
+    middleware?: readonly MiddlewareHandler<E, P>[];
+}>;
+/**
+ * A declared route table: a frozen, opaque value only {@link routes} 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 {@link serveHost}, {@link serveDoors} and {@link 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.
+ */
+export declare class Routes<E extends Env> {
+    #private;
+    /** Module-private: use {@link routes}. */
+    constructor(token: symbol);
+    /** Register one GET route. */
+    get<P extends string, A>(path: P, requirement: Requirement<A>, handler: Handler<E, P, A>, options?: RouteOptions<E, NoInfer<P>>): this;
+    /** Register one POST route. */
+    post<P extends string, A>(path: P, requirement: Requirement<A>, handler: Handler<E, P, A>, options?: RouteOptions<E, NoInfer<P>>): this;
+    /** Register one PUT route. */
+    put<P extends string, A>(path: P, requirement: Requirement<A>, handler: Handler<E, P, A>, options?: RouteOptions<E, NoInfer<P>>): this;
+    /** Register one DELETE route. */
+    delete<P extends string, A>(path: P, requirement: Requirement<A>, handler: Handler<E, P, A>, options?: RouteOptions<E, NoInfer<P>>): this;
+    /** Register one route for every method. */
+    all<P extends string, A>(path: P, requirement: Requirement<A>, handler: Handler<E, P, A>, options?: RouteOptions<E, NoInfer<P>>): this;
+    /** Register one route for several methods. */
+    on<P extends string, A>(methods: readonly Method[], path: P, requirement: Requirement<A>, handler: Handler<E, P, A>, options?: RouteOptions<E, NoInfer<P>>): this;
+    /** Serve another table's routes at this position, keeping its own error handler. */
+    include(other: Routes<E>): this;
+    /** Answer an error thrown by this table's own handlers. */
+    onError(handler: ErrorHandler<E>): this;
+    /** Every route this table and its included tables declare, in serving order. */
+    declarations(): readonly RouteDeclaration[];
+}
+/** Start a declared route table. */
+export declare function routes<E extends Env>(): Routes<E>;
+/** What a header hook may read of a finished response: never its body or request. */
+export type ResponseView = Readonly<{
+    status: number;
+    /** A copy: changing it changes nothing served. */
+    headers: Headers;
+}>;
+/** One header hook: the headers to add to a finished response, if any. */
+export type ResponseHeaders = (response: ResponseView) => Readonly<Record<string, string>> | null;
+/** How the host table is served beyond its principal and ports. */
+export type HostServeOptions = Readonly<{
+    /**
+     * Headers to add to every finished response (never an upgraded socket).
+     * Each hook sees only a read-only view of the response the route answered
+     * with, after its requirement decided, and can only add headers.
+     */
+    headers?: readonly ResponseHeaders[];
+    /** Record Server-Timing through Hono's own `timing` middleware. */
+    serverTiming?: Readonly<{
+        totalDescription: string;
+    }>;
+}>;
+/** A served table: it answers requests and names what it serves, and is never a router. */
+export type ServedTable<E extends Env> = Readonly<{
+    /** Answer one request. */
+    fetch: (...request: Parameters<Hono<E>["fetch"]>) => Promise<Response>;
+    /** Answer one request built from a path or URL (tests and composition). */
+    request: (...request: Parameters<Hono<E>["request"]>) => Promise<Response>;
+    /** Every path the router answers, for the law test. */
+    servedPaths: () => readonly string[];
+}>;
+/**
+ * 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.
+ */
+export declare function serveHost<E extends Env>(table: Routes<E>, authenticate: (request: Request) => Promise<OysterAuthResult>, ports: AuthorityPorts, options?: HostServeOptions): 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.
+ */
+export declare function serveDoors<E extends Env>(table: Routes<E>): ServedTable<E>;
+/**
+ * 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.
+ */
+export declare function serveCapability(table: Routes<CapabilityEnv>, ports: AuthorityPorts): ServedTable<CapabilityEnv>;