@stacksjs/auth 0.70.88 → 0.70.91

package/dist/authentication.d.ts

@@ -0,0 +1,43 @@
+import { User } from '@stacksjs/orm';
+import type { AuthCredentials, AuthToken, NewAccessToken, PersonalAccessToken, TokenCreateOptions } from '@stacksjs/types';
+declare type UserModel = NonNullable<Awaited<ReturnType<typeof User.find>>>;
+export declare class Auth {
+  static attempt(credentials: AuthCredentials): Promise<boolean>;
+  static validate(credentials: AuthCredentials): Promise<boolean>;
+  static login(credentials: AuthCredentials, options?: TokenCreateOptions): Promise<
+    { user: UserModel, token: AuthToken, refreshToken?: string, expiresIn?: number } | null
+  >;
+  static loginUsingId(userId: number, options?: TokenCreateOptions): Promise<
+    { user: UserModel, token: AuthToken, refreshToken?: string, expiresIn?: number } | null
+  >;
+  static logout(): Promise<void>;
+  static user(): Promise<UserModel | undefined>;
+  static check(): Promise<boolean>;
+  static guest(): Promise<boolean>;
+  static id(): Promise<number | undefined>;
+  static setUser(user: UserModel): void;
+  static createTokenForUser(user: UserModel, options?: TokenCreateOptions): Promise<NewAccessToken>;
+  static createToken(user: UserModel, name?: string, abilities?: string[]): Promise<AuthToken>;
+  static requestToken(credentials: AuthCredentials, clientId: number, clientSecret: string): Promise<{ token: AuthToken } | null>;
+  static validateToken(token: string): Promise<boolean>;
+  static getUserFromToken(token: string): Promise<UserModel | undefined>;
+  static currentAccessToken(): Promise<PersonalAccessToken | undefined>;
+  static tokenCan(ability: string): Promise<boolean>;
+  static tokenCant(ability: string): Promise<boolean>;
+  static tokenAbilities(): Promise<string[]>;
+  static tokenCanAll(abilities: string[]): Promise<boolean>;
+  static tokenCanAny(abilities: string[]): Promise<boolean>;
+  static tokens(userId?: number): Promise<PersonalAccessToken[]>;
+  static revokeToken(token: string): Promise<void>;
+  static revokeTokenById(tokenId: number): Promise<void>;
+  static revokeAllTokens(userId?: number): Promise<void>;
+  static revokeOtherTokens(userId?: number): Promise<void>;
+  static pruneExpiredTokens(): Promise<number>;
+  static pruneRevokedTokens(): Promise<number>;
+  static rotateToken(oldToken: string): Promise<AuthToken | null>;
+  static findToken(tokenId: number): Promise<PersonalAccessToken | null>;
+  static once(credentials: AuthCredentials): Promise<boolean>;
+  static guard(_name?: string): typeof Auth;
+  static viaRemember(): boolean;
+  static clearState(): void;
+}

package/dist/authentication.js

