@ccmsg/cli 0.1.0 → 0.2.1

package/src/instance/instance.ts

@@ -1,6 +1,7 @@
 import { mkdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import {
+  type AuthRecord,
   type Capability,
   type Endpoint,
   type InstanceId,
@@ -52,6 +53,7 @@ import {
 import { topicHandlers, Topics } from "../topics/index.ts";
 import { TranscriptFiles, Transcripts } from "../transcript/index.ts";
 import {
+  type AuthorizedUpgrade,
   ConnRegistry,
   type EntryPolicy,
   type Listener,
@@ -76,6 +78,16 @@ import {
   translateHandlers,
   translateSetup,
 } from "../translate/index.ts";
+import {
+  adminRequestOf,
+  Auth,
+  AuthRecords,
+  AuthTopic,
+  authHandlers,
+  handleAdmin,
+  handleAuth,
+  recordsDir,
+} from "../auth/index.ts";
 import { type EntryConfig, type InstanceConfig, loadConfig } from "./config.ts";
 import { completeHandlers } from "./handlers.ts";
 import { acquireLock, type Held, isHeldByUs, type Lock } from "./lock.ts";
@@ -94,6 +106,14 @@ export interface StartOptions {
   /** Overrides the mesh's own intervals, for a test that cannot wait out a
    * heartbeat or a reconnection backoff. */
   readonly meshTiming?: MeshTiming;
+  /** The clock the person's authentication judges expiry against.
+   *
+   * An access token lasts hours, so a test that wanted to watch a connection
+   * reach its deadline would have to wait them out. Moving this instead lets
+   * the deadline arrive on the real path — the timer the connection was held
+   * with, and the close at the end of it — rather than through a second way of
+   * closing that only a test ever takes. */
+  readonly now?: () => Timestamp;
 }
 
 /** The mesh intervals a caller may shorten. The values themselves, and why they
@@ -179,6 +199,7 @@ export async function start(options: StartOptions = {}): Promise<StartOutcome> {
       gateway,
       helper,
       wiring,
+      options.now,
     );
     wiring?.attach(instance);
     await instance.listen();
@@ -246,10 +267,11 @@ async function bindForMesh(config: InstanceConfig, mesh: Mesh): Promise<MeshWiri
       instance === undefined
         ? Promise.resolve(failure(undefined, "internal_error", "this instance is still starting"))
         : instance.handle(frame, conn),
-    entry: entryPolicy(config, true),
+    entry: entryPolicy(config, true, () => instance?.auth),
     route: async (request) => (await mesh.route(request)) ?? (await instance?.route(request)),
     onConn: (conn, info) => {
       mesh.accept(conn, info);
+      instance?.accepted(conn, info);
     },
   });
   try {
@@ -292,6 +314,9 @@ export class Instance {
   readonly #direct: DirectRoute;
   readonly #notify: Notify;
   readonly #translate: Translate | undefined;
+  /** The person's authentication: who may open a connection, and the records
+   * that say so (DR-0001). */
+  readonly #auth: Auth;
   readonly #handlers: Handlers;
   readonly #capabilities: ReadonlySet<Capability>;
   /** Set the moment shutdown starts, which is the re-entry guard of §8.5 step
@@ -318,6 +343,8 @@ export class Instance {
     setup: GatewaySetup = {},
     helper?: string,
     wiring?: MeshWiring,
+    /** The clock the person's authentication reads (`StartOptions.now`). */
+    now?: () => Timestamp,
   ) {
     this.#conns = wiring?.conns ?? new ConnRegistry();
     this.#mesh = wiring?.mesh;
@@ -346,6 +373,14 @@ export class Instance {
       publish: (topic, data, instance) => {
         this.#topics.publish(topic, data, instance);
       },
+      // What a peer wrote on `auth_records`, folded into the set this instance
+      // holds. It is not relayed onward: every instance subscribes to every
+      // peer, so a record reaches all of them without anyone repeating it, and
+      // what this instance writes travels as its own (DR-0001 §2.6).
+      element: (_topic, _instance, data) => {
+        const stated = (data as { records?: AuthRecord[] } | undefined)?.records;
+        if (Array.isArray(stated)) this.#auth.merge(stated);
+      },
       // What `peers` says about the instances is this instance's own view, so
       // it is restated when that view moves (§7.5).
       changed: () => {
@@ -390,6 +425,7 @@ export class Instance {
     this.#sessions = new Sessions({
       self: this.self,
       endpoint: selfEndpoint(config),
+      authExpiresAt: (conn) => this.#auth.expiresAt(conn),
       configHome: paths.configHome,
       stateDir: paths.stateDir,
       capabilities: [...this.#capabilities],
@@ -474,6 +510,33 @@ export class Instance {
     });
     this.#topics.attach("kv", kv);
 
+    // The credentials, tokens and removals the cluster shares (DR-0001 §2.6).
+    // Written down beside the store and for the same reason: none of it is
+    // derived from anything else this instance holds (§3.6).
+    const records = new AuthRecords({
+      dir: recordsDir(paths.stateDir),
+      self: this.self,
+      ...(now === undefined ? {} : { now }),
+      publish: (written) => {
+        this.#topics.publish("auth_records", { records: written });
+      },
+    });
+    this.#auth = new Auth({
+      self: this.self,
+      records,
+      origins: () => config.entry?.origins ?? [],
+      endpoint: () => selfEndpoint(config),
+      unit: paths.key,
+      ...(this.#mesh === undefined
+        ? {}
+        : { ask: (to, op, args) => (this.#mesh as Mesh).ask(to, op, args) }),
+      ...(now === undefined ? {} : { now }),
+      log: (msg, fields) => {
+        this.log.write(msg, fields);
+      },
+    });
+    this.#topics.attach("auth_records", new AuthTopic(this.self, records));
+
     // The upstreams that answer a question rather than hold a value. Each is
     // built only where its config named one, and dispatch has already refused
     // the ops for the capability this instance then does not have.
@@ -532,6 +595,7 @@ export class Instance {
       ...(this.#translate === undefined ? {} : translateHandlers(this.#translate)),
       ...gatewayHandlers(setup),
       ...kvHandlers(kv),
+      ...authHandlers(this.#auth),
       instance_ping: (): InstancePingResult => this.ping(),
       instance_shutdown: () => {
         // The reply goes out when this handler's value reaches the driver, so
@@ -557,7 +621,14 @@ export class Instance {
       listenUds({
         path: this.paths.socketReal,
         conns: this.#conns,
-        handle: (frame, conn) => this.handle(frame, conn),
+        // The one door, plus the administrative frames that may be asked only
+        // here: registering a passkey is local by design, and reaching this
+        // address is what says the caller is local (DR-0001 §2.2).
+        handle: (frame, conn) => {
+          const admin = adminRequestOf(frame);
+          if (admin !== undefined) return Promise.resolve(handleAdmin(this.#auth, admin));
+          return this.handle(frame, conn);
+        },
       }),
     );
     // The address clients use, moved onto this process once it is accepting.
@@ -572,7 +643,10 @@ export class Instance {
           port: this.config.entry.port,
           conns: this.#conns,
           handle: (frame, conn) => this.handle(frame, conn),
-          entry: entryPolicy(this.config, false),
+          entry: entryPolicy(this.config, false, () => this.#auth),
+          onConn: (conn, info) => {
+            this.accepted(conn, info);
+          },
           // The gateway posts to the address this instance already serves,
           // behind the same entry check (§3.1).
           route: (request) => this.route(request),
@@ -596,8 +670,29 @@ export class Instance {
    * gateway's webhook is the one such route this instance answers itself; the
    * mesh's two are answered before this is asked, because they are served
    * before anything is proven and this instance's own routes are not. */
-  route(request: Request): Promise<Response | undefined> {
-    return this.#gateway.route(request);
+  async route(request: Request): Promise<Response | undefined> {
+    // The person's authentication comes first: it is the one route reached
+    // before anything is proven, and the gateway's webhook carries its own
+    // secret and cannot be confused with it (DR-0001 §2.7).
+    const authorized = await handleAuth(
+      request,
+      { auth: this.#auth, self: this.self, origins: () => this.config.entry?.origins ?? [] },
+      {},
+    );
+    if (authorized !== undefined) return authorized;
+    return await this.#gateway.route(request);
+  }
+
+  /** The person's authentication, for the entry policy and for a test. */
+  get auth(): Auth {
+    return this.#auth;
+  }
+
+  /** A connection the listener accepted. One that an access token opened is
+   * held until that token runs out (DR-0001 §2.5); a peer's is the mesh's. */
+  accepted(conn: Requester, info: { readonly auth?: AuthorizedUpgrade }): void {
+    if (info.auth === undefined) return;
+    this.#auth.hold(conn, { sub: info.auth.sub, expiresAt: info.auth.expiresAt });
   }
 
   /** Every bound WebSocket address, as `host:port`. */
@@ -847,11 +942,15 @@ export function selfEndpoint(config: InstanceConfig): Endpoint | undefined {
  * the one that must say so. An empty `source_ips` leaves the addresses to the
  * bind, which for the default loopback host is this machine.
  *
- * These two are the whole of it until the person's own authentication lands
- * (DR-0001): the entry token they replaced only ever restated the uid boundary,
- * which on a tailnet nothing here can cross anyway, and a passkey is what will
- * answer "who came" rather than "could they read a file". */
-function entryPolicy(config: InstanceConfig, mesh: boolean): EntryPolicy {
+ * Neither of them says who came, which is what the access token on the
+ * handshake answers (DR-0001 §2.5): every connection that is not a peer's
+ * presents one, and a handshake without one is refused rather than let in as an
+ * anonymous person. */
+function entryPolicy(
+  config: InstanceConfig,
+  mesh: boolean,
+  auth: () => Auth | undefined,
+): EntryPolicy {
   const entry = config.entry;
   if (entry === undefined) return {};
   return {
@@ -873,14 +972,29 @@ function entryPolicy(config: InstanceConfig, mesh: boolean): EntryPolicy {
       if (mesh && offered.includes(MESH_PROTOCOL)) {
         return { ok: true, protocol: MESH_PROTOCOL, mesh: true };
       }
-      // The handshake echoes a subprotocol only when one was offered: a browser
-      // fails a connection whose reply names none of what it asked for.
-      const selected = offered[0];
-      return selected === undefined ? { ok: true } : { ok: true, protocol: selected };
+      // Everyone else is a person, and a person presents the access token they
+      // were given when they authenticated. It rides in a subprotocol because
+      // that is the only field a browser lets a WebSocket handshake carry.
+      const presented = offered.find((name) => name.startsWith(TOKEN_PROTOCOL));
+      if (presented === undefined) {
+        return { ok: false, reason: "this connection presents no access token" };
+      }
+      const held = auth();
+      const admitted = held?.admits(presented.slice(TOKEN_PROTOCOL.length));
+      if (admitted === undefined) {
+        return { ok: false, reason: "this access token is not accepted" };
+      }
+      // The handshake echoes the subprotocol it selected: a browser fails a
+      // connection whose reply names none of what it asked for.
+      return { ok: true, protocol: presented, auth: admitted };
     },
   };
 }
 
+/** How an access token reaches a WebSocket handshake (DR-0001 §2.4). The proxy
+ * in front of an instance has to pass `Sec-WebSocket-Protocol` through. */
+export const TOKEN_PROTOCOL = "ccmsg.token.";
+
 function protocolsOf(request: Request): string[] {
   const header = request.headers.get("sec-websocket-protocol");
   if (header === null) return [];

package/src/mesh/mesh.ts

@@ -18,7 +18,7 @@ import {
   type SettledIdentity,
 } from "../dispatch/index.ts";
 import type { TopicValue } from "../topics/index.ts";
-import { isClusterTopic, Relay } from "./relay.ts";
+import { AUTH_TOPIC, isClusterTopic, Relay } from "./relay.ts";
 import {
   ALLOWED_ALGS,
   EphemeralKey,
@@ -120,6 +120,13 @@ export interface MeshHost {
   handle(frame: unknown, conn: Requester): Promise<DispatchResult>;
   /** Hand a relayed frame to this instance's own subscribers (§7.4). */
   publish(topic: string, data: unknown, instance: InstanceId): void;
+  /** Take a frame on a topic the relay does not carry.
+   *
+   * `auth_records` is the one: its granularity is `element`, so a frame states
+   * the entries that moved rather than a whole value per instance, and there is
+   * nothing for the relay's last-value-per-instance table to hold. What
+   * receives it is the set itself, which merges by key (DR-0001 §2.6). */
+  element(topic: string, instance: InstanceId, data: unknown): void;
   /** Which instances can be reached has changed, which is part of what this
    * instance states on `peers` (§7.5). */
   changed(): void;
@@ -280,7 +287,7 @@ export class Mesh {
    * always among them: it is the routing table of §7.3, and a question about
    * where a session lives is answered whether or not anyone is subscribed
    * (§6.3, "reading the current value is not what subscription drives"). */
-  readonly #demanded = new Set<string>(["peers"]);
+  readonly #demanded = new Set<string>(["peers", AUTH_TOPIC]);
   #host: MeshHost | undefined;
 
   /** What the peers said, kept across a disconnection (§7.5). */
@@ -458,6 +465,35 @@ export class Mesh {
     return await settled.promise;
   }
 
+  /** Ask another instance one op, as this instance rather than for anybody.
+   *
+   * What the person's authentication needs of a peer (`auth_resolve`,
+   * `auth_rotate`) is a fact only its issuer holds, asked for by the instance
+   * that needs it — so the `caller` is this instance's own role, and the
+   * request travels the ordinary forwarding path (§7.3, DR-0001 §2.6).
+   *
+   * The body of the reply is answered, and a refusal is thrown as the error the
+   * far end named, so a caller reads one outcome rather than a result kind. */
+  async ask(
+    to: InstanceId,
+    op: string,
+    args: Record<string, unknown>,
+  ): Promise<Record<string, unknown>> {
+    const result = await this.forward(
+      to,
+      { op, request_id: `mesh-ask-${randomId()}`, ...args },
+      { role: "instance" },
+    );
+    if (result.kind === "reply") {
+      const { ok: _ok, request_id: _id, ...body } = result.response;
+      return body;
+    }
+    if (result.kind === "error") {
+      throw new OpError(result.response.error.code, result.response.error.msg);
+    }
+    throw new OpError("instance_unreachable", `${to} did not answer ${op}`);
+  }
+
   /** Whether this connection is an established link to a peer. */
   isLink(conn: Requester): boolean {
     return this.#linkOf.has(conn);
@@ -499,7 +535,10 @@ export class Mesh {
    * instance asks of every peer, and the frames come back unchanged (§7.4).
    * `peers` is never given up, because it is also the routing table. */
   demand(topic: string, wanted: boolean): void {
-    if (!isClusterTopic(topic)) return;
+    // `auth_records` is never given up and never asked for on demand: every
+    // instance holds the whole set whether or not anything local is watching
+    // it, the way `peers` is also the routing table (§7.4, DR-0001 §2.6).
+    if (topic === AUTH_TOPIC || !isClusterTopic(topic)) return;
     if (wanted) {
       if (this.#demanded.has(topic)) return;
       this.#demanded.add(topic);
@@ -527,7 +566,13 @@ export class Mesh {
       // have in common is that they are this deployment's people rather than
       // any one session: a cluster topic is the same value for all of them
       // (§6.2), so there is nothing narrower to name.
-      caller: { role: "user" } satisfies CallerIdentity,
+      //
+      // `auth_records` is the exception, and the one topic no person may hear:
+      // it carries the tokens that authenticate them, so the instance asks for
+      // it as itself (DR-0001 §2.6).
+      caller: (topic === AUTH_TOPIC
+        ? { role: "instance" }
+        : { role: "user" }) satisfies CallerIdentity,
     };
     if (afterAck) conn.deferSend(frame);
     else conn.send(frame);
@@ -706,6 +751,10 @@ export class Mesh {
     // Our own value, come back around a triangle. Relaying it again would put
     // this instance's value on the wire as something it received.
     if (instance === this.deps.id) return true;
+    if (topic === AUTH_TOPIC) {
+      this.#host?.element(topic, instance as InstanceId, fields["data"]);
+      return true;
+    }
     this.relay.accept(instance as InstanceId, topic, fields["data"]);
     return true;
   }

package/src/mesh/relay.ts

@@ -22,6 +22,13 @@ export const CLUSTER_TOPICS: readonly string[] = PLAIN_TOPICS.filter(
   (topic) => TOPIC_ATTRIBUTES[topic].granularity === "per_instance_whole",
 );
 
+/** The one topic the mesh carries that the relay does not.
+ *
+ * It is `element`-granular, so what travels is the entries that changed and the
+ * receiver merges them by key; and it is the instances' own, so it is asked for
+ * as the instance rather than on a person's behalf (DR-0001 §2.6). */
+export const AUTH_TOPIC = "auth_records";
+
 export function isClusterTopic(topic: string): boolean {
   return CLUSTER_TOPICS.includes(topic);
 }

package/src/sessions/registry.ts

@@ -35,6 +35,10 @@ export interface SessionsDeps {
    * what a peer is to dial is neither that nor derivable from the id. Absent on
    * an instance reached by the unix socket alone, which has no URL to state. */
   readonly endpoint?: Endpoint;
+  /** When the connection's authorization runs out, on one an access token
+   * opened (DR-0001 §2.5). Absent on the unix socket, where reaching the
+   * instance is itself the permission, and on a mesh link. */
+  readonly authExpiresAt?: (conn: Requester) => Timestamp | undefined;
   /** The one config home this instance answers for (§8.2). Its `sessions/` is
    * the only directory read, and no other config home is ever looked for (M6). */
   readonly configHome: string;
@@ -238,6 +242,7 @@ export class Sessions implements UpstreamResource {
 
   /** What every greeting answers, once whatever had to be settled has been. */
   #greeted(args: HelloArgs, input: HandlerInput): HelloResult {
+    const expiresAt = this.deps.authExpiresAt?.(input.conn);
     const sid = requiredSid(args);
     if (sid !== undefined) {
       this.register(sid, args, this.deps.configHome);
@@ -247,25 +252,22 @@ export class Sessions implements UpstreamResource {
       protocol_version: PROTOCOL_VERSION,
       instance: this.deps.self,
       ...(this.deps.endpoint === undefined ? {} : { endpoint: this.deps.endpoint }),
-      // Without a mesh the cluster is this instance alone. It appears in the
-      // list only where it has a URL to be named by: an instance serving the
-      // unix socket alone is reached by nothing that could dial an endpoint,
-      // and `instance` above has already said who is answering.
-      instances:
-        this.deps.mesh?.instances() ??
-        (this.deps.endpoint === undefined
-          ? []
-          : [
-              {
-                id: this.deps.self,
-                endpoint: this.deps.endpoint,
-                host: hostname(),
-                reachable: true,
-              },
-            ]),
+      // Without a mesh the cluster is this instance alone, and it says so:
+      // an instance serving the unix socket alone has no URL to be dialed at,
+      // which is a row without an endpoint rather than no row (contract,
+      // `InstanceInfo`).
+      instances: this.deps.mesh?.instances() ?? [
+        {
+          id: this.deps.self,
+          ...(this.deps.endpoint === undefined ? {} : { endpoint: this.deps.endpoint }),
+          host: hostname(),
+          reachable: true,
+        },
+      ],
       capabilities: [...this.deps.capabilities],
       version: this.deps.version,
       started_at: this.deps.startedAt,
+      ...(expiresAt === undefined ? {} : { auth_expires_at: expiresAt }),
     };
   }
 

package/src/transport/entry.ts

@@ -31,9 +31,19 @@ export type UpgradeDecision =
        * gets decided by the mesh handshake, so until that finishes it may do
        * only the one thing that can decide it. */
       readonly mesh?: boolean;
+      /** Who the access token on the handshake admitted, and until when
+       * (DR-0001 §2.5). The connection lives to that instant unless it is
+       * extended on itself. */
+      readonly auth?: AuthorizedUpgrade;
     }
   | { readonly ok: false; readonly reason: string };
 
+/** What a person's connection was let in as. */
+export interface AuthorizedUpgrade {
+  readonly sub: string;
+  readonly expiresAt: number;
+}
+
 /** Accepts everything. A listener given no policy is open to whatever can reach
  * the address it is bound to. */
 export const OPEN: EntryPolicy = {};

package/src/transport/ws.ts

@@ -2,12 +2,14 @@ import { MAX_FRAME_BYTES } from "@ccmsg/protocol";
 import { BaseConn, type Conn, type ConnRegistry } from "./conn.ts";
 import { createDriver, type FrameHandler } from "./driver.ts";
 import { LineReader, WriteQueue } from "./framing.ts";
-import { type EntryPolicy, OPEN } from "./entry.ts";
+import { type AuthorizedUpgrade, type EntryPolicy, OPEN } from "./entry.ts";
 import type { Listener } from "./listener.ts";
 
 /** What the upgrade hands the socket: whether it was let in as a peer. */
 interface UpgradeData {
   readonly mesh: boolean;
+  /** Who the handshake's access token admitted, on a person's connection. */
+  readonly auth?: AuthorizedUpgrade;
 }
 
 interface WsState {
@@ -27,7 +29,10 @@ export interface WsOptions {
   /** `mesh` is set when the handshake was let in as a peer rather than on the
    * entry token, so whoever holds the connection can keep it to the one
    * exchange that can prove what it is. */
-  readonly onConn?: (conn: Conn, info: { readonly mesh: boolean }) => void;
+  readonly onConn?: (
+    conn: Conn,
+    info: { readonly mesh: boolean; readonly auth?: AuthorizedUpgrade },
+  ) => void;
   /** An HTTP request that is not the upgrade, answered by whoever wants it.
    *
    * It shares this listener rather than opening a second one: a producer that
@@ -46,7 +51,7 @@ export interface WsOptions {
  * is either buffered whole by Bun or dropped whole — and the queue absorbs
  * that difference here (§3.1). */
 export function serveWs(options: WsOptions): Listener {
-  const path = options.path ?? "/ws";
+  const path = options.path ?? ENTRY_PATH;
   const entry = options.entry ?? OPEN;
   // The per-connection state is made in `open`, where the socket to write to
   // exists, so the upgrade carries nothing and the socket keeps no data of its
@@ -71,7 +76,10 @@ export function serveWs(options: WsOptions): Listener {
       const selected = decision.protocol;
       if (
         srv.upgrade(request, {
-          data: { mesh: decision.mesh === true },
+          data: {
+            mesh: decision.mesh === true,
+            ...(decision.auth === undefined ? {} : { auth: decision.auth }),
+          },
           ...(selected === undefined
             ? {}
             : { headers: { "sec-websocket-protocol": selected } satisfies Record<string, string> }),
@@ -108,7 +116,10 @@ export function serveWs(options: WsOptions): Listener {
         states.set(ws, { conn, queue, reader: new LineReader(driver) });
         options.conns.add(conn);
         const data = ws.data as UpgradeData | undefined;
-        options.onConn?.(conn, { mesh: data?.mesh === true });
+        options.onConn?.(conn, {
+          mesh: data?.mesh === true,
+          ...(data?.auth === undefined ? {} : { auth: data.auth }),
+        });
       },
       message(ws, message) {
         const state = states.get(ws);
@@ -147,6 +158,12 @@ export function serveWs(options: WsOptions): Listener {
   };
 }
 
+/** Where a person's WebSocket is answered, on whatever prefix a proxy puts the
+ * instance under. Named here because it is one door, and more than one place
+ * has to know what it is called: the entry match below, and the registration
+ * URL, which is the same address without it (DR-0001 §2.2). */
+export const ENTRY_PATH = "/ws";
+
 /** Whether a request's path is this listener's entry.
  *
  * Matched at the end rather than whole, so a proxy that puts the instance under