@fluixi/api 0.0.0-stage → 0.1.0-alpha.2

package/dist/security.cjs

@@ -0,0 +1,222 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/security.ts
+var security_exports = {};
+__export(security_exports, {
+  DEFAULT_SECURITY_HEADERS: () => DEFAULT_SECURITY_HEADERS,
+  apiSecurity: () => apiSecurity,
+  cors: () => cors,
+  originCheck: () => originCheck,
+  securityHeaders: () => securityHeaders
+});
+module.exports = __toCommonJS(security_exports);
+
+// src/errors.ts
+var ApiError = class extends Error {
+  constructor(status, code, message, details) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+};
+function errorResponse(error) {
+  const body = { error: { code: error.code, message: error.message } };
+  if (error.details !== void 0) body.error.details = error.details;
+  return new Response(JSON.stringify(body), {
+    status: error.status,
+    headers: { "content-type": "application/json; charset=utf-8" }
+  });
+}
+
+// src/middleware.ts
+function withHeaders(response, set) {
+  try {
+    set(response.headers);
+    return response;
+  } catch {
+    const copy = new Response(response.body, response);
+    set(copy.headers);
+    return copy;
+  }
+}
+function appendVary(headers, name) {
+  const vary = headers.get("vary");
+  if (!vary) headers.set("vary", name);
+  else if (!vary.split(",").some((v) => v.trim().toLowerCase() === name.toLowerCase())) headers.set("vary", `${vary}, ${name}`);
+}
+
+// src/rate-limit.ts
+var import_rate_limiter_flexible = require("rate-limiter-flexible");
+function memoryRateLimitStore() {
+  return storeOf(async (limit, windowSeconds) => new import_rate_limiter_flexible.RateLimiterMemory({ points: limit, duration: windowSeconds }));
+}
+function storeOf(make, onHit) {
+  const limiters = /* @__PURE__ */ new Map();
+  return {
+    async hit(key, limit, windowSeconds) {
+      const id = `${limit}/${windowSeconds}`;
+      let pending = limiters.get(id);
+      if (!pending) {
+        limiters.set(id, pending = make(limit, windowSeconds));
+        pending.catch(() => limiters.delete(id));
+      }
+      const limiter = await pending;
+      onHit?.(limiter);
+      try {
+        const res = await limiter.consume(key);
+        return { allowed: true, remaining: res.remainingPoints, resetMs: res.msBeforeNext };
+      } catch (thrown) {
+        if (thrown instanceof import_rate_limiter_flexible.RateLimiterRes) return { allowed: false, remaining: 0, resetMs: thrown.msBeforeNext };
+        throw thrown;
+      }
+    }
+  };
+}
+var ADDRESSES = /* @__PURE__ */ Symbol.for("fluixi.clientAddress");
+var sharedMemory = memoryRateLimitStore();
+var created = 0;
+function clientAddressOf(request) {
+  return globalThis[ADDRESSES]?.get(request);
+}
+function rateLimit(options) {
+  const { match, methods, limit, window, key = clientAddressOf, store = sharedMemory } = options;
+  const applies = matcher(match);
+  const methodSet = methods && new Set(methods.map((m) => m.toUpperCase()));
+  const bucket = options.name ?? `limit${++created}`;
+  return async (request, next) => {
+    if (methodSet && !methodSet.has(request.method)) return next();
+    if (!applies(request)) return next();
+    const who = await key(request);
+    if (!who) return next();
+    const { allowed, remaining, resetMs } = await store.hit(`${bucket}:${who}`, limit, window);
+    const reset = String(Math.ceil(resetMs / 1e3));
+    const set = (headers) => {
+      headers.set("ratelimit-limit", String(limit));
+      headers.set("ratelimit-remaining", String(remaining));
+      headers.set("ratelimit-reset", reset);
+    };
+    if (!allowed) {
+      const refused = errorResponse(new ApiError(429, "rate_limited", "Too many requests. Try again later."));
+      refused.headers.set("retry-after", reset);
+      set(refused.headers);
+      return refused;
+    }
+    return withHeaders(await next(), set);
+  };
+}
+function matcher(match) {
+  if (!match) return () => true;
+  if (typeof match === "function") return match;
+  const exact = new Set(match.filter((p) => !p.endsWith("/*")));
+  const prefixes = match.filter((p) => p.endsWith("/*")).map((p) => p.slice(0, -1));
+  return (request) => {
+    const { pathname } = new URL(request.url);
+    return exact.has(pathname) || prefixes.some((p) => pathname.startsWith(p));
+  };
+}
+
+// src/security.ts
+var allows = (origins, origin) => typeof origins === "function" ? origins(origin) : origins.includes(origin);
+var DEFAULT_SECURITY_HEADERS = {
+  "content-security-policy": "default-src 'none'; frame-ancestors 'none'",
+  "cross-origin-opener-policy": "same-origin",
+  "cross-origin-resource-policy": "same-origin",
+  "referrer-policy": "no-referrer",
+  "strict-transport-security": "max-age=31536000; includeSubDomains",
+  "x-content-type-options": "nosniff",
+  "x-frame-options": "DENY",
+  "x-permitted-cross-domain-policies": "none",
+  "cache-control": "no-store"
+};
+function securityHeaders(options = {}) {
+  const merged = { ...DEFAULT_SECURITY_HEADERS, ...options };
+  const entries = Object.entries(merged).filter((e) => e[1] !== false);
+  return async (request, next) => withHeaders(await next(), (headers) => {
+    for (const [name, value] of entries) if (!headers.has(name)) headers.set(name, value);
+  });
+}
+var METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"];
+function cors(options) {
+  const { origins, credentials = true, methods = METHODS, allowHeaders, exposeHeaders, maxAge = 600 } = options;
+  return async (request, next) => {
+    const origin = request.headers.get("origin");
+    if (!origin || origin === new URL(request.url).origin) return next();
+    const allowed = allows(origins, origin);
+    const preflight = request.method === "OPTIONS" && request.headers.has("access-control-request-method");
+    if (preflight) {
+      if (!allowed) return refusal(403, "origin_not_allowed", "This origin may not call the API.");
+      const headers = new Headers({
+        "access-control-allow-origin": origin,
+        "access-control-allow-methods": methods.join(", "),
+        "access-control-max-age": String(maxAge),
+        vary: "Origin, Access-Control-Request-Headers"
+      });
+      const asked = request.headers.get("access-control-request-headers");
+      const allowedHeaders = allowHeaders ? allowHeaders.join(", ") : asked;
+      if (allowedHeaders) headers.set("access-control-allow-headers", allowedHeaders);
+      if (credentials) headers.set("access-control-allow-credentials", "true");
+      return new Response(null, { status: 204, headers });
+    }
+    const response = await next();
+    return withHeaders(response, (headers) => {
+      appendVary(headers, "Origin");
+      if (!allowed) return;
+      headers.set("access-control-allow-origin", origin);
+      if (credentials) headers.set("access-control-allow-credentials", "true");
+      if (exposeHeaders?.length) headers.set("access-control-expose-headers", exposeHeaders.join(", "));
+    });
+  };
+}
+var SAFE = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS"]);
+function originCheck(options) {
+  return (request, next) => {
+    if (SAFE.has(request.method) || !request.headers.has("cookie")) return next();
+    const origin = request.headers.get("origin");
+    const site = request.headers.get("sec-fetch-site");
+    const self = new URL(request.url).origin;
+    if (site === "same-origin" || site === "none") return next();
+    if (origin && (origin === self || allows(options.origins, origin))) return next();
+    if (!site && !origin) return next();
+    return refusal(403, "cross_origin_refused", "Requests from this origin are refused.");
+  };
+}
+function apiSecurity(options = {}) {
+  const origins = options.origins ?? [];
+  const prefix = (options.prefix ?? "/api").replace(/\/$/, "");
+  const chain = [];
+  if (options.headers !== false) chain.push(securityHeaders(options.headers));
+  if (options.cors !== false) chain.push(cors({ ...options.cors, origins }));
+  if (options.originCheck !== false) chain.push(originCheck({ origins }));
+  for (const limit of options.rateLimits ?? []) chain.push(rateLimit(limit));
+  return (request, next) => {
+    const { pathname } = new URL(request.url);
+    if (pathname !== prefix && !pathname.startsWith(prefix + "/")) return next();
+    const run = (i) => {
+      const middleware = chain[i];
+      return middleware ? Promise.resolve(middleware(request, () => run(i + 1))) : next();
+    };
+    return run(0);
+  };
+}
+function refusal(status, code, message) {
+  return errorResponse(new ApiError(status, code, message));
+}

