@agentadmit/sdk 1.0.0 → 1.1.0

package/src/errors.ts

@@ -1,50 +0,0 @@
-/**
- * agentadmit/errors.ts
- * Custom error types for the AgentAdmit Node.js SDK.
- */
-
-/**
- * Thrown when the AgentAdmit introspection endpoint returns HTTP 429
- * and all retry attempts (with exponential backoff) have been exhausted.
- *
- * @example
- * ```ts
- * import { validateAgentToken, RateLimitError } from '@agentadmit/sdk';
- *
- * try {
- *   await validateAgentToken(token);
- * } catch (err) {
- *   if (err instanceof RateLimitError) {
- *     res.status(429).json({
- *       error: 'rate_limited',
- *       retry_after: err.retryAfter,
- *     });
- *   }
- * }
- * ```
- */
-export class RateLimitError extends Error {
-  /** Seconds to wait before retrying (from Retry-After header), or null. */
-  readonly retryAfter: number | null;
-  /** Total request limit for the current window (X-RateLimit-Limit), or null. */
-  readonly limit: number | null;
-  /** Requests remaining in the current window (X-RateLimit-Remaining), or null. */
-  readonly remaining: number | null;
-  /** Unix timestamp when the rate limit window resets (X-RateLimit-Reset), or null. */
-  readonly reset: number | null;
-
-  constructor(options: {
-    message?: string;
-    retryAfter?: number | null;
-    limit?: number | null;
-    remaining?: number | null;
-    reset?: number | null;
-  } = {}) {
-    super(options.message ?? 'AgentAdmit rate limit exceeded. Max retries exhausted.');
-    this.name = 'RateLimitError';
-    this.retryAfter = options.retryAfter ?? null;
-    this.limit = options.limit ?? null;
-    this.remaining = options.remaining ?? null;
-    this.reset = options.reset ?? null;
-  }
-}

package/src/index.ts

@@ -1,27 +0,0 @@
-/**
- * @agentadmit/sdk — Node.js SDK for AgentAdmit
- * 
- * User-mediated AI agent authorization. Plug-and-play for Express and Next.js.
- */
-
-export { loadConfig, getConfig, getScopeMetadata, getDurationOptions, getTierLimits } from './config';
-export type { AgentAdmitConfig, ScopeDefinition, DurationOption, TierDefinition, StorageConfig } from './config';
-
-export { generateKeyPair, loadPrivateKey, loadPublicKey } from './keys';
-
-export { StorageBackend, MongoDBStorage, MemoryStorage, createStorage } from './storage';
-
-export {
-  validateAgentToken,
-  requireScope,
-  requireScopeIfAgent,
-  resolveAuth,
-  checkConnectionCap,
-  setStorage,
-  setUserVerifier,
-} from './auth';
-export type { AgentContext } from './auth';
-
-export { createAgentAdmitRouter } from './routes';
-
-export { RateLimitError } from './errors';

package/src/keys.ts

@@ -1,33 +0,0 @@
-/**
- * agentadmit/keys.ts
- *
- * DEPRECATED — AgentAdmit is a hosted service.
- *
- * All cryptographic operations (key generation, JWT signing, JWKS serving)
- * are performed by the AgentAdmit hosted service. The SDK does NOT generate
- * or load RSA key pairs. Calling any function in this module will throw.
- */
-
-export function generateKeyPair(_outputDir?: string): never {
-  throw new Error(
-    '[AgentAdmit] generateKeyPair() is not supported. ' +
-    'AgentAdmit is a hosted service — all key management is handled server-side. ' +
-    'Remove any calls to generateKeyPair() from your codebase.',
-  );
-}
-
-export function loadPrivateKey(_keyPath?: string): never {
-  throw new Error(
-    '[AgentAdmit] loadPrivateKey() is not supported. ' +
-    'AgentAdmit is a hosted service — JWT signing is handled by the hosted service. ' +
-    'Remove any calls to loadPrivateKey() from your codebase.',
-  );
-}
-
-export function loadPublicKey(_keyPath?: string): never {
-  throw new Error(
-    '[AgentAdmit] loadPublicKey() is not supported. ' +
-    'AgentAdmit is a hosted service — token verification uses hosted introspection. ' +
-    'Remove any calls to loadPublicKey() from your codebase.',
-  );
-}

package/src/routes.ts

