@x402sentinel/x402 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,387 @@
+import { S as StorageBackend, A as AuditRecord, a as AuditQuery, b as AuditSummary } from './interface-CNi4rtm1.js';
+
+/**
+ * Stub types for x402 packages (@x402/core, @x402/fetch).
+ * These allow development without installing the actual x402 packages.
+ * When used as peer deps, the real types take precedence.
+ */
+/** CAIP-2 network identifier (e.g., "eip155:8453") */
+type Network = `${string}:${string}`;
+interface ResourceInfo {
+    url: string;
+    description: string;
+    mimeType: string;
+}
+interface PaymentRequirements {
+    scheme: string;
+    network: Network;
+    asset: string;
+    amount: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra: Record<string, unknown>;
+}
+interface PaymentRequired {
+    x402Version: number;
+    error?: string;
+    resource: ResourceInfo;
+    accepts: PaymentRequirements[];
+    extensions?: Record<string, unknown>;
+}
+interface PaymentPayload {
+    x402Version: number;
+    resource: ResourceInfo;
+    accepted: PaymentRequirements;
+    payload: Record<string, unknown>;
+    extensions?: Record<string, unknown>;
+}
+interface SettleResponse {
+    success: boolean;
+    errorReason?: string;
+    errorMessage?: string;
+    payer?: string;
+    transaction: string;
+    network: Network;
+    extensions?: Record<string, unknown>;
+}
+
+/** Context about a payment that is about to happen or just happened */
+interface PaymentContext {
+    /** Full URL being requested */
+    endpoint: string;
+    /** HTTP method */
+    method: string;
+    /** Agent making the request */
+    agentId: string;
+    /** Team the agent belongs to */
+    team: string | null;
+    /** Payment amount in human-readable USDC */
+    amount: string;
+    /** Raw base-unit amount string */
+    amountRaw: string;
+    /** Token address or symbol */
+    asset: string;
+    /** Network identifier (CAIP-2) */
+    network: string;
+    /** x402 scheme (e.g., "exact") */
+    scheme: string;
+    /** Recipient address */
+    payTo: string;
+    /** When this context was created (unix ms) */
+    timestamp: number;
+    /** Custom metadata from config */
+    metadata: Record<string, string>;
+}
+/** Decision returned by a beforePayment hook */
+interface PaymentDecision {
+    /** Whether to proceed with the payment */
+    proceed: boolean;
+    /** Reason if blocked */
+    reason?: string;
+}
+/** Anomaly detected by spike detection or other heuristics */
+interface Anomaly {
+    type: "spike" | "unusual_endpoint" | "high_frequency" | "custom";
+    /** Human-readable description */
+    message: string;
+    /** The payment context that triggered the anomaly */
+    context: PaymentContext;
+    /** Severity level */
+    severity: "low" | "medium" | "high" | "critical";
+    /** Additional details */
+    details: Record<string, string>;
+}
+/** Configuration for automatic record enrichment */
+interface EnrichmentConfig {
+    /** Tag rules: if endpoint matches pattern, add these tags */
+    tagRules?: Array<{
+        pattern: string;
+        tags: string[];
+    }>;
+    /** Static tags added to every record */
+    staticTags?: string[];
+    /** Whether to include request headers in metadata (default false) */
+    captureRequestHeaders?: boolean;
+}
+
+/** Spending limits and policy constraints for an agent or team */
+interface BudgetPolicy {
+    /** Max USDC per single payment (e.g., "1.00") */
+    maxPerCall?: string;
+    /** Hourly rolling cap in USDC */
+    maxPerHour?: string;
+    /** Daily rolling cap in USDC */
+    maxPerDay?: string;
+    /** Lifetime total cap in USDC */
+    maxTotal?: string;
+    /** Multiplier vs rolling average to trigger spike alert (default 3.0) */
+    spikeThreshold?: number;
+    /** URL patterns allowed (whitelist — if set, only these pass) */
+    allowedEndpoints?: string[];
+    /** URL patterns blocked (blacklist — always rejected) */
+    blockedEndpoints?: string[];
+    /** Require human approval above a threshold */
+    requireApproval?: {
+        above: string;
+        handler: (context: PaymentContext) => Promise<boolean>;
+    };
+}
+/** Runtime state of budget consumption */
+interface BudgetState {
+    totalSpent: string;
+    hourlySpent: string;
+    dailySpent: string;
+    callCount: number;
+    lastReset: {
+        hourly: number;
+        daily: number;
+    };
+    /** Rolling average payment size (human-readable USDC) */
+    rollingAverage: string;
+    /** Last N payment amounts for spike detection */
+    rollingWindow: string[];
+}
+/** Details of a budget policy violation */
+interface BudgetViolation {
+    type: "per_call" | "hourly" | "daily" | "total" | "spike" | "blocked_endpoint" | "approval_required";
+    /** The policy limit that was hit (human-readable USDC) */
+    limit: string;
+    /** Current spend in the relevant window */
+    current: string;
+    /** Amount that was attempted */
+    attempted: string;
+    agentId: string;
+    endpoint: string;
+    timestamp: number;
+}
+/** Result of evaluating a payment against a budget policy */
+type BudgetEvaluation = {
+    allowed: true;
+    warnings: string[];
+} | {
+    allowed: false;
+    violation: BudgetViolation;
+};
+
+/** Main configuration object for a Sentinel-wrapped fetch */
+interface SentinelConfig {
+    /** Unique identifier for this agent */
+    agentId: string;
+    /** Team or department grouping */
+    team?: string;
+    /** Human accountable for this agent's spend */
+    humanSponsor?: string;
+    /** Spending limits and policy constraints */
+    budget?: BudgetPolicy;
+    /** Audit trail configuration */
+    audit?: AuditConfig;
+    /** Lifecycle hooks */
+    hooks?: SentinelHooks;
+    /** Custom key/value pairs attached to every audit record */
+    metadata?: Record<string, string>;
+}
+/** Audit-specific configuration */
+interface AuditConfig {
+    /** Whether audit logging is enabled (default true) */
+    enabled?: boolean;
+    /** Storage backend for audit records (default: in-memory) */
+    storage?: StorageBackend;
+    /** Additional metadata enrichment rules */
+    enrichment?: EnrichmentConfig;
+    /** Field names to redact from stored records */
+    redactFields?: string[];
+}
+/** Lifecycle hooks for payment events */
+interface SentinelHooks {
+    /** Called before each payment. Return a decision to allow/block. */
+    beforePayment?: (context: PaymentContext) => Promise<PaymentDecision>;
+    /** Called after a payment settles successfully. */
+    afterPayment?: (record: AuditRecord) => Promise<void>;
+    /** Called when a budget limit is exceeded. */
+    onBudgetExceeded?: (violation: BudgetViolation) => Promise<void>;
+    /** Called when an anomaly is detected (e.g., spike). */
+    onAnomaly?: (anomaly: Anomaly) => Promise<void>;
+}
+
+/**
+ * Wrap an x402-enabled fetch function with Sentinel budget enforcement and audit logging.
+ *
+ * @param fetchWithPayment - The x402-wrapped fetch (from wrapFetchWithPayment)
+ * @param config - Sentinel configuration (agent identity, budget, audit settings)
+ * @returns A drop-in replacement fetch function with Sentinel instrumentation
+ *
+ * @example
+ * ```ts
+ * const fetchWithSentinel = wrapWithSentinel(fetchWithPayment, {
+ *   agentId: "agent-weather-001",
+ *   budget: standardPolicy(),
+ * });
+ * const response = await fetchWithSentinel("https://api.example.com/weather");
+ * ```
+ */
+declare function wrapWithSentinel(fetchWithPayment: typeof fetch, config: SentinelConfig): typeof fetch;
+
+/** Tight limits for low-risk or testing scenarios */
+declare function conservativePolicy(): BudgetPolicy;
+/** Balanced limits for typical production agents */
+declare function standardPolicy(): BudgetPolicy;
+/** Higher limits for trusted, high-throughput agents */
+declare function liberalPolicy(): BudgetPolicy;
+/** No spending limits — audit logging only */
+declare function unlimitedPolicy(): BudgetPolicy;
+/** Build a custom policy by overriding defaults */
+declare function customPolicy(overrides: Partial<BudgetPolicy>): BudgetPolicy;
+
+/** Enforces budget policies by evaluating proposed payments against spending state */
+declare class BudgetManager {
+    private state;
+    private readonly policy;
+    private readonly spikeDetector;
+    constructor(policy: BudgetPolicy);
+    /**
+     * Evaluate a proposed payment against the budget policy.
+     * Called BEFORE every payment. Returns allow/deny with reason.
+     */
+    evaluate(context: PaymentContext): BudgetEvaluation;
+    /** Record a completed payment. Called AFTER payment succeeds. */
+    record(amount: string, _endpoint: string): void;
+    /** Get current budget state (for dashboard/debugging) */
+    getState(): BudgetState;
+    /** Reset spending counters for a given scope */
+    reset(scope: "hourly" | "daily" | "total"): void;
+    /** Serialize state for persistence */
+    serialize(): string;
+    /** Restore a BudgetManager from serialized state */
+    static deserialize(data: string, policy: BudgetPolicy): BudgetManager;
+    /** Auto-reset hourly/daily windows when the time window has rolled over */
+    private maybeResetWindows;
+    private violation;
+}
+
+/** Central audit logger — writes records to a pluggable storage backend */
+declare class AuditLogger {
+    private readonly storage;
+    private readonly enabled;
+    private readonly redactFields;
+    constructor(config?: AuditConfig);
+    /** Log a completed payment record */
+    log(record: Omit<AuditRecord, "id" | "created_at">): Promise<AuditRecord>;
+    /** Log a blocked payment attempt */
+    logBlocked(context: PaymentContext, violation: BudgetViolation, config: {
+        humanSponsor?: string;
+        metadata?: Record<string, string>;
+    }): Promise<AuditRecord>;
+    /** Query audit records */
+    query(query: AuditQuery): Promise<AuditRecord[]>;
+    /** Get summary statistics */
+    summarize(query?: Partial<AuditQuery>): Promise<AuditSummary>;
+    /** Export records as CSV */
+    exportCSV(query?: AuditQuery): Promise<string>;
+    /** Export records as JSON */
+    exportJSON(query?: AuditQuery): Promise<string>;
+    /** Flush pending writes to storage */
+    flush(): Promise<void>;
+    /** Get the underlying storage backend (for dashboard integration) */
+    getStorage(): StorageBackend;
+    private redact;
+}
+
+/** In-memory audit storage with configurable capacity and FIFO eviction */
+declare class MemoryStorage implements StorageBackend {
+    private readonly records;
+    private readonly insertOrder;
+    private readonly maxRecords;
+    constructor(maxRecords?: number);
+    write(record: AuditRecord): Promise<void>;
+    query(query: AuditQuery): Promise<AuditRecord[]>;
+    summarize(query: Partial<AuditQuery>): Promise<AuditSummary>;
+    count(query: Partial<AuditQuery>): Promise<number>;
+    getById(id: string): Promise<AuditRecord | null>;
+    private filter;
+    private sort;
+}
+
+/** JSONL file-based audit storage — appends one record per line */
+declare class FileStorage implements StorageBackend {
+    private readonly filePath;
+    private buffer;
+    private readonly flushThreshold;
+    private flushTimer;
+    constructor(filePath?: string, flushThreshold?: number);
+    write(record: AuditRecord): Promise<void>;
+    query(query: AuditQuery): Promise<AuditRecord[]>;
+    summarize(query: Partial<AuditQuery>): Promise<AuditSummary>;
+    count(query: Partial<AuditQuery>): Promise<number>;
+    getById(id: string): Promise<AuditRecord | null>;
+    /** Write buffered records to disk */
+    flush(): Promise<void>;
+    /** Stop the auto-flush timer (for clean shutdown) */
+    destroy(): void;
+    private readAll;
+    private ensureDir;
+    private startAutoFlush;
+}
+
+interface ApiStorageConfig {
+    apiKey: string;
+    baseUrl?: string;
+    batchSize?: number;
+    flushIntervalMs?: number;
+}
+/**
+ * Remote API storage backend — batches and POSTs records to api.valeo.money.
+ * Falls back to in-memory storage if the API is unreachable.
+ */
+declare class ApiStorage implements StorageBackend {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly batchSize;
+    private buffer;
+    private readonly fallback;
+    private flushTimer;
+    private useFallback;
+    constructor(config: ApiStorageConfig);
+    write(record: AuditRecord): Promise<void>;
+    query(query: AuditQuery): Promise<AuditRecord[]>;
+    summarize(query: Partial<AuditQuery>): Promise<AuditSummary>;
+    count(query: Partial<AuditQuery>): Promise<number>;
+    getById(id: string): Promise<AuditRecord | null>;
+    /** Flush buffered records to the remote API */
+    flush(): Promise<void>;
+    /** Stop the auto-flush timer */
+    destroy(): void;
+    private apiRequest;
+    private startAutoFlush;
+}
+
+declare class SentinelError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+declare class SentinelBudgetError extends SentinelError {
+    readonly violation: BudgetViolation;
+    constructor(violation: BudgetViolation);
+}
+/** Audit failures are NEVER fatal — they should be caught and logged */
+declare class SentinelAuditError extends SentinelError {
+    readonly record?: Partial<AuditRecord>;
+    constructor(message: string, record?: Partial<AuditRecord>);
+}
+declare class SentinelConfigError extends SentinelError {
+    constructor(message: string);
+}
+/** Validate a SentinelConfig at initialization time */
+declare function validateConfig(config: {
+    agentId: string;
+    budget?: {
+        maxPerCall?: string;
+        maxPerHour?: string;
+        maxPerDay?: string;
+        maxTotal?: string;
+        spikeThreshold?: number;
+        allowedEndpoints?: string[];
+        blockedEndpoints?: string[];
+    };
+}): void;
+
+export { type Anomaly, ApiStorage, type AuditConfig, AuditLogger, AuditQuery, AuditRecord, AuditSummary, type BudgetEvaluation, BudgetManager, type BudgetPolicy, type BudgetState, type BudgetViolation, type EnrichmentConfig, FileStorage, MemoryStorage, type Network, type PaymentContext, type PaymentDecision, type PaymentPayload, type PaymentRequired, type PaymentRequirements, SentinelAuditError, SentinelBudgetError, type SentinelConfig, SentinelConfigError, SentinelError, type SentinelHooks, type SettleResponse, StorageBackend, conservativePolicy, customPolicy, liberalPolicy, standardPolicy, unlimitedPolicy, validateConfig, wrapWithSentinel };