@skrr-ai/auth-core 0.1.2

package/dist/esm/headers-helper.js

@@ -0,0 +1,316 @@
+/**
+ * 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 {}.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getAuthLogger } from './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.
+ */
+export 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.
+ */
+export async function runHeadersHelper(opts) {
+    const log = 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 (!path.isAbsolute(scriptPath)) {
+        throw new Error(`[headersHelper] OVERSKY_HEADERS_HELPER must be an absolute path; got "${scriptPath}"`);
+    }
+    let stat;
+    try {
+        stat = fs.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 = 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/esm/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';

package/dist/esm/index.js

@@ -0,0 +1,144 @@
+/**
+ * @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.
+ */
+// Daemon scope vocabulary — single source of truth for non-Mongoose tiers
+// (daemon, desktop, cli). Schema-bound canonical lives in
+// `@skrr-ai/data-schemas/common/daemonScopes`; the two are kept byte-equal
+// by the api-side parity test. See daemonScopes.ts header for details.
+export { SCOPES, ALL_DAEMON_SCOPES, VALID_DAEMON_SCOPE_SET, isDaemonScope, OAUTH_CLI_SCOPE, } from './daemonScopes.js';
+// Runtime / DI
+export { configureAuthCore, getAuthLogger, getAuthConfigDir, getAuthKillSwitches, getAuthBinaryName, emitAuthTelemetry, } from './runtime.js';
+// Types
+export { PermanentAuthFailure, TransientAuthFailure, } from './types.js';
+// JWT helpers
+export { decodeJwtExpiry, decodeJwtPayload } from './jwtUtils.js';
+// Mid-stream auth-expired SSE detector — recognises terminal "auth_expired"
+// events from long-lived SSE / Socket.IO streams and orchestrates a
+// refresher-driven recovery. Mobile RN keeps a byte-equal mirror; see file
+// header.
+export { isAuthExpiredSseEvent, handleMidStreamAuthExpiry, } from './authExpiredDetector.js';
+// Reauth messaging
+export { formatReauthMessage, EXIT_NEEDS_REAUTH } from './messages.js';
+// Pure HTTP→{Permanent, Transient, Success} response classification —
+// exposed so RN-side clients can apply the same mapping daemon uses.
+export { classifyRefreshResponse, } from './refreshClassification.js';
+// Refresh
+export { refreshDaemonToken, revokeDaemonRefreshSession, withAuthLock, persistReauthState, needsReauthState, clearReauthState, installLockExitHandlers, 
+// H1 — Test-only diagnostic counters that prove every outgoing
+// refresh request mints a fresh proof. Production code never reads
+// this; tests use it to assert the per-attempt invariant.
+__refreshDiagnostics, 
+// Finding 4 — Test-only reset for the per-daemonId unknown-shape-401
+// retry budget. Lets tests start each case with a clean streak.
+__resetUnknown401StreaksForTest, 
+// Finding 4 follow-up (BOOT-BUDGET COUPLING) — consumed by the daemon's
+// startup-recovery loop to statically assert
+// `STARTUP_RECOVERY_MAX_ATTEMPTS >= UNKNOWN_401_BUDGET` so the in-process
+// unknown-401 latch always fires before the boot loop yields to the
+// supervisor. See daemon/src/auth.ts.
+UNKNOWN_401_BUDGET, } from './refresh.js';
+// Refresh scheduler
+export { createRefreshScheduler, } from './refreshScheduler.js';
+// Fd handoff
+export { readAuthFromFd, __setFdReaderForTest } from './fdToken.js';
+// Credential resolver — Phase H precedence chain + Phase I tokenKind
+export { CredentialResolver, CREDENTIAL_PRECEDENCE, __resetCredentialResolverForTest, 
+// H3-6 — public seam 401 handlers call to bust the helper cache so
+// the next resolve re-invokes OVERSKY_AUTH_HELPER immediately
+// instead of serving the stale cached token for up to its TTL.
+invalidateAuthHelperCache, classifyTokenKind, CI_TOKEN_PREFIX, 
+// L6.1 / L6.3 — fail-closed errors thrown by the auth-helper slot.
+AuthHelperUntrustedError, AuthHelperUnavailableError, } from './credentialResolver.js';
+// Auth helper — invocation contract for OVERSKY_AUTH_HELPER
+export { invokeAuthHelper, getDefaultHelperTtlMs, getLastAuthHelperFailureReason, __resetAuthHelperFailureReasonForTest, SENTINEL_TRIGGERING_FAILURES, } from './authHelper.js';
+// Headers helper — invocation contract for OVERSKY_HEADERS_HELPER
+// (authenticates OverSky to outbound MCP servers)
+export { runHeadersHelper, invalidateHeadersHelperCache, } from './headers-helper.js';
+// PKCE — RFC 7636 primitives for the Phase H.0 localhost-callback login.
+// Keep `safeEqual` and `verifyChallenge` exported even though they are
+// server-side concerns: server code consumes auth-core via the same
+// public surface and the alternative (a separate server-only module)
+// fragments the spec implementation across two locations.
+export { generateVerifier, challenge, generateState, safeEqual, verifyChallenge, } from './pkce.js';
+// Local 127.0.0.1 callback server — Phase H.0.2.
+// Keep error classes exported; callers branch on them to decide
+// fallback behavior (BindError → retry on different port; TimeoutError
+// → fall back to device-code; StateMismatchError → fail loudly).
+export { startLocalCallback, DEFAULT_LOGIN_TIMEOUT_MS, LocalCallbackError, LocalCallbackBindError, LocalCallbackTimeoutError, LocalCallbackStateMismatchError, LocalCallbackDeniedError, LocalCallbackMalformedError, } from './loginLocalhost.js';
+// Phase H.0.2.b — single-call orchestrator that ties PKCE + local
+// callback + server endpoints into the daemon-style token bundle.
+// Daemon/CLI consume this; auth-core is platform-agnostic via the
+// caller-injected `openBrowser` and `fetchImpl`.
+export { loginWithLocalhost, LoginInitError, LoginExchangeError, } from './loginWithLocalhost.js';
+// ADD-CLI1 — shared `--ttl` parser for `create-token`. Both the
+// daemon CLI (`oversky create-token`) and the oclif CLI (`sky
+// create-token`) import from here to prevent grammar drift.
+export { parseTtlDays, MIN_TTL_DAYS, MAX_TTL_DAYS, } from './ttlParser.js';
+// Tier 1 #3 — printable account-recovery code format (1Password-style
+// 11-group base32). Server, CLI, and daemon-side helper all import from here.
+export { formatRecoveryCode, parseRecoveryCode, normalizeRecoveryCode, isValidRecoveryCode, } from './recoveryCode.js';
+// L12 Layer 0 — at-rest credential envelope encryption primitives.
+// Pure crypto, no platform code. Daemon and CLI both consume.
+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, } from './credentialEnvelope.js';
+// L12 Layer 1 — KEK platform-strategy interface and implementations.
+//
+// This block used to claim "today every strategy reports available=false so
+// the daemon falls through to legacy plaintext". That has not been true since
+// the macOS `security(1)` backend (C5) and the Linux tier-3 machine-id HKDF
+// fallback shipped: on Linux `available()` is now essentially always true, and
+// on macOS it is true whenever a login keychain resolves. The stale note is
+// worth calling out rather than deleting, because four daemon suites were
+// written against it and only failed once CI first ran them on Linux.
+//
+// Tests that need the unavailable branch must inject `UnavailableKek`;
+// `__setKekStrategyForTest(null)` restores the PLATFORM default, which is not
+// the same thing and differs per OS.
+export { __setKekStrategyForTest, getKekStrategy, InMemoryKek, UnavailableKek, KekUnavailableError, LinuxKek, MacosKek, registerZeroizeHook, WindowsKek, zeroizeKekCaches, } from './kek/index.js';
+// L11 Phase 1 — Device identity (Ed25519) + DPoP-shaped proof JWS.
+// The crypto half of the two-axis identity story; daemon-side
+// persistence + signing lives in `daemon/src/deviceIdentity.ts`.
+// Server-side verification middleware is a later PR.
+export { buildProof as buildDeviceProof, generateDeviceKeyPair, jwkThumbprint, normalizeHtu, publicJwkFromX, tokenHash, verifyProof as verifyDeviceProof, } from './deviceKey.js';
+// L11/L12 — composed runtime: init, transforms, sign, enroll, locks.
+// Daemon and CLI consume these; the underlying primitives live above.
+export { 
+// credEnvelope bridge
+initCredEnvelope, resetCredEnvelope, shutdownCredEnvelope, isCredEnvelopeActive, describeCredEnvelopeState, maybeEncryptForWrite, maybeDecryptOnRead, 
+// Test seams — `__`-prefixed so consumers don't import them in
+// production code paths. Re-exported here so CLI/daemon spec files
+// can resolve the wrapped-DEK path against the same module instance.
+__wrappedDekFilePathForTest, __setStateForTest as __setCredEnvelopeStateForTest, __getStateForTest as __getCredEnvelopeStateForTest, __resetShutdownGuardForTest, } from './credentialEnvelopeBridge.js';
+export { 
+// deviceIdentity bridge
+initDeviceIdentity, resetDeviceIdentity, signServerRequest, enrollWithServer, clearEnrollmentMarker, isDeviceIdentityActive, getDevicePublicKey, describeDeviceIdentityState, 
+// Test seams — file path resolvers + state setters for spec files.
+__publicKeyPathForTest, __privateKeyPathForTest, __enrollmentMarkerPathForTest, __enrollmentBackoffPathForTest, __setStateForTest as __setDeviceIdentityStateForTest, __getStateForTest as __getDeviceIdentityStateForTest, } from './deviceIdentityBridge.js';
+// Stable per-machine UUIDv7 identity persisted at <configDir>/daemon.id.
+export { ensureMachineDaemonId, legacyDaemonUuids, __resetCachedDaemonIdForTest, } from './machineId.js';
+// Tier 1 #2 — daemon QR pairing primitives. Pure crypto + AAD framing,
+// shared between the daemon CLI orchestrator (`daemon/src/pair.ts`) and
+// any future native-app callers. The mobile RN client mirrors the same
+// shapes locally because it can't pull a Node-shaped package.
+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, } from './daemonPair.js';
+// OSK-3897 — harness trust tiers, shared by the daemon (the authority) and the
+// CLI (which publishes the fact in `sky code doctor`). The PROVENANCE half stays
+// in the daemon on purpose: a tier is a published fact, provenance is evidence
+// about bytes on disk that only the spawning process can gather.
+export { HARNESS_TIERS, getHarnessTier, credentialPolicyForTier, tierPermitsConfiguredAutoMode, } from './harnessTrust.js';
+// OSK-3892 — spawn-env sanitization, shared by the daemon (which has stripped
+// its own credentials before every harness spawn all along) and the CLI (which
+// spawns the SAME engine and did not). `daemon/src/env-sanitize.ts` re-exports
+// these so its own importers are unchanged, and keeps `filterCustomEnv` — that
+// governs SERVER-PROVIDED env, which no other process is handed.
+export { sanitizeSpawnEnv, SENSITIVE_ENV_VARS, SENSITIVE_ENV_PREFIXES, SENSITIVE_ENV_SUFFIXES, SENSITIVE_ENV_PREFIX_EXCEPTIONS, } from './spawnEnv.js';
+/* Local-machine identity — the names this product leaves on a disk. Exported so
+   the CLI, daemon and Desktop share one definition instead of 47 literals. */
+export { CONFIG_DIR_NAME, LEGACY_CONFIG_DIR_NAMES, NATIVE_ID_PREFIX, LEGACY_NATIVE_ID_PREFIXES, DEFAULT_BINARY_NAME, } from './localIdentity.js';
+/* Pre-rename state detection. Callers REFUSE on a positive result; nothing here
+   reads, copies or removes what it finds (§7.2, §8.4). */
+export { findLegacyLocalState, describeLegacyState, } from './legacyStatePreflight.js';

