@stacksjs/auth 0.70.88 → 0.70.90

package/dist/passkey.d.ts

@@ -0,0 +1,97 @@
+import { User } from '@stacksjs/orm';
+import type { Insertable } from '@stacksjs/database';
+import type { VerifiedRegistrationResponse } from '@stacksjs/ts-auth';
+// Re-export WebAuthn types from ts-auth
+export type {
+  VerifiedRegistrationResponse,
+  VerifiedAuthenticationResponse,
+  RegistrationCredential,
+  AuthenticationCredential,
+  PublicKeyCredentialCreationOptions,
+  PublicKeyCredentialRequestOptions,
+  RegistrationOptions,
+  AuthenticationOptions,
+} from '@stacksjs/ts-auth';
+export declare function getUserPasskeys(userId: number): Promise<PasskeyAttribute[]>;
+export declare function getUserPasskey(userId: number, passkeyId: string): Promise<PasskeyAttribute | undefined>;
+/**
+ * Persist the post-verification authenticator counter and refresh the
+ * passkey's last-used timestamp. WebAuthn's anti-cloning guarantee
+ * depends on the relying party rejecting any authentication whose
+ * `newCounter` is **not strictly greater** than the stored value —
+ * authenticators monotonically increment their counter on every use,
+ * so a counter that doesn't advance (or goes backwards) signals a
+ * cloned or replayed credential.
+ *
+ * Returns `true` when the counter was updated successfully; `false`
+ * when the new counter is not greater than the stored one (the
+ * authentication MUST be rejected by the caller in that case).
+ * stacksjs/stacks#1861 A-4.
+ */
+export declare function updatePasskeyCounter(userId: number, passkeyId: string, newCounter: number): Promise<boolean>;
+export declare function setCurrentRegistrationOptions(user: UserModel, verified: VerifiedRegistrationResponse): Promise<void>;
+/**
+ * Persist a server-issued WebAuthn challenge for the given user +
+ * purpose. Deletes any prior challenge for the same (user, purpose)
+ * pair so a fresh `generateOptions` invalidates the previous one.
+ *
+ * The unique index on `(user_id, purpose)` enforces single-outstanding
+ * at the DB layer; this delete makes the upsert safe even on installs
+ * that ran an earlier auth:setup before the unique index existed.
+ */
+export declare function storeWebAuthnChallenge(userId: number, challenge: string | Uint8Array, purpose: WebAuthnChallengePurpose, ttlSeconds?: number): Promise<void>;
+/**
+ * Read + delete (single-use) a WebAuthn challenge for the given user
+ * + purpose. Returns `null` when no outstanding challenge exists or
+ * when the stored challenge has expired.
+ *
+ * Single-use semantics matter: a successful verify must invalidate
+ * the challenge so a captured assertion can't be replayed even within
+ * the TTL window. Callers MUST treat a `null` return as a verification
+ * failure.
+ */
+export declare function consumeWebAuthnChallenge(userId: number, purpose: WebAuthnChallengePurpose): Promise<Uint8Array | null>;
+export declare interface PasskeyAttribute {
+  id: string
+  cred_public_key: string
+  user_id: number
+  webauthn_user_id: string
+  counter: number
+  credential_type: string
+  device_type: string
+  backup_eligible: boolean
+  backup_status: boolean
+  transports?: string
+  created_at?: Date
+  last_used_at: string
+}
+declare type UserModel = NonNullable<Awaited<ReturnType<typeof User.find>>>;
+declare type PasskeyInsertable = Insertable<PasskeyAttribute>;
+// =============================================================================
+// WebAuthn challenge persistence (stacksjs/stacks#1866)
+// =============================================================================
+//
+// WebAuthn relying parties MUST verify the assertion's challenge
+// against a server-issued nonce. Previously Stacks returned the
+// challenge in `generateOptions` and trusted the client to echo it
+// back on verify — so any attacker who captured the assertion AND the
+// challenge could replay the response. Persisting the challenge
+// server-side and consuming it on verify closes that gap.
+//
+// The default TTL is 5 minutes — long enough for slow biometric
+// flows, short enough to bound the replay window. Override per-call
+// via the `ttlSeconds` parameter.
+export type WebAuthnChallengePurpose = 'registration' | 'authentication';
+// Re-export WebAuthn functions from ts-auth
+export {
+  generateRegistrationOptions,
+  generateAuthenticationOptions,
+  verifyRegistrationResponse,
+  verifyAuthenticationResponse,
+  // Browser-side functions (for client use)
+  startRegistration,
+  startAuthentication,
+  browserSupportsWebAuthn,
+  browserSupportsWebAuthnAutofill,
+  platformAuthenticatorIsAvailable,
+} from '@stacksjs/ts-auth';

