@skrr-ai/auth-core 0.1.2

package/dist/esm/runtime.d.ts

@@ -0,0 +1,149 @@
+export interface AuthLogger {
+    trace?: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+/**
+ * Kill switches that gate auth behavior. Mirrors the surface of the daemon's
+ * `KILL` object so the daemon can pass it through verbatim. Each flag defaults
+ * OFF — i.e., the new code path runs.
+ */
+export interface AuthKillSwitches {
+    /** Bypass the OVERSKY_AUTH_FD handoff and use file/keychain backend only. */
+    fdTokenHandoff?: boolean;
+    /** Disable the proactive refresh scheduler — fall back to ad-hoc 4401 refresh. */
+    refreshScheduler?: boolean;
+}
+/**
+ * Minimal telemetry event shape passed to the consumer-supplied logEvent.
+ * Kept narrow so auth-core has no dependency on the daemon's full DaemonEvent.
+ *
+ * Known event names and their metadata payloads:
+ *   refresh_start            — {daemonId, sessionId?}
+ *   refresh_success          — {daemonId, durationMs, tokensRotated: boolean}
+ *   refresh_failure          — {daemonId, durationMs, errorCode, statusCode?}
+ *   refresh_lock_acquiring   — {daemonId}
+ *   refresh_lock_acquired    — {daemonId, waitedMs}
+ *   refresh_lock_retry       — {daemonId, attempt, errorCode}
+ *   refresh_lock_released    — {daemonId, heldForMs}
+ *   refresh_race_resolved    — {daemonId, sourceTokenAdopted: boolean}
+ */
+export interface AuthTelemetryEvent {
+    timestamp: string;
+    eventType: 'auth';
+    success: boolean;
+    metadata: Record<string, unknown>;
+}
+export interface AuthCoreConfig {
+    /** Resolves the directory where auth state lives. Called per-access; may
+     *  return different values across invocations (e.g. profile switching). */
+    configDir: () => string;
+    /**
+     * Resolves the MACHINE-scoped root directory — the location for identity
+     * that must be stable across profile switches and restarts (currently just
+     * `daemon.id`, via `machineId.ts`). Unlike `configDir`, this must NOT vary
+     * by profile: the daemon's `configDir` is `~/.skrr/profiles/<profile>`,
+     * so pinning the machine UUID to it made the "stable per-machine id" drift
+     * per-profile and silently killed the `legacyDaemonUuids()` fold safety net
+     * (it scanned `<profileDir>/profiles/*`, which never exists). See OSK-1478.
+     *
+     * Default: falls back to `configDir()` when unset. The CLI's `configDir` is
+     * already the machine root (`~/.skrr`), so it needs no wiring; the daemon
+     * wires this explicitly to its root `CONFIG_DIR` in `auth/configure.ts`.
+     */
+    machineConfigDir?: () => string;
+    /** Logger used by all stateful helpers. */
+    logger: AuthLogger;
+    /** Kill switches; missing keys default to false (new path runs). */
+    killSwitches?: AuthKillSwitches;
+    /**
+     * Binary name used in user-facing reauth messages (e.g. "skrrd", "skrr").
+     * Default: "skrrd".
+     */
+    binaryName?: string;
+    /**
+     * Optional structured event sink. When supplied, auth-core emits telemetry
+     * events (refresh lifecycle, lock acquire/release, race resolution) into this
+     * callback. The callback must be fire-and-forget — auth-core never awaits it.
+     * Default: no-op (telemetry silently dropped).
+     */
+    logEvent?: (event: AuthTelemetryEvent) => void;
+    /**
+     * Optional response observer invoked once per HTTP response received from
+     * the OverSky backend (currently: refresh + revoke endpoints in `refresh.ts`).
+     *
+     * Intended for cross-cutting observation that does not branch the auth flow —
+     * e.g. the daemon wires `checkResponseClockSkew` here so the server's `Date:`
+     * header is sampled on every refresh round-trip. The observer must be
+     * synchronous, non-throwing, and free of side effects on the response itself
+     * (the body is consumed downstream).
+     *
+     * Auth-core wraps every invocation in try/catch, so a buggy observer cannot
+     * break refresh. Default: no-op.
+     */
+    observeResponse?: (response: {
+        headers: Headers;
+    }) => void;
+    /**
+     * When true, `maybeEncryptForWrite` throws (fail-closed) whenever the
+     * envelope path is not active — callers must surface the failure rather
+     * than silently writing plaintext.
+     *
+     * Daemon still sets this explicitly to true in `auth/configure.ts` to
+     * keep the L12 contract pinned regardless of env-var state. Other
+     * consumers (CLI, Electron main) inherit the env-resolved default —
+     * see `getCredEnvelopeFailClosed()` below.
+     *
+     * Default after the 2026-04-28 audit M2 flip: env-resolved fail-closed
+     * (true) unless the operator explicitly sets `OVERSKY_KEK_REQUIRED=0`
+     * (or `=false`, case-insensitive) as an emergency rollback.
+     *
+     * Default: undefined (env-resolved; fail-closed unless overridden).
+     */
+    credEnvelopeFailClosed?: boolean;
+}
+/**
+ * Wire up the auth-core runtime. Call once at process startup, before any
+ * other auth-core function. Subsequent calls replace the previous config —
+ * useful for tests but not intended for production code paths.
+ */
+export declare function configureAuthCore(config: Partial<AuthCoreConfig>): void;
+export declare function getAuthLogger(): AuthLogger;
+export declare function getAuthConfigDir(): string;
+/**
+ * Resolve the machine-scoped root dir (see `machineConfigDir` on
+ * `AuthCoreConfig`). Falls back to the profile-scoped `configDir()` when no
+ * machine root is wired, preserving pre-OSK-1478 behavior for consumers whose
+ * `configDir` is already the machine root (e.g. the CLI).
+ */
+export declare function getAuthMachineConfigDir(): string;
+export declare function getAuthKillSwitches(): AuthKillSwitches;
+export declare function getAuthBinaryName(): string;
+/**
+ * Resolve whether the credential envelope path should fail-closed on writes
+ * when not active. Honors the explicit `configureAuthCore({credEnvelopeFailClosed})`
+ * first; otherwise resolves from the env.
+ *
+ * Default after the 2026-04-28 audit M2 flip: fail-closed for everyone.
+ * Operators can opt back to fail-open via `OVERSKY_KEK_REQUIRED=0` (or
+ * `=false`, case-insensitive) as an emergency rollback only — it is NOT a
+ * feature flag. Any other value, including unset, means fail-closed.
+ */
+export declare function getCredEnvelopeFailClosed(): boolean;
+/**
+ * Emit a telemetry event via the consumer-supplied logEvent callback.
+ * No-op when the callback is not configured. Never throws.
+ */
+export declare function emitAuthTelemetry(event: AuthTelemetryEvent): void;
+/**
+ * Hand a freshly-received HTTP response to the consumer's `observeResponse`
+ * callback. No-op when the callback is not configured. Never throws — the
+ * caller (refresh.ts) must continue regardless of observer state.
+ */
+export declare function notifyResponseObserver(response: {
+    headers: Headers;
+}): void;
+/** Test-only: restore defaults. Not exported from the package barrel. */
+export declare function __resetAuthCoreForTest(): void;

package/dist/esm/runtime.js

@@ -0,0 +1,121 @@
+/**
+ * runtime.ts — dependency-injection seam for @skrr-ai/auth-core.
+ *
+ * The package never imports the daemon's `logger` or `config` directly. Each
+ * consumer (daemon, CLI, Electron main) calls `configureAuthCore()` once at
+ * startup with its own logger, config-dir resolver, and kill-switch source.
+ * Until configured, sensible no-op defaults apply so imports never crash and
+ * unit tests can exercise pure helpers without setup.
+ *
+ * Why DI not module-globals: the same auth substrate must serve binaries
+ * with different home dirs (`~/.skrr`, and historically `~/.skrr`), different log sinks
+ * (winston, console, oclif), and different rollback flags. A single shared
+ * runtime is fine; hard-coding either choice into the package would force
+ * every consumer onto the daemon's conventions.
+ */
+import os from 'node:os';
+import path from 'node:path';
+import { CONFIG_DIR_NAME, DEFAULT_BINARY_NAME } from './localIdentity.js';
+const DEFAULT_LOGGER = {
+    debug: () => undefined,
+    info: () => undefined,
+    warn: (...args) => {
+        if (process.env.NODE_ENV !== 'test')
+            console.warn('[auth-core]', ...args);
+    },
+    error: (...args) => {
+        if (process.env.NODE_ENV !== 'test')
+            console.error('[auth-core]', ...args);
+    },
+};
+const DEFAULT_CONFIG = {
+    configDir: () => path.join(os.homedir(), CONFIG_DIR_NAME),
+    logger: DEFAULT_LOGGER,
+    killSwitches: {},
+    binaryName: DEFAULT_BINARY_NAME,
+};
+let _config = DEFAULT_CONFIG;
+/**
+ * Wire up the auth-core runtime. Call once at process startup, before any
+ * other auth-core function. Subsequent calls replace the previous config —
+ * useful for tests but not intended for production code paths.
+ */
+export function configureAuthCore(config) {
+    _config = {
+        ...DEFAULT_CONFIG,
+        ..._config,
+        ...config,
+        killSwitches: { ...(_config.killSwitches ?? {}), ...(config.killSwitches ?? {}) },
+    };
+}
+export function getAuthLogger() {
+    return _config.logger;
+}
+export function getAuthConfigDir() {
+    return _config.configDir();
+}
+/**
+ * Resolve the machine-scoped root dir (see `machineConfigDir` on
+ * `AuthCoreConfig`). Falls back to the profile-scoped `configDir()` when no
+ * machine root is wired, preserving pre-OSK-1478 behavior for consumers whose
+ * `configDir` is already the machine root (e.g. the CLI).
+ */
+export function getAuthMachineConfigDir() {
+    return (_config.machineConfigDir ?? _config.configDir)();
+}
+export function getAuthKillSwitches() {
+    return _config.killSwitches ?? {};
+}
+export function getAuthBinaryName() {
+    return _config.binaryName ?? DEFAULT_BINARY_NAME;
+}
+/**
+ * Resolve whether the credential envelope path should fail-closed on writes
+ * when not active. Honors the explicit `configureAuthCore({credEnvelopeFailClosed})`
+ * first; otherwise resolves from the env.
+ *
+ * Default after the 2026-04-28 audit M2 flip: fail-closed for everyone.
+ * Operators can opt back to fail-open via `OVERSKY_KEK_REQUIRED=0` (or
+ * `=false`, case-insensitive) as an emergency rollback only — it is NOT a
+ * feature flag. Any other value, including unset, means fail-closed.
+ */
+export function getCredEnvelopeFailClosed() {
+    if (typeof _config.credEnvelopeFailClosed === 'boolean') {
+        return _config.credEnvelopeFailClosed;
+    }
+    // Default after 2026-04-28 audit M2 flip: fail-closed for everyone.
+    // Operators can opt back to fail-open via OVERSKY_KEK_REQUIRED=0
+    // (emergency rollback only). Any other value — including unset —
+    // means fail-closed.
+    const raw = (process.env.OVERSKY_KEK_REQUIRED ?? '').toLowerCase();
+    return raw !== '0' && raw !== 'false';
+}
+/**
+ * Emit a telemetry event via the consumer-supplied logEvent callback.
+ * No-op when the callback is not configured. Never throws.
+ */
+export function emitAuthTelemetry(event) {
+    try {
+        _config.logEvent?.(event);
+    }
+    catch {
+        /* telemetry is best-effort — never let it crash auth paths */
+    }
+}
+/**
+ * Hand a freshly-received HTTP response to the consumer's `observeResponse`
+ * callback. No-op when the callback is not configured. Never throws — the
+ * caller (refresh.ts) must continue regardless of observer state.
+ */
+export function notifyResponseObserver(response) {
+    try {
+        _config.observeResponse?.(response);
+    }
+    catch {
+        /* observation is best-effort — never let a buggy observer crash refresh */
+    }
+}
+/** Test-only: restore defaults. Not exported from the package barrel. */
+export function __resetAuthCoreForTest() {
+    _config = DEFAULT_CONFIG;
+}

package/dist/esm/spawnEnv.d.ts

@@ -0,0 +1,76 @@
+/**
+ * OSK-3892 — spawn-env sanitization, shared by every OverSky process that
+ * spawns a model-driven child.
+ *
+ * ── Why this lives in auth-core ────────────────────────────────────────────
+ *
+ * The daemon has stripped its own credentials out of `process.env` before every
+ * harness spawn since `daemon/src/env-sanitize.ts` was written. `sky code` spawns
+ * THE SAME engine — `daemon/src/backends/acp.ts` and `cli/src/lib/sky-code.ts`
+ * resolve the same binary, from the same managed location — and had no
+ * equivalent, so `OVERSKY_TOKEN` (a cloud-reusable platform credential that
+ * authenticates every `/api/*` call as the human) entered the environment of a
+ * process that executes model-directed tools.
+ *
+ * The CLI cannot import `daemon/src`: separate packages, and the daemon already
+ * depends on the CLI, so the reverse edge would be a cycle. `auth-core` is the
+ * one package BOTH already resolve — it is a daemon dependency and is copied
+ * verbatim into the published CLI by `cli/scripts/vendor-monorepo-deps.js` — so
+ * this is the same move `harnessTrust.ts` made, for the same reason, with no
+ * build or release wiring to change.
+ *
+ * ── What deliberately did NOT move ────────────────────────────────────────
+ *
+ * `filterCustomEnv` and the `BLOCKED_CUSTOM_ENV_*` constants stay in the daemon.
+ * They govern SERVER-PROVIDED `customEnv` — a different threat model (stopping
+ * THEIR values coming IN and overriding the sandbox, rather than stopping OUR
+ * secrets leaking OUT) and a daemon-only concern: no other process is handed an
+ * env map by the control plane.
+ *
+ * ── The one asymmetry a consumer must decide for itself ───────────────────
+ *
+ * This is a DENY-LIST over the parent's own environment, and it strips provider
+ * credentials because the daemon delivers a child's model credential explicitly
+ * (`cred.env`, after the trust gate) and never by ambient inheritance. A parent
+ * whose supported mode IS ambient inheritance — `sky code` running BYOK, where
+ * the user's own key is the credential the run is meant to spend — has to
+ * re-admit that credential deliberately after this filter. See
+ * `cli/src/lib/sky-code.ts` (`engineSpawnEnv`). Do not soften the list here to
+ * serve that case: a deny-list with a hole is not a deny-list.
+ */
+/**
+ * Env vars that must NEVER reach a spawned subprocess.
+ *
+ * A malicious or compromised cloud-issued prompt that achieves command
+ * execution should NOT also exfiltrate every credential the parent has
+ * in its own env. We use a deny-list (strip these, keep everything
+ * else) because real tools legitimately need PATH, HOME, USER, LANG,
+ * etc.
+ *
+ * Categories:
+ *   - Daemon/Claude/Anthropic auth — direct account takeover.
+ *   - AWS — STS / IAM credentials, full cloud access.
+ *   - GitHub / npm / OpenAI — package-publish, repo, model access.
+ *   - OverSky internal secrets — match by prefix.
+ *   - DYLD/LD preload — library-injection vector for in-process compromise.
+ */
+export declare const SENSITIVE_ENV_VARS: ReadonlySet<string>;
+/** Variable name prefixes that should be stripped (catches families like AWS_*). */
+export declare const SENSITIVE_ENV_PREFIXES: readonly string[];
+/**
+ * Credential-shaped suffixes are also forbidden. A fixed provider list is
+ * never complete: a newly configured provider would otherwise leak its key
+ * into every harness until an engineer remembers to edit this file. The
+ * parent's own credentials must be delivered through a backend's explicit
+ * per-request allow-list, never by ambient inheritance.
+ */
+export declare const SENSITIVE_ENV_SUFFIXES: readonly string[];
+/** Specific OVERSKY_ vars to keep (the prefix sweep is broad on purpose). */
+export declare const SENSITIVE_ENV_PREFIX_EXCEPTIONS: ReadonlySet<string>;
+/**
+ * Build a sanitized snapshot of the parent's own env for a spawned
+ * child, stripping credentials and library-injection vectors while
+ * preserving everything else (PATH, HOME, USER, LANG, terminal vars,
+ * etc.) so legitimate tools keep working.
+ */
+export declare function sanitizeSpawnEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/esm/spawnEnv.js

@@ -0,0 +1,149 @@
+/**
+ * OSK-3892 — spawn-env sanitization, shared by every OverSky process that
+ * spawns a model-driven child.
+ *
+ * ── Why this lives in auth-core ────────────────────────────────────────────
+ *
+ * The daemon has stripped its own credentials out of `process.env` before every
+ * harness spawn since `daemon/src/env-sanitize.ts` was written. `sky code` spawns
+ * THE SAME engine — `daemon/src/backends/acp.ts` and `cli/src/lib/sky-code.ts`
+ * resolve the same binary, from the same managed location — and had no
+ * equivalent, so `OVERSKY_TOKEN` (a cloud-reusable platform credential that
+ * authenticates every `/api/*` call as the human) entered the environment of a
+ * process that executes model-directed tools.
+ *
+ * The CLI cannot import `daemon/src`: separate packages, and the daemon already
+ * depends on the CLI, so the reverse edge would be a cycle. `auth-core` is the
+ * one package BOTH already resolve — it is a daemon dependency and is copied
+ * verbatim into the published CLI by `cli/scripts/vendor-monorepo-deps.js` — so
+ * this is the same move `harnessTrust.ts` made, for the same reason, with no
+ * build or release wiring to change.
+ *
+ * ── What deliberately did NOT move ────────────────────────────────────────
+ *
+ * `filterCustomEnv` and the `BLOCKED_CUSTOM_ENV_*` constants stay in the daemon.
+ * They govern SERVER-PROVIDED `customEnv` — a different threat model (stopping
+ * THEIR values coming IN and overriding the sandbox, rather than stopping OUR
+ * secrets leaking OUT) and a daemon-only concern: no other process is handed an
+ * env map by the control plane.
+ *
+ * ── The one asymmetry a consumer must decide for itself ───────────────────
+ *
+ * This is a DENY-LIST over the parent's own environment, and it strips provider
+ * credentials because the daemon delivers a child's model credential explicitly
+ * (`cred.env`, after the trust gate) and never by ambient inheritance. A parent
+ * whose supported mode IS ambient inheritance — `sky code` running BYOK, where
+ * the user's own key is the credential the run is meant to spend — has to
+ * re-admit that credential deliberately after this filter. See
+ * `cli/src/lib/sky-code.ts` (`engineSpawnEnv`). Do not soften the list here to
+ * serve that case: a deny-list with a hole is not a deny-list.
+ */
+/**
+ * Env vars that must NEVER reach a spawned subprocess.
+ *
+ * A malicious or compromised cloud-issued prompt that achieves command
+ * execution should NOT also exfiltrate every credential the parent has
+ * in its own env. We use a deny-list (strip these, keep everything
+ * else) because real tools legitimately need PATH, HOME, USER, LANG,
+ * etc.
+ *
+ * Categories:
+ *   - Daemon/Claude/Anthropic auth — direct account takeover.
+ *   - AWS — STS / IAM credentials, full cloud access.
+ *   - GitHub / npm / OpenAI — package-publish, repo, model access.
+ *   - OverSky internal secrets — match by prefix.
+ *   - DYLD/LD preload — library-injection vector for in-process compromise.
+ */
+export const SENSITIVE_ENV_VARS = new Set([
+    'CLAUDE_CODE_OAUTH_TOKEN',
+    'OVERSKY_TOKEN',
+    'AWS_ACCESS_KEY_ID',
+    'AWS_SECRET_ACCESS_KEY',
+    'AWS_SESSION_TOKEN',
+    'GH_TOKEN',
+    'GITHUB_TOKEN',
+    'NPM_TOKEN',
+    'OPENAI_API_KEY',
+    'ANTHROPIC_API_KEY',
+    // Provider keys are parent-process credentials just as much as the two
+    // original OpenAI/Anthropic entries.  A child must receive one only through
+    // its backend's per-request, trust-gated credential contract; inheriting an
+    // operator export turns a compromised harness into a provider-account
+    // takeover. Keep this explicit rather than guessing from a suffix: ordinary
+    // application variables sometimes end in `_KEY` and are not credentials.
+    'OPENROUTER_API_KEY',
+    'GEMINI_API_KEY',
+    'GOOGLE_API_KEY',
+    'MOONSHOT_API_KEY',
+    'AZURE_OPENAI_API_KEY',
+    'COHERE_API_KEY',
+    'DEEPSEEK_API_KEY',
+    'MISTRAL_API_KEY',
+    'PERPLEXITY_API_KEY',
+    'XAI_API_KEY',
+    'HUGGINGFACE_HUB_TOKEN',
+    'LITELLM_MASTER_KEY',
+    'DYLD_INSERT_LIBRARIES',
+    'LD_PRELOAD',
+]);
+/** Variable name prefixes that should be stripped (catches families like AWS_*). */
+export const SENSITIVE_ENV_PREFIXES = ['AWS_', 'OVERSKY_'];
+/**
+ * Credential-shaped suffixes are also forbidden. A fixed provider list is
+ * never complete: a newly configured provider would otherwise leak its key
+ * into every harness until an engineer remembers to edit this file. The
+ * parent's own credentials must be delivered through a backend's explicit
+ * per-request allow-list, never by ambient inheritance.
+ */
+export const SENSITIVE_ENV_SUFFIXES = [
+    '_API_KEY',
+    '_API_TOKEN',
+    '_AUTH_TOKEN',
+    '_ACCESS_TOKEN',
+    '_REFRESH_TOKEN',
+    '_SECRET',
+    '_SECRET_KEY',
+    '_PASSWORD',
+    '_CREDENTIALS',
+];
+/** Specific OVERSKY_ vars to keep (the prefix sweep is broad on purpose). */
+export const SENSITIVE_ENV_PREFIX_EXCEPTIONS = new Set([
+    // Headless flag is read by spawned tools to know they're inside the daemon —
+    // not a secret. Add more here if a tool legitimately needs an OVERSKY_ var.
+    'OVERSKY_HEADLESS',
+    'OVERSKY_LAUNCHD_LABEL',
+    // OSK-1108 — canonical supervisor marker; spawned tools read it to
+    // know they're inside a supervised daemon on Linux/Windows in addition
+    // to macOS launchd. Not a secret.
+    'OVERSKY_SUPERVISOR',
+]);
+/**
+ * Build a sanitized snapshot of the parent's own env for a spawned
+ * child, stripping credentials and library-injection vectors while
+ * preserving everything else (PATH, HOME, USER, LANG, terminal vars,
+ * etc.) so legitimate tools keep working.
+ */
+export function sanitizeSpawnEnv(env) {
+    const out = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (value === undefined)
+            continue;
+        // Explicit deny wins unconditionally — even if key is in SENSITIVE_ENV_PREFIX_EXCEPTIONS.
+        if (SENSITIVE_ENV_VARS.has(key))
+            continue;
+        let stripped = false;
+        for (const prefix of SENSITIVE_ENV_PREFIXES) {
+            if (key.startsWith(prefix) && !SENSITIVE_ENV_PREFIX_EXCEPTIONS.has(key)) {
+                stripped = true;
+                break;
+            }
+        }
+        if (!stripped && SENSITIVE_ENV_SUFFIXES.some((suffix) => key.endsWith(suffix))) {
+            stripped = true;
+        }
+        if (stripped)
+            continue;
+        out[key] = value;
+    }
+    return out;
+}