@@ -0,0 +1,413 @@
+import { config } from "@stacksjs/config";
+import { db } from "@stacksjs/database";
+import { HttpError } from "@stacksjs/error-handling";
+import { formatDate, User } from "@stacksjs/orm";
+import { getCurrentRequest, request } from "@stacksjs/router";
+import { Buffer } from "node:buffer";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { decrypt, encrypt, verifyHash } from "@stacksjs/security";
+import { log } from "@stacksjs/logging";
+import { DUMMY_BCRYPT_HASH } from "./internal-constants";
+import { RateLimiter } from "./rate-limiter";
+const REQUEST_AUTH_STATE_KEY = Symbol.for("stacks.requestAuthState");
+function authStateOrNull() {
+  const req = getCurrentRequest();
+  if (!req)
+    return null;
+  let state = req[REQUEST_AUTH_STATE_KEY];
+  if (!state) {
+    state = {};
+    req[REQUEST_AUTH_STATE_KEY] = state;
+  }
+  return state;
+}
+function hashToken(token) {
+  return createHash("sha256").update(token).digest("hex");
+}
+import { createToken as createRawToken, getPasswordChangedAt, isIssuedBeforePasswordChange, parseScopes } from "./tokens";
+
+export class Auth {
+  static getBearerToken() {
+    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);
+    }
+    return bearerToken || null;
+  }
+  static parseToken(token) {
+    const firstColonIndex = token.indexOf(":");
+    if (firstColonIndex === -1)
+      return null;
+    const plainToken = token.substring(0, firstColonIndex), encryptedId = token.substring(firstColonIndex + 1);
+    if (!plainToken || !encryptedId)
+      return null;
+    return { plainToken, encryptedId };
+  }
+  static async getClientSecret() {
+    const state = authStateOrNull();
+    if (state?.clientSecret)
+      return state.clientSecret;
+    const client = await this.getPersonalAccessClient();
+    if (state)
+      state.clientSecret = client.secret;
+    return client.secret;
+  }
+  static async encryptTokenId(id) {
+    return await encrypt(String(id));
+  }
+  static async decryptTokenId(encryptedId) {
+    try {
+      return await decrypt(encryptedId);
+    } catch {
+      try {
+        const clientSecret = await this.getClientSecret();
+        return await decrypt(encryptedId, clientSecret);
+      } catch {
+        return null;
+      }
+    }
+  }
+  static async getPersonalAccessClient() {
+    try {
+      const client = await db.selectFrom("oauth_clients").where("personal_access_client", "=", !0).where("revoked", "=", !1).selectAll().executeTakeFirst();
+      if (!client)
+        throw new HttpError(500, "No personal access client found. Please run `./buddy auth:setup` first.");
+      return client;
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("does not exist"))
+        throw new HttpError(500, "OAuth tables not found. Please run `./buddy auth:setup` first.");
+      throw error;
+    }
+  }
+  static async validateClient(clientId, clientSecret) {
+    const client = await db.selectFrom("oauth_clients").where("id", "=", clientId).where("revoked", "=", !1).selectAll().executeTakeFirst(), provided = Buffer.from(clientSecret);
+    if (!client?.secret) {
+      const dummy = Buffer.alloc(Math.max(provided.length, 1)), padded = provided.length > 0 ? provided : Buffer.alloc(1);
+      timingSafeEqual(dummy, padded);
+      return !1;
+    }
+    const stored = String(client.secret);
+    if (stored.startsWith("$2"))
+      return await verifyHash(clientSecret, stored);
+    const storedBuf = Buffer.from(stored);
+    if (storedBuf.length !== provided.length) {
+      timingSafeEqual(storedBuf, storedBuf);
+      return !1;
+    }
+    return timingSafeEqual(storedBuf, provided);
+  }
+  static async getTokenFromId(tokenId) {
+    const result = await db.selectFrom("oauth_access_tokens").where("id", "=", tokenId).selectAll().executeTakeFirst();
+    if (!result)
+      return null;
+    const token = result;
+    return {
+      id: token.id,
+      userId: token.user_id,
+      clientId: token.oauth_client_id,
+      name: token.name || "auth-token",
+      scopes: parseScopes(token.scopes),
+      abilities: parseScopes(token.scopes),
+      expiresAt: token.expires_at ? new Date(String(token.expires_at)) : null,
+      createdAt: token.created_at ? new Date(String(token.created_at)) : new Date,
+      updatedAt: token.updated_at ? new Date(String(token.updated_at)) : new Date,
+      revoked: !!token.revoked
+    };
+  }
+  static async attempt(credentials) {
+    const username = config.auth.username || "email", password = config.auth.password || "password", email = credentials[username];
+    if (!email)
+      return !1;
+    const isRateLimited = await RateLimiter.isRateLimited(email), user = await User.where("email", "=", email).first(), authPass = credentials[password] || "", hashToVerify = user?.password || DUMMY_BCRYPT_HASH, hashCheck = await verifyHash(authPass, hashToVerify);
+    if (isRateLimited)
+      return !1;
+    if (hashCheck && user) {
+      await RateLimiter.resetAttempts(email);
+      const state = authStateOrNull();
+      if (state)
+        state.authUser = user;
+      return !0;
+    }
+    await RateLimiter.recordFailedAttempt(email);
+    return !1;
+  }
+  static async validate(credentials) {
+    const username = config.auth.username || "email", password = config.auth.password || "password", email = credentials[username];
+    if (!email)
+      return !1;
+    const user = await User.where("email", "=", email).first(), authPass = credentials[password] || "", hashToVerify = user?.password || DUMMY_BCRYPT_HASH;
+    return await verifyHash(authPass, hashToVerify) && !!user;
+  }
+  static async login(credentials, options) {
+    const isValid = await this.attempt(credentials), authedUser = authStateOrNull()?.authUser;
+    if (!isValid || !authedUser)
+      return null;
+    const { plainTextToken, refreshToken, expiresIn } = await this.createTokenForUser(authedUser, options);
+    return { user: authedUser, token: plainTextToken, refreshToken, expiresIn };
+  }
+  static async loginUsingId(userId, options) {
+    const user = await User.find(userId);
+    if (!user)
+      return null;
+    const state = authStateOrNull();
+    if (state)
+      state.authUser = user;
+    const { plainTextToken, refreshToken, expiresIn } = await this.createTokenForUser(user, options);
+    return { user, token: plainTextToken, refreshToken, expiresIn };
+  }
+  static async logout() {
+    const bearerToken = this.getBearerToken();
+    if (bearerToken) {
+      const accessToken = await db.selectFrom("oauth_access_tokens").where("token", "=", hashToken(bearerToken)).select(["id"]).executeTakeFirst();
+      if (accessToken)
+        await db.updateTable("oauth_refresh_tokens").set({ revoked: !0 }).where("access_token_id", "=", Number(accessToken.id)).execute();
+      await this.revokeToken(bearerToken);
+    }
+    const state = authStateOrNull();
+    if (state) {
+      state.authUser = void 0;
+      state.currentToken = void 0;
+    }
+  }
+  static async user() {
+    const state = authStateOrNull();
+    if (state?.authUser)
+      return state.authUser;
+    const bearerToken = this.getBearerToken();
+    if (!bearerToken)
+      return;
+    const user = await this.getUserFromToken(bearerToken);
+    if (user && state)
+      state.authUser = user;
+    return user;
+  }
+  static async check() {
+    return await this.user() !== void 0;
+  }
+  static async guest() {
+    return !await this.check();
+  }
+  static async id() {
+    return (await this.user())?.id;
+  }
+  static setUser(user) {
+    const state = authStateOrNull();
+    if (state)
+      state.authUser = user;
+  }
+  static async createTokenForUser(user, options) {
+    const name = options?.name ?? config.auth.defaultTokenName ?? "auth-token", abilities = options?.abilities ?? options?.scopes ?? config.auth.defaultAbilities ?? ["*"], accessTtlMs = options?.expiresInMinutes !== void 0 ? options.expiresInMinutes * 60 * 1000 : config.auth.tokenExpiry ?? 3600000, expiresAt = options?.expiresAt ?? new Date(Date.now() + accessTtlMs), expiresInMinutes = Math.max(1, Math.floor((expiresAt.getTime() - Date.now()) / 60000)), refreshExpiresInDays = options?.refreshExpiresInDays ?? Math.max(1, Math.round((config.auth.refreshTokenExpiry ?? 2592000000) / 86400000));
+    log.debug(`[auth] Creating token for user#${user.id}: ${name}`);
+    const result = await createRawToken(user.id, name, abilities, {
+      expiresInMinutes,
+      withRefreshToken: options?.withRefreshToken !== !1,
+      refreshExpiresInDays
+    }), plainTextToken = result.plainTextToken;
+    return {
+      accessToken: {
+        id: result.accessToken.id,
+        userId: result.accessToken.userId,
+        clientId: result.accessToken.clientId,
+        name: result.accessToken.name,
+        scopes: result.accessToken.scopes,
+        abilities,
+        expiresAt: result.accessToken.expiresAt ?? expiresAt,
+        createdAt: result.accessToken.createdAt,
+        updatedAt: result.accessToken.updatedAt,
+        revoked: result.accessToken.revoked,
+        plainTextToken
+      },
+      plainTextToken,
+      refreshToken: result.refreshToken,
+      expiresIn: result.expiresIn
+    };
+  }
+  static async createToken(user, name = config.auth.defaultTokenName || "auth-token", abilities = config.auth.defaultAbilities || ["*"]) {
+    const { plainTextToken } = await this.createTokenForUser(user, { name, abilities });
+    return plainTextToken;
+  }
+  static async requestToken(credentials, clientId, clientSecret) {
+    if (!await this.validateClient(clientId, clientSecret))
+      throw new HttpError(401, "Invalid client credentials");
+    const isValid = await this.attempt(credentials), authedUser = authStateOrNull()?.authUser;
+    if (!isValid || !authedUser)
+      return null;
+    return { token: await this.createToken(authedUser, "user-auth-token") };
+  }
+  static async validateToken(token) {
+    const hashedPlainToken = hashToken(token), accessToken = await db.selectFrom("oauth_access_tokens").where("token", "=", hashedPlainToken).selectAll().executeTakeFirst();
+    if (!accessToken)
+      return !1;
+    log.debug(`[auth] Token validated for token#${accessToken.id}`);
+    if (accessToken.expires_at && new Date(String(accessToken.expires_at)) < new Date) {
+      await db.deleteFrom("oauth_access_tokens").where("id", "=", accessToken.id).execute();
+      return !1;
+    }
+    if (accessToken.revoked)
+      return !1;
+    if (isIssuedBeforePasswordChange(accessToken.created_at, await getPasswordChangedAt(accessToken.user_id)))
+      return !1;
+    await db.updateTable("oauth_access_tokens").set({ updated_at: formatDate(new Date) }).where("id", "=", accessToken.id).execute();
+    return !0;
+  }
+  static async getUserFromToken(token) {
+    const hashedPlainToken = hashToken(token), accessToken = await db.selectFrom("oauth_access_tokens").where("token", "=", hashedPlainToken).selectAll().executeTakeFirst();
+    if (!accessToken)
+      return;
+    if (accessToken.expires_at && new Date(String(accessToken.expires_at)) < new Date) {
+      await db.deleteFrom("oauth_access_tokens").where("id", "=", accessToken.id).execute();
+      return;
+    }
+    if (accessToken.revoked)
+      return;
+    const stateForToken = authStateOrNull();
+    if (stateForToken)
+      stateForToken.currentToken = await this.getTokenFromId(accessToken.id) ?? void 0;
+    await db.updateTable("oauth_access_tokens").set({ updated_at: formatDate(new Date) }).where("id", "=", accessToken.id).execute();
+    if (!accessToken?.user_id)
+      return;
+    const user = await User.find(accessToken.user_id);
+    if (isIssuedBeforePasswordChange(accessToken.created_at, await getPasswordChangedAt(accessToken.user_id)))
+      return;
+    return user;
+  }
+  static async currentAccessToken() {
+    const state = authStateOrNull();
+    if (state?.currentToken)
+      return state.currentToken;
+    const bearerToken = this.getBearerToken();
+    if (!bearerToken)
+      return;
+    const accessToken = await db.selectFrom("oauth_access_tokens").where("token", "=", hashToken(bearerToken)).select(["id"]).executeTakeFirst();
+    if (!accessToken)
+      return;
+    const token = await this.getTokenFromId(Number(accessToken.id));
+    if (token && state)
+      state.currentToken = token;
+    return token ?? void 0;
+  }
+  static async tokenCan(ability) {
+    const token = await this.currentAccessToken();
+    if (!token)
+      return !1;
+    if (token.abilities.includes("*"))
+      return !0;
+    return token.abilities.includes(ability);
+  }
+  static async tokenCant(ability) {
+    return !await this.tokenCan(ability);
+  }
+  static async tokenAbilities() {
+    return (await this.currentAccessToken())?.abilities ?? [];
+  }
+  static async tokenCanAll(abilities) {
+    const token = await this.currentAccessToken();
+    if (!token)
+      return !1;
+    if (token.abilities.includes("*"))
+      return !0;
+    return abilities.every((a) => token.abilities.includes(a));
+  }
+  static async tokenCanAny(abilities) {
+    const token = await this.currentAccessToken();
+    if (!token)
+      return !1;
+    if (token.abilities.includes("*"))
+      return !0;
+    return abilities.some((a) => token.abilities.includes(a));
+  }
+  static async tokens(userId) {
+    const uid = userId ?? await this.id();
+    if (!uid)
+      return [];
+    return (await db.selectFrom("oauth_access_tokens").where("user_id", "=", uid).where("revoked", "=", !1).selectAll().execute()).map((token) => ({
+      id: Number(token.id),
+      userId: Number(token.user_id),
+      clientId: Number(token.oauth_client_id),
+      name: String(token.name || "auth-token"),
+      scopes: parseScopes(String(token.scopes ?? "")),
+      abilities: parseScopes(String(token.scopes ?? "")),
+      expiresAt: token.expires_at ? new Date(String(token.expires_at)) : null,
+      createdAt: token.created_at ? new Date(String(token.created_at)) : new Date,
+      updatedAt: token.updated_at ? new Date(String(token.updated_at)) : new Date,
+      revoked: !!token.revoked
+    }));
+  }
+  static async revokeToken(token) {
+    await db.updateTable("oauth_access_tokens").set({ revoked: !0, updated_at: formatDate(new Date) }).where("token", "=", hashToken(token)).execute();
+  }
+  static async revokeTokenById(tokenId) {
+    await db.updateTable("oauth_access_tokens").set({ revoked: !0, updated_at: formatDate(new Date) }).where("id", "=", tokenId).execute();
+  }
+  static async revokeAllTokens(userId) {
+    const uid = userId ?? await this.id();
+    if (!uid)
+      return;
+    await db.updateTable("oauth_access_tokens").set({ revoked: !0, updated_at: formatDate(new Date) }).where("user_id", "=", uid).execute();
+  }
+  static async revokeOtherTokens(userId) {
+    const uid = userId ?? await this.id();
+    if (!uid)
+      return;
+    const currentToken = await this.currentAccessToken();
+    if (!currentToken)
+      return;
+    await db.updateTable("oauth_access_tokens").set({ revoked: !0, updated_at: formatDate(new Date) }).where("user_id", "=", uid).where("id", "!=", currentToken.id).execute();
+  }
+  static async pruneExpiredTokens() {
+    const result = await db.deleteFrom("oauth_access_tokens").where("expires_at", "<", formatDate(new Date)).executeTakeFirst();
+    return Number(result?.numDeletedRows) || 0;
+  }
+  static async pruneRevokedTokens() {
+    const result = await db.deleteFrom("oauth_access_tokens").where("revoked", "=", !0).executeTakeFirst();
+    return Number(result?.numDeletedRows) || 0;
+  }
+  static async rotateToken(oldToken) {
+    const { findToken: findRawToken, revokeToken: revokeRawToken } = await import("./tokens"), existing = await findRawToken(oldToken);
+    if (!existing)
+      return null;
+    const remainingMs = existing.expiresAt ? existing.expiresAt.getTime() - Date.now() : config.auth.tokenExpiry ?? 3600000, expiresInMinutes = Math.max(1, Math.floor(remainingMs / 60000));
+    await revokeRawToken(oldToken);
+    const user = await User.find(existing.userId);
+    if (!user)
+      return null;
+    return (await this.createTokenForUser(user, {
+      name: existing.name,
+      abilities: existing.scopes ?? ["*"],
+      expiresInMinutes,
+      withRefreshToken: !1
+    })).plainTextToken;
+  }
+  static async findToken(tokenId) {
+    return this.getTokenFromId(tokenId);
+  }
+  static async once(credentials) {
+    const username = config.auth.username || "email", password = config.auth.password || "password", email = credentials[username];
+    if (!email)
+      return !1;
+    const user = await User.where("email", "=", email).first(), authPass = credentials[password] || "", hashToVerify = user?.password || DUMMY_BCRYPT_HASH;
+    if (await verifyHash(authPass, hashToVerify) && user) {
+      const state = authStateOrNull();
+      if (state)
+        state.authUser = user;
+      return !0;
+    }
+    return !1;
+  }
+  static guard(_name) {
+    return this;
+  }
+  static viaRemember() {
+    return !1;
+  }
+  static clearState() {
+    const state = authStateOrNull();
+    if (state) {
+      state.authUser = void 0;
+      state.currentToken = void 0;
+      state.clientSecret = void 0;
+    }
+  }
+}

