@supacloud/elysia 0.17.0 → 0.19.0

package/README.md

@@ -1,5 +1,11 @@
 # @supacloud/elysia
 
+For a cross-module composition shared by HTTP, event/scheduled workers and a
+trusted CLI, see the [fulfillment example](src/examples/fulfillment.ts) and
+[developer guide](../../docs/framework-composition.md). It reuses bound commands,
+explicit aspects and durable receipts, not a new workflow engine. Compensation
+is a separately authorized business command, never an assumed rollback.
+
 ## Compatibility and Acceptance Boundary
 
 The dependency range is not a claim that every allowed version has been tested.
@@ -89,6 +95,81 @@ These gates prove the stated scenarios, not a full historical npm upgrade matrix
 or all business-domain isolation. See [framework acceptance](../../docs/framework-acceptance.md)
 for the evidence boundaries and upgrade policy.
 
+## Native HTTP Context And Static DI
+
+Pass a native Elysia plugin as `http` to `createApplication`, `createTestApp`,
+or the options argument of `createModulePlugin`. `decorate` shares existing
+instances; `derive` runs before validation; `resolve` runs after validation.
+Use scoped/global hooks, or finish a context plugin with `.as("scoped")`.
+Local hooks retain native encapsulation and do not extend the consuming routes.
+
+```ts
+import { Elysia, t } from "elysia";
+import { createApplication } from "@supacloud/elysia";
+
+const http = new Elysia({ name: "application-context" })
+  .decorate("clock", { now: () => Date.now() })
+  .derive(({ clock }) => ({ startedAt: clock.now() }))
+  .guard({ query: t.Object({ locale: t.Optional(t.String()) }) })
+  .resolve(({ query }) => ({ locale: query.locale ?? "en" }))
+  .as("scoped");
+
+const app = createApplication({
+  http,
+  modules: compiledModules,
+  requestContext: (request, context) => ({
+    request,
+    startedAt: context.startedAt,
+    locale: context.locale,
+  }),
+}).get("/locale", ({ locale, clock }) => ({
+  locale,
+  now: clock.now(),
+}));
+```
+
+The second `requestContext` argument contains the validated HTTP inputs and
+the inferred native plugin extensions. Existing one-argument factories remain
+valid. Its result is passed to generated request-scoped constructors and the
+controller's `context`/`requestContext` input. It is built once per request;
+early resolver responses and validation failures do not construct DI scopes.
+Request scopes are created inside the existing governed handler and released
+after the response, including handler failures. They are not application
+singletons or native `resolve` hooks.
+
+Native routes added to the returned app retain the HTTP plugin's decorator,
+derive and resolve types. `createModulePlugin` also preserves the concrete
+`services` type supplied by its caller. Module service bags are attached by
+the module-local resolver, not merged into a root `decorator.services` bag;
+the service instances themselves remain shared. This prevents same-named
+services in sibling modules from overwriting each other's values or types.
+
+Fresh compiler output preserves literal module names and inferred application
+service factory results. Narrow a generated module by its `name`, call its
+`createServices`, and pass that result to `createModulePlugin` to retain the
+service types. Regenerate older artifacts to obtain this inference; explicitly
+annotating them as `CompiledModule[]` still intentionally widens the types.
+Compiled route schemas are runtime
+descriptors: their body/params/query/header/cookie fields in the application-wide
+context factory remain `unknown`-based instead of pretending to infer one
+route's schema for every route. Use shared guards for schema-typed native
+resolvers and the existing generated contracts for individual compiled routes.
+Do not store per-request identity or transaction handles in decorated singletons.
+
+The `http` plugin is composed into each compiled module and subsequently into
+the root for native routes. Keep it focused on reusable context extensions;
+register unrelated endpoints on the returned app. Hook execution is tested
+for named/anonymous plugins and scoped/global hooks without duplicate work.
+Anonymous extensions receive a stable internal plugin identity for native
+hook deduplication; the caller's plugin configuration is not mutated.
+This is native HTTP composition, not a replacement runtime DI container or
+an arbitrary native-hook passthrough in compiled route descriptors.
+
+`src/http-context.test.ts` covers lifecycle ordering, decoded inputs, failure
+short-circuiting, context/service type inference, cross-module composition and
+concurrent request isolation. Run it with `bun run typecheck:test` as well as
+`bun test src/http-context.test.ts`; runtime tests alone do not verify inference.
+
 ## Persistent Command Adapters
 
 `createPersistentCommandAdapter(command, { identity, input })` binds a
