@ccmsg/protocol 1.2.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/protocol",
-  "version": "1.2.0",
+  "version": "1.4.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,13 @@ export const RegisterClaims = Type.Object(
     expires_at: Timestamp,
     /** Names this registration, so it can be spent once. */
     jti: Type.String({ minLength: 1 }),
+    /** The WebAuthn user handle for this subject: sixteen random bytes the
+     * issuing instance settles on once per `sub`. The page creates the
+     * credential against it, the record keeps it, and an assertion that names a
+     * handle is held to it. It is here rather than left to the page because the
+     * authenticator stores it beyond this instance's reach — a second value for
+     * one person would be a second account on their device. */
+    user_id: Base64Url,
     /** 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
@@ -242,7 +249,16 @@ export const AuthRefreshResponse = response("auth_refresh", AuthRefreshResult);
  * verification, the record lookup — the receiving instance does itself. */
 export const AuthResolveArgs = Type.Union(
   [
-    Type.Object({ kind: Type.Literal("register"), token: Type.String({ minLength: 1 }) }),
+    Type.Object({
+      kind: Type.Literal("register"),
+      token: Type.String({ minLength: 1 }),
+      /** The digits the person typed, forwarded unchecked. The issuer holds
+       * both the code and the count of attempts against it, so it is the only
+       * one that can refuse a wrong one and retire the URL after enough of
+       * them; a receiver that judged the code itself would let an attacker
+       * spread guesses across instances without any of them counting. */
+      code: Type.String({ pattern: "^[0-9]{6}$" }),
+    }),
     Type.Object({ kind: Type.Literal("challenge"), challenge: Base64Url }),
   ],
   { $id: "AuthResolveArgs" },
@@ -300,7 +316,9 @@ export const CredentialRecord = Type.Object(
     credential_id: Base64Url,
     /** The public key, COSE-encoded. */
     public_key: Base64Url,
-    /** The `user.id` this credential was created against. */
+    /** The `user_id` of the registration's claims, which is what the credential
+     * was created against and what an assertion naming a handle is checked
+     * 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
@@ -355,6 +373,30 @@ export const TokenFamily = Type.Object(
     refresh: Type.Object({ value: Base64Url, expires_at: Timestamp }),
     /** The generation before the current one, while the grace for it lasts. */
     previous_refresh: Type.Optional(Type.Object({ value: Base64Url, expires_at: Timestamp })),
+    /** What every generation retired before that was, kept only as a digest and
+     * only until the value itself would have expired.
+     *
+     * Recognising a replay takes remembering the value, but holding it is what
+     * the family is trying to protect — these travel to every instance, and a
+     * retired token still inside its lifetime would be a live secret copied
+     * around for no purpose it could serve. A digest answers the one question
+     * asked of it, that a value presented now was once issued here and is no
+     * longer, which fails the whole family.
+     *
+     * Written by the `iss` alone, like the rest of the family, and replicated,
+     * so the memory survives that instance restarting and holds wherever the
+     * reused value is presented. */
+    retired: Type.Optional(
+      Type.Array(
+        Type.Object({
+          /** sha256 of the retired value, lowercase hex. */
+          hash: Type.String({ pattern: "^[0-9a-f]{64}$" }),
+          /** When the value would have expired, after which remembering it
+           * refuses nothing that its own expiry would not. */
+          expires_at: Timestamp,
+        }),
+      ),
+    ),
   },
   { $id: "TokenFamily" },
 );