@stacksjs/auth 0.70.88 → 0.70.91

package/dist/email-verification.js

@@ -0,0 +1,111 @@
+import { Buffer } from "node:buffer";
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { config } from "@stacksjs/config";
+import { db } from "@stacksjs/database";
+import { mail, template } from "@stacksjs/email";
+import { log } from "@stacksjs/logging";
+function getVerificationKey() {
+  const appKey = config.app.key;
+  if (typeof appKey !== "string" || appKey.length === 0)
+    throw Error("[auth] config.app.key is not set \u2014 email-verification HMAC requires a real APP_KEY. " + "Run `./buddy key:generate` to provision one, or set the APP_KEY env var before booting the app.");
+  return appKey;
+}
+function generateVerificationToken(userId) {
+  const nonce = randomBytes(32).toString("hex"), payload = `${userId}:${nonce}`, hash = createHmac("sha256", getVerificationKey()).update(payload).digest("hex");
+  return { token: nonce, hash };
+}
+function verifyToken(userId, token, storedHash) {
+  const payload = `${userId}:${token}`, hash = createHmac("sha256", getVerificationKey()).update(payload).digest("hex"), a = Buffer.from(hash), b = Buffer.from(storedHash);
+  if (a.length !== b.length)
+    return !1;
+  return timingSafeEqual(a, b);
+}
+function getExpiryMinutes() {
+  const emailVerification = (config.auth ?? {}).emailVerification;
+  if (emailVerification != null && typeof emailVerification === "object") {
+    const ev = emailVerification;
+    if (typeof ev.expire === "number")
+      return ev.expire;
+  }
+  return 60;
+}
+function getVerificationUrl(userId, token) {
+  const base = config.app.url ? `https://${config.app.url}` : `http://localhost:${process.env.PORT || "3000"}`, filled = (config.auth.emailVerification?.url ?? "/verify-email/{id}/{token}").replace("{id}", String(userId)).replace("{token}", token);
+  return /^https?:\/\//.test(filled) ? filled : `${base}${filled.startsWith("/") ? "" : "/"}${filled}`;
+}
+export function isEmailVerified(user) {
+  return user.email_verified_at != null;
+}
+export async function sendVerificationEmail(user) {
+  const { token, hash } = generateVerificationToken(user.id), expiryMinutes = getExpiryMinutes(), expiresAt = new Date(Date.now() + expiryMinutes * 60 * 1000);
+  await db.deleteFrom("email_verifications").where("user_id", "=", user.id).execute();
+  await db.insertInto("email_verifications").values({
+    user_id: user.id,
+    token: hash,
+    expires_at: expiresAt.toISOString()
+  }).executeTakeFirst();
+  const verificationUrl = getVerificationUrl(user.id, token), appName = config.app.name || "Stacks";
+  try {
+    const { html, text } = await template("email-verification", {
+      subject: `Verify Your ${appName} Email Address`,
+      variables: {
+        verificationUrl,
+        expiryMinutes,
+        userName: user.name || user.email
+      }
+    });
+    if (!html && !text)
+      throw Error("email-verification template missing or rendered empty");
+    await mail.send({
+      to: user.email,
+      subject: `Verify Your ${appName} Email Address`,
+      text,
+      html
+    });
+  } catch (templateError) {
+    const errorMessage = templateError instanceof Error ? templateError.message : String(templateError);
+    log.warn(`[email] Email verification template failed, using plain text fallback: ${errorMessage}`);
+    await mail.send({
+      to: user.email,
+      subject: `Verify Your ${appName} Email Address`,
+      text: `Please verify your email address by visiting: ${verificationUrl}
+
+This link expires in ${expiryMinutes} minutes.`
+    });
+  }
+}
+export async function verifyEmail(userId, token) {
+  const record = await db.selectFrom("email_verifications").where("user_id", "=", userId).selectAll().executeTakeFirst();
+  if (!record)
+    return { success: !1, message: "No verification request found. Please request a new verification email." };
+  const expiresAt = new Date(record.expires_at);
+  if (Number.isNaN(expiresAt.getTime()) || new Date > expiresAt) {
+    await db.deleteFrom("email_verifications").where("user_id", "=", userId).execute();
+    return { success: !1, message: "Verification link has expired. Please request a new one." };
+  }
+  if (!verifyToken(userId, token, record.token))
+    return { success: !1, message: "Invalid verification link." };
+  await db.updateTable("users").set({ email_verified_at: new Date().toISOString() }).where("id", "=", userId).executeTakeFirst();
+  await db.deleteFrom("email_verifications").where("user_id", "=", userId).execute();
+  return { success: !0, message: "Email verified successfully." };
+}
+export async function resendVerificationEmail(user) {
+  if (isEmailVerified(user))
+    return { success: !1, message: "Email is already verified." };
+  const existing = await db.selectFrom("email_verifications").where("user_id", "=", user.id).selectAll().executeTakeFirst();
+  if (existing) {
+    const createdAt = new Date(existing.created_at), secondsSince = (Date.now() - createdAt.getTime()) / 1000;
+    if (Number.isNaN(secondsSince))
+      return { success: !1, message: "Please wait a moment before requesting another verification email." };
+    if (secondsSince < 60)
+      return { success: !1, message: `Please wait ${Math.ceil(60 - secondsSince)} seconds before requesting another verification email.` };
+  }
+  await sendVerificationEmail(user);
+  return { success: !0, message: "Verification email sent." };
+}
+export const EmailVerification = {
+  isVerified: isEmailVerified,
+  send: sendVerificationEmail,
+  verify: verifyEmail,
+  resend: resendVerificationEmail
+};