package/dist/passkey.js

@@ -0,0 +1,76 @@
+import { Buffer } from "node:buffer";
+import { db } from "@stacksjs/database";
+import { User } from "@stacksjs/orm";
+export {
+  generateRegistrationOptions,
+  generateAuthenticationOptions,
+  verifyRegistrationResponse,
+  verifyAuthenticationResponse,
+  startRegistration,
+  startAuthentication,
+  browserSupportsWebAuthn,
+  browserSupportsWebAuthnAutofill,
+  platformAuthenticatorIsAvailable
+} from "@stacksjs/ts-auth";
+export async function getUserPasskeys(userId) {
+  return await db.selectFrom("passkeys").selectAll().where("user_id", "=", userId).execute();
+}
+export async function getUserPasskey(userId, passkeyId) {
+  return await db.selectFrom("passkeys").selectAll().where("id", "=", passkeyId).where("user_id", "=", userId).executeTakeFirst();
+}
+export async function updatePasskeyCounter(userId, passkeyId, newCounter) {
+  const passkey = await getUserPasskey(userId, passkeyId);
+  if (!passkey)
+    return !1;
+  const stored = Number(passkey.counter ?? 0);
+  if (newCounter <= stored && !(newCounter === 0 && stored === 0))
+    return !1;
+  await db.updateTable("passkeys").set({ counter: newCounter, last_used_at: formatDateTime() }).where("id", "=", passkeyId).where("user_id", "=", userId).execute();
+  return !0;
+}
+export async function setCurrentRegistrationOptions(user, verified) {
+  const credentialId = verified.registrationInfo?.credential.id, credentialPublicKey = verified.registrationInfo?.credential.publicKey;
+  if (!credentialId)
+    throw Error("[auth/passkey] WebAuthn registration response is missing credential.id");
+  if (!credentialPublicKey)
+    throw Error("[auth/passkey] WebAuthn registration response is missing credential.publicKey");
+  const passkeyData = {
+    id: credentialId,
+    cred_public_key: JSON.stringify(credentialPublicKey),
+    user_id: user.id,
+    webauthn_user_id: user.email || "",
+    counter: verified.registrationInfo?.credential.counter || 0,
+    credential_type: verified.registrationInfo?.credentialType || "",
+    device_type: verified.registrationInfo?.credentialDeviceType || "",
+    backup_eligible: !1,
+    backup_status: verified.registrationInfo?.credentialBackedUp || !1,
+    transports: JSON.stringify(["internal"]),
+    last_used_at: formatDateTime()
+  };
+  await db.insertInto("passkeys").values(passkeyData).executeTakeFirstOrThrow();
+}
+function formatDateTime() {
+  const date = new Date, pad = (num) => String(num).padStart(2, "0"), year = date.getFullYear(), month = pad(date.getMonth() + 1), day = pad(date.getDate()), hours = pad(date.getHours()), minutes = pad(date.getMinutes()), seconds = pad(date.getSeconds());
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
+}
+const DEFAULT_CHALLENGE_TTL_SECONDS = 300;
+export async function storeWebAuthnChallenge(userId, challenge, purpose, ttlSeconds = DEFAULT_CHALLENGE_TTL_SECONDS) {
+  const expiresAt = new Date(Date.now() + ttlSeconds * 1000).toISOString(), encodedChallenge = typeof challenge === "string" ? challenge : Buffer.from(challenge).toString("base64url");
+  await db.deleteFrom("webauthn_challenges").where("user_id", "=", userId).where("purpose", "=", purpose).execute();
+  await db.insertInto("webauthn_challenges").values({
+    user_id: userId,
+    challenge: encodedChallenge,
+    purpose,
+    expires_at: expiresAt
+  }).execute();
+}
+export async function consumeWebAuthnChallenge(userId, purpose) {
+  const row = await db.selectFrom("webauthn_challenges").where("user_id", "=", userId).where("purpose", "=", purpose).selectAll().executeTakeFirst();
+  if (!row)
+    return null;
+  await db.deleteFrom("webauthn_challenges").where("user_id", "=", userId).where("purpose", "=", purpose).execute();
+  const expiresAt = row.expires_at ? new Date(String(row.expires_at)).getTime() : 0;
+  if (Date.now() > expiresAt)
+    return null;
+  return Buffer.from(String(row.challenge), "base64url");
+}

