@govcore/middleware 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# @govcore/middleware
+
+## 0.1.0
+
+### Minor Changes
+
+- ca7cadb: Phase 3 — route protection and identity.
+
+  `@govcore/auth`: `createAuth` factory wrapping Auth.js (NextAuth v5) — injected
+  OIDC providers + local credentials (bcrypt), the Drizzle adapter over
+  `@govcore/schema`, the invite-based SSO provisioning guard, JWT/session callbacks
+  that stamp the active org/role from the membership model, login/logout audit, and
+  the resurrection-guard marker. Plus `hashPassword`/`verifyPassword`/`validatePassword`
+  and an edge-safe `./logout-marker` subpath. GovEA's product-specific per-org
+  policy (lockout/session-timeout/password-expiry) is intentionally not included.
+
+  `@govcore/middleware`: edge-safe `createMiddleware` factory — read-only `getToken`
+  decode (never writes cookies, ADR-0003), the #782 post-logout resurrection guard,
+  the #807 bind-address-safe redirect, and configurable public/instance-only/
+  maintenance gating, plus `defaultMatcher`.
+
+### Patch Changes
+
+- Updated dependencies [ca7cadb]
+- Updated dependencies [18bed9e]
+  - @govcore/auth@0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob Allred
+
+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/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { NextResponse, type NextRequest } from 'next/server';
+export interface CreateMiddlewareOptions {
+    /** Path prefixes reachable without a session. */
+    publicPaths?: string[];
+    /** Path prefixes that require an instance-level role. */
+    instanceOnlyPaths?: string[];
+    /** The `instanceRole` value that satisfies instanceOnlyPaths. Default 'instance_admin'. */
+    instanceRole?: string;
+    /** When true, only `maintenanceBypassRole` may pass; everyone else → maintenancePath. */
+    maintenanceMode?: boolean;
+    /** Role allowed through during maintenance. Default 'admin'. */
+    maintenanceBypassRole?: string;
+    loginPath?: string;
+    maintenancePath?: string;
+    /** Where instance-only violations are sent. Default '/'. */
+    homePath?: string;
+    /** Auth.js secret. Defaults to process.env.AUTH_SECRET. */
+    authSecret?: string;
+}
+/**
+ * Matcher that excludes static assets and the Auth.js endpoints (they manage
+ * their own cookies). Provided as the canonical reference value.
+ *
+ * NOTE: do NOT use this directly in `export const config = { matcher }` — Next.js
+ * statically parses the middleware `config` export at build time and rejects any
+ * value it can't resolve to a literal (it reports "Unknown identifier" /
+ * "Invalid segment configuration export"). Copy the literal inline instead.
+ */
+export declare const defaultMatcher: string[];
+/** Build a Next.js middleware function from GovCore's route-protection rules. */
+export declare function createMiddleware(opts?: CreateMiddlewareOptions): (req: NextRequest) => Promise<NextResponse>;
+//# 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":"AAUA,OAAO,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAA;AAG5D,MAAM,WAAW,uBAAuB;IACtC,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,yDAAyD;IACzD,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC5B,2FAA2F;IAC3F,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,yFAAyF;IACzF,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,gEAAgE;IAChE,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAID;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,UAA6D,CAAA;AAoCxF,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,uBAA4B,IAShC,KAAK,WAAW,KAAG,OAAO,CAAC,YAAY,CAAC,CA4C1E"}

package/dist/index.js

