@forgesworn/fold-kit 0.6.0 → 0.7.0

package/README.md

@@ -160,6 +160,14 @@ the rest).
   authority answers `refused: 'unknown'`, which `requestRoomEpoch` waits
   through). `encodeRekeyEvent({ members })` and `hostRoomEpoch({ members })`
   carry the authority's member list (`readMemberList` reads one)
+- Seal keys (`docs/seal-key.md`): a credential may name a seal key
+  (`createDeviceCredential({ seal })`, `generateSealKey`), and rekeys and
+  both grants are sealed to the newest one the sender holds for a device
+  instead of its device key, so a copied device heals once its credential
+  lapses and the room rekeys. Recipients as `{ device, credential }`;
+  `sealSks` on the readers; `credentialFor` on both desks;
+  `credentialSeal`, `sealTarget`, `sealTo`, `openSealed`, `newerCredential`,
+  `sealCredential`. Vectors: `vectors/seal-vectors.json`
 - `canonicalAdmins`, `signAdmins`, `verifyAdmins` - the authority's signed
   admin list
 - `canonicalChannels`, `signChannels`, `verifyChannels`, `CHANNEL_NAME`,

package/dist/credential.d.ts

@@ -25,6 +25,11 @@ export interface CreateCredentialOptions {
     expiresAt: number;
     /** Injectable clock, in unix seconds. Defaults to the real one. */
     now?: () => number;
+    /** The device's seal key for this credential: an x-only public key,
+     *  minted fresh for each credential, to which rekeys and epoch grants are
+     *  then sealed instead of the device key. See `seal.ts`. Omitted, the
+     *  credential is byte-identical to one minted before seal keys. */
+    seal?: string;
 }
 /** The longest a person-scoped credential may run. A phone that leaves the house is better at seven days. */
 export declare const PERSON_CREDENTIAL_MAX_SECONDS: number;

package/dist/credential.js

@@ -1,6 +1,7 @@
 import { KINDS } from './kinds.js';
 import { verifyEventUncached } from './verify.js';
 import { hexEquals, normaliseHex } from './hex.js';
+import { isSealPubkey, SEAL_TAG } from './seal.js';
 /** The longest a person-scoped credential may run. A phone that leaves the house is better at seven days. */
 export const PERSON_CREDENTIAL_MAX_SECONDS = 30 * 24 * 60 * 60;
 /**
@@ -43,6 +44,8 @@ export async function createDeviceCredential(opts) {
         throw new Error('a room credential needs a room');
     if (person && opts.expiresAt - now > PERSON_CREDENTIAL_MAX_SECONDS)
         throw new Error('a person credential may not run more than 30 days');
+    if (opts.seal !== undefined && !isSealPubkey(opts.seal))
+        throw new Error('a seal key must be an x-only public key on the curve');
     const unsigned = {
         kind: KINDS.CREDENTIAL,
         created_at: now,
@@ -52,6 +55,7 @@ export async function createDeviceCredential(opts) {
             ['expiration', String(opts.expiresAt)],
             ...(person ? [['scope', 'person']] : []),
             ...(opts.label !== undefined ? [['label', opts.label]] : []),
+            ...(opts.seal !== undefined ? [[SEAL_TAG, opts.seal.toLowerCase()]] : []),
         ],
         content: '',
     };

package/dist/epoch.d.ts

@@ -98,8 +98,11 @@ export interface EncodeRekeyOptions {
     /** The epoch being entered. Must be `current.epoch + 1`. */
     next: RoomEpoch;
     /** Devices to seal the new secret for. Everybody still in the room,
-     *  except the removed participants' devices. */
-    recipients: string[];
+     *  except the removed participants' devices. A recipient given with its
+     *  newest credential is sealed to that credential's seal key, when it
+     *  names one; a bare device, to the device key (see `seal.ts`). The
+     *  `keys` map is keyed by device either way. */
+    recipients: ReadonlyArray<string | RekeyRecipient>;
     /** Participants removed at this step. Empty on a rekey that only turns
      *  the key over. */
     removed: string[];
@@ -122,6 +125,12 @@ export interface EncodeRekeyOptions {
      *  NIP-40 expiration (see `withExpiration`). Omit for a room with no end. */
     expiresAt?: number;
 }