package/dist/esm/jwtUtils.d.ts

@@ -0,0 +1,35 @@
+/**
+ * jwtUtils.ts — signature-less JWT payload inspection.
+ *
+ * Used by the proactive refresh scheduler to read the `exp` claim off an
+ * access token without round-tripping to the server. We do NOT verify the
+ * signature here — the token is one the server just issued to us, and any
+ * tampering would surface as a 401 on the next API call anyway.
+ *
+ * THEREFORE: NOTHING THESE FUNCTIONS RETURN MAY DECIDE WHAT THE HOLDER IS
+ * ALLOWED TO DO.
+ *
+ * The reasoning above is only sound because the decoded values are used to
+ * schedule work (when to refresh) and to pick a local code path — never to
+ * grant anything. A claim read here is attacker-controlled input in the exact
+ * case that matters: anyone who can write the credential file, set the env var,
+ * or hand us a token over an fd can put any `scope`, `role`, `exp` or `sub` in
+ * it, because forging a payload requires no key when nobody checks the
+ * signature. "It would 401 later" is not a control if the decision was already
+ * made locally before any call went out.
+ *
+ * Safe: refresh timing, telemetry, diagnostics, choosing which resolver branch
+ * to take. Unsafe: gating a capability, trusting an identity, skipping a check,
+ * widening a scope. If you need a claim you can trust, verify the signature or
+ * ask the server.
+ *
+ * `credentialResolver.classifyTokenKind` is the one non-`exp` reader today; see
+ * the note there for why routing on `scope` is not an authorization decision.
+ */
+/** Base64url-decode the middle segment of a JWT and JSON-parse it. */
+export declare function decodeJwtPayload(token: string): unknown | null;
+/**
+ * Decode the `exp` (expiry) claim from a JWT without verifying the signature.
+ * @returns The `exp` value in Unix seconds, or `null` if unparseable / missing.
+ */
+export declare function decodeJwtExpiry(token: string): number | null;

