@indigoai-us/hq-cli 5.345.133 → 5.345.135

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

package/dist/lib/fingerprint/self-core.js

@@ -0,0 +1,371 @@
+/**
+ * The network-free part of the session fingerprint builder: session id,
+ * company, machine id, the fingerprint.yaml cache, and the synchronous offline
+ * build. Lane start and the handoff commits import this module directly, so
+ * it must never import vault-api, cognito-session, hq-cloud, or any other
+ * network client, not even lazily. The person lookup lives in self.ts.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import yaml from "js-yaml";
+import { peekIdToken } from "../../utils/id-token.js";
+import { build, COMPANY_RE } from "./format.js";
+export const SESSION_ID_ENV_VARS = [
+    "HQ_SESSION_ID",
+    "CLAUDE_CODE_SESSION_ID",
+    "CLAUDE_SESSION_ID",
+    "CODEX_SESSION_ID",
+    "CODEX_THREAD_ID",
+    "GROK_SESSION_ID",
+];
+export const IDENTITY_LOOKUP_TIMEOUT_MS = 3000;
+export const FINGERPRINT_FILE = "fingerprint.yaml";
+const SESSION_ID_RE = /^[A-Za-z0-9._-]+$/;
+export const IDENTITY_UID_RE = /^(prs|agt)_[A-Za-z0-9]{8,}$/;
+function registrationKeys(cache) {
+    const keys = {};
+    if (typeof cache?.registered_at === "string" && cache.registered_at)
+        keys.registered_at = cache.registered_at;
+    if (typeof cache?.registration_skipped === "string" && cache.registration_skipped) {
+        keys.registration_skipped = cache.registration_skipped;
+    }
+    return keys;
+}
+export function resolveSessionId(env) {
+    for (const name of SESSION_ID_ENV_VARS) {
+        const value = env[name];
+        if (!value)
+            continue;
+        if (value === "." || value === "..")
+            continue;
+        if (!SESSION_ID_RE.test(value))
+            continue;
+        return value;
+    }
+    return null;
+}
+export function sessionDir(hqRoot, sessionId) {
+    return path.join(hqRoot, "workspace", "sessions", sessionId);
+}
+/** Reads a YAML mapping. Unreadable or unparseable files warn and count as missing. */
+function readYamlRecord(file, warn) {
+    try {
+        const parsed = yaml.load(fs.readFileSync(file, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        warn(`hq fingerprint: ignoring unreadable ${file}: ${err.message}`);
+        return null;
+    }
+}
+function resolveCompany(hqRoot, sessionId, env, warn) {
+    let company = null;
+    let from = "";
+    if (sessionId) {
+        const meta = readYamlRecord(path.join(sessionDir(hqRoot, sessionId), "meta.yaml"), warn);
+        const slug = meta?.company_slug;
+        if (typeof slug === "string" && slug.trim()) {
+            company = slug.trim();
+            from = "meta.yaml company_slug";
+        }
+    }
+    if (!company && env.HQ_COMPANY)
+        [company, from] = [env.HQ_COMPANY, "HQ_COMPANY"];
+    if (!company && env.HQ_SPAWN_COMPANY)
+        [company, from] = [env.HQ_SPAWN_COMPANY, "HQ_SPAWN_COMPANY"];
+    if (company && !COMPANY_RE.test(company)) {
+        warn(`hq fingerprint: ignoring ${from}: not a company slug`);
+        return null;
+    }
+    return company;
+}
+/**
+ * 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 function readOrCreateMachineId(hqRoot) {
+    const file = path.join(hqRoot, ".hq", "machine-id");
+    try {
+        const existing = fs.readFileSync(file, "utf8").trim();
+        if (existing)
+            return existing;
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    let id = null;
+    try {
+        const menubar = JSON.parse(fs.readFileSync(path.join(os.homedir(), ".hq", "menubar.json"), "utf8"));
+        if (typeof menubar?.machineId === "string" && menubar.machineId)
+            id = menubar.machineId;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT" && !(err instanceof SyntaxError))
+            throw err;
+    }
+    id ??= randomUUID();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${id}\n`);
+    return id;
+}
+/** Read `<hqRoot>/.hq/machine-id` without creating it. Null when it is missing or empty. */
+export function readMachineIdIfPresent(hqRoot) {
+    try {
+        return fs.readFileSync(path.join(hqRoot, ".hq", "machine-id"), "utf8").trim() || null;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+/** Machine ids are usually UUIDs. A free-form id is hashed so the fingerprint keeps 8 hex chars. */
+export function machineIdForFingerprint(machineId) {
+    const hex = machineId.toLowerCase().replace(/-/g, "");
+    if (/^[0-9a-f]{8,}$/.test(hex))
+        return machineId;
+    return createHash("sha256").update(machineId).digest("hex");
+}
+function tokenOwner(sub) {
+    return typeof sub === "string" && sub ? createHash("sha256").update(sub).digest("hex") : null;
+}
+function writeCacheAtomic(file, record, warn) {
+    const tmp = `${file}.${process.pid}.tmp`;
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(tmp, yaml.dump(record));
+        fs.renameSync(tmp, file);
+    }
+    catch (err) {
+        warn(`hq fingerprint: could not write ${file}: ${err.message}`);
+        fs.rmSync(tmp, { force: true });
+    }
+}
+function kindOfUid(uid) {
+    return uid.startsWith("agt_") ? "agent" : "person";
+}
+export function identityContext(deps, idToken, creds) {
+    const env = deps.env ?? process.env;
+    const hqRoot = deps.hqRoot;
+    const warn = deps.warn ?? ((message) => process.stderr.write(`${message}\n`));
+    const sessionId = resolveSessionId(env);
+    const claims = idToken ? peekIdToken(idToken) : {};
+    const entityType = typeof claims["custom:entityType"] === "string" ? claims["custom:entityType"] : null;
+    const entityUid = typeof claims["custom:entityUid"] === "string" ? claims["custom:entityUid"] : null;
+    const owner = tokenOwner(claims.sub);
+    let hostKind = "laptop";
+    if (entityType === "agent" || creds)
+        hostKind = "fleet";
+    if (entityType === "outpost" ||
+        entityType === "company-outpost" ||
+        entityUid?.startsWith("out_") ||
+        creds?.entityType === "outpost" ||
+        creds?.entityType === "company-outpost") {
+        hostKind = "outpost";
+    }
+    const cacheFile = sessionId && !deps.noRoot ? path.join(sessionDir(hqRoot, sessionId), FINGERPRINT_FILE) : null;
+    const rawCache = cacheFile ? readYamlRecord(cacheFile, warn) : null;
+    // A cache written for another signed-in user says nothing about this one.
+    const cached = rawCache && (rawCache.token_owner ?? null) === owner ? rawCache : null;
+    const agentPrincipal = entityType === "agent" || creds?.entityType === "agent" || entityUid?.startsWith("agt_") === true;
+    let identityUid = null;
+    let source = "none";
+    let needsLookup = false;
+    if (entityUid && IDENTITY_UID_RE.test(entityUid)) {
+        identityUid = entityUid;
+        source = "token";
+    }
+    else if (creds?.entityUid && IDENTITY_UID_RE.test(creds.entityUid)) {
+        identityUid = creds.entityUid;
+        source = "machine-creds";
+    }
+    else if (cached?.identity_lookup_done) {
+        identityUid = typeof cached.identity_uid === "string" ? cached.identity_uid : null;
+        source = "cache";
+    }
+    else if (sessionId && !deps.offline && idToken && hostKind !== "outpost" && !agentPrincipal) {
+        needsLookup = true;
+    }
+    return {
+        env,
+        hqRoot,
+        warn,
+        sessionId,
+        idToken,
+        owner,
+        hostKind,
+        cacheFile,
+        identityUid,
+        source,
+        lookupDone: cached?.identity_lookup_done === true,
+        needsLookup,
+        cachedRegistration: {
+            fingerprint: typeof rawCache?.fingerprint === "string" ? rawCache.fingerprint : null,
+            ...registrationKeys(rawCache),
+        },
+    };
+}
+/**
+ * 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 function buildSelfFingerprintOfflineSync(deps) {
+    const warn = deps.warn ?? ((message) => process.stderr.write(`${message}\n`));
+    let idToken = null;
+    try {
+        idToken = deps.loadIdToken();
+    }
+    catch (err) {
+        warn(`hq fingerprint: could not read the cached token: ${err.message}`);
+    }
+    let creds = null;
+    try {
+        creds = deps.loadMachineCreds();
+    }
+    catch (err) {
+        warn(`hq fingerprint: could not read machine creds: ${err.message}`);
+    }
+    const offlineDeps = { ...deps, offline: true };
+    return finishFingerprint(offlineDeps, identityContext(offlineDeps, idToken, creds));
+}
+export function finishFingerprint(deps, ctx) {
+    const result = finishFingerprintAtRoot(deps, ctx);
+    if (!deps.noRoot)
+        return result;
+    return { ...result, reason: result.reason ? `no HQ root; ${result.reason}` : "no HQ root" };
+}
+function finishFingerprintAtRoot(deps, ctx) {
+    const { env, hqRoot, warn, sessionId, idToken, owner, hostKind, cacheFile, identityUid, source, lookupDone } = ctx;
+    let rawMachineId = deps.noRoot ? null : env.HQ_MACHINE_ID?.trim() || null;
+    if (!rawMachineId && !deps.noRoot) {
+        try {
+            rawMachineId = (deps.readMachineId ?? (deps.readOnly ? readMachineIdIfPresent : readOrCreateMachineId))(hqRoot);
+        }
+        catch (err) {
+            warn(`hq fingerprint: could not read the machine id: ${err.message}`);
+        }
+    }
+    const machineId = rawMachineId ? machineIdForFingerprint(rawMachineId) : null;
+    const company = resolveCompany(hqRoot, deps.noRoot ? null : sessionId, env, warn);
+    const identityKind = identityUid ? kindOfUid(identityUid) : null;
+    if (!identityUid && !sessionId) {
+        return {
+            fingerprint: null,
+            company,
+            identityUid: null,
+            identityKind: null,
+            machineId: rawMachineId,
+            hostKind,
+            sessionId: null,
+            source,
+            reason: idToken
+                ? "no session id in the environment and no identity uid on the cached token"
+                : "no session id in the environment and not signed in",
+        };
+    }
+    if (deps.readOnly && !machineId) {
+        return {
+            fingerprint: null,
+            company,
+            identityUid,
+            identityKind,
+            machineId: null,
+            hostKind,
+            sessionId,
+            source,
+            reason: "no machine id and read-only mode does not create one",
+        };
+    }
+    let fingerprint;
+    try {
+        fingerprint = build({ company, identityUid, hostKind, machineId, sessionId });
+    }
+    catch (err) {
+        return {
+            fingerprint: null,
+            company,
+            identityUid,
+            identityKind,
+            machineId: rawMachineId,
+            hostKind,
+            sessionId,
+            source,
+            reason: `could not build fingerprint: ${err.message}`,
+        };
+    }
+    if (sessionId && cacheFile && !deps.readOnly) {
+        const record = {
+            fingerprint,
+            company,
+            identity_uid: identityUid,
+            identity_kind: identityKind,
+            identity_lookup_done: lookupDone,
+            token_owner: owner,
+            machine_id: rawMachineId,
+            host_kind: hostKind,
+            session_id: sessionId,
+            built_at: (deps.now ?? (() => new Date()))().toISOString(),
+            // The fingerprint names company, identity, machine and session, so the
+            // same value means hq-pro already holds this exact record.
+            ...(ctx.cachedRegistration?.fingerprint === fingerprint ? registrationKeys(ctx.cachedRegistration) : {}),
+        };
+        writeCacheAtomic(cacheFile, record, warn);
+    }
+    return {
+        fingerprint,
+        company,
+        identityUid,
+        identityKind,
+        machineId: rawMachineId,
+        hostKind,
+        sessionId,
+        source,
+    };
+}
+function cachePathFor(hqRoot, sessionId) {
+    return path.join(sessionDir(hqRoot, sessionId), FINGERPRINT_FILE);
+}
+/**
+ * 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 function readRegistrationState(hqRoot, sessionId, fingerprint, warn) {
+    const cache = readYamlRecord(cachePathFor(hqRoot, sessionId), warn);
+    if (!cache || cache.fingerprint !== fingerprint)
+        return null;
+    const keys = registrationKeys(cache);
+    return { registeredAt: keys.registered_at ?? null, skipped: keys.registration_skipped ?? 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 function recordRegistrationState(hqRoot, sessionId, fingerprint, update, warn) {
+    const file = cachePathFor(hqRoot, sessionId);
+    const cache = readYamlRecord(file, warn);
+    if (!cache || cache.fingerprint !== fingerprint)
+        return false;
+    const record = { ...cache };
+    if ("registeredAt" in update) {
+        record.registered_at = update.registeredAt;
+        delete record.registration_skipped;
+    }
+    else {
+        record.registration_skipped = update.skipped;
+    }
+    writeCacheAtomic(file, record, warn);
+    return true;
+}
+//# sourceMappingURL=self-core.js.map

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

@@ -0,0 +1,44 @@
+import type { RegistryFetch } from "./registry-client.js";
+import { type MachineCredsSummary, type SelfFingerprint, type SelfFingerprintDeps } from "./self-core.js";
+export * from "./self-core.js";
+/** An unparseable creds file yields null, so it never marks the host as fleet. */
+export declare function defaultLoadMachineCreds(): Promise<MachineCredsSummary | null>;
+export declare function buildSelfFingerprint(deps: SelfFingerprintDeps): Promise<SelfFingerprint>;
+export interface RegisterSelfDeps {
+    hqRoot: string;
+    env?: NodeJS.ProcessEnv;
+    offline?: boolean;
+    /** false when the caller passed --no-register. */
+    register?: boolean;
+    loadIdToken?: () => string | null | Promise<string | null>;
+    fetch?: RegistryFetch;
+    timeoutMs?: number;
+    /** Directory for fingerprint.log. Defaults to ~/.hq. */
+    logDir?: string;
+    now?: () => Date;
+}
+export type RegisterSelfOutcome = {
+    status: "registered";
+} | {
+    status: "already-registered";
+} | {
+    status: "skipped";
+    reason: string;
+} | {
+    status: "failed";
+    reason: string;
+};
+/**
+ * Records this session's fingerprint with hq-pro (POST /v1/fingerprints), at
+ * most once per session. Fire-and-forget: it never writes to stdout or stderr
+ * and never throws, so the printed fingerprint and the exit code stay the
+ * same whatever the registry does.
+ *
+ * hq-pro denies company-outpost machine tokens, so outpost hosts skip the call
+ * and record `registration_skipped: outpost`. A 403 is also final and is
+ * recorded the same way. A 404 means the registry is not deployed for this
+ * API, so it records `registration_skipped: unavailable` and the session stops
+ * calling. Any other failure is logged and retried next run.
+ */
+export declare function registerSelfFingerprint(self: SelfFingerprint, deps: RegisterSelfDeps): Promise<RegisterSelfOutcome>;
+//# sourceMappingURL=self.d.ts.map