@agentadmit/sdk 1.0.0 → 1.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentadmit/sdk",
-  "version": "1.0.0",
-  "description": "AgentAdmit SDK \u2014 User-mediated AI agent authorization for Node.js apps",
+  "version": "1.1.0",
+  "description": "AgentAdmit SDK — User-mediated AI agent authorization for Node.js apps",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
@@ -16,8 +16,8 @@
     "mongodb": "6.0.0"
   },
   "devDependencies": {
-    "typescript": "5.3.0",
-    "@types/node": "20.0.0",
+    "typescript": "5.9.3",
+    "@types/node": "22.19.20",
     "@types/jsonwebtoken": "9.0.0",
     "@types/js-yaml": "4.0.0",
     "@types/uuid": "9.0.0",
@@ -34,6 +34,13 @@
       "optional": true
     }
   },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "roots": [
+      "<rootDir>/tests"
+    ]
+  },
   "license": "SEE LICENSE IN LICENSE",
   "author": "Christopher Emerson",
   "repository": {

package/tests/webhooks.test.ts

@@ -0,0 +1,109 @@
+/** Tests for src/webhooks.ts — X-AgentAdmit-Signature verification. */
+
+import { createHmac } from 'crypto';
+import {
+  isValidWebhookSignature,
+  verifyWebhookSignature,
+  WebhookSignatureError,
+} from '../src/webhooks';
+
+const SECRET = 'whsec_test123';
+const PAYLOAD = Buffer.from('{"event":"agentadmit.alert","alert_type":"usage_spike"}');
+const NOW = 1750000000;
+
+function sign(payload: Buffer, secret = SECRET, timestamp = NOW): string {
+  const digest = createHmac('sha256', secret)
+    .update(`${timestamp}.`)
+    .update(payload)
+    .digest('hex');
+  return `t=${timestamp},v1=${digest}`;
+}
+
+describe('verifyWebhookSignature', () => {
+  it('accepts a valid signature', () => {
+    expect(() =>
+      verifyWebhookSignature(PAYLOAD, sign(PAYLOAD), SECRET, { now: NOW }),
+    ).not.toThrow();
+  });
+
+  it('accepts a string payload', () => {
+    expect(() =>
+      verifyWebhookSignature(PAYLOAD.toString(), sign(PAYLOAD), SECRET, { now: NOW }),
+    ).not.toThrow();
+  });
+
+  it('rejects a tampered payload', () => {
+    expect(() =>
+      verifyWebhookSignature(Buffer.concat([PAYLOAD, Buffer.from(' ')]), sign(PAYLOAD), SECRET, { now: NOW }),
+    ).toThrow(WebhookSignatureError);
+  });
+
+  it('rejects a signature made with the wrong secret', () => {
+    expect(() =>
+      verifyWebhookSignature(PAYLOAD, sign(PAYLOAD, 'whsec_other456'), SECRET, { now: NOW }),
+    ).toThrow('verification failed');
+  });
+
+  it('rejects a stale timestamp', () => {
+    expect(() =>
+      verifyWebhookSignature(PAYLOAD, sign(PAYLOAD, SECRET, NOW - 600), SECRET, { now: NOW }),
+    ).toThrow('tolerance');
+  });
+
+  it('rejects a future timestamp', () => {
+    expect(() =>
+      verifyWebhookSignature(PAYLOAD, sign(PAYLOAD, SECRET, NOW + 600), SECRET, { now: NOW }),
+    ).toThrow('tolerance');
+  });
+
+  it('accepts a timestamp within tolerance', () => {
+    expect(() =>
+      verifyWebhookSignature(PAYLOAD, sign(PAYLOAD, SECRET, NOW - 200), SECRET, { now: NOW }),
+    ).not.toThrow();
+  });
+
+  it('skips the timestamp check when tolerance is 0', () => {
+    expect(() =>
+      verifyWebhookSignature(PAYLOAD, sign(PAYLOAD, SECRET, NOW - 99999), SECRET, {
+        toleranceSeconds: 0,
+        now: NOW,
+      }),
+    ).not.toThrow();
+  });
+
+  it('rejects a missing header', () => {
+    expect(() => verifyWebhookSignature(PAYLOAD, '', SECRET, { now: NOW })).toThrow('Missing');
+  });
+
+  it.each(['nonsense', 't=abc,v1=def', 't=123', 'v1=abc'])(
+    'rejects malformed header %p',
+    header => {
+      expect(() => verifyWebhookSignature(PAYLOAD, header, SECRET, { now: NOW })).toThrow(
+        'Malformed',
+      );
+    },
+  );
+
+  it('rejects a missing secret', () => {
+    expect(() => verifyWebhookSignature(PAYLOAD, sign(PAYLOAD), '', { now: NOW })).toThrow(
+      'secret',
+    );
+  });
+
+  it('accepts when any v1 candidate matches', () => {
+    expect(() =>
+      verifyWebhookSignature(PAYLOAD, `${sign(PAYLOAD)},v1=deadbeef`, SECRET, { now: NOW }),
+    ).not.toThrow();
+  });
+});
+
+describe('isValidWebhookSignature', () => {
+  it('returns booleans instead of throwing', () => {
+    expect(isValidWebhookSignature(PAYLOAD, sign(PAYLOAD), SECRET, { now: NOW })).toBe(true);
+    expect(
+      isValidWebhookSignature(Buffer.concat([PAYLOAD, Buffer.from('x')]), sign(PAYLOAD), SECRET, {
+        now: NOW,
+      }),
+    ).toBe(false);
+  });
+});

package/.github/workflows/publish.yml

@@ -1,53 +0,0 @@
-# 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/src/auth.ts

@@ -1,356 +0,0 @@
-/**
- * agentadmit/auth.ts
- * Token validation, scope enforcement, and audit logging for Express.
- */
-
-import { Request, Response, NextFunction } from 'express';
-import jwt from 'jsonwebtoken';
-import { getConfig } from './config';
-import { loadPublicKey } from './keys';
-import { StorageBackend } from './storage';
-import { RateLimitError } from './errors';
-
-let _storage: StorageBackend | null = null;
-let _verifyUserToken: ((token: string) => string | Promise<string>) | null = null;
-
-export function setStorage(storage: StorageBackend) {
-  _storage = storage;
-}
-
-export function setUserVerifier(fn: (token: string) => string | Promise<string>) {
-  _verifyUserToken = fn;
-}
-
-function getStorage(): StorageBackend {
-  if (!_storage) throw new Error('AgentAdmit storage not initialized');
-  return _storage;
-}
-
-function getBearerToken(req: Request): string | null {
-  const auth = req.headers.authorization || '';
-  if (auth.startsWith('Bearer ')) return auth.slice(7);
-  return null;
-}
-
-export interface AgentContext {
-  auth_type: 'agent' | 'user';
-  user: Record<string, any>;
-  connection: Record<string, any> | null;
-  scopes: string[];
-}
-
-// ---------------------------------------------------------------------------
-// Rate-limit retry helpers
-// ---------------------------------------------------------------------------
-
-/** Parse an integer from an HTTP response header. Returns null if missing or invalid. */
-function parseIntHeader(headers: Headers, name: string): number | null {
-  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: Headers, name: string): number | null {
-  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: number): Promise<void> {
-  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: string,
-  token: string,
-  appId: string,
-  apiKey: string,
-  maxRetries: number,
-): Promise<globalThis.Response> {
-  let delay = 1000; // ms
-
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    let response: globalThis.Response;
-    try {
-      response = await fetch(verifyUrl, {
-        method: 'POST',
-        headers: {
-          Authorization: `Bearer ${apiKey}`,
-          'Content-Type': 'application/json',
-        },
-        body: JSON.stringify({ token }),
-      });
-    } catch (err: any) {
-      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 RateLimitError({
-        message: `AgentAdmit rate limit exceeded. Max retries (${maxRetries}) exhausted.`,
-        retryAfter,
-        limit,
-        remaining,
-        reset,
-      });
-    }
-
-    const waitMs = retryAfter !== null ? retryAfter * 1000 : Math.min(delay, 30_000);
-    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, 30_000);
-  }
-
-  // Should never be reached
-  throw new Error('Unexpected exit from retry loop');
-}
-
-// ---------------------------------------------------------------------------
-
-/**
- * Validate an ag_at_ token and return the agent context.
- */
-export async function validateAgentToken(token: string): Promise<Omit<AgentContext, 'auth_type'>> {
-  const config = 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 as any).agentadmit_verify_url || 'https://api.agentadmit.com/v1/verify';
-  const appId = config.app_id;
-  const apiKey = (config as any).api_key || '';
-  const maxRetries = (config as any).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(() => ({}))) as Record<string, string>;
-    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()) as Record<string, any>;
-
-  // 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: string[] = data.scopes || [];
-  const userId: string = data.user_id;
-  const connectionId: string = 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: Record<string, any> = { [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).
- */
-export function requireScope(scope: string) {
-  return async (req: Request, res: Response, next: NextFunction) => {
-    const token = getBearerToken(req);
-    const config = 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 as any).agentAdmit = { auth_type: 'agent', ...ctx };
-      next();
-    } catch (err: any) {
-      return res.status(401).json({ error: 'invalid_token', error_description: err.message });
-    }
-  };
-}
-
-/**
- * Express middleware: enforce scope only if caller is an agent.
- */
-export function requireScopeIfAgent(scope: string) {
-  return async (req: Request, res: Response, next: NextFunction) => {
-    const token = getBearerToken(req);
-    const config = 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 as any).agentAdmit = { auth_type: 'agent', ...ctx };
-      next();
-    } catch (err: any) {
-      return res.status(401).json({ error: 'invalid_token', error_description: err.message });
-    }
-  };
-}
-
-/**
- * Express middleware: resolve user or agent from token.
- */
-export function resolveAuth() {
-  return async (req: Request, res: Response, next: NextFunction) => {
-    const token = getBearerToken(req);
-    const config = 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 as any).agentAdmit = { auth_type: 'agent', ...ctx };
-        return next();
-      } catch (err: any) {
-        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 as any).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: { connection: Record<string, any> | null; user: Record<string, any> },
-  scope: string,
-  req: Request,
-): Promise<void> {
-  try {
-    const config = 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.
- */
-export async function checkConnectionCap(userId: string, tier: string): Promise<void> {
-  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: any = 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;
-  }
-}

package/src/config.ts

@@ -1,150 +0,0 @@
-/**
- * agentadmit/config.ts
- * Configuration loader for AgentAdmit Node.js SDK.
- *
- * IMPORTANT: AgentAdmit uses MANDATORY hosted 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.
- */
-
-import fs from 'fs';
-import path from 'path';
-import yaml from 'js-yaml';
-
-export interface ScopeDefinition {
-  name: string;
-  description: string;
-  category?: string;
-  role?: string;
-}
-
-export interface DurationOption {
-  label: string;
-  seconds: number | null; // null = "until revoked"
-}
-
-export interface TierDefinition {
-  name: string;
-  connections_limit: number;
-  api_calls_monthly?: number;
-  hard_cap: boolean;
-  overage_per_thousand?: number;
-}
-
-export interface StorageConfig {
-  backend: 'mongodb' | 'memory';
-  uri?: string;
-  database?: string;
-  connections_collection?: string;
-  audit_log_collection?: string;
-  tokens_collection?: string;
-}
-
-export interface AgentAdmitConfig {
-  app_name: string;
-  app_id: string;
-  api_key: string;
-  api_base_url: string;
-  agentadmit_api_url: string;
-  agentadmit_verify_url: string;
-  token_prefix_connection: string;
-  token_prefix_access: string;
-  algorithm: string;
-  audience: string;
-  connection_token_ttl: number;
-  scopes: ScopeDefinition[];
-  durations: DurationOption[];
-  tiers: TierDefinition[];
-  default_tier: string;
-  storage: StorageConfig;
-  route_prefix: string;
-  discovery_path: string;
-  user_lookup_field: string;
-  private_key_path: string;
-  public_key_path: string;
-  /** Max retries on 429 before throwing RateLimitError. Default: 3. */
-  max_retries: number;
-}
-
-const DEFAULT_CONFIG: Partial<AgentAdmitConfig> = {
-  app_name: 'My App',
-  app_id: '',
-  api_key: '',
-  api_base_url: 'http://localhost:3000',
-  agentadmit_api_url: 'https://api.agentadmit.com',
-  agentadmit_verify_url: 'https://api.agentadmit.com/v1/verify',
-  token_prefix_connection: 'ag_ct_',
-  token_prefix_access: 'ag_at_',
-  algorithm: 'RS256',
-  audience: 'agentadmit',
-  connection_token_ttl: 900,
-  scopes: [],
-  durations: [
-    { label: '1 Hour', seconds: 3600 },
-    { label: '24 Hours', seconds: 86400 },
-    { label: '7 Days', seconds: 604800 },
-    { label: '30 Days', seconds: 2592000 },
-    { label: 'Until I Revoke', seconds: null },
-  ],
-  tiers: [
-    { name: 'trial', connections_limit: 3, hard_cap: true },
-    { name: 'standard', connections_limit: 100, api_calls_monthly: 2000000, hard_cap: false },
-  ],
-  default_tier: 'standard',
-  storage: {
-    backend: 'mongodb',
-    uri: 'mongodb://localhost:27017',
-    database: 'agentadmit',
-    connections_collection: 'agentadmit_connections',
-    audit_log_collection: 'agentadmit_audit_log',
-    tokens_collection: 'agentadmit_tokens',
-  },
-  route_prefix: '/agentadmit',
-  discovery_path: '/.well-known/agentadmit',
-  user_lookup_field: 'user_id',
-  max_retries: 3,
-};
-
-let _config: AgentAdmitConfig | null = null;
-
-export function loadConfig(configPath: string = 'agentadmit.yaml'): AgentAdmitConfig {
-  let resolvedPath = configPath;
-
-  if (!fs.existsSync(resolvedPath)) {
-    const envPath = process.env.AGENTADMIT_CONFIG;
-    if (envPath && fs.existsSync(envPath)) {
-      resolvedPath = envPath;
-    } else {
-      throw new Error(
-        `Config file not found: ${configPath}. Run 'agentadmit init' to generate one.`
-      );
-    }
-  }
-
-  const raw = yaml.load(fs.readFileSync(resolvedPath, 'utf-8')) as Record<string, any> || {};
-  _config = { ...DEFAULT_CONFIG, ...raw } as AgentAdmitConfig;
-
-  console.log(`[AgentAdmit] Config loaded: ${resolvedPath} (${_config.scopes.length} scopes)`);
-  return _config;
-}
-
-export function getConfig(): AgentAdmitConfig {
-  if (!_config) {
-    throw new Error('AgentAdmit config not loaded. Call loadConfig() first.');
-  }
-  return _config;
-}
-
-export function getScopeMetadata(): ScopeDefinition[] {
-  return getConfig().scopes;
-}
-
-export function getDurationOptions(): DurationOption[] {
-  return getConfig().durations;
-}
-
-export function getTierLimits(tierName: string): TierDefinition | undefined {
-  const config = getConfig();
-  return config.tiers.find(t => t.name === tierName) || config.tiers.find(t => t.name === config.default_tier);
-}