@ccmsg/protocol 1.0.0 → 1.2.0

package/package.json

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

@@ -92,6 +92,11 @@ export const RegisterClaims = Type.Object(
     expires_at: Timestamp,
     /** Names this registration, so it can be spent once. */
     jti: Type.String({ minLength: 1 }),
+    /** What the administrator who issued the URL wrote down about who it was
+     * for. Their words, not the holder's — the label the person gives their
+     * own device is `device_label` on the record, and the two are worth telling
+     * apart when a list is read back later. */
+    issued_label: Type.Optional(Type.String({ maxLength: 128 })),
   },
   { $id: "RegisterClaims" },
 );
@@ -118,6 +123,24 @@ export const AuthRegisterArgs = Type.Object({
   /** The registration URL's token, opaque to the caller and to any instance
    * but its issuer. */
   token: Type.String({ minLength: 1 }),
+  /** The six digits the command line showed when the URL was made, typed in by
+   * the person registering. It is not in the URL and never travels with it, so
+   * a leaked URL is not a registration: the two halves reach the browser by
+   * different routes, and only someone who was shown the terminal has both. */
+  code: Type.String({ pattern: "^[0-9]{6}$" }),
+  /** What the person calls the device they are registering, for their own use
+   * when they later read back a list of several. Nothing is decided by it. */
+  device_label: Type.Optional(Type.String({ maxLength: 128 })),
+  /** The challenge this registration answers, with the instance that can spend
+   * it — the same pairing an assertion carries, and for the same reason: the
+   * value also sits inside `client_data_json`, but who may consume it does not,
+   * and behind a load balancer the instance that issued it, the one that made
+   * the registration URL and the one receiving this may all be different.
+   *
+   * Omitting it leaves the receiver with a value and no issuer, so it can only
+   * be honoured where the receiver itself holds the challenge; anywhere else
+   * the registration is refused rather than guessed at. */
+  challenge: Type.Optional(AuthChallenge),
   credential: RegistrationCredential,
 });
 export type AuthRegisterArgs = Static<typeof AuthRegisterArgs>;
@@ -279,11 +302,38 @@ export const CredentialRecord = Type.Object(
     public_key: Base64Url,
     /** The `user.id` this credential was created against. */
     user_handle: Base64Url,
+    /** 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 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. */
     sign_count: Type.Optional(Type.Integer({ minimum: 0 })),
+    /** 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 })),
+    /** The label the person put on this device as they registered it. */
+    device_label: Type.Optional(Type.String({ maxLength: 128 })),
     registered_at: Timestamp,
+    /** Where the registration came from and what browser sent it.
+     *
+     * None of this authenticates anything, and nothing is ever admitted or
+     * refused by it — an address is trivially chosen by whoever is making the
+     * request. They are here to be recognised by the one person reading their
+     * own list: an address that is their home provider's and a browser that is
+     * the one they use is how they place a line as theirs, or fail to, which is
+     * the whole reason to keep it. The same holds of the pair below. */
+    registered_ip: Type.Optional(Type.String({ minLength: 1, maxLength: 45 })),
+    registered_user_agent: Type.Optional(Type.String({ maxLength: 512 })),
+    /** When this credential last answered a challenge, and from where. A
+     * credential the person no longer recognises is one they remove. */
+    last_used_at: Type.Optional(Timestamp),
+    last_used_ip: Type.Optional(Type.String({ minLength: 1, maxLength: 45 })),
+    last_used_user_agent: Type.Optional(Type.String({ maxLength: 512 })),
   },
   { $id: "CredentialRecord" },
 );

package/src/common/hello.ts

@@ -86,11 +86,16 @@ export type HelloArgs = Static<typeof HelloArgs>;
 /** One instance as seen from the instance answering `hello`. */
 export const InstanceInfo = Type.Object(
   {
-    id: InstanceId,
+    /** Absent until the handshake with it has settled: an endpoint an operator
+     * 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. */
-    endpoint: Endpoint,
+     * 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),
     /** The host it runs on. An attribute of the instance, not its identity —
      * one host may run several instances. */
     host: Type.String({ minLength: 1 }),
@@ -107,8 +112,10 @@ export const HelloResult = Type.Object({
   instance: InstanceId,
   /** Where the answering instance is dialed. 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. */
-  endpoint: Endpoint,
+   * 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
+   * its own machine, and it has no URL to give a peer. */
+  endpoint: Type.Optional(Endpoint),
   /** The instances this one knows of, itself included. */
   instances: Type.Array(InstanceInfo),
   /** What this instance can do. An op whose `capability` is absent here