@platless/axom-cli 0.6.36 → 0.6.52

package/dist/workstation/keepers/terminal/sessions.js

@@ -0,0 +1,526 @@
+import { randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { KeeperMethodError } from '../kit/protocol.js';
+import { TERMINAL_GRID_LIMITS as limits, } from './gridProtocol.js';
+import { TerminalFrames } from './frames.js';
+import { TerminalScreen } from './screen.js';
+import { createTerminalInput } from './input.js';
+import { createTerminalMetadata } from './metadata.js';
+export const NATIVE_PTY_OPERATIONS = new Set(['attach', 'poll', 'resize', 'input', 'scroll', 'detach', 'close']);
+const bad = (message) => { throw new KeeperMethodError('bad_request', message); };
+const fail = (code, message) => { throw new KeeperMethodError(code, message); };
+const ok = { ok: true };
+const nativeScheduler = {
+    schedule(callback, delay) { const timer = setTimeout(callback, delay); timer.unref(); return { dispose: () => clearTimeout(timer) }; },
+};
+const basename = (name) => path.basename(name.trim()).replace(/^-/, '');
+/** Keeper-owned sessions: ordered within a PTY, independent between PTYs. */
+export class NativePtySessions {
+    options;
+    sessions = new Map();
+    now;
+    scheduler;
+    module;
+    unavailable;
+    disposed = false;
+    constructor(options = {}) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+        this.scheduler = options.scheduler ?? nativeScheduler;
+        try {
+            this.module = (options.loadPty ?? (() => createRequire(import.meta.url)('node-pty')))();
+        }
+        catch {
+            this.unavailable = 'Terminal native dependency unavailable; reinstall CLI with optional node-pty support';
+        }
+    }
+    list() {
+        return { schema: 1, limits: { ...limits }, sessions: [...this.sessions.values()].map(s => this.descriptor(s)) };
+    }
+    async create(params, launch) {
+        this.available();
+        request(params);
+        keys(params, ['id', 'cwd', 'registrationId']);
+        const id = identifier(params, 'id');
+        if (params.registrationId !== undefined)
+            identifier(params, 'registrationId');
+        if (params.cwd !== undefined && (typeof params.cwd !== 'string' || params.cwd.includes('\0')))
+            bad('Invalid cwd');
+        const existing = this.sessions.get(id);
+        if (existing)
+            return this.descriptor(existing);
+        this.checkLimit();
+        const resolved = await launch();
+        this.available();
+        const concurrent = this.sessions.get(id);
+        if (concurrent)
+            return this.descriptor(concurrent);
+        this.checkLimit();
+        const cols = 100;
+        const rows = 30;
+        const screen = new TerminalScreen(cols, rows);
+        let pty;
+        try {
+            pty = this.module.spawn(resolved.shell, ['-l'], { name: 'xterm-256color', cwd: resolved.cwd, cols, rows, env: { ...resolved.env, TERM: 'xterm-256color', COLORTERM: 'truecolor' } });
+        }
+        catch (error) {
+            screen.dispose();
+            throw error;
+        }
+        const createdAt = this.now();
+        const shell = basename(resolved.shell);
+        const s = {
+            value: { id, ...(typeof params.registrationId === 'string' ? { registrationId: params.registrationId } : {}), incarnation: randomUUID(), title: 'Terminal', cwd: resolved.cwd, cwdSource: 'launch', cols, rows, createdAt, exited: false, exitCode: null },
+            shell, shellNames: new Set([shell]), shellNameStarted: false, pty, screen, frames: new TerminalFrames(), attachments: new Map(), geometry: 1,
+            closed: false, queue: Promise.resolve(), rendered: Promise.resolve(), pendingBytes: 0, dirty: true, capturedAt: -Infinity,
+            listeners: [], input: createTerminalInput(screen), exitedAt: 0, observed: { label: shell, state: 'idle', since: createdAt },
+        };
+        const context = { pty, screen, session: () => this.descriptor(s), changed: () => this.dirty(s) };
+        try {
+            s.input = this.options.createInput?.(context) ?? s.input;
+            s.metadata = (this.options.createMetadata ?? createTerminalMetadata)(context);
+            this.capture(s, true);
+            s.listeners.push(disposable(pty.onData(data => this.output(s, data))), disposable(pty.onExit(event => {
+                if (s.closed)
+                    return;
+                s.shellNameTimer?.dispose();
+                s.shellNameTimer = undefined;
+                s.value.exited = true;
+                s.value.exitCode = event.exitCode;
+                s.exitedAt = this.now();
+                this.dirty(s);
+            })), screen.onReply(data => { if (!s.closed && !s.value.exited) {
+                try {
+                    pty.write(data);
+                }
+                catch (error) {
+                    this.failed(s, error);
+                }
+            } }));
+            this.sessions.set(id, s);
+        }
+        catch (error) {
+            await this.close(s);
+            throw error;
+        }
+        return this.descriptor(s);
+    }
+    async operate(op, params) {
+        request(params);
+        const id = identifier(params, 'id');
+        const incarnation = identifier(params, 'incarnation');
+        const s = this.sessions.get(id);
+        if (!s) {
+            if (op === 'close' || op === 'detach')
+                return ok;
+            return fail('pty_not_found', 'Terminal session not found; keeper restart loses live PTYs');
+        }
+        if (s.value.incarnation !== incarnation)
+            return fail('pty_incarnation_mismatch', 'Terminal incarnation no longer matches');
+        return this.ordered(s, async () => {
+            if (s.closed) {
+                if (op === 'close' || op === 'detach')
+                    return ok;
+                return fail('pty_not_found', 'Terminal session is closed');
+            }
+            if (op === 'close') {
+                keys(params, ['id', 'incarnation']);
+                await this.close(s);
+                return ok;
+            }
+            await this.expire(s);
+            const clientId = identifier(params, 'clientId');
+            const ref = ['id', 'incarnation', 'clientId'];
+            if (op === 'detach') {
+                keys(params, ref);
+                this.release(s, clientId);
+                await this.capacity(s);
+                return ok;
+            }
+            if (op === 'attach') {
+                keys(params, [...ref, 'cols', 'rows']);
+                const cols = integer(params, 'cols', limits.minCols, limits.maxCols);
+                const rows = integer(params, 'rows', limits.minRows, limits.maxRows);
+                if (!s.attachments.has(clientId) && s.attachments.size >= limits.maxAttachments)
+                    return fail('pty_limit', 'Terminal attachment limit exceeded');
+                const previous = s.attachments.get(clientId);
+                s.attachments.set(clientId, { cols, rows, expires: this.now() + limits.leaseMs });
+                try {
+                    await this.capacity(s);
+                    await this.settle(s);
+                    this.capture(s, true);
+                }
+                catch (error) {
+                    if (previous)
+                        s.attachments.set(clientId, previous);
+                    else
+                        this.release(s, clientId);
+                    try {
+                        await this.capacity(s);
+                    }
+                    catch (rollback) {
+                        this.failed(s, rollback);
+                    }
+                    throw error;
+                }
+                this.scheduleLease(s);
+                return s.frames.poll(0);
+            }
+            const attachment = s.attachments.get(clientId);
+            if (!attachment)
+                return fail('pty_attachment_expired', 'Terminal attachment expired; attach again');
+            if (op === 'poll') {
+                keys(params, [...ref, 'after']);
+                const after = integer(params, 'after', 0, Number.MAX_SAFE_INTEGER);
+                attachment.expires = this.now() + limits.leaseMs;
+                this.scheduleLease(s);
+                await this.captureDue(s);
+                return s.frames.poll(after);
+            }
+            if (op === 'resize') {
+                keys(params, [...ref, 'cols', 'rows']);
+                const cols = integer(params, 'cols', limits.minCols, limits.maxCols);
+                const rows = integer(params, 'rows', limits.minRows, limits.maxRows);
+                const previous = { ...attachment };
+                attachment.cols = cols;
+                attachment.rows = rows;
+                try {
+                    await this.capacity(s);
+                }
+                catch (error) {
+                    Object.assign(attachment, previous);
+                    throw error;
+                }
+            }
+            else if (op === 'input') {
+                const event = input(params, ref);
+                await this.settle(s);
+                this.assertRunning(s);
+                if (event.kind === 'pointer' || event.kind === 'button')
+                    this.coordinates(s, event);
+                const data = s.input.input(event, clientId, this.inputContext(s));
+                if (data)
+                    s.pty.write(data);
+            }
+            else if (op === 'scroll') {
+                keys(params, [...ref, 'lines', 'x', 'y', 'modifiers', 'geometry']);
+                const gesture = { lines: integer(params, 'lines', -Number.MAX_SAFE_INTEGER, Number.MAX_SAFE_INTEGER), ...position(params), modifiers: integer(params, 'modifiers', 0, 15) };
+                await this.settle(s);
+                this.coordinates(s, gesture);
+                const data = s.input.scroll(gesture, clientId, this.inputContext(s));
+                if (data) {
+                    this.assertRunning(s);
+                    s.pty.write(data);
+                }
+                else if (data === undefined && s.screen.state().buffer === 'normal') {
+                    s.screen.scroll(gesture.lines);
+                    this.dirty(s);
+                }
+            }
+            else
+                return bad('Unsupported terminal operation');
+            attachment.expires = this.now() + limits.leaseMs;
+            this.scheduleLease(s);
+            return ok;
+        });
+    }
+    activity() {
+        const metrics = { ptyOpen: 0, ptyActive: 0, ptyExited: 0 };
+        const items = [...this.sessions.values()].map(s => {
+            if (s.value.exited) {
+                metrics.ptyExited++;
+                return { type: 'pty', id: s.value.id, label: s.shell.slice(0, 64), state: 'exited', sinceEpochMs: s.exitedAt };
+            }
+            metrics.ptyOpen++;
+            let foreground = '';
+            try {
+                foreground = basename(s.pty.process);
+            }
+            catch { /* process can disappear during exit */ }
+            const active = foreground !== '' && !s.shellNames.has(foreground);
+            const label = (active ? foreground : s.shell).slice(0, 64);
+            const state = active ? 'active' : 'idle';
+            if (active)
+                metrics.ptyActive++;
+            if (s.observed.label !== label || s.observed.state !== state)
+                s.observed = { label, state, since: this.now() };
+            return { type: 'pty', id: s.value.id, label, state, sinceEpochMs: s.observed.since };
+        });
+        return { metrics, items };
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        await Promise.all([...this.sessions.values()].map(s => this.ordered(s, () => this.close(s))));
+    }
+    descriptor(s) { return { ...s.value, ...s.metadata?.read() }; }
+    available() {
+        if (this.disposed)
+            fail('pty_unavailable', 'Terminal host is disposed');
+        if (!this.module)
+            fail('pty_unavailable', this.unavailable ?? 'Terminal native dependency unavailable');
+    }
+    checkLimit() { if (this.sessions.size >= limits.maxSessions)
+        fail('pty_limit', 'Terminal session limit exceeded'); }
+    scheduleShellName(s, attempt = 0) {
+        const live = () => !s.closed && !s.value.exited && !this.disposed;
+        if (!live())
+            return;
+        s.shellNameTimer = this.scheduler.schedule(() => {
+            s.shellNameTimer = undefined;
+            if (!live())
+                return;
+            const retry = () => { if (attempt < 2)
+                this.scheduleShellName(s, attempt + 1); };
+            // Query the original shell PID: the foreground process may be a running command.
+            void Promise.resolve().then(() => live() ? (this.options.shellProcessName ?? defaultShellProcessName)(s.pty.pid) : null).then(name => {
+                if (!live())
+                    return;
+                const shell = name && basename(name);
+                if (shell && shell !== 'spawn-helper')
+                    s.shellNames.add(shell);
+                else
+                    retry();
+            }, retry);
+        }, this.options.shellNameDelayMs ?? 250);
+    }
+    ordered(s, action) {
+        const operation = s.queue.then(action);
+        s.queue = operation.catch(() => { });
+        return operation;
+    }
+    async settle(s) {
+        for (;;) {
+            const rendered = s.rendered;
+            await rendered;
+            if (rendered === s.rendered)
+                break;
+        }
+        if (s.failure)
+            throw s.failure;
+    }
+    output(s, data) {
+        if (s.closed || !data || s.failure)
+            return;
+        // node-pty initially runs a spawn-helper trampoline at this PID. First output
+        // starts the bounded lookup after shell startup, once per session.
+        if (!s.shellNameStarted) {
+            s.shellNameStarted = true;
+            this.scheduleShellName(s);
+        }
+        const bytes = Buffer.byteLength(data);
+        s.pendingBytes += bytes;
+        try {
+            if (s.pendingBytes > 256 * 1024)
+                s.pty.pause();
+            s.metadata?.onData?.(data);
+            // Submit directly to xterm's ordered parser; chaining writes costs one timer per PTY chunk.
+            s.rendered = s.screen.write(data);
+            void s.rendered.then(() => {
+                s.pendingBytes -= bytes;
+                try {
+                    if (!s.closed && !s.value.exited && s.pendingBytes < 64 * 1024)
+                        s.pty.resume();
+                }
+                catch (error) {
+                    this.failed(s, error);
+                }
+                this.dirty(s);
+            }, error => this.failed(s, error));
+            this.dirty(s);
+        }
+        catch (error) {
+            this.failed(s, error);
+        }
+    }
+    failed(s, error) { if (!s.closed) {
+        s.failure = error;
+        s.captureTimer?.dispose();
+        s.captureTimer = undefined;
+    } }
+    dirty(s) {
+        if (s.closed || s.failure)
+            return;
+        s.dirty = true;
+        if (!s.captureTimer)
+            s.captureTimer = this.scheduler.schedule(() => {
+                s.captureTimer = undefined;
+                void this.ordered(s, async () => { if (s.closed)
+                    return; await this.settle(s); this.capture(s); }).catch(error => { if (!(error instanceof KeeperMethodError && error.code === 'pty_snapshot_too_large'))
+                    this.failed(s, error); });
+            }, Math.max(0, 50 - (this.now() - s.capturedAt)));
+    }
+    async captureDue(s) {
+        if (s.dirty && this.now() - s.capturedAt < 50) {
+            s.captureTimer?.dispose();
+            s.captureTimer = undefined;
+            await new Promise(resolve => this.scheduler.schedule(resolve, 50 - (this.now() - s.capturedAt)));
+        }
+        await this.settle(s);
+        this.capture(s, true);
+    }
+    capture(s, force = false) {
+        if (!s.dirty || (!force && this.now() - s.capturedAt < 50))
+            return;
+        s.frames.publish(s.screen.capture(), this.descriptor(s), s.geometry);
+        s.dirty = false;
+        s.capturedAt = this.now();
+        s.captureTimer?.dispose();
+        s.captureTimer = undefined;
+    }
+    async capacity(s) {
+        if (!s.attachments.size)
+            return;
+        const cols = Math.min(...[...s.attachments.values()].map(a => a.cols));
+        const rows = Math.min(...[...s.attachments.values()].map(a => a.rows));
+        if (cols === s.value.cols && rows === s.value.rows)
+            return;
+        await this.settle(s);
+        if (!s.value.exited)
+            s.pty.resize(cols, rows);
+        try {
+            await s.screen.resize(cols, rows);
+            await this.settle(s);
+        }
+        catch (error) {
+            // A native emulator failure may have changed part of the grid. Never publish or accept input against uncertain geometry.
+            this.failed(s, error);
+            try {
+                if (!s.value.exited)
+                    s.pty.resize(s.value.cols, s.value.rows);
+            }
+            catch (rollback) {
+                this.failed(s, rollback);
+            }
+            throw error;
+        }
+        s.value.cols = cols;
+        s.value.rows = rows;
+        s.geometry++;
+        this.dirty(s);
+    }
+    inputContext(s) { return { cols: s.value.cols, rows: s.value.rows, geometry: s.geometry, modes: s.screen.state().modes }; }
+    coordinates(s, event) {
+        if (event.geometry !== s.geometry)
+            fail('pty_geometry_mismatch', 'Terminal geometry changed');
+        if (event.x >= s.value.cols || event.y >= s.value.rows)
+            bad('Terminal coordinates outside geometry');
+    }
+    assertRunning(s) { if (s.value.exited)
+        fail('pty_exited', 'Terminal has exited'); }
+    release(s, clientId) {
+        if (s.attachments.delete(clientId))
+            s.input.release(clientId);
+        this.scheduleLease(s);
+    }
+    async expire(s) {
+        let changed = false;
+        for (const [id, attachment] of s.attachments)
+            if (attachment.expires <= this.now()) {
+                this.release(s, id);
+                changed = true;
+            }
+        if (changed)
+            await this.capacity(s);
+    }
+    scheduleLease(s) {
+        s.leaseTimer?.dispose();
+        s.leaseTimer = undefined;
+        if (s.closed || this.disposed || !s.attachments.size)
+            return;
+        const expires = Math.min(...[...s.attachments.values()].map(attachment => attachment.expires));
+        s.leaseTimer = this.scheduler.schedule(() => {
+            s.leaseTimer = undefined;
+            void this.ordered(s, () => this.expire(s)).catch(error => this.failed(s, error)).finally(() => this.scheduleLease(s));
+        }, Math.max(0, expires - this.now()));
+    }
+    async close(s) {
+        if (s.closed)
+            return;
+        s.closed = true;
+        if (this.sessions.get(s.value.id) === s)
+            this.sessions.delete(s.value.id);
+        s.shellNameTimer?.dispose();
+        s.shellNameTimer = undefined;
+        s.captureTimer?.dispose();
+        s.captureTimer = undefined;
+        s.leaseTimer?.dispose();
+        s.leaseTimer = undefined;
+        for (const listener of s.listeners)
+            listener.dispose();
+        for (const id of [...s.attachments.keys()])
+            this.release(s, id);
+        s.input.dispose();
+        s.metadata?.dispose?.();
+        try {
+            if (!s.value.exited)
+                s.pty.kill();
+        }
+        finally {
+            s.screen.dispose();
+            await s.rendered.catch(() => { });
+        }
+    }
+}
+function disposable(value) {
+    return value && typeof value.dispose === 'function' ? value : { dispose: () => { } };
+}
+function request(params) { if (Buffer.byteLength(JSON.stringify(params)) > limits.maxRequestBytes)
+    bad('Terminal request exceeds limit'); }
+function keys(params, allowed) { if (Object.keys(params).some(key => !allowed.includes(key)))
+    bad('Unexpected terminal parameter'); }
+function identifier(params, name) {
+    const value = params[name];
+    if (typeof value !== 'string' || !/^[A-Za-z0-9_.:-]{1,128}$/.test(value))
+        return bad(`Invalid ${name}`);
+    return value;
+}
+function integer(params, name, min, max) {
+    const value = params[name];
+    if (!Number.isSafeInteger(value) || value < min || value > max)
+        return bad(`Invalid ${name}`);
+    return value;
+}
+function position(params) {
+    return { x: integer(params, 'x', 0, limits.maxCols - 1), y: integer(params, 'y', 0, limits.maxRows - 1), geometry: integer(params, 'geometry', 1, Number.MAX_SAFE_INTEGER) };
+}
+function input(params, ref) {
+    switch (params.kind) {
+        case 'text':
+        case 'paste':
+            keys(params, [...ref, 'kind', 'text']);
+            if (typeof params.text !== 'string' || Buffer.byteLength(params.text) > limits.maxInputBytes)
+                return bad('Terminal input exceeds limit');
+            return { kind: params.kind, text: params.text };
+        case 'key':
+            keys(params, [...ref, 'kind', 'usage', 'down', 'modifiers']);
+            if (typeof params.down !== 'boolean')
+                return bad('Invalid down');
+            return { kind: 'key', usage: integer(params, 'usage', 0, 65535), down: params.down, modifiers: integer(params, 'modifiers', 0, 15) };
+        case 'pointer':
+        case 'button': {
+            keys(params, [...ref, 'kind', 'x', 'y', 'geometry', 'modifiers', ...(params.kind === 'button' ? ['button', 'down'] : [])]);
+            const point = { ...position(params), modifiers: integer(params, 'modifiers', 0, 15) };
+            if (params.kind === 'pointer')
+                return { kind: 'pointer', ...point };
+            if (typeof params.down !== 'boolean')
+                return bad('Invalid down');
+            return { kind: 'button', ...point, button: integer(params, 'button', 0, 2), down: params.down };
+        }
+        case 'release':
+            keys(params, [...ref, 'kind']);
+            return { kind: 'release' };
+        default: return bad('Invalid terminal input kind');
+    }
+}
+/** This lookup is never awaited by poll/input/activity and never exposes process arguments. */
+function defaultShellProcessName(pid) {
+    if (process.platform !== 'darwin')
+        return Promise.resolve(null);
+    return new Promise(resolve => {
+        execFile('ps', ['-o', 'ucomm=', '-p', String(pid)], { timeout: 1000 }, (error, stdout) => resolve(error ? null : stdout.trim() || null));
+    });
+}

