@suluk/hono 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,35 @@
+<p align="center">
+  <a href="https://github.com/MahmoodKhalil57/suluk">
+    <img src="https://raw.githubusercontent.com/MahmoodKhalil57/suluk/main/branding/export/wordmark.png" alt="Suluk" width="360" />
+  </a>
+</p>
+
+<h1 align="center">@suluk/hono</h1>
+
+<p align="center"><b>The Suluk derivation engine: minimal Hono+Zod RouteContracts in; v4 doc (dynamic per principal+time), validation, contract tests, and doc-coverage audit out.</b></p>
+
+<p align="center">
+  <em>Part of <a href="https://github.com/MahmoodKhalil57/suluk">Suluk</a> — one typed OpenAPI v4 contract projecting into every full-stack layer.</em>
+</p>
+
+---
+
+> **CANDIDATE tooling — not official OpenAPI.** Suluk is a single-contributor candidate for
+> OpenAPI Specification v4.0 ("Moonwalk"), unaffiliated with the OpenAPI Initiative and unable
+> to ratify anything on the SIG's behalf.
+
+## Install
+
+```sh
+bun add @suluk/hono
+```
+
+## The Suluk cycle
+
+`@suluk/hono` is one station on the Suluk walk — author one v4 source, then **validate · audit ·
+preview · generate · deploy** the whole stack from it. Explore the full toolchain in the
+[main repository](https://github.com/MahmoodKhalil57/suluk) or drive it from the [VS Code cockpit](https://marketplace.visualstudio.com/items?itemName=MahmoodKhalil.suluk-vscode).
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,15 +1,26 @@
 {
   "name": "@suluk/hono",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "The Suluk derivation engine: minimal Hono+Zod RouteContracts in; v4 doc (dynamic per principal+time), validation, contract tests, and doc-coverage audit out. CANDIDATE tooling.",
-  "type": "module",
-  "main": "src/index.ts",
-  "exports": {
-  ".": "./src/index.ts"
+  "publishConfig": {
+  "access": "public"
+},
+"license": "Apache-2.0",
+"repository": {
+  "type": "git",
+  "url": "git+https://github.com/MahmoodKhalil57/suluk.git",
+  "directory": "tooling/ts/packages/hono"
+},
+"homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
+"bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
+"type": "module",
+"main": "src/index.ts",
+"exports": {
+".": "./src/index.ts"
 },
 "dependencies": {
-  "@suluk/core": "0.1.0",
-  "@suluk/zod": "0.1.0",
+  "@suluk/core": "^0.1.11",
+  "@suluk/zod": "^0.1.2",
   "ajv": "^8.20.0",
   "ajv-formats": "^3.0.1"
 },
@@ -20,7 +31,7 @@
 },
 "devDependencies": {
   "@types/bun": "latest",
-  "@suluk/openapi-compat": "0.1.0",
+  "@suluk/openapi-compat": "^0.1.2",
   "zod": "^4.4.3",
   "hono": "^4.0.0",
   "@hono/zod-validator": "^0.8.0"

package/src/access.ts

@@ -0,0 +1,67 @@
+/**
+ * The ROW-LEVEL authorization engine that pairs with {@link enforceAccess} (the wire-level facet enforcer). A
+ * generic CRUD app declares each entity's access MODE; this maps mode → per-operation Rule → a decision: may the
+ * caller run it, and is the query SCOPED to their own rows. Pure (no Hono Context — takes the resolved
+ * `{ isAdmin, principal }`), so it is testable and reusable. `ruleToRequires` projects a Rule to the wire
+ * `requires` level so ONE declaration drives BOTH the CRUD gate AND the `x-suluk-access` facet/docs.
+ */
+import type { AccessRequires } from "./enforce";
+
+/** A CRUD operation's authorization rule. */
+export type Rule = "any" | "owner" | "admin" | "none";
+/** The five CRUD operations' rules for one access mode. */
+export interface Policy { list: Rule; get: Rule; create: Rule; update: Rule; delete: Rule }
+/** The built-in access modes (a sensible SaaS/commerce default set; override via `policyFor`'s `policies` arg). */
+export type AccessMode = "public" | "admin" | "submit" | "owned" | "ownedAppend" | "ownedReadonly" | "review";
+
+/** The opt-in default mode→policy preset. Adopt by reference, or pass your own matrix to {@link policyFor}. */
+export const DEFAULT_POLICIES: Record<AccessMode, Policy> = {
+  // catalog + content: world-readable, admin-writable
+  public: { list: "any", get: "any", create: "admin", update: "admin", delete: "admin" },
+  // sensitive (e.g. discount codes): admin-only — even reads (listing all is a leak)
+  admin: { list: "admin", get: "admin", create: "admin", update: "admin", delete: "admin" },
+  // public submissions (contact, newsletter): anyone may create; only admins read/modify
+  submit: { list: "admin", get: "admin", create: "any", update: "admin", delete: "admin" },
+  // user-owned: each caller only sees/mutates their own rows (admin sees all)
+  owned: { list: "owner", get: "owner", create: "owner", update: "owner", delete: "owner" },
+  // owned + append-only to the user — place + read your own, but only the system/admin mutates (no self-mark-paid)
+  ownedAppend: { list: "owner", get: "owner", create: "owner", update: "admin", delete: "admin" },
+  // owned but READ-ONLY to the user — the system/admin even creates it (e.g. billing rows)
+  ownedReadonly: { list: "owner", get: "owner", create: "admin", update: "admin", delete: "admin" },
+  // public-read, owner-write (e.g. product reviews): everyone reads; you only edit your own
+  review: { list: "any", get: "any", create: "owner", update: "owner", delete: "owner" },
+};
+
+/** The policy for an access mode (default: owned when an ownerCol is present, else public). `policies` overrides the preset. */
+export function policyFor(access: AccessMode | undefined, ownerCol?: string, policies: Record<AccessMode, Policy> = DEFAULT_POLICIES): Policy {
+  return policies[access ?? (ownerCol ? "owned" : "public")];
+}
+
+/** The resolved caller identity a gate decision needs (compute from your Hono Context: isAdmin flag + principal id). */
+export interface GateIdentity { isAdmin: boolean; principal: string | null }
+/** A gate decision: may the op run, scope the query to the owner, and — when denied — the honest status. */
+export interface GateDecision { ok: boolean; scopeOwner: boolean; status?: 401 | 403 }
+
+/**
+ * Decide whether a caller may run an op (per the rule), whether to scope the query to their own rows, and the honest
+ * deny status. FAIL-CLOSED: an `owner` op with no principal is 401 (the wire must enforce what `x-suluk-access`
+ * claims — a null-scoped empty 200 would let the facet lie); `admin` with no principal is 401, signed-in-non-admin is
+ * 403; `none` hard-denies 403. A signed-in owner is scoped to their rows; an admin sees all.
+ */
+export function gate(rule: Rule, id: GateIdentity): GateDecision {
+  switch (rule) {
+    case "any": return { ok: true, scopeOwner: false };
+    case "owner":
+      if (id.isAdmin) return { ok: true, scopeOwner: false };                   // admin sees all
+      if (!id.principal) return { ok: false, scopeOwner: false, status: 401 };  // owner op needs a verified caller
+      return { ok: true, scopeOwner: true };                                    // signed-in: scoped to own rows
+    case "admin":
+      if (!id.principal) return { ok: false, scopeOwner: false, status: 401 };  // authenticate first (RFC 7235)
+      return { ok: id.isAdmin, scopeOwner: false, status: 403 };                // signed-in but not admin → forbidden
+    default: return { ok: false, scopeOwner: false, status: 403 };
+  }
+}
+
+/** Project a CRUD Rule to the wire-level `requires` (so one rule drives BOTH the gate AND the x-suluk-access facet). */
+const RULE_TO_REQUIRES: Record<Rule, AccessRequires> = { any: "anyone", owner: "authenticated", admin: "admin", none: "admin" };
+export function ruleToRequires(rule: Rule): AccessRequires { return RULE_TO_REQUIRES[rule]; }

package/src/contract.ts

@@ -4,7 +4,7 @@
  * the pure derivations (emitV4 / audit / contractChecks) need no running server — only mount() touches Hono.
  */
 import type * as z from "zod";
-import type { SecurityRequirement } from "@suluk/core";
+import type { SecurityRequirement, SulukRateLimit } from "@suluk/core";
 
 export type Method = "get" | "post" | "put" | "patch" | "delete" | "head" | "options";
 
@@ -51,6 +51,16 @@ export interface RouteContract {
   security?: SecurityRequirement[];
   /** Required scopes. Drives BOTH the per-principal filter (the "who") and synthesized security. */
   scopes?: string[];
+  /**
+   * Error statuses this operation can return. Synthesized into RFC-9457 error responses by emitV4 (alongside
+   * the auto-derived 401/403 for auth-gated ops, 429 when rate-limited, and an always-present 500).
+   */
+  errors?: number[];
+  /**
+   * The declared rate budget (the `x-suluk-ratelimit` facet). emitV4 stamps it onto the operation + synthesizes a
+   * 429 response; @suluk/hono's enforceRateLimit middleware ENFORCES it on the wire. Advisory vendor extension.
+   */
+  rateLimit?: SulukRateLimit;
   request?: RouteRequest;
   /** Responses, as a list (each carries its own status) or a status-keyed map. */
   responses?: RouteResponse[] | Record<string, RouteResponse>;

package/src/emit.ts

@@ -4,9 +4,10 @@
  * NOT a static file: the document is a pure function of the contracts × the requesting principal (scopes,
  * the "who") × time (now, the "when"). A public export is just emitV4(routes) with no principal/now.
  */
-import { buildAda } from "@suluk/core";
+import { buildAda, PROBLEM_CONTENT_TYPE, PROBLEM_DETAILS_SCHEMA } from "@suluk/core";
 import type {
   OpenAPIv4Document, PathItem, Request, Response, ParameterSchema, SecurityRequirement, Server, Info, SecurityScheme,
+  Components, Schema,
 } from "@suluk/core";
 import { zodToV4 } from "@suluk/zod";
 import { responseList, type RouteContract, type Method } from "./contract";
@@ -24,6 +25,31 @@ export interface EmitContext {
   securitySchemes?: Record<string, SecurityScheme>;
   /** Include operations flagged deprecated (default true; they are marked, not hidden). */
   includeDeprecated?: boolean;
+  /**
+   * Synthesize RFC-9457 error responses (401/403 from access, 429 from a rate-limit facet, always-500, plus any
+   * `route.errors`) + a shared `components.schemas.ProblemDetails`. Default true — the SDK's `isApiError` guard and
+   * testgen's error-conformance need declared non-2xx responses to check. Set false for a success-only projection.
+   */
+  synthesizeErrors?: boolean;
+}
+
+/** A human title per synthesized error status (RFC-9457 `description`). */
+const ERROR_DESCRIPTION: Readonly<Record<number, string>> = {
+  400: "Bad request", 401: "Unauthorized", 402: "Payment required", 403: "Forbidden",
+  404: "Not found", 409: "Conflict", 429: "Too many requests", 500: "Internal server error", 502: "Bad gateway",
+};
+
+/**
+ * Which error statuses an operation declares it can return: explicit `route.errors`, + 401/403 when the op is
+ * auth-gated (it can deny), + 429 when it declares a rate-limit budget, + always-500 (any handler can fail).
+ */
+function errorStatusesFor(route: RouteContract, ctx: EmitContext): number[] {
+  if (ctx.synthesizeErrors === false) return [];
+  const set = new Set<number>(route.errors ?? []);
+  if ((route.scopes && route.scopes.length > 0) || route.security) { set.add(401); set.add(403); }
+  if (route.rateLimit) set.add(429);
+  set.add(500);
+  return [...set].sort((a, b) => a - b);
 }
 
 export interface EmitDiagnostic {
@@ -97,8 +123,22 @@ function buildRequest(route: RouteContract, deprecated: boolean, ctx: EmitContex
     responses[String(r.status)] = resp;
   }
   if (Object.keys(responses).length === 0) responses["200"] = { status: 200 };
+  // synthesize RFC-9457 error responses — but never clobber a user-declared one for the same status.
+  for (const status of errorStatusesFor(route, ctx)) {
+    const key = String(status);
+    if (responses[key]) continue;
+    responses[key] = {
+      status,
+      description: ERROR_DESCRIPTION[status] ?? "Error",
+      contentType: PROBLEM_CONTENT_TYPE,
+      contentSchema: { $ref: "#/components/schemas/ProblemDetails" },
+    };
+  }
   req.responses = responses;
 
+  // stamp the declared rate-limit facet so rateLimitIndex/coverage + the middleware can read it off the document.
+  if (route.rateLimit) req["x-suluk-ratelimit"] = route.rateLimit;
+
   // security: explicit wins; else synthesize from scopes if a scheme name is configured.
   const security: SecurityRequirement[] | undefined =
     route.security ?? (route.scopes && ctx.securityScheme ? [{ [ctx.securityScheme]: route.scopes }] : undefined);
@@ -153,7 +193,15 @@ export function emitV4(routes: readonly RouteContract[], ctx: EmitContext = {}):
     paths,
   };
   if (ctx.servers) document.servers = ctx.servers;
-  if (ctx.securitySchemes) document.components = { securitySchemes: ctx.securitySchemes };
+
+  // components: securitySchemes (C014) + the shared ProblemDetails schema iff any op synthesized a problem+json response.
+  const usesProblem = Object.values(paths).some((pi) =>
+    Object.values(pi.requests).some((r) =>
+      Object.values(r.responses).some((resp) => resp.contentType === PROBLEM_CONTENT_TYPE)));
+  const components: Components = {};
+  if (ctx.securitySchemes) components.securitySchemes = ctx.securitySchemes;
+  if (usesProblem) components.schemas = { ProblemDetails: PROBLEM_DETAILS_SCHEMA as unknown as Schema };
+  if (Object.keys(components).length > 0) document.components = components;
 
   // static collision audit over the ADA (detect-and-tolerate; surfaced as diagnostics, never a gate).
   for (const c of buildAda(document).collisions) {

package/src/enforce.ts

@@ -0,0 +1,112 @@
+/**
+ * ENFORCEMENT — the reusable server-side authz primitive (saastarter-parity roadmap, Phase 0).
+ *
+ * Suluk's facets are ADVISORY; the server is the only authz boundary (C022 inv.3). For CRUD routes the
+ * derivation engine can scope rows, but CUSTOM operations are raw handlers — so without a shared primitive an
+ * `x-suluk-access` facet on a custom op is DECORATIVE: nothing makes the wire honor it. This module is that
+ * primitive, in two shapes:
+ *
+ *   • `enforceAccess(cfg)` — ONE facet-driven middleware: for each request it resolves the operation, reads its
+ *     declared `x-suluk-access`, and enforces it on the wire (anon → 401 on a non-public op; wrong scope → 403).
+ *     Applied once, it makes EVERY operation's access facet load-bearing — the contract-first way to close the
+ *     "facet is decorative on custom ops" gap. Row-level `scope: "owner"` stays the app's concern (the CRUD
+ *     factory filters rows); this enforces the requires-LEVEL (anyone < authenticated < admin) + named scopes.
+ *   • `createGuard(cfg)` — explicit per-route middlewares (`requireAuth` / `requireAdmin` / `requireScopes(...)`)
+ *     for apps that want to gate specific routes by hand, or that have no ADA to match against.
+ *
+ * Identity is INJECTED (the app knows its own principal/scope model — Better Auth session, API token, etc.), so
+ * the primitive is generic over any Suluk app. It never trusts a header it didn't verify; the app's `principal`
+ * / `isAdmin` callbacks are responsible for verification.
+ */
+import { PROBLEM_CONTENT_TYPE, toProblemDetails } from "@suluk/core";
+import type { Context, MiddlewareHandler } from "hono";
+
+export type AccessRequires = "anyone" | "authenticated" | "admin";
+export interface AccessFacet { requires?: AccessRequires | string; scope?: string }
+
+/** Read identity from a request — the app supplies these (it owns its principal/scope model). */
+export interface IdentityConfig {
+  /** the caller's verified principal id, or null/undefined for anonymous. */
+  principal: (c: Context) => string | null | undefined;
+  /** fast-path admin check (verified). If omitted, the literal "admin" scope is used. */
+  isAdmin?: (c: Context) => boolean;
+  /** the caller's granted scopes (e.g. ["admin"], ["org:1:read"]). Default: none. */
+  scopes?: (c: Context) => string[] | undefined;
+}
+
+/** A deny response — the shared RFC-9457 Problem Details envelope (@suluk/core), so deny + the error model agree. */
+function deny(c: Context, status: 401 | 403, scope?: string): Response {
+  const body = status === 401
+    ? toProblemDetails({ tag: "UnauthorizedError", detail: "authentication required" })
+    : toProblemDetails({ tag: "ForbiddenError", detail: scope ? `requires scope: ${scope}` : "insufficient permissions" });
+  return c.json(body, status, { "content-type": PROBLEM_CONTENT_TYPE });
+}
+
+function hasScope(cfg: IdentityConfig, c: Context, scope: string): boolean {
+  if (scope === "admin" && cfg.isAdmin) return cfg.isAdmin(c);
+  return (cfg.scopes?.(c) ?? []).includes(scope);
+}
+
+export interface EnforceAccessConfig extends IdentityConfig {
+  /** the operation name for this request, or undefined for non-contract paths (static/auth/docs → allowed). */
+  operationOf: (c: Context) => string | undefined;
+  /** the declared access facet for an operation (e.g. from the document's x-suluk-access). */
+  accessOf: (operation: string) => AccessFacet | undefined;
+  /**
+   * what an operation that declares NO access facet requires. Defaults to "authenticated" — DENY BY DEFAULT, so a
+   * dropped/missing facet is a 401 in tests, NEVER a silent public route (a fail-open default is how an annotation
+   * gap becomes a live breach). Mark genuinely-public ops explicitly `requires:"anyone"`.
+   */
+  defaultRequires?: AccessRequires;
+}
+
+/** Normalize a wire-supplied `requires` to the CLOSED enum; an unknown/typo'd value is `null` → fail closed. */
+function normalizeRequires(raw: string | undefined, fallback: AccessRequires): AccessRequires | null {
+  const v = (raw ?? fallback).toLowerCase().trim();
+  return v === "anyone" || v === "authenticated" || v === "admin" ? v : null;
+}
+
+/**
+ * The facet-driven gate. Apply once (after identity is resolved, before the handlers): every operation is then
+ * enforced at the level its `x-suluk-access` declares. FAIL-CLOSED throughout — a missing facet denies (deny-by-
+ * default), an unknown/mis-cased `requires` denies, and a non-owner `scope` is enforced even when `requires` is
+ * "anyone" (a named scope implies authentication). Non-contract paths (operationOf → undefined) pass untouched;
+ * a consumer's operationOf MUST be at least as strict as the router and MUST fail closed if it can't resolve.
+ */
+export function enforceAccess(cfg: EnforceAccessConfig): MiddlewareHandler {
+  const fallback = cfg.defaultRequires ?? "authenticated"; // deny by default
+  return async (c, next) => {
+    const op = cfg.operationOf(c);
+    if (!op) return next(); // not a contract operation (static asset, /api/auth, docs) — out of scope
+    const facet = cfg.accessOf(op);
+    const requires = normalizeRequires(facet?.requires, fallback);
+    if (requires === null) return deny(c, 403); // unknown/typo'd level — fail closed, never degrade to authenticated
+    // a named (non-owner) scope is a real requirement; row-level "owner" is the app's CRUD concern, not enforced here
+    const namedScope = facet?.scope && facet.scope !== "owner" ? facet.scope : undefined;
+    if (requires === "anyone" && !namedScope) return next(); // truly public
+    if (!cfg.principal(c)) return deny(c, 401);                                    // authenticated / admin / a named scope all need a caller
+    if (requires === "admin" && !hasScope(cfg, c, "admin")) return deny(c, 403, "admin");
+    if (namedScope && !hasScope(cfg, c, namedScope)) return deny(c, 403, namedScope);
+    return next();
+  };
+}
+
+export interface Guard {
+  /** 401 unless a verified principal is present. */
+  requireAuth: MiddlewareHandler;
+  /** 401 if anonymous, else 403 unless the caller is admin. */
+  requireAdmin: MiddlewareHandler;
+  /** 401 if anonymous, else 403 unless the caller holds EVERY named scope. */
+  requireScopes: (...need: string[]) => MiddlewareHandler;
+}
+
+/** Build explicit, hand-applied guards bound to one identity model (for fine-grained per-route gating). */
+export function createGuard(cfg: IdentityConfig): Guard {
+  const requireAuth: MiddlewareHandler = async (c, next) => (cfg.principal(c) ? next() : deny(c, 401));
+  const requireScopes = (...need: string[]): MiddlewareHandler => async (c, next) => {
+    if (!cfg.principal(c)) return deny(c, 401);
+    for (const s of need) if (!hasScope(cfg, c, s)) return deny(c, 403, s);
+    return next();
+  };
+  return { requireAuth, requireScopes, requireAdmin: requireScopes("admin") };
+}

package/src/errors.ts

@@ -0,0 +1,113 @@
+/**
+ * The error model (saastarter-parity Phase 0) — the portable value extracted from saastarter's dropped Effect
+ * route-handler (src/lib/effect/route-handler.ts): a closed set of typed throws, each mapped to an HTTP status +
+ * an RFC-9457 Problem Details body. In plain Hono the idiom is throw-a-typed-error → an `onError` handler maps it
+ * to the wire (see on-error.ts). The status/title/code mapping is the SHARED core table (@suluk/core errors.ts),
+ * so the SDK's `isApiError`, testgen's error-conformance, and enforce.ts's deny body all agree on one envelope.
+ */
+import {
+  PROBLEM_STATUS_TABLE, TITLE_BY_TAG, toProblemDetails, retryAfterSeconds,
+  type ErrorTag, type ProblemDetails, type ProblemStatus,
+} from "@suluk/core";
+
+export interface SulukHttpErrorInit {
+  /** the human-readable explanation (RFC-9457 `detail`). */
+  detail?: string;
+  /** a URI reference identifying the specific occurrence (RFC-9457 `instance`). */
+  instance?: string;
+  /** structured validation errors (saastarter's `details`). */
+  errors?: Record<string, unknown>;
+  /** override the `type` URI (default "about:blank"). */
+  type?: string;
+  /** RateLimitedError: ms until the window resets — drives the Retry-After header (route-handler.ts:75). */
+  retryAfterMs?: number;
+  /** server-only diagnostic context (cause/service/op) — LOGGED by onError, never sent on the wire. */
+  logContext?: unknown;
+}
+
+/**
+ * A typed, throwable HTTP error. `tag` selects the status + title from the frozen core tables; the instance
+ * renders to a Problem Details body via {@link toProblem}. Throw one from a handler; `onError()` maps it.
+ */
+export class SulukHttpError extends Error {
+  readonly tag: ErrorTag;
+  readonly instance?: string;
+  readonly errors?: Record<string, unknown>;
+  readonly problemType?: string;
+  readonly retryAfterMs?: number;
+  readonly logContext?: unknown;
+
+  constructor(tag: ErrorTag, init: SulukHttpErrorInit = {}) {
+    super(init.detail ?? TITLE_BY_TAG[tag]);
+    this.name = tag;
+    this.tag = tag;
+    if (init.detail !== undefined) this.detail = init.detail;
+    this.instance = init.instance;
+    this.errors = init.errors;
+    this.problemType = init.type;
+    this.retryAfterMs = init.retryAfterMs;
+    this.logContext = init.logContext;
+  }
+
+  /** the human `detail` (distinct from Error.message, which mirrors it for stack-trace readability). */
+  readonly detail?: string;
+
+  /** the HTTP status this error renders as (the frozen core mapping). */
+  get status(): ProblemStatus {
+    return PROBLEM_STATUS_TABLE[this.tag];
+  }
+
+  /** seconds for the Retry-After header (RateLimitedError only) — `ceil(retryAfterMs/1000)`, else undefined. */
+  get retryAfterSeconds(): number | undefined {
+    return this.retryAfterMs == null ? undefined : retryAfterSeconds({ windowMs: this.retryAfterMs });
+  }
+
+  /** render to the canonical RFC-9457 Problem Details body. */
+  toProblem(): ProblemDetails {
+    return toProblemDetails({
+      tag: this.tag,
+      detail: this.detail,
+      instance: this.instance,
+      errors: this.errors,
+      type: this.problemType,
+    });
+  }
+}
+
+/**
+ * Factory helpers mirroring saastarter's TaggedError set (errors.ts) with the SAME field semantics the route-handler
+ * rendered (route-handler.ts:24-86). `externalService`/`internal` keep their detail GENERIC on the wire and stash
+ * the cause in `logContext` (route-handler.ts:63,81 log it server-side, never leak it).
+ */
+export const HttpErrors = {
+  /** 401 (route-handler.ts:26-30). */
+  unauthorized: (detail?: string) => new SulukHttpError("UnauthorizedError", { detail }),
+  /** 403 (route-handler.ts:32-36); `resource` becomes the instance. */
+  forbidden: (detail?: string, resource?: string) =>
+    new SulukHttpError("ForbiddenError", { detail, instance: resource }),
+  /** 401 (route-handler.ts:38-39); the key reason is the detail. */
+  invalidApiKey: (reason: string) => new SulukHttpError("InvalidApiKeyError", { detail: reason }),
+  /** 400 (route-handler.ts:41-45); `details` → `errors`. */
+  validation: (message: string, details?: Record<string, unknown>) =>
+    new SulukHttpError("ValidationError", { detail: message, errors: details }),
+  /** 404 (route-handler.ts:47-51); detail is `${resource} not found`, id → instance. */
+  notFound: (resource: string, id?: string) =>
+    new SulukHttpError("NotFoundError", { detail: `${resource} not found`, instance: id ? `${resource}/${id}` : undefined }),
+  /** 409 (route-handler.ts:53-54). */
+  conflict: (message: string) => new SulukHttpError("ConflictError", { detail: message }),
+  /** 402 (route-handler.ts:56-57); optional Stripe-style `code` → errors. */
+  payment: (message: string, code?: string) =>
+    new SulukHttpError("PaymentError", { detail: message, errors: code ? { code } : undefined }),
+  /** 400 (route-handler.ts:59-60); the discount code → errors, reason → detail. */
+  invalidDiscount: (code: string, reason: string) =>
+    new SulukHttpError("InvalidDiscountError", { detail: reason, errors: { code } }),
+  /** 502 (route-handler.ts:62-67); GENERIC wire detail, cause logged only. */
+  externalService: (service: string, operation: string, cause?: unknown) =>
+    new SulukHttpError("ExternalServiceError", { logContext: { service, operation, cause } }),
+  /** 429 (route-handler.ts:69-78); retryAfterMs drives the Retry-After header. */
+  rateLimited: (retryAfterMs: number) =>
+    new SulukHttpError("RateLimitedError", { retryAfterMs }),
+  /** 500 (route-handler.ts:80-85); GENERIC wire detail, cause logged only. */
+  internal: (message?: string, cause?: unknown) =>
+    new SulukHttpError("PayloadOperationError", { logContext: message || cause ? { message, cause } : undefined }),
+};

package/src/index.ts

@@ -9,3 +9,12 @@ export { audit, coverage, autofill, type Finding } from "./audit";
 export { contractChecks, runContractChecks, type Check, type CheckRun } from "./checks";
 export { validateSchema2020, type SchemaCheck } from "./schema-check";
 export { mount } from "./mount";
+export { enforceAccess, createGuard, type EnforceAccessConfig, type IdentityConfig, type Guard, type AccessFacet, type AccessRequires } from "./enforce";
+// the row-level CRUD authorization engine (mode→policy→rule→decision + owner-scoping) that pairs with enforceAccess.
+export { gate, policyFor, ruleToRequires, DEFAULT_POLICIES, type Rule, type Policy, type AccessMode, type GateIdentity, type GateDecision } from "./access";
+export { SulukHttpError, HttpErrors, type SulukHttpErrorInit } from "./errors";
+export { onError, type OnErrorOptions } from "./on-error";
+export {
+  enforceRateLimit, MemoryRateLimitStore,
+  type EnforceRateLimitConfig, type RateLimitStore, type RateLimitResult, type RateLimitConsumeOptions,
+} from "./ratelimit";

package/src/on-error.ts

@@ -0,0 +1,34 @@
+/**
+ * onError — the Hono error handler that bridges a thrown typed error to the wire as RFC-9457 Problem Details.
+ * The plain-Hono counterpart of saastarter's `handleRoute` catchAll/catchAllDefect (route-handler.ts:109-125):
+ * a {@link SulukHttpError} maps to its declared status + body; ANY other throw is a defect → 500 internal (the
+ * cause logged, never leaked). Wire it once with `app.onError(onError())`.
+ */
+import { PROBLEM_CONTENT_TYPE, toProblemDetails } from "@suluk/core";
+import type { Context } from "hono";
+import { SulukHttpError } from "./errors";
+
+export interface OnErrorOptions {
+  /** sink for server-only diagnostics (defaults to console.error). Receives (message, context). */
+  log?: (message: string, context: unknown) => void;
+}
+
+type ErrorHandler = (err: Error, c: Context) => Response;
+
+/** Build the Hono error handler. Every response carries `content-type: application/problem+json`. */
+export function onError(opts: OnErrorOptions = {}): ErrorHandler {
+  const log = opts.log ?? ((m, ctx) => console.error(m, ctx));
+  return (err, c) => {
+    if (err instanceof SulukHttpError) {
+      if (err.logContext !== undefined) log(`${err.tag}:`, err.logContext); // external/internal causes (route-handler.ts:63,81)
+      const headers: Record<string, string> = { "content-type": PROBLEM_CONTENT_TYPE };
+      const retry = err.retryAfterSeconds;
+      if (retry !== undefined) headers["retry-after"] = String(retry); // route-handler.ts:74-76
+      return c.json(err.toProblem(), err.status, headers);
+    }
+    // an untyped throw is a defect — never leak it (route-handler.ts:117-122).
+    log("Unhandled error in handler:", err);
+    const body = toProblemDetails({ tag: "PayloadOperationError" });
+    return c.json(body, body.status, { "content-type": PROBLEM_CONTENT_TYPE });
+  };
+}

package/src/ratelimit.ts

@@ -0,0 +1,126 @@
+/**
+ * Rate-limit middleware (saastarter-parity Phase 0) — the facet-driven counterpart of enforceAccess: for each
+ * request it resolves the operation, reads its declared `x-suluk-ratelimit` budget, derives a key, consults a
+ * SWAPPABLE store, and emits 429 + Retry-After (the shared RFC-9457 envelope) when the fixed window is exceeded.
+ *
+ * Ports saastarter's checkRateLimit fixed-window algorithm (src/lib/effect/rate-limit.ts:16-38) into a Hono
+ * middleware. Three deliberate shapes:
+ *   • The durable counter is a SWAPPABLE BINDING (the {@link RateLimitStore} interface) — `MemoryRateLimitStore`
+ *     is a DEV default only; the production KV / Durable-Object store lives in @suluk/deploy (roadmap Open-Decision
+ *     #4, KV vs DO). The package never hosts a production runtime (the L3 line).
+ *   • ONE clock owner: the middleware computes `now` (cfg.now ?? Date.now) and passes it into `store.consume`, so
+ *     the store stays a pure function of its inputs and tests inject a deterministic clock.
+ *   • Default-UNLIMITED, opt-in (NOT enforceAccess's deny-by-default): an op without a budget is unmetered — the
+ *     threat models differ (a missing access facet is a breach; a missing rate budget is just unmetered). An
+ *     optional `defaultFacet` is the escape hatch for a blanket floor.
+ *
+ * DEVIATION from saastarter (receipted): saastarter callers prefix the key per-route (`payment-${ip}`); we key by
+ * `${operation}:${scope}:${baseKey}` so per-operation budgets never collide — necessary because each op declares
+ * its OWN window/max (a shared bare-IP counter with two different limits would be incoherent).
+ */
+import { PROBLEM_CONTENT_TYPE, toProblemDetails, retryAfterSeconds, type SulukRateLimit } from "@suluk/core";
+import type { Context, MiddlewareHandler } from "hono";
+
+export interface RateLimitConsumeOptions {
+  maxRequests: number;
+  windowMs: number;
+  /** the current epoch-ms, supplied by the middleware (the single clock owner). */
+  now: number;
+}
+
+export interface RateLimitResult {
+  /** true ⇒ this request is OVER the budget and must be rejected. */
+  limited: boolean;
+  /** requests remaining in the window after this one (≥ 0). */
+  remaining: number;
+  /** ms until the window resets — drives Retry-After. 0 when not limited. */
+  retryAfterMs: number;
+}
+
+/**
+ * The swap point for a durable counter. `consume` atomically records one hit for `key` under the budget and
+ * reports whether it's now over. A production impl (KV / Durable Object) MUST be atomic-per-key; the in-memory
+ * default is per-instance and NOT durable, so it is dev-only.
+ */
+export interface RateLimitStore {
+  consume(key: string, opts: RateLimitConsumeOptions): Promise<RateLimitResult> | RateLimitResult;
+}
+
+/**
+ * DEV-ONLY fixed-window store — a single in-process Map, ported from saastarter rate-limit.ts:7-38. Per-instance
+ * (does NOT coordinate across workers/isolates) so it must NOT back production; use a @suluk/deploy KV/DO binding
+ * there. Retry-After is the FULL `windowMs` (saastarter parity, rate-limit.ts:35); the precise `resetAt - now` is a
+ * documented alternative a durable store may choose instead.
+ */
+export class MemoryRateLimitStore implements RateLimitStore {
+  private readonly store = new Map<string, { count: number; resetAt: number }>();
+
+  consume(key: string, { maxRequests, windowMs, now }: RateLimitConsumeOptions): RateLimitResult {
+    const entry = this.store.get(key);
+    if (!entry || now > entry.resetAt) {
+      this.store.set(key, { count: 1, resetAt: now + windowMs });
+      return { limited: false, remaining: Math.max(0, maxRequests - 1), retryAfterMs: 0 };
+    }
+    entry.count++;
+    const limited = entry.count > maxRequests;
+    return {
+      limited,
+      remaining: Math.max(0, maxRequests - entry.count),
+      retryAfterMs: limited ? windowMs : 0, // saastarter parity (rate-limit.ts:35); precise alt: entry.resetAt - now
+    };
+  }
+}
+
+export interface EnforceRateLimitConfig {
+  /** Resolve the contract operation for a request (undefined ⇒ a non-contract path, passed through). */
+  operationOf: (c: Context) => string | undefined;
+  /** The declared rate budget for an operation (e.g. read off the document's `x-suluk-ratelimit`). */
+  rateLimitOf: (operation: string) => SulukRateLimit | undefined;
+  /** The durable counter (default: a per-instance {@link MemoryRateLimitStore} — DEV ONLY). */
+  store?: RateLimitStore;
+  /** Derive the caller key from a request + facet (default: client IP from x-forwarded-for / x-real-ip). */
+  keyOf?: (c: Context, facet: SulukRateLimit) => string;
+  /** The clock (default: `Date.now`) — the single source of `now`. */
+  now?: () => number;
+  /** A blanket budget applied to operations that declare none (escape hatch; default: unmetered). */
+  defaultFacet?: SulukRateLimit;
+}
+
+/** Default key: the client IP. `"global"` shares one bucket; `"principal"`/`"api-key"` fall back to IP until the
+ * Principal model lands (roadmap Open-Decision #5) — a consumer that has a principal supplies its own `keyOf`. */
+function defaultKeyOf(c: Context, facet: SulukRateLimit): string {
+  if (facet.key === "global") return "global";
+  const fwd = c.req.header("x-forwarded-for");
+  const first = fwd ? fwd.split(",")[0]?.trim() : undefined;
+  return first || c.req.header("x-real-ip") || "unknown";
+}
+
+/** A 429 response in the shared RFC-9457 envelope + a Retry-After header (agrees with the B1 error model). */
+function denyRateLimited(c: Context, retryAfterMs: number): Response {
+  return c.json(toProblemDetails({ tag: "RateLimitedError" }), 429, {
+    "content-type": PROBLEM_CONTENT_TYPE,
+    "retry-after": String(retryAfterSeconds({ windowMs: retryAfterMs })),
+  });
+}
+
+/**
+ * The facet-driven rate-limit gate. Apply once (typically after identity, alongside enforceAccess): every operation
+ * that DECLARES an `x-suluk-ratelimit` budget is metered; the rest pass untouched. On overflow → 429 + Retry-After.
+ */
+export function enforceRateLimit(cfg: EnforceRateLimitConfig): MiddlewareHandler {
+  const store = cfg.store ?? new MemoryRateLimitStore();
+  const clock = cfg.now ?? (() => Date.now());
+  const keyOf = cfg.keyOf ?? defaultKeyOf;
+  return async (c, next) => {
+    const op = cfg.operationOf(c);
+    if (!op) return next(); // not a contract operation
+    const facet = cfg.rateLimitOf(op) ?? cfg.defaultFacet;
+    if (!facet) return next(); // unmetered (opt-in)
+    const base = keyOf(c, facet);
+    const key = `${op}:${facet.scope ?? ""}:${base}`;
+    const res = await store.consume(key, { maxRequests: facet.maxRequests, windowMs: facet.windowMs, now: clock() });
+    if (res.limited) return denyRateLimited(c, res.retryAfterMs);
+    c.header("x-ratelimit-remaining", String(Math.max(0, res.remaining)));
+    return next();
+  };
+}

package/test/access.test.ts

@@ -0,0 +1,46 @@
+/**
+ * The row-level CRUD authorization engine — gate() decisions (fail-closed 401/403 + owner-scoping), policyFor
+ * preset resolution + override, and ruleToRequires (the rule→wire-requires projection that keeps the CRUD gate and
+ * the x-suluk-access facet in lockstep).
+ */
+import { test, expect, describe } from "bun:test";
+import { gate, policyFor, ruleToRequires, DEFAULT_POLICIES, type Rule } from "../src/index";
+
+describe("gate", () => {
+  test("any → open, no scope", () => {
+    expect(gate("any", { isAdmin: false, principal: null })).toEqual({ ok: true, scopeOwner: false });
+  });
+  test("owner: anon → 401, signed-in → scoped, admin → all", () => {
+    expect(gate("owner", { isAdmin: false, principal: null })).toEqual({ ok: false, scopeOwner: false, status: 401 });
+    expect(gate("owner", { isAdmin: false, principal: "u1" })).toEqual({ ok: true, scopeOwner: true });
+    expect(gate("owner", { isAdmin: true, principal: "u1" })).toEqual({ ok: true, scopeOwner: false }); // admin sees all
+  });
+  test("admin: anon → 401 (authenticate first), signed-in-non-admin → 403, admin → ok", () => {
+    expect(gate("admin", { isAdmin: false, principal: null })).toEqual({ ok: false, scopeOwner: false, status: 401 });
+    expect(gate("admin", { isAdmin: false, principal: "u1" })).toEqual({ ok: false, scopeOwner: false, status: 403 });
+    expect(gate("admin", { isAdmin: true, principal: "u1" })).toEqual({ ok: true, scopeOwner: false });
+  });
+  test("none → hard 403", () => {
+    expect(gate("none", { isAdmin: true, principal: "u1" })).toEqual({ ok: false, scopeOwner: false, status: 403 });
+  });
+});
+
+describe("policyFor", () => {
+  test("resolves modes, defaults owned-with-ownerCol / public-without, honors an override matrix", () => {
+    expect(policyFor("owned").update).toBe("owner");
+    expect(policyFor("ownedAppend").update).toBe("admin"); // no self-mutate
+    expect(policyFor(undefined, "customerId")).toEqual(DEFAULT_POLICIES.owned);
+    expect(policyFor(undefined)).toEqual(DEFAULT_POLICIES.public);
+    const custom = { ...DEFAULT_POLICIES, public: { ...DEFAULT_POLICIES.public, list: "admin" as Rule } };
+    expect(policyFor("public", undefined, custom).list).toBe("admin");
+  });
+});
+
+describe("ruleToRequires", () => {
+  test("projects a CRUD rule to the wire requires level", () => {
+    expect(ruleToRequires("any")).toBe("anyone");
+    expect(ruleToRequires("owner")).toBe("authenticated");
+    expect(ruleToRequires("admin")).toBe("admin");
+    expect(ruleToRequires("none")).toBe("admin");
+  });
+});

package/test/enforce.test.ts

@@ -0,0 +1,121 @@
+import { test, expect, describe } from "bun:test";
+import { Hono } from "hono";
+import { enforceAccess, createGuard, type AccessFacet } from "../src/index";
+
+// a tiny app identity model: the x-user header is the "principal", x-admin:1 marks admin, x-scopes is csv.
+const ID = {
+  principal: (c: any) => c.req.header("x-user") || null,
+  isAdmin: (c: any) => c.req.header("x-admin") === "1",
+  scopes: (c: any) => (c.req.header("x-scopes") || "").split(",").filter(Boolean),
+};
+
+describe("@suluk/hono enforceAccess — facet-driven wire enforcement (the server is the boundary)", () => {
+  // a fake contract: op name → access facet + the path it lives at
+  const OPS: Record<string, { path: string; access?: AccessFacet }> = {
+    listPet: { path: "/pet", access: { requires: "anyone" } },
+    createPet: { path: "/pet-create", access: { requires: "admin" } },
+    myCart: { path: "/cart", access: { requires: "authenticated", scope: "owner" } },
+    orgReport: { path: "/report", access: { requires: "authenticated", scope: "org:read" } },
+    undeclared: { path: "/undeclared" },                                   // no facet → DENY by default
+    scopedPublic: { path: "/scoped-public", access: { requires: "anyone", scope: "admin" } }, // a named scope despite anyone
+    miscased: { path: "/miscased", access: { requires: "Admin" } },        // a casing typo must still gate as admin
+    unknownLevel: { path: "/unknown", access: { requires: "superuser" } }, // an unknown level must fail closed
+  };
+  const byPath = Object.fromEntries(Object.entries(OPS).map(([name, o]) => [o.path, name]));
+
+  const app = new Hono();
+  app.use("*", enforceAccess({
+    operationOf: (c) => byPath[new URL(c.req.url).pathname],
+    accessOf: (op) => OPS[op]?.access,
+    ...ID,
+  }));
+  for (const [name, o] of Object.entries(OPS)) app.get(o.path, (c) => c.json({ ok: name }));
+  app.get("/static.css", (c) => c.text("body{}")); // a non-contract path
+
+  const get = (path: string, h: Record<string, string> = {}) => app.request(path, { headers: h });
+
+  test("public op (requires: anyone) is reachable by anon", async () => {
+    expect((await get("/pet")).status).toBe(200);
+  });
+
+  test("admin op: anon → 401, signed-in non-admin → 403, admin → 200", async () => {
+    expect((await get("/pet-create")).status).toBe(401);
+    expect((await get("/pet-create", { "x-user": "u1" })).status).toBe(403);
+    expect((await get("/pet-create", { "x-user": "u1", "x-admin": "1" })).status).toBe(200);
+  });
+
+  test("authenticated op (owner-scoped): anon → 401, any signed-in caller → 200 (row-scoping is the app's job)", async () => {
+    expect((await get("/cart")).status).toBe(401);
+    expect((await get("/cart", { "x-user": "alice" })).status).toBe(200); // owner scope NOT enforced here
+  });
+
+  test("named-scope op: signed-in WITHOUT the scope → 403, WITH it → 200", async () => {
+    expect((await get("/report", { "x-user": "u1" })).status).toBe(403);
+    expect((await get("/report", { "x-user": "u1", "x-scopes": "org:read" })).status).toBe(200);
+  });
+
+  test("FAIL-CLOSED: an undeclared op denies by default (anon → 401), not opens publicly", async () => {
+    expect((await get("/undeclared")).status).toBe(401);                 // deny-by-default (was the fail-open hole)
+    expect((await get("/undeclared", { "x-user": "u" })).status).toBe(200); // a signed-in caller passes the default
+  });
+
+  test("FAIL-CLOSED: a named scope is enforced even when requires is \"anyone\" (no silent scope-drop)", async () => {
+    expect((await get("/scoped-public")).status).toBe(401);              // anon can't reach a scope-gated op
+    expect((await get("/scoped-public", { "x-user": "u" })).status).toBe(403);            // signed-in but no admin scope
+    expect((await get("/scoped-public", { "x-user": "u", "x-admin": "1" })).status).toBe(200);
+  });
+
+  test("FAIL-CLOSED: a mis-cased requires (\"Admin\") still gates as admin (not degraded to authenticated)", async () => {
+    expect((await get("/miscased", { "x-user": "u" })).status).toBe(403);
+    expect((await get("/miscased", { "x-user": "u", "x-admin": "1" })).status).toBe(200);
+  });
+
+  test("FAIL-CLOSED: an UNKNOWN requires level denies everyone (a typo can't open a route)", async () => {
+    expect((await get("/unknown")).status).toBe(403);
+    expect((await get("/unknown", { "x-user": "u" })).status).toBe(403);
+    expect((await get("/unknown", { "x-user": "u", "x-admin": "1" })).status).toBe(403); // even admin — a typo is fixed, not bypassed
+  });
+
+  test("a non-contract path (no matched op) is passed straight through", async () => {
+    expect((await get("/static.css")).status).toBe(200);
+  });
+
+  test("deny responses are RFC-9457-shaped problem+json", async () => {
+    const r = await get("/pet-create");
+    expect(r.headers.get("content-type")).toContain("application/problem+json");
+    const body = await r.json();
+    expect(body).toMatchObject({ error: "unauthorized", status: 401 });
+  });
+
+  test("admin can be expressed via a scope when no isAdmin callback is given", async () => {
+    const app2 = new Hono();
+    app2.use("*", enforceAccess({ operationOf: () => "x", accessOf: () => ({ requires: "admin" }), principal: (c: any) => c.req.header("x-user") || null, scopes: (c: any) => (c.req.header("x-scopes") || "").split(",").filter(Boolean) }));
+    app2.get("/x", (c) => c.json({ ok: true }));
+    expect((await app2.request("/x", { headers: { "x-user": "u" } })).status).toBe(403);
+    expect((await app2.request("/x", { headers: { "x-user": "u", "x-scopes": "admin" } })).status).toBe(200);
+  });
+});
+
+describe("@suluk/hono createGuard — explicit per-route guards", () => {
+  const guard = createGuard(ID);
+  const app = new Hono();
+  app.get("/auth", guard.requireAuth, (c) => c.json({ ok: true }));
+  app.get("/admin", guard.requireAdmin, (c) => c.json({ ok: true }));
+  app.get("/write", guard.requireScopes("write:pets", "read:pets"), (c) => c.json({ ok: true }));
+  const get = (path: string, h: Record<string, string> = {}) => app.request(path, { headers: h });
+
+  test("requireAuth: 401 anon, 200 signed-in", async () => {
+    expect((await get("/auth")).status).toBe(401);
+    expect((await get("/auth", { "x-user": "u" })).status).toBe(200);
+  });
+  test("requireAdmin: 401 anon, 403 non-admin, 200 admin", async () => {
+    expect((await get("/admin")).status).toBe(401);
+    expect((await get("/admin", { "x-user": "u" })).status).toBe(403);
+    expect((await get("/admin", { "x-user": "u", "x-admin": "1" })).status).toBe(200);
+  });
+  test("requireScopes needs EVERY scope (401 anon, 403 partial, 200 all)", async () => {
+    expect((await get("/write")).status).toBe(401);
+    expect((await get("/write", { "x-user": "u", "x-scopes": "write:pets" })).status).toBe(403); // missing read:pets
+    expect((await get("/write", { "x-user": "u", "x-scopes": "write:pets,read:pets" })).status).toBe(200);
+  });
+});

package/test/errors.test.ts

@@ -0,0 +1,121 @@
+import { test, expect, describe } from "bun:test";
+import { Hono } from "hono";
+import { HttpErrors } from "../src/errors";
+import { onError as onErrorHandler } from "../src/on-error";
+import { emitV4 } from "../src/emit";
+import { isProblemDetails } from "@suluk/core";
+
+describe("@suluk/hono error model — typed throws → RFC-9457 (ported from saastarter route-handler.ts)", () => {
+  test("each factory maps to its saastarter status", () => {
+    expect(HttpErrors.unauthorized().status).toBe(401);
+    expect(HttpErrors.forbidden().status).toBe(403);
+    expect(HttpErrors.invalidApiKey("bad").status).toBe(401);
+    expect(HttpErrors.validation("nope").status).toBe(400);
+    expect(HttpErrors.notFound("Pet", "7").status).toBe(404);
+    expect(HttpErrors.conflict("dup").status).toBe(409);
+    expect(HttpErrors.payment("declined").status).toBe(402);
+    expect(HttpErrors.invalidDiscount("SAVE", "expired").status).toBe(400);
+    expect(HttpErrors.externalService("stripe", "charge").status).toBe(502);
+    expect(HttpErrors.rateLimited(60_000).status).toBe(429);
+    expect(HttpErrors.internal().status).toBe(500);
+  });
+
+  test("toProblem renders a valid Problem Details body with ported field semantics", () => {
+    const nf = HttpErrors.notFound("Pet", "7").toProblem();
+    expect(isProblemDetails(nf)).toBe(true);
+    expect(nf).toMatchObject({ status: 404, title: "Not found", detail: "Pet not found", instance: "Pet/7", error: "not_found" });
+
+    const val = HttpErrors.validation("bad body", { name: "required" }).toProblem();
+    expect(val).toMatchObject({ status: 400, detail: "bad body", errors: { name: "required" } });
+  });
+
+  test("externalService/internal keep the wire detail GENERIC and stash the cause for server logs only", () => {
+    const ext = HttpErrors.externalService("stripe", "charge", new Error("boom"));
+    expect(ext.toProblem().detail).toBeUndefined();            // not leaked
+    expect(ext.toProblem().title).toBe("External service unavailable");
+    expect(ext.logContext).toMatchObject({ service: "stripe", operation: "charge" });
+  });
+
+  test("retryAfterSeconds is ceil(retryAfterMs/1000), only for RateLimitedError", () => {
+    expect(HttpErrors.rateLimited(60_000).retryAfterSeconds).toBe(60);
+    expect(HttpErrors.rateLimited(1500).retryAfterSeconds).toBe(2);
+    expect(HttpErrors.notFound("X").retryAfterSeconds).toBeUndefined();
+  });
+});
+
+describe("onError handler — bridges a thrown typed error to the wire", () => {
+  function appThrowing(err: unknown) {
+    const logs: unknown[] = [];
+    const app = new Hono();
+    app.onError(onErrorHandler({ log: (m, ctx) => logs.push([m, ctx]) }));
+    app.get("/boom", () => { throw err; });
+    return { app, logs };
+  }
+
+  test("a SulukHttpError → its status + application/problem+json body", async () => {
+    const { app } = appThrowing(HttpErrors.forbidden("nope"));
+    const r = await app.request("/boom");
+    expect(r.status).toBe(403);
+    expect(r.headers.get("content-type")).toContain("application/problem+json");
+    const body = await r.json();
+    expect(body).toMatchObject({ status: 403, title: "Forbidden", error: "forbidden", detail: "nope" });
+  });
+
+  test("a 429 carries a Retry-After header (seconds)", async () => {
+    const { app } = appThrowing(HttpErrors.rateLimited(60_000));
+    const r = await app.request("/boom");
+    expect(r.status).toBe(429);
+    expect(r.headers.get("retry-after")).toBe("60");
+  });
+
+  test("an untyped throw is a defect → 500, cause logged, never leaked", async () => {
+    const { app, logs } = appThrowing(new Error("secret stack detail"));
+    const r = await app.request("/boom");
+    expect(r.status).toBe(500);
+    const body = await r.json();
+    expect(body.title).toBe("Internal server error");
+    expect(JSON.stringify(body)).not.toContain("secret stack detail");
+    expect(logs.length).toBe(1); // logged server-side
+  });
+});
+
+describe("emitV4 — synthesizes RFC-9457 error responses + a shared ProblemDetails schema", () => {
+  test("an auth-gated op gets 401/403/500 problem+json responses + components.schemas.ProblemDetails", () => {
+    const { document } = emitV4([
+      { method: "get", path: "/admin/report", name: "getReport", scopes: ["admin"] },
+    ], { securityScheme: "bearerAuth" });
+    const resps = document.paths["admin/report"].requests.getReport.responses;
+    expect(Object.keys(resps).sort()).toEqual(["200", "401", "403", "500"]);
+    expect(resps["401"].contentType).toBe("application/problem+json");
+    expect(resps["401"].contentSchema).toEqual({ $ref: "#/components/schemas/ProblemDetails" });
+    expect(document.components?.schemas?.ProblemDetails).toBeDefined();
+  });
+
+  test("a public op gets only the always-500 error (no 401/403 without auth)", () => {
+    const { document } = emitV4([{ method: "get", path: "/health", name: "health" }]);
+    expect(Object.keys(document.paths.health.requests.health.responses).sort()).toEqual(["200", "500"]);
+  });
+
+  test("explicit route.errors + rateLimit synthesize 404 + 429; a user-declared response is never clobbered", () => {
+    const { document } = emitV4([
+      {
+        method: "post", path: "/orders", name: "createOrder",
+        errors: [404],
+        rateLimit: { windowMs: 60_000, maxRequests: 20, key: "ip" },
+        responses: [{ status: 201, description: "created" }],
+      },
+    ]);
+    const resps = document.paths.orders.requests.createOrder.responses;
+    expect(Object.keys(resps).sort()).toEqual(["201", "404", "429", "500"]);
+    expect(resps["201"].description).toBe("created"); // user's response preserved
+    expect(document.paths.orders.requests.createOrder["x-suluk-ratelimit"]).toMatchObject({ maxRequests: 20 });
+  });
+
+  test("synthesizeErrors:false yields a success-only projection (no error responses, no ProblemDetails schema)", () => {
+    const { document } = emitV4([
+      { method: "get", path: "/admin/report", name: "getReport", scopes: ["admin"] },
+    ], { synthesizeErrors: false });
+    expect(Object.keys(document.paths["admin/report"].requests.getReport.responses)).toEqual(["200"]);
+    expect(document.components?.schemas?.ProblemDetails).toBeUndefined();
+  });
+});

package/test/ratelimit.test.ts

@@ -0,0 +1,104 @@
+import { test, expect, describe } from "bun:test";
+import { Hono } from "hono";
+import { enforceRateLimit, MemoryRateLimitStore } from "../src/ratelimit";
+import type { SulukRateLimit } from "@suluk/core";
+
+describe("MemoryRateLimitStore — fixed window (ported from saastarter rate-limit.ts)", () => {
+  test("permits up to maxRequests, then limits; Retry-After is the full window (saastarter parity)", () => {
+    const s = new MemoryRateLimitStore();
+    const opts = { maxRequests: 2, windowMs: 60_000, now: 1_000 };
+    expect(s.consume("k", opts)).toMatchObject({ limited: false, remaining: 1 });
+    expect(s.consume("k", opts)).toMatchObject({ limited: false, remaining: 0 });
+    const third = s.consume("k", opts);
+    expect(third.limited).toBe(true);
+    expect(third.retryAfterMs).toBe(60_000); // rate-limit.ts:35
+  });
+
+  test("the window resets once now passes resetAt", () => {
+    const s = new MemoryRateLimitStore();
+    s.consume("k", { maxRequests: 1, windowMs: 1_000, now: 0 });
+    expect(s.consume("k", { maxRequests: 1, windowMs: 1_000, now: 500 }).limited).toBe(true);  // same window
+    expect(s.consume("k", { maxRequests: 1, windowMs: 1_000, now: 2_000 }).limited).toBe(false); // window rolled
+  });
+
+  test("distinct keys hold independent counters", () => {
+    const s = new MemoryRateLimitStore();
+    const opts = { maxRequests: 1, windowMs: 1_000, now: 0 };
+    expect(s.consume("a", opts).limited).toBe(false);
+    expect(s.consume("b", opts).limited).toBe(false); // b is not affected by a
+    expect(s.consume("a", opts).limited).toBe(true);
+  });
+});
+
+describe("enforceRateLimit middleware — facet-driven, 429 + Retry-After", () => {
+  const BUDGET: SulukRateLimit = { windowMs: 60_000, maxRequests: 2, key: "ip" };
+
+  // a controllable clock + an operation router, mirroring enforce.test.ts's harness style.
+  function makeApp(facets: Record<string, SulukRateLimit | undefined>, opts?: { now?: () => number }) {
+    const byPath: Record<string, string> = {
+      "/limited": "limited", "/other": "other", "/free": "free",
+    };
+    const app = new Hono();
+    app.use("*", enforceRateLimit({
+      operationOf: (c) => byPath[new URL(c.req.url).pathname],
+      rateLimitOf: (op) => facets[op],
+      store: new MemoryRateLimitStore(),
+      now: opts?.now,
+    }));
+    app.get("/limited", (c) => c.text("ok"));
+    app.get("/other", (c) => c.text("ok"));
+    app.get("/free", (c) => c.text("ok"));
+    app.get("/static.css", (c) => c.text("body{}")); // non-contract path
+    return app;
+  }
+  const ip = { "x-forwarded-for": "1.2.3.4" };
+
+  test("an op WITHOUT a facet is unmetered (never 429)", async () => {
+    const app = makeApp({ free: undefined });
+    for (let i = 0; i < 10; i++) expect((await app.request("/free", { headers: ip })).status).toBe(200);
+  });
+
+  test("a metered op returns 429 + Retry-After once the budget is exceeded", async () => {
+    let t = 1000;
+    const app = makeApp({ limited: BUDGET }, { now: () => t });
+    expect((await app.request("/limited", { headers: ip })).status).toBe(200);
+    expect((await app.request("/limited", { headers: ip })).status).toBe(200);
+    const r = await app.request("/limited", { headers: ip });
+    expect(r.status).toBe(429);
+    expect(r.headers.get("content-type")).toContain("application/problem+json");
+    expect(r.headers.get("retry-after")).toBe("60");
+    const body = await r.json();
+    expect(body).toMatchObject({ status: 429, title: "Too many requests", error: "rate_limited" });
+  });
+
+  test("advancing the clock past the window lets the caller through again", async () => {
+    let t = 1000;
+    const app = makeApp({ limited: BUDGET }, { now: () => t });
+    await app.request("/limited", { headers: ip });
+    await app.request("/limited", { headers: ip });
+    expect((await app.request("/limited", { headers: ip })).status).toBe(429);
+    t += 60_001; // roll the window
+    expect((await app.request("/limited", { headers: ip })).status).toBe(200);
+  });
+
+  test("budgets are PER-OPERATION (a different op does not drain this op's counter)", async () => {
+    const app = makeApp({ limited: BUDGET, other: BUDGET });
+    await app.request("/limited", { headers: ip });
+    await app.request("/limited", { headers: ip });
+    expect((await app.request("/limited", { headers: ip })).status).toBe(429);
+    expect((await app.request("/other", { headers: ip })).status).toBe(200); // independent budget
+  });
+
+  test("budgets are per-IP (a different client is unaffected)", async () => {
+    const app = makeApp({ limited: BUDGET });
+    await app.request("/limited", { headers: ip });
+    await app.request("/limited", { headers: ip });
+    expect((await app.request("/limited", { headers: ip })).status).toBe(429);
+    expect((await app.request("/limited", { headers: { "x-forwarded-for": "9.9.9.9" } })).status).toBe(200);
+  });
+
+  test("a non-contract path passes straight through", async () => {
+    const app = makeApp({ limited: BUDGET });
+    expect((await app.request("/static.css")).status).toBe(200);
+  });
+});