@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/lib/http/middleware/rateLimit.d.ts

@@ -0,0 +1,105 @@
+import type { Context, MiddlewareHandler } from "hono";
+import type { RateLimitBackend } from "../../app/services/rateLimit/RateLimitBackend.js";
+import { logger as defaultLogger } from "../../observability/logger.js";
+/**
+ * `rateLimit({ windowMs, max, ... })` — Hono middleware factory.
+ *
+ * Replaces v3's in-memory `RateLimitMiddleware`. Production-default backend
+ * is `RedisSlidingWindowBackend` (atomic Lua sliding-window log); v4.0 also
+ * ships `InMemorySlidingWindowBackend` for tests + dev fallback.
+ *
+ * Headers (RFC-draft `RateLimit-*`):
+ *   - `RateLimit-Limit: <max>`
+ *   - `RateLimit-Remaining: <max - used>`
+ *   - `RateLimit-Policy: <max>;w=<window-seconds>`
+ * Optional legacy headers (`X-RateLimit-Limit/Remaining/Reset`) emitted when
+ * `legacyHeaders: true` for clients that haven't moved to the draft yet.
+ *
+ * On rejection: throws `RateLimitError` (mapped to 429 by registerErrorHandlers)
+ * after setting `Retry-After: <seconds>`. The middleware sets headers on the
+ * outgoing response *before* throwing so the 429 response carries them.
+ *
+ * Redis-unavailable behavior is configurable, NOT a silent fallback:
+ *   - `'deny'` (default, fail-closed) — returns RateLimitError as if the
+ *     ceiling were exceeded. Safer default; the user gets a real 429
+ *     instead of unintentional unlimited access.
+ *   - `'allow'` (fail-open) — calls next() without enforcement. Logs a
+ *     warning so operators can detect Redis flapping.
+ *
+ * Tagged `RATE_LIMIT_META` so `createApp` populates the route registry.
+ */
+export interface RateLimitOptions {
+    /** Window length in milliseconds. */
+    windowMs: number;
+    /** Maximum requests per key per window. */
+    max: number;
+    /** Backend implementation. Default: a shared in-memory backend; production
+     *  consumers pass a `RedisSlidingWindowBackend`. */
+    backend: RateLimitBackend;
+    /**
+     * Compose the bucket key from the request. Default: authenticated user
+     * ID (from `c.get('user').id`) when set, else the client IP. The request
+     * path is *not* included by default — for per-route limits, instantiate
+     * a separate `rateLimit({...})` per route.
+     */
+    keyGenerator?: (c: Context) => string;
+    /**
+     * Namespace appended to the bucket key (e.g., `"login"` for a tighter
+     * limiter on `POST /accounts/login`). Default: empty.
+     */
+    scope?: string;
+    /**
+     * Behavior when the backend throws (e.g., Redis unreachable):
+     *   - `'deny'` (default): treat as over-limit, throw RateLimitError.
+     *   - `'allow'`: log a warning, call next() without enforcement.
+     *
+     * **F28 — security note on `'allow'`.** `onBackendError: 'allow'`
+     * **removes rate limiting entirely** during any window where the
+     * backend is unavailable — login / signup / password-reset
+     * endpoints become unbounded for the duration of the outage. Don't
+     * pick `'allow'` as a workaround for flaky Redis: fix Redis first
+     * (HA failover, connection pool tuning, a separate Redis tier
+     * for rate-limit state). Choose `'allow'` only with a deliberate
+     * threat-model decision that the availability cost of brief
+     * unlimited access during outages outweighs the security cost.
+     * Common deployments where `'allow'` is defensible: internal-only
+     * APIs behind VPN auth where rate limiting is UX-shaping rather
+     * than security; public APIs with WAF-layer rate limiting
+     * upstream. Public-facing SaaS authentication endpoints are
+     * exactly where `'allow'` is wrong.
+     */
+    onBackendError?: "allow" | "deny";
+    /** Emit `X-RateLimit-*` headers in addition to the RFC draft `RateLimit-*` set. */
+    legacyHeaders?: boolean;
+    /** Override the framework default pino logger. */
+    logger?: typeof defaultLogger;
+    /**
+     * CIDR allowlist for upstream proxies. The default key generator
+     * trusts `X-Forwarded-For` **only** when the immediate peer's IP
+     * falls inside one of these ranges; otherwise XFF is ignored and
+     * the peer IP wins. The framework default is the empty list — the
+     * secure, fail-closed posture for adopters who haven't declared
+     * their topology.
+     *
+     * In production, set this to the public CIDR ranges of your CDN /
+     * load balancer (Cloudflare, AWS ALB, Fastly, Google Cloud Armor,
+     * etc.). The rightmost-untrusted-IP walker then returns the real
+     * client IP from XFF, skipping each known proxy hop.
+     *
+     * Example (Cloudflare, abbreviated):
+     *   `trustProxy: ["173.245.48.0/20", "103.21.244.0/22", "2400:cb00::/32", ...]`
+     *
+     * `["0.0.0.0/0", "::/0"]` trusts every peer — useful in unit tests
+     * where the peer IP cannot be observed, **never** in production.
+     */
+    trustProxy?: readonly string[];
+    /**
+     * Resolve the immediate peer IP from the Hono `Context`. Default:
+     * read `c.env.incoming.socket.remoteAddress` (Node adapter). Tests
+     * and non-Node runtimes (Cloudflare, Deno, Bun) override this with
+     * an env-specific reader.
+     */
+    resolvePeerIp?: (c: Context) => string | undefined;
+}
+export declare function rateLimit(opts: RateLimitOptions): MiddlewareHandler;
+//# sourceMappingURL=rateLimit.d.ts.map

