@serviceme/devtools-core 0.1.8 → 0.2.0

package/dist/device.mjs

@@ -0,0 +1,647 @@
+// src/device/deviceAuth.ts
+import { createHash } from "crypto";
+var 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"
+};
+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");
+}
+function buildSignedHeaders(params) {
+  const timestamp = params.timestamp ?? Date.now();
+  const signature = createDeviceRequestSignature({
+    method: params.method,
+    path: params.path,
+    timestamp,
+    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)
+  };
+}
+
+// src/device/Enroller.ts
+import { randomBytes } from "crypto";
+
+// src/device/InstallationId.ts
+import { createHash as createHash2, randomUUID } from "crypto";
+import * as os from "os";
+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("|");
+}
+function deriveInstallationId() {
+  const material = fingerprintMaterial();
+  const digest = createHash2("sha256").update(material).digest("hex");
+  return formatAsV4(digest.slice(0, 32));
+}
+function randomInstallationId() {
+  return randomUUID();
+}
+function fingerprintSource() {
+  return fingerprintMaterial();
+}
+function formatAsV4(hex32) {
+  const chars = hex32.split("");
+  const versionIdx = 12;
+  const variantIdx = 16;
+  const versionChar = parseInt(chars[versionIdx] ?? "8", 16) & 0 | 4;
+  chars[versionIdx] = versionChar.toString(16);
+  const variantChar = parseInt(chars[variantIdx] ?? "8", 16) & 3 | 8;
+  chars[variantIdx] = variantChar.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)}`;
+}
+
+// src/device/Enroller.ts
+var SECRET_BYTES = 32;
+var PUBLIC_ID_BYTES = 16;
+var defaultRandomBytes = (size) => {
+  return randomBytes(size);
+};
+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";
+  }
+};
+var DeviceSecretVersionMismatchError = class extends Error {
+  constructor(message = "Device secret version mismatch \u2014 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() {
+    const stored = await this.identity.read();
+    return stored?.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 platform3 = current?.platform ?? "unknown";
+      let response;
+      if (this.enrollRequest) {
+        response = await this.enrollRequest({
+          installationId,
+          machineId,
+          platform: platform3,
+          existing,
+          force: Boolean(opts.force),
+          requireAuth: Boolean(opts.requireAuth)
+        });
+      } else {
+        response = synthesizeEnrollResponse(this.random, existing);
+      }
+      const next = {
+        version: current?.version ?? 1,
+        installationId,
+        machineId,
+        platform: platform3,
+        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 { next };
+    });
+    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);
+      const next = {
+        ...current,
+        deviceSecret: newSecret,
+        previousDeviceSecret: current.deviceSecret,
+        previousSecretExpiresAt: graceExpiresAt.toISOString(),
+        secretVersion: current.secretVersion + 1,
+        lastEnrollAt: now.toISOString()
+      };
+      return { next };
+    });
+    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 };
+      }
+      const next = { ...current, bindingState: "expired" };
+      return { next };
+    });
+  }
+  /**
+   * 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");
+      }
+      const next = {
+        ...current,
+        bindingState: "claimed",
+        lastSyncAt: this.now().toISOString(),
+        lastSyncError: void 0
+      };
+      return { next };
+    });
+  }
+};
+function deriveExpiresAt(_identity, _now) {
+  return void 0;
+}
+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()
+  };
+}
+
+// src/device/IdentityStore.ts
+import * as fsp from "fs/promises";
+import * as os3 from "os";
+import * as path2 from "path";
+import { setTimeout as delay } from "timers/promises";
+
+// src/paths/userHome.ts
+import * as os2 from "os";
+import * as path from "path";
+var SERVICEME_DIR_NAME = ".serviceme";
+var SERVICEME_HOME_ENV = "SERVICEME_HOME";
+var activeOverrides = {};
+function resolveHomeDir() {
+  const injected = activeOverrides.homeDir;
+  if (injected !== void 0) {
+    return injected;
+  }
+  return os2.homedir();
+}
+function resolveServicemeHomeEnv() {
+  const injected = activeOverrides.servicemeHomeEnv;
+  if (injected !== void 0) {
+    return injected.length > 0 ? injected : void 0;
+  }
+  const envValue = process.env[SERVICEME_HOME_ENV];
+  return envValue && envValue.length > 0 ? envValue : void 0;
+}
+function getServicemeHome() {
+  const override = resolveServicemeHomeEnv();
+  if (override !== void 0) {
+    return path.resolve(override);
+  }
+  return path.join(resolveHomeDir(), SERVICEME_DIR_NAME);
+}
+var DEVICE_JSON_FILENAME = "device.json";
+function getDeviceJsonPath() {
+  return path.join(getServicemeHome(), DEVICE_JSON_FILENAME);
+}
+
+// src/device/types.ts
+var DEVICE_JSON_SCHEMA_VERSION = 1;
+
+// src/device/IdentityStore.ts
+var FILE_MODE = 384;
+var LOCK_DIR_MODE = 448;
+var DEFAULT_LOCK_TIMEOUT_MS = 5e3;
+var DEFAULT_LOCK_RETRY_MS = 25;
+var TMP_SUFFIX = ".tmp";
+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");
+      const parsed = JSON.parse(buf);
+      return migratePersistedIdentity(parsed);
+    } catch (err) {
+      if (isNodeError(err) && err.code === "ENOENT") return null;
+      throw err;
+    }
+  }
+  async write(filePath, payload) {
+    await fsp.mkdir(path2.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 });
+  }
+};
+function migratePersistedIdentity(parsed) {
+  if (!isRecord(parsed)) {
+    throw new Error("device.json: top-level must be an object");
+  }
+  const version = parsed.version;
+  if (version === DEVICE_JSON_SCHEMA_VERSION) {
+    if (parsed.publicId === void 0 && parsed.deviceSecret === void 0 && ("claimed" in parsed || "publicKeyFingerprint" in parsed)) {
+      return null;
+    }
+    return parsed;
+  }
+  if (typeof version === "number" && version < DEVICE_JSON_SCHEMA_VERSION) {
+    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";
+}
+var FileLock = class {
+  constructor(filePath, timeoutMs, retryMs) {
+    this.acquired = false;
+    this.dirPath = `${filePath}.lock`;
+    this.timeoutMs = timeoutMs;
+    this.retryMs = retryMs;
+  }
+  async acquire() {
+    const start = Date.now();
+    while (true) {
+      try {
+        await fsp.mkdir(this.dirPath, { mode: LOCK_DIR_MODE });
+        this.acquired = true;
+        return;
+      } catch (err) {
+        if (!isNodeError(err) || err.code !== "EEXIST") {
+          throw err;
+        }
+        if (Date.now() - start >= this.timeoutMs) {
+          throw new Error(`IdentityStore lock acquisition timed out for ${this.dirPath}`);
+        }
+        await delay(this.retryMs);
+      }
+    }
+  }
+  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;
+    this.now = opts.now ?? (() => /* @__PURE__ */ new Date());
+  }
+  /** 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: DEVICE_JSON_SCHEMA_VERSION
+      };
+      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 current = await this.backend.read(this.filePath);
+      const { next, result } = await mutator(current);
+      const stamped = {
+        ...next,
+        version: DEVICE_JSON_SCHEMA_VERSION
+      };
+      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() {
+    const machineId = os3.hostname();
+    const platform3 = os3.platform();
+    return {
+      installationId: "",
+      // intentionally empty; caller fills via deriveInstallationId()
+      machineId,
+      platform: platform3
+    };
+  }
+  /**
+   * 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(path2.dirname(this.filePath), { recursive: true });
+  }
+};
+
+// 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 canonical 5-header map for an outbound signed request. */
+  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
+  };
+}
+export {
+  DEVICE_JSON_SCHEMA_VERSION,
+  DeviceAuthHeaders,
+  DeviceCore,
+  DeviceReenrollRequiresAuthError,
+  DeviceSecretVersionMismatchError,
+  Enroller,
+  FsIdentityFileBackend,
+  IdentityStore,
+  buildSignedHeaders,
+  createDeviceRequestSignature,
+  deriveInstallationId,
+  fingerprintSource,
+  randomInstallationId
+};
+//# sourceMappingURL=device.mjs.map