package/dist/security.d.ts

@@ -0,0 +1,64 @@
+import { type Middleware } from './middleware.js';
+import { type RateLimitOptions } from './rate-limit.js';
+/** Allowed origins: exact `scheme://host[:port]` strings, or a test. */
+export type Origins = readonly string[] | ((origin: string) => boolean);
+/** OWASP's recommendations for a JSON API: nothing in it is meant to render, frame or be cached. */
+export declare const DEFAULT_SECURITY_HEADERS: Readonly<Record<string, string>>;
+/**
+ * Header name to value, or `false` to leave that header out. Merged over the defaults. A header
+ * the response already has is kept: a route that sets its own `cache-control` wins.
+ */
+export type SecurityHeadersOptions = Record<string, string | false>;
+export declare function securityHeaders(options?: SecurityHeadersOptions): Middleware;
+export interface CorsOptions {
+    /** Who may call from another origin. Nobody when empty. */
+    origins: Origins;
+    /** Send cookies along. On: the session is a cookie. */
+    credentials?: boolean;
+    /** Allowed in a preflight. Every method a route can export by default. */
+    methods?: readonly string[];
+    /** Allowed request headers. What the preflight asks for when not given. */
+    allowHeaders?: readonly string[];
+    /** Response headers a script may read beyond the safelisted ones. */
+    exposeHeaders?: readonly string[];
+    /** How long a browser keeps a preflight answer, in seconds. */
+    maxAge?: number;
+}
+/**
+ * CORS for listed origins. A same-origin request, or one with no `Origin`, passes untouched.
+ * An unlisted origin's preflight is refused with a 403; its other requests go through without
+ * CORS headers, so the browser keeps the response from the page.
+ */
+export declare function cors(options: CorsOptions): Middleware;
+/**
+ * Refuses a write that carries cookies from a page on another site, unless that origin is
+ * listed: cross-site request forgery against cookie sessions. Uses `Sec-Fetch-Site` where the
+ * browser sends it and `Origin` otherwise. A request with neither is not from a browser page
+ * (curl, another server), so there is no forgery to stop.
+ */
+export declare function originCheck(options: {
+    origins: Origins;
+}): Middleware;
+export interface ApiSecurityOptions {
+    /** Origins of the apps that call the API from a browser: CORS and the origin check. */
+    origins?: Origins;
+    /** Only requests under this path are touched. `/api`, start's API prefix. */
+    prefix?: string;
+    /** Overrides for the headers, or `false` for none. */
+    headers?: SecurityHeadersOptions | false;
+    /** CORS options beyond the origins, or `false` to answer no cross-origin call. */
+    cors?: Omit<CorsOptions, 'origins'> | false;
+    /** `false` turns the origin check off. */
+    originCheck?: false;
+    /** Limits, checked in order: sign-in and sign-up at least. */
+    rateLimits?: readonly RateLimitOptions[];
+}
+/**
+ * The API's protections in one middleware: headers, CORS, the origin check, rate limits. Put it
+ * first in `src/middleware.ts` so refusals from what follows carry the headers too.
+ *
+ * With no options every cross-origin call is refused and nothing is rate limited: list the web
+ * app's origins, and limit the routes that guess passwords.
+ */
+export declare function apiSecurity(options?: ApiSecurityOptions): Middleware;
+//# sourceMappingURL=security.d.ts.map