package/lib/http/middleware/rateLimit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimit.d.ts","sourceRoot":"","sources":["../../../src/http/middleware/rateLimit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kDAAkD,CAAC;AACzF,OAAO,EAAE,MAAM,IAAI,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAKxE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ;wDACoD;IACpD,OAAO,EAAE,gBAAgB,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,CAAC;IACtC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAClC,mFAAmF;IACnF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kDAAkD;IAClD,MAAM,CAAC,EAAE,OAAO,aAAa,CAAC;IAC9B;;;;;;;;;;;;;;;;;;OAkBG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;CACpD;AAiDD,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,iBAAiB,CA2DnE"}

package/lib/http/middleware/rateLimit.js

@@ -0,0 +1,84 @@
+import { logger as defaultLogger } from "../../observability/logger.js";
+import { RateLimitError } from "../errors/RateLimitError.js";
+import { compileTrustProxy, resolveClientIp } from "../utils/clientIp.js";
+import { RATE_LIMIT_META, setMetaTag } from "../utils/metaTags.js";
+function defaultResolvePeerIp(c) {
+    // Node adapter exposes the underlying IncomingMessage via `c.env.incoming`.
+    // Cloudflare / Deno / Bun runtimes pass `resolvePeerIp` explicitly.
+    const env = c.env;
+    return env?.incoming?.socket?.remoteAddress;
+}
+function makeDefaultKeyGenerator(trustList, resolvePeerIp) {
+    return (c) => {
+        // Prefer authenticated user when present — auth-bound limits are
+        // never affected by IP trust, since the key is identity-based.
+        const user = c.get("user");
+        if (user?.id)
+            return `user:${user.id}`;
+        const peerIp = resolvePeerIp(c);
+        const xff = c.req.header("x-forwarded-for");
+        return `ip:${resolveClientIp({ peerIp, xff, trustProxy: trustList })}`;
+    };
+}
+function setHeaders(c, used, limit, windowMs, resetAtMs, legacy) {
+    const remaining = Math.max(0, limit - used);
+    const windowSec = Math.ceil(windowMs / 1000);
+    const resetEpochSec = Math.ceil(resetAtMs / 1000);
+    // RFC-draft headers (draft-ietf-httpapi-ratelimit-headers-10).
+    c.header("RateLimit-Limit", String(limit));
+    c.header("RateLimit-Remaining", String(remaining));
+    c.header("RateLimit-Policy", `${limit};w=${windowSec}`);
+    if (legacy) {
+        c.header("X-RateLimit-Limit", String(limit));
+        c.header("X-RateLimit-Remaining", String(remaining));
+        c.header("X-RateLimit-Reset", String(resetEpochSec));
+    }
+}
+export function rateLimit(opts) {
+    if (opts.windowMs <= 0 || opts.max <= 0) {
+        throw new Error("rateLimit(): windowMs and max must be positive");
+    }
+    const trustList = compileTrustProxy(opts.trustProxy);
+    const resolvePeerIp = opts.resolvePeerIp ?? defaultResolvePeerIp;
+    const keyGen = opts.keyGenerator ?? makeDefaultKeyGenerator(trustList, resolvePeerIp);
+    const onBackendError = opts.onBackendError ?? "deny";
+    const log = opts.logger ?? defaultLogger;
+    const scopePrefix = opts.scope ? `${opts.scope}:` : "";
+    const middleware = async (c, next) => {
+        const key = scopePrefix + keyGen(c);
+        const now = Date.now();
+        let result;
+        try {
+            result = await opts.backend.check({
+                key,
+                windowMs: opts.windowMs,
+                max: opts.max,
+                now,
+            });
+        }
+        catch (err) {
+            // Backend failure (e.g., Redis down). Apply the configured policy.
+            log.warn({ err, key, policy: onBackendError }, "ratelimit.backend_error");
+            if (onBackendError === "allow")
+                return next();
+            // 'deny' — fail closed
+            const retryAfterSec = Math.max(1, Math.ceil(opts.windowMs / 1000));
+            throw new RateLimitError(retryAfterSec, "Rate limiter unavailable");
+        }
+        setHeaders(c, result.used, result.limit, opts.windowMs, result.resetAtMs, opts.legacyHeaders ?? false);
+        if (!result.allowed) {
+            const retryAfterSec = Math.max(1, Math.ceil((result.resetAtMs - now) / 1000));
+            c.header("Retry-After", String(retryAfterSec));
+            throw new RateLimitError(retryAfterSec);
+        }
+        return next();
+    };
+    const tag = {
+        windowMs: opts.windowMs,
+        max: opts.max,
+        scope: opts.scope,
+    };
+    setMetaTag(middleware, RATE_LIMIT_META, tag);
+    return middleware;
+}
+//# sourceMappingURL=rateLimit.js.map