@@ -0,0 +1,99 @@
+// @govcore/middleware — the edge-safe Next.js route-protection factory.
+//
+// Deliberately NOT next-auth's `auth()` wrapper: that re-issues (rolls) the
+// session cookie on its responses, making the middleware itself a resurrection
+// emitter that fights the #782 guard. `getToken` is a read-only decode — this
+// middleware never writes session cookies (ADR-0003). Edge-safe: token decode +
+// pure arithmetic, no DB. The only cross-package import is @govcore/auth's pure
+// `logout-marker` subpath (no next-auth/db pulled in).
+import { getToken } from 'next-auth/jwt';
+import { NextResponse } from 'next/server';
+import { LOGGED_OUT_MARKER_COOKIE, isResurrectedSession } from '@govcore/auth/logout-marker';
+const DEFAULT_PUBLIC_PATHS = ['/login', '/setup', '/error', '/api/auth', '/maintenance'];
+/**
+ * Matcher that excludes static assets and the Auth.js endpoints (they manage
+ * their own cookies). Provided as the canonical reference value.
+ *
+ * NOTE: do NOT use this directly in `export const config = { matcher }` — Next.js
+ * statically parses the middleware `config` export at build time and rejects any
+ * value it can't resolve to a literal (it reports "Unknown identifier" /
+ * "Invalid segment configuration export"). Copy the literal inline instead.
+ */
+export const defaultMatcher = ['/((?!_next/static|_next/image|favicon.ico|api/auth).*)'];
+/**
+ * Absolute redirect that never echoes the container bind address (#807). Next
+ * middleware requires an absolute Location; behind a TLS-terminating proxy the
+ * request origin can be `0.0.0.0:3000`, which we rebuild from the forwarded host
+ * or NEXT_PUBLIC_APP_URL.
+ */
+function redirectTo(req, path) {
+    const target = new URL(path, req.nextUrl.origin);
+    if (target.hostname === '0.0.0.0') {
+        const fwdHost = req.headers.get('x-forwarded-host')?.split(',')[0].trim();
+        const fwdProto = req.headers.get('x-forwarded-proto')?.split(',')[0].trim();
+        const base = (fwdHost && !fwdHost.startsWith('0.0.0.0') && `${fwdProto || 'https'}://${fwdHost}`) ||
+            process.env.NEXT_PUBLIC_APP_URL ||
+            null;
+        if (base) {
+            try {
+                return NextResponse.redirect(new URL(path, base));
+            }
+            catch {
+                /* malformed base — fall through */
+            }
+        }
+    }
+    return NextResponse.redirect(target);
+}
+/** Read-only session decode — checks both secure and plain cookie salts. */
+async function decodeSession(req, secret) {
+    return ((await getToken({ req, secret, secureCookie: true, salt: '__Secure-authjs.session-token' })) ??
+        (await getToken({ req, secret, secureCookie: false, salt: 'authjs.session-token' })));
+}
+/** Build a Next.js middleware function from GovCore's route-protection rules. */
+export function createMiddleware(opts = {}) {
+    const publicPaths = opts.publicPaths ?? DEFAULT_PUBLIC_PATHS;
+    const instanceOnlyPaths = opts.instanceOnlyPaths ?? ['/instance'];
+    const instanceRole = opts.instanceRole ?? 'instance_admin';
+    const maintenanceBypassRole = opts.maintenanceBypassRole ?? 'admin';
+    const loginPath = opts.loginPath ?? '/login';
+    const maintenancePath = opts.maintenancePath ?? '/maintenance';
+    const homePath = opts.homePath ?? '/';
+    return async function middleware(req) {
+        const { pathname } = req.nextUrl;
+        const isPublic = publicPaths.some((p) => pathname.startsWith(p));
+        const isStatic = pathname.startsWith('/_next') || pathname === '/favicon.ico';
+        if (isPublic || isStatic)
+            return NextResponse.next();
+        const secret = opts.authSecret ?? process.env.AUTH_SECRET;
+        const token = await decodeSession(req, secret);
+        // #782 — post-logout resurrection guard. Reject (and actively delete) any
+        // session token issued before the logged-out marker (plus the guard window).
+        const loggedOutMarker = req.cookies.get(LOGGED_OUT_MARKER_COOKIE)?.value;
+        if (token && isResurrectedSession(loggedOutMarker, token.iat)) {
+            const res = redirectTo(req, loginPath);
+            for (const cookie of req.cookies.getAll()) {
+                if (cookie.name.includes('authjs.session-token')) {
+                    res.cookies.set(cookie.name, '', {
+                        maxAge: 0,
+                        expires: new Date(0),
+                        path: '/',
+                        secure: cookie.name.startsWith('__Secure-'),
+                    });
+                }
+            }
+            return res;
+        }
+        if (!token)
+            return redirectTo(req, loginPath);
+        const maintenanceMode = opts.maintenanceMode ?? process.env.MAINTENANCE_MODE === 'true';
+        if (maintenanceMode && token.role !== maintenanceBypassRole) {
+            return redirectTo(req, maintenancePath);
+        }
+        if (instanceOnlyPaths.some((p) => pathname.startsWith(p)) &&
+            token.instanceRole !== instanceRole) {
+            return redirectTo(req, homePath);
+        }
+        return NextResponse.next();
+    };
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@govcore/middleware",
+  "version": "0.1.0",
+  "description": "Edge-safe Next.js middleware factory: read-only session decode, resurrection guard, instance/maintenance gating",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "next-auth": "^5.0.0-beta.25",
+    "@govcore/auth": "0.1.0"
+  },
+  "peerDependencies": {
+    "next": "^15.0.0"
+  },
+  "devDependencies": {
+    "next": "^15.5.0",
+    "typescript": "^5.5.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch"
+  }
+}