package/dist/password/reset.d.ts

@@ -0,0 +1,10 @@
+export declare function passwordResets(email: string): PasswordResetActions;
+export declare interface PasswordResetResult {
+  success: boolean
+  message?: string
+}
+export declare interface PasswordResetActions {
+  sendEmail: () => Promise<void>
+  verifyToken: (token: string) => Promise<boolean>
+  resetPassword: (token: string, newPassword: string) => Promise<PasswordResetResult>
+}

package/dist/password/reset.js

@@ -0,0 +1,156 @@
+import { randomBytes } from "node:crypto";
+import { config } from "@stacksjs/config";
+import { db } from "@stacksjs/database";
+import { mail, template } from "@stacksjs/email";
+import { log } from "@stacksjs/logging";
+import { formatDate } from "@stacksjs/orm";
+import { makeHash, verifyHash } from "@stacksjs/security";
+import { sessionDestroyAll } from "../session-auth";
+import { revokeAllTokens } from "../tokens";
+function getTokenExpireMinutes() {
+  return config.auth.passwordReset?.expire ?? 60;
+}
+function isWithinExpiry(row) {
+  const explicit = row.expires_at;
+  if (typeof explicit === "string" || explicit instanceof Date)
+    return new Date(explicit).getTime() > Date.now();
+  const created = row.created_at;
+  if (typeof created === "string" || created instanceof Date) {
+    const expireMinutes = getTokenExpireMinutes();
+    return new Date(created).getTime() + expireMinutes * 60000 > Date.now();
+  }
+  return !1;
+}
+async function sendPasswordChangedNotification(userEmail) {
+  const appName = config.app.name || "Stacks", supportEmail = config.app.supportEmail || config.email?.from?.address || "", changedAt = new Date().toLocaleString("en-US", {
+    dateStyle: "full",
+    timeStyle: "short"
+  });
+  try {
+    const { html, text } = await template("password-changed", {
+      subject: `Your ${appName} password has been changed`,
+      variables: {
+        changedAt,
+        supportEmail
+      }
+    });
+    if (!html && !text) {
+      await mail.send({
+        to: userEmail,
+        subject: `Your ${appName} password has been changed`,
+        text: `Your ${appName} password was changed on ${changedAt}.${supportEmail ? ` If this wasn't you, contact ${supportEmail}.` : ""}`
+      });
+      return;
+    }
+    await mail.send({
+      to: userEmail,
+      subject: `Your ${appName} password has been changed`,
+      text,
+      html
+    });
+  } catch (error) {
+    console.error("[PasswordReset] Failed to send password changed notification:", error);
+  }
+}
+export function passwordResets(email) {
+  function generateResetToken() {
+    return randomBytes(32).toString("hex");
+  }
+  async function createResetToken() {
+    const token = generateResetToken(), hashedToken = await makeHash(token, { algorithm: "bcrypt" }), expireMinutes = getTokenExpireMinutes(), expiresAt = new Date(Date.now() + expireMinutes * 60000).toISOString();
+    await db.deleteFrom("password_resets").where("email", "=", email).execute();
+    await db.insertInto("password_resets").values({
+      email,
+      token: hashedToken,
+      expires_at: expiresAt
+    }).executeTakeFirst();
+    return token;
+  }
+  async function sendEmail() {
+    if (!await db.selectFrom("users").where("email", "=", email).selectAll().executeTakeFirst())
+      return;
+    const token = await createResetToken(), expireMinutes = getTokenExpireMinutes(), appName = config.app.name || "Stacks", base = config.app.url ? `https://${config.app.url}` : `http://localhost:${process.env.PORT || "3000"}`, filled = (config.auth.passwordReset?.url ?? "/password/reset/{token}?email={email}").replace("{token}", token).replace("{email}", encodeURIComponent(email)), resetUrl = /^https?:\/\//.test(filled) ? filled : `${base}${filled.startsWith("/") ? "" : "/"}${filled}`;
+    try {
+      const { html, text } = await template("password-reset", {
+        subject: `Reset Your ${appName} Password`,
+        variables: {
+          resetUrl,
+          expireMinutes
+        }
+      });
+      if (!html && !text)
+        throw Error("password-reset template missing or rendered empty");
+      await mail.send({
+        to: email,
+        subject: `Reset Your ${appName} Password`,
+        text,
+        html
+      });
+    } catch (templateError) {
+      const msg = templateError instanceof Error ? templateError.message : String(templateError);
+      console.warn(`[PasswordReset] template render failed, sending plain-text fallback: ${msg}`);
+      await mail.send({
+        to: email,
+        subject: `Reset Your ${appName} Password`,
+        text: `Reset your password by visiting: ${resetUrl}
+
+This link expires in ${expireMinutes} minutes. If you didn't request this, you can safely ignore this email.`
+      });
+    }
+  }
+  async function verifyToken(token) {
+    const result = await db.selectFrom("password_resets").where("email", "=", email).selectAll().executeTakeFirst();
+    if (!result)
+      return !1;
+    if (!isWithinExpiry(result)) {
+      await db.deleteFrom("password_resets").where("email", "=", email).execute();
+      return !1;
+    }
+    const hashedToken = result.token;
+    return await verifyHash(token, hashedToken);
+  }
+  async function resetPassword(token, newPassword) {
+    const result = await db.transaction(async (rawTrx) => {
+      const trx = rawTrx, resetRecord = await trx.selectFrom("password_resets").where("email", "=", email).selectAll().executeTakeFirst();
+      if (!resetRecord)
+        return { success: !1, message: "Invalid or expired reset token" };
+      if (!isWithinExpiry(resetRecord)) {
+        await trx.deleteFrom("password_resets").where("email", "=", email).execute();
+        return { success: !1, message: "This password reset link has expired. Please request a new one." };
+      }
+      const hashedToken = resetRecord.token;
+      if (!await verifyHash(token, hashedToken))
+        return { success: !1, message: "Invalid or expired reset token" };
+      const user = await trx.selectFrom("users").where("email", "=", email).selectAll().executeTakeFirst();
+      if (!user)
+        return { success: !1, message: "Invalid or expired reset token" };
+      const hashedPassword = await makeHash(newPassword, { algorithm: "bcrypt" });
+      try {
+        await trx.updateTable("users").set({ password: hashedPassword, password_changed_at: formatDate(new Date) }).where("email", "=", email).executeTakeFirst();
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (/password_changed_at|no such column|unknown column/i.test(message)) {
+          log.warn("[PasswordReset] password_changed_at column missing \u2014 run `buddy migrate`; resetting without the credential-version stamp");
+          await trx.updateTable("users").set({ password: hashedPassword }).where("email", "=", email).executeTakeFirst();
+        } else
+          throw err;
+      }
+      await trx.deleteFrom("password_resets").where("email", "=", email).execute();
+      return { success: !0, userId: Number(user.id) };
+    });
+    if (result.success) {
+      await revokeAllTokens(result.userId);
+      await sessionDestroyAll(result.userId);
+      sendPasswordChangedNotification(email).catch((err) => {
+        console.error("[PasswordReset] Failed to send notification:", err);
+      });
+      return { success: !0 };
+    }
+    return result;
+  }
+  return {
+    sendEmail,
+    verifyToken,
+    resetPassword
+  };
+}

