@ccmsg/protocol 1.4.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/protocol",
-  "version": "1.4.0",
+  "version": "1.7.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. */
@@ -210,9 +212,28 @@ 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({});
+/** Why a client asked for a fresh pair. Stated by the caller and never checked,
+ * so nothing may be decided by it; it is kept only to be recognised later by
+ * the person whose sessions they are. */
+export const AuthRefreshReason = Type.Union(
+  [Type.Literal("reload"), Type.Literal("expiring"), Type.Literal("reconnect")],
+  { $id: "AuthRefreshReason" },
+);
+export type AuthRefreshReason = Static<typeof AuthRefreshReason>;
+
+/** The refresh token is not among the arguments: it is a cookie the carrier
+ * already holds, and a caller that could state it is a caller that could read
+ * it. What is left is why the caller is asking, which nothing is decided by. */
+export const AuthRefreshTokenArgs = Type.Object({
+  /** What prompted this refresh, as the client knows it: the page was loaded
+   * again, the access token was about to expire, or a dropped connection is
+   * being remade. A hint kept on the family (`last_refresh`) for a person
+   * reading their own sessions back — a run of `reconnect` at an hour they were
+   * asleep is something to recognise. The value is the caller's word and is
+   * never checked, so nothing may turn on it; an unstated reason is as valid a
+   * refresh as any. */
+  reason: Type.Optional(AuthRefreshReason),
+});
 export type AuthRefreshTokenArgs = Static<typeof AuthRefreshTokenArgs>;
 
 export const AuthRefreshTokenResult = AuthSession;
@@ -320,6 +341,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,
@@ -331,6 +364,22 @@ export const CredentialRecord = Type.Object(
      * 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 })),
+    /** The BE flag of the authenticator data at registration: whether this
+     * credential is one the authenticator may back up, which in practice is
+     * what separates a passkey synced across a person's devices from one that
+     * lives on the single device it was made on.
+     *
+     * A hint and nothing else, like the address and the user agent beside it:
+     * nothing is admitted or refused by it. It is here so the person reading
+     * their own list can tell "this is my iCloud passkey, it is on every device
+     * I own" from "this is the key on the stick in my drawer" — which decides
+     * what removing the line actually costs them. */
+    backup_eligible: Type.Optional(Type.Boolean()),
+    /** The BS flag of the same authenticator data: whether the credential was
+     * backed up at that moment. Read beside `backup_eligible` — eligible and
+     * not yet backed up is an ordinary state on a device that has just made the
+     * key, and it too decides nothing. */
+    backup_state: Type.Optional(Type.Boolean()),
     /** The label the administrator put on the registration URL, carried over
      * from the claims it was spent against. */
     issued_label: Type.Optional(Type.String({ maxLength: 128 })),
@@ -371,6 +420,22 @@ export const TokenFamily = Type.Object(
     iss: InstanceId,
     access: Type.Object({ value: Base64Url, expires_at: Timestamp }),
     refresh: Type.Object({ value: Base64Url, expires_at: Timestamp }),
+    /** When the family was last rotated, and what the client said prompted it.
+     *
+     * The same kind of thing as a credential's `last_used_*`: a hint for the
+     * one person reading their own sessions, never a reason to admit or refuse
+     * anything. `reason` in particular is the caller's unchecked word. Only the
+     * most recent rotation is kept — a family holds what stands now, and a log
+     * of every generation would be a second store hidden inside a record that
+     * travels to every instance. */
+    last_refresh: Type.Optional(
+      Type.Object({
+        at: Timestamp,
+        reason: Type.Optional(AuthRefreshReason),
+        ip: Type.Optional(Type.String({ minLength: 1, maxLength: 45 })),
+        user_agent: Type.Optional(Type.String({ maxLength: 512 })),
+      }),
+    ),
     /** The generation before the current one, while the grace for it lasts. */
     previous_refresh: Type.Optional(Type.Object({ value: Base64Url, expires_at: Timestamp })),
     /** What every generation retired before that was, kept only as a digest and

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>;