package/src/index.ts

@@ -0,0 +1,134 @@
+// @govcore/middleware — the edge-safe Next.js route-protection factory.
+//
+// Deliberately NOT next-auth's `auth()` wrapper: that re-issues (rolls) the
+// session cookie on its responses, making the middleware itself a resurrection
+// emitter that fights the #782 guard. `getToken` is a read-only decode — this
+// middleware never writes session cookies (ADR-0003). Edge-safe: token decode +
+// pure arithmetic, no DB. The only cross-package import is @govcore/auth's pure
+// `logout-marker` subpath (no next-auth/db pulled in).
+
+import { getToken, type JWT } from 'next-auth/jwt'
+import { NextResponse, type NextRequest } from 'next/server'
+import { LOGGED_OUT_MARKER_COOKIE, isResurrectedSession } from '@govcore/auth/logout-marker'
+
+export interface CreateMiddlewareOptions {
+  /** Path prefixes reachable without a session. */
+  publicPaths?: string[]
+  /** Path prefixes that require an instance-level role. */
+  instanceOnlyPaths?: string[]
+  /** The `instanceRole` value that satisfies instanceOnlyPaths. Default 'instance_admin'. */
+  instanceRole?: string
+  /** When true, only `maintenanceBypassRole` may pass; everyone else → maintenancePath. */
+  maintenanceMode?: boolean
+  /** Role allowed through during maintenance. Default 'admin'. */
+  maintenanceBypassRole?: string
+  loginPath?: string
+  maintenancePath?: string
+  /** Where instance-only violations are sent. Default '/'. */
+  homePath?: string
+  /** Auth.js secret. Defaults to process.env.AUTH_SECRET. */
+  authSecret?: string
+}
+
+const DEFAULT_PUBLIC_PATHS = ['/login', '/setup', '/error', '/api/auth', '/maintenance']
+
+/**
+ * Matcher that excludes static assets and the Auth.js endpoints (they manage
+ * their own cookies). Provided as the canonical reference value.
+ *
+ * NOTE: do NOT use this directly in `export const config = { matcher }` — Next.js
+ * statically parses the middleware `config` export at build time and rejects any
+ * value it can't resolve to a literal (it reports "Unknown identifier" /
+ * "Invalid segment configuration export"). Copy the literal inline instead.
+ */
+export const defaultMatcher = ['/((?!_next/static|_next/image|favicon.ico|api/auth).*)']
+
+/**
+ * Absolute redirect that never echoes the container bind address (#807). Next
+ * middleware requires an absolute Location; behind a TLS-terminating proxy the
+ * request origin can be `0.0.0.0:3000`, which we rebuild from the forwarded host
+ * or NEXT_PUBLIC_APP_URL.
+ */
+function redirectTo(req: NextRequest, path: string): NextResponse {
+  const target = new URL(path, req.nextUrl.origin)
+  if (target.hostname === '0.0.0.0') {
+    const fwdHost = req.headers.get('x-forwarded-host')?.split(',')[0].trim()
+    const fwdProto = req.headers.get('x-forwarded-proto')?.split(',')[0].trim()
+    const base =
+      (fwdHost && !fwdHost.startsWith('0.0.0.0') && `${fwdProto || 'https'}://${fwdHost}`) ||
+      process.env.NEXT_PUBLIC_APP_URL ||
+      null
+    if (base) {
+      try {
+        return NextResponse.redirect(new URL(path, base))
+      } catch {
+        /* malformed base — fall through */
+      }
+    }
+  }
+  return NextResponse.redirect(target)
+}
+
+/** Read-only session decode — checks both secure and plain cookie salts. */
+async function decodeSession(req: NextRequest, secret: string | undefined): Promise<JWT | null> {
+  return (
+    (await getToken({ req, secret, secureCookie: true, salt: '__Secure-authjs.session-token' })) ??
+    (await getToken({ req, secret, secureCookie: false, salt: 'authjs.session-token' }))
+  )
+}
+
+/** Build a Next.js middleware function from GovCore's route-protection rules. */
+export function createMiddleware(opts: CreateMiddlewareOptions = {}) {
+  const publicPaths = opts.publicPaths ?? DEFAULT_PUBLIC_PATHS
+  const instanceOnlyPaths = opts.instanceOnlyPaths ?? ['/instance']
+  const instanceRole = opts.instanceRole ?? 'instance_admin'
+  const maintenanceBypassRole = opts.maintenanceBypassRole ?? 'admin'
+  const loginPath = opts.loginPath ?? '/login'
+  const maintenancePath = opts.maintenancePath ?? '/maintenance'
+  const homePath = opts.homePath ?? '/'
+
+  return async function middleware(req: NextRequest): Promise<NextResponse> {
+    const { pathname } = req.nextUrl
+
+    const isPublic = publicPaths.some((p) => pathname.startsWith(p))
+    const isStatic = pathname.startsWith('/_next') || pathname === '/favicon.ico'
+    if (isPublic || isStatic) return NextResponse.next()
+
+    const secret = opts.authSecret ?? process.env.AUTH_SECRET
+    const token = await decodeSession(req, secret)
+
+    // #782 — post-logout resurrection guard. Reject (and actively delete) any
+    // session token issued before the logged-out marker (plus the guard window).
+    const loggedOutMarker = req.cookies.get(LOGGED_OUT_MARKER_COOKIE)?.value
+    if (token && isResurrectedSession(loggedOutMarker, token.iat as number | undefined)) {
+      const res = redirectTo(req, loginPath)
+      for (const cookie of req.cookies.getAll()) {
+        if (cookie.name.includes('authjs.session-token')) {
+          res.cookies.set(cookie.name, '', {
+            maxAge: 0,
+            expires: new Date(0),
+            path: '/',
+            secure: cookie.name.startsWith('__Secure-'),
+          })
+        }
+      }
+      return res
+    }
+
+    if (!token) return redirectTo(req, loginPath)
+
+    const maintenanceMode = opts.maintenanceMode ?? process.env.MAINTENANCE_MODE === 'true'
+    if (maintenanceMode && token.role !== maintenanceBypassRole) {
+      return redirectTo(req, maintenancePath)
+    }
+
+    if (
+      instanceOnlyPaths.some((p) => pathname.startsWith(p)) &&
+      token.instanceRole !== instanceRole
+    ) {
+      return redirectTo(req, homePath)
+    }
+
+    return NextResponse.next()
+  }
+}