@nifrajs/auth 5.6.0 → 5.7.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @nifrajs/auth
 
+## 5.7.0
+
+### Minor Changes
+
+- b141cf4: `csrf()` takes `exempt`: route patterns whose requests skip the Origin check, for a route no browser
+  calls that verifies its sender another way, such as a signed payment webhook arriving with no
+  `Origin`. Patterns are written as routes are (`/inbound/:vendor`) and matched against the path the
+  server routes, so any other path stays checked.
+
 ## 5.6.0
 
 ### Patch Changes

package/dist/csrf.d.ts

@@ -1,9 +1,3 @@
-/**
- * CSRF protection via an **Origin / Referer check** on state-changing requests - OWASP's recommended
- * defense for cookie-authenticated apps. A browser always attaches `Origin` (or at least `Referer`) to
- * a cross-origin or same-origin *unsafe* request; it must match an allowed origin, else `403`. Safe
- * methods (GET/HEAD/OPTIONS) pass. Apply with `app.use(csrf({ origins: ["https://example.com"] }))`.
- */
 import { type Middleware } from "@nifrajs/core/server";
 export interface CsrfOptions {
     /**
@@ -12,6 +6,14 @@ export interface CsrfOptions {
      * works). Set it when the proxy rewrites `Host`, so the public origin differs from the worker's.
      */
     readonly origins?: readonly string[];
+    /**
+     * Route patterns whose requests skip the check, for a route no browser calls that proves its sender
+     * another way - a signed payment webhook arrives with no `Origin` at all. Written as routes are
+     * (`/inbound/:vendor`) and matched against the path this server routes, so a different path to
+     * the same handler is still checked. Exempt nothing that acts on a session cookie: a cross-site page
+     * can post to it.
+     */
+    readonly exempt?: readonly string[];
 }
 export declare function csrf(options?: CsrfOptions): Middleware;
 //# sourceMappingURL=csrf.d.ts.map

package/dist/csrf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"csrf.d.ts","sourceRoot":"","sources":["../src/csrf.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAuB,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAQ3E,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC;AAKD,wBAAgB,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,UAAU,CAmC1D"}
+{"version":3,"file":"csrf.d.ts","sourceRoot":"","sources":["../src/csrf.ts"],"names":[],"mappings":"AASA,OAAO,EAAuB,KAAK,UAAU,EAAc,MAAM,sBAAsB,CAAA;AAQvF,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AAcD,wBAAgB,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,UAAU,CAqC1D"}

package/dist/csrf.js

@@ -2,22 +2,38 @@
  * CSRF protection via an **Origin / Referer check** on state-changing requests - OWASP's recommended
  * defense for cookie-authenticated apps. A browser always attaches `Origin` (or at least `Referer`) to
  * a cross-origin or same-origin *unsafe* request; it must match an allowed origin, else `403`. Safe
- * methods (GET/HEAD/OPTIONS) pass. Apply with `app.use(csrf({ origins: ["https://example.com"] }))`.
+ * methods (GET/HEAD/OPTIONS) pass, as do routes listed in `exempt`. Apply with
+ * `app.use(csrf({ origins: ["https://example.com"] }))`.
  */
-import { isSameOriginRequest } from "@nifrajs/core/server";
+import { expandOptionalParams } from "@nifrajs/core/pattern";
+import { Router } from "@nifrajs/core/router";
+import { isSameOriginRequest, pathnameOf } from "@nifrajs/core/server";
 const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
 // A name per instance: `use()` skips a name it already applied, which would drop a second, stricter
 // `csrf()` inside a `group()`.
 let instances = 0;
 const forbidden = () => Response.json({ ok: false, error: "csrf_failed" }, { status: 403 });
