@ccmsg/protocol 2.2.0 → 2.4.0

package/package.json

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

@@ -39,13 +39,17 @@ export interface OpAttributes {
    * cannot, and they answer before any identity is settled. The route each is
    * published at belongs to the instance, not here.
    *
-   * Being reachable from a page is also what gives the three that settle an
+   * Being reachable from a page is also what gives the four 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 say the call came
-   * from a page at all — a navigation typed into the address bar is not how
-   * anyone authenticates. A missing header is a failure like a wrong one, and either
-   * answers `auth_invalid` without saying which. `auth.challenge` is checked
+   * browser states, held to the enrolment URL's origin on the two that spend one
+   * (`auth.register`, `auth.enroll`) and to the credential's or the family's on
+   * the two that do not (`auth.assert`, `auth.token.refresh`), 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";
@@ -68,7 +72,7 @@ const INSTANCE_ONLY = ["instance"] as const;
  * facts live: authorization, capability gating and forwarding all read it
  * rather than each carrying their own copy. */
 export const OP_ATTRIBUTES = {
-  // --- common: connect, declare the end, and subscribe (15) ---
+  // --- common: connect, declare the end, and subscribe (18) ---
   // A greeting settles what the connection is, and there is one per role: what
   // each must carry is then the op's own schema rather than a rule read off a
   // field, and a connection cannot be settled as something neither side meant.
@@ -136,7 +140,7 @@ export const OP_ATTRIBUTES = {
     errors: ["topic_unknown"],
   },
 
-  // The four ops that authenticate a person are open to every role for the
+  // The five ops that authenticate a person are open to every role for the
   // same reason the greetings are: they run before there is an identity to
   // check, and what they answer is what settles one. They are `any_instance` because whichever
   // instance is reached answers — behind a load balancer that is not a choice
@@ -166,6 +170,17 @@ export const OP_ATTRIBUTES = {
     carrier: "http",
     errors: ["auth_invalid", "auth_expired", "auth_unknown_issuer"],
   },
+  // Adding an instance to a person who already exists: the same enrolment URL
+  // and the same six digits as a registration, answered by an assertion instead
+  // of a new credential. Its attributes are the registration's for that reason.
+  "auth.enroll": {
+    plane: "common",
+    roles: ALL_ROLES,
+    needs_hello: false,
+    locality: "any_instance",
+    carrier: "http",
+    errors: ["auth_invalid", "auth_expired", "auth_unknown_issuer"],
+  },
   "auth.token.refresh": {
     plane: "common",
     roles: ALL_ROLES,
@@ -183,17 +198,44 @@ export const OP_ATTRIBUTES = {
     locality: "any_instance",
     errors: ["auth_invalid", "auth_expired"],
   },
-  // Between instances: what an issuer alone can answer. `owner_instance` by the
-  // usual rule — the subject belongs to one instance, and it is reached by
-  // `to_instance` being that instance's id.
-  "auth.resolve": {
+  // Reads back the caller's own account, which the connection already settled
+  // who is — so there is nothing further to check and nothing to name.
+  // `scope: "role"` because the role is what decides the reply's contents: it
+  // is the caller's own user, passkeys and instances and nobody else's.
+  "auth.account.read": {
     plane: "common",
-    roles: INSTANCE_ONLY,
+    roles: USER_ONLY,
     needs_hello: true,
-    locality: "owner_instance",
-    errors: ["auth_invalid", "auth_expired"],
+    locality: "any_instance",
+    scope: "role",
+    errors: [],
+  },
+  // Letting go of one of the two things a person holds. Both act on the
+  // caller's own records and nobody else's, which is what `scope: "role"` says
+  // here as it does on the read; what is removed is named, and who it belongs
+  // to is the connection. `auth_in_use` is the refusal when the thing named is
+  // what the call is being made with.
+  "auth.ownership.remove": {
+    plane: "common",
+    roles: USER_ONLY,
+    needs_hello: true,
+    locality: "any_instance",
+    scope: "role",
+    errors: ["not_found", "auth_in_use"],
   },
-  "auth.rotate": {
+  "auth.credential.remove": {
+    plane: "common",
+    roles: USER_ONLY,
+    needs_hello: true,
+    locality: "any_instance",
+    scope: "role",
+    errors: ["not_found", "auth_in_use"],
+  },
+  // Between instances: what an issuer alone can answer — an enrolment URL's
+  // secret and a challenge that may be spent once. `owner_instance` because
+  // both live in one instance's memory, and it is reached by `to_instance`
+  // being that instance's id.
+  "auth.resolve": {
     plane: "common",
     roles: INSTANCE_ONLY,
     needs_hello: true,