@ivalt/agent-auth 0.1.0 → 0.1.1

package/README.md

@@ -1,70 +1,34 @@
-# @ivalt/agent-auth — iVALT human-approval MCP server
+<div align="center">
 
-Escalate a sensitive agent step to a real human. This MCP server sends an iVALT
-push to the approver's phone, the human approves with biometrics (FaceID /
-fingerprint, plus optional location / time / device checks), and the agent
-receives a **PKI-signed attestation**.
+<img src="https://unpkg.com/@ivalt/agent-auth/assets/logo.svg" alt="iVALT" width="80" height="80" />
 
-It ships two transports from one codebase:
+# @ivalt/agent-auth
 
-- **stdio** — launched locally via `npx` (for Cursor, Claude Desktop, LangGraph).
-- **HTTP** (Streamable-HTTP) — a hostable endpoint (Docker image) for the
-  multi-tenant / remote use case.
+**Human-in-the-loop authentication for AI agents**
 
-The agent never sees the iVALT key — it lives only in this server's env. The
-client decides *when* to call and owns governance; iVALT owns the verify action.
+Biometric approval with PKI-signed attestation — via [Model Context Protocol (MCP)](https://modelcontextprotocol.io).
 
-## Tools
+[![npm version](https://img.shields.io/npm/v/@ivalt/agent-auth)](https://www.npmjs.com/package/@ivalt/agent-auth)
+[![license](https://img.shields.io/npm/l/@ivalt/agent-auth)](https://www.npmjs.com/package/@ivalt/agent-auth)
+[![node](https://img.shields.io/node/v/@ivalt/agent-auth)](https://www.npmjs.com/package/@ivalt/agent-auth)
 
-| Tool | Behavior |
-|------|----------|
-| `request_approval` | Blocking. Sends the request and waits up to `timeout_s` (default 90, max 120) for approval. Returns the attestation. |
-| `request_approval_async` | Returns a `request_id` immediately. For long-running cloud agents. |
-| `check_status` | Polls a `request_id` -> `pending` / `approved` (with attestation) / `denied` / `expired`. |
+[Website](https://www.ivalt.com) · [Report issue](https://github.com/ivalt/agent-auth/issues)
 
-Shared inputs: `action` (required), `reason`, `approver_mobile` (E.164, overrides
-the default — this is how one endpoint serves many tenants), `factors`
-(`biometric` | `location` | `time` | `device`).
+</div>
 
-Approved responses return a normalized attestation:
+When an agent hits a sensitive step, this MCP server pauses the workflow, sends an iVALT push to the approver's phone, and returns a **PKI-signed attestation** after biometric approval (FaceID / fingerprint, plus optional location, time, and device checks).
 
-```json
-{
-  "status": "approved",
-  "attestation": {
-    "approved": true,
-    "request_id": "a518d10b-...",
-    "approver": { "mobile": "+1...", "name": "Jane Doe", "email": "jane@example.com" },
-    "approver_mobile": "+1...",
-    "request_from": "iVALT MCP: <action>",
-    "factors_verified": { "biometric": true, "location": true, "time": false, "device": true },
-    "location": { "latitude": "32.84...", "longitude": "-79.86...", "address": "..." },
-    "signed_at": "2026-06-26T...Z",
-    "pki": { "public_key": "MIICIjANBgkq...", "signature": null, "key_ref": "a518d10b-..." },
-    "raw": { }
-  }
-}
+```
+Agent step → request_approval → iVALT push → human approves → PKI attestation → agent continues
 ```
 
-Notes on the live shape: iVALT returns the device's registered public key in `raw.imei` (mapped to `pki.public_key`), the iVALT request UUID in `raw.request_id`, and geo data (`latitude`/`longitude`/`address`) when the device shares it. This endpoint does not return a separate detached `signature`, so `pki.signature` is typically `null` while `pki.public_key` carries the PKI material. The complete upstream payload is always preserved under `raw`.
-
-## Configuration
-
-All config is via environment variables (see [`.env.example`](.env.example)).
-With **no key set**, the server uses iVALT's public `ondemandid.com` proxy (no
-credentials needed). Set `IVALT_API_KEY` to call `api.ivalt.com` directly.
+## Install
 
-| Var | Default | Purpose |
-|-----|---------|---------|
-| `IVALT_API_KEY` / `IVALT_CONNECTION_ID` | _(none)_ | iVALT credential; presence switches upstream to `direct`. |
-| `IVALT_UPSTREAM` | auto | Force `direct` or `proxy`. |
-| `IVALT_DEFAULT_MOBILE` | _(none)_ | Default approver phone (E.164). If unset, callers must pass `approver_mobile` per request. |
-| `IVALT_REQUEST_FROM` | `iVALT MCP` | Label on the approval request. |
-| `IVALT_DEFAULT_FACTORS` | _(none)_ | Comma list of default factors. |
-| `PORT` | `8080` | HTTP transport port. |
-| `MCP_AUTH_TOKEN` | _(none)_ | Bearer token required on `POST /mcp`. |
+No clone or build — run directly from npm:
 
-## Use it from a client
+```bash
+npx -y @ivalt/agent-auth
+```
 
 ### Cursor (`.cursor/mcp.json`)
 
@@ -83,20 +47,6 @@ credentials needed). Set `IVALT_API_KEY` to call `api.ivalt.com` directly.
 }
 ```
 
-Pre-publish, point at the local path instead:
-
-```json
-{
-  "mcpServers": {
-    "ivalt": {
-      "command": "node",
-      "args": ["C:/dev/iv/projects/mcp/bin/ivalt-mcp.js"],
-      "env": { "IVALT_DEFAULT_MOBILE": "+1..." }
-    }
-  }
-}
-```
-
 ### Claude Desktop
 
 Same shape under `mcpServers` in `claude_desktop_config.json`.
@@ -115,10 +65,70 @@ client = MultiServerMCPClient({
     }
 })
 tools = await client.get_tools()   # request_approval, request_approval_async, check_status
-# bind `tools` into your graph; use request_approval as a human-in-the-loop gate.
 ```
 
-To connect to a hosted HTTP server instead (no Node needed on the client):
+## Requirements
+
+- **Node.js** 18+
+- **iVALT credential** (optional) — without `IVALT_API_KEY`, the server uses iVALT's public demo proxy (`ondemandid.com`); set a key to call `api.ivalt.com` directly
+- **Approver phone** — set `IVALT_DEFAULT_MOBILE` (E.164) or pass `approver_mobile` on each tool call
+
+## Transports
+
+- **stdio** — launched locally via `npx` (Cursor, Claude Desktop, LangGraph)
+- **HTTP** (Streamable-HTTP) — hostable endpoint for multi-tenant / remote use (Docker)
+
+The agent never sees the iVALT key — it lives only in this server's env.
+
+## Tools
+
+| Tool | Behavior |
+|------|----------|
+| `request_approval` | Blocking. Sends the request and waits up to `timeout_s` (default 90, max 120) for approval. Returns the attestation. |
+| `request_approval_async` | Returns a `request_id` immediately. For long-running cloud agents. |
+| `check_status` | Polls a `request_id` → `pending` / `approved` (with attestation) / `denied` / `expired`. |
+
+Shared inputs: `action` (required), `reason`, `approver_mobile` (E.164, overrides the default — this is how one endpoint serves many tenants), `factors` (`biometric` \| `location` \| `time` \| `device`).
+
+Approved responses return a normalized attestation:
+
+```json
+{
+  "status": "approved",
+  "attestation": {
+    "approved": true,
+    "request_id": "a518d10b-...",
+    "approver": { "mobile": "+1...", "name": "Jane Doe", "email": "jane@example.com" },
+    "approver_mobile": "+1...",
+    "request_from": "iVALT MCP: <action>",
+    "factors_verified": { "biometric": true, "location": true, "time": false, "device": true },
+    "location": { "latitude": "32.84...", "longitude": "-79.86...", "address": "..." },
+    "signed_at": "2026-06-26T...Z",
+    "pki": { "public_key": "MIICIjANBgkq...", "signature": null, "key_ref": "a518d10b-..." },
+    "raw": { }
+  }
+}
+```
+
+Notes on the live shape: iVALT returns the device's registered public key in `raw.imei` (mapped to `pki.public_key`), the iVALT request UUID in `raw.request_id`, and geo data when the device shares it. This endpoint does not return a separate detached `signature`, so `pki.signature` is typically `null` while `pki.public_key` carries the PKI material. The complete upstream payload is always preserved under `raw`.
+
+## Configuration
+
+All config is via environment variables (see [`.env.example`](.env.example)).
+
+| Var | Default | Purpose |
+|-----|---------|---------|
+| `IVALT_API_KEY` / `IVALT_CONNECTION_ID` | _(none)_ | iVALT credential; presence switches upstream to `direct`. |
+| `IVALT_UPSTREAM` | auto | Force `direct` or `proxy`. |
+| `IVALT_DEFAULT_MOBILE` | _(none)_ | Default approver phone (E.164). If unset, callers must pass `approver_mobile` per request. |
+| `IVALT_REQUEST_FROM` | `iVALT MCP` | Label on the approval request. |
+| `IVALT_DEFAULT_FACTORS` | _(none)_ | Comma list of default factors. |
+| `PORT` | `8080` | HTTP transport port. |
+| `MCP_AUTH_TOKEN` | _(none)_ | Bearer token required on `POST /mcp`. |
+
+## Hosted HTTP transport
+
+To connect to a hosted server instead of running locally (no Node needed on the client):
 
 ```python
 client = MultiServerMCPClient({
@@ -130,9 +140,11 @@ client = MultiServerMCPClient({
 })
 ```
 
-## Run locally
+## Development
 
 ```bash
+git clone https://github.com/ivalt/agent-auth.git
+cd agent-auth
 npm install
 
 # stdio (what Cursor/Claude/LangGraph spawn)
@@ -143,7 +155,7 @@ MCP_AUTH_TOKEN=secret PORT=8080 npm run start:http
 curl http://localhost:8080/health
 ```
 
-Quick wiring check over both transports:
+Quick wiring check:
 
 ```bash
 node test/smoke.js stdio
@@ -151,7 +163,7 @@ node test/smoke.js http http://localhost:8080/mcp secret
 # add SMOKE_FIRE=1 to also fire a real push to IVALT_DEFAULT_MOBILE
 ```
 
-## Run with Docker (HTTP transport)
+### Docker (HTTP transport)
 
 ```bash
 docker build -t ivalt-mcp .
@@ -163,12 +175,14 @@ docker run -p 8080:8080 \
 curl http://localhost:8080/health
 ```
 
-The multi-tenant router connects to `POST /mcp` with the bearer token and passes
-a per-tenant `approver_mobile` in each tool call.
+The multi-tenant router connects to `POST /mcp` with the bearer token and passes a per-tenant `approver_mobile` in each tool call.
 
 ## Notes
 
-- `request_id` encodes the approver mobile + issue time; iVALT's result endpoint
-  keys on the mobile, so avoid concurrent in-flight requests for the same phone.
+- `request_id` encodes the approver mobile + issue time; iVALT's result endpoint keys on the mobile, so avoid concurrent in-flight requests for the same phone.
 - Approval window is ~60s; blocking `request_approval` polls every 2s.
 - HTTP runs in stateless mode (`GET`/`DELETE /mcp` return 405).
+
+## License
+
+[MIT](LICENSE)

package/assets/logo.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 120" role="img" aria-label="iVALT">
+  <rect width="120" height="120" rx="24" fill="#0E7C95"/>
+  <path fill="#fff" d="M36 78V42h12.4l11.2 28.4L70.8 42H83v36H73.6V58.8L63.2 78h-6.4L46.4 58.8V78H36zm44.8 0V42H91v36H80.8z"/>
+</svg>

package/package.json

@@ -1,9 +1,18 @@
 {
   "name": "@ivalt/agent-auth",
-  "version": "0.1.0",
-  "description": "iVALT human-approval MCP server: escalate sensitive agent steps to biometric, PKI-signed human attestation. stdio + HTTP transports.",
+  "version": "0.1.1",
+  "description": "Human-in-the-loop MCP server for AI agents — biometric approval with PKI-signed attestation. stdio + HTTP.",
   "type": "module",
   "license": "MIT",
+  "author": "iVALT <info@ivalt.com> (https://www.ivalt.com)",
+  "homepage": "https://www.ivalt.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ivalt/agent-auth.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ivalt/agent-auth/issues"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -21,6 +30,7 @@
   },
   "main": "src/server.js",
   "files": [
+    "assets",
     "bin",
     "src",
     ".env.example",