package/dist/gate.d.ts

@@ -0,0 +1,180 @@
+import type { UserModel as OrmUserModel } from '@stacksjs/orm';
+/**
+ * Define a new authorization gate
+ *
+ * @example
+ * define('edit-settings', (user) => user?.isAdmin)
+ * define('update-post', (user, post) => user?.id === post.userId)
+ */
+export declare function define<T = any>(ability: string, callback: GateCallback<T>): void;
+/**
+ * Register a policy for a model
+ *
+ * @example
+ * policy('Post', PostPolicy)
+ * policy(Post, PostPolicy)
+ */
+export declare function policy(model: string | { name: string }, policyClass: new () => Policy): void;
+/**
+ * Register a callback to run before all gate checks
+ *
+ * @example
+ * before((user, _ability) => {
+ *   if (user?.isSuperAdmin) return true // Super admins can do anything
+ *   return null // Continue to normal checks
+ * })
+ */
+export declare function before(callback: (user: UserModel | null, ability: string, args: any[]) => boolean | null | Promise<boolean | null>): void;
+/**
+ * Register a callback to run after all gate checks
+ */
+export declare function after(callback: (user: UserModel | null, ability: string, result: boolean, args: any[]) => boolean | void | Promise<boolean | void>): void;
+/**
+ * Check if the user is allowed to perform an ability
+ *
+ * @example
+ * if (await allows('edit-settings', user)) { ... }
+ * if (await allows('update', user, post)) { ... }
+ */
+export declare function allows(ability: string, user: UserModel | null, ...args: any[]): Promise<boolean>;
+/**
+ * Check if the user is denied from performing an ability
+ *
+ * @example
+ * if (await denies('delete', user, post)) { ... }
+ */
+export declare function denies(ability: string, user: UserModel | null, ...args: any[]): Promise<boolean>;
+/**
+ * Check if the user can perform an ability (alias for allows)
+ */
+export declare function can(ability: string, user: UserModel | null, ...args: any[]): Promise<boolean>;
+/**
+ * Check if the user cannot perform an ability (alias for denies)
+ */
+export declare function cannot(ability: string, user: UserModel | null, ...args: any[]): Promise<boolean>;
+/**
+ * Check if the user can perform any of the given abilities
+ *
+ * @example
+ * if (await any(['update', 'delete'], user, post)) { ... }
+ */
+export declare function any(abilities: string[], user: UserModel | null, ...args: any[]): Promise<boolean>;
+/**
+ * Check if the user can perform all of the given abilities
+ *
+ * @example
+ * if (await all(['view', 'update'], user, post)) { ... }
+ */
+export declare function all(abilities: string[], user: UserModel | null, ...args: any[]): Promise<boolean>;
+/**
+ * Check if the user can perform none of the given abilities
+ */
+export declare function none(abilities: string[], user: UserModel | null, ...args: any[]): Promise<boolean>;
+/**
+ * Authorize an ability or throw an exception
+ *
+ * @example
+ * await authorize('update', user, post) // Throws if not allowed
+ */
+export declare function authorize(ability: string, user: UserModel | null, ...args: any[]): Promise<AuthorizationResponse>;
+/**
+ * Get detailed inspection result for an ability check
+ */
+export declare function inspect(ability: string, user: UserModel | null, ...args: any[]): Promise<AuthorizationResponse>;
+/**
+ * Get a policy instance for a model
+ */
+export declare function getPolicyFor<T = any>(model: T): Policy<T> | null;
+/**
+ * Check if a gate is defined
+ */
+export declare function has(ability: string): boolean;
+/**
+ * Check if a policy is registered for a model
+ */
+export declare function hasPolicy(model: string | { name: string }): boolean;
+/**
+ * Get all defined gate names
+ */
+export declare function abilities(): string[];
+/**
+ * Clear all gates and policies (useful for testing)
+ */
+export declare function flush(): void;
+/**
+ * Gate facade for convenient access
+ */
+export declare const Gate: {
+  define: typeof define;
+  policy: typeof policy;
+  before: typeof before;
+  after: typeof after;
+  allows: typeof allows;
+  denies: typeof denies;
+  can: typeof can;
+  cannot: typeof cannot;
+  any: typeof any;
+  all: typeof all;
+  none: typeof none;
+  authorize: typeof authorize;
+  inspect: typeof inspect;
+  has: typeof has;
+  hasPolicy: typeof hasPolicy;
+  abilities: typeof abilities;
+  getPolicyFor: typeof getPolicyFor;
+  flush: typeof flush;
+  AuthorizationResponse: typeof AuthorizationResponse;
+  AuthorizationException: typeof AuthorizationException
+};
+/**
+ * Policy class interface
+ */
+export declare interface Policy<T = any> {
+  before?(user: UserModel | null, ability: string): boolean | null | Promise<boolean | null>
+  viewAny?(user: UserModel | null): boolean | Promise<boolean> | AuthorizationResponse
+  view?(user: UserModel | null, model: T): boolean | Promise<boolean> | AuthorizationResponse
+  create?(user: UserModel | null): boolean | Promise<boolean> | AuthorizationResponse
+  update?(user: UserModel | null, model: T): boolean | Promise<boolean> | AuthorizationResponse
+  delete?(user: UserModel | null, model: T): boolean | Promise<boolean> | AuthorizationResponse
+  restore?(user: UserModel | null, model: T): boolean | Promise<boolean> | AuthorizationResponse
+  forceDelete?(user: UserModel | null, model: T): boolean | Promise<boolean> | AuthorizationResponse
+  [key: string]: PolicyMethod | undefined
+}
+// Alias the ORM-derived UserModel under the name this module uses internally.
+// The gate API receives authenticated user objects (rows / instances),
+// not the User class constructor.
+declare type UserModel = OrmUserModel;
+/**
+ * Gate callback function type
+ */
+export type GateCallback<T = any> = (_user: UserModel | null, ..._args: T[]) => boolean | Promise<boolean> | AuthorizationResponse;
+/**
+ * Policy method type. The return type intentionally allows `null` so that
+ * a policy's `before()` hook (which returns `null` to delegate to the
+ * underlying ability check) is index-compatible with the catch-all
+ * `[key: string]: PolicyMethod | undefined` signature on `Policy`.
+ */
+export type PolicyMethod<T = any> = (_user: UserModel | null, _model?: T, ..._args: any[]) => boolean | null | Promise<boolean | null> | AuthorizationResponse;
+/**
+ * Authorization response for detailed allow/deny
+ */
+export declare class AuthorizationResponse {
+  readonly isAllowed: boolean;
+  readonly message?: string;
+  readonly code?: string;
+  constructor(allowed: boolean, message?: string, code?: string);
+  static allow(message?: string): AuthorizationResponse;
+  static deny(message?: string, code?: string): AuthorizationResponse;
+  allowed(): boolean;
+  denied(): boolean;
+  authorize(): void;
+}
+/**
+ * Authorization exception
+ */
+export declare class AuthorizationException extends Error {
+  public readonly code?: string;
+  public readonly status?: number;
+  constructor(message?: string, code?: string, status?: number);
+}
+export default Gate;