+/** A rekey recipient: a device, and the newest credential the sender holds
+ *  for it. */
+export interface RekeyRecipient {
+    device: string;
+    credential?: DeviceCredential;
+}
 /** Announce the next epoch. See the module comment for what this is. */
 export declare function encodeRekeyEvent(opts: EncodeRekeyOptions): Event;
 /** What a rekey says, once read. */
@@ -160,6 +169,9 @@ export interface DecodeRekeyOptions extends PeekRekeyOptions {
     current: EpochKeys;
     /** This device's key, to open its own copy. */
     deviceSk: Uint8Array;
+    /** The seal key secrets this device holds, newest first, tried before
+     *  the device key (see `seal.ts`). */
+    sealSks?: readonly Uint8Array[];
 }
 /**
  * Read a rekey. Null for anything that does not check out, and for a rekey
@@ -258,6 +270,9 @@ export interface EncodeEpochGrantOptions {
      *  desk knows them too. Omitted, the body is as before. */
     members?: string[];
     refused?: EpochRefusal;
+    /** The newest credential the authority holds for the device: the grant
+     *  is sealed to its seal key when it names one (see `seal.ts`). */
+    credential?: DeviceCredential;
     /** A conference room's end, in unix seconds: the event carries it as a
      *  NIP-40 expiration (see `withExpiration`). Omit for a room with no end. */
     expiresAt?: number;
@@ -269,6 +284,9 @@ export interface DecodeEpochGrantOptions {
     roomId: string;
     authority: string;
     deviceSk: Uint8Array;
+    /** The seal key secrets this device holds: see
+     *  `DecodeRekeyOptions.sealSks`. */
+    sealSks?: readonly Uint8Array[];
     request: string;
     now: number;
     maxAgeSeconds?: number;
@@ -314,6 +332,15 @@ export interface HostRoomEpochOptions {
     /** The participants to tell a granted device about, so its own member
      *  desk knows them too. Asked on every grant. */
     members?: () => readonly string[];
+    /**
+     * The newest credential the authority has seen for a device, from the
+     * roster. An answer is sealed to the newer of this and the one the
+     * request carries, so a thief replaying a device's older, still-live
+     * credential is answered under the seal key the device minted since.
+     * Keep it monotone: a roster entry carrying an older credential than one
+     * already seen must not replace it, or the thief can publish one.
+     */
+    credentialFor?: (device: string) => DeviceCredential | undefined;
     /** Somebody the room does not know asked, after a removal: what an app
      *  turns into "let them in?". Called once per participant, and again
      *  every `reportUnknownEvery` seconds while they keep asking. Letting them in
@@ -330,6 +357,15 @@ export interface HostRoomEpochOptions {
     /** A conference room's end: every grant carries it as an expiration. */
     expiresAt?: number;
 }
+/**
+ * The credential to seal an answer to: the one the request carries, unless
+ * the room has seen a newer one for the same device and participant that
+ * still verifies. Shared by both desks.
+ */
+export declare function sealCredential(request: {
+    device: string;
+    participant: string;
+}, presented: DeviceCredential, credentialFor: ((device: string) => DeviceCredential | undefined) | undefined, roomId: string, now: number): DeviceCredential;
 /**
  * Answer epoch requests for as long as the handle is open. What a keeper
  * runs beside its invitation desk: a member arriving, or returning, after
@@ -370,6 +406,9 @@ export interface RequestRoomEpochOptions {
     /** The authority said the room does not know this participant yet. Not
      *  final: the ask goes on, and a member letting them in settles it. */
     onUnknown?: () => void;
+    /** The seal key secrets this device holds. Asked on every answer,
+     *  because a credential may renew while the ask is out. */
+    sealSks?: () => readonly Uint8Array[];
 }
 /** Thrown when the authority answered, and the answer was no. */
 export declare class EpochRefusedError extends Error {

package/dist/epoch.js

@@ -12,6 +12,7 @@ import { deriveRoom } from './room.js';
 import { verifyDeviceCredential } from './credential.js';
 import { evaluateAccess } from './access.js';
 import { verifyEventUncached } from './verify.js';
+import { newerCredential, openSealed, sealTo } from './seal.js';
 import { withExpiration } from './expiration.js';
 import { epochCommitment } from './epoch-commit.js';
 /**
@@ -146,8 +147,9 @@ export function encodeRekeyEvent(opts) {
     const sealed = { v: 1, secret: base64urlnopad.encode(opts.next.secret) };
     const plaintext = JSON.stringify(sealed);
     for (const raw of opts.closed ? [] : opts.recipients) {
-        const device = requireHex32(raw, 'recipient device');
-        keys[device] = nip44.v2.encrypt(plaintext, nip44.v2.utils.getConversationKey(opts.authoritySk, device));
+        const recipient = typeof raw === 'string' ? { device: raw } : raw;
+        const device = requireHex32(recipient.device, 'recipient device');
+        keys[device] = sealTo(plaintext, opts.authoritySk, device, recipient.credential);
     }
     const body = {
         v: 1,
@@ -227,11 +229,20 @@ export function decodeRekeyEvent(event, opts) {
         const device = getPublicKey(opts.deviceSk);
         const mine = Object.entries(body.keys).find(([to]) => hexEquals(to, device))?.[1];
         if (typeof mine === 'string') {
-            const sealed = JSON.parse(nip44.v2.decrypt(mine, nip44.v2.utils.getConversationKey(opts.deviceSk, event.pubkey)));
-            if (sealed.v === 1 && typeof sealed.secret === 'string') {
-                const secret = base64urlnopad.decode(sealed.secret);
-                if (secret.length === 32)
-                    notice.secret = secret;
+            // A copy none of this device's keys opens is no copy: sealed to a
+            // seal key it has since erased, or one it never had. The rest of the
+            // rekey still says who was removed, so it is read without the secret,
+            // and the device asks for the epoch.
+            try {
+                const sealed = JSON.parse(openSealed(mine, event.pubkey, opts.deviceSk, opts.sealSks));
+                if (sealed.v === 1 && typeof sealed.secret === 'string') {
+                    const secret = base64urlnopad.decode(sealed.secret);
+                    if (secret.length === 32)
+                        notice.secret = secret;
+                }
+            }
+            catch {
+                // No secret, as above.
             }
         }
         return notice;
@@ -314,6 +325,12 @@ export function encodeEpochRequest(opts) {
  *  cannot prove which participant it speaks for in this room, or from one
  *  that cannot prove it was admitted to the room at all. */
 export function decodeEpochRequest(event, opts) {
+    const read = readEpochRequest(event, opts);
+    return read && read.request;
+}
+/** `decodeEpochRequest`, keeping the credential the request was made
+ *  under: what the desk seals its answer by. */
+function readEpochRequest(event, opts) {
     try {
         if (event.kind !== KINDS.EPOCH_REQUEST)
             return null;
@@ -358,7 +375,7 @@ export function decodeEpochRequest(event, opts) {
             if (!evaluateAccess(opts.policy, verdict.participant, proof, opts.now, opts.roomId).admitted)
                 return null;
         }
-        return { device: verdict.device, participant: verdict.participant, request: event.id };
+        return { request: { device: verdict.device, participant: verdict.participant, request: event.id }, credential: body.credential };
     }
     catch {
         return null;
@@ -398,7 +415,7 @@ export function encodeEpochGrant(opts) {
             ['d', roomId],
             ['p', device],
         ], opts.expiresAt),
-        content: nip44.v2.encrypt(JSON.stringify(body), nip44.v2.utils.getConversationKey(opts.authoritySk, device)),
+        content: sealTo(JSON.stringify(body), opts.authoritySk, device, opts.credential),
     }, opts.authoritySk);
 }
 /** Read the authority's answer to this device's own request. Null for
@@ -420,7 +437,7 @@ export function decodeEpochGrant(event, opts) {
         const addressed = event.tags.find((t) => t[0] === 'p')?.[1];
         if (addressed === undefined || !hexEquals(addressed, device))
             return null;
-        const body = JSON.parse(nip44.v2.decrypt(event.content, nip44.v2.utils.getConversationKey(opts.deviceSk, event.pubkey)));
+        const body = JSON.parse(openSealed(event.content, event.pubkey, opts.deviceSk, opts.sealSks));
         if (body.v !== 1 || typeof body.request !== 'string' || !hexEquals(body.request, opts.request))
             return null;
         if (body.refused === 'removed' || body.refused === 'closed' || body.refused === 'unknown')
@@ -445,6 +462,26 @@ export function decodeEpochGrant(event, opts) {
         return null;
     }
 }
+/**
+ * The credential to seal an answer to: the one the request carries, unless
+ * the room has seen a newer one for the same device and participant that
+ * still verifies. Shared by both desks.
+ */
+export function sealCredential(request, presented, credentialFor, roomId, now) {
+    let known;
+    try {
+        known = credentialFor?.(request.device);
+    }
+    catch {
+        known = undefined;
+    }
+    if (!known)
+        return presented;
+    const verdict = verifyDeviceCredential(known, { roomId, now });
+    if (!verdict.ok || verdict.device !== normaliseHex(request.device) || verdict.participant !== normaliseHex(request.participant))
+        return presented;
+    return newerCredential(presented, known);
+}
 /**
  * Answer epoch requests for as long as the handle is open. What a keeper
  * runs beside its invitation desk: a member arriving, or returning, after
@@ -483,7 +520,7 @@ export function hostRoomEpoch(opts) {
     const unsub = opts.transport.subscribe([{ kinds: [KINDS.EPOCH_REQUEST], '#d': [roomId], '#p': [authority] }], (event) => {
         if (closed)
             return;
-        const request = decodeEpochRequest(event, {
+        const read = readEpochRequest(event, {
             roomId,
             authoritySk: opts.authoritySk,
             roomKey: opts.roomKey,
@@ -491,8 +528,9 @@ export function hostRoomEpoch(opts) {
             policy: opts.policy,
             legacyParticipants: opts.legacyParticipants,
         });
-        if (!request || answered.has(request.request))
+        if (!read || answered.has(read.request.request))
             return;
+        const request = read.request;
         let refused;
         if (opts.closed?.())
             refused = 'closed';
@@ -514,7 +552,16 @@ export function hostRoomEpoch(opts) {
         let grant;
         try {
             grant = refused
-                ? encodeEpochGrant({ roomId, authoritySk: opts.authoritySk, device: request.device, request: request.request, now: now(), refused, expiresAt: opts.expiresAt })
+                ? encodeEpochGrant({
+                    roomId,
+                    authoritySk: opts.authoritySk,
+                    device: request.device,
+                    request: request.request,
+                    now: now(),
+                    refused,
+                    credential: sealCredential(request, read.credential, opts.credentialFor, roomId, now()),
+                    expiresAt: opts.expiresAt,
+                })
                 : encodeEpochGrant({
                     roomId,
                     authoritySk: opts.authoritySk,
@@ -524,6 +571,7 @@ export function hostRoomEpoch(opts) {
                     epoch: opts.current(),
                     removed: [...opts.removed()],
                     ...(opts.members ? { members: [...opts.members()] } : {}),
+                    credential: sealCredential(request, read.credential, opts.credentialFor, roomId, now()),
                     expiresAt: opts.expiresAt,
                 });
         }
@@ -604,7 +652,14 @@ export function requestRoomEpoch(opts) {
             settle();
         };
         unsub = opts.transport.subscribe([{ kinds: [KINDS.EPOCH_GRANT], '#d': [roomId], '#p': [device] }], (event) => {
-            const grant = decodeEpochGrant(event, { roomId, authority: opts.authority, deviceSk: opts.deviceSk, request: request.id, now: now() });
+            const grant = decodeEpochGrant(event, {
+                roomId,
+                authority: opts.authority,
+                deviceSk: opts.deviceSk,
+                sealSks: opts.sealSks?.(),
+                request: request.id,
+                now: now(),
+            });
             if (!grant)
                 return;
             if (grant.refused === 'unknown') {

package/dist/index.d.ts

@@ -7,6 +7,8 @@ export type { DeviceCredential, AccessTier, AgentRule, RoomPolicy, KindredProof
 export type { RelayTransport } from './transport.js';
 export { createDeviceCredential, verifyDeviceCredential, PERSON_CREDENTIAL_MAX_SECONDS, RestampedCredentialExpiryError, } from './credential.js';
 export type { CreateCredentialOptions, VerifyResult } from './credential.js';
+export { SEAL_TAG, isSealPubkey, generateSealKey, credentialSeal, sealTarget, sealTo, openSealed, newerCredential, } from './seal.js';
+export type { SealKey } from './seal.js';
 export { deriveScoped, SCOPED_LABEL_PATTERN } from './scoped.js';
 export type { ScopedKeys } from './scoped.js';
 export { createSubKeyCertificate, verifySubKeyCertificate, SUB_KEY_CERTIFICATE_SCOPE, } from './sub-cert.js';
@@ -24,8 +26,8 @@ export { withExpiration, isRoomEnds, requireRoomEnds, MAX_ROOM_ENDS_SECONDS } fr
 export { isInvitationRelays, requireInvitationRelays, MAX_INVITATION_RELAYS } from './invitation-relays.js';
 export { MAX_ROOM_LINK_FRAGMENT_LENGTH, parseRoomLink, encodeRoomLink, } from './link.js';
 export type { RoomLink } from './link.js';
-export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, readMemberList, REPORT_UNKNOWN_EVERY_SECONDS, decodeRekeyEvent, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';
-export type { RoomEpoch, EpochKeys, EncodeRekeyOptions, RekeyNotice, PeekRekeyOptions, DecodeRekeyOptions, EpochRequestAdmissionOptions, EncodeEpochRequestOptions, DecodeEpochRequestOptions, EpochRequest, EpochRefusal, EncodeEpochGrantOptions, DecodeEpochGrantOptions, EpochGrant, HostRoomEpochOptions, RequestRoomEpochOptions, SignAdminsOptions, SignChannelsOptions, VerifyChannelsOptions, VerifyAdminsOptions, } from './epoch.js';
+export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, readMemberList, REPORT_UNKNOWN_EVERY_SECONDS, decodeRekeyEvent, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, sealCredential, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';
+export type { RoomEpoch, EpochKeys, EncodeRekeyOptions, RekeyRecipient, RekeyNotice, PeekRekeyOptions, DecodeRekeyOptions, EpochRequestAdmissionOptions, EncodeEpochRequestOptions, DecodeEpochRequestOptions, EpochRequest, EpochRefusal, EncodeEpochGrantOptions, DecodeEpochGrantOptions, EpochGrant, HostRoomEpochOptions, RequestRoomEpochOptions, SignAdminsOptions, SignChannelsOptions, VerifyChannelsOptions, VerifyAdminsOptions, } from './epoch.js';
 export { EPOCH_COMMIT_PREFIX, epochCommitment, EPOCH_COMMIT_LABELS } from './epoch-commit.js';
 export { MEMBER_EPOCH_KINDS, MEMBER_EPOCH_REQUEST_KEY_INFO, MAX_MEMBER_EPOCH_CHAIN, deriveMemberEpochRequestKey, readRekeyEvidence, encodeMemberEpochRequest, decodeMemberEpochRequest, encodeMemberEpochGrant, decodeMemberEpochGrant, hostMemberEpochDesk, memberEpochSource, requestMemberEpoch, MEMBER_EPOCH_LABELS, } from './member-epoch.js';
 export type { RekeyEvidence, EncodeMemberEpochRequestOptions, DecodeMemberEpochRequestOptions, MemberEpochRequest, EncodeMemberEpochGrantOptions, DecodeMemberEpochGrantOptions, MemberEpochGrant, HostMemberEpochDeskOptions, MemberEpochRequestOptions, MemberEpochSource, } from './member-epoch.js';

package/dist/index.js

@@ -5,6 +5,7 @@ export { verifyEventUncached, boundedEventVerifier } from './verify.js';
 export { localIdentity } from './identity.js';
 export { KINDS } from './kinds.js';
 export { createDeviceCredential, verifyDeviceCredential, PERSON_CREDENTIAL_MAX_SECONDS, RestampedCredentialExpiryError, } from './credential.js';
+export { SEAL_TAG, isSealPubkey, generateSealKey, credentialSeal, sealTarget, sealTo, openSealed, newerCredential, } from './seal.js';
 export { deriveScoped, SCOPED_LABEL_PATTERN } from './scoped.js';
 export { createSubKeyCertificate, verifySubKeyCertificate, SUB_KEY_CERTIFICATE_SCOPE, } from './sub-cert.js';
 export { generateRoomSecret, deriveRoom, encodeJoinUrl, decodeJoinUrl, parseRoomPolicy, ROOM_LABELS, } from './room.js';
@@ -16,7 +17,7 @@ export { encodePersistentInvitation, decodePersistentInvitation, requestPersiste
 export { withExpiration, isRoomEnds, requireRoomEnds, MAX_ROOM_ENDS_SECONDS } from './expiration.js';
 export { isInvitationRelays, requireInvitationRelays, MAX_INVITATION_RELAYS } from './invitation-relays.js';
 export { MAX_ROOM_LINK_FRAGMENT_LENGTH, parseRoomLink, encodeRoomLink, } from './link.js';
-export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, readMemberList, REPORT_UNKNOWN_EVERY_SECONDS, decodeRekeyEvent, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';
+export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, readMemberList, REPORT_UNKNOWN_EVERY_SECONDS, decodeRekeyEvent, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, sealCredential, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';
 export { EPOCH_COMMIT_PREFIX, epochCommitment, EPOCH_COMMIT_LABELS } from './epoch-commit.js';
 export { MEMBER_EPOCH_KINDS, MEMBER_EPOCH_REQUEST_KEY_INFO, MAX_MEMBER_EPOCH_CHAIN, deriveMemberEpochRequestKey, readRekeyEvidence, encodeMemberEpochRequest, decodeMemberEpochRequest, encodeMemberEpochGrant, decodeMemberEpochGrant, hostMemberEpochDesk, memberEpochSource, requestMemberEpoch, MEMBER_EPOCH_LABELS, } from './member-epoch.js';
 export { deriveChannel, CHANNEL_ID_INFO, CHANNEL_KEY_INFO, MAX_CHANNEL_NAME_LENGTH, CHANNEL_LABELS } from './channel.js';

package/dist/member-epoch.d.ts

@@ -118,6 +118,9 @@ export interface EncodeMemberEpochGrantOptions {
     epochs: RoomEpoch[];
     /** The authority's rekey event for each of `epochs`, in the same order. */
     rekeys: Event[];
+    /** The newest credential the member holds for the device: the grant is
+     *  sealed to its seal key when it names one (see `seal.ts`). */
+    credential?: DeviceCredential;
     now: number;
     expiresAt?: number;
 }
@@ -136,6 +139,9 @@ export interface DecodeMemberEpochGrantOptions {
     authority: string;
     /** The asking device's key. */
     deviceSk: Uint8Array;
+    /** The seal key secrets this device holds, newest first, tried before
+     *  the device key (see `seal.ts`). */
+    sealSks?: readonly Uint8Array[];
     /** The ids of this device's own outstanding member requests. */
     requests: ReadonlySet<string>;
     /** Where this device is: the chain starts from this epoch's key. */
@@ -201,6 +207,10 @@ export interface HostMemberEpochDeskOptions {
      * answered (#207). Without it, after a removal, nobody is known.
      */
     known?: (participant: string) => boolean;
+    /** The newest credential this device has seen for another device, from
+     *  the roster: see `HostRoomEpochOptions.credentialFor`. Keep it
+     *  monotone. */
+    credentialFor?: (device: string) => DeviceCredential | undefined;
     /** Somebody the room does not know asked, after a removal. Called once
      *  per participant, and again every `reportUnknownEvery` seconds while
      *  they keep asking; nothing is published. Letting them in is making `known`
@@ -270,6 +280,9 @@ export interface MemberEpochRequestOptions {
     now?: () => number;
     /** How often a fresh request goes out. Default 4000 ms. */
     retryMs?: number;
+    /** The seal key secrets this device holds. Asked on every answer,
+     *  because a credential may renew while the ask is out. */
+    sealSks?: () => readonly Uint8Array[];
     expiresAt?: number;
 }
 /** What `requestRoomEpoch({ members })` takes: a second source of answers

package/dist/member-epoch.js

@@ -9,8 +9,9 @@ import { evaluateAccess } from './access.js';
 import { verifyEventUncached } from './verify.js';
 import { withExpiration } from './expiration.js';
 import { epochCommitment } from './epoch-commit.js';
+import { openSealed, sealTo } from './seal.js';
 import { KINDS } from './kinds.js';
-import { MAX_EPOCH, REPORT_UNKNOWN_EVERY_SECONDS, deriveEpoch, epochRequestAdmission, peekRekeyEvent, readMemberList, } from './epoch.js';
+import { MAX_EPOCH, REPORT_UNKNOWN_EVERY_SECONDS, deriveEpoch, epochRequestAdmission, peekRekeyEvent, readMemberList, sealCredential, } from './epoch.js';
 /**
  * Member-to-member epoch catch-up: any current member can bring an
  * admitted, non-removed member up to date.
@@ -153,6 +154,12 @@ export function encodeMemberEpochRequest(opts) {
 /** Null for anything malformed, stale, from a device that cannot prove
  *  which participant it speaks for, or that cannot prove admission. */
 export function decodeMemberEpochRequest(event, opts) {
+    const read = readMemberEpochRequest(event, opts);
+    return read && read.request;
+}
+/** `decodeMemberEpochRequest`, keeping the credential the request was made
+ *  under: what the desk seals its answer by. */
+function readMemberEpochRequest(event, opts) {
     try {
         if (event.kind !== MEMBER_EPOCH_KINDS.REQUEST)
             return null;
@@ -187,7 +194,10 @@ export function decodeMemberEpochRequest(event, opts) {
             if (!evaluateAccess(opts.policy, verdict.participant, proof, opts.now, roomId).admitted)
                 return null;
         }
-        return { device: verdict.device, participant: verdict.participant, request: event.id, have: body.have };
+        return {
+            request: { device: verdict.device, participant: verdict.participant, request: event.id, have: body.have },
+            credential: body.credential,
+        };
     }
     catch {
         return null;
@@ -239,7 +249,7 @@ export function encodeMemberEpochGrant(opts) {
             ['d', roomId],
             ['p', device],
         ], opts.expiresAt),
-        content: nip44.v2.encrypt(JSON.stringify(body), nip44.v2.utils.getConversationKey(signerSk, device)),
+        content: sealTo(JSON.stringify(body), signerSk, device, opts.credential),
     }, signerSk);
 }
 /**
@@ -262,7 +272,7 @@ export function decodeMemberEpochGrant(event, opts) {
         const addressed = event.tags.find((t) => t[0] === 'p')?.[1];
         if (addressed === undefined || !hexEquals(addressed, device))
             return null;
-        const body = JSON.parse(nip44.v2.decrypt(event.content, nip44.v2.utils.getConversationKey(opts.deviceSk, event.pubkey)));
+        const body = JSON.parse(openSealed(event.content, event.pubkey, opts.deviceSk, opts.sealSks));
         if (body.v !== 1 || typeof body.request !== 'string' || !HEX64.test(body.request))
             return null;
         if (![...opts.requests].some((r) => hexEquals(r, body.request)))
@@ -404,7 +414,7 @@ export function hostMemberEpochDesk(opts) {
             return false;
         return removed.size === 0 || opts.known?.(request.participant) === true;
     };
-    const answer = (request) => {
+    const answer = (request, presented) => {
         if (closed)
             return;
         if (grantSeen.has(request.device) && !stoodDown.has(request.device)) {
@@ -432,6 +442,7 @@ export function hostMemberEpochDesk(opts) {
                 request: request.request,
                 epochs: chain.epochs,
                 rekeys: chain.rekeys,
+                credential: sealCredential(request, presented, opts.credentialFor, roomId, now()),
                 now: now(),
                 expiresAt: opts.expiresAt,
             });
@@ -458,9 +469,10 @@ export function hostMemberEpochDesk(opts) {
     const unsubRequests = opts.transport.subscribe([{ kinds: [MEMBER_EPOCH_KINDS.REQUEST], '#d': [roomId] }], (event) => {
         if (closed || hexEquals(event.pubkey, self))
             return;
-        const request = decodeMemberEpochRequest(event, { roomId, authority, roomKey: opts.roomKey, now: now(), policy: opts.policy });
-        if (!request || answered.has(request.request))
+        const read = readMemberEpochRequest(event, { roomId, authority, roomKey: opts.roomKey, now: now(), policy: opts.policy });
+        if (!read || answered.has(read.request.request))
             return;
+        const { request, credential } = read;
         if (opts.closed?.()) {
             answered.add(request.request);
             bound(answered);
@@ -493,12 +505,12 @@ export function hostMemberEpochDesk(opts) {
         grantSeen.delete(request.device);
         const delay = jitterMs === 0 ? 0 : Math.floor(random() * jitterMs);
         if (delay === 0) {
-            answer(request);
+            answer(request, credential);
             return;
         }
         const timer = setTimeout(() => {
             timers.delete(timer);
-            answer(request);
+            answer(request, credential);
         }, delay);
         timer.unref?.();
         timers.add(timer);
@@ -589,6 +601,7 @@ export function memberEpochSource(opts) {
                     roomId,
                     authority,
                     deviceSk: opts.deviceSk,
+                    sealSks: opts.sealSks?.(),
                     requests,
                     current: current(),
                     participant,

package/dist/seal.d.ts

@@ -0,0 +1,77 @@
+import type { DeviceCredential } from './types.js';
+/**
+ * Seal keys: how a device heals after its key is copied.
+ *
+ * A device key signs, and until now every rekey copy and every epoch grant
+ * was also sealed to it. Whoever copied it opened every one after, until
+ * somebody noticed and removed the device. Rotating a receiving key signed
+ * by the device key would heal nothing: the thief holds that key and signs
+ * their own rotation.
+ *
+ * So the receiving key rides in the device credential (kind 20460), which
+ * the participant signs. A device mints a fresh seal key at every renewal,
+ * and its participant's signer, not the device, binds it. Rekeys and grants
+ * are sealed to the seal key of the newest credential the sender holds for
+ * the device. A thief who copied the device once holds the seal keys minted
+ * up to then, and none minted after: once the copied credential has lapsed
+ * and the room has rekeyed, they are out.
+ *
+ * A device keeps its seal secrets as it keeps its device key, to open what
+ * was sealed to them when it reads the room again. Healing needs only that
+ * each new one is fresh; retiring old ones is a question of forward
+ * secrecy, not of healing.
+ *
+ * A credential with no `seal` tag is sealed to as before, to the device
+ * key, so a client that knows nothing of this keeps working, unhealed. See
+ * docs/seal-key.md.
+ */
+/** The credential tag that names a device's seal key. */
+export declare const SEAL_TAG = "seal";
+/** True for an x-only secp256k1 public key: 32-byte hex that lifts to a
+ *  point on the curve, so NIP-44 can agree a key with it. */
+export declare function isSealPubkey(value: unknown): value is string;
+export interface SealKey {
+    secretKey: Uint8Array;
+    /** x-only, lower-case hex: what `createDeviceCredential({ seal })` takes. */
+    pubkey: string;
+}
+/** A fresh seal key, for the next credential this device asks for. */
+export declare function generateSealKey(): SealKey;
+/**
+ * The seal key a credential names. Undefined when it names none, and null
+ * when its `seal` tags are unusable: more than one, or one that is not a
+ * point on the curve. Only the participant could have signed either, so
+ * nothing here is an attack, but a sender must not throw on it mid-rekey:
+ * it treats null as none.
+ */
+export declare function credentialSeal(credential: DeviceCredential): string | undefined | null;
+/**
+ * Where to seal something for `device`: the seal key `credential` names, or
+ * the device key when it names none, or is not this device's.
+ *
+ * Expiry is deliberately not checked. A device that has gone quiet for
+ * longer than its credential kept that seal key, and opens the copy when it
+ * is back. Falling back to the device key instead would hand that copy to
+ * anybody holding a stolen device key, which is the one person healing
+ * exists to shut out.
+ */
+export declare function sealTarget(device: string, credential?: DeviceCredential): string;
+/** Seal `plaintext` from `senderSk` to `device`, by `sealTarget`. */
+export declare function sealTo(plaintext: string, senderSk: Uint8Array, device: string, credential?: DeviceCredential): string;
+/**
+ * Open something sealed to this device by `sender`: under each seal key in
+ * turn, then under the device key. Throws when none of them opens it.
+ * NIP-44's MAC verifies under the right key only, so a wrong one fails
+ * rather than producing garbage.
+ */
+export declare function openSealed(ciphertext: string, sender: string, deviceSk: Uint8Array, sealSks?: readonly Uint8Array[]): string;
+/**
+ * The newer of two credentials: the later expiry, then the later
+ * `created_at`. Expiry first because some remote signers restamp
+ * `created_at` with their own clock (kithmoot#205), while the expiry is the
+ * device's own request, inside the signature either way. Ties keep `a`.
+ *
+ * Neither is checked here; compare only credentials already verified for
+ * the same device.
+ */
+export declare function newerCredential(a: DeviceCredential, b: DeviceCredential): DeviceCredential;