@elisym/sdk 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -685,6 +685,82 @@ declare class BoundedSet<T> {
     add(item: T): void;
 }
 
+/**
+ * Sliding-window rate limiter keyed by an arbitrary string (typically a
+ * customer pubkey). Each key gets at most `maxPerWindow` requests inside a
+ * rolling `windowMs`. Stale timestamps are pruned lazily on every `check`.
+ * When the tracked-key set grows past `maxKeys`, the least-recently-used
+ * key is evicted so an attacker cannot exhaust memory by cycling keys.
+ *
+ * Thread-safety: not required. Designed for single-threaded JS consumers
+ * (Node/Bun event loops, browser main thread). No timers - pruning happens
+ * inside `check` and `prune`.
+ */
+interface SlidingWindowLimiterOptions {
+    /** Rolling window width, in ms. */
+    windowMs: number;
+    /** Max hits allowed per key inside the window. */
+    maxPerWindow: number;
+    /** Cap on total tracked keys. LRU-evicted past this cap. */
+    maxKeys: number;
+}
+interface RateLimitDecision {
+    allowed: boolean;
+    /** Wall-clock timestamp (ms) when the limit window will reset for this key. */
+    resetAt: number;
+    /** Number of hits inside the current window after this call (or the attempted hit if denied). */
+    count: number;
+}
+interface SlidingWindowLimiter {
+    /** Record a hit against `key`; return whether it was allowed. */
+    check(key: string, now?: number): RateLimitDecision;
+    /**
+     * Inspect the current state for `key` without recording a hit. Useful
+     * when a single request must clear multiple limiters and callers want
+     * to avoid double-counting against one limiter after another denies.
+     */
+    peek(key: string, now?: number): RateLimitDecision;
+    /** Drop entries whose windows have fully elapsed. Bounded memory hygiene. */
+    prune(now?: number): void;
+    /** Current number of tracked keys. */
+    size(): number;
+    /** Clear all state. */
+    reset(): void;
+}
+declare function createSlidingWindowLimiter(options: SlidingWindowLimiterOptions): SlidingWindowLimiter;
+
+/**
+ * Canonical pino redact paths for the elisym stack. Plugin, CLI, MCP, and
+ * any downstream integrator should consume these arrays directly - one
+ * source of truth for "fields that carry user input or secrets".
+ *
+ * Wire them into a pino instance like:
+ *
+ *   import pino from 'pino';
+ *   import { DEFAULT_REDACT_PATHS, makeCensor } from '@elisym/sdk';
+ *   const logger = pino({
+ *     redact: { paths: DEFAULT_REDACT_PATHS, censor: makeCensor() },
+ *   });
+ */
+/**
+ * Field paths that carry Nostr / Solana secret keys or operator secrets.
+ * Censored as `[REDACTED]`.
+ */
+declare const SECRET_REDACT_PATHS: string[];
+/**
+ * Field paths that carry customer-confidential text (LLM prompts, raw
+ * event content, job input). Censored as `[INPUT REDACTED]` so log
+ * readers can distinguish redacted input from redacted secrets.
+ */
+declare const INPUT_REDACT_PATHS: string[];
+/**
+ * Union of the two arrays, in the order pino's redact engine should
+ * visit them. Prefer this when wiring a new logger so no downstream
+ * consumer forgets half the set.
+ */
+declare const DEFAULT_REDACT_PATHS: string[];
+declare function makeCensor(): (value: unknown, path: string[]) => string;
+
 declare const RELAYS: string[];
 declare const KIND_APP_HANDLER = 31990;
 declare const KIND_JOB_REQUEST_BASE = 5000;
@@ -760,4 +836,4 @@ declare const LIMITS: {
     readonly MAX_CAPABILITY_LENGTH: 64;
 };
 