package/dist/gate.js

@@ -0,0 +1,203 @@
+const RESERVED_POLICY_MEMBERS = new Set([
+  "before",
+  "allow",
+  "deny",
+  "denyIf",
+  "denyUnless",
+  "allowIf",
+  "constructor"
+]);
+
+export class AuthorizationResponse {
+  isAllowed;
+  message;
+  code;
+  constructor(allowed, message, code) {
+    this.isAllowed = allowed;
+    this.message = message;
+    this.code = code;
+  }
+  static allow(message) {
+    return new AuthorizationResponse(!0, message);
+  }
+  static deny(message, code) {
+    return new AuthorizationResponse(!1, message || "This action is unauthorized.", code);
+  }
+  allowed() {
+    return this.isAllowed;
+  }
+  denied() {
+    return !this.isAllowed;
+  }
+  authorize() {
+    if (!this.isAllowed)
+      throw new AuthorizationException(this.message || "This action is unauthorized.", this.code);
+  }
+}
+
+export class AuthorizationException extends Error {
+  code;
+  status;
+  constructor(message = "This action is unauthorized.", code, status = 403) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "AuthorizationException";
+  }
+}
+const state = {
+  gates: new Map,
+  policies: new Map,
+  beforeCallbacks: [],
+  afterCallbacks: []
+};
+export function define(ability, callback) {
+  state.gates.set(ability, callback);
+}
+export function policy(model, policyClass) {
+  const modelName = typeof model === "string" ? model : model.name;
+  state.policies.set(modelName, policyClass);
+}
+export function before(callback) {
+  state.beforeCallbacks.push(callback);
+}
+export function after(callback) {
+  state.afterCallbacks.push(callback);
+}
+export async function allows(ability, user, ...args) {
+  return check(ability, user, ...args);
+}
+export async function denies(ability, user, ...args) {
+  return !await check(ability, user, ...args);
+}
+export async function can(ability, user, ...args) {
+  return check(ability, user, ...args);
+}
+export async function cannot(ability, user, ...args) {
+  return !await check(ability, user, ...args);
+}
+export async function any(abilities, user, ...args) {
+  for (const ability of abilities)
+    if (await check(ability, user, ...args))
+      return !0;
+  return !1;
+}
+export async function all(abilities, user, ...args) {
+  for (const ability of abilities)
+    if (!await check(ability, user, ...args))
+      return !1;
+  return !0;
+}
+export async function none(abilities, user, ...args) {
+  return !await any(abilities, user, ...args);
+}
+export async function authorize(ability, user, ...args) {
+  const result = await inspect(ability, user, ...args);
+  if (!result.isAllowed)
+    throw new AuthorizationException(result.message, result.code);
+  return result;
+}
+export async function inspect(ability, user, ...args) {
+  let response = null;
+  for (const callback of state.beforeCallbacks) {
+    const beforeResult = await callback(user, ability, args);
+    if (beforeResult === !0) {
+      response = AuthorizationResponse.allow();
+      break;
+    }
+    if (beforeResult === !1) {
+      response = AuthorizationResponse.deny();
+      break;
+    }
+  }
+  if (!response)
+    response = await resolveAbility(ability, user, args);
+  for (const callback of state.afterCallbacks) {
+    const afterResult = await callback(user, ability, response.isAllowed, args);
+    if (typeof afterResult === "boolean")
+      return afterResult ? AuthorizationResponse.allow() : AuthorizationResponse.deny();
+  }
+  return response;
+}
+async function resolveAbility(ability, user, args) {
+  const model = args[0];
+  if (model && typeof model === "object") {
+    const modelName = model.constructor?.name, policyClass = state.policies.get(modelName);
+    if (policyClass) {
+      const policyInstance = new policyClass;
+      if (policyInstance.before) {
+        const beforeResult = await policyInstance.before(user, ability);
+        if (beforeResult === !0)
+          return AuthorizationResponse.allow();
+        if (beforeResult === !1)
+          return AuthorizationResponse.deny();
+      }
+      const method = RESERVED_POLICY_MEMBERS.has(ability) ? void 0 : policyInstance[ability];
+      if (typeof method === "function") {
+        const result = await method.call(policyInstance, user, ...args);
+        return normalizeResponse(result ?? !1);
+      }
+    }
+  }
+  const gate = state.gates.get(ability);
+  if (gate)
+    return normalizeResponse(await gate(user, ...args));
+  return AuthorizationResponse.deny(`No gate or policy defined for ability: ${ability}`);
+}
+async function check(ability, user, ...args) {
+  return (await inspect(ability, user, ...args)).isAllowed;
+}
+function normalizeResponse(result) {
+  if (result instanceof AuthorizationResponse)
+    return result;
+  if (typeof result !== "boolean")
+    throw TypeError(`[gate] Policy must return boolean or AuthorizationResponse; got ${typeof result}. If you returned a model/value by mistake, return \`true\`/\`false\` instead.`);
+  return result ? AuthorizationResponse.allow() : AuthorizationResponse.deny();
+}
+export function getPolicyFor(model) {
+  if (!model || typeof model !== "object")
+    return null;
+  const modelName = model.constructor?.name, policyClass = state.policies.get(modelName);
+  if (policyClass)
+    return new policyClass;
+  return null;
+}
+export function has(ability) {
+  return state.gates.has(ability);
+}
+export function hasPolicy(model) {
+  const modelName = typeof model === "string" ? model : model.name;
+  return state.policies.has(modelName);
+}
+export function abilities() {
+  return Array.from(state.gates.keys());
+}
+export function flush() {
+  state.gates.clear();
+  state.policies.clear();
+  state.beforeCallbacks = [];
+  state.afterCallbacks = [];
+}
+export const Gate = {
+  define,
+  policy,
+  before,
+  after,
+  allows,
+  denies,
+  can,
+  cannot,
+  any,
+  all,
+  none,
+  authorize,
+  inspect,
+  has,
+  hasPolicy,
+  abilities,
+  getPolicyFor,
+  flush,
+  AuthorizationResponse,
+  AuthorizationException
+};
+export default Gate;

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+export type { SeedDefaultRolesResult } from './rbac-seed';
+export * from './authentication';
+export * from './authenticator';
+export * from './client';
+export * from './middleware';
+export * from './rate-limiter';
+// WebAuthn/Passkey support (now using ts-auth - no external dependencies)
+export * from './passkey';
+export * from './password/reset';
+export * from './register';
+export * from './user';
+// Token management (Laravel Passport-style)
+export * from './tokens';
+// Authorization Gates & Policies (Laravel-style)
+export * from './gate';
+export * from './policy';
+export * from './authorizable';
+// Role-Based Access Control (RBAC)
+export * from './rbac';
+export { createBqbRbacStore } from './rbac-store-bqb';
+export { DEFAULT_ROLE_PACKS, seedDefaultRoles } from './rbac-seed';
+// Email Verification
+export * from './email-verification';
+// Session-based Authentication (SPA Cookie Auth)
+export * from './session-auth';
+// TOTP (Two-Factor Authentication) - re-export from ts-auth
+export {
+  generateTOTP,
+  verifyTOTP,
+  generateTOTPSecret,
+  totpKeyUri,
+} from '@stacksjs/ts-auth';
+// TOTP setup/enable/disable + login-challenge persistence
+export * from './two-factor';
+// Team resolution from auth credentials (dashboard-form scoping)
+export * from './team';

