@serviceme/devtools-core 2.0.0 → 2.0.2

package/dist/index-BI11AfMH.d.mts

@@ -0,0 +1,377 @@
+import { DeviceBindingState, DeviceEnrollResult, DeviceRotateSecretResult, DeviceStatus } from "@serviceme/devtools-protocol";
+//#region src/device/deviceAuth.d.ts
+/**
+ * deviceAuth — Pure HMAC-SHA-256 signing helpers for device auth headers.
+ *
+ * **Boundary exception copy.** The single source of truth for the
+ * `x-ms-device-*` header names + the signature algorithm 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. The basis is `METHOD\nPATH\nTIMESTAMP\nBODY\nSECRET`
+ * (LF-joined, NOT JSON). Output is lowercase hex SHA-256.
+ */
+/** Canonical header names — MUST match `@serviceme/devtools-shared`'s `DeviceAuthHeaders`. */
+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;
+//#endregion
+//#region src/device/types.d.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>;
+}
+//#endregion
+//#region src/device/IdentityStore.d.ts
+/**
+ * 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;
+  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>;
+}
+//#endregion
+//#region src/device/Enroller.d.ts
+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>;
+}
+//#endregion
+//#region src/device/DeviceCore.d.ts
+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;
+}
+//#endregion
+//#region src/device/InstallationId.d.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
+ */
+/**
+ * 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;
+//#endregion
+export { DeviceSignedHeaders as C, DeviceRequestSignatureParams as S, createDeviceRequestSignature as T, DEVICE_JSON_SCHEMA_VERSION as _, DeviceCoreOptions as a, BuildSignedHeadersParams as b, EnrollRequestFn as c, EnrollerOptions as d, FsIdentityFileBackend as f, AtomicWriteResult as g, IdentityStoreOptions as h, DeviceCore as i, EnrollResponse as l, IdentityStore as m, fingerprintSource as n, DeviceReenrollRequiresAuthError as o, IdentityFileBackend as p, randomInstallationId as r, DeviceSecretVersionMismatchError as s, deriveInstallationId as t, Enroller as u, IdentityStoreHooks as v, buildSignedHeaders as w, DeviceAuthHeaders as x, PersistedDeviceIdentity as y };
+//# sourceMappingURL=index-BI11AfMH.d.mts.map