aixyz 0.33.0 → 0.35.0

package/app/plugins/session/index.ts

@@ -0,0 +1,193 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { BasePlugin, type RegisterContext, type InitializeContext } from "../../plugin";
+import type { PaymentGateway } from "../../payment/payment";
+import { InMemorySessionStore } from "./memory";
+
+export { InMemorySessionStore, type InMemorySessionStoreOptions } from "./memory";
+
+// ── Storage Interface ────────────────────────────────────────────────
+
+/** Options for {@link SessionStore.set} and {@link SessionStore.setMany}. */
+export interface SetOptions {
+  /** Per-key TTL in milliseconds. Overrides the store-level default when supported. */
+  ttlMs?: number;
+}
+
+/** Options for {@link SessionStore.list}. */
+export interface ListOptions {
+  /** Only return keys starting with this prefix. */
+  prefix?: string;
+  /** Opaque cursor from a previous `list()` call for pagination. */
+  cursor?: string;
+  /** Maximum number of entries to return. The store decides its own default when omitted. */
+  limit?: number;
+  /** If true, values are omitted (all values will be empty strings). */
+  keysOnly?: boolean;
+}
+
+/** Return type for {@link SessionStore.list}. */
+export interface ListResult {
+  entries: Record<string, string>;
+  /** If present, more results are available — pass to the next `list()` call. */
+  cursor?: string;
+}
+
+/**
+ * Pluggable session storage backend.
+ * All methods are async to support external stores (Redis, DB, KV, etc.).
+ * Operations are scoped by payer address — the x402 signer for the request.
+ */
+export interface SessionStore {
+  get(payer: string, key: string): Promise<string | undefined>;
+  set(payer: string, key: string, value: string, options?: SetOptions): Promise<void>;
+  delete(payer: string, key: string): Promise<boolean>;
+  list(payer: string, options?: ListOptions): Promise<ListResult>;
+
+  /** Retrieve multiple keys in a single call. */
+  getMany?(payer: string, keys: string[]): Promise<Record<string, string | undefined>>;
+  /** Set multiple keys in a single call. */
+  setMany?(payer: string, entries: Record<string, string>, options?: SetOptions): Promise<void>;
+  /** Delete multiple keys in a single call. Returns the number of keys actually removed. */
+  deleteMany?(payer: string, keys: string[]): Promise<number>;
+
+  /** Release resources held by the store (connections, timers, etc.). */
+  close?(): Promise<void>;
+}
+
+// ── Session Handle ───────────────────────────────────────────────────
+
+/**
+ * Payer-scoped session handle. All operations target the current
+ * x402 payer without requiring the caller to pass an address.
+ */
+export interface Session {
+  readonly payer: string;
+  get(key: string): Promise<string | undefined>;
+  set(key: string, value: string, options?: SetOptions): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  list(options?: ListOptions): Promise<ListResult>;
+}
+
+function createSession(payer: string, store: SessionStore): Session {
+  // Normalize the payer address to lowercase so sessions are keyed consistently
+  // regardless of whether the x402 verifier returns a checksummed (EIP-55) or
+  // lowercase address. The original (possibly checksummed) address is still
+  // exposed as `session.payer` for display purposes.
+  const storedPayer = payer.toLowerCase();
+  return {
+    payer,
+    get: (key) => store.get(storedPayer, key),
+    set: (key, value, options) => store.set(storedPayer, key, value, options),
+    delete: (key) => store.delete(storedPayer, key),
+    list: (options) => store.list(storedPayer, options),
+  };
+}
+
+// ── AsyncLocalStorage API ────────────────────────────────────────────
+
+const sessionStorage = new AsyncLocalStorage<Session | undefined>();
+
+/**
+ * Get the current payer-scoped session.
+ * Returns `undefined` if no x402 payment was made for this request.
+ */
+export function getSession(): Session | undefined {
+  return sessionStorage.getStore();
+}
+
+/**
+ * Get the current x402 payer address.
+ * Shorthand for `getSession()?.payer`.
+ */
+export function getPayer(): string | undefined {
+  return sessionStorage.getStore()?.payer;
+}
+
+// ── Plugin ───────────────────────────────────────────────────────────
+
+export interface SessionPluginOptions {
+  /** Custom session store. Defaults to {@link InMemorySessionStore}. */
+  store?: SessionStore;
+}
+
+/**
+ * Session plugin for aixyz. Provides payer-scoped key-value storage
+ * gated by x402 payment identity.
+ *
+ * Register **before** other plugins so the session middleware runs first:
+ *
+ * ```ts
+ * await app.withPlugin(new SessionPlugin());
+ * await app.withPlugin(new A2APlugin([...]));
+ * ```
+ *
+ * Tools access the session via {@link getSession}:
+ *
+ * ```ts
+ * import { getSession } from "aixyz/app/plugins/session";
+ *
+ * const session = getSession();
+ * await session?.set("key", "value");
+ * ```
+ */
+export class SessionPlugin extends BasePlugin {
+  readonly name = "session";
+  readonly store: SessionStore;
+  private payment?: PaymentGateway;
+
+  constructor(options?: SessionPluginOptions) {
+    super();
+    this.store = options?.store ?? new InMemorySessionStore();
+  }
+
+  register(ctx: RegisterContext): void {
+    ctx.use(async (request, next) => {
+      const payer = this.payment?.getPayer(request);
+      if (payer) {
+        const session = createSession(payer, this.store);
+        return sessionStorage.run(session, next);
+      }
+      // Explicitly clear any inherited ALS context so that an unpaid route
+      // nested inside a paid handler's app.fetch() doesn't leak the outer session.
+      return sessionStorage.run(undefined, next);
+    });
+  }
+
+  initialize(ctx: InitializeContext): void {
+    this.payment = ctx.payment;
+  }
+
+  /**
+   * Run a function within a session context for the given payer.
+   * Used by other plugins (e.g., MCPPlugin) to set session context
+   * for tool execution when payment is handled at the protocol level.
+   *
+   * **Security note:** This method bypasses HTTP-level payment verification.
+   * Only call it with a payer address that has already been authenticated by a
+   * trusted payment mechanism (e.g., the `@x402/mcp` payment wrapper).
+   * @internal
+   */
+  runWithPayer<T>(payer: string, fn: () => T): T {
+    const session = createSession(payer, this.store);
+    return sessionStorage.run(session, fn);
+  }
+}
+
+/**
+ * Identity helper that provides full type inference for a {@link SessionStore}.
+ * Use in `app/session.ts` to get type-safe autocompletion:
+ *
+ * ```ts
+ * import { defineSessionStore } from "aixyz/app/plugins/session";
+ *
+ * export default defineSessionStore({
+ *   async get(payer, key) { ... },
+ *   async set(payer, key, value) { ... },
+ *   async delete(payer, key) { ... },
+ *   async list(payer) { ... },
+ * });
+ * ```
+ */
+export function defineSessionStore(store: SessionStore): SessionStore {
+  return store;
+}

