@serfab/cadre-core 1.17.0 → 1.19.0

package/src/cadre-invite-protocol.ts

@@ -33,6 +33,7 @@ import {
   type ControlDatabase
 } from './control-database.js';
 import { verifyCadreInviteRow, verifyCadreInviteRedemption } from './peer-authorization.js';
+import { verifyPeerRecordSignature } from './peer-record.js';
 import { ed25519PublicKeyB64FromPeerId } from './ed25519-key.js';
 import { CADRE_INVITATION_PREFIX, CADRE_JOIN_REQUEST_PREFIX, OWNER_GRANT_PREFIX, OWNER_KEY_EXPORT_STEM } from './cadre-join-request.js';
 import {
@@ -54,7 +55,7 @@ import {
   type RedemptionAddressOutcome,
   type RedemptionRejection
 } from './member-redemption.js';
-import type { CadreInviteRow, CadreJoinProgress, SeedPeer } from './types.js';
+import type { CadreInviteRow, CadreJoinProgress, PeerAddressRecord, SeedPeer } from './types.js';
 
 const log = debug('sereus:cadre:invite-proto');
 
@@ -168,17 +169,28 @@ function isWellFormedCadreInvitation(value: unknown): value is CadreInvitation {
 
 // ── Wire messages ────────────────────────────────────────────────────────────
 
+/**
+ * The device's own address record as a request carries it: a {@link PeerAddressRecord} without
+ * the peer id, which the connection gives, and the key, which is the request's `peerKey`.
+ */
+export type RedeemSelfRecord = Pick<PeerAddressRecord, 'addrs' | 'updatedAt' | 'profile' | 'sig'>;
+
 /** Device → member: one frame, the whole redemption. */
 export interface CadreInviteRedeemRequest {
-  v: 1;
+  v: 2;
   /** The cadre the device believes it is joining; a machine serving another party refuses by name. */
   partyId: string;
   /** The owner-signed row from the bundle. */
   invite: CadreInviteRow;
   /** The device's ed25519 public key, base64url; must be the key behind the connecting peer id. */
   peerKey: string;
-  /** The device's dialable addresses; empty for a phone. Stored on its `CadrePeer` row. */
-  multiaddrs: string[];
+  /**
+   * The device's own address record for its `CadrePeer` row, self-signed for the invitation's
+   * party as `CadreNode.registerSelf` signs it (`signPeerRecord`); `addrs` is empty for a phone.
+   * The member stores `addrs` and, when the signature verifies over them, the rest of the
+   * record too ({@link admittedRecord}), so the device's first publish is its admission.
+   */
+  record: RedeemSelfRecord;
   /** Single-use nonce the device minted (`generateStampId`); both signatures cover it. */
   usageStampId: string;
   /** By `invitePrivateKey` over the `'redeem'` digest. */
@@ -336,19 +348,62 @@ export function isWellFormedCadreInviteRow(value: unknown): value is CadreInvite
     && isBoundedString(row.issuerSig);
 }
 
+/**
+ * The record's other fields are left to {@link admittedRecord}: a bad value there costs the
+ * device its signature on the row, not its admission.
+ */
 function isWellFormedRedeemRequest(value: unknown): value is CadreInviteRedeemRequest {
   if (typeof value !== 'object' || value === null) return false;
-  const { v, partyId, invite, peerKey, multiaddrs, usageStampId, inviteSig, peerSig } = value as Record<string, unknown>;
-  return v === 1
+  const { v, partyId, invite, peerKey, record, usageStampId, inviteSig, peerSig } = value as Record<string, unknown>;
+  return v === 2
     && isBoundedString(partyId)
     && isWellFormedCadreInviteRow(invite)
     && isEd25519KeyB64(peerKey)
-    && Array.isArray(multiaddrs)
+    && typeof record === 'object' && record !== null && Array.isArray((record as Record<string, unknown>).addrs)
     && isBoundedString(usageStampId)
     && isBoundedString(inviteSig)
     && isBoundedString(peerSig);
 }
 
+/** What the member writes on the device's `CadrePeer` row from the request's record. */
+interface AdmittedRecord {
+  /** The record's addresses, sanitized ({@link sanitizeAddrs}): stored whether or not the rest is. */
+  addrs: string[];
+  /** The record's freshness, profile and signature, or null when they cannot be stored as the device's own. */
+  signed: Pick<PeerAddressRecord, 'updatedAt' | 'profile' | 'sig'> | null;
+  /** Why `signed` is null; absent when it is not. */
+  unsignedBecause?: string;
+}
+
+/**
+ * Judge the device's record (`request.record`) for its admission row. The signature covers the
+ * exact address list, so it is kept only when sanitizing dropped nothing, the profile is one the
+ * schema's `KnownProfile` check admits, the stamp and signature are in their stored forms, and
+ * the signature verifies for `partyId` under the device's key. Anything less admits the device
+ * with its addresses and no signature, as an owner-written row is, and the device's next
+ * publish fills it in. No clock check: a stamp in the future or the past is one the device's own
+ * self-publish could write too.
+ */
+function admittedRecord(partyId: string, remotePeerId: string, request: Pick<CadreInviteRedeemRequest, 'peerKey' | 'record'>): AdmittedRecord {
+  const { addrs: offered, updatedAt, profile, sig } = request.record as Partial<Record<keyof RedeemSelfRecord, unknown>>;
+  const addrs = sanitizeAddrs(offered);
+  const unsigned = (because: string): AdmittedRecord => ({ addrs, signed: null, unsignedBecause: because });
+  // Sanitizing only drops entries, so an unchanged length is an unchanged list.
+  if (!Array.isArray(offered) || addrs.length !== offered.length) {
+    return unsigned('sanitizing changed the signed address list');
+  }
+  if (profile !== null && profile !== 'transaction' && profile !== 'storage') {
+    return unsigned('unknown profile');
+  }
+  if (typeof updatedAt !== 'number' || !Number.isSafeInteger(updatedAt) || updatedAt <= 0 || !isBoundedString(sig)) {
+    return unsigned('malformed stamp or signature');
+  }
+  if (!verifyPeerRecordSignature(partyId, { peerId: remotePeerId, publicKey: request.peerKey, addrs, updatedAt, profile, sig })) {
+    return unsigned('signature does not verify');
+  }
+  return { addrs, signed: { updatedAt, profile, sig } };
+}
+
 /**
  * Keep only parsable, distinct multiaddr strings, capped at {@link MAX_ADDRS}, order kept.
  * Applied on both sides: the member bounds what it stores on the device's row, the device
@@ -411,22 +466,26 @@ export interface RedeemSigner {
  * (invitation key, `usageStampId`, device key) for the invitation's party. The same bytes
  * the schema verifies at the member (`cadreInviteRedeemMessage` / `cadreInviteConsentMessage`),
  * whose own `party_id()` must therefore be the party the bundle names.
+ *
+ * @param record - the device's address record, already signed for the invitation's party over
+ *   sanitized addresses ({@link sanitizeAddrs}); copied in unchanged, since the signature
+ *   covers the exact list.
  */
 export function signRedeemRequest(
   invitation: CadreInvitation,
   signer: RedeemSigner,
   usageStampId: string,
-  multiaddrs: string[]
+  record: RedeemSelfRecord
 ): CadreInviteRedeemRequest {
   const fields = { inviteKey: invitation.invite.key, usageStampId, peerKey: signer.peerKey };
   const signB64 = (message: Uint8Array, privateKey: string): string =>
     sign(message, privateKey, 'ed25519', 'bytes', 'base64url', 'base64url') as string;
   return {
-    v: 1,
+    v: 2,
     partyId: invitation.partyId,
     invite: invitation.invite,
     peerKey: signer.peerKey,
-    multiaddrs: sanitizeAddrs(multiaddrs),
+    record: { addrs: [...record.addrs], updatedAt: record.updatedAt, profile: record.profile, sig: record.sig },
     usageStampId,
     inviteSig: signB64(cadreInviteRedeemMessage(invitation.partyId, fields), invitation.invitePrivateKey),
     peerSig: signB64(cadreInviteConsentMessage(invitation.partyId, fields), signer.peerPrivateKey)
@@ -466,7 +525,7 @@ export function verifyRedeemReply(
 // ── Member side (handler) ────────────────────────────────────────────────────
 
 /** The control-database surface a redemption needs; a `ControlDatabase` satisfies it. */
-export type CadreInviteStore = Pick<ControlDatabase, 'seatCadreInvite' | 'isCadreInviteLive' | 'redeemCadreInvite' | 'querySeedPeers'>;
+export type CadreInviteStore = Pick<ControlDatabase, 'queryCadreInvite' | 'seatCadreInvite' | 'isCadreInviteLive' | 'redeemCadreInvite' | 'querySeedPeers'>;
 
 export interface CadreInviteHandlerOptions extends MemberRedemptionHandlerOptions {
   /** This member's peer id: the reply's peer list marks it preferred, since the device just reached it. */
@@ -485,11 +544,11 @@ const REDEEM_CONSTRAINT_CODES: ReadonlyArray<ConstraintRefusalRow<CadreInviteRej
  * Member side of the invitation protocol (`MemberRedemptionHandler` has the shape): after the
  * request's shape, it checks the party, the connecting identity (an ed25519 peer id is an
  * identity multihash of the very key, and this is the only layer that can check the pair),
- * both signatures and a targeted invitation's device, then seats the row from the bundle and
- * redeems. An issuer this member does not know as an owner is the one retryable refusal left:
- * the device tries the next address, which may hold the issuer's row.
+ * both signatures and a targeted invitation's device, then seats the row from the bundle when
+ * this member holds none and redeems. An issuer this member does not know as an owner is the
+ * one retryable refusal left: the device tries the next address, which may hold the issuer's row.
  */
-export class CadreInviteHandler extends MemberRedemptionHandler<CadreInviteRedeemRequest, CadreInviteRedeemReply> {
+export class CadreInviteHandler extends MemberRedemptionHandler<CadreInviteRedeemRequest, CadreInviteRedeemReply, CadreInviteRow> {
   private readonly peerId: string;
   private readonly store: CadreInviteStore;
   protected readonly busyRefusal = rejection('busy', 'Too many concurrent redemptions');
@@ -523,27 +582,41 @@ export class CadreInviteHandler extends MemberRedemptionHandler<CadreInviteRedee
     return null;
   }
 
-  protected isLive(request: CadreInviteRedeemRequest): Promise<boolean> {
-    return this.store.isCadreInviteLive(request.invite);
+  protected readHeld(request: CadreInviteRedeemRequest): Promise<CadreInviteRow | null> {
+    return this.store.queryCadreInvite(request.invite.key);
   }
 
-  /** The two writes — the seat (its own transaction; a no-op when held) and the redemption — each answered by name when it fails. */
-  protected async redeemAdmitted(request: CadreInviteRedeemRequest, remotePeerId: string): Promise<CadreInviteRedeemReply> {
-    try {
-      await this.store.seatCadreInvite(request.invite);
-    } catch (error) {
-      if (error instanceof CadreInviteIssuerUnknownError) {
-        return rejection('issuer-unknown', 'The invitation\'s issuer is not known as an owner here');
-      }
-      log('seating invitation %s from %s failed: %o', request.invite.key, remotePeerId, error);
-      return constraintRefusal(error, REDEEM_CONSTRAINT_CODES) ?? writeFailureRefusal(error);
+  protected isLive(request: CadreInviteRedeemRequest, held: CadreInviteRow | null): Promise<boolean> {
+    return this.store.isCadreInviteLive(request.invite, held);
+  }
+
+  /**
+   * The two writes — the seat (its own transaction), only when this member holds no row, and
+   * the redemption — each answered by name when it fails. The held row is carried into the
+   * redemption so it is not read again in the write lock; after a fresh seat nothing is carried
+   * and the redemption reads the row it seated, since the bundle's copy is the requester's.
+   */
+  protected async redeemAdmitted(request: CadreInviteRedeemRequest, remotePeerId: string, held: CadreInviteRow | null): Promise<CadreInviteRedeemReply> {
+    if (held === null) {
+      const refused = await this.seat(request, remotePeerId);
+      if (refused) return refused;
+    }
+    // Built before the write: the `CadrePeer` membership view is normally warm then (the
+    // connection gate read it when the device connected), and the redemption's commit drops it.
+    // The list lacks the device's own row, which the device drops from it anyway.
+    const peers = await this.peersBestEffort();
+    const record = admittedRecord(this.partyId, remotePeerId, request);
+    if (record.signed === null) {
+      log('admitting %s without its own record signature: %s', remotePeerId, record.unsignedBecause);
     }
     try {
       const result = await this.store.redeemCadreInvite({
         inviteKey: request.invite.key,
+        ...(held ? { held } : {}),
         peerId: remotePeerId,
         peerKey: request.peerKey,
-        multiaddrs: sanitizeAddrs(request.multiaddrs),
+        multiaddrs: record.addrs,
+        ...(record.signed ? { record: record.signed } : {}),
         usageStampId: request.usageStampId,
         inviteSig: request.inviteSig,
         peerSig: request.peerSig
@@ -556,9 +629,24 @@ export class CadreInviteHandler extends MemberRedemptionHandler<CadreInviteRedee
       log('redeeming invitation %s for %s failed: %o', request.invite.key, remotePeerId, error);
       return constraintRefusal(error, REDEEM_CONSTRAINT_CODES) ?? writeFailureRefusal(error);
     }
-    // The row as held: the seat inserted this copy verbatim, or found the same row (its key
-    // is the primary key and every column is under the issuer's signature).
-    return { accepted: true, partyId: this.partyId, invite: request.invite, peers: await this.peersBestEffort() };
+    // The row as held: read before the write, or the bundle's copy the seat inserted verbatim
+    // or found already held (its key is the primary key and every column is under the issuer's
+    // signature).
+    return { accepted: true, partyId: this.partyId, invite: held ?? request.invite, peers };
+  }
+
+  /** Seat the bundle's copy of the row; a refusal answered by name, or null once it is held. */
+  private async seat(request: CadreInviteRedeemRequest, remotePeerId: string): Promise<CadreInviteRejection | null> {
+    try {
+      await this.store.seatCadreInvite(request.invite);
+      return null;
+    } catch (error) {
+      if (error instanceof CadreInviteIssuerUnknownError) {
+        return rejection('issuer-unknown', 'The invitation\'s issuer is not known as an owner here');
+      }
+      log('seating invitation %s from %s failed: %o', request.invite.key, remotePeerId, error);
+      return constraintRefusal(error, REDEEM_CONSTRAINT_CODES) ?? writeFailureRefusal(error);
+    }
   }
 
   /** Dial hints are an optimization; a failed read costs the device its hints, not its membership. */