@agentadmit/sdk 1.0.0

package/.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+# Publish @agentadmit/sdk to npm with Trusted Publishing + Provenance
+#
+# Trusted Publishing (OIDC) eliminates long-lived npm tokens.
+# Provenance is generated automatically with trusted publishing.
+#
+# Prerequisites (one-time setup on npmjs.com):
+#   1. Create npm org: @agentadmit
+#   2. Create package: @agentadmit/sdk
+#   3. Configure trusted publisher:
+#      - Organization: PhoenixCo-Founder
+#      - Repository: agentadmit-sdk-node
+#      - Workflow: publish.yml
+#   4. Restrict token access: "Require 2FA and disallow tokens"
+#
+# Trigger: push a version tag (e.g., git tag v0.1.0 && git push --tags)
+
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+
+      # Install npm 11+ for trusted publishing support
+      - name: Upgrade npm for trusted publishing
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests
+        run: npm test --if-present
+
+      - name: Publish with trusted publishing
+        run: npm publish --access public

package/LICENSE

@@ -0,0 +1,56 @@
+AgentAdmit Proprietary License
+
+Copyright (c) 2026 AgentAdmit LLC. All rights reserved.
+
+Patent Pending — U.S. Application No. 19/660,916
+
+TERMS OF USE
+
+1. GRANT OF LICENSE. AgentAdmit LLC ("Licensor") grants you a limited,
+   non-exclusive, non-transferable, revocable license to use this software
+   development kit ("SDK") solely for the purpose of integrating with the
+   AgentAdmit hosted service (api.agentadmit.com).
+
+2. RESTRICTIONS. You may not:
+   (a) Use this SDK with any service other than the AgentAdmit hosted service;
+   (b) Modify, adapt, or create derivative works of this SDK for the purpose
+       of building or operating a competing service;
+   (c) Reverse engineer, decompile, or disassemble the AgentAdmit protocol
+       or service architecture;
+   (d) Remove or alter any proprietary notices, labels, or marks;
+   (e) Redistribute this SDK as a standalone product or as part of a
+       competing authorization service.
+
+3. PERMITTED USES. You may:
+   (a) Install and use this SDK in your applications;
+   (b) Include this SDK as a dependency in your projects;
+   (c) Distribute your applications that incorporate this SDK, provided
+       those applications connect to the AgentAdmit hosted service.
+
+4. AGENTADMIT SERVICE REQUIRED. This SDK is designed exclusively for use
+   with the AgentAdmit hosted service. An AgentAdmit account and valid API
+   keys are required. Sign up at https://agentadmit.com.
+
+5. INTELLECTUAL PROPERTY. The AgentAdmit protocol, user-mediated token
+   delivery mechanism, mandatory introspection architecture, and related
+   inventions are protected by pending U.S. patent(s) and other intellectual
+   property rights. This license does not grant any rights to the underlying
+   patents or trade secrets.
+
+6. NO WARRANTY. THIS SDK IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+7. LIMITATION OF LIABILITY. IN NO EVENT SHALL AGENTADMIT LLC BE LIABLE FOR
+   ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES
+   ARISING FROM YOUR USE OF THIS SDK.
+
+8. TERMINATION. This license terminates automatically if you violate any
+   of its terms. Upon termination, you must cease all use and destroy all
+   copies of this SDK in your possession.
+
+9. GOVERNING LAW. This license is governed by the laws of the State of
+   California, United States.
+
+For licensing inquiries: legal@agentadmit.com
+For developer support: https://agentadmit.com/docs

package/README.md

