@avijs/security 0.0.0-stage → 0.1.1

package/LICENSE

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

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @avijs/security
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+CORS and security headers for Avi.js, as `onRequest` hooks.
+
+```sh
+npm install @avijs/security
+```
+
+```ts
+import { createAvi } from '@avijs/core';
+import { cors, securityHeaders } from '@avijs/security';
+
+const app = createAvi({
+  onRequest: [securityHeaders(), cors({ origin: 'https://app.example.com' })],
+});
+```
+
+Part of [Avi.js](https://github.com/chrischase011/avi-js), a TypeScript framework for Node.js with
+modules, controllers and dependency injection, without `reflect-metadata`. See the
+[security chapter](https://github.com/chrischase011/avi-js/blob/main/docs/tutorial/12-security.md)
+of the tutorial.
+
+Requires Node.js 22.12 or newer. MIT licensed.

package/dist/cors.d.ts

@@ -0,0 +1,22 @@
+import { type RequestHook } from '@avijs/http';
+export type CorsOrigin = string | readonly string[] | RegExp | ((origin: string) => boolean);
+export interface CorsOptions {
+    /**
+     * Origins allowed to call the API: `'*'` for any, an origin like `'https://app.example.com'`,
+     * a list, a RegExp or a function.
+     */
+    origin: CorsOrigin;
+    /** Methods allowed in preflights. Default: GET, HEAD, PUT, PATCH, POST, DELETE. */
+    methods?: readonly string[];
+    /** Request headers allowed in preflights. Default: the headers the browser asks for. */
+    allowedHeaders?: readonly string[];
+    /** Response headers the browser may read. */
+    exposedHeaders?: readonly string[];
+    /** Allow cookies and `Authorization`. Requires explicit origins. */
+    credentials?: boolean;
+    /** How long browsers may cache a preflight, in seconds. */
+    maxAge?: number;
+}
+/** CORS as an `onRequest` hook: answers preflights and adds headers to allowed origins. */
+export declare function cors(options: CorsOptions): RequestHook;
+//# sourceMappingURL=cors.d.ts.map

package/dist/cors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../src/cors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAGtD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC;AAE7F,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,MAAM,EAAE,UAAU,CAAC;IACnB,mFAAmF;IACnF,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,wFAAwF;IACxF,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,6CAA6C;IAC7C,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,oEAAoE;IACpE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD,2FAA2F;AAC3F,wBAAgB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW,CA6CtD"}

package/dist/cors.js

@@ -0,0 +1,93 @@
+import { reply } from '@avijs/http';
+const DEFAULT_METHODS = ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE'];
+const VISIBLE_ASCII = /^[!-~]+$/;
+const TOKEN_LIST = /^[\w!#$%&'*+.^`|~-]+(?:[ \t]*,[ \t]*[\w!#$%&'*+.^`|~-]+)*$/;
+/** CORS as an `onRequest` hook: answers preflights and adds headers to allowed origins. */
+export function cors(options) {
+    const any = options.origin === '*';
+    const allows = originMatcher(options.origin);
+    const credentials = options.credentials === true;
+    if (any && credentials) {
+        throw new TypeError("cors: credentials cannot be used with origin '*'; list the origins");
+    }
+    const methods = (options.methods ?? DEFAULT_METHODS).join(', ');
+    const allowedHeaders = options.allowedHeaders?.join(', ');
+    const exposed = options.exposedHeaders?.length ? options.exposedHeaders.join(', ') : undefined;
+    const maxAge = options.maxAge === undefined ? undefined : seconds(options.maxAge);
+    return (ctx) => {
+        if (!any)
+            ctx.setHeader('vary', 'Origin');
+        const origin = ctx.headers.origin;
+        if (origin === undefined || !VISIBLE_ASCII.test(origin) || !allows(origin))
+            return undefined;
+        const allowOrigin = any ? '*' : origin;
+        const requestMethod = ctx.headers['access-control-request-method'];
+        if (ctx.method === 'OPTIONS' && requestMethod !== undefined) {
+            const headers = {
+                'access-control-allow-origin': allowOrigin,
+                'access-control-allow-methods': methods,
+            };
+            if (credentials)
+                headers['access-control-allow-credentials'] = 'true';
+            if (maxAge !== undefined)
+                headers['access-control-max-age'] = maxAge;
+            if (allowedHeaders !== undefined) {
+                headers['access-control-allow-headers'] = allowedHeaders;
+            }
+            else {
+                headers.vary = any
+                    ? 'Access-Control-Request-Headers'
+                    : 'Origin, Access-Control-Request-Headers';
+                const requested = ctx.headers['access-control-request-headers'];
+                if (requested !== undefined && TOKEN_LIST.test(requested)) {
+                    headers['access-control-allow-headers'] = requested;
+                }
+            }
+            return reply(undefined, { status: 204, headers });
+        }
+        ctx.setHeader('access-control-allow-origin', allowOrigin);
+        if (credentials)
+            ctx.setHeader('access-control-allow-credentials', 'true');
+        if (exposed !== undefined)
+            ctx.setHeader('access-control-expose-headers', exposed);
+        return undefined;
+    };
+}
+function originMatcher(origin) {
+    if (origin === '*')
+        return () => true;
+    if (typeof origin === 'function')
+        return origin;
+    if (origin instanceof RegExp) {
+        return (value) => {
+            origin.lastIndex = 0;
+            return origin.test(value);
+        };
+    }
+    const list = typeof origin === 'string' ? [origin] : origin;
+    if (!Array.isArray(list) || list.length === 0) {
+        throw new TypeError('cors: origin must be set');
+    }
+    const allowed = new Set(list.map(checkOrigin));
+    return (value) => allowed.has(value);
+}
+function checkOrigin(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (parsed?.origin !== value) {
+        throw new TypeError(`cors: '${value}' is not an origin. Use scheme, host and optional port, like 'https://example.com'`);
+    }
+    return value;
+}
+function seconds(value) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new RangeError(`cors: maxAge must be a non-negative integer, got ${String(value)}`);
+    }
+    return String(value);
+}
+//# sourceMappingURL=cors.js.map

package/dist/cors.js.map

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

package/dist/headers.d.ts

@@ -0,0 +1,19 @@
+import type { RequestHook } from '@avijs/http';
+export interface SecurityHeadersOptions {
+    /** Default: `default-src 'none'; frame-ancestors 'none'`, for JSON APIs. Relax it to serve HTML. */
+    contentSecurityPolicy?: string | false;
+    /** Default: `max-age=31536000; includeSubDomains`. Browsers only honor it over HTTPS. */
+    strictTransportSecurity?: string | false;
+    /** Default: `DENY`. */
+    frameOptions?: 'DENY' | 'SAMEORIGIN' | false;
+    /** Default: `no-referrer`. */
+    referrerPolicy?: string | false;
+    /** Default: `same-origin`. Use `cross-origin` for public assets embedded elsewhere. */
+    crossOriginResourcePolicy?: 'same-origin' | 'same-site' | 'cross-origin' | false;
+}
+/**
+ * Common security headers as an `onRequest` hook. Pass `false` to leave one out. Headers set by
+ * a handler with `reply()` win. `X-Content-Type-Options: nosniff` is always sent by Avi.js.
+ */
+export declare function securityHeaders(options?: SecurityHeadersOptions): RequestHook;
+//# sourceMappingURL=headers.d.ts.map

package/dist/headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../src/headers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C,MAAM,WAAW,sBAAsB;IACrC,oGAAoG;IACpG,qBAAqB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACvC,yFAAyF;IACzF,uBAAuB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACzC,uBAAuB;IACvB,YAAY,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,KAAK,CAAC;IAC7C,8BAA8B;IAC9B,cAAc,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAChC,uFAAuF;IACvF,yBAAyB,CAAC,EAAE,aAAa,GAAG,WAAW,GAAG,cAAc,GAAG,KAAK,CAAC;CAClF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,WAAW,CA2BjF"}

package/dist/headers.js

@@ -0,0 +1,26 @@
+import { validateHeaderValue } from 'node:http';
+/**
+ * Common security headers as an `onRequest` hook. Pass `false` to leave one out. Headers set by
+ * a handler with `reply()` win. `X-Content-Type-Options: nosniff` is always sent by Avi.js.
+ */
+export function securityHeaders(options = {}) {
+    const entries = [];
+    const add = (name, value, fallback) => {
+        if (value === false)
+            return;
+        const resolved = value ?? fallback;
+        validateHeaderValue(name, resolved);
+        entries.push([name, resolved]);
+    };
+    add('content-security-policy', options.contentSecurityPolicy, "default-src 'none'; frame-ancestors 'none'");
+    add('strict-transport-security', options.strictTransportSecurity, 'max-age=31536000; includeSubDomains');
+    add('x-frame-options', options.frameOptions, 'DENY');
+    add('referrer-policy', options.referrerPolicy, 'no-referrer');
+    add('cross-origin-resource-policy', options.crossOriginResourcePolicy, 'same-origin');
+    return (ctx) => {
+        for (const [name, value] of entries)
+            ctx.setHeader(name, value);
+        return undefined;
+    };
+}
+//# sourceMappingURL=headers.js.map

package/dist/headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.js","sourceRoot":"","sources":["../src/headers.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAehD;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkC,EAAE;IAClE,MAAM,OAAO,GAAuB,EAAE,CAAC;IACvC,MAAM,GAAG,GAAG,CAAC,IAAY,EAAE,KAAiC,EAAE,QAAgB,EAAE,EAAE;QAChF,IAAI,KAAK,KAAK,KAAK;YAAE,OAAO;QAC5B,MAAM,QAAQ,GAAG,KAAK,IAAI,QAAQ,CAAC;QACnC,mBAAmB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACpC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IACjC,CAAC,CAAC;IAEF,GAAG,CACD,yBAAyB,EACzB,OAAO,CAAC,qBAAqB,EAC7B,4CAA4C,CAC7C,CAAC;IACF,GAAG,CACD,2BAA2B,EAC3B,OAAO,CAAC,uBAAuB,EAC/B,qCAAqC,CACtC,CAAC;IACF,GAAG,CAAC,iBAAiB,EAAE,OAAO,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACrD,GAAG,CAAC,iBAAiB,EAAE,OAAO,CAAC,cAAc,EAAE,aAAa,CAAC,CAAC;IAC9D,GAAG,CAAC,8BAA8B,EAAE,OAAO,CAAC,yBAAyB,EAAE,aAAa,CAAC,CAAC;IAEtF,OAAO,CAAC,GAAG,EAAE,EAAE;QACb,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,OAAO;YAAE,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAChE,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { cors } from './cors.js';
+export type { CorsOptions, CorsOrigin } from './cors.js';
+export { securityHeaders } from './headers.js';
+export type { SecurityHeadersOptions } from './headers.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { cors } from './cors.js';
+export { securityHeaders } from './headers.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@avijs/security",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "CORS and security headers for Avi.js.",
+  "keywords": [
+    "avi",
+    "avi.js",
+    "cors",
+    "security",
+    "headers"
+  ],
+  "license": "MIT",
+  "author": "Christopher Robin Chase",
+  "homepage": "https://github.com/chrischase011/avi-js#readme",
+  "bugs": {
+    "url": "https://github.com/chrischase011/avi-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chrischase011/avi-js.git",
+    "directory": "packages/security"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.12"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "@avijs/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@avijs/http": "0.1.1"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }

package/src/cors.ts

@@ -0,0 +1,113 @@
+import { reply, type RequestHook } from '@avijs/http';
+import type { OutgoingHttpHeaders } from 'node:http';
+
+export type CorsOrigin = string | readonly string[] | RegExp | ((origin: string) => boolean);
+
+export interface CorsOptions {
+  /**
+   * Origins allowed to call the API: `'*'` for any, an origin like `'https://app.example.com'`,
+   * a list, a RegExp or a function.
+   */
+  origin: CorsOrigin;
+  /** Methods allowed in preflights. Default: GET, HEAD, PUT, PATCH, POST, DELETE. */
+  methods?: readonly string[];
+  /** Request headers allowed in preflights. Default: the headers the browser asks for. */
+  allowedHeaders?: readonly string[];
+  /** Response headers the browser may read. */
+  exposedHeaders?: readonly string[];
+  /** Allow cookies and `Authorization`. Requires explicit origins. */
+  credentials?: boolean;
+  /** How long browsers may cache a preflight, in seconds. */
+  maxAge?: number;
+}
+
+const DEFAULT_METHODS = ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE'];
+const VISIBLE_ASCII = /^[!-~]+$/;
+const TOKEN_LIST = /^[\w!#$%&'*+.^`|~-]+(?:[ \t]*,[ \t]*[\w!#$%&'*+.^`|~-]+)*$/;
+
+/** CORS as an `onRequest` hook: answers preflights and adds headers to allowed origins. */
+export function cors(options: CorsOptions): RequestHook {
+  const any = options.origin === '*';
+  const allows = originMatcher(options.origin);
+  const credentials = options.credentials === true;
+  if (any && credentials) {
+    throw new TypeError("cors: credentials cannot be used with origin '*'; list the origins");
+  }
+  const methods = (options.methods ?? DEFAULT_METHODS).join(', ');
+  const allowedHeaders = options.allowedHeaders?.join(', ');
+  const exposed = options.exposedHeaders?.length ? options.exposedHeaders.join(', ') : undefined;
+  const maxAge = options.maxAge === undefined ? undefined : seconds(options.maxAge);
+
+  return (ctx) => {
+    if (!any) ctx.setHeader('vary', 'Origin');
+    const origin = ctx.headers.origin;
+    if (origin === undefined || !VISIBLE_ASCII.test(origin) || !allows(origin)) return undefined;
+
+    const allowOrigin = any ? '*' : origin;
+    const requestMethod = ctx.headers['access-control-request-method'];
+    if (ctx.method === 'OPTIONS' && requestMethod !== undefined) {
+      const headers: OutgoingHttpHeaders = {
+        'access-control-allow-origin': allowOrigin,
+        'access-control-allow-methods': methods,
+      };
+      if (credentials) headers['access-control-allow-credentials'] = 'true';
+      if (maxAge !== undefined) headers['access-control-max-age'] = maxAge;
+      if (allowedHeaders !== undefined) {
+        headers['access-control-allow-headers'] = allowedHeaders;
+      } else {
+        headers.vary = any
+          ? 'Access-Control-Request-Headers'
+          : 'Origin, Access-Control-Request-Headers';
+        const requested = ctx.headers['access-control-request-headers'];
+        if (requested !== undefined && TOKEN_LIST.test(requested)) {
+          headers['access-control-allow-headers'] = requested;
+        }
+      }
+      return reply(undefined, { status: 204, headers });
+    }
+
+    ctx.setHeader('access-control-allow-origin', allowOrigin);
+    if (credentials) ctx.setHeader('access-control-allow-credentials', 'true');
+    if (exposed !== undefined) ctx.setHeader('access-control-expose-headers', exposed);
+    return undefined;
+  };
+}
+
+function originMatcher(origin: CorsOrigin): (value: string) => boolean {
+  if (origin === '*') return () => true;
+  if (typeof origin === 'function') return origin;
+  if (origin instanceof RegExp) {
+    return (value) => {
+      origin.lastIndex = 0;
+      return origin.test(value);
+    };
+  }
+  const list = typeof origin === 'string' ? [origin] : origin;
+  if (!Array.isArray(list) || list.length === 0) {
+    throw new TypeError('cors: origin must be set');
+  }
+  const allowed = new Set(list.map(checkOrigin));
+  return (value) => allowed.has(value);
+}
+
+function checkOrigin(value: string): string {
+  let parsed: URL | undefined;
+  try {
+    parsed = new URL(value);
+  } catch {
+    parsed = undefined;
+  }
+  if (parsed?.origin !== value) {
+    throw new TypeError(
+      `cors: '${value}' is not an origin. Use scheme, host and optional port, like 'https://example.com'`,
+    );
+  }
+  return value;
+}
+
+function seconds(value: number): string {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new RangeError(`cors: maxAge must be a non-negative integer, got ${String(value)}`);
+  }
+  return String(value);
+}

package/src/headers.ts

@@ -0,0 +1,48 @@
+import type { RequestHook } from '@avijs/http';
+import { validateHeaderValue } from 'node:http';
+
+export interface SecurityHeadersOptions {
+  /** Default: `default-src 'none'; frame-ancestors 'none'`, for JSON APIs. Relax it to serve HTML. */
+  contentSecurityPolicy?: string | false;
+  /** Default: `max-age=31536000; includeSubDomains`. Browsers only honor it over HTTPS. */
+  strictTransportSecurity?: string | false;
+  /** Default: `DENY`. */
+  frameOptions?: 'DENY' | 'SAMEORIGIN' | false;
+  /** Default: `no-referrer`. */
+  referrerPolicy?: string | false;
+  /** Default: `same-origin`. Use `cross-origin` for public assets embedded elsewhere. */
+  crossOriginResourcePolicy?: 'same-origin' | 'same-site' | 'cross-origin' | false;
+}
+
+/**
+ * Common security headers as an `onRequest` hook. Pass `false` to leave one out. Headers set by
+ * a handler with `reply()` win. `X-Content-Type-Options: nosniff` is always sent by Avi.js.
+ */
+export function securityHeaders(options: SecurityHeadersOptions = {}): RequestHook {
+  const entries: [string, string][] = [];
+  const add = (name: string, value: string | false | undefined, fallback: string) => {
+    if (value === false) return;
+    const resolved = value ?? fallback;
+    validateHeaderValue(name, resolved);
+    entries.push([name, resolved]);
+  };
+
+  add(
+    'content-security-policy',
+    options.contentSecurityPolicy,
+    "default-src 'none'; frame-ancestors 'none'",
+  );
+  add(
+    'strict-transport-security',
+    options.strictTransportSecurity,
+    'max-age=31536000; includeSubDomains',
+  );
+  add('x-frame-options', options.frameOptions, 'DENY');
+  add('referrer-policy', options.referrerPolicy, 'no-referrer');
+  add('cross-origin-resource-policy', options.crossOriginResourcePolicy, 'same-origin');
+
+  return (ctx) => {
+    for (const [name, value] of entries) ctx.setHeader(name, value);
+    return undefined;
+  };
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { cors } from './cors.js';
+export type { CorsOptions, CorsOrigin } from './cors.js';
+export { securityHeaders } from './headers.js';
+export type { SecurityHeadersOptions } from './headers.js';