@platless/axom-cli 0.6.36 → 0.6.52

package/dist/workstation/rd/upkeep.js

@@ -1,16 +1,47 @@
+import { randomUUID } from 'node:crypto';
 export class RdUpkeep {
     options;
     pending;
     running = false;
     stopped = false;
+    original;
+    completion;
     constructor(options) {
         this.options = options;
     }
     async tick() {
         if (this.running || this.stopped)
             return;
+        if (this.options.device && (this.options.platform ?? process.platform) !== 'linux')
+            return;
         this.running = true;
+        this.completion = this.run();
+        try {
+            await this.completion;
+        }
+        finally {
+            this.running = false;
+        }
+    }
+    async run() {
+        if (this.original) {
+            try {
+                await this.original.release();
+                this.original = undefined;
+            }
+            catch (error) {
+                this.options.log?.(`[rd] original maintenance restoration remains pending: ${error instanceof Error ? error.message : 'unknown'}`);
+                return;
+            }
+        }
         try {
+            if (this.options.device) {
+                this.original = this.options.device.acquireMaintenance({ transactionId: `rd-upkeep:${randomUUID()}` });
+                await this.original.ready;
+                if ((await this.original.observe()).status !== 'candidate')
+                    return;
+            }
+            await this.options.adopt?.();
             this.pending ??= await this.options.synchronize();
             if (this.stopped || !this.pending)
                 return;
@@ -31,8 +62,19 @@ export class RdUpkeep {
             this.options.log?.(`[rd] automatic update failed: ${error instanceof Error ? error.message : String(error)}`);
         }
         finally {
-            this.running = false;
+            if (this.original) {
+                try {
+                    await this.original.release();
+                    this.original = undefined;
+                }
+                catch (error) {
+                    this.options.log?.(`[rd] original maintenance restoration remains pending: ${error instanceof Error ? error.message : 'unknown'}`);
+                }
+            }
         }
     }
-    stop() { this.stopped = true; }
+    async stop() { this.stopped = true; await this.completion; if (this.original) {
+        await this.original.release();
+        this.original = undefined;
+    } }
 }

package/dist/workstation/registrations/enrollment.js

@@ -0,0 +1,250 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { LocalControlError } from '../control/protocol.js';
+import { assertLockOwnership, withWorkstationLock } from '../control/locks.js';
+import { normalizeWorkstationServer, workstationEndpoint } from '../control/serverIdentity.js';
+import { deriveSessionKey, generateKeyPair } from '../crypto.js';
+import { osInfo } from '../osinfo.js';
+import { RegistrationStore } from './store.js';
+import { registrationKey, registrationSchema } from './model.js';
+import { assertRegistrationEnrollmentAdmission } from './migration.js';
+import { EnrollmentPendingStore, enrollmentDirectory, enrollmentStorageError, keySchema, operationIdSchema, registrationEnrollmentInputSchema, requestDigest, requestSchema } from './enrollmentPending.js';
+const inputSchema = registrationEnrollmentInputSchema;
+async function acquisitionMatches(store, pending) {
+    const latest = (await store.completedTombstones()).filter(entry => entry.server === pending.server && entry.ownerUserId === pending.ownerUserId).at(-1);
+    return latest ? pending.request.acquisition.kind === 'reattach' && pending.request.proposedWorkstationId === latest.workstationId : pending.request.acquisition.kind === 'create';
+}
+function recoveryProof(store) {
+    return {
+        committed: async (pending, completed) => {
+            try {
+                const identity = await store.read(pending.registrationId);
+                const registration = identity.registration;
+                return registration.id === completed.registrationId && registration.revision === completed.registrationRevision && registration.server === pending.server && registration.ownerUserId === pending.ownerUserId && registration.workstationId === pending.request.proposedWorkstationId && registration.workstationId === completed.workstationId && identity.clientKey.toString('base64') === pending.clientPrivateKey;
+            }
+            catch {
+                return false;
+            }
+        },
+        removed: async (completed, candidate) => {
+            if (!await store.hasCompletedRemoval({ id: completed.registrationId, server: completed.server, ownerUserId: completed.ownerUserId, workstationId: completed.workstationId }))
+                return false;
+            if (!candidate)
+                return true;
+            return acquisitionMatches(store, candidate);
+        },
+    };
+}
+export async function retireRegistrationEnrollment(root, registration) {
+    try {
+        assertLockOwnership();
+        root = path.resolve(root);
+        const parsed = registrationSchema.parse(registration);
+        await enrollmentDirectory(root, root, false);
+        const store = new RegistrationStore(root);
+        const inspection = await store.inspect();
+        if (!inspection.known)
+            throw enrollmentStorageError();
+        const entry = inspection.entries.find(candidate => candidate.id === parsed.id);
+        const target = entry?.state === 'ready' ? entry.registration : entry?.target;
+        if (target) {
+            if (target.server !== parsed.server || target.ownerUserId !== parsed.ownerUserId || target.workstationId !== parsed.workstationId)
+                throw enrollmentStorageError();
+            if (target.revision !== parsed.revision)
+                throw new LocalControlError('BINDING_CONFLICT', 'Registration changed before enrollment cleanup');
+        }
+        else if (!await store.hasCompletedRemoval({ id: parsed.id, server: parsed.server, ownerUserId: parsed.ownerUserId, workstationId: parsed.workstationId }))
+            throw new LocalControlError('BINDING_CONFLICT', 'Registration removal could not be verified');
+        await new EnrollmentPendingStore(root, parsed.server, parsed.ownerUserId, recoveryProof(store)).purge(parsed.id, parsed.workstationId);
+    }
+    catch (error) {
+        if (error instanceof LocalControlError)
+            throw error;
+        throw enrollmentStorageError();
+    }
+}
+const identitySchema = z.object({ ownerUserId: z.string().min(1).max(1024).refine(value => !/[\x00-\x1f\x7f-\x9f]/.test(value)) }).strict();
+const lookupSchema = identitySchema.extend({ workstationId: z.string().uuid(), version: z.number().int().min(1).max(2147483646) }).strict();
+const responseSchema = identitySchema.extend({ protocol: z.literal(2), operationId: operationIdSchema, workstationId: z.string().uuid(), serverPub: keySchema }).strict();
+async function requestJson(input, endpoint, body, mutation = false, historical = false) {
+    try {
+        const response = await fetch(workstationEndpoint(input.server, endpoint), {
+            method: body === undefined ? 'GET' : 'POST', headers: { Authorization: `Bearer ${input.accessToken}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }), redirect: 'manual', signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) {
+            await response.body?.cancel();
+            if ([401, 403].includes(response.status))
+                throw new LocalControlError('AUTHORIZATION_REQUIRED', 'Workstation enrollment requires current workstation authority');
+            if (response.status === 409 || (historical && response.status === 404))
+                throw new LocalControlError('BINDING_CONFLICT', 'Historical workstation could not be verified or changed; inspect before retrying');
+            if ([404, 405, 501].includes(response.status))
+                throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'This server requires an upgrade for workstation enrollment');
+            if (mutation && response.status >= 500)
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'Enrollment outcome is unknown; retry with the saved request');
+            throw new LocalControlError('NETWORK_FAILED', 'The workstation enrollment request was refused');
+        }
+        const reader = response.body?.getReader();
+        if (!reader)
+            throw Error('Missing response');
+        const chunks = [];
+        let size = 0;
+        try {
+            while (true) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                    break;
+                size += chunk.value.length;
+                if (size > 65_536)
+                    throw Error('Response limit');
+                chunks.push(chunk.value);
+            }
+        }
+        finally {
+            await reader.cancel().catch(() => undefined);
+        }
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch (error) {
+        if (error instanceof LocalControlError)
+            throw error;
+        throw new LocalControlError(mutation ? 'OUTCOME_UNKNOWN' : 'NETWORK_FAILED', mutation ? 'Enrollment outcome is unknown; retry with the saved request' : 'Workstation authority could not be verified');
+    }
+}
+export async function verifyRegistrationAuthority(input) {
+    const scopes = z.object({ results: z.array(z.object({ scope: z.string(), allowed: z.boolean() }).strict()).max(64) }).strict().safeParse(await requestJson(input, '/rest/auth/scopes/check', { scopes: ['workstation'] }));
+    if (!scopes.success || scopes.data.results.length !== 1 || scopes.data.results[0]?.scope !== 'workstation')
+        throw new LocalControlError('NETWORK_FAILED', 'Workstation permission response is invalid');
+    if (!scopes.data.results[0].allowed)
+        throw new LocalControlError('AUTHORIZATION_REQUIRED', 'Workstation permission is required');
+    const identity = identitySchema.safeParse(await requestJson(input, '/workstation/enroll/identity'));
+    if (!identity.success)
+        throw new LocalControlError('NETWORK_FAILED', 'Workstation owner response is invalid');
+    if (input.expectedOwnerUserId !== undefined && input.expectedOwnerUserId !== identity.data.ownerUserId)
+        throw new LocalControlError('OWNER_MISMATCH', 'The authenticated workstation owner differs from the expected owner');
+    return identity.data.ownerUserId;
+}
+async function enrollLocked(input, root, options) {
+    await options.beforeEnrollment?.();
+    await assertRegistrationEnrollmentAdmission(root);
+    const ownerUserId = await verifyRegistrationAuthority(input);
+    const store = new RegistrationStore(root, { afterStage: stage => options.afterStage?.('store-' + stage) ?? Promise.resolve() });
+    await store.assertEnrollmentAllowed(input.server, ownerUserId);
+    const inspection = await store.inspect();
+    if (!inspection.known)
+        throw enrollmentStorageError();
+    const key = registrationKey(input.server, ownerUserId);
+    const existing = inspection.entries.find(entry => registrationKey(entry.state === 'ready' ? entry.registration.server : entry.target.server, entry.state === 'ready' ? entry.registration.ownerUserId : entry.target.ownerUserId) === key);
+    if (existing?.state === 'corrupt')
+        throw new LocalControlError('CORRUPT_IDENTITY', 'The matching workstation registration needs repair');
+    const proof = recoveryProof(store);
+    const pendingStore = new EnrollmentPendingStore(root, input.server, ownerUserId, proof, options.afterStage);
+    let envelope = await pendingStore.read();
+    if (existing?.state === 'ready') {
+        if (envelope?.state === 'pending' && envelope.registrationId === existing.id) {
+            const identity = await store.read(existing.id);
+            if (identity.registration.workstationId !== envelope.request.proposedWorkstationId || identity.clientKey.toString('base64') !== envelope.clientPrivateKey)
+                throw enrollmentStorageError();
+            try {
+                await pendingStore.complete(envelope, existing.registration.revision);
+            }
+            catch {
+                throw new LocalControlError('OUTCOME_UNKNOWN', 'Local enrollment recovery completion is uncertain; retry with the saved identity');
+            }
+        }
+        return { operationId: input.operationId, registration: existing.registration, kind: 'reused' };
+    }
+    if (envelope?.state === 'completed' && !await proof.removed(envelope))
+        throw enrollmentStorageError();
+    if (!envelope || envelope.state === 'completed') {
+        const historical = (await store.completedTombstones()).filter(entry => registrationKey(entry.server, entry.ownerUserId) === key).at(-1);
+        let acquisition = { kind: 'create' };
+        let proposedWorkstationId = randomUUID();
+        if (historical) {
+            let metadata;
+            try {
+                metadata = lookupSchema.parse(await requestJson(input, '/workstation/enroll/' + historical.workstationId, undefined, false, true));
+            }
+            catch (error) {
+                if (error instanceof LocalControlError)
+                    throw error;
+                throw new LocalControlError('BINDING_CONFLICT', 'Historical workstation response could not be verified');
+            }
+            if (metadata.workstationId !== historical.workstationId || metadata.ownerUserId !== ownerUserId)
+                throw new LocalControlError('BINDING_CONFLICT', 'Historical workstation owner or identity differs');
+            proposedWorkstationId = metadata.workstationId;
+            acquisition = { kind: 'reattach', expectedVersion: metadata.version };
+        }
+        const keys = generateKeyPair();
+        const request = requestSchema.parse({ protocol: 2, operationId: randomUUID(), proposedWorkstationId, clientPublicKey: keys.publicKey.toString('base64'), name: input.defaults.name, os: osInfo(), shell: input.defaults.shell, ...(input.defaults.workspace ? { defaultWorkspace: input.defaults.workspace } : {}), acquisition });
+        envelope = { schemaVersion: 1, state: 'pending', server: input.server, ownerUserId, registrationId: randomUUID(), requestDigest: requestDigest(request), request, clientPrivateKey: keys.privateKey.toString('base64') };
+        await pendingStore.write(envelope);
+    }
+    const pending = envelope;
+    try {
+        await fs.lstat(path.join(root, 'registrations', pending.registrationId, 'retired.json'));
+        throw new LocalControlError('BINDING_CONFLICT', 'The pending local identity was removed; verification is required');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    if (!await acquisitionMatches(store, pending))
+        throw enrollmentStorageError();
+    await options.afterStage?.('pending-persisted');
+    const response = responseSchema.safeParse(await requestJson(input, '/workstation/enroll', pending.request, true));
+    if (!response.success || response.data.operationId !== pending.request.operationId || response.data.workstationId !== pending.request.proposedWorkstationId || response.data.ownerUserId !== ownerUserId)
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Enrollment response could not be verified; retry with the saved request');
+    try {
+        deriveSessionKey(Buffer.from(pending.clientPrivateKey, 'base64'), Buffer.from(response.data.serverPub, 'base64'), Buffer.alloc(32), Buffer.alloc(32));
+    }
+    catch {
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Enrollment server key could not be verified; retry with the saved request');
+    }
+    assertLockOwnership();
+    const dataDirectory = path.join(root, 'registrations', pending.registrationId, 'data');
+    let registration;
+    try {
+        registration = await store.commit({ registration: { id: pending.registrationId, server: input.server, ownerUserId, workstationId: response.data.workstationId, dataDirectory, keeperConfigDirectory: dataDirectory }, clientKey: Buffer.from(pending.clientPrivateKey, 'base64'), serverPub: Buffer.from(response.data.serverPub, 'base64'), expectedRevision: null, configuration: { server: input.server, ownerUserId, workstationId: response.data.workstationId, workspaces: pending.request.defaultWorkspace ? [{ name: pending.request.defaultWorkspace.name, cwd: pending.request.defaultWorkspace.cwd }] : [] } });
+        await options.afterStage?.('after-local-commit');
+        await pendingStore.complete(pending, registration.revision);
+    }
+    catch {
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Local enrollment commit needs recovery; retry with the saved request');
+    }
+    return { operationId: input.operationId, registration, kind: pending.request.acquisition.kind === 'create' ? 'created' : 'reattached' };
+}
+export async function enrollRegistration(input, root, options = {}) {
+    let parsed;
+    try {
+        parsed = inputSchema.parse(input);
+        parsed.server = normalizeWorkstationServer(parsed.server);
+    }
+    catch {
+        throw new LocalControlError('BINDING_CONFLICT', 'Workstation enrollment inputs are invalid');
+    }
+    root = path.resolve(root);
+    try {
+        await enrollmentDirectory(root);
+        await enrollmentDirectory(root, path.join(root, 'control'));
+        try {
+            // The live lock owner publishes this file in place; its contents may still be growing.
+            const owner = await fs.lstat(path.join(root, 'control/operation.owner.json'));
+            if (!owner.isFile() || owner.nlink !== 1 || owner.size > 4096 || (owner.mode & 0o077) !== 0
+                || (process.getuid && owner.uid !== process.getuid()))
+                throw enrollmentStorageError();
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        return await withWorkstationLock(root, 'operation', () => enrollLocked(parsed, root, options));
+    }
+    catch (error) {
+        if (error instanceof LocalControlError)
+            throw error;
+        throw enrollmentStorageError();
+    }
+}