@iwas/mcp 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# @iwas/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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):
+
+```bash
+# Display help & version
+iwas --help
+iwas --version
+
+# 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
+iwas status
+iwas status --server https://getiwas.com --json
+
+# Log out and remove credentials from vault & keychain
+iwas logout
+iwas logout --server https://getiwas.com --json
+```
+
+Auth server origin can also be set via the `IWAS_SERVER_URL` environment variable.
+
+### OAuth Scopes & Least-Privilege Defaults
+
+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`.
+
+> [!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.
+
+### Machine-Readable JSON Mode (`--json`)
+
+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.
+
+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}
+   ```
+
+3. **Error event:**
+   ```json
+   {"event":"error","error":"Invalid OAuth client: client not found"}
+   ```
+
+*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`.
+
+## Automatic Token Refresh & Concurrency Control (DEV-10)
+
+`@iwas/mcp` provides automatic, transparent token refresh and concurrency-safe credential management:
+
+```typescript
+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)
+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
+
+```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
+```