@ccmsg/protocol 2.1.1 → 2.3.0

package/package.json

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

@@ -37,7 +37,19 @@ export interface OpAttributes {
    * 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. */
+   * published at belongs to the instance, not here.
+   *
+   * Being reachable from a page is also what gives the three that settle an
+   * identity the only headers this contract reads over HTTP: the `Origin` a
+   * browser states, held to the origin of the web UI the credential or the
+   * registration names, and `Sec-Fetch-Site`, which has to be one of
+   * `same-origin`, `same-site` or `cross-site` — the three that say a page made
+   * the call. Anything else fails: `none`, which is a request with no initiator
+   * at all, a header that is absent, and a value this contract does not know.
+   * Both headers are read as an allowlist rather than a blocklist, and either
+   * failing answers `auth_invalid` without saying which. `auth.challenge` is checked
+   * against neither, having nothing yet to be checked against; what it hands
+   * out is spendable only at its issuer. */
   readonly carrier?: "http";
   /** Present when the role changes what the reply may contain rather than
    * whether the call is allowed. */

package/src/common/auth.ts

@@ -1,6 +1,34 @@
 import { type Static, Type } from "@sinclair/typebox";
 import { request, response, topicFrame } from "../envelope.ts";
-import { Endpoint, InstanceId, Timestamp } from "../identifiers.ts";
+import { Endpoint, InstanceId, type Origin, Timestamp, WebUi } from "../identifiers.ts";
+
+/** The origin of a web UI's URL: what a browser puts in an `Origin` header and
+ * in a credential's `clientDataJSON`, which is the URL's scheme and authority
+ * and no more.
+ *
+ * Derived rather than stored, and derived here rather than once per
+ * implementation, because every use of it is an exact comparison against a
+ * value a browser serialized. The normalization that makes those comparisons
+ * hold — a lowercase scheme and host, a port only where it is not the scheme's
+ * own, an address literal in its brackets — is the URL parser's, and this is
+ * the one place the contract says so. */
+export function originOf(webui: string): Origin {
+  return new URL(webui).origin;
+}
+
+/** The WebAuthn relying party a credential made at a web UI is created under:
+ * the host of its URL, port and scheme left off, as a relying party is a domain
+ * and not an origin.
+ *
+ * Derived for the same reason as the origin, and held to the host exactly. A
+ * client will accept a relying party that is the page's effective domain or a
+ * registrable suffix of it, so anything shorter than the host would be one
+ * credential several sites could answer with — which is the single thing
+ * binding a credential to one web UI rules out. An assertion's `rpIdHash` is
+ * the SHA-256 of what this returns. */
+export function rpIdOf(webui: string): string {
+  return new URL(webui).hostname;
+}
 
 /** 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
@@ -88,9 +116,19 @@ export const RegisterClaims = Type.Object(
      * 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. */
-    rp_id: Type.String({ minLength: 1 }),
+    /** Where the URL sends the person: the web UI they will open it at, and so
+     * the page the credential will be made by. It is not read off the endpoint,
+     * the UI being publishable anywhere, and a registration URL that did not
+     * name it would not be a URL anyone could open.
+     *
+     * Its origin (`originOf`) is what the ceremony is then held to, and it is
+     * also what lets a first registration be answered across sites at all: an
+     * instance answers CORS for the origins its credentials name, and the first
+     * registration at a new UI has no credential yet — the URL it issued and
+     * still holds stands in for one until it does. That is the issuer's own
+     * knowledge and travels nowhere, which is why a registration is only
+     * completed where it was issued. */
+    webui: WebUi,
     expires_at: Timestamp,
     /** Names this registration, so it can be spent once. */
     jti: Type.String({ minLength: 1 }),
@@ -159,7 +197,15 @@ export type AuthRegisterArgs = Static<typeof AuthRegisterArgs>;
  * 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. */
+ * the cookie exists to have. That holds however far the page is from the
+ * endpoint: a cookie the page's own site cannot reach is sent from a site it
+ * does not own only as a partitioned one, which keeps a session taken at one
+ * site from being carried to another. That partition is by site, where a
+ * credential is by origin, so it is the `Origin` held against this family's
+ * `webui` that keeps a session to the one place it was made — the cookie's
+ * partition answers for sites and nothing finer. Sending it at all across sites takes a browser that partitions
+ * cookies, which is a premise of this contract rather than a case it
+ * accommodates: one that does not is not an environment this is spoken over. */
 export const AuthSession = Type.Object(
   {
     sub: Subject,
@@ -358,22 +404,43 @@ export const CredentialRecord = Type.Object(
     /** 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
+     * Which instance the credential admits its holder to: an assertion is
+     * accepted only where the request arrived at this base URL — the same
+     * scheme and authority, and a path below it. (The authority the request
+     * reached, which is a property of the connection; where the page asking was
+     * served from is `webui` below and a separate question.)
+     * `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,
-     * so an assertion's `rpIdHash` is checked against this and not against
-     * whatever the endpoint being reached happens to be. Absent only on a
-     * record written before the field existed. */
-    rp_id: Type.Optional(Type.String({ minLength: 1 })),
+    /** The web UI the page that created this credential was served from, whose
+     * origin is the one it may ever be used from.
+     *
+     * Holding it to one origin is this contract's rule rather than WebAuthn's. A
+     * passkey is bound to its relying party, which may be a suffix of the host,
+     * so the authenticator alone would answer for every origin under that
+     * suffix. What holds a credential to one is the check made against
+     * this: the `clientDataJSON.origin` of every ceremony, registration and
+     * assertion alike, has to equal `originOf` this URL. The relying party is
+     * `rpIdOf` the same URL, which is what makes the authenticator's own
+     * binding say the same thing rather than something wider.
+     *
+     * The URL is what is kept, and the origin read off it where a header is
+     * matched — a token minted here carries the same URL and its connection's
+     * `Origin` is held to the origin of it, and the origins of an endpoint's
+     * credentials are the set the HTTP auth ops answer CORS for. Keeping the
+     * origin alongside instead would be a second copy of one fact, able to
+     * disagree with the URL a person is actually sent to. A person using web
+     * UIs at two origins holds two credentials, one per origin; two UIs under
+     * one origin are one place to every check here, there being no path in an
+     * `Origin` header to tell them apart by.
+     *
+     * Apart from `endpoint` because the two answer different questions: which
+     * page may speak, and which instance it may speak to. */
+    webui: WebUi,
     /** 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. */
@@ -432,6 +499,21 @@ export const TokenFamily = Type.Object(
     sub: Subject,
     /** The instance that minted the family and the only one that may write it. */
     iss: InstanceId,
+    /** The web UI the page that authenticated was served from, carried over
+     * from the credential that answered.
+     *
+     * What a connection presenting one of these tokens is held to: the
+     * handshake compares `originOf` this with the `Origin` the browser states,
+     * and a page from anywhere else is refused however good the token is —
+     * refused as an upgrade that does not happen, there being no connection yet
+     * to answer an error on. A handshake that states no `Origin` at all is
+     * refused the same way: every gate has to be passed, and a caller with
+     * nothing to compare has not passed this one. Without it a token that leaked would be usable
+     * from any page at all, since it says who the person is and nothing about
+     * what is holding it. It lives on the family rather than inside the token's
+     * own spelling because every instance has the family and none of them has
+     * the minting instance's reading of an opaque value. */
+    webui: WebUi,
     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.

package/src/fixtures/common.ts

@@ -36,7 +36,7 @@ import type {
 } from "../common/topics.ts";
 import { FIXTURE_IDS, FIXTURE_NOW } from "./ids.ts";
 
-const { sid, instance, other_instance, endpoint, other_endpoint, request_id } = FIXTURE_IDS;
+const { sid, instance, other_instance, endpoint, other_endpoint, webui, request_id } = FIXTURE_IDS;
 
 export const HELLO_SESSION_REQUEST: Static<typeof HelloSessionRequest> = {
   request_id,
@@ -277,7 +277,7 @@ export const AUTH_RESOLVE_RESPONSE = {
     sub: SUBJECT,
     unit: "personal",
     endpoint,
-    rp_id: "mba.example.ts.net",
+    webui,
     expires_at: FIXTURE_NOW + 600_000,
     jti: "01J9Z3W2Q",
     user_id: "dXNlci1oYW5kbGU",

package/src/fixtures/ids.ts

@@ -9,6 +9,17 @@ export const FIXTURE_IDS = {
   other_instance: "a1b2c3d4e5f60718293a4b5c6d7e8f90",
   endpoint: "https://mba.example.ts.net/ccmsg/personal/",
   other_endpoint: "https://nuc.example.ts.net/ccmsg/personal/",
+  /** Where the web UI is published, which is nobody's endpoint: a credential is
+   * made here and used against the endpoints above. A base URL with a path of
+   * its own, as an endpoint is, and its registrable domain is not the
+   * endpoints' — so the two are cross-site and a refresh cookie between them is
+   * a partitioned one. */
+  webui: "https://ui.example.test/ccmsg/",
+  /** A second web UI, sharing the endpoints' registrable domain: same-site, and
+   * still an origin of its own. A credential made here is a separate
+   * credential, and the cookie between it and an endpoint is not partitioned —
+   * one contract, two shapes, which is why both are written down. */
+  same_site_webui: "https://ui.example.ts.net/",
   mid: "3f9c1a7b5e2d48069c1a7b5e2d480691/1841",
   request_id: "1",
 } as const;

package/src/fixtures/topics.ts

@@ -14,7 +14,17 @@ import type { InboxFrame } from "../messaging/message.ts";
 import type { NotifyFrame } from "../messaging/notify.ts";
 import { FIXTURE_IDS, FIXTURE_NOW } from "./ids.ts";
 
-const { sid, other_sid, instance, other_instance, endpoint, other_endpoint, mid } = FIXTURE_IDS;
+const {
+  sid,
+  other_sid,
+  instance,
+  other_instance,
+  endpoint,
+  other_endpoint,
+  webui,
+  same_site_webui,
+  mid,
+} = FIXTURE_IDS;
 
 const WORKSPACE = "/repos/kawaz/ccmsg-protocol/main";
 
@@ -511,7 +521,7 @@ export const AUTH_RECORDS_FRAME = {
           public_key: "pQECAyYgASFYIA",
           user_handle: "dXNlci1oYW5kbGU",
           endpoint,
-          rp_id: "mba.example.ts.net",
+          webui,
           sign_count: 0,
           issued_label: "for kawaz",
           device_label: "work laptop",
@@ -523,6 +533,25 @@ export const AUTH_RECORDS_FRAME = {
           last_used_user_agent: "Mozilla/5.0",
         },
       },
+      {
+        // The same person at a second site, which shares the endpoint's
+        // registrable domain where the first does not. One credential per site,
+        // and the difference between the two is what decides whether the
+        // refresh cookie for a session made here is a partitioned one.
+        key: "credential/personal-1/Y3JlZC1pZC0y",
+        updated_at: FIXTURE_NOW,
+        body: {
+          kind: "credential",
+          sub: "personal-1",
+          credential_id: "Y3JlZC1pZC0y",
+          public_key: "pQECAyYgASFYIB",
+          user_handle: "dXNlci1oYW5kbGU",
+          endpoint,
+          webui: same_site_webui,
+          device_label: "phone",
+          registered_at: FIXTURE_NOW - 300_000,
+        },
+      },
     ],
   },
 } satisfies Static<typeof AuthRecordsFrame>;
@@ -542,6 +571,7 @@ export const AUTH_RECORDS_FAMILY_FRAME = {
           kind: "token_family",
           sub: "personal-1",
           iss: instance,
+          webui,
           access: { value: "YWNjZXNz", expires_at: FIXTURE_NOW + 10_000_000 },
           refresh: { value: "cmVmcmVzaA", expires_at: FIXTURE_NOW + 600_000_000 },
           last_refresh: {

package/src/identifiers.ts

@@ -43,6 +43,54 @@ export const InstanceId = Type.String({
 });
 export type InstanceId = Static<typeof InstanceId>;
 
+/** A host name as a browser serializes one: lowercase labels, no uppercase, no
+ * userinfo and no empty label — each of those is either a second spelling of
+ * one host or a string no URL parser will take. */
+const HOST_NAME = "[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*";
+
+/** A host: a name as above, or an address literal in its brackets (no zone id,
+ * which no URL parser takes). */
+const HOST = `(?:${HOST_NAME}|\\[[0-9a-f:.]+\\])`;
+
+/** A port in range, 1 to 65535. */
+const PORT =
+  "(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5])";
+
+/** A scheme and authority, with the scheme's own port left unspelled — a
+ * browser omits it, so writing it would be a second name for one place. `tail`
+ * closes the pattern: the end of the string for an origin, a path for a base
+ * URL, and it is what the lookaheads read to know a port ended. */
+function port(its: string): string {
+  return `(?::(?!${its}(?:/|$))${PORT})?`;
+}
+
+function authority(tail: string): string {
+  return `^(?:https://${HOST}${port("443")}|http://${HOST}${port("80")})${tail}`;
+}
+
+/** A base URL: an authority as above, then a path that ends in a slash and
+ * carries no query or fragment. */
+const BASE_URL = authority("(?:/[^?#\\s]*)?/$");
+
+/** The path part of a base URL, as above. */
+const BASE_PATH = "(?:/[^?#\\s]*)?/$";
+
+/** A base URL a WebAuthn ceremony can actually run at.
+ *
+ * Narrower than `BASE_URL` on two counts, both of them the authenticator's
+ * rules rather than this contract's taste. A ceremony needs a secure context,
+ * so the scheme is `https` — with `http` on the loopback names browsers treat
+ * as trustworthy, which is what makes a web UI runnable on a development
+ * machine. And a relying party is a domain, so the host may not be an address
+ * literal: `https://198.51.100.9/` parses fine and could never hold a passkey.
+ *
+ * Writing it into the type rather than leaving it to the daemon is what keeps
+ * `rpIdOf` total over the values a record may carry. A URL that no ceremony can
+ * run at would be a credential that could never have been made. */
+const WEBUI_URL =
+  `^(?:https://(?!\\d{1,3}(?:\\.\\d{1,3}){3}(?:[:/]))${HOST_NAME}${port("443")}` +
+  `|http://(?:localhost|127\\.0\\.0\\.1|\\[::1\\])${port("80")})${BASE_PATH}`;
+
 /** Where an instance is published: the base URL everything it serves hangs
  * under, ending in a slash and naming no route of its own.
  *
@@ -57,8 +105,11 @@ export type InstanceId = Static<typeof InstanceId>;
  *
  * Compared as a whole string, path included (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.
+ * them). Every part of it is held to one spelling for that comparison's sake:
+ * the trailing slash is required, so `/ccmsg` and `/ccmsg/` are not two
+ * endpoints; the host is lowercase and the scheme's own port is left out, as a
+ * browser would write them; an internationalized host is spelled in punycode,
+ * which is what the wire carries anyway.
  *
  * Apart from `InstanceId` because the two answer different questions and change
  * on different occasions. This is what a peer dials, what the TLS certificate
@@ -66,12 +117,59 @@ export type InstanceId = Static<typeof InstanceId>;
  * 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: "^https?://[^/?#\\s]+(/[^?#\\s]*)?/$",
-});
+export const Endpoint = Type.String({ $id: "Endpoint", pattern: BASE_URL });
 export type Endpoint = Static<typeof Endpoint>;
 
+/** Where the web UI is published: the base URL a person opens it at, ending in
+ * a slash and naming no route of its own (`https://ui.example/ccmsg/`).
+ *
+ * The counterpart of `Endpoint` on the other side of the wire. An endpoint says
+ * where an instance is dialed; this says where the page doing the dialing came
+ * from, and one of each is what a credential is made against. Spelled to the
+ * same rule as an endpoint, path and trailing slash included, because it is the
+ * same kind of value: a base URL that something is published under — but held
+ * to a narrower set of them: `https`, or `http` on a loopback name a browser
+ * treats as trustworthy, and never an address literal for a host. Those are the
+ * authenticator's conditions, not this contract's taste: a ceremony wants a
+ * secure context, and a relying party is a domain. A URL outside them is one no
+ * credential could have been made at.
+ *
+ * **What is kept and what is compared are different sizes.** The whole URL is
+ * kept: it is where a person is sent, what an operator configures, and what
+ * they read back in a list of their own credentials. Every comparison this
+ * contract makes is of the origin (`originOf`) or the host (`rpIdOf`), because
+ * a browser writes neither a path in an `Origin` header nor one in a
+ * `clientDataJSON` — there is nothing finer on the wire to compare. Two web UIs
+ * under one origin are therefore one place to everything here. The origin is
+ * read off the URL where a header has to be matched rather than kept beside it
+ * as a second field that could disagree. */
+export const WebUi = Type.String({ $id: "WebUi", pattern: WEBUI_URL });
+export type WebUi = Static<typeof WebUi>;
+
+/** Where a page was served from: a scheme and an authority and nothing else,
+ * spelled as a browser spells it in the `Origin` header and in a credential's
+ * `clientDataJSON` — no path, no trailing slash.
+ *
+ * Apart from `Endpoint` because the two are units of different size and answer
+ * different questions. An endpoint says which instance a person is admitted to
+ * and is compared with its path; an origin says which site the page in front of
+ * them came from, which is all the browser's same-origin rules know about and
+ * all a page's own script cannot lie about. One site may be the page for many
+ * endpoints, and one origin may carry many instances, so neither is derivable
+ * from the other.
+ *
+ * Held to the one spelling a browser serializes: a lowercase scheme, a
+ * lowercase host, and a port only where it is not the scheme's own. No
+ * userinfo, no path, no trailing slash, nothing else a URL may carry.
+ *
+ * The narrowness is the point rather than pedantry. Every use of this value is
+ * a whole-string comparison — against an `Origin` header, against a
+ * `clientDataJSON.origin`, against the members of a CORS answer — so a second
+ * spelling of one site would be a record that never matches the site it names,
+ * or an allowed origin that quietly admits nothing. */
+export const Origin = Type.String({ $id: "Origin", pattern: authority("$") });
+export type Origin = Static<typeof Origin>;
+
 /** 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. */