@serviceme/devtools-core 0.1.8 → 0.2.0

package/dist/device.d.ts

@@ -0,0 +1,456 @@
+import { DeviceBindingState, DeviceEnrollResult, DeviceStatus, DeviceRotateSecretResult } from '@serviceme/devtools-protocol';
+
+/**
+ * deviceAuth — Pure HMAC-SHA-256 signing helpers for device auth headers.
+ *
+ * Ported byte-for-byte from
+ * `apps/extension/src/services/device/deviceAuth.ts:11-26` (the wire
+ * algorithm is locked by the server-side `device-signature-guard.ts`
+ * verifier, see `docs/architecture/phase-5-device-header-spec.md` §5).
+ *
+ * The basis is `METHOD\nPATH\nTIMESTAMP\nBODY\nSECRET` (LF-joined,
+ * NOT JSON). Output is lowercase hex SHA-256.
+ *
+ * Refs:
+ * - 4.功能规划.md §2.2 — `deviceAuth.ts HMAC 签名(纯 node:crypto,直接搬)`
+ * - `docs/architecture/phase-5-device-header-spec.md` §5 (signature format)
+ */
+/** Canonical header names — MUST match server's `device-signature-guard.ts:9-15`. */
+declare const DeviceAuthHeaders: {
+    readonly deviceId: "x-ms-device-id";
+    readonly deviceSecret: "x-ms-device-secret";
+    readonly signature: "x-ms-device-signature";
+    readonly timestamp: "x-ms-device-timestamp";
+    readonly secretVersion: "x-ms-device-secret-version";
+};
+interface DeviceRequestSignatureParams {
+    method: string;
+    path: string;
+    timestamp: number;
+    body: string;
+    secret: string;
+}
+/**
+ * Compute the HMAC-SHA-256 hex digest of the canonical basis.
+ *
+ * Server contract (`apps/server/src/lib/auth/device-signature-guard.ts:46-62`)
+ * is line-for-line identical: same LF-joined basis, same lowercase
+ * hex output. Any divergence breaks `device-signature-guard.test.ts`.
+ */
+declare function createDeviceRequestSignature(params: DeviceRequestSignatureParams): string;
+/** 5-header map consumed by `fetch()` callers (CLI bridge, Extension). */
+interface DeviceSignedHeaders {
+    [DeviceAuthHeaders.deviceId]: string;
+    [DeviceAuthHeaders.deviceSecret]: string;
+    [DeviceAuthHeaders.signature]: string;
+    [DeviceAuthHeaders.timestamp]: string;
+    [DeviceAuthHeaders.secretVersion]: string;
+}
+interface BuildSignedHeadersParams {
+    method: string;
+    path: string;
+    body: string;
+    publicId: string;
+    deviceSecret: string;
+    secretVersion: number;
+    /** Override for deterministic tests. */
+    timestamp?: number;
+}
+/**
+ * Build the canonical 5-header map. The `body` parameter MUST be the
+ * exact byte sequence sent on the wire (no whitespace re-canonicalization
+ * between client serialization and signature basis construction).
+ */
+declare function buildSignedHeaders(params: BuildSignedHeadersParams): DeviceSignedHeaders;
+
+/**
+ * Internal types for the device domain.
+ *
+ * These types are NOT re-exported from the protocol package — they are
+ * implementation details of the IdentityStore + Enroller. Public data
+ * models (the bridge wire shape) live in `@serviceme/devtools-protocol`'s
+ * `device.ts`.
+ *
+ * Refs:
+ * - 4.功能规划.md §2.2 — `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).
+ */
+declare const DEVICE_JSON_SCHEMA_VERSION = 1;
+/** Internal representation of the persisted identity file. */
+interface PersistedDeviceIdentity {
+    version: number;
+    /** Stable per-machine id (UUID v4 shape) — survives secret rotates. */
+    installationId: string;
+    /** Raw `os.hostname()` for diagnostics. */
+    machineId: string;
+    /** Platform string (e.g. "darwin"). */
+    platform: string;
+    /** Optional hostname override for environments where `os.hostname()` is unstable. */
+    hostname?: string;
+    /** Public, non-secret id returned by the server. 32-char hex. */
+    publicId: string;
+    /** Monotonic secret version counter, starts at 1 after first enroll. */
+    secretVersion: number;
+    /** Current binding state — drives the re-enroll matrix. */
+    bindingState: DeviceBindingState;
+    /** HMAC secret (32 bytes hex-encoded = 64 chars). Persisted per `device-header-spec.md` §3.1. */
+    deviceSecret: string;
+    /** Optional: previous secret retained during the grace window (rotation). */
+    previousDeviceSecret?: string;
+    /** Optional: ISO timestamp at which the previous secret stops being accepted. */
+    previousSecretExpiresAt?: string;
+    /** ISO timestamp of the most recent successful enroll / rotate. */
+    lastEnrollAt: string;
+    /** Optional ISO timestamp of the most recent server sync. */
+    lastSyncAt?: string;
+    /** Optional human-readable message for the last sync error. */
+    lastSyncError?: string;
+}
+/** Result of a single atomic write. */
+interface AtomicWriteResult {
+    bytesWritten: number;
+    /** Path to the temp file (post-rename it no longer exists; useful for diagnostics). */
+    tmpPath: string;
+}
+/** Hook called before/after every identity write — used by tests to assert concurrency safety. */
+interface IdentityStoreHooks {
+    beforeWrite?: (next: PersistedDeviceIdentity) => void | Promise<void>;
+    afterWrite?: (next: PersistedDeviceIdentity) => void | Promise<void>;
+}
+
+/**
+ * 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
+ */
+
+/**
+ * Minimal interface for reading + writing the persisted identity file.
+ * Default impl uses `getDeviceJsonPath()` (which honors `SERVICEME_HOME`),
+ * but tests can substitute a custom path for isolation.
+ */
+interface IdentityFileBackend {
+    read(filePath: string): Promise<PersistedDeviceIdentity | null>;
+    write(filePath: string, payload: PersistedDeviceIdentity): Promise<AtomicWriteResult>;
+    exists(filePath: string): Promise<boolean>;
+    delete(filePath: string): Promise<void>;
+    listDir?(dir: string): Promise<string[]>;
+}
+interface IdentityStoreOptions {
+    filePath?: string;
+    hooks?: IdentityStoreHooks;
+    lockTimeoutMs?: number;
+    lockRetryMs?: number;
+    /** Injectable clock for deterministic tests. */
+    now?: () => Date;
+    backend?: IdentityFileBackend;
+}
+/**
+ * Default file backend — uses `node:fs/promises` with the canonical
+ * tmp-then-rename atomic-write pattern.
+ */
+declare class FsIdentityFileBackend implements IdentityFileBackend {
+    exists(filePath: string): Promise<boolean>;
+    read(filePath: string): Promise<PersistedDeviceIdentity | null>;
+    write(filePath: string, payload: PersistedDeviceIdentity): Promise<AtomicWriteResult>;
+    delete(filePath: string): Promise<void>;
+}
+declare class IdentityStore {
+    private readonly filePath;
+    private readonly backend;
+    private readonly hooks;
+    private readonly lockTimeoutMs;
+    private readonly lockRetryMs;
+    private readonly now;
+    constructor(opts?: IdentityStoreOptions);
+    /** Absolute path to the underlying JSON file (test seam). */
+    getFilePath(): string;
+    /** True when the JSON file already exists on disk. */
+    exists(): Promise<boolean>;
+    /** Read the persisted identity; returns `null` when no identity is stored. */
+    read(): Promise<PersistedDeviceIdentity | null>;
+    /**
+     * 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.
+     */
+    write(next: PersistedDeviceIdentity): Promise<AtomicWriteResult>;
+    /**
+     * 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.
+     */
+    mutate<T>(mutator: (current: PersistedDeviceIdentity | null) => Promise<{
+        next: PersistedDeviceIdentity;
+        result?: T;
+    }>): Promise<{
+        result: T | undefined;
+        written: PersistedDeviceIdentity;
+    }>;
+    /** Wipe the persisted identity (used by `device.enroll --force`). */
+    clear(): Promise<void>;
+    /**
+     * Resolve the installation metadata for the current machine.
+     * Pure helper — no I/O, just `os.*` calls.
+     */
+    resolveInstallationMetadata(): Pick<PersistedDeviceIdentity, "installationId" | "machineId" | "platform">;
+    /**
+     * Ensure the parent directory exists (`~/.serviceme/`). Idempotent.
+     * Useful when the bootstrap phase5 placeholder wasn't run yet.
+     */
+    ensureHome(): Promise<void>;
+}
+
+/**
+ * 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
+ */
+
+interface EnrollerOptions {
+    identityStore: IdentityStore;
+    /** Injectable clock for deterministic tests. */
+    now?: () => Date;
+    /** Override the random source (tests). */
+    randomBytes?: (size: number) => Buffer;
+    /** Caller-supplied enroll HTTP function. Phase 5.4 wires the real one. */
+    enrollRequest?: EnrollRequestFn;
+}
+type EnrollRequestFn = (input: {
+    installationId: string;
+    machineId: string;
+    platform: string;
+    existing: PersistedDeviceIdentity | null;
+    force: boolean;
+    requireAuth: boolean;
+}) => Promise<EnrollResponse>;
+interface EnrollResponse {
+    publicId: string;
+    deviceSecret: string;
+    secretVersion: number;
+    bindingState: DeviceBindingState;
+    expiresAt?: string;
+}
+/** Sentinel error — re-enroll on a claimed device without auth. */
+declare class DeviceReenrollRequiresAuthError extends Error {
+    constructor(message?: string);
+}
+/** Sentinel error — server returned a 410 / version-mismatch after rotation. */
+declare class DeviceSecretVersionMismatchError extends Error {
+    constructor(message?: string);
+}
+declare class Enroller {
+    private readonly identity;
+    private readonly now;
+    private readonly random;
+    private readonly enrollRequest?;
+    private inflight;
+    constructor(opts: EnrollerOptions);
+    /**
+     * Read the current binding state without touching the disk.
+     * Returns `anonymous` when no identity is stored.
+     */
+    currentState(): Promise<DeviceBindingState>;
+    /**
+     * 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.
+     */
+    waitForEnrollment(): Promise<void>;
+    enroll(opts?: {
+        force?: boolean;
+        requireAuth?: boolean;
+    }): Promise<DeviceEnrollResult>;
+    /** Test seam — surface the underlying identity store. */
+    getIdentityStore(): IdentityStore;
+    /** True when an enrollment is currently in-flight. Used by callers (e.g. the extension's `buildDeviceAuthHeaders`) to skip triggering a competing enrollment. */
+    isEnrolling(): boolean;
+    private runEnroll;
+    /**
+     * 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.
+     */
+    rotateSecret(opts?: {
+        gracePeriodDays?: number;
+    }): Promise<{
+        publicId: string;
+        secretVersion: number;
+        gracePeriodDays: number;
+    }>;
+    /**
+     * Mark the device as `expired`. Used when the server returns a
+     * device-expiry response; the next `enroll()` call forces a fresh
+     * round-trip.
+     */
+    markExpired(): Promise<void>;
+    /**
+     * Mark the device as `claimed`. Called by the bridge after a
+     * successful `device.claim` server response.
+     */
+    markClaimed(): Promise<void>;
+}
+
+/**
+ * DeviceCore — Main entry for the device domain.
+ *
+ * Aggregates `IdentityStore` + `Enroller` + signer helpers into a single
+ * surface that the CLI / Extension / Bridge can call. Pure orchestration
+ * — no HTTP of its own (the actual `POST /api/v1/devices/enroll` lives
+ * behind `EnrollerOptions.enrollRequest`, wired in Phase 5.4).
+ *
+ * Refs:
+ * - 4.功能规划.md §2.2 — `DeviceCore.ts 主入口`
+ * - ADL-003 — data model in `@serviceme/devtools-protocol`
+ * - `docs/architecture/phase-5-device-header-spec.md` §3.1
+ */
+
+interface DeviceCoreOptions {
+    identityStore?: IdentityStore;
+    enrollRequest?: EnrollRequestFn;
+    now?: () => Date;
+    /** Optional override for `deriveInstallationId` (used by tests for determinism). */
+    resolveInstallationId?: () => string;
+}
+declare class DeviceCore {
+    private readonly identity;
+    private readonly enroller;
+    private readonly resolveInstallationId;
+    constructor(opts?: DeviceCoreOptions);
+    /** Read-only snapshot of the device status (matches `device.status` wire shape). */
+    status(): Promise<DeviceStatus>;
+    /** Enroll (or re-enroll) the device. */
+    enroll(opts?: {
+        force?: boolean;
+        requireAuth?: boolean;
+    }): Promise<DeviceEnrollResult>;
+    /** 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. */
+    waitForEnrollment(): Promise<void>;
+    /** True when an enrollment is currently in-flight. Used by callers to skip triggering a competing enrollment. */
+    isEnrolling(): boolean;
+    /** Rotate the HMAC secret while keeping the previous one for the grace window. */
+    rotateSecret(opts?: {
+        gracePeriodDays?: number;
+    }): Promise<DeviceRotateSecretResult>;
+    /** Build the canonical 5-header map for an outbound signed request. */
+    buildSignedHeaders(input: {
+        method: string;
+        path: string;
+        body: string;
+    }): Promise<DeviceSignedHeaders | null>;
+    /** Raw stored identity (CLI/extension internal use). Test seam too. */
+    readIdentity(): Promise<PersistedDeviceIdentity | null>;
+    /** Wipe the local identity (the `--force` path before re-enroll). */
+    clear(): Promise<void>;
+    /** Mark the device as claimed (called by the bridge after a successful claim). */
+    markClaimed(): Promise<void>;
+    /** Mark the device as expired (server returned an expiry response). */
+    markExpired(): Promise<void>;
+    /** Expose the identity store (CLI uses it for direct file access in tests). */
+    getIdentityStore(): IdentityStore;
+    /** Expose the enroller (CLI uses it for state inspection). */
+    getEnroller(): Enroller;
+    /** Header name constants — re-exported from `deviceAuth.ts`. */
+    getHeaderNames(): typeof DeviceAuthHeaders;
+    /** Compute the installation id for the current machine. */
+    getInstallationId(): string;
+}
+
+/**
+ * InstallationId — Derive a stable per-machine identifier from
+ * `os.hostname()` + `os.userInfo()`.
+ *
+ * Per `docs/requirements/phase-5-auth-device-toolbox/3.功能拆分.md` 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
+ */
+/**
+ * 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.
+ */
+declare function deriveInstallationId(): string;
+/**
+ * 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).
+ */
+declare function randomInstallationId(): string;
+/** SHA-256 fingerprint material exposed for tests + diagnostics. */
+declare function fingerprintSource(): string;
+
+export { type AtomicWriteResult, type BuildSignedHeadersParams, DEVICE_JSON_SCHEMA_VERSION, DeviceAuthHeaders, DeviceCore, type DeviceCoreOptions, DeviceReenrollRequiresAuthError, type DeviceRequestSignatureParams, DeviceSecretVersionMismatchError, type DeviceSignedHeaders, type EnrollRequestFn, type EnrollResponse, Enroller, type EnrollerOptions, FsIdentityFileBackend, type IdentityFileBackend, IdentityStore, type IdentityStoreHooks, type IdentityStoreOptions, type PersistedDeviceIdentity, buildSignedHeaders, createDeviceRequestSignature, deriveInstallationId, fingerprintSource, randomInstallationId };