@7h3/protocol 0.5.3 → 0.5.6

package/gateway.d.ts

@@ -1,6 +1,6 @@
 import { type KeyRegistry } from './keyRegistry';
 import { type RoutePolicy } from './routePolicy';
-import { SlidingWindowRateLimiter } from './rateLimiter';
+import { SlidingWindowRateLimiter, type RateLimitStore } from './rateLimiter';
 import type { ReplayStore } from './replayStores';
 export type { KeyRegistry, RoutePolicy };
 export interface GatewayConfig {
@@ -15,6 +15,14 @@ export interface GatewayConfig {
     metricsPath?: string;
     /** Optional distributed replay store — prevents nonce reuse across gateway instances. */
     replayStore?: ReplayStore;
+    /**
+     * Optional persistent rate-limit store — required for correct rate limiting
+     * whenever the gateway is rebuilt per-request (e.g. inside a Workers/Lambda
+     * fetch handler). Without it, rate limiting falls back to the in-memory
+     * SlidingWindowRateLimiter, which only works if this Gateway instance
+     * persists across the requests it's limiting.
+     */
+    rateLimitStore?: RateLimitStore;
     /** Optional capability token registry for capability-based auth. */
     capabilityRegistry?: {
         getPublicKey(id: string): Promise<string | null>;
@@ -38,16 +46,42 @@ export type GatewayVerifyOutcome = {
     envelopeId?: string;
 } | {
     ok: false;
-    status: 401 | 403 | 429;
+    status: 400 | 401 | 403 | 429;
     reason: string;
 };
+/**
+ * Normalize a request path before it's used for both policy matching and
+ * upstream forwarding. Without this, a path like `/public/../admin/secret`
+ * matches a permissive `/public/**` policy (or no policy at all, under
+ * `defaultPolicy: 'allow'`) as a literal string, is forwarded unverified,
+ * and then gets collapsed by the URL parser inside `fetch()` on the way out
+ * — landing on `/admin/secret` at the upstream with zero verification ever
+ * having been performed against the path that's actually reached. Matching
+ * and forwarding must both operate on the same fully-normalized path so
+ * there's no gap between what was checked and what was sent.
+ *
+ * Returns null for anything that isn't a clean absolute path — including a
+ * `..` that would escape above the root, or percent-encoding that doesn't
+ * settle after a bounded number of decode passes (double-encoding is a
+ * classic way to smuggle a traversal past a single decode).
+ */
+export declare function normalizeGatewayPath(rawPath: string): string | null;
 declare class Protocol7h3Gateway {
     private config;
     private rateLimiter;
     constructor(config: GatewayConfig);
+    private checkSenderAndRateLimit;
     verify(req: GatewayRequest): Promise<GatewayVerifyOutcome>;
     handle(req: GatewayRequest): Promise<GatewayResponse>;
     getRateLimiter(): SlidingWindowRateLimiter;
 }
 export declare function createGateway(config: GatewayConfig): Protocol7h3Gateway;
+/**
+ * Hardened preset for production deployments: fails fast (rather than
+ * silently falling back to permissive defaults) if `defaultPolicy` isn't
+ * explicitly `'deny'` or `replayStore` isn't configured. Use this instead of
+ * `createGateway()` wherever a misconfiguration should be a deploy-time error,
+ * not a runtime security gap discovered later.
+ */
+export declare function createProductionGateway(config: GatewayConfig): Protocol7h3Gateway;
 export { Protocol7h3Gateway };