package/dist/index.js

@@ -0,0 +1,26 @@
+export * from "./authentication";
+export * from "./authenticator";
+export * from "./client";
+export * from "./middleware";
+export * from "./rate-limiter";
+export * from "./passkey";
+export * from "./password/reset";
+export * from "./register";
+export * from "./user";
+export * from "./tokens";
+export * from "./gate";
+export * from "./policy";
+export * from "./authorizable";
+export * from "./rbac";
+export { createBqbRbacStore } from "./rbac-store-bqb";
+export { DEFAULT_ROLE_PACKS, seedDefaultRoles } from "./rbac-seed";
+export * from "./email-verification";
+export * from "./session-auth";
+export {
+  generateTOTP,
+  verifyTOTP,
+  generateTOTPSecret,
+  totpKeyUri
+} from "@stacksjs/ts-auth";
+export * from "./two-factor";
+export * from "./team";

package/dist/internal-constants.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Internal constants shared across the auth package.
+ *
+ * Lives in its own file so consumers like `authentication.ts` and
+ * `session-auth.ts` can pull the same literal without re-declaring it
+ * (stacksjs/stacks#1861 L-1).
+ */
+/**
+ * Pre-computed bcrypt hash of nothing — used to keep timing constant
+ * when the lookup-by-email half of a login fails. Without it, the
+ * "user not found" branch would short-circuit fast and the "wrong
+ * password" branch would always pay the bcrypt cost, leaking
+ * "does this email exist?" via response time.
+ *
+ * The hash itself is intentionally non-verifiable: nothing the
+ * attacker types will ever match it, so the dummy compare always
+ * returns false but spends the same CPU as a real one would.
+ */
+export declare const DUMMY_BCRYPT_HASH: '$2b$12$000000000000000000000uGByljkdFkOJRCRiYZGFOAstyLlSgTSW';

package/dist/internal-constants.js

@@ -0,0 +1 @@
+export const DUMMY_BCRYPT_HASH = "$2b$12$000000000000000000000uGByljkdFkOJRCRiYZGFOAstyLlSgTSW";

package/dist/middleware.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Built-in auth middleware handler
+ * Validates bearer token and sets the authenticated user on Auth
+ */
+export declare function authMiddleware(request: any): Promise<void>;
+/**
+ * Auth middleware object with handle method (for compatibility with middleware loader)
+ * @defaultValue `{ name: 'auth' }`
+ */
+export declare const authMiddlewareHandler: {
+  /** @defaultValue 'auth' */
+  name: string;
+  handle: unknown
+};

package/dist/middleware.js

@@ -0,0 +1,28 @@
+import { Auth } from "./authentication";
+export async function authMiddleware(request) {
+  let bearerToken = request.bearerToken?.();
+  if (!bearerToken) {
+    const authHeader = request.headers?.get?.("authorization") || request.headers?.get?.("Authorization");
+    if (authHeader && authHeader.startsWith("Bearer "))
+      bearerToken = authHeader.substring(7);
+  }
+  if (!bearerToken) {
+    const error = Error("No authentication token provided.");
+    error.statusCode = 401;
+    throw error;
+  }
+  const user = await Auth.getUserFromToken(bearerToken);
+  if (!user) {
+    const error = Error("Invalid or expired authentication token.");
+    error.statusCode = 401;
+    throw error;
+  }
+  Auth.setUser(user);
+  request._authenticatedUser = user;
+  const accessToken = await Auth.currentAccessToken();
+  request._currentAccessToken = accessToken;
+}
+export const authMiddlewareHandler = {
+  name: "auth",
+  handle: authMiddleware
+};