diff --git a/packages/plugin/src/server-credentials.ts b/packages/plugin/src/server-credentials.ts new file mode 100644 index 0000000..40704a2 --- /dev/null +++ b/packages/plugin/src/server-credentials.ts @@ -0,0 +1,266 @@ +import { chmod, link, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises' +import { basename, dirname, join, sep } from 'node:path' +import { z } from 'zod' +import { uuidV7 } from './ids.js' + +const credentialSchema = z.object({ + schemaVersion: z.literal(1), + serverUrl: z.string().url(), + deviceId: z.string().min(1), + authorizationMethod: z.enum(['account', 'host_registration_code', 'owned_device', 'device_pairing']), + accountKind: z.enum(['standard', 'device_only']).optional(), + pairingRestricted: z.boolean().optional(), + inboundOnly: z.boolean().optional(), + account: z.string().min(1).max(254).optional(), + accessToken: z.string().min(16), + accessTokenExpiresAt: z.number().int().positive(), + refreshToken: z.string().min(16), + refreshTokenExpiresAt: z.number().int().positive(), +}).strict() + +export interface ServerCredentials extends z.infer {} + +export class ServerCredentialStore { + private readonly path: string + + constructor(directory: string) { this.path = join(directory, 'server-credentials.json') } + + /** Each process owns one queue record. A dead process cannot hold the queue. */ + async withRefreshLock(operation: () => Promise): Promise { + const gate = defaultMigrationGate(dirname(this.path)) + const run = () => withQueueLock(`${this.path}.refresh-lock`, operation) + return gate === undefined ? run() : withQueueLock(gate, run) + } + + async pairingHostOnly(): Promise { + const policy = await readPrivateJson(join(dirname(this.path), 'pairing-host-only.json')) + if (policy === undefined) return false + z.object({ hostOnly: z.literal(true) }).strict().parse(policy) + return true + } + + async restrictPairingHostOnly(): Promise { + await atomicWritePrivate(join(dirname(this.path), 'pairing-host-only.json'), '{"hostOnly":true}') + } + + async load(serverUrl: string, deviceId: string): Promise { + if (!(await exists(this.path))) return undefined + await assertPrivateMode(this.path) + let parsed: ServerCredentials + try { + parsed = credentialSchema.parse(JSON.parse(await readFile(this.path, 'utf8'))) + } catch (error) { + throw new ServerCredentialsInvalidError(`server credentials are invalid: ${safeMessage(error)}`) + } + return parsed.serverUrl === serverUrl && parsed.deviceId === deviceId ? parsed : undefined + } + + async save(credentials: Omit): Promise { + const record = credentialSchema.parse({ schemaVersion: 1, ...credentials }) + await atomicWritePrivate(this.path, `${JSON.stringify(record, null, 2)}\n`) + return record + } + + async clear(): Promise { + await rm(this.path, { force: true }) + } +} + +function defaultMigrationGate(directory: string): string | undefined { + const parts = directory.split(sep) + let rootIndex = -1 + for (let index = parts.length - 1; index >= 0; index--) { + if ((parts[index] === 'remote' || parts[index] === 'ds-harness-remote') + && (index === parts.length - 1 || parts[index + 1] === 'servers')) { + rootIndex = index + break + } + } + if (rootIndex < 1) return undefined + const suffix = parts.slice(rootIndex + 1) + if (suffix.length !== 0 && (suffix.length !== 3 || suffix[0] !== 'servers' + || !/^[a-f0-9]{24}$/.test(suffix[1]!) || !['host', 'client'].includes(suffix[2]!))) return undefined + return join(parts.slice(0, rootIndex).join(sep) || sep, '.ds-harness-remote-migration', 'credential-refresh-gate') +} + +export function withDefaultCredentialMigrationGate(home: string, operation: () => Promise): Promise { + return withQueueLock(join(home, '.ds-harness-remote-migration', 'credential-refresh-gate'), operation) +} + +export async function assertRefreshQueueIdle(directory: string): Promise { + const lock = join(directory, 'server-credentials.json.refresh-lock') + const marker = await readQueueMarker(lock) + if (marker === undefined) { + if ((await readdir(directory)).some(name => name.startsWith(`${basename(lock)}.holder-`) && !name.endsWith('.tmp'))) { + throw new ServerCredentialsBusyError() + } + return + } + if (marker !== SERVER_CREDENTIALS_QUEUE_MARKER) throw new ServerCredentialsBusyError() + if ((await participants(lock)).length > 0) throw new ServerCredentialsBusyError() +} + +async function withQueueLock(lock: string, operation: () => Promise): Promise { + await mkdir(dirname(lock), { recursive: true, mode: 0o700 }) + const deadline = Date.now() + 15_000 + await ensureQueueMarker(lock, deadline) + const id = `${process.pid}-${uuidV7()}` + const holder = `${lock}.holder-${id}` + // Publish intent first. A later contender must see this record before it chooses a ticket. + await publishExclusive(holder, `${id} choosing\n`) + try { + const ticket = 1 + (await participants(lock)).reduce((max, entry) => Math.max(max, entry.ticket ?? 0), 0) + if (!Number.isSafeInteger(ticket)) throw new ServerCredentialsBusyError() + await atomicWritePrivate(holder, `${id} ${ticket}\n`) + for (;;) { + const entries = await participants(lock) + const preceding = entries.some(entry => entry.id !== id && (entry.ticket === undefined + || entry.ticket < ticket || (entry.ticket === ticket && entry.id < id))) + if (!preceding) break + if (Date.now() >= deadline) throw new ServerCredentialsBusyError() + await new Promise(resolve => setTimeout(resolve, 50)) + } + return await operation() + } finally { + await rm(holder, { force: true }) + } +} + +export class ServerCredentialsInvalidError extends Error { + readonly code = 'SERVER_CREDENTIALS_INVALID' +} + +export class ServerCredentialsBusyError extends Error { + readonly code = 'SERVER_CREDENTIALS_BUSY' + constructor() { + super('Credential refresh is busy. Stop other instances. Remove a legacy refresh lock only after every instance stops.') + } +} + +export class ServerCredentialsLockUnsupportedError extends Error { + readonly code = 'SERVER_CREDENTIALS_LOCK_UNSUPPORTED' + constructor() { + super('Credential lock cannot create a hard link in DSH_HOME. Use a writable local ext4 or XFS file system.') + } +} + +export const SERVER_CREDENTIALS_QUEUE_MARKER = 'DSH_REFRESH_LOCK_V2\n' + +async function ensureQueueMarker(lock: string, deadline: number): Promise { + // Old versions use this path as their lock. Keep them outside the new queue. + for (;;) { + try { + await publishExclusive(lock, SERVER_CREDENTIALS_QUEUE_MARKER) + return + } catch (error) { + if (!(await isLockContention(error, lock))) throw error + if (await readQueueMarker(lock) === SERVER_CREDENTIALS_QUEUE_MARKER) return + if (Date.now() >= deadline) throw new ServerCredentialsBusyError() + await new Promise(resolve => setTimeout(resolve, 50)) + } + } +} + +interface QueueParticipant { id: string; ticket?: number } + +async function participants(lock: string): Promise { + const prefix = `${basename(lock)}.holder-` + const entries = await readdir(dirname(lock)) + const result: QueueParticipant[] = [] + for (const name of entries) { + if (!name.startsWith(prefix)) continue + if (name.endsWith('.tmp')) continue + const id = name.slice(prefix.length) + if (!/^\d+-[0-9a-f-]{36}$/.test(id)) throw new ServerCredentialsBusyError() + const path = join(dirname(lock), name) + const record = await readLockRecord(path) + if (record === undefined) continue + const match = new RegExp(`^${id} (choosing|[1-9]\\d*)\\n$`).exec(record) + if (match === null) throw new ServerCredentialsBusyError() + const pid = Number(id.slice(0, id.indexOf('-'))) + // A unique path cannot become a new owner's record. Dead records can leave the queue. + if (await ownerExited(pid)) { + await rm(path, { force: true }) + continue + } + const ticket = match[1] === 'choosing' ? undefined : Number(match[1]) + if (ticket !== undefined && !Number.isSafeInteger(ticket)) throw new ServerCredentialsBusyError() + result.push({ id, ...(ticket === undefined ? {} : { ticket }) }) + } + return result +} + +async function publishExclusive(path: string, record: string): Promise { + const temporary = `${path}.${process.pid}.${uuidV7()}.tmp` + await writeFile(temporary, record, { mode: 0o600, flag: 'wx' }) + try { + try { await link(temporary, path) } catch (error) { + if (error instanceof Error && 'code' in error + && ['EXDEV', 'EOPNOTSUPP', 'ENOTSUP', 'ENOSYS', 'EPERM', 'EACCES'].includes(String(error.code))) { + throw new ServerCredentialsLockUnsupportedError() + } + throw error + } + } finally { await rm(temporary, { force: true }) } +} + +async function isLockContention(error: unknown, path: string): Promise { + if (!(error instanceof Error) || !('code' in error)) return false + if (error.code === 'EEXIST') return true + if (process.platform !== 'win32' || error.code !== 'EPERM') return false + return exists(path) +} + +async function readLockRecord(path: string): Promise { + try { return await readFile(path, 'utf8') } catch (error) { + if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return undefined + throw error + } +} + +async function readQueueMarker(lock: string): Promise { + try { return await readLockRecord(lock) } catch (error) { + if (error instanceof Error && 'code' in error && error.code === 'EISDIR') return undefined + throw error + } +} + +async function ownerExited(pid: number): Promise { + if (pid < 1 || pid > 2147483647 || pid === process.pid) return false + try { process.kill(pid, 0); return false } catch (error) { + return error instanceof Error && 'code' in error && error.code === 'ESRCH' + } +} + +export async function atomicWritePrivate(path: string, contents: string): Promise { + await mkdir(dirname(path), { recursive: true, mode: 0o700 }) + const temporary = `${path}.${process.pid}.${uuidV7()}.tmp` + await writeFile(temporary, contents, { encoding: 'utf8', mode: 0o600, flag: 'wx' }) + await chmod(temporary, 0o600) + await rename(temporary, path) + await chmod(path, 0o600) +} + +async function assertPrivateMode(path: string): Promise { + if (process.platform === 'win32') return + const mode = (await stat(path)).mode & 0o777 + if ((mode & 0o077) !== 0) throw new ServerCredentialsInvalidError('server credentials permissions must be 0600') +} + +async function exists(path: string): Promise { + try { + await stat(path) + return true + } catch (error: unknown) { + if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return false + throw error + } +} + +function safeMessage(error: unknown): string { return error instanceof Error ? error.message : 'invalid credential data' } + +export async function readPrivateJson(path: string): Promise { + if (!await exists(path)) return undefined + await assertPrivateMode(path) + return JSON.parse(await readFile(path, 'utf8')) as unknown +}