@ccmsg/protocol 2.2.0 → 2.4.0

package/src/identifiers.ts

@@ -43,12 +43,14 @@ export const InstanceId = Type.String({
 });
 export type InstanceId = Static<typeof InstanceId>;
 
-/** A host as a browser serializes one: lowercase labels, or an address literal
- * in its brackets. No uppercase, no userinfo, no empty label and no zone id —
- * every one of those is either a second spelling of one host or a string no URL
- * parser will take. */
-const HOST =
-  "(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*|\\[[0-9a-f:.]+\\])";
+/** 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 =
@@ -58,8 +60,11 @@ const PORT =
  * 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 {
-  const port = (its: string) => `(?::(?!${its}(?:/|$))${PORT})?`;
   return `^(?:https://${HOST}${port("443")}|http://${HOST}${port("80")})${tail}`;
 }
 
@@ -67,6 +72,14 @@ function authority(tail: string): string {
  * carries no query or fragment. */
 const BASE_URL = authority("(?:/[^?#\\s]*)?/$");
 
+/** An origin a WebAuthn ceremony can be held at: `https` on a host that is a
+ * domain, or `http` on one of the loopback names a browser trusts. The
+ * lookahead is what keeps an IPv4 literal out, a bracketed IPv6 one being
+ * outside `HOST_NAME` already. */
+const CEREMONY_ORIGIN =
+  `^(?:https://(?!\\d{1,3}(?:\\.\\d{1,3}){3}(?::|$))${HOST_NAME}${port("443")}` +
+  `|http://(?:localhost|127\\.0\\.0\\.1|\\[::1\\])${port("80")})$`;
+
 /** Where an instance is published: the base URL everything it serves hangs
  * under, ending in a slash and naming no route of its own.
  *
@@ -96,49 +109,47 @@ const BASE_URL = authority("(?:/[^?#\\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.
- *
- * **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: BASE_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.
  *
+ * The one unit this contract holds a page to. A credential names one of these
+ * and a token family carries it over; nothing finer exists to name, a browser
+ * writing a path into neither header nor `clientDataJSON`. Serving two
+ * instances under one origin at different paths is therefore not a shape this
+ * contract has: the two would be one place to every check made here. Where that
+ * separation is wanted, the hosts are what a browser tells apart.
+ *
  * 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.
+ * different questions. An endpoint says where an instance is dialed; an origin
+ * says which site the page in front of a person 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 — and which instance a
+ * person may enter is answered by ownership rather than by either of them.
  *
  * 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.
  *
+ * Held to somewhere a WebAuthn ceremony could actually be held, too, which is
+ * narrower than what a URL parser takes and is the authenticator's rule 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 page 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`
+ * is a perfectly good origin that could never hold a passkey. Writing it into
+ * the type rather than leaving it to the daemon is what keeps the relying party
+ * total over the values a record may carry — an origin no ceremony could run at
+ * would be a credential that could never have been made, accepted and
+ * replicated before anything noticed.
+ *
  * 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 const Origin = Type.String({ $id: "Origin", pattern: CEREMONY_ORIGIN });
 export type Origin = Static<typeof Origin>;
 
 /** A delivery-frame id: `<instance id>/<counter>`, numbered by the instance

package/src/schemas.ts

@@ -15,8 +15,14 @@ import {
   AuthRegisterResponse,
   AuthResolveRequest,
   AuthResolveResponse,
-  AuthRotateRequest,
-  AuthRotateResponse,
+  AuthAccountReadRequest,
+  AuthAccountReadResponse,
+  AuthCredentialRemoveRequest,
+  AuthCredentialRemoveResponse,
+  AuthOwnershipRemoveRequest,
+  AuthOwnershipRemoveResponse,
+  AuthEnrollRequest,
+  AuthEnrollResponse,
 } from "./common/auth.ts";
 import {
   HelloInstanceRequest,
@@ -151,10 +157,19 @@ export const OP_SCHEMAS: Record<OpName, OpSchemas> = {
   "auth.challenge": { request: AuthChallengeRequest, response: AuthChallengeResponse },
   "auth.register": { request: AuthRegisterRequest, response: AuthRegisterResponse },
   "auth.assert": { request: AuthAssertRequest, response: AuthAssertResponse },
+  "auth.enroll": { request: AuthEnrollRequest, response: AuthEnrollResponse },
   "auth.token.refresh": { request: AuthTokenRefreshRequest, response: AuthTokenRefreshResponse },
   "auth.extend": { request: AuthExtendRequest, response: AuthExtendResponse },
+  "auth.account.read": { request: AuthAccountReadRequest, response: AuthAccountReadResponse },
+  "auth.ownership.remove": {
+    request: AuthOwnershipRemoveRequest,
+    response: AuthOwnershipRemoveResponse,
+  },
+  "auth.credential.remove": {
+    request: AuthCredentialRemoveRequest,
+    response: AuthCredentialRemoveResponse,
+  },
   "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.unread.clear": { request: SayUnreadClearRequest, response: SayUnreadClearResponse },