@shaferllc/keel 0.58.0 → 0.66.0

package/dist/core/index.js

@@ -2,7 +2,7 @@
 export { Container } from "./container.js";
 export { Application } from "./application.js";
 export { Config, env } from "./config.js";
-export { app, config, view, bind, singleton, instance, make, bound, events, emit, listen, cache, logger, onReady, onShutdown, terminate, } from "./helpers.js";
+export { app, config, view, bind, singleton, instance, make, bound, alias, swap, restore, events, emit, listen, cache, logger, onReady, onShutdown, terminate, } from "./helpers.js";
 export { Logger } from "./logger.js";
 export { requestLogger, requestLog } from "./request-logger.js";
 export { Events } from "./events.js";
@@ -10,9 +10,12 @@ export { Cache, MemoryStore } from "./cache.js";
 export { serveStatic } from "./static.js";
 export { Storage, MemoryDisk, storage, setDisk } from "./storage.js";
 export { dump, dd } from "./debug.js";
-export { hash, encryption } from "./crypto.js";
+export { hash, encryption, jwt } from "./crypto.js";
 export { rateLimiter } from "./rate-limit.js";
-export { db, setConnection, QueryBuilder } from "./database.js";
+export { cors } from "./cors.js";
+export { securityHeaders } from "./shield.js";
+export { csrf, csrfToken, csrfField } from "./csrf.js";
+export { db, connection, setConnection, addConnection, setDefaultConnection, connectionNames, clearConnections, QueryBuilder, } from "./database.js";
 export { Model } from "./model.js";
 export { Relation, HasOne, HasMany, BelongsTo, BelongsToMany } from "./relations.js";
 export { Faker, Factory as ModelFactory, factory, Seeder, seed } from "./factory.js";
@@ -35,8 +38,10 @@ export { TestClient, TestResponse, testClient } from "./testing.js";
 export { HttpException, BadRequestException, UnauthorizedException, PaymentRequiredException, ForbiddenException, NotFoundException, MethodNotAllowedException, NotAcceptableException, RequestTimeoutException, ConflictException, LengthRequiredException, ValidationException, TooManyRequestsException, ServerErrorException, NotImplementedException, BadGatewayException, ServiceUnavailableException, createError, STATUS_TEXT, } from "./exceptions.js";
 export { validate, validateRequest, validated } from "./validation.js";
 export { Session, session, sessionMiddleware } from "./session.js";
-export { Auth, auth, authGuard, setUserProvider } from "./auth.js";
-export { define, policy, gateBefore, setUserResolver, clearAuthorization, can, cannot, canFor, authorize, authorizeFor, } from "./authorization.js";
+export { Auth, auth, authGuard, bearerAuth, basicAuth, tokenAuth, token, tokenCan, setUserProvider } from "./auth.js";
+export { createToken, verifyToken, revokeToken, revokeTokens, listTokens, tokenAllows, tokenDenies, setTokensTable, } from "./tokens.js";
+export { social, github, google, discord, oauthDriver, oauthState, OAuthDriver, OAuthError, twitter, oauth1Driver, oauth1Signature, OAuth1Driver, } from "./social.js";
+export { define, policy, gateBefore, gateAfter, setUserResolver, clearAuthorization, can, cannot, canFor, authorize, authorizeFor, } from "./authorization.js";
 export { Transformer } from "./transformer.js";
 export { Broker, Service, LocalTransporter, ServiceNotFoundError, RequestTimeoutError, broker, setBroker, } from "./broker.js";
 export { Vite, viteTags, viteAsset, viteReactRefresh } from "./vite.js";

package/dist/core/model.d.ts

