@ccmsg/protocol 0.7.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/protocol",
-  "version": "0.7.0",
+  "version": "1.0.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

@@ -22,6 +22,16 @@ export interface OpAttributes {
   /** The capability the op needs, when it needs one. */
   readonly capability?: Capability;
   readonly locality: Locality;
+  /** Set on an op a client reaches over HTTP rather than as a frame on its
+   * WebSocket. Such an op is in this table like any other because the table is
+   * the one place authorization is decided — an op reachable without appearing
+   * here would be a second, unwritten rule about who may call what.
+   *
+   * 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. */
+  readonly carrier?: "http";
   /** Present when the role changes what the reply may contain rather than
    * whether the call is allowed. */
   readonly scope?: "role";
@@ -34,13 +44,14 @@ const ALL_ROLES = ["session", "user", "instance"] as const;
 const AGENT_AND_USER = ["session", "user"] as const;
 const USER_ONLY = ["user"] as const;
 const SESSION_ONLY = ["session"] as const;
+const INSTANCE_ONLY = ["instance"] as const;
 
 /** The whole op vocabulary, with the attributes that decide who may call each
  * op, what it needs, and where it runs. This table is the single place those
  * facts live: authorization, capability gating and forwarding all read it
  * rather than each carrying their own copy. */
 export const OP_ATTRIBUTES = {
-  // --- common: connect, declare the end, and subscribe (6) ---
+  // --- common: connect, declare the end, and subscribe (13) ---
   // `hello` and `instance_ping` address the instance the caller reached, so
   // there is nothing to forward and no unreachable instance to report — which
   // is why they are `cluster` despite answering about one instance.
@@ -72,21 +83,89 @@ export const OP_ATTRIBUTES = {
     locality: "instance-local",
     errors: [],
   },
+  // Open to every role, with which role may have which topic left to the topic
+  // table: an instance subscribes as itself to what only instances may hold,
+  // and a person is refused there by that table rather than here.
   topic_subscribe: {
     plane: "common",
-    roles: AGENT_AND_USER,
+    roles: ALL_ROLES,
     needs_hello: true,
     locality: "cluster",
     errors: ["topic_unknown"],
   },
   topic_unsubscribe: {
     plane: "common",
-    roles: AGENT_AND_USER,
+    roles: ALL_ROLES,
     needs_hello: true,
     locality: "cluster",
     errors: ["topic_unknown"],
   },
 
+  // The four ops that authenticate a person are open to every role for the
+  // same reason `hello` is: they run before there is an identity to check, and
+  // what they answer is what settles one. They are `cluster` because whichever
+  // instance is reached answers — behind a load balancer that is not a choice
+  // the caller makes — and each asks the issuing instance itself for the parts
+  // only it holds.
+  auth_challenge: {
+    plane: "common",
+    roles: ALL_ROLES,
+    needs_hello: false,
+    locality: "cluster",
+    carrier: "http",
+    errors: [],
+  },
+  auth_register: {
+    plane: "common",
+    roles: ALL_ROLES,
+    needs_hello: false,
+    locality: "cluster",
+    carrier: "http",
+    errors: ["auth_invalid", "auth_expired", "auth_unknown_issuer"],
+  },
+  auth_assert: {
+    plane: "common",
+    roles: ALL_ROLES,
+    needs_hello: false,
+    locality: "cluster",
+    carrier: "http",
+    errors: ["auth_invalid", "auth_expired", "auth_unknown_issuer"],
+  },
+  auth_refresh_token: {
+    plane: "common",
+    roles: ALL_ROLES,
+    needs_hello: false,
+    locality: "cluster",
+    carrier: "http",
+    errors: ["auth_invalid", "auth_expired", "auth_unknown_issuer"],
+  },
+  // Addresses the connection it arrives on, which is on the instance that
+  // received it: nothing to forward, as with `hello`.
+  auth_refresh: {
+    plane: "common",
+    roles: USER_ONLY,
+    needs_hello: true,
+    locality: "cluster",
+    errors: ["auth_invalid", "auth_expired"],
+  },
+  // Between instances: what an issuer alone can answer. Instance-local by the
+  // usual rule — the subject belongs to one instance, and it is reached by
+  // `to_instance` being that instance's id.
+  auth_resolve: {
+    plane: "common",
+    roles: INSTANCE_ONLY,
+    needs_hello: true,
+    locality: "instance-local",
+    errors: ["auth_invalid", "auth_expired"],
+  },
+  auth_rotate: {
+    plane: "common",
+    roles: INSTANCE_ONLY,
+    needs_hello: true,
+    locality: "instance-local",
+    errors: ["auth_invalid", "auth_expired"],
+  },
+
   // --- messaging: one-to-one delivery (4) ---
   message_send: {
     plane: "messaging",

package/src/common/auth.ts

@@ -0,0 +1,356 @@
+import { type Static, Type } from "@sinclair/typebox";
+import { request, response, topicFrame } from "../envelope.ts";
+import { Endpoint, InstanceId, Timestamp } from "../identifiers.ts";
+
+/** 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
+ * one encoding covers the values this contract issues and the ones the browser
+ * hands over, and so a value survives a URL, a header and a cookie unaltered. */
+export const Base64Url = Type.String({
+  $id: "Base64Url",
+  minLength: 1,
+  pattern: "^[A-Za-z0-9_-]+$",
+});
+export type Base64Url = Static<typeof Base64Url>;
+
+/** How long a challenge is good for. Short because a challenge is consumed
+ * within one interaction at a keyboard; the window is only what covers the
+ * person reaching for their authenticator. */
+export const AUTH_CHALLENGE_TTL_MS = 5 * 60 * 1000;
+
+/** How long a registration URL is good for. Longer than a challenge: the
+ * person has to carry the URL from a terminal to a browser first. */
+export const REGISTER_TTL_MS = 10 * 60 * 1000;
+
+/** How long a token family's tombstone is kept. A family expires on its own
+ * with the refresh token, so the mark only has to outlive the longest one.
+ *
+ * A credential's tombstone has no counterpart here on purpose: it is kept
+ * without end, because a peer returning from a partition longer than any
+ * retention would otherwise carry the removed credential back as news. */
+export const FAMILY_TOMBSTONE_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Who a person is to this cluster. Issued when the registration URL is made
+ * (`<unit>-<counter>` by default) and carried by every record they own. */
+export const Subject = Type.String({ $id: "Subject", minLength: 1, maxLength: 128 });
+export type Subject = Static<typeof Subject>;
+
+// --- challenge -------------------------------------------------------------
+
+export const AuthChallengeArgs = Type.Object({});
+export type AuthChallengeArgs = Static<typeof AuthChallengeArgs>;
+
+/** A challenge and who issued it.
+ *
+ * The issuer travels beside the value rather than inside it because the
+ * instance that receives the answer is not necessarily the one that issued it:
+ * behind a load balancer either may be reached, so the receiver reads the
+ * issuer, asks it to consume the challenge (`auth_resolve`), and verifies the
+ * assertion itself. An issuer a caller made up names an instance that knows no
+ * such challenge, which is a refusal and not a way in. */
+export const AuthChallenge = Type.Object(
+  {
+    /** At least 16 bytes of randomness, good once. */
+    challenge: Base64Url,
+    /** The instance holding it, which alone can consume it. */
+    issuer: InstanceId,
+    expires_at: Timestamp,
+  },
+  { $id: "AuthChallenge" },
+);
+export type AuthChallenge = Static<typeof AuthChallenge>;
+
+export const AuthChallengeResult = AuthChallenge;
+export type AuthChallengeResult = Static<typeof AuthChallengeResult>;
+
+export const AuthChallengeRequest = request("auth_challenge", AuthChallengeArgs);
+export const AuthChallengeResponse = response("auth_challenge", AuthChallengeResult);
+
+// --- registration ----------------------------------------------------------
+
+/** What the registration URL carries, as the instance that issued it reads it
+ * back. On the wire between a browser and an instance the whole of it is one
+ * opaque string; this shape is what `auth_resolve` answers with, so the two
+ * instances involved agree on what was authorized.
+ *
+ * Its integrity rests on a secret made for this one registration and held only
+ * in the issuing instance's memory. Nothing outlives the window: a restart
+ * loses the secret, and the remedy is to issue another URL rather than to keep
+ * a key that could sign anything later. */
+export const RegisterClaims = Type.Object(
+  {
+    /** The instance that issued the URL and holds the secret. */
+    iss: InstanceId,
+    sub: Subject,
+    /** The instance's name as a person operates it, for display. */
+    unit: Type.String({ minLength: 1 }),
+    /** The endpoint the credential is being registered for. */
+    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 }),
+    expires_at: Timestamp,
+    /** Names this registration, so it can be spent once. */
+    jti: Type.String({ minLength: 1 }),
+  },
+  { $id: "RegisterClaims" },
+);
+export type RegisterClaims = Static<typeof RegisterClaims>;
+
+/** What `navigator.credentials.create()` produced, in this contract's spelling.
+ * The browser's own field names are camelCase; they are written snake_case here
+ * like every other field on this wire, and the client that speaks to the
+ * authenticator is what maps between the two. */
+export const RegistrationCredential = Type.Object(
+  {
+    id: Base64Url,
+    raw_id: Base64Url,
+    client_data_json: Base64Url,
+    /** Attestation is `none`, so what this carries is the authenticator data
+     * and the public key, not a statement about the hardware. */
+    attestation_object: Base64Url,
+  },
+  { $id: "RegistrationCredential" },
+);
+export type RegistrationCredential = Static<typeof RegistrationCredential>;
+
+export const AuthRegisterArgs = Type.Object({
+  /** The registration URL's token, opaque to the caller and to any instance
+   * but its issuer. */
+  token: Type.String({ minLength: 1 }),
+  credential: RegistrationCredential,
+});
+export type AuthRegisterArgs = Static<typeof AuthRegisterArgs>;
+
+/** What a person holds after they are authenticated.
+ *
+ * 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. */
+export const AuthSession = Type.Object(
+  {
+    sub: Subject,
+    /** The access token and when it stops being accepted. It is presented on
+     * the WebSocket handshake, and a connection lives until this instant unless
+     * it is renewed on the connection itself. */
+    access: Type.Object({ value: Base64Url, expires_at: Timestamp }),
+  },
+  { $id: "AuthSession" },
+);
+export type AuthSession = Static<typeof AuthSession>;
+
+export const AuthRegisterResult = AuthSession;
+export type AuthRegisterResult = Static<typeof AuthRegisterResult>;
+
+export const AuthRegisterRequest = request("auth_register", AuthRegisterArgs);
+export const AuthRegisterResponse = response("auth_register", AuthRegisterResult);
+
+// --- assertion -------------------------------------------------------------
+
+/** What `navigator.credentials.get()` produced. `user_handle` is what a
+ * resident credential answers with when the person named no account, so a
+ * signed-in subject can be found without the browser having been told one. */
+export const AssertionCredential = Type.Object(
+  {
+    raw_id: Base64Url,
+    client_data_json: Base64Url,
+    authenticator_data: Base64Url,
+    signature: Base64Url,
+    user_handle: Type.Optional(Base64Url),
+  },
+  { $id: "AssertionCredential" },
+);
+export type AssertionCredential = Static<typeof AssertionCredential>;
+
+export const AuthAssertArgs = Type.Object({
+  credential: AssertionCredential,
+  /** The challenge this assertion answers, with the instance that can spend
+   * it. The value also sits inside `client_data_json`; it is stated here so the
+   * receiver knows who to ask before it parses anything the browser sent. */
+  challenge: AuthChallenge,
+});
+export type AuthAssertArgs = Static<typeof AuthAssertArgs>;
+
+export const AuthAssertResult = AuthSession;
+export type AuthAssertResult = Static<typeof AuthAssertResult>;
+
+export const AuthAssertRequest = request("auth_assert", AuthAssertArgs);
+export const AuthAssertResponse = response("auth_assert", AuthAssertResult);
+
+// --- refreshing a token pair ----------------------------------------------
+
+/** Takes no arguments: the refresh token is a cookie the carrier already holds,
+ * and a caller that could state it is a caller that could read it. */
+export const AuthRefreshTokenArgs = Type.Object({});
+export type AuthRefreshTokenArgs = Static<typeof AuthRefreshTokenArgs>;
+
+export const AuthRefreshTokenResult = AuthSession;
+export type AuthRefreshTokenResult = Static<typeof AuthRefreshTokenResult>;
+
+export const AuthRefreshTokenRequest = request("auth_refresh_token", AuthRefreshTokenArgs);
+export const AuthRefreshTokenResponse = response("auth_refresh_token", AuthRefreshTokenResult);
+
+// --- extending a live connection ------------------------------------------
+
+/** Carries a token got from `auth_refresh_token`, on the connection whose life
+ * it extends. Apart from that op because they answer different questions: one
+ * mints, this one moves a live connection's deadline, and a client that had to
+ * reconnect to use a fresh token would blink every few hours for no reason. */
+export const AuthRefreshArgs = Type.Object({ access_token: Base64Url });
+export type AuthRefreshArgs = Static<typeof AuthRefreshArgs>;
+
+export const AuthRefreshResult = Type.Object({
+  /** The connection's new deadline, as `hello` first stated it. */
+  auth_expires_at: Timestamp,
+});
+export type AuthRefreshResult = Static<typeof AuthRefreshResult>;
+
+export const AuthRefreshRequest = request("auth_refresh", AuthRefreshArgs);
+export const AuthRefreshResponse = response("auth_refresh", AuthRefreshResult);
+
+// --- between instances -----------------------------------------------------
+
+/** Asks the instance that issued something to check it and spend it.
+ *
+ * Two things are only knowable at their issuer: a registration URL, whose
+ * secret never left it, and a challenge, which is good once and so has to be
+ * spent somewhere single. Everything else about the exchange — the WebAuthn
+ * verification, the record lookup — the receiving instance does itself. */
+export const AuthResolveArgs = Type.Union(
+  [
+    Type.Object({ kind: Type.Literal("register"), token: Type.String({ minLength: 1 }) }),
+    Type.Object({ kind: Type.Literal("challenge"), challenge: Base64Url }),
+  ],
+  { $id: "AuthResolveArgs" },
+);
+export type AuthResolveArgs = Static<typeof AuthResolveArgs>;
+
+/** What was authorized, for a registration; nothing beyond the acknowledgement
+ * for a challenge, whose whole answer is that it was unspent and now is not. */
+export const AuthResolveResult = Type.Union(
+  [
+    Type.Object({ kind: Type.Literal("register"), claims: RegisterClaims }),
+    Type.Object({ kind: Type.Literal("challenge") }),
+  ],
+  { $id: "AuthResolveResult" },
+);
+export type AuthResolveResult = Static<typeof AuthResolveResult>;
+
+export const AuthResolveRequest = request("auth_resolve", AuthResolveArgs);
+export const AuthResolveResponse = response("auth_resolve", AuthResolveResult);
+
+/** Rotates a token family at the one instance allowed to write it.
+ *
+ * A family is written by its `iss` alone. Two instances rotating one family in
+ * parallel would merge by last write and lose a generation, which reads exactly
+ * like a stolen token being replayed — so the rotation is forwarded rather than
+ * done where the request landed. */
+export const AuthRotateArgs = Type.Object({ refresh_token: Base64Url });
+export type AuthRotateArgs = Static<typeof AuthRotateArgs>;
+
+/** Both halves, unlike the person-facing ops: the instance that asked for the
+ * rotation is the one that has to put the new refresh token in a cookie. */
+export const AuthRotateResult = Type.Object({
+  sub: Subject,
+  access: Type.Object({ value: Base64Url, expires_at: Timestamp }),
+  refresh: Type.Object({ value: Base64Url, expires_at: Timestamp }),
+});
+export type AuthRotateResult = Static<typeof AuthRotateResult>;
+
+export const AuthRotateRequest = request("auth_rotate", AuthRotateArgs);
+export const AuthRotateResponse = response("auth_rotate", AuthRotateResult);
+
+// --- the replicated records ------------------------------------------------
+
+/** A registered passkey, as every instance in the cluster holds it.
+ *
+ * Complete once it is written: the instance that registered it is not asked
+ * about it again, which is what lets a person authenticate anywhere in the
+ * cluster while the instance they registered at is down. */
+export const CredentialRecord = Type.Object(
+  {
+    kind: Type.Literal("credential"),
+    sub: Subject,
+    /** The credential's id as the authenticator names it, which is also what an
+     * assertion is looked up by. */
+    credential_id: Base64Url,
+    /** The public key, COSE-encoded. */
+    public_key: Base64Url,
+    /** The `user.id` this credential was created against. */
+    user_handle: Base64Url,
+    /** 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. */
+    sign_count: Type.Optional(Type.Integer({ minimum: 0 })),
+    registered_at: Timestamp,
+  },
+  { $id: "CredentialRecord" },
+);
+export type CredentialRecord = Static<typeof CredentialRecord>;
+
+/** One person's tokens, in the generation that stands and the one before it.
+ *
+ * The previous generation is kept so that a reply lost on the way — the client
+ * rotated, the answer never arrived, it retries — is answered rather than read
+ * as a replay. Anything older than that is a stolen value being reused, and it
+ * fails the whole family. */
+export const TokenFamily = Type.Object(
+  {
+    kind: Type.Literal("token_family"),
+    sub: Subject,
+    /** The instance that minted the family and the only one that may write it. */
+    iss: InstanceId,
+    access: Type.Object({ value: Base64Url, expires_at: Timestamp }),
+    refresh: Type.Object({ value: Base64Url, expires_at: Timestamp }),
+    /** The generation before the current one, while the grace for it lasts. */
+    previous_refresh: Type.Optional(Type.Object({ value: Base64Url, expires_at: Timestamp })),
+  },
+  { $id: "TokenFamily" },
+);
+export type TokenFamily = Static<typeof TokenFamily>;
+
+/** A removal, which has to be a record of its own rather than an absence: an
+ * instance that was partitioned still holds what was removed, and an absence in
+ * a set of changes says nothing.
+ *
+ * A tombstone refuses every later write to its key, so a returning peer cannot
+ * bring back what a person revoked. */
+export const AuthTombstone = Type.Object(
+  {
+    kind: Type.Literal("tombstone"),
+    sub: Subject,
+    deleted_at: Timestamp,
+    /** When the mark itself may be dropped. Absent on a credential's, which is
+     * kept without end because the credential it refuses has none either. */
+    expires_at: Type.Optional(Timestamp),
+  },
+  { $id: "AuthTombstone" },
+);
+export type AuthTombstone = Static<typeof AuthTombstone>;
+
+/** One entry of the replicated set, under the key it is matched by. */
+export const AuthRecord = Type.Object(
+  {
+    /** What this entry is, cluster-wide. Two instances writing one key hold the
+     * same thing, and the later `updated_at` is what stands. */
+    key: Type.String({ minLength: 1, maxLength: 256 }),
+    updated_at: Timestamp,
+    body: Type.Union([CredentialRecord, TokenFamily, AuthTombstone]),
+  },
+  { $id: "AuthRecord" },
+);
+export type AuthRecord = Static<typeof AuthRecord>;
+
+/** The `auth_records` topic: how credentials and token families reach every
+ * instance.
+ *
+ * Apart from the store because of who may read it. The store is the person's to
+ * read and write, and these are secrets that authenticate them — a token read
+ * out of the store would be the person's session, and a credential written into
+ * it would be a new way in. Only instances subscribe, and a relay carries the
+ * frames as the instance it is rather than on a person's behalf. */
+export const AuthRecordsFrame = topicFrame(
+  "auth_records",
+  Type.Object({ records: Type.Array(AuthRecord) }),
+);

package/src/common/hello.ts

@@ -1,6 +1,6 @@
 import { type Static, Type } from "@sinclair/typebox";
 import { request, response } from "../envelope.ts";
-import { Capability, InstanceId, Role, Sid, Timestamp } from "../identifiers.ts";
+import { Capability, Endpoint, InstanceId, Role, Sid, Timestamp } from "../identifiers.ts";
 import { SessionMetaFields } from "../session-meta.ts";
 
 /** The mesh handshake's opening claim, carried by a `role: "instance"` hello.
@@ -13,12 +13,21 @@ export const MeshHello = Type.Object(
     /** Generation of the mesh handshake format, apart from the protocol
      * generation so the handshake can change without the wire changing. */
     ver: Type.Integer({ minimum: 1 }),
-    /** The endpoint URL the connecting instance claims to be. */
-    iss: InstanceId,
+    /** The endpoint URL the connecting instance claims to be reached at. */
+    iss: Endpoint,
     /** The endpoint URL it believes it is connecting to. Compared whole
      * against the receiver's own URL, which is what stops a signature made for
      * one instance from being replayed at another on the same host. */
-    aud: InstanceId,
+    aud: Endpoint,
+    /** Which instance is answering at `iss`. The claim is worth nothing until
+     * the proof lands, after which everything this hello said is trusted, so
+     * the receiver keeps the pair as its authenticated endpoint-to-id mapping —
+     * the table every later `to_instance` is dialed through.
+     *
+     * One id binds to one authenticated link: a hello naming an id already
+     * bound to another endpoint is the one closed, the standing binding being
+     * the one an operator's endpoint list has already vouched for. */
+    id: InstanceId,
     /** Names the ephemeral key the receiver is to fetch for this connection. */
     kid: Type.String({ minLength: 16 }),
   },