package/dist/authenticator.d.ts

@@ -0,0 +1,17 @@
+export declare function generateTwoFactorSecret(): string;
+export declare function generateTwoFactorToken(secret: Secret): Promise<Token>;
+export declare function verifyTwoFactorCode(token: Token, secret: Secret): Promise<boolean>;
+/**
+ * Generate an otpauth:// URI for two-factor authentication
+ *
+ * This URI can be used with any QR code library to generate a scannable
+ * QR code for authenticator apps.
+ *
+ * @param user - User identifier (email or username)
+ * @param service - Service name (e.g., 'StacksJS 2FA')
+ * @param secret - Optional secret (will be generated if not provided)
+ * @returns The otpauth:// URI string
+ */
+export declare function generateTwoFactorUri(user?: string, service?: string, secret?: Secret): string;
+export type Token = string;
+export type Secret = string;

package/dist/authenticator.js

@@ -0,0 +1,14 @@
+import { generateTOTP, generateTOTPSecret, totpKeyUri, verifyTOTP } from "@stacksjs/ts-auth";
+export function generateTwoFactorSecret() {
+  return generateTOTPSecret();
+}
+export async function generateTwoFactorToken(secret) {
+  return generateTOTP({ secret });
+}
+export async function verifyTwoFactorCode(token, secret) {
+  return verifyTOTP(token, { secret });
+}
+export function generateTwoFactorUri(user, service, secret) {
+  const userIdentifier = user || "johndoe@example.com", serviceName = service || "StacksJS 2fa", otpSecret = secret || generateTwoFactorSecret();
+  return totpKeyUri(userIdentifier, serviceName, otpSecret);
+}

