@everystack/auth 0.2.4 → 0.2.6

package/README.md

@@ -247,4 +247,8 @@ Part of [everystack](https://github.com/scalable-technology/everystack) — a se
 
 ## License
 
-MIT
+[AGPL-3.0-only](https://www.gnu.org/licenses/agpl-3.0.html) © Scalable Technology, Inc.
+
+A commercial license is available for organizations that cannot or do not wish to
+comply with the AGPL-3.0 terms. For commercial licensing, contact
+licensing@scalable.technology.

package/package.json

@@ -1,8 +1,18 @@
 {
   "name": "@everystack/auth",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "JWT authentication handlers, password hashing, and React auth context",
   "license": "AGPL-3.0-only",
+  "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scalable-technology/everystack.git",
+    "directory": "packages/auth"
+  },
+  "homepage": "https://github.com/scalable-technology/everystack#readme",
+  "bugs": {
+    "url": "https://github.com/scalable-technology/everystack/issues"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -75,11 +85,6 @@
       "default": "./src/testing.ts"
     }
   },
-  "scripts": {
-    "test": "jest",
-    "build": "tsc --build",
-    "lint": "tsc --noEmit"
-  },
   "dependencies": {
     "bcryptjs": "3.0.3"
   },
@@ -101,7 +106,6 @@
     }
   },
   "devDependencies": {
-    "@everystack/api": "workspace:*",
     "@types/bcryptjs": "3.0.0",
     "@types/jest": "29.5.14",
     "@types/node": "22.19.18",
@@ -110,6 +114,12 @@
     "jest": "29.7.0",
     "postgres": "3.4.9",
     "ts-jest": "29.4.9",
-    "typescript": "5.9.3"
+    "typescript": "5.9.3",
+    "@everystack/api": "0.2.9"
+  },
+  "scripts": {
+    "test": "jest",
+    "build": "tsc --build",
+    "lint": "tsc --noEmit"
   }
-}
+}

package/src/cookies.ts

@@ -3,7 +3,11 @@
  *
  * Access token cookie is sent on all requests (Path=/).
  * Refresh token cookie is scoped to the refresh endpoint only (Path=/api/auth/refresh).