@@ -78,6 +87,10 @@ export type HelloArgs = Static<typeof HelloArgs>;
 export const InstanceInfo = Type.Object(
   {
     id: InstanceId,
+    /** Where it is dialed. An attribute of the instance like the host below:
+     * it is what a peer connects to and authenticates against, and it may
+     * change under a fixed `id` when the instance moves. */
+    endpoint: Endpoint,
     /** The host it runs on. An attribute of the instance, not its identity —
      * one host may run several instances. */
     host: Type.String({ minLength: 1 }),
@@ -92,6 +105,10 @@ export const HelloResult = Type.Object({
   protocol_version: Type.Integer({ minimum: 1 }),
   /** The instance answering. Every other id in the reply is relative to it. */
   instance: InstanceId,
+  /** Where the answering instance is dialed. Stated beside the id because the
+   * caller reached it by some URL of its own — a proxy's, an alias — and what a
+   * peer is to dial is neither that nor derivable from the id. */
+  endpoint: Endpoint,
   /** The instances this one knows of, itself included. */
   instances: Type.Array(InstanceInfo),
   /** What this instance can do. An op whose `capability` is absent here
@@ -101,6 +118,12 @@ export const HelloResult = Type.Object({
   /** The daemon build, for display. */
   version: Type.String(),
   started_at: Timestamp,
+  /** When this connection's authorization runs out, after which the instance
+   * closes it. Present on a connection an access token opened; absent where
+   * reaching the instance is itself the permission (the Unix socket) or where
+   * the connection is a mesh link. The person's client renews before this
+   * instant with `auth_refresh` rather than reconnecting. */
+  auth_expires_at: Type.Optional(Timestamp),
 });
 export type HelloResult = Static<typeof HelloResult>;
 

package/src/common/topics.ts

@@ -11,6 +11,7 @@ export const PLAIN_TOPICS = [
   "session_errors",
   "llm_requests",
   "llm_status",
+  "auth_records",
 ] as const;
 
 /** Topics naming one session, written `<topic>:<sid>`. */
@@ -102,6 +103,11 @@ export const TOPIC_ATTRIBUTES = {
   session_status: { roles: ["user"], granularity: "whole" },
   transcript: { roles: ["user"], granularity: "append" },
   kv: { roles: ["user"], granularity: "element" },
+  // The only topic no person may subscribe to: its elements are the secrets
+  // that authenticate them. A relay carries it as the instance it is, not on a
+  // caller's behalf, so there is no path by which a person's subscription
+  // reaches it.
+  auth_records: { roles: ["instance"], granularity: "element" },
 } as const satisfies Record<
   PlainTopic | SessionScopedTopic | NamespaceScopedTopic,
   TopicAttributes

package/src/envelope.ts

@@ -6,7 +6,7 @@ import { InstanceId, Role, Sid } from "./identifiers.ts";
  * fields and whole new ops may be added; a removal or a change of meaning
  * raises it. Peers announcing another generation are refused, on client
  * connections and on mesh links alike. */
-export const PROTOCOL_VERSION = 2;
+export const PROTOCOL_VERSION = 3;
 
 /** The largest a single frame — one newline-delimited line, request, reply or
  * topic frame alike — may be, in bytes.

package/src/errors.ts

@@ -46,6 +46,20 @@ export const ERROR_CODES = [
   /** The on-disk content sniffed as binary, so a text edit would not be
    * faithful to what the caller saw. */
   "not_a_text_file",
+  // --- authenticating a person ---
+  /** A challenge, registration or token was good once and its window has
+   * passed. Apart from `auth_invalid` because it is the one authentication
+   * failure a client answers by itself: it repeats the step that issues a fresh
+   * one, where anything invalid means asking the person again. */
+  "auth_expired",
+  /** The credential, signature, challenge or token did not check out. What
+   * failed is not stated: a caller learns only that this attempt is not one,
+   * and `msg` says no more than the instance's own log would want. */
+  "auth_invalid",
+  /** The instance that issued the challenge or registration, and alone can
+   * spend it, is not one this cluster knows or could reach just now. The client
+   * asks for a fresh one, which the instance it is talking to can issue. */
+  "auth_unknown_issuer",
   // --- translate ---
   /** The helper process is present but failed on this call. (Its absence is
    * `capability_unavailable` instead.) */

package/src/identifiers.ts

@@ -24,22 +24,47 @@ export type Sender = Static<typeof Sender>;
 /** The sender that is the person rather than a session. */
 export const USER_SENDER = "user" as const;
 
-/** An instance id: the endpoint URL other instances dial, compared as a whole
- * string including its path (mesh-peer-auth §4.2 — one origin may host several
- * instances, so origin-level comparison would confuse them). The display name
- * lives in config, never on the wire. */
+/** An instance id: an opaque random value an instance issues for itself once
+ * and keeps for its life, held in its state directory.
+ *
+ * It names the instance and nothing else — where to reach it is the `Endpoint`
+ * below, which may change without this changing. Everything that has to survive
+ * an instance moving is keyed by this: `mid`, the store's keys, the issuer of a
+ * credential record, a token family and a challenge.
+ *
+ * Hexadecimal of a fixed width, because the value appears inside composed
+ * strings (`mid`) and in the store's keys, where a character that means
+ * something to a reader of those — a separator, a case fold — would make two
+ * ids that differ compare equal. The display name lives in config, never on
+ * the wire. */
 export const InstanceId = Type.String({
   $id: "InstanceId",
-  pattern: "^wss?://[^\\s?#]+$",
+  pattern: "^[0-9a-f]{32}$",
 });
 export type InstanceId = Static<typeof InstanceId>;
 
-/** A delivery-frame id: `<instance>/<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. */
+/** Where an instance is reached: the URL other instances dial, compared as a
+ * whole string including its path (mesh-peer-auth §4.2 — one origin may host
+ * several instances, so origin-level comparison would confuse them).
+ *
+ * Apart from `InstanceId` because the two answer different questions and change
+ * on different occasions. This is what a peer dials, what the TLS certificate
+ * is checked against and what the mesh handshake's `iss` / `aud` are compared
+ * 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: "^wss?://[^\\s?#]+$",
+});
+export type Endpoint = Static<typeof Endpoint>;
+
+/** 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. */
 export const Mid = Type.String({
   $id: "Mid",
-  pattern: "^wss?://[^\\s?#]+/\\d+$",
+  pattern: "^[0-9a-f]{32}/\\d+$",
 });
 export type Mid = Static<typeof Mid>;
 

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from "./attributes.ts";
+export * from "./common/auth.ts";
 export * from "./common/hello.ts";
 export * from "./common/ping.ts";
 export * from "./common/shutdown.ts";

package/src/schemas.ts

@@ -1,6 +1,23 @@
 import type { TSchema } from "@sinclair/typebox";
 import { TypeCompiler, type TypeCheck } from "@sinclair/typebox/compiler";
 import type { OpName } from "./attributes.ts";
+import {
+  AuthAssertRequest,
+  AuthAssertResponse,
+  AuthChallengeRequest,
+  AuthChallengeResponse,
+  AuthRecordsFrame,
+  AuthRefreshRequest,
+  AuthRefreshResponse,
+  AuthRefreshTokenRequest,
+  AuthRefreshTokenResponse,
+  AuthRegisterRequest,
+  AuthRegisterResponse,
+  AuthResolveRequest,
+  AuthResolveResponse,
+  AuthRotateRequest,
+  AuthRotateResponse,
+} from "./common/auth.ts";
 import { HelloRequest, HelloResponse } from "./common/hello.ts";
 import { InstancePingRequest, InstancePingResponse } from "./common/ping.ts";
 import {
@@ -116,6 +133,13 @@ export const OP_SCHEMAS: Record<OpName, OpSchemas> = {
   session_stopping: { request: SessionStoppingRequest, response: SessionStoppingResponse },
   topic_subscribe: { request: TopicSubscribeRequest, response: TopicSubscribeResponse },
   topic_unsubscribe: { request: TopicUnsubscribeRequest, response: TopicUnsubscribeResponse },
+  auth_challenge: { request: AuthChallengeRequest, response: AuthChallengeResponse },
+  auth_register: { request: AuthRegisterRequest, response: AuthRegisterResponse },
+  auth_assert: { request: AuthAssertRequest, response: AuthAssertResponse },
+  auth_refresh_token: { request: AuthRefreshTokenRequest, response: AuthRefreshTokenResponse },
+  auth_refresh: { request: AuthRefreshRequest, response: AuthRefreshResponse },
+  auth_resolve: { request: AuthResolveRequest, response: AuthResolveResponse },
+  auth_rotate: { request: AuthRotateRequest, response: AuthRotateResponse },
   message_send: { request: MessageSendRequest, response: MessageSendResponse },
   say_post: { request: SayPostRequest, response: SayPostResponse },
   say_mark_read: { request: SayMarkReadRequest, response: SayMarkReadResponse },
@@ -175,6 +199,7 @@ export const TOPIC_SCHEMAS = {
   llm_requests: LlmRequestsFrame,
   llm_status: LlmStatusFrame,
   kv: KvFrame,
+  auth_records: AuthRecordsFrame,
 } as const;
 
 const compiled = new WeakMap<TSchema, TypeCheck<TSchema>>();