@ccmsg/cli 0.2.10 → 0.2.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/cli",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "The ccmsg daemon, CLI and agent plugins for one instance (= one config home)",
   "license": "MIT",
   "author": "kawaz",
@@ -20,7 +20,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ccmsg/protocol": "1.7.0"
+    "@ccmsg/protocol": "1.8.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.0",

package/src/auth/auth.ts

@@ -684,12 +684,17 @@ export class Auth {
       throw new OpError("auth_invalid", "この refresh token は使えません");
     }
     if (held.body.iss !== this.deps.self) {
-      // What the client said about this refresh stays here: `auth_rotate`
-      // carries the value and nothing else, and the address the issuer would
-      // see is this instance's rather than the person's. The issuer records
-      // that the family rotated, which is the part it can vouch for.
+      // What the carrier observed goes with the value: the person is at the
+      // other end of this instance's connection and not the issuer's, so these
+      // are only knowable here, and a rotation forwarded without them would be
+      // remembered as a time and nothing else. The issuer writes them
+      // unchecked, as it does the ones it observes itself (contract,
+      // `AuthRotateArgs`).
       const answer = (await this.#atIssuer(held.body.iss, "auth_rotate", {
         refresh_token: value,
+        ...(from.reason === undefined ? {} : { reason: from.reason }),
+        ...(from.ip === undefined ? {} : { ip: from.ip }),
+        ...(from.userAgent === undefined ? {} : { user_agent: from.userAgent }),
       } satisfies AuthRotateArgs)) as AuthRotateResult;
       return { session: { sub: answer.sub, access: answer.access }, refresh: answer.refresh };
     }
@@ -927,8 +932,17 @@ export function authHandlers(auth: Auth) {
       // the URL and the count of tries against it (§2.2).
       return { kind: "register", claims: auth.resolveRegistration(args.token, args.code) };
     },
-    auth_rotate: (input: HandlerInput): AuthRotateResult =>
-      auth.rotate((input.args as unknown as AuthRotateArgs).refresh_token),
+    auth_rotate: (input: HandlerInput): AuthRotateResult => {
+      const args = input.args as unknown as AuthRotateArgs;
+      // The receiving instance's account of the person, taken as stated: it is
+      // the only one that saw them, and `last_refresh` is a hint nothing is
+      // decided by (contract, `AuthRotateArgs`).
+      return auth.rotate(args.refresh_token, {
+        ...(args.reason === undefined ? {} : { reason: args.reason }),
+        ...(args.ip === undefined ? {} : { ip: args.ip }),
+        ...(args.user_agent === undefined ? {} : { userAgent: args.user_agent }),
+      });
+    },
   };
 }
 

package/src/instance/client.ts