package/dist/esm/jwtUtils.js

@@ -0,0 +1,57 @@
+/**
+ * jwtUtils.ts — signature-less JWT payload inspection.
+ *
+ * Used by the proactive refresh scheduler to read the `exp` claim off an
+ * access token without round-tripping to the server. We do NOT verify the
+ * signature here — the token is one the server just issued to us, and any
+ * tampering would surface as a 401 on the next API call anyway.
+ *
+ * THEREFORE: NOTHING THESE FUNCTIONS RETURN MAY DECIDE WHAT THE HOLDER IS
+ * ALLOWED TO DO.
+ *
+ * The reasoning above is only sound because the decoded values are used to
+ * schedule work (when to refresh) and to pick a local code path — never to
+ * grant anything. A claim read here is attacker-controlled input in the exact
+ * case that matters: anyone who can write the credential file, set the env var,
+ * or hand us a token over an fd can put any `scope`, `role`, `exp` or `sub` in
+ * it, because forging a payload requires no key when nobody checks the
+ * signature. "It would 401 later" is not a control if the decision was already
+ * made locally before any call went out.
+ *
+ * Safe: refresh timing, telemetry, diagnostics, choosing which resolver branch
+ * to take. Unsafe: gating a capability, trusting an identity, skipping a check,
+ * widening a scope. If you need a claim you can trust, verify the signature or
+ * ask the server.
+ *
+ * `credentialResolver.classifyTokenKind` is the one non-`exp` reader today; see
+ * the note there for why routing on `scope` is not an authorization decision.
+ */
+/** Base64url-decode the middle segment of a JWT and JSON-parse it. */
+export function decodeJwtPayload(token) {
+    if (typeof token !== 'string' || token.length === 0)
+        return null;
+    const parts = token.split('.');
+    if (parts.length !== 3 || !parts[1])
+        return null;
+    try {
+        const json = Buffer.from(parts[1], 'base64url').toString('utf8');
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decode the `exp` (expiry) claim from a JWT without verifying the signature.
+ * @returns The `exp` value in Unix seconds, or `null` if unparseable / missing.
+ */
+export function decodeJwtExpiry(token) {
+    const payload = decodeJwtPayload(token);
+    if (payload !== null &&
+        typeof payload === 'object' &&
+        'exp' in payload &&
+        typeof payload.exp === 'number') {
+        return payload.exp;
+    }
+    return null;
+}