@ccmsg/protocol 1.4.0 → 1.6.0

package/package.json

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

package/src/common/auth.ts

@@ -84,7 +84,9 @@ export const RegisterClaims = Type.Object(
     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. */
+    /** The endpoint the credential is being registered for. The base URL: the
+     * 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. */
@@ -320,6 +322,18 @@ export const CredentialRecord = Type.Object(
      * was created against and what an assertion naming a handle is checked
      * against. */
     user_handle: Base64Url,
+    /** 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
+     * 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,

package/src/common/hello.ts

@@ -13,9 +13,10 @@ 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 reached at. */
+    /** The base URL the connecting instance claims to be published at — the
+     * endpoint itself, not the `<endpoint>ws` it dialed to get here. */
     iss: Endpoint,
-    /** The endpoint URL it believes it is connecting to. Compared whole
+    /** The base 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: Endpoint,
@@ -90,9 +91,11 @@ export const InstanceInfo = Type.Object(
      * configured is known before anything answers there, and leaving such a
      * peer out of the list would hide the very entry whose link is down. */
     id: Type.Optional(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. Absent for the same
+    /** The base URL it is published at, which a peer dials as `<endpoint>ws`,
+     * that scheme included — the WebSocket upgrades from an HTTP request.
+     * 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. Absent for the same
      * reason it is absent from the reply's own `endpoint`: an instance in no
      * mesh has no URL to be dialed at, including on its own line. */
     endpoint: Type.Optional(Endpoint),
@@ -110,7 +113,8 @@ 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
+  /** The base URL the answering instance is published at, under which its own
+   * routes (`ws`, `mesh/…`, `auth/…`) sit. 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. Absent on an
    * instance that joins no mesh: it is reached by the people and sessions on

package/src/identifiers.ts

@@ -43,9 +43,22 @@ export const InstanceId = Type.String({
 });
 export type InstanceId = Static<typeof InstanceId>;
 
-/** 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).
+/** Where an instance is published: the base URL everything it serves hangs
+ * under, ending in a slash and naming no route of its own.
+ *
+ * The routes are below it and are not part of it — `<endpoint>ws` for the
+ * WebSocket, `<endpoint>mesh/…`, `<endpoint>auth/…`, `<endpoint>webhook/…`. All
+ * of them keep the endpoint's own scheme: a WebSocket starts as an HTTP request
+ * that upgrades, so there is no second spelling of the URL and nothing to
+ * rewrite. Naming the base rather than one of
+ * them is what lets a transport be added or replaced without the value that
+ * identifies where an instance lives changing with it, and what lets the HTTP
+ * routes be spelled without stripping a suffix off first.
+ *
+ * Compared as a whole string, path included (mesh-peer-auth §4.2 — 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.
  *
  * Apart from `InstanceId` because the two answer different questions and change
  * on different occasions. This is what a peer dials, what the TLS certificate
@@ -55,7 +68,7 @@ export type InstanceId = Static<typeof InstanceId>;
  * not alter. */
 export const Endpoint = Type.String({
   $id: "Endpoint",
-  pattern: "^wss?://[^\\s?#]+$",
+  pattern: "^https?://[^/?#\\s]+(/[^?#\\s]*)?/$",
 });
 export type Endpoint = Static<typeof Endpoint>;