@@ -1,245 +0,0 @@
-/**
- * agentadmit/routes.ts
- * Express router with all AgentAdmit endpoints.
- *
- * ALL token operations go through the AgentAdmit hosted service. The SDK does
- * NOT sign JWTs, generate RSA keys, or serve JWKS endpoints. The hosted service
- * owns all cryptographic operations.
- */
-
-import { Router, Request, Response } from 'express';
-import { randomBytes } from 'crypto';
-import { getConfig, getScopeMetadata, getDurationOptions } from './config';
-import { StorageBackend } from './storage';
-import { checkConnectionCap } from './auth';
-
-const AGENTADMIT_VERSION = '0.1';
-
-interface RouterOptions {
-  storage: StorageBackend;
-  getCurrentUser: (req: Request) => Promise<Record<string, any> | null>;
-  determineRole?: (user: Record<string, any>) => string;
-  getUserTier?: (user: Record<string, any>) => string;
-  validateScopes?: (scopes: string[], user: Record<string, any>) => { valid: boolean; invalid: string[] };
-  getEndpointsForScopes?: (scopes: string[]) => Record<string, any>[];
-}
-
-/**
- * Make an authenticated request to the AgentAdmit hosted service.
- */
-async function callHostedService(
-  path: string,
-  body: Record<string, any>,
-): Promise<{ status: number; data: any }> {
-  const config = getConfig();
-  const url = `${config.agentadmit_api_url.replace(/\/$/, '')}${path}`;
-
-  const resp = await fetch(url, {
-    method: 'POST',
-    headers: {
-      'Authorization': `Bearer ${config.api_key}`,
-      'Content-Type': 'application/json',
-      'X-App-Id': config.app_id,
-    },
-    body: JSON.stringify(body),
-  });
-
-  const data = await resp.json().catch(() => ({}));
-  return { status: resp.status, data };
-}
-
-export function createAgentAdmitRouter(options: RouterOptions): { wellknownRouter: Router; agentadmitRouter: Router } {
-  const config = getConfig();
-  const { storage, getCurrentUser } = options;
-  const determineRole = options.determineRole || (() => 'user');
-  const getUserTier = options.getUserTier || (() => config.default_tier);
-  const getEndpointsForScopes = options.getEndpointsForScopes || (() => []);
-
-  const validateScopes = options.validateScopes || ((scopes: string[]) => {
-    const validNames = new Set(config.scopes.map(s => s.name));
-    const invalid = scopes.filter(s => !validNames.has(s));
-    return { valid: invalid.length === 0, invalid };
-  });
-
-  const wellknownRouter = Router();
-  const agentadmitRouter = Router();
-
-  // Discovery
-  wellknownRouter.get('/.well-known/agentadmit', (_req: Request, res: Response) => {
-    const base = config.api_base_url.replace(/\/$/, '');
-    res.json({
-      agentadmit_version: AGENTADMIT_VERSION,
-      issuer: base,
-      app_name: config.app_name,
-      app_id: config.app_id,
-      api_base_url: base,
-      agentadmit_service_url: config.agentadmit_api_url,
-      scopes_endpoint: `${base}${config.route_prefix}/scopes`,
-      discovery_endpoint: `${base}${config.route_prefix}/discovery`,
-      connections_endpoint: `${base}${config.route_prefix}/connections`,
-      scopes_supported: config.scopes.map(s => s.name),
-      roles_supported: [...new Set(config.scopes.map(s => s.role || 'user'))],
-      duration_options: getDurationOptions(),
-    });
-  });
-
-  // Scopes
-  agentadmitRouter.get('/scopes', (_req: Request, res: Response) => {
-    res.json({
-      scopes: getScopeMetadata(),
-      roles: [...new Set(config.scopes.map(s => s.role || 'user'))],
-    });
-  });
-
-  // Durations
-  agentadmitRouter.get('/durations', (_req: Request, res: Response) => {
-    res.json({ durations: getDurationOptions() });
-  });
-
-  // Generate connection token — calls hosted service
-  agentadmitRouter.post('/connections/generate-token', async (req: Request, res: Response) => {
-    try {
-      const currentUser = await getCurrentUser(req);
-      if (!currentUser) return res.status(401).json({ error: 'unauthorized' });
-
-      const { scopes, duration_seconds, label } = req.body;
-      if (!scopes || !Array.isArray(scopes)) {
-        return res.status(400).json({ error: 'invalid_request', error_description: 'scopes array required' });
-      }
-
-      const validation = validateScopes(scopes, currentUser);
-      if (!validation.valid) {
-        return res.status(400).json({ error: 'invalid_scope', invalid_scopes: validation.invalid });
-      }
-
-      const duration = duration_seconds || config.connection_token_ttl;
-      const userId = currentUser[config.user_lookup_field];
-      const role = determineRole(currentUser);
-      const userTier = getUserTier(currentUser);
-
-      await checkConnectionCap(userId, userTier);
-
-      // Call AgentAdmit hosted service
-      const { status, data } = await callHostedService(`/api/v1/apps/${config.app_id}/token`, {
-        user_id: String(userId),
-        scopes,
-        duration_hours: Math.max(1, Math.floor(duration / 3600)),
-        label: label ?? null,
-        user_role: role,
-        metadata: { subscription_tier: userTier, app_name: config.app_name },
-      });
-
-      if (status !== 200 && status !== 201) {
-        console.error('[AgentAdmit] Hosted token generation failed:', status, data);
-        return res.status(502).json({ error: 'token_generation_failed', error_description: 'Authorization service could not generate token' });
-      }
-
-      // Store local record
-      // Use hosted service's connection_id if provided; generate a local fallback
-      // to prevent duplicate-key errors when hosting service omits it.
-      await storage.storeConnection({
-        connection_id: data.connection_id || `conn_${randomBytes(16).toString('base64url')}`,
-        user_id: String(userId),
-        scopes,
-        role,
-        agent_label: label,
-        duration_seconds: duration,
-        status: 'active',
-      });
-
-      res.json({
-        connection_token: data.token || data.connection_token,
-        expires_in: duration,
-        scopes,
-      });
-    } catch (err: any) {
-      console.error('[AgentAdmit] Generate token error:', err);
-      res.status(500).json({ error: 'server_error', error_description: err.message });
-    }
-  });
-
-  // Token exchange — forwards to hosted service
-  agentadmitRouter.post('/token', async (req: Request, res: Response) => {
-    try {
-      const { grant_type, connection_token, agent_id, agent_label, agent_metadata } = req.body;
-
-      if (grant_type !== 'connection_token') {
-        return res.status(400).json({ error: 'unsupported_grant_type' });
-      }
-      if (!connection_token) {
-        return res.status(400).json({ error: 'invalid_request', error_description: 'connection_token required' });
-      }
-
-      // Forward to AgentAdmit hosted service
-      const { status, data } = await callHostedService('/api/v1/exchange', {
-        token: connection_token,
-        agent_label: agent_label ?? null,
-        agent_id: agent_id ?? null,
-        agent_metadata: agent_metadata ?? null,
-      });
-
-      if (status !== 200) {
-        return res.status(status < 500 ? status : 502).json(data);
-      }
-
-      // Add endpoint map if available
-      if (getEndpointsForScopes && data.scopes) {
-        data.endpoints = getEndpointsForScopes(data.scopes);
-      }
-
-      res.json(data);
-    } catch (err: any) {
-      const status = err.statusCode || 500;
-      res.status(status).json(err.detail || { error: 'server_error', error_description: err.message });
-    }
-  });
-
-  // List connections
-  agentadmitRouter.get('/connections', async (req: Request, res: Response) => {
-    try {
-      const currentUser = await getCurrentUser(req);
-      if (!currentUser) return res.status(401).json({ error: 'unauthorized' });
-
-      const userId = currentUser[config.user_lookup_field];
-      const connections = await storage.listConnections(userId);
-      res.json({ connections, total: connections.length });
-    } catch {
-      res.status(500).json({ error: 'server_error' });
-    }
-  });
-
-  // Delete connection — also notifies hosted service
-  agentadmitRouter.delete('/connections/:connectionId', async (req: Request, res: Response) => {
-    try {
-      const currentUser = await getCurrentUser(req);
-      if (!currentUser) return res.status(401).json({ error: 'unauthorized' });
-
-      const userId = currentUser[config.user_lookup_field];
-      const conn = await storage.getConnection(req.params.connectionId);
-
-      if (!conn || conn.user_id !== String(userId)) {
-        return res.status(404).json({ error: 'not_found' });
-      }
-      if (conn.status !== 'active') {
-        return res.status(400).json({ error: 'already_revoked' });
-      }
-
-      // Notify hosted service
-      try {
-        await callHostedService('/api/v1/revoke', {
-          connection_id: req.params.connectionId,
-          reason: 'user_requested',
-        });
-      } catch (e) {
-        console.warn('[AgentAdmit] Hosted revoke failed, revoking locally:', e);
-      }
-
-      await storage.revokeConnection(req.params.connectionId);
-      res.json({ revoked: true, connection_id: req.params.connectionId });
-    } catch {
-      res.status(500).json({ error: 'server_error' });
-    }
-  });
-
-  return { wellknownRouter, agentadmitRouter };
-}

