regen-koi-mcp 1.2.0 → 1.3.0

package/README.md

@@ -4,28 +4,69 @@ Access Regen Network's Knowledge Organization Infrastructure (KOI) through Model
 
 ## 🚀 Quick Start
 
-### One-Line Install (Easiest!)
+**Choose your installation method:**
+- **Native CLI commands** (Recommended) - Most transparent and secure
+- **Automated install script** - Convenient for multiple clients at once
+- **Manual configuration** - Full control over your setup
+
+### Recommended: Native CLI Commands
+
+The simplest and most secure way to install for supported clients:
+
+**Claude Code CLI:**
+```bash
+claude mcp add regen-koi npx regen-koi-mcp@latest
+```
+
+**Codex:**
+```bash
+codex mcp add regen-koi npx "-y regen-koi-mcp@latest"
+```
+
+**Warp:**
+```bash
+/add-mcp regen-koi npx -y regen-koi-mcp@latest
+```
+
+**Amp:**
+```bash
+amp mcp add regen-koi -- npx -y regen-koi-mcp@latest
+```
+
+**Factory:**
+```bash
+droid mcp add regen-koi "npx -y regen-koi-mcp@latest"
+```
+
+Then configure the environment variable (see [client-specific sections](#-supported-clients) below for details).
+
+### Alternative: Automated Install Script
+
+**⚠️ Security Note:** This script requires bash access and modifies config files. Review the [install script](https://raw.githubusercontent.com/gaiaaiagent/regen-koi-mcp/main/install.sh) before running.
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/gaiaaiagent/regen-koi-mcp/main/install.sh | bash
 ```
 
-This automatically configures Claude Desktop and Claude Code CLI. Just restart and you're done! 🎉
+**What this does:**
+- Automatically configures Claude Desktop and Claude Code CLI
+- Sets up environment variables
+- Works for multiple clients at once
 
-**Quick Test:** After restarting, open Claude and ask: _"What repositories are indexed in KOI?"_ to verify the tools are working.
+**Quick Test:** After installation, restart your client and ask: _"What repositories are indexed in KOI?"_ to verify the tools are working.
 
 ---
 
-### Option 1: NPM (Recommended - Auto-Updates)
+### Manual Configuration (All Clients)
 
-**No installation needed!** Just configure Claude Desktop with:
+**For clients without a CLI command**, manually add this configuration:
 
 ```json
 {
   "mcpServers": {
     "regen-koi": {
       "command": "npx",
-      "args": ["-y", "regen-koi-mcp@latest"],
+      "args": ["regen-koi-mcp@latest"],
       "env": {
         "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
       }
@@ -55,7 +96,9 @@ Then restart Claude Desktop and you're done! 🎉
 
 ### 🔄 Migrating from Git Installation
 
-If you previously installed via `git clone`, switch to npx for automatic updates:
+If you previously installed via `git clone`, switch to npx for automatic updates.
+
+⚠️ **Security Note:** Review the [migrate script](https://raw.githubusercontent.com/gaiaaiagent/regen-koi-mcp/main/migrate.sh) before running.
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/gaiaaiagent/regen-koi-mcp/main/migrate.sh | bash
@@ -123,20 +166,31 @@ Regen Network team members with `@regen.network` emails can optionally authentic
 ```
 User: "Please use the regen_koi_authenticate tool"
 
-MCP: Opening browser for authentication...
-     [Browser opens to Google OAuth]
+MCP: ## Authentication Required
+
+     🌐 Your browser should open automatically. If not, click:
+     [Open Activation Page](https://regen.gaiaai.xyz/activate)
+
+     Enter this code: NWDV-FCFC
+
+     Sign in with your @regen.network email.
 
-User: [Log in with yourname@regen.network]
-      [Grant permissions: email, profile]
+     After completing, run this tool again to retrieve your session token.
+
+User: [Completes authentication in browser]
+      "Please use the regen_koi_authenticate tool again"
+
+MCP: ✅ Authentication Successful!
+     You now have access to internal Regen Network documentation.
 
-MCP: ✅ Authentication successful!
      Authenticated as: yourname@regen.network
 ```
 
 **After authentication:**
 - Queries automatically include internal documentation
-- Token is saved on the server (not your machine)
-- No need to re-authenticate unless token expires (~7 days)
+- Token is saved locally in `~/.koi-auth.json` and cached in memory
+- Session expires after ~1 hour
+- Browser auto-opens to activation page for convenience
 
 ### What Permissions Are Requested
 
@@ -174,10 +228,20 @@ MCP: Found 23 results from multiple sources:
 ### Token Security
 
 Your authentication tokens are:
-- 🔒 Stored server-side only (never on your machine)
-- 🔒 Encrypted in PostgreSQL database
-- 🔒 User-specific (never shared between users)
-- 🔒 Automatically refreshed when needed
+- 🔒 **Local Storage**: Saved in `~/.koi-auth.json` with `0o600` permissions (owner read/write only)
+- 🔒 **Database**: SHA-256 hashed when stored in PostgreSQL (no plain tokens stored)
+- 🔒 **User-Specific**: Never shared between users; each session is isolated
+- 🔒 **Short-Lived**: Sessions expire after 1 hour; tokens are revocable
+- 🔒 **Domain Enforcement**: Only `@regen.network` emails are permitted (verified in JWT claims)
+- 🔒 **Phishing Prevention**: RFC 8628 Device Authorization Grant with user-typed codes
+- 🔒 **Rate Limited**: 5 attempts/min on activation, 60 req/min on token endpoint
+- 🔒 **No Secrets in URLs**: All authentication flows use POST requests to prevent logging
+- 🔒 **Hardcoded URLs**: Activation page URL is hardcoded in the client (not from server)
+- 🔒 **JWT Validation**: Google ID tokens validated locally with signature verification
+
+**Production-Ready:** This authentication system follows RFC 8628 and industry best practices.
+
+See [docs/AUTHENTICATION.md](docs/AUTHENTICATION.md) for complete security documentation and threat model.
 
 ### Troubleshooting
 
@@ -268,8 +332,7 @@ Once you've installed the MCP server, try these queries in Claude to explore wha
 ### Knowledge Base Search
 | Tool | Description | Key Inputs |
 |------|-------------|-----------|
-| `search_knowledge` | Hybrid search (vectors + graph with RRF) | `query` (string), `limit` (1–20, default 5), `published_from` (YYYY‑MM‑DD), `published_to` (YYYY‑MM‑DD), `include_undated` (bool, default false) |
-| `hybrid_search` | Intelligent search routing (auto-detects entity vs conceptual queries) | `query` (string), `limit` (1–50, default 10) |
+| `search` | Hybrid search (vectors + graph with RRF) | `query` (string), `limit` (1–50, default 10), `published_from` (YYYY‑MM‑DD), `published_to` (YYYY‑MM‑DD), `include_undated` (bool, default false) |
 | `get_stats` | Knowledge base statistics | `detailed` (boolean) |
 | `generate_weekly_digest` | Generate weekly digest SUMMARY of Regen Network activity | `start_date` (YYYY-MM-DD, default: 7 days ago), `end_date` (YYYY-MM-DD, default: today), `save_to_file` (bool, default false), `output_path` (string), `format` ('markdown' or 'json', default: 'markdown') |
 | `get_notebooklm_export` | Get FULL NotebookLM export with complete forum posts, Notion pages, and source material | `save_to_file` (bool, default false), `output_path` (string) |
@@ -286,6 +349,11 @@ Once you've installed the MCP server, try these queries in Claude to explore wha
 | `get_repo_overview` | Get structured overview of a Regen repository | `repository` (enum: regen-ledger, regen-web, regen-data-standards, regenie-corpus) |
 | `get_tech_stack` | Get technical stack information for Regen repositories | `repository` (optional, omit to show all repos) |
 
+### Authentication (Team Members Only)
+| Tool | Description | Key Inputs |
+|------|-------------|-----------|
+| `regen_koi_authenticate` | Authenticate with @regen.network email to access internal documentation | None (opens browser for OAuth login) |
+
 ---
 
 ## 🤔 What Can I Ask? User Guide
@@ -317,8 +385,8 @@ This table helps you understand which tool to use for different tasks. Just ask
 | Get repository overview                                  | "Give me an overview of regen-web"                       | `get_repo_overview`      |
 | Understand tech stack                                    | "What's the tech stack for regen-ledger?"                | `get_tech_stack`         |
 | **Search everything (hybrid)**                           |                                                          |                          |
-| Semantic search across code and docs                     | "How does credit retirement work?"                       | `hybrid_search`          |
-| Advanced filtering by date                               | "Find discussions about tokens from last week"           | `search_knowledge`       |
+| Semantic search across code and docs                     | "How does credit retirement work?"                       | `search`                 |
+| Advanced filtering by date                               | "Find discussions about tokens from last week"           | `search`                 |
 | **Get activity summaries**                               |                                                          |                          |
 | Generate weekly digest summary                           | "Create a weekly digest of Regen activity"               | `generate_weekly_digest` |
 | Get full content for NotebookLM                          | "Get the full NotebookLM export with all forum posts"    | `get_notebooklm_export`  |
@@ -394,18 +462,19 @@ regen-koi-mcp/
 
 ### Claude Desktop
 
-**One-line install:**
-```bash
-curl -fsSL https://raw.githubusercontent.com/gaiaaiagent/regen-koi-mcp/main/install.sh | bash
-```
+**Recommended: Manual configuration**
+
+Add to your config file:
+- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux:** `~/.config/Claude/claude_desktop_config.json`
 
-Or manually add to config (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac, `~/.config/Claude/claude_desktop_config.json` on Linux):
 ```json
 {
   "mcpServers": {
     "regen-koi": {
       "command": "npx",
-      "args": ["-y", "regen-koi-mcp@latest"],
+      "args": ["regen-koi-mcp@latest"],
       "env": {
         "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
       }
@@ -414,29 +483,34 @@ Or manually add to config (`~/Library/Application Support/Claude/claude_desktop_
 }
 ```
 
----
+**Alternative: Automated installer**
 
-### Claude Code CLI
+⚠️ **Security Note:** Review the [install script](https://raw.githubusercontent.com/gaiaaiagent/regen-koi-mcp/main/install.sh) before running.
 
-**Option 1: Use the automated installer (recommended)**
 ```bash
 curl -fsSL https://raw.githubusercontent.com/gaiaaiagent/regen-koi-mcp/main/install.sh | bash
 ```
-This configures both Claude Desktop and Claude Code CLI with the correct environment variables.
 
-**Option 2: Manual installation**
-1. Add the MCP server:
+---
+
+### Claude Code CLI
+
+**Recommended: One-line command**
 ```bash
-claude mcp add regen-koi npx -y regen-koi-mcp@latest
+claude mcp add regen-koi npx regen-koi-mcp@latest
 ```
 
-2. Configure the environment variable in your Claude Code settings file (`~/.claude/settings.json` or similar):
+Then manually add the environment variable to your Claude Code settings file:
+
+**Mac/Linux:** `~/.config/claude/claude_code_config.json`
+**Windows:** `%APPDATA%\claude\claude_code_config.json`
+
 ```json
 {
   "mcpServers": {
     "regen-koi": {
       "command": "npx",
-      "args": ["-y", "regen-koi-mcp@latest"],
+      "args": ["regen-koi-mcp@latest"],
       "env": {
         "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
       }
@@ -445,22 +519,38 @@ claude mcp add regen-koi npx -y regen-koi-mcp@latest
 }
 ```
 
+**Alternative: Use the automated installer**
+
+⚠️ **Security Note:** Review the [install script](https://raw.githubusercontent.com/gaiaaiagent/regen-koi-mcp/main/install.sh) before running.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/gaiaaiagent/regen-koi-mcp/main/install.sh | bash
+```
+
+This configures both Claude Desktop and Claude Code CLI with the correct environment variables.
+
 **Verification:** After installation, restart Claude Code and ask: "What repositories are indexed?" to verify the tools are working.
 
 ---
 
 ### VS Code / VS Code Insiders
 
-**One-line install:**
+**Recommended: CLI command**
+
+For VS Code:
 ```bash
-code --add-mcp '{"name":"regen-koi","command":"npx","args":["-y","regen-koi-mcp@latest"],"env":{"KOI_API_ENDPOINT":"https://regen.gaiaai.xyz/api/koi"}}'
+code --add-mcp '{"name":"regen-koi","command":"npx","args":["regen-koi-mcp@latest"],"env":{"KOI_API_ENDPOINT":"https://regen.gaiaai.xyz/api/koi"}}'
 ```
 
-Or for VS Code Insiders:
+For VS Code Insiders:
 ```bash
-code-insiders --add-mcp '{"name":"regen-koi","command":"npx","args":["-y","regen-koi-mcp@latest"],"env":{"KOI_API_ENDPOINT":"https://regen.gaiaai.xyz/api/koi"}}'
+code-insiders --add-mcp '{"name":"regen-koi","command":"npx","args":["regen-koi-mcp@latest"],"env":{"KOI_API_ENDPOINT":"https://regen.gaiaai.xyz/api/koi"}}'
 ```
 
+**Alternative: Manual configuration**
+
+Add to your VS Code MCP settings with the command, args, and env values shown above.
+
 ---
 
 ### Cursor
@@ -472,7 +562,7 @@ code-insiders --add-mcp '{"name":"regen-koi","command":"npx","args":["-y","regen
 4. Enter:
    - Name: `regen-koi`
    - Command: `npx`
-   - Args: `-y regen-koi-mcp@latest`
+   - Args: `regen-koi-mcp@latest`
    - Env: `KOI_API_ENDPOINT=https://regen.gaiaai.xyz/api/koi`
 
 ---
@@ -485,7 +575,7 @@ Add to your Windsurf MCP config:
   "mcpServers": {
     "regen-koi": {
       "command": "npx",
-      "args": ["-y", "regen-koi-mcp@latest"],
+      "args": ["regen-koi-mcp@latest"],
       "env": {
         "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
       }
@@ -504,7 +594,7 @@ Install [Cline from VS Code Marketplace](https://marketplace.visualstudio.com/it
   "mcpServers": {
     "regen-koi": {
       "command": "npx",
-      "args": ["-y", "regen-koi-mcp@latest"],
+      "args": ["regen-koi-mcp@latest"],
       "env": {
         "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
       }
@@ -523,7 +613,7 @@ Install [Continue from VS Code Marketplace](https://marketplace.visualstudio.com
   "mcpServers": {
     "regen-koi": {
       "command": "npx",
-      "args": ["-y", "regen-koi-mcp@latest"],
+      "args": ["regen-koi-mcp@latest"],
       "env": {
         "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
       }
@@ -541,61 +631,77 @@ Install [Continue from VS Code Marketplace](https://marketplace.visualstudio.com
 2. Go to Extensions
 3. Add MCP server with:
    - Command: `npx`
-   - Args: `-y regen-koi-mcp@latest`
+   - Args: `regen-koi-mcp@latest`
    - Env: `KOI_API_ENDPOINT=https://regen.gaiaai.xyz/api/koi`
 
 ---
 
 ### Warp
 
-**Via Settings:**
-1. Open Settings → AI → Manage MCP Servers
-2. Add new server
-
-Or use slash command:
+**Recommended: Slash command**
 ```bash
 /add-mcp regen-koi npx -y regen-koi-mcp@latest
 ```
 
+Then add the environment variable `KOI_API_ENDPOINT=https://regen.gaiaai.xyz/api/koi` in the server settings.
+
+**Alternative: Manual configuration via Settings**
+1. Open Settings → AI → Manage MCP Servers
+2. Add new server
+3. Configure:
+   - Command: `npx`
+   - Args: `regen-koi-mcp@latest`
+   - Env: `KOI_API_ENDPOINT=https://regen.gaiaai.xyz/api/koi`
+
 ---
 
 ### Amp
 
-**One-line install:**
+**Recommended: One-line command**
 ```bash
 amp mcp add regen-koi -- npx -y regen-koi-mcp@latest
 ```
 
+Then manually add the environment variable `KOI_API_ENDPOINT=https://regen.gaiaai.xyz/api/koi` to the server configuration.
+
 ---
 
 ### Factory
 
-**One-line install:**
+**Recommended: One-line command**
 ```bash
 droid mcp add regen-koi "npx -y regen-koi-mcp@latest"
 ```
 
-Or use interactive UI with `/mcp` command.
+Then manually add the environment variable `KOI_API_ENDPOINT=https://regen.gaiaai.xyz/api/koi` to the server configuration.
+
+**Alternative: Interactive UI**
+
+Use the `/mcp` command in Factory to add the server interactively.
 
 ---
 
 ### Codex
 
-**One-line install:**
+**Recommended: One-line command**
 ```bash
 codex mcp add regen-koi npx "-y regen-koi-mcp@latest"
 ```
 
-Or manually edit `~/.codex/config.toml`:
+Then manually add the environment variable to `~/.codex/config.toml`:
 ```toml
 [[mcp.servers]]
 name = "regen-koi"
 command = "npx"
-args = ["-y", "regen-koi-mcp@latest"]
+args = ["regen-koi-mcp@latest"]
 [mcp.servers.env]
 KOI_API_ENDPOINT = "https://regen.gaiaai.xyz/api/koi"
 ```
 
+**Alternative: Manual configuration**
+
+Edit `~/.codex/config.toml` directly with the complete config above.
+
 ---
 
 ### Opencode
@@ -606,7 +712,7 @@ Add to `~/.config/opencode/opencode.json`:
   "mcpServers": {
     "regen-koi": {
       "command": "npx",
-      "args": ["-y", "regen-koi-mcp@latest"],
+      "args": ["regen-koi-mcp@latest"],
       "env": {
         "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
       }
@@ -625,7 +731,7 @@ Add to `.kiro/settings/mcp.json`:
   "mcpServers": {
     "regen-koi": {
       "command": "npx",
-      "args": ["-y", "regen-koi-mcp@latest"],
+      "args": ["regen-koi-mcp@latest"],
       "env": {
         "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
       }
@@ -641,7 +747,7 @@ Add to `.kiro/settings/mcp.json`:
 **Via Settings:**
 1. Open Program sidebar
 2. Go to MCP configuration
-3. Add server with npx command: `npx -y regen-koi-mcp@latest`
+3. Add server with npx command: `npx regen-koi-mcp@latest`
 
 ---
 
@@ -652,7 +758,7 @@ Add to `.kiro/settings/mcp.json`:
 2. Click "Connect more tools"
 3. Add MCP server:
    - Command: `npx`
-   - Args: `-y regen-koi-mcp@latest`
+   - Args: `regen-koi-mcp@latest`
    - Env: `KOI_API_ENDPOINT=https://regen.gaiaai.xyz/api/koi`
 
 ---
@@ -665,7 +771,7 @@ Add to Gemini CLI MCP config:
   "mcpServers": {
     "regen-koi": {
       "command": "npx",
-      "args": ["-y", "regen-koi-mcp@latest"],
+      "args": ["regen-koi-mcp@latest"],
       "env": {
         "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
       }
@@ -683,7 +789,7 @@ Any MCP-compatible client can use this server with:
 ```json
 {
   "command": "npx",
-  "args": ["-y", "regen-koi-mcp@latest"],
+  "args": ["regen-koi-mcp@latest"],
   "env": {
     "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
   }
@@ -762,7 +868,7 @@ curl -s http://localhost:8301/api/koi/query \
   }' | jq '.results[0:3]'
 ```
 
-Within MCP, the `search_knowledge` tool accepts:
+Within MCP, the `search` tool accepts:
 
 - `published_from` / `published_to` (YYYY-MM-DD)
 - `include_undated` (boolean)

package/dist/auth-store.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Auth State Persistence
+ *
+ * Stores authentication state to .koi-auth.json to enable
+ * the "One Tool, Two Calls" pattern (no polling loop).
+ *
+ * State Flow:
+ * 1. No state -> Request device code, save to file
+ * 2. Has device_code -> Check status with server
+ * 3. Has access_token -> Already authenticated
+ */
+export interface AuthState {
+    deviceCode?: string;
+    userCode?: string;
+    verificationUri?: string;
+    deviceCodeExpiresAt?: number;
+    accessToken?: string;
+    accessTokenExpiresAt?: number;
+    userEmail?: string;
+}
+/**
+ * Load auth state from disk.
+ * Returns empty object if file doesn't exist or is invalid.
+ */
+export declare function loadAuthState(): AuthState;
+/**
+ * Save auth state to disk with secure file permissions.
+ * File is set to 0o600 (owner read/write only) for security on shared machines.
+ */
+export declare function saveAuthState(state: AuthState): void;
+/**
+ * Clear auth state (logout).
+ */
+export declare function clearAuthState(): void;
+/**
+ * Check if access token is still valid.
+ */
+export declare function hasValidAccessToken(state: AuthState): boolean;
+/**
+ * Check if device code is still valid.
+ */
+export declare function hasValidDeviceCode(state: AuthState): boolean;
+/**
+ * Clear device code from state (after successful auth or expiry).
+ */
+export declare function clearDeviceCode(state: AuthState): AuthState;
+//# sourceMappingURL=auth-store.d.ts.map

package/dist/auth-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-store.d.ts","sourceRoot":"","sources":["../src/auth-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH,MAAM,WAAW,SAAS;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,SAAS,CAUzC;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CASpD;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAQrC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAK7D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAK5D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAG3D"}

package/dist/auth-store.js

@@ -0,0 +1,86 @@
+/**
+ * Auth State Persistence
+ *
+ * Stores authentication state to .koi-auth.json to enable
+ * the "One Tool, Two Calls" pattern (no polling loop).
+ *
+ * State Flow:
+ * 1. No state -> Request device code, save to file
+ * 2. Has device_code -> Check status with server
+ * 3. Has access_token -> Already authenticated
+ */
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+// Store auth state in user's home directory
+const AUTH_FILE = path.join(os.homedir(), '.koi-auth.json');
+/**
+ * Load auth state from disk.
+ * Returns empty object if file doesn't exist or is invalid.
+ */
+export function loadAuthState() {
+    try {
+        if (fs.existsSync(AUTH_FILE)) {
+            const data = fs.readFileSync(AUTH_FILE, 'utf8');
+            return JSON.parse(data);
+        }
+    }
+    catch (err) {
+        console.error('[Auth] Failed to load auth state:', err);
+    }
+    return {};
+}
+/**
+ * Save auth state to disk with secure file permissions.
+ * File is set to 0o600 (owner read/write only) for security on shared machines.
+ */
+export function saveAuthState(state) {
+    try {
+        fs.writeFileSync(AUTH_FILE, JSON.stringify(state, null, 2), {
+            encoding: 'utf8',
+            mode: 0o600 // Owner read/write only
+        });
+    }
+    catch (err) {
+        console.error('[Auth] Failed to save auth state:', err);
+    }
+}
+/**
+ * Clear auth state (logout).
+ */
+export function clearAuthState() {
+    try {
+        if (fs.existsSync(AUTH_FILE)) {
+            fs.unlinkSync(AUTH_FILE);
+        }
+    }
+    catch (err) {
+        console.error('[Auth] Failed to clear auth state:', err);
+    }
+}
+/**
+ * Check if access token is still valid.
+ */
+export function hasValidAccessToken(state) {
+    if (!state.accessToken || !state.accessTokenExpiresAt) {
+        return false;
+    }
+    return Date.now() < state.accessTokenExpiresAt;
+}
+/**
+ * Check if device code is still valid.
+ */
+export function hasValidDeviceCode(state) {
+    if (!state.deviceCode || !state.deviceCodeExpiresAt) {
+        return false;
+    }
+    return Date.now() < state.deviceCodeExpiresAt;
+}
+/**
+ * Clear device code from state (after successful auth or expiry).
+ */
+export function clearDeviceCode(state) {
+    const { deviceCode, userCode, verificationUri, deviceCodeExpiresAt, ...rest } = state;
+    return rest;
+}
+//# sourceMappingURL=auth-store.js.map

package/dist/auth-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-store.js","sourceRoot":"","sources":["../src/auth-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,MAAM,IAAI,CAAC;AAEpB,4CAA4C;AAC5C,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,gBAAgB,CAAC,CAAC;AAY5D;;;GAGG;AACH,MAAM,UAAU,aAAa;IAC3B,IAAI,CAAC;QACH,IAAI,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YAChD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,mCAAmC,EAAE,GAAG,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAgB;IAC5C,IAAI,CAAC;QACH,EAAE,CAAC,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;YAC1D,QAAQ,EAAE,MAAM;YAChB,IAAI,EAAE,KAAK,CAAE,wBAAwB;SACtC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,mCAAmC,EAAE,GAAG,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc;IAC5B,IAAI,CAAC;QACH,IAAI,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7B,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,oCAAoC,EAAE,GAAG,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAgB;IAClD,IAAI,CAAC,KAAK,CAAC,WAAW,IAAI,CAAC,KAAK,CAAC,oBAAoB,EAAE,CAAC;QACtD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,oBAAoB,CAAC;AACjD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAgB;IACjD,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,KAAK,CAAC,mBAAmB,EAAE,CAAC;QACpD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,mBAAmB,CAAC;AAChD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAAgB;IAC9C,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,eAAe,EAAE,mBAAmB,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC;IACtF,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/auth.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Authentication Module
+ * Manages session tokens for authenticated API calls
+ *
+ * SECURITY: This module stores session tokens (NOT Google OAuth tokens).
+ * Session tokens are generated by our server and only work with our API.
+ * They are safe to store locally - even if leaked, they can't be used
+ * to access Google APIs or impersonate the user elsewhere.
+ */
+export declare const USER_EMAIL: string;
+/**
+ * Get the current session token (if any)
+ * Returns null if no token is stored or if expired
+ */
+export declare function getSessionToken(): string | null;
+export declare const getAccessToken: typeof getSessionToken;
+/**
+ * Store session token after successful OAuth
+ * @param token - The session token from our server (NOT Google OAuth token)
+ * @param expiresAt - Expiry timestamp
+ */
+export declare function setSessionToken(token: string, expiresAt?: number): void;
+export declare const setAccessToken: typeof setSessionToken;
+/**
+ * Clear session token (called when token is invalid or on logout)
+ */
+export declare function clearAuthCache(): void;
+/**
+ * Check if we have a valid session token
+ */
+export declare function hasSessionToken(): boolean;
+export declare const hasAccessToken: typeof hasSessionToken;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuBH,eAAO,MAAM,UAAU,QAAuB,CAAC;AAc/C;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAS/C;AAGD,eAAO,MAAM,cAAc,wBAAkB,CAAC;AAE9C;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAQvE;AAGD,eAAO,MAAM,cAAc,wBAAkB,CAAC;AAE9C;;GAEG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAKrC;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAGD,eAAO,MAAM,cAAc,wBAAkB,CAAC"}