+function exemptionOf(patterns) {
+    if (patterns.length === 0)
+        return undefined;
+    const forms = new Set(patterns.flatMap((pattern) => expandOptionalParams(pattern)));
+    const router = new Router();
+    // An exemption names a path whatever the method, so every form sits under one method key.
+    for (const form of forms)
+        router.add("POST", form, true);
+    return (path) => router.find("POST", path).found;
+}
 export function csrf(options = {}) {
     const configured = options.origins !== undefined ? new Set(options.origins) : undefined;
+    const exempt = exemptionOf(options.exempt ?? []);
     instances += 1;
     return {
         name: `csrf#${instances}`,
         onRequest(req) {
             if (SAFE_METHODS.has(req.method))
                 return undefined;
+            if (exempt?.(pathnameOf(req.url)) === true)
+                return undefined;
             // The same-origin default uses core's check, which accepts an `https:` page reaching an `http:`
             // request URL on the same host - what every TLS-terminating proxy looks like from here.
             const allowed = (candidate) => configured !== undefined ? configured.has(candidate) : isSameOriginRequest(candidate, req);

package/dist/csrf.js.map

@@ -1 +1 @@
-{"version":3,"file":"csrf.js","sourceRoot":"","sources":["../src/csrf.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,mBAAmB,EAAmB,MAAM,sBAAsB,CAAA;AAE3E,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAA;AAExD,oGAAoG;AACpG,+BAA+B;AAC/B,IAAI,SAAS,GAAG,CAAC,CAAA;AAWjB,MAAM,SAAS,GAAG,GAAa,EAAE,CAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;AAErE,MAAM,UAAU,IAAI,CAAC,UAAuB,EAAE;IAC5C,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IACvF,SAAS,IAAI,CAAC,CAAA;IACd,OAAO;QACL,IAAI,EAAE,QAAQ,SAAS,EAAE;QACzB,SAAS,CAAC,GAAG;YACX,IAAI,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,OAAO,SAAS,CAAA;YAClD,gGAAgG;YAChG,wFAAwF;YACxF,MAAM,OAAO,GAAG,CAAC,SAAiB,EAAW,EAAE,CAC7C,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,SAAS,EAAE,GAAG,CAAC,CAAA;YAE5F,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YACxC,oFAAoF;YACpF,+FAA+F;YAC/F,IAAI,MAAM,KAAK,MAAM,IAAI,UAAU,KAAK,SAAS;gBAC/C,OAAO,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,EAAE,CAAA;YACtF,IAAI,MAAM,KAAK,IAAI;gBAAE,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,EAAE,CAAA;YAErE,iFAAiF;YACjF,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;YAC1C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrB,IAAI,aAAqB,CAAA;gBACzB,IAAI,CAAC;oBACH,aAAa,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,MAAM,CAAA;gBACzC,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,SAAS,EAAE,CAAA,CAAC,oBAAoB;gBACzC,CAAC;gBACD,OAAO,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,EAAE,CAAA;YACzD,CAAC;YAED,mGAAmG;YACnG,OAAO,SAAS,EAAE,CAAA;QACpB,CAAC;KACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"csrf.js","sourceRoot":"","sources":["../src/csrf.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/auth",
-  "version": "5.6.0",
+  "version": "5.7.0",
   "description": "Session primitives for nifra - signed-cookie + server-store sessions, CSRF, and route guards. Bring your own identity (Better Auth / Lucia / OAuth); nifra owns the session.",
   "keywords": [
     "bun",
@@ -41,7 +41,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@nifrajs/core": "^5.6.0"
+    "@nifrajs/core": "^5.7.0"
   },
   "devDependencies": {
     "@nifrajs/core": "workspace:*"

package/src/csrf.ts

@@ -2,9 +2,12 @@
  * CSRF protection via an **Origin / Referer check** on state-changing requests - OWASP's recommended
  * defense for cookie-authenticated apps. A browser always attaches `Origin` (or at least `Referer`) to
  * a cross-origin or same-origin *unsafe* request; it must match an allowed origin, else `403`. Safe
- * methods (GET/HEAD/OPTIONS) pass. Apply with `app.use(csrf({ origins: ["https://example.com"] }))`.
+ * methods (GET/HEAD/OPTIONS) pass, as do routes listed in `exempt`. Apply with
+ * `app.use(csrf({ origins: ["https://example.com"] }))`.
  */
-import { isSameOriginRequest, type Middleware } from "@nifrajs/core/server"
+import { expandOptionalParams } from "@nifrajs/core/pattern"
+import { Router } from "@nifrajs/core/router"
+import { isSameOriginRequest, type Middleware, pathnameOf } from "@nifrajs/core/server"
 
 const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"])
 
@@ -19,18 +22,37 @@ export interface CsrfOptions {
    * works). Set it when the proxy rewrites `Host`, so the public origin differs from the worker's.
    */
   readonly origins?: readonly string[]
+  /**
+   * Route patterns whose requests skip the check, for a route no browser calls that proves its sender
+   * another way - a signed payment webhook arrives with no `Origin` at all. Written as routes are
+   * (`/inbound/:vendor`) and matched against the path this server routes, so a different path to
+   * the same handler is still checked. Exempt nothing that acts on a session cookie: a cross-site page
+   * can post to it.
+   */
+  readonly exempt?: readonly string[]
 }
 
 const forbidden = (): Response =>
   Response.json({ ok: false, error: "csrf_failed" }, { status: 403 })
 
+function exemptionOf(patterns: readonly string[]): ((path: string) => boolean) | undefined {
+  if (patterns.length === 0) return undefined
+  const forms = new Set(patterns.flatMap((pattern) => expandOptionalParams(pattern)))
+  const router = new Router<true>()
+  // An exemption names a path whatever the method, so every form sits under one method key.
+  for (const form of forms) router.add("POST", form, true)
+  return (path) => router.find("POST", path).found
+}
+
 export function csrf(options: CsrfOptions = {}): Middleware {
   const configured = options.origins !== undefined ? new Set(options.origins) : undefined
+  const exempt = exemptionOf(options.exempt ?? [])
   instances += 1
   return {
     name: `csrf#${instances}`,
     onRequest(req) {
       if (SAFE_METHODS.has(req.method)) return undefined
+      if (exempt?.(pathnameOf(req.url)) === true) return undefined
       // The same-origin default uses core's check, which accepts an `https:` page reaching an `http:`
       // request URL on the same host - what every TLS-terminating proxy looks like from here.
       const allowed = (candidate: string): boolean =>