package/dist/policy.d.ts

@@ -0,0 +1,33 @@
+import { AuthorizationResponse } from './gate';
+import type { UserModel as OrmUserModel } from '@stacksjs/orm';
+/**
+ * Discover and register policies from app/Policies directory
+ */
+export declare function discoverPolicies(): Promise<void>;
+/**
+ * Register inline gates from Gates.ts
+ */
+export declare function registerGates(): Promise<void>;
+/**
+ * Initialize authorization system
+ */
+export declare function initializeAuthorization(): Promise<void>;
+// Use the row/instance shape from orm so policies operate on the
+// authenticated user object, not the User class constructor.
+declare type UserModel = OrmUserModel;
+export declare abstract class BasePolicy<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;
+  protected allow(message?: string): AuthorizationResponse;
+  protected deny(message?: string, code?: string): AuthorizationResponse;
+  protected denyIf(condition: boolean, message?: string): AuthorizationResponse | boolean;
+  protected denyUnless(condition: boolean, message?: string): AuthorizationResponse | boolean;
+  protected allowIf(condition: boolean, message?: string): AuthorizationResponse | boolean;
+}
+export { AuthorizationResponse };

package/dist/policy.js

@@ -0,0 +1,91 @@
+import { AuthorizationResponse } from "./gate";
+
+export class BasePolicy {
+  allow(message) {
+    return AuthorizationResponse.allow(message);
+  }
+  deny(message, code) {
+    return AuthorizationResponse.deny(message, code);
+  }
+  denyIf(condition, message) {
+    if (condition)
+      return this.deny(message);
+    return !0;
+  }
+  denyUnless(condition, message) {
+    if (!condition)
+      return this.deny(message);
+    return !0;
+  }
+  allowIf(condition, message) {
+    if (condition)
+      return this.allow(message);
+    return !1;
+  }
+}
+import { log } from "@stacksjs/logging";
+import * as p from "@stacksjs/path";
+import { policy as registerPolicy } from "./gate";
+export async function discoverPolicies() {
+  const { fs } = await import("@stacksjs/storage"), policiesDir = p.appPath("Policies");
+  if (!fs.existsSync(policiesDir)) {
+    log.debug("No Policies directory found");
+    return;
+  }
+  try {
+    const mappings = (await import(p.appPath("Gates.ts"))).policies || {};
+    for (const [modelName, config] of Object.entries(mappings)) {
+      const policyFile = typeof config === "string" ? config : config.policy, policyPath = `${policiesDir}/${policyFile}.ts`;
+      if (fs.existsSync(policyPath)) {
+        const policyModule = await import(policyPath), PolicyClass = policyModule.default || policyModule[policyFile];
+        if (PolicyClass) {
+          registerPolicy(modelName, PolicyClass);
+          log.debug(`Registered policy: ${policyFile} for ${modelName}`);
+        }
+      }
+    }
+  } catch {
+    log.debug("No Gates.ts found, using convention-based discovery");
+  }
+  const policyFiles = fs.readdirSync(policiesDir).filter((file) => file.endsWith("Policy.ts"));
+  for (const file of policyFiles) {
+    const policyName = file.replace(".ts", ""), modelName = policyName.replace("Policy", ""), policyPath = `${policiesDir}/${file}`;
+    try {
+      const policyModule = await import(policyPath), PolicyClass = policyModule.default || policyModule[policyName];
+      if (PolicyClass) {
+        registerPolicy(modelName, PolicyClass);
+        log.debug(`Auto-discovered policy: ${policyName} for ${modelName}`);
+      }
+    } catch (error) {
+      log.error(`Failed to load policy ${policyName}:`, error);
+    }
+  }
+}
+export async function registerGates() {
+  const { define, before, after } = await import("./gate");
+  try {
+    const gatesModule = await import(p.appPath("Gates.ts")), gates = gatesModule.gates || gatesModule.default?.gates || {};
+    for (const [ability, callback] of Object.entries(gates))
+      if (typeof callback === "function") {
+        define(ability, callback);
+        log.debug(`Registered gate: ${ability}`);
+      }
+    const beforeCallbacks = gatesModule.before || gatesModule.default?.before || [];
+    for (const callback of beforeCallbacks)
+      if (typeof callback === "function")
+        before(callback);
+    const afterCallbacks = gatesModule.after || gatesModule.default?.after || [];
+    for (const callback of afterCallbacks)
+      if (typeof callback === "function")
+        after(callback);
+    log.debug("Gates registered successfully");
+  } catch {
+    log.debug("No Gates.ts found or failed to load");
+  }
+}
+export async function initializeAuthorization() {
+  await registerGates();
+  await discoverPolicies();
+}
+
+export { AuthorizationResponse };