package/lib/http/middleware/rateLimit.js.map

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

package/lib/http/middleware/requireAuth.d.ts

@@ -0,0 +1,58 @@
+import type { MiddlewareHandler } from "hono";
+import type { AuthenticatedAccount, AuthProvider } from "../../app/auth/AuthProvider.js";
+/**
+ * `requireAuth({ provider, ... })` — Hono middleware factory that runs the
+ * configured `AuthProvider` chain (verify + resolve) and attaches the
+ * authenticated `Account` to `c.set('user', ...)`.
+ *
+ * Replaces v3's `JwtAuthMiddleware`. Key differences:
+ *
+ * 1. **Pluggable**. Backed by the `AuthProvider` interface; Firebase is
+ *    adapter #1, but any v4.x adapter (Better-Auth / Clerk / WorkOS / …)
+ *    drops in without changing this middleware.
+ *
+ * 2. **Silent fall-through is opt-in**. The v3 default (no token →
+ *    `next()` without user) was a footgun. v4 throws `AuthenticationError`
+ *    when a token is missing unless `optional: true` is set explicitly.
+ *
+ * 3. **Tagged for the route registry**. `createApp`'s interceptor reads
+ *    the `AUTH_META` tag to populate the route registry with auth state
+ *    so MCP tools, `ship-reviewer`, and `/dev/routes` know whether each
+ *    route requires auth.
+ *
+ * 4. **Throws AppErrors**, not direct responses. `app.onError(...)` formats
+ *    them — keeps the response shape consistent across the framework.
+ *
+ * Failure mapping:
+ * - `missing-token` + `optional: false` → 401 `AuthenticationError`
+ * - `missing-token` + `optional: true`  → `next()` with no user / claims
+ * - any other verify failure (invalid / expired / revoked / issuer-mismatch)
+ *   → 401 `AuthenticationError` regardless of `optional` (a present-but-bad
+ *   token is always rejected)
+ * - verify ok + resolve returns null + `onUnknownAccount: 'reject'` (default)
+ *   → 403 `AuthorizationError`
+ * - verify ok + resolve null + `onUnknownAccount: 'next'` → `next()` with
+ *   `claims` set but no `user`
+ *
+ * On success: sets `c.set('user', account)` and `c.set('claims', claims)`,
+ * publishes `account.id` to `RequestContext.userId` (so audit-stamping and
+ * structured logging see the actor), then `next()`.
+ */
+export interface RequireAuthOptions<TAccount extends AuthenticatedAccount = AuthenticatedAccount> {
+    /** The AuthProvider to use. Required. */
+    provider: AuthProvider<TAccount>;
+    /**
+     * If true, missing tokens fall through to `next()` without throwing. Default
+     * `false`. Use this for endpoints that serve unauthenticated traffic with
+     * degraded data (e.g., a public profile page that shows extra fields when
+     * logged in).
+     */
+    optional?: boolean;
+}
+/** Hono context-variable keys this middleware sets on success. */
+export declare const AUTH_CONTEXT_KEYS: {
+    user: "user";
+    claims: "claims";
+};
+export declare function requireAuth<TAccount extends AuthenticatedAccount = AuthenticatedAccount>(opts: RequireAuthOptions<TAccount>): MiddlewareHandler;
+//# sourceMappingURL=requireAuth.d.ts.map

