@vivero/stoma 0.1.0-rc.10

package/CHANGELOG.md

@@ -0,0 +1,196 @@
+# @vivero/stoma
+
+## 0.1.0-rc.10
+### Patch Changes
+
+
+
+- [`c6f0576`](https://github.com/vivero-dev/stoma/commit/c6f05763d6f2ba3e8a3c6845258d57e6f8c1d693) Thanks [@JonathanBennett](https://github.com/JonathanBennett)! - fix: resolve `workspace:*` protocols in published packages
+  
+  Replaces `changeset publish` with a custom publish script (`scripts/publish.mjs`) that uses `yarn pack` to resolve `workspace:*` protocols and apply `publishConfig` overrides, then `npm publish <tarball>` for OIDC trusted publishing with provenance. The prepack/postpack workaround scripts have been removed.
+- Updated dependencies [[`c6f0576`](https://github.com/vivero-dev/stoma/commit/c6f05763d6f2ba3e8a3c6845258d57e6f8c1d693)]:
+  - @vivero/stoma-core@0.1.0-rc.3
+
+## 0.1.0-rc.9
+### Patch Changes
+
+
+
+- [`c6f0576`](https://github.com/vivero-dev/stoma/commit/c6f05763d6f2ba3e8a3c6845258d57e6f8c1d693) Thanks [@JonathanBennett](https://github.com/JonathanBennett)! - fix: publish via `yarn npm publish` to correctly resolve `workspace:*` protocols
+  
+  Replaces `changeset publish` (which used `npm publish <dir>` and never resolved workspace protocols) with a custom publish script that runs `yarn npm publish` from each package directory. Yarn natively handles `workspace:*` resolution and `publishConfig` field overrides, so the prepack/postpack workaround scripts have been removed.
+- Updated dependencies [[`c6f0576`](https://github.com/vivero-dev/stoma/commit/c6f05763d6f2ba3e8a3c6845258d57e6f8c1d693)]:
+  - @vivero/stoma-core@0.1.0-rc.2
+
+## 0.1.0-rc.8
+### Patch Changes
+
+
+
+- [`cfa0a04`](https://github.com/vivero-dev/stoma/commit/cfa0a040eda481782cc34131b2e4b99015e74cea) Thanks [@JonathanBennett](https://github.com/JonathanBennett)! - Add CLI test coverage and split monorepo/package READMEs
+  
+  ### CLI tests
+  
+  Add 26 tests across 3 files covering the playground wrapper, OAuth relay, gateway resolution security boundary, and TypeScript transpilation end-to-end:
+  
+  - **Playground routing invariants**: `/__playground` returns HTML, `/registry` returns exact JSON, non-playground paths always pass through to the gateway
+  - **Send proxy contract**: response shape (`status`, `statusText`, `headers`, `body`, `elapsed`), header forwarding, error handling, body stripping for GET
+  - **OAuth relay**: interception only fires for navigation requests to callback routes with query params; XSS prevention via `<` escaping
+  - **Security boundary**: remote URLs without `--trust-remote` always reject with security warning
+  - **TS transpilation e2e**: loads real `.ts` fixture through esbuild, verifies the gateway's fetch handler produces correct responses
+  
+  ### README
+  
+  - Root README is now a monorepo landing page with package table, quick start, and dev/release instructions
+  - Gateway package (`packages/gateway`) retains the full library README for npm
+
+## 0.1.0-rc.7
+### Patch Changes
+
+
+
+- [`a414008`](https://github.com/vivero-dev/stoma/commit/a41400882fbe51f9f5ac7f623dec52f0e2ca1dd6) Thanks [@JonathanBennett](https://github.com/JonathanBennett)! - Fix npm publish pipeline to correctly resolve workspace protocols and apply publishConfig overrides
+  
+  Adds prepack/postpack lifecycle scripts that prepare package.json for `npm publish` by resolving `workspace:*` to real versions and applying `publishConfig` field overrides (main, types, exports, bin). This replaces the previous `@changesets/cli` yarn patch approach and restores compatibility with GitHub Actions OIDC tokens for npm authentication and provenance.
+- Updated dependencies [[`a414008`](https://github.com/vivero-dev/stoma/commit/a41400882fbe51f9f5ac7f623dec52f0e2ca1dd6)]:
+  - @vivero/stoma-core@0.1.0-rc.1
+
+## 0.1.0-rc.6
+### Patch Changes
+
+
+
+- [`c14161a`](https://github.com/vivero-dev/stoma/commit/c14161a0846ef1991bb0fa71337435e6366579a7) Thanks [@JonathanBennett](https://github.com/JonathanBennett)! - Fix Content-Encoding/Content-Length mismatch on proxied upstream responses; enrich request logs with upstream target and client IP from socket
+  
+  ### Fixes
+  
+  - **Stale encoding headers on URL and Service Binding upstreams**: The runtime's `fetch()` transparently decompresses gzip/deflate/br responses, but the gateway was forwarding the original `Content-Encoding` and `Content-Length` headers unchanged. Downstream clients (browsers, proxies) would then attempt to decompress an already-decoded body, resulting in `ERR_CONTENT_DECODING_FAILED` or `ERR_CONTENT_LENGTH_MISMATCH` errors. Both `createUrlUpstream` and `createServiceBindingUpstream` now strip `content-encoding` and `content-length` from upstream responses before returning them.
+  - **`upstream` always "unknown" in request logs**: The `request-log` policy hardcoded `upstream: "unknown"` because no upstream handler was setting the value. All three upstream types (`createUrlUpstream`, `createServiceBindingUpstream`, `createHandlerUpstream`) now set `c.set("_upstreamTarget", identifier)` with the full resolved URL (including rewritten path and query string), `"service-binding:<name>"`, or `"handler"` respectively.
+  - **`clientIp` always "unknown" when running locally**: `extractClientIp()` only checked HTTP headers (`cf-connecting-ip`, `x-forwarded-for`), which aren't present when running with `@hono/node-server` locally. Added a `fallbackAddress` option to `extractClientIp()` and a `getRemoteAddress()` helper in `request-log` that duck-types `c.env.incoming.socket.remoteAddress` from the Node.js adapter.
+
+## 0.1.0-rc.5
+### Patch Changes
+
+
+
+- [`363341d`](https://github.com/vivero-dev/stoma/commit/363341dbc92a9f58a4b7df1ca0c66db2407cfe43) Thanks [@JonathanBennett](https://github.com/JonathanBennett)! - Accept trailing slashes on route paths
+  
+  ### Fixes
+  
+  - **Trailing-slash route aliases**: The gateway now registers both `/path` and `/path/` for every non-wildcard route, so requests with a trailing slash no longer 404. This also covers CORS preflight — if a `cors` policy is present, the OPTIONS handler is registered on both variants.
+  - **Scope path normalisation**: `scope()` and the internal `joinPaths` helper now strip trailing slashes from prefixes and handle root-path (`"/"`) children correctly, avoiding double-slash joins or unintended `/path/` suffixes.
+
+## 0.1.0-rc.5
+### Patch Changes
+
+
+
+- [`277d1a2`](https://github.com/vivero-dev/stoma/commit/277d1a2d27d98b444f074e4ecf0ae8095ef6f133) Thanks [@JonathanBennett](https://github.com/JonathanBennett)! - Fix policy middleware swallowing handler return values, breaking context finalization
+  
+  ### Fixes
+  
+  - **Policy pipeline context finalization**: `policiesToMiddleware` now propagates the return value from policy handlers back to Hono's compose chain. Previously, policies that short-circuit by returning a `Response` (rather than setting `c.res` or calling `next()`) would have their return value discarded, leaving `context.finalized` as `false` and causing Hono to throw "Context is not finalized". Both the fast path (no tracing) and slow path (OTel/policy trace active) are fixed.
+  - **Auto-inject OPTIONS for preflight**: When a route restricts its methods (e.g. `methods: ["GET"]`) and a policy that handles OPTIONS preflight is present, the gateway now automatically registers an OPTIONS handler for that path so preflight requests don't 404.
+
+## 0.1.0-rc.4
+### Patch Changes
+
+
+
+- [`c4f3901`](https://github.com/vivero-dev/stoma/commit/c4f39017bf8187e5e750d4bae1acb4fe016b78a8) Thanks [@JonathanBennett](https://github.com/JonathanBennett)! - ### Fixes
+  
+  - Refactored JWT auth validation: Extracted duplicated validation logic from `handler` and `evaluate.onRequest` into a shared `validateJwt()` function. Returns a discriminated `JWTValidationResult`, so each runtime path maps to its own error model.
+  
+  ### Docs
+  
+  - Docs have been updated with new about and sustainability pages.
+
+## 0.1.0-rc.3
+### Patch Changes
+
+
+
+- [`e7ecfb7`](https://github.com/vivero-dev/stoma/commit/e7ecfb763ef8b7a750984690436ce8bf7253f804) Thanks [@JonathanBennett](https://github.com/JonathanBennett)! - # Docs updates only:
+  
+  Add Open Graph meta tags and decouple docs deployment from package releases
+  
+  - Add `og:image` and related OG headers to Starlight config
+  - Decouple `deploy-docs` CI job from npm publish — docs now deploy on any successful release job
+
+
+- [`c1485eb`](https://github.com/vivero-dev/stoma/commit/c1485eb0e5933c1e45cb0ba05dff75d11569f46d) Thanks [@JonathanBennett](https://github.com/JonathanBennett)! - Tree-shakeable builds — 57% smaller bundles for consumers
+  
+  ### Build
+  
+  - **Unbundled dist output**: Switched tsup from bundled code-splitting (`splitting: true`) to per-file transpilation (`bundle: false`). The published `dist/` now mirrors the `src/` module structure, allowing consumer bundlers (esbuild, Rollup, webpack) to tree-shake at the module level instead of importing a monolithic chunk.
+  - **`sideEffects: false`**: Added to `package.json` so bundlers can safely drop unused modules.
+  - **`/*#__PURE__*/` annotations**: Added to all 33 `definePolicy()` call sites across policy files. These tell bundlers the factory calls can be dropped when their return values are unused.
+  
+  ### Impact
+  
+  A basic gateway with `requestLog` + `cors` drops from **89 KB / 28 KB gzip** to **38 KB / 15 KB gzip**. Consumers only pay for the policies they actually import.
+  
+  ### Docs
+  
+  - Fixed rate-limit error response in how-it-works guide: error code corrected from `rate_limit_exceeded` to `rate_limited`, `retryAfter` moved from JSON body to response header (matching actual implementation).
+  - Fixed IP extraction order: `cf-connecting-ip` checked first, then `x-forwarded-for`.
+
+## 0.1.0-rc.2
+### Patch Changes
+
+
+
+- [`75d0447`](https://github.com/vivero-dev/stoma/commit/75d04472e736fafe9528e258514a9fe3e352e511) Thanks [@JonathanBennett](https://github.com/JonathanBennett)! - Live demo API, interactive editor links across docs, release workflow fixes
+  
+  ### Features
+  
+  - **Demo API gateway** (`docs/src/demo-api/`): Real Stoma gateway deployed alongside the docs site at `/demo-api/*`, serving echo, users, products, status, and delay endpoints. Dogfoods Stoma with rate limiting (60 req/min) and CORS. Same-origin deployment eliminates CORS issues from the editor.
+  - **EditorLink on all guide and recipe pages**: Added "Open in Editor" buttons to 8 docs pages — webhook firewall, cache resilience, shadow release, caching (basic + advanced), JWT auth (HMAC + JWKS), route scopes, and the basic gateway partial. Real-world example page converted from inline code to imported example with EditorLink.
+  
+  ### Fixes
+  
+  - **EditorLink Unicode encoding**: Replaced `btoa()` with `Buffer.from().toString("base64")` to handle non-Latin1 characters in example code.
+  - **Release workflow: npm auth**: Added `NODE_AUTH_TOKEN` env var — `setup-node` with `registry-url` generates an `.npmrc` referencing `NODE_AUTH_TOKEN`, not `NPM_TOKEN`. Without this, `changeset publish` would fail with 401.
+  - **Release workflow: docs deploy build**: Added `yarn build` (tsup) step before docs build — the demo API worker imports `@vivero/stoma` which resolves to `dist/`, so stoma must be built first.
+  - **Release workflow: docs build command**: Changed from `yarn docs:build` (`astro build` only) to `cd docs && yarn build` (`build:assets && astro build`) so the stoma bundle, editor worker, and service worker are built before Astro runs.
+  - **Webhook firewall test**: Rewritten to test policy behavior (auth rejection for missing signature) instead of depending on upstream DNS resolution. Tests no longer make outbound network requests.
+  
+  ### Docs
+  
+  - All concept examples updated to use the live demo API (`https://stoma.vivero.dev/demo-api`) as upstream target, so editor demos produce real responses instead of 502 errors.
+  - Docs Cloudflare Worker updated with `main` entry point and `ASSETS` binding to serve both the demo API and static assets.
+
+## 0.1.0-rc.1
+### Patch Changes
+
+
+
+- [`155433e`](https://github.com/vivero-dev/stoma/commit/155433e7eb9f0050cc7b81fdc582e1d9045a583e) Thanks [@JonathanBennett](https://github.com/JonathanBennett)! - Protocol-agnostic policy evaluation, docs editor improvements, lint fixes
+  
+  - Multi-protocol policy architecture: `PolicyInput`, `PolicyResult`, `PolicyEvaluator` types enabling policies to run outside HTTP (ext_proc, WebSocket)
+  - `ipFilter` now exposes `evaluate.onRequest` alongside the existing Hono `handler`
+  - Docs editor: Hono types inlined into the stoma type bundle via `--external-inlines hono` (removes hand-written stubs)
+  - Docs editor: subpath registration for Monaco IntelliSense (`/sdk`, `/config`, `/adapters/*`)
+  - Fixed broken `EditorLink` component (`_href` → `href`)
+  - Lint error cleanup
+
+## 0.1.0-rc.0
+### Minor Changes
+
+
+
+- [`bb4d04f`](https://github.com/vivero-dev/stoma/commit/bb4d04ff85c8c133b10c323d92695cf11b944552) Thanks [@JonathanBennett](https://github.com/JonathanBennett)! - Initial release candidate for v0.1.0
+  
+  Declarative API gateway library built on Hono for Cloudflare Workers and edge runtimes. Features:
+  
+  - Gateway construction from declarative TypeScript config
+  - 43 policies across auth, traffic, resilience, transform, and observability domains
+  - 4-layer policy SDK with `definePolicy()`, priority constants, composable helpers, and test harness
+  - Three upstream types: URL proxy, Cloudflare Service Binding, and custom handler
+  - Runtime adapters for Cloudflare Workers, Node.js, Deno, and Bun
+  - Cloudflare-specific stores (KV, Durable Objects, Cache API)
+  - Admin introspection API with Prometheus metrics export
+  - W3C trace context propagation
+  - Zod-based config validation (optional peer dependency)
+  - Zero-dependency debug system with namespace filtering
+  - SSRF protection on URL upstreams

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Bennett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,325 @@
+# Stoma 🌱
+
+**Declarative API gateway as a TypeScript library. Runs on Cloudflare Workers, Node.js, Deno, Bun, and more.**
+
+![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)
+![Hono](https://img.shields.io/badge/Hono-4.7-orange)
+![License](https://img.shields.io/badge/License-MIT-green)
+
+---
+
+## Why
+
+API gateways in the JavaScript ecosystem are stuck between two bad options:
+
+1. **Infrastructure you deploy** -- Kong, KrakenD, AWS API Gateway. Powerful, but they are separate services you provision, configure with YAML, and operate independently from your application code. You lose type safety, your gateway config drifts from your codebase, and you pay for another piece of infrastructure.
+
+2. **Dead or abandoned libraries** -- Express Gateway was the closest thing to a TS-native gateway. It is unmaintained, locked to Express 4, and has no story for modern runtimes.
+
+There is a third option: **a declarative gateway library that lives in your codebase and deploys with your standard workflow.**
+
+`@vivero/stoma` fills this gap. It is a TypeScript library you import -- not a Go binary or YAML config you deploy. Define your routes, policies, and upstreams as typed objects. The library compiles them into an HTTP application you can export directly.
+
+- Configured with **TypeScript**, not YAML
+- Lives in **your codebase** -- deploy as part of your app or as a standalone service
+- Runs on Cloudflare Workers, Node.js, Deno, Bun, Fastly, Lambda@Edge, Vercel Edge Functions
+- Optionally leverages **platform-specific features** (Cloudflare Service Bindings, KV, Durable Objects) through a pluggable adapter system
+
+Think KrakenD's declarative route-to-pipeline model, but as a TypeScript library.
+
+## Features
+
+- **TypeScript-first with full type safety** -- Every config object, policy, and upstream is typed. No YAML. No JSON Schema. Your editor catches mistakes before your users do.
+- **Powered by Hono** -- lightweight, zero dependencies, Web Standards API. One of the fastest routers in the JavaScript ecosystem.
+- **Declarative route / pipeline / policy chain model** -- Define routes, attach ordered policy chains, and point at an upstream. The gateway wires it all together.
+- **Dozens of built-in policies** -- Auth (JWT, API key, OAuth2, RBAC, HTTP signatures), traffic control (rate limiting, IP filtering, caching, threat protection), resilience (circuit breaker, retry, timeout), transforms (CORS, request/response rewriting, validation), and observability (structured logging, metrics, health checks).
+- **Multi-runtime** -- Core depends only on Hono and the Web `Request`/`Response` API. No Node.js built-ins, no platform lock-in.
+- **Pluggable adapter system** -- Runtime-specific capabilities (distributed stores, background tasks, service bindings) are injected through adapters, not hard-coded. Adapters ship for Cloudflare Workers, Node.js, Deno, Bun, and in-memory development.
+- **Pluggable policy system** -- Policies are middleware functions with metadata. Write a custom policy in a few lines, or use `definePolicy()` from the SDK for a structured approach.
+
+## Installation
+
+```sh
+npm install @vivero/stoma hono
+```
+
+## Quick Start
+
+### Basic gateway (runs on any runtime)
+
+```typescript
+import { createGateway, jwtAuth, rateLimit, requestLog, cors } from "@vivero/stoma";
+
+const gateway = createGateway({
+  name: "my-api-gateway",
+  basePath: "/api",
+  policies: [requestLog(), cors()],
+  routes: [
+    {
+      path: "/users/*",
+      methods: ["GET", "POST", "PUT", "DELETE"],
+      pipeline: {
+        policies: [
+          jwtAuth({ secret: "your-secret" }),
+          rateLimit({ max: 100, windowSeconds: 60 }),
+        ],
+        upstream: {
+          type: "url",
+          target: "https://users-api.internal.example.com",
+          rewritePath: (path) => path.replace("/api/users", ""),
+        },
+      },
+    },
+    {
+      path: "/health",
+      pipeline: {
+        upstream: {
+          type: "handler",
+          handler: () =>
+            new Response(JSON.stringify({ status: "ok" }), {
+              headers: { "Content-Type": "application/json" },
+            }),
+        },
+      },
+    },
+  ],
+});
+
+export default gateway.app;
+```
+
+This gateway works out of the box on Cloudflare Workers (`export default gateway.app`), Bun (`export default gateway.app`), Deno (`Deno.serve(gateway.app.fetch)`), or Node.js (via `@hono/node-server`).
+
+### With Cloudflare-specific features
+
+When deploying to Cloudflare Workers, use the Cloudflare adapter to unlock Service Bindings, KV-backed rate limiting, and Durable Objects:
+
+```typescript
+import { createGateway, jwtAuth, rateLimit, requestLog } from "@vivero/stoma";
+import { cloudflareAdapter } from "@vivero/stoma/adapters/cloudflare";
+
+type Env = {
+  JWT_SECRET: string;
+  USERS_SERVICE: Fetcher;
+  RATE_LIMIT_KV: KVNamespace;
+};
+
+export default {
+  fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    const gateway = createGateway({
+      name: "my-api-gateway",
+      basePath: "/api",
+      adapter: cloudflareAdapter({
+        rateLimitKv: env.RATE_LIMIT_KV,
+        executionCtx: ctx,
+        env,
+      }),
+      policies: [requestLog()],
+      routes: [
+        {
+          path: "/users/*",
+          pipeline: {
+            policies: [
+              jwtAuth({ secret: env.JWT_SECRET }),
+              rateLimit({ max: 100, windowSeconds: 60 }),
+            ],
+            upstream: {
+              type: "service-binding",
+              service: "USERS_SERVICE",
+            },
+          },
+        },
+      ],
+    });
+
+    return gateway.app.fetch(request, env, ctx);
+  },
+};
+```
+
+## Configuration
+
+The gateway is configured entirely through TypeScript. The top-level `GatewayConfig` type drives everything:
+
+```typescript
+interface GatewayConfig {
+  name?: string;            // Gateway name, used in logs and metrics
+  basePath?: string;        // Base path prefix for all routes (e.g. "/api")
+  routes: RouteConfig[];    // Route definitions
+  policies?: Policy[];      // Global policies applied to every route
+  adapter?: GatewayAdapter; // Runtime adapter for stores and platform capabilities
+  onError?: (error: Error, c: unknown) => Response | Promise<Response>;
+}
+```
+
+Each route defines a **path**, optional **methods**, and a **pipeline**:
+
+```typescript
+interface RouteConfig {
+  path: string;                   // Hono path syntax: "/users/:id", "/files/*"
+  methods?: HttpMethod[];         // ["GET", "POST", ...] -- defaults to all
+  pipeline: PipelineConfig;       // Policy chain + upstream target
+  metadata?: Record<string, unknown>;
+}
+```
+
+A pipeline is an ordered chain of policies leading to an upstream:
+
+```typescript
+interface PipelineConfig {
+  policies?: Policy[];     // Executed in order before the upstream
+  upstream: UpstreamConfig; // Where the request goes
+}
+```
+
+### Upstream Types
+
+Three upstream types cover the common deployment patterns:
+
+```typescript
+// URL proxy -- forward to any HTTP endpoint (works on all runtimes)
+{ type: "url", target: "https://api.example.com", headers: { "X-Forwarded-By": "gateway" } }
+
+// Service Binding -- zero-latency Worker-to-Worker routing (Cloudflare only)
+{ type: "service-binding", service: "AUTH_SERVICE" }
+
+// Inline handler -- respond directly without proxying (works on all runtimes)
+{ type: "handler", handler: (c) => new Response("ok") }
+```
+
+### Adapters
+
+Adapters provide runtime-specific store implementations and platform capabilities. The gateway core is runtime-agnostic; adapters plug in distributed rate limiting, caching, background tasks, and service binding dispatch.
+
+```typescript
+import { cloudflareAdapter } from "@vivero/stoma/adapters/cloudflare";
+import { nodeAdapter } from "@vivero/stoma/adapters/node";
+import { denoAdapter } from "@vivero/stoma/adapters/deno";
+import { bunAdapter } from "@vivero/stoma/adapters/bun";
+import { memoryAdapter } from "@vivero/stoma/adapters/memory";
+```
+
+| Adapter | Stores | `waitUntil` | Service Bindings | Use case |
+|---------|--------|-------------|------------------|----------|
+| `cloudflareAdapter` | KV, Durable Objects, Cache API | Yes | Yes | Production on Cloudflare Workers |
+| `nodeAdapter` | In-memory defaults | No | No | Node.js servers via `@hono/node-server` |
+| `denoAdapter` | In-memory defaults | No | No | Deno / Deno Deploy |
+| `bunAdapter` | In-memory defaults | No | No | Bun servers |
+| `memoryAdapter` | In-memory (all stores) | No | No | Development, testing, single-instance |
+
+No adapter is required. Without one, policies that need stores (rate limiting, caching, circuit breaking) fall back to in-memory defaults automatically.
+
+## Policies
+
+Policies are the building blocks of gateway pipelines. They are middleware handlers with a name and a priority (lower numbers execute first).
+
+### Built-in Policies
+
+| Category | Policies |
+|----------|----------|
+| **Auth** | `jwtAuth`, `apiKeyAuth`, `basicAuth`, `oauth2`, `rbac`, `generateJwt`, `jws`, `generateHttpSignature`, `verifyHttpSignature` |
+| **Traffic** | `rateLimit`, `ipFilter`, `geoIpFilter`, `cache`, `sslEnforce`, `requestLimit`, `jsonThreatProtection`, `regexThreatProtection`, `trafficShadow`, `interrupt`, `dynamicRouting`, `httpCallout`, `resourceFilter` |
+| **Resilience** | `timeout`, `retry`, `circuitBreaker`, `latencyInjection` |
+| **Transform** | `cors`, `overrideMethod`, `assignAttributes`, `assignContent`, `requestTransform`, `responseTransform`, `requestValidation`, `jsonValidation` |
+| **Observability** | `requestLog`, `metricsReporter`, `assignMetrics`, `health` |
+| **Utility** | `proxy`, `mock` |
+
+Every policy accepts a `skip` function for conditional execution:
+
+```typescript
+rateLimit({
+  max: 100,
+  skip: (c) => c.req.header("X-Internal") === "true",
+})
+```
+
+### Writing a Custom Policy
+
+A policy is any object conforming to the `Policy` interface:
+
+```typescript
+import type { Policy } from "@vivero/stoma";
+
+function requestTimer(): Policy {
+  return {
+    name: "request-timer",
+    priority: 5,
+    handler: async (c, next) => {
+      const start = performance.now();
+      await next();
+      c.header("X-Response-Time", `${(performance.now() - start).toFixed(1)}ms`);
+    },
+  };
+}
+```
+
+For a more structured approach, use the SDK:
+
+```typescript
+import { definePolicy, Priority } from "@vivero/stoma";
+
+const requestTimer = definePolicy({
+  name: "request-timer",
+  priority: Priority.EARLY_TRANSFORM,
+  handler: async ({ c, next }) => {
+    const start = performance.now();
+    await next();
+    c.header("X-Response-Time", `${(performance.now() - start).toFixed(1)}ms`);
+  },
+});
+```
+
+### Policy Execution Order
+
+Policies execute in **priority order** (lowest number first), then in **declaration order** for policies sharing a priority. Global policies and route-level policies are merged and sorted together.
+
+| Priority | Phase | Examples |
+|----------|-------|---------|
+| 0 | Observability | `requestLog`, `assignMetrics` |
+| 1 | Network filter | `ipFilter`, `geoIpFilter`, `metricsReporter` |
+| 5 | Early transform | `cors`, `sslEnforce`, `requestLimit`, `latencyInjection` |
+| 10 | Authentication | `jwtAuth`, `apiKeyAuth`, `basicAuth`, `oauth2`, `rbac` |
+| 20 | Rate limiting | `rateLimit` |
+| 30 | Circuit breaker | `circuitBreaker` |
+| 40 | Caching | `cache` |
+| 50 | Mid-pipeline | `requestTransform`, `assignAttributes`, `generateJwt`, `dynamicRouting` |
+| 85 | Timeout | `timeout` |
+| 90 | Retry | `retry` |
+| 92 | Response | `responseTransform`, `trafficShadow`, `resourceFilter` |
+| 95 | Proxy | `proxy`, `generateHttpSignature` |
+| 100 | Default | Custom policies |
+| 999 | Terminal | `mock` |
+
+## Documentation & Resources
+
+- [Architecture Design](ARCHITECTURE.md) - Deep dive into the gateway's internal design and decisions.
+- [Full Documentation](https://stoma.vivero.dev) - Comprehensive guides, recipes, and API reference.
+
+## Package Exports
+
+| Import path | Contents |
+|-------------|----------|
+| `@vivero/stoma` | `createGateway`, all policies, metrics, core types |
+| `@vivero/stoma/policies` | Policies only |
+| `@vivero/stoma/sdk` | `definePolicy`, `Priority`, test harness |
+| `@vivero/stoma/config` | Config types + optional Zod validation (requires `zod` peer dep) |
+| `@vivero/stoma/adapters` | All adapter factories |
+| `@vivero/stoma/adapters/cloudflare` | Cloudflare adapter only |
+| `@vivero/stoma/adapters/node` | Node.js adapter only |
+| `@vivero/stoma/adapters/deno` | Deno adapter only |
+| `@vivero/stoma/adapters/bun` | Bun adapter only |
+| `@vivero/stoma/adapters/memory` | In-memory adapter (dev/test) |
+
+## Contributing
+
+Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request.
+
+```sh
+yarn install
+yarn test
+yarn typecheck
+```
+
+## License
+
+MIT

package/dist/adapters/bun.d.ts

@@ -0,0 +1,9 @@
+import { G as GatewayAdapter } from '../protocol-2fD3DJrL.js';
+import 'hono';
+import '../policies/sdk/trace.js';
+import '@vivero/stoma-core';
+
+/** Create a GatewayAdapter for Bun. Delegates to memoryAdapter() for in-memory stores. */
+declare function bunAdapter(): GatewayAdapter;
+
+export { bunAdapter };

package/dist/adapters/bun.js

@@ -0,0 +1,8 @@
+import { memoryAdapter } from "./memory";
+function bunAdapter() {
+  return memoryAdapter();
+}
+export {
+  bunAdapter
+};
+//# sourceMappingURL=bun.js.map

package/dist/adapters/bun.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/bun.ts"],"sourcesContent":["/**\n * Bun adapter for stoma.\n *\n * Bun doesn't provide `waitUntil` or service bindings natively.\n * Use `memoryAdapter()` for stores and this adapter as a marker/extension\n * point for Bun-specific capabilities.\n *\n * @example\n * ```ts\n * import { createGateway } from \"@vivero/stoma\";\n * import { bunAdapter } from \"@vivero/stoma/adapters/bun\";\n *\n * const gateway = createGateway({\n *   adapter: bunAdapter(),\n *   routes: [...]\n * });\n *\n * export default gateway.app;\n * ```\n *\n * @module bun-adapter\n */\nimport { memoryAdapter } from \"./memory\";\nimport type { GatewayAdapter } from \"./types\";\n\n/** Create a GatewayAdapter for Bun. Delegates to memoryAdapter() for in-memory stores. */\nexport function bunAdapter(): GatewayAdapter {\n  return memoryAdapter();\n}\n"],"mappings":"AAsBA,SAAS,qBAAqB;AAIvB,SAAS,aAA6B;AAC3C,SAAO,cAAc;AACvB;","names":[]}

package/dist/adapters/cloudflare.d.ts

@@ -0,0 +1,49 @@
+import { C as CacheStore, R as RateLimitStore, G as GatewayAdapter } from '../protocol-2fD3DJrL.js';
+import 'hono';
+import '../policies/sdk/trace.js';
+import '@vivero/stoma-core';
+
+/** Rate limit store backed by Cloudflare Workers KV. */
+declare class KVRateLimitStore implements RateLimitStore {
+    private kv;
+    constructor(kv: KVNamespace);
+    increment(key: string, windowSeconds: number): Promise<{
+        count: number;
+        resetAt: number;
+    }>;
+}
+/** Response cache backed by the Cloudflare Cache API. */
+declare class CacheApiCacheStore implements CacheStore {
+    private cache;
+    private origin;
+    /**
+     * @param cache - A `Cache` instance (e.g. `caches.default`). Falls back to `caches.default` when omitted.
+     * @param origin - Synthetic origin used to construct cache keys. Default: `"https://edge-gateway.internal"`.
+     */
+    constructor(cache?: Cache, origin?: string);
+    get(key: string): Promise<Response | null>;
+    put(key: string, response: Response, ttlSeconds: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+}
+interface CloudflareAdapterBindings {
+    rateLimitKv?: KVNamespace;
+    rateLimitDo?: DurableObjectNamespace;
+    cache?: Cache;
+    /** Synthetic origin used for Cache API cache keys. Default: `"https://edge-gateway.internal"`. */
+    cacheOrigin?: string;
+    /** Workers `ExecutionContext` - enables `waitUntil` for background work (e.g. traffic shadow). */
+    executionCtx?: ExecutionContext;
+    /** Workers `env` object - enables `dispatchBinding` for service binding dispatch via the adapter. */
+    env?: Record<string, unknown>;
+}
+/**
+ * Create a GatewayAdapter using Cloudflare-native stores.
+ *
+ * Rate limiting priority: Durable Objects (strongly consistent) > KV (eventually consistent) > none.
+ *
+ * Pass `executionCtx` to enable `waitUntil` (for traffic shadow and other background work).
+ * Pass `env` to enable `dispatchBinding` (for service binding dispatch via the adapter).
+ */
+declare function cloudflareAdapter(bindings: CloudflareAdapterBindings): GatewayAdapter;
+
+export { CacheApiCacheStore, type CloudflareAdapterBindings, KVRateLimitStore, cloudflareAdapter };