@stacksjs/auth 0.70.23 → 0.70.25

package/dist/src/rbac.d.ts

@@ -0,0 +1,219 @@
+import type { UserModel as OrmUserModel } from '@stacksjs/orm';
+/**
+ * Set the RBAC store implementation
+ */
+export declare function setRbacStore(rbacStore: RbacStore): void;
+/**
+ * Flush the RBAC cache
+ */
+export declare function flushRbacCache(): void;
+/**
+ * Create a new role
+ */
+export declare function createRole(name: string, guardName?: string, description?: string): Promise<RoleRecord>;
+/**
+ * Find a role by name
+ */
+export declare function findRole(name: string, guardName?: string): Promise<RoleRecord | null>;
+/**
+ * Delete a role
+ */
+export declare function deleteRole(name: string, guardName?: string): Promise<void>;
+/**
+ * Get all roles
+ */
+export declare function getAllRoles(guardName?: string): Promise<RoleRecord[]>;
+/**
+ * Create a new permission
+ */
+export declare function createPermission(name: string, guardName?: string, description?: string): Promise<PermissionRecord>;
+/**
+ * Find a permission by name
+ */
+export declare function findPermission(name: string, guardName?: string): Promise<PermissionRecord | null>;
+/**
+ * Delete a permission
+ */
+export declare function deletePermission(name: string, guardName?: string): Promise<void>;
+/**
+ * Get all permissions
+ */
+export declare function getAllPermissions(guardName?: string): Promise<PermissionRecord[]>;
+/**
+ * Get all roles for a user
+ */
+export declare function getUserRoles(user: UserModel | { id: number } | number): Promise<RoleRecord[]>;
+/**
+ * Assign a role to a user
+ */
+export declare function assignRole(user: UserModel | { id: number } | number, roleName: string, guardName?: string): Promise<void>;
+/**
+ * Remove a role from a user
+ */
+export declare function removeRole(user: UserModel | { id: number } | number, roleName: string, guardName?: string): Promise<void>;
+/**
+ * Remove all roles from a user
+ */
+export declare function removeAllRoles(user: UserModel | { id: number } | number): Promise<void>;
+/**
+ * Sync roles for a user (replaces all current roles)
+ */
+export declare function syncRoles(user: UserModel | { id: number } | number, roleNames: string[], guardName?: string): Promise<void>;
+/**
+ * Check if a user has a specific role
+ */
+export declare function hasRole(user: UserModel | { id: number } | number, roleName: string, guardName?: string): Promise<boolean>;
+/**
+ * Check if a user has any of the given roles
+ */
+export declare function hasAnyRole(user: UserModel | { id: number } | number, roleNames: string[], guardName?: string): Promise<boolean>;
+/**
+ * Check if a user has all of the given roles
+ */
+export declare function hasAllRoles(user: UserModel | { id: number } | number, roleNames: string[], guardName?: string): Promise<boolean>;
+/**
+ * Get all permissions for a user (direct + via roles)
+ */
+export declare function getUserPermissions(user: UserModel | { id: number } | number): Promise<PermissionRecord[]>;
+/**
+ * Give a direct permission to a user
+ */
+export declare function givePermission(user: UserModel | { id: number } | number, permissionName: string, guardName?: string): Promise<void>;
+/**
+ * Revoke a direct permission from a user
+ */
+export declare function revokePermission(user: UserModel | { id: number } | number, permissionName: string, guardName?: string): Promise<void>;
+/**
+ * Revoke all direct permissions from a user
+ */
+export declare function revokeAllPermissions(user: UserModel | { id: number } | number): Promise<void>;
+/**
+ * Sync direct permissions for a user
+ */
+export declare function syncPermissions(user: UserModel | { id: number } | number, permissionNames: string[], guardName?: string): Promise<void>;
+/**
+ * Check if a user has a specific permission (direct or via role)
+ */
+export declare function hasPermission(user: UserModel | { id: number } | number, permissionName: string, guardName?: string): Promise<boolean>;
+/**
+ * Check if a user has any of the given permissions
+ */
+export declare function hasAnyPermission(user: UserModel | { id: number } | number, permissionNames: string[], guardName?: string): Promise<boolean>;
+/**
+ * Check if a user has all of the given permissions
+ */
+export declare function hasAllPermissions(user: UserModel | { id: number } | number, permissionNames: string[], guardName?: string): Promise<boolean>;
+/**
+ * Get all permissions for a role
+ */
+export declare function getRolePermissions(roleId: number): Promise<PermissionRecord[]>;
+/**
+ * Assign a permission to a role
+ */
+export declare function givePermissionToRole(roleName: string, permissionName: string, guardName?: string): Promise<void>;
+/**
+ * Remove a permission from a role
+ */
+export declare function revokePermissionFromRole(roleName: string, permissionName: string, guardName?: string): Promise<void>;
+/**
+ * Sync permissions for a role
+ */
+export declare function syncRolePermissions(roleName: string, permissionNames: string[], guardName?: string): Promise<void>;
+/**
+ * Add RBAC methods to a user object
+ *
+ * @example
+ * const user = withRbac(authenticatedUser)
+ * if (await user.hasRole('admin')) { ... }
+ * await user.assignRole('editor')
+ */
+export declare function withRbac<T extends UserModel | { id: number }>(user: T): T & RbacMethods;
+/**
+ * RBAC facade for convenient access
+ */
+export declare const Rbac: {
+  setStore: unknown;
+  flushCache: unknown
+};
+export declare interface RoleRecord {
+  id: number
+  name: string
+  guard_name: string
+  description?: string
+  created_at?: string
+  updated_at?: string
+}
+export declare interface PermissionRecord {
+  id: number
+  name: string
+  guard_name: string
+  description?: string
+  created_at?: string
+  updated_at?: string
+}
+export declare interface RolePermissionPivot {
+  role_id: number
+  permission_id: number
+  created_at?: string
+}
+export declare interface UserRolePivot {
+  user_id: number
+  role_id: number
+  created_at?: string
+}
+export declare interface UserPermissionPivot {
+  user_id: number
+  permission_id: number
+  created_at?: string
+}
+/**
+ * RBAC database adapter interface.
+ * Implement this to connect RBAC to your database layer.
+ */
+export declare interface RbacStore {
+  findRoleByName(name: string, guardName?: string): Promise<RoleRecord | null>
+  findRoleById(id: number): Promise<RoleRecord | null>
+  createRole(name: string, guardName?: string, description?: string): Promise<RoleRecord>
+  deleteRole(id: number): Promise<void>
+  getAllRoles(guardName?: string): Promise<RoleRecord[]>
+  findPermissionByName(name: string, guardName?: string): Promise<PermissionRecord | null>
+  findPermissionById(id: number): Promise<PermissionRecord | null>
+  createPermission(name: string, guardName?: string, description?: string): Promise<PermissionRecord>
+  deletePermission(id: number): Promise<void>
+  getAllPermissions(guardName?: string): Promise<PermissionRecord[]>
+  getUserRoles(userId: number): Promise<RoleRecord[]>
+  assignRoleToUser(userId: number, roleId: number): Promise<void>
+  removeRoleFromUser(userId: number, roleId: number): Promise<void>
+  removeAllRolesFromUser(userId: number): Promise<void>
+  syncUserRoles(userId: number, roleIds: number[]): Promise<void>
+  getUserDirectPermissions(userId: number): Promise<PermissionRecord[]>
+  assignPermissionToUser(userId: number, permissionId: number): Promise<void>
+  removePermissionFromUser(userId: number, permissionId: number): Promise<void>
+  removeAllPermissionsFromUser(userId: number): Promise<void>
+  syncUserPermissions(userId: number, permissionIds: number[]): Promise<void>
+  getRolePermissions(roleId: number): Promise<PermissionRecord[]>
+  assignPermissionToRole(roleId: number, permissionId: number): Promise<void>
+  removePermissionFromRole(roleId: number, permissionId: number): Promise<void>
+  syncRolePermissions(roleId: number, permissionIds: number[]): Promise<void>
+}
+// ─── Authorizable Mixin (add to user objects) ───────────────────
+export declare interface RbacMethods {
+  hasRole(roleName: string, guardName?: string): Promise<boolean>
+  hasAnyRole(roleNames: string[], guardName?: string): Promise<boolean>
+  hasAllRoles(roleNames: string[], guardName?: string): Promise<boolean>
+  hasPermission(permissionName: string, guardName?: string): Promise<boolean>
+  hasAnyPermission(permissionNames: string[], guardName?: string): Promise<boolean>
+  hasAllPermissions(permissionNames: string[], guardName?: string): Promise<boolean>
+  getRoles(): Promise<RoleRecord[]>
+  getPermissions(): Promise<PermissionRecord[]>
+  assignRole(roleName: string, guardName?: string): Promise<void>
+  removeRole(roleName: string, guardName?: string): Promise<void>
+  syncRoles(roleNames: string[], guardName?: string): Promise<void>
+  givePermission(permissionName: string, guardName?: string): Promise<void>
+  revokePermission(permissionName: string, guardName?: string): Promise<void>
+  syncPermissions(permissionNames: string[], guardName?: string): Promise<void>
+}
+// Use the row/instance shape from orm so role helpers operate on the
+// authenticated user object, not the User class constructor.
+declare type UserModel = OrmUserModel;
+export default Rbac;

package/dist/src/register.d.ts

@@ -0,0 +1,3 @@
+import type { AuthToken } from './token';
+import type { NewUser } from '@stacksjs/orm';
+export declare function register(credentials: NewUser): Promise<{ token: AuthToken }>;

package/dist/src/session-auth.d.ts

@@ -0,0 +1,30 @@
+import { User } from '@stacksjs/orm';
+/**
+ * Authenticate a user via email and password, creating a session.
+ * Sessions are persisted to the database so they survive server restarts.
+ */
+export declare function sessionLogin(email: string, password: string): Promise<{ user: UserModel, sessionId: string }>;
+/**
+ * Destroy the session for the given session ID.
+ */
+export declare function sessionLogout(sessionId: string): Promise<void>;
+/**
+ * Get the authenticated user from a session ID.
+ */
+export declare function sessionUser(sessionId: string): Promise<UserModel | undefined>;
+/**
+ * Check if a session is authenticated.
+ */
+export declare function sessionCheck(sessionId: string): Promise<boolean>;
+/**
+ * Refresh a session's expiry time.
+ */
+export declare function sessionRefresh(sessionId: string, ttlMs?: unknown): Promise<boolean>;
+export declare const SessionAuth: {
+  login: unknown;
+  logout: unknown;
+  user: unknown;
+  check: unknown;
+  refresh: unknown
+};
+declare type UserModel = InstanceType<typeof User>;

package/dist/src/tokens.d.ts

@@ -0,0 +1,251 @@
+import type { AccessToken, CreateClientOptions, CreateClientResult, OAuthClient, PersonalAccessTokenResult, RefreshTokenResult, TokenScopes } from '@stacksjs/types';
+/**
+ * Get all access tokens for a user
+ *
+ * @example
+ * import { tokens } from '@stacksjs/auth'
+ * const userTokens = await tokens(user.id)
+ */
+export declare function tokens(userId: number): Promise<AccessToken[]>;
+/**
+ * Get a specific token by its plain text value
+ * Uses hash comparison for security
+ *
+ * @example
+ * import { findToken } from '@stacksjs/auth'
+ * const token = await findToken('abc123...')
+ */
+export declare function findToken(plainTextToken: string): Promise<AccessToken | null>;
+/**
+ * Get the current access token from the request context
+ *
+ * @example
+ * import { currentAccessToken } from '@stacksjs/auth'
+ * const token = await currentAccessToken()
+ */
+export declare function currentAccessToken(): Promise<AccessToken | null>;
+/**
+ * Check if the current token has a given scope/ability
+ *
+ * @example
+ * import { tokenCan } from '@stacksjs/auth'
+ * if (await tokenCan('posts:create')) {
+ *   // user can create posts
+ * }
+ */
+export declare function tokenCan(scope: string): Promise<boolean>;
+/**
+ * Check if the current token does NOT have a given scope/ability
+ *
+ * @example
+ * import { tokenCant } from '@stacksjs/auth'
+ * if (await tokenCant('admin')) {
+ *   throw new Error('Admin access required')
+ * }
+ */
+export declare function tokenCant(scope: string): Promise<boolean>;
+/**
+ * Check if token has ALL of the given scopes
+ *
+ * @example
+ * import { tokenCanAll } from '@stacksjs/auth'
+ * if (await tokenCanAll(['posts:read', 'posts:write'])) {
+ *   // user has both scopes
+ * }
+ */
+export declare function tokenCanAll(scopes: string[]): Promise<boolean>;
+/**
+ * Check if token has ANY of the given scopes
+ *
+ * @example
+ * import { tokenCanAny } from '@stacksjs/auth'
+ * if (await tokenCanAny(['admin', 'moderator'])) {
+ *   // user has at least one of the scopes
+ * }
+ */
+export declare function tokenCanAny(scopes: string[]): Promise<boolean>;
+/**
+ * Get all scopes/abilities for the current token
+ *
+ * @example
+ * import { tokenAbilities } from '@stacksjs/auth'
+ * const abilities = await tokenAbilities()
+ * // ['read', 'write', 'posts:create']
+ */
+export declare function tokenAbilities(): Promise<string[]>;
+/**
+ * Create a new personal access token for a user
+ * Tokens are hashed before storage for security
+ *
+ * @param userId - The user ID to create the token for
+ * @param name - A name/description for the token
+ * @param scopes - Array of scopes/abilities for the token
+ * @param options - Additional options
+ * @param options.expiresInMinutes - Token expiry in minutes (default: 60)
+ * @param options.withRefreshToken - Whether to create a refresh token (default: true)
+ * @param options.refreshExpiresInDays - Refresh token expiry in days (default: 30)
+ *
+ * @example
+ * import { createToken } from '@stacksjs/auth'
+ * const result = await createToken(user.id, 'My API Token', ['read', 'write'])
+ * console.log(result.plainTextToken) // Save this - it won't be shown again!
+ * console.log(result.refreshToken)   // Use this to get new access tokens
+ */
+export declare function createToken(userId: number, name?: string, scopes?: string[], options?: {
+    expiresInMinutes?: number
+    withRefreshToken?: boolean
+    refreshExpiresInDays?: number
+  }): Promise<PersonalAccessTokenResult>;
+/**
+ * Exchange a refresh token for a new access token
+ *
+ * @param refreshTokenPlain - The plain text refresh token
+ * @param options - Additional options
+ * @param options.expiresInMinutes - New access token expiry in minutes (default: 60)
+ * @param options.refreshExpiresInDays - New refresh token expiry in days (default: 30)
+ *
+ * @example
+ * import { refreshToken } from '@stacksjs/auth'
+ * const result = await refreshToken('your-refresh-token')
+ * // Use result.plainTextToken as new access token
+ * // Use result.refreshToken as new refresh token (old one is revoked)
+ */
+export declare function refreshToken(refreshTokenPlain: string, options?: {
+    expiresInMinutes?: number
+    refreshExpiresInDays?: number
+  }): Promise<RefreshTokenResult>;
+/**
+ * Validate a refresh token without exchanging it
+ *
+ * @example
+ * import { validateRefreshToken } from '@stacksjs/auth'
+ * const isValid = await validateRefreshToken('your-refresh-token')
+ */
+export declare function validateRefreshToken(refreshTokenPlain: string): Promise<boolean>;
+/**
+ * Revoke a specific refresh token
+ *
+ * @example
+ * import { revokeRefreshToken } from '@stacksjs/auth'
+ * await revokeRefreshToken('your-refresh-token')
+ */
+export declare function revokeRefreshToken(refreshTokenPlain: string): Promise<void>;
+/**
+ * Revoke all refresh tokens for a user
+ *
+ * @example
+ * import { revokeAllRefreshTokens } from '@stacksjs/auth'
+ * await revokeAllRefreshTokens(user.id)
+ */
+export declare function revokeAllRefreshTokens(userId: number): Promise<void>;
+/**
+ * Delete expired refresh tokens (cleanup)
+ *
+ * @example
+ * import { deleteExpiredRefreshTokens } from '@stacksjs/auth'
+ * const count = await deleteExpiredRefreshTokens()
+ */
+export declare function deleteExpiredRefreshTokens(): Promise<number>;
+/**
+ * Delete revoked refresh tokens older than specified days
+ *
+ * @example
+ * import { deleteRevokedRefreshTokens } from '@stacksjs/auth'
+ * const count = await deleteRevokedRefreshTokens(7)
+ */
+export declare function deleteRevokedRefreshTokens(daysOld?: number): Promise<number>;
+/**
+ * Revoke a specific access token
+ *
+ * @example
+ * import { revokeToken } from '@stacksjs/auth'
+ * await revokeToken('abc123...')
+ */
+export declare function revokeToken(plainTextToken: string): Promise<void>;
+/**
+ * Revoke a token by its ID
+ *
+ * @example
+ * import { revokeTokenById } from '@stacksjs/auth'
+ * await revokeTokenById(123)
+ */
+export declare function revokeTokenById(tokenId: number): Promise<void>;
+/**
+ * Revoke all tokens for a user
+ *
+ * @example
+ * import { revokeAllTokens } from '@stacksjs/auth'
+ * await revokeAllTokens(user.id)
+ */
+export declare function revokeAllTokens(userId: number): Promise<void>;
+/**
+ * Revoke all tokens except the current one
+ *
+ * @example
+ * import { revokeOtherTokens } from '@stacksjs/auth'
+ * await revokeOtherTokens(user.id)
+ */
+export declare function revokeOtherTokens(userId: number): Promise<void>;
+/**
+ * Delete expired tokens (cleanup)
+ *
+ * @example
+ * import { deleteExpiredTokens } from '@stacksjs/auth'
+ * const count = await deleteExpiredTokens()
+ */
+export declare function deleteExpiredTokens(): Promise<number>;
+/**
+ * Delete revoked tokens older than specified days
+ *
+ * @example
+ * import { deleteRevokedTokens } from '@stacksjs/auth'
+ * const count = await deleteRevokedTokens(30) // older than 30 days
+ */
+export declare function deleteRevokedTokens(daysOld?: number): Promise<number>;
+/**
+ * Get all OAuth clients for a user
+ *
+ * @example
+ * import { clients } from '@stacksjs/auth'
+ * const userClients = await clients(user.id)
+ */
+export declare function clients(userId: number): Promise<OAuthClient[]>;
+/**
+ * Get a specific OAuth client by ID
+ *
+ * @example
+ * import { findClient } from '@stacksjs/auth'
+ * const client = await findClient(1)
+ */
+export declare function findClient(clientId: number): Promise<OAuthClient | null>;
+/**
+ * Create a new OAuth client
+ *
+ * @example
+ * import { createClient } from '@stacksjs/auth'
+ * const client = await createClient({
+ *   name: 'My App',
+ *   redirect: 'https://myapp.com/callback'
+ * })
+ */
+export declare function createClient(options: CreateClientOptions): Promise<CreateClientResult>;
+/**
+ * Revoke an OAuth client
+ *
+ * @example
+ * import { revokeClient } from '@stacksjs/auth'
+ * await revokeClient(1)
+ */
+export declare function revokeClient(clientId: number): Promise<void>;
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+export declare function parseScopes(scopes: string | string[] | null | undefined): TokenScopes;
+/**
+ * Alias for currentAccessToken
+ *
+ * @example
+ * import { token } from '@stacksjs/auth'
+ * const t = await token()
+ */
+export declare const token: unknown;

package/dist/src/user.d.ts

@@ -0,0 +1,34 @@
+import type { UserModel as OrmUserModel } from '@stacksjs/orm';
+/**
+ * Get the currently authenticated user
+ *
+ * This is the primary way to get the authenticated user in your application.
+ * It first checks if the user was already set by the auth middleware,
+ * then falls back to validating the bearer token.
+ *
+ * @example
+ * import { authUser } from '@stacksjs/auth'
+ *
+ * const user = await authUser()
+ * if (user) {
+ *   console.log('Logged in as:', user.email)
+ * }
+ */
+export declare function authUser(): Promise<UserModel | undefined>;
+/**
+ * Alias for authUser() - for backwards compatibility
+ * @deprecated Use authUser() instead
+ */
+export declare function getCurrentUser(): Promise<UserModel | undefined>;
+export declare function check(): Promise<boolean>;
+export declare function id(): Promise<number | undefined>;
+export declare function email(): Promise<string | undefined>;
+export declare function name(): Promise<string | undefined>;
+export declare function isAuthenticated(): Promise<boolean>;
+export declare function logout(): Promise<void>;
+export declare function refresh(): Promise<void>;
+// Local aliases — keep the existing `UserModel` / `UserJsonResponse` symbols
+// in this module while sourcing the underlying type from the ORM.
+declare type UserModel = OrmUserModel;
+declare type UserJsonResponse = OrmUserModel;
+export type AuthUser = UserJsonResponse;

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@stacksjs/auth",
   "type": "module",
-  "version": "0.70.23",
+  "version": "0.70.25",
   "description": "A more simplistic way to authenticate.",
   "author": "Chris Breuer",
-  "contributors": ["Chris Breuer <chris@stacksjs.org>"],
+  "contributors": [
+    "Chris Breuer <chris@stacksjs.com>"
+  ],
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",
   "homepage": "https://github.com/stacksjs/stacks/tree/main/storage/framework/core/auth#readme",
@@ -16,31 +18,39 @@
   "bugs": {
     "url": "https://github.com/stacksjs/stacks/issues"
   },
-  "keywords": ["auth", "authenticate", "stacks"],
+  "keywords": [
+    "auth",
+    "authenticate",
+    "stacks"
+  ],
   "exports": {
     ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
     "./*": {
+      "bun": "./src/*",
       "import": "./dist/*"
     }
   },
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["README.md", "dist"],
+  "files": [
+    "README.md",
+    "dist"
+  ],
   "scripts": {
     "build": "bun build.ts",
     "typecheck": "bun tsc --noEmit",
     "prepublishOnly": "bun run build"
   },
+  "dependencies": {
+    "@stacksjs/ts-auth": "^0.4.1"
+  },
   "devDependencies": {
-    "@simplewebauthn/browser": "^13.1.0",
-    "@simplewebauthn/server": "^13.1.1",
-    "@stacksjs/development": "0.70.22",
-    "@stacksjs/error-handling": "0.70.22",
-    "@stacksjs/router": "0.70.22",
-    "@types/qrcode": "^1.5.5",
-    "otplib": "^12.0.1",
-    "qrcode": "^1.5.4"
+    "better-dx": "^0.2.12",
+    "@stacksjs/error-handling": "0.70.23",
+    "@stacksjs/router": "0.70.23"
   }
 }