@fuzdev/fuz_app 0.51.0 → 0.53.0

package/dist/http/route_spec.d.ts

@@ -46,15 +46,11 @@ export type AuthGuardResolver = (auth: RouteAuth) => Array<MiddlewareHandler>;
 export type RouteMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
 /**
  * Per-request deps provided by the framework to route handlers.
- *
- * `db` is transaction-scoped for mutation routes and pool-level for reads.
- * `background_db` is always pool-level — use it for fire-and-forget effects
- * that must outlive the transaction.
  */
 export interface RouteContext {
     /** Transaction-scoped for mutations, pool-level for reads. */
     db: Db;
-    /** Always pool-level — for fire-and-forget effects that outlive the transaction. */
+    /** Always pool-level — for fire-and-forget effects that must outlive the transaction. */
     background_db: Db;
     /** Fire-and-forget side effects — push here for post-response flushing. */
     pending_effects: Array<Promise<void>>;
@@ -76,20 +72,14 @@ export type RouteHandler = (c: Context, route: RouteContext) => Response | Promi
 export interface RouteSpec {
     method: RouteMethod;
     path: string;
-    /**
-     * Auth requirement for this route.
-     *
-     * `{type: 'none'}` means the route is open to all clients including non-browser
-     * callers (CLI, scripts) — no auth guards are applied.
-     */
     auth: RouteAuth;
     handler: RouteHandler;
     description: string;
     /**
      * URL path parameter schema. Use `z.strictObject()` with string fields matching `:param` segments.
      *
-     * TODO @action-system-review `params` is HTTP-specific — SAES encodes everything in
-     * `input`. When saes-rpc lands, this may move to `ActionRouteOptions` only.
+     * REST-only — actions dispatch through a single JSON-RPC endpoint and encode
+     * everything in `input`, so `params` doesn't appear on `ActionSpec`.
      */
     params?: z.ZodObject;
     /** URL query parameter schema. Use `z.strictObject()` with string fields. */
@@ -131,38 +121,30 @@ export interface RouteSpec {
 /**
  * Get validated input from the Hono context.
  *
- * Call this in route handlers after the input validation middleware has run.
- * The type parameter should match the route's `input` schema.
- *
- * @returns the validated request body
+ * Call after the input validation middleware has run. The type parameter
+ * should match the route's `input` schema.
  */
 export declare const get_route_input: <T>(c: Context) => T;
 /**
  * Get validated URL path params from the Hono context.
  *
- * Call this in route handlers after the params validation middleware has run.
- * The type parameter should match the route's `params` schema.
- *
- * TODO @action-system-review Make typesafe — derive `T` from the `params` schema on the
- * route spec so the type parameter isn't manually specified.
+ * Call after the params validation middleware has run. The type parameter
+ * should match the route's `params` schema.
  *
- * @returns the validated path parameters
+ * TODO derive `T` from the route spec so the type parameter isn't manually
+ * specified — same applies to `get_route_input` / `get_route_query`.
  */
 export declare const get_route_params: <T>(c: Context) => T;
 /**
  * Get validated URL query params from the Hono context.
  *
- * Call this in route handlers after the query validation middleware has run.
- * The type parameter should match the route's `query` schema.
- *
- * @returns the validated query parameters
+ * Call after the query validation middleware has run. The type parameter
+ * should match the route's `query` schema.
  */
 export declare const get_route_query: <T>(c: Context) => T;
 /**
  * Apply named middleware specs to a Hono app.
  *
- * @param app - the Hono app
- * @param specs - middleware specs to apply
  * @mutates `app`
  */
 export declare const apply_middleware_specs: (app: Hono, specs: Array<MiddlewareSpec>) => void;
@@ -179,20 +161,17 @@ export declare const apply_middleware_specs: (app: Hono, specs: Array<Middleware
  * - `background_db`: always pool-level
  * - `pending_effects`: fire-and-forget effect queue
  *
- * @param app - the Hono app
- * @param specs - route specs to apply
  * @param resolve_auth_guards - maps `RouteAuth` to middleware — use `fuz_auth_guard_resolver` from `auth/route_guards.ts`
- * @param log - the logger instance
- * @param db - database instance for transaction wrapping and `RouteContext`
+ * @param db - used for transaction wrapping and `RouteContext`
  * @mutates `app`
+ * @throws Error if two specs share the same `method` + `path` (each combination must be unique)
  */
 export declare const apply_route_specs: (app: Hono, specs: Array<RouteSpec>, resolve_auth_guards: AuthGuardResolver, log: Logger, db: Db) => void;
 /**
  * Prepend a prefix to all route spec paths.
  *
  * @param prefix - the path prefix (e.g. `/api/account`)
- * @param specs - route specs to prefix
- * @returns new array of specs with prefixed paths
+ * @returns a new array — the input specs are not mutated
  */
 export declare const prefix_route_specs: (prefix: string, specs: Array<RouteSpec>) => Array<RouteSpec>;
 //# sourceMappingURL=route_spec.d.ts.map

package/dist/http/route_spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route_spec.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/route_spec.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"route_spec.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/route_spec.ts"],"names":[],"mappings":"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"}

package/dist/http/route_spec.js

@@ -19,10 +19,8 @@ import { is_null_schema, merge_error_schemas } from './schema_helpers.js';
 /**
  * Get validated input from the Hono context.
  *
- * Call this in route handlers after the input validation middleware has run.
- * The type parameter should match the route's `input` schema.
- *
- * @returns the validated request body
+ * Call after the input validation middleware has run. The type parameter
+ * should match the route's `input` schema.
  */
 export const get_route_input = (c) => {
     return c.get('validated_input');
@@ -30,13 +28,11 @@ export const get_route_input = (c) => {
 /**
  * Get validated URL path params from the Hono context.
  *
- * Call this in route handlers after the params validation middleware has run.
- * The type parameter should match the route's `params` schema.
- *
- * TODO @action-system-review Make typesafe — derive `T` from the `params` schema on the
- * route spec so the type parameter isn't manually specified.
+ * Call after the params validation middleware has run. The type parameter
+ * should match the route's `params` schema.
  *
- * @returns the validated path parameters
+ * TODO derive `T` from the route spec so the type parameter isn't manually
+ * specified — same applies to `get_route_input` / `get_route_query`.
  */
 export const get_route_params = (c) => {
     return c.get('validated_params');
@@ -44,10 +40,8 @@ export const get_route_params = (c) => {
 /**
  * Get validated URL query params from the Hono context.
  *
- * Call this in route handlers after the query validation middleware has run.
- * The type parameter should match the route's `query` schema.
- *
- * @returns the validated query parameters
+ * Call after the query validation middleware has run. The type parameter
+ * should match the route's `query` schema.
  */
 export const get_route_query = (c) => {
     return c.get('validated_query');
@@ -60,6 +54,8 @@ export const get_route_query = (c) => {
  * and for null-input routes (no body expected). For other routes with input
  * schemas, returns a middleware that parses and validates the JSON body,
  * storing the result on the context as `validated_input`.
+ *
+ * @mutates `c.var.validated_input` - set to the parsed and validated body on success
  */
 const create_input_validation = (input_schema, method) => {
     if (method === 'GET')
@@ -92,6 +88,8 @@ const create_input_validation = (input_schema, method) => {
  * Returns an empty array when no params schema is defined.
  * For routes with params schemas, returns a middleware that validates
  * `c.req.param()` against the schema, storing the result on the context as `validated_params`.
+ *
+ * @mutates `c.var.validated_params` - set to the parsed and validated path params on success
  */
 const create_params_validation = (params_schema) => {
     if (!params_schema)
@@ -113,6 +111,8 @@ const create_params_validation = (params_schema) => {
  * Returns an empty array when no query schema is defined.
  * For routes with query schemas, returns a middleware that validates
  * `c.req.query()` against the schema, storing the result on the context as `validated_query`.
+ *
+ * @mutates `c.var.validated_query` - set to the parsed and validated query params on success
  */
 const create_query_validation = (query_schema) => {
     if (!query_schema)
@@ -182,8 +182,6 @@ const wrap_output_validation = (handler, output_schema, error_schemas, log) => {
 /**
  * Apply named middleware specs to a Hono app.
  *
- * @param app - the Hono app
- * @param specs - middleware specs to apply
  * @mutates `app`
  */
 export const apply_middleware_specs = (app, specs) => {
@@ -232,12 +230,10 @@ const wrap_error_catch = (handler, log) => {
  * - `background_db`: always pool-level
  * - `pending_effects`: fire-and-forget effect queue
  *
- * @param app - the Hono app
- * @param specs - route specs to apply
  * @param resolve_auth_guards - maps `RouteAuth` to middleware — use `fuz_auth_guard_resolver` from `auth/route_guards.ts`
- * @param log - the logger instance
- * @param db - database instance for transaction wrapping and `RouteContext`
+ * @param db - used for transaction wrapping and `RouteContext`
  * @mutates `app`
+ * @throws Error if two specs share the same `method` + `path` (each combination must be unique)
  */
 export const apply_route_specs = (app, specs, resolve_auth_guards, log, db) => {
     const registered = new Set();
@@ -269,8 +265,7 @@ export const apply_route_specs = (app, specs, resolve_auth_guards, log, db) => {
  * Prepend a prefix to all route spec paths.
  *
  * @param prefix - the path prefix (e.g. `/api/account`)
- * @param specs - route specs to prefix
- * @returns new array of specs with prefixed paths
+ * @returns a new array — the input specs are not mutated
  */
 export const prefix_route_specs = (prefix, specs) => {
     return specs.map((spec) => ({

package/dist/http/schema_helpers.d.ts

@@ -47,9 +47,6 @@ export declare const schema_to_surface: (schema: z.ZodType) => unknown;
  * - `/api/*` matches `/api/anything`
  * - `/api/tx/*` matches `/api/tx/runs` but not `/api/account/login`
  * - Exact match: `/health` matches `/health`
- *
- * @param mw_path - the middleware path pattern
- * @param route_path - the route path
  */
 export declare const middleware_applies: (mw_path: string, route_path: string) => boolean;
 /**
@@ -59,7 +56,6 @@ export declare const middleware_applies: (mw_path: string, route_path: string) =
  * Later layers override earlier ones for the same status code.
  *
  * @param spec - the route spec (needs `auth`, `input`, `params`, `rate_limit`, `errors`)
- * @param middleware_errors - optional middleware error schemas
  * @returns merged error schemas, or `null` if empty
  */
 export declare const merge_error_schemas: (spec: {

package/dist/http/schema_helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/schema_helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAuB,KAAK,YAAY,EAAE,KAAK,iBAAiB,EAAC,MAAM,oBAAoB,CAAC;AAEnG;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAAsC,CAAC;AAE1F;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAAsC,CAAC;AAE1F;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OACe,CAAC;AAE5E;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAQrD,CAAC;AAoBF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,EAAE,YAAY,MAAM,KAAG,OAQxE,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM;IACL,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACrB,KAAK,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACpB,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC3B,EACD,oBAAoB,iBAAiB,GAAG,IAAI,KAC1C,iBAAiB,GAAG,IAUtB,CAAC"}
+{"version":3,"file":"schema_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/schema_helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAuB,KAAK,YAAY,EAAE,KAAK,iBAAiB,EAAC,MAAM,oBAAoB,CAAC;AAEnG;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAAsC,CAAC;AAE1F;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAAsC,CAAC;AAE1F;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OACe,CAAC;AAE5E;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAQrD,CAAC;AAoBF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,EAAE,YAAY,MAAM,KAAG,OAQxE,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM;IACL,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACrB,KAAK,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACpB,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC3B,EACD,oBAAoB,iBAAiB,GAAG,IAAI,KAC1C,iBAAiB,GAAG,IAUtB,CAAC"}

package/dist/http/schema_helpers.js

@@ -76,9 +76,6 @@ const strip_json_schema_noise = (value) => {
  * - `/api/*` matches `/api/anything`
  * - `/api/tx/*` matches `/api/tx/runs` but not `/api/account/login`
  * - Exact match: `/health` matches `/health`
- *
- * @param mw_path - the middleware path pattern
- * @param route_path - the route path
  */
 export const middleware_applies = (mw_path, route_path) => {
     if (mw_path === '*')
@@ -98,7 +95,6 @@ export const middleware_applies = (mw_path, route_path) => {
  * Later layers override earlier ones for the same status code.
  *
  * @param spec - the route spec (needs `auth`, `input`, `params`, `rate_limit`, `errors`)
- * @param middleware_errors - optional middleware error schemas
  * @returns merged error schemas, or `null` if empty
  */
 export const merge_error_schemas = (spec, middleware_errors) => {

package/dist/http/surface.d.ts

@@ -70,6 +70,8 @@ export interface AppSurfaceRpcMethod {
     output_schema: unknown;
     side_effects: boolean;
     description: string;
+    /** Rate limit key declared on the action spec. `null` when not rate-limited. */
+    rate_limit_key: RateLimitKey | null;
 }
 /** An RPC endpoint in the generated attack surface (JSON-serializable). */
 export interface AppSurfaceRpcEndpoint {
@@ -120,8 +122,6 @@ export interface GenerateAppSurfaceOptions {
 /**
  * Collect error schemas from all middleware that applies to a route path.
  *
- * @param middleware - the middleware specs
- * @param route_path - the route path to match against
  * @returns merged middleware error schemas, or `null` if none
  */
 export declare const collect_middleware_errors: (middleware: Array<MiddlewareSpec>, route_path: string) => RouteErrorSchemas | null;
@@ -129,29 +129,19 @@ export declare const collect_middleware_errors: (middleware: Array<MiddlewareSpe
  * Convert env schema to surface entries using `.meta()` metadata.
  *
  * @param schema - Zod object schema with `.meta()` on fields
- * @returns array of env surface entries
  */
 export declare const env_schema_to_surface: (schema: z.ZodObject) => Array<AppSurfaceEnv>;
 /**
  * Convert SSE event specs to surface entries.
- *
- * @param event_specs - event specs to convert
- * @returns array of event surface entries
  */
 export declare const events_to_surface: (event_specs: Array<EventSpec>) => Array<AppSurfaceEvent>;
 /**
  * Generate a JSON-serializable attack surface from middleware, route specs,
  * and optional env/event metadata.
- *
- * @param options - the surface generation options
- * @returns the attack surface
  */
 export declare const generate_app_surface: (options: GenerateAppSurfaceOptions) => AppSurface;
 /**
  * Create an `AppSurfaceSpec` — the surface bundled with its source specs.
- *
- * @param options - the surface generation options
- * @returns the surface spec with surface and raw specs
  */
 export declare const create_app_surface_spec: (options: GenerateAppSurfaceOptions) => AppSurfaceSpec;
 //# sourceMappingURL=surface.d.ts.map

package/dist/http/surface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"surface.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/surface.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"surface.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/surface.ts"],"names":[],"mappings":"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"}

package/dist/http/surface.js

@@ -13,8 +13,6 @@ import { schema_to_surface, middleware_applies, merge_error_schemas, is_null_sch
 /**
  * Collect error schemas from all middleware that applies to a route path.
  *
- * @param middleware - the middleware specs
- * @param route_path - the route path to match against
  * @returns merged middleware error schemas, or `null` if none
  */
 export const collect_middleware_errors = (middleware, route_path) => {
@@ -30,7 +28,6 @@ export const collect_middleware_errors = (middleware, route_path) => {
  * Convert env schema to surface entries using `.meta()` metadata.
  *
  * @param schema - Zod object schema with `.meta()` on fields
- * @returns array of env surface entries
  */
 export const env_schema_to_surface = (schema) => {
     const entries = [];
@@ -50,9 +47,6 @@ export const env_schema_to_surface = (schema) => {
 };
 /**
  * Convert SSE event specs to surface entries.
- *
- * @param event_specs - event specs to convert
- * @returns array of event surface entries
  */
 export const events_to_surface = (event_specs) => {
     return event_specs.map((spec) => ({
@@ -65,9 +59,6 @@ export const events_to_surface = (event_specs) => {
 /**
  * Generate a JSON-serializable attack surface from middleware, route specs,
  * and optional env/event metadata.
- *
- * @param options - the surface generation options
- * @returns the attack surface
  */
 export const generate_app_surface = (options) => {
     const { route_specs, middleware_specs, env_schema, event_specs, rpc_endpoints } = options;
@@ -147,6 +138,7 @@ export const generate_app_surface = (options) => {
                     output_schema: schema_to_surface(a.spec.output),
                     side_effects: a.spec.side_effects,
                     description: a.spec.description,
+                    rate_limit_key: a.spec.rate_limit ?? null,
                 })),
             }))
             : [],
@@ -156,9 +148,6 @@ export const generate_app_surface = (options) => {
 };
 /**
  * Create an `AppSurfaceSpec` — the surface bundled with its source specs.
- *
- * @param options - the surface generation options
- * @returns the surface spec with surface and raw specs
  */
 export const create_app_surface_spec = (options) => {
     const surface = generate_app_surface(options);

package/dist/rate_limiter.d.ts

@@ -46,6 +46,22 @@ export interface RateLimiterOptions {
 export declare const DEFAULT_LOGIN_IP_RATE_LIMIT: RateLimiterOptions;
 /** Default options for per-account login rate limiting: 10 attempts per 30 minutes. */
 export declare const DEFAULT_LOGIN_ACCOUNT_RATE_LIMIT: RateLimiterOptions;
+/**
+ * Default options for per-IP action-dispatcher rate limiting: 600 attempts
+ * per 15 minutes. Shared by the HTTP RPC and WebSocket action dispatchers
+ * (one budget per action, not per transport). Permissive — catches runaway
+ * scripts and egregious oracle probes, but well above human or normal
+ * automation pace. Tighten downstream for stricter deployments.
+ */
+export declare const DEFAULT_ACTION_IP_RATE_LIMIT: RateLimiterOptions;
+/**
+ * Default options for per-actor action-dispatcher rate limiting: 1200
+ * attempts per 15 minutes. Shared by the HTTP RPC and WebSocket action
+ * dispatchers. Permissive — sustained ~80/min is well above any human
+ * admin workflow; an oracle probing 10k addresses still finishes in
+ * ~2 hours, slow enough to surface in audit. Tighten downstream.
+ */
+export declare const DEFAULT_ACTION_ACCOUNT_RATE_LIMIT: RateLimiterOptions;
 /**
  * Result of a rate limit check or record operation.
  */
@@ -83,8 +99,13 @@ export declare class RateLimiter {
     /**
      * Check whether `key` is allowed without recording an attempt.
      *
+     * Prunes timestamps that fell outside the window as a side effect (and
+     * removes the key entirely when none remain), so the backing map stays
+     * bounded even under read-only traffic.
+     *
      * @param key - rate limit key (e.g. IP address)
      * @param now - current timestamp in ms (defaults to `Date.now()`)
+     * @mutates internal map - prunes expired timestamps for `key`
      */
     check(key: string, now?: number): RateLimitResult;
     /**
@@ -92,19 +113,27 @@ export declare class RateLimiter {
      *
      * @param key - rate limit key (e.g. IP address)
      * @param now - current timestamp in ms (defaults to `Date.now()`)
+     * @mutates internal map - appends `now` to the timestamp list for `key` (after pruning expired entries)
      */
     record(key: string, now?: number): RateLimitResult;
     /**
      * Clear all attempts for `key` (e.g. after successful login).
+     *
+     * @mutates internal map - removes the entry for `key`
      */
     reset(key: string): void;
     /**
      * Remove entries whose timestamps are all outside the window.
      *
      * @param now - current timestamp in ms (defaults to `Date.now()`)
+     * @mutates internal map - prunes expired timestamps and deletes empty keys
      */
     cleanup(now?: number): void;
-    /** Stop the cleanup timer. Safe to call multiple times. */
+    /**
+     * Stop the cleanup timer. Safe to call multiple times.
+     *
+     * @mutates timer - clears the cleanup `setInterval` and nulls the handle
+     */
     dispose(): void;
 }
 /**

package/dist/rate_limiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rate_limiter.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/rate_limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,MAAM,CAAC;AAKlC;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,SAAU,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,iFAAiF;AACjF,eAAO,MAAM,2BAA2B,EAAE,kBAKzC,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,gCAAgC,EAAE,kBAK9C,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAW;;IACvB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;gBAOzB,OAAO,EAAE,kBAAkB;IAcvC,8BAA8B;IAC9B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,eAAe;IA2B7D;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,eAAe;IA0B9D;;OAEG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIxB;;;;OAIG;IACH,OAAO,CAAC,GAAG,GAAE,MAAmB,GAAG,IAAI;IAgBvC,2DAA2D;IAC3D,OAAO,IAAI,IAAI;CAMf;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAU,OAAO,CAAC,kBAAkB,CAAC,KAAG,WAE3E,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GAAI,GAAG,OAAO,EAAE,aAAa,MAAM,KAAG,QAI7E,CAAC"}
+{"version":3,"file":"rate_limiter.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/rate_limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,MAAM,CAAC;AAKlC;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,SAAU,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,iFAAiF;AACjF,eAAO,MAAM,2BAA2B,EAAE,kBAKzC,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,gCAAgC,EAAE,kBAK9C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,EAAE,kBAK1C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,kBAK/C,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAW;;IACvB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;gBAOzB,OAAO,EAAE,kBAAkB;IAcvC,8BAA8B;IAC9B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,eAAe;IA2B7D;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,eAAe;IA0B9D;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIxB;;;;;OAKG;IACH,OAAO,CAAC,GAAG,GAAE,MAAmB,GAAG,IAAI;IAgBvC;;;;OAIG;IACH,OAAO,IAAI,IAAI;CAMf;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAU,OAAO,CAAC,kBAAkB,CAAC,KAAG,WAE3E,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GAAI,GAAG,OAAO,EAAE,aAAa,MAAM,KAAG,QAI7E,CAAC"}

package/dist/rate_limiter.js

@@ -30,6 +30,32 @@ export const DEFAULT_LOGIN_ACCOUNT_RATE_LIMIT = {
     cleanup_interval_ms: 5 * 60_000,
     max_keys: DEFAULT_RATE_LIMITER_MAX_KEYS,
 };
+/**
+ * Default options for per-IP action-dispatcher rate limiting: 600 attempts
+ * per 15 minutes. Shared by the HTTP RPC and WebSocket action dispatchers
+ * (one budget per action, not per transport). Permissive — catches runaway
+ * scripts and egregious oracle probes, but well above human or normal
+ * automation pace. Tighten downstream for stricter deployments.
+ */
+export const DEFAULT_ACTION_IP_RATE_LIMIT = {
+    max_attempts: 600,
+    window_ms: 15 * 60_000,
+    cleanup_interval_ms: 5 * 60_000,
+    max_keys: DEFAULT_RATE_LIMITER_MAX_KEYS,
+};
+/**
+ * Default options for per-actor action-dispatcher rate limiting: 1200
+ * attempts per 15 minutes. Shared by the HTTP RPC and WebSocket action
+ * dispatchers. Permissive — sustained ~80/min is well above any human
+ * admin workflow; an oracle probing 10k addresses still finishes in
+ * ~2 hours, slow enough to surface in audit. Tighten downstream.
+ */
+export const DEFAULT_ACTION_ACCOUNT_RATE_LIMIT = {
+    max_attempts: 1200,
+    window_ms: 15 * 60_000,
+    cleanup_interval_ms: 5 * 60_000,
+    max_keys: DEFAULT_RATE_LIMITER_MAX_KEYS,
+};
 /**
  * In-memory sliding window rate limiter.
  *
@@ -71,8 +97,13 @@ export class RateLimiter {
     /**
      * Check whether `key` is allowed without recording an attempt.
      *
+     * Prunes timestamps that fell outside the window as a side effect (and
+     * removes the key entirely when none remain), so the backing map stays
+     * bounded even under read-only traffic.
+     *
      * @param key - rate limit key (e.g. IP address)
      * @param now - current timestamp in ms (defaults to `Date.now()`)
+     * @mutates internal map - prunes expired timestamps for `key`
      */
     check(key, now = Date.now()) {
         const { max_attempts, window_ms } = this.options;
@@ -102,6 +133,7 @@ export class RateLimiter {
      *
      * @param key - rate limit key (e.g. IP address)
      * @param now - current timestamp in ms (defaults to `Date.now()`)
+     * @mutates internal map - appends `now` to the timestamp list for `key` (after pruning expired entries)
      */
     record(key, now = Date.now()) {
         const { max_attempts, window_ms } = this.options;
@@ -128,6 +160,8 @@ export class RateLimiter {
     }
     /**
      * Clear all attempts for `key` (e.g. after successful login).
+     *
+     * @mutates internal map - removes the entry for `key`
      */
     reset(key) {
         this.#attempts.delete(key);
@@ -136,6 +170,7 @@ export class RateLimiter {
      * Remove entries whose timestamps are all outside the window.
      *
      * @param now - current timestamp in ms (defaults to `Date.now()`)
+     * @mutates internal map - prunes expired timestamps and deletes empty keys
      */
     cleanup(now = Date.now()) {
         const cutoff = now - this.options.window_ms;
@@ -153,7 +188,11 @@ export class RateLimiter {
             }
         }
     }
-    /** Stop the cleanup timer. Safe to call multiple times. */
+    /**
+     * Stop the cleanup timer. Safe to call multiple times.
+     *
+     * @mutates timer - clears the cleanup `setInterval` and nulls the handle
+     */
     dispose() {
         if (this.#cleanup_timer !== null) {
             clearInterval(this.#cleanup_timer);

package/dist/realtime/sse.d.ts

@@ -46,8 +46,8 @@ export interface SseNotification {
  * Uses `hono_stream.write()` directly (not `writeSSE`) to avoid
  * Hono's HTML callback resolution — keeps the same `data: JSON\n\n` format.
  *
- * @param c - Hono context
- * @returns object with response and stream controller
+ * @param log - logger for serialization and `on_close` listener errors
+ * @returns object with the streaming `Response` and an `SseStream` controller
  */
 export declare const create_sse_response: <T = unknown>(c: Context, log: Logger) => {
     response: Response;
@@ -57,9 +57,13 @@ export declare const create_sse_response: <T = unknown>(c: Context, log: Logger)
 export declare const SSE_CONNECTED_COMMENT = ": connected\n\n";
 /** Spec for a push event — declares params schema, description, and channel. */
 export interface EventSpec {
+    /** Event method name, used as the JSON-RPC notification `method`. */
     method: string;
+    /** Zod schema for the notification `params` payload. */
     params: z.ZodType;
+    /** Human-readable description for surface output and docs. */
     description: string;
+    /** Channel this event broadcasts on. Omit for cross-channel events. */
     channel?: string;
 }
 /**
@@ -70,6 +74,7 @@ export interface EventSpec {
  *
  * @param broadcaster - duck-typed broadcaster (e.g. `SubscriberRegistry`)
  * @param event_specs - event specs to validate against
+ * @param log - logger used to emit DEV warnings on unknown methods or param mismatches
  * @returns validated broadcaster wrapper (passthrough in production)
  */
 export declare const create_validated_broadcaster: <T extends SseNotification>(broadcaster: {

package/dist/realtime/sse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/realtime/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,MAAM,CAAC;AAElC,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO;IACrC,mDAAmD;IACnD,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;IACxB,6CAA6C;IAC7C,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,wBAAwB;IACxB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,+FAA+F;IAC/F,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,MAAM,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,GAAG,OAAO,EAC9C,GAAG,OAAO,EACV,KAAK,MAAM,KACT;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;CAiD3C,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,qBAAqB,oBAAoB,CAAC;AAEvD,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B,GAAI,CAAC,SAAS,eAAe,EACrE,aAAa;IAAC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;CAAC,EAC5D,aAAa,KAAK,CAAC,SAAS,CAAC,EAC7B,KAAK,MAAM,KACT;IAAC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;CAmBhD,CAAC"}
+{"version":3,"file":"sse.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/realtime/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,MAAM,CAAC;AAElC,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO;IACrC,mDAAmD;IACnD,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;IACxB,6CAA6C;IAC7C,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,wBAAwB;IACxB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,+FAA+F;IAC/F,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,MAAM,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,GAAG,OAAO,EAC9C,GAAG,OAAO,EACV,KAAK,MAAM,KACT;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;CAiD3C,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,qBAAqB,oBAAoB,CAAC;AAEvD,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACzB,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GAAI,CAAC,SAAS,eAAe,EACrE,aAAa;IAAC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;CAAC,EAC5D,aAAa,KAAK,CAAC,SAAS,CAAC,EAC7B,KAAK,MAAM,KACT;IAAC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;CAmBhD,CAAC"}

package/dist/realtime/sse.js

@@ -20,8 +20,8 @@ import { DEV } from 'esm-env';
  * Uses `hono_stream.write()` directly (not `writeSSE`) to avoid
  * Hono's HTML callback resolution — keeps the same `data: JSON\n\n` format.
  *
- * @param c - Hono context
- * @returns object with response and stream controller
+ * @param log - logger for serialization and `on_close` listener errors
+ * @returns object with the streaming `Response` and an `SseStream` controller
  */
 export const create_sse_response = (c, log) => {
     const { promise, resolve } = Promise.withResolvers();
@@ -84,6 +84,7 @@ export const SSE_CONNECTED_COMMENT = `: connected\n\n`;
  *
  * @param broadcaster - duck-typed broadcaster (e.g. `SubscriberRegistry`)
  * @param event_specs - event specs to validate against
+ * @param log - logger used to emit DEV warnings on unknown methods or param mismatches
  * @returns validated broadcaster wrapper (passthrough in production)
  */
 export const create_validated_broadcaster = (broadcaster, event_specs, log) => {