@serviceme/devtools-core 2.0.2 → 2.0.4

package/dist/device-DCo0rgUt.mjs

@@ -0,0 +1,793 @@
+import { G as getServicemeHome, O as getDeviceJsonPath } from "./userHome-B97jBm5O.mjs";
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+import { createHash, createHmac, randomBytes, randomUUID } from "node:crypto";
+import { setTimeout } from "node:timers/promises";
+//#region src/device/deviceAuth.ts
+/**
+* deviceAuth — Device request signing helpers for device auth headers.
+*
+* **Boundary exception copy.** The single source of truth for the
+* `x-ms-device-*` header names + the signature algorithms now lives in
+* `@serviceme/devtools-shared` (`device-auth.ts`), consumed by the
+* extension signer and the server verifier. ADL-003 forbids
+* core → shared (and shared → core), so this module keeps a
+* byte-for-byte copy as the documented exception. Keep it in lock-step
+* with `packages/serviceme-shared/src/device-auth.ts`.
+*
+* See `docs/architecture/phase-5-device-header-spec.md` §5 for the wire
+* format. Legacy (v1) basis is `METHOD\nPATH\nTIMESTAMP\nBODY\nSECRET`
+* hashed with a secret-suffix SHA-256; v2 basis is
+* `METHOD\nPATH?QUERY\nTIMESTAMP\nNONCE\nBODY\nSECRET` MACed with real
+* HMAC-SHA-256 keyed by the device secret and signed over the full
+* path-with-query. Both output lowercase hex.
+*/
+/** Canonical header names — MUST match `@serviceme/devtools-shared`'s `DeviceAuthHeaders`. */
+const DeviceAuthHeaders = {
+	deviceId: "x-ms-device-id",
+	deviceSecret: "x-ms-device-secret",
+	signature: "x-ms-device-signature",
+	timestamp: "x-ms-device-timestamp",
+	secretVersion: "x-ms-device-secret-version",
+	/** v2 only — algorithm self-declaration so the server can verify
+	* both schemes during the legacy-client rollout window. */
+	sigAlg: "x-ms-device-sig-alg",
+	/** v2 only — one-time value folded into the signature basis and
+	* checked against a server-side replay cache. */
+	nonce: "x-ms-device-nonce"
+};
+/** v2 signature algorithm identifier carried in `x-ms-device-sig-alg`. */
+const DEVICE_SIG_ALG_V2 = "hmac-sha256-v2";
+/**
+* Legacy (v1) secret-suffix SHA-256 over the canonical basis. Retained
+* for backward compatibility with fielded verifiers/clients that
+* predate v2; new code should use `createDeviceRequestSignatureV2`.
+*/
+function createDeviceRequestSignature(params) {
+	const basis = [
+		params.method.toUpperCase(),
+		params.path,
+		String(params.timestamp),
+		params.body,
+		params.secret
+	].join("\n");
+	return createHash("sha256").update(basis).digest("hex");
+}
+/**
+* Compute the v2 HMAC-SHA-256 hex digest over the canonical basis
+* (path-with-query + nonce).
+*
+* Server contract (`apps/server/src/lib/auth/device-signature-guard.ts`)
+* is line-for-line identical: same LF-joined basis, same lowercase hex
+* output. Any divergence breaks `device-signature-guard.test.ts`.
+*/
+function createDeviceRequestSignatureV2(params) {
+	const basis = [
+		params.method.toUpperCase(),
+		params.path,
+		String(params.timestamp),
+		params.nonce,
+		params.body,
+		params.secret
+	].join("\n");
+	return createHmac("sha256", params.secret).update(basis).digest("hex");
+}
+/**
+* Build the v2 header map. The `path` parameter MUST include the exact
+* query string sent on the wire, and the `body` parameter MUST be the
+* exact byte sequence sent on the wire (no whitespace
+* re-canonicalization between client serialization and signature basis
+* construction).
+*/
+function buildSignedHeaders(params) {
+	const timestamp = params.timestamp ?? Date.now();
+	const nonce = params.nonce ?? randomUUID();
+	const signature = createDeviceRequestSignatureV2({
+		method: params.method,
+		path: params.path,
+		timestamp,
+		nonce,
+		body: params.body,
+		secret: params.deviceSecret
+	});
+	return {
+		[DeviceAuthHeaders.deviceId]: params.publicId,
+		[DeviceAuthHeaders.deviceSecret]: params.deviceSecret,
+		[DeviceAuthHeaders.signature]: signature,
+		[DeviceAuthHeaders.timestamp]: String(timestamp),
+		[DeviceAuthHeaders.secretVersion]: String(params.secretVersion),
+		[DeviceAuthHeaders.sigAlg]: DEVICE_SIG_ALG_V2,
+		[DeviceAuthHeaders.nonce]: nonce
+	};
+}
+//#endregion
+//#region src/device/InstallationId.ts
+/**
+* InstallationId — Derive a stable per-machine identifier from
+* `os.hostname()` + `os.userInfo()`.
+*
+* Per `docs/architecture/phase-5-auth-device-toolbox.md § P5-2 (并入本文时对应 § P5-2 拆分)` B2,
+* `installationId` MUST survive Extension re-installs but vary across
+* machines. We compute a UUID v5-style hash over hostname + username +
+* platform so the result is:
+*   - deterministic (same machine → same id)
+*   - collision-resistant (SHA-256, 128-bit truncated)
+*   - browser-safe (no PII survives — username never enters output)
+*
+* Note: this intentionally differs from `vscode.env.machineId`, which
+* is per-Extension-install and uses a different algorithm. The two
+* coexist: `installationId` is what gets sent to the server, while
+* `machineId` (raw `os.hostname()`) is for diagnostics.
+*
+* Refs:
+* - 4.功能规划.md §2.2 — `InstallationId.ts os.hostname() + os.userInfo() 哈希生成`
+* - 3.功能拆分.md B2 — installationId semantics
+*/
+/** Hex-encoded SHA-256 input. Format: `<hostname>|<username>|<platform>|<nodeVersion>`. */
+function fingerprintMaterial() {
+	let username = "unknown";
+	try {
+		username = os.userInfo().username;
+	} catch {
+		username = process.env.USER ?? process.env.USERNAME ?? "unknown";
+	}
+	return [
+		os.hostname(),
+		username,
+		os.platform(),
+		os.arch(),
+		process.versions.node ?? "unknown"
+	].join("|");
+}
+/**
+* Returns a deterministic installation id for the current machine.
+* Use this when you need an id that survives Extension reinstalls
+* but stays stable across restarts on the same machine.
+*/
+function deriveInstallationId() {
+	const material = fingerprintMaterial();
+	return formatAsV4(createHash("sha256").update(material).digest("hex").slice(0, 32));
+}
+/**
+* Returns a random installation id (UUID v4). Use this for fresh
+* installs when no fingerprint input is available (e.g. containerized
+* CI runners where `os.hostname()` is meaningless).
+*/
+function randomInstallationId() {
+	return randomUUID();
+}
+/** SHA-256 fingerprint material exposed for tests + diagnostics. */
+function fingerprintSource() {
+	return fingerprintMaterial();
+}
+function formatAsV4(hex32) {
+	const chars = hex32.split("");
+	const versionIdx = 12;
+	const variantIdx = 16;
+	chars[versionIdx] = (parseInt(chars[versionIdx] ?? "8", 16) & 0 | 4).toString(16);
+	chars[variantIdx] = (parseInt(chars[variantIdx] ?? "8", 16) & 3 | 8).toString(16);
+	const formatted = chars.join("");
+	return `${formatted.slice(0, 8)}-${formatted.slice(8, 12)}-${formatted.slice(12, 16)}-${formatted.slice(16, 20)}-${formatted.slice(20, 32)}`;
+}
+//#endregion
+//#region src/device/Enroller.ts
+/**
+* Enroller — State machine for `device.enroll` and `device.rotate-secret`.
+*
+* States per `2.需求澄清.md` §1.2:
+*   anonymous → pending → claimed → expired
+*
+*   - `anonymous` (initial): no device has ever enrolled. Server returns
+*     a fresh `publicId` + secret.
+*   - `pending`: enrollment HTTP call has been issued but the server
+*     hasn't confirmed yet. In-flight state — never persisted.
+*   - `claimed`: user has linked this device to their account (via
+*     `/api/v1/devices/claim`). Sticky binding locks future re-enrolls
+*     to the same `userId` (server-side matrix).
+*   - `expired`: server returned a device-expiry error. Forces a fresh
+*     enroll on next call.
+*
+* `--force` semantics: any non-anonymous state can be force-reset to
+* `anonymous` by wiping the local identity file. The next enroll will
+* be treated as a brand-new install by the server (no sticky binding).
+*
+* The Enroller is the **state machine**; the actual HTTP I/O is the
+* caller's responsibility (the `DeviceSyncClient` in Phase 5.4 wires
+* the server). This split keeps the Enroller unit-testable without
+* a live server.
+*
+* Refs:
+* - 4.功能规划.md §2.2 — `Enroller.ts anonymous → pending → claimed → expired`
+* - `2.需求澄清.md` §1.2 — binding-state machine
+*/
+/** 32 bytes of HMAC secret material — matches the server's `device-registration.ts:73-80` generator. */
+const SECRET_BYTES = 32;
+/** Server returns `publicId` as 32-char hex (16 bytes). Match the wire length. */
+const PUBLIC_ID_BYTES = 16;
+const defaultRandomBytes = (size) => {
+	return randomBytes(size);
+};
+/** Sentinel error — re-enroll on a claimed device without auth. */
+var DeviceReenrollRequiresAuthError = class extends Error {
+	constructor(message = "Re-enroll on a claimed device requires current device credentials or the bound user") {
+		super(message);
+		this.name = "DeviceReenrollRequiresAuthError";
+	}
+};
+/** Sentinel error — server returned a 410 / version-mismatch after rotation. */
+var DeviceSecretVersionMismatchError = class extends Error {
+	constructor(message = "Device secret version mismatch — server has rotated past the local copy") {
+		super(message);
+		this.name = "DeviceSecretVersionMismatchError";
+	}
+};
+var Enroller = class {
+	constructor(opts) {
+		this.inflight = null;
+		this.identity = opts.identityStore;
+		this.now = opts.now ?? (() => /* @__PURE__ */ new Date());
+		this.random = opts.randomBytes ?? defaultRandomBytes;
+		this.enrollRequest = opts.enrollRequest;
+	}
+	/**
+	* Read the current binding state without touching the disk.
+	* Returns `anonymous` when no identity is stored.
+	*/
+	async currentState() {
+		return (await this.identity.read())?.bindingState ?? "anonymous";
+	}
+	/**
+	* Drive the enrollment flow.
+	*
+	* @param force when true, drop the local identity and start fresh
+	*              (server treats this as a brand-new install).
+	* @param requireAuth when true, refuse to silently re-enroll an
+	*              existing claimed device — throw
+	*              `DeviceReenrollRequiresAuthError` instead.
+	*/
+	/**
+	* Resolve when any in-flight enrollment completes.  Returns immediately
+	* when no enrollment is in progress.  Allows callers (e.g. the extension's
+	* `buildDeviceAuthHeaders`) to wait for a concurrent `syncDeviceInfo()`
+	* enrollment before attempting to read the identity from the store.
+	*/
+	async waitForEnrollment() {
+		if (this.inflight) await this.inflight;
+	}
+	async enroll(opts = {}) {
+		if (this.inflight) return this.inflight;
+		const promise = this.runEnroll(opts);
+		this.inflight = promise;
+		try {
+			return await promise;
+		} finally {
+			if (this.inflight === promise) this.inflight = null;
+		}
+	}
+	/** Test seam — surface the underlying identity store. */
+	getIdentityStore() {
+		return this.identity;
+	}
+	/** True when an enrollment is currently in-flight. Used by callers (e.g. the extension's `buildDeviceAuthHeaders`) to skip triggering a competing enrollment. */
+	isEnrolling() {
+		return this.inflight !== null;
+	}
+	async runEnroll(opts) {
+		const { written } = await this.identity.mutate(async (current) => {
+			const existing = opts.force ? null : current;
+			if (!opts.force && current) {
+				if (current.bindingState === "expired") {} else if (opts.requireAuth && (current.bindingState === "claimed" || current.bindingState === "pending")) throw new DeviceReenrollRequiresAuthError();
+			}
+			const installationId = current?.installationId ?? deriveInstallationId();
+			const machineId = current?.machineId ?? "unknown";
+			const platform = current?.platform ?? "unknown";
+			let response;
+			if (this.enrollRequest) response = await this.enrollRequest({
+				installationId,
+				machineId,
+				platform,
+				existing,
+				force: Boolean(opts.force),
+				requireAuth: Boolean(opts.requireAuth)
+			});
+			else response = synthesizeEnrollResponse(this.random, existing);
+			return { next: {
+				version: current?.version ?? 1,
+				installationId,
+				machineId,
+				platform,
+				hostname: current?.hostname,
+				publicId: response.publicId,
+				secretVersion: response.secretVersion,
+				bindingState: response.bindingState,
+				deviceSecret: response.deviceSecret,
+				previousDeviceSecret: existing?.deviceSecret,
+				previousSecretExpiresAt: opts.force || response.secretVersion === (existing?.secretVersion ?? 0) + 1 ? void 0 : existing?.previousSecretExpiresAt,
+				lastEnrollAt: this.now().toISOString(),
+				lastSyncAt: existing?.lastSyncAt,
+				lastSyncError: void 0
+			} };
+		});
+		return {
+			publicId: written.publicId,
+			bindingState: written.bindingState,
+			expiresAt: deriveExpiresAt(written, this.now)
+		};
+	}
+	/**
+	* Rotate the HMAC secret. Keeps the previous secret for the grace
+	* window (default 7 days per `2.需求澄清.md` §1.2) — the
+	* `previousSecretExpiresAt` is stamped on the persisted identity.
+	*/
+	async rotateSecret(opts = {}) {
+		const gracePeriodDays = opts.gracePeriodDays ?? 7;
+		const now = this.now();
+		const newSecret = this.random(SECRET_BYTES).toString("hex");
+		const { written } = await this.identity.mutate(async (current) => {
+			if (!current) throw new Error("Cannot rotate-secret without a prior enrollment");
+			const graceExpiresAt = new Date(now.getTime() + gracePeriodDays * 24 * 60 * 60 * 1e3);
+			return { next: {
+				...current,
+				deviceSecret: newSecret,
+				previousDeviceSecret: current.deviceSecret,
+				previousSecretExpiresAt: graceExpiresAt.toISOString(),
+				secretVersion: current.secretVersion + 1,
+				lastEnrollAt: now.toISOString()
+			} };
+		});
+		return {
+			publicId: written.publicId,
+			secretVersion: written.secretVersion,
+			gracePeriodDays
+		};
+	}
+	/**
+	* Mark the device as `expired`. Used when the server returns a
+	* device-expiry response; the next `enroll()` call forces a fresh
+	* round-trip.
+	*/
+	async markExpired() {
+		await this.identity.mutate(async (current) => {
+			if (!current) return {
+				next: current ?? await emptyIdentity(this.random),
+				result: void 0
+			};
+			return { next: {
+				...current,
+				bindingState: "expired"
+			} };
+		});
+	}
+	/**
+	* Mark the device as `claimed`. Called by the bridge after a
+	* successful `device.claim` server response.
+	*/
+	async markClaimed() {
+		await this.identity.mutate(async (current) => {
+			if (!current) throw new Error("Cannot mark-claimed without a prior enrollment");
+			return { next: {
+				...current,
+				bindingState: "claimed",
+				lastSyncAt: this.now().toISOString(),
+				lastSyncError: void 0
+			} };
+		});
+	}
+};
+function deriveExpiresAt(_identity, _now) {}
+function synthesizeEnrollResponse(random, existing) {
+	const publicId = existing?.publicId ?? random(PUBLIC_ID_BYTES).toString("hex");
+	const secretVersion = (existing?.secretVersion ?? 0) + 1;
+	return {
+		publicId,
+		deviceSecret: random(SECRET_BYTES).toString("hex"),
+		secretVersion,
+		bindingState: existing?.bindingState === "claimed" ? "claimed" : "anonymous"
+	};
+}
+async function emptyIdentity(random) {
+	return {
+		version: 1,
+		installationId: deriveInstallationId(),
+		machineId: "unknown",
+		platform: "unknown",
+		publicId: random(PUBLIC_ID_BYTES).toString("hex"),
+		secretVersion: 1,
+		bindingState: "anonymous",
+		deviceSecret: random(SECRET_BYTES).toString("hex"),
+		lastEnrollAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+//#endregion
+//#region src/device/types.ts
+/**
+* Schema version of the on-disk `device.json` file. Bumped when the
+* shape changes incompatibly. IdentityStore checks this on read and
+* either migrates (versions ≤ 1) or refuses (versions > supported).
+*/
+const DEVICE_JSON_SCHEMA_VERSION = 1;
+//#endregion
+//#region src/device/IdentityStore.ts
+/**
+* IdentityStore — Atomic JSON persistence for the device identity file.
+*
+* Stores the `PersistedDeviceIdentity` (incl. the HMAC secret cleartext)
+* at `~/.serviceme/device.json` (per `phase-5-device-header-spec.md`
+* §3.1). Writes are atomic via `write-tmp + fsync + rename`, matching
+* the `SkillStore` / `ToolboxStore` precedent. Concurrent writes are
+* serialized with a mkdir-based file lock (POSIX-atomic) — proper
+* cross-process locking is deferred to Phase 6+ per the open spec.
+*
+* The file mode is `0600` (owner read/write only) so the cleartext
+* secret stays safe at rest. On Windows the mode hint is a no-op
+* (Windows uses ACLs) but `writeFile` still succeeds.
+*
+* Migration — IdentityStore auto-detects a v0-shape (pre-Phase-5.2)
+* file written by the Extension's old `globalState` blob:
+*   { version: 1, claimed: false, publicKeyFingerprint: null }
+* In that case the file is migrated forward to the v1 schema on the
+* next write (the data fields are empty and a fresh enroll is required).
+* The full Extension `globalState` → JSON migration happens in the
+* Phase 5.5 adapter (`apps/extension/.../DeviceService.ts`) since the
+* adapter holds the live `globalState` access.
+*
+* Refs:
+* - 4.功能规划.md §2.2 — `IdentityStore.ts 持久化到 ~/.config/serviceme/device.json, 原子写`
+* - `docs/architecture/phase-5-device-header-spec.md` §3.1, §2.5
+*/
+const FILE_MODE = 384;
+const LOCK_DIR_MODE = 448;
+const DEFAULT_LOCK_TIMEOUT_MS = 5e3;
+const DEFAULT_LOCK_RETRY_MS = 25;
+const LOCK_STALE_GRACE_MS = 200;
+const TMP_SUFFIX = ".tmp";
+/**
+* Default file backend — uses `node:fs/promises` with the canonical
+* tmp-then-rename atomic-write pattern.
+*/
+var FsIdentityFileBackend = class {
+	async exists(filePath) {
+		try {
+			await fsp.access(filePath);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	async read(filePath) {
+		try {
+			const buf = await fsp.readFile(filePath, "utf8");
+			return migratePersistedIdentity(JSON.parse(buf));
+		} catch (err) {
+			if (isNodeError(err) && err.code === "ENOENT") return null;
+			throw err;
+		}
+	}
+	async write(filePath, payload) {
+		await fsp.mkdir(path.dirname(filePath), { recursive: true });
+		const tmpPath = `${filePath}${TMP_SUFFIX}`;
+		const bytes = Buffer.from(JSON.stringify(payload, null, "	"), "utf8");
+		await fsp.rm(tmpPath, { force: true });
+		const handle = await fsp.open(tmpPath, "w", FILE_MODE);
+		try {
+			await handle.writeFile(bytes);
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+		await fsp.rename(tmpPath, filePath);
+		await fsp.chmod(filePath, FILE_MODE).catch(() => void 0);
+		return {
+			bytesWritten: bytes.byteLength,
+			tmpPath
+		};
+	}
+	async delete(filePath) {
+		await fsp.rm(filePath, { force: true });
+	}
+};
+/**
+* Reconcile an unknown on-disk shape into the current `PersistedDeviceIdentity`.
+*
+* - v1 IdentityStore files (current shape) pass through unchanged.
+* - v0 bootstrap files (`{ version: 1, claimed: false, publicKeyFingerprint: null }`)
+*   are recognized by their placeholder keys and discarded; the next
+*   enroll writes a fresh identity.
+* - Anything else throws — refuse to silently drop user data.
+*/
+function migratePersistedIdentity(parsed) {
+	if (!isRecord(parsed)) throw new Error("device.json: top-level must be an object");
+	const version = parsed.version;
+	if (version === 1) {
+		if (parsed.publicId === void 0 && parsed.deviceSecret === void 0 && ("claimed" in parsed || "publicKeyFingerprint" in parsed)) return null;
+		return parsed;
+	}
+	if (typeof version === "number" && version < 1) return null;
+	throw new Error(`device.json: unsupported schema version ${String(version)}`);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function isNodeError(value) {
+	return value instanceof Error && typeof value.code === "string";
+}
+const LOCK_PID_FILE = "pid";
+/**
+* Check whether a process is still alive (best-effort, cross-platform).
+* Returns `false` for any PID we cannot verify as alive.
+*/
+function isProcessAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* mkdir-based advisory file lock with stale-lock recovery.
+*
+* POSIX mkdir is atomic; on Windows modern filesystems (NTFS) it's also
+* atomic at the API level. Sufficient for single-host, single-user
+* scenarios (which is the SERVICEME threat model).
+*
+* Stale lock recovery: a `pid` file inside the lock directory records the
+* owner's PID. On `EEXIST`, if the recorded PID is no longer alive, the
+* lock directory is forcibly removed and acquisition retried immediately.
+* This prevents permanent lockout when a process crashes without calling
+* `release()`.
+*/
+var FileLock = class {
+	constructor(filePath, timeoutMs, retryMs) {
+		this.acquired = false;
+		this.dirPath = `${filePath}.lock`;
+		this.pidFilePath = path.join(this.dirPath, LOCK_PID_FILE);
+		this.timeoutMs = timeoutMs;
+		this.retryMs = retryMs;
+	}
+	async acquire() {
+		const start = Date.now();
+		while (true) try {
+			await fsp.mkdir(this.dirPath, { mode: LOCK_DIR_MODE });
+			await fsp.writeFile(this.pidFilePath, String(process.pid), "utf8").catch(() => void 0);
+			this.acquired = true;
+			return;
+		} catch (err) {
+			if (!isNodeError(err) || err.code !== "EEXIST") throw err;
+			if (await this.isStaleLock()) {
+				await fsp.rm(this.dirPath, {
+					recursive: true,
+					force: true
+				});
+				continue;
+			}
+			if (Date.now() - start >= this.timeoutMs) throw new Error(`IdentityStore lock acquisition timed out for ${this.dirPath}`);
+			await setTimeout(this.retryMs);
+		}
+	}
+	async isStaleLock() {
+		let pidStr;
+		try {
+			pidStr = await fsp.readFile(this.pidFilePath, "utf8");
+		} catch {
+			try {
+				const stat = await fsp.stat(this.dirPath);
+				return Date.now() - stat.mtimeMs > LOCK_STALE_GRACE_MS;
+			} catch {
+				return false;
+			}
+		}
+		const pid = Number.parseInt(pidStr.trim(), 10);
+		if (!Number.isFinite(pid) || pid <= 0) return true;
+		return !isProcessAlive(pid);
+	}
+	async release() {
+		if (!this.acquired) return;
+		this.acquired = false;
+		await fsp.rm(this.dirPath, {
+			recursive: true,
+			force: true
+		});
+	}
+};
+var IdentityStore = class {
+	constructor(opts = {}) {
+		this.filePath = opts.filePath ?? getDeviceJsonPath();
+		this.backend = opts.backend ?? new FsIdentityFileBackend();
+		this.hooks = opts.hooks ?? {};
+		this.lockTimeoutMs = opts.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
+		this.lockRetryMs = opts.lockRetryMs ?? DEFAULT_LOCK_RETRY_MS;
+	}
+	/** Absolute path to the underlying JSON file (test seam). */
+	getFilePath() {
+		return this.filePath;
+	}
+	/** True when the JSON file already exists on disk. */
+	async exists() {
+		return this.backend.exists(this.filePath);
+	}
+	/** Read the persisted identity; returns `null` when no identity is stored. */
+	async read() {
+		return this.backend.read(this.filePath);
+	}
+	/**
+	* Atomically write the given identity. Concurrent writers are
+	* serialized via the file lock; the read-modify-write happens
+	* inside the lock so callers can't see a partial state.
+	*/
+	async write(next) {
+		await this.hooks.beforeWrite?.(next);
+		const lock = new FileLock(this.filePath, this.lockTimeoutMs, this.lockRetryMs);
+		await lock.acquire();
+		try {
+			const stamped = {
+				...next,
+				version: 1
+			};
+			const result = await this.backend.write(this.filePath, stamped);
+			await this.hooks.afterWrite?.(stamped);
+			return result;
+		} finally {
+			await lock.release();
+		}
+	}
+	/**
+	* Read-modify-write under the same lock. The mutator receives the
+	* current identity (or `null` on first call) and returns the
+	* replacement. Throwing inside the mutator aborts the write.
+	*/
+	async mutate(mutator) {
+		const lock = new FileLock(this.filePath, this.lockTimeoutMs, this.lockRetryMs);
+		await lock.acquire();
+		try {
+			const { next, result } = await mutator(await this.backend.read(this.filePath));
+			const stamped = {
+				...next,
+				version: 1
+			};
+			await this.hooks.beforeWrite?.(stamped);
+			await this.backend.write(this.filePath, stamped);
+			await this.hooks.afterWrite?.(stamped);
+			return {
+				result,
+				written: stamped
+			};
+		} finally {
+			await lock.release();
+		}
+	}
+	/** Wipe the persisted identity (used by `device.enroll --force`). */
+	async clear() {
+		await this.backend.delete(this.filePath);
+	}
+	/**
+	* Resolve the installation metadata for the current machine.
+	* Pure helper — no I/O, just `os.*` calls.
+	*/
+	resolveInstallationMetadata() {
+		return {
+			installationId: "",
+			machineId: os.hostname(),
+			platform: os.platform()
+		};
+	}
+	/**
+	* Ensure the parent directory exists (`~/.serviceme/`). Idempotent.
+	* Useful when the bootstrap phase5 placeholder wasn't run yet.
+	*/
+	async ensureHome() {
+		await fsp.mkdir(getServicemeHome(), { recursive: true });
+		await fsp.mkdir(path.dirname(this.filePath), { recursive: true });
+	}
+};
+//#endregion
+//#region src/device/DeviceCore.ts
+var DeviceCore = class {
+	constructor(opts = {}) {
+		this.identity = opts.identityStore ?? new IdentityStore();
+		this.enroller = new Enroller({
+			identityStore: this.identity,
+			enrollRequest: opts.enrollRequest,
+			now: opts.now
+		});
+		this.resolveInstallationId = opts.resolveInstallationId ?? deriveInstallationId;
+	}
+	/** Read-only snapshot of the device status (matches `device.status` wire shape). */
+	async status() {
+		const stored = await this.identity.read();
+		return stored ? {
+			bindingState: stored.bindingState,
+			identity: projectIdentity(stored),
+			metadata: projectMetadata(stored),
+			lastSyncAt: stored.lastSyncAt,
+			lastSyncError: stored.lastSyncError
+		} : { bindingState: "anonymous" };
+	}
+	/** Enroll (or re-enroll) the device. */
+	async enroll(opts = {}) {
+		return this.enroller.enroll(opts);
+	}
+	/** Wait for any in-flight enrollment to finish.  Use before `buildSignedHeaders` so that a concurrent `syncDeviceInfo` enrollment has time to write the identity to the store. */
+	async waitForEnrollment() {
+		await this.enroller.waitForEnrollment();
+	}
+	/** True when an enrollment is currently in-flight. Used by callers to skip triggering a competing enrollment. */
+	isEnrolling() {
+		return this.enroller.isEnrolling();
+	}
+	/** Rotate the HMAC secret while keeping the previous one for the grace window. */
+	async rotateSecret(opts = {}) {
+		const result = await this.enroller.rotateSecret(opts);
+		const stored = await this.identity.read();
+		return {
+			...result,
+			gracePeriodEndsAt: stored?.previousSecretExpiresAt
+		};
+	}
+	/** Build the v2 signed header map for an outbound request. The path
+	* MUST include the query string (v2 signs it). */
+	async buildSignedHeaders(input) {
+		const stored = await this.identity.read();
+		if (!stored) return null;
+		return buildSignedHeaders({
+			method: input.method,
+			path: input.path,
+			body: input.body,
+			publicId: stored.publicId,
+			deviceSecret: stored.deviceSecret,
+			secretVersion: stored.secretVersion
+		});
+	}
+	/** Raw stored identity (CLI/extension internal use). Test seam too. */
+	async readIdentity() {
+		return this.identity.read();
+	}
+	/** Wipe the local identity (the `--force` path before re-enroll). */
+	async clear() {
+		await this.identity.clear();
+	}
+	/** Mark the device as claimed (called by the bridge after a successful claim). */
+	async markClaimed() {
+		await this.enroller.markClaimed();
+	}
+	/** Mark the device as expired (server returned an expiry response). */
+	async markExpired() {
+		await this.enroller.markExpired();
+	}
+	/** Expose the identity store (CLI uses it for direct file access in tests). */
+	getIdentityStore() {
+		return this.identity;
+	}
+	/** Expose the enroller (CLI uses it for state inspection). */
+	getEnroller() {
+		return this.enroller;
+	}
+	/** Header name constants — re-exported from `deviceAuth.ts`. */
+	getHeaderNames() {
+		return DeviceAuthHeaders;
+	}
+	/** Compute the installation id for the current machine. */
+	getInstallationId() {
+		return this.resolveInstallationId();
+	}
+};
+function projectIdentity(stored) {
+	return {
+		publicId: stored.publicId,
+		secretVersion: stored.secretVersion,
+		bindingState: stored.bindingState
+	};
+}
+function projectMetadata(stored) {
+	return {
+		installationId: stored.installationId,
+		machineId: stored.machineId,
+		platform: stored.platform,
+		hostname: stored.hostname
+	};
+}
+//#endregion
+export { DeviceReenrollRequiresAuthError as a, deriveInstallationId as c, DeviceAuthHeaders as d, buildSignedHeaders as f, DEVICE_JSON_SCHEMA_VERSION as i, fingerprintSource as l, FsIdentityFileBackend as n, DeviceSecretVersionMismatchError as o, createDeviceRequestSignature as p, IdentityStore as r, Enroller as s, DeviceCore as t, randomInstallationId as u };
+
+//# sourceMappingURL=device-DCo0rgUt.mjs.map