@ivalt/agent-auth 0.1.0

package/.env.example

@@ -0,0 +1,32 @@
+# iVALT MCP server configuration. Copy to .env (gitignored) or pass these as
+# real environment variables from your MCP client / container.
+#
+# With NO key set at all, the server routes through iVALT's public ondemandid.com
+# proxy and needs no credentials (good for demos).
+
+# --- iVALT credential (optional) ---
+# Set to call api.ivalt.com directly with your license key / connection id.
+# IVALT_API_KEY=your-x-api-key-here
+# IVALT_CONNECTION_ID=your-connection-id   # alias for IVALT_API_KEY
+
+# Force the upstream regardless of key presence: "direct" or "proxy".
+# IVALT_UPSTREAM=proxy
+
+# --- Approver defaults ---
+# Default approver phone (E.164), e.g. +12025550123. No default — set this, or
+# pass approver_mobile on each tool call. Callers can override per request.
+# IVALT_DEFAULT_MOBILE=+12025550123
+# Label shown in the approval request.
+IVALT_REQUEST_FROM=iVALT MCP
+# Default verification factors (comma list of: biometric,location,time,device).
+# IVALT_DEFAULT_FACTORS=biometric,location,time
+
+# --- HTTP transport (src/http.js / Docker) ---
+# Port the HTTP server listens on.
+PORT=8080
+# Bearer token required on POST /mcp. Leave unset only for local dev.
+# MCP_AUTH_TOKEN=change-me
+
+# --- Tuning (optional) ---
+# IVALT_POLL_INTERVAL_MS=2000
+# IVALT_AUTH_WINDOW_MS=180000

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iVALT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# @ivalt/agent-auth — iVALT human-approval MCP server
+
+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**.
+
+It ships two transports from one codebase:
+
+- **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.
+
+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.
+
+## 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 (`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.
+
+| 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`. |
+
+## Use it from a client
+
+### Cursor (`.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "ivalt": {
+      "command": "npx",
+      "args": ["-y", "@ivalt/agent-auth"],
+      "env": {
+        "IVALT_API_KEY": "your-key",
+        "IVALT_DEFAULT_MOBILE": "+1..."
+      }
+    }
+  }
+}
+```
+
+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`.
+
+### Python / LangGraph (`langchain-mcp-adapters`)
+
+```python
+from langchain_mcp_adapters.client import MultiServerMCPClient
+
+client = MultiServerMCPClient({
+    "ivalt": {
+        "command": "npx",
+        "args": ["-y", "@ivalt/agent-auth"],
+        "env": {"IVALT_API_KEY": "your-key", "IVALT_DEFAULT_MOBILE": "+1..."},
+        "transport": "stdio",
+    }
+})
+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):
+
+```python
+client = MultiServerMCPClient({
+    "ivalt": {
+        "url": "https://your-host/mcp",
+        "transport": "streamable_http",
+        "headers": {"Authorization": "Bearer <MCP_AUTH_TOKEN>"},
+    }
+})
+```
+
+## Run locally
+
+```bash
+npm install
+
+# stdio (what Cursor/Claude/LangGraph spawn)
+npm run start:stdio
+
+# HTTP transport
+MCP_AUTH_TOKEN=secret PORT=8080 npm run start:http
+curl http://localhost:8080/health
+```
+
+Quick wiring check over both transports:
+
+```bash
+node test/smoke.js stdio
+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)
+
+```bash
+docker build -t ivalt-mcp .
+docker run -p 8080:8080 \
+  -e MCP_AUTH_TOKEN=secret \
+  -e IVALT_API_KEY=your-key \
+  -e IVALT_DEFAULT_MOBILE=+1... \
+  ivalt-mcp
+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.
+
+## 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.
+- Approval window is ~60s; blocking `request_approval` polls every 2s.
+- HTTP runs in stateless mode (`GET`/`DELETE /mcp` return 405).

package/bin/ivalt-mcp.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { buildServer } from '../src/server.js';
+import { describeConfig } from '../src/config.js';
+
+async function main() {
+  const server = buildServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  // stderr only — stdout is the MCP protocol channel and must stay clean.
+  console.error('[ivalt-mcp] stdio server ready', JSON.stringify(describeConfig()));
+}
+
+main().catch((err) => {
+  console.error('[ivalt-mcp] fatal:', err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "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.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ivalt",
+    "human-in-the-loop",
+    "authentication",
+    "biometric",
+    "agent"
+  ],
+  "bin": {
+    "ivalt-mcp": "bin/ivalt-mcp.js"
+  },
+  "main": "src/server.js",
+  "files": [
+    "bin",
+    "src",
+    ".env.example",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node src/http.js",
+    "start:stdio": "node bin/ivalt-mcp.js",
+    "start:http": "node src/http.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "express": "^4.21.2",
+    "zod": "^3.24.1"
+  }
+}

package/src/config.js

@@ -0,0 +1,72 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/* Tiny, dependency-free .env loader. Real env vars (passed by the MCP client
+   or the container) always win over a local .env file. */
+function loadDotEnv() {
+  const candidates = [
+    path.join(process.cwd(), '.env'),
+    path.join(__dirname, '..', '.env'),
+  ];
+  for (const file of candidates) {
+    try {
+      const raw = fs.readFileSync(file, 'utf8');
+      for (const line of raw.split(/\r?\n/)) {
+        if (!line || line.trim().startsWith('#')) continue;
+        const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/i);
+        if (m && process.env[m[1]] === undefined) {
+          process.env[m[1]] = m[2].replace(/^["']|["']$/g, '');
+        }
+      }
+    } catch {
+      /* no .env at this path — fine */
+    }
+  }
+}
+
+loadDotEnv();
+
+function parseFactors(value) {
+  if (!value) return [];
+  return value
+    .split(',')
+    .map((s) => s.trim().toLowerCase())
+    .filter((s) => ['biometric', 'location', 'time', 'device'].includes(s));
+}
+
+const apiKey = process.env.IVALT_API_KEY || process.env.IVALT_CONNECTION_ID || '';
+
+/* upstream: 'direct' (api.ivalt.com, needs x-api-key) or 'proxy' (ondemandid.com,
+   no key needed). Defaults based on whether a key is present, overridable. */
+let upstream = (process.env.IVALT_UPSTREAM || '').toLowerCase();
+if (upstream !== 'direct' && upstream !== 'proxy') {
+  upstream = apiKey ? 'direct' : 'proxy';
+}
+
+export const config = {
+  apiKey,
+  upstream,
+  defaultMobile: process.env.IVALT_DEFAULT_MOBILE || '',
+  requestFrom: process.env.IVALT_REQUEST_FROM || 'iVALT MCP',
+  defaultFactors: parseFactors(process.env.IVALT_DEFAULT_FACTORS),
+  port: Number(process.env.PORT || 8080),
+  authToken: process.env.MCP_AUTH_TOKEN || '',
+  pollIntervalMs: Number(process.env.IVALT_POLL_INTERVAL_MS || 2000),
+  authWindowMs: Number(process.env.IVALT_AUTH_WINDOW_MS || 180000),
+  maxTimeoutS: 120,
+  defaultTimeoutS: 90,
+};
+
+export function describeConfig() {
+  return {
+    upstream: config.upstream,
+    upstream_host: config.upstream === 'direct' ? 'api.ivalt.com' : 'www.ondemandid.com',
+    key_set: Boolean(config.apiKey),
+    default_mobile: config.defaultMobile,
+    request_from: config.requestFrom,
+    default_factors: config.defaultFactors,
+  };
+}

package/src/http.js

@@ -0,0 +1,67 @@
+import express from 'express';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { buildServer } from './server.js';
+import { config, describeConfig } from './config.js';
+
+const app = express();
+app.use(express.json({ limit: '256kb' }));
+
+/* Unauthenticated health check for container orchestration. */
+app.get('/health', (_req, res) => {
+  res.json({ ok: true, transport: 'http', ...describeConfig() });
+});
+
+/* Bearer-token gate. When MCP_AUTH_TOKEN is set, every /mcp call must present it. */
+function requireAuth(req, res, next) {
+  if (!config.authToken) return next(); // open mode (dev only) — warned at startup
+  const header = req.headers['authorization'] || '';
+  const token = header.startsWith('Bearer ') ? header.slice(7) : '';
+  if (token && token === config.authToken) return next();
+  return res.status(401).json({
+    jsonrpc: '2.0',
+    error: { code: -32001, message: 'Unauthorized: missing or invalid bearer token.' },
+    id: null,
+  });
+}
+
+/* Stateless Streamable-HTTP: a fresh server + transport per request. Per-call
+   approver_mobile overrides ride in the tool arguments, so one endpoint serves
+   many tenants. */
+app.post('/mcp', requireAuth, async (req, res) => {
+  const server = buildServer();
+  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+  res.on('close', () => {
+    transport.close();
+    server.close();
+  });
+  try {
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  } catch (err) {
+    console.error('[ivalt-mcp] http request error:', err);
+    if (!res.headersSent) {
+      res.status(500).json({
+        jsonrpc: '2.0',
+        error: { code: -32603, message: 'Internal server error.' },
+        id: null,
+      });
+    }
+  }
+});
+
+/* Stateless mode does not support server-initiated streams or sessions. */
+const methodNotAllowed = (_req, res) =>
+  res.status(405).json({
+    jsonrpc: '2.0',
+    error: { code: -32000, message: 'Method not allowed (stateless server).' },
+    id: null,
+  });
+app.get('/mcp', methodNotAllowed);
+app.delete('/mcp', methodNotAllowed);
+
+app.listen(config.port, () => {
+  console.error(`[ivalt-mcp] HTTP server on :${config.port}`, JSON.stringify(describeConfig()));
+  if (!config.authToken) {
+    console.error('[ivalt-mcp] WARNING: MCP_AUTH_TOKEN is not set — /mcp is open. Set it before exposing this server.');
+  }
+});

package/src/ivalt-client.js

@@ -0,0 +1,145 @@
+import { config } from './config.js';
+
+/* Upstream endpoints. Direct hits api.ivalt.com with an x-api-key header;
+   proxy hits iVALT's public ondemandid.com demo proxy (no key needed). */
+const ENDPOINTS = {
+  direct: {
+    request: 'https://api.ivalt.com/biometric-auth-request',
+    result: 'https://api.ivalt.com/biometric-geo-fence-auth-results',
+  },
+  proxy: {
+    request: 'https://www.ondemandid.com/api/biometric-auth-request',
+    result: 'https://www.ondemandid.com/api/biometric-auth-result',
+  },
+};
+
+function endpoints() {
+  return ENDPOINTS[config.upstream] || ENDPOINTS.proxy;
+}
+
+function headers() {
+  const h = { 'Content-Type': 'application/json' };
+  if (config.upstream === 'direct' && config.apiKey) h['x-api-key'] = config.apiKey;
+  return h;
+}
+
+async function postJson(url, body, timeoutMs = 20000) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: headers(),
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    let json = null;
+    try {
+      json = await res.json();
+    } catch {
+      json = null;
+    }
+    return { status: res.status, ok: res.ok, json };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function extractDetail(json, fallback) {
+  return (
+    json?.error?.detail ||
+    json?.error?.message ||
+    json?.message ||
+    json?.detail ||
+    fallback
+  );
+}
+
+/**
+ * Fire a biometric approval request (push to the approver's phone).
+ * @returns {Promise<{ok: boolean, status: number, detail?: string, raw: any}>}
+ */
+export async function requestApproval({ mobile, requestFrom }) {
+  try {
+    const { status, ok, json } = await postJson(endpoints().request, {
+      mobile,
+      requestFrom: requestFrom || config.requestFrom,
+    });
+    if (!ok) {
+      return { ok: false, status, detail: extractDetail(json, 'iVALT request failed.'), raw: json };
+    }
+    return { ok: true, status, raw: json };
+  } catch (err) {
+    return { ok: false, status: 0, detail: `Upstream unreachable: ${err.message}`, raw: null };
+  }
+}
+
+/**
+ * Poll the result endpoint once.
+ * @returns {Promise<{state: 'approved'|'pending'|'denied'|'error', detail?: string, raw: any, status: number}>}
+ */
+export async function pollResult({ mobile }) {
+  let res;
+  try {
+    res = await postJson(endpoints().result, { mobile });
+  } catch (err) {
+    // Transient network error — caller should keep polling.
+    return { state: 'pending', detail: `transient: ${err.message}`, raw: null, status: 0 };
+  }
+
+  const { status, ok, json } = res;
+
+  if (ok) {
+    const details = json?.data?.details || json?.details || json || {};
+    return { state: 'approved', raw: details, status };
+  }
+  // 422 = still waiting; 404 = not yet registered — both mean keep polling.
+  if (status === 422 || status === 404) {
+    return { state: 'pending', raw: json, status };
+  }
+  // Anything else is a hard failure (denied / geofence / timezone / bad request).
+  return { state: 'denied', detail: extractDetail(json, 'Authentication failed.'), raw: json, status };
+}
+
+/**
+ * Normalize an approved iVALT response into a stable attestation object so
+ * callers never parse raw upstream shapes.
+ */
+export function normalizeAttestation(rawDetails, { mobile, requestFrom, factors }) {
+  const d = rawDetails || {};
+  const requested = Array.isArray(factors) ? factors : [];
+
+  // iVALT returns geo data when the device shares it.
+  const hasLocation = d.latitude != null || d.longitude != null || d.address != null;
+  const location = hasLocation
+    ? { latitude: d.latitude ?? null, longitude: d.longitude ?? null, address: d.address ?? null }
+    : null;
+
+  return {
+    approved: true,
+    request_id: d.request_id || d.requestId || null,
+    approver: {
+      mobile,
+      name: d.name || null,
+      email: d.email || null,
+    },
+    approver_mobile: mobile,
+    request_from: requestFrom || config.requestFrom,
+    factors_verified: {
+      // iVALT is biometric by definition; location is verified when geo is returned.
+      biometric: true,
+      location: requested.includes('location') || hasLocation,
+      time: requested.includes('time'),
+      device: requested.includes('device') || Boolean(d.imei),
+    },
+    location,
+    signed_at: new Date().toISOString(),
+    pki: {
+      // iVALT returns the device's registered public key in the `imei` field.
+      public_key: d.imei || d.publicKey || d.public_key || null,
+      signature: d.signature || d.attestation || d.token || null,
+      key_ref: d.request_id || d.requestId || d.keyId || d.key_ref || null,
+    },
+    raw: d,
+  };
+}

package/src/server.js

@@ -0,0 +1,13 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerTools } from './tools.js';
+
+/* Build a fresh MCP server instance with the iVALT tools registered.
+   A new instance is created per stdio process and per stateless HTTP request. */
+export function buildServer() {
+  const server = new McpServer({
+    name: 'ivalt-approval',
+    version: '0.1.0',
+  });
+  registerTools(server);
+  return server;
+}

package/src/tools.js

@@ -0,0 +1,197 @@
+import { z } from 'zod';
+import { config } from './config.js';
+import { requestApproval, pollResult, normalizeAttestation } from './ivalt-client.js';
+
+const FACTORS = ['biometric', 'location', 'time', 'device'];
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/* request_id is an opaque, self-describing handle. iVALT's result endpoint keys
+   off the approver mobile, so we encode mobile + context + issue time. */
+function encodeRequestId({ mobile, requestFrom, factors, issuedAt }) {
+  const json = JSON.stringify({ m: mobile, r: requestFrom, f: factors, t: issuedAt });
+  return Buffer.from(json, 'utf8').toString('base64url');
+}
+
+function decodeRequestId(requestId) {
+  try {
+    const json = Buffer.from(String(requestId), 'base64url').toString('utf8');
+    const o = JSON.parse(json);
+    return { mobile: o.m, requestFrom: o.r, factors: o.f || [], issuedAt: o.t };
+  } catch {
+    return null;
+  }
+}
+
+function resolveApprover(input) {
+  return (input && String(input).trim()) || config.defaultMobile;
+}
+
+const NO_APPROVER_DETAIL =
+  'No approver phone configured. Pass approver_mobile (E.164, e.g. +12025550123) or set IVALT_DEFAULT_MOBILE on the server.';
+
+function resolveFactors(input) {
+  if (Array.isArray(input) && input.length) return input.filter((f) => FACTORS.includes(f));
+  return config.defaultFactors;
+}
+
+/* Wrap a JS object as an MCP tool result (text content with pretty JSON). */
+function result(payload, { isError = false } = {}) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    isError,
+  };
+}
+
+const sharedInput = {
+  action: z.string().min(1).describe('Human-readable description of the sensitive action requiring approval.'),
+  reason: z.string().optional().describe('Optional extra context shown alongside the action.'),
+  approver_mobile: z
+    .string()
+    .optional()
+    .describe('Approver phone in E.164 (e.g. +12025550123). Defaults to the server-configured approver. Override per call for multi-tenant routing.'),
+  factors: z
+    .array(z.enum(FACTORS))
+    .optional()
+    .describe('Verification factors to require. Defaults to the server-configured factors.'),
+};
+
+export function registerTools(server) {
+  /* ---- request_approval: blocking, waits for the phone approval ---- */
+  server.registerTool(
+    'request_approval',
+    {
+      title: 'Request human approval (blocking)',
+      description:
+        'Escalate a sensitive step to a human: sends an iVALT push to the approver phone, waits for biometric approval, and returns a PKI-signed attestation. Blocks up to timeout_s seconds.',
+      inputSchema: {
+        ...sharedInput,
+        timeout_s: z
+          .number()
+          .int()
+          .positive()
+          .max(config.maxTimeoutS)
+          .optional()
+          .describe(`How long to wait for approval, seconds (default ${config.defaultTimeoutS}, max ${config.maxTimeoutS}).`),
+      },
+    },
+    async ({ action, reason, approver_mobile, factors, timeout_s }) => {
+      const mobile = resolveApprover(approver_mobile);
+      if (!mobile) {
+        return result({ status: 'error', detail: NO_APPROVER_DETAIL }, { isError: true });
+      }
+      const usedFactors = resolveFactors(factors);
+      const requestFrom = reason ? `${config.requestFrom}: ${action} (${reason})` : `${config.requestFrom}: ${action}`;
+
+      const sent = await requestApproval({ mobile, requestFrom });
+      if (!sent.ok) {
+        return result({ status: 'error', detail: sent.detail, approver_mobile: mobile }, { isError: true });
+      }
+
+      const timeoutMs = Math.min((timeout_s || config.defaultTimeoutS) * 1000, config.maxTimeoutS * 1000);
+      const expiresAt = Date.now() + timeoutMs;
+
+      while (Date.now() < expiresAt) {
+        await sleep(config.pollIntervalMs);
+        const r = await pollResult({ mobile });
+        if (r.state === 'approved') {
+          return result({
+            status: 'approved',
+            attestation: normalizeAttestation(r.raw, { mobile, requestFrom, factors: usedFactors }),
+          });
+        }
+        if (r.state === 'denied') {
+          return result({ status: 'denied', detail: r.detail, approver_mobile: mobile }, { isError: true });
+        }
+      }
+
+      return result(
+        { status: 'expired', detail: 'No approval received within the timeout window.', approver_mobile: mobile },
+        { isError: true }
+      );
+    }
+  );
+
+  /* ---- request_approval_async: returns a request_id immediately ---- */
+  server.registerTool(
+    'request_approval_async',
+    {
+      title: 'Request human approval (async)',
+      description:
+        'Fire an iVALT approval request and return immediately with a request_id. Use check_status to poll for the result. Best for long-running cloud agents.',
+      inputSchema: { ...sharedInput },
+    },
+    async ({ action, reason, approver_mobile, factors }) => {
+      const mobile = resolveApprover(approver_mobile);
+      if (!mobile) {
+        return result({ status: 'error', detail: NO_APPROVER_DETAIL }, { isError: true });
+      }
+      const usedFactors = resolveFactors(factors);
+      const requestFrom = reason ? `${config.requestFrom}: ${action} (${reason})` : `${config.requestFrom}: ${action}`;
+
+      const sent = await requestApproval({ mobile, requestFrom });
+      if (!sent.ok) {
+        return result({ status: 'error', detail: sent.detail, approver_mobile: mobile }, { isError: true });
+      }
+
+      const issuedAt = Date.now();
+      const request_id = encodeRequestId({ mobile, requestFrom, factors: usedFactors, issuedAt });
+      return result({
+        status: 'pending',
+        request_id,
+        approver_mobile: mobile,
+        expires_at: new Date(issuedAt + config.authWindowMs).toISOString(),
+      });
+    }
+  );
+
+  /* ---- check_status: poll a previously issued request ---- */
+  server.registerTool(
+    'check_status',
+    {
+      title: 'Check approval status',
+      description:
+        'Check the status of a request_id from request_approval_async. Returns pending, approved (with attestation), denied, or expired.',
+      inputSchema: {
+        request_id: z.string().min(1).describe('The request_id returned by request_approval_async.'),
+      },
+    },
+    async ({ request_id }) => {
+      const decoded = decodeRequestId(request_id);
+      if (!decoded || !decoded.mobile) {
+        return result({ status: 'error', detail: 'Invalid request_id.' }, { isError: true });
+      }
+      const { mobile, requestFrom, factors, issuedAt } = decoded;
+      const expired = Date.now() > issuedAt + config.authWindowMs;
+
+      const r = await pollResult({ mobile });
+      if (r.state === 'approved') {
+        return result({
+          status: 'approved',
+          request_id,
+          attestation: normalizeAttestation(r.raw, { mobile, requestFrom, factors }),
+        });
+      }
+      if (r.state === 'denied') {
+        return result({ status: 'denied', request_id, detail: r.detail }, { isError: true });
+      }
+      if (expired) {
+        return result(
+          {
+            status: 'expired',
+            request_id,
+            detail: `No approval received within the ${Math.round(config.authWindowMs / 1000)}s window.`,
+          },
+          { isError: true }
+        );
+      }
+      return result({
+        status: 'pending',
+        request_id,
+        expires_at: new Date(issuedAt + config.authWindowMs).toISOString(),
+      });
+    }
+  );
+
+  return server;
+}