@@ -22,6 +22,8 @@ type ModelClass<T extends Model> = (new (attributes?: Row) => T) & typeof Model;
 export declare class Model {
     static table: string;
     static primaryKey: string;
+    /** Which registered connection this model uses; the default when unset. */
+    static connection: string | undefined;
     /** Columns mass-assignable via `create`/`fill` (allowlist). */
     static fillable: string[];
     /** Columns NOT mass-assignable (denylist). Ignored when `fillable` is set. */

package/dist/core/model.js

@@ -34,6 +34,8 @@ function serialize(value) {
 export class Model {
     static table = "";
     static primaryKey = "id";
+    /** Which registered connection this model uses; the default when unset. */
+    static connection = undefined;
     /** Columns mass-assignable via `create`/`fill` (allowlist). */
     static fillable = [];
     /** Columns NOT mass-assignable (denylist). Ignored when `fillable` is set. */
@@ -51,7 +53,7 @@ export class Model {
     /* ------------------------------ static -------------------------------- */
     /** A raw query builder scoped to this model's table. */
     static query() {
-        return db(this.table);
+        return db(this.table, this.connection);
     }
     /** Keep only the attributes mass-assignment allows (fillable / guarded). */
     static filterFillable(attributes) {
@@ -86,11 +88,11 @@ export class Model {
         return out;
     }
     static async all() {
-        const rows = await db(this.table).get();
+        const rows = await db(this.table, this.connection).get();
         return rows.map((row) => new this(row));
     }
     static async find(id) {
-        const row = await db(this.table).where(this.primaryKey, id).first();
+        const row = await db(this.table, this.connection).where(this.primaryKey, id).first();
         return row ? new this(row) : null;
     }
     static async findOrFail(id) {
@@ -100,18 +102,18 @@ export class Model {
         return model;
     }
     static async first() {
-        const row = await db(this.table).first();
+        const row = await db(this.table, this.connection).first();
         return row ? new this(row) : null;
     }
     /** Fetch models matching a simple equality condition. */
     static async where(column, value) {
-        const rows = await db(this.table).where(column, value).get();
+        const rows = await db(this.table, this.connection).where(column, value).get();
         return rows.map((row) => new this(row));
     }
     static async create(attributes) {
         const filtered = this.filterFillable(attributes);
         const write = this.stampTimestamps(this.toDatabase(filtered), true);
-        const id = await db(this.table).insertGetId(write);
+        const id = await db(this.table, this.connection).insertGetId(write);
         const model = new this(filtered);
         if (this.timestamps) {
             model[this.createdAtColumn] = write[this.createdAtColumn];
@@ -123,7 +125,7 @@ export class Model {
     }
     /** A page of models plus pagination metadata. */
     static async paginate(page = 1, perPage = 15) {
-        const result = await db(this.table).paginate(page, perPage);
+        const result = await db(this.table, this.connection).paginate(page, perPage);
         return { ...result, data: result.data.map((row) => new this(row)) };
     }
     /** Find the first row matching `match`, or create one from `{ ...match, ...values }`. */
@@ -145,7 +147,7 @@ export class Model {
     }
     /** A query scoped to every column/value in `match`. */
     static matching(match) {
-        let q = db(this.table);
+        let q = db(this.table, this.connection);
         for (const [column, value] of Object.entries(match))
             q = q.where(column, value);
         return q;
@@ -209,7 +211,7 @@ export class Model {
     /** Insert (no primary key) or update (has one). */
     async save() {
         const ctor = this.ctor();
-        const { table, primaryKey } = ctor;
+        const { table, primaryKey, connection } = ctor;
         const idValue = this[primaryKey];
         const forInsert = idValue == null;
         const data = ctor.stampTimestamps(ctor.toDatabase({ ...this }), forInsert);
@@ -221,10 +223,10 @@ export class Model {
         }
         delete data[primaryKey];
         if (!forInsert) {
-            await db(table).where(primaryKey, idValue).update(data);
+            await db(table, connection).where(primaryKey, idValue).update(data);
         }
         else {
-            const id = await db(table).insertGetId(data);
+            const id = await db(table, connection).insertGetId(data);
             if (id != null)
                 this[primaryKey] = id;
         }
@@ -237,14 +239,14 @@ export class Model {
     /** Reload this model's columns from the database. */
     async refresh() {
         const ctor = this.ctor();
-        const row = await db(ctor.table).where(ctor.primaryKey, this[ctor.primaryKey]).first();
+        const row = await db(ctor.table, ctor.connection).where(ctor.primaryKey, this[ctor.primaryKey]).first();
         if (row)
             Object.assign(this, applyCasts(row, ctor.casts, castGet));
         return this;
     }
     async delete() {
-        const { table, primaryKey } = this.ctor();
-        await db(table).where(primaryKey, this[primaryKey]).delete();
+        const { table, primaryKey, connection } = this.ctor();
+        await db(table, connection).where(primaryKey, this[primaryKey]).delete();
     }
     /** Merge mass-assignable attributes into the model (cast, not saved). */
     fill(attributes) {

package/dist/core/provider.d.ts

@@ -6,6 +6,11 @@
  *             here — nothing is guaranteed to be registered yet.
  * boot():     called after every provider has registered. Safe to resolve
  *             and wire things together here.
+ * ready():    called once the whole app has booted (after every provider's
+ *             boot() and any onReady hooks). For work that needs a fully-live
+ *             app — attaching to the running server, warming a cache.
+ * shutdown(): called during graceful termination, in reverse registration
+ *             order (LIFO). Close connections, flush queues, cancel timers.
  *
  * Register with options to make a provider reusable:
  *
@@ -21,5 +26,7 @@ export declare abstract class ServiceProvider<O = Record<string, unknown>> {
     constructor(app: Application, options?: O);
     register(): void | Promise<void>;
     boot(): void | Promise<void>;
+    ready(): void | Promise<void>;
+    shutdown(): void | Promise<void>;
 }
 export type ProviderClass = new (app: Application, options?: any) => ServiceProvider;

package/dist/core/provider.js

@@ -6,6 +6,11 @@
  *             here — nothing is guaranteed to be registered yet.
  * boot():     called after every provider has registered. Safe to resolve
  *             and wire things together here.
+ * ready():    called once the whole app has booted (after every provider's
+ *             boot() and any onReady hooks). For work that needs a fully-live
+ *             app — attaching to the running server, warming a cache.
+ * shutdown(): called during graceful termination, in reverse registration
+ *             order (LIFO). Close connections, flush queues, cancel timers.
  *
  * Register with options to make a provider reusable:
  *
@@ -23,4 +28,6 @@ export class ServiceProvider {
     }
     register() { }
     boot() { }
+    ready() { }
+    shutdown() { }
 }

package/dist/core/rate-limit.js

@@ -35,10 +35,12 @@ export function rateLimiter(options = {}) {
         }
         bucket.count++;
         const remaining = Math.max(0, max - bucket.count);
+        const resetSeconds = Math.ceil(bucket.reset / 1000);
         if (bucket.count > max) {
             return c.json({ error: options.message ?? "Too Many Requests", status: 429 }, 429, {
                 "X-RateLimit-Limit": String(max),
                 "X-RateLimit-Remaining": "0",
+                "X-RateLimit-Reset": String(resetSeconds),
                 "Retry-After": String(Math.ceil((bucket.reset - now) / 1000)),
             });
         }
@@ -46,5 +48,6 @@ export function rateLimiter(options = {}) {
         // Set headers on the final response (survives any handler type).
         c.header("X-RateLimit-Limit", String(max));
         c.header("X-RateLimit-Remaining", String(remaining));
+        c.header("X-RateLimit-Reset", String(resetSeconds));
     };
 }

package/dist/core/relations.js

@@ -56,7 +56,7 @@ export class HasMany extends Relation {
         return this.parent[this.localKey];
     }
     query() {
-        return db(this.related.table).where(this.foreignKey, this.localValue());
+        return db(this.related.table, this.related.connection).where(this.foreignKey, this.localValue());
     }
     async get() {
         return this.hydrate(await this.query().get());
@@ -64,7 +64,7 @@ export class HasMany extends Relation {
     async eager(models, name) {
         const keys = unique(models.map((m) => m[this.localKey]).filter((v) => v != null));
         const rows = keys.length
-            ? await db(this.related.table).whereIn(this.foreignKey, keys).get()
+            ? await db(this.related.table, this.related.connection).whereIn(this.foreignKey, keys).get()
             : [];
         const grouped = new Map();
         for (const row of rows) {
@@ -90,7 +90,7 @@ export class HasOne extends Relation {
         return this.parent[this.localKey];
     }
     query() {
-        return db(this.related.table).where(this.foreignKey, this.localValue());
+        return db(this.related.table, this.related.connection).where(this.foreignKey, this.localValue());
     }
     async get() {
         const row = await this.query().first();
@@ -99,7 +99,7 @@ export class HasOne extends Relation {
     async eager(models, name) {
         const keys = unique(models.map((m) => m[this.localKey]).filter((v) => v != null));
         const rows = keys.length
-            ? await db(this.related.table).whereIn(this.foreignKey, keys).get()
+            ? await db(this.related.table, this.related.connection).whereIn(this.foreignKey, keys).get()
             : [];
         const byKey = new Map();
         for (const row of rows) {
@@ -124,7 +124,7 @@ export class BelongsTo extends Relation {
         return this.parent[this.foreignKey];
     }
     query() {
-        return db(this.related.table).where(this.ownerKey, this.foreignValue());
+        return db(this.related.table, this.related.connection).where(this.ownerKey, this.foreignValue());
     }
     async get() {
         if (this.foreignValue() == null)
@@ -135,7 +135,7 @@ export class BelongsTo extends Relation {
     async eager(models, name) {
         const keys = unique(models.map((m) => m[this.foreignKey]).filter((v) => v != null));
         const rows = keys.length
-            ? await db(this.related.table).whereIn(this.ownerKey, keys).get()
+            ? await db(this.related.table, this.related.connection).whereIn(this.ownerKey, keys).get()
             : [];
         const byKey = new Map();
         for (const row of rows)
@@ -165,18 +165,18 @@ export class BelongsToMany extends Relation {
     }
     /** The query against the related table, once pivot rows are known. */
     query() {
-        return db(this.related.table);
+        return db(this.related.table, this.related.connection);
     }
     async get() {
         if (this.parentValue() == null)
             return [];
-        const pivots = await db(this.pivotTable)
+        const pivots = await db(this.pivotTable, this.related.connection)
             .where(this.foreignPivotKey, this.parentValue())
             .get();
         const relatedIds = unique(pivots.map((p) => p[this.relatedPivotKey]));
         if (!relatedIds.length)
             return [];
-        const rows = await db(this.related.table).whereIn(this.relatedKey, relatedIds).get();
+        const rows = await db(this.related.table, this.related.connection).whereIn(this.relatedKey, relatedIds).get();
         return this.hydrate(rows);
     }
     async eager(models, name) {
@@ -186,10 +186,10 @@ export class BelongsToMany extends Relation {
                 m.setRelation(name, []);
             return;
         }
-        const pivots = await db(this.pivotTable).whereIn(this.foreignPivotKey, parentIds).get();
+        const pivots = await db(this.pivotTable, this.related.connection).whereIn(this.foreignPivotKey, parentIds).get();
         const relatedIds = unique(pivots.map((p) => p[this.relatedPivotKey]));
         const rows = relatedIds.length
-            ? await db(this.related.table).whereIn(this.relatedKey, relatedIds).get()
+            ? await db(this.related.table, this.related.connection).whereIn(this.relatedKey, relatedIds).get()
             : [];
         const relatedById = new Map(rows.map((row) => [row[this.relatedKey], row]));
         const grouped = new Map();
@@ -207,7 +207,7 @@ export class BelongsToMany extends Relation {
     }
     /** Attach a related row by linking it through the pivot table. */
     async attach(id, extra = {}) {
-        await db(this.pivotTable).insert({
+        await db(this.pivotTable, this.related.connection).insert({
             [this.foreignPivotKey]: this.parentValue(),
             [this.relatedPivotKey]: id,
             ...extra,
@@ -215,7 +215,7 @@ export class BelongsToMany extends Relation {
     }
     /** Detach one related row (or all, when no id is given). */
     async detach(id) {
-        let q = db(this.pivotTable).where(this.foreignPivotKey, this.parentValue());
+        let q = db(this.pivotTable, this.related.connection).where(this.foreignPivotKey, this.parentValue());
         if (id !== undefined)
             q = q.where(this.relatedPivotKey, id);
         await q.delete();

package/dist/core/request.d.ts

@@ -33,6 +33,8 @@ interface ResponseHelper {
     text(body: string, status?: number): Response;
     html(body: string, status?: number): Response;
     redirect(location: string, status?: number): Response;
+    /** Redirect to the `Referer` header, or `fallback` (default "/") if absent. */
+    back(fallback?: string, status?: number): Response;
     /** Send a value — objects become JSON, everything else becomes text. */
     send(data: unknown, status?: number): Response;
     /** Set the response status (chainable). */
@@ -47,6 +49,8 @@ interface ResponseHelper {
     hasHeader(name: string): boolean;
     /** Set the Content-Type (chainable). */
     type(mime: string): ResponseHelper;
+    /** Mark the response as a downloadable attachment via Content-Disposition (chainable). */
+    attachment(filename?: string): ResponseHelper;
     /** Append a value to a (possibly multi-value) header (chainable). */
     append(name: string, value: string): ResponseHelper;
     /** Remove a response header (chainable). */
@@ -74,6 +78,20 @@ export declare const request: {
     readonly method: string;
     readonly path: string;
     readonly url: string;
+    /** The request protocol — "https" or "http" — honoring X-Forwarded-Proto. */
+    readonly protocol: string;
+    /** Whether the request came in over HTTPS. */
+    readonly secure: boolean;
+    /** The host with port, honoring X-Forwarded-Host (e.g. "example.com:443"). */
+    readonly host: string;
+    /** The host without port (e.g. "example.com"). */
+    readonly hostname: string;
+    /** Scheme + host — "https://example.com" — with no trailing slash. */
+    readonly origin: string;
+    /** The absolute request URL, rebuilt from the (proxy-aware) origin. */
+    readonly fullUrl: string;
+    /** The raw query string without the leading "?" (empty when none). */
+    readonly querystring: string;
     /** The response status (useful after `await next()` in middleware). */
     readonly status: number;
     header(name: string): string | undefined;
@@ -128,6 +146,14 @@ export declare const request: {
     language(languages: string[]): string | null;
     /** Accepted languages, ordered by preference. */
     languages(): string[];
+    /** The best of the offered content encodings per Accept-Encoding, or null. */
+    encoding(encodings: string[]): string | null;
+    /** Accepted content encodings, ordered by preference. */
+    encodings(): string[];
+    /** The best of the offered charsets per Accept-Charset, or null. */
+    charset(charsets: string[]): string | null;
+    /** Accepted charsets, ordered by preference. */
+    charsets(): string[];
     /** A single input (from query or body), with an optional fallback (async). */
     input<T = unknown>(key: string, fallback?: T): Promise<T>;
     /** Only the named inputs (async). */

package/dist/core/request.js

@@ -67,6 +67,20 @@ function negotiate(headerName, offered) {
             return a;
     return null;
 }
+/* ------------------------------ url / host ----------------------------- */
+/* Proxy-aware URL introspection: X-Forwarded-* wins over the raw URL, so an
+ * app behind a TLS-terminating proxy sees the client's protocol and host. */
+/** The first value of a (possibly comma-listed) header. */
+function firstForwarded(name) {
+    const v = ctx().req.header(name);
+    return v ? v.split(",")[0].trim() : undefined;
+}
+function requestProtocol() {
+    return firstForwarded("x-forwarded-proto") ?? new URL(ctx().req.url).protocol.replace(/:$/, "");
+}
+function requestHost() {
+    return firstForwarded("x-forwarded-host") ?? ctx().req.header("host") ?? new URL(ctx().req.url).host;
+}
 /* ------------------------------ responses ------------------------------ */
 /* These work inside a handler AND standalone (e.g. as a static route value).
  * Inside a request they build on the context (merging any headers); outside a
@@ -98,6 +112,9 @@ export function html(body, status) {
 }
 export function redirect(location, status) {
     const c = maybeCtx();
+    // Koa-style `redirect("back")`: bounce to the Referer, or "/" if there isn't one.
+    if (location === "back")
+        location = c?.req.header("referer") ?? "/";
     return c
         ? c.redirect(location, status)
         : new Response(null, { status: status ?? 302, headers: { location } });
@@ -115,6 +132,9 @@ export const response = {
     redirect(location, status) {
         return redirect(location, status);
     },
+    back(fallback = "/", status) {
+        return redirect(ctx().req.header("referer") ?? fallback, status);
+    },
     send(data, status) {
         return typeof data === "object" && data !== null
             ? json(data, status)
@@ -143,6 +163,18 @@ export const response = {
         ctx().header("content-type", mime);
         return response;
     },
+    attachment(filename) {
+        if (filename === undefined) {
+            ctx().header("content-disposition", "attachment");
+        }
+        else {
+            // Quote the ASCII-safe name; add RFC 5987 filename* for anything else.
+            const ascii = filename.replace(/[^\x20-\x7e]/g, "?").replace(/["\\]/g, "_");
+            const encoded = encodeURIComponent(filename);
+            ctx().header("content-disposition", `attachment; filename="${ascii}"; filename*=UTF-8''${encoded}`);
+        }
+        return response;
+    },
     append(name, value) {
         ctx().header(name, value, { append: true });
         return response;
@@ -189,6 +221,35 @@ export const request = {
     get url() {
         return ctx().req.url;
     },
+    /** The request protocol — "https" or "http" — honoring X-Forwarded-Proto. */
+    get protocol() {
+        return requestProtocol();
+    },
+    /** Whether the request came in over HTTPS. */
+    get secure() {
+        return requestProtocol() === "https";
+    },
+    /** The host with port, honoring X-Forwarded-Host (e.g. "example.com:443"). */
+    get host() {
+        return requestHost();
+    },
+    /** The host without port (e.g. "example.com"). */
+    get hostname() {
+        return requestHost().split(":")[0];
+    },
+    /** Scheme + host — "https://example.com" — with no trailing slash. */
+    get origin() {
+        return `${requestProtocol()}://${requestHost()}`;
+    },
+    /** The absolute request URL, rebuilt from the (proxy-aware) origin. */
+    get fullUrl() {
+        const u = new URL(ctx().req.url);
+        return `${requestProtocol()}://${requestHost()}${u.pathname}${u.search}`;
+    },
+    /** The raw query string without the leading "?" (empty when none). */
+    get querystring() {
+        return new URL(ctx().req.url).search.replace(/^\?/, "");
+    },
     /** The response status (useful after `await next()` in middleware). */
     get status() {
         return ctx().res.status;
@@ -332,6 +393,22 @@ export const request = {
     languages() {
         return parseAccept(ctx().req.header("accept-language"));
     },
+    /** The best of the offered content encodings per Accept-Encoding, or null. */
+    encoding(encodings) {
+        return negotiate("accept-encoding", encodings);
+    },
+    /** Accepted content encodings, ordered by preference. */
+    encodings() {
+        return parseAccept(ctx().req.header("accept-encoding"));
+    },
+    /** The best of the offered charsets per Accept-Charset, or null. */
+    charset(charsets) {
+        return negotiate("accept-charset", charsets);
+    },
+    /** Accepted charsets, ordered by preference. */
+    charsets() {
+        return parseAccept(ctx().req.header("accept-charset"));
+    },
     /** A single input (from query or body), with an optional fallback (async). */
     async input(key, fallback) {
         const all = await this.all();

package/dist/core/shield.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Security headers — the "shield" for server-rendered apps. One middleware that
+ * sets the defensive HTTP headers browsers act on: a Content-Security-Policy,
+ * HSTS, clickjacking and MIME-sniffing guards, and a referrer policy.
+ *
+ *   this.use(securityHeaders());   // sensible defaults
+ *
+ *   this.use(securityHeaders({
+ *     csp: { defaultSrc: ["'self'"], scriptSrc: ["'self'", "https://cdn.example.com"] },
+ *     hsts: { maxAge: 15552000, includeSubDomains: true },
+ *     frameGuard: "DENY",
+ *   }));
+ *
+ * Each header can be turned off with `false`. CSP takes a ready-made string or a
+ * directives object whose camelCase keys become `kebab-case` (`defaultSrc` →
+ * `default-src`). Pair with [`csrf()`](./csrf.ts) for form protection.
+ */
+import type { MiddlewareHandler } from "hono";
+export interface HstsOptions {
+    /** Max-age in seconds. Default 180 days. */
+    maxAge?: number;
+    /** Apply to subdomains too. Default true. */
+    includeSubDomains?: boolean;
+    /** Add `preload` (only if you've submitted to the HSTS preload list). Default false. */
+    preload?: boolean;
+}
+export interface SecurityHeadersOptions {
+    /** Content-Security-Policy — a raw string, a directives object, or `false` to omit. */
+    csp?: string | Record<string, string[]> | false;
+    /** Strict-Transport-Security. `true` for defaults, an object to tune, `false` to omit. Default off unless set. */
+    hsts?: boolean | HstsOptions;
+    /** X-Frame-Options clickjacking guard. Default `"SAMEORIGIN"`; `false` to omit. */
+    frameGuard?: false | "DENY" | "SAMEORIGIN";
+    /** X-Content-Type-Options: nosniff. Default true. */
+    noSniff?: boolean;
+    /** Referrer-Policy. Default `"strict-origin-when-cross-origin"`; `false` to omit. */
+    referrerPolicy?: string | false;
+}
+export declare function securityHeaders(options?: SecurityHeadersOptions): MiddlewareHandler;

package/dist/core/shield.js

@@ -0,0 +1,60 @@
+/**
+ * Security headers — the "shield" for server-rendered apps. One middleware that
+ * sets the defensive HTTP headers browsers act on: a Content-Security-Policy,
+ * HSTS, clickjacking and MIME-sniffing guards, and a referrer policy.
+ *
+ *   this.use(securityHeaders());   // sensible defaults
+ *
+ *   this.use(securityHeaders({
+ *     csp: { defaultSrc: ["'self'"], scriptSrc: ["'self'", "https://cdn.example.com"] },
+ *     hsts: { maxAge: 15552000, includeSubDomains: true },
+ *     frameGuard: "DENY",
+ *   }));
+ *
+ * Each header can be turned off with `false`. CSP takes a ready-made string or a
+ * directives object whose camelCase keys become `kebab-case` (`defaultSrc` →
+ * `default-src`). Pair with [`csrf()`](./csrf.ts) for form protection.
+ */
+/** camelCase directive names → the kebab-case CSP spelling. */
+function buildCsp(directives) {
+    return Object.entries(directives)
+        .map(([key, values]) => {
+        const name = key.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase());
+        return values.length ? `${name} ${values.join(" ")}` : name;
+    })
+        .join("; ");
+}
+export function securityHeaders(options = {}) {
+    const frame = options.frameGuard === undefined ? "SAMEORIGIN" : options.frameGuard;
+    const referrer = options.referrerPolicy === undefined ? "strict-origin-when-cross-origin" : options.referrerPolicy;
+    const noSniff = options.noSniff !== false;
+    // Precompute the static header values once.
+    const csp = options.csp === false || options.csp === undefined
+        ? null
+        : typeof options.csp === "string"
+            ? options.csp
+            : buildCsp(options.csp);
+    let hstsValue = null;
+    if (options.hsts) {
+        const h = options.hsts === true ? {} : options.hsts;
+        const parts = [`max-age=${h.maxAge ?? 15552000}`];
+        if (h.includeSubDomains !== false)
+            parts.push("includeSubDomains");
+        if (h.preload)
+            parts.push("preload");
+        hstsValue = parts.join("; ");
+    }
+    return async (c, next) => {
+        await next();
+        if (csp)
+            c.header("Content-Security-Policy", csp);
+        if (hstsValue)
+            c.header("Strict-Transport-Security", hstsValue);
+        if (frame)
+            c.header("X-Frame-Options", frame);
+        if (noSniff)
+            c.header("X-Content-Type-Options", "nosniff");
+        if (referrer)
+            c.header("Referrer-Policy", referrer);
+    };
+}