@@ -0,0 +1,183 @@
+/** Where a request came from, when something in front of us is forwarding it
+ * (§3.1).
+ *
+ * The address the listener observed is the one thing here that cannot be
+ * claimed, and behind a reverse proxy it is always the proxy's. `X-Forwarded-*`
+ * carries what the proxy saw, but the header is a header: anyone who can reach
+ * the port can write one. The operator names the proxies as CIDR blocks, which
+ * is the only way this instance can tell a forwarding it asked for from a
+ * forwarding a caller invented.
+ *
+ * What is recovered is a hint and not a credential — an address is what a
+ * person recognises their own session by (DR-0001 §2.2), and nothing is
+ * admitted or refused by it. That is also why a wrong answer here is worse than
+ * no answer: a forged address kept on a record is a hint pointing away from
+ * whoever reads it.
+ */
+
+/** One address block, as the operator wrote it. Held as the address's bytes and
+ * how many of its leading bits the block fixes. */
+interface Cidr {
+  readonly bytes: Uint8Array;
+  readonly bits: number;
+}
+
+/** Parse an address, or answer nothing for a text that is not one.
+ *
+ * IPv4 and IPv6 are both read to bytes here rather than compared as text: a
+ * block is a run of bits, and two spellings of one address (`::ffff:127.0.0.1`
+ * and `127.0.0.1`, `::1` and `0:0:0:0:0:0:0:1`) are the same address. An
+ * IPv4-mapped IPv6 address is answered as its four IPv4 bytes, so an operator
+ * who wrote `127.0.0.0/8` is not asked to also write the mapped spelling of it.
+ */
+export function addressBytes(text: string): Uint8Array | undefined {
+  // A zone id names an interface on the host that holds the address, and says
+  // nothing about which address it is.
+  const bare = text.includes("%") ? text.slice(0, text.indexOf("%")) : text;
+  if (bare === "") return undefined;
+  return bare.includes(":") ? ipv6Bytes(bare) : ipv4Bytes(bare);
+}
+
+function ipv4Bytes(text: string): Uint8Array | undefined {
+  const parts = text.split(".");
+  if (parts.length !== 4) return undefined;
+  const bytes = new Uint8Array(4);
+  for (const [index, part] of parts.entries()) {
+    // Leading zeros are refused rather than read: `0177.0.0.1` is one address
+    // to a library that reads it as octal and another to one that does not, and
+    // an address this instance is unsure of is not one to trust a header by.
+    if (!/^(?:0|[1-9][0-9]{0,2})$/.test(part)) return undefined;
+    const value = Number(part);
+    if (value > 255) return undefined;
+    bytes[index] = value;
+  }
+  return bytes;
+}
+
+function ipv6Bytes(text: string): Uint8Array | undefined {
+  const halves = text.split("::");
+  if (halves.length > 2) return undefined;
+  const head = groupsOf(halves[0] ?? "");
+  const tail = halves.length === 2 ? groupsOf(halves[1] ?? "") : [];
+  if (head === undefined || tail === undefined) return undefined;
+  // The address's last group may be written as a dotted IPv4, which is how a
+  // mapped address is spelled; it stands for the two groups it fills.
+  const last = tail.length > 0 ? tail : head;
+  const trailing = last[last.length - 1];
+  let embedded: Uint8Array | undefined;
+  if (trailing !== undefined && trailing.includes(".")) {
+    embedded = ipv4Bytes(trailing);
+    if (embedded === undefined) return undefined;
+    last.pop();
+  }
+  const front = bytesOfGroups(head);
+  const back = bytesOfGroups(tail);
+  if (front === undefined || back === undefined) return undefined;
+  const stated = front.length + back.length + (embedded === undefined ? 0 : 4);
+  // Without `::` the groups are the whole address; with it they are less than
+  // the whole, since it has to stand for at least one group of zeros.
+  if (halves.length === 1 ? stated !== 16 : stated > 14) return undefined;
+  const bytes = new Uint8Array(16);
+  bytes.set(front, 0);
+  const rest = new Uint8Array([...back, ...(embedded ?? [])]);
+  bytes.set(rest, 16 - rest.length);
+  return mappedV4(bytes) ?? bytes;
+}
+
+function bytesOfGroups(groups: readonly string[]): Uint8Array | undefined {
+  const bytes = new Uint8Array(groups.length * 2);
+  for (const [index, group] of groups.entries()) {
+    if (!/^[0-9a-fA-F]{1,4}$/.test(group)) return undefined;
+    const value = Number.parseInt(group, 16);
+    bytes[index * 2] = value >> 8;
+    bytes[index * 2 + 1] = value & 0xff;
+  }
+  return bytes;
+}
+
+/** The four IPv4 bytes of an IPv4-mapped address (`::ffff:0:0/96`), if it is
+ * one. Held as IPv4 so that one written block covers both spellings. */
+function mappedV4(bytes: Uint8Array): Uint8Array | undefined {
+  for (let index = 0; index < 10; index += 1) if (bytes[index] !== 0) return undefined;
+  if (bytes[10] !== 0xff || bytes[11] !== 0xff) return undefined;
+  return bytes.slice(12);
+}
+
+function groupsOf(half: string): string[] | undefined {
+  if (half === "") return [];
+  const groups = half.split(":");
+  return groups.some((group) => group === "") ? undefined : groups;
+}
+
+/** Parse `<address>/<bits>`, or a bare address as the block holding it alone.
+ * Answers nothing for a text that is not a block, which is what lets config
+ * refuse it at load rather than silently trusting nobody. */
+export function parseCidr(text: string): Cidr | undefined {
+  const slash = text.lastIndexOf("/");
+  const address = slash === -1 ? text : text.slice(0, slash);
+  const bytes = addressBytes(address);
+  if (bytes === undefined) return undefined;
+  const width = bytes.length * 8;
+  if (slash === -1) return { bytes, bits: width };
+  const suffix = text.slice(slash + 1);
+  if (!/^(?:0|[1-9][0-9]?[0-9]?)$/.test(suffix)) return undefined;
+  const bits = Number(suffix);
+  if (bits > width) return undefined;
+  return { bytes, bits };
+}
+
+function within(address: Uint8Array, block: Cidr): boolean {
+  // A block fixes bits of one family, so an address of the other is outside it.
+  if (address.length !== block.bytes.length) return false;
+  const whole = block.bits >> 3;
+  for (let index = 0; index < whole; index += 1) {
+    if (address[index] !== block.bytes[index]) return false;
+  }
+  const rest = block.bits & 7;
+  if (rest === 0) return true;
+  const mask = 0xff << (8 - rest);
+  return ((address[whole] ?? 0) & mask) === ((block.bytes[whole] ?? 0) & mask);
+}
+
+/** Whether an address is one of the named blocks. */
+export function trusted(address: string | undefined, blocks: readonly Cidr[]): boolean {
+  if (address === undefined || blocks.length === 0) return false;
+  const bytes = addressBytes(address);
+  if (bytes === undefined) return false;
+  return blocks.some((block) => within(bytes, block));
+}
+
+/** The address the person is at, as far as this instance can tell.
+ *
+ * The observed address when it is not a proxy the operator named — a header
+ * from anyone else is a claim about somebody else and is dropped. When it is
+ * one, `X-Forwarded-For` is read from the right and the first address that is
+ * not itself a trusted proxy is answered: the entries to the right were written
+ * by the proxies in the chain, and the first one outside that chain is the last
+ * value this instance has any reason to believe. Everything further left was
+ * written by whoever was talking to the outermost proxy and could say anything.
+ *
+ * A chain of nothing but trusted proxies leaves the observed address, which is
+ * the honest answer when every value in the header is one of our own hops.
+ */
+export function clientAddress(
+  request: Request,
+  observed: string | undefined,
+  proxies: readonly Cidr[],
+): string | undefined {
+  if (!trusted(observed, proxies)) return observed;
+  const forwarded = request.headers.get("x-forwarded-for");
+  if (forwarded === null) return observed;
+  const hops = forwarded
+    .split(",")
+    .map((hop) => hop.trim())
+    .filter((hop) => hop !== "");
+  for (let index = hops.length - 1; index >= 0; index -= 1) {
+    const hop = hops[index] ?? "";
+    if (addressBytes(hop) === undefined) return observed;
+    if (!trusted(hop, proxies)) return hop;
+  }
+  return observed;
+}
+
+export type { Cidr };

