@platless/axom-cli 0.5.9 → 0.6.52

package/dist/workstation/registrations/store.js

@@ -0,0 +1,737 @@
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { z } from 'zod';
+import { registrationIdSchema, registrationIdentitySchema, registrationKey, registrationSchema } from './model.js';
+import { assertLockOwnership, assertWorkstationOperationLock, withPrivateLock } from '../control/locks.js';
+import { assertDeviceUpdateTransitionSafe, assertDurableDeviceMutationAllowed } from '../control/updateTransition.js';
+import { LocalControlError } from '../control/protocol.js';
+import { inspectPendingEnrollments } from './enrollmentPending.js';
+import { resolveBrowserBinding } from '../desktop/binding.js';
+import { registrationServerSchema } from './model.js';
+const collectionSchema = z.array(registrationSchema).max(1024);
+const atomicTemporaryPattern = /^\.write-[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const stagedGenerationPattern = /^\.stage-[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const tombstoneSchema = z.object({ server: registrationServerSchema, ownerUserId: z.string().min(1), workstationId: z.string().min(1), completed: z.literal(true) }).strict();
+const tombstonesSchema = z.array(tombstoneSchema).max(4096);
+const retiredSchema = z.object({ retired: z.literal(true), registration: registrationIdentitySchema }).strict();
+export const removalIntentSchema = z.object({
+    schemaVersion: z.literal(1), registration: registrationSchema,
+    operationId: z.string().min(1).max(128).refine(value => value.trim().length > 0 && !/[\u0000-\u001f\u007f-\u009f]/.test(value)),
+    runtimeGeneration: z.string().min(1).max(128), force: z.boolean(),
+    phase: z.enum(['intent', 'sealed', 'disposed', 'credentials-retired', 'completed', 'restoring', 'cancelled']),
+}).strict();
+const removalIntentsSchema = z.array(removalIntentSchema).max(4096);
+const deviceSchema = z.object({ schemaVersion: z.literal(1), deviceId: z.string().uuid(), initialized: z.boolean() }).strict();
+const transactionSchema = z.object({ collection: collectionSchema, previous: collectionSchema, previousTombstones: tombstonesSchema, changed: registrationIdSchema.optional(), removed: registrationIdSchema.optional(), tombstones: tombstonesSchema }).strict().refine(value => Boolean(value.changed) !== Boolean(value.removed));
+const localPath = z.string().max(4096).refine(value => path.isAbsolute(value) && !value.includes('\0'));
+const configurationSchema = z.object({
+    server: registrationServerSchema, workstationId: z.string().min(1), ownerUserId: z.string().min(1).optional(),
+    workspaces: z.array(z.object({ name: z.string().max(1024), cwd: localPath }).strict()).max(256).optional(),
+    browserBinding: z.object({ bindingId: z.string(), displayName: z.string(), vncEndpoint: z.string(), cdpEndpoint: z.string().optional(), downloadsRoot: localPath.optional() }).strict().optional(),
+    desktopProvider: z.object({ kind: z.literal('linux-native'), helperPath: localPath, runtimeDir: localPath }).strict().optional(),
+}).strict();
+const missing = (error) => error.code === 'ENOENT';
+const corrupt = () => new LocalControlError('CORRUPT_IDENTITY', 'Unsafe or corrupt registration storage');
+const storeQueues = new Map();
+const storeOperations = new AsyncLocalStorage();
+async function serializeStore(root, work) {
+    const inherited = storeOperations.getStore();
+    if (inherited?.get(root)?.active)
+        throw new LocalControlError('BUSY', 'A registration store operation cannot call itself');
+    const lease = { active: true };
+    const context = new Map(inherited);
+    context.set(root, lease);
+    const operation = (storeQueues.get(root) ?? Promise.resolve()).then(() => storeOperations.run(context, async () => {
+        try {
+            return await work();
+        }
+        finally {
+            lease.active = false;
+        }
+    }));
+    const tail = operation.then(() => { }, () => { });
+    storeQueues.set(root, tail);
+    try {
+        return await operation;
+    }
+    finally {
+        if (storeQueues.get(root) === tail)
+            storeQueues.delete(root);
+    }
+}
+function digest(registration, clientKey, serverPub, nonce, configuration) {
+    const { revision: _revision, ...metadata } = registrationSchema.parse(registration);
+    return createHash('sha256').update(JSON.stringify(metadata)).update(clientKey).update(serverPub).update(nonce).update(JSON.stringify(configuration ?? null)).digest('hex');
+}
+export class RegistrationStore {
+    options;
+    root;
+    constructor(root, options = {}) {
+        this.options = options;
+        this.root = path.resolve(root);
+    }
+    async directory(directory, create = false) {
+        const relative = path.relative(this.root, directory);
+        if (relative.startsWith('..') || path.isAbsolute(relative))
+            throw corrupt();
+        let current = this.root;
+        for (const component of ['', ...relative.split(path.sep).filter(Boolean)]) {
+            if (component)
+                current = path.join(current, component);
+            if (create) {
+                try {
+                    await fs.mkdir(current, { mode: 0o700 });
+                }
+                catch (error) {
+                    if (error.code !== 'EEXIST')
+                        throw error;
+                }
+            }
+            const stat = await fs.lstat(current);
+            if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0 || (process.getuid && stat.uid !== process.getuid()))
+                throw corrupt();
+        }
+    }
+    async file(file, limit = 1_048_576) {
+        await this.directory(path.dirname(file));
+        const handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile() || stat.nlink !== 1 || stat.size > limit || (stat.mode & 0o077) !== 0 || (process.getuid && stat.uid !== process.getuid()))
+                throw corrupt();
+            const buffer = Buffer.alloc(stat.size + 1);
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+            if (bytesRead !== stat.size)
+                throw corrupt();
+            return buffer.subarray(0, bytesRead);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async sync(directory) {
+        await this.directory(directory);
+        const handle = await fs.open(directory, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async write(file, value) {
+        const text = JSON.stringify(value);
+        const limit = ['identity.json', 'retired.json'].includes(path.basename(file)) ? 16_384 : 1_048_576;
+        if (Buffer.byteLength(text) > limit)
+            throw corrupt();
+        assertLockOwnership();
+        await this.directory(path.dirname(file));
+        try {
+            await this.file(file);
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+        const temporary = path.join(path.dirname(file), `.write-${randomUUID()}`);
+        try {
+            const handle = await fs.open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+            try {
+                await handle.writeFile(text);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            if (path.basename(file) === 'identity.json')
+                await this.options.afterStage?.('identity-file-synced');
+            if (path.basename(file) === 'removal-intents.json')
+                await this.options.afterStage?.('removal-intent-file-synced');
+            assertLockOwnership();
+            await fs.rename(temporary, file);
+            await this.sync(path.dirname(file));
+        }
+        finally {
+            assertLockOwnership();
+            await fs.rm(temporary, { force: true });
+            await this.sync(path.dirname(file));
+        }
+    }
+    async locked(work) {
+        await this.directory(this.root, true);
+        const canonicalRoot = await fs.realpath(this.root);
+        return serializeStore(canonicalRoot, () => this.lockedFile(work));
+    }
+    async lockedFile(work) {
+        try {
+            if (!deviceSchema.parse(JSON.parse((await this.file(path.join(this.root, 'device.json'), 4096)).toString())).initialized)
+                await assertDeviceUpdateTransitionSafe(this.root);
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+            await assertDeviceUpdateTransitionSafe(this.root);
+        }
+        await this.directory(path.join(this.root, 'registrations'), true);
+        return withPrivateLock(path.join(this.root, 'registration-store'), async () => {
+            let device;
+            try {
+                device = deviceSchema.parse(JSON.parse((await this.file(path.join(this.root, 'device.json'), 4096)).toString()));
+            }
+            catch (error) {
+                if (!missing(error))
+                    throw error;
+                await assertDeviceUpdateTransitionSafe(this.root);
+                if ((await fs.readdir(path.join(this.root, 'registrations'))).length !== 0)
+                    throw corrupt();
+                for (const name of ['registrations.json', 'registration-tombstones.json', 'registrations.pending.json']) {
+                    try {
+                        await fs.lstat(path.join(this.root, name));
+                        throw corrupt();
+                    }
+                    catch (existingError) {
+                        if (!missing(existingError))
+                            throw existingError;
+                    }
+                }
+                device = { schemaVersion: 1, deviceId: randomUUID(), initialized: false };
+                await this.write(path.join(this.root, 'device.json'), device);
+            }
+            if (!device.initialized) {
+                await assertDeviceUpdateTransitionSafe(this.root);
+                if ((await fs.readdir(path.join(this.root, 'registrations'))).length !== 0)
+                    throw corrupt();
+                try {
+                    await fs.lstat(path.join(this.root, 'registrations.pending.json'));
+                    throw corrupt();
+                }
+                catch (error) {
+                    if (!missing(error))
+                        throw error;
+                }
+                for (const name of ['registrations.json', 'registration-tombstones.json']) {
+                    try {
+                        if ((await this.file(path.join(this.root, name))).toString() !== '[]')
+                            throw corrupt();
+                    }
+                    catch (error) {
+                        if (!missing(error))
+                            throw error;
+                        await this.write(path.join(this.root, name), []);
+                    }
+                }
+                await this.write(path.join(this.root, 'device.json'), { ...device, initialized: true });
+            }
+            return work();
+        });
+    }
+    validate(registration) {
+        const parsed = registrationSchema.parse(registration);
+        const data = path.join(this.root, 'registrations', parsed.id, 'data');
+        if (parsed.dataDirectory !== data || ![data, this.root].includes(parsed.keeperConfigDirectory) || !/^[a-f0-9]{64}$/.test(parsed.revision))
+            throw corrupt();
+        return parsed;
+    }
+    configuration(value, registration) {
+        if (value === undefined)
+            return undefined;
+        const parsed = configurationSchema.parse(value);
+        if (parsed.server !== registration.server || parsed.workstationId !== registration.workstationId || (parsed.ownerUserId !== undefined && parsed.ownerUserId !== registration.ownerUserId))
+            throw corrupt();
+        if (parsed.browserBinding)
+            resolveBrowserBinding(parsed.browserBinding, {});
+        return parsed;
+    }
+    async collection() {
+        try {
+            const entries = collectionSchema.parse(JSON.parse((await this.file(path.join(this.root, 'registrations.json'))).toString()));
+            const ids = new Set();
+            const keys = new Set();
+            for (const entry of entries) {
+                this.validate(entry);
+                const key = registrationKey(entry.server, entry.ownerUserId);
+                if (ids.has(entry.id) || keys.has(key))
+                    throw corrupt();
+                ids.add(entry.id);
+                keys.add(key);
+            }
+            return entries;
+        }
+        catch {
+            throw corrupt();
+        }
+    }
+    async identity(registration, generation = registration.revision) {
+        this.validate(registration);
+        await this.directory(registration.dataDirectory);
+        await this.directory(registration.keeperConfigDirectory);
+        const identity = z.object({ registration: registrationSchema, clientKey: z.string(), serverPub: z.string(), nonce: z.string().uuid(), configuration: configurationSchema.optional() }).strict().parse(JSON.parse((await this.file(path.join(this.root, 'registrations', registration.id, generation, 'identity.json'), 16_384)).toString()));
+        if (JSON.stringify(identity.registration) !== JSON.stringify(registration))
+            throw corrupt();
+        const clientKey = Buffer.from(identity.clientKey, 'base64');
+        const serverPub = Buffer.from(identity.serverPub, 'base64');
+        if (clientKey.length !== 32 || serverPub.length !== 32 || clientKey.toString('base64') !== identity.clientKey || serverPub.toString('base64') !== identity.serverPub)
+            throw corrupt();
+        const configuration = this.configuration(identity.configuration, registration);
+        if (digest(registration, clientKey, serverPub, identity.nonce, configuration) !== registration.revision)
+            throw corrupt();
+        return { registration, clientKey, serverPub, ...(configuration ? { configuration } : {}) };
+    }
+    async inspect() {
+        return this.locked(async () => {
+            let collection;
+            try {
+                await this.recoverLocked();
+                collection = await this.collection();
+            }
+            catch {
+                return { known: false, entries: [], diagnostic: 'Registration collection needs verification' };
+            }
+            const entries = [];
+            for (const registration of collection) {
+                try {
+                    await this.identity(registration);
+                    entries.push({ id: registration.id, state: 'ready', registration });
+                }
+                catch {
+                    entries.push({ id: registration.id, state: 'corrupt', target: { server: registration.server, ownerUserId: registration.ownerUserId, workstationId: registration.workstationId, revision: registration.revision }, diagnostic: 'Registration identity needs repair' });
+                }
+            }
+            return { known: true, entries };
+        });
+    }
+    async list() {
+        const inspection = await this.inspect();
+        if (!inspection.known)
+            throw corrupt();
+        return inspection.entries.flatMap(entry => entry.state === 'ready' ? [entry.registration] : []);
+    }
+    async pendingEnrollments() {
+        return inspectPendingEnrollments(this.root);
+    }
+    async read(id) {
+        registrationIdSchema.parse(id);
+        return this.locked(async () => {
+            await this.recoverLocked();
+            const registration = (await this.collection()).find(entry => entry.id === id);
+            if (!registration)
+                throw new LocalControlError('BINDING_CONFLICT', 'Registration is no longer present');
+            return this.identity(registration);
+        });
+    }
+    async readMetadata(id, expectedRevision) {
+        registrationIdSchema.parse(id);
+        return this.locked(async () => {
+            await this.recoverLocked();
+            const registration = (await this.collection()).find(entry => entry.id === id);
+            if (!registration || registration.revision !== expectedRevision)
+                throw new LocalControlError('BINDING_CONFLICT', 'Registration changed; inspect again');
+            await this.directory(registration.dataDirectory);
+            await this.directory(registration.keeperConfigDirectory);
+            return { ...registration };
+        });
+    }
+    async removalIntentsLocked() {
+        try {
+            const intents = removalIntentsSchema.parse(JSON.parse((await this.file(path.join(this.root, 'removal-intents.json'))).toString()));
+            const ids = new Set();
+            const operations = new Set();
+            for (const intent of intents) {
+                this.validate(intent.registration);
+                if (ids.has(intent.registration.id) || operations.has(intent.operationId))
+                    throw corrupt();
+                ids.add(intent.registration.id);
+                operations.add(intent.operationId);
+            }
+            return intents;
+        }
+        catch (error) {
+            if (missing(error))
+                return [];
+            throw corrupt();
+        }
+    }
+    async removalIntents() {
+        return this.locked(async () => {
+            const intents = await this.removalIntentsLocked();
+            const recovered = [];
+            let changed = false;
+            for (const intent of intents) {
+                if (intent.phase === 'credentials-retired' && await this.completedRemovalLocked(intent.registration)) {
+                    recovered.push({ ...intent, phase: 'completed' });
+                    changed = true;
+                }
+                else
+                    recovered.push(intent);
+            }
+            if (changed) {
+                await assertDurableDeviceMutationAllowed(this.root);
+                await this.write(path.join(this.root, 'removal-intents.json'), recovered);
+            }
+            return recovered;
+        });
+    }
+    sameRemoval(left, right) {
+        return left.operationId === right.operationId && left.runtimeGeneration === right.runtimeGeneration && left.force === right.force && JSON.stringify(left.registration) === JSON.stringify(right.registration);
+    }
+    async beginRemoval(input) {
+        await assertDurableDeviceMutationAllowed(this.root);
+        assertWorkstationOperationLock(this.root);
+        const intent = removalIntentSchema.parse(input);
+        if (intent.phase !== 'intent')
+            throw corrupt();
+        return this.locked(async () => {
+            await assertDurableDeviceMutationAllowed(this.root);
+            await this.recoverLocked();
+            const intents = await this.removalIntentsLocked();
+            const previous = intents.find(entry => entry.operationId === intent.operationId || entry.registration.id === intent.registration.id && entry.phase !== 'cancelled');
+            if (previous) {
+                if (!this.sameRemoval(previous, intent))
+                    throw new LocalControlError('BINDING_CONFLICT', 'Removal operation identity changed');
+                return previous;
+            }
+            const registration = (await this.collection()).find(entry => entry.id === intent.registration.id);
+            if (!registration || JSON.stringify(registration) !== JSON.stringify(intent.registration))
+                throw new LocalControlError('BINDING_CONFLICT', 'Removal target changed');
+            await this.identity(registration);
+            await this.write(path.join(this.root, 'removal-intents.json'), removalIntentsSchema.parse([...intents.filter(entry => entry.registration.id !== intent.registration.id), intent]));
+            await this.options.afterStage?.('removal-intent-published');
+            return intent;
+        });
+    }
+    async advanceRemoval(input, phase) {
+        await assertDurableDeviceMutationAllowed(this.root);
+        assertWorkstationOperationLock(this.root);
+        return this.locked(async () => {
+            await assertDurableDeviceMutationAllowed(this.root);
+            const intents = await this.removalIntentsLocked();
+            const previous = intents.find(entry => entry.operationId === input.operationId);
+            if (!previous || !this.sameRemoval(previous, input))
+                throw new LocalControlError('BINDING_CONFLICT', 'Removal operation identity changed');
+            const phases = removalIntentSchema.shape.phase.options;
+            if (['restoring', 'cancelled'].includes(phase) || ['restoring', 'cancelled'].includes(previous.phase))
+                throw new LocalControlError('BINDING_CONFLICT', 'Cancelled removal cannot resume termination');
+            if (phases.indexOf(phase) < phases.indexOf(previous.phase))
+                return previous;
+            if (phases.indexOf(phase) > phases.indexOf(previous.phase) + 1)
+                throw corrupt();
+            if (phase === 'completed' && !await this.completedRemovalLocked(previous.registration))
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'Removal finalization needs verification');
+            const next = { ...previous, phase };
+            await this.write(path.join(this.root, 'removal-intents.json'), intents.map(entry => entry === previous ? next : entry));
+            await this.options.afterStage?.('removal-' + phase + '-published');
+            return next;
+        });
+    }
+    async cancelRemoval(input) {
+        await assertDurableDeviceMutationAllowed(this.root);
+        assertWorkstationOperationLock(this.root);
+        await this.locked(async () => {
+            await assertDurableDeviceMutationAllowed(this.root);
+            const intents = await this.removalIntentsLocked();
+            const previous = intents.find(entry => entry.operationId === input.operationId);
+            if (!previous)
+                return;
+            if (!this.sameRemoval(previous, input) || !['intent', 'restoring'].includes(previous.phase))
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'Removal cannot reopen original admission');
+            await this.write(path.join(this.root, 'removal-intents.json'), intents.map(entry => entry === previous ? { ...previous, phase: 'restoring' } : entry));
+            await this.options.afterStage?.('removal-cancelled');
+        });
+    }
+    async finishRemovalRestoration(input) {
+        await assertDurableDeviceMutationAllowed(this.root);
+        assertWorkstationOperationLock(this.root);
+        await this.locked(async () => {
+            await assertDurableDeviceMutationAllowed(this.root);
+            const intents = await this.removalIntentsLocked();
+            const previous = intents.find(entry => entry.operationId === input.operationId);
+            if (!previous)
+                return;
+            if (!this.sameRemoval(previous, input) || previous.phase !== 'restoring')
+                throw new LocalControlError('BINDING_CONFLICT', 'Original removal restoration changed');
+            await this.write(path.join(this.root, 'removal-intents.json'), intents.map(entry => entry === previous ? { ...previous, phase: 'cancelled' } : entry));
+        });
+    }
+    async assertEnrollmentAllowed(server, ownerUserId) {
+        await assertDurableDeviceMutationAllowed(this.root);
+        await this.locked(async () => {
+            await assertDurableDeviceMutationAllowed(this.root);
+            if ((await this.removalIntentsLocked()).some(intent => !['completed', 'cancelled'].includes(intent.phase) && registrationKey(intent.registration.server, intent.registration.ownerUserId) === registrationKey(server, ownerUserId)))
+                throw new LocalControlError('BUSY', 'Matching registration removal remains pending');
+        });
+    }
+    async tombstones() {
+        try {
+            return z.array(tombstoneSchema).max(4096).parse(JSON.parse((await this.file(path.join(this.root, 'registration-tombstones.json'))).toString()));
+        }
+        catch {
+            throw corrupt();
+        }
+    }
+    async completedTombstones() {
+        return this.locked(async () => { await this.recoverLocked(); await this.collection(); return this.tombstones(); });
+    }
+    async hasCompletedRemoval(target) {
+        const parsed = registrationIdentitySchema.omit({ revision: true }).parse(target);
+        return this.locked(() => this.completedRemovalLocked(parsed));
+    }
+    async verifyRemovalCompletion(registration) {
+        const parsed = this.validate(registration);
+        return this.locked(() => this.completedRemovalLocked(parsed));
+    }
+    async completedRemovalLocked(parsed) {
+        await this.recoverLocked();
+        if ((await this.collection()).some(entry => entry.id === parsed.id))
+            return false;
+        let retired;
+        try {
+            retired = retiredSchema.parse(JSON.parse((await this.file(path.join(this.root, 'registrations', parsed.id, 'retired.json'), 16_384)).toString()));
+        }
+        catch (error) {
+            if (missing(error))
+                return false;
+            throw corrupt();
+        }
+        const registration = retired.registration;
+        if (registration.id !== parsed.id || registration.server !== parsed.server || registration.ownerUserId !== parsed.ownerUserId || registration.workstationId !== parsed.workstationId)
+            return false;
+        if (parsed.revision !== undefined && registration.revision !== parsed.revision)
+            return false;
+        if ((await this.scrubTargets(parsed.id)).length)
+            return false;
+        return (await this.tombstones()).some(entry => entry.server === parsed.server && entry.ownerUserId === parsed.ownerUserId && entry.workstationId === parsed.workstationId);
+    }
+    async commit(input) {
+        await assertDurableDeviceMutationAllowed(this.root);
+        if (!Buffer.isBuffer(input.clientKey) || !Buffer.isBuffer(input.serverPub) || input.clientKey.length !== 32 || input.serverPub.length !== 32)
+            throw corrupt();
+        const nonce = randomUUID();
+        const normalized = registrationSchema.parse({ ...input.registration, revision: 'pending' });
+        const configuration = this.configuration(input.configuration, normalized);
+        const registration = this.validate({ ...normalized, revision: digest(normalized, input.clientKey, input.serverPub, nonce, configuration) });
+        return this.locked(async () => {
+            await assertDurableDeviceMutationAllowed(this.root);
+            await this.recoverLocked();
+            const collection = await this.collection();
+            const current = collection.find(entry => entry.id === registration.id);
+            if ((await this.removalIntentsLocked()).some(intent => !['completed', 'cancelled'].includes(intent.phase) && (intent.registration.id === registration.id || registrationKey(intent.registration.server, intent.registration.ownerUserId) === registrationKey(registration.server, registration.ownerUserId))))
+                throw new LocalControlError('BUSY', 'Matching registration removal remains pending');
+            if ((current?.revision ?? null) !== input.expectedRevision || collection.some(entry => entry.id !== registration.id && registrationKey(entry.server, entry.ownerUserId) === registrationKey(registration.server, registration.ownerUserId)))
+                throw new LocalControlError('BINDING_CONFLICT', 'Registration changed or account already registered');
+            if (current)
+                await this.identity(current);
+            const base = path.join(this.root, 'registrations', registration.id);
+            if (!current) {
+                try {
+                    await this.directory(base);
+                    try {
+                        await this.file(path.join(base, 'retired.json'), 16_384);
+                        throw new LocalControlError('BINDING_CONFLICT', 'Registration ID was retired; choose a new ID');
+                    }
+                    catch (error) {
+                        if (!missing(error))
+                            throw error;
+                    }
+                    let matching = false;
+                    const names = await fs.readdir(base);
+                    let unpublished = names.every(name => name === 'data' || stagedGenerationPattern.test(name));
+                    if (names.includes('data'))
+                        await this.directory(registration.dataDirectory);
+                    for (const name of names) {
+                        if (!/^[a-f0-9]{64}$/.test(name) && !stagedGenerationPattern.test(name))
+                            continue;
+                        let text;
+                        try {
+                            text = await this.file(path.join(base, name, 'identity.json'), 16_384);
+                        }
+                        catch (error) {
+                            if (!missing(error) || !name.startsWith('.stage-'))
+                                throw error;
+                            await this.discardUnpublishedStage(path.join(base, name));
+                            continue;
+                        }
+                        unpublished = false;
+                        const raw = JSON.parse(text.toString());
+                        const old = await this.identity(registrationSchema.parse(raw.registration), name);
+                        const { revision: _oldRevision, ...oldMetadata } = old.registration;
+                        const { revision: _newRevision, ...newMetadata } = registration;
+                        if (JSON.stringify(oldMetadata) !== JSON.stringify(newMetadata) || !old.clientKey.equals(input.clientKey) || !old.serverPub.equals(input.serverPub) || JSON.stringify(old.configuration) !== JSON.stringify(configuration))
+                            throw new LocalControlError('BINDING_CONFLICT', 'Unpublished registration identity differs');
+                        matching = true;
+                    }
+                    if (!matching && !unpublished)
+                        throw new LocalControlError('BINDING_CONFLICT', 'Unrecognized existing registration data');
+                }
+                catch (error) {
+                    if (!missing(error))
+                        throw error;
+                    try {
+                        await fs.lstat(base);
+                    }
+                    catch (baseError) {
+                        if (missing(baseError)) {
+                            await this.directory(base, true);
+                        }
+                        else
+                            throw baseError;
+                    }
+                    if ((await fs.readdir(base)).length !== 0)
+                        throw corrupt();
+                }
+            }
+            await this.directory(base, true);
+            await this.directory(registration.dataDirectory, true);
+            await this.directory(registration.keeperConfigDirectory);
+            const staged = path.join(base, `.stage-${randomUUID()}`);
+            await this.directory(staged, true);
+            await this.write(path.join(staged, 'identity.json'), { registration, clientKey: input.clientKey.toString('base64'), serverPub: input.serverPub.toString('base64'), nonce, ...(configuration ? { configuration } : {}) });
+            await this.options.afterStage?.('staged');
+            await fs.rename(staged, path.join(base, registration.revision));
+            await this.sync(base);
+            await this.options.afterStage?.('identity-published');
+            const tombstones = await this.tombstones();
+            await this.write(path.join(this.root, 'registrations.pending.json'), transactionSchema.parse({ previous: collection, previousTombstones: tombstones, collection: [...collection.filter(entry => entry.id !== registration.id), registration], changed: registration.id, tombstones }));
+            await this.options.afterStage?.('transaction-ready');
+            await this.recoverLocked(true);
+            return registration;
+        });
+    }
+    async remove(id, expectedRevision) {
+        await assertDurableDeviceMutationAllowed(this.root);
+        registrationIdSchema.parse(id);
+        return this.locked(async () => {
+            await assertDurableDeviceMutationAllowed(this.root);
+            await this.recoverLocked();
+            const collection = await this.collection();
+            const current = collection.find(entry => entry.id === id);
+            if (!current || current.revision !== expectedRevision)
+                throw new LocalControlError('BINDING_CONFLICT', 'Registration changed; inspect again');
+            await this.scrubTargets(id);
+            const previousTombstones = await this.tombstones();
+            const tombstones = [...previousTombstones, { server: current.server, ownerUserId: current.ownerUserId, workstationId: current.workstationId, completed: true }];
+            await this.write(path.join(this.root, 'registrations.pending.json'), transactionSchema.parse({ previous: collection, previousTombstones, collection: collection.filter(entry => entry.id !== id), removed: id, tombstones }));
+            await this.options.afterStage?.('transaction-ready');
+            await this.recoverLocked(true);
+        });
+    }
+    async recover() { return this.locked(() => this.recoverLocked()); }
+    async discardUnpublishedStage(directory) {
+        await this.directory(directory);
+        const names = await fs.readdir(directory);
+        if (names.some(name => !atomicTemporaryPattern.test(name)))
+            throw corrupt();
+        for (const name of names)
+            if ((await fs.lstat(path.join(directory, name))).isDirectory())
+                throw corrupt();
+        for (const name of names) {
+            assertLockOwnership();
+            await fs.unlink(path.join(directory, name));
+        }
+        await this.sync(directory);
+        assertLockOwnership();
+        await fs.rmdir(directory);
+        await this.sync(path.dirname(directory));
+    }
+    async scrubTargets(id) {
+        const base = path.join(this.root, 'registrations', id);
+        await this.directory(base);
+        const targets = [];
+        for (const name of await fs.readdir(base)) {
+            if (!/^[a-f0-9]{64}$/.test(name) && !stagedGenerationPattern.test(name))
+                continue;
+            const directory = path.join(base, name);
+            await this.directory(directory);
+            for (const file of await fs.readdir(directory)) {
+                if (file !== 'identity.json' && !atomicTemporaryPattern.test(file))
+                    continue;
+                const target = path.join(directory, file);
+                try {
+                    const stat = await fs.lstat(target);
+                    if (stat.isDirectory())
+                        throw corrupt();
+                    targets.push(target);
+                }
+                catch (error) {
+                    if (!missing(error))
+                        throw error;
+                }
+            }
+        }
+        return targets;
+    }
+    async recoverLocked(inject = false) {
+        let transaction;
+        try {
+            transaction = transactionSchema.parse(JSON.parse((await this.file(path.join(this.root, 'registrations.pending.json'))).toString()));
+        }
+        catch (error) {
+            if (missing(error))
+                return;
+            throw corrupt();
+        }
+        const current = await this.collection();
+        const previous = transaction.previous;
+        const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+        if (!same(current, previous) && !same(current, transaction.collection))
+            throw corrupt();
+        const currentTombstones = await this.tombstones();
+        let expectedTombstones = transaction.previousTombstones;
+        if (transaction.removed) {
+            const removed = previous.find(entry => entry.id === transaction.removed);
+            if (!removed)
+                throw corrupt();
+            expectedTombstones = [...expectedTombstones, { server: removed.server, ownerUserId: removed.ownerUserId, workstationId: removed.workstationId, completed: true }];
+        }
+        if (!same(transaction.tombstones, expectedTombstones) || (!same(currentTombstones, transaction.previousTombstones) && !same(currentTombstones, expectedTombstones)))
+            throw corrupt();
+        if (transaction.changed && same(previous, transaction.collection))
+            throw corrupt();
+        for (const old of previous) {
+            const next = transaction.collection.find(entry => entry.id === old.id);
+            if (!next && old.id !== transaction.removed)
+                throw corrupt();
+            if (next && JSON.stringify(next) !== JSON.stringify(old) && old.id !== transaction.changed)
+                throw corrupt();
+        }
+        const ids = new Set();
+        const keys = new Set();
+        for (const registration of transaction.collection) {
+            const key = registrationKey(registration.server, registration.ownerUserId);
+            if (ids.has(registration.id) || keys.has(key) || registration.id === transaction.removed)
+                throw corrupt();
+            this.validate(registration);
+            ids.add(registration.id);
+            keys.add(key);
+            const old = previous.find(entry => entry.id === registration.id);
+            if (!old && registration.id !== transaction.changed)
+                throw corrupt();
+            if (registration.id === transaction.changed)
+                await this.identity(registration);
+        }
+        if (transaction.changed && !ids.has(transaction.changed))
+            throw corrupt();
+        const targets = transaction.removed ? await this.scrubTargets(transaction.removed) : [];
+        if (transaction.removed) {
+            const { dataDirectory: _data, keeperConfigDirectory: _keeper, ...registration } = previous.find(entry => entry.id === transaction.removed);
+            await this.write(path.join(this.root, 'registrations', transaction.removed, 'retired.json'), { retired: true, registration: registrationIdentitySchema.parse(registration) });
+        }
+        for (const target of targets) {
+            assertLockOwnership();
+            await fs.unlink(target);
+            await this.sync(path.dirname(target));
+            if (inject)
+                await this.options.afterStage?.('identity-scrubbed');
+        }
+        await this.write(path.join(this.root, 'registration-tombstones.json'), transaction.tombstones);
+        if (inject)
+            await this.options.afterStage?.('tombstone-published');
+        await this.write(path.join(this.root, 'registrations.json'), transaction.collection);
+        if (inject)
+            await this.options.afterStage?.('collection-published');
+        assertLockOwnership();
+        await fs.unlink(path.join(this.root, 'registrations.pending.json'));
+        await this.sync(this.root);
+    }
+}