@newhomestar/sdk 0.5.2 → 0.6.5

package/dist/credentials.js

@@ -0,0 +1,754 @@
+// Nova SDK — Credential Resolution & mTLS-aware Fetch
+// =====================================================
+// Generic infrastructure for resolving OAuth credentials for ANY integration.
+// Handles three auth modes:
+//   - 'mtls'               → client_credentials + mTLS cert/key
+//   - 'client_credentials' → client_credentials grant (server-to-server)
+//   - 'standard'           → authorization_code (per-user OAuth redirect)
+//
+// Two credential resolution strategies:
+//   A. Direct DB (PLATFORM_SUPABASE_*) — container has direct DB access
+//   B. HTTP callback (AUTH_ISSUER_BASE_URL) — container calls auth server with JWT
+//
+// Tokens are cached:
+//   1. In-memory Map (hot path — no I/O)
+//   2. user_app_connections DB rows (durable — vault-encrypted) [strategy A only]
+//   3. Fresh token exchange (cold path — network + vault I/O)
+//
+// Every integration gets this for free via ctx.resolveCredentials() / ctx.fetch().
+import { createClient } from "@supabase/supabase-js";
+import https from "node:https";
+// ─── Error Classes ──────────────────────────────────────────────────────────
+export class IntegrationNotFoundError extends Error {
+    constructor(slug) {
+        super(`Integration "${slug}" not found or not registered`);
+        this.name = "IntegrationNotFoundError";
+    }
+}
+export class IntegrationDisabledError extends Error {
+    constructor(slug) {
+        super(`Integration "${slug}" is disabled. Enable it in the admin dashboard.`);
+        this.name = "IntegrationDisabledError";
+    }
+}
+export class CredentialsNotConfiguredError extends Error {
+    constructor(slug, detail) {
+        super(`Integration "${slug}" credentials not configured: ${detail}`);
+        this.name = "CredentialsNotConfiguredError";
+    }
+}
+export class ConnectionNotFoundError extends Error {
+    constructor(slug, userId) {
+        super(`No active connection found for user "${userId}" on integration "${slug}". The user must authorize first.`);
+        this.name = "ConnectionNotFoundError";
+    }
+}
+export class TokenExchangeError extends Error {
+    constructor(slug, detail) {
+        super(`Token exchange failed for "${slug}": ${detail}`);
+        this.name = "TokenExchangeError";
+    }
+}
+// ─── Platform Client Singleton ──────────────────────────────────────────────
+let _platformClient = null;
+/**
+ * Creates / returns the singleton Platform DB client.
+ * Reads from PLATFORM_SUPABASE_URL + PLATFORM_SUPABASE_SERVICE_ROLE_KEY.
+ */
+export function createPlatformClient() {
+    if (!_platformClient) {
+        const url = process.env.PLATFORM_SUPABASE_URL;
+        const key = process.env.PLATFORM_SUPABASE_SERVICE_ROLE_KEY;
+        if (!url || !key) {
+            throw new Error("[nova-sdk] Missing PLATFORM_SUPABASE_URL or PLATFORM_SUPABASE_SERVICE_ROLE_KEY. " +
+                "These should be injected by the Nova orchestrator at container runtime.");
+        }
+        _platformClient = createClient(url, key, {
+            auth: { autoRefreshToken: false, persistSession: false },
+        });
+        console.log("[nova-sdk] ✅ Platform DB client initialized");
+    }
+    return _platformClient;
+}
+const _tokenCache = new Map();
+/** Token buffer — refresh tokens 5 minutes before actual expiry */
+const TOKEN_EXPIRY_BUFFER_MS = 5 * 60 * 1000;
+/** System user UUID for client_credentials/mTLS connections (audit trail) */
+const SYSTEM_USER_ID = "00000000-0000-0000-0000-000000000000";
+function getCacheKey(integrationSlug, userId) {
+    return `${integrationSlug}:${userId ?? SYSTEM_USER_ID}`;
+}
+function getCachedToken(key) {
+    const cached = _tokenCache.get(key);
+    if (!cached)
+        return null;
+    if (new Date().getTime() >= cached.expiresAt.getTime() - TOKEN_EXPIRY_BUFFER_MS) {
+        console.log(`[nova-sdk] 🔄 In-memory cached token expired for ${key}`);
+        _tokenCache.delete(key);
+        return null;
+    }
+    return cached;
+}
+// ─── Vault Helpers ──────────────────────────────────────────────────────────
+async function getVaultSecret(platformDB, vaultId, label) {
+    if (!vaultId)
+        return null;
+    console.log(`[nova-sdk] 🔐 Reading vault secret: ${label} (${vaultId.slice(0, 8)}...)`);
+    const { data, error } = await platformDB.rpc("get_vault_secret", { p_id: vaultId });
+    if (error) {
+        if (error.code === "PGRST116")
+            return null;
+        throw new Error(`[nova-sdk] Vault read failed for ${label}: ${error.message}`);
+    }
+    return data ?? null;
+}
+async function storeVaultSecret(platformDB, name, value, description) {
+    console.log(`[nova-sdk] 🔐 Storing vault secret: ${name}`);
+    const { data, error } = await platformDB.rpc("create_vault_secret", {
+        p_secret: value,
+        p_name: name,
+        p_description: description ?? `Nova integration credential: ${name}`,
+    });
+    if (error) {
+        throw new Error(`[nova-sdk] Vault store failed for ${name}: ${error.message}`);
+    }
+    return data;
+}
+async function updateVaultSecret(platformDB, vaultId, newValue) {
+    const { error } = await platformDB.rpc("update_vault_secret", {
+        p_id: vaultId,
+        p_secret: newValue,
+    });
+    if (error) {
+        throw new Error(`[nova-sdk] Vault update failed for ${vaultId}: ${error.message}`);
+    }
+}
+// ─── mTLS Agent Builder ─────────────────────────────────────────────────────
+// Cache mTLS agents per integration slug (cert/key don't change during container lifetime)
+const _mtlsAgents = new Map();
+async function buildMtlsAgent(platformDB, config) {
+    const existing = _mtlsAgents.get(config.slug);
+    if (existing)
+        return existing;
+    if (!config.mtls_cert_vault_id || !config.mtls_key_vault_id) {
+        throw new CredentialsNotConfiguredError(config.slug, "mTLS cert and/or key not stored in vault. Upload PEM files via admin dashboard.");
+    }
+    const [certPem, keyPem] = await Promise.all([
+        getVaultSecret(platformDB, config.mtls_cert_vault_id, "mtls_cert"),
+        getVaultSecret(platformDB, config.mtls_key_vault_id, "mtls_key"),
+    ]);
+    if (!certPem || !keyPem) {
+        throw new CredentialsNotConfiguredError(config.slug, "mTLS cert or key vault entries are empty. Re-upload PEM files.");
+    }
+    console.log(`[nova-sdk] 🔒 Built mTLS agent for "${config.slug}" (cert: ${certPem.length} bytes, key: ${keyPem.length} bytes)`);
+    const agent = new https.Agent({ cert: certPem, key: keyPem, keepAlive: true });
+    _mtlsAgents.set(config.slug, agent);
+    return agent;
+}
+async function performTokenExchange(slug, params) {
+    const { tokenEndpoint, clientId, clientSecret, httpsAgent, grantType = "client_credentials", } = params;
+    const body = new URLSearchParams({
+        grant_type: grantType,
+        client_id: clientId,
+        client_secret: clientSecret,
+    });
+    // For mTLS, we must use node:https directly because global fetch()
+    // doesn't support custom TLS agents.
+    if (httpsAgent) {
+        return new Promise((resolve, reject) => {
+            const url = new URL(tokenEndpoint);
+            const reqOptions = {
+                hostname: url.hostname,
+                port: url.port || 443,
+                path: url.pathname + url.search,
+                method: "POST",
+                agent: httpsAgent,
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    "Content-Length": Buffer.byteLength(body.toString()),
+                    Accept: "application/json",
+                },
+            };
+            const req = https.request(reqOptions, (res) => {
+                let data = "";
+                res.on("data", (chunk) => (data += chunk));
+                res.on("end", () => {
+                    if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+                        try {
+                            resolve(JSON.parse(data));
+                        }
+                        catch {
+                            reject(new TokenExchangeError(slug, `Invalid JSON response: ${data.slice(0, 200)}`));
+                        }
+                    }
+                    else {
+                        reject(new TokenExchangeError(slug, `HTTP ${res.statusCode}: ${data.slice(0, 500)}`));
+                    }
+                });
+            });
+            req.on("error", (err) => {
+                reject(new TokenExchangeError(slug, `mTLS request error: ${err.message}`));
+            });
+            req.write(body.toString());
+            req.end();
+        });
+    }
+    // Non-mTLS: use regular fetch
+    const res = await fetch(tokenEndpoint, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+            Accept: "application/json",
+        },
+        body: body.toString(),
+    });
+    if (!res.ok) {
+        const errText = await res.text();
+        throw new TokenExchangeError(slug, `HTTP ${res.status}: ${errText.slice(0, 500)}`);
+    }
+    return res.json();
+}
+// ─── Main: resolveCredentials() ─────────────────────────────────────────────
+/**
+ * Resolves an access token for an integration, handling all auth modes.
+ *
+ * Flow:
+ * 1. Look up integration config from app_integrations (by slug)
+ * 2. Check auth_mode → route to server or user flow
+ * 3. Check in-memory cache → DB (user_app_connections) → exchange if needed
+ * 4. Cache the result and return
+ *
+ * @param platformDB  - Platform Supabase client (project-starfleet-auth)
+ * @param slug        - Integration slug (e.g., 'adp', 'salesforce')
+ * @param userId      - User ID for standard OAuth; optional for server flows
+ */
+export async function resolveCredentials(platformDB, slug, userId) {
+    console.log(`[nova-sdk] 🔑 Resolving credentials for "${slug}" (userId: ${userId ?? "system"})`);
+    // ── Step 1: Look up integration config ────────────────────────────────
+    const { data: integration, error: intError } = await platformDB
+        .from("app_integrations")
+        .select("id, slug, name, auth_mode, client_id, client_secret_vault_id, token_endpoint, mtls_cert_vault_id, mtls_key_vault_id, is_active")
+        .eq("slug", slug)
+        .single();
+    if (intError || !integration) {
+        console.error(`[nova-sdk] ❌ Integration "${slug}" not found:`, intError?.message);
+        throw new IntegrationNotFoundError(slug);
+    }
+    if (!integration.is_active) {
+        console.error(`[nova-sdk] ❌ Integration "${slug}" is disabled`);
+        throw new IntegrationDisabledError(slug);
+    }
+    const config = integration;
+    console.log(`[nova-sdk] 📋 Integration: ${config.name} | auth_mode=${config.auth_mode} | id=${config.id}`);
+    // ── Step 2: Route by auth_mode ────────────────────────────────────────
+    switch (config.auth_mode) {
+        case "mtls":
+        case "client_credentials":
+            return resolveServerCredentials(platformDB, config, userId);
+        case "standard":
+            if (!userId) {
+                throw new Error(`[nova-sdk] userId is required for standard OAuth (authorization_code) flow on "${slug}"`);
+            }
+            return resolveUserCredentials(platformDB, config, userId);
+        default:
+            throw new Error(`[nova-sdk] Unknown auth_mode: ${config.auth_mode}`);
+    }
+}
+// ─── Server Credentials (client_credentials / mTLS) ─────────────────────────
+async function resolveServerCredentials(platformDB, config, userId) {
+    const effectiveUserId = userId ?? SYSTEM_USER_ID;
+    const cacheKey = getCacheKey(config.slug, effectiveUserId);
+    // ── Check in-memory cache ─────────────────────────────────────────────
+    const cached = getCachedToken(cacheKey);
+    if (cached) {
+        console.log(`[nova-sdk] ⚡ Using in-memory cached token (expires ${cached.expiresAt.toISOString()})`);
+        return {
+            accessToken: cached.accessToken,
+            expiresAt: cached.expiresAt,
+            integrationId: config.id,
+            authMode: config.auth_mode,
+            httpsAgent: cached.httpsAgent,
+        };
+    }
+    // ── Check DB cache (user_app_connections) ─────────────────────────────
+    const { data: existingConn } = await platformDB
+        .from("user_app_connections")
+        .select("id, access_token_vault_id, refresh_token_vault_id, token_expires_at, is_active")
+        .eq("integration_id", config.id)
+        .eq("user_id", effectiveUserId)
+        .eq("is_active", true)
+        .single();
+    if (existingConn?.access_token_vault_id && existingConn.token_expires_at) {
+        const expiresAt = new Date(existingConn.token_expires_at);
+        const now = new Date();
+        if (expiresAt.getTime() - TOKEN_EXPIRY_BUFFER_MS > now.getTime()) {
+            console.log(`[nova-sdk] 📦 Found valid cached token in DB (expires ${expiresAt.toISOString()})`);
+            const accessToken = await getVaultSecret(platformDB, existingConn.access_token_vault_id, "cached_access_token");
+            if (accessToken) {
+                const httpsAgent = config.auth_mode === "mtls"
+                    ? await buildMtlsAgent(platformDB, config)
+                    : undefined;
+                _tokenCache.set(cacheKey, { accessToken, expiresAt, httpsAgent });
+                return {
+                    accessToken,
+                    expiresAt,
+                    integrationId: config.id,
+                    authMode: config.auth_mode,
+                    httpsAgent,
+                };
+            }
+            console.warn(`[nova-sdk] ⚠️ Vault secret missing for cached token — will re-exchange`);
+        }
+        else {
+            console.log(`[nova-sdk] 🔄 Cached token expired (was ${expiresAt.toISOString()}) — re-exchanging`);
+        }
+    }
+    else {
+        console.log(`[nova-sdk] 📭 No cached token found in DB — performing initial token exchange`);
+    }
+    // ── Exchange for new token ────────────────────────────────────────────
+    return exchangeAndCacheServerToken(platformDB, config, effectiveUserId, existingConn?.id);
+}
+async function exchangeAndCacheServerToken(platformDB, config, userId, existingConnectionId) {
+    // Validate required fields
+    if (!config.client_id) {
+        throw new CredentialsNotConfiguredError(config.slug, "client_id is not set");
+    }
+    if (!config.client_secret_vault_id) {
+        throw new CredentialsNotConfiguredError(config.slug, "client_secret is not stored in vault");
+    }
+    if (!config.token_endpoint) {
+        throw new CredentialsNotConfiguredError(config.slug, "token_endpoint is not set");
+    }
+    // Decrypt client_secret from vault
+    const clientSecret = await getVaultSecret(platformDB, config.client_secret_vault_id, "client_secret");
+    if (!clientSecret) {
+        throw new CredentialsNotConfiguredError(config.slug, "client_secret vault entry is empty");
+    }
+    // Build mTLS agent if needed
+    let httpsAgent;
+    if (config.auth_mode === "mtls") {
+        httpsAgent = await buildMtlsAgent(platformDB, config);
+    }
+    console.log(`[nova-sdk] 🔄 Exchanging client_credentials at ${config.token_endpoint} for "${config.slug}"`);
+    const tokenResponse = await performTokenExchange(config.slug, {
+        tokenEndpoint: config.token_endpoint,
+        clientId: config.client_id,
+        clientSecret,
+        httpsAgent,
+    });
+    const expiresAt = new Date(Date.now() + tokenResponse.expires_in * 1000);
+    const cacheKey = getCacheKey(config.slug, userId);
+    console.log(`[nova-sdk] ✅ Token exchange successful for "${config.slug}" — expires ${expiresAt.toISOString()} (${tokenResponse.expires_in}s)`);
+    // ── Store token in vault + user_app_connections ───────────────────────
+    const vaultName = `connection:${userId}:${config.slug}:access_token`;
+    let accessTokenVaultId;
+    if (existingConnectionId) {
+        const { data: conn } = await platformDB
+            .from("user_app_connections")
+            .select("access_token_vault_id")
+            .eq("id", existingConnectionId)
+            .single();
+        if (conn?.access_token_vault_id) {
+            await updateVaultSecret(platformDB, conn.access_token_vault_id, tokenResponse.access_token);
+            accessTokenVaultId = conn.access_token_vault_id;
+        }
+        else {
+            accessTokenVaultId = await storeVaultSecret(platformDB, vaultName, tokenResponse.access_token);
+        }
+        await platformDB
+            .from("user_app_connections")
+            .update({
+            access_token_vault_id: accessTokenVaultId,
+            token_expires_at: expiresAt.toISOString(),
+            token_scope: tokenResponse.scope ?? null,
+            last_used_at: new Date().toISOString(),
+            is_active: true,
+        })
+            .eq("id", existingConnectionId);
+        console.log(`[nova-sdk] 📦 Updated existing connection ${existingConnectionId}`);
+    }
+    else {
+        accessTokenVaultId = await storeVaultSecret(platformDB, vaultName, tokenResponse.access_token);
+        const { error: insertError } = await platformDB
+            .from("user_app_connections")
+            .upsert({
+            user_id: userId,
+            integration_id: config.id,
+            access_token_vault_id: accessTokenVaultId,
+            token_expires_at: expiresAt.toISOString(),
+            token_scope: tokenResponse.scope ?? null,
+            is_active: true,
+            last_used_at: new Date().toISOString(),
+            metadata: { auth_mode: config.auth_mode, grant_type: "client_credentials" },
+        }, { onConflict: "user_id,integration_id" });
+        if (insertError) {
+            console.error(`[nova-sdk] ⚠️ Failed to cache connection:`, insertError.message);
+        }
+        else {
+            console.log(`[nova-sdk] 📦 Created new connection for user ${userId}`);
+        }
+    }
+    // Populate in-memory cache
+    _tokenCache.set(cacheKey, {
+        accessToken: tokenResponse.access_token,
+        expiresAt,
+        httpsAgent,
+    });
+    return {
+        accessToken: tokenResponse.access_token,
+        expiresAt,
+        integrationId: config.id,
+        authMode: config.auth_mode,
+        httpsAgent,
+    };
+}
+// ─── User Credentials (authorization_code / standard) ───────────────────────
+async function resolveUserCredentials(platformDB, config, userId) {
+    const cacheKey = getCacheKey(config.slug, userId);
+    // Check in-memory cache
+    const cached = getCachedToken(cacheKey);
+    if (cached) {
+        console.log(`[nova-sdk] ⚡ Using in-memory cached user token (expires ${cached.expiresAt.toISOString()})`);
+        return {
+            accessToken: cached.accessToken,
+            expiresAt: cached.expiresAt,
+            integrationId: config.id,
+            authMode: "standard",
+        };
+    }
+    // Look up user's connection
+    const { data: conn, error: connError } = await platformDB
+        .from("user_app_connections")
+        .select("id, access_token_vault_id, refresh_token_vault_id, token_expires_at, is_active")
+        .eq("integration_id", config.id)
+        .eq("user_id", userId)
+        .eq("is_active", true)
+        .single();
+    if (connError || !conn) {
+        throw new ConnectionNotFoundError(config.slug, userId);
+    }
+    if (!conn.access_token_vault_id) {
+        throw new ConnectionNotFoundError(config.slug, userId);
+    }
+    const expiresAt = conn.token_expires_at ? new Date(conn.token_expires_at) : new Date(0);
+    const now = new Date();
+    // Check if token is still valid
+    if (expiresAt.getTime() - TOKEN_EXPIRY_BUFFER_MS > now.getTime()) {
+        const accessToken = await getVaultSecret(platformDB, conn.access_token_vault_id, "user_access_token");
+        if (accessToken) {
+            _tokenCache.set(cacheKey, { accessToken, expiresAt });
+            console.log(`[nova-sdk] ✅ User token valid (expires ${expiresAt.toISOString()})`);
+            return {
+                accessToken,
+                expiresAt,
+                integrationId: config.id,
+                authMode: "standard",
+            };
+        }
+    }
+    // Token expired — try refresh
+    if (conn.refresh_token_vault_id) {
+        console.log(`[nova-sdk] 🔄 User token expired — refreshing...`);
+        return refreshUserToken(platformDB, config, userId, conn.id, conn.refresh_token_vault_id);
+    }
+    throw new ConnectionNotFoundError(config.slug, `${userId} (token expired and no refresh token available — user must re-authorize)`);
+}
+async function refreshUserToken(platformDB, config, userId, connectionId, refreshTokenVaultId) {
+    if (!config.token_endpoint) {
+        throw new CredentialsNotConfiguredError(config.slug, "token_endpoint not set — cannot refresh");
+    }
+    const refreshToken = await getVaultSecret(platformDB, refreshTokenVaultId, "refresh_token");
+    if (!refreshToken) {
+        throw new ConnectionNotFoundError(config.slug, `${userId} (refresh token missing from vault)`);
+    }
+    const clientSecret = config.client_secret_vault_id
+        ? await getVaultSecret(platformDB, config.client_secret_vault_id, "client_secret")
+        : null;
+    const body = new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+        client_id: config.client_id ?? "",
+        ...(clientSecret ? { client_secret: clientSecret } : {}),
+    });
+    const res = await fetch(config.token_endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+    });
+    if (!res.ok) {
+        const errText = await res.text();
+        console.error(`[nova-sdk] ❌ Refresh token exchange failed for "${config.slug}": ${res.status}`, errText);
+        throw new TokenExchangeError(config.slug, `refresh failed: ${res.status} ${errText}`);
+    }
+    const tokenData = (await res.json());
+    const expiresAt = new Date(Date.now() + (tokenData.expires_in ?? 3600) * 1000);
+    // Update vault + connection
+    const { data: existingConn } = await platformDB
+        .from("user_app_connections")
+        .select("access_token_vault_id, refresh_token_vault_id")
+        .eq("id", connectionId)
+        .single();
+    if (existingConn?.access_token_vault_id) {
+        await updateVaultSecret(platformDB, existingConn.access_token_vault_id, tokenData.access_token);
+    }
+    if (tokenData.refresh_token && existingConn?.refresh_token_vault_id) {
+        await updateVaultSecret(platformDB, existingConn.refresh_token_vault_id, tokenData.refresh_token);
+    }
+    await platformDB
+        .from("user_app_connections")
+        .update({
+        token_expires_at: expiresAt.toISOString(),
+        token_scope: tokenData.scope ?? null,
+        last_used_at: new Date().toISOString(),
+    })
+        .eq("id", connectionId);
+    // Cache it
+    const cacheKey = getCacheKey(config.slug, userId);
+    _tokenCache.set(cacheKey, { accessToken: tokenData.access_token, expiresAt });
+    console.log(`[nova-sdk] ✅ User token refreshed for "${config.slug}" (expires ${expiresAt.toISOString()})`);
+    return {
+        accessToken: tokenData.access_token,
+        expiresAt,
+        integrationId: config.id,
+        authMode: "standard",
+    };
+}
+// ─── integrationFetch: mTLS-aware fetch wrapper ─────────────────────────────
+/**
+ * Generic mTLS-aware fetch for integration API calls.
+ * If the resolved credentials include an httpsAgent (mTLS), uses node:https.
+ * Otherwise, uses global fetch().
+ *
+ * Works with ANY integration — not ADP-specific.
+ */
+export async function integrationFetch(url, credentials, options = {}) {
+    const { accessToken, httpsAgent } = credentials;
+    if (httpsAgent) {
+        // Use node:https for mTLS
+        return new Promise((resolve, reject) => {
+            const parsedUrl = new URL(url);
+            const reqOptions = {
+                hostname: parsedUrl.hostname,
+                port: parsedUrl.port || 443,
+                path: parsedUrl.pathname + parsedUrl.search,
+                method: options.method ?? "GET",
+                agent: httpsAgent,
+                headers: {
+                    Authorization: `Bearer ${accessToken}`,
+                    Accept: "application/json",
+                    ...options.headers,
+                    ...(options.body ? { "Content-Type": "application/json" } : {}),
+                },
+            };
+            const req = https.request(reqOptions, (res) => {
+                const chunks = [];
+                res.on("data", (chunk) => chunks.push(chunk));
+                res.on("end", () => {
+                    const bodyStr = Buffer.concat(chunks).toString("utf-8");
+                    resolve(new Response(bodyStr, {
+                        status: res.statusCode ?? 500,
+                        statusText: res.statusMessage ?? "Unknown",
+                        headers: new Headers(res.headers),
+                    }));
+                });
+            });
+            req.on("error", (err) => reject(err));
+            if (options.body)
+                req.write(options.body);
+            req.end();
+        });
+    }
+    // Non-mTLS: regular fetch
+    return fetch(url, {
+        method: options.method ?? "GET",
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            Accept: "application/json",
+            ...options.headers,
+            ...(options.body ? { "Content-Type": "application/json" } : {}),
+        },
+        body: options.body,
+    });
+}
+// ─── emitPlatformEvent: PGMQ event emission ────────────────────────────────
+/**
+ * Emit a PGMQ event to the platform database.
+ * Used for cross-service communication (e.g., sync complete, webhook received).
+ */
+export async function emitPlatformEvent(platformDB, topic, integrationSlug, payload) {
+    console.log(`[nova-sdk] 📤 Emitting event: ${topic} (integration: ${integrationSlug})`);
+    const { error } = await platformDB.rpc("pgmq_send", {
+        queue_name: "platform_events",
+        message: JSON.stringify({
+            topic,
+            integration: integrationSlug,
+            timestamp: new Date().toISOString(),
+            ...payload,
+        }),
+    });
+    if (error) {
+        console.error(`[nova-sdk] ⚠️ Failed to emit PGMQ event "${topic}":`, error.message);
+        // Don't throw — event emission failure shouldn't abort the operation
+    }
+    else {
+        console.log(`[nova-sdk] ✅ Event emitted: ${topic}`);
+    }
+}
+/**
+ * Build an mTLS agent from PEM strings (received via HTTP, not from vault).
+ * Cached per slug — cert/key don't change during container lifetime.
+ */
+function buildMtlsAgentFromPem(slug, certPem, keyPem) {
+    const existing = _mtlsAgents.get(slug);
+    if (existing)
+        return existing;
+    console.log(`[nova-sdk] 🔒 Built mTLS agent for "${slug}" from HTTP response (cert: ${certPem.length} bytes, key: ${keyPem.length} bytes)`);
+    const agent = new https.Agent({ cert: certPem, key: keyPem, keepAlive: true });
+    _mtlsAgents.set(slug, agent);
+    return agent;
+}
+/**
+ * Fetch integration credentials from the auth server over HTTP.
+ * Requires a valid JWT Bearer token (the same one that authenticated the
+ * inbound request to this container).
+ *
+ * @param authBaseUrl - Auth server base URL (e.g., "http://localhost:3001")
+ * @param slug        - Integration slug (e.g., "adp")
+ * @param bearerToken - JWT to forward as Authorization header
+ */
+async function fetchCredentialsFromAuthServer(authBaseUrl, slug, bearerToken) {
+    const url = `${authBaseUrl}/api/integrations/${encodeURIComponent(slug)}/credentials`;
+    console.log(`[nova-sdk] 🌐 Fetching credentials via HTTP: GET ${url}`);
+    const res = await fetch(url, {
+        method: "GET",
+        headers: {
+            Authorization: `Bearer ${bearerToken}`,
+            Accept: "application/json",
+        },
+    });
+    if (!res.ok) {
+        const errBody = await res.text().catch(() => "");
+        if (res.status === 401) {
+            throw new Error(`[nova-sdk] Auth server rejected JWT for credential fetch (401). ` +
+                `Ensure the JWT is valid and signed by the auth server. ${errBody}`);
+        }
+        if (res.status === 404) {
+            throw new IntegrationNotFoundError(slug);
+        }
+        throw new Error(`[nova-sdk] Credential fetch failed: HTTP ${res.status} ${errBody.slice(0, 300)}`);
+    }
+    const data = (await res.json());
+    console.log(`[nova-sdk] ✅ Received credentials for "${slug}" via HTTP (authMode: ${data.authMode})`);
+    return data;
+}
+/**
+ * Resolve credentials for an integration using the HTTP callback strategy.
+ *
+ * This is the main entry point for Strategy B. It:
+ * 1. Checks the in-memory cache
+ * 2. Fetches decrypted credentials from the auth server via HTTP
+ * 3. Performs the OAuth token exchange (client_credentials or mTLS)
+ * 4. Caches the resulting access token in memory
+ *
+ * @param authBaseUrl - Auth server base URL
+ * @param slug        - Integration slug
+ * @param bearerToken - JWT to authenticate with the auth server
+ * @param userId      - Optional user ID (for cache key differentiation)
+ */
+export async function resolveCredentialsViaHttp(authBaseUrl, slug, bearerToken, userId) {
+    const effectiveUserId = userId ?? SYSTEM_USER_ID;
+    const cacheKey = getCacheKey(slug, effectiveUserId);
+    console.log(`[nova-sdk] 🔑 Resolving credentials for "${slug}" via HTTP (userId: ${effectiveUserId})`);
+    // ── Step 1: Check in-memory cache ─────────────────────────────────────
+    const cached = getCachedToken(cacheKey);
+    if (cached) {
+        // Derive authMode: use stored value if available, otherwise infer from httpsAgent
+        const cachedAuthMode = cached.authMode ?? (cached.httpsAgent ? "mtls" : "client_credentials");
+        console.log(`[nova-sdk] ⚡ Using in-memory cached token (expires ${cached.expiresAt.toISOString()}, authMode: ${cachedAuthMode})`);
+        return {
+            accessToken: cached.accessToken,
+            expiresAt: cached.expiresAt,
+            integrationId: `http:${slug}`, // No DB UUID available in HTTP mode
+            authMode: cachedAuthMode,
+            httpsAgent: cached.httpsAgent,
+        };
+    }
+    // ── Step 2: Fetch credentials from auth server ────────────────────────
+    const creds = await fetchCredentialsFromAuthServer(authBaseUrl, slug, bearerToken);
+    // ── Step 2b: Standard auth — use pre-resolved access token if available ──
+    if (creds.authMode === "standard") {
+        if (creds.accessToken) {
+            const expiresAt = creds.expiresAt
+                ? new Date(creds.expiresAt)
+                : new Date(Date.now() + 3600 * 1000); // default 1h if not provided
+            console.log(`[nova-sdk] ✅ Using pre-resolved access token for "${slug}" (standard auth, HTTP mode) — expires ${expiresAt.toISOString()}`);
+            // Cache in memory (include authMode so cache hits return correct mode)
+            _tokenCache.set(cacheKey, { accessToken: creds.accessToken, expiresAt, authMode: "standard" });
+            return {
+                accessToken: creds.accessToken,
+                expiresAt,
+                integrationId: `http:${slug}`,
+                authMode: "standard",
+            };
+        }
+        // Standard auth but no access token returned — user hasn't authorized yet
+        throw new ConnectionNotFoundError(slug, `${effectiveUserId} (no stored access token — user must authorize via OAuth popup first)`);
+    }
+    // ── Step 3: Validate required fields (client_credentials / mTLS only) ──
+    if (!creds.clientId) {
+        throw new CredentialsNotConfiguredError(slug, "client_id is not set");
+    }
+    if (!creds.clientSecret) {
+        throw new CredentialsNotConfiguredError(slug, "client_secret not available");
+    }
+    if (!creds.tokenEndpoint) {
+        throw new CredentialsNotConfiguredError(slug, "token_endpoint is not set");
+    }
+    // ── Step 4: Build mTLS agent if needed ────────────────────────────────
+    let httpsAgent;
+    if (creds.authMode === "mtls") {
+        if (!creds.mtlsCert || !creds.mtlsKey) {
+            throw new CredentialsNotConfiguredError(slug, "mTLS cert/key not returned by auth server");
+        }
+        httpsAgent = buildMtlsAgentFromPem(slug, creds.mtlsCert, creds.mtlsKey);
+    }
+    // ── Step 5: Perform token exchange (client_credentials / mTLS) ────────
+    console.log(`[nova-sdk] 🔄 Exchanging client_credentials at ${creds.tokenEndpoint} for "${slug}" (HTTP mode)`);
+    const tokenResponse = await performTokenExchange(slug, {
+        tokenEndpoint: creds.tokenEndpoint,
+        clientId: creds.clientId,
+        clientSecret: creds.clientSecret,
+        httpsAgent,
+    });
+    const expiresAt = new Date(Date.now() + tokenResponse.expires_in * 1000);
+    console.log(`[nova-sdk] ✅ Token exchange successful for "${slug}" (HTTP mode) — expires ${expiresAt.toISOString()} (${tokenResponse.expires_in}s)`);
+    // ── Step 6: Cache in memory ───────────────────────────────────────────
+    _tokenCache.set(cacheKey, {
+        accessToken: tokenResponse.access_token,
+        expiresAt,
+        httpsAgent,
+    });
+    return {
+        accessToken: tokenResponse.access_token,
+        expiresAt,
+        integrationId: `http:${slug}`,
+        authMode: creds.authMode,
+        httpsAgent,
+    };
+}
+/**
+ * Detect which credential resolution strategy to use.
+ * Returns 'db' if PLATFORM_SUPABASE_* are available, 'http' if AUTH_ISSUER_BASE_URL
+ * is set, or 'none' if neither is configured.
+ */
+export function detectCredentialStrategy() {
+    const hasDB = !!process.env.PLATFORM_SUPABASE_URL &&
+        !!process.env.PLATFORM_SUPABASE_SERVICE_ROLE_KEY;
+    const hasAuth = !!process.env.AUTH_ISSUER_BASE_URL;
+    if (hasDB)
+        return "db";
+    if (hasAuth)
+        return "http";
+    return "none";
+}