@iwas/mcp 1.0.0 → 1.0.1

package/README.md

@@ -1,110 +1,148 @@
 # @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):
+> **Intelligent WiFi Access & Presence Service (IWAS) Model Context Protocol (MCP) CLI & SDK**
+
+Official command-line tool and developer SDK for connecting AI coding assistants (Claude Desktop, Cursor, Antigravity, Cline) and enterprise applications to the **IWAS** WiFi billing, captive portal, and network presence infrastructure.
+
+[![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)
+
+---
+
+## Highlights
+
+- 🚀 **Zero Setup**: Run instantly via `npx @iwas/mcp` without cloning or pre-installing dependencies.
+- 🔐 **RFC 8628 Device Authorization**: Secure, headless browser-based login with standard OAuth 2.0 device flow.
+- 🛡️ **Enterprise Credential Security**: Integrates with native OS Keychains (macOS Keychain, Linux Secret Service) with atomic, permissions-hardened file fallbacks.
+- 🤖 **Native AI Assistant Support**: Plug-and-play Model Context Protocol (MCP) server for Claude, Cursor, and custom agentic frameworks.
+- 📦 **Standalone Zero-Dependency Binary**: Self-contained runtime bundle engineered for maximum reliability.
+
+---
+
+## Quickstart
+
+### Run with `npx` (No installation needed)
 
 ```bash
-# Display help & version
-iwas --help
+# Log in via interactive browser
+npx @iwas/mcp login --browser
+
+# Check session & authentication status
+npx @iwas/mcp status
+```
+
+### Install Globally
+
+```bash
+npm install -g @iwas/mcp
+
+# Verify installation
 iwas --version
+iwas --help
+```
+
+*(Note: `iwas-mcp` is also provided as a backward-compatible command alias).*
+
+---
+
+## Integrating with AI Assistants
+
+You can wire IWAS tools directly into your favorite AI environments via standard MCP configuration:
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "iwas": {
+      "command": "npx",
+      "args": ["-y", "@iwas/mcp"]
+    }
+  }
+}
+```
+
+### Cursor / Cline / Antigravity
+
+Configure an MCP server with command `npx` and arguments `["-y", "@iwas/mcp"]`. The CLI will automatically use your stored credentials from `iwas login`.
 
-# Log in using OAuth 2.0 Device Authorization Grant (RFC 8628)
-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
+## CLI Commands
+
+### 1. `iwas login`
+Authenticate your workstation or development environment using OAuth 2.0 Device Flow:
+
+```bash
+# Interactive login with automatic browser opening
+iwas login --browser
+
+# Connect to a custom or self-hosted IWAS gateway
+iwas login --server https://getiwas.com --browser
+
+# Headless / remote server login (shows verification URL & code)
+iwas login --no-browser
+
+# Request custom scopes
+iwas login --scopes "analytics:read session:read offline_access"
+```
+
+### 2. `iwas status`
+Inspect the active authenticated profile, expiration status, and authorized scopes:
+
+```bash
 iwas status
-iwas status --server https://getiwas.com --json
 
-# Log out and remove credentials from vault & keychain
+# JSON output for automated scripting & CI/CD
+iwas status --json
+```
+
+### 3. `iwas logout`
+Revoke active session grants on the server and remove stored credentials from the local vault:
+
+```bash
 iwas logout
-iwas logout --server https://getiwas.com --json
+
+# Force local cleanup even if the authentication server is unreachable
+iwas logout --force
 ```
 
-Auth server origin can also be set via the `IWAS_SERVER_URL` environment variable.
+---
 
-### OAuth Scopes & Least-Privilege Defaults
+## Machine-Readable JSON Mode (`--json`)
 
-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`.
+When passed the `--json` flag, all commands output structured, newline-delimited JSON events to `stdout`, while human-readable prompts and notices are redirected to `stderr`.
 
-> [!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.
+**Example: Initiating device login**
+```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}
+```
 
-### Machine-Readable JSON Mode (`--json`)
+**Example: Successful login**
+```json
+{"event":"login_success","success":true,"profileKey":"https://getiwas.com::iwas-cli","serverUrl":"https://getiwas.com","clientId":"iwas-cli","organizationId":"org_123","scope":"...","expiresAt":1792376265000}
+```
 
-When `--json` is passed, machine consumers receive newline-delimited JSON events on `stdout`:
+---
 
-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.
+## TypeScript SDK & Programmatic Usage
 
-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}
-   ```
+`@iwas/mcp` provides first-class TypeScript library exports for building custom agents and administrative tools:
 
-3. **Error event:**
-   ```json
-   {"event":"error","error":"Invalid OAuth client: client not found"}
-   ```
+```bash
+pnpm add @iwas/mcp
+# or
+npm install @iwas/mcp
+```
 
-*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`.
+### Subpath Exports
 
-## Automatic Token Refresh & Concurrency Control (DEV-10)
+* `@iwas/mcp` — Core entrypoint and package metadata.
+* `@iwas/mcp/client` — Programmatic MCP client transport and client interfaces.
+* `@iwas/mcp/auth` — Credential vault (`CredentialVault`), Token refresh manager (`TokenRefreshManager`), and OS Keychain utilities.
+* `@iwas/mcp/catalog` — Typed permission vocabulary and tool definition catalog.
 
-`@iwas/mcp` provides automatic, transparent token refresh and concurrency-safe credential management:
+### Example: Automated Token Refresh in Node.js
 
 ```typescript
 import { CredentialVault, TokenRefreshManager } from '@iwas/mcp/auth';
@@ -112,24 +150,27 @@ import { CredentialVault, TokenRefreshManager } from '@iwas/mcp/auth';
 const vault = new CredentialVault();
 const refreshManager = new TokenRefreshManager({ vault });
 
-// Automatically returns a valid access token, refreshing if within safety margin (60s)
+// Automatically retrieves a valid token, refreshing via OAuth family rotation if near expiration
 const accessToken = await refreshManager.getValidAccessToken('https://getiwas.com::iwas-cli');
 ```
 
-### 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.
+---
 
-## Development
+## Credential Storage & Security
 
-```bash
-pnpm --filter @iwas/mcp build          # emits dist/*.js and dist/*.d.ts
-pnpm --filter @iwas/mcp test           # compiles, then runs test suite
-pnpm --filter @iwas/mcp exec tsc --noEmit
-```
+Credentials are protected using defense-in-depth:
+
+* **macOS**: Stored securely in the **macOS Keychain Services** under service `iwas-cli`.
+* **Linux**: Stored via standard **Secret Service API / libsecret**.
+* **Headless / Windows / Container Fallback**: Stored in `~/.config/iwas/credentials.json` with strict POSIX `0600` permissions and atomic write guarantees.
+
+You can explicitly enforce storage mode via the `IWAS_MCP_VAULT` environment variable:
+- `IWAS_MCP_VAULT=auto` (default: Keychain if available, fallback to file)
+- `IWAS_MCP_VAULT=keychain` (strict Keychain only)
+- `IWAS_MCP_VAULT=file` (strict file storage only)
+
+---
+
+## License
+
+MIT © [9xlayer](https://getiwas.com)