package/dist/esm/ttlParser.d.ts

@@ -0,0 +1,54 @@
+/**
+ * ttlParser.ts — shared TTL-duration grammar for CI-token lifetimes.
+ *
+ * Single source of truth for the `--ttl` flag accepted by both
+ * `oversky create-token` (daemon CLI) and `sky create-token` (CLI).
+ * Before this module the CLI accepted bare integers only while the
+ * daemon accepted `30d`/`1y`/`1w` — users would learn the daemon
+ * grammar, hit a cryptic oclif integer-parser error when they tried
+ * the same string on `sky`, and file a confused bug (ADD-CLI1).
+ *
+ * Grammar:
+ *   <number><unit?>
+ *     unit := 'd' | 'w' | 'y'    (default 'd' if absent)
+ *
+ * Constraints:
+ *   days ∈ [MIN_TTL_DAYS, MAX_TTL_DAYS]  (1 .. 365)
+ *
+ * Errors are returned as a discriminated-union value rather than
+ * thrown, so each CLI can surface them with its own idioms
+ * (`this.error(...)` on oclif vs `showError(); process.exit(2)` on
+ * the daemon) without the parser owning process-exit semantics.
+ */
+export declare const MIN_TTL_DAYS = 1;
+export declare const MAX_TTL_DAYS = 365;
+export interface ParseTtlSuccess {
+    ok: true;
+    days: number;
+    /** Raw input for error echoing by the caller if needed. */
+    input: string;
+}
+export interface ParseTtlError {
+    ok: false;
+    code: 'INVALID_FORMAT' | 'OUT_OF_RANGE';
+    message: string;
+    input: string;
+}
+export type ParseTtlResult = ParseTtlSuccess | ParseTtlError;
+/**
+ * Parse a `--ttl` string into a concrete day count. Pure; never
+ * throws. Accepts `undefined`/empty as "use default."
+ *
+ * Examples:
+ *   parseTtlDays('30d')      → { ok: true, days: 30 }
+ *   parseTtlDays('1y')       → { ok: true, days: 365 }
+ *   parseTtlDays('2w')       → { ok: true, days: 14 }
+ *   parseTtlDays('90')       → { ok: true, days: 90 }
+ *   parseTtlDays('0')        → { ok: false, code: 'OUT_OF_RANGE' }
+ *   parseTtlDays('abc')      → { ok: false, code: 'INVALID_FORMAT' }
+ *   parseTtlDays('2y')       → { ok: false, code: 'OUT_OF_RANGE' } // 730d > 365
+ *
+ * The default-days argument is a day count, not a string, because the
+ * caller already knows it's in range — no need to re-parse.
+ */
+export declare function parseTtlDays(input: string | undefined | null, defaultDays: number): ParseTtlResult;