package/src/instance/config.ts

@@ -1,6 +1,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute } from "node:path";
 import type { Endpoint } from "@ccmsg/protocol";
+import { parseCidr } from "./client.ts";
 
 /** Where the instance accepts WebSocket connections, and from whom.
  *
@@ -14,6 +15,15 @@ export interface EntryConfig {
   /** Source addresses allowed to connect. Empty means every address the bind
    * itself already permits, which for the default loopback bind is this host. */
   readonly source_ips: readonly string[];
+  /** Address blocks, in CIDR notation, whose `X-Forwarded-For` this instance
+   * believes.
+   *
+   * Separate from `source_ips` because the two answer different questions: that
+   * one is who may connect at all, this one is whose account of somebody else
+   * to take. A reverse proxy is commonly allowed in without being the only
+   * thing allowed in, and an operator with no proxy leaves this empty and has
+   * every forwarding header ignored. */
+  readonly trusted_proxies: readonly string[];
 }
 
 /** One value a launch recipe's command reads, as the operator declares it. */
@@ -274,10 +284,22 @@ function entryOf(file: string, raw: unknown): EntryConfig {
   if (typeof host !== "string" || host === "") {
     throw new ConfigError(file, "entry.host must be an address to bind");
   }
+  const proxies = stringsOf(file, "entry.trusted_proxies", fields["trusted_proxies"]);
+  // Read here rather than where a request is: a block that parses to nothing
+  // would silently trust nobody, and an operator who wrote one meant to trust
+  // somebody.
+  const unreadable = proxies.filter((block) => parseCidr(block) === undefined);
+  if (unreadable.length > 0) {
+    throw new ConfigError(
+      file,
+      `entry.trusted_proxies must be CIDR blocks, got ${unreadable.join(", ")}`,
+    );
+  }
   return {
     host,
     port,
     source_ips: stringsOf(file, "entry.source_ips", fields["source_ips"]),
+    trusted_proxies: proxies,
   };
 }
 

package/src/instance/instance.ts

@@ -87,6 +87,7 @@ import {
   handleAuth,
   recordsDir,
 } from "../auth/index.ts";