package/dist/workstation/oauth/deviceAuthorization.js

@@ -42,8 +42,11 @@ function requireString(value, field, description) {
         throw new DeviceAuthorizationError(`${description} missing ${field}`);
     return value;
 }
-function websocketUrl(server) {
-    const url = new URL('/oauth/device/ws', server);
+function deviceEndpoint(server, endpoint, identity) {
+    return identity ? new URL(server + endpoint) : new URL(endpoint, server);
+}
+function websocketUrl(server, identity) {
+    const url = deviceEndpoint(server, '/oauth/device/ws', identity);
     url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
     return url.toString();
 }
@@ -89,23 +92,33 @@ function waitForNotification(socket, sessionId, notificationTicket, deadline, no
         socket.on('error', () => finish('reconnect'));
     });
 }
-async function exchangeDeviceCode(server, clientId, deviceCode, fetch_, requestedScopes) {
-    const response = await requestJson(fetch_, new URL('/oauth/token', server), {
+async function exchangeDeviceCode(server, clientId, deviceCode, fetch_, requestedScopes, identity) {
+    const response = await requestJson(fetch_, deviceEndpoint(server, '/oauth/token', identity), {
         method: 'POST',
         headers: { 'content-type': 'application/x-www-form-urlencoded' },
         body: new URLSearchParams({
             grant_type: DEVICE_CODE_GRANT_TYPE,
             client_id: clientId,
             device_code: deviceCode,
-            device_id: await loadDeviceId(),
+            device_id: identity?.deviceId ?? await loadDeviceId(),
         }),
     }, 200, 'Device token exchange');
-    return validateTokenResponse(server, response, requestedScopes, fetch_);
+    return validateTokenResponse(server, response, requestedScopes, fetch_, identity);
 }
-async function validateTokenResponse(server, response, requestedScopes, fetch_) {
-    const accessToken = requireString(response.access_token, 'access_token', 'Device token response');
+async function validateTokenResponse(server, response, requestedScopes, fetch_, identity) {
+    let accessToken;
+    try {
+        accessToken = requireString(response.access_token, 'access_token', 'Device token response');
+    }
+    catch (error) {
+        if (identity && typeof response.refresh_token === 'string' && response.refresh_token)
+            await revokeRefreshToken(server, response.refresh_token, fetch_);
+        throw error;
+    }
     const refreshToken = requireString(response.refresh_token, 'refresh_token', 'Device token response');
     if (!Number.isFinite(response.expires_in) || response.expires_in <= 0) {
+        if (identity)
+            await revokeRefreshToken(server, refreshToken, fetch_);
         throw new DeviceAuthorizationError('Device token response has invalid expires_in');
     }
     let scopes;
@@ -118,15 +131,15 @@ async function validateTokenResponse(server, response, requestedScopes, fetch_)
     }
     return { accessToken, refreshToken, expiresInSeconds: response.expires_in, scopes };
 }
-async function pollDeviceCode(server, clientId, deviceCode, fetch_, requestedScopes) {
-    const response = await fetch_(new URL('/oauth/token', server), {
+async function pollDeviceCode(server, clientId, deviceCode, fetch_, requestedScopes, identity) {
+    const response = await fetch_(deviceEndpoint(server, '/oauth/token', identity), {
         method: 'POST',
         headers: { 'content-type': 'application/x-www-form-urlencoded' },
         body: new URLSearchParams({
             grant_type: DEVICE_CODE_GRANT_TYPE,
             client_id: clientId,
             device_code: deviceCode,
-            device_id: await loadDeviceId(),
+            device_id: identity?.deviceId ?? await loadDeviceId(),
         }),
     });
     if (response.status === 400) {
@@ -141,13 +154,13 @@ async function pollDeviceCode(server, clientId, deviceCode, fetch_, requestedSco
     if (response.status !== 200)
         throw new DeviceAuthorizationError(`Device token polling failed: ${response.status}`);
     const token = await response.json();
-    return validateTokenResponse(server, token, requestedScopes, fetch_);
+    return validateTokenResponse(server, token, requestedScopes, fetch_, identity);
 }
 /**
  * Uses OAuth Device Authorization for both desktop and headless clients. The notification socket
  * only carries state; the tokens exist only in this call's return value.
  */
-export async function authorizeDevice(server, clientName, hostname, deps = {}, requestedScopes = DEFAULT_CLI_SCOPES) {
+export async function authorizeDevice(server, clientName, hostname, deps = {}, requestedScopes = DEFAULT_CLI_SCOPES, identity) {
     const baseUrl = normalizedServer(server);
     const fetch_ = deps.fetch ?? globalThis.fetch;
     const print = deps.print ?? console.log;
@@ -155,9 +168,10 @@ export async function authorizeDevice(server, clientName, hostname, deps = {}, r
     const createWebSocket = deps.createWebSocket ?? ((url) => new WebSocket(url));
     const now = deps.now ?? Date.now;
     const wait = deps.sleep ?? sleep;
+    const flowIdentity = identity ? Object.freeze({ deviceId: requireString(identity.deviceId, 'deviceId', 'Device authorization identity') }) : undefined;
     void clientName;
     const clientId = 'axom-cli';
-    const authorization = await requestJson(fetch_, new URL('/oauth/device_authorization', baseUrl), {
+    const authorization = await requestJson(fetch_, deviceEndpoint(baseUrl, '/oauth/device_authorization', flowIdentity), {
         method: 'POST',
         headers: { 'content-type': 'application/x-www-form-urlencoded' },
         body: new URLSearchParams({ client_id: clientId, hostname, scope: requestedScopes.join(' ') }),
@@ -176,7 +190,7 @@ export async function authorizeDevice(server, clientName, hostname, deps = {}, r
     while (now() < deadline) {
         let socket;
         try {
-            socket = createWebSocket(websocketUrl(baseUrl));
+            socket = createWebSocket(websocketUrl(baseUrl, flowIdentity));
         }
         catch {
             const delay = Math.min(retry.recordFailure(), Math.max(0, deadline - now()));
@@ -187,14 +201,14 @@ export async function authorizeDevice(server, clientName, hostname, deps = {}, r
         }
         const status = await waitForNotification(socket, sessionId, notificationTicket, deadline, now, () => retry.recordSuccess());
         if (status === 'approved') {
-            const tokens = await exchangeDeviceCode(baseUrl, clientId, deviceCode, fetch_, requestedScopes);
+            const tokens = await exchangeDeviceCode(baseUrl, clientId, deviceCode, fetch_, requestedScopes, flowIdentity);
             return { clientId, ...tokens };
         }
         if (status === 'denied')
             throw new DeviceAuthorizationError('Device authorization was denied');
         if (status === 'expired')
             break;
-        const polled = await pollDeviceCode(baseUrl, clientId, deviceCode, fetch_, requestedScopes);
+        const polled = await pollDeviceCode(baseUrl, clientId, deviceCode, fetch_, requestedScopes, flowIdentity);
         if (polled)
             return { clientId, ...polled };
         const pollingFloor = Math.max(1, authorization.interval ?? 5) * 1_000;