-export { type Agent, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DiscoveryService, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EstimatePriorityFeeOptions, type GetProtocolConfigOptions, type Job, type JobStatus, type JobSubscriptionOptions, type JobUpdateCallbacks, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, type Network, type NetworkStats, NostrPool, PROTOCOL_FEE_BPS, PROTOCOL_PROGRAM_ID_DEVNET, PROTOCOL_TREASURY, type ParseOptions, type ParseResult, type ParsedPaymentRequest, type PaymentInfo, type PaymentRequestData, PaymentRequestSchema, type PaymentStrategy, type PaymentValidationCode, type PaymentValidationError, type PingResult, PingService, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, RELAYS, type Signer, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type VerifyOptions, type VerifyResult, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearPriorityFeeCache, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, estimatePriorityFeeMicroLamports, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };
+export { type Agent, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, DiscoveryService, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EstimatePriorityFeeOptions, type GetProtocolConfigOptions, INPUT_REDACT_PATHS, type Job, type JobStatus, type JobSubscriptionOptions, type JobUpdateCallbacks, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, type Network, type NetworkStats, NostrPool, PROTOCOL_FEE_BPS, PROTOCOL_PROGRAM_ID_DEVNET, PROTOCOL_TREASURY, type ParseOptions, type ParseResult, type ParsedPaymentRequest, type PaymentInfo, type PaymentRequestData, PaymentRequestSchema, type PaymentStrategy, type PaymentValidationCode, type PaymentValidationError, type PingResult, PingService, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, RELAYS, type RateLimitDecision, SECRET_REDACT_PATHS, type Signer, type SlidingWindowLimiter, type SlidingWindowLimiterOptions, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type VerifyOptions, type VerifyResult, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearPriorityFeeCache, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, createSlidingWindowLimiter, estimatePriorityFeeMicroLamports, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };

package/dist/index.d.ts

@@ -685,6 +685,82 @@ declare class BoundedSet<T> {
     add(item: T): void;
 }
 
+/**
+ * Sliding-window rate limiter keyed by an arbitrary string (typically a
+ * customer pubkey). Each key gets at most `maxPerWindow` requests inside a
+ * rolling `windowMs`. Stale timestamps are pruned lazily on every `check`.
+ * When the tracked-key set grows past `maxKeys`, the least-recently-used
+ * key is evicted so an attacker cannot exhaust memory by cycling keys.
+ *
+ * Thread-safety: not required. Designed for single-threaded JS consumers
+ * (Node/Bun event loops, browser main thread). No timers - pruning happens
+ * inside `check` and `prune`.
+ */
+interface SlidingWindowLimiterOptions {
+    /** Rolling window width, in ms. */
+    windowMs: number;
+    /** Max hits allowed per key inside the window. */
+    maxPerWindow: number;
+    /** Cap on total tracked keys. LRU-evicted past this cap. */
+    maxKeys: number;
+}
+interface RateLimitDecision {
+    allowed: boolean;
+    /** Wall-clock timestamp (ms) when the limit window will reset for this key. */
+    resetAt: number;
+    /** Number of hits inside the current window after this call (or the attempted hit if denied). */
+    count: number;
+}
+interface SlidingWindowLimiter {
+    /** Record a hit against `key`; return whether it was allowed. */
+    check(key: string, now?: number): RateLimitDecision;
+    /**
+     * Inspect the current state for `key` without recording a hit. Useful
+     * when a single request must clear multiple limiters and callers want
+     * to avoid double-counting against one limiter after another denies.
+     */
+    peek(key: string, now?: number): RateLimitDecision;
+    /** Drop entries whose windows have fully elapsed. Bounded memory hygiene. */
+    prune(now?: number): void;
+    /** Current number of tracked keys. */
+    size(): number;
+    /** Clear all state. */
+    reset(): void;
+}
+declare function createSlidingWindowLimiter(options: SlidingWindowLimiterOptions): SlidingWindowLimiter;
+
+/**
+ * Canonical pino redact paths for the elisym stack. Plugin, CLI, MCP, and
+ * any downstream integrator should consume these arrays directly - one
+ * source of truth for "fields that carry user input or secrets".
+ *
+ * Wire them into a pino instance like:
+ *
+ *   import pino from 'pino';
+ *   import { DEFAULT_REDACT_PATHS, makeCensor } from '@elisym/sdk';
+ *   const logger = pino({
+ *     redact: { paths: DEFAULT_REDACT_PATHS, censor: makeCensor() },
+ *   });
+ */
+/**
+ * Field paths that carry Nostr / Solana secret keys or operator secrets.
+ * Censored as `[REDACTED]`.
+ */
+declare const SECRET_REDACT_PATHS: string[];
+/**
+ * Field paths that carry customer-confidential text (LLM prompts, raw
+ * event content, job input). Censored as `[INPUT REDACTED]` so log
+ * readers can distinguish redacted input from redacted secrets.
+ */
+declare const INPUT_REDACT_PATHS: string[];
+/**
+ * Union of the two arrays, in the order pino's redact engine should
+ * visit them. Prefer this when wiring a new logger so no downstream
+ * consumer forgets half the set.
+ */
+declare const DEFAULT_REDACT_PATHS: string[];
+declare function makeCensor(): (value: unknown, path: string[]) => string;
+
 declare const RELAYS: string[];
 declare const KIND_APP_HANDLER = 31990;
 declare const KIND_JOB_REQUEST_BASE = 5000;