+import { type Cidr, clientAddress, parseCidr } from "./client.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";
@@ -264,7 +265,8 @@ async function bindForMesh(config: InstanceConfig, mesh: Mesh): Promise<MeshWiri
         ? Promise.resolve(failure(undefined, "internal_error", "this instance is still starting"))
         : instance.handle(frame, conn),
     entry: entryPolicy(config, true, () => instance?.auth),
-    route: async (request) => (await mesh.route(request)) ?? (await instance?.route(request)),
+    route: async (request, source) =>
+      (await mesh.route(request)) ?? (await instance?.route(request, source)),
     onConn: (conn, info) => {
       mesh.accept(conn, info);
       instance?.accepted(conn, info);
@@ -313,6 +315,10 @@ export class Instance {
   /** The person's authentication: who may open a connection, and the records
    * that say so (DR-0001). */
   readonly #auth: Auth;
+  /** The forwarding proxies the operator named, read once: a block is config,
+   * and parsing one per request would be work done for every caller to answer
+   * a question the config already settled. */
+  readonly #proxies: readonly Cidr[];
   readonly #handlers: Handlers;
   readonly #capabilities: ReadonlySet<Capability>;
   /** Set the moment shutdown starts, which is the re-entry guard of §8.5 step
@@ -343,6 +349,12 @@ export class Instance {
     now?: () => Timestamp,
   ) {
     this.#conns = wiring?.conns ?? new ConnRegistry();
+    // Config refused anything that does not parse, so what is dropped here is
+    // nothing an operator wrote.
+    this.#proxies = (config.entry?.trusted_proxies ?? []).flatMap((block) => {
+      const parsed = parseCidr(block);
+      return parsed === undefined ? [] : [parsed];
+    });
     this.#mesh = wiring?.mesh;
     this.#boundWs = wiring?.ws;
     // Every capability rests on an upstream, so what is configured is what
@@ -401,13 +413,23 @@ export class Instance {
       },
     });
 
+    // Which transcript a sid means. Only this instance's config home is ever
+    // looked in (M6): a session that greeted said where its transcript is, and
+    // one that never greeted is looked for under that home and nowhere else.
+    // Both the ops that read a transcript and the tails that follow one ask
+    // here, so a sid resolves to the same file whichever way it is reached.
+    const transcriptFiles = new TranscriptFiles({
+      configHome: paths.configHome,
+      announced: (sid) => this.#sessions.transcriptPath(sid),
+    });
+
     // The transcript tails and their folds. Built before the sessions domain
     // and reading from it lazily: the fold is one of the sessions domain's
     // inputs (§5.1) while the path to follow is one of its outputs, and the
     // two meet at the moment a tail starts rather than at construction.
     this.#transcripts = new Transcripts({
       self: this.self,
-      pathOf: (sid) => this.#sessions.transcriptPath(sid),
+      pathOf: (sid) => transcriptFiles.path(sid),
       publish: (topic, data) => {
         this.#topics.publish(topic, data);
       },
@@ -433,6 +455,9 @@ export class Instance {
       transcript: this.#transcripts,
       gateway: this.#gateway,
       terminals: hostTerminalReader(),
+      log: (msg, fields) => {
+        this.log.write(msg, fields);
+      },
       ...(this.#mesh === undefined ? {} : { mesh: this.#mesh }),
       onChanged: () => {
         this.#status.refresh();
@@ -557,15 +582,6 @@ export class Instance {
     });
     const origin = config.upstream.sandbox_origin;
 
-    // Which transcript an op means, for the ops that read one rather than
-    // follow one. Only this instance's config home is ever looked in (M6): a
-    // session that greeted said where its transcript is, and one that never
-    // greeted is looked for under that home and nowhere else.
-    const transcriptFiles = new TranscriptFiles({
-      configHome: paths.configHome,
-      announced: (sid) => this.#sessions.transcriptPath(sid),
-    });
-
     this.#handlers = completeHandlers({
       hello: this.#sessions.hello,
       session_stopping: this.#sessions.stopping,
@@ -644,7 +660,7 @@ export class Instance {
           },
           // The gateway posts to the address this instance already serves,
           // behind the same entry check (§3.1).
-          route: (request) => this.route(request),
+          route: (request, source) => this.route(request, source),
         }),
       );
     }
@@ -665,11 +681,16 @@ 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. */
-  async route(request: Request): Promise<Response | undefined> {
+  async route(request: Request, source?: string): 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 }, {});
+    const ip = clientAddress(request, source, this.#proxies);
+    const authorized = await handleAuth(
+      request,
+      { auth: this.#auth, self: this.self },
+      ip === undefined ? {} : { ip },
+    );
     if (authorized !== undefined) return authorized;
     return await this.#gateway.route(request);
   }

package/src/sessions/registry.ts

@@ -67,6 +67,13 @@ export interface SessionsDeps {
   readonly onChanged?: () => void;
   /** How often the confirmation poll runs, for a test that cannot wait. */
   readonly pollMs?: number;
+  /** Where this domain says what it declined to act on. A greeting whose
+   * `transcript_path` this instance will not read is answered `ok` all the
+   * same — the field is simply absent from what `peers` says of the session —
+   * and the reason it is absent is operational rather than contractual, so it
+   * is written here for `ccmsg daemon log` to answer with. Absent where
+   * nothing collects it. */
+  readonly log?: (message: string, fields?: Record<string, unknown>) => void;
   /** How the terminal a session runs in is read from its process. Absent on a
    * host where no process's environment can be read, where every row's
    * terminal stays unknown — which is a state the classification has. */
@@ -245,7 +252,7 @@ export class Sessions implements UpstreamResource {
     const expiresAt = this.deps.authExpiresAt?.(input.conn);
     const sid = requiredSid(args);
     if (sid !== undefined) {
-      this.register(sid, args, this.deps.configHome);
+      this.register(sid, args);
       input.conn.onClose(() => this.release(sid));
     }
     return {
@@ -503,10 +510,15 @@ export class Sessions implements UpstreamResource {
    * silence for a retraction would let each of them erase what the last one
    * knew, and the session would be described by whichever process spoke most
    * recently rather than by everything it has said. */
-  private register(sid: Sid, args: HelloArgs, configHome: string): void {
+  private register(sid: Sid, args: HelloArgs): void {
     const now = Date.now();
     const held = this.#connected.get(sid);
-    const meta = { ...this.#stated.get(sid), ...metaOf(args, configHome) };
+    const meta = {
+      ...this.#stated.get(sid),
+      ...metaOf(args, this.deps.configHome, (refused) => {
+        this.deps.log?.("transcript_path not taken", { sid, path: args.transcript_path, refused });
+      }),
+    };
     this.#connected.set(sid, {
       sid,
       connected_at: held?.connected_at ?? now,
@@ -689,15 +701,22 @@ export class Sessions implements UpstreamResource {
  * else — a session naming a file elsewhere is a session that named nothing,
  * which is what a session that stayed silent already is (M6). It is not an
  * error: how a session describes itself is its own business, and the instance
- * simply does not act on a description it cannot stand behind. */
-function metaOf(args: HelloArgs, configHome: string): SessionMeta {
+ * simply does not act on a description it cannot stand behind. Why a path was
+ * not taken is told to `refused`, which is the operator's answer to a field
+ * that is simply absent from what `peers` says. */
+function metaOf(
+  args: HelloArgs,
+  configHome: string,
+  refused: (reason: string) => void,
+): SessionMeta {
   const meta: Record<string, string> = {};
   for (const field of META_FIELDS) {
     const value = args[field];
     if (value === undefined) continue;
     if (field === "transcript_path") {
-      const path = ownTranscript(value, configHome);
-      if (path !== undefined) meta[field] = path;
+      const taken = ownTranscript(value, configHome);
+      if (typeof taken === "string") meta[field] = taken;
+      else refused(taken.refused);
       continue;
     }
     meta[field] = value;
@@ -721,19 +740,33 @@ function metaOf(args: HelloArgs, configHome: string): SessionMeta {
  * symlink and one spelled directly are the same path, and a link anywhere
  * along it that leads out of the tree lands outside and is refused. What is
  * already there must be a file: a directory by that name is not a transcript.
- */
-function ownTranscript(named: string, configHome: string): string | undefined {
-  if (!isAbsolute(named)) return undefined;
-  let projects: string;
+ *
+ * `projects/` itself is settled the same way, so a config home whose first
+ * session has yet to write anything is a boundary all the same: the directory
+ * that is there is followed, the part that is not is taken as spelled, and the
+ * comparison is between two paths resolved by one rule. The config home is not
+ * treated that way — an instance answers for a home it is running out of, and
+ * one that is not there names no tree to be inside of. */
+function ownTranscript(named: string, configHome: string): string | Refused {
+  if (!isAbsolute(named)) return { refused: "not an absolute path" };
+  let projects: string | undefined;
   try {
-    projects = realpathSync(join(configHome, "projects"));
+    projects = resolveAsFarAsItGoes(join(realpathSync(configHome), "projects"));
   } catch {
-    return undefined;
+    return { refused: "the config home is not there" };
   }
   const settled = resolveAsFarAsItGoes(named);
-  if (settled === undefined || !within(settled, projects)) return undefined;
+  if (projects === undefined || settled === undefined || !within(settled, projects)) {
+    return { refused: "outside this config home's projects tree" };
+  }
   const stat = statSync(settled, { throwIfNoEntry: false });
-  return stat === undefined || stat.isFile() ? settled : undefined;
+  if (stat !== undefined && !stat.isFile()) return { refused: "not a file" };
+  return settled;
+}
+
+/** Why a stated path was not taken, in the words the log states it in. */
+interface Refused {
+  readonly refused: string;
 }
 
 /** The path with every segment of it that exists resolved.

package/src/transcript/files.ts

@@ -38,11 +38,24 @@ export interface TranscriptFilesDeps {
 export class TranscriptFiles {
   constructor(private readonly deps: TranscriptFilesDeps) {}
 
-  /** The session's own transcript. */
-  session(sid: Sid): string {
+  /** The session's own transcript, or nothing where this instance holds none.
+   *
+   * Two ways to the one file, in the order of what each is good for: what the
+   * session announced is exact and costs no search, and the walk finds the
+   * file by the identity it carries in its name (`<sid>.jsonl`) for a session
+   * that never greeted or is no longer running. Both stay inside this
+   * instance's `projects/` — the announced path because it was taken only if
+   * it was inside it, the walk because that tree is what it walks (M6). */
+  path(sid: Sid): string | undefined {
     const announced = this.deps.announced(sid);
     if (announced !== undefined && isFile(announced)) return announced;
-    const found = this.find(sid);
+    return this.find(sid);
+  }
+
+  /** The session's own transcript, for an op that has nothing to answer
+   * without one. */
+  session(sid: Sid): string {
+    const found = this.path(sid);
     if (found === undefined) throw new OpError("not_found", `no transcript is held for ${sid}`);
     return found;
   }

package/src/transcript/transcripts.ts

@@ -5,8 +5,10 @@ import { type Appended, TranscriptTail } from "./tail.ts";
 
 export interface TranscriptsDeps {
   readonly self: InstanceId;
-  /** Where a session's transcript is, as the session announced it (§5.1). A
-   * sid with no path is one that never said, and nothing is guessed for it. */
+  /** Where a session's transcript is: what it announced when it greeted
+   * (§5.1), or the `<sid>.jsonl` under this instance's `projects/` that
+   * carries its name. A sid neither names nor is named by a file there has
+   * none, and nothing is guessed for it. */
   readonly pathOf: (sid: Sid) => string | undefined;
   /** The one way a value reaches subscribers (§6.1). */
   readonly publish: (topic: string, data: unknown) => void;

package/src/transport/ws.ts

@@ -39,8 +39,13 @@ export interface WsOptions {
    * posts to this instance reaches it at the address it already has, and the
    * entry check of §3.1 runs before this is asked, so a route cannot be
    * reached by anyone the WebSocket could not be. Answering `undefined` leaves
-   * the request to the upgrade, which refuses it. */
-  readonly route?: (request: Request) => Promise<Response | undefined>;
+   * the request to the upgrade, which refuses it.
+   *
+   * `source` is the peer address the server observed, passed for the reason
+   * `allowRequest` is given it: what a route can be told about where a request
+   * came from is written by whoever is in front of us, and only the listener
+   * knows who that actually was. */
+  readonly route?: (request: Request, source: string | undefined) => Promise<Response | undefined>;
 }
 
 /** Accept the webui, and later mesh peers, over WebSocket.
@@ -61,10 +66,11 @@ export function serveWs(options: WsOptions): Listener {
     hostname: options.hostname ?? "127.0.0.1",
     port: options.port,
     async fetch(request, srv) {
-      if (entry.allowRequest?.(request, srv.requestIP(request)?.address) === false) {
+      const source = srv.requestIP(request)?.address;
+      if (entry.allowRequest?.(request, source) === false) {
         return new Response("Forbidden", { status: 403 });
       }
-      const routed = await options.route?.(request);
+      const routed = await options.route?.(request, source);
       if (routed !== undefined) return routed;
       if (!entryPath(new URL(request.url).pathname, path)) {
         return new Response("Not Found", { status: 404 });