package/app/plugins/session/memory.ts

@@ -0,0 +1,206 @@
+import type { SessionStore, SetOptions, ListOptions, ListResult } from "./index";
+
+// ── Types ─────────────────────────────────────────────────────────────
+
+export interface InMemorySessionStoreOptions {
+  /** Maximum number of entries across all payers. Default: 10 000. */
+  maxEntries?: number;
+  /** Time-to-live in milliseconds (sliding window). 0 = no expiry. Default: 3 600 000 (1 h). */
+  ttlMs?: number;
+}
+
+interface Entry {
+  value: string;
+  payer: string;
+  key: string;
+  expiresAt: number; // 0 = never expires
+  ttlMs: number; // effective TTL used when refreshing on get(); 0 = no expiry
+}
+
+// ── Implementation ────────────────────────────────────────────────────
+
+/**
+ * Production-ready in-memory {@link SessionStore} with LRU eviction and
+ * optional TTL.
+ *
+ * - **LRU eviction** — backed by `Map` insertion-order. When `maxEntries`
+ *   is reached, the least-recently-used entry is evicted.
+ * - **Sliding-window TTL** — `get()` refreshes the expiry timer.
+ *   Expired entries are lazily removed on read; no background timers.
+ * - **OOM-safe** — `maxEntries` is a hard cap. Memory usage is bounded
+ *   regardless of TTL or access patterns.
+ */
+export class InMemorySessionStore implements SessionStore {
+  private readonly maxEntries: number;
+  private readonly ttlMs: number;
+
+  /** Flat LRU map. Key = `${payer}:${key}`. Insertion order = access order. */
+  private readonly entries = new Map<string, Entry>();
+  /** Secondary index: payer → set of composite keys (for efficient `list`). */
+  private readonly payerIndex = new Map<string, Set<string>>();
+
+  constructor(options?: InMemorySessionStoreOptions) {
+    this.maxEntries = options?.maxEntries ?? 10_000;
+    this.ttlMs = options?.ttlMs ?? 3_600_000;
+    if (this.maxEntries < 1) throw new Error("maxEntries must be >= 1");
+    if (this.ttlMs < 0) throw new Error("ttlMs must be >= 0");
+  }
+
+  async get(payer: string, key: string): Promise<string | undefined> {
+    const ck = compositeKey(payer, key);
+    const entry = this.entries.get(ck);
+    if (!entry) return undefined;
+
+    if (this.isExpired(entry)) {
+      this.removeEntry(ck, entry);
+      return undefined;
+    }
+
+    // LRU touch: move to end + refresh TTL using the entry's own TTL
+    this.entries.delete(ck);
+    entry.expiresAt = this.expiryFor(entry.ttlMs);
+    this.entries.set(ck, entry);
+
+    return entry.value;
+  }
+
+  async set(payer: string, key: string, value: string, options?: SetOptions): Promise<void> {
+    const ck = compositeKey(payer, key);
+
+    // If overwriting, remove first so re-insert lands at the end.
+    const existing = this.entries.get(ck);
+    if (existing) {
+      this.entries.delete(ck);
+    }
+
+    // Evict LRU entry if at capacity.
+    if (this.entries.size >= this.maxEntries) {
+      const oldest = this.entries.keys().next();
+      if (!oldest.done) {
+        const oldestEntry = this.entries.get(oldest.value)!;
+        this.removeEntry(oldest.value, oldestEntry);
+      }
+    }
+
+    const effectiveTtl = options?.ttlMs ?? this.ttlMs;
+    const entry: Entry = { value, payer, key, expiresAt: this.expiryFor(effectiveTtl), ttlMs: effectiveTtl };
+    this.entries.set(ck, entry);
+
+    // Update payer index.
+    let idx = this.payerIndex.get(payer);
+    if (!idx) {
+      idx = new Set();
+      this.payerIndex.set(payer, idx);
+    }
+    idx.add(ck);
+  }
+
+  async delete(payer: string, key: string): Promise<boolean> {
+    const ck = compositeKey(payer, key);
+    const entry = this.entries.get(ck);
+    if (!entry) return false;
+    this.removeEntry(ck, entry);
+    return true;
+  }
+
+  async list(payer: string, options?: ListOptions): Promise<ListResult> {
+    const idx = this.payerIndex.get(payer);
+    if (!idx) return { entries: {} };
+
+    const prefix = options?.prefix;
+    const limit = options?.limit && options.limit > 0 ? options.limit : Infinity;
+    const keysOnly = options?.keysOnly ?? false;
+    const cursor = options?.cursor;
+
+    const result: Record<string, string> = {};
+    let count = 0;
+    let pastCursor = !cursor;
+    let lastCk: string | undefined;
+    let hasMore = false;
+
+    for (const ck of idx) {
+      const entry = this.entries.get(ck);
+      if (!entry) {
+        idx.delete(ck);
+        continue;
+      }
+      if (this.isExpired(entry)) {
+        this.removeEntry(ck, entry);
+        continue;
+      }
+
+      // Skip until we pass the cursor position.
+      if (!pastCursor) {
+        if (ck === cursor) pastCursor = true;
+        continue;
+      }
+
+      // Apply prefix filter.
+      if (prefix && !entry.key.startsWith(prefix)) continue;
+
+      if (count >= limit) {
+        hasMore = true;
+        break;
+      }
+
+      result[entry.key] = keysOnly ? "" : entry.value;
+      lastCk = ck;
+      count++;
+    }
+
+    if (idx.size === 0) this.payerIndex.delete(payer);
+    return { entries: result, cursor: hasMore ? lastCk : undefined };
+  }
+
+  async getMany(payer: string, keys: string[]): Promise<Record<string, string | undefined>> {
+    const result: Record<string, string | undefined> = {};
+    for (const key of keys) {
+      result[key] = await this.get(payer, key);
+    }
+    return result;
+  }
+
+  async setMany(payer: string, entries: Record<string, string>, options?: SetOptions): Promise<void> {
+    for (const [key, value] of Object.entries(entries)) {
+      await this.set(payer, key, value, options);
+    }
+  }
+
+  async deleteMany(payer: string, keys: string[]): Promise<number> {
+    let count = 0;
+    for (const key of keys) {
+      if (await this.delete(payer, key)) count++;
+    }
+    return count;
+  }
+
+  async close(): Promise<void> {
+    this.entries.clear();
+    this.payerIndex.clear();
+  }
+
+  // ── Internals ───────────────────────────────────────────────────────
+
+  private removeEntry(ck: string, entry: Entry): void {
+    this.entries.delete(ck);
+    const idx = this.payerIndex.get(entry.payer);
+    if (idx) {
+      idx.delete(ck);
+      if (idx.size === 0) this.payerIndex.delete(entry.payer);
+    }
+  }
+
+  private isExpired(entry: Entry): boolean {
+    return entry.expiresAt > 0 && Date.now() > entry.expiresAt;
+  }
+
+  private expiryFor(ttlMs: number): number {
+    return ttlMs > 0 ? Date.now() + ttlMs : 0;
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+function compositeKey(payer: string, key: string): string {
+  return `${payer}:${key}`;
+}

package/app/types.ts

@@ -1,4 +1,4 @@
-import type { AcceptsX402 } from "../accepts";
+import type { Accepts, AcceptsX402, AcceptsX402Multi } from "../accepts";
 
 export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
 
@@ -6,9 +6,13 @@ export type RouteHandler = (request: Request) => Response | Promise<Response>;
 
 export type Middleware = (request: Request, next: () => Promise<Response>) => Response | Promise<Response>;
 
+export interface RouteOptions {
+  payment?: Accepts;
+}
+
 export interface RouteEntry {
   method: HttpMethod;
   path: string;
   handler: RouteHandler;
-  payment?: AcceptsX402;
+  payment?: AcceptsX402 | AcceptsX402Multi;
 }

package/docs/api-reference/accepts.mdx

@@ -6,18 +6,18 @@ description: "Payment configuration types and facilitator client for x402 gating
 Types and utilities for configuring x402 payment gating on agent and tool endpoints.
 
 ```typescript
-import type { Accepts, AcceptsX402, AcceptsFree } from "aixyz/accepts";
-import { HTTPFacilitatorClient, facilitator } from "aixyz/accepts";
+import type { Accepts, AcceptsX402, AcceptsX402Entry, AcceptsX402Multi, AcceptsFree } from "aixyz/accepts";
+import { HTTPFacilitatorClient, facilitator, normalizeAcceptsX402, isAcceptsPaid } from "aixyz/accepts";
 ```
 
 ## Types
 
 ### `Accepts`
 
-Union type for payment configuration:
+Union type for payment configuration. Supports a single payment option, free access, or an array of payment options for multi-network support:
 
 ```typescript
-type Accepts = AcceptsX402 | AcceptsFree;
+type Accepts = AcceptsX402 | AcceptsFree | AcceptsX402Multi;
 ```
 
 ### `AcceptsX402`
@@ -40,6 +40,34 @@ type AcceptsX402 = {
 | `network` | `string` | No       | CAIP-2 chain ID, overrides `x402.network` from config         |
 | `payTo`   | `string` | No       | EVM address to receive payment, overrides `x402.payTo` config |
 
+### `AcceptsX402Entry`
+
+A single payment option within a multi-accepts array. Same as `AcceptsX402` but `network` is **required** — the server needs an explicit network to register each payment scheme:
+
+```typescript
+type AcceptsX402Entry = {
+  scheme: "exact";
+  price: string;
+  network: string; // required
+  payTo?: string;
+};
+```
+
+| Field     | Type     | Required | Description                                                   |
+| --------- | -------- | -------- | ------------------------------------------------------------- |
+| `scheme`  | `string` | Yes      | Must be `"exact"`                                             |
+| `price`   | `string` | Yes      | USD price string (e.g. `"$0.005"`)                            |
+| `network` | `string` | Yes      | CAIP-2 chain ID — required for multi-accepts                  |
+| `payTo`   | `string` | No       | EVM address to receive payment, overrides `x402.payTo` config |
+
+### `AcceptsX402Multi`
+
+An array of payment entries, enabling multi-network support. Must contain at least one entry:
+
+```typescript
+type AcceptsX402Multi = AcceptsX402Entry[];
+```
+
 ### `AcceptsFree`
 
 No payment required:
@@ -52,6 +80,22 @@ type AcceptsFree = {
 
 ## Exports
 
+### `normalizeAcceptsX402`
+
+Converts a single or multi accepts value into a uniform array:
+
+```typescript
+function normalizeAcceptsX402(accepts: AcceptsX402 | AcceptsX402Multi): AcceptsX402[];
+```
+
+### `isAcceptsPaid`
+
+Type guard that returns `true` if the accepts config requires payment (i.e., is not `{ scheme: "free" }`):
+
+```typescript
+function isAcceptsPaid(accepts: Accepts): accepts is AcceptsX402 | AcceptsX402Multi;
+```
+
 ### `HTTPFacilitatorClient`
 
 Client for communicating with an x402 facilitator service. Re-exported from `@x402/core/server`.
@@ -74,12 +118,19 @@ import { facilitator } from "aixyz/accepts";
 
 ### `AcceptsScheme`
 
-Zod schema for validating `Accepts` objects at runtime:
+Zod schema for validating `Accepts` objects at runtime. Accepts a single object or an array of payment entries:
 
 ```typescript
 import { AcceptsScheme } from "aixyz/accepts";
 
+// Single accepts
 AcceptsScheme.parse({ scheme: "exact", price: "$0.005" });
+
+// Multiple accepts
+AcceptsScheme.parse([
+  { scheme: "exact", price: "$0.005", network: "eip155:8453" },
+  { scheme: "exact", price: "$0.005", network: "eip155:84532" },
+]);
 ```
 
 ## Usage
@@ -103,6 +154,21 @@ export const accepts: Accepts = {
 };
 ```
 
+### Multiple payment options
+
+Accept payment across multiple networks by passing an array. Each entry requires an explicit `network`:
+
+```typescript title="app/agent.ts"
+import type { Accepts } from "aixyz/accepts";
+
+export const accepts: Accepts = [
+  { scheme: "exact", price: "$0.005", network: "eip155:8453" },
+  { scheme: "exact", price: "$0.005", network: "eip155:84532" },
+];
+```
+
+All referenced networks are automatically registered with the payment gateway during initialization — no manual setup required.
+
 ### Custom facilitator
 
 Create `app/accepts.ts` to override the default facilitator:

package/docs/api-reference/agent.mdx

@@ -38,7 +38,7 @@ export default new ToolLoopAgent({
 | `accepts`      | `Accepts`       | No       | Payment config — gates the A2A `/agent` route                       |
 | `capabilities` | `Capabilities`  | No       | A2A capabilities — controls streaming and push notification support |
 
-When `accepts` is exported, the `/agent` endpoint requires x402 payment. Without it, the agent is not registered on the A2A endpoint.
+When `accepts` is exported, the `/agent` endpoint requires x402 payment. Without it, the agent is not registered on the A2A endpoint. `accepts` can also be an array of payment entries for [multi-network support](/getting-started/payments#multiple-payment-options).
 
 ## Capabilities
 

package/docs/api-reference/aixyz-server.mdx

@@ -91,12 +91,15 @@ await server.initialize();
 
 ```typescript title="app/server.ts"
 import { AixyzApp } from "aixyz/app";
+import { SessionPlugin } from "aixyz/app/plugins/session";
 import { IndexPagePlugin } from "aixyz/app/plugins/index-page";
 import { A2APlugin } from "aixyz/app/plugins/a2a";
 import * as agent from "./agent";
 
 const server = new AixyzApp();
 
+// SessionPlugin must be registered first so its middleware runs before other plugins
+await server.withPlugin(new SessionPlugin());
 await server.withPlugin(new IndexPagePlugin());
 await server.withPlugin(new A2APlugin([{ exports: agent }]));