@ccmsg/protocol 2.2.0 → 2.4.0

package/src/errors.ts

@@ -79,6 +79,16 @@ export const ERROR_CODES = [
    * spend it, is not one this mesh 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",
+  /** What the caller asked to remove is what they are using to ask. Removing
+   * the ownership of the instance this connection is on, or the credential this
+   * session was authenticated with, would be cutting the branch underneath — so
+   * it is refused rather than half-applied.
+   *
+   * Apart from `forbidden` because nothing about the caller's standing is
+   * wrong: it is theirs to remove, and doing it from somewhere else is all it
+   * takes. Stated as a code of its own so a client can say that rather than
+   * showing a refusal it cannot explain. */
+  "auth_in_use",
   // --- translate ---
   /** The helper process is present but failed on this call. (Its absence is
    * `capability_unavailable` instead.) */

package/src/fixtures/common.ts

@@ -12,8 +12,14 @@ import type {
   AuthRegisterResponse,
   AuthResolveRequest,
   AuthResolveResponse,
-  AuthRotateRequest,
-  AuthRotateResponse,
+  AuthAccountReadRequest,
+  AuthAccountReadResponse,
+  AuthCredentialRemoveRequest,
+  AuthCredentialRemoveResponse,
+  AuthOwnershipRemoveRequest,
+  AuthOwnershipRemoveResponse,
+  AuthEnrollRequest,
+  AuthEnrollResponse,
 } from "../common/auth.ts";
 import type {
   HelloInstanceRequest,
@@ -36,7 +42,18 @@ import type {
 } from "../common/topics.ts";
 import { FIXTURE_IDS, FIXTURE_NOW } from "./ids.ts";
 
-const { sid, instance, other_instance, endpoint, other_endpoint, webui, request_id } = FIXTURE_IDS;
+const {
+  sid,
+  instance,
+  other_instance,
+  endpoint,
+  other_endpoint,
+  origin,
+  same_site_origin,
+  hosting_endpoint,
+  user: USER,
+  request_id,
+} = FIXTURE_IDS;
 
 export const HELLO_SESSION_REQUEST: Static<typeof HelloSessionRequest> = {
   request_id,
@@ -176,11 +193,8 @@ const CHALLENGE = {
 };
 
 const ACCESS = { value: "YWNjZXNzLXRva2Vu", expires_at: FIXTURE_NOW + 10_000_000 };
-const REFRESH = { value: "cmVmcmVzaA", expires_at: FIXTURE_NOW + 600_000_000 };
-const REGISTER_TOKEN = "eyJhbGciOiJIUzI1NiJ9.e30.c2ln";
-const REGISTER_CODE = "048213";
-const SUBJECT = "personal-1";
-
+const ENROLL_TOKEN = "eyJhbGciOiJIUzI1NiJ9.e30.c2ln";
+const ENROLL_CODE = "048213";
 export const AUTH_CHALLENGE_REQUEST: Static<typeof AuthChallengeRequest> = {
   request_id,
   op: "auth.challenge",
@@ -195,8 +209,8 @@ export const AUTH_CHALLENGE_RESPONSE: Static<typeof AuthChallengeResponse> = {
 export const AUTH_REGISTER_REQUEST: Static<typeof AuthRegisterRequest> = {
   request_id,
   op: "auth.register",
-  token: REGISTER_TOKEN,
-  code: REGISTER_CODE,
+  token: ENROLL_TOKEN,
+  code: ENROLL_CODE,
   device_label: "work laptop",
   challenge: CHALLENGE,
   credential: {
@@ -210,7 +224,7 @@ export const AUTH_REGISTER_REQUEST: Static<typeof AuthRegisterRequest> = {
 export const AUTH_REGISTER_RESPONSE: Static<typeof AuthRegisterResponse> = {
   ok: true,
   request_id,
-  sub: SUBJECT,
+  user: USER,
   access: ACCESS,
 };
 
@@ -223,14 +237,38 @@ export const AUTH_ASSERT_REQUEST: Static<typeof AuthAssertRequest> = {
     client_data_json: "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0In0",
     authenticator_data: "YXV0aC1kYXRh",
     signature: "c2lnbmF0dXJl",
-    user_handle: "dXNlci1oYW5kbGU",
+    user_handle: USER,
   },
 };
 
 export const AUTH_ASSERT_RESPONSE: Static<typeof AuthAssertResponse> = {
   ok: true,
   request_id,
-  sub: SUBJECT,
+  user: USER,
+  access: ACCESS,
+};
+
+/** Taking a second instance as one's own: the same token and digits a
+ * registration carries, answered with the passkey that already exists. */
+export const AUTH_ENROLL_REQUEST: Static<typeof AuthEnrollRequest> = {
+  request_id,
+  op: "auth.enroll",
+  token: ENROLL_TOKEN,
+  code: ENROLL_CODE,
+  challenge: CHALLENGE,
+  credential: {
+    raw_id: "Y3JlZC1pZA",
+    client_data_json: "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0In0",
+    authenticator_data: "YXV0aC1kYXRh",
+    signature: "c2lnbmF0dXJl",
+    user_handle: USER,
+  },
+};
+
+export const AUTH_ENROLL_RESPONSE: Static<typeof AuthEnrollResponse> = {
+  ok: true,
+  request_id,
+  user: USER,
   access: ACCESS,
 };
 
@@ -243,7 +281,7 @@ export const AUTH_TOKEN_REFRESH_REQUEST: Static<typeof AuthTokenRefreshRequest>
 export const AUTH_TOKEN_REFRESH_RESPONSE: Static<typeof AuthTokenRefreshResponse> = {
   ok: true,
   request_id,
-  sub: SUBJECT,
+  user: USER,
   access: ACCESS,
 };
 
@@ -259,32 +297,137 @@ export const AUTH_EXTEND_RESPONSE: Static<typeof AuthExtendResponse> = {
   auth_expires_at: FIXTURE_NOW + 20_000_000,
 };
 
+/** The three things a person has, read back at once: who they are, what answers
+ * for them at each origin, and the instances they own. Two instances here, one
+ * of them granted by nobody (they made it) and one added by an owner. */
+export const AUTH_ACCOUNT_READ_REQUEST: Static<typeof AuthAccountReadRequest> = {
+  request_id,
+  op: "auth.account.read",
+};
+
+export const AUTH_ACCOUNT_READ_RESPONSE: Static<typeof AuthAccountReadResponse> = {
+  ok: true,
+  request_id,
+  user: {
+    kind: "user",
+    user: USER,
+    display_name: "kawaz",
+    created_at: FIXTURE_NOW - 900_000,
+  },
+  credentials: [
+    {
+      kind: "credential",
+      user: USER,
+      credential_id: "Y3JlZC1pZA",
+      origin,
+      sign_count: 0,
+      issued_label: "for kawaz",
+      device_label: "work laptop",
+      registered_at: FIXTURE_NOW - 600_000,
+      registered_ip: "203.0.113.7",
+      registered_user_agent: "Mozilla/5.0",
+      last_used_at: FIXTURE_NOW,
+      last_used_ip: "203.0.113.7",
+      last_used_user_agent: "Mozilla/5.0",
+    },
+    {
+      kind: "credential",
+      user: USER,
+      credential_id: "Y3JlZC1pZC0y",
+      origin: same_site_origin,
+      device_label: "phone",
+      registered_at: FIXTURE_NOW - 300_000,
+    },
+  ],
+  instances: [
+    {
+      instance,
+      endpoint,
+      granted_at: FIXTURE_NOW - 600_000,
+      granted_by: { kind: "instance", instance },
+    },
+    {
+      instance: other_instance,
+      endpoint: other_endpoint,
+      granted_at: FIXTURE_NOW - 60_000,
+      granted_by: { kind: "user", user: USER },
+    },
+  ],
+};
+
+/** Giving up an instance, named from another one the person owns — the
+ * connection's own instance is the one call that is refused. */
+export const AUTH_OWNERSHIP_REMOVE_REQUEST: Static<typeof AuthOwnershipRemoveRequest> = {
+  request_id,
+  op: "auth.ownership.remove",
+  instance: other_instance,
+};
+
+export const AUTH_OWNERSHIP_REMOVE_RESPONSE: Static<typeof AuthOwnershipRemoveResponse> = {
+  ok: true,
+  request_id,
+};
+
+/** Removing a passkey that is not the one this session authenticated with. */
+export const AUTH_CREDENTIAL_REMOVE_REQUEST: Static<typeof AuthCredentialRemoveRequest> = {
+  request_id,
+  op: "auth.credential.remove",
+  credential_id: "Y3JlZC1pZC0y",
+};
+
+export const AUTH_CREDENTIAL_REMOVE_RESPONSE: Static<typeof AuthCredentialRemoveResponse> = {
+  ok: true,
+  request_id,
+};
+
 export const AUTH_RESOLVE_REQUEST = {
   request_id,
   op: "auth.resolve",
   to_instance: instance,
-  kind: "register",
-  token: REGISTER_TOKEN,
-  code: REGISTER_CODE,
+  kind: "claims",
+  token: ENROLL_TOKEN,
+  code: ENROLL_CODE,
 } satisfies Static<typeof AuthResolveRequest>;
 
+/** What the issuer answers about a URL that makes a person. It names the user
+ * the credential will be created against, and posts to the address in front of
+ * the instances rather than to the issuer's own — whichever of them the answer
+ * lands on completes it. */
 export const AUTH_RESOLVE_RESPONSE = {
   ok: true,
   request_id,
-  kind: "register",
+  kind: "claims",
   claims: {
     iss: instance,
-    sub: SUBJECT,
-    unit: "personal",
-    endpoint,
-    webui,
+    purpose: "create_user",
+    instance,
+    origin,
+    endpoint: hosting_endpoint,
     expires_at: FIXTURE_NOW + 600_000,
     jti: "01J9Z3W2Q",
-    user_id: "dXNlci1oYW5kbGU",
+    user: USER,
     issued_label: "for kawaz",
   },
 } satisfies Static<typeof AuthResolveResponse>;
 
+/** The other purpose: a URL that adds an instance to whoever asserts. It names
+ * no user — who arrives is what the assertion says. */
+export const AUTH_RESOLVE_ADD_OWNER_RESPONSE = {
+  ok: true,
+  request_id,
+  kind: "claims",
+  claims: {
+    iss: other_instance,
+    purpose: "add_owner",
+    instance: other_instance,
+    origin,
+    endpoint: hosting_endpoint,
+    expires_at: FIXTURE_NOW + 600_000,
+    jti: "01J9Z3W2R",
+    issued_label: "nuc, for kawaz",
+  },
+} satisfies Static<typeof AuthResolveResponse>;
+
 /** The other half of the resolve union: spending a challenge, which answers
  * nothing beyond having spent it. */
 export const AUTH_RESOLVE_CHALLENGE_REQUEST = {
@@ -300,21 +443,3 @@ export const AUTH_RESOLVE_CHALLENGE_RESPONSE = {
   request_id,
   kind: "challenge",
 } satisfies Static<typeof AuthResolveResponse>;
-
-export const AUTH_ROTATE_REQUEST: Static<typeof AuthRotateRequest> = {
-  request_id,
-  op: "auth.rotate",
-  to_instance: instance,
-  refresh_token: REFRESH.value,
-  reason: "reconnect",
-  ip: "203.0.113.7",
-  user_agent: "Mozilla/5.0",
-};
-
-export const AUTH_ROTATE_RESPONSE: Static<typeof AuthRotateResponse> = {
-  ok: true,
-  request_id,
-  sub: SUBJECT,
-  access: ACCESS,
-  refresh: REFRESH,
-};

package/src/fixtures/ids.ts

@@ -9,17 +9,29 @@ 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
+  /** The person every auth fixture is about: sixteen bytes spelled base64url,
+   * which is at once their id in these records and the user handle their
+   * authenticator holds. Twenty-two characters, as sixteen bytes always are. */
+  user: "d2hvLWlzLXRoaXMtdXNlcg",
+  /** A second person, so that an instance with two owners can be written down.
+   * Nothing but the id distinguishes them here. */
+  other_user: "c29tZWJvZHktZWxzZS1oaQ",
+  /** Where the page a person opens is served from, which is nobody's endpoint:
+   * a credential is made here and used at whichever instance the person owns.
+   * Its registrable domain is not the endpoints' — so the two are cross-site
+   * and a refresh cookie between them is a partitioned one. */
+  origin: "https://ui.example.test",
+  /** A second origin, 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/",
+  same_site_origin: "https://ui.example.ts.net",
+  /** The address a person reaches the instances at when a load balancer is in
+   * front of them: an endpoint like any other, and the one an enrolment URL
+   * names as where to post. It is nobody's own address — which of the instances
+   * behind it answers is not a thing the caller chooses — so it is never
+   * compared with anything. */
+  hosting_endpoint: "https://ccmsg2.example.ts.net/",
   mid: "3f9c1a7b5e2d48069c1a7b5e2d480691/1841",
   request_id: "1",
 } as const;

package/src/fixtures/index.ts

@@ -61,13 +61,25 @@ export const OP_FIXTURES = {
     response: common.AUTH_REGISTER_RESPONSE,
   },
   "auth.assert": { request: common.AUTH_ASSERT_REQUEST, response: common.AUTH_ASSERT_RESPONSE },
+  "auth.enroll": { request: common.AUTH_ENROLL_REQUEST, response: common.AUTH_ENROLL_RESPONSE },
   "auth.token.refresh": {
     request: common.AUTH_TOKEN_REFRESH_REQUEST,
     response: common.AUTH_TOKEN_REFRESH_RESPONSE,
   },
   "auth.extend": { request: common.AUTH_EXTEND_REQUEST, response: common.AUTH_EXTEND_RESPONSE },
+  "auth.account.read": {
+    request: common.AUTH_ACCOUNT_READ_REQUEST,
+    response: common.AUTH_ACCOUNT_READ_RESPONSE,
+  },
+  "auth.ownership.remove": {
+    request: common.AUTH_OWNERSHIP_REMOVE_REQUEST,
+    response: common.AUTH_OWNERSHIP_REMOVE_RESPONSE,
+  },
+  "auth.credential.remove": {
+    request: common.AUTH_CREDENTIAL_REMOVE_REQUEST,
+    response: common.AUTH_CREDENTIAL_REMOVE_RESPONSE,
+  },
   "auth.resolve": { request: common.AUTH_RESOLVE_REQUEST, response: common.AUTH_RESOLVE_RESPONSE },
-  "auth.rotate": { request: common.AUTH_ROTATE_REQUEST, response: common.AUTH_ROTATE_RESPONSE },
 
   "message.send": {
     request: messaging.MESSAGE_SEND_REQUEST,

package/src/fixtures/topics.ts

@@ -21,8 +21,10 @@ const {
   other_instance,
   endpoint,
   other_endpoint,
-  webui,
-  same_site_webui,
+  origin,
+  same_site_origin,
+  user: USER,
+  other_user: OTHER_USER,
   mid,
 } = FIXTURE_IDS;
 
@@ -504,6 +506,15 @@ export const KV_FRAME: Static<typeof KvFrame> = {
   },
 };
 
+/** The grantings the fixtures name. A granting's id is random and never reused,
+ * which is what lets the same instance be given up and taken again. */
+const GRANT = "Z3JhbnQtb25l";
+const OTHER_GRANT = "Z3JhbnQtdHdv";
+const THIRD_GRANT = "Z3JhbnQtdGhyZWU";
+const FOURTH_GRANT = "Z3JhbnQtZm91cg";
+
+/** The person, the passkeys that answer for them, and the instances they own —
+ * the records an instance needs to admit somebody, all replicated. */
 export const AUTH_RECORDS_FRAME = {
   ev: "topic",
   topic: "auth.records",
@@ -512,16 +523,24 @@ export const AUTH_RECORDS_FRAME = {
   data: {
     records: [
       {
-        key: "credential/personal-1/Y3JlZC1pZA",
+        key: `user/${USER}`,
+        updated_at: FIXTURE_NOW - 900_000,
+        body: {
+          kind: "user",
+          user: USER,
+          display_name: "kawaz",
+          created_at: FIXTURE_NOW - 900_000,
+        },
+      },
+      {
+        key: "credential/Y3JlZC1pZA",
         updated_at: FIXTURE_NOW,
         body: {
           kind: "credential",
-          sub: "personal-1",
+          user: USER,
           credential_id: "Y3JlZC1pZA",
           public_key: "pQECAyYgASFYIA",
-          user_handle: "dXNlci1oYW5kbGU",
-          endpoint,
-          webui,
+          origin,
           sign_count: 0,
           issued_label: "for kawaz",
           device_label: "work laptop",
@@ -534,30 +553,77 @@ export const AUTH_RECORDS_FRAME = {
         },
       },
       {
-        // 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",
+        // The same person at a second origin, which shares the endpoints'
+        // registrable domain where the first does not. One credential per
+        // origin, and the difference between the two is what decides whether
+        // the refresh cookie for a session made here is a partitioned one.
+        key: "credential/Y3JlZC1pZC0y",
         updated_at: FIXTURE_NOW,
         body: {
           kind: "credential",
-          sub: "personal-1",
+          user: USER,
           credential_id: "Y3JlZC1pZC0y",
           public_key: "pQECAyYgASFYIB",
-          user_handle: "dXNlci1oYW5kbGU",
-          endpoint,
-          webui: same_site_webui,
+          origin: same_site_origin,
           device_label: "phone",
           registered_at: FIXTURE_NOW - 300_000,
         },
       },
+      {
+        // The instance this person made themselves, from its command line:
+        // there was no user yet to do it, which is why a granting's author can
+        // be an instance at all.
+        key: `ownership/${instance}/${USER}/${GRANT}`,
+        updated_at: FIXTURE_NOW - 600_000,
+        body: {
+          kind: "ownership",
+          user: USER,
+          instance,
+          grant: GRANT,
+          granted_at: FIXTURE_NOW - 600_000,
+          granted_by: { kind: "instance", instance },
+        },
+      },
+      {
+        // A second instance, taken as their own afterwards. Neither credential
+        // is named here: which instances a person may enter is this record's
+        // answer, and which page may speak is the credential's.
+        //
+        // The frame is this instance's, and what it carries is an ownership of
+        // its peer: a granting is written wherever the operator is standing and
+        // replicated from there, peers trusting one another equally. Nothing
+        // requires the instance that wrote a granting to be the one granted.
+        key: `ownership/${other_instance}/${USER}/${OTHER_GRANT}`,
+        updated_at: FIXTURE_NOW - 60_000,
+        body: {
+          kind: "ownership",
+          user: USER,
+          instance: other_instance,
+          grant: OTHER_GRANT,
+          granted_at: FIXTURE_NOW - 60_000,
+          granted_by: { kind: "user", user: USER },
+        },
+      },
+      {
+        // A second person owning that same instance. One instance may have
+        // several owners, and they are told apart by the key alone.
+        key: `ownership/${other_instance}/${OTHER_USER}/${THIRD_GRANT}`,
+        updated_at: FIXTURE_NOW - 30_000,
+        body: {
+          kind: "ownership",
+          user: OTHER_USER,
+          instance: other_instance,
+          grant: THIRD_GRANT,
+          granted_at: FIXTURE_NOW - 30_000,
+          granted_by: { kind: "user", user: USER },
+        },
+      },
     ],
   },
 } satisfies Static<typeof AuthRecordsFrame>;
 
-/** The token half of the same topic: one family, written by the instance that
- * issued it. */
+/** The token half of the same topic: one family, minted by one instance and
+ * writable at every instance its owner owns. */
 export const AUTH_RECORDS_FAMILY_FRAME = {
   ev: "topic",
   topic: "auth.records",
@@ -569,9 +635,9 @@ export const AUTH_RECORDS_FAMILY_FRAME = {
         updated_at: FIXTURE_NOW + 100_000,
         body: {
           kind: "token_family",
-          sub: "personal-1",
+          user: USER,
           iss: instance,
-          webui,
+          origin,
           access: { value: "YWNjZXNz", expires_at: FIXTURE_NOW + 10_000_000 },
           refresh: { value: "cmVmcmVzaA", expires_at: FIXTURE_NOW + 600_000_000 },
           last_refresh: {
@@ -588,8 +654,10 @@ export const AUTH_RECORDS_FAMILY_FRAME = {
   },
 } satisfies Static<typeof AuthRecordsFrame>;
 
-/** A removal travels as a record of its own. A credential's never expires; a
- * family's is kept only as long as a refresh token could still arrive. */
+/** A removal travels as a record of its own, and says nothing but when: what
+ * was removed is the key it arrives under. A credential's and an ownership's
+ * never expire; a family's is kept only as long as a refresh token could still
+ * arrive. */
 export const AUTH_RECORDS_TOMBSTONE_FRAME = {
   ev: "topic",
   topic: "auth.records",
@@ -597,16 +665,37 @@ export const AUTH_RECORDS_TOMBSTONE_FRAME = {
   data: {
     records: [
       {
-        key: "credential/personal-1/Y3JlZC1pZA",
+        key: "credential/Y3JlZC1pZA",
+        updated_at: FIXTURE_NOW + 100_000,
+        body: { kind: "tombstone", deleted_at: FIXTURE_NOW + 100_000 },
+      },
+      {
+        // The second person gives that instance up.
+        key: `ownership/${other_instance}/${OTHER_USER}/${THIRD_GRANT}`,
         updated_at: FIXTURE_NOW + 100_000,
-        body: { kind: "tombstone", sub: "personal-1", deleted_at: FIXTURE_NOW + 100_000 },
+        body: { kind: "tombstone", deleted_at: FIXTURE_NOW + 100_000 },
+      },
+      {
+        // And is made an owner of it again. A granting has an id of its own, so
+        // this is a key no tombstone stands on — where a key made of the
+        // instance and the person alone would have made the removal above
+        // final, with nothing able to undo it.
+        key: `ownership/${other_instance}/${OTHER_USER}/${FOURTH_GRANT}`,
+        updated_at: FIXTURE_NOW + 200_000,
+        body: {
+          kind: "ownership",
+          user: OTHER_USER,
+          instance: other_instance,
+          grant: FOURTH_GRANT,
+          granted_at: FIXTURE_NOW + 200_000,
+          granted_by: { kind: "user", user: USER },
+        },
       },
       {
         key: "family/01J9Z3W2Q",
         updated_at: FIXTURE_NOW + 100_000,
         body: {
           kind: "tombstone",
-          sub: "personal-1",
           deleted_at: FIXTURE_NOW + 100_000,
           expires_at: FIXTURE_NOW + 604_900_000,
         },