@stacksjs/auth 0.70.23 → 0.70.26

package/dist/src/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 = InstanceType<typeof User>;
+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/src/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/src/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/src/client.d.ts

@@ -0,0 +1,2 @@
+import type { Result } from '@stacksjs/error-handling';
+export declare function createPersonalAccessClient(): Promise<Result<string, never>>;

package/dist/src/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
+}

package/dist/src/gate.d.ts

@@ -0,0 +1,161 @@
+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: {
+  
+};
+/**
+ * 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/src/index.d.ts

@@ -0,0 +1,29 @@
+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';
+// 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';

package/dist/src/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/src/passkey.d.ts

@@ -0,0 +1,46 @@
+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>;
+export declare function setCurrentRegistrationOptions(user: UserModel, verified: VerifiedRegistrationResponse): Promise<void>;
+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 = InstanceType<typeof User>;
+declare type PasskeyInsertable = Insertable<PasskeyAttribute>;
+// 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/src/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/src/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/src/rate-limiter.d.ts

@@ -0,0 +1,6 @@
+export declare class RateLimiter {
+  static isRateLimited(email: string): boolean;
+  static recordFailedAttempt(email: string): void;
+  static resetAttempts(email: string): void;
+  static validateAttempt(email: string): void;
+}