@@ -0,0 +1,203 @@
+# @agentadmit/sdk — Node.js
+
+User-mediated AI agent authorization. Plug-and-play for Express and Next.js.
+
+> **Get started:** Sign up at [agentadmit.com](https://agentadmit.com) → Get your test keys → Install the SDK → Build.
+> Test keys are available immediately after signup. Live keys become available when you subscribe an app.
+
+## Quick Start
+
+```bash
+npm install @agentadmit/sdk
+npx agentadmit init
+```
+
+Edit `agentadmit.yaml` to define your scopes, then add to your Express app:
+
+```javascript
+const express = require('express');
+const { loadConfig, createStorage, createAgentAdmitRouter, setStorage, requireScopeIfAgent } = require('@agentadmit/sdk');
+
+const app = express();
+app.use(express.json());
+
+// Initialize AgentAdmit
+const config = loadConfig('agentadmit.yaml');
+const storage = createStorage(config);
+setStorage(storage);
+
+// Create and mount AgentAdmit routes
+const { wellknownRouter, agentadmitRouter } = createAgentAdmitRouter({
+  storage,
+  getCurrentUser: async (req) => { /* your auth logic */ },
+});
+app.use(wellknownRouter);
+app.use('/agentadmit', agentadmitRouter);
+
+// Protect your routes with scope enforcement
+app.get('/api/orders', requireScopeIfAgent('read:orders'), (req, res) => {
+  const user = req.agentAdmit?.user;
+  // Your existing logic — unchanged
+  res.json({ orders: getOrdersForUser(user.user_id) });
+});
+```
+
+## Next.js API Routes
+
+```typescript
+// pages/api/orders.ts (or app/api/orders/route.ts)
+import { validateAgentToken, getConfig } from '@agentadmit/sdk';
+
+export default async function handler(req, res) {
+  const token = req.headers.authorization?.replace('Bearer ', '');
+  const config = getConfig();
+
+  if (token?.startsWith(config.token_prefix_access)) {
+    const ctx = await validateAgentToken(token);
+    if (!ctx.scopes.includes('read:orders')) {
+      return res.status(403).json({ error: 'insufficient_scope' });
+    }
+    // Agent path
+    return res.json({ orders: await getOrders(ctx.user.user_id) });
+  }
+
+  // Regular user path
+  // ... your existing auth
+}
+```
+
+## MCP Server Integration
+
+Building an MCP server in TypeScript/Node? AgentAdmit is the auth layer. MCP servers are app owners. Same SDK, same pricing.
+
+For **STDIO transport** (most MCP servers), the agent includes the token in tool arguments:
+
+```javascript
+const { validateAgentToken } = require('@agentadmit/sdk');
+
+async function handleToolCall(name, args) {
+  // 1. Extract token from tool arguments
+  const token = args.agentadmit_token;
+  delete args.agentadmit_token;
+  if (!token) throw new Error('agentadmit_token required');
+  
+  // 2. Validate via AgentAdmit hosted service
+  const ctx = await validateAgentToken(token);
+  
+  // 3. Check scope for this tool
+  const required = SCOPE_MAP[name];
+  if (required && !ctx.scopes.includes(required)) {
+    throw new Error(`Missing scope '${required}'`);
+  }
+  
+  // 4. Run the tool
+  return TOOL_HANDLERS[name](args, ctx);
+}
+```
+
+For **HTTP transport** (Express-based MCP servers), use the full SDK middleware. The agent sends the token via `Authorization: Bearer` header, same as any HTTP API.
+
+Full MCP integration guide with complete before/after examples: `agentadmit.com/docs/mcp-guide`
+
+**MCP operators:** You also get the embeddable admin panel with revoke capability, admin scopes for your own AI agent to monitor your server, and full audit trail for billing. See the Admin Revocation and Embeddable Admin Panel sections below.
+
+## How It Works
+
+1. User clicks "AgentAdmit" in your app
+2. Selects scopes and connection duration
+3. Gets a token to give to their AI agent
+4. Agent exchanges the token for scoped API access
+5. User revokes anytime
+
+The token goes to the human, not the agent. No automated delivery = no prompt injection surface.
+
+## Important
+
+**Mandatory introspection.** All token validation goes through api.agentadmit.com. There is no self-hosted mode. No local JWT validation. No bypass. This is required for security, audit logging, and scope enforcement.
+
+**Admin revocation.** As the app operator, you can revoke any user's agent connection via `DELETE /agentadmit/admin/connections/{connection_id}` (requires admin role or `manage:connections` scope). Your own AI agent can also revoke connections if given this scope.
+
+**Embeddable admin panel.** Drop the `<AgentAdmitAdminPanel>` React component into your admin section to view all agent connections, usage metrics, billing status, and revoke any connection without leaving your app. See the React SDK for details.
+
+**In-app AI scopes.** If your app has built-in AI features (analysis, plan generation, photo recognition), do not expose those as agent scopes. The user's AI agent can read the raw data and do the analysis itself. Exposing in-app AI endpoints to agents creates double cost.
+
+## Rate Limiting
+
+The AgentAdmit introspection endpoint enforces rate limits. The Node.js SDK handles HTTP 429 responses **automatically** with exponential backoff and jitter — no changes needed in your middleware code.
+
+### Retry behavior
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| Initial delay | 1 second | First retry wait |
+| Backoff multiplier | 2× | Doubles each retry |
+| Cap | 30 seconds | Maximum wait per retry |
+| Jitter | 0–500 ms | Random addition to each delay |
+| Max retries | **3** | Configurable |
+
+The SDK also respects the `Retry-After` response header — if present, it overrides the computed backoff delay.
+
+### Configuring max retries
+
+In `agentadmit.yaml`:
+
+```yaml
+max_retries: 5  # default: 3. Set to 0 to disable retries.
+```
+
+### Handling exhausted retries
+
+When all retries are exhausted, `validateAgentToken` throws `RateLimitError`:
+
+```typescript
+import { requireScope, RateLimitError } from '@agentadmit/sdk';
+
+app.use((err: any, req, res, next) => {
+  if (err instanceof RateLimitError) {
+    res.set('Retry-After', String(err.retryAfter ?? 60));
+    return res.status(429).json({
+      error: 'rate_limited',
+      retry_after: err.retryAfter,
+      limit: err.limit,
+      remaining: err.remaining,
+      reset: err.reset,
+    });
+  }
+  next(err);
+});
+```
+
+`RateLimitError` properties:
+- `retryAfter` — seconds from `Retry-After` header (or `null`)
+- `limit` — `X-RateLimit-Limit` header value (or `null`)
+- `remaining` — `X-RateLimit-Remaining` header value (or `null`)
+- `reset` — `X-RateLimit-Reset` Unix timestamp (or `null`)
+
+## Documentation
+
+Full integration guide: https://agentadmit.com/docs/app-owner-guide
+
+
+## Data Collection & Privacy
+
+The AgentAdmit Node.js SDK runs server-side and does not interact with app stores or end-user devices directly.
+
+### What the SDK does
+- Validates AgentAdmit tokens presented by AI agents
+- Enforces scope-based access control on your API routes
+- Manages connection lifecycle (create, revoke, audit)
+
+### What the SDK does NOT do
+- Does not collect end-user data
+- Does not send telemetry or analytics
+- Does not phone home to AgentAdmit servers (all operations use your configured keys and storage)
+- Does not track users or devices
+
+### Privacy impact
+Since this SDK runs on your server, it has no direct App Store or Play Store compliance surface. Your client-side integration (e.g., the AgentAdmit React SDK) handles privacy manifest and data safety requirements.
+
+For complete compliance guidance, see our [compliance guide](https://agentadmit.com/docs/compliance).
+
+## License
+
+All rights reserved. Patent pending.

package/dist/auth.d.ts

@@ -0,0 +1,34 @@
+/**
+ * agentadmit/auth.ts
+ * Token validation, scope enforcement, and audit logging for Express.
+ */
+import { Request, Response, NextFunction } from 'express';
+import { StorageBackend } from './storage';
+export declare function setStorage(storage: StorageBackend): void;
+export declare function setUserVerifier(fn: (token: string) => string | Promise<string>): void;
+export interface AgentContext {
+    auth_type: 'agent' | 'user';
+    user: Record<string, any>;
+    connection: Record<string, any> | null;
+    scopes: string[];
+}
+/**
+ * Validate an ag_at_ token and return the agent context.
+ */
+export declare function validateAgentToken(token: string): Promise<Omit<AgentContext, 'auth_type'>>;
+/**
+ * Express middleware: require a specific scope (agent-only).
+ */
+export declare function requireScope(scope: string): (req: Request, res: Response, next: NextFunction) => Promise<Response<any, Record<string, any>> | undefined>;
+/**
+ * Express middleware: enforce scope only if caller is an agent.
+ */
+export declare function requireScopeIfAgent(scope: string): (req: Request, res: Response, next: NextFunction) => Promise<void | Response<any, Record<string, any>>>;
+/**
+ * Express middleware: resolve user or agent from token.
+ */
+export declare function resolveAuth(): (req: Request, res: Response, next: NextFunction) => Promise<void | Response<any, Record<string, any>>>;
+/**
+ * Check connection cap for tier enforcement.
+ */
+export declare function checkConnectionCap(userId: string, tier: string): Promise<void>;

package/dist/auth.js

@@ -0,0 +1,305 @@
+"use strict";
+/**
+ * agentadmit/auth.ts
+ * Token validation, scope enforcement, and audit logging for Express.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setStorage = setStorage;
+exports.setUserVerifier = setUserVerifier;
+exports.validateAgentToken = validateAgentToken;
+exports.requireScope = requireScope;
+exports.requireScopeIfAgent = requireScopeIfAgent;
+exports.resolveAuth = resolveAuth;
+exports.checkConnectionCap = checkConnectionCap;
+const config_1 = require("./config");
+const errors_1 = require("./errors");
+let _storage = null;
+let _verifyUserToken = null;
+function setStorage(storage) {
+    _storage = storage;
+}
+function setUserVerifier(fn) {
+    _verifyUserToken = fn;
+}
+function getStorage() {
+    if (!_storage)
+        throw new Error('AgentAdmit storage not initialized');
+    return _storage;
+}
+function getBearerToken(req) {
+    const auth = req.headers.authorization || '';
+    if (auth.startsWith('Bearer '))
+        return auth.slice(7);
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Rate-limit retry helpers
+// ---------------------------------------------------------------------------
+/** Parse an integer from an HTTP response header. Returns null if missing or invalid. */
+function parseIntHeader(headers, name) {
+    const val = headers.get(name);
+    if (val === null)
+        return null;
+    const n = parseInt(val, 10);
+    return Number.isFinite(n) ? n : null;
+}
+/** Parse a float from an HTTP response header. Returns null if missing or invalid. */
+function parseFloatHeader(headers, name) {
+    const val = headers.get(name);
+    if (val === null)
+        return null;
+    const n = parseFloat(val);
+    return Number.isFinite(n) ? n : null;
+}
+/** sleep for `ms` milliseconds */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * POST to the AgentAdmit introspection endpoint with automatic 429 retry.
+ *
+ * Retry policy:
+ *   - Initial delay: 1 second
+ *   - Each retry doubles the delay, capped at 30 seconds
+ *   - Each delay adds 0–500 ms of random jitter
+ *   - Honors Retry-After header if present
+ *   - After maxRetries exhausted, throws RateLimitError
+ */
+async function introspectWithRetry(verifyUrl, token, appId, apiKey, maxRetries) {
+    let delay = 1000; // ms
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        let response;
+        try {
+            response = await fetch(verifyUrl, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ token }),
+            });
+        }
+        catch (err) {
+            throw new Error(`AgentAdmit introspection failed (network): ${err.message}`);
+        }
+        if (response.status !== 429) {
+            return response;
+        }
+        // --- 429 handling ---
+        const retryAfter = parseFloatHeader(response.headers, 'Retry-After');
+        const limit = parseIntHeader(response.headers, 'X-RateLimit-Limit');
+        const remaining = parseIntHeader(response.headers, 'X-RateLimit-Remaining');
+        const reset = parseIntHeader(response.headers, 'X-RateLimit-Reset');
+        if (attempt >= maxRetries) {
+            throw new errors_1.RateLimitError({
+                message: `AgentAdmit rate limit exceeded. Max retries (${maxRetries}) exhausted.`,
+                retryAfter,
+                limit,
+                remaining,
+                reset,
+            });
+        }
+        const waitMs = retryAfter !== null ? retryAfter * 1000 : Math.min(delay, 30000);
+        const jitterMs = Math.random() * 500; // 0–500 ms
+        const totalWaitMs = waitMs + jitterMs;
+        console.warn(`[AgentAdmit] Rate-limited (attempt ${attempt + 1}/${maxRetries}). ` +
+            `Retrying in ${(totalWaitMs / 1000).toFixed(2)}s.`);
+        await sleep(totalWaitMs);
+        delay = Math.min(delay * 2, 30000);
+    }
+    // Should never be reached
+    throw new Error('Unexpected exit from retry loop');
+}
+// ---------------------------------------------------------------------------
+/**
+ * Validate an ag_at_ token and return the agent context.
+ */
+async function validateAgentToken(token) {
+    const config = (0, config_1.getConfig)();
+    if (!token.startsWith(config.token_prefix_access)) {
+        throw new Error('Not an AgentAdmit access token');
+    }
+    // MANDATORY INTROSPECTION — validate via AgentAdmit hosted service
+    // No local JWT decode. Every verification call goes through AgentAdmit.
+    const verifyUrl = config.agentadmit_verify_url || 'https://api.agentadmit.com/v1/verify';
+    const appId = config.app_id;
+    const apiKey = config.api_key || '';
+    const maxRetries = config.max_retries ?? 3;
+    // introspectWithRetry handles 429 with exponential backoff + jitter.
+    // RateLimitError propagates to the caller when retries are exhausted.
+    const response = await introspectWithRetry(verifyUrl, token, appId, apiKey, maxRetries);
+    if (response.status === 401) {
+        const errData = (await response.json().catch(() => ({})));
+        throw new Error(errData.error_description || 'Token validation failed');
+    }
+    if (response.status !== 200) {
+        throw new Error(`Verification service returned ${response.status}`);
+    }
+    const data = (await response.json());
+    // Check active flag (RFC 7662 introspection pattern).
+    // The verify endpoint returns {active: false} with HTTP 200 for invalid/
+    // expired/revoked tokens. Without this check, we'd read empty scopes.
+    if (!data.active) {
+        const reason = data.error || 'invalid_token';
+        throw new Error(`Token is not active: ${reason}`);
+    }
+    const scopes = data.scopes || [];
+    const userId = data.user_id;
+    const connectionId = data.connection_id;
+    if (!userId) {
+        throw new Error('Introspection returned no user');
+    }
+    // User lookup from app's local database (if storage is configured)
+    let user = { [config.user_lookup_field]: userId };
+    try {
+        const storage = getStorage();
+        const localUser = await storage.getUser(userId, config.user_lookup_field);
+        if (localUser)
+            user = localUser;
+    }
+    catch { }
+    const connection = {
+        connection_id: connectionId,
+        scopes,
+        agent_label: data.agent_label || 'Unknown Agent',
+    };
+    return { user, connection, scopes };
+}
+/**
+ * Express middleware: require a specific scope (agent-only).
+ */
+function requireScope(scope) {
+    return async (req, res, next) => {
+        const token = getBearerToken(req);
+        const config = (0, config_1.getConfig)();
+        if (!token || !token.startsWith(config.token_prefix_access)) {
+            return res.status(401).json({ error: 'invalid_token', error_description: 'AgentAdmit token required' });
+        }
+        try {
+            const ctx = await validateAgentToken(token);
+            if (!ctx.scopes.includes(scope)) {
+                return res.status(403).json({
+                    error: 'insufficient_scope',
+                    required_scope: scope,
+                    granted_scopes: ctx.scopes,
+                });
+            }
+            await logAccess(ctx, scope, req);
+            req.agentAdmit = { auth_type: 'agent', ...ctx };
+            next();
+        }
+        catch (err) {
+            return res.status(401).json({ error: 'invalid_token', error_description: err.message });
+        }
+    };
+}
+/**
+ * Express middleware: enforce scope only if caller is an agent.
+ */
+function requireScopeIfAgent(scope) {
+    return async (req, res, next) => {
+        const token = getBearerToken(req);
+        const config = (0, config_1.getConfig)();
+        if (!token || !token.startsWith(config.token_prefix_access)) {
+            return next(); // Not an agent — pass through
+        }
+        try {
+            const ctx = await validateAgentToken(token);
+            if (!ctx.scopes.includes(scope)) {
+                return res.status(403).json({
+                    error: 'insufficient_scope',
+                    required_scope: scope,
+                    granted_scopes: ctx.scopes,
+                });
+            }
+            await logAccess(ctx, scope, req);
+            req.agentAdmit = { auth_type: 'agent', ...ctx };
+            next();
+        }
+        catch (err) {
+            return res.status(401).json({ error: 'invalid_token', error_description: err.message });
+        }
+    };
+}
+/**
+ * Express middleware: resolve user or agent from token.
+ */
+function resolveAuth() {
+    return async (req, res, next) => {
+        const token = getBearerToken(req);
+        const config = (0, config_1.getConfig)();
+        if (!token) {
+            return res.status(401).json({ error: 'not_authenticated' });
+        }
+        if (token.startsWith(config.token_prefix_access)) {
+            try {
+                const ctx = await validateAgentToken(token);
+                req.agentAdmit = { auth_type: 'agent', ...ctx };
+                return next();
+            }
+            catch (err) {
+                return res.status(401).json({ error: 'invalid_token', error_description: err.message });
+            }
+        }
+        // Regular user token
+        if (!_verifyUserToken) {
+            return res.status(500).json({ error: 'server_error', error_description: 'User token verifier not configured' });
+        }
+        try {
+            const userId = await _verifyUserToken(token);
+            const storage = getStorage();
+            const user = await storage.getUser(userId, config.user_lookup_field);
+            if (!user) {
+                return res.status(404).json({ error: 'user_not_found' });
+            }
+            req.agentAdmit = { auth_type: 'user', user, scopes: ['*'], connection: null };
+            next();
+        }
+        catch {
+            return res.status(401).json({ error: 'invalid_token' });
+        }
+    };
+}
+/**
+ * Write audit log entry.
+ */
+async function logAccess(ctx, scope, req) {
+    try {
+        const config = (0, config_1.getConfig)();
+        const storage = getStorage();
+        await storage.logAccess({
+            timestamp: new Date(),
+            connection_id: ctx.connection?.connection_id || 'unknown',
+            user_id: ctx.user?.[config.user_lookup_field] || 'unknown',
+            scope_used: scope,
+            resource: req.path,
+            method: req.method,
+            agent_label: ctx.connection?.agent_label || 'Unknown Agent',
+        });
+    }
+    catch (err) {
+        console.error('[AgentAdmit] Audit log failed:', err);
+    }
+}
+/**
+ * Check connection cap for tier enforcement.
+ */
+async function checkConnectionCap(userId, tier) {
+    const { getTierLimits } = require('./config');
+    const limits = getTierLimits(tier);
+    if (!limits?.hard_cap)
+        return;
+    const storage = getStorage();
+    const count = await storage.countActiveConnections(userId);
+    if (count >= limits.connections_limit) {
+        const err = new Error(`Connection limit reached (${count}/${limits.connections_limit})`);
+        err.statusCode = 429;
+        err.detail = {
+            error: 'connection_limit_reached',
+            connections_used: count,
+            connections_limit: limits.connections_limit,
+            tier,
+        };
+        throw err;
+    }
+}