package/dist/rate-limiter.d.ts

@@ -0,0 +1,44 @@
+export declare interface RateLimitEntry {
+  attempts: number
+  lockedUntil: number
+}
+/**
+ * Pluggable backing store for the auth rate limiter.
+ *
+ * Methods may be sync or async — the limiter awaits them either way. The
+ * default {@link MemoryStore} is process-local (fine for single-instance and
+ * dev). On a horizontally-scaled deployment the in-memory store is trivially
+ * bypassed by spreading attempts across instances, so production should swap
+ * in a shared store via `RateLimiter.useSharedStore()` (cache-backed; becomes
+ * cluster-wide when the cache driver is Redis) or a custom `useStore()`.
+ */
+export declare interface RateLimiterStore {
+  get: (key: string) => Promise<RateLimitEntry | undefined> | RateLimitEntry | undefined
+  set: (key: string, entry: RateLimitEntry, ttlMs: number) => Promise<void> | void
+  delete: (key: string) => Promise<void> | void
+}
+/** Process-local store — the default. */
+declare class MemoryStore implements RateLimiterStore {
+  get(key: string): RateLimitEntry | undefined;
+  set(key: string, entry: RateLimitEntry): void;
+  delete(key: string): void;
+}
+/**
+ * Cache-backed store. Cross-instance when the configured cache driver is
+ * Redis; otherwise behaves like an in-memory store with TTL eviction. Entries
+ * carry a TTL so attempts decay automatically — no separate eviction pass.
+ */
+declare class CacheStore implements RateLimiterStore {
+  get(key: string): Promise<RateLimitEntry | undefined>;
+  set(key: string, entry: RateLimitEntry, ttlMs: number): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+export declare class RateLimiter {
+  static useStore(custom: RateLimiterStore): void;
+  static useSharedStore(): void;
+  static useMemoryStore(): void;
+  static isRateLimited(email: string): Promise<boolean>;
+  static recordFailedAttempt(email: string): Promise<void>;
+  static resetAttempts(email: string): Promise<void>;
+  static validateAttempt(email: string): Promise<void>;
+}

package/dist/rate-limiter.js

@@ -0,0 +1,91 @@
+import { HttpError } from "@stacksjs/error-handling";
+const MAX_ATTEMPTS = 5, LOCKOUT_DURATION = 900000, MAX_STORE_SIZE = 1e4, EVICTION_INTERVAL = 300000;
+
+class MemoryStore {
+  store = new Map;
+  lastEviction = Date.now();
+  evict() {
+    const now = Date.now(), intervalElapsed = now - this.lastEviction >= EVICTION_INTERVAL, overCapacity = this.store.size >= MAX_STORE_SIZE;
+    if (!intervalElapsed && !overCapacity)
+      return;
+    this.lastEviction = now;
+    for (const [key, value] of this.store)
+      if (value.lockedUntil > 0 && value.lockedUntil <= now)
+        this.store.delete(key);
+      else if (value.lockedUntil === 0 && value.attempts === 0)
+        this.store.delete(key);
+  }
+  get(key) {
+    this.evict();
+    return this.store.get(key);
+  }
+  set(key, entry) {
+    this.store.set(key, entry);
+  }
+  delete(key) {
+    this.store.delete(key);
+  }
+}
+
+class CacheStore {
+  prefix = "auth:ratelimit:";
+  async get(key) {
+    const { cache } = await import("@stacksjs/cache"), raw = await cache.get(`${this.prefix}${key}`);
+    if (raw == null)
+      return;
+    try {
+      return typeof raw === "string" ? JSON.parse(raw) : raw;
+    } catch {
+      return;
+    }
+  }
+  async set(key, entry, ttlMs) {
+    const { cache } = await import("@stacksjs/cache");
+    await cache.set(`${this.prefix}${key}`, JSON.stringify(entry), Math.ceil(ttlMs / 1000));
+  }
+  async delete(key) {
+    const { cache } = await import("@stacksjs/cache");
+    await cache.remove(`${this.prefix}${key}`);
+  }
+}
+let store = new MemoryStore;
+
+export class RateLimiter {
+  static useStore(custom) {
+    store = custom;
+  }
+  static useSharedStore() {
+    store = new CacheStore;
+  }
+  static useMemoryStore() {
+    store = new MemoryStore;
+  }
+  static async isRateLimited(email) {
+    email = email.toLowerCase();
+    const now = Date.now(), userAttempts = await store.get(email);
+    if (!userAttempts)
+      return !1;
+    if (userAttempts.lockedUntil > 0 && userAttempts.lockedUntil <= now) {
+      await store.delete(email);
+      return !1;
+    }
+    return userAttempts.lockedUntil > 0;
+  }
+  static async recordFailedAttempt(email) {
+    email = email.toLowerCase();
+    const now = Date.now(), userAttempts = await store.get(email) || { attempts: 0, lockedUntil: 0 };
+    userAttempts.attempts++;
+    if (userAttempts.attempts >= MAX_ATTEMPTS) {
+      userAttempts.lockedUntil = now + LOCKOUT_DURATION;
+      userAttempts.attempts = 0;
+    }
+    await store.set(email, userAttempts, LOCKOUT_DURATION);
+  }
+  static async resetAttempts(email) {
+    await store.delete(email.toLowerCase());
+  }
+  static async validateAttempt(email) {
+    if (await this.isRateLimited(email))
+      throw new HttpError(429, "Too many login attempts. Please try again later.");
+  }
+}

package/dist/rbac-seed.d.ts

@@ -0,0 +1,24 @@
+import type { RoleRecord } from './rbac';
+/**
+ * Idempotently seed the three default role packs. Existing role records
+ * with the same `(name, guard_name)` are left untouched.
+ *
+ * Throws only if the underlying `createRole` throws for a reason other
+ * than a unique-constraint race (the BqbRbacStore's `swallowDuplicate`
+ * already handles that case). Caller should typically log the error and
+ * surface it — a missing roles table means the migrations haven't run
+ * yet, which is a different bug than a seeder failure.
+ */
+export declare function seedDefaultRoles(): Promise<SeedDefaultRolesResult>;
+/**
+ * The role packs every Stacks install starts with. `useRole()`'s built-in
+ * predicates (`isAdmin`, `isDev`, `isClient`) check these names verbatim,
+ * so renaming them in a project effectively unbinds the composable from
+ * its defaults — that's fine, but obvious to readers.
+ * @defaultValue `[ { name: 'admin', guard_name: 'web', description: 'Full access. Sees every dashboard surface, every model, every infra control.', }, { name: 'dev', guard_name: 'web', description: 'Developer / infra. Sees dev-mode surfaces (CI, query inspector, runner alerts) but not billing/admin-only management.', }, { name: 'client', guard_name: 'web', description: 'End user / client. Sees content, orders, profile, billing — no dev tools, no infra surfaces.', }, ]`
+ */
+export declare const DEFAULT_ROLE_PACKS: Array<{ name: string, guard_name: string, description: string }>;
+export declare interface SeedDefaultRolesResult {
+  created: RoleRecord[]
+  skipped: Array<{ name: string, guard_name: string, reason: 'already_exists' }>
+}

package/dist/rbac-seed.js

@@ -0,0 +1,30 @@
+import { createRole, findRole } from "./rbac";
+export const DEFAULT_ROLE_PACKS = [
+  {
+    name: "admin",
+    guard_name: "web",
+    description: "Full access. Sees every dashboard surface, every model, every infra control."
+  },
+  {
+    name: "dev",
+    guard_name: "web",
+    description: "Developer / infra. Sees dev-mode surfaces (CI, query inspector, runner alerts) but not billing/admin-only management."
+  },
+  {
+    name: "client",
+    guard_name: "web",
+    description: "End user / client. Sees content, orders, profile, billing \u2014 no dev tools, no infra surfaces."
+  }
+];
+export async function seedDefaultRoles() {
+  const created = [], skipped = [];
+  for (const pack of DEFAULT_ROLE_PACKS) {
+    if (await findRole(pack.name, pack.guard_name)) {
+      skipped.push({ name: pack.name, guard_name: pack.guard_name, reason: "already_exists" });
+      continue;
+    }
+    const role = await createRole(pack.name, pack.guard_name, pack.description);
+    created.push(role);
+  }
+  return { created, skipped };
+}