package/dist/authorizable.d.ts

@@ -0,0 +1,77 @@
+import { any, can, cannot } from './gate';
+import type { AuthorizationResponse } from './gate';
+import type { UserModel as OrmUserModel } from '@stacksjs/orm';
+/**
+ * Check if a user can perform an ability
+ *
+ * @example
+ * if (await userCan(user, 'edit-settings')) { ... }
+ * if (await userCan(user, 'update', post)) { ... }
+ */
+export declare function userCan(user: UserModel | null, ability: string, ...args: any[]): Promise<boolean>;
+/**
+ * Check if a user cannot perform an ability
+ *
+ * @example
+ * if (await userCannot(user, 'delete', post)) { ... }
+ */
+export declare function userCannot(user: UserModel | null, ability: string, ...args: any[]): Promise<boolean>;
+/**
+ * Check if a user can perform any of the given abilities
+ *
+ * @example
+ * if (await userCanAny(user, ['update', 'delete'], post)) { ... }
+ */
+export declare function userCanAny(user: UserModel | null, abilities: string[], ...args: any[]): Promise<boolean>;
+/**
+ * Check if a user can perform all of the given abilities
+ *
+ * @example
+ * if (await userCanAll(user, ['view', 'update'], post)) { ... }
+ */
+export declare function userCanAll(user: UserModel | null, abilities: string[], ...args: any[]): Promise<boolean>;
+/**
+ * Authorize a user or throw an exception
+ *
+ * @example
+ * await authorizeUser(user, 'update', post) // Throws if not allowed
+ */
+export declare function authorizeUser(user: UserModel | null, ability: string, ...args: any[]): Promise<AuthorizationResponse>;
+/**
+ * Get detailed authorization result
+ *
+ * @example
+ * const result = await inspectUser(user, 'update', post)
+ * if (result.denied()) {
+ *   console.log(result.message)
+ * }
+ */
+export declare function inspectUser(user: UserModel | null, ability: string, ...args: any[]): Promise<AuthorizationResponse>;
+/**
+ * Authorizable trait for user models
+ *
+ * Add authorization methods to a user object
+ *
+ * @example
+ * const authorizedUser = withAuthorization(user)
+ * if (await authorizedUser.can('update', post)) { ... }
+ */
+export declare function withAuthorization<T extends UserModel>(user: T): T & AuthorizableMethods;
+/**
+ * Authorization methods interface
+ */
+export declare interface AuthorizableMethods {
+  can(ability: string, ...args: any[]): Promise<boolean>
+  cannot(ability: string, ...args: any[]): Promise<boolean>
+  canAny(abilities: string[], ...args: any[]): Promise<boolean>
+  canAll(abilities: string[], ...args: any[]): Promise<boolean>
+  authorize(ability: string, ...args: any[]): Promise<AuthorizationResponse>
+}
+// Alias the ORM-derived UserModel under the name the rest of this module
+// expects. Using the row/instance shape (rather than `typeof User`) lets
+// callers pass plain authenticated user objects to the gate helpers.
+declare type UserModel = OrmUserModel;
+/**
+ * Type for a user with authorization methods
+ */
+export type AuthorizableUser<T extends UserModel> = T & AuthorizableMethods;

