@ccmsg/protocol 2.0.1 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/protocol",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "description": "Wire contract (schema + types + op attribute table) shared by the ccmsg daemon and web UI",
   "license": "MIT",
   "author": "kawaz",

package/src/attributes.ts

@@ -37,7 +37,17 @@ export interface OpAttributes {
    * What the carrier decides is not authorization but what the op can do: these
    * are the ops that set or read a cookie, which a frame on an open connection
    * cannot, and they answer before any identity is settled. The route each is
-   * published at belongs to the instance, not here. */
+   * published at belongs to the instance, not here.
+   *
+   * Being reachable from a page is also what gives the three that settle an
+   * identity the only headers this contract reads over HTTP: the `Origin` a
+   * browser states, held to the origin of the web UI the credential or the
+   * registration names, and `Sec-Fetch-Site`, which has to say the call came
+   * from a page at all — a navigation typed into the address bar is not how
+   * anyone authenticates. A missing header is a failure like a wrong one, and either
+   * answers `auth_invalid` without saying which. `auth.challenge` is checked
+   * against neither, having nothing yet to be checked against; what it hands
+   * out is spendable only at its issuer. */
   readonly carrier?: "http";
   /** Present when the role changes what the reply may contain rather than
    * whether the call is allowed. */

package/src/common/auth.ts

@@ -1,6 +1,34 @@
 import { type Static, Type } from "@sinclair/typebox";
 import { request, response, topicFrame } from "../envelope.ts";
-import { Endpoint, InstanceId, Timestamp } from "../identifiers.ts";
+import { Endpoint, InstanceId, type Origin, Timestamp, WebUi } from "../identifiers.ts";
+
+/** The origin of a web UI's URL: what a browser puts in an `Origin` header and
+ * in a credential's `clientDataJSON`, which is the URL's scheme and authority
+ * and no more.
+ *
+ * Derived rather than stored, and derived here rather than once per
+ * implementation, because every use of it is an exact comparison against a
+ * value a browser serialized. The normalization that makes those comparisons
+ * hold — a lowercase scheme and host, a port only where it is not the scheme's
+ * own, an address literal in its brackets — is the URL parser's, and this is
+ * the one place the contract says so. */
+export function originOf(webui: string): Origin {
+  return new URL(webui).origin;
+}
+
+/** The WebAuthn relying party a credential made at a web UI is created under:
+ * the host of its URL, port and scheme left off, as a relying party is a domain
+ * and not an origin.
+ *
+ * Derived for the same reason as the origin, and held to the host exactly. A
+ * client will accept a relying party that is the page's effective domain or a
+ * registrable suffix of it, so anything shorter than the host would be one
+ * credential several sites could answer with — which is the single thing
+ * binding a credential to one web UI rules out. An assertion's `rpIdHash` is
+ * the SHA-256 of what this returns. */
+export function rpIdOf(webui: string): string {
+  return new URL(webui).hostname;
+}
 
 /** A value that is nothing but bytes to everyone who handles it: a token, a
  * challenge, a credential id, a signature. Spelled base64url without padding so
@@ -88,9 +116,19 @@ export const RegisterClaims = Type.Object(
      * registration is posted to `<endpoint>auth/register`, and the cookie set
      * for it hangs under the same prefix. */
     endpoint: Endpoint,
-    /** The WebAuthn relying party: a domain, not an origin. Either the
-     * endpoint's host or a registrable suffix of it. */
-    rp_id: Type.String({ minLength: 1 }),
+    /** Where the URL sends the person: the web UI they will open it at, and so
+     * the page the credential will be made by. It is not read off the endpoint,
+     * the UI being publishable anywhere, and a registration URL that did not
+     * name it would not be a URL anyone could open.
+     *
+     * Its origin (`originOf`) is what the ceremony is then held to, and it is
+     * also what lets a first registration be answered across sites at all: an
+     * instance answers CORS for the origins its credentials name, and the first
+     * registration at a new UI has no credential yet — the URL it issued and
+     * still holds stands in for one until it does. That is the issuer's own
+     * knowledge and travels nowhere, which is why a registration is only
+     * completed where it was issued. */
+    webui: WebUi,
     expires_at: Timestamp,
     /** Names this registration, so it can be spent once. */
     jti: Type.String({ minLength: 1 }),
@@ -159,7 +197,13 @@ export type AuthRegisterArgs = Static<typeof AuthRegisterArgs>;
  * Only the access token is stated. The refresh token is set as a cookie by the
  * carrier that ran the op, so putting it here too would be a second copy of a
  * secret in a place the browser's script can read — which is the one property
- * the cookie exists to have. */
+ * the cookie exists to have. That holds however far the page is from the
+ * endpoint: a cookie the page's own site cannot reach is sent from a site it
+ * does not own only as a partitioned one, which keeps a session taken at one
+ * site from being carried to another — the same shape one credential per web UI
+ * already has. Sending it at all across sites takes a browser that partitions
+ * cookies, which is a premise of this contract rather than a case it
+ * accommodates: one that does not is not an environment this is spoken over. */
 export const AuthSession = Type.Object(
   {
     sub: Subject,
@@ -358,22 +402,43 @@ export const CredentialRecord = Type.Object(
     /** The endpoint this credential was registered for, as the registration's
      * claims stated it.
      *
-     * What the credential is good for, and the whole of it: an assertion is
-     * accepted only where the origin matches and the request's path falls under
-     * this base URL. `https://h.example/` and `https://h.example/personal/` are
+     * Which instance the credential admits its holder to: an assertion is
+     * accepted only where the request arrived at this base URL — the same
+     * scheme and authority, and a path below it. (The authority the request
+     * reached, which is a property of the connection; where the page asking was
+     * served from is `webui` below and a separate question.)
+     * `https://h.example/` and `https://h.example/personal/` are
      * two endpoints and take two registrations, even on one host and one
      * relying party — the RP ID says which domain an authenticator will answer
      * for, which is a coarser thing than which instance a person has been
      * admitted to. Binding to the base URL rather than the origin is what keeps
      * one instance's credential from being a way into its neighbour. */
     endpoint: Endpoint,
-    /** The relying party this credential was created under, as the claims of
-     * the registration that made it stated. Written by the registration and not
-     * derived later: a passkey only answers for the domain it was made under,
-     * so an assertion's `rpIdHash` is checked against this and not against
-     * whatever the endpoint being reached happens to be. Absent only on a
-     * record written before the field existed. */
-    rp_id: Type.Optional(Type.String({ minLength: 1 })),
+    /** The web UI the page that created this credential was served from, whose
+     * origin is the one it may ever be used from.
+     *
+     * Holding it to one origin is this contract's rule rather than WebAuthn's. A
+     * passkey is bound to its relying party, which may be a suffix of the host,
+     * so the authenticator alone would answer for every origin under that
+     * suffix. What holds a credential to one is the check made against
+     * this: the `clientDataJSON.origin` of every ceremony, registration and
+     * assertion alike, has to equal `originOf` this URL. The relying party is
+     * `rpIdOf` the same URL, which is what makes the authenticator's own
+     * binding say the same thing rather than something wider.
+     *
+     * The URL is what is kept, and the origin read off it where a header is
+     * matched — a token minted here carries the same URL and its connection's
+     * `Origin` is held to the origin of it, and the origins of an endpoint's
+     * credentials are the set the HTTP auth ops answer CORS for. Keeping the
+     * origin alongside instead would be a second copy of one fact, able to
+     * disagree with the URL a person is actually sent to. A person using web
+     * UIs at two origins holds two credentials, one per origin; two UIs under
+     * one origin are one place to every check here, there being no path in an
+     * `Origin` header to tell them apart by.
+     *
+     * Apart from `endpoint` because the two answer different questions: which
+     * page may speak, and which instance it may speak to. */
+    webui: WebUi,
     /** The authenticator's counter, when it keeps one. Synced passkeys report
      * zero forever, so only a pair of non-zero readings says anything, and a
      * reading below the last one is a refusal. */
@@ -432,6 +497,21 @@ export const TokenFamily = Type.Object(
     sub: Subject,
     /** The instance that minted the family and the only one that may write it. */
     iss: InstanceId,
+    /** The web UI the page that authenticated was served from, carried over
+     * from the credential that answered.
+     *
+     * What a connection presenting one of these tokens is held to: the
+     * handshake compares `originOf` this with the `Origin` the browser states,
+     * and a page from anywhere else is refused however good the token is —
+     * refused as an upgrade that does not happen, there being no connection yet
+     * to answer an error on. A handshake that states no `Origin` at all is
+     * refused the same way: every gate has to be passed, and a caller with
+     * nothing to compare has not passed this one. Without it a token that leaked would be usable
+     * from any page at all, since it says who the person is and nothing about
+     * what is holding it. It lives on the family rather than inside the token's
+     * own spelling because every instance has the family and none of them has
+     * the minting instance's reading of an opaque value. */
+    webui: WebUi,
     access: Type.Object({ value: Base64Url, expires_at: Timestamp }),
     refresh: Type.Object({ value: Base64Url, expires_at: Timestamp }),
     /** When the family was last rotated, and what the client said prompted it.

package/src/common/topics.ts

@@ -9,6 +9,7 @@ export const PLAIN_TOPICS = [
   "peers",
   "instances",
   "agents",
+  "terminals",
   "session.errors",
   "llm.requests",
   "llm.status",
@@ -109,6 +110,9 @@ export const TOPIC_ATTRIBUTES = {
   // is apart from the rows of `peers`.
   instances: { roles: ["session", "user"], granularity: "per_instance_whole" },
   agents: { roles: ["user"], granularity: "element" },
+  // The host's terminals, which exist whether a session is in them or not, so
+  // they are a list of their own rather than a field of a session's row.
+  terminals: { roles: ["user"], granularity: "element" },
   // A set the instance derives whole, by folding one error pattern over its
   // sessions: it learns which sessions are stopped, not that one of them
   // changed, so each frame is that reading entire.

package/src/control/agents.ts

@@ -45,7 +45,11 @@ export const AgentInfo = Type.Object(
     /** The terminal the session runs in, which is the handle a rename types
      * into. Absent when the process does not name one or its environment could
      * not be read. Read from the running process rather than remembered from
-     * when it started, since resuming a session gives it a new process. */
+     * when it started, since resuming a session gives it a new process.
+     *
+     * Where the instance states `terminals` as well, the match of the pids
+     * there is what says which terminal this run is in; this field is what an
+     * instance with no terminal manager has to go on. */
     terminal_id: Type.Optional(TerminalId),
     /** Which namespace that terminal lives in. Absent means the process set
      * none, which the multiplexer treats as its default — not the instance's

package/src/control/terminals.ts

@@ -0,0 +1,166 @@
+import { type Static, Type } from "@sinclair/typebox";
+import { topicFrame } from "../envelope.ts";
+import { InstanceId, TerminalId, Timestamp } from "../identifiers.ts";
+
+/** One terminal on a host, as the terminal manager reports it.
+ *
+ * A terminal is not an attribute of a session: a person opens one with nothing
+ * running in it, and the terminal outlives the session that was running there.
+ * So it is a row of its own, matched by `instance` and `id`, and which session
+ * is in it is read off the pids rather than stated here.
+ *
+ * The words are a terminal's own — `id`, `state`, `pid` — rather than any one
+ * manager's, so another manager's terminals are rows of the same list. Which
+ * manager a row came from is the scheme of its `id`. */
+export const TerminalInfo = Type.Object(
+  {
+    /** The instance that polled it, and whose host the pid belongs to. */
+    instance: InstanceId,
+    /** `<scheme>:<id>`, the scheme naming which terminal manager observed it. */
+    id: TerminalId,
+    /** What the terminal manager says the terminal is doing. An open set. */
+    state: Type.String(),
+    /** What is running in the terminal, as argv. */
+    command: Type.Array(Type.String()),
+    cwd: Type.Optional(Type.String()),
+    /** The main process inside the terminal. Absent where the manager reports
+     * none, which is also what leaves such a row out of every derivation
+     * below: nothing can be matched against a pid that is not there. */
+    pid: Type.Optional(Type.Integer({ minimum: 1 })),
+    started_at: Type.Optional(Timestamp),
+  },
+  { $id: "TerminalInfo" },
+);
+export type TerminalInfo = Static<typeof TerminalInfo>;
+
+/** A row that is gone: the terminal was closed, or the instance that polled it
+ * stopped. Marked rather than absent, since a frame carries only what changed. */
+export const TerminalRemoved = Type.Object(
+  {
+    instance: InstanceId,
+    id: TerminalId,
+    removed: Type.Literal(true),
+  },
+  { $id: "TerminalRemoved" },
+);
+export type TerminalRemoved = Static<typeof TerminalRemoved>;
+
+export const TerminalElement = Type.Union([TerminalInfo, TerminalRemoved], {
+  $id: "TerminalElement",
+});
+export type TerminalElement = Static<typeof TerminalElement>;
+
+/** The commands a harness is started as, by the name its binary is installed
+ * under. What `starting` below reads a terminal's `command` against, so that a
+ * shell a person opened is not read as a session on its way up.
+ *
+ * Names rather than paths: the same harness is installed under a dozen
+ * prefixes and run through as many wrappers, and none of that changes what it
+ * is. A harness outside this list is one nothing here claims to recognise — its
+ * terminal is unattached until the harness reports the run itself. */
+export const HARNESS_COMMANDS = ["claude", "codex"] as const;
+
+/** What a derivation below reads off a terminal: where it is and what is
+ * running in it. */
+interface TerminalRow {
+  readonly instance: string;
+  readonly pid?: number;
+  readonly command?: readonly string[];
+}
+
+/** What it reads off an `agents` row: where the process is, and whose session
+ * it runs. */
+interface AgentRow {
+  readonly instance: string;
+  readonly pid: number;
+  readonly sid?: string;
+}
+
+const held = (agents: readonly AgentRow[]): Set<string> =>
+  new Set(agents.map((agent) => `${agent.instance}/${agent.pid}`));
+
+/** Whether a terminal is running a harness, read off the name its command was
+ * invoked under. */
+const isHarness = (command: readonly string[] | undefined): boolean => {
+  const argv0 = command?.[0];
+  if (argv0 === undefined) return false;
+  const name = argv0.slice(argv0.lastIndexOf("/") + 1);
+  return (HARNESS_COMMANDS as readonly string[]).includes(name);
+};
+
+const key = (terminal: TerminalRow): string | undefined =>
+  terminal.pid === undefined ? undefined : `${terminal.instance}/${terminal.pid}`;
+
+/** The terminals a session is running in: those whose process is a run of that
+ * session.
+ *
+ * The pid is what says so, not `agents.terminal_id`: the terminal list is the
+ * one that knows which terminals exist, and a run reaches it as the process
+ * inside one. Both lists are the `user` role's, and both are keyed by the host
+ * the pid belongs to, which is why a row is matched by `instance` and `pid`
+ * together.
+ *
+ * Derived here rather than by each side, for the reason `liveness` is: an
+ * instance and a client that each wrote this would show one host two ways. */
+export function terminalsOf<T extends TerminalRow>(
+  sid: string,
+  agents: readonly AgentRow[],
+  terminals: readonly T[],
+): T[] {
+  const pids = held(agents.filter((agent) => agent.sid === sid));
+  return terminals.filter((terminal) => {
+    const at = key(terminal);
+    return at !== undefined && pids.has(at);
+  });
+}
+
+/** The terminals no run is in: the ones a person opened for themselves, and the
+ * ones a harness has just started in and not yet been seen as a run of.
+ *
+ * A terminal whose manager reports no pid is here too — nothing can be matched
+ * against it, so nothing can claim it. */
+export function unattachedTerminals<T extends TerminalRow>(
+  agents: readonly AgentRow[],
+  terminals: readonly T[],
+): T[] {
+  const pids = held(agents);
+  return terminals.filter((terminal) => {
+    const at = key(terminal);
+    return at === undefined || !pids.has(at);
+  });
+}
+
+/** The terminals a harness is running in that the harness has not reported: one
+ * that has started and has neither written a state file nor greeted yet. This
+ * is where a run before its state file is said, rather than as an `agents` row
+ * without a `sid`.
+ *
+ * Narrower than `unattachedTerminals` in both ways it can be: a terminal with
+ * no process is one nothing can be starting in, and a terminal running
+ * something that is not a harness is a person's own and is not on its way to
+ * becoming a session. The `command` is what says which — a pid alone cannot
+ * tell a shell from a harness — so a row that states none is not here. */
+export function starting<T extends TerminalRow>(
+  terminals: readonly T[],
+  agents: readonly AgentRow[],
+): T[] {
+  const pids = held(agents);
+  return terminals.filter((terminal) => {
+    const at = key(terminal);
+    return at !== undefined && !pids.has(at) && isHarness(terminal.command);
+  });
+}
+
+/** The `terminals` topic. Elements, like `agents`: the rows that changed since
+ * the last frame, matched by their `instance` and `id`.
+ *
+ * The `user` role's alone. A terminal is the host's, and a session has no
+ * reason to be told which terminals another session is being typed into. */
+export const TerminalsFrame = topicFrame(
+  "terminals",
+  Type.Object({
+    terminals: Type.Array(TerminalElement),
+    /** When the poll behind these rows ran. Absent before the first one. */
+    polled_at: Type.Optional(Timestamp),
+  }),
+);

package/src/fixtures/common.ts

@@ -36,7 +36,7 @@ import type {
 } from "../common/topics.ts";
 import { FIXTURE_IDS, FIXTURE_NOW } from "./ids.ts";
 
-const { sid, instance, other_instance, endpoint, other_endpoint, request_id } = FIXTURE_IDS;
+const { sid, instance, other_instance, endpoint, other_endpoint, webui, request_id } = FIXTURE_IDS;
 
 export const HELLO_SESSION_REQUEST: Static<typeof HelloSessionRequest> = {
   request_id,
@@ -277,7 +277,7 @@ export const AUTH_RESOLVE_RESPONSE = {
     sub: SUBJECT,
     unit: "personal",
     endpoint,
-    rp_id: "mba.example.ts.net",
+    webui,
     expires_at: FIXTURE_NOW + 600_000,
     jti: "01J9Z3W2Q",
     user_id: "dXNlci1oYW5kbGU",

package/src/fixtures/ids.ts

@@ -9,6 +9,17 @@ export const FIXTURE_IDS = {
   other_instance: "a1b2c3d4e5f60718293a4b5c6d7e8f90",
   endpoint: "https://mba.example.ts.net/ccmsg/personal/",
   other_endpoint: "https://nuc.example.ts.net/ccmsg/personal/",
+  /** Where the web UI is published, which is nobody's endpoint: a credential is
+   * made here and used against the endpoints above. A base URL with a path of
+   * its own, as an endpoint is, and its registrable domain is not the
+   * endpoints' — so the two are cross-site and a refresh cookie between them is
+   * a partitioned one. */
+  webui: "https://ui.example.test/ccmsg/",
+  /** A second web UI, sharing the endpoints' registrable domain: same-site, and
+   * still an origin of its own. A credential made here is a separate
+   * credential, and the cookie between it and an endpoint is not partitioned —
+   * one contract, two shapes, which is why both are written down. */
+  same_site_webui: "https://ui.example.ts.net/",
   mid: "3f9c1a7b5e2d48069c1a7b5e2d480691/1841",
   request_id: "1",
 } as const;

package/src/fixtures/index.ts

@@ -179,6 +179,7 @@ export const TOPIC_FIXTURES = {
   peers: topics.PEERS_FRAME,
   instances: topics.INSTANCES_FRAME,
   agents: topics.AGENTS_FRAME,
+  terminals: topics.TERMINALS_FRAME,
   "session.status": topics.SESSION_STATUS_FRAME,
   transcript: topics.TRANSCRIPT_FRAME,
   "transcript.items": topics.TRANSCRIPT_ITEMS_FRAME,

package/src/fixtures/topics.ts

@@ -7,13 +7,24 @@ import type { LlmRequestsFrame, LlmStatusFrame } from "../control/llm.ts";
 import type { PeersFrame } from "../control/peers.ts";
 import type { SessionErrorsFrame } from "../control/session-errors.ts";
 import type { SessionStatusFrame } from "../control/session-status.ts";
+import type { TerminalsFrame } from "../control/terminals.ts";
 import type { TranscriptFrame, TranscriptItemsFrame } from "../control/transcript.ts";
 import { TRANSCRIPT_ITEMS } from "./control.ts";
 import type { InboxFrame } from "../messaging/message.ts";
 import type { NotifyFrame } from "../messaging/notify.ts";
 import { FIXTURE_IDS, FIXTURE_NOW } from "./ids.ts";
 
-const { sid, other_sid, instance, other_instance, endpoint, other_endpoint, mid } = FIXTURE_IDS;
+const {
+  sid,
+  other_sid,
+  instance,
+  other_instance,
+  endpoint,
+  other_endpoint,
+  webui,
+  same_site_webui,
+  mid,
+} = FIXTURE_IDS;
 
 const WORKSPACE = "/repos/kawaz/ccmsg-protocol/main";
 
@@ -223,6 +234,47 @@ export const AGENTS_CHANGE_FRAME: Static<typeof AgentsFrame> = {
   data: { agents: [{ instance, pid: 7314, removed: true }], polled_at: FIXTURE_NOW + 5_000 },
 };
 
+export const TERMINALS_FRAME: Static<typeof TerminalsFrame> = {
+  ev: "topic",
+  topic: "terminals",
+  snapshot: true,
+  instance,
+  data: {
+    terminals: [
+      {
+        instance,
+        id: "hyoui:%17",
+        state: "running",
+        command: ["claude", "--continue"],
+        cwd: WORKSPACE,
+        pid: 4821,
+        started_at: FIXTURE_NOW - 600_000,
+      },
+      {
+        instance,
+        id: "hyoui:%31",
+        state: "running",
+        command: ["zsh", "-i"],
+        cwd: WORKSPACE,
+        pid: 5177,
+        started_at: FIXTURE_NOW - 120_000,
+      },
+    ],
+    polled_at: FIXTURE_NOW,
+  },
+};
+
+/** A later frame: one terminal was closed. */
+export const TERMINALS_CHANGE_FRAME: Static<typeof TerminalsFrame> = {
+  ev: "topic",
+  topic: "terminals",
+  instance,
+  data: {
+    terminals: [{ instance, id: "hyoui:%31", removed: true }],
+    polled_at: FIXTURE_NOW + 5_000,
+  },
+};
+
 export const SESSION_STATUS_FRAME: Static<typeof SessionStatusFrame> = {
   ev: "topic",
   topic: `session.status:${sid}`,
@@ -469,7 +521,7 @@ export const AUTH_RECORDS_FRAME = {
           public_key: "pQECAyYgASFYIA",
           user_handle: "dXNlci1oYW5kbGU",
           endpoint,
-          rp_id: "mba.example.ts.net",
+          webui,
           sign_count: 0,
           issued_label: "for kawaz",
           device_label: "work laptop",
@@ -481,6 +533,25 @@ export const AUTH_RECORDS_FRAME = {
           last_used_user_agent: "Mozilla/5.0",
         },
       },
+      {
+        // The same person at a second site, which shares the endpoint's
+        // registrable domain where the first does not. One credential per site,
+        // and the difference between the two is what decides whether the
+        // refresh cookie for a session made here is a partitioned one.
+        key: "credential/personal-1/Y3JlZC1pZC0y",
+        updated_at: FIXTURE_NOW,
+        body: {
+          kind: "credential",
+          sub: "personal-1",
+          credential_id: "Y3JlZC1pZC0y",
+          public_key: "pQECAyYgASFYIB",
+          user_handle: "dXNlci1oYW5kbGU",
+          endpoint,
+          webui: same_site_webui,
+          device_label: "phone",
+          registered_at: FIXTURE_NOW - 300_000,
+        },
+      },
     ],
   },
 } satisfies Static<typeof AuthRecordsFrame>;
@@ -500,6 +571,7 @@ export const AUTH_RECORDS_FAMILY_FRAME = {
           kind: "token_family",
           sub: "personal-1",
           iss: instance,
+          webui,
           access: { value: "YWNjZXNz", expires_at: FIXTURE_NOW + 10_000_000 },
           refresh: { value: "cmVmcmVzaA", expires_at: FIXTURE_NOW + 600_000_000 },
           last_refresh: {

package/src/identifiers.ts

@@ -43,6 +43,30 @@ export const InstanceId = Type.String({
 });
 export type InstanceId = Static<typeof InstanceId>;
 
+/** A host as a browser serializes one: lowercase labels, or an address literal
+ * in its brackets. No uppercase, no userinfo, no empty label and no zone id —
+ * every one of those is either a second spelling of one host or a string no URL
+ * parser will take. */
+const HOST =
+  "(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*|\\[[0-9a-f:.]+\\])";
+
+/** A port in range, 1 to 65535. */
+const PORT =
+  "(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5])";
+
+/** A scheme and authority, with the scheme's own port left unspelled — a
+ * browser omits it, so writing it would be a second name for one place. `tail`
+ * closes the pattern: the end of the string for an origin, a path for a base
+ * URL, and it is what the lookaheads read to know a port ended. */
+function authority(tail: string): string {
+  const port = (its: string) => `(?::(?!${its}(?:/|$))${PORT})?`;
+  return `^(?:https://${HOST}${port("443")}|http://${HOST}${port("80")})${tail}`;
+}
+
+/** A base URL: an authority as above, then a path that ends in a slash and
+ * carries no query or fragment. */
+const BASE_URL = authority("(?:/[^?#\\s]*)?/$");
+
 /** Where an instance is published: the base URL everything it serves hangs
  * under, ending in a slash and naming no route of its own.
  *
@@ -57,8 +81,11 @@ export type InstanceId = Static<typeof InstanceId>;
  *
  * Compared as a whole string, path included (one origin
  * may host several instances, so an origin-level comparison would confuse
- * them). The trailing slash is required so that comparison is exact: `/ccmsg`
- * and `/ccmsg/` would otherwise be two spellings of one instance.
+ * them). Every part of it is held to one spelling for that comparison's sake:
+ * the trailing slash is required, so `/ccmsg` and `/ccmsg/` are not two
+ * endpoints; the host is lowercase and the scheme's own port is left out, as a
+ * browser would write them; an internationalized host is spelled in punycode,
+ * which is what the wire carries anyway.
  *
  * Apart from `InstanceId` because the two answer different questions and change
  * on different occasions. This is what a peer dials, what the TLS certificate
@@ -66,12 +93,54 @@ export type InstanceId = Static<typeof InstanceId>;
  * as — trust is rooted in the URL and nowhere else. Which instance answers
  * there is the id, which the handshake states and which an alias or a move does
  * not alter. */
-export const Endpoint = Type.String({
-  $id: "Endpoint",
-  pattern: "^https?://[^/?#\\s]+(/[^?#\\s]*)?/$",
-});
+export const Endpoint = Type.String({ $id: "Endpoint", pattern: BASE_URL });
 export type Endpoint = Static<typeof Endpoint>;
 
+/** Where the web UI is published: the base URL a person opens it at, ending in
+ * a slash and naming no route of its own (`https://ui.example/ccmsg/`).
+ *
+ * The counterpart of `Endpoint` on the other side of the wire. An endpoint says
+ * where an instance is dialed; this says where the page doing the dialing came
+ * from, and one of each is what a credential is made against. Spelled to the
+ * same rule as an endpoint, path and trailing slash included, because it is the
+ * same kind of value: a base URL that something is published under.
+ *
+ * **What is kept and what is compared are different sizes.** The whole URL is
+ * kept: it is where a person is sent, what an operator configures, and what
+ * they read back in a list of their own credentials. Every comparison this
+ * contract makes is of the origin (`originOf`) or the host (`rpIdOf`), because
+ * a browser writes neither a path in an `Origin` header nor one in a
+ * `clientDataJSON` — there is nothing finer on the wire to compare. Two web UIs
+ * under one origin are therefore one place to everything here. The origin is
+ * read off the URL where a header has to be matched rather than kept beside it
+ * as a second field that could disagree. */
+export const WebUi = Type.String({ $id: "WebUi", pattern: BASE_URL });
+export type WebUi = Static<typeof WebUi>;
+
+/** Where a page was served from: a scheme and an authority and nothing else,
+ * spelled as a browser spells it in the `Origin` header and in a credential's
+ * `clientDataJSON` — no path, no trailing slash.
+ *
+ * Apart from `Endpoint` because the two are units of different size and answer
+ * different questions. An endpoint says which instance a person is admitted to
+ * and is compared with its path; an origin says which site the page in front of
+ * them came from, which is all the browser's same-origin rules know about and
+ * all a page's own script cannot lie about. One site may be the page for many
+ * endpoints, and one origin may carry many instances, so neither is derivable
+ * from the other.
+ *
+ * Held to the one spelling a browser serializes: a lowercase scheme, a
+ * lowercase host, and a port only where it is not the scheme's own. No
+ * userinfo, no path, no trailing slash, nothing else a URL may carry.
+ *
+ * The narrowness is the point rather than pedantry. Every use of this value is
+ * a whole-string comparison — against an `Origin` header, against a
+ * `clientDataJSON.origin`, against the members of a CORS answer — so a second
+ * spelling of one site would be a record that never matches the site it names,
+ * or an allowed origin that quietly admits nothing. */
+export const Origin = Type.String({ $id: "Origin", pattern: authority("$") });
+export type Origin = Static<typeof Origin>;
+
 /** A delivery-frame id: `<instance id>/<counter>`, numbered by the instance
  * that issued the frame. It exists so `reply_to` can point at one frame; it is
  * not a cursor and carries no ordering across instances. */

package/src/index.ts

@@ -16,6 +16,7 @@ export * from "./control/sandbox.ts";
 export * from "./control/session-errors.ts";
 export * from "./control/session-status.ts";
 export * from "./control/session.ts";
+export * from "./control/terminals.ts";
 export * from "./control/transcript.ts";
 export * from "./control/translate.ts";
 export * from "./envelope.ts";

package/src/schemas.ts

@@ -94,6 +94,7 @@ import {
 } from "./control/sandbox.ts";
 import { SessionErrorsFrame } from "./control/session-errors.ts";
 import { SessionStatusFrame } from "./control/session-status.ts";
+import { TerminalsFrame } from "./control/terminals.ts";
 import {
   SessionDumpWriteRequest,
   SessionDumpWriteResponse,
@@ -216,6 +217,7 @@ export const TOPIC_SCHEMAS = {
   peers: PeersFrame,
   instances: InstancesFrame,
   agents: AgentsFrame,
+  terminals: TerminalsFrame,
   "session.status": SessionStatusFrame,
   transcript: TranscriptFrame,
   "transcript.items": TranscriptItemsFrame,