- * Both are HttpOnly + Secure + SameSite=Lax.
+ *
+ * Access token is SameSite=Lax — it must ride top-level SSR navigations into the
+ * app. Refresh token is SameSite=Strict — it is only ever hit by XHR at its scoped
+ * path, never a navigation target, so Strict kills its CSRF surface by construction
+ * (a cross-site page can't make the browser attach it at all).
  */
 
 export const COOKIE_NAMES = {
@@ -44,7 +48,7 @@ export function serializeAuthCookies(
 
   return [
     `${COOKIE_NAMES.token}=${token}; HttpOnly; ${secure ? 'Secure; ' : ''}SameSite=Lax; Path=${basePath}; Max-Age=${tokenMaxAge}${domain}`,
-    `${COOKIE_NAMES.refresh}=${refreshToken}; HttpOnly; ${secure ? 'Secure; ' : ''}SameSite=Lax; Path=/api/auth/refresh; Max-Age=${refreshMaxAge}${domain}`,
+    `${COOKIE_NAMES.refresh}=${refreshToken}; HttpOnly; ${secure ? 'Secure; ' : ''}SameSite=Strict; Path=/api/auth/refresh; Max-Age=${refreshMaxAge}${domain}`,
   ];
 }
 
@@ -58,7 +62,7 @@ export function clearAuthCookies(opts?: CookieOptions): string[] {
 
   return [
     `${COOKIE_NAMES.token}=; HttpOnly; ${secure ? 'Secure; ' : ''}SameSite=Lax; Path=${basePath}; Max-Age=0${domain}`,
-    `${COOKIE_NAMES.refresh}=; HttpOnly; ${secure ? 'Secure; ' : ''}SameSite=Lax; Path=/api/auth/refresh; Max-Age=0${domain}`,
+    `${COOKIE_NAMES.refresh}=; HttpOnly; ${secure ? 'Secure; ' : ''}SameSite=Strict; Path=/api/auth/refresh; Max-Age=0${domain}`,
   ];
 }
 

package/src/index.ts

@@ -147,10 +147,22 @@ export interface AuthOptions {
   /** One-time token operations for email confirmation and password recovery.
    *  Required for confirmEmail, forgotPassword, and resetPassword handlers. */
   tokens?: TokenOperations;
-  /** Called after successful signup when tokens are configured. App sends confirmation email. */
+  /** Called after successful signup when tokens are configured. App sends confirmation email.
+   *  Receives a token MINTED IN THE API — owner-only, so this breaks under least-privilege.
+   *  Postgres least-priv path uses `onConfirmationRequested` instead (mint on the worker). */
   onConfirmationRequired?: (user: { id: string; email: string }, token: string) => Promise<void>;
-  /** Called on forgot-password — app sends recovery email. */
+  /** Called on forgot-password with a token MINTED IN THE API (owner-only — breaks under
+   *  least-privilege). Postgres least-priv path uses `onRecoveryRequested` instead. */
   onRecoveryRequired?: (user: { id: string; email: string }, token: string) => Promise<void>;
+  /** Least-privilege confirmation: called after signup with only the new user's identity.
+   *  The API does NOT mint a token — the app enqueues a job; the privileged worker mints the
+   *  one-time token and sends the email. Takes precedence over onConfirmationRequired. */
+  onConfirmationRequested?: (user: { id: string; email: string }) => Promise<void>;
+  /** Least-privilege recovery: called on forgot-password with ONLY the email. The API does
+   *  not read the user table or mint a token — it enqueues a job; the privileged worker
+   *  looks up the user, mints the recovery token, and sends the email. Always responds the
+   *  same to the client (no user enumeration). Takes precedence over onRecoveryRequired. */
+  onRecoveryRequested?: (email: string) => Promise<void>;
   /** Called after email confirmed via one-time token — app updates user record. */
   onEmailConfirmed?: (userId: string) => Promise<void>;
 }
@@ -180,9 +192,40 @@ function csrfCheck(request: Request, cookies?: CookieConfig): Response | null {
   return validateCsrfOrigin(request, cookies.allowedOrigins);
 }
 
+/**
+ * Fail-closed cookie config check, run once at handler construction.
+ *
+ * Cookie-authenticated requests carry a CSRF surface (the cookie is auto-sent).
+ * The Origin allowlist is the defense-in-depth behind SameSite — and it silently
+ * no-ops when `allowedOrigins` is empty, so enabling cookies without it would turn
+ * the CSRF check off without any signal. We refuse to start instead: a misconfig
+ * dies at deploy, not silently-allows until a request happens to hit the check.
+ *
+ * The `cookies: true` shorthand cannot carry an allowlist, so it is rejected —
+ * there is no construction-time same-origin to derive. Pass an explicit allowlist
+ * or omit cookies entirely for Bearer-only (mobile/API) auth.
+ */
+function assertSafeCookieConfig(cookies: CookieConfig | undefined): void {
+  if (!cookies) return; // cookie auth disabled (false/undefined) — Bearer-only, no CSRF surface
+  const allowedOrigins = cookies === true ? undefined : cookies.allowedOrigins;
+  if (!allowedOrigins || allowedOrigins.length === 0) {
+    throw new Error(
+      '[everystack/auth] Cookie authentication is enabled but cookies.allowedOrigins is empty. '
+      + 'Cookie-authenticated requests carry a CSRF surface; an explicit Origin allowlist is '
+      + 'required. Pass cookies: { allowedOrigins: ["https://your-web-origin"] } instead of '
+      + 'cookies: true, or omit cookies for Bearer-only (mobile/API) auth.'
+    );
+  }
+}
+
 /**
  * Add mode-independent email confirmation and password management handlers.
  * Called after base handlers are created (works with both node and postgres modes).
+ *
+ * Uses `??=` so a handler already provided by the base (e.g. the least-privilege
+ * postgres confirmEmail/resetPassword that run via SECDEF wrappers under withRole)
+ * is NOT overwritten by the generic owner-connection version. Node mode provides
+ * none of these, so it gets the generic implementations.
  */
 function addEmailPasswordFlows(
   handlers: AuthHandlers,
@@ -191,7 +234,7 @@ function addEmailPasswordFlows(
   options?: AuthOptions,
 ): void {
   if (options?.tokens) {
-    handlers.confirmEmail = async (request: Request): Promise<Response> => {
+    handlers.confirmEmail ??= async (request: Request): Promise<Response> => {
       const csrfError = csrfCheck(request, options?.cookies);
       if (csrfError) return csrfError;
 
@@ -218,7 +261,7 @@ function addEmailPasswordFlows(
       }
     };
 
-    handlers.forgotPassword = async (request: Request): Promise<Response> => {
+    handlers.forgotPassword ??= async (request: Request): Promise<Response> => {
       const csrfError = csrfCheck(request, options?.cookies);
       if (csrfError) return csrfError;
 
@@ -253,7 +296,7 @@ function addEmailPasswordFlows(
       return Response.json({ sent: true });
     };
 
-    handlers.resetPassword = async (request: Request): Promise<Response> => {
+    handlers.resetPassword ??= async (request: Request): Promise<Response> => {
       const csrfError = csrfCheck(request, options?.cookies);
       if (csrfError) return csrfError;
 
@@ -287,7 +330,7 @@ function addEmailPasswordFlows(
     };
   }
 
-  handlers.changePassword = async (request: Request): Promise<Response> => {
+  handlers.changePassword ??= async (request: Request): Promise<Response> => {
     const csrfError = csrfCheck(request, options?.cookies);
     if (csrfError) return csrfError;
 
@@ -389,6 +432,8 @@ export function createAuthHandlers(
   jwtSecret: Uint8Array,
   options?: AuthOptions
 ): AuthHandlers {
+  assertSafeCookieConfig(options?.cookies);
+
   if (options?.mode === 'postgres') {
     const handlers = createPostgresAuthHandlers(db, schema, jwtSecret, options);
     addEmailPasswordFlows(handlers, db, schema.users, options);