package/dist/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../src/security.ts"],"names":[],"mappings":"AASA,OAAO,EAA2B,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EAAa,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnE,wEAAwE;AACxE,MAAM,MAAM,OAAO,GAAG,SAAS,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC;AAOxE,oGAAoG;AACpG,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUrE,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC;AAEpE,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,UAAU,CAOhF;AAID,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,OAAO,EAAE,OAAO,CAAC;IACjB,uDAAuD;IACvD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,2EAA2E;IAC3E,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,qEAAqE;IACrE,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,UAAU,CAgCrD;AAMD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,UAAU,CAYrE;AAID,MAAM,WAAW,kBAAkB;IACjC,uFAAuF;IACvF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,OAAO,CAAC,EAAE,sBAAsB,GAAG,KAAK,CAAC;IACzC,kFAAkF;IAClF,IAAI,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,GAAG,KAAK,CAAC;IAC5C,0CAA0C;IAC1C,WAAW,CAAC,EAAE,KAAK,CAAC;IACpB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,UAAU,CAkBxE"}

package/dist/security.js

@@ -0,0 +1,135 @@
+/**
+ * Security middleware for API responses: headers, CORS and an origin check on cookie-carrying
+ * writes. Written against the published rules (OWASP Secure Headers Project, the Fetch standard)
+ * rather than taken from `helmet` or `cors`, which are built for Express's response object.
+ *
+ * Each works alone in `src/middleware.ts`; `apiSecurity()` puts them together with safe
+ * defaults, limited to the API's paths so pages keep their own policy.
+ */
+import { ApiError, errorResponse } from './errors.js';
+import { appendVary, withHeaders } from './middleware.js';
+import { rateLimit } from './rate-limit.js';
+const allows = (origins, origin) => typeof origins === 'function' ? origins(origin) : origins.includes(origin);
+// ─── Headers ────────────────────────────────────────────────────────────────
+/** OWASP's recommendations for a JSON API: nothing in it is meant to render, frame or be cached. */
+export const DEFAULT_SECURITY_HEADERS = {
+    'content-security-policy': "default-src 'none'; frame-ancestors 'none'",
+    'cross-origin-opener-policy': 'same-origin',
+    'cross-origin-resource-policy': 'same-origin',
+    'referrer-policy': 'no-referrer',
+    'strict-transport-security': 'max-age=31536000; includeSubDomains',
+    'x-content-type-options': 'nosniff',
+    'x-frame-options': 'DENY',
+    'x-permitted-cross-domain-policies': 'none',
+    'cache-control': 'no-store',
+};
+export function securityHeaders(options = {}) {
+    const merged = { ...DEFAULT_SECURITY_HEADERS, ...options };
+    const entries = Object.entries(merged).filter((e) => e[1] !== false);
+    return async (request, next) => withHeaders(await next(), (headers) => {
+        for (const [name, value] of entries)
+            if (!headers.has(name))
+                headers.set(name, value);
+    });
+}
+const METHODS = ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE'];
+/**
+ * CORS for listed origins. A same-origin request, or one with no `Origin`, passes untouched.
+ * An unlisted origin's preflight is refused with a 403; its other requests go through without
+ * CORS headers, so the browser keeps the response from the page.
+ */
+export function cors(options) {
+    const { origins, credentials = true, methods = METHODS, allowHeaders, exposeHeaders, maxAge = 600 } = options;
+    return async (request, next) => {
+        const origin = request.headers.get('origin');
+        if (!origin || origin === new URL(request.url).origin)
+            return next();
+        const allowed = allows(origins, origin);
+        const preflight = request.method === 'OPTIONS' && request.headers.has('access-control-request-method');
+        if (preflight) {
+            if (!allowed)
+                return refusal(403, 'origin_not_allowed', 'This origin may not call the API.');
+            const headers = new Headers({
+                'access-control-allow-origin': origin,
+                'access-control-allow-methods': methods.join(', '),
+                'access-control-max-age': String(maxAge),
+                vary: 'Origin, Access-Control-Request-Headers',
+            });
+            const asked = request.headers.get('access-control-request-headers');
+            const allowedHeaders = allowHeaders ? allowHeaders.join(', ') : asked;
+            if (allowedHeaders)
+                headers.set('access-control-allow-headers', allowedHeaders);
+            if (credentials)
+                headers.set('access-control-allow-credentials', 'true');
+            return new Response(null, { status: 204, headers });
+        }
+        const response = await next();
+        return withHeaders(response, (headers) => {
+            appendVary(headers, 'Origin');
+            if (!allowed)
+                return;
+            headers.set('access-control-allow-origin', origin);
+            if (credentials)
+                headers.set('access-control-allow-credentials', 'true');
+            if (exposeHeaders?.length)
+                headers.set('access-control-expose-headers', exposeHeaders.join(', '));
+        });
+    };
+}
+// ─── Origin check ───────────────────────────────────────────────────────────
+const SAFE = new Set(['GET', 'HEAD', 'OPTIONS']);
+/**
+ * Refuses a write that carries cookies from a page on another site, unless that origin is
+ * listed: cross-site request forgery against cookie sessions. Uses `Sec-Fetch-Site` where the
+ * browser sends it and `Origin` otherwise. A request with neither is not from a browser page
+ * (curl, another server), so there is no forgery to stop.
+ */
+export function originCheck(options) {
+    return (request, next) => {
+        if (SAFE.has(request.method) || !request.headers.has('cookie'))
+            return next();
+        const origin = request.headers.get('origin');
+        const site = request.headers.get('sec-fetch-site');
+        const self = new URL(request.url).origin;
+        if (site === 'same-origin' || site === 'none')
+            return next();
+        if (origin && (origin === self || allows(options.origins, origin)))
+            return next();
+        if (!site && !origin)
+            return next();
+        return refusal(403, 'cross_origin_refused', 'Requests from this origin are refused.');
+    };
+}
+/**
+ * The API's protections in one middleware: headers, CORS, the origin check, rate limits. Put it
+ * first in `src/middleware.ts` so refusals from what follows carry the headers too.
+ *
+ * With no options every cross-origin call is refused and nothing is rate limited: list the web
+ * app's origins, and limit the routes that guess passwords.
+ */
+export function apiSecurity(options = {}) {
+    const origins = options.origins ?? [];
+    const prefix = (options.prefix ?? '/api').replace(/\/$/, '');
+    const chain = [];
+    if (options.headers !== false)
+        chain.push(securityHeaders(options.headers));
+    if (options.cors !== false)
+        chain.push(cors({ ...options.cors, origins }));
+    if (options.originCheck !== false)
+        chain.push(originCheck({ origins }));
+    for (const limit of options.rateLimits ?? [])
+        chain.push(rateLimit(limit));
+    return (request, next) => {
+        const { pathname } = new URL(request.url);
+        if (pathname !== prefix && !pathname.startsWith(prefix + '/'))
+            return next();
+        const run = (i) => {
+            const middleware = chain[i];
+            return middleware ? Promise.resolve(middleware(request, () => run(i + 1))) : next();
+        };
+        return run(0);
+    };
+}
+function refusal(status, code, message) {
+    return errorResponse(new ApiError(status, code, message));
+}