@indigoai-us/hq-cloud 5.1.0

package/dist/cognito-auth.js

@@ -0,0 +1,280 @@
+/**
+ * Cognito browser-OAuth helper (VLT-9).
+ *
+ * Drives the Cognito Hosted UI authorization-code + PKCE flow for the
+ * vault-service User Pool. Used by the CLI (`hq login`, `create-hq`) to
+ * obtain a JWT that is then passed to the vault-service API as
+ * `Authorization: Bearer <accessToken>`.
+ *
+ * Why PKCE: the CLI is a public client (no secret), so we use PKCE per
+ * RFC 7636 to prove that the same process that started the auth request
+ * is the one exchanging the code for tokens.
+ *
+ * Why a localhost callback: Cognito allows `http://localhost:*` as a
+ * redirect URI specifically for native/CLI apps (RFC 8252 §7). We spin
+ * up a one-shot HTTP server on the chosen port, capture exactly one
+ * callback, then close it.
+ */
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as http from "http";
+import * as path from "path";
+import * as os from "os";
+import open from "open";
+/** Returned when an interactive login is needed but stdin/browser is unavailable. */
+export class CognitoAuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CognitoAuthError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Token cache (~/.hq/cognito-tokens.json)
+// ---------------------------------------------------------------------------
+const HQ_DIR = path.join(os.homedir(), ".hq");
+const TOKEN_FILE = path.join(HQ_DIR, "cognito-tokens.json");
+export function loadCachedTokens() {
+    if (!fs.existsSync(TOKEN_FILE))
+        return null;
+    try {
+        const raw = fs.readFileSync(TOKEN_FILE, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function saveCachedTokens(tokens) {
+    if (!fs.existsSync(HQ_DIR)) {
+        fs.mkdirSync(HQ_DIR, { recursive: true, mode: 0o700 });
+    }
+    fs.writeFileSync(TOKEN_FILE, JSON.stringify(tokens, null, 2), { mode: 0o600 });
+}
+export function clearCachedTokens() {
+    if (fs.existsSync(TOKEN_FILE))
+        fs.unlinkSync(TOKEN_FILE);
+}
+/** True when the token expires within the given buffer (default 60s). */
+export function isExpiring(tokens, bufferSeconds = 60) {
+    const expiresAt = new Date(tokens.expiresAt).getTime();
+    return expiresAt - Date.now() < bufferSeconds * 1000;
+}
+// ---------------------------------------------------------------------------
+// PKCE
+// ---------------------------------------------------------------------------
+function base64UrlEncode(buf) {
+    return buf
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+function generatePkce() {
+    const verifier = base64UrlEncode(crypto.randomBytes(32));
+    const challenge = base64UrlEncode(crypto.createHash("sha256").update(verifier).digest());
+    return { verifier, challenge };
+}
+// ---------------------------------------------------------------------------
+// Endpoint helpers
+// ---------------------------------------------------------------------------
+function authBaseUrl(config) {
+    return `https://${config.userPoolDomain}.auth.${config.region}.amazoncognito.com`;
+}
+function redirectUri(port) {
+    return `http://localhost:${port}/callback`;
+}
+// ---------------------------------------------------------------------------
+// Browser login
+// ---------------------------------------------------------------------------
+/**
+ * Open the Cognito Hosted UI in the user's browser, wait for the redirect
+ * back to localhost, and exchange the auth code for tokens.
+ *
+ * Times out after 5 minutes if the user doesn't complete the flow.
+ */
+export async function browserLogin(config) {
+    const port = config.port ?? 3000;
+    const scopes = (config.scopes ?? ["openid", "email", "profile"]).join(" ");
+    const { verifier, challenge } = generatePkce();
+    const state = base64UrlEncode(crypto.randomBytes(16));
+    const authUrl = new URL(`${authBaseUrl(config)}/login`);
+    authUrl.searchParams.set("client_id", config.clientId);
+    authUrl.searchParams.set("response_type", "code");
+    authUrl.searchParams.set("scope", scopes);
+    authUrl.searchParams.set("redirect_uri", redirectUri(port));
+    authUrl.searchParams.set("code_challenge", challenge);
+    authUrl.searchParams.set("code_challenge_method", "S256");
+    authUrl.searchParams.set("state", state);
+    const code = await waitForAuthCode(port, state);
+    const tokens = await exchangeCodeForTokens(config, code, verifier, port);
+    saveCachedTokens(tokens);
+    return tokens;
+    // -- inner: spin up loopback server and open browser ---------------------
+    function waitForAuthCode(port, expectedState) {
+        return new Promise((resolve, reject) => {
+            // cleanup() is a function declaration so it can be referenced from the
+            // server callbacks and the timeout closure below before its source
+            // position. It clears the 15-min login timer + closes the loopback
+            // server — without this both keep Node's event loop alive after the
+            // calling script "completes", making it look hung.
+            const server = http.createServer((req, res) => {
+                const url = new URL(req.url ?? "/", `http://localhost:${port}`);
+                if (url.pathname !== "/callback") {
+                    res.writeHead(404);
+                    res.end("Not found");
+                    return;
+                }
+                const code = url.searchParams.get("code");
+                const state = url.searchParams.get("state");
+                const error = url.searchParams.get("error");
+                if (error) {
+                    res.writeHead(400, { "Content-Type": "text/html" });
+                    res.end(`<h1>Authentication failed</h1><p>${escapeHtml(error)}</p>`);
+                    cleanup();
+                    reject(new CognitoAuthError(`Cognito returned error: ${error}`));
+                    return;
+                }
+                if (state !== expectedState) {
+                    res.writeHead(400, { "Content-Type": "text/html" });
+                    res.end("<h1>State mismatch</h1><p>Possible CSRF — try again.</p>");
+                    cleanup();
+                    reject(new CognitoAuthError("Cognito state parameter mismatch"));
+                    return;
+                }
+                if (!code) {
+                    res.writeHead(400, { "Content-Type": "text/html" });
+                    res.end("<h1>Missing code</h1>");
+                    cleanup();
+                    reject(new CognitoAuthError("Cognito callback missing code"));
+                    return;
+                }
+                res.writeHead(200, { "Content-Type": "text/html" });
+                res.end(`<!doctype html><html><body style="font-family:system-ui;text-align:center;padding:48px;">
+            <h1>Signed in to HQ by Indigo</h1>
+            <p>You can close this tab and return to your terminal.</p>
+            <script>setTimeout(()=>window.close(),1500)</script>
+          </body></html>`);
+                cleanup();
+                resolve(code);
+            });
+            server.on("error", (err) => {
+                cleanup();
+                reject(err);
+            });
+            server.listen(port, "127.0.0.1", () => {
+                console.log(`\n  Opening browser for HQ sign-in...`);
+                console.log(`  If your browser doesn't open, visit:\n  ${authUrl.toString()}\n`);
+                open(authUrl.toString()).catch(() => {
+                    /* user can paste the URL manually */
+                });
+            });
+            const loginTimer = setTimeout(() => {
+                cleanup();
+                reject(new CognitoAuthError("Login timed out after 15 minutes"));
+            }, 15 * 60 * 1000);
+            function cleanup() {
+                clearTimeout(loginTimer);
+                server.close();
+            }
+        });
+    }
+}
+async function exchangeCodeForTokens(config, code, verifier, port) {
+    const body = new URLSearchParams({
+        grant_type: "authorization_code",
+        client_id: config.clientId,
+        code,
+        code_verifier: verifier,
+        redirect_uri: redirectUri(port),
+    });
+    const res = await fetch(`${authBaseUrl(config)}/oauth2/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new CognitoAuthError(`Token exchange failed (${res.status}): ${text}`);
+    }
+    const data = (await res.json());
+    if (!data.refresh_token) {
+        throw new CognitoAuthError("Cognito did not return a refresh token — check OAuth scopes include offline_access semantics");
+    }
+    return {
+        accessToken: data.access_token,
+        idToken: data.id_token,
+        refreshToken: data.refresh_token,
+        expiresAt: new Date(Date.now() + data.expires_in * 1000).toISOString(),
+        tokenType: "Bearer",
+    };
+}
+/**
+ * Use the refresh token to obtain a fresh access token without user interaction.
+ * The refresh token itself is NOT rotated by Cognito on the refresh grant, so
+ * we preserve the existing one in the result.
+ */
+export async function refreshTokens(config, currentRefreshToken) {
+    const body = new URLSearchParams({
+        grant_type: "refresh_token",
+        client_id: config.clientId,
+        refresh_token: currentRefreshToken,
+    });
+    const res = await fetch(`${authBaseUrl(config)}/oauth2/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new CognitoAuthError(`Refresh failed (${res.status}): ${text}`);
+    }
+    const data = (await res.json());
+    const tokens = {
+        accessToken: data.access_token,
+        idToken: data.id_token,
+        refreshToken: data.refresh_token ?? currentRefreshToken,
+        expiresAt: new Date(Date.now() + data.expires_in * 1000).toISOString(),
+        tokenType: "Bearer",
+    };
+    saveCachedTokens(tokens);
+    return tokens;
+}
+/**
+ * High-level helper: return a non-expired access token, refreshing or
+ * launching browser login as needed.
+ *
+ * Pass `interactive: false` from automated contexts where you would rather
+ * fail fast than open a browser.
+ */
+export async function getValidAccessToken(config, options = {}) {
+    const interactive = options.interactive ?? true;
+    const cached = loadCachedTokens();
+    if (cached && !isExpiring(cached))
+        return cached.accessToken;
+    if (cached) {
+        try {
+            const refreshed = await refreshTokens(config, cached.refreshToken);
+            return refreshed.accessToken;
+        }
+        catch {
+            // fall through to interactive login
+        }
+    }
+    if (!interactive) {
+        throw new CognitoAuthError("No valid HQ session and interactive login is disabled. Run `hq login` first.");
+    }
+    const fresh = await browserLogin(config);
+    return fresh.accessToken;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+//# sourceMappingURL=cognito-auth.js.map

package/dist/cognito-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cognito-auth.js","sourceRoot":"","sources":["../src/cognito-auth.ts"],"names":[],"mappings":"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"}

package/dist/context.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Entity context resolution (VLT-5 US-001).
+ *
+ * Resolves an entity (company) via vault-service, vends STS-scoped credentials,
+ * and returns an EntityContext for S3 operations. Handles auto-refresh when
+ * credentials are within 2 minutes of expiry.
+ */
+import type { EntityContext, VaultServiceConfig } from "./types.js";
+/**
+ * Look up an entity by slug or UID via vault-service, then vend STS-scoped
+ * credentials for that entity. Returns an EntityContext ready for S3 ops.
+ *
+ * Caches the result and auto-refreshes when the credentials are within
+ * 2 minutes of expiry.
+ */
+export declare function resolveEntityContext(companyUidOrSlug: string, config: VaultServiceConfig): Promise<EntityContext>;
+/**
+ * Check if credentials are expiring within the refresh threshold.
+ */
+export declare function isExpiringSoon(expiresAt: string): boolean;
+/**
+ * Force-refresh a cached context. Useful when an S3 operation fails with
+ * an expired credentials error.
+ */
+export declare function refreshEntityContext(companyUidOrSlug: string, config: VaultServiceConfig): Promise<EntityContext>;
+/**
+ * Clear the entire context cache. Useful for tests.
+ */
+export declare function clearContextCache(): void;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAWpE;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,aAAa,CAAC,CAwCxB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAIzD;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,aAAa,CAAC,CAIxB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}

package/dist/context.js

@@ -0,0 +1,117 @@
+/**
+ * Entity context resolution (VLT-5 US-001).
+ *
+ * Resolves an entity (company) via vault-service, vends STS-scoped credentials,
+ * and returns an EntityContext for S3 operations. Handles auto-refresh when
+ * credentials are within 2 minutes of expiry.
+ */
+/** Minimum remaining TTL before auto-refresh triggers (2 minutes). */
+const REFRESH_THRESHOLD_MS = 2 * 60 * 1000;
+/** STS session duration requested from vault-service (15 minutes). */
+const DEFAULT_SESSION_DURATION_SECONDS = 900;
+/** Cached contexts keyed by entity UID. */
+const contextCache = new Map();
+/**
+ * Look up an entity by slug or UID via vault-service, then vend STS-scoped
+ * credentials for that entity. Returns an EntityContext ready for S3 ops.
+ *
+ * Caches the result and auto-refreshes when the credentials are within
+ * 2 minutes of expiry.
+ */
+export async function resolveEntityContext(companyUidOrSlug, config) {
+    // Check cache — return if credentials still fresh
+    const cached = contextCache.get(companyUidOrSlug);
+    if (cached && !isExpiringSoon(cached.expiresAt)) {
+        return cached;
+    }
+    // Step 1: Resolve entity — if it looks like a UID (cmp_*), fetch directly;
+    // otherwise look up by slug
+    const entity = companyUidOrSlug.startsWith("cmp_")
+        ? await fetchEntity(companyUidOrSlug, config)
+        : await fetchEntityBySlug("company", companyUidOrSlug, config);
+    if (!entity.bucketName) {
+        throw new Error(`Entity ${entity.uid} (${entity.slug}) has no bucket provisioned. ` +
+            `Run VLT-2 bucket provisioning first.`);
+    }
+    // Step 2: Vend STS-scoped credentials
+    const vendResult = await vendCredentials(entity.uid, config);
+    const ctx = {
+        uid: entity.uid,
+        bucketName: entity.bucketName,
+        region: config.region ?? "us-east-1",
+        credentials: {
+            accessKeyId: vendResult.credentials.accessKeyId,
+            secretAccessKey: vendResult.credentials.secretAccessKey,
+            sessionToken: vendResult.credentials.sessionToken,
+        },
+        expiresAt: vendResult.expiresAt,
+    };
+    // Cache by both UID and slug for fast lookups
+    contextCache.set(entity.uid, ctx);
+    contextCache.set(entity.slug, ctx);
+    return ctx;
+}
+/**
+ * Check if credentials are expiring within the refresh threshold.
+ */
+export function isExpiringSoon(expiresAt) {
+    const expiryMs = new Date(expiresAt).getTime();
+    const nowMs = Date.now();
+    return expiryMs - nowMs < REFRESH_THRESHOLD_MS;
+}
+/**
+ * Force-refresh a cached context. Useful when an S3 operation fails with
+ * an expired credentials error.
+ */
+export async function refreshEntityContext(companyUidOrSlug, config) {
+    // Evict cache entry to force fresh resolution
+    contextCache.delete(companyUidOrSlug);
+    return resolveEntityContext(companyUidOrSlug, config);
+}
+/**
+ * Clear the entire context cache. Useful for tests.
+ */
+export function clearContextCache() {
+    contextCache.clear();
+}
+async function fetchEntity(uid, config) {
+    const res = await fetch(`${config.apiUrl}/entity/${uid}`, {
+        headers: { Authorization: `Bearer ${config.authToken}` },
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`Failed to fetch entity ${uid}: ${res.status} ${body}`);
+    }
+    const data = (await res.json());
+    return data.entity;
+}
+async function fetchEntityBySlug(type, slug, config) {
+    const res = await fetch(`${config.apiUrl}/entity/by-slug/${type}/${slug}`, {
+        headers: { Authorization: `Bearer ${config.authToken}` },
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`Failed to find entity by slug ${type}/${slug}: ${res.status} ${body}`);
+    }
+    const data = (await res.json());
+    return data.entity;
+}
+async function vendCredentials(companyUid, config) {
+    const res = await fetch(`${config.apiUrl}/sts/vend`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${config.authToken}`,
+        },
+        body: JSON.stringify({
+            companyUid,
+            durationSeconds: DEFAULT_SESSION_DURATION_SECONDS,
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`STS vend failed for ${companyUid}: ${res.status} ${body}`);
+    }
+    return (await res.json());
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/context.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Unit tests for context.ts — entity context resolution (VLT-5 US-001).
+ *
+ * Uses a mock fetch to simulate vault-service API responses.
+ */
+export {};
+//# sourceMappingURL=context.test.d.ts.map

package/dist/context.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.test.d.ts","sourceRoot":"","sources":["../src/context.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/context.test.js

@@ -0,0 +1,148 @@
+/**
+ * Unit tests for context.ts — entity context resolution (VLT-5 US-001).
+ *
+ * Uses a mock fetch to simulate vault-service API responses.
+ */
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { resolveEntityContext, refreshEntityContext, clearContextCache, isExpiringSoon, } from "./context.js";
+const mockConfig = {
+    apiUrl: "https://vault-api.test",
+    authToken: "test-jwt-token",
+    region: "us-east-1",
+};
+const mockEntity = {
+    uid: "cmp_01ABCDEF",
+    slug: "acme",
+    bucketName: "hq-vault-acme-123",
+    status: "active",
+};
+const mockVendResponse = {
+    credentials: {
+        accessKeyId: "ASIA_TEST_KEY",
+        secretAccessKey: "test-secret",
+        sessionToken: "test-session-token",
+        expiration: new Date(Date.now() + 15 * 60 * 1000).toISOString(),
+    },
+    expiresAt: new Date(Date.now() + 15 * 60 * 1000).toISOString(),
+};
+function setupFetchMock(overrides) {
+    const fetchMock = vi.fn();
+    fetchMock.mockImplementation(async (url) => {
+        const urlStr = String(url);
+        if (urlStr.includes("/entity/by-slug/")) {
+            return {
+                ok: (overrides?.entityStatus ?? 200) < 400,
+                status: overrides?.entityStatus ?? 200,
+                json: async () => overrides?.entityBody ?? { entity: mockEntity },
+                text: async () => JSON.stringify(overrides?.entityBody ?? { entity: mockEntity }),
+            };
+        }
+        if (urlStr.includes("/entity/cmp_")) {
+            return {
+                ok: (overrides?.entityStatus ?? 200) < 400,
+                status: overrides?.entityStatus ?? 200,
+                json: async () => overrides?.entityBody ?? { entity: mockEntity },
+                text: async () => JSON.stringify(overrides?.entityBody ?? { entity: mockEntity }),
+            };
+        }
+        if (urlStr.includes("/sts/vend")) {
+            return {
+                ok: (overrides?.vendStatus ?? 200) < 400,
+                status: overrides?.vendStatus ?? 200,
+                json: async () => overrides?.vendBody ?? mockVendResponse,
+                text: async () => JSON.stringify(overrides?.vendBody ?? mockVendResponse),
+            };
+        }
+        return { ok: false, status: 404, text: async () => "Not found" };
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    return fetchMock;
+}
+describe("resolveEntityContext", () => {
+    beforeEach(() => {
+        clearContextCache();
+        vi.restoreAllMocks();
+    });
+    it("resolves context by slug", async () => {
+        const fetchMock = setupFetchMock();
+        const ctx = await resolveEntityContext("acme", mockConfig);
+        expect(ctx.uid).toBe("cmp_01ABCDEF");
+        expect(ctx.bucketName).toBe("hq-vault-acme-123");
+        expect(ctx.credentials.accessKeyId).toBe("ASIA_TEST_KEY");
+        expect(ctx.region).toBe("us-east-1");
+        // Verify entity lookup used by-slug endpoint
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        expect(String(fetchMock.mock.calls[0][0])).toContain("/entity/by-slug/company/acme");
+        expect(String(fetchMock.mock.calls[1][0])).toContain("/sts/vend");
+    });
+    it("resolves context by UID directly", async () => {
+        const fetchMock = setupFetchMock();
+        const ctx = await resolveEntityContext("cmp_01ABCDEF", mockConfig);
+        expect(ctx.uid).toBe("cmp_01ABCDEF");
+        // Verify entity lookup used direct UID endpoint
+        expect(String(fetchMock.mock.calls[0][0])).toContain("/entity/cmp_01ABCDEF");
+    });
+    it("returns cached context when credentials are fresh", async () => {
+        const fetchMock = setupFetchMock();
+        const ctx1 = await resolveEntityContext("acme", mockConfig);
+        const ctx2 = await resolveEntityContext("acme", mockConfig);
+        expect(ctx1).toBe(ctx2); // Same reference
+        expect(fetchMock).toHaveBeenCalledTimes(2); // Only 1 entity + 1 vend call
+    });
+    it("auto-refreshes when credentials expire soon", async () => {
+        const almostExpired = new Date(Date.now() + 60 * 1000).toISOString(); // 1 min left
+        const fetchMock = setupFetchMock({
+            vendBody: {
+                credentials: mockVendResponse.credentials,
+                expiresAt: almostExpired,
+            },
+        });
+        const ctx1 = await resolveEntityContext("acme", mockConfig);
+        // Second call should refresh because <2 min remaining
+        const ctx2 = await resolveEntityContext("acme", mockConfig);
+        expect(ctx2).not.toBe(ctx1);
+        expect(fetchMock).toHaveBeenCalledTimes(4); // 2 entity + 2 vend calls
+    });
+    it("throws when entity has no bucket", async () => {
+        setupFetchMock({
+            entityBody: { entity: { ...mockEntity, bucketName: undefined } },
+        });
+        await expect(resolveEntityContext("acme", mockConfig)).rejects.toThrow(/no bucket provisioned/);
+    });
+    it("throws on entity lookup failure", async () => {
+        setupFetchMock({ entityStatus: 404 });
+        await expect(resolveEntityContext("nonexistent", mockConfig)).rejects.toThrow(/Failed to find entity/);
+    });
+    it("throws on STS vend failure", async () => {
+        setupFetchMock({ vendStatus: 403 });
+        await expect(resolveEntityContext("acme", mockConfig)).rejects.toThrow(/STS vend failed/);
+    });
+});
+describe("refreshEntityContext", () => {
+    beforeEach(() => {
+        clearContextCache();
+        vi.restoreAllMocks();
+    });
+    it("evicts cache and fetches fresh credentials", async () => {
+        const fetchMock = setupFetchMock();
+        const ctx1 = await resolveEntityContext("acme", mockConfig);
+        const ctx2 = await refreshEntityContext("acme", mockConfig);
+        expect(ctx2).not.toBe(ctx1);
+        expect(fetchMock).toHaveBeenCalledTimes(4); // 2 initial + 2 refresh
+    });
+});
+describe("isExpiringSoon", () => {
+    it("returns false when well within TTL", () => {
+        const future = new Date(Date.now() + 10 * 60 * 1000).toISOString();
+        expect(isExpiringSoon(future)).toBe(false);
+    });
+    it("returns true when within 2 minutes", () => {
+        const soon = new Date(Date.now() + 90 * 1000).toISOString();
+        expect(isExpiringSoon(soon)).toBe(true);
+    });
+    it("returns true when already expired", () => {
+        const past = new Date(Date.now() - 1000).toISOString();
+        expect(isExpiringSoon(past)).toBe(true);
+    });
+});
+//# sourceMappingURL=context.test.js.map

package/dist/context.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.test.js","sourceRoot":"","sources":["../src/context.test.ts"],"names":[],"mappings":"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"}

package/dist/daemon-worker.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Daemon worker — runs as a detached child process
+ * Watches HQ directory and syncs changes to S3
+ */
+export {};
+//# sourceMappingURL=daemon-worker.d.ts.map

package/dist/daemon-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-worker.d.ts","sourceRoot":"","sources":["../src/daemon-worker.ts"],"names":[],"mappings":"AAAA;;;GAGG"}