@iwas/mcp 1.0.0 → 1.0.2

package/README.md

@@ -1,135 +1,406 @@
 # @iwas/mcp
 
-Intelligent WiFi Access & Presence Service (IWAS) Model Context Protocol (MCP) workspace package.
-
-> **Status: Standalone Distribution Package.** This package is bundled via `tsup` into a self-contained
-> binary (`dist/bin.js`) with zero monorepo dependencies, published to the NPM Registry under
-> `@iwas/mcp`. It exposes the `iwas` (and `iwas-mcp`) CLI supporting RFC 8628 Device Authorization,
-> native OS Keychain storage, and tool catalog definitions.
-
-## Subpath Exports
-
-- `@iwas/mcp` — root entrypoint (version plus re-exports).
-- `@iwas/mcp/catalog` — re-exports the single permission vocabulary from `@iwas/auth/permissions`
-  (FR-011). The MCP capability census is generated by the API drift gate (INV-MCP-14) and is
-  deliberately not pinned here.
-- `@iwas/mcp/client` — programmatic MCP client interfaces.
-- `@iwas/mcp/auth` — MCP credential vault (`CredentialVault`), OS Keychain integration (`KeychainService`), profile normalization, and token redaction helpers (DEV-08).
-
-## Credential Vault & Storage Security
-
-`@iwas/mcp/auth` provides secure credential storage for RFC 8628 Device Flow:
-
-- **Keychain Backend (Default on macOS & Linux):**
-  - **Service:** `iwas-cli` (default)
-  - **Account:** Profile key in canonical format `<origin>::<clientId>` (e.g. `https://getiwas.com::iwas-cli`).
-  - macOS: Uses `/usr/bin/security` (`add-generic-password -U`, `find-generic-password -w`, `delete-generic-password`).
-  - Linux: Uses `secret-tool` (`store`, `lookup`, `clear`) with secrets passed strictly via `stdin` (never exposed in `argv` or `ps`).
-- **Manual Verification on macOS:**
-  ```bash
-  # Check stored secret in macOS Keychain:
-  security find-generic-password -s iwas-cli -a "https://getiwas.com::iwas-cli" -w
-  ```
-- **File Fallback (`~/.config/iwas/credentials.json`):**
-  - Active in headless CI, Docker containers, and on Windows (`%USERPROFILE%\.config\iwas\credentials.json`).
-  - Respects `$XDG_CONFIG_HOME/iwas/credentials.json`.
-  - Enforces strict POSIX permissions: directory `0700` (`rwx------`), file `0600` (`rw-------`).
-  - Atomic write strategy: writes to temporary file, syncs to disk (`fsync`), and renames atomically.
-  - Protects corrupt files: if the JSON is malformed or missing fields, the vault fails closed and refuses to overwrite.
-- **Security Considerations & Trade-offs:**
-  > [!WARNING]
-  > The file fallback stores serialized credentials in plaintext JSON protected only by OS file permissions (`0600`). On systems where native OS keychain utilities are available, the keychain backend is strongly preferred.
-  > On macOS workstations, `/usr/bin/security` accepts `-w <secret>` via arguments which is transiently visible in the process table `ps` to local processes running under the same user UID.
-- **Conflict Resolution & Precedence:**
-  - Credentials include an internal `updatedAt` timestamp (`Date.now()`). When operating in `auto` mode with both keychain and file present, the vault compares timestamps (`updatedAt ?? expiresAt`) and automatically migrates newer file credentials into the keychain while purging stale copies (resolving split-backend desync).
-- **Environment Override:**
-  - Set `IWAS_MCP_VAULT=auto` (default: keychain if available, fallback to file).
-  - Set `IWAS_MCP_VAULT=keychain` (strict keychain; throws if unavailable or locked).
-  - Set `IWAS_MCP_VAULT=file` (forces file storage; useful for headless CI).
-  - Set `IWAS_MCP_REAL_KEYCHAIN=1` (opt-in to execute real host macOS Keychain tests).
-
-## Local CLI
-
-Executable binary is `iwas` (with `iwas-mcp` provided as a backward-compatible alias):
+# IWAS MCP server
+
+[`@iwas/mcp`](https://www.npmjs.com/package/@iwas/mcp) is the official MCP server for [IWAS](https://getiwas.com) — the enterprise WiFi billing, captive portal, FreeRADIUS control, and network presence intelligence platform.
+
+It operates over **stdio** as a secure bridge: it signs in via OAuth 2.0 Device Authorization (RFC 8628), persists credentials to native OS Keychains, transparently rotates expired tokens behind a cross-process lock (`VaultLock`), and proxies MCP tool calls to the IWAS API with authorized Bearer tokens.
+
+[![npm version](https://img.shields.io/npm/v/@iwas/mcp.svg)](https://www.npmjs.com/package/@iwas/mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node: 18+](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)
+
+> 💡 **Dual-Transport Architecture:** Every IWAS API deployment also exposes a native Streamable HTTP MCP endpoint at `/mcp` (e.g. `https://getiwas.com/mcp` or `http://localhost:3001/mcp`) supporting RFC 9728 Protected Resource Metadata and RFC 9449 DPoP proofs. If your client supports direct Streamable HTTP (such as cloud agents or webhooks), you can connect directly. For desktop AI IDEs that communicate over stdio, use this `@iwas/mcp` bridge.
+
+---
+
+## Highlights
+
+- 🚀 **Zero Setup**: Run instantly via `npx -y @iwas/mcp` without cloning the repository or pre-installing dependencies.
+- 🔐 **RFC 8628 Device Authorization**: Browser-based interactive login supporting Passkeys (Touch ID/Face ID), Google OAuth, and 2FA.
+- 🛡️ **Native OS Keychain Security**: Stores tokens directly in **Apple Keychain Services** (macOS) and **Secret Service** (Linux), with atomic POSIX `0600` file fallback.
+- 🔄 **Silent Token Rotation**: Seamless background refresh before expiration (`TokenRefreshManager`) and automatic recovery on HTTP 401.
+- 🔒 **Concurrency-Safe (`VaultLock`)**: Cross-process file locking ensures multiple IDE windows or concurrent subagents never corrupt token families.
+- 🤖 **Plug-and-Play AI Assistant Support**: Instant integration for Claude Desktop, Cursor, Antigravity IDE, Windsurf, and VS Code (Cline / Roo Code).
+- 📦 **Dual Executable**: Provides both `iwas` and backward-compatible `iwas-mcp` CLI commands.
+
+---
+
+## Prerequisites
+
+- **Node.js 18+** (Node.js 20+ recommended)
+- An accessible IWAS API instance (defaults to production `https://getiwas.com`, or local development `http://localhost:3001`).
+
+---
+
+## Quickstart
+
+### 1. Authenticate Workstation
+
+Run the login command once to authenticate your machine via OAuth 2.0 Device Flow:
 
 ```bash
-# Display help & version
-iwas --help
-iwas --version
+# Interactive login (automatically opens browser)
+npx -y @iwas/mcp login
+
+# Connect to a self-hosted or local development instance
+npx -y @iwas/mcp login --server http://localhost:3001
+
+# Headless / remote server login (prints verification URL & user code)
+npx -y @iwas/mcp login --no-browser
+```
+
+### 2. Verify Session Status
+
+Inspect your active profile and token remaining duration:
+
+```bash
+# Check default production profile (https://getiwas.com)
+npx -y @iwas/mcp status
+
+# Check a specific server or local development instance
+npx -y @iwas/mcp status --server http://localhost:3001
+```
+
+_Example Output:_
+
+```text
+============================================================
+                   IWAS MCP Auth Status
+============================================================
+
+- Profile:       https://getiwas.com::iwas-cli
+- Server:        https://getiwas.com
+- Client ID:     iwas-cli
+- Status:        🟢 Active
+- Organization:  org_123 (or platform scope)
+- Resource:      https://getiwas.com/mcp
+- Expires:       2026-10-19T10:43:18.314Z (48m 51s remaining)
+```
+
+---
+
+## Integrating with AI Assistants
+
+Wire IWAS tools into your AI coding assistant using standard MCP configuration.
+
+> ⚠️ **Important:** Ensure you have completed `npx -y @iwas/mcp login` once before launching your MCP client.
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`  
+On Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "iwas": {
+      "command": "npx",
+      "args": ["-y", "@iwas/mcp", "mcp"],
+      "env": {
+        "IWAS_SERVER_URL": "https://getiwas.com"
+      }
+    }
+  }
+}
+```
+
+### Cursor (`.cursor/mcp.json` or Global Features > MCP)
+
+```json
+{
+  "mcpServers": {
+    "iwas": {
+      "command": "npx",
+      "args": ["-y", "@iwas/mcp", "mcp"],
+      "env": {
+        "IWAS_SERVER_URL": "https://getiwas.com"
+      }
+    }
+  }
+}
+```
+
+### Antigravity IDE (`mcp_config.json`)
+
+In `~/.gemini/config/mcp_config.json` or `.agents/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "iwas": {
+      "command": "npx",
+      "args": ["-y", "@iwas/mcp", "mcp"],
+      "env": {
+        "IWAS_SERVER_URL": "https://getiwas.com"
+      }
+    }
+  }
+}
+```
+
+### VS Code (Cline / Roo Code)
+
+In Cline MCP settings (`cline_mcp_settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "iwas": {
+      "command": "npx",
+      "args": ["-y", "@iwas/mcp", "mcp"],
+      "env": {
+        "IWAS_SERVER_URL": "https://getiwas.com"
+      }
+    }
+  }
+}
+```
+
+> 💡 **Local Development:** When pairing against a local NestJS backend, set `"IWAS_SERVER_URL": "http://localhost:3001"`.
+
+---
+
+## Environment Variables
+
+| Variable          | Default               | Description                                                                                                                                 |
+| :---------------- | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
+| `IWAS_SERVER_URL` | `https://getiwas.com` | Base origin of the IWAS API & Auth server (e.g. `http://localhost:3001` for local dev).                                                     |
+| `IWAS_MCP_VAULT`  | `auto`                | Credential storage mode: `auto` (OS Keychain with file fallback), `keychain` (strict OS Keychain only), or `file` (strict POSIX file only). |
+| `XDG_CONFIG_HOME` | `~/.config`           | Custom base directory for credentials file fallback (`$XDG_CONFIG_HOME/iwas/credentials.json`).                                             |
+
+_Note: Custom OAuth Client IDs and Resource endpoints can be configured via `--client-id <id>` and `--resource <url>` CLI options._
+
+---
+
+## CLI Reference
+
+The package provides two identical executable binaries: `iwas` and `iwas-mcp`.
+
+```text
+USAGE:
+  iwas <command> [options]
+  iwas-mcp <command> [options]
+
+COMMANDS:
+  login     Authenticate using OAuth 2.0 Device Authorization Grant (RFC 8628)
+  status    Display current authentication status for a server profile
+  logout    Remove stored credentials for a server profile
+  mcp       Run a stdio MCP bridge using the stored device-flow credentials
+  help      Display help information
+```
+
+### `iwas login`
 
-# Log in using OAuth 2.0 Device Authorization Grant (RFC 8628)
+Initiate an OAuth 2.0 Device Authorization Grant flow:
+
+```bash
+# Standard browser login
 iwas login
-iwas login --server https://getiwas.com --no-browser
-iwas login --scopes "analytics:read session:read offline_access" --json
 
-# Inspect active authentication status for a server profile
+# Specify target server
+iwas login --server http://localhost:3001
+
+# Headless / remote SSH session (no browser)
+iwas login --no-browser
+
+# Custom least-privilege OAuth scopes
+iwas login --scopes "analytics:read session:read offline_access"
+
+# Machine-readable JSON output for automated scripting
+iwas login --json
+```
+
+### `iwas status`
+
+Display authentication status, active profile, and human-readable expiration countdown:
+
+```bash
+# Check default profile
 iwas status
-iwas status --server https://getiwas.com --json
 
-# Log out and remove credentials from vault & keychain
+# Check status for a specific server instance
+iwas status --server http://localhost:3001
+
+# Machine-readable JSON output
+iwas status --json
+```
+
+### `iwas logout`
+
+Revoke active session grants on the server (RFC 7009) and purge stored credentials from the local vault:
+
+```bash
+# Logout from default server
 iwas logout
-iwas logout --server https://getiwas.com --json
+
+# Logout from a specific server instance
+iwas logout --server http://localhost:3001
+
+# Force local cleanup even if the authentication server is unreachable
+iwas logout --force
+```
+
+### `iwas mcp`
+
+Launch the stdio-to-HTTP MCP bridge used by AI coding assistants. Reads tokens automatically from native OS Keychain and routes JSON-RPC frames:
+
+```bash
+iwas mcp
+iwas mcp --server http://localhost:3001
 ```
 
-Auth server origin can also be set via the `IWAS_SERVER_URL` environment variable.
+_Note: The `mcp` command strictly reserves stdout for JSON-RPC frames; passing `--json` will error._
+
+---
+
+## 🛠️ Complete MCP Capabilities Catalog (26 Tools + 2 Prompts)
+
+### 1. Analytics & Revenue Intelligence
 
-### OAuth Scopes & Least-Privilege Defaults
+| Tool | Description |
+| :--- | :--- |
+| `get_dashboard_stats` | Real-time network telemetry, active WiFi guests, revenue today, and router connectivity. Aligned with `/api/admin/stats`. |
+| `get_revenue_breakdown` | Granular revenue breakdown by time period, package tier, venue, and payment provider. Aligned with `/api/admin/revenue`. |
+| `list_packages` | Paginated listing of hotspot billing packages, duration, bandwidth limits, and pricing. |
+| `get_package` | Retrieve full configuration and tax category for a specific package ID. |
 
-Default scopes requested during `iwas login` follow **strict least-privilege**: only read-only capabilities (`*:read`) plus `offline_access` are requested. Mutating or administrative actions (such as `:manage`, `:delete`, `:control`, `:issue`, `:write`) require explicitly passing the required permissions via `--scopes`.
+### 2. Sessions & FreeRADIUS Accounting
 
-> [!NOTE]
-> Platform-only read scopes (such as `diagnostics:read`) are included in `DEFAULT_READ_ONLY_SCOPES` for platform administrators, while tenant callers have access strictly evaluated and gated by the server's RBAC engine at execution time.
+| Tool | Description |
+| :--- | :--- |
+| `list_active_sessions` | Inspect currently connected captive portal and hotspot guest sessions. |
+| `list_today_sessions` | Query all guest sessions recorded for the current day with `revenueToday` summary. |
+| `get_session_accounting` | Granular byte count, duration, and FreeRADIUS RFC 2866 accounting usage per session ID. |
 
-### Machine-Readable JSON Mode (`--json`)
+### 3. Business Insights & Optimization
 
-When `--json` is passed, machine consumers receive newline-delimited JSON events on `stdout`:
+| Tool | Description |
+| :--- | :--- |
+| `summarize_package_performance` | Statistical duration, ARPU, and conversion metrics across billing plans (default 7-day lookback). |
+| `suggest_promo_windows` | AI-driven revenue timing analysis to identify optimal discount and marketing windows. |
 
-1. **Authorization initiated (`device_authorization` event):** Emitted immediately after obtaining the device code, providing headless runners and IDE extensions with the verification details without waiting for token approval:
-   ```json
-   {"event":"device_authorization","user_code":"WDJB-MJHT","verification_uri":"https://getiwas.com/device","verification_uri_complete":"https://getiwas.com/device?user_code=WDJB-MJHT","expires_in":600,"interval":5}
-   ```
-   *Security:* per RFC 8628 §3.2, `device_code` is strictly kept internal to the CLI and never included in this payload.
+### 4. Diagnostics & Network Observability
 
-2. **Authorization completed (`login_success` event):**
-   ```json
-   {"event":"login_success","success":true,"profileKey":"https://getiwas.com::iwas-cli","serverUrl":"https://getiwas.com","clientId":"iwas-cli","organizationId":"org_123","scope":"...","resource":"...","expiresAt":1792376265000}
-   ```
+| Tool | Description |
+| :--- | :--- |
+| `read_service_health` | Real-time liveness, readiness, and database connectivity checks. Valid authentication required. |
+| `get_mcp_span` | Retrieve end-to-end execution span telemetry for an MCP request by `requestId` or numeric ID. |
+| `get_error_by_request_id` _(Platform Staff)_ | Deep diagnostic trace and error detail for a specific failed `requestId`. |
+| `list_error_events` _(Platform Staff)_ | Fetch recent unhandled exceptions, paths, and sanitized stack traces. |
+| `list_flow_events` _(Platform Staff)_ | Interactive multi-stage journey lifecycle traces (OAuth, login, checkout). |
+| `list_issues` _(Platform Staff)_ | Recurring incident clusters, severity badges, and automated triage statuses. |
+| `update_issue_status` _(Platform Staff)_ | Update diagnostic issue triage state (`open`, `investigating`, `resolved`, `ignored`). |
+| `list_audit_logs` | Query tamper-evident administrative action history. |
+| `query_system_logs` _(Platform Staff)_ | Execute structured queries against system JSONL infrastructure logs. |
 
-3. **Error event:**
-   ```json
-   {"event":"error","error":"Invalid OAuth client: client not found"}
-   ```
+### 5. Captive Portal Content & Announcements
 
-*Stream Isolation:* In `--json` mode, `stdout` is strictly reserved for structured JSON events. Human-readable interactive prompts, code highlights, and browser warnings are routed to `stderr`.
+| Tool | Description |
+| :--- | :--- |
+| `blog_list_posts` | List captive portal venue announcements, promotions, and articles with filters. |
+| `blog_get_post` | Retrieve full content and metadata of a specific portal post by ID or slug. |
+| `blog_create_post` | Author a new captive portal announcement with Markdown, SEO tags, and translation pairing. |
+| `blog_update_post` | Update title, content, published status, or cover image. |
+| `blog_delete_post` | Soft-delete an obsolete portal announcement. |
+| `blog_import_media` | Download an external image from a public URL and store it in IWAS media CDN storage. |
+| `blog_request_upload_url` | Request a presigned URL for direct client-side media uploads. |
+| `blog_upload_media_base64` | Direct Base64 media asset upload (max 10MB decoded) for portal banners. |
 
-## Automatic Token Refresh & Concurrency Control (DEV-10)
+### 6. MCP Prompts (Pre-Configured Workflows)
 
-`@iwas/mcp` provides automatic, transparent token refresh and concurrency-safe credential management:
+| Prompt | Description | Parameters |
+| :--- | :--- | :--- |
+| `morning_revenue_digest` | Multi-step workflow to analyze 24-hour financial metrics, peak hours, and underperforming billing packages. | `lookbackDays` (1..30, optional) |
+| `investigate_api_failure` | Diagnostic workflow to trace an error by `requestId`, inspect span telemetry, and correlate recurring issues. | `requestId` (string, optional) |
+
+---
+
+## Security & Credential Storage
+
+`@iwas/mcp` applies defense-in-depth principles to protect developer credentials:
+
+1. **Native OS Keychains**:
+   - **macOS**: Stored securely in **Apple Keychain Services** under service name `iwas-cli` with account key `<serverUrl>::<clientId>`.
+   - **Linux**: Stored via standard **Secret Service API / libsecret**.
+2. **Hardened File Fallback**:
+   - On headless environments, Docker containers, or Windows, credentials fall back to `~/.config/iwas/credentials.json` with strict POSIX `0700` directory and `0600` file permissions.
+3. **Cross-Process Concurrency (`VaultLock`)**:
+   - Acquires an atomic file lock (`~/.config/iwas/credentials.lock`) during token refresh. Prevents race conditions and token family invalidation when multiple IDE windows or subagents make concurrent requests.
+4. **Zero Token Leakage**:
+   - Tokens and secrets are automatically redacted from stdout, stderr, logs, and error traces.
+
+---
+
+## Troubleshooting
+
+### 1. `No IWAS credentials for profile "..."`
+
+- **Cause:** The machine has not been authenticated yet.
+- **Solution:** Run `npx -y @iwas/mcp login` (or `npx -y @iwas/mcp login --server http://localhost:3001` for local development).
+
+### 2. `fetch failed: connection closed` or `ECONNREFUSED`
+
+- **Cause:** The IWAS backend server specified by `IWAS_SERVER_URL` is offline or unreachable.
+- **Solution:** Verify the API server is running (e.g. `pnpm dev:api` on `http://localhost:3001`) or check internet connectivity to `https://getiwas.com`.
+
+### 3. macOS Keychain Permission Prompt
+
+- **Cause:** macOS prompts once when a new Node.js binary accesses Keychain Services items created under `iwas-cli`.
+- **Solution:** Click **"Always Allow"** in the macOS dialog. Alternatively, set `IWAS_MCP_VAULT=file` in your environment to use file-based storage.
+
+### 4. `The mcp command reserves stdout for MCP frames; --json is not supported`
+
+- **Cause:** Passing `--json` to `iwas mcp`.
+- **Solution:** The MCP stdio protocol requires raw JSON-RPC on stdout. Do not pass `--json` to the `mcp` command.
+
+---
+
+## Programmatic TypeScript SDK Usage
+
+`@iwas/mcp` exports programmatic primitives for custom agent developers:
+
+```bash
+pnpm add @iwas/mcp
+```
 
 ```typescript
-import { CredentialVault, TokenRefreshManager } from '@iwas/mcp/auth';
+import { CredentialVault, TokenRefreshManager } from '@iwas/mcp/auth'
 
-const vault = new CredentialVault();
-const refreshManager = new TokenRefreshManager({ vault });
+const vault = new CredentialVault()
+const refreshManager = new TokenRefreshManager({ vault })
 
-// Automatically returns a valid access token, refreshing if within safety margin (60s)
-const accessToken = await refreshManager.getValidAccessToken('https://getiwas.com::iwas-cli');
+// Automatically retrieves a valid token, refreshing via OAuth family rotation if near expiration:
+const credentials = await refreshManager.getValidCredentials('https://getiwas.com::iwas-cli')
+console.log('Access token:', credentials.accessToken)
 ```
 
-### Concurrency Guarantees
-- **In-process Single-flight:** Multiple concurrent asynchronous calls (both automatic and explicit force `refresh()`) for the same profile collapse to exactly one HTTP refresh request.
-- **Cross-process Mutual Exclusion (`VaultLock`):** Protects `<config-dir>/iwas/credentials.lock` via atomic `wx` creation (mode `0600`), dedicated app directory `0700` verification, and default 60s bounded timeout.
-- **Double-Checked Locking:** After acquiring the cross-process lock, the vault is re-read. If another concurrent process has already rotated the token family, the refreshed token is used immediately without issuing a redundant request.
-- **Active Process Immunity & Dead PID Reclaim (M1):** On the same host, a lock owned by a running process (`process.kill(pid, 0)`) is **never** reclaimed or stolen regardless of age, preventing token family destruction during slow network operations. Stale lock recovery occurs only when the holding PID is confirmed dead. *Cross-host/network FS tradeoff:* Across different machines or on shared network mounts (e.g. NFS/SMB), remote PIDs cannot be probed, so locks older than `staleTimeoutMs = 60s` are reclaimed based on lease age; configure a higher `staleTimeoutMs` for multi-host setups with operations exceeding 60s.
-- **TOCTOU-Safe Reclamation & Inode Verification:** Stale locks are verified via hardlink (`linkSync`) + `nlink` checks and inode matching before unlinking, ensuring racing processes acquiring new locks are never unlinked or overwritten. If the filesystem does not support hardlinks, reclamation fails closed (the caller times out) rather than risk deleting a live lock; remove the stale lock manually in that environment.
-- **Strictly Scoped Terminal Errors (M2):** ONLY `invalid_grant` (revoked/expired refresh token) and `invalid_client` purge local vault credentials and raise `ReauthenticationRequiredError`. Non-terminal 4xx errors (e.g. `invalid_request`, `invalid_scope`) throw sanitized errors while safely preserving credentials in the vault.
-- **Transient Retries & 30s Reuse Grace Window:** Network errors and 5xx server errors retry with bounded exponential backoff and never wipe stored credentials. Single retry on POST is protected by Better Auth's 30s refresh token reuse grace window (`MCP-OAUTH-04`).
-- **Atomic Persistence Failure Handling:** If saving rotated credentials to the vault fails, the profile is purged and raises `ReauthenticationRequiredError` ('persistence_failure') to avoid repeated replay of stale refresh tokens. Secret tokens are strictly redacted from diagnostic logs and error messages.
+### Subpath Exports:
+
+- `@iwas/mcp` — Core entrypoint and metadata.
+- `@iwas/mcp/auth` — `CredentialVault`, `TokenRefreshManager`, `VaultLock`, and Device Flow utilities.
+- `@iwas/mcp/catalog` — Typed permission vocabulary, tool schemas, and prompt definitions.
+- `@iwas/mcp/client` — MCP client transport and Streamable HTTP utilities.
 
-## Development
+---
+
+## Develop from Source
+
+From the monorepo root:
 
 ```bash
-pnpm --filter @iwas/mcp build          # emits dist/*.js and dist/*.d.ts
-pnpm --filter @iwas/mcp test           # compiles, then runs test suite
+# Build the package
+pnpm --filter @iwas/mcp build
+
+# Run unit and integration tests (126 tests)
+pnpm --filter @iwas/mcp test
+
+# Run type check
 pnpm --filter @iwas/mcp exec tsc --noEmit
 ```
+
+---
+
+## License
+
+MIT © [9xlayer](https://getiwas.com)

package/dist/auth/index.d.ts

@@ -395,6 +395,10 @@ declare function pollDeviceToken(serverUrl: string, params: {
  * Orchestrates the full login flow, saves credentials in vault, and formats output.
  */
 declare function executeLogin(options?: DeviceLoginOptions): Promise<DeviceLoginResult>;
+/**
+ * Formats a duration in seconds into human-readable units (e.g. "1d 2h 30m 15s", "52m 1s", or "45s").
+ */
+declare function formatRemainingDuration(totalSeconds: number): string;
 /**
  * Checks and outputs stored authentication status for the given profile.
  */
@@ -627,5 +631,5 @@ declare class TokenRefreshManager {
     private performTokenExchange;
 }
 
-export { CredentialVault, DEFAULT_CLI_CLIENT_ID, DEFAULT_KEYCHAIN_SERVICE, DEFAULT_READ_ONLY_SCOPES, DEFAULT_SCOPES, DEFAULT_SERVER_URL, DEVICE_CODE_GRANT_TYPE, DefaultKeychainRunner, HttpError, KeychainService, ReauthenticationRequiredError, TokenRefreshManager, VaultLock, VaultLockError, VaultLockTimeoutError, decodeJwtPayload, defaultIsProcessAlive, executeLogin, executeLogout, executeStatus, isCredentialExpired, isLocalhost, isValidStoredCredentials, normalizeProfileKey, openBrowser, pollDeviceToken, redactCredentials, requestDeviceCode, resolveAuthServerUrl, resolveMcpResourceUrl, sanitizeSecretString, sendRequest, validateScopes, withVaultLock };
+export { CredentialVault, DEFAULT_CLI_CLIENT_ID, DEFAULT_KEYCHAIN_SERVICE, DEFAULT_READ_ONLY_SCOPES, DEFAULT_SCOPES, DEFAULT_SERVER_URL, DEVICE_CODE_GRANT_TYPE, DefaultKeychainRunner, HttpError, KeychainService, ReauthenticationRequiredError, TokenRefreshManager, VaultLock, VaultLockError, VaultLockTimeoutError, decodeJwtPayload, defaultIsProcessAlive, executeLogin, executeLogout, executeStatus, formatRemainingDuration, isCredentialExpired, isLocalhost, isValidStoredCredentials, normalizeProfileKey, openBrowser, pollDeviceToken, redactCredentials, requestDeviceCode, resolveAuthServerUrl, resolveMcpResourceUrl, sanitizeSecretString, sendRequest, validateScopes, withVaultLock };
 export type { CredentialVaultOptions, DeviceAuthorizationResponse, DeviceLoginOptions, DeviceLoginResult, HttpResponse, KeychainCommandRunner, KeychainOptions, KeychainRunResult, LogoutOptions, LogoutResult, McpCredentials, OAuthTokenErrorResponse, OAuthTokenSuccessResponse, RequestOptions, SpawnFunction, StoredMcpCredentials, TokenRefreshManagerOptions, VaultBackendType, VaultLockData, VaultLockOptions };