package/lib/http/middleware/requireAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requireAuth.d.ts","sourceRoot":"","sources":["../../../src/http/middleware/requireAuth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,KAAK,EAEV,oBAAoB,EACpB,YAAY,EAEb,MAAM,gCAAgC,CAAC;AAMxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,MAAM,WAAW,kBAAkB,CAAC,QAAQ,SAAS,oBAAoB,GAAG,oBAAoB;IAC9F,yCAAyC;IACzC,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,kEAAkE;AAClE,eAAO,MAAM,iBAAiB;;;CAG7B,CAAC;AAYF,wBAAgB,WAAW,CAAC,QAAQ,SAAS,oBAAoB,GAAG,oBAAoB,EACtF,IAAI,EAAE,kBAAkB,CAAC,QAAQ,CAAC,GACjC,iBAAiB,CAmDnB"}

package/lib/http/middleware/requireAuth.js

@@ -0,0 +1,63 @@
+import { setRequestContextField } from "../../app/context/RequestContext.js";
+import { AuthenticationError } from "../errors/AuthenticationError.js";
+import { AuthorizationError } from "../errors/AuthorizationError.js";
+import { AUTH_META, setMetaTag } from "../utils/metaTags.js";
+/** Hono context-variable keys this middleware sets on success. */
+export const AUTH_CONTEXT_KEYS = {
+    user: "user",
+    claims: "claims",
+};
+function buildProviderContext(c) {
+    const headers = {};
+    // Hono normalizes header names to lowercase; AuthProvider adapters
+    // (firebase) expect lowercase too.
+    c.req.raw.headers.forEach((value, key) => {
+        headers[key.toLowerCase()] = value;
+    });
+    return { headers };
+}
+export function requireAuth(opts) {
+    const { provider } = opts;
+    const optional = opts.optional ?? false;
+    const middleware = async (c, next) => {
+        const providerCtx = buildProviderContext(c);
+        const verifyResult = await provider.verify(providerCtx);
+        if (!verifyResult.ok) {
+            if (verifyResult.reason === "missing-token") {
+                if (optional)
+                    return next();
+                throw new AuthenticationError(verifyResult.message ?? "Authentication required");
+            }
+            // present-but-bad token is always rejected, even when optional=true
+            throw new AuthenticationError(verifyResult.message ?? `Authentication failed (${verifyResult.reason})`);
+        }
+        const claims = verifyResult.claims;
+        const account = await provider.resolve(claims);
+        if (account === null) {
+            const policy = provider.onUnknownAccount ?? "reject";
+            if (policy === "next") {
+                c.set(AUTH_CONTEXT_KEYS.claims, claims);
+                return next();
+            }
+            // 'create' is the provider's responsibility — if a provider wants
+            // first-sight account creation it does it inside `resolve()` itself.
+            // Here we treat 'create' as 'reject' (no-op) since we can't synthesize
+            // an account.
+            throw new AuthorizationError("No account registered for this credential");
+        }
+        c.set(AUTH_CONTEXT_KEYS.user, account);
+        c.set(AUTH_CONTEXT_KEYS.claims, claims);
+        // Publish the resolved account id to the request context so the logger,
+        // `DrizzleEntityService` audit-stamping (createdBy / updatedBy), and OTel
+        // spans all see the actor. No-op (returns false) outside an active context.
+        setRequestContextField("userId", account.id);
+        return next();
+    };
+    const tag = {
+        required: !optional,
+        providerName: provider.name,
+    };
+    setMetaTag(middleware, AUTH_META, tag);
+    return middleware;
+}
+//# sourceMappingURL=requireAuth.js.map

