@volter/world-runtime 2.0.0 → 2.0.2

package/dist/src/served-world.d.ts

@@ -1,5 +1,6 @@
 import { type HistoryReference } from '@volter/world-core';
 import { type TwinStreamConnection, type TwinStreamSink } from '@volter/world-core';
+import { type TrustedIssuer } from '@volter/world-access';
 import { type Changeset, type Receipt } from '@volter/world-core';
 import { rootForControlRoot } from './root.js';
 import type { WorldInstance } from './schema.js';
@@ -29,6 +30,11 @@ export type ServedWorld = {
     console: string | null;
     stop: () => Promise<void>;
 };
+/** Where a World keeps its browser sessions (WorldDoors): a host that rotates the tokens without the doors at hand
+ *  clears it itself. */
+export declare function sessionsFile(worldRoot: string): string;
+/** Where a World keeps its named keys (their hashes, never a key): `.volter/keys.json`. */
+export declare function keysFile(worldRoot: string): string;
 /** The served name: `bare.name` (`acme/team`), else `<id>/<id>`. */
 export declare function servedName(worldRoot: string, configRef: string): string;
 /** A world MOUNTED for serving: its doors, its tokens, and a boot that writes the serve record once the
@@ -53,7 +59,11 @@ export type MountedWorld = {
     stop: () => Promise<void>;
 };
 export declare function mountWorld(name: string, opts?: {
-    root?: string;
+    passIssuers?: TrustedIssuer[];
+    root?: string; /** the host's branches of this World, by its served name */
+    branches?: (served: string) => BranchDoors | undefined; /** the origin a browser reaches this World at, when the host gives each World one */
+    browserOrigin?: (served: string) => string | null; /** served on this machine's loopback: its own pages need no token (DoorHost.localTrust) */
+    localTrust?: boolean;
 }): Promise<MountedWorld>;
 /** Boot the world (state kept) and serve it on its own port. Announces and returns after boot; `stop` downs the world. */
 export declare function serveWorld(name: string, opts?: {
@@ -99,7 +109,78 @@ export type DoorHost = {
     /** Where this host reads a twin's scenario (the handlers document a generative twin serves from,
      *  re-read on every request), or null when the twin takes none here. */
     scenarioPath?: (vendor: string) => string | null;
+    /** A twin's mirror as its pack builds it: `index.html` (the shell) or `assets/<file>`, or null when
+     *  the twin has none here. Every host answers the same mount (`/<served>/<vendor>/mirror/`); only
+     *  where the files come from differs (built at serve under Bun, prebuilt under Node, static assets
+     *  on Cloudflare). */
+    mirror?: (vendor: string, file: string) => Promise<Response | null>;
+    /** Whether the twin has a mirror on this host, without building it. */
+    hasMirror?: (vendor: string) => boolean | Promise<boolean>;
+    /** The account and token a twin's screens open signed in as, resolved by its pack from the twin's state at `root`
+     *  for the account the World's config names (`signIn.as`); null when the pack cannot, or has no such account. */
+    mirrorSignIn?: (vendor: string, as: string, ctx: {
+        root: string;
+        twin: (path: string, init?: RequestInit) => Promise<Response>;
+    }) => Promise<{
+        account: string;
+        token: string;
+    } | null>;
+    /** Where this World's clock lives in its store (the file every twin reads `worldNow()` from). */
+    clockPath?: () => string;
+    /** The origin a browser reaches this World at (`http://<world>--<org>.localhost:<port>`), when the
+     *  host gives each World one: its session lives only there (docs/contributing/architecture.md,
+     *  "Viewing a World"). Null, or absent, on a host whose Worlds share one origin. */
+    browserOrigin?: () => string | null;
+    /** The origin another World this host serves (a branch of this one) is reached at, where it has one of its own. */
+    originOf?: (served: string) => string | null;
+    /** This World is served on this machine's loopback, for the person at it: a page of this World, reached by a
+     *  loopback name, is given the World's session without a token (`localSession`). A remote host leaves it absent,
+     *  and its pages sign in with a token. */
+    localTrust?: () => boolean;
+    /** The platforms whose passes open this World (docs/contributing/architecture.md, "The hosted product"): a person a
+     *  trusted platform signed a pass for is given a session of the pass's scope. Absent, or empty, no pass opens it. */
+    passIssuers?: () => TrustedIssuer[];
+    /** This World's branches, where the host can make them (a branch is another World, so making one
+     *  is the host's act); absent, the branches doors answer 404. */
+    branches?: BranchDoors;
+};
+/** A branch as its parent lists it. */
+export type BranchRow = {
+    name: string;
+    from: string;
+    at: {
+        instant?: string;
+        live?: boolean;
+        label?: string;
+    } | null;
+    createdAt: string;
+    expiresAt: string | null;
 };
+/** What a host does for a World's branches doors. `create` makes a World cloned from this one at
+ *  `at` (its history cut at that instant), removed when `ttlSeconds` runs out; `origin` is where the
+ *  request reached this World (a host whose branches clone over its public URL uses it). */
+export type BranchDoors = {
+    list: () => Promise<BranchRow[]>;
+    /** `parentKey`: the key the branch reaches this World with (never this World's own token), made for whoever asked */
+    create: (at: {
+        instant?: string;
+        live?: boolean;
+        label?: string;
+    }, ttlSeconds: number | null, origin: string, parentKey?: string) => Promise<{
+        name: string;
+        token: string;
+        readToken: string;
+        expiresAt: string | null;
+    }>;
+    remove: (name: string) => Promise<boolean>;
+};
+/** A World's browser-origin label, `<world>--<org>`, or null when its names cannot make one (a DNS
+ *  label: lowercase letters, digits and single hyphens, 63 at most). A host maps a label back by the
+ *  Worlds it serves, never by parsing it. */
+export declare function worldOriginLabel(served: string): string | null;
+/** The header the doors set on a read-scope request to a twin: the twin refuses the caller's writes
+ *  and still makes the vendor's own moves. It only restricts, so a twin trusts it without a token. */
+export declare const READ_ONLY_HEADER = "x-volter-read-only";
 export declare class WorldDoors {
     readonly name: string;
     readonly worldRoot: string;
@@ -112,6 +193,46 @@ export declare class WorldDoors {
     constructor(name: string, worldRoot: string, configRef: string, served: string, host: DoorHost, token: string, readToken: string);
     /** New tokens; a request presenting the old ones is refused from the next call on. */
     retoken(token: string, readToken: string): void;
+    /** BROWSER SESSIONS: the session cookie carries an opaque id, never a token, so a leaked cookie is one session and
+     *  not the World's write token; rotating the tokens ends every session. Kept in the World's store, so a restart
+     *  keeps them; each lasts 30 days from its opening. */
+    private sessionsPath;
+    private held;
+    private sessions;
+    private keepSessions;
+    /** A new session of `scope`: its id, the cookie's value. A token's lasts 30 days; a person's from a pass, `who`,
+     *  lasts as long as the pass's platform says (twelve hours), so a person removed there loses it within the day. */
+    private openSession;
+    /** NAMED KEYS: what an app or a script holds (docs/contributing/architecture.md, "The hosted product"), each named
+     *  when made, shown once, kept only as its hash, and revoked alone; the World's two tokens stay its first keys. */
+    private heldKeys;
+    private keys;
+    private keepKeys;
+    /** When a key was last used, to the minute (a key in constant use is not a write per request). */
+    private touchKey;
+    /** `GET|POST /-/<world>/keys`, `DELETE /-/<world>/keys/<id>`, `DELETE /-/<world>/keys?person=<sub>`: named keys are
+     *  managed with write access by the World's token or a person's session, never by a key (a key cannot make a key
+     *  that outlives it). Each records who made it and whom it is for; the token may give one an end and a person, and
+     *  revoke every key made by or for a person (their leaving the org). */
+    /** The person a key is for: whom it was made for, else the person whose session made it. */
+    private keyPerson;
+    /** Revoke the keys `pick` names, and what they reach: the branches whose parent key goes, and the branches (with their
+     *  keys) a revoked key made. Answers the revoked keys' ids. */
+    private revokeKeys;
+    private keysDoor;
+    /** Passes this World has already spent: each opens one session. */
+    private readonly spent;
+    /** A PASS opens a session: a person a trusted platform signed a pass for, into this World, at its own origin, asked
+     *  from its own page (the console reads the pass from its address's fragment and posts it here). */
+    /** The org its host records as this World's owner (`<state>/owner`, written at its making or its claim), or null. */
+    private recordedOwner;
+    private passSession;
+    /** A named key that still opens this World: not revoked, not expired. */
+    private liveKey;
+    /** The named key a request presents, with the end of its life. */
+    private presentedKey;
+    private endSession;
+    private endSessions;
     /** The world's twins, by vendor, once booted. */
     twins(): string[];
     private up;
@@ -119,8 +240,29 @@ export declare class WorldDoors {
      *  the injector's `x-twins-key` (a zero-edit app keeps its SDK's own Authorization), `Bearer <token>`,
      *  GitHub's `token <token>`, or the password half of `Basic` (Jira's email:token). */
     private scope;
-    /** The World token the request presented, in whichever form, and the scope it opens. */
-    private match;
+    /** The request's scope, whether it came by a token the caller presented or by a browser's session
+     *  (the cookie `POST …/session` set), and the token that opened it. Every form presented is a
+     *  candidate: a mirror page sends the VENDOR's bearer (the token its sign-in holds) beside the World's
+     *  session cookie, and the cookie is what opens the World. With a browser origin of its own
+     *  (`browserOrigin`), a World honours its session only on that origin: a session cookie on any other
+     *  (a host's shared origin, path-addressed) opens nothing. */
+    /** What this World issued, for world-access to decide a grant against: its two tokens, its named keys, its sessions. */
+    private issued;
+    private credential;
+    /** The session cookie's name where `url` reached this World, or null where a session opens nothing:
+     *  on the World's own origin a host-only cookie (`__Host-` over https); without an origin of its own,
+     *  the path-scoped cookie a shared origin has always carried. */
+    private sessionCookieName;
+    /** The session cookie for `url`, set to `value`: host-only over the whole origin on the World's own
+     *  origin (a `__Host-` cookie must be), scoped to the World's paths on a shared one. Null where a
+     *  session opens nothing (another World's origin). */
+    private sessionCookie;
+    /** A browser's session opens the World only to the World's own pages: a request the session cookie carries must
+     *  say `Sec-Fetch-Site: same-origin` (a browser sets it; a page cannot), or be a read the person navigated to
+     *  (`none`: a typed or bookmarked address). Another page of the same site (a sibling World's origin shares its
+     *  suffix) is refused its reads too, so a twin that echoes the caller's Origin with credentials cannot hand one
+     *  World's data to another World's page; a request with no header fails closed. Null when it may pass. */
+    private crossOriginSession;
     /** Open one connection on a byte-stream door for the holder of the World's (write) token; null when
      *  the token is not the World's or the World has no such stream. */
     openStream(token: string, id: string, sink: TwinStreamSink, peer: string): TwinStreamConnection | null;
@@ -129,14 +271,24 @@ export declare class WorldDoors {
     private controlRoot;
     private stateOf;
     handle(request: Request): Promise<Response>;
+    /** THE MIRROR MOUNT: `/<served>/<vendor>/mirror/` and `…/mirror/assets/<file>`, keyless and GET only —
+     *  the pack's own shell and client. The shell's <base> is the twin's place in this World, so the
+     *  mirror reads and writes the World's wire with the browser's session (`POST …/session`); any
+     *  other path under mirror/ is one of the mirror's own routes (a reloaded deep link) and gets the
+     *  shell. A link is not a twin and has no mirror. */
+    private mirror;
+    /** A vendor's screens' sign-in (`signIn.as`), once per account every twelve hours while this World is served (rotating the
+     *  tokens forgets them): the pack finds the account and mints its credential through the twin's own doors; a failure
+     *  is not kept, so the next page asks again. An account or credential that is not plain printable text is refused. */
+    private readonly signIns;
+    private readonly signInAt;
+    private signedIn;
+    /** Whether a twin enforces a read-scope request itself (its manifest names `requestScopes: ['read']`):
+     *  only then may the read token reach it with anything but GET or HEAD. Asked once per twin. */
+    private readonly readEnforced;
+    private enforcesRead;
     /** The vendor wire: `/<org>/<world>/<vendor>/<rest>` → the twin's own URL. */
     private wire;
-    /** Whether the twin's pack ships a mirror (its vendor's UI over this World's state). */
-    private hasMirror;
-    /** THE MIRROR MOUNT, as the hosted World serves it (apps/cloud supervisor.ts): `/<org>/<world>/<vendor>/mirror/`
-     *  and `…/mirror/assets/*`, keyless, GET only — the pack's own shell and bundle. The shell's <base> is the
-     *  twin's place under this World, so its reads go to the keyed wire with the browser's World session. */
-    private mirror;
     private linksPath;
     /** The World's links: name → the vendor origin it forwards to. */
     links(): Record<string, {
@@ -151,6 +303,41 @@ export declare class WorldDoors {
     private observedAt;
     /** The world's own doors under `/-/<org>/<world>/`. */
     private door;
+    /** A browser session for this World: the presented token as an HttpOnly cookie scoped to the World's
+     *  paths, so a page served under it (a twin's mirror) reads the wire as the token's holder, in the
+     *  token's scope. */
+    /** THE LOCAL SESSION: a World served on this machine's loopback never asks the person at it for a token. Any
+     *  website can send requests to 127.0.0.1, so what stands in for the token is proof the request is this World's own
+     *  page, as Vite and Jupyter check their dev servers: the Host is a loopback name (a rebound DNS name is not, so DNS
+     *  rebinding fails), the browser's Origin is exactly this origin (another site's page cannot claim it, so CSRF
+     *  fails), and the fetch says it is same-origin. A process on this machine can claim all three: a local World
+     *  trusts this machine's user, as a local dev server does. The session is the write token's. A World with no origin
+     *  of its own (a shared origin, where every World's pages are one origin) is not trusted so: its page asks for a
+     *  token. */
+    private localPage;
+    private localSession;
+    private session;
+    /** THE CLOCK: the frozen instant every twin stamps from, kept in the World's store. It moves only
+     *  forward once the World has entries (a twin's catch-up stamps each move at its due time, so a
+     *  clock set back would put new entries before old ones); the past is reached by branching. */
+    private clockDoor;
+    /** THE BRANCHES DOORS: list (read), make one as of an instant, remove one (write). The host makes
+     *  and removes them; a host that makes none answers 404, and a view offers no "as of". */
+    private branchesDoor;
+    /** The newest entry's instant across the World's twins (ms), or null when it has none. */
+    private newestEntry;
+    /** THE MAP: every twin and what it holds, by resource type, and whether it has a mirror. */
+    private map;
+    /** THE TIMELINE: the entries of every twin's log merged, newest first, by each entry's instant, then
+     *  twin, then position. The World keeps no order across twins finer than its clock, and this claims
+     *  none. `before` is the cursor the previous page answered; `twin` and `trace` narrow it. */
+    private timeline;
+    /** Each twin's timeline rows, kept until its logs change: a poll of an unchanged World reads no log
+     *  (a twin is read again only when the size or time of its parent log, branch log or branch record
+     *  moved), and the merged order is sorted again only when a twin was. */
+    private readonly timelineByTwin;
+    private timelineMerged;
+    private timelineRows;
     /** PUSH: see `landChangeset` — the door hands the body to it. */
     private push;
 }