package/dist/authorizable.js

@@ -0,0 +1,28 @@
+import { all, any, authorize as gateAuthorize, can, cannot, inspect } from "./gate";
+export async function userCan(user, ability, ...args) {
+  return can(ability, user, ...args);
+}
+export async function userCannot(user, ability, ...args) {
+  return cannot(ability, user, ...args);
+}
+export async function userCanAny(user, abilities, ...args) {
+  return any(abilities, user, ...args);
+}
+export async function userCanAll(user, abilities, ...args) {
+  return all(abilities, user, ...args);
+}
+export async function authorizeUser(user, ability, ...args) {
+  return gateAuthorize(ability, user, ...args);
+}
+export async function inspectUser(user, ability, ...args) {
+  return inspect(ability, user, ...args);
+}
+export function withAuthorization(user) {
+  return Object.assign(user, {
+    can: (ability, ...args) => userCan(user, ability, ...args),
+    cannot: (ability, ...args) => userCannot(user, ability, ...args),
+    canAny: (abilities, ...args) => userCanAny(user, abilities, ...args),
+    canAll: (abilities, ...args) => userCanAll(user, abilities, ...args),
+    authorize: (ability, ...args) => authorizeUser(user, ability, ...args)
+  });
+}

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+import type { Result } from '@stacksjs/error-handling';
+/**
+ * Create a personal access OAuth client.
+ *
+ * Idempotent: returns an `err({ code: 'already-exists' })` when a
+ * non-revoked personal access client already exists in the
+ * `oauth_clients` table, rather than inserting a duplicate. The
+ * previous behaviour silently created a second row, which made
+ * `getPersonalAccessClient()` (which `LIMIT 1`s with no `ORDER BY`)
+ * return whichever the DB happened to surface first — racy with
+ * subsequent token mints. See stacksjs/stacks#1860 M-7.
+ *
+ * The plaintext secret is what callers (e.g., `./buddy auth:token`)
+ * surface to the operator — they store it themselves. The DB holds
+ * only the bcrypt hash so a DB compromise doesn't leak usable client
+ * credentials (stacksjs/stacks#1861 M-1).
+ */
+export declare function createPersonalAccessClient(): Promise<Result<string, CreatePersonalAccessClientError>>;
+export declare interface CreatePersonalAccessClientError {
+  code: 'already-exists'
+  message: string
+}

package/dist/client.js

@@ -0,0 +1,26 @@
+import { randomBytes } from "node:crypto";
+import { db } from "@stacksjs/database";
+import { formatDate } from "@stacksjs/orm";
+import { err, HttpError, ok } from "@stacksjs/error-handling";
+import { makeHash } from "@stacksjs/security";
+export async function createPersonalAccessClient() {
+  if ((await db.selectFrom("oauth_clients").where("personal_access_client", "=", !0).where("revoked", "=", !1).select(["id"]).executeTakeFirst())?.id)
+    return err({
+      code: "already-exists",
+      message: "A personal access client already exists. Revoke the existing client (`./buddy auth:revoke-client`) before creating a new one."
+    });
+  const secret = randomBytes(40).toString("hex"), hashedSecret = await makeHash(secret, { algorithm: "bcrypt" });
+  await db.insertInto("oauth_clients").values({
+    name: "Personal Access Client",
+    secret: hashedSecret,
+    provider: "local",
+    redirect: "http://localhost",
+    personal_access_client: !0,
+    password_client: !1,
+    revoked: !1,
+    created_at: formatDate(new Date)
+  }).execute();
+  if (!(await db.selectFrom("oauth_clients").where("secret", "=", hashedSecret).select(["id"]).executeTakeFirst())?.id)
+    throw new HttpError(500, "Failed to create personal access client");
+  return ok(secret);
+}

package/dist/email-verification.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Check if a user's email is verified
+ */
+export declare function isEmailVerified(user: { email_verified_at?: string | Date | null }): boolean;
+/**
+ * Send a verification email to the user
+ */
+export declare function sendVerificationEmail(user: { id: number, email: string, name?: string }): Promise<void>;
+/**
+ * Verify a user's email with the provided token
+ */
+export declare function verifyEmail(userId: number, token: string): Promise<EmailVerificationResult>;
+/**
+ * Resend verification email with rate limiting
+ */
+export declare function resendVerificationEmail(user: { id: number, email: string, name?: string, email_verified_at?: string | Date | null }): Promise<EmailVerificationResult>;
+/**
+ * Email verification facade
+ */
+export declare const EmailVerification: {
+  isVerified: unknown;
+  send: unknown;
+  verify: unknown;
+  resend: unknown
+};
+export declare interface EmailVerificationResult {
+  success: boolean
+  message?: string
+}