@platless/axom-cli 0.5.9 → 0.6.52

package/dist/workstation/rd/upkeep.js

@@ -0,0 +1,80 @@
+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;
+            const activate = this.pending;
+            await this.options.whenIdle(async () => {
+                if (this.stopped)
+                    return;
+                try {
+                    await activate();
+                }
+                finally {
+                    this.pending = undefined;
+                }
+                this.options.refresh();
+            });
+        }
+        catch (error) {
+            this.options.log?.(`[rd] automatic update failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            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'}`);
+                }
+            }
+        }
+    }
+    async stop() { this.stopped = true; await this.completion; if (this.original) {
+        await this.original.release();
+        this.original = undefined;
+    } }
+}

package/dist/workstation/register.js

@@ -1,46 +1,36 @@
-import { UsageError } from '../config.js';
-import { clientDir, loadClientConfig, saveClientConfig, writeKeys } from './config.js';
+import { randomUUID } from 'node:crypto';
+import { clientDir } from './config.js';
 import { osInfo } from './osinfo.js';
-export async function registerWorkstation(server, clientName, token, ws) {
-    const dir = clientDir();
-    const existing = await loadClientConfig(dir).catch(() => undefined);
-    const body = {
-        name: clientName,
-        ...(existing?.server === server ? { workstationId: existing.workstationId } : {}),
-        os: osInfo(),
-        defaultWorkspace: { name: ws.name, cwd: ws.cwd, shell: ws.shell },
-    };
+import { workstationEndpoint } from './control/serverIdentity.js';
+import { LocalControlError } from './control/protocol.js';
+import { z } from 'zod';
+export const registerResponseSchema = z.object({ workstationId: z.string().min(1), ownerUserId: z.string().min(1).optional(), clientKey: z.string(), serverPub: z.string() });
+/** No persistence; callers own the operation lock and identity transaction. */
+export async function requestWorkstationRegistration(server, clientName, token, ws, workstationId, shell = ws?.shell ?? '/bin/sh') {
     let res;
     try {
-        res = await fetch(new URL('/workstation/register', server), {
-            method: 'POST',
+        res = await fetch(workstationEndpoint(server, '/workstation/register'), { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(30_000),
             headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
-            body: JSON.stringify(body),
+            body: JSON.stringify({ name: clientName, ...(workstationId ? { workstationId } : {}), os: osInfo(), shell, ...(ws ? { defaultWorkspace: ws } : {}) }),
         });
     }
-    catch (err) {
-        throw new Error(`Failed to reach ${server}/workstation/register: ${err instanceof Error ? err.message : err}`);
+    catch {
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Registration was sent but its outcome could not be confirmed. Check your workstation list before trying again.');
+    }
+    if (res.status === 409)
+        throw new LocalControlError('BINDING_CONFLICT', 'A workstation with this name is already registered. Check Settings → Workstations.');
+    if (res.status === 401 || res.status === 403)
+        throw new LocalControlError('AUTHORIZATION_REQUIRED', 'Workstation permission is required. Run `axom auth` and select workstation, then try again.');
+    if (!res.ok)
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Registration could not be confirmed. Check your workstation list.');
+    try {
+        return registerResponseSchema.parse(await res.json());
     }
-    if (!res.ok) {
-        // A workstation with this name is already registered for this account — most commonly because
-        // this same machine registered before an axom-cli upgrade and no longer has a local config at
-        // the new config-directory path (see the client's move from ~/.axom-workstation to
-        // ~/.axom/workstation). Rebinding the existing row silently would hand this machine's identity
-        // to whichever caller re-registers next, so the server refuses instead of upserting.
-        if (res.status === 409) {
-            throw new UsageError(`A workstation named '${clientName}' is already registered for this account. This is expected `
-                + `when the same machine re-registers after an axom-cli upgrade. Delete it under Settings → `
-                + 'Workstations, then run `axom workstation start` again.');
-        }
-        if (res.status === 403) {
-            throw new UsageError('This credential is not authorized to register a workstation. '
-                + 'Run `axom auth` and select workstation, then try again.');
-        }
-        throw new Error(`Registration failed: ${res.status} ${await res.text()}`);
+    catch {
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Registration response was incomplete. Check your workstation list.');
     }
-    const data = (await res.json());
-    if (!data.workstationId)
-        throw new Error('Registration response missing workstationId');
-    await saveClientConfig(dir, { server, workstationId: data.workstationId, workspaces: [{ name: ws.name, cwd: ws.cwd }] });
-    await writeKeys(dir, data.clientKey, data.serverPub);
+}
+export async function registerWorkstation(server, clientName, token, ws) {
+    const { enrollLegacyWorkstation } = await import('./control/enrollment.js');
+    await enrollLegacyWorkstation({ server, name: clientName, accessToken: token, workspace: ws, operationId: randomUUID() }, clientDir());
 }

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();
+    }
+}