package/src/storage.ts

@@ -1,228 +0,0 @@
-/**
- * agentadmit/storage.ts
- * Abstract storage interface + MongoDB + Memory implementations.
- */
-
-export interface StorageBackend {
-  storeConnection(connection: Record<string, any>): Promise<void>;
-  getConnection(connectionId: string): Promise<Record<string, any> | null>;
-  getActiveConnection(connectionId: string): Promise<Record<string, any> | null>;
-  updateConnection(connectionId: string, updates: Record<string, any>): Promise<boolean>;
-  revokeConnection(connectionId: string): Promise<boolean>;
-  listConnections(userId: string): Promise<Record<string, any>[]>;
-  countActiveConnections(userId: string): Promise<number>;
-  storeToken(tokenRecord: Record<string, any>): Promise<void>;
-  getToken(tokenHash: string): Promise<Record<string, any> | null>;
-  markTokenUsed(tokenHash: string): Promise<boolean>;
-  logAccess(entry: Record<string, any>): Promise<void>;
-  countAuditCalls(userId: string, periodStart: Date, periodEnd: Date): Promise<number>;
-  getUser(userId: string, lookupField: string): Promise<Record<string, any> | null>;
-}
-
-export class MongoDBStorage implements StorageBackend {
-  private db: any;
-  private connections: any;
-  private auditLog: any;
-  private tokens: any;
-  private users: any = null;
-
-  constructor(
-    uri: string,
-    database: string,
-    connectionsCollection: string,
-    auditLogCollection: string,
-    tokensCollection: string,
-  ) {
-    // Lazy import to keep mongodb as optional peer dep
-    const { MongoClient } = require('mongodb');
-    const client = new MongoClient(uri);
-    this.db = client.db(database);
-    this.connections = this.db.collection(connectionsCollection);
-    this.auditLog = this.db.collection(auditLogCollection);
-    this.tokens = this.db.collection(tokensCollection);
-
-    // Create indexes
-    this.connections.createIndex({ connection_id: 1 }, { unique: true }).catch(() => {});
-    this.connections.createIndex({ user_id: 1, status: 1 }).catch(() => {});
-    this.tokens.createIndex({ token_hash: 1 }, { unique: true }).catch(() => {});
-    this.auditLog.createIndex({ user_id: 1, timestamp: -1 }).catch(() => {});
-
-    console.log(`[AgentAdmit] MongoDB storage initialized: ${database}`);
-  }
-
-  setUsersCollection(name: string) {
-    this.users = this.db.collection(name);
-  }
-
-  async storeConnection(connection: Record<string, any>): Promise<void> {
-    await this.connections.insertOne(connection);
-  }
-
-  async getConnection(connectionId: string): Promise<Record<string, any> | null> {
-    return this.connections.findOne({ connection_id: connectionId });
-  }
-
-  async getActiveConnection(connectionId: string): Promise<Record<string, any> | null> {
-    return this.connections.findOne({ connection_id: connectionId, status: 'active' });
-  }
-
-  async updateConnection(connectionId: string, updates: Record<string, any>): Promise<boolean> {
-    const result = await this.connections.updateOne(
-      { connection_id: connectionId },
-      { $set: updates },
-    );
-    return result.modifiedCount > 0;
-  }
-
-  async revokeConnection(connectionId: string): Promise<boolean> {
-    const result = await this.connections.updateOne(
-      { connection_id: connectionId, status: 'active' },
-      { $set: { status: 'revoked', revoked_at: new Date() } },
-    );
-    return result.modifiedCount > 0;
-  }
-
-  async listConnections(userId: string): Promise<Record<string, any>[]> {
-    return this.connections.find({ user_id: userId }, { projection: { _id: 0 } }).sort({ created_at: -1 }).toArray();
-  }
-
-  async countActiveConnections(userId: string): Promise<number> {
-    return this.connections.countDocuments({ user_id: userId, status: 'active' });
-  }
-
-  async storeToken(tokenRecord: Record<string, any>): Promise<void> {
-    await this.tokens.insertOne(tokenRecord);
-  }
-
-  async getToken(tokenHash: string): Promise<Record<string, any> | null> {
-    return this.tokens.findOne({ token_hash: tokenHash });
-  }
-
-  async markTokenUsed(tokenHash: string): Promise<boolean> {
-    const result = await this.tokens.updateOne(
-      { token_hash: tokenHash, used: false },
-      { $set: { used: true, used_at: new Date() } },
-    );
-    return result.modifiedCount > 0;
-  }
-
-  async logAccess(entry: Record<string, any>): Promise<void> {
-    try {
-      await this.auditLog.insertOne(entry);
-    } catch (err) {
-      console.error('[AgentAdmit] Audit log failed:', err);
-    }
-  }
-
-  async countAuditCalls(userId: string, periodStart: Date, periodEnd: Date): Promise<number> {
-    return this.auditLog.countDocuments({
-      user_id: userId,
-      timestamp: { $gte: periodStart, $lt: periodEnd },
-    });
-  }
-
-  async getUser(userId: string, lookupField: string = 'user_id'): Promise<Record<string, any> | null> {
-    if (!this.users) return null;
-    return this.users.findOne({ [lookupField]: userId });
-  }
-}
-
-export class MemoryStorage implements StorageBackend {
-  private _connections: Map<string, Record<string, any>> = new Map();
-  private _tokens: Map<string, Record<string, any>> = new Map();
-  private _auditLog: Record<string, any>[] = [];
-  private _users: Map<string, Record<string, any>> = new Map();
-
-  async storeConnection(connection: Record<string, any>): Promise<void> {
-    this._connections.set(connection.connection_id, connection);
-  }
-
-  async getConnection(connectionId: string): Promise<Record<string, any> | null> {
-    return this._connections.get(connectionId) || null;
-  }
-
-  async getActiveConnection(connectionId: string): Promise<Record<string, any> | null> {
-    const conn = this._connections.get(connectionId);
-    return conn?.status === 'active' ? conn : null;
-  }
-
-  async updateConnection(connectionId: string, updates: Record<string, any>): Promise<boolean> {
-    const conn = this._connections.get(connectionId);
-    if (!conn) return false;
-    Object.assign(conn, updates);
-    return true;
-  }
-
-  async revokeConnection(connectionId: string): Promise<boolean> {
-    const conn = this._connections.get(connectionId);
-    if (!conn || conn.status !== 'active') return false;
-    conn.status = 'revoked';
-    conn.revoked_at = new Date();
-    return true;
-  }
-
-  async listConnections(userId: string): Promise<Record<string, any>[]> {
-    return Array.from(this._connections.values()).filter(c => c.user_id === userId);
-  }
-
-  async countActiveConnections(userId: string): Promise<number> {
-    return Array.from(this._connections.values()).filter(c => c.user_id === userId && c.status === 'active').length;
-  }
-
-  async storeToken(tokenRecord: Record<string, any>): Promise<void> {
-    this._tokens.set(tokenRecord.token_hash, tokenRecord);
-  }
-
-  async getToken(tokenHash: string): Promise<Record<string, any> | null> {
-    return this._tokens.get(tokenHash) || null;
-  }
-
-  async markTokenUsed(tokenHash: string): Promise<boolean> {
-    const token = this._tokens.get(tokenHash);
-    if (!token || token.used) return false;
-    token.used = true;
-    token.used_at = new Date();
-    return true;
-  }
-
-  async logAccess(entry: Record<string, any>): Promise<void> {
-    this._auditLog.push(entry);
-  }
-
-  async countAuditCalls(userId: string, periodStart: Date, periodEnd: Date): Promise<number> {
-    return this._auditLog.filter(e =>
-      e.user_id === userId &&
-      e.timestamp >= periodStart &&
-      e.timestamp < periodEnd
-    ).length;
-  }
-
-  async getUser(userId: string, lookupField: string = 'user_id'): Promise<Record<string, any> | null> {
-    return this._users.get(userId) || null;
-  }
-
-  addTestUser(userId: string, data: Record<string, any>): void {
-    this._users.set(userId, data);
-  }
-}
-
-export function createStorage(config: any): StorageBackend {
-  const backend = config.storage?.backend || 'mongodb';
-
-  if (backend === 'mongodb') {
-    const s = new MongoDBStorage(
-      config.storage.uri,
-      config.storage.database,
-      config.storage.connections_collection || 'agentadmit_connections',
-      config.storage.audit_log_collection || 'agentadmit_audit_log',
-      config.storage.tokens_collection || 'agentadmit_tokens',
-    );
-    return s;
-  }
-
-  if (backend === 'memory') {
-    return new MemoryStorage();
-  }
-
-  throw new Error(`Unsupported storage backend: ${backend}`);
-}

package/tsconfig.json

@@ -1,19 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "commonjs",
-    "lib": ["ES2020"],
-    "declaration": true,
-    "strict": true,
-    "noImplicitAny": true,
-    "strictNullChecks": true,
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "tests"]
-}