imarobot-verify 1.0.0

package/README.md

@@ -0,0 +1,52 @@
+# imarobot-verify
+
+Verify [ImaRobot](https://imarobot.ai) agent identity tokens. Open source receiver-side SDK.
+
+## Install
+
+```bash
+npm install imarobot-verify
+```
+
+## Quick start
+
+```javascript
+const { createVerifier } = require('imarobot-verify');
+
+const verifier = createVerifier({
+  publishableKey: 'pk_live_YOUR_KEY',
+});
+
+const result = await verifier.verify(token);
+// { valid: true, agentId, name, issuer, scopes, expiresAt }
+// { valid: false, error: 'TOKEN_REVOKED' | 'TOKEN_EXPIRED' | 'TOKEN_INVALID' }
+```
+
+## Express middleware
+
+```javascript
+const { middleware } = createVerifier({ publishableKey: 'pk_live_...' });
+
+app.get('/api/data', middleware(), (req, res) => {
+  const { agentId, scopes } = req.agent;
+  res.json({ message: `Hello, agent ${agentId}` });
+});
+```
+
+## Offline mode
+
+```javascript
+const verifier = createVerifier({
+  publishableKey: 'pk_live_...',
+  mode: 'offline',
+  cacheTTL: 300,
+});
+```
+
+## Docs
+
+[docs.imarobot.ai/sdks/verify](https://docs.imarobot.ai/sdks/verify)
+
+## License
+
+MIT — [Humans and Robots LLC](https://humansandrobots.ai)

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+export interface VerifierOptions {
+    /** Your pk_live_ or pk_test_ publishable key */
+    publishableKey: string;
+    /** 'online' (default) checks revocation; 'offline' is local-only */
+    mode?: 'online' | 'offline';
+    /** Seconds to cache public keys (default: 300) */
+    cacheTTL?: number;
+    /** Ms before falling back to offline (default: 3000) */
+    timeout?: number;
+    /** API base URL (default: https://api.imarobot.ai) */
+    baseUrl?: string;
+}
+export interface VerifyResultValid {
+    valid: true;
+    agentId: string;
+    name: string;
+    issuer: string;
+    scopes: string[];
+    description?: string;
+    issuedAt?: string;
+    expiresAt: string;
+    verifiedAt?: string;
+}
+export interface VerifyResultInvalid {
+    valid: false;
+    error: 'TOKEN_REVOKED' | 'TOKEN_EXPIRED' | 'TOKEN_INVALID';
+}
+export type VerifyResult = VerifyResultValid | VerifyResultInvalid;
+export interface AgentInfo {
+    agentId: string;
+    name: string;
+    issuer: string;
+    scopes: string[];
+    expiresAt: string;
+}
+declare global {
+    namespace Express {
+        interface Request {
+            agent?: AgentInfo;
+        }
+    }
+}
+export declare function createVerifier(options: VerifierOptions): {
+    verify: (token: string) => Promise<VerifyResult>;
+    middleware: () => (req: any, res: any, next: any) => Promise<any>;
+    warmCache: (domains?: string[]) => Promise<void>;
+};

package/dist/index.js

@@ -0,0 +1,206 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVerifier = createVerifier;
+const crypto = __importStar(require("crypto"));
+const https = __importStar(require("https"));
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function httpGet(url, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const req = https.get(url, { timeout: timeoutMs }, (res) => {
+            let data = '';
+            res.on('data', (chunk) => (data += chunk));
+            res.on('end', () => {
+                if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+                    resolve(data);
+                }
+                else {
+                    reject(new Error(`HTTP ${res.statusCode}: ${data.slice(0, 200)}`));
+                }
+            });
+        });
+        req.on('error', reject);
+        req.on('timeout', () => { req.destroy(); reject(new Error('Request timed out')); });
+    });
+}
+function base64UrlDecode(str) {
+    const base64 = str.replace(/-/g, '+').replace(/_/g, '/');
+    const padding = '='.repeat((4 - (base64.length % 4)) % 4);
+    return Buffer.from(base64 + padding, 'base64').toString('utf8');
+}
+function decodeJwtPayload(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        throw new Error('Invalid JWT format');
+    return JSON.parse(base64UrlDecode(parts[1]));
+}
+// ─── Verifier ────────────────────────────────────────────────────────────────
+function createVerifier(options) {
+    const { publishableKey, mode = 'online', cacheTTL = 300, timeout = 3000, baseUrl = 'https://api.imarobot.ai', } = options;
+    if (!publishableKey)
+        throw new Error('publishableKey is required');
+    // Public key cache: domain → { key, fetchedAt }
+    const keyCache = new Map();
+    async function fetchPublicKey(domain) {
+        const cacheKey = domain || '__default__';
+        const cached = keyCache.get(cacheKey);
+        if (cached && (Date.now() - cached.fetchedAt) / 1000 < cacheTTL) {
+            return cached.key;
+        }
+        const url = `${baseUrl}/.well-known/public-key.pem`;
+        const pem = await httpGet(url, timeout);
+        keyCache.set(cacheKey, { key: pem.trim(), fetchedAt: Date.now() });
+        return pem.trim();
+    }
+    function verifyOffline(token, publicKeyPem) {
+        try {
+            const payload = decodeJwtPayload(token);
+            // Check expiry
+            if (payload.exp && payload.exp * 1000 < Date.now()) {
+                return { valid: false, error: 'TOKEN_EXPIRED' };
+            }
+            // Verify RS256 signature
+            const [headerB64, payloadB64, signatureB64] = token.split('.');
+            const signedContent = `${headerB64}.${payloadB64}`;
+            const signature = Buffer.from(signatureB64.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (signatureB64.length % 4)) % 4), 'base64');
+            const verifier = crypto.createVerify('RSA-SHA256');
+            verifier.update(signedContent);
+            if (!verifier.verify(publicKeyPem, signature)) {
+                return { valid: false, error: 'TOKEN_INVALID' };
+            }
+            const agent = payload.agent || {};
+            return {
+                valid: true,
+                agentId: payload.sub,
+                name: agent.name || '',
+                issuer: payload.iss || '',
+                scopes: agent.scopes || [],
+                description: agent.description,
+                issuedAt: payload.iat ? new Date(payload.iat * 1000).toISOString() : undefined,
+                expiresAt: payload.exp ? new Date(payload.exp * 1000).toISOString() : '',
+            };
+        }
+        catch {
+            return { valid: false, error: 'TOKEN_INVALID' };
+        }
+    }
+    /**
+     * Verify an ImaRobot agent token.
+     */
+    async function verify(token) {
+        if (!token || typeof token !== 'string') {
+            return { valid: false, error: 'TOKEN_INVALID' };
+        }
+        // Online mode: call the API
+        if (mode === 'online') {
+            try {
+                const url = `${baseUrl}/v1/verify/${encodeURIComponent(token)}`;
+                const body = await httpGet(url, timeout);
+                const data = JSON.parse(body);
+                if (data.valid) {
+                    return {
+                        valid: true,
+                        agentId: data.agent_id,
+                        name: data.name || '',
+                        issuer: data.issuer || '',
+                        scopes: data.scopes || [],
+                        description: data.description,
+                        issuedAt: data.issued_at,
+                        expiresAt: data.expires_at || '',
+                        verifiedAt: data.verified_at,
+                    };
+                }
+                const errorMap = {
+                    TOKEN_REVOKED: 'TOKEN_REVOKED',
+                    TOKEN_EXPIRED: 'TOKEN_EXPIRED',
+                };
+                return { valid: false, error: errorMap[data.error] || 'TOKEN_INVALID' };
+            }
+            catch {
+                // Fallback to offline on network error
+                try {
+                    const publicKey = await fetchPublicKey();
+                    return verifyOffline(token, publicKey);
+                }
+                catch {
+                    return { valid: false, error: 'TOKEN_INVALID' };
+                }
+            }
+        }
+        // Offline mode: local validation only
+        try {
+            const publicKey = await fetchPublicKey();
+            return verifyOffline(token, publicKey);
+        }
+        catch {
+            return { valid: false, error: 'TOKEN_INVALID' };
+        }
+    }
+    /**
+     * Express middleware. Attaches req.agent on success, returns 401 on failure.
+     */
+    function middleware() {
+        return async (req, res, next) => {
+            const authHeader = req.headers?.['authorization'] || '';
+            const token = authHeader.startsWith('Bearer ') ? authHeader.slice(7).trim() : null;
+            if (!token) {
+                return res.status(401).json({
+                    error: { code: 'UNAUTHORIZED', message: 'Missing Authorization header.' },
+                });
+            }
+            const result = await verify(token);
+            if (!result.valid) {
+                return res.status(401).json({
+                    error: { code: 'UNAUTHORIZED', message: result.error },
+                });
+            }
+            req.agent = {
+                agentId: result.agentId,
+                name: result.name,
+                issuer: result.issuer,
+                scopes: result.scopes,
+                expiresAt: result.expiresAt,
+            };
+            next();
+        };
+    }
+    /**
+     * Pre-fetch and cache public keys for known issuer domains.
+     */
+    async function warmCache(domains) {
+        await fetchPublicKey();
+    }
+    return { verify, middleware, warmCache };
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "imarobot-verify",
+  "version": "1.0.0",
+  "description": "Verify ImaRobot agent identity tokens. Open source receiver-side SDK.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["imarobot", "agent", "identity", "verification", "jwt", "ai", "agent-identity"],
+  "author": "Humans and Robots LLC <rafi@humansandrobots.ai>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/humansandrobots/imarobot-verify"
+  },
+  "homepage": "https://docs.imarobot.ai/sdks/verify",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.0.0"
+  }
+}