@@ -112,6 +193,67 @@ authorization infrastructure failure is 503, and redacted-input lookup is 410.
 See [the migration plan](../../docs/command-migration.md) for compiler policy,
 authentication replay changes, deployment order and rollback limitations.
 
+## Bind A Command Once
+
+`bindCompiledCommand` is an optional convenience layer over
+`executeCompiledCommand` and `previewCompiledCommand`. Register static wiring
+once and supply fresh trusted host context for each invocation:
+
+```ts
+import { bindCompiledCommand } from "@supacloud/elysia";
+
+const approve = bindCompiledCommand({
+  module: generatedApprovalModule,
+  command: "ApproveCommand", // compiled class name
+  governance,
+  handler: (input: ApproveInput, call) =>
+    approvalService.execute(input, call.requestContext),
+  decode: decodeApprovalResult,
+  preview: (input, call) =>
+    approvalService.preview(input, call.requestContext),
+});
+
+// In a trusted HTTP controller, Worker job, or server-side CLI adapter:
+const result = await approve.execute(input, {
+  request,
+  requestContext: verifiedContext,
+  services,
+  scope,
+});
+```
+
+The generated module, domain types, service, decoder and governance above are
+supplied by the application. The wrapper does not implement a second business
+model, permission system, transaction mechanism or identity provider.
+
+- A binding does not execute business code or capture a request identity.
+  Calls still resolve the descriptor and authorize each execution, including
+  idempotent replays. Static dependencies should be application-scoped; resolve
+  request/job-scoped services from the current `call.scope` instead of capturing
+  them in the binding.
+- `preview` is present only when a domain preview function was supplied.
+  An explicit callback makes it callable without a presence check; dynamically
+  optional configuration still requires checking `approve.preview`. It reuses the existing read-only
+  preview API: authorization and domain preview only, no command execution,
+  aspects, transaction, idempotency, RPC or audit.
+- Keep decoding/validating untrusted input at the existing ingress/domain
+  boundary. A TypeScript input type alone is not runtime validation.
+- An HTTP handler calling `approve.execute` must not also bind that same
+  command through route-level `command:` metadata. Choose one execution
+  boundary to avoid duplicate authorization or aspect execution. Likewise,
+  place command aspects on the business module, not a duplicate entry module.
+- Workers must resolve trusted identity in the host and explicitly construct
+  the call's `Request`, cancellation signal and idempotency context where
+  applicable. Do not infer identity from queue payloads. The binding adds no
+  retry, acknowledgement or scope-cleanup policy.
+- The result decoder still runs after execution or receipt replay. A decoding
+  failure does not prove rollback and must not trigger a blind retry.
+
+Existing direct APIs, route bindings, custom executors, RPC adapters and Worker
+transports remain available without adopting the binding. Local parity tests
+cover HTTP and Worker ingress with fake governance adapters; real database
+atomicity remains covered by the separate PostgreSQL acceptance gates.
+
 Runtime adapter that turns `@supacloud/compiler` output into a production-ready
 [Elysia](https://elysiajs.com/) application.
 
@@ -526,3 +668,180 @@ registration instead of silently disabling response validation.
 
 See [type safety and migration](../../docs/type-safety.md) and [command migration](../../docs/command-migration.md) for examples and
 the distinction between contract declarations and runtime verification.
+
+## Declarative HTTP Policies
+
+Business dependency wiring remains generated constructors and factories. HTTP
+policies are selected using existing compiler-preserved route metadata:
+
+```ts
+@Get("/:id", {
+  data: { httpPolicies: [{ name: "authenticated" }] },
+})
+getItem() { /* domain handler */ }
+```
+
+Register implementations at the HTTP composition root:
+
+```ts
+const app = createApplication({
+  modules: createCompiledModules(),
+  http: identityPlugin,
+  httpPolicies: {
+    authenticated: (options, route) => {
+      // Validate options here. This factory runs once per declared route policy.
+      return async ({ http }) => {
+        if (!http.identity) {
+          return new Response("Unauthorized", { status: 401 });
+        }
+      };
+    },
+  },
+});
+```
+
+`identityPlugin` is an application-owned scoped/global Elysia plugin that verifies
+credentials and resolves `identity`; the adapter does not trust a raw user/tenant
+header as identity. Policy callbacks preserve its native context types.
+
+Policies become native route-local `beforeHandle` hooks. They execute sequentially
+after schema validation, native resolvers and the application request-context
+factory, but before compiled request-scope construction and command execution.
+Return `undefined` to continue or a `Response` to stop; thrown errors use the
+application error mapper. Native earlier hooks can still short-circuit the request.
+Unknown policies, malformed declarations and invalid factories reject startup.
+Routes without declarations do not install a policy hook.
+
+Use the registry for custom resource access or application-owned HTTP policies.
+For bundled security, rate limiting, caching and tracing, use the suite below. Shared factories
+must not retain mutable per-request state; use the callback's request/context.
+Cleanup belongs to native lifecycle hooks. Transactions, durable audit, idempotency
+and recovery remain in command governance, not HTTP policies.
+
+Policy metadata can appear in generated clients: never put secrets in options.
+Changes to declarations or registry configuration require creating a new application.
+
+### Built-In Security And Governance
+
+```ts
+import {
+  createApplication, createHttpPolicySuite, createHttpTelemetry,
+  createMemoryHttpRateLimitStore, createMemoryHttpCacheStore,
+} from "@supacloud/elysia";
+
+const suite = createHttpPolicySuite({
+  auth: supAuthOptions,
+  cacheNamespace: "release-2026-09-25",
+  rateLimitStore: createMemoryHttpRateLimitStore({ maxEntries: 10_000 }),
+  cacheStore: createMemoryHttpCacheStore({ maxEntries: 1_000, maxBytes: 8 * 1024 * 1024 }),
+});
+const app = createApplication({
+  ...suite,
+  modules: createCompiledModules(),
+  http: createHttpTelemetry((event) => logger.info(event)),
+});
+```
+
+`supAuthOptions` uses `createSupAuthRequestContext`'s existing configuration:
+trusted issuer, audience, application client ID, project ID, HTTPS JWKS endpoint
+and `resolveAccess` for current server-side tenant membership/permissions.
+JWT verification and membership resolution run on every credentialed request,
+including cache hits. They are not replaced by a tenant or user header.
+Requests without Authorization get an anonymous identity; public routes may
+remain anonymous. Invalid supplied credentials are rejected even on public routes.
+Use the suite's paired `requestContext`; the registry cannot trust fabricated
+context objects or forwarded subjects. Additional native context plugins may be
+composed with the telemetry plugin using ordinary Elysia `.use(...)`.
+
+Routes select built-ins through metadata (use `BuiltinHttpPolicyDeclaration`
+with TypeScript `satisfies` for author-time option checking):
+
+```ts
+@Get("/tenants/:tenant/items", {
+  data: {
+    httpPolicies: [
+      { name: "authenticated" },
+      { name: "tenant", options: { param: "tenant" } },
+      { name: "permission", options: { allOf: ["items.read"] } },
+      { name: "rateLimit", options: { limit: 120, windowMs: 60_000 } },
+      { name: "cache", options: { ttlMs: 5_000, maxBodyBytes: 262_144 } },
+    ],
+  },
+})
+listItems() { /* use the verified tenant in repository queries */ }
+```
+
+- `authenticated`: requires successful JWT verification and active application access.
+- `tenant`: matches a validated route parameter to that access record's tenant.
+  It is an HTTP boundary check, not automatic repository filtering or database RLS.
+- `permission`: requires every exact permission in `allOf`; no wildcard inference.
+- `rateLimit`: fixed-window quota scoped to route, issuer, application, actor and
+  tenant. It does not trust forwarded IP headers. Denials return 429 with
+  `Retry-After`; unavailable storage returns a sanitized 503. Anonymous/IP abuse
+  protection belongs at the trusted proxy or an explicitly configured native hook.
+- `cache`: authenticated, private GET query caching only; commands are rejected.
+  It must be last, so cache hits cannot skip declared permission or quota checks.
+  Keys hash trusted identity, permissions, complete URL and request headers
+  except the correlation ID. Credentials and query contents are not stored as keys.
+  Only successful plain JSON object/array results are stored. Native responses,
+  streams, errors, oversized output, cookies, Vary, custom response headers and
+  cache-control prohibitions are conservatively excluded. Conditional/range
+  requests and request no-cache/no-store bypass caching. Cache-read outages return
+  503; post-response write failures notify `onCacheWriteError` (sanitized warning
+  by default) without changing a completed response.
+- `createHttpTelemetry`: emits immutable request ID, method, static route template,
+  final status and duration after responses, including denied and invalid requests.
+  The response header and command/request context share the same correlation ID.
+  It never emits raw paths, query parameters, tokens, bodies or errors. Observer
+  failures cannot change business results. Connect the observer to your logger or
+  telemetry exporter; this is request tracing, not an OpenTelemetry backend.
+
+The memory stores are explicitly **single-process**. Quota capacity exhaustion
+fails closed rather than evicting active quotas; local cache storage is bounded
+by entry count and byte budget. They do not coordinate replicas.
+
+### Shared PostgreSQL Stores
+
+Apply `HTTP_POLICY_STORE_SQL` through normal migrations, then use
+`createPostgresHttpPolicyStores(database)`. Its database port takes a parameterized
+`query(text, parameters)` function; it does not own a pool or transaction scope:
+
+```ts
+const stores = createPostgresHttpPolicyStores({
+  query: async (text, parameters) => Array.from(await sql.unsafe(text, [...parameters])),
+});
+const suite = createHttpPolicySuite({ auth: supAuthOptions, cacheNamespace: deploymentId, ...stores });
+```
+
+Concurrent replicas share an atomic row-locked quota and persistent
+cache entries. Tables live in `supacloud_http` with no PUBLIC privileges. Grant
+only the server runtime's database role access; never expose store credentials to
+clients. Different applications/issuers/tenants/users have distinct keys.
+
+Schedule `stores.prune()` to remove expired rows and monitor database size.
+`cacheNamespace` is mandatory when a cache policy is declared. Use the same
+namespace across replicas of one release and a different namespace for every
+representation/schema/security-rule revision. This prevents old in-flight requests
+from repopulating the current release's cache; reusing a namespace opts into reuse.
+Use TTLs appropriate for stale-read tolerance and invoke `cacheStore.clear()` only
+after a confirmed write when explicit broad invalidation is desired. Clear advances
+a shared generation atomically; fills from older generations are rejected. Already
+in-flight HTTP responses are not cancelled. Custom stores must implement the same
+generation/check-and-write contract. Do not cache responses
+containing per-request IDs, nonces or time-sensitive authorization decisions.
+These stores do not provide business transactions or durable audit.
+
+### Reproducible Performance Checks
+
+Run `bun run bench:http-policy [output.json]`. Optional environment settings:
+`BENCH_REQUESTS`, `BENCH_ROUNDS`, `BENCH_CONCURRENCY`. It compares native static
+Elysia, compiled static DI, one no-op policy, and a full verified policy pipeline.
+The harness warms each case, rotates case order, validates every response and
+records throughput, P50/P95/P99, live heap deltas and RSS. Cache hits and misses
+are separate scenarios with asserted handler/hit/fill counts; sorting is outside
+the throughput timer.
+
+Loopback results include the same-process fetch client; heap deltas are affected
+by GC and are **not total allocation counts**. Full-policy results include local
+ES256 verification, not remote identity/database latency. See
+[acceptance evidence](../../docs/http-policy-acceptance.md) for the measured scope.

package/dist/command-binding.d.ts

@@ -0,0 +1,33 @@
+import type { CommandPreview } from "@supacloud/contracts";
+import { type CommandGovernance, type CompiledModule, type ExecutionObserver } from "./index";
+/** Supplied by the trusted host for each call, never captured as binding configuration. */
+export interface CompiledCommandCallContext {
+    request: Request;
+    requestContext: unknown;
+    services?: Record<string, unknown>;
+    scope?: Record<string, unknown>;
+}
+export interface CompiledCommandBindingOptions<Input, Result> {
+    module: Pick<CompiledModule, "name" | "commands" | "aspects" | "aspectPipeline">;
+    /** Compiled command class name, as required by executeCompiledCommand. */
+    command: string;
+    governance: CommandGovernance;
+    observer?: ExecutionObserver;
+    handler(input: Input, context: CompiledCommandCallContext): Result | Promise<Result>;
+    decode(value: unknown): Result;
+    preview?(input: Input, context: CompiledCommandCallContext): unknown;
+}
+export interface CompiledCommandBinding<Input, Result> {
+    execute(input: Input, context: CompiledCommandCallContext): Promise<Result>;
+    preview?(input: Input, context: CompiledCommandCallContext): Promise<CommandPreview>;
+}
+/**
+ * Binds static wiring, not an identity or an execution outcome.
+ * All policy, replay, aspects and decoding remain in the existing command APIs.
+ */
+export declare function bindCompiledCommand<Input, Result>(options: CompiledCommandBindingOptions<Input, Result> & {
+    preview: NonNullable<CompiledCommandBindingOptions<Input, Result>["preview"]>;
+}): CompiledCommandBinding<Input, Result> & {
+    preview(input: Input, context: CompiledCommandCallContext): Promise<CommandPreview>;
+};
+export declare function bindCompiledCommand<Input, Result>(options: CompiledCommandBindingOptions<Input, Result>): CompiledCommandBinding<Input, Result>;

package/dist/examples/fulfillment.d.ts

@@ -0,0 +1,38 @@
+import type { DurableCommandReceipt } from "@supacloud/contracts";
+import type { CompiledCommandBinding, CompiledCommandCallContext } from "../command-binding";
+export interface OrderInput {
+    orderId: string;
+}
+export interface ReservationInput extends OrderInput {
+    reservationId: string;
+}
+export interface ReservationResult {
+    reservationId: string;
+}
+export interface PaymentResult {
+    outcome: "paid" | "declined";
+}
+export interface OrderResult {
+    orderId: string;
+}
+export interface FulfillmentSteps {
+    reserve: CompiledCommandBinding<OrderInput, DurableCommandReceipt<ReservationResult>>;
+    charge: CompiledCommandBinding<ReservationInput, DurableCommandReceipt<PaymentResult>>;
+    confirm: CompiledCommandBinding<ReservationInput, DurableCommandReceipt<OrderResult>>;
+    release: CompiledCommandBinding<ReservationInput, DurableCommandReceipt<OrderResult>>;
+}
+export type FulfillmentOutcome = {
+    status: "completed" | "declined";
+    orderId: string;
+} | {
+    status: "pending";
+    step: keyof FulfillmentSteps;
+    operationId: string;
+};
+/**
+ * Application-owned composition, not a scheduler or a distributed transaction.
+ * Each bound step owns authorization, durable receipts and its local transaction.
+ */
+export declare function createFulfillment(steps: FulfillmentSteps): {
+    execute(input: OrderInput, context: CompiledCommandCallContext): Promise<FulfillmentOutcome>;
+};

package/dist/fixtures/webhook-generated/application.d.ts

@@ -1,4 +1,7 @@
+import { UpdateWebhook } from "../webhook/update.command";
 export interface CompiledRoute {
+    parse?: "none";
+    allowDeleteBody?: true;
     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
     path: string;
     handler: string;
@@ -101,7 +104,14 @@ export interface CompiledModule {
 }
 type CompiledAspectObserver = (stage: string, run: () => unknown | Promise<unknown>) => unknown | Promise<unknown>;
 type CompiledAspectPipeline = (context: CompiledAspectContext, next: () => unknown | Promise<unknown>, observe?: CompiledAspectObserver) => unknown | Promise<unknown>;
-export declare function createCompiledModules(): CompiledModule[];
+export type CompiledApplicationModule = Omit<CompiledModule, "name" | "createServices"> & ({
+    name: "webhook";
+    createServices: typeof createWebhookServices;
+});
+export declare function createCompiledModules(): CompiledApplicationModule[];
 export declare function initializeApplication(services: Record<string, unknown>): Promise<void>;
 export declare function destroyApplication(services: Record<string, unknown>): Promise<void>;
+declare function createWebhookServices(deps: Record<string, unknown>, imported: Record<string, Record<string, unknown>>): {
+    updateWebhook: UpdateWebhook;
+};
 export {};

package/dist/http-policy-postgres.d.ts

@@ -0,0 +1,12 @@
+import type { HttpCacheStore, HttpRateLimitStore } from "./http-policy-stores";
+export interface HttpPolicyDatabase {
+    query(text: string, parameters: readonly unknown[]): Promise<readonly Record<string, unknown>[]>;
+}
+/** Apply through migrations, never from a request. Credentials must be server-only. */
+export declare const HTTP_POLICY_STORE_SQL = "\nCREATE SCHEMA IF NOT EXISTS supacloud_http;\nREVOKE ALL ON SCHEMA supacloud_http FROM PUBLIC;\nCREATE TABLE IF NOT EXISTS supacloud_http.rate_limits (\n  key text PRIMARY KEY CHECK (key ~ '^[a-f0-9]{64}$'),\n  used bigint NOT NULL CHECK (used > 0),\n  reset_at timestamptz NOT NULL\n);\nCREATE INDEX IF NOT EXISTS http_rate_limit_expiry ON supacloud_http.rate_limits(reset_at);\nCREATE TABLE IF NOT EXISTS supacloud_http.response_cache (\n  key text PRIMARY KEY CHECK (key ~ '^[a-f0-9]{64}$'),\n  body text NOT NULL CHECK (octet_length(body) <= 16777216),\n  expires_at timestamptz NOT NULL,\n  generation uuid NOT NULL\n);\nALTER TABLE supacloud_http.response_cache ADD COLUMN IF NOT EXISTS generation uuid\n  NOT NULL DEFAULT '00000000-0000-0000-0000-000000000000';\nCREATE TABLE IF NOT EXISTS supacloud_http.cache_generation (\n  singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton),\n  generation uuid NOT NULL DEFAULT gen_random_uuid()\n);\nINSERT INTO supacloud_http.cache_generation(singleton) VALUES (true) ON CONFLICT DO NOTHING;\nCREATE INDEX IF NOT EXISTS http_response_cache_expiry ON supacloud_http.response_cache(expires_at);\nREVOKE ALL ON ALL TABLES IN SCHEMA supacloud_http FROM PUBLIC;\nCREATE OR REPLACE FUNCTION supacloud_http.consume_rate_limit(p_key text, p_limit bigint, p_window_ms integer)\nRETURNS TABLE(allowed boolean, remaining bigint, reset_at_ms numeric)\nLANGUAGE plpgsql SET search_path = pg_catalog, supacloud_http AS $rate$\nDECLARE\n  entry supacloud_http.rate_limits%ROWTYPE;\n  observed_at timestamptz;\nBEGIN\n  IF p_limit < 1 OR p_limit > 1000000000 OR p_window_ms < 1 OR p_window_ms > 86400000 THEN\n    RAISE EXCEPTION 'Invalid rate limit window';\n  END IF;\n  LOOP\n    INSERT INTO supacloud_http.rate_limits(key, used, reset_at)\n      VALUES (p_key, 1, '-infinity') ON CONFLICT DO NOTHING;\n    SELECT * INTO entry FROM supacloud_http.rate_limits WHERE key=p_key FOR UPDATE;\n    EXIT WHEN FOUND;\n    -- Expiry pruning may remove a conflicting row before we acquire its lock.\n  END LOOP;\n  observed_at := clock_timestamp();\n  IF entry.reset_at <= observed_at THEN\n    entry.used := 1;\n    entry.reset_at := observed_at + p_window_ms * interval '1 millisecond';\n  ELSE\n    entry.used := least(entry.used + 1, p_limit + 1);\n  END IF;\n  UPDATE supacloud_http.rate_limits SET used=entry.used, reset_at=entry.reset_at WHERE key=p_key;\n  RETURN QUERY SELECT entry.used <= p_limit, greatest(p_limit-entry.used,0),\n    extract(epoch FROM entry.reset_at)*1000;\nEND\n$rate$;\nREVOKE ALL ON FUNCTION supacloud_http.consume_rate_limit(text,bigint,integer) FROM PUBLIC;\n";
+/** Independent instances sharing a database share atomic quotas and private cache entries. */
+export declare function createPostgresHttpPolicyStores(database: HttpPolicyDatabase): {
+    rateLimitStore: HttpRateLimitStore;
+    cacheStore: HttpCacheStore;
+    prune(): Promise<void>;
+};

package/dist/http-policy-stores.d.ts

@@ -0,0 +1,33 @@
+export interface HttpRateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    resetAt: number;
+}
+export interface HttpRateLimitStore {
+    /** Must atomically consume one request across every process sharing this store. */
+    consume(key: string, limit: number, windowMs: number): HttpRateLimitResult | Promise<HttpRateLimitResult>;
+}
+export interface HttpCacheEntry {
+    body: string;
+    contentType: string;
+    expiresAt: number;
+}
+export interface HttpCacheStore {
+    generation(): string | Promise<string>;
+    get(key: string, generation: string): HttpCacheEntry | undefined | Promise<HttpCacheEntry | undefined>;
+    /** Atomically refuse fills from an invalidated generation. */
+    set(key: string, value: HttpCacheEntry, generation: string): void | Promise<void>;
+    /** Invalidation is explicit, never inferred from a write that may have failed. */
+    clear(): void | Promise<void>;
+}
+/** Single-process fixed windows. Capacity exhaustion fails closed, not quota eviction. */
+export declare function createMemoryHttpRateLimitStore(options?: {
+    maxEntries?: number;
+    now?: () => number;
+}): HttpRateLimitStore;
+/** Bounded local LRU; use a shared store for cross-process caching/invalidation. */
+export declare function createMemoryHttpCacheStore(options?: {
+    maxEntries?: number;
+    maxBytes?: number;
+    now?: () => number;
+}): HttpCacheStore;

package/dist/http-policy-suite.d.ts

@@ -0,0 +1,75 @@
+import { type SupaCloudRequestContext } from "./index";
+import { type SupAuthContextOptions, type SupAuthRequestContext } from "./identity";
+import type { HttpPolicy } from "./http-policy";
+import type { HttpCacheStore, HttpRateLimitStore } from "./http-policy-stores";
+export type BuiltinHttpPolicyDeclaration = {
+    name: "authenticated";
+    options?: never;
+} | {
+    name: "tenant";
+    options: {
+        param: string;
+    };
+} | {
+    name: "permission";
+    options: {
+        allOf: readonly string[];
+    };
+} | {
+    name: "rateLimit";
+    options: {
+        limit: number;
+        windowMs: number;
+    };
+} | {
+    name: "cache";
+    options: {
+        ttlMs: number;
+        maxBodyBytes?: number;
+    };
+};
+export interface HttpPolicySuiteOptions {
+    auth: SupAuthContextOptions;
+    rateLimitStore?: HttpRateLimitStore;
+    cacheStore?: HttpCacheStore;
+    /** Required for cache policies. Change for each representation/deployment version. */
+    cacheNamespace?: string;
+    /** Sanitized operational notification; no exception, key, user or payload. */
+    onCacheWriteError?: () => void;
+}
+export declare function policyOptions(value: unknown, allowed: readonly string[]): Record<string, unknown>;
+export declare function positiveInteger(value: unknown, max: number): number;
+export declare function policyKey(parts: unknown[]): Promise<string>;
+export declare function principalKey(context: SupAuthRequestContext): unknown[];
+/** Pair the returned factory and registry; only this verifier can populate policy identity. */
+export declare function createHttpPolicySuite(options: HttpPolicySuiteOptions): {
+    requestContext: (request: Request) => Promise<SupaCloudRequestContext | SupAuthRequestContext>;
+    httpPolicies: Readonly<Record<string, (options: unknown, route: Readonly<Pick<import("./index").CompiledRoute, "method" | "path" | "command">>) => HttpPolicy<import("elysia").default<"", {
+        decorator: {};
+        store: {};
+        derive: {};
+        resolve: {};
+    }, {
+        typebox: {};
+        error: {};
+    }, {
+        schema: {};
+        standaloneSchema: {};
+        macro: {};
+        macroFn: {};
+        parser: {};
+        response: {};
+    }, {}, {
+        derive: {};
+        resolve: {};
+        schema: {};
+        standaloneSchema: {};
+        response: {};
+    }, {
+        derive: {};
+        resolve: {};
+        schema: {};
+        standaloneSchema: {};
+        response: {};
+    }>>>>;
+};

package/dist/http-policy.d.ts

@@ -0,0 +1,25 @@
+import type { AnyElysia, Elysia } from "elysia";
+import type { ApplicationHttpContext, CompiledRoute } from "./index";
+export interface HttpPolicyDeclaration {
+    name: string;
+    options?: unknown;
+}
+export interface HttpPolicyContext<Http extends AnyElysia = Elysia> {
+    http: ApplicationHttpContext<Http>;
+    requestContext: unknown;
+}
+export interface HttpPolicyResponseContext<Http extends AnyElysia = Elysia> extends HttpPolicyContext<Http> {
+    response: unknown;
+}
+export type HttpPolicy<Http extends AnyElysia = Elysia> = ((context: HttpPolicyContext<Http>) => void | Response | Promise<void | Response>) & {
+    /** Terminal policies (cache hits) must not skip later security checks. */
+    terminal?: boolean;
+    mapResponse?: (context: HttpPolicyResponseContext<Http>) => void | Response | Promise<void | Response>;
+    afterResponse?: (context: HttpPolicyResponseContext<Http>) => void | Promise<void>;
+};
+/** Factories validate configuration once at startup, never per request. */
+export type HttpPolicyRegistry<Http extends AnyElysia = Elysia> = Readonly<Record<string, (options: unknown, route: Readonly<Pick<CompiledRoute, "method" | "path" | "command">>) => HttpPolicy<Http>>>;
+export declare class HttpPolicyConfigurationError extends Error {
+    readonly code = "HTTP_POLICY_CONFIGURATION_INVALID";
+}
+export declare function compileHttpPolicies<Http extends AnyElysia>(route: CompiledRoute, path: string, registry?: HttpPolicyRegistry<Http>): HttpPolicy<Http>[];

package/dist/http-response-cache.d.ts

@@ -0,0 +1,14 @@
+import type { SupAuthRequestContext } from "./identity";
+import type { HttpPolicy } from "./http-policy";
+import type { HttpCacheStore } from "./http-policy-stores";
+interface CachePolicyOptions {
+    store: HttpCacheStore;
+    requireAccess(request: Request): SupAuthRequestContext;
+    ttlMs: number;
+    maxBodyBytes: number;
+    route: string;
+    namespace: string;
+    onWriteError(): void;
+}
+export declare function createCachePolicy(options: CachePolicyOptions): HttpPolicy;
+export {};

package/dist/http-telemetry.d.ts

@@ -0,0 +1,40 @@
+import { Elysia } from "elysia";
+export declare function httpRequestId(request: Request): string | undefined;
+export interface HttpTelemetryEvent {
+    requestId: string;
+    method: string;
+    /** Static route template only. Query strings and concrete paths are excluded. */
+    route: string;
+    status: number;
+    durationMs: number;
+}
+export type HttpTelemetryObserver = (event: Readonly<HttpTelemetryEvent>) => void | Promise<void>;
+/** Request tracing is best effort, not a durable business audit. */
+export declare function createHttpTelemetry(observe: HttpTelemetryObserver): Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;