package/dist/esm/ttlParser.js

@@ -0,0 +1,83 @@
+/**
+ * ttlParser.ts — shared TTL-duration grammar for CI-token lifetimes.
+ *
+ * Single source of truth for the `--ttl` flag accepted by both
+ * `oversky create-token` (daemon CLI) and `sky create-token` (CLI).
+ * Before this module the CLI accepted bare integers only while the
+ * daemon accepted `30d`/`1y`/`1w` — users would learn the daemon
+ * grammar, hit a cryptic oclif integer-parser error when they tried
+ * the same string on `sky`, and file a confused bug (ADD-CLI1).
+ *
+ * Grammar:
+ *   <number><unit?>
+ *     unit := 'd' | 'w' | 'y'    (default 'd' if absent)
+ *
+ * Constraints:
+ *   days ∈ [MIN_TTL_DAYS, MAX_TTL_DAYS]  (1 .. 365)
+ *
+ * Errors are returned as a discriminated-union value rather than
+ * thrown, so each CLI can surface them with its own idioms
+ * (`this.error(...)` on oclif vs `showError(); process.exit(2)` on
+ * the daemon) without the parser owning process-exit semantics.
+ */
+export const MIN_TTL_DAYS = 1;
+export const MAX_TTL_DAYS = 365;
+const TTL_RE = /^(\d+)\s*([dwy]?)$/i;
+/**
+ * Parse a `--ttl` string into a concrete day count. Pure; never
+ * throws. Accepts `undefined`/empty as "use default."
+ *
+ * Examples:
+ *   parseTtlDays('30d')      → { ok: true, days: 30 }
+ *   parseTtlDays('1y')       → { ok: true, days: 365 }
+ *   parseTtlDays('2w')       → { ok: true, days: 14 }
+ *   parseTtlDays('90')       → { ok: true, days: 90 }
+ *   parseTtlDays('0')        → { ok: false, code: 'OUT_OF_RANGE' }
+ *   parseTtlDays('abc')      → { ok: false, code: 'INVALID_FORMAT' }
+ *   parseTtlDays('2y')       → { ok: false, code: 'OUT_OF_RANGE' } // 730d > 365
+ *
+ * The default-days argument is a day count, not a string, because the
+ * caller already knows it's in range — no need to re-parse.
+ */
+export function parseTtlDays(input, defaultDays) {
+    if (input == null || input === '') {
+        return { ok: true, days: defaultDays, input: '' };
+    }
+    const trimmed = String(input).trim();
+    const m = trimmed.match(TTL_RE);
+    if (!m) {
+        return {
+            ok: false,
+            code: 'INVALID_FORMAT',
+            input: trimmed,
+            message: `Invalid --ttl value "${trimmed}". ` +
+                `Examples: 30d (30 days), 2w (14 days), 1y (365 days), 90 (treated as days).`,
+        };
+    }
+    const n = parseInt(m[1], 10);
+    const unit = (m[2] || 'd').toLowerCase();
+    let days;
+    switch (unit) {
+        case 'd':
+            days = n;
+            break;
+        case 'w':
+            days = n * 7;
+            break;
+        case 'y':
+            days = n * 365;
+            break;
+        default:
+            days = n;
+            break;
+    }
+    if (!Number.isFinite(days) || days < MIN_TTL_DAYS || days > MAX_TTL_DAYS) {
+        return {
+            ok: false,
+            code: 'OUT_OF_RANGE',
+            input: trimmed,
+            message: `--ttl must be ${MIN_TTL_DAYS}–${MAX_TTL_DAYS} days (got ${days} days from "${trimmed}").`,
+        };
+    }
+    return { ok: true, days, input: trimmed };
+}