@skrr-ai/auth-core 0.1.2

package/dist/cjs/headers-helper.js

@@ -0,0 +1,323 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.invalidateHeadersHelperCache = invalidateHeadersHelperCache;
+exports.runHeadersHelper = runHeadersHelper;
+/**
+ * headers-helper.ts — invocation contract for `OVERSKY_HEADERS_HELPER`.
+ *
+ * The helper is a user-supplied executable that prints a JSON object of
+ * HTTP headers to stdout. It exists so operators can supply dynamic,
+ * rotating credentials for outbound MCP server connections (e.g., a
+ * single `~/.skrr/mcp-headers.sh` that switches on `$MCP_SERVER_NAME`).
+ *
+ * This is a SIBLING to `OVERSKY_AUTH_HELPER` (daemon→OverSky auth).
+ * Headers helper authenticates OverSky to OUTBOUND MCP servers.
+ *
+ * Wire protocol (git credential-helper style — see deshaw/anthropic-issues#28):
+ *   - `OVERSKY_HEADERS_HELPER` env points at an absolute, executable path.
+ *   - We `spawn(path, [], { shell: false, detached: true })` — never via
+ *     shell (no argument injection), detached so the group can be
+ *     SIGKILL-ed on timeout.
+ *   - `MCP_SERVER_NAME` and `MCP_SERVER_URL` are passed via env (NOT argv)
+ *     so the values never appear in `ps` output.
+ *   - The helper prints a JSON object of string-valued headers to stdout.
+ *   - Stderr is captured for diagnostic logging only.
+ *   - Stdout cap: 64 KiB. Real header payloads are tiny.
+ *   - Default timeout: 10 s (same constant as auth-helper).
+ *
+ * Output validation (fail closed on violation):
+ *   - Stdout MUST be valid JSON parseable as `Record<string, string>`.
+ *   - Every key MUST match RFC 7230 §3.2.6 token chars:
+ *       `^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$`
+ *   - Every value MUST be a string.
+ *   - `Authorization` values MUST start with a recognised scheme word
+ *     followed by a space (`Bearer `, `Basic `, `Token `, `Digest `,
+ *     `NTLM `, `Negotiate `, `AWS4-HMAC-SHA256 `, `MAC `). This guards
+ *     against the common bug where a helper returns a raw secret without
+ *     the scheme prefix, which causes a malformed Authorization header.
+ *
+ * Caching: per-serverName, 5-minute TTL (same as auth-helper DEFAULT_TTL_MS).
+ * Invalidation seam mirrors `invalidateAuthHelperCache`.
+ *
+ * Failure semantics: cold-cache helper failure throws (fail closed) rather
+ * than silently sending the request without auth headers. Warm-cache
+ * failure logs a warning and returns the stale cached value.
+ *
+ * Kill switch: `OVERSKY_DISABLE_HEADERS_HELPER=1` short-circuits to {}.
+ */
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const runtime_js_1 = require("./runtime.js");
+// -------------------------------------------------------------------------
+// Constants — deliberately not re-imported from authHelper.ts to keep the
+// two modules independently deployable. Values are identical by spec.
+// -------------------------------------------------------------------------
+const MAX_OUTPUT_BYTES = 64 * 1024;
+const HELPER_TIMEOUT_MS = 10_000;
+const CACHE_TTL_MS = 5 * 60_000;
+/**
+ * RFC 7230 §3.2.6 token character class.
+ * Valid HTTP header field name chars: printable US-ASCII minus separators.
+ */
+const HEADER_NAME_RE = /^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$/;
+/**
+ * Recognised Authorization scheme words. Requiring the scheme prefix
+ * prevents helpers from accidentally returning a raw secret as the
+ * header value, which produces a malformed Authorization header that
+ * either leaks or silently fails at the MCP server.
+ */
+const AUTH_SCHEME_RE = /^(?:Bearer |Basic |Token |Digest |NTLM |Negotiate |AWS4-HMAC-SHA256 |MAC )/i;
+/** Module-level cache: serverName → entry. */
+const cache = new Map();
+/**
+ * Invalidate the headers-helper cache.
+ * - `invalidateHeadersHelperCache('foo')` clears only the `foo` server.
+ * - `invalidateHeadersHelperCache()` clears all servers.
+ */
+function invalidateHeadersHelperCache(serverName) {
+    if (serverName !== undefined) {
+        cache.delete(serverName);
+    }
+    else {
+        cache.clear();
+    }
+}
+/**
+ * Invoke the headers helper for the named MCP server and return the
+ * resulting headers. Results are cached per `serverName` for 5 minutes.
+ *
+ * On cold-cache failure the function throws (fail closed — better to
+ * surface the misconfiguration than to silently send unauthenticated
+ * requests to an MCP server expecting credentials).
+ *
+ * On warm-cache helper failure the stale cached value is returned with
+ * a warning so ongoing requests are not disrupted during a transient
+ * helper outage.
+ *
+ * Returns `{}` (empty object) when no helper is configured.
+ */
+async function runHeadersHelper(opts) {
+    const log = (0, runtime_js_1.getAuthLogger)();
+    if (process.env.OVERSKY_DISABLE_HEADERS_HELPER === '1') {
+        log.debug?.('[headersHelper] OVERSKY_DISABLE_HEADERS_HELPER=1 — skipping');
+        return {};
+    }
+    const scriptPath = process.env.OVERSKY_HEADERS_HELPER?.trim();
+    if (!scriptPath) {
+        return {};
+    }
+    // Validate path before any subprocess spawn.
+    if (!node_path_1.default.isAbsolute(scriptPath)) {
+        throw new Error(`[headersHelper] OVERSKY_HEADERS_HELPER must be an absolute path; got "${scriptPath}"`);
+    }
+    let stat;
+    try {
+        stat = node_fs_1.default.statSync(scriptPath);
+    }
+    catch (err) {
+        throw new Error(`[headersHelper] OVERSKY_HEADERS_HELPER not found at "${scriptPath}": ${formatErr(err)}`);
+    }
+    if (!stat.isFile()) {
+        throw new Error(`[headersHelper] OVERSKY_HEADERS_HELPER "${scriptPath}" is not a regular file`);
+    }
+    if ((stat.mode & 0o111) === 0) {
+        throw new Error(`[headersHelper] OVERSKY_HEADERS_HELPER "${scriptPath}" is not executable`);
+    }
+    // Cache hit?
+    const cached = cache.get(opts.serverName);
+    if (cached && Date.now() < cached.expiresAt) {
+        log.debug?.(`[headersHelper] cache hit for server "${opts.serverName}"`);
+        return cached.headers;
+    }
+    const isWarm = cached !== undefined;
+    let headers;
+    try {
+        headers = await invokeScript(scriptPath, opts.serverName, opts.serverUrl, log);
+    }
+    catch (err) {
+        if (isWarm) {
+            log.warn?.(`[headersHelper] helper failed for "${opts.serverName}" (using stale cache): ${formatErr(err)}`);
+            return cached.headers;
+        }
+        // Cold cache: fail closed.
+        throw err;
+    }
+    cache.set(opts.serverName, {
+        headers,
+        expiresAt: Date.now() + CACHE_TTL_MS,
+    });
+    return headers;
+}
+// -------------------------------------------------------------------------
+// Internal — script invocation
+// -------------------------------------------------------------------------
+async function invokeScript(scriptPath, serverName, serverUrl, log) {
+    return new Promise((resolve, reject) => {
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let truncated = false;
+        let killedForTimeout = false;
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (result instanceof Error) {
+                reject(result);
+            }
+            else {
+                resolve(result);
+            }
+        };
+        let child;
+        try {
+            child = (0, node_child_process_1.spawn)(scriptPath, [], {
+                shell: false,
+                // detached=true → child is its own process-group leader so we can
+                // SIGKILL the whole tree (vault, curl, etc.) on timeout, not just
+                // the script shell. Mirrors the same pattern in authHelper.ts.
+                detached: true,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                env: {
+                    ...process.env,
+                    // Pass context via env, NOT argv — keeps the URL out of `ps` listings.
+                    MCP_SERVER_NAME: serverName,
+                    MCP_SERVER_URL: serverUrl,
+                },
+            });
+        }
+        catch (err) {
+            reject(new Error(`[headersHelper] spawn failed for "${serverName}": ${formatErr(err)}`));
+            return;
+        }
+        const timer = setTimeout(() => {
+            killedForTimeout = true;
+            log.warn?.(`[headersHelper] helper timed out after ${HELPER_TIMEOUT_MS}ms for "${serverName}" — killing`);
+            try {
+                if (typeof child.pid === 'number') {
+                    process.kill(-child.pid, 'SIGKILL');
+                }
+                else {
+                    child.kill('SIGKILL');
+                }
+            }
+            catch {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            try {
+                child.stdout?.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+            try {
+                child.stderr?.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+            settle(new Error(`[headersHelper] helper timed out after ${HELPER_TIMEOUT_MS}ms for server "${serverName}"`));
+        }, HELPER_TIMEOUT_MS);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+        child.stdout?.on('data', (chunk) => {
+            stdoutBytes += chunk.length;
+            if (stdoutBytes > MAX_OUTPUT_BYTES) {
+                truncated = true;
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    /* ignore */
+                }
+                return;
+            }
+            stdoutChunks.push(chunk);
+        });
+        child.stderr?.on('data', (chunk) => {
+            if (stderrBytes < MAX_OUTPUT_BYTES) {
+                stderrChunks.push(chunk);
+                stderrBytes += chunk.length;
+            }
+        });
+        child.on('error', (err) => {
+            settle(new Error(`[headersHelper] runtime error for "${serverName}": ${formatErr(err)}`));
+        });
+        child.on('close', (code) => {
+            if (killedForTimeout) {
+                // timer already settled
+                return;
+            }
+            if (truncated) {
+                settle(new Error(`[headersHelper] stdout exceeded ${MAX_OUTPUT_BYTES} bytes for "${serverName}" — refusing to parse`));
+                return;
+            }
+            const stderr = Buffer.concat(stderrChunks).toString('utf-8').trim();
+            if (stderr) {
+                log.debug?.(`[headersHelper] stderr for "${serverName}": ${stderr}`);
+            }
+            if (code !== 0) {
+                settle(new Error(`[headersHelper] helper exited with code ${code} for "${serverName}"`));
+                return;
+            }
+            const stdout = Buffer.concat(stdoutChunks).toString('utf-8').trim();
+            if (!stdout) {
+                settle(new Error(`[headersHelper] helper produced empty stdout for "${serverName}"`));
+                return;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(stdout);
+            }
+            catch (err) {
+                settle(new Error(`[headersHelper] JSON parse failed for "${serverName}": ${formatErr(err)}`));
+                return;
+            }
+            if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+                settle(new Error(`[headersHelper] output for "${serverName}" must be a JSON object, got: ${JSON.stringify(parsed)}`));
+                return;
+            }
+            const result = {};
+            for (const [key, value] of Object.entries(parsed)) {
+                // Validate header name (RFC 7230 §3.2.6 token chars).
+                if (!HEADER_NAME_RE.test(key)) {
+                    settle(new Error(`[headersHelper] invalid header name "${key}" for server "${serverName}" — must match RFC 7230 token chars`));
+                    return;
+                }
+                // Values must be strings.
+                if (typeof value !== 'string') {
+                    settle(new Error(`[headersHelper] non-string value for header "${key}" in server "${serverName}": ${typeof value}`));
+                    return;
+                }
+                // Authorization values must include a scheme word.
+                if (key.toLowerCase() === 'authorization' && !AUTH_SCHEME_RE.test(value)) {
+                    settle(new Error(`[headersHelper] Authorization header for "${serverName}" must start with a recognised scheme (Bearer, Basic, Token, …). ` +
+                        `Got: "${value.slice(0, 20)}…". ` +
+                        `This guards against raw secrets without a scheme prefix.`));
+                    return;
+                }
+                result[key] = value;
+            }
+            log.debug?.(`[headersHelper] got ${Object.keys(result).length} header(s) for server "${serverName}"`);
+            settle(result);
+        });
+    });
+}
+// -------------------------------------------------------------------------
+// Utilities
+// -------------------------------------------------------------------------
+function formatErr(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @skrr-ai/auth-core — shared auth substrate.
+ *
+ * Public surface for the OverSky daemon, Sky CLI, and Electron main
+ * process. Each consumer calls `configureAuthCore()` once at startup to
+ * wire up its logger, config dir, kill switches, and binary name — then
+ * uses the rest of the API uniformly.
+ */
+export { SCOPES, ALL_DAEMON_SCOPES, VALID_DAEMON_SCOPE_SET, isDaemonScope, OAUTH_CLI_SCOPE, type DaemonScope, type OAuthCliScope, type OAuthScope, } from './daemonScopes.js';
+export { configureAuthCore, getAuthLogger, getAuthConfigDir, getAuthKillSwitches, getAuthBinaryName, emitAuthTelemetry, type AuthCoreConfig, type AuthLogger, type AuthKillSwitches, type AuthTelemetryEvent, } from './runtime.js';
+export { PermanentAuthFailure, TransientAuthFailure, type PermanentAuthReason, type ReauthState, type TokenPair, } from './types.js';
+export { decodeJwtExpiry, decodeJwtPayload } from './jwtUtils.js';
+export { isAuthExpiredSseEvent, handleMidStreamAuthExpiry, type ParsedSseLike, type AuthExpiredCallbacks, type HandleMidStreamAuthExpiryResult, } from './authExpiredDetector.js';
+export { formatReauthMessage, EXIT_NEEDS_REAUTH, type AuthFailureReason } from './messages.js';
+export { classifyRefreshResponse, type RefreshResponseShape, type ClassifiedRefreshResult, type ClassifiedRefreshSuccess, type ClassifiedRefreshFailure, } from './refreshClassification.js';
+export { refreshDaemonToken, revokeDaemonRefreshSession, withAuthLock, persistReauthState, needsReauthState, clearReauthState, installLockExitHandlers, __refreshDiagnostics, __resetUnknown401StreaksForTest, UNKNOWN_401_BUDGET, } from './refresh.js';
+export { createRefreshScheduler, type RefreshScheduler, type RefreshSchedulerOptions, } from './refreshScheduler.js';
+export { readAuthFromFd, __setFdReaderForTest, type FdAuthPayload } from './fdToken.js';
+export { CredentialResolver, CREDENTIAL_PRECEDENCE, __resetCredentialResolverForTest, invalidateAuthHelperCache, classifyTokenKind, CI_TOKEN_PREFIX, AuthHelperUntrustedError, AuthHelperUnavailableError, type CredentialSource, type CredentialStoreMode, type CredentialResolverOptions, type ResolvedCredential, type TokenKind, type HelperTrustDecision, type AuthHelperBlockedInfo, type AuthHelperSentinelInfo, } from './credentialResolver.js';
+export { invokeAuthHelper, getDefaultHelperTtlMs, getLastAuthHelperFailureReason, __resetAuthHelperFailureReasonForTest, SENTINEL_TRIGGERING_FAILURES, type HelperResult, type InvokeAuthHelperOptions, type AuthHelperFailureReason, } from './authHelper.js';
+export { runHeadersHelper, invalidateHeadersHelperCache, type RunHeadersHelperOptions, } from './headers-helper.js';
+export { generateVerifier, challenge, generateState, safeEqual, verifyChallenge, type PkceChallengeMethod, } from './pkce.js';
+export { startLocalCallback, DEFAULT_LOGIN_TIMEOUT_MS, LocalCallbackError, LocalCallbackBindError, LocalCallbackTimeoutError, LocalCallbackStateMismatchError, LocalCallbackDeniedError, LocalCallbackMalformedError, type StartLocalCallbackOptions, type LocalCallbackResult, type LocalCallbackHandle, } from './loginLocalhost.js';
+export { loginWithLocalhost, LoginInitError, LoginExchangeError, type BrowserOpener, type LoginWithLocalhostOptions, type LoginWithLocalhostResult, } from './loginWithLocalhost.js';
+export { parseTtlDays, MIN_TTL_DAYS, MAX_TTL_DAYS, type ParseTtlResult, type ParseTtlSuccess, type ParseTtlError, } from './ttlParser.js';
+export { formatRecoveryCode, parseRecoveryCode, normalizeRecoveryCode, isValidRecoveryCode, } from './recoveryCode.js';
+export { buildCredentialAad, decrypt as credEnvelopeDecrypt, deserialize as credEnvelopeDeserialize, encrypt as credEnvelopeEncrypt, ENVELOPE_MAGIC as CRED_ENVELOPE_MAGIC, generateDek, isEnvelopeString as isCredEnvelopeString, KEY_LEN as CRED_KEY_LEN, openBuffer as credOpenBuffer, sealBuffer as credSealBuffer, serialize as credEnvelopeSerialize, unwrap as credEnvelopeUnwrap, wrap as credEnvelopeWrap, type SealedBlob as CredSealedBlob, } from './credentialEnvelope.js';
+export { __setKekStrategyForTest, getKekStrategy, InMemoryKek, UnavailableKek, KekUnavailableError, LinuxKek, MacosKek, registerZeroizeHook, WindowsKek, zeroizeKekCaches, type KekStrategy, } from './kek/index.js';
+export { buildProof as buildDeviceProof, generateDeviceKeyPair, jwkThumbprint, normalizeHtu, publicJwkFromX, tokenHash, verifyProof as verifyDeviceProof, type DeviceKeyPair, type DeviceProofClaims, type DeviceProofHeader, type Ed25519PrivateJwk, type Ed25519PublicJwk, type VerifyFailureReason as DeviceProofVerifyFailureReason, type VerifyFailure as DeviceProofVerifyFailure, type VerifyOptions as DeviceProofVerifyOptions, type VerifySuccess as DeviceProofVerifySuccess, } from './deviceKey.js';
+export { initCredEnvelope, resetCredEnvelope, shutdownCredEnvelope, isCredEnvelopeActive, describeCredEnvelopeState, maybeEncryptForWrite, maybeDecryptOnRead, __wrappedDekFilePathForTest, __setStateForTest as __setCredEnvelopeStateForTest, __getStateForTest as __getCredEnvelopeStateForTest, __resetShutdownGuardForTest, type ReadTransformResult, } from './credentialEnvelopeBridge.js';
+export { initDeviceIdentity, resetDeviceIdentity, signServerRequest, enrollWithServer, clearEnrollmentMarker, isDeviceIdentityActive, getDevicePublicKey, describeDeviceIdentityState, __publicKeyPathForTest, __privateKeyPathForTest, __enrollmentMarkerPathForTest, __enrollmentBackoffPathForTest, __setStateForTest as __setDeviceIdentityStateForTest, __getStateForTest as __getDeviceIdentityStateForTest, type EnrollmentResult, } from './deviceIdentityBridge.js';
+export { ensureMachineDaemonId, legacyDaemonUuids, __resetCachedDaemonIdForTest, } from './machineId.js';
+export { PAIR_AAD_PREFIX, PAIR_AAD_MAX_LEN, PAIR_BUNDLE_MAX_BASE64_LEN, PAIR_NONCE_LEN, PAIR_PUBKEY_LEN, PAIR_SECRET_LEN, PairBundleError, assemblePairBundleBase64, base64ToUint8Array as pairBase64ToUint8Array, base64UrlToUint8Array as pairBase64UrlToUint8Array, buildPairAad, buildPairUrl, generatePairKeyPair, openPairBundleBase64, parsePairBundle, parsePairPlaintext, parsePairUrl, uint8ArrayToBase64 as pairUint8ArrayToBase64, uint8ArrayToBase64Url as pairUint8ArrayToBase64Url, type AssembleBundleOptions as PairAssembleBundleOptions, type OpenBundleOptions as PairOpenBundleOptions, type PairBundle, type PairBundleErrorCode, type PairKeyPair, type PairPlaintextV1, type PairUrlFields, } from './daemonPair.js';
+export { HARNESS_TIERS, getHarnessTier, credentialPolicyForTier, tierPermitsConfiguredAutoMode, type HarnessTrustTier, type CredentialDeliveryPolicy, type CredentialMode, } from './harnessTrust.js';
+export { sanitizeSpawnEnv, SENSITIVE_ENV_VARS, SENSITIVE_ENV_PREFIXES, SENSITIVE_ENV_SUFFIXES, SENSITIVE_ENV_PREFIX_EXCEPTIONS, } from './spawnEnv.js';
+export { CONFIG_DIR_NAME, LEGACY_CONFIG_DIR_NAMES, NATIVE_ID_PREFIX, LEGACY_NATIVE_ID_PREFIXES, DEFAULT_BINARY_NAME, } from './localIdentity.js';
+export { findLegacyLocalState, describeLegacyState, type LegacyStateFinding, type LegacyStateReport, } from './legacyStatePreflight.js';