@id-wispera/core 0.1.0

package/dist/auth/keychainProvider.js

@@ -0,0 +1,98 @@
+/**
+ * ID Wispera Keychain Provider
+ * Optional OS keychain integration for secure passphrase storage.
+ *
+ * Uses `keytar` when available (macOS Keychain, Windows Credential Manager,
+ * Linux Secret Service). Degrades gracefully — returns null if keytar is
+ * not installed or the OS keychain is unavailable.
+ */
+const SERVICE_NAME = 'id-wispera';
+const ACCOUNT_NAME = 'vault-passphrase';
+/**
+ * Thin wrapper around the OS keychain.  Every public method catches import
+ * and runtime errors so callers never need to know whether keytar is present.
+ */
+export class KeychainProvider {
+    keytar = null;
+    loadAttempted = false;
+    /**
+     * Lazily try to load keytar.  Called once — result is cached.
+     */
+    async loadKeytar() {
+        if (this.loadAttempted)
+            return this.keytar;
+        this.loadAttempted = true;
+        try {
+            // Dynamic import so keytar remains an optional peer dependency
+            this.keytar = await import('keytar');
+        }
+        catch {
+            this.keytar = null;
+        }
+        return this.keytar;
+    }
+    /**
+     * Whether the keychain backend is available on this system.
+     */
+    async isAvailable() {
+        const kt = await this.loadKeytar();
+        if (!kt)
+            return false;
+        // Some environments have keytar installed but no backing store.
+        // Smoke-test with a harmless read to verify.
+        try {
+            await kt.getPassword(SERVICE_NAME, '__probe__');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Store the vault passphrase in the OS keychain.
+     * Returns `true` on success, `false` if the keychain is unavailable.
+     */
+    async store(passphrase) {
+        const kt = await this.loadKeytar();
+        if (!kt)
+            return false;
+        try {
+            await kt.setPassword(SERVICE_NAME, ACCOUNT_NAME, passphrase);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Retrieve the vault passphrase from the OS keychain.
+     * Returns `null` if unavailable or no entry exists.
+     */
+    async retrieve() {
+        const kt = await this.loadKeytar();
+        if (!kt)
+            return null;
+        try {
+            return await kt.getPassword(SERVICE_NAME, ACCOUNT_NAME);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Remove the vault passphrase from the OS keychain.
+     * Returns `true` if deleted, `false` if unavailable or nothing to delete.
+     */
+    async remove() {
+        const kt = await this.loadKeytar();
+        if (!kt)
+            return false;
+        try {
+            return await kt.deletePassword(SERVICE_NAME, ACCOUNT_NAME);
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=keychainProvider.js.map

package/dist/auth/keychainProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keychainProvider.js","sourceRoot":"","sources":["../../src/auth/keychainProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,YAAY,GAAG,YAAY,CAAC;AAClC,MAAM,YAAY,GAAG,kBAAkB,CAAC;AAExC;;;GAGG;AACH,MAAM,OAAO,gBAAgB;IACnB,MAAM,GAAmC,IAAI,CAAC;IAC9C,aAAa,GAAG,KAAK,CAAC;IAE9B;;OAEG;IACK,KAAK,CAAC,UAAU;QACtB,IAAI,IAAI,CAAC,aAAa;YAAE,OAAO,IAAI,CAAC,MAAM,CAAC;QAC3C,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QAE1B,IAAI,CAAC;YACH,+DAA+D;YAC/D,IAAI,CAAC,MAAM,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvC,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACrB,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,WAAW;QACf,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC,EAAE;YAAE,OAAO,KAAK,CAAC;QAEtB,gEAAgE;QAChE,6CAA6C;QAC7C,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,WAAW,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;YAChD,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK,CAAC,UAAkB;QAC5B,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC,EAAE;YAAE,OAAO,KAAK,CAAC;QAEtB,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,WAAW,CAAC,YAAY,EAAE,YAAY,EAAE,UAAU,CAAC,CAAC;YAC7D,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,QAAQ;QACZ,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QAErB,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,CAAC,WAAW,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;QAC1D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,MAAM;QACV,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC,EAAE;YAAE,OAAO,KAAK,CAAC;QAEtB,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,CAAC,cAAc,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;QAC7D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}

package/dist/auth/passphraseProvider.d.ts

@@ -0,0 +1,80 @@
+/**
+ * ID Wispera Passphrase Provider
+ * Resolves the vault passphrase through a priority chain of strategies.
+ *
+ * Resolution order:
+ *   1. Session token  — IDW_SESSION_TOKEN env var → sidecar decrypt
+ *   2. OS keychain    — keytar (optional native module)
+ *   3. Env var / .env — IDW_PASSPHRASE from environment or .env file
+ *   4. Interactive     — masked terminal prompt (CLI only)
+ *
+ * The user explicitly chooses their auth mode:
+ *   - Passphrase mode (default): keychain, env var, or interactive prompt
+ *   - Session token mode (opt-in): for CI / headless via `idw auth token create`
+ *
+ * If IDW_SESSION_TOKEN is set it takes precedence — the user has opted in.
+ * Otherwise we try the keychain, then env var / .env, then prompt.
+ */
+export interface PassphraseProviderOptions {
+    /**
+     * Allow interactive terminal prompt (masked input).
+     * Set to `false` for headless environments (MCP server, CI).
+     * @default false
+     */
+    allowInteractive?: boolean;
+    /**
+     * Allow the IDW_PASSPHRASE env var (or .env file).
+     * When true, the provider checks the process environment and then
+     * .env files ($CWD/.env, ~/.id-wispera/.env) for IDW_PASSPHRASE.
+     * @default true
+     */
+    allowEnvVar?: boolean;
+    /**
+     * Custom prompt function for interactive mode.
+     * Receives a message string and must return the passphrase.
+     * If not provided, a default `inquirer` prompt is used.
+     */
+    promptFn?: (message: string) => Promise<string>;
+    /**
+     * Custom path for the session token sidecar file.
+     * Defaults to ~/.id-wispera/sessions.json
+     */
+    sidecarPath?: string;
+}
+export type PassphraseSource = 'session-token' | 'keychain' | 'env-var' | 'dotenv-file' | 'interactive';
+export interface PassphraseResult {
+    passphrase: string;
+    source: PassphraseSource;
+}
+export declare class PassphraseProvider {
+    private keychain;
+    private tokenManager;
+    private options;
+    constructor(options?: PassphraseProviderOptions);
+    /**
+     * Resolve the vault passphrase by walking the strategy chain.
+     * @throws Error if no strategy succeeds.
+     */
+    resolve(): Promise<PassphraseResult>;
+    /**
+     * Convenience: resolve and return just the passphrase string.
+     */
+    getPassphrase(): Promise<string>;
+    /**
+     * Look for IDW_PASSPHRASE in the process environment first, then in .env
+     * files ($CWD/.env → ~/.id-wispera/.env).  Only the IDW_PASSPHRASE key is
+     * read — no other variables are loaded.
+     */
+    private static resolveFromEnvOrDotenv;
+    /**
+     * Parse a .env file and return the value of IDW_PASSPHRASE, or null.
+     * Lightweight parser: splits on first `=`, ignores comments and blanks.
+     */
+    private static readPassphraseFromDotenv;
+    /**
+     * Warn to stderr if a .env file is world-readable.
+     */
+    private static warnIfWorldReadable;
+    private prompt;
+}
+//# sourceMappingURL=passphraseProvider.d.ts.map

package/dist/auth/passphraseProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"passphraseProvider.d.ts","sourceRoot":"","sources":["../../src/auth/passphraseProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA0BH,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAEhD;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,gBAAgB,GACxB,eAAe,GACf,UAAU,GACV,SAAS,GACT,aAAa,GACb,aAAa,CAAC;AAElB,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAMD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAmB;IACnC,OAAO,CAAC,YAAY,CAAsB;IAC1C,OAAO,CAAC,OAAO,CAEiD;gBAEpD,OAAO,GAAE,yBAA8B;IAWnD;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAkC1C;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAStC;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAwBrC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,wBAAwB;IA2BvC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;YAepB,MAAM;CAyBrB"}

package/dist/auth/passphraseProvider.js

@@ -0,0 +1,188 @@
+/**
+ * ID Wispera Passphrase Provider
+ * Resolves the vault passphrase through a priority chain of strategies.
+ *
+ * Resolution order:
+ *   1. Session token  — IDW_SESSION_TOKEN env var → sidecar decrypt
+ *   2. OS keychain    — keytar (optional native module)
+ *   3. Env var / .env — IDW_PASSPHRASE from environment or .env file
+ *   4. Interactive     — masked terminal prompt (CLI only)
+ *
+ * The user explicitly chooses their auth mode:
+ *   - Passphrase mode (default): keychain, env var, or interactive prompt
+ *   - Session token mode (opt-in): for CI / headless via `idw auth token create`
+ *
+ * If IDW_SESSION_TOKEN is set it takes precedence — the user has opted in.
+ * Otherwise we try the keychain, then env var / .env, then prompt.
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { KeychainProvider } from './keychainProvider.js';
+import { SessionTokenManager, } from './sessionTokenManager.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const PASSPHRASE_ENV_VAR = 'IDW_PASSPHRASE';
+const NO_PASSPHRASE_ERROR = 'No passphrase available. Options:\n' +
+    "  - Run 'idw auth login' to store in OS keychain\n" +
+    "  - Run 'idw auth token create' for headless / CI environments\n" +
+    `  - Set ${PASSPHRASE_ENV_VAR} in your environment or a .env file`;
+// ============================================================================
+// Provider
+// ============================================================================
+export class PassphraseProvider {
+    keychain;
+    tokenManager;
+    options;
+    constructor(options = {}) {
+        this.options = {
+            allowInteractive: options.allowInteractive ?? false,
+            allowEnvVar: options.allowEnvVar ?? true,
+            promptFn: options.promptFn,
+            sidecarPath: options.sidecarPath,
+        };
+        this.keychain = new KeychainProvider();
+        this.tokenManager = new SessionTokenManager(this.options.sidecarPath);
+    }
+    /**
+     * Resolve the vault passphrase by walking the strategy chain.
+     * @throws Error if no strategy succeeds.
+     */
+    async resolve() {
+        // ── 1. Session token ───────────────────────────────────────────────
+        const token = SessionTokenManager.getTokenFromEnv();
+        if (token) {
+            const passphrase = await this.tokenManager.resolve(token);
+            return { passphrase, source: 'session-token' };
+        }
+        // ── 2. OS keychain ─────────────────────────────────────────────────
+        const keychainPassphrase = await this.keychain.retrieve();
+        if (keychainPassphrase) {
+            return { passphrase: keychainPassphrase, source: 'keychain' };
+        }
+        // ── 3. IDW_PASSPHRASE env var or .env file ────────────────────────
+        if (this.options.allowEnvVar) {
+            const envResult = PassphraseProvider.resolveFromEnvOrDotenv();
+            if (envResult) {
+                return envResult;
+            }
+        }
+        // ── 4. Interactive prompt ──────────────────────────────────────────
+        if (this.options.allowInteractive) {
+            const passphrase = await this.prompt();
+            if (passphrase) {
+                return { passphrase, source: 'interactive' };
+            }
+        }
+        // ── Nothing worked ─────────────────────────────────────────────────
+        throw new Error(NO_PASSPHRASE_ERROR);
+    }
+    /**
+     * Convenience: resolve and return just the passphrase string.
+     */
+    async getPassphrase() {
+        const result = await this.resolve();
+        return result.passphrase;
+    }
+    // --------------------------------------------------------------------------
+    // Internal
+    // --------------------------------------------------------------------------
+    /**
+     * Look for IDW_PASSPHRASE in the process environment first, then in .env
+     * files ($CWD/.env → ~/.id-wispera/.env).  Only the IDW_PASSPHRASE key is
+     * read — no other variables are loaded.
+     */
+    static resolveFromEnvOrDotenv() {
+        // Process environment takes precedence
+        const envVal = process.env[PASSPHRASE_ENV_VAR];
+        if (envVal) {
+            return { passphrase: envVal, source: 'env-var' };
+        }
+        // Try .env files: CWD first, then ~/.id-wispera/
+        const candidates = [
+            join(process.cwd(), '.env'),
+            join(homedir(), '.id-wispera', '.env'),
+        ];
+        for (const filePath of candidates) {
+            const passphrase = PassphraseProvider.readPassphraseFromDotenv(filePath);
+            if (passphrase) {
+                PassphraseProvider.warnIfWorldReadable(filePath);
+                return { passphrase, source: 'dotenv-file' };
+            }
+        }
+        return null;
+    }
+    /**
+     * Parse a .env file and return the value of IDW_PASSPHRASE, or null.
+     * Lightweight parser: splits on first `=`, ignores comments and blanks.
+     */
+    static readPassphraseFromDotenv(filePath) {
+        try {
+            const content = readFileSync(filePath, 'utf-8');
+            for (const line of content.split('\n')) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed.startsWith('#'))
+                    continue;
+                const eqIndex = trimmed.indexOf('=');
+                if (eqIndex === -1)
+                    continue;
+                const key = trimmed.slice(0, eqIndex).trim();
+                if (key === PASSPHRASE_ENV_VAR) {
+                    let value = trimmed.slice(eqIndex + 1).trim();
+                    // Strip surrounding quotes if present
+                    if ((value.startsWith('"') && value.endsWith('"')) ||
+                        (value.startsWith("'") && value.endsWith("'"))) {
+                        value = value.slice(1, -1);
+                    }
+                    return value || null;
+                }
+            }
+        }
+        catch {
+            // File doesn't exist or isn't readable — skip
+        }
+        return null;
+    }
+    /**
+     * Warn to stderr if a .env file is world-readable.
+     */
+    static warnIfWorldReadable(filePath) {
+        try {
+            const mode = statSync(filePath).mode;
+            // Check "other read" bit (0o004)
+            if (mode & 0o004) {
+                process.stderr.write(`[WARNING] ${filePath} is world-readable. ` +
+                    'Consider running: chmod 600 ' + filePath + '\n');
+            }
+        }
+        catch {
+            // stat failed — skip warning
+        }
+    }
+    async prompt() {
+        // User-supplied prompt function takes precedence
+        if (this.options.promptFn) {
+            return this.options.promptFn('Enter vault passphrase:');
+        }
+        // Fallback to inquirer (dynamic import — optional dep for non-CLI use)
+        try {
+            const inquirer = await import('inquirer');
+            const { passphrase } = await inquirer.default.prompt([
+                {
+                    type: 'password',
+                    name: 'passphrase',
+                    message: 'Enter vault passphrase:',
+                    mask: '*',
+                    validate: (input) => input.length >= 1 || 'Passphrase is required',
+                },
+            ]);
+            return passphrase || null;
+        }
+        catch {
+            // inquirer not available — skip interactive
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=passphraseProvider.js.map

package/dist/auth/passphraseProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"passphraseProvider.js","sourceRoot":"","sources":["../../src/auth/passphraseProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EACL,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAElC,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AAE5C,MAAM,mBAAmB,GACvB,qCAAqC;IACrC,oDAAoD;IACpD,kEAAkE;IAClE,WAAW,kBAAkB,qCAAqC,CAAC;AAgDrE,+EAA+E;AAC/E,WAAW;AACX,+EAA+E;AAE/E,MAAM,OAAO,kBAAkB;IACrB,QAAQ,CAAmB;IAC3B,YAAY,CAAsB;IAClC,OAAO,CAEiD;IAEhE,YAAY,UAAqC,EAAE;QACjD,IAAI,CAAC,OAAO,GAAG;YACb,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,IAAI,KAAK;YACnD,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;YACxC,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,CAAC;QACF,IAAI,CAAC,QAAQ,GAAG,IAAI,gBAAgB,EAAE,CAAC;QACvC,IAAI,CAAC,YAAY,GAAG,IAAI,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACxE,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO;QACX,sEAAsE;QACtE,MAAM,KAAK,GAAG,mBAAmB,CAAC,eAAe,EAAE,CAAC;QACpD,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;QACjD,CAAC;QAED,sEAAsE;QACtE,MAAM,kBAAkB,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;QAC1D,IAAI,kBAAkB,EAAE,CAAC;YACvB,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;QAChE,CAAC;QAED,qEAAqE;QACrE,IAAI,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;YAC7B,MAAM,SAAS,GAAG,kBAAkB,CAAC,sBAAsB,EAAE,CAAC;YAC9D,IAAI,SAAS,EAAE,CAAC;gBACd,OAAO,SAAS,CAAC;YACnB,CAAC;QACH,CAAC;QAED,sEAAsE;QACtE,IAAI,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC;YAClC,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;YACvC,IAAI,UAAU,EAAE,CAAC;gBACf,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;YAC/C,CAAC;QACH,CAAC;QAED,sEAAsE;QACtE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,aAAa;QACjB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACpC,OAAO,MAAM,CAAC,UAAU,CAAC;IAC3B,CAAC;IAED,6EAA6E;IAC7E,WAAW;IACX,6EAA6E;IAE7E;;;;OAIG;IACK,MAAM,CAAC,sBAAsB;QACnC,uCAAuC;QACvC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QAC/C,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QACnD,CAAC;QAED,iDAAiD;QACjD,MAAM,UAAU,GAAG;YACjB,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC;YAC3B,IAAI,CAAC,OAAO,EAAE,EAAE,aAAa,EAAE,MAAM,CAAC;SACvC,CAAC;QAEF,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;YAClC,MAAM,UAAU,GAAG,kBAAkB,CAAC,wBAAwB,CAAC,QAAQ,CAAC,CAAC;YACzE,IAAI,UAAU,EAAE,CAAC;gBACf,kBAAkB,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;gBACjD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;YAC/C,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACK,MAAM,CAAC,wBAAwB,CAAC,QAAgB;QACtD,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAChD,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;gBACvC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;gBAC5B,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;oBAAE,SAAS;gBAClD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;gBACrC,IAAI,OAAO,KAAK,CAAC,CAAC;oBAAE,SAAS;gBAC7B,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;gBAC7C,IAAI,GAAG,KAAK,kBAAkB,EAAE,CAAC;oBAC/B,IAAI,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;oBAC9C,sCAAsC;oBACtC,IACE,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;wBAC9C,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAC9C,CAAC;wBACD,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;oBAC7B,CAAC;oBACD,OAAO,KAAK,IAAI,IAAI,CAAC;gBACvB,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,8CAA8C;QAChD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,mBAAmB,CAAC,QAAgB;QACjD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC;YACrC,iCAAiC;YACjC,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;gBACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,aAAa,QAAQ,sBAAsB;oBAC3C,8BAA8B,GAAG,QAAQ,GAAG,IAAI,CACjD,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,6BAA6B;QAC/B,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,MAAM;QAClB,iDAAiD;QACjD,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;YAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAC,CAAC;QAC1D,CAAC;QAED,uEAAuE;QACvE,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;YAC1C,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC;gBACnD;oBACE,IAAI,EAAE,UAAU;oBAChB,IAAI,EAAE,YAAY;oBAClB,OAAO,EAAE,yBAAyB;oBAClC,IAAI,EAAE,GAAG;oBACT,QAAQ,EAAE,CAAC,KAAa,EAAE,EAAE,CAC1B,KAAK,CAAC,MAAM,IAAI,CAAC,IAAI,wBAAwB;iBAChD;aACF,CAAC,CAAC;YACH,OAAO,UAAU,IAAI,IAAI,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,4CAA4C;YAC5C,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;CACF"}

package/dist/auth/sessionTokenManager.d.ts

@@ -0,0 +1,106 @@
+/**
+ * ID Wispera Session Token Manager
+ * Manages short-lived session tokens for headless / CI environments.
+ *
+ * Design:
+ *   - Tokens live in a sidecar file (~/.id-wispera/sessions.json), NOT inside
+ *     the encrypted vault (avoids the chicken-and-egg problem).
+ *   - Each sidecar entry stores the vault passphrase encrypted with a key
+ *     derived from the token itself (PBKDF2 + AES-256-GCM).
+ *   - The token is the only runtime credential needed — set as
+ *     IDW_SESSION_TOKEN env var.
+ *   - If the sidecar is lost or corrupted the user still has their passphrase
+ *     as the root recovery path.
+ *
+ * Token format:
+ *   idw_token_ + 64 random bytes base64url-encoded  (~90 chars total)
+ *
+ * Sidecar schema (cross-SDK compatible — TS, Python, Go all read/write this):
+ *   {
+ *     "version": 1,
+ *     "entries": [
+ *       {
+ *         "tokenHash":            "<SHA-256 hex>",
+ *         "salt":                 "<32 bytes hex>",
+ *         "iv":                   "<12 bytes hex>",
+ *         "encryptedPassphrase":  "<AES-256-GCM ciphertext, base64>",
+ *         "createdAt":            "<ISO 8601>",
+ *         "expiresAt":            "<ISO 8601 | null>",
+ *         "label":                "<user-provided label>"
+ *       }
+ *     ]
+ *   }
+ */
+declare const ENV_VAR = "IDW_SESSION_TOKEN";
+export interface SidecarEntry {
+    tokenHash: string;
+    salt: string;
+    iv: string;
+    encryptedPassphrase: string;
+    createdAt: string;
+    expiresAt: string | null;
+    label: string;
+}
+export interface SidecarFile {
+    version: number;
+    entries: SidecarEntry[];
+}
+export interface TokenInfo {
+    tokenHash: string;
+    label: string;
+    createdAt: string;
+    expiresAt: string | null;
+}
+export declare class SessionTokenManager {
+    private sidecarPath;
+    constructor(sidecarPath?: string);
+    /** Read the sidecar file.  Returns an empty structure if missing/corrupt. */
+    private readSidecar;
+    /** Write the sidecar file, creating parent directories as needed. */
+    private writeSidecar;
+    /**
+     * Generate a new CSPRNG token string.
+     */
+    generateToken(): string;
+    /**
+     * Create a session token entry.  Encrypts the passphrase with a key
+     * derived from the token and stores the entry in the sidecar file.
+     *
+     * @returns The plaintext token (shown to the user once — never stored).
+     */
+    create(passphrase: string, options?: {
+        label?: string;
+        expiresInSeconds?: number;
+    }): Promise<string>;
+    /**
+     * Resolve a session token → vault passphrase.
+     *
+     * Looks up the sidecar entry by the token's SHA-256 hash, checks expiry,
+     * then decrypts the passphrase.
+     *
+     * @throws Error if the token is invalid, expired, or sidecar is missing.
+     */
+    resolve(token: string): Promise<string>;
+    /**
+     * Revoke a session token by its hash prefix (first 8+ hex chars).
+     * Returns `true` if an entry was removed.
+     */
+    revoke(hashPrefix: string): Promise<boolean>;
+    /**
+     * List all session tokens (metadata only — never returns secrets).
+     * Expired entries are included but marked.
+     */
+    list(): Promise<TokenInfo[]>;
+    /**
+     * Remove all expired entries from the sidecar.
+     * Returns the number of entries removed.
+     */
+    pruneExpired(): Promise<number>;
+    /**
+     * Read the token from the environment variable.
+     * Returns `null` if not set.
+     */
+    static getTokenFromEnv(): string | null;
+}
+export { ENV_VAR as SESSION_TOKEN_ENV_VAR };
+//# sourceMappingURL=sessionTokenManager.d.ts.map

package/dist/auth/sessionTokenManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionTokenManager.d.ts","sourceRoot":"","sources":["../../src/auth/sessionTokenManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAcH,QAAA,MAAM,OAAO,sBAAsB,CAAC;AAMpC,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,mBAAmB,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AA+GD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,WAAW,CAAS;gBAEhB,WAAW,CAAC,EAAE,MAAM;IAKhC,6EAA6E;YAC/D,WAAW;IAczB,qEAAqE;YACvD,YAAY;IAc1B;;OAEG;IACH,aAAa,IAAI,MAAM;IAKvB;;;;;OAKG;IACG,MAAM,CACV,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAO,GAC1D,OAAO,CAAC,MAAM,CAAC;IA6BlB;;;;;;;OAOG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuC7C;;;OAGG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWlD;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAUlC;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAYrC;;;OAGG;IACH,MAAM,CAAC,eAAe,IAAI,MAAM,GAAG,IAAI;CAGxC;AAED,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,CAAC"}