@@ -760,4 +836,4 @@ declare const LIMITS: {
     readonly MAX_CAPABILITY_LENGTH: 64;
 };
 
-export { type Agent, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DiscoveryService, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EstimatePriorityFeeOptions, type GetProtocolConfigOptions, type Job, type JobStatus, type JobSubscriptionOptions, type JobUpdateCallbacks, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, type Network, type NetworkStats, NostrPool, PROTOCOL_FEE_BPS, PROTOCOL_PROGRAM_ID_DEVNET, PROTOCOL_TREASURY, type ParseOptions, type ParseResult, type ParsedPaymentRequest, type PaymentInfo, type PaymentRequestData, PaymentRequestSchema, type PaymentStrategy, type PaymentValidationCode, type PaymentValidationError, type PingResult, PingService, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, RELAYS, type Signer, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type VerifyOptions, type VerifyResult, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearPriorityFeeCache, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, estimatePriorityFeeMicroLamports, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };
+export { type Agent, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, DiscoveryService, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EstimatePriorityFeeOptions, type GetProtocolConfigOptions, INPUT_REDACT_PATHS, type Job, type JobStatus, type JobSubscriptionOptions, type JobUpdateCallbacks, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, type Network, type NetworkStats, NostrPool, PROTOCOL_FEE_BPS, PROTOCOL_PROGRAM_ID_DEVNET, PROTOCOL_TREASURY, type ParseOptions, type ParseResult, type ParsedPaymentRequest, type PaymentInfo, type PaymentRequestData, PaymentRequestSchema, type PaymentStrategy, type PaymentValidationCode, type PaymentValidationError, type PingResult, PingService, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, RELAYS, type RateLimitDecision, SECRET_REDACT_PATHS, type Signer, type SlidingWindowLimiter, type SlidingWindowLimiterOptions, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type VerifyOptions, type VerifyResult, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearPriorityFeeCache, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, createSlidingWindowLimiter, estimatePriorityFeeMicroLamports, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };

package/dist/index.js

@@ -2387,6 +2387,141 @@ function validateAgentName(name) {
   }
 }
 
-export { BoundedSet, DEFAULTS, DEFAULT_KIND_OFFSET, DiscoveryService, ElisymClient, ElisymIdentity, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, NostrPool, PROTOCOL_FEE_BPS, PROTOCOL_PROGRAM_ID_DEVNET, PROTOCOL_TREASURY, PaymentRequestSchema, PingService, RELAYS, SolanaPaymentStrategy, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearPriorityFeeCache, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, estimatePriorityFeeMicroLamports, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };
+// src/primitives/rateLimiter.ts
+function createSlidingWindowLimiter(options) {
+  const { windowMs, maxPerWindow, maxKeys } = options;
+  if (windowMs <= 0) {
+    throw new RangeError("windowMs must be > 0");
+  }
+  if (maxPerWindow <= 0) {
+    throw new RangeError("maxPerWindow must be > 0");
+  }
+  if (maxKeys <= 0) {
+    throw new RangeError("maxKeys must be > 0");
+  }
+  const entries = /* @__PURE__ */ new Map();
+  function evictIfNeeded() {
+    while (entries.size > maxKeys) {
+      const oldestKey = entries.keys().next().value;
+      if (oldestKey === void 0) {
+        return;
+      }
+      entries.delete(oldestKey);
+    }
+  }
+  return {
+    peek(key, now = Date.now()) {
+      const entry = entries.get(key);
+      if (!entry) {
+        return { allowed: true, resetAt: now + windowMs, count: 0 };
+      }
+      const cutoff = now - windowMs;
+      const fresh = entry.hits.filter((timestamp) => timestamp > cutoff);
+      return {
+        allowed: fresh.length < maxPerWindow,
+        resetAt: (fresh[0] ?? now) + windowMs,
+        count: fresh.length
+      };
+    },
+    check(key, now = Date.now()) {
+      const entry = entries.get(key) ?? { hits: [] };
+      const cutoff = now - windowMs;
+      const fresh = entry.hits.filter((timestamp) => timestamp > cutoff);
+      if (fresh.length >= maxPerWindow) {
+        entries.delete(key);
+        entries.set(key, { hits: fresh });
+        return {
+          allowed: false,
+          resetAt: (fresh[0] ?? now) + windowMs,
+          count: fresh.length
+        };
+      }
+      fresh.push(now);
+      entries.delete(key);
+      entries.set(key, { hits: fresh });
+      evictIfNeeded();
+      return {
+        allowed: true,
+        resetAt: (fresh[0] ?? now) + windowMs,
+        count: fresh.length
+      };
+    },
+    prune(now = Date.now()) {
+      const cutoff = now - windowMs;
+      for (const [key, entry] of entries) {
+        const fresh = entry.hits.filter((timestamp) => timestamp > cutoff);
+        if (fresh.length === 0) {
+          entries.delete(key);
+        } else if (fresh.length !== entry.hits.length) {
+          entry.hits = fresh;
+        }
+      }
+    },
+    size() {
+      return entries.size;
+    },
+    reset() {
+      entries.clear();
+    }
+  };
+}
+
+// src/primitives/logRedact.ts
+var SECRET_REDACT_PATHS = [
+  "*.ELISYM_NOSTR_PRIVATE_KEY",
+  "*.ELISYM_SOLANA_PRIVATE_KEY",
+  "*.nostrPrivateKeyHex",
+  "*.solanaPrivateKeyBase58",
+  "*.secretKey",
+  "*.secret",
+  "ELISYM_NOSTR_PRIVATE_KEY",
+  "ELISYM_SOLANA_PRIVATE_KEY",
+  // Canonical on-disk `.secrets.json` field names. Logging the whole
+  // `secrets` object, or any single field directly, must not leak.
+  "llm_api_key",
+  "nostr_secret_key",
+  "solana_secret_key",
+  "*.llm_api_key",
+  "*.nostr_secret_key",
+  "*.solana_secret_key",
+  "secrets",
+  "*.secrets"
+];
+var INPUT_REDACT_PATHS = [
+  "content",
+  "input",
+  "prompt",
+  "*.content",
+  "*.input",
+  "*.prompt",
+  "event.content",
+  "*.event.content",
+  // JobLedger entries carry the raw Nostr event JSON (which embeds
+  // `event.content`) and the full LLM `resultContent` - both are
+  // customer-confidential and must never land in a structured log.
+  "rawEventJson",
+  "resultContent",
+  "*.rawEventJson",
+  "*.resultContent"
+];
+var DEFAULT_REDACT_PATHS = [...SECRET_REDACT_PATHS, ...INPUT_REDACT_PATHS];
+var INPUT_REDACT_LEAVES = /* @__PURE__ */ new Set([
+  "content",
+  "input",
+  "prompt",
+  "rawEventJson",
+  "resultContent"
+]);
+function makeCensor() {
+  return (_value, path) => {
+    const last = path[path.length - 1];
+    if (last !== void 0 && INPUT_REDACT_LEAVES.has(last)) {
+      return "[INPUT REDACTED]";
+    }
+    return "[REDACTED]";
+  };
+}
+
+export { BoundedSet, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, DiscoveryService, ElisymClient, ElisymIdentity, INPUT_REDACT_PATHS, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, NostrPool, PROTOCOL_FEE_BPS, PROTOCOL_PROGRAM_ID_DEVNET, PROTOCOL_TREASURY, PaymentRequestSchema, PingService, RELAYS, SECRET_REDACT_PATHS, SolanaPaymentStrategy, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearPriorityFeeCache, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, createSlidingWindowLimiter, estimatePriorityFeeMicroLamports, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map