@agentadmit/sdk 1.0.0 → 1.1.0

package/README.md

@@ -201,3 +201,72 @@ For complete compliance guidance, see our [compliance guide](https://agentadmit.
 ## License
 
 All rights reserved. Patent pending.
+
+## Security Alerts
+
+Monitor suspicious agent activity. Six alert types:
+- `volume_spike`, `failed_scope_attempts`, `burst_pattern`,
+- `stale_reactivation`, `new_scope_usage`, `revoked_connection_attempt`
+
+### Configure Alert Thresholds
+
+```typescript
+import { configureAlerts } from '@agentadmit/sdk';
+
+await configureAlerts({
+  app_id: 'app_abc123',
+  alert_type: 'volume_spike',
+  enabled: true,
+  threshold_value: 100,
+  threshold_window_minutes: 5,
+  kill_switch_enabled: true,
+});
+```
+
+### List Alert Events
+
+```typescript
+import { listAlerts } from '@agentadmit/sdk';
+const { events, total } = await listAlerts({ app_id: 'app_abc123', alert_type: 'volume_spike' });
+```
+
+### Get Current Config
+
+```typescript
+import { getAlertConfig } from '@agentadmit/sdk';
+const config = await getAlertConfig({ app_id: 'app_abc123' });
+```
+
+
+### Notifying Your Users
+
+AgentAdmit detects anomalies, fires alerts, and (with kill switch) auto-revokes connections. **How you notify your own users is up to you.** AgentAdmit provides the data — you deliver it through your own system (in-app notifications, email, push, etc.).
+
+- **Poll alerts** — Use the SDK methods above from your backend to check for new events, then notify users through your existing system.
+- **Webhook delivery** — Configure a webhook URL in your AgentAdmit dashboard. When an alert fires, AgentAdmit POSTs the payload to your server, signed with your `whsec_…` secret. Always verify the signature against the **raw** request body before trusting the payload:
+
+  ```ts
+  import express from 'express';
+  import { verifyWebhookSignature, WebhookSignatureError } from '@agentadmit/sdk';
+
+  app.post('/agentadmit/alerts', express.raw({ type: 'application/json' }), (req, res) => {
+    try {
+      verifyWebhookSignature(
+        req.body, // raw Buffer
+        req.header('X-AgentAdmit-Signature') ?? '',
+        process.env.AGENTADMIT_WEBHOOK_SECRET!, // whsec_…
+      );
+    } catch (err) {
+      if (err instanceof WebhookSignatureError) {
+        return res.status(400).json({ error: 'invalid_signature' });
+      }
+      throw err;
+    }
+    const event = JSON.parse(req.body.toString('utf-8'));
+    // ...
+    res.sendStatus(200);
+  });
+  ```
+
+  The header format is `t=<unix_ts>,v1=<hex>` — an HMAC-SHA256 of `${t}.${rawBody}` keyed with your signing secret. The helper compares in constant time and rejects timestamps more than 5 minutes off (replay protection).
+- **React SDK** — Embed the `<AlertsPanel>` component so users can view their own alert history and tighten thresholds.

package/dist/alerts.d.ts

@@ -0,0 +1,93 @@
+/**
+ * agentadmit/alerts.ts
+ * Alert configuration and event management for the AgentAdmit hosted service.
+ *
+ * Usage:
+ *   import { configureAlerts, listAlerts, getAlertConfig } from '@agentadmit/sdk';
+ *
+ *   // Configure a volume spike alert
+ *   const result = await configureAlerts({
+ *     app_id: 'app_abc123',
+ *     alert_type: 'volume_spike',
+ *     enabled: true,
+ *     threshold_value: 100,
+ *     threshold_window_minutes: 5,
+ *   });
+ *
+ *   // List alert events
+ *   const events = await listAlerts({ app_id: 'app_abc123', alert_type: 'volume_spike' });
+ *
+ *   // Get current config
+ *   const config = await getAlertConfig({ app_id: 'app_abc123' });
+ */
+/** The 6 supported alert types. */
+export declare const ALERT_TYPES: readonly ["volume_spike", "failed_scope_attempts", "burst_pattern", "stale_reactivation", "new_scope_usage", "revoked_connection_attempt"];
+export type AlertType = typeof ALERT_TYPES[number];
+export interface ConfigureAlertsOptions {
+    app_id: string;
+    alert_type: AlertType | string;
+    connection_id?: string;
+    enabled?: boolean;
+    threshold_value?: number;
+    threshold_window_minutes?: number;
+    threshold_rate_per_minute?: number;
+    stale_days?: number;
+    kill_switch_enabled?: boolean;
+    kill_switch_threshold_value?: number;
+    kill_switch_threshold_window_minutes?: number;
+}
+export interface ListAlertsOptions {
+    app_id: string;
+    connection_id?: string;
+    alert_type?: AlertType | string;
+    limit?: number;
+    offset?: number;
+}
+export interface GetAlertConfigOptions {
+    app_id: string;
+    connection_id?: string;
+}
+export interface AlertEvent {
+    id?: string;
+    app_id: string;
+    connection_id?: string;
+    alert_type: string;
+    triggered_at: string;
+    details?: Record<string, any>;
+}
+export interface AlertEventsResponse {
+    events: AlertEvent[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+export interface AlertConfigResponse {
+    app_id: string;
+    app_level: Record<string, any>;
+    connection_overrides: Record<string, Record<string, any>>;
+    alert_types: string[];
+}
+/**
+ * Configure alert thresholds for an app or connection.
+ *
+ * @param options - Alert configuration options.
+ * @returns { ok: true, config: {...} }
+ */
+export declare function configureAlerts(options: ConfigureAlertsOptions): Promise<{
+    ok: true;
+    config: Record<string, any>;
+}>;
+/**
+ * List alert events for an app.
+ *
+ * @param options - Filter and pagination options.
+ * @returns { events: [...], total, limit, offset }
+ */
+export declare function listAlerts(options: ListAlertsOptions): Promise<AlertEventsResponse>;
+/**
+ * Get the current alert configuration for an app.
+ *
+ * @param options - App ID and optional connection ID.
+ * @returns Current alert config with app-level and connection-level settings.
+ */
+export declare function getAlertConfig(options: GetAlertConfigOptions): Promise<AlertConfigResponse>;

package/dist/alerts.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * agentadmit/alerts.ts
+ * Alert configuration and event management for the AgentAdmit hosted service.
+ *
+ * Usage:
+ *   import { configureAlerts, listAlerts, getAlertConfig } from '@agentadmit/sdk';
+ *
+ *   // Configure a volume spike alert
+ *   const result = await configureAlerts({
+ *     app_id: 'app_abc123',
+ *     alert_type: 'volume_spike',
+ *     enabled: true,
+ *     threshold_value: 100,
+ *     threshold_window_minutes: 5,
+ *   });
+ *
+ *   // List alert events
+ *   const events = await listAlerts({ app_id: 'app_abc123', alert_type: 'volume_spike' });
+ *
+ *   // Get current config
+ *   const config = await getAlertConfig({ app_id: 'app_abc123' });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALERT_TYPES = void 0;
+exports.configureAlerts = configureAlerts;
+exports.listAlerts = listAlerts;
+exports.getAlertConfig = getAlertConfig;
+const config_1 = require("./config");
+/** The 6 supported alert types. */
+exports.ALERT_TYPES = [
+    'volume_spike',
+    'failed_scope_attempts',
+    'burst_pattern',
+    'stale_reactivation',
+    'new_scope_usage',
+    'revoked_connection_attempt',
+];
+/**
+ * Make an authenticated request to the AgentAdmit hosted service.
+ * Supports GET (with query string) and POST (with JSON body).
+ */
+async function callHostedService(method, path, body) {
+    const config = (0, config_1.getConfig)();
+    const url = `${config.agentadmit_api_url.replace(/\/$/, '')}${path}`;
+    const resp = await fetch(url, {
+        method,
+        headers: {
+            Authorization: `Bearer ${config.api_key}`,
+            'Content-Type': 'application/json',
+            'X-App-Id': config.app_id,
+        },
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    });
+    if (!resp.ok) {
+        const errData = await resp.json().catch(() => ({}));
+        const err = new Error(errData.error_description || errData.error || `HTTP ${resp.status}`);
+        err.status = resp.status;
+        err.data = errData;
+        throw err;
+    }
+    return resp.json();
+}
+/**
+ * Configure alert thresholds for an app or connection.
+ *
+ * @param options - Alert configuration options.
+ * @returns { ok: true, config: {...} }
+ */
+async function configureAlerts(options) {
+    // Remove undefined values
+    const body = Object.fromEntries(Object.entries(options).filter(([, v]) => v !== undefined));
+    return callHostedService('POST', '/api/v1/alerts', body);
+}
+/**
+ * List alert events for an app.
+ *
+ * @param options - Filter and pagination options.
+ * @returns { events: [...], total, limit, offset }
+ */
+async function listAlerts(options) {
+    const params = new URLSearchParams({ app_id: options.app_id });
+    if (options.connection_id)
+        params.set('connection_id', options.connection_id);
+    if (options.alert_type)
+        params.set('alert_type', options.alert_type);
+    if (options.limit !== undefined)
+        params.set('limit', String(options.limit));
+    if (options.offset !== undefined)
+        params.set('offset', String(options.offset));
+    return callHostedService('GET', `/api/v1/alerts?${params}`);
+}
+/**
+ * Get the current alert configuration for an app.
+ *
+ * @param options - App ID and optional connection ID.
+ * @returns Current alert config with app-level and connection-level settings.
+ */
+async function getAlertConfig(options) {
+    const params = new URLSearchParams({ app_id: options.app_id });
+    if (options.connection_id)
+        params.set('connection_id', options.connection_id);
+    return callHostedService('GET', `/api/v1/alerts/config?${params}`);
+}

package/dist/auth.d.ts

@@ -12,6 +12,29 @@ export interface AgentContext {
     connection: Record<string, any> | null;
     scopes: string[];
 }
+/**
+ * Error codes the hosted /api/v1/verify endpoint returns with HTTP 200 and
+ * `active: false`. Unknown codes pass through as plain strings.
+ */
+export declare const VERIFY_ERROR_CODES: readonly ["invalid_token", "token_expired", "token_revoked", "connection_revoked", "connection_expired", "environment_mismatch", "insufficient_scope"];
+export type VerifyErrorCode = (typeof VERIFY_ERROR_CODES)[number];
+/** Successful introspection result from /api/v1/verify. */
+export interface VerifyActive {
+    active: true;
+    sub?: string;
+    user_id?: string;
+    connection_id?: string;
+    scopes?: string[];
+    role?: string;
+    app_id?: string;
+    jti?: string;
+    exp?: number;
+}
+/** Failed (but non-fatal) introspection result — HTTP 200, active: false. */
+export interface VerifyInactive {
+    active: false;
+    error?: VerifyErrorCode | (string & {});
+}
 /**
  * Validate an ag_at_ token and return the agent context.
  */
@@ -19,15 +42,15 @@ export declare function validateAgentToken(token: string): Promise<Omit<AgentCon
 /**
  * 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>;
+export declare function requireScope(scope: string): (req: Request, res: Response, next: NextFunction) => Promise<Response | 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>>>;
+export declare function requireScopeIfAgent(scope: string): (req: Request, res: Response, next: NextFunction) => Promise<void | Response>;
 /**
  * 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>>>;
+export declare function resolveAuth(): (req: Request, res: Response, next: NextFunction) => Promise<void | Response>;
 /**
  * Check connection cap for tier enforcement.
  */

package/dist/auth.js

@@ -4,6 +4,7 @@
  * Token validation, scope enforcement, and audit logging for Express.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERIFY_ERROR_CODES = void 0;
 exports.setStorage = setStorage;
 exports.setUserVerifier = setUserVerifier;
 exports.validateAgentToken = validateAgentToken;
@@ -32,6 +33,19 @@ function getBearerToken(req) {
         return auth.slice(7);
     return null;
 }
+/**
+ * Error codes the hosted /api/v1/verify endpoint returns with HTTP 200 and
+ * `active: false`. Unknown codes pass through as plain strings.
+ */
+exports.VERIFY_ERROR_CODES = [
+    'invalid_token',
+    'token_expired',
+    'token_revoked',
+    'connection_revoked',
+    'connection_expired',
+    'environment_mismatch',
+    'insufficient_scope',
+];
 // ---------------------------------------------------------------------------
 // Rate-limit retry helpers
 // ---------------------------------------------------------------------------
@@ -121,7 +135,7 @@ async function validateAgentToken(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 verifyUrl = config.agentadmit_verify_url || 'https://api.agentadmit.com/api/v1/verify';
     const appId = config.app_id;
     const apiKey = config.api_key || '';
     const maxRetries = config.max_retries ?? 3;
@@ -135,10 +149,13 @@ async function validateAgentToken(token) {
     if (response.status !== 200) {
         throw new Error(`Verification service returned ${response.status}`);
     }
+    // Shape: VerifyActive | VerifyInactive (kept loose for forward-compat).
     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.
+    // expired/revoked tokens (error is one of VERIFY_ERROR_CODES, e.g.
+    // token_expired, connection_expired, environment_mismatch). 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}`);

package/dist/config.js

@@ -25,7 +25,7 @@ const DEFAULT_CONFIG = {
     api_key: '',
     api_base_url: 'http://localhost:3000',
     agentadmit_api_url: 'https://api.agentadmit.com',
-    agentadmit_verify_url: 'https://api.agentadmit.com/v1/verify',
+    agentadmit_verify_url: 'https://api.agentadmit.com/api/v1/verify',
     token_prefix_connection: 'ag_ct_',
     token_prefix_access: 'ag_at_',
     algorithm: 'RS256',
@@ -71,6 +71,10 @@ function loadConfig(configPath = 'agentadmit.yaml') {
     }
     const raw = js_yaml_1.default.load(fs_1.default.readFileSync(resolvedPath, 'utf-8')) || {};
     _config = { ...DEFAULT_CONFIG, ...raw };
+    // Validate the key prefix without ever echoing the key itself.
+    if (_config.api_key && !/^aa_(test|live)_/.test(_config.api_key)) {
+        throw new Error("Invalid api_key: must start with 'aa_test_' or 'aa_live_'");
+    }
     console.log(`[AgentAdmit] Config loaded: ${resolvedPath} (${_config.scopes.length} scopes)`);
     return _config;
 }

package/dist/index.d.ts

@@ -7,7 +7,11 @@ export { loadConfig, getConfig, getScopeMetadata, getDurationOptions, getTierLim
 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 { validateAgentToken, requireScope, requireScopeIfAgent, resolveAuth, checkConnectionCap, setStorage, setUserVerifier, VERIFY_ERROR_CODES, } from './auth';
+export type { AgentContext, VerifyErrorCode, VerifyActive, VerifyInactive } from './auth';
+export { verifyWebhookSignature, isValidWebhookSignature, WebhookSignatureError, SIGNATURE_HEADER, DEFAULT_TOLERANCE_SECONDS, } from './webhooks';
+export type { VerifyWebhookSignatureOptions } from './webhooks';
 export { createAgentAdmitRouter } from './routes';
 export { RateLimitError } from './errors';
+export { configureAlerts, listAlerts, getAlertConfig, ALERT_TYPES, } from './alerts';
+export type { AlertType, ConfigureAlertsOptions, ListAlertsOptions, GetAlertConfigOptions, AlertEvent, AlertEventsResponse, AlertConfigResponse, } from './alerts';

package/dist/index.js

@@ -5,7 +5,7 @@
  * User-mediated AI agent authorization. Plug-and-play for Express and Next.js.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RateLimitError = exports.createAgentAdmitRouter = exports.setUserVerifier = exports.setStorage = exports.checkConnectionCap = exports.resolveAuth = exports.requireScopeIfAgent = exports.requireScope = exports.validateAgentToken = exports.createStorage = exports.MemoryStorage = exports.MongoDBStorage = exports.loadPublicKey = exports.loadPrivateKey = exports.generateKeyPair = exports.getTierLimits = exports.getDurationOptions = exports.getScopeMetadata = exports.getConfig = exports.loadConfig = void 0;
+exports.ALERT_TYPES = exports.getAlertConfig = exports.listAlerts = exports.configureAlerts = exports.RateLimitError = exports.createAgentAdmitRouter = exports.DEFAULT_TOLERANCE_SECONDS = exports.SIGNATURE_HEADER = exports.WebhookSignatureError = exports.isValidWebhookSignature = exports.verifyWebhookSignature = exports.VERIFY_ERROR_CODES = exports.setUserVerifier = exports.setStorage = exports.checkConnectionCap = exports.resolveAuth = exports.requireScopeIfAgent = exports.requireScope = exports.validateAgentToken = exports.createStorage = exports.MemoryStorage = exports.MongoDBStorage = exports.loadPublicKey = exports.loadPrivateKey = exports.generateKeyPair = exports.getTierLimits = exports.getDurationOptions = exports.getScopeMetadata = exports.getConfig = exports.loadConfig = void 0;
 var config_1 = require("./config");
 Object.defineProperty(exports, "loadConfig", { enumerable: true, get: function () { return config_1.loadConfig; } });
 Object.defineProperty(exports, "getConfig", { enumerable: true, get: function () { return config_1.getConfig; } });
@@ -28,7 +28,19 @@ Object.defineProperty(exports, "resolveAuth", { enumerable: true, get: function
 Object.defineProperty(exports, "checkConnectionCap", { enumerable: true, get: function () { return auth_1.checkConnectionCap; } });
 Object.defineProperty(exports, "setStorage", { enumerable: true, get: function () { return auth_1.setStorage; } });
 Object.defineProperty(exports, "setUserVerifier", { enumerable: true, get: function () { return auth_1.setUserVerifier; } });
+Object.defineProperty(exports, "VERIFY_ERROR_CODES", { enumerable: true, get: function () { return auth_1.VERIFY_ERROR_CODES; } });
+var webhooks_1 = require("./webhooks");
+Object.defineProperty(exports, "verifyWebhookSignature", { enumerable: true, get: function () { return webhooks_1.verifyWebhookSignature; } });
+Object.defineProperty(exports, "isValidWebhookSignature", { enumerable: true, get: function () { return webhooks_1.isValidWebhookSignature; } });
+Object.defineProperty(exports, "WebhookSignatureError", { enumerable: true, get: function () { return webhooks_1.WebhookSignatureError; } });
+Object.defineProperty(exports, "SIGNATURE_HEADER", { enumerable: true, get: function () { return webhooks_1.SIGNATURE_HEADER; } });
+Object.defineProperty(exports, "DEFAULT_TOLERANCE_SECONDS", { enumerable: true, get: function () { return webhooks_1.DEFAULT_TOLERANCE_SECONDS; } });
 var routes_1 = require("./routes");
 Object.defineProperty(exports, "createAgentAdmitRouter", { enumerable: true, get: function () { return routes_1.createAgentAdmitRouter; } });
 var errors_1 = require("./errors");
 Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_1.RateLimitError; } });
+var alerts_1 = require("./alerts");
+Object.defineProperty(exports, "configureAlerts", { enumerable: true, get: function () { return alerts_1.configureAlerts; } });
+Object.defineProperty(exports, "listAlerts", { enumerable: true, get: function () { return alerts_1.listAlerts; } });
+Object.defineProperty(exports, "getAlertConfig", { enumerable: true, get: function () { return alerts_1.getAlertConfig; } });
+Object.defineProperty(exports, "ALERT_TYPES", { enumerable: true, get: function () { return alerts_1.ALERT_TYPES; } });

package/dist/routes.js

@@ -15,18 +15,23 @@ const config_1 = require("./config");
 const auth_1 = require("./auth");
 const AGENTADMIT_VERSION = '0.1';
 /**
- * Make an authenticated request to the AgentAdmit hosted service.
+ * Make a request to the AgentAdmit hosted service. Authenticated with the
+ * operator API key, except for /exchange (authenticated: false) where the
+ * connection token itself is the credential.
  */
-async function callHostedService(path, body) {
+async function callHostedService(path, body, options = {}) {
     const config = (0, config_1.getConfig)();
     const url = `${config.agentadmit_api_url.replace(/\/$/, '')}${path}`;
+    const headers = {
+        'Content-Type': 'application/json',
+        'X-App-Id': config.app_id,
+    };
+    if (options.authenticated !== false) {
+        headers['Authorization'] = `Bearer ${config.api_key}`;
+    }
     const resp = await fetch(url, {
         method: 'POST',
-        headers: {
-            'Authorization': `Bearer ${config.api_key}`,
-            'Content-Type': 'application/json',
-            'X-App-Id': config.app_id,
-        },
+        headers,
         body: JSON.stringify(body),
     });
     const data = await resp.json().catch(() => ({}));
@@ -88,20 +93,22 @@ function createAgentAdmitRouter(options) {
             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 (0, auth_1.checkConnectionCap)(userId, userTier);
-            // Call AgentAdmit hosted service
-            const { status, data } = await callHostedService(`/api/v1/apps/${config.app_id}/token`, {
+            // Call AgentAdmit hosted service. duration_seconds is tri-state:
+            // key absent → hosted default (30 days); explicit null → until
+            // revoked; integer 60–31536000 → explicit duration.
+            const issueBody = {
                 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 },
-            });
+                role,
+            };
+            if ('duration_seconds' in req.body) {
+                issueBody.duration_seconds = duration_seconds ?? null;
+            }
+            const { status, data } = await callHostedService(`/api/v1/apps/${config.app_id}/token`, issueBody);
             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' });
@@ -115,12 +122,12 @@ function createAgentAdmitRouter(options) {
                 scopes,
                 role,
                 agent_label: label,
-                duration_seconds: duration,
+                duration_seconds: 'duration_seconds' in req.body ? duration_seconds ?? null : null,
                 status: 'active',
             });
             res.json({
-                connection_token: data.token || data.connection_token,
-                expires_in: duration,
+                connection_token: data.token,
+                expires_in: data.expires_in ?? config.connection_token_ttl,
                 scopes,
             });
         }
@@ -139,13 +146,14 @@ function createAgentAdmitRouter(options) {
             if (!connection_token) {
                 return res.status(400).json({ error: 'invalid_request', error_description: 'connection_token required' });
             }
-            // Forward to AgentAdmit hosted service
+            // Forward to AgentAdmit hosted service. No API key on this call —
+            // the connection token is the credential.
             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,
-            });
+            }, { authenticated: false });
             if (status !== 200) {
                 return res.status(status < 500 ? status : 502).json(data);
             }

package/dist/webhooks.d.ts

@@ -0,0 +1,37 @@
+/**
+ * agentadmit/webhooks.ts
+ * Verification for inbound AgentAdmit alert webhooks.
+ *
+ * AgentAdmit signs every alert webhook delivery with the app's webhook
+ * signing secret (`whsec_…`, returned once when the webhook URL is
+ * configured). The signature arrives in the `X-AgentAdmit-Signature` header:
+ *
+ *     X-AgentAdmit-Signature: t=<unix_ts>,v1=<hex hmac-sha256>
+ *
+ * where the HMAC input is `${t}.${rawBody}` keyed with the full whsec_
+ * secret. Always verify against the raw request body, before JSON parsing
+ * (use `express.raw()` or capture the body with a verify hook).
+ */
+export declare const SIGNATURE_HEADER = "X-AgentAdmit-Signature";
+export declare const DEFAULT_TOLERANCE_SECONDS = 300;
+export declare class WebhookSignatureError extends Error {
+    constructor(message?: string);
+}
+export interface VerifyWebhookSignatureOptions {
+    /**
+     * Maximum allowed clock skew (seconds) between the signature timestamp and
+     * now; deliveries outside the window are rejected to prevent replay.
+     * Set to 0 to disable. Default: 300.
+     */
+    toleranceSeconds?: number;
+    /** Override the current unix timestamp (for tests). */
+    now?: number;
+}
+/**
+ * Verify the X-AgentAdmit-Signature header on an inbound alert webhook.
+ * Throws WebhookSignatureError on any failure; the message never includes
+ * the secret or the payload.
+ */
+export declare function verifyWebhookSignature(payload: string | Buffer, signatureHeader: string, secret: string, options?: VerifyWebhookSignatureOptions): void;
+/** Boolean form of verifyWebhookSignature(). */
+export declare function isValidWebhookSignature(payload: string | Buffer, signatureHeader: string, secret: string, options?: VerifyWebhookSignatureOptions): boolean;

package/dist/webhooks.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * agentadmit/webhooks.ts
+ * Verification for inbound AgentAdmit alert webhooks.
+ *
+ * AgentAdmit signs every alert webhook delivery with the app's webhook
+ * signing secret (`whsec_…`, returned once when the webhook URL is
+ * configured). The signature arrives in the `X-AgentAdmit-Signature` header:
+ *
+ *     X-AgentAdmit-Signature: t=<unix_ts>,v1=<hex hmac-sha256>
+ *
+ * where the HMAC input is `${t}.${rawBody}` keyed with the full whsec_
+ * secret. Always verify against the raw request body, before JSON parsing
+ * (use `express.raw()` or capture the body with a verify hook).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookSignatureError = exports.DEFAULT_TOLERANCE_SECONDS = exports.SIGNATURE_HEADER = void 0;
+exports.verifyWebhookSignature = verifyWebhookSignature;
+exports.isValidWebhookSignature = isValidWebhookSignature;
+const crypto_1 = require("crypto");
+exports.SIGNATURE_HEADER = 'X-AgentAdmit-Signature';
+exports.DEFAULT_TOLERANCE_SECONDS = 300;
+class WebhookSignatureError extends Error {
+    constructor(message = 'Webhook signature verification failed') {
+        super(message);
+        this.name = 'WebhookSignatureError';
+    }
+}
+exports.WebhookSignatureError = WebhookSignatureError;
+/**
+ * Verify the X-AgentAdmit-Signature header on an inbound alert webhook.
+ * Throws WebhookSignatureError on any failure; the message never includes
+ * the secret or the payload.
+ */
+function verifyWebhookSignature(payload, signatureHeader, secret, options = {}) {
+    const { toleranceSeconds = exports.DEFAULT_TOLERANCE_SECONDS, now } = options;
+    if (!secret)
+        throw new WebhookSignatureError('Webhook signing secret is required');
+    if (!signatureHeader)
+        throw new WebhookSignatureError('Missing X-AgentAdmit-Signature header');
+    const body = Buffer.isBuffer(payload) ? payload : Buffer.from(payload, 'utf-8');
+    let timestamp = null;
+    const candidates = [];
+    for (const part of signatureHeader.split(',')) {
+        const eq = part.indexOf('=');
+        if (eq === -1)
+            continue;
+        const key = part.slice(0, eq).trim();
+        const value = part.slice(eq + 1).trim();
+        if (key === 't') {
+            timestamp = /^\d+$/.test(value) ? parseInt(value, 10) : null;
+            if (timestamp === null)
+                throw new WebhookSignatureError('Malformed signature header');
+        }
+        else if (key === 'v1') {
+            candidates.push(value);
+        }
+    }
+    if (timestamp === null || candidates.length === 0) {
+        throw new WebhookSignatureError('Malformed signature header');
+    }
+    if (toleranceSeconds) {
+        const current = now ?? Math.floor(Date.now() / 1000);
+        if (Math.abs(current - timestamp) > toleranceSeconds) {
+            throw new WebhookSignatureError('Signature timestamp outside tolerance window');
+        }
+    }
+    const expected = (0, crypto_1.createHmac)('sha256', secret)
+        .update(`${timestamp}.`)
+        .update(body)
+        .digest('hex');
+    const expectedBuf = Buffer.from(expected, 'utf-8');
+    const matched = candidates.some(candidate => {
+        const candidateBuf = Buffer.from(candidate, 'utf-8');
+        return candidateBuf.length === expectedBuf.length && (0, crypto_1.timingSafeEqual)(candidateBuf, expectedBuf);
+    });
+    if (!matched) {
+        throw new WebhookSignatureError('Signature verification failed');
+    }
+}
+/** Boolean form of verifyWebhookSignature(). */
+function isValidWebhookSignature(payload, signatureHeader, secret, options = {}) {
+    try {
+        verifyWebhookSignature(payload, signatureHeader, secret, options);
+        return true;
+    }
+    catch (err) {
+        if (err instanceof WebhookSignatureError)
+            return false;
+        throw err;
+    }
+}