package/lib/http/middleware/requireAuth.js.map

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

package/lib/http/middleware/requirePermission.d.ts

@@ -0,0 +1,23 @@
+import type { MiddlewareHandler } from "hono";
+/**
+ * `requirePermission(...slugs)` — Hono middleware factory that enforces
+ * the authenticated user has at least one of the supplied permission slugs
+ * (OR semantics within a single call).
+ *
+ * Replaces v3's `@HasPermission` decorator. To express AND across multiple
+ * permission groups, chain multiple `requirePermission()` middlewares —
+ * `createApp`'s registry interceptor unions slugs across calls so the
+ * registry shows the full set, and the runtime checks each call gates
+ * independently.
+ *
+ * Must run *after* a `requireAuth(...)` middleware on the same route — if
+ * `c.get('user')` is unset, this throws `AuthenticationError`. The user
+ * object must implement `hasPermission(slug)`; if not, this throws an
+ * Error (configuration issue → 500).
+ *
+ * Tagged with `PERMISSION_META` so `createApp`'s interceptor and downstream
+ * tooling (MCP `describe_route`, `ship-reviewer`, `/dev/routes`) see the
+ * permission slugs the route requires.
+ */
+export declare function requirePermission(...slugs: string[]): MiddlewareHandler;
+//# sourceMappingURL=requirePermission.d.ts.map

package/lib/http/middleware/requirePermission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirePermission.d.ts","sourceRoot":"","sources":["../../../src/http/middleware/requirePermission.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAM9C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,iBAAiB,CAqCvE"}

package/lib/http/middleware/requirePermission.js

@@ -0,0 +1,50 @@
+import { AuthenticationError } from "../errors/AuthenticationError.js";
+import { AuthorizationError } from "../errors/AuthorizationError.js";
+import { PERMISSION_META, setMetaTag } from "../utils/metaTags.js";
+/**
+ * `requirePermission(...slugs)` — Hono middleware factory that enforces
+ * the authenticated user has at least one of the supplied permission slugs
+ * (OR semantics within a single call).
+ *
+ * Replaces v3's `@HasPermission` decorator. To express AND across multiple
+ * permission groups, chain multiple `requirePermission()` middlewares —
+ * `createApp`'s registry interceptor unions slugs across calls so the
+ * registry shows the full set, and the runtime checks each call gates
+ * independently.
+ *
+ * Must run *after* a `requireAuth(...)` middleware on the same route — if
+ * `c.get('user')` is unset, this throws `AuthenticationError`. The user
+ * object must implement `hasPermission(slug)`; if not, this throws an
+ * Error (configuration issue → 500).
+ *
+ * Tagged with `PERMISSION_META` so `createApp`'s interceptor and downstream
+ * tooling (MCP `describe_route`, `ship-reviewer`, `/dev/routes`) see the
+ * permission slugs the route requires.
+ */
+export function requirePermission(...slugs) {
+    if (slugs.length === 0) {
+        throw new Error("requirePermission(): at least one slug must be provided");
+    }
+    const middleware = async (c, next) => {
+        const user = c.get("user");
+        if (!user) {
+            throw new AuthenticationError("requirePermission: no authenticated user — apply requireAuth(...) before this middleware");
+        }
+        if (typeof user.hasPermission !== "function") {
+            throw new Error("requirePermission: the resolved user does not implement hasPermission(slug). " +
+                "Ensure your AuthProvider's resolve() returns an Account that does.");
+        }
+        for (const slug of slugs) {
+            const ok = await user.hasPermission(slug);
+            if (ok)
+                return next();
+        }
+        throw new AuthorizationError(slugs.length === 1
+            ? `Missing required permission: ${slugs[0]}`
+            : `Requires one of: ${slugs.join(", ")}`);
+    };
+    const tag = { permissions: [...slugs] };
+    setMetaTag(middleware, PERMISSION_META, tag);
+    return middleware;
+}
+//# sourceMappingURL=requirePermission.js.map

package/lib/http/middleware/requirePermission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirePermission.js","sourceRoot":"","sources":["../../../src/http/middleware/requirePermission.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,eAAe,EAAuB,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAExF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAG,KAAe;IAClD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IAED,MAAM,UAAU,GAAsB,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QACtD,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,MAAe,CAAqC,CAAC;QAExE,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,mBAAmB,CAC3B,0FAA0F,CAC3F,CAAC;QACJ,CAAC;QAED,IAAI,OAAO,IAAI,CAAC,aAAa,KAAK,UAAU,EAAE,CAAC;YAC7C,MAAM,IAAI,KAAK,CACb,+EAA+E;gBAC7E,oEAAoE,CACvE,CAAC;QACJ,CAAC;QAED,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;YAC1C,IAAI,EAAE;gBAAE,OAAO,IAAI,EAAE,CAAC;QACxB,CAAC;QAED,MAAM,IAAI,kBAAkB,CAC1B,KAAK,CAAC,MAAM,KAAK,CAAC;YAChB,CAAC,CAAC,gCAAgC,KAAK,CAAC,CAAC,CAAC,EAAE;YAC5C,CAAC,CAAC,oBAAoB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC3C,CAAC;IACJ,CAAC,CAAC;IAEF,MAAM,GAAG,GAAmB,EAAE,WAAW,EAAE,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC;IACxD,UAAU,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,CAAC,CAAC;IAE7C,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/lib/http/middleware/resolveTenant.d.ts

@@ -0,0 +1,41 @@
+import type { Context, MiddlewareHandler } from "hono";
+/**
+ * `resolveTenant()` — opt-in middleware that resolves the active tenant for the
+ * request and publishes it to `RequestContext.tenantId`.
+ *
+ * The framework convention is: code reads the active tenant from
+ * `RequestContext.tenantId`, NEVER from `account.tenantId` directly. That
+ * indirection is what keeps a future one-tenant-per-user → membership move
+ * (Model A → B) a one-middleware change — swap this resolver and every
+ * downstream read is unaffected.
+ *
+ * Default (Model A — one tenant per account): read `tenantId` off the
+ * authenticated account that `requireAuth` placed on the Hono context. Wire it
+ * AFTER `requireAuth`:
+ *
+ * ```ts
+ * app.use("*", requireAuth({ provider }));
+ * app.use("*", resolveTenant());
+ * ```
+ *
+ * For custom resolution (a tenant header, a sub-domain, a membership lookup),
+ * pass `resolve`:
+ *
+ * ```ts
+ * app.use("*", resolveTenant({ resolve: (c) => c.req.header("x-tenant-id") }));
+ * ```
+ *
+ * This is a thin, opt-in helper — single-tenant products never wire it and
+ * `RequestContext.tenantId` stays `undefined`. Tenant *enforcement*
+ * (auto-scoping every query) is deferred to V8; this only resolves + publishes.
+ */
+export interface ResolveTenantOptions {
+    /**
+     * Custom resolver. Receives the Hono context and returns the active tenant id
+     * (or `undefined` / `null` to leave `RequestContext.tenantId` unset). Default:
+     * read `tenantId` off the authenticated account (`c.get("user")`).
+     */
+    resolve?: (c: Context) => string | null | undefined | Promise<string | null | undefined>;
+}
+export declare function resolveTenant(opts?: ResolveTenantOptions): MiddlewareHandler;
+//# sourceMappingURL=resolveTenant.d.ts.map

package/lib/http/middleware/resolveTenant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveTenant.d.ts","sourceRoot":"","sources":["../../../src/http/middleware/resolveTenant.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAIvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CAC1F;AAED,wBAAgB,aAAa,CAAC,IAAI,GAAE,oBAAyB,GAAG,iBAAiB,CAchF"}

package/lib/http/middleware/resolveTenant.js

@@ -0,0 +1,17 @@
+import { setRequestContextField } from "../../app/context/RequestContext.js";
+import { AUTH_CONTEXT_KEYS } from "./requireAuth.js";
+export function resolveTenant(opts = {}) {
+    const resolve = opts.resolve ??
+        ((c) => {
+            const account = c.get(AUTH_CONTEXT_KEYS.user);
+            return account?.tenantId;
+        });
+    return async (c, next) => {
+        const tenantId = await resolve(c);
+        // No-op (returns false) when called outside an active RequestContext.
+        if (tenantId)
+            setRequestContextField("tenantId", tenantId);
+        return next();
+    };
+}
+//# sourceMappingURL=resolveTenant.js.map

package/lib/http/middleware/resolveTenant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveTenant.js","sourceRoot":"","sources":["../../../src/http/middleware/resolveTenant.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAyCrD,MAAM,UAAU,aAAa,CAAC,OAA6B,EAAE;IAC3D,MAAM,OAAO,GACX,IAAI,CAAC,OAAO;QACZ,CAAC,CAAC,CAAU,EAAE,EAAE;YACd,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAa,CAAsC,CAAC;YAC5F,OAAO,OAAO,EAAE,QAAQ,CAAC;QAC3B,CAAC,CAAC,CAAC;IAEL,OAAO,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QACvB,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;QAClC,sEAAsE;QACtE,IAAI,QAAQ;YAAE,sBAAsB,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;QAC3D,OAAO,IAAI,EAAE,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}

package/lib/http/streaming/sse.d.ts

@@ -0,0 +1,31 @@
+import type { Context } from "hono";
+import type { SSEStreamingApi } from "hono/streaming";
+/**
+ * `streamSSE(c, fn, opts?)` — framework wrapper around `hono/streaming`'s
+ * SSE helper. Adds an OTel span around the streaming callback's lifetime
+ * and a documented home for v4.x SSE-related helpers (LLM streaming, etc.).
+ *
+ * Re-exports `SSEStreamingApi` so consumers don't have to import from two
+ * paths to type their stream callback.
+ *
+ * Usage:
+ * ```ts
+ * import { streamSSE } from "@sixthsummit/ship-api/http/streaming/sse";
+ *
+ * app.get("/feed", requireAuth({ provider }), (c) =>
+ *   streamSSE(c, async (stream) => {
+ *     for await (const event of someEventSource()) {
+ *       if (stream.aborted) break; // honor client disconnect
+ *       await stream.writeSSE({ event: event.type, data: JSON.stringify(event) });
+ *     }
+ *   }, { spanName: "feed.subscribe" }),
+ * );
+ * ```
+ */
+export type { SSEStreamingApi };
+export interface StreamSSEOptions {
+    /** OTel span name. Default `"http.sse"`. */
+    spanName?: string;
+}
+export declare function streamSSE(c: Context, fn: (stream: SSEStreamingApi) => Promise<void>, opts?: StreamSSEOptions): Response;
+//# sourceMappingURL=sse.d.ts.map

package/lib/http/streaming/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../../src/http/streaming/sse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAItD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,SAAS,CACvB,CAAC,EAAE,OAAO,EACV,EAAE,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,EAC9C,IAAI,GAAE,gBAAqB,GAC1B,QAAQ,CAOV"}

package/lib/http/streaming/sse.js

@@ -0,0 +1,11 @@
+import { streamSSE as honoStreamSSE } from "hono/streaming";
+import { withSpan } from "../../observability/tracing.js";
+export function streamSSE(c, fn, opts = {}) {
+    const spanName = opts.spanName ?? "http.sse";
+    return honoStreamSSE(c, async (stream) => {
+        await withSpan(spanName, async () => {
+            await fn(stream);
+        });
+    });
+}
+//# sourceMappingURL=sse.js.map

package/lib/http/streaming/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../../src/http/streaming/sse.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAgC1D,MAAM,UAAU,SAAS,CACvB,CAAU,EACV,EAA8C,EAC9C,OAAyB,EAAE;IAE3B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,UAAU,CAAC;IAC7C,OAAO,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QACvC,MAAM,QAAQ,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;YAClC,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;QACnB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/lib/http/streaming/streamLLM.d.ts

@@ -0,0 +1,94 @@
+import type { Context } from "hono";
+import { logger as defaultLogger } from "../../observability/logger.js";
+/**
+ * `streamLLM(c, events, opts?)` — Hono-aware SSE bridge for LLM stream
+ * events. Pipes any `AsyncIterable<{ type, ... }>` (typically the
+ * `streamComplete()` output of an `LLMProvider` adapter from
+ * `libraries/ai`) through `streamSSE`, with client-disconnect
+ * propagation upstream.
+ *
+ * Event format:
+ *   - `event:` field = the iterator value's `type` field
+ *   - `data:` field = JSON-serialized rest of the value (everything
+ *     except `type`)
+ *
+ * Disconnect handling: when the request client disconnects,
+ * `stream.aborted` flips true. We notice between iterator ticks and
+ * call `iterator.return?.()` so the upstream generator can run its
+ * `finally` (closes provider stream, cancels in-flight HTTP, etc.).
+ *
+ * Errors: if the iterator throws, the error is forwarded as a final
+ * `event: error` SSE event with `{ message }` payload, then the
+ * stream closes. The optional `onError` hook is called *before* the
+ * error event is written so consumers can log / record without
+ * blocking the close.
+ *
+ * Provider-agnostic by design — no import from `libraries/ai`. The
+ * library's `StreamEvent` union (`start` / `text_delta` /
+ * `tool_use_*` / `stop`) is just one valid event source; consumers
+ * with a different shape (custom event taxonomy) can pipe through
+ * unchanged.
+ *
+ * Usage:
+ * ```ts
+ * import { streamLLM } from "@sixthsummit/ship-api/http/streaming/streamLLM";
+ * import { AnthropicAdapter } from "@sixthsummit/ship-api/libraries/ai";
+ *
+ * const llm = new AnthropicAdapter({ apiKey: env.ANTHROPIC_API_KEY });
+ *
+ * app.post("/chat", validate("json", schema), async (c) => {
+ *   const { prompt } = c.req.valid("json");
+ *   const stream = llm.streamComplete({
+ *     model: "claude-opus-4-7",
+ *     messages: [{ role: "user", content: prompt }],
+ *   });
+ *   return streamLLM(c, stream, { spanName: "chat.stream" });
+ * });
+ * ```
+ */
+export interface StreamLLMOptions {
+    /** OTel span name. Default `"llm.stream"`. */
+    spanName?: string;
+    /**
+     * Called once if the upstream iterator throws, before the final
+     * `event: error` SSE write. Use to log / record the failure;
+     * throwing here is swallowed so the close still completes.
+     */
+    onError?: (err: Error) => Promise<void> | void;
+    /**
+     * Override how the SSE event id field is generated. Defaults to a
+     * monotonically-incrementing counter — sufficient for replay scope
+     * within a single response.
+     */
+    generateEventId?: (event: LLMStreamEvent, index: number) => string;
+    /**
+     * Maximum serialized bytes per event payload (F15). Events whose
+     * `JSON.stringify(payload)` exceeds this are skipped + logged +
+     * counted on the `stream.event.dropped_oversized` OTel counter.
+     * Default 256 KB. A misbehaving upstream provider that emits
+     * multi-megabyte single events (e.g. a duplicated tool-call
+     * argument) would otherwise amplify into a bandwidth + client-
+     * memory DoS at the consumer.
+     */
+    maxEventBytes?: number;
+    /**
+     * Tag attached to the `dropped_oversized` counter and the warn
+     * line emitted on oversize. Useful for distinguishing "Anthropic
+     * stream went wild" from "OpenAI stream went wild" in dashboards.
+     * Defaults to the event's `type` field at log time.
+     */
+    provider?: string;
+    /** Override the framework default pino logger (tests). */
+    logger?: typeof defaultLogger;
+}
+/**
+ * Minimum shape `streamLLM` requires. Any object with a string `type`
+ * and arbitrary other JSON-serializable fields fits — including the
+ * full `StreamEvent` union from `libraries/ai`.
+ */
+export interface LLMStreamEvent {
+    type: string;
+    [key: string]: unknown;
+}
+export declare function streamLLM(c: Context, events: AsyncIterable<LLMStreamEvent>, opts?: StreamLLMOptions): Response;
+//# sourceMappingURL=streamLLM.d.ts.map

package/lib/http/streaming/streamLLM.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamLLM.d.ts","sourceRoot":"","sources":["../../../src/http/streaming/streamLLM.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,EAAE,MAAM,IAAI,aAAa,EAAE,MAAM,+BAA+B,CAAC;AA8BxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC/C;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACnE;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,OAAO,aAAa,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,wBAAgB,SAAS,CACvB,CAAC,EAAE,OAAO,EACV,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,EACrC,IAAI,GAAE,gBAAqB,GAC1B,QAAQ,CAoDV"}