@agentsbloom/sdk 0.2.0 → 0.4.0

package/index.d.ts

@@ -16,19 +16,62 @@ export interface AgentAction {
 export interface AgentsBloomConfig {
   apiKey?: string | null;
   agentSecret?: string | null;
+  /**
+   * Previous shared secret, kept verify-live during AGENTSBLOOM_SECRET
+   * rotation so in-flight signed requests survive the window. Falls back
+   * to the AGENTSBLOOM_SECRET_PREVIOUS environment variable.
+   */
+  agentSecretPrevious?: string | null;
   name?: string;
   description?: string;
   actions?: Record<string, AgentAction>;
   llmsDoc?: string;
   baseUrl?: string;
-  corsOrigin?: string;
+  /**
+   * v4: when set, only requests whose Host header matches one of these
+   * values get Host-derived discovery URLs; any other Host falls back to
+   * `baseUrl`. Prevents Host-header poisoning of discovery documents.
+   */
+  allowedHosts?: string[];
+  /**
+   * v4 medium pass: string behaves as before; an ARRAY is an exact-match
+   * allow-list - matching Origins are reflected (Vary: Origin), everything
+   * else receives no Access-Control-Allow-Origin at all.
+   */
+  corsOrigin?: string | string[];
+  /** v4 medium pass (V10): body-size cap in bytes, enforced against the
+   *  received bytes as well as Content-Length (default 1 MiB). */
+  maxBodyBytes?: number;
+  /**
+   * v4 medium pass (V11): per-agent legacy-HMAC secrets keyed by
+   * X-Agent-Identifier. Checked before the shared `agentSecret` fallback.
+   */
+  agentKeys?: Record<string, string>;
+  /** v4 medium pass (V11): identifiers rejected outright before verification. */
+  revokedIdentifiers?: string[];
+  /**
+   * v4 medium pass (V12): per-action authorization. 'authenticated'
+   * requires a verified RFC/legacy signature identity even for reads.
+   */
+  actionAccess?: Record<string, 'anonymous' | 'authenticated'>;
+  /**
+   * v4 medium pass (V12): per-action identity allow-lists. Entries match
+   * exactly (`rfc:key-1`) or by prefix when ending with ':' (`legacy:`).
+   */
+  actionIdentities?: Record<string, string[]>;
   merchantJwks?: Record<string, unknown>;
+  /**
+   * v4: RFC 9421 verification now FAILS CLOSED - one of `agentJwks` or
+   * `agentJwksUrl` must be configured for Signature-header writes to verify.
+   */
   agentJwks?: {
     keys: Array<Record<string, unknown>>;
   };
   agentJwksUrl?: string;
   signature?: {
     maxAgeMs?: number;
+    /** v4 medium pass (V14): require the @authority covered component. */
+    requireAuthority?: boolean;
   };
   ap2PublicKey?: unknown;
   ap2?: {
@@ -36,13 +79,27 @@ export interface AgentsBloomConfig {
     maxMandateLifetimeSec?: number;
     requireJti?: boolean;
     requestedCategories?: string[];
+    /**
+     * v4: reject self-certifying did:key mandates (anyone can mint those
+     * with an arbitrary maxBudget) and accept only mandates signed by the
+     * merchant-configured trusted key.
+     */
+    trustedIssuersOnly?: boolean;
+    /** v4 medium pass (V17): pin the currency budgets are denominated in. */
+    expectedCurrency?: string;
   };
   rateLimit?: {
     max?: number;
     windowMs?: number;
   };
+  mcp?: {
+    /** v4: cap on concurrent MCP SSE sessions (default 100). */
+    maxSessions?: number;
+  };
   idempotency?: {
     ttlMs?: number;
+    /** v4 medium pass (V18): bound on cached entries (default 10,000). */
+    maxEntries?: number;
   };
   demoMode?: boolean;
   disableSignatureAuth?: boolean;
@@ -70,6 +127,12 @@ export interface TelemetryConfig {
 
 export interface Ap2VerificationResult {
   valid: boolean;
+  /**
+   * True only when a presented mandate cryptographically verified. When a
+   * shared replay store (UPSTASH_REDIS_REST_URL/TOKEN) is configured,
+   * verification may resolve asynchronously - the return type becomes
+   * Promise<Ap2VerificationResult>; callers should await it either way.
+   */
   verified?: boolean;
   protocol: 'AP2';
   reason?: string;
@@ -84,6 +147,8 @@ export interface Ap2VerifyOptions {
   maxMandateLifetimeSec?: number;
   requireJti?: boolean;
   requestedCategories?: string[];
+  /** v4: when false, self-certifying did:key issuers are rejected. */
+  allowSelfCertifying?: boolean;
 }
 
 export interface CreateAp2MandateOptions {
@@ -117,8 +182,36 @@ export function verifyAP2Mandates(
   headers?: Record<string, string | undefined>,
   body?: Record<string, unknown>,
   publicKeyOrOptions?: unknown | Ap2VerifyOptions
-): Ap2VerificationResult;
+): Ap2VerificationResult | Promise<Ap2VerificationResult>;
 export function createAp2Mandate(options: CreateAp2MandateOptions): Ap2Mandate;
 export function didKeyFromEd25519PublicKey(publicKey: unknown): string;
 export function ed25519PublicKeyFromDidKey(didKey: string): unknown | null;
 export function resetAp2ReplayCache(): void;
+/**
+ * Normalizes an audience/merchantScope value (URL-parsed: lowercased host,
+ * trailing slashes stripped) so mandates built via new URL().href compare
+ * equal to slash-free configured audiences.
+ */
+export function normalizeAudience(value: string): string;
+
+export interface OutcomeReport {
+  orderRef: string;
+  status: 'paid' | 'declined' | 'refunded' | 'chargeback' | 'disputed' | 'canceled';
+  gateway?: 'stripe' | 'razorpay' | 'paddle' | 'other';
+  reason?: string | null;
+  amount?: number | null;
+  currency?: string | null;
+  identityKey?: string | null;
+  occurredAt?: string;
+}
+
+export interface OutcomeReporter {
+  report(body: OutcomeReport): Promise<{ ok: boolean; recorded: string; orderRef: string }>;
+  captureStripeOutcome(event: unknown): Promise<{ skipped: boolean } | { ok: boolean }>;
+}
+export function stripeEventToOutcome(event: unknown): OutcomeReport | null;
+export function createOutcomeReporter(options: {
+  apiKey: string;
+  collectorUrl?: string;
+  fetchImpl?: (url: string, init: object) => Promise<Response>;
+}): OutcomeReporter;