@indigoai-us/hq-cli 5.345.134 → 5.345.136

package/dist/lib/fingerprint/registry-client.js

@@ -0,0 +1,141 @@
+/**
+ * Client for the hq-pro fingerprint registry (session-fingerprints US-006):
+ *
+ *   POST /v1/fingerprints          record this session's fingerprint
+ *   GET  /v1/fingerprints/{value}  resolve a fingerprint to its record
+ *
+ * Every call is capped at REGISTRY_TIMEOUT_MS and never throws: failures come
+ * back as a typed result. vault-api is imported lazily, and self.ts and the
+ * command import this module lazily, so the offline builder (self-core.ts,
+ * offline.ts) never reaches it.
+ *
+ * Failures are written as one line to ~/.hq/fingerprint.log. A line names the
+ * operation, the HTTP status or the error class, and the server's error text,
+ * never a token or a request header.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+export const REGISTRY_TIMEOUT_MS = 3000;
+export const FINGERPRINT_LOG_FILE = "fingerprint.log";
+async function defaultFetch(opts) {
+    const { vaultApiFetch } = await import("../../utils/vault-api.js");
+    return vaultApiFetch(opts);
+}
+/** Runs the request with an AbortController that fires after the timeout. */
+async function withDeadline(run, ms) {
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            const err = new Error(`timed out after ${ms}ms`);
+            err.name = "TimeoutError";
+            controller.abort(err);
+            reject(err);
+        }, ms);
+    });
+    try {
+        return await Promise.race([run(controller.signal), timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function readJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        // A body that is not JSON (an HTML gateway page, an empty 502) has no
+        // fields to read; the caller reports the status instead.
+        return null;
+    }
+}
+function serverError(body, status) {
+    if (body && typeof body === "object") {
+        const record = body;
+        if (typeof record.error === "string")
+            return record.error;
+        if (typeof record.message === "string")
+            return record.message;
+    }
+    return `HTTP ${status}`;
+}
+function thrownError(err) {
+    const e = err instanceof Error ? err : new Error(String(err));
+    return { ok: false, status: null, error: `${e.name}: ${e.message}` };
+}
+export async function registerFingerprint(body, token, opts = {}) {
+    const fetchImpl = opts.fetch ?? defaultFetch;
+    try {
+        const response = await withDeadline((signal) => fetchImpl({
+            baseUrl: opts.baseUrl,
+            token,
+            path: "/v1/fingerprints",
+            method: "POST",
+            body: { ...body },
+            signal,
+        }), opts.timeoutMs ?? REGISTRY_TIMEOUT_MS);
+        const json = await readJson(response);
+        if (response.status === 200 || response.status === 201) {
+            return { ok: true, status: response.status, row: json };
+        }
+        return { ok: false, status: response.status, error: serverError(json, response.status) };
+    }
+    catch (err) {
+        return thrownError(err);
+    }
+}
+export async function lookupFingerprint(value, token, opts = {}) {
+    const fetchImpl = opts.fetch ?? defaultFetch;
+    try {
+        const response = await withDeadline((signal) => fetchImpl({
+            baseUrl: opts.baseUrl,
+            token,
+            path: `/v1/fingerprints/${encodeURIComponent(value)}`,
+            signal,
+        }), opts.timeoutMs ?? REGISTRY_TIMEOUT_MS);
+        const json = await readJson(response);
+        if (response.status === 200 && json && typeof json === "object") {
+            return { ok: true, found: true, record: json };
+        }
+        // Unknown values and fingerprints of other companies get the same 404.
+        if (response.status === 404)
+            return { ok: true, found: false };
+        return { ok: false, status: response.status, error: serverError(json, response.status) };
+    }
+    catch (err) {
+        return thrownError(err);
+    }
+}
+export function fingerprintLogPath(dir = path.join(os.homedir(), ".hq")) {
+    return path.join(dir, FINGERPRINT_LOG_FILE);
+}
+/** Strips newlines and anything shaped like a bearer token or a JWT. */
+function sanitize(text) {
+    return text
+        .replace(/[\r\n]+/g, " ")
+        .replace(/Bearer\s+\S+/gi, "Bearer <redacted>")
+        .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*/g, "<redacted>")
+        .replace(/\bhqk_[A-Za-z0-9_-]+/g, "<redacted>")
+        .slice(0, 300);
+}
+/**
+ * Appends one line to ~/.hq/fingerprint.log. A log that cannot be written is
+ * dropped: registration is fire-and-forget and must not print or fail.
+ */
+export function appendFingerprintLog(op, detail, opts = {}) {
+    const file = fingerprintLogPath(opts.dir);
+    const at = (opts.now ?? (() => new Date()))().toISOString();
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, `${at} ${op} ${sanitize(detail)}\n`, { mode: 0o600 });
+    }
+    catch {
+        // Nowhere left to report it without changing the command's output.
+    }
+}
+export function describeFailure(result) {
+    return result.status === null ? result.error : `status=${result.status} ${result.error}`;
+}
+//# sourceMappingURL=registry-client.js.map

package/dist/lib/fingerprint/resolve-local.d.ts

@@ -0,0 +1,14 @@
+import type { HostKind, IdentityKind } from "./format.js";
+export interface LocalFingerprintRecord {
+    fingerprint: string;
+    identityUid: string | null;
+    identityKind: IdentityKind | null;
+    machineId: string | null;
+    hostKind: HostKind | null;
+    sessionId: string | null;
+    company: string | null;
+    builtAt: string | null;
+    source: "local";
+}
+export declare function resolveLocalFingerprint(hqRoot: string, value: string): LocalFingerprintRecord | null;
+//# sourceMappingURL=resolve-local.d.ts.map

package/dist/lib/fingerprint/resolve-local.js

@@ -0,0 +1,67 @@
+/**
+ * Resolve a fingerprint against this machine's session records
+ * (workspace/sessions/<sid>/fingerprint.yaml). Exact value match only.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import yaml from "js-yaml";
+import { FINGERPRINT_FILE } from "./self-core.js";
+function str(value) {
+    return typeof value === "string" && value ? value : null;
+}
+export function resolveLocalFingerprint(hqRoot, value) {
+    const sessionsDir = path.join(hqRoot, "workspace", "sessions");
+    let entries;
+    try {
+        entries = fs.readdirSync(sessionsDir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const file = path.join(sessionsDir, entry.name, FINGERPRINT_FILE);
+        let raw;
+        try {
+            raw = fs.readFileSync(file, "utf8");
+        }
+        catch (err) {
+            if (err.code !== "ENOENT") {
+                process.stderr.write(`hq fingerprint: skipping unreadable ${file}: ${err.message}\n`);
+            }
+            continue;
+        }
+        // A cheap substring check skips the YAML parse for the many sessions that do not match.
+        if (!raw.includes(value))
+            continue;
+        let record;
+        try {
+            record = yaml.load(raw);
+        }
+        catch (err) {
+            process.stderr.write(`hq fingerprint: skipping unreadable ${file}: ${err.message}\n`);
+            continue;
+        }
+        if (!record || typeof record !== "object")
+            continue;
+        const r = record;
+        if (r.fingerprint !== value)
+            continue;
+        return {
+            fingerprint: value,
+            identityUid: str(r.identity_uid),
+            identityKind: str(r.identity_kind) ?? null,
+            machineId: str(r.machine_id),
+            hostKind: str(r.host_kind) ?? null,
+            sessionId: str(r.session_id),
+            company: str(r.company),
+            builtAt: str(r.built_at),
+            source: "local",
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=resolve-local.js.map

package/dist/lib/fingerprint/self-core.d.ts

@@ -0,0 +1,139 @@
+import { type HostKind, type IdentityKind } from "./format.js";
+export declare const SESSION_ID_ENV_VARS: readonly ["HQ_SESSION_ID", "CLAUDE_CODE_SESSION_ID", "CLAUDE_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID", "GROK_SESSION_ID"];
+export declare const IDENTITY_LOOKUP_TIMEOUT_MS = 3000;
+export declare const FINGERPRINT_FILE = "fingerprint.yaml";
+export declare const IDENTITY_UID_RE: RegExp;
+export type IdentitySource = "token" | "machine-creds" | "cache" | "lookup" | "none";
+export interface SelfFingerprint {
+    fingerprint: string | null;
+    company: string | null;
+    identityUid: string | null;
+    identityKind: IdentityKind | null;
+    machineId: string | null;
+    hostKind: HostKind;
+    sessionId: string | null;
+    source: IdentitySource;
+    reason?: string;
+}
+export interface MachineCredsSummary {
+    entityType?: string;
+    entityUid?: string;
+}
+export interface SelfFingerprintDeps {
+    hqRoot: string;
+    env?: NodeJS.ProcessEnv;
+    offline?: boolean;
+    /** Returns the cached ID token, or null when signed out. */
+    loadIdToken?: () => string | null | Promise<string | null>;
+    /** Returns the machine creds, or null when this host has none or they are unreadable. */
+    loadMachineCreds?: () => MachineCredsSummary | null | Promise<MachineCredsSummary | null>;
+    /** Resolves the caller's uid over the network. The signal aborts on timeout. */
+    resolveIdentity?: (idToken: string, signal: AbortSignal) => Promise<{
+        kind: IdentityKind;
+        uid: string;
+    }>;
+    readMachineId?: (hqRoot: string) => string | null;
+    /**
+     * Never create or write a file: read an existing machine id only, return a
+     * null fingerprint without one, and skip the session cache write. For the
+     * handoff commits, which must leave the tree as the shell script does.
+     */
+    readOnly?: boolean;
+    /**
+     * The caller found no HQ root, so `hqRoot` names no HQ tree. The machine is
+     * `-`, nothing under `hqRoot` is read or written, and the result carries
+     * `reason: "no HQ root"`.
+     */
+    noRoot?: boolean;
+    lookupTimeoutMs?: number;
+    now?: () => Date;
+    warn?: (message: string) => void;
+}
+interface FingerprintCacheFile {
+    fingerprint?: string | null;
+    company?: string | null;
+    identity_uid?: string | null;
+    identity_kind?: IdentityKind | null;
+    identity_lookup_done?: boolean;
+    /** sha256 of the ID token `sub` the identity was resolved for, or null without one. */
+    token_owner?: string | null;
+    machine_id?: string | null;
+    host_kind?: HostKind;
+    session_id?: string;
+    built_at?: string;
+    /** When hq-pro recorded this fingerprint (US-007). Set by the registry step in self.ts. */
+    registered_at?: string;
+    /** Why registration will not be tried again for this fingerprint, such as "outpost". */
+    registration_skipped?: string;
+}
+/** Registration keys carried across rewrites while the fingerprint stays the same. */
+type RegistrationKeys = Pick<FingerprintCacheFile, "registered_at" | "registration_skipped">;
+export declare function resolveSessionId(env: NodeJS.ProcessEnv): string | null;
+export declare function sessionDir(hqRoot: string, sessionId: string): string;
+/**
+ * Read `<hqRoot>/.hq/machine-id`, creating it when missing. Mirrors
+ * getOrCreateMachineId in hq-cloud, which the package does not export (its
+ * exports map has no ./lib/machine-id entry). Falls back to the menubar id in
+ * ~/.hq/menubar.json before generating a new UUID, as hq-cloud does.
+ */
+export declare function readOrCreateMachineId(hqRoot: string): string | null;
+/** Read `<hqRoot>/.hq/machine-id` without creating it. Null when it is missing or empty. */
+export declare function readMachineIdIfPresent(hqRoot: string): string | null;
+/** Machine ids are usually UUIDs. A free-form id is hashed so the fingerprint keeps 8 hex chars. */
+export declare function machineIdForFingerprint(machineId: string): string;
+export interface IdentityContext {
+    env: NodeJS.ProcessEnv;
+    hqRoot: string;
+    warn: (message: string) => void;
+    sessionId: string | null;
+    idToken: string | null;
+    owner: string | null;
+    hostKind: HostKind;
+    cacheFile: string | null;
+    identityUid: string | null;
+    source: IdentitySource;
+    lookupDone: boolean;
+    /** True when no local source named the identity and a person lookup may run. */
+    needsLookup: boolean;
+    /** The cached fingerprint and its registration keys, kept when the value is unchanged. */
+    cachedRegistration?: {
+        fingerprint: string | null;
+    } & RegistrationKeys;
+}
+export declare function identityContext(deps: SelfFingerprintDeps, idToken: string | null, creds: MachineCredsSummary | null): IdentityContext;
+export interface SelfFingerprintSyncDeps extends Omit<SelfFingerprintDeps, "offline" | "loadIdToken" | "loadMachineCreds" | "resolveIdentity" | "lookupTimeoutMs"> {
+    /** Returns the cached ID token, or null when signed out. */
+    loadIdToken: () => string | null;
+    /** Returns the machine creds, or null when this host has none or they are unreadable. */
+    loadMachineCreds: () => MachineCredsSummary | null;
+}
+/**
+ * The offline build as a synchronous call, for callers that cannot await
+ * (lane start). It never does the person lookup, so the loaders are required:
+ * the default ones live in self.ts, which loads them lazily and only
+ * asynchronously.
+ */
+export declare function buildSelfFingerprintOfflineSync(deps: SelfFingerprintSyncDeps): SelfFingerprint;
+export declare function finishFingerprint(deps: SelfFingerprintDeps, ctx: IdentityContext): SelfFingerprint;
+export interface FingerprintRegistrationState {
+    registeredAt: string | null;
+    skipped: string | null;
+}
+/**
+ * The registration keys of this session's fingerprint.yaml, or null when the
+ * file is missing or holds another fingerprint (the registry step then has no
+ * record to mark).
+ */
+export declare function readRegistrationState(hqRoot: string, sessionId: string, fingerprint: string, warn: (message: string) => void): FingerprintRegistrationState | null;
+/**
+ * Writes registered_at or registration_skipped into fingerprint.yaml. Re-reads
+ * the file first and writes nothing when it now holds another fingerprint.
+ * Returns true when the file was rewritten.
+ */
+export declare function recordRegistrationState(hqRoot: string, sessionId: string, fingerprint: string, update: {
+    registeredAt: string;
+} | {
+    skipped: string;
+}, warn: (message: string) => void): boolean;
+export {};
+//# sourceMappingURL=self-core.d.ts.map