mindoodb 0.0.94 → 0.0.95

package/dist/core/userkeys/UserKeyManager.js

@@ -8,6 +8,9 @@ const rsaOaep3072_1 = require("../crypto/rsaOaep3072");
 const types_1 = require("../types");
 const fingerprint_1 = require("./fingerprint");
 const resolveUserKeyDocument_1 = require("./resolveUserKeyDocument");
+const generationSignature_1 = require("./generationSignature");
+const fingerprint_2 = require("./fingerprint");
+const deviceCertificate_1 = require("./deviceCertificate");
 const validateUserKeyDocument_1 = require("./validateUserKeyDocument");
 const UserKeyDocument_1 = require("./UserKeyDocument");
 const types_2 = require("./types");
@@ -22,6 +25,9 @@ class UserKeyManager {
         this.seededBytesVerifiedForPublicKey = null;
         this.resolvingOwnDeviceWrap = false;
         this.reconcileInFlight = null;
+        this.decryptedSelfGrantBytes = null;
+        this.seededSelfGrantBytes = null;
+        this.resolvingSelfGrantWrap = false;
     }
     noteUserDirectoryFetched() {
         this.userDirectoryFetched = true;
@@ -76,6 +82,15 @@ class UserKeyManager {
         this.seededBytesVerifiedForPublicKey = publicKeyPem;
         return matches;
     }
+    /**
+     * Inject the device self-grant private key (PKCS8) the host decrypted from
+     * the identity (Haven unlock), for sessions opened with an empty password.
+     * Used only when it belongs to `PrivateUserId.deviceSelfGrantKeyPair`.
+     */
+    seedDecryptedSelfGrantKeyBytes(bytes) {
+        this.seededSelfGrantBytes = bytes.slice();
+        this.decryptedSelfGrantBytes = null;
+    }
     hasFetchedUserDirectory() {
         return this.userDirectoryFetched;
     }
@@ -125,8 +140,471 @@ class UserKeyManager {
         this.decryptedUserKeyCache = null;
         this.seededBytesMatchLocalPublic = true;
         this.seededBytesVerifiedForPublicKey = pair.publicKey;
+        if (!user.deviceSelfGrantKeyPair) {
+            await this.generateLocalSelfGrantKey(user, password);
+        }
         return pair;
     }
+    // ==================== Device certificates (docs/userkeys.md §9.6) ====================
+    /**
+     * Vouch for another device of this person (docs/userkeys.md §9.6): write a
+     * `dcert_<fingerprint>` certificate signed with the person's self-grant key
+     * and wrap the User-Key (and self-grant key) to the device, so it can sync,
+     * write and read without the admin. Requires the admin to have granted
+     * device self-grant with the key this device holds.
+     */
+    async issueDeviceCertificate(device, label) {
+        const granted = await this.grantedSelfGrantKey();
+        if (!granted) {
+            throw new Error("Cannot certify a device: the administrator has not granted device self-grant to this person.");
+        }
+        const signer = await this.selfGrantSigner();
+        if (!signer || (0, fingerprint_2.normalizePublicKeyPem)(signer.publicKeyPem) !== (0, fingerprint_2.normalizePublicKeyPem)(granted)) {
+            throw new Error("Cannot certify a device: this device does not hold the self-grant key named in the grant.");
+        }
+        const resolved = await this.resolveOwnUserKeyDocument();
+        const usernameHash = resolved?.payload.username_hash ??
+            (await this.mintBindingForUsername((await this.tenant.getCurrentUserId()).username))?.usernameHash;
+        if (!usernameHash)
+            throw new Error("Cannot certify a device: no grant for this person");
+        const crypto = this.tenant.getCryptoAdapter();
+        const me = await this.tenant.getCurrentUserId();
+        const trimmedLabel = label?.trim();
+        const certificate = await (0, deviceCertificate_1.signDeviceCertificate)(crypto, signer.privateKey, {
+            username_hash: usernameHash,
+            deviceSigningPublicKey: device.signingPublicKey,
+            deviceEncryptionPublicKey: device.encryptionPublicKey,
+            ...(trimmedLabel ? { label: trimmedLabel } : {}),
+            issuedAt: Date.now(),
+            issuedBySigningPublicKey: me.userSigningPublicKey,
+            selfGrantPublicKey: signer.publicKeyPem,
+        });
+        const fingerprint = await (0, fingerprint_2.fingerprintPublicKeyPem)(device.signingPublicKey, crypto.getSubtle());
+        const db = await this.openUserDirectory();
+        const create = {
+            decryptionKeyId: types_1.PUBLIC_INFOS_KEY_ID,
+            initialValues: certificate,
+        };
+        let doc;
+        try {
+            doc = await db.createDocument({
+                ...create,
+                id: (0, deviceCertificate_1.deviceCertificateDocId)(fingerprint),
+                // The certificate must be in the doc_create itself: readers take it
+                // from there only (see deviceCertificate.ts).
+                assumeUniqueId: true,
+            });
+        }
+        catch {
+            // Id taken (an earlier, withdrawn certificate): any `dcert_` id works.
+            doc = await db.createDocument({ ...create, idPrefix: "dcert" });
+        }
+        if (resolved) {
+            await this.wrapUserKeyForGrantDevice(device.encryptionPublicKey, trimmedLabel);
+        }
+        return { docId: doc.getId(), certificate };
+    }
+    /** This person's device certificates in the local `userdirectory` replica. */
+    async listOwnDeviceCertificates() {
+        const resolved = await this.resolveOwnUserKeyDocument();
+        if (!resolved)
+            return [];
+        const db = await this.openUserDirectory();
+        const crypto = this.tenant.getCryptoAdapter();
+        const result = [];
+        for (const id of await db.getAllDocumentIds()) {
+            if (!id.startsWith(deviceCertificate_1.DEVICE_CERT_DOC_ID_PREFIX))
+                continue;
+            try {
+                const doc = await db.getDocument(id);
+                if (doc.isDeleted())
+                    continue;
+                const cert = (0, deviceCertificate_1.asDeviceCertificate)(doc.getData());
+                if (!cert || cert.username_hash !== resolved.payload.username_hash)
+                    continue;
+                result.push({
+                    docId: id,
+                    fingerprint: await (0, fingerprint_2.fingerprintPublicKeyPem)(cert.deviceSigningPublicKey, crypto.getSubtle()),
+                    certificate: cert,
+                });
+            }
+            catch {
+                // unreadable
+            }
+        }
+        return result;
+    }
+    /**
+     * Withdraw a certificate this person issued (a device they sold or retired):
+     * delete its document, so the device stops counting from the delete's
+     * trusted time. `fingerprint` is the device's signing-key fingerprint or the
+     * document id. Any device of the person can do this, so against a stolen
+     * device the admin revokes the key on the grant instead.
+     */
+    async revokeOwnDeviceCertificate(fingerprint) {
+        const certs = await this.listOwnDeviceCertificates();
+        const db = await this.openUserDirectory();
+        let removed = 0;
+        for (const entry of certs) {
+            if (entry.fingerprint !== fingerprint && entry.docId !== fingerprint)
+                continue;
+            await db.deleteDocument(entry.docId);
+            removed += 1;
+        }
+        if (removed === 0) {
+            throw new Error(`No device certificate of this person matches "${fingerprint}"`);
+        }
+        return removed;
+    }
+    /**
+     * Grant devices plus devices this person certified, for wrapping the
+     * User-Key and the self-grant key (rotation, self-grant distribution).
+     */
+    async devicesForWrapping(username) {
+        const directory = await this.directory();
+        const overview = await directory.getUserGrantOverview(username);
+        const devices = [
+            ...overview.activeDevices,
+        ];
+        const hashes = new Set();
+        for (const grant of await directory.findGrantAccessDocuments(username)) {
+            const hash = grant.getData().username_hash;
+            if (typeof hash === "string")
+                hashes.add(hash);
+        }
+        for (const hash of hashes) {
+            for (const cert of await directory.listCertifiedDevices(hash)) {
+                if (devices.some((d) => (0, fingerprint_2.normalizePublicKeyPem)(d.signingPublicKey) === (0, fingerprint_2.normalizePublicKeyPem)(cert.deviceSigningPublicKey))) {
+                    continue;
+                }
+                devices.push({
+                    signingPublicKey: cert.deviceSigningPublicKey,
+                    encryptionPublicKey: cert.deviceEncryptionPublicKey,
+                    ...(cert.label ? { label: cert.label } : {}),
+                });
+            }
+        }
+        return devices;
+    }
+    // ==================== Device self-grant key (docs/userkeys.md §9) ====================
+    async generateLocalSelfGrantKey(user, password) {
+        const crypto = this.tenant.getCryptoAdapter();
+        const generated = await (0, generationSignature_1.generateSelfGrantKeyPair)(crypto);
+        user.deviceSelfGrantKeyPair = {
+            publicKey: generated.publicKeyPem,
+            privateKey: await (0, privateKeyEncryption_1.encryptPrivateKey)(crypto, generated.privateKeyBytes, password, types_2.DEVICE_SELF_GRANT_PRIVATE_SALT),
+        };
+        this.decryptedSelfGrantBytes = generated.privateKeyBytes;
+    }
+    /**
+     * Public half of this person's device self-grant key, as held by this
+     * device (docs/userkeys.md §9). The admin names it in the grant with
+     * `directory.setDeviceSelfGrant`. `null` while this device holds none.
+     */
+    async getDeviceSelfGrantPublicKey() {
+        const bytes = await this.getSelfGrantPrivateKeyBytes();
+        if (!bytes)
+            return null;
+        return this.tenant.getCurrentPrivateUser().deviceSelfGrantKeyPair?.publicKey ?? null;
+    }
+    /**
+     * The self-grant private key (PKCS8): from memory, the password-encrypted
+     * copy on the identity, or this device's wrap in the own User-Key document.
+     * When the admin named a key in the grant, a held key that differs is not
+     * returned as long as a wrap of the granted key exists.
+     */
+    async getSelfGrantPrivateKeyBytes() {
+        if (this.decryptedSelfGrantBytes)
+            return this.decryptedSelfGrantBytes;
+        const user = this.tenant.getCurrentPrivateUser();
+        const pair = user.deviceSelfGrantKeyPair;
+        const password = this.tenant.getCurrentUserPassword();
+        // A device that made its own key before joining holds one nobody else
+        // knows; the person's key (the one in the grant) comes from a wrap.
+        const granted = await this.grantedSelfGrantKey();
+        if (granted && pair && (0, fingerprint_2.normalizePublicKeyPem)(pair.publicKey) !== (0, fingerprint_2.normalizePublicKeyPem)(granted)) {
+            const fromWrap = await this.importSelfGrantKeyFromWrap();
+            if (fromWrap)
+                return fromWrap;
+        }
+        if (pair && this.seededSelfGrantBytes) {
+            try {
+                const derived = await (0, generationSignature_1.ed25519FromPkcs8)(this.tenant.getCryptoAdapter(), this.seededSelfGrantBytes);
+                if ((0, fingerprint_2.normalizePublicKeyPem)(derived.publicKeyPem) === (0, fingerprint_2.normalizePublicKeyPem)(pair.publicKey)) {
+                    this.decryptedSelfGrantBytes = this.seededSelfGrantBytes;
+                    return this.decryptedSelfGrantBytes;
+                }
+            }
+            catch {
+                // not a usable key; fall through
+            }
+        }
+        if (pair && password) {
+            try {
+                const bytes = new Uint8Array(await this.tenant.decryptPrivateKey(pair.privateKey, password, types_2.DEVICE_SELF_GRANT_PRIVATE_SALT));
+                const derived = await (0, generationSignature_1.ed25519FromPkcs8)(this.tenant.getCryptoAdapter(), bytes);
+                if ((0, fingerprint_2.normalizePublicKeyPem)(derived.publicKeyPem) === (0, fingerprint_2.normalizePublicKeyPem)(pair.publicKey)) {
+                    this.decryptedSelfGrantBytes = bytes;
+                    return bytes;
+                }
+            }
+            catch {
+                // fall through to the wrap
+            }
+        }
+        return this.importSelfGrantKeyFromWrap();
+    }
+    /** Unwrap the self-grant key from this device's wrap and keep it on the identity. */
+    async importSelfGrantKeyFromWrap() {
+        if (this.resolvingSelfGrantWrap)
+            return null;
+        this.resolvingSelfGrantWrap = true;
+        try {
+            if (!this.canReconcileAgainstUserDirectory())
+                return null;
+            const deviceKey = await this.tenant.getEncryptionPrivateKeyForReconcile();
+            if (!deviceKey)
+                return null;
+            const resolved = await this.resolveOwnUserKeyDocument();
+            if (!resolved)
+                return null;
+            const crypto = this.tenant.getCryptoAdapter();
+            const user = this.tenant.getCurrentPrivateUser();
+            const deviceFp = await (0, fingerprint_1.fingerprintEncryptionPublicKey)(user.userEncryptionKeyPair.publicKey, crypto.getSubtle());
+            const granted = await this.grantedSelfGrantKey();
+            let fallback = null;
+            for (const epoch of this.epochsNewestFirst(resolved.payload)) {
+                const wrapped = resolved.payload.userKeys[epoch]?.deviceWraps?.[deviceFp]?.wrappedSelfGrantKey;
+                if (!wrapped)
+                    continue;
+                try {
+                    const bytes = await (0, UserKeyDocument_1.unwrapPrivateKeyFromDevice)({
+                        cryptoAdapter: crypto,
+                        wrappedKeyB64: wrapped,
+                        deviceEncryptionPrivateKey: deviceKey,
+                    });
+                    const { publicKeyPem } = await (0, generationSignature_1.ed25519FromPkcs8)(crypto, bytes);
+                    if (!granted || (0, fingerprint_2.normalizePublicKeyPem)(publicKeyPem) === (0, fingerprint_2.normalizePublicKeyPem)(granted)) {
+                        fallback = { bytes, publicKeyPem };
+                        break;
+                    }
+                    fallback ?? (fallback = { bytes, publicKeyPem });
+                }
+                catch (error) {
+                    console.warn("[userkeys] self-grant key unwrap failed", { epoch }, error);
+                }
+            }
+            if (!fallback)
+                return null;
+            user.deviceSelfGrantKeyPair = {
+                publicKey: fallback.publicKeyPem,
+                privateKey: await (0, privateKeyEncryption_1.encryptPrivateKey)(crypto, fallback.bytes, this.tenant.getCurrentUserPassword(), types_2.DEVICE_SELF_GRANT_PRIVATE_SALT),
+            };
+            this.decryptedSelfGrantBytes = fallback.bytes;
+            return fallback.bytes;
+        }
+        finally {
+            this.resolvingSelfGrantWrap = false;
+        }
+    }
+    /** The self-grant key the admin named in this person's grant, or `null`. */
+    async grantedSelfGrantKey() {
+        try {
+            const directory = await this.directory();
+            const username = (await this.tenant.getCurrentUserId()).username;
+            const grant = await directory.getDeviceSelfGrant(username);
+            return grant && grant.revokedAt === undefined ? grant.signingPublicKey : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Self-grant signer for this device, if it holds the key. */
+    async selfGrantSigner() {
+        const bytes = await this.getSelfGrantPrivateKeyBytes();
+        if (!bytes)
+            return null;
+        try {
+            return await (0, generationSignature_1.ed25519FromPkcs8)(this.tenant.getCryptoAdapter(), bytes);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Wrap the self-grant key to a device, when this device holds it. */
+    async wrapSelfGrantKeyFor(deviceEncryptionPublicKey) {
+        const bytes = await this.getSelfGrantPrivateKeyBytes();
+        if (!bytes)
+            return undefined;
+        return (0, UserKeyDocument_1.wrapPrivateKeyForDevice)({
+            cryptoAdapter: this.tenant.getCryptoAdapter(),
+            privateKeyBytes: bytes,
+            deviceEncryptionPublicKey,
+        });
+    }
+    /**
+     * Signing key and signatures for a generation (docs/userkeys.md §9.3).
+     * `ownBytes` derive the generation's own signing key. Signs with the
+     * previous generation's key when `previous` is given, with the self-grant
+     * key when this device holds it, and with its own key when `selfSign`
+     * (pending adoption; harmless otherwise).
+     */
+    async generationSignatureFields(input) {
+        const crypto = this.tenant.getCryptoAdapter();
+        const own = await (0, generationSignature_1.deriveGenerationSigningKey)(crypto, input.ownBytes);
+        const message = (0, generationSignature_1.userKeyGenerationSigningMessage)(input.usernameHash, input.epoch, {
+            ...input.gen,
+            signingPublicKey: own.publicKeyPem,
+        });
+        const signatures = [];
+        if (input.previous?.gen.signingPublicKey) {
+            const prev = await (0, generationSignature_1.deriveGenerationSigningKey)(crypto, input.previous.bytes);
+            if ((0, fingerprint_2.normalizePublicKeyPem)(prev.publicKeyPem) ===
+                (0, fingerprint_2.normalizePublicKeyPem)(input.previous.gen.signingPublicKey)) {
+                signatures.push({
+                    signerPublicKey: prev.publicKeyPem,
+                    signature: await (0, generationSignature_1.signEd25519)(crypto, prev.privateKey, message),
+                });
+            }
+        }
+        const selfGrant = await this.selfGrantSigner();
+        if (selfGrant) {
+            signatures.push({
+                signerPublicKey: selfGrant.publicKeyPem,
+                signature: await (0, generationSignature_1.signEd25519)(crypto, selfGrant.privateKey, message),
+            });
+        }
+        if (input.selfSign) {
+            signatures.push({
+                signerPublicKey: own.publicKeyPem,
+                signature: await (0, generationSignature_1.signEd25519)(crypto, own.privateKey, message),
+            });
+        }
+        return { signingPublicKey: own.publicKeyPem, signatures };
+    }
+    /** The document's generations that count (docs/userkeys.md §9.3). */
+    async validated(doc) {
+        const raw = (0, validateUserKeyDocument_1.asUserKeyPayload)(doc.getData());
+        if (!raw)
+            return null;
+        return (0, resolveUserKeyDocument_1.applyGenerationValidity)(doc, raw, {
+            db: doc.getDatabase(),
+            directory: await this.directory(),
+        });
+    }
+    /** Effective cutoff for unsigned generations of this person (tenant policy, self-grant). */
+    async generationSignatureCutoff(usernameHash) {
+        const directory = await this.directory();
+        const tenantCutoff = await directory.getRequireUserKeyGenerationSignatureSince();
+        const selfGrant = await directory.getDeviceSelfGrantForUsernameHash(usernameHash);
+        const cutoffs = [tenantCutoff, selfGrant?.grantedAt].filter((t) => typeof t === "number" && Number.isFinite(t));
+        return cutoffs.length > 0 ? Math.min(...cutoffs) : undefined;
+    }
+    /**
+     * Give the current generation its signing key when it has none (or one this
+     * device cannot derive), so the next rotation can be chained to it. Written
+     * only when the change will count: while the person's document is pending,
+     * before the cutoff, or signed by a granted self-grant key.
+     */
+    async ensureCurrentGenerationSigningKey(resolved) {
+        const epoch = (0, types_2.currentUserKeyEpoch)(resolved.payload);
+        if (!epoch)
+            return;
+        const gen = resolved.payload.userKeys[epoch];
+        const bytes = await this.privateKeyBytesForEpoch(resolved.payload, epoch);
+        if (!gen || !bytes)
+            return;
+        const crypto = this.tenant.getCryptoAdapter();
+        const derived = await (0, generationSignature_1.deriveGenerationSigningKey)(crypto, bytes);
+        if (gen.signingPublicKey &&
+            (0, fingerprint_2.normalizePublicKeyPem)(gen.signingPublicKey) === (0, fingerprint_2.normalizePublicKeyPem)(derived.publicKeyPem)) {
+            return;
+        }
+        const usernameHash = resolved.payload.username_hash;
+        const pending = (0, types_2.isPendingUserKeyDocument)(resolved.rawPayload);
+        const cutoff = await this.generationSignatureCutoff(usernameHash);
+        const granted = await this.grantedSelfGrantKey();
+        const selfGrant = granted ? await this.selfGrantSigner() : null;
+        const holdsGranted = !!selfGrant && (0, fingerprint_2.normalizePublicKeyPem)(selfGrant.publicKeyPem) === (0, fingerprint_2.normalizePublicKeyPem)(granted);
+        const lowest = this.epochsNewestFirst(resolved.payload).reverse()[0] === epoch;
+        const counts = (pending && lowest) || cutoff === undefined || Date.now() < cutoff || holdsGranted;
+        if (!counts)
+            return;
+        const fields = await this.generationSignatureFields({
+            usernameHash,
+            epoch,
+            gen,
+            ownBytes: bytes,
+            selfSign: pending && lowest,
+        });
+        const live = (0, validateUserKeyDocument_1.asUserKeyPayload)(resolved.doc.getData()) ?? resolved.rawPayload;
+        await (0, UserKeyDocument_1.replaceUserKeys)(resolved.doc.getDatabase(), resolved.doc, {
+            ...live.userKeys,
+            [epoch]: { ...(live.userKeys[epoch] ?? gen), ...fields },
+        });
+    }
+    /**
+     * Make sure this person has a self-grant key and every approved device of
+     * the current generation holds it (docs/userkeys.md §9). The first updated
+     * device that holds the User-Key and finds no wrapped self-grant key creates
+     * one; every device wraps the key it holds to devices that lack it.
+     */
+    async ensureSelfGrantKeyDistributed(resolved) {
+        const epoch = (0, types_2.currentUserKeyEpoch)(resolved.payload);
+        if (!epoch)
+            return;
+        const gen = resolved.payload.userKeys[epoch];
+        if (!gen)
+            return;
+        const userKeyBytes = await this.privateKeyBytesForEpoch(resolved.payload, epoch);
+        if (!userKeyBytes)
+            return;
+        let bytes = await this.getSelfGrantPrivateKeyBytes();
+        const anyWrapped = Object.values(gen.deviceWraps ?? {}).some((w) => !!w.wrappedSelfGrantKey);
+        const user = this.tenant.getCurrentPrivateUser();
+        // Generate only for an identity that has none: one this session merely
+        // cannot open (host without seed, empty password) must not be replaced.
+        if (!bytes && !anyWrapped && !user.deviceSelfGrantKeyPair) {
+            await this.generateLocalSelfGrantKey(user, this.tenant.getCurrentUserPassword());
+            bytes = this.decryptedSelfGrantBytes;
+        }
+        if (!bytes)
+            return;
+        const username = (await this.tenant.getCurrentUserId()).username;
+        const devices = await this.devicesForWrapping(username);
+        const crypto = this.tenant.getCryptoAdapter();
+        const db = resolved.doc.getDatabase();
+        for (const device of devices) {
+            const fp = await (0, fingerprint_1.fingerprintEncryptionPublicKey)(device.encryptionPublicKey, crypto.getSubtle());
+            const wrap = gen.deviceWraps?.[fp];
+            if (!wrap?.wrappedKey || wrap.wrappedSelfGrantKey)
+                continue;
+            await (0, UserKeyDocument_1.writeDeviceWrap)({
+                db,
+                doc: resolved.doc,
+                epoch,
+                deviceFingerprint: fp,
+                wrap: { ...wrap, wrappedSelfGrantKey: await this.wrapSelfGrantKeyFor(device.encryptionPublicKey) },
+            });
+        }
+        // Wraps written by other devices may not be in the grant overview yet
+        // (directory not pulled). This device's own wrap is covered either way.
+        const ownFp = await (0, fingerprint_1.fingerprintEncryptionPublicKey)(user.userEncryptionKeyPair.publicKey, crypto.getSubtle());
+        const live = (0, validateUserKeyDocument_1.asUserKeyPayload)(resolved.doc.getData());
+        const ownWrap = live?.userKeys[epoch]?.deviceWraps?.[ownFp];
+        if (ownWrap?.wrappedKey && !ownWrap.wrappedSelfGrantKey) {
+            await (0, UserKeyDocument_1.writeDeviceWrap)({
+                db,
+                doc: resolved.doc,
+                epoch,
+                deviceFingerprint: ownFp,
+                wrap: {
+                    ...ownWrap,
+                    wrappedSelfGrantKey: await this.wrapSelfGrantKeyFor(user.userEncryptionKeyPair.publicKey),
+                },
+            });
+        }
+    }
     async getLocalUserPublicKey() {
         const user = this.tenant.getCurrentPrivateUser();
         if (user.userKeyPair?.publicKey)
@@ -374,6 +852,17 @@ class UserKeyManager {
             return null;
         const { grantDocId, usernameHash, usernameHashVersion } = binding;
         const fingerprint = await (0, UserKeyDocument_1.fingerprintUserPublicKey)(pair.publicKey, this.tenant.getCryptoAdapter());
+        const mintBytes = await this.getDecryptedUserKeyBytes();
+        const createdAt = Date.now();
+        const signed = mintBytes
+            ? await this.generationSignatureFields({
+                usernameHash,
+                epoch: "1",
+                gen: { publicKey: pair.publicKey, fingerprint, createdAt },
+                ownBytes: mintBytes,
+                selfSign: true,
+            })
+            : undefined;
         const db = await this.openUserDirectory();
         let doc;
         let mintedHere = false;
@@ -394,7 +883,8 @@ class UserKeyManager {
                     usernameHashVersion,
                     publicKey: pair.publicKey,
                     fingerprint,
-                    createdAt: Date.now(),
+                    createdAt,
+                    ...signed,
                 });
                 doc = await db.createDocument({
                     idPrefix: "userkey",
@@ -410,6 +900,8 @@ class UserKeyManager {
                     usernameHashVersion,
                     publicKey: pair.publicKey,
                     fingerprint,
+                    createdAt,
+                    ...signed,
                 });
             }
             mintedHere = true;
@@ -451,10 +943,12 @@ class UserKeyManager {
         }
         const live = (0, validateUserKeyDocument_1.asUserKeyPayload)(doc.getData()) ?? payload;
         const localPublic = await this.getLocalUserPublicKey();
-        const epoch = (0, types_2.currentUserKeyEpoch)(live);
+        // "Current" only among generations that count (§9.3); write into `live`.
+        const valid = (await this.validated(doc))?.payload ?? payload;
+        const epoch = (0, types_2.currentUserKeyEpoch)(valid);
         if (!epoch || !localPublic)
             return;
-        const gen = live.userKeys[epoch];
+        const gen = live.userKeys[epoch] ?? valid.userKeys[epoch];
         if (!gen || gen.publicKey !== localPublic)
             return;
         const directory = await this.directory();
@@ -488,16 +982,13 @@ class UserKeyManager {
                 }
                 continue;
             }
-            deviceWraps[deviceFp] = {
-                wrappedKey: await (0, UserKeyDocument_1.wrapPrivateKeyForDevice)({
-                    cryptoAdapter: this.tenant.getCryptoAdapter(),
-                    privateKeyBytes: bytes,
-                    deviceEncryptionPublicKey: device.encryptionPublicKey,
-                }),
-                ...(device.label ? { label: device.label } : {}),
+            deviceWraps[deviceFp] = await this.buildDeviceWrap({
+                userKeyBytes: bytes,
+                deviceEncryptionPublicKey: device.encryptionPublicKey,
+                label: device.label,
                 approvedAt: now,
                 approvedBySigningPublicKey: signer.userSigningPublicKey,
-            };
+            });
             changed = true;
         }
         if (!changed)
@@ -507,6 +998,21 @@ class UserKeyManager {
             [epoch]: { ...gen, deviceWraps },
         });
     }
+    /** A device wrap of the User-Key, plus the self-grant key when this device holds it. */
+    async buildDeviceWrap(input) {
+        const wrappedSelfGrantKey = await this.wrapSelfGrantKeyFor(input.deviceEncryptionPublicKey);
+        return {
+            wrappedKey: await (0, UserKeyDocument_1.wrapPrivateKeyForDevice)({
+                cryptoAdapter: this.tenant.getCryptoAdapter(),
+                privateKeyBytes: input.userKeyBytes,
+                deviceEncryptionPublicKey: input.deviceEncryptionPublicKey,
+            }),
+            ...(input.label ? { label: input.label } : {}),
+            approvedAt: input.approvedAt,
+            approvedBySigningPublicKey: input.approvedBySigningPublicKey,
+            ...(wrappedSelfGrantKey ? { wrappedSelfGrantKey } : {}),
+        };
+    }
     async tryImportUserKeyFromWrap(payload) {
         const user = this.tenant.getCurrentPrivateUser();
         const deviceKey = await this.tenant.getEncryptionPrivateKeyForReconcile();
@@ -533,6 +1039,12 @@ class UserKeyManager {
                 this.decryptedUserKeyCache = null;
                 this.seededBytesMatchLocalPublic = true;
                 this.seededBytesVerifiedForPublicKey = gen.publicKey;
+                // The person's self-grant key travels with their User-Key and
+                // replaces one this device may have made for itself before joining.
+                if (wrap.wrappedSelfGrantKey) {
+                    this.decryptedSelfGrantBytes = null;
+                    await this.importSelfGrantKeyFromWrap().catch(() => null);
+                }
                 return true;
             }
             catch {
@@ -546,7 +1058,7 @@ class UserKeyManager {
         if (!localPublic) {
             throw new types_2.UserKeyMismatchError("This device has no local User-Key to compare against the published document");
         }
-        const live = (0, validateUserKeyDocument_1.asUserKeyPayload)(doc.getData()) ?? payload;
+        const live = (await this.validated(doc))?.payload ?? (0, validateUserKeyDocument_1.asUserKeyPayload)(doc.getData()) ?? payload;
         const currentEpoch = (0, types_2.currentUserKeyEpoch)(live);
         if (!currentEpoch) {
             throw new types_2.UserKeyMismatchError("Published user-key document has no generations");
@@ -580,22 +1092,18 @@ class UserKeyManager {
             if (!bytes) {
                 throw new types_2.UserKeyMismatchError("Local User-Key private material is unavailable");
             }
-            const wrapped = await (0, UserKeyDocument_1.wrapPrivateKeyForDevice)({
-                cryptoAdapter: this.tenant.getCryptoAdapter(),
-                privateKeyBytes: bytes,
-                deviceEncryptionPublicKey: user.userEncryptionKeyPair.publicKey,
-            });
             await (0, UserKeyDocument_1.writeDeviceWrap)({
                 db,
                 doc,
                 epoch,
                 deviceFingerprint: deviceFp,
-                wrap: {
-                    wrappedKey: wrapped,
-                    ...(ownLabel ? { label: ownLabel } : {}),
+                wrap: await this.buildDeviceWrap({
+                    userKeyBytes: bytes,
+                    deviceEncryptionPublicKey: user.userEncryptionKeyPair.publicKey,
+                    label: ownLabel,
                     approvedAt: Date.now(),
                     approvedBySigningPublicKey: signer.userSigningPublicKey,
-                },
+                }),
             });
         }
     }
@@ -610,13 +1118,27 @@ class UserKeyManager {
         const epoch = (0, types_2.currentUserKeyEpoch)(payload) ?? "1";
         const gen = payload.userKeys[epoch];
         const fingerprint = await (0, UserKeyDocument_1.fingerprintUserPublicKey)(pair.publicKey, this.tenant.getCryptoAdapter());
+        const createdAt = gen?.createdAt ?? Date.now();
+        const bytes = await this.getDecryptedUserKeyBytes();
+        // Adopting a pending document counts only self-signed (§9.3, rule 3).
+        const signed = bytes
+            ? await this.generationSignatureFields({
+                usernameHash: payload.username_hash,
+                epoch,
+                gen: { publicKey: pair.publicKey, fingerprint, createdAt },
+                ownBytes: bytes,
+                selfSign: true,
+            })
+            : {};
+        const raw = (0, validateUserKeyDocument_1.asUserKeyPayload)(doc.getData()) ?? payload;
         await (0, UserKeyDocument_1.replaceUserKeys)(doc.getDatabase(), doc, {
-            ...payload.userKeys,
+            ...raw.userKeys,
             [epoch]: {
                 publicKey: pair.publicKey,
                 fingerprint,
-                createdAt: gen?.createdAt ?? Date.now(),
+                createdAt,
                 deviceWraps: {},
+                ...signed,
             },
         });
         const db = await this.openUserDirectory();
@@ -649,6 +1171,11 @@ class UserKeyManager {
         const canUsePlantedKey = Boolean(localPublic && published && localPublic === published && bytes);
         try {
             if (canUsePlantedKey) {
+                // While still pending, give generation 1 its signing key first, so the
+                // self-signed change counts as an adoption (§9.3, rule 3).
+                const current = await this.validated(doc);
+                if (current)
+                    await this.ensureCurrentGenerationSigningKey(current);
                 await this.writeOwnDeviceWrap(doc, payload);
                 await this.wrapPrivateKeyForActiveGrantDevices(doc, payload, {
                     legacyUnstampedOnly: true,
@@ -766,6 +1293,18 @@ class UserKeyManager {
                 }
             }
             await this.dropRevokedDeviceWraps(resolved.doc, resolved.payload);
+            try {
+                const latest = (await this.resolveOwnUserKeyDocument()) ?? (await this.validated(resolved.doc));
+                if (latest) {
+                    await this.ensureCurrentGenerationSigningKey(latest);
+                    const afterSign = (await this.resolveOwnUserKeyDocument()) ?? latest;
+                    await this.ensureSelfGrantKeyDistributed(afterSign);
+                    resolved = (await this.resolveOwnUserKeyDocument()) ?? afterSign;
+                }
+            }
+            catch (error) {
+                console.warn("[userkeys] generation signing key / self-grant key upkeep failed", error);
+            }
             return this.enrollmentStatus(resolved.payload, this.waitState());
         }
         catch (error) {
@@ -871,22 +1410,18 @@ class UserKeyManager {
             });
             if (!bytes)
                 continue;
-            const wrapped = await (0, UserKeyDocument_1.wrapPrivateKeyForDevice)({
-                cryptoAdapter: this.tenant.getCryptoAdapter(),
-                privateKeyBytes: bytes,
-                deviceEncryptionPublicKey: encryptionPublicKey,
-            });
             await (0, UserKeyDocument_1.writeDeviceWrap)({
                 db,
                 doc: resolved.doc,
                 epoch,
                 deviceFingerprint: fingerprint,
-                wrap: {
-                    wrappedKey: wrapped,
-                    ...(label ? { label } : {}),
+                wrap: await this.buildDeviceWrap({
+                    userKeyBytes: bytes,
+                    deviceEncryptionPublicKey: encryptionPublicKey,
+                    label,
                     approvedAt: Date.now(),
                     approvedBySigningPublicKey: signer.userSigningPublicKey,
-                },
+                }),
             });
             wroteWrap = true;
         }
@@ -916,22 +1451,18 @@ class UserKeyManager {
             const bytes = await this.privateKeyBytesForEpoch(resolved.payload, epoch);
             if (!bytes)
                 continue;
-            const wrapped = await (0, UserKeyDocument_1.wrapPrivateKeyForDevice)({
-                cryptoAdapter: this.tenant.getCryptoAdapter(),
-                privateKeyBytes: bytes,
-                deviceEncryptionPublicKey: match.encryptionPublicKey,
-            });
             await (0, UserKeyDocument_1.writeDeviceWrap)({
                 db,
                 doc: resolved.doc,
                 epoch,
                 deviceFingerprint: fingerprint,
-                wrap: {
-                    wrappedKey: wrapped,
-                    ...(match.label ? { label: match.label } : {}),
+                wrap: await this.buildDeviceWrap({
+                    userKeyBytes: bytes,
+                    deviceEncryptionPublicKey: match.encryptionPublicKey,
+                    label: match.label,
                     approvedAt: Date.now(),
                     approvedBySigningPublicKey: signer.userSigningPublicKey,
-                },
+                }),
             });
             wroteWrap = true;
         }
@@ -977,10 +1508,13 @@ class UserKeyManager {
         if (!current) {
             throw new Error("Cannot rotate: user-key document has no generations");
         }
-        const nextEpoch = (BigInt(current) + 1n).toString();
-        if (resolved.payload.userKeys[nextEpoch]) {
-            throw new Error(`Cannot rotate: epoch ${nextEpoch} already exists`);
-        }
+        // Above every stored epoch, including ones that do not count (§9.3).
+        const highestStored = Object.keys(resolved.rawPayload.userKeys ?? {})
+            .filter((e) => /^\d+$/.test(e))
+            .reduce((max, e) => (BigInt(e) > max ? BigInt(e) : max), BigInt(current));
+        const nextEpoch = (highestStored + 1n).toString();
+        const previousGen = resolved.payload.userKeys[current];
+        const previousBytes = await this.privateKeyBytesForEpoch(resolved.payload, current);
         const user = this.tenant.getCurrentPrivateUser();
         const generated = await (0, rsaOaep3072_1.generateRsaOaep3072)(this.tenant.getCryptoAdapter());
         const encrypted = await (0, privateKeyEncryption_1.encryptPrivateKey)(this.tenant.getCryptoAdapter(), generated.privateKeyBytes, this.tenant.getCurrentUserPassword(), types_2.USERKEY_PRIVATE_SALT);
@@ -993,33 +1527,44 @@ class UserKeyManager {
         const fingerprint = await (0, UserKeyDocument_1.fingerprintUserPublicKey)(generated.publicKeyPem, this.tenant.getCryptoAdapter());
         const signer = await this.tenant.getCurrentUserId();
         const now = Date.now();
-        const directory = await this.directory();
-        const overview = await directory.getUserGrantOverview(signer.username);
+        const signed = await this.generationSignatureFields({
+            usernameHash: resolved.payload.username_hash,
+            epoch: nextEpoch,
+            gen: { publicKey: generated.publicKeyPem, fingerprint, createdAt: now },
+            ownBytes: generated.privateKeyBytes,
+            previous: previousGen && previousBytes ? { gen: previousGen, bytes: previousBytes } : null,
+        });
+        if (signed.signatures.length === 0) {
+            const cutoff = await this.generationSignatureCutoff(resolved.payload.username_hash);
+            if (cutoff !== undefined && now >= cutoff) {
+                throw new Error("Cannot rotate: this device can sign the new User-Key generation neither with the previous generation nor with a granted device self-grant key, so it would not count.");
+            }
+        }
+        const devices = await this.devicesForWrapping(signer.username);
         const previousWraps = resolved.payload.userKeys[current]?.deviceWraps ?? {};
         const deviceWraps = {};
-        for (const device of overview.activeDevices) {
+        for (const device of devices) {
             const deviceFp = await (0, fingerprint_1.fingerprintEncryptionPublicKey)(device.encryptionPublicKey, this.tenant.getCryptoAdapter().getSubtle());
             if (!previousWraps[deviceFp])
                 continue;
-            deviceWraps[deviceFp] = {
-                wrappedKey: await (0, UserKeyDocument_1.wrapPrivateKeyForDevice)({
-                    cryptoAdapter: this.tenant.getCryptoAdapter(),
-                    privateKeyBytes: generated.privateKeyBytes,
-                    deviceEncryptionPublicKey: device.encryptionPublicKey,
-                }),
-                ...(device.label ? { label: device.label } : {}),
+            deviceWraps[deviceFp] = await this.buildDeviceWrap({
+                userKeyBytes: generated.privateKeyBytes,
+                deviceEncryptionPublicKey: device.encryptionPublicKey,
+                label: device.label,
                 approvedAt: now,
                 approvedBySigningPublicKey: signer.userSigningPublicKey,
-            };
+            });
         }
+        const raw = (0, validateUserKeyDocument_1.asUserKeyPayload)(resolved.doc.getData()) ?? resolved.rawPayload;
         await (0, UserKeyDocument_1.replaceUserKeys)(resolved.doc.getDatabase(), resolved.doc, {
-            ...resolved.payload.userKeys,
-            [current]: { ...resolved.payload.userKeys[current], retiredAt: now },
+            ...raw.userKeys,
+            [current]: { ...(raw.userKeys[current] ?? previousGen), retiredAt: now },
             [nextEpoch]: {
                 publicKey: generated.publicKeyPem,
                 fingerprint,
                 createdAt: now,
                 deviceWraps,
+                ...signed,
             },
         });
     }
@@ -1202,7 +1747,9 @@ class UserKeyManager {
             return;
         let changed = false;
         const userKeys = {};
-        for (const [epoch, gen] of Object.entries(payload.userKeys ?? {})) {
+        // Write back every stored generation, also those that do not count.
+        const raw = (0, validateUserKeyDocument_1.asUserKeyPayload)(doc.getData()) ?? payload;
+        for (const [epoch, gen] of Object.entries(raw.userKeys ?? {})) {
             const deviceWraps = { ...(gen.deviceWraps ?? {}) };
             for (const fp of Object.keys(deviceWraps)) {
                 if (revokedFps.has(fp)) {