@stacksjs/defaults 0.70.207 → 0.70.208

package/ai/skills/stacks-arrays/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: stacks-arrays
+description: Use when working with array utilities in Stacks — statistical operations (average, median, mode, standard deviation, z-score, percentile, covariance), array manipulation (unique, flatten, partition, shuffle, sample, move), containment checks, or the Arr facade. Covers @stacksjs/arrays.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Array Utilities
+
+## Key Paths
+- Core package: `storage/framework/core/arrays/src/`
+- Package: `@stacksjs/arrays`
+
+## Architecture
+
+The `index.ts` exports:
+```typescript
+export * from './arr'
+export * as arr from './arr'
+export * from './macro'
+```
+
+The `arr.ts` re-exports from three submodules:
+- `contains.ts` — containment check functions
+- `helpers.ts` — array manipulation (toArray, flatten, partition, unique, shuffle, etc.)
+- `math.ts` — statistical functions (average, median, mode, variance, etc.)
+
+The `macro.ts` provides the `Arr` and `arr` facade objects.
+
+## Array Manipulation (`helpers.ts`)
+
+### Converting to Arrays
+```typescript
+import type { Arrayable, Nullable } from '@stacksjs/types'
+
+toArray('foo')           // ['foo']
+toArray(['foo'])         // ['foo']
+toArray(null)            // []
+toArray(undefined)       // []
+toArray(1)               // [1]
+toArray({ a: 1 })        // [{ a: 1 }]
+```
+
+### Flattening
+```typescript
+flatten([1, [2, [3, [4, [5]]]]])   // [1, 2, 3, 4, 5]  -- fully recursive
+flatten(null)                       // []
+flatten('hello')                    // ['hello']
+```
+
+### Merging
+```typescript
+mergeArrayable([1, 2], [3, 4], [5, 6])   // [1, 2, 3, 4, 5, 6]
+mergeArrayable(1, [2, 3], null)           // [1, 2, 3]  -- handles non-arrays and nulls
+```
+
+### Unique Values
+```typescript
+uniq([1, 1, 2, 3])                        // [1, 2, 3]  -- uses Set
+unique([1, 1, 2, 3])                      // [1, 2, 3]  -- alias for uniq
+
+uniqueBy(
+  [{ id: 1 }, { id: 1 }, { id: 2 }],
+  (a, b) => a.id === b.id
+)                                          // [{ id: 1 }, { id: 2 }]
+```
+
+### Accessing Elements
+```typescript
+last([1, 2, 3])                    // 3
+last([])                            // undefined
+
+at([1, 2, 3], 0)                   // 1
+at([1, 2, 3], -1)                  // 3   -- negative indexing
+at([1, 2, 3], 3)                   // undefined -- out of bounds
+at([], 0)                           // undefined
+```
+
+### Mutation
+```typescript
+const arr = [1, 2, 3]
+remove(arr, 2)                     // true -- arr is now [1, 3]
+remove(arr, 4)                     // false -- value not found, arr unchanged
+// WARNING: remove() MUTATES the original array
+```
+
+### Reordering
+```typescript
+move([1, 2, 3, 4], 0, 2)          // [2, 3, 1, 4]
+move([1, 2, 3, 4], 0, -1)         // [2, 3, 4, 1]  -- negative indexing
+move([1, 2, 3, 4], -1, 0)         // [4, 1, 2, 3]
+// WARNING: move() MUTATES the original array (splices in place)
+```
+
+### Random Selection
+```typescript
+sample([1, 2, 3, 4, 5], 3)        // e.g. [3, 1, 5] -- 3 random items
+// Items can repeat -- uses Math.random() * arr.length per pick
+```
+
+### Shuffling
+```typescript
+shuffle([1, 2, 3, 4])             // e.g. [3, 1, 4, 2]
+// WARNING: shuffle() MUTATES the original array (Fisher-Yates in-place)
+```
+
+### Clamping
+```typescript
+clampArrayRange([1, 2, 3], 0)     // 0
+clampArrayRange([1, 2, 3], 5)     // 2   -- clamped to last valid index
+clampArrayRange([1, 2, 3], -1)    // 0   -- clamped to 0
+// Uses clamp() from @stacksjs/browser
+```
+
+### Partitioning
+```typescript
+// With 1 filter: returns [matches, rest]
+const [odds, evens] = partition([1, 2, 3, 4], i => i % 2 !== 0)
+// odds = [1, 3], evens = [2, 4]
+
+// With 2 filters: returns [f1 matches, f2 matches, rest]
+const [small, medium, large] = partition(
+  [1, 5, 10, 50, 100],
+  n => n < 10,
+  n => n < 50
+)
+// small = [1, 5], medium = [10], large = [50, 100]
+
+// Supports up to 6 filter functions, always returns one extra array for unmatched items
+```
+
+Partition filter signature: `(item: T, index: number, array: readonly T[]) => any`
+
+## Containment Checks (`contains.ts`)
+
+All containment functions work with `string[]`. The `contains` function checks if the needle includes any element from the haystack (substring matching via `needle.includes(hay)`).
+
+```typescript
+contains('foobar', ['foo', 'baz'])              // true  -- 'foobar'.includes('foo')
+contains('hello', ['foo', 'bar'])               // false
+
+containsAll(['foo', 'bar'], ['foobar', 'barx']) // true  -- all needles found
+containsAll(['foo', 'qux'], ['foobar'])         // false -- 'qux' not found
+
+containsAny(['foo', 'qux'], ['foobar'])         // true  -- at least one found
+containsAny(['baz', 'qux'], ['foobar'])         // false
+
+containsNone(['baz', 'qux'], ['foobar'])        // true  -- none found
+containsNone(['foo', 'qux'], ['foobar'])        // false
+
+containsOnly(['foo', 'bar'], ['foobar', 'barx']) // checks if haystack items only contain needles
+// Implemented as: containsAll(haystack, needles) -- reversed args
+
+doesNotContain('qux', ['foo', 'bar'])           // true
+doesNotContain('foo', ['foobar'])               // false
+```
+
+**Important**: `contains` uses `needle.includes(hay)`, NOT `haystack.includes(needle)`. It checks if the needle string contains any of the haystack substrings. This is substring matching, not array membership.
+
+## Statistical Functions (`math.ts`)
+
+All statistical functions expect `number[]` and throw `Error` on empty arrays (except `sum` and `product` which return identity values).
+
+### Basic Aggregates
+```typescript
+sum([1, 2, 3, 4])                  // 10  -- reduce with +
+product([2, 3, 4])                 // 24  -- reduce with *
+min([5, 1, 3])                     // 1   -- Math.min(), throws on empty
+max([5, 1, 3])                     // 5   -- Math.max(), throws on empty
+range([1, 5, 3])                   // 4   -- max - min
+```
+
+### Central Tendency
+```typescript
+average([1, 2, 3, 4, 5])          // 3      -- sum / length
+avg([1, 2, 3])                     // 2      -- alias for average
+
+median([1, 2, 3, 4, 5])           // 3      -- middle value (sorted)
+median([1, 2, 3, 4])              // 2.5    -- average of two middle values
+
+mode([1, 2, 2, 3, 3, 4, 4, 4])   // 4      -- most frequent value
+mode([1, 2, 3, 4])                // 1      -- first value when all equal frequency
+```
+
+### Dispersion
+```typescript
+variance([1, 2, 3, 4])            // 1.25   -- population variance (not sample)
+standardDeviation([1, 2, 3, 4])   // 1.118... -- sqrt(variance), population std dev
+```
+
+### Advanced Statistics
+```typescript
+zScore([1, 2, 3, 4], 2)           // -0.447... -- (value - mean) / stddev
+zScore([1, 2, 3, 4], 3)           // 0.447...
+
+percentile([1, 2, 3, 4, 5], 50)   // 3       -- interpolated percentile
+percentile([1, 2, 3, 4], 25)      // 1.75    -- linear interpolation
+// Note: takes percentile value (0-100), uses linear interpolation
+
+interquartileRange([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+// Q3 median - Q1 median
+// Splits array at midpoint, computes median of each half
+
+covariance([1, 2, 3, 4], [1, 2, 3, 4])     // 1.25  -- positive correlation
+covariance([1, 2, 3, 4], [4, 3, 2, 1])     // -1.25 -- negative correlation
+// Throws if arrays have different lengths
+```
+
+**Important**: `variance` and `standardDeviation` compute POPULATION metrics (divides by N), not sample metrics (which would divide by N-1).
+
+## Arr Facade (`macro.ts`)
+
+Both `Arr` and `arr` are exported as equivalent facade objects.
+
+```typescript
+import { Arr, arr } from '@stacksjs/arrays'
+
+// Array manipulation
+Arr.toArray(value)                 // convert to array
+Arr.flatten(array)                 // recursive flatten
+Arr.mergeArrayable(...arrays)      // merge arrays
+Arr.unique(arr)                    // deduplicate (Set-based)
+Arr.uniqueBy(arr, equalFn)        // deduplicate with custom equality
+Arr.last(arr)                      // last element
+Arr.at(arr, index)                 // get by index (negative supported)
+Arr.remove(arr, value)             // remove first occurrence (mutates)
+Arr.move(arr, from, to)            // move element (mutates)
+Arr.clampArrayRange(arr, n)        // clamp index to bounds
+Arr.shuffle(arr)                   // shuffle in place
+Arr.sample(arr, count)             // random items
+Arr.random(arr, count)             // alias for sample, filters nulls
+Arr.partition(arr, filter)         // partition by filter
+
+// Containment
+Arr.contains(needle, haystack)
+Arr.containsAll(needles, haystack)
+Arr.containsAny(needles, haystack)
+Arr.containsNone(needles, haystack)
+Arr.containsOnly(needles, haystack)
+Arr.doesNotContain(needle, haystack)
+
+// Statistics
+Arr.sum(arr)                       // sum
+Arr.average(arr)                   // mean
+Arr.avg(arr)                       // alias for average
+Arr.median(arr)                    // median
+Arr.mode(arr)                      // mode
+Arr.range(arr)                     // max - min
+```
+
+Note: The `Arr` facade does NOT expose `variance`, `standardDeviation`, `zScore`, `percentile`, `interquartileRange`, `covariance`, `product`, `min`, or `max` -- use the standalone functions for those.
+
+The facade adds one extra method not in the standalone functions:
+```typescript
+Arr.random(arr, count)   // like sample but filters null/undefined from results
+```
+
+## Exported Types
+
+```typescript
+type PartitionFilter<T> = (item: T, index: number, array: readonly T[]) => any
+// Also uses Arrayable<T> and Nullable<T> from @stacksjs/types
+```
+
+## Gotchas
+- `shuffle()` and `move()` MUTATE the original array -- they do NOT return copies
+- `remove()` MUTATES the original array and returns a boolean (not the removed element)
+- `sample()` can return duplicate items since each pick is independent
+- `contains()` uses SUBSTRING matching (`needle.includes(hay)`), not array membership -- `contains('foobar', ['foo'])` is true
+- Statistical functions throw on empty arrays (except `sum` which returns 0 and `product` which returns 1)
+- `variance` and `standardDeviation` use POPULATION formulas (divide by N), not sample formulas
+- `percentile` takes a value 0-100 and uses linear interpolation between sorted array elements
+- `interquartileRange` splits the sorted array at the midpoint and takes median of each half
+- `mode` returns the first most-frequent value when there's a tie
+- For complex collection operations with chaining, consider `@stacksjs/collections`
+- The `Arr` facade wraps most but not all standalone functions -- advanced stats need direct imports

package/ai/skills/stacks-auth/SKILL.md

@@ -0,0 +1,422 @@
+---
+name: stacks-auth
+description: Use when implementing authentication, authorization, passkeys, TOTP/2FA, RBAC, gates, policies, session auth, token management, email verification, password resets, or rate limiting in a Stacks application. Covers the @stacksjs/auth package, config/auth.ts, app/Gates.ts, and app/Middleware/.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Authentication & Authorization
+
+The `@stacksjs/auth` package provides comprehensive authentication and authorization for Stacks applications, built on `@stacksjs/ts-auth`.
+
+## Key Paths
+
+- Core package source: `storage/framework/core/auth/src/`
+- Configuration: `config/auth.ts`
+- Security config: `config/security.ts`
+- Hashing config: `config/hashing.ts`
+- Application gates: `app/Gates.ts`
+- Application middleware: `app/Middleware/`
+- Middleware aliases: `app/Middleware.ts`
+- Auth types: `storage/framework/core/types/src/auth.ts`
+
+## Source Files
+
+```
+auth/src/
+├── index.ts              # All re-exports
+├── authentication.ts     # Auth class - core auth logic
+├── authenticator.ts      # 2FA and personal access client
+├── client.ts             # Client re-exports
+├── middleware.ts          # Auth middleware handler
+├── rate-limiter.ts        # RateLimiter class (5 attempts, 15min lockout)
+├── passkey.ts             # WebAuthn/Passkey support
+├── password/reset.ts      # Password reset flow
+├── register.ts            # User registration
+├── user.ts                # Auth user helpers
+├── tokens.ts              # Token CRUD, scopes, refresh tokens, OAuth clients
+├── gate.ts                # Authorization gates & policies
+├── policy.ts              # BasePolicy class + discovery
+├── authorizable.ts        # User authorization mixin
+├── rbac.ts                # Full RBAC system
+├── email-verification.ts  # Email verification flow
+└── session-auth.ts        # Session-based SPA auth
+```
+
+## Auth Class (authentication.ts) — Static Methods
+
+### Login & Authentication
+- `Auth.attempt(credentials: AuthCredentials): Promise<boolean>` — validate credentials without creating token
+- `Auth.validate(credentials: AuthCredentials): Promise<boolean>` — alias for attempt
+- `Auth.login(credentials: AuthCredentials, options?: TokenCreateOptions): Promise<{ user, token } | null>` — login and create token
+- `Auth.loginUsingId(userId: number, options?: TokenCreateOptions): Promise<{ user, token } | null>` — login by user ID
+- `Auth.logout(): Promise<void>` — revoke current token
+- `Auth.once(credentials: AuthCredentials): Promise<boolean>` — one-time auth without token
+- `Auth.requestToken(credentials, clientId, clientSecret): Promise<{ token } | null>` — OAuth token request
+
+### User State
+- `Auth.user(): Promise<UserModel | undefined>` — get authenticated user from bearer token
+- `Auth.check(): Promise<boolean>` — is user authenticated?
+- `Auth.guest(): Promise<boolean>` — is user a guest?
+- `Auth.id(): Promise<number | undefined>` — get authenticated user ID
+- `Auth.setUser(user: UserModel): void` — manually set user
+
+### Token Creation
+- `Auth.createTokenForUser(user, options?: TokenCreateOptions): Promise<NewAccessToken>`
+- `Auth.createToken(user, name?, abilities?): Promise<AuthToken>`
+
+### Token Validation
+- `Auth.validateToken(token: string): Promise<boolean>` — validate bearer token
+- `Auth.getUserFromToken(token: string): Promise<UserModel | undefined>`
+- `Auth.currentAccessToken(): Promise<PersonalAccessToken | undefined>`
+
+### Token Abilities (Scopes)
+- `Auth.tokenCan(ability: string): Promise<boolean>`
+- `Auth.tokenCant(ability: string): Promise<boolean>`
+- `Auth.tokenAbilities(): Promise<string[]>`
+- `Auth.tokenCanAll(abilities: string[]): Promise<boolean>`
+- `Auth.tokenCanAny(abilities: string[]): Promise<boolean>`
+
+### Token Management
+- `Auth.tokens(userId?: number): Promise<PersonalAccessToken[]>`
+- `Auth.revokeToken(token: string): Promise<void>`
+- `Auth.revokeTokenById(tokenId: number): Promise<void>`
+- `Auth.revokeAllTokens(userId?: number): Promise<void>`
+- `Auth.revokeOtherTokens(userId?: number): Promise<void>`
+- `Auth.pruneExpiredTokens(): Promise<number>`
+- `Auth.pruneRevokedTokens(): Promise<number>`
+- `Auth.rotateToken(oldToken: string): Promise<AuthToken | null>`
+- `Auth.findToken(tokenId: number): Promise<PersonalAccessToken | null>`
+
+### Utility
+- `Auth.guard(name?: string): typeof Auth` — select guard (returns self)
+- `Auth.viaRemember(): boolean` — always false currently
+- `Auth.clearState(): void` — clear cached user/token
+
+## Token System (tokens.ts)
+
+### Access Tokens
+- `tokens(userId: number): Promise<AccessToken[]>`
+- `findToken(plainTextToken: string): Promise<AccessToken | null>`
+- `currentAccessToken(): Promise<AccessToken | null>`
+- `createToken(userId, name?, scopes?, options?): Promise<PersonalAccessTokenResult>`
+  - Options: `{ expiresInMinutes?, withRefreshToken?, refreshExpiresInDays? }`
+
+### Refresh Tokens
+- `refreshToken(refreshTokenPlain, options?): Promise<RefreshTokenResult>`
+- `validateRefreshToken(refreshTokenPlain): Promise<boolean>`
+- `revokeRefreshToken(refreshTokenPlain): Promise<void>`
+- `revokeAllRefreshTokens(userId): Promise<void>`
+- `deleteExpiredRefreshTokens(): Promise<number>`
+- `deleteRevokedRefreshTokens(daysOld?): Promise<number>`
+
+### Token Revocation
+- `revokeToken(plainTextToken): Promise<void>`
+- `revokeTokenById(tokenId): Promise<void>`
+- `revokeAllTokens(userId): Promise<void>`
+- `revokeOtherTokens(userId): Promise<void>`
+- `deleteExpiredTokens(): Promise<number>`
+- `deleteRevokedTokens(daysOld?): Promise<number>`
+
+### Token Scopes
+- `tokenCan(scope): Promise<boolean>`
+- `tokenCant(scope): Promise<boolean>`
+- `tokenCanAll(scopes): Promise<boolean>`
+- `tokenCanAny(scopes): Promise<boolean>`
+- `tokenAbilities(): Promise<string[]>`
+- `parseScopes(scopes: string | string[] | null | undefined): TokenScopes`
+
+### OAuth Clients
+- `clients(userId): Promise<OAuthClient[]>`
+- `findClient(clientId): Promise<OAuthClient | null>`
+- `createClient(options: CreateClientOptions): Promise<CreateClientResult>`
+- `revokeClient(clientId): Promise<void>`
+
+## Two-Factor Authentication (authenticator.ts)
+
+- `generateTwoFactorSecret(): string`
+- `generateTwoFactorToken(secret: Secret): Promise<Token>`
+- `verifyTwoFactorCode(token: Token, secret: Secret): Promise<boolean>`
+- `generateTwoFactorUri(user?, service?, secret?): string`
+- `createPersonalAccessClient(): Promise<Result<string, never>>`
+
+### Re-exported from @stacksjs/ts-auth
+- `generateTOTP`, `verifyTOTP`, `generateTOTPSecret`, `totpKeyUri`
+
+## Authorization Gates (gate.ts)
+
+### Gate Functions
+- `define<T>(ability: string, callback: GateCallback<T>): void`
+- `policy(model: string | { name }, policyClass: new () => Policy): void`
+- `before(callback): void` — run before any gate check
+- `after(callback): void` — run after any gate check
+- `allows(ability, user, ...args): Promise<boolean>`
+- `denies(ability, user, ...args): Promise<boolean>`
+- `can(ability, user, ...args): Promise<boolean>`
+- `cannot(ability, user, ...args): Promise<boolean>`
+- `any(abilities[], user, ...args): Promise<boolean>`
+- `all(abilities[], user, ...args): Promise<boolean>`
+- `none(abilities[], user, ...args): Promise<boolean>`
+- `authorize(ability, user, ...args): Promise<AuthorizationResponse>` — throws on deny
+- `inspect(ability, user, ...args): Promise<AuthorizationResponse>` — never throws
+- `has(ability): boolean`
+- `hasPolicy(model): boolean`
+- `abilities(): string[]`
+- `getPolicyFor<T>(model: T): Policy<T> | null`
+- `flush(): void` — clear all gates
+
+### Gate Facade — `Gate.define()`, `Gate.can()`, etc
+
+### AuthorizationResponse Class
+- `static allow(message?): AuthorizationResponse`
+- `static deny(message?, code?): AuthorizationResponse`
+- `allowed(): boolean`, `denied(): boolean`
+- `authorize(): void` — throws AuthorizationException if denied
+
+### Policy Interface
+Methods: `before?`, `viewAny?`, `view?`, `create?`, `update?`, `delete?`, `restore?`, `forceDelete?`
+
+### BasePolicy Abstract Class
+Protected helpers: `allow(message?)`, `deny(message?, code?)`, `denyIf(condition)`, `denyUnless(condition)`, `allowIf(condition)`
+
+## RBAC System (rbac.ts)
+
+### Role Management
+- `Rbac.createRole(name, guardName?, description?): Promise<RoleRecord>`
+- `Rbac.findRole(name, guardName?): Promise<RoleRecord | null>`
+- `Rbac.deleteRole(name, guardName?): Promise<void>`
+- `Rbac.getAllRoles(guardName?): Promise<RoleRecord[]>`
+
+### Permission Management
+- `Rbac.createPermission(name, guardName?, description?): Promise<PermissionRecord>`
+- `Rbac.findPermission(name, guardName?): Promise<PermissionRecord | null>`
+- `Rbac.deletePermission(name, guardName?): Promise<void>`
+- `Rbac.getAllPermissions(guardName?): Promise<PermissionRecord[]>`
+
+### User-Role Operations
+- `Rbac.getUserRoles(user): Promise<RoleRecord[]>`
+- `Rbac.assignRole(user, roleName, guardName?): Promise<void>`
+- `Rbac.removeRole(user, roleName, guardName?): Promise<void>`
+- `Rbac.removeAllRoles(user): Promise<void>`
+- `Rbac.syncRoles(user, roleNames[], guardName?): Promise<void>`
+- `Rbac.hasRole(user, roleName, guardName?): Promise<boolean>`
+- `Rbac.hasAnyRole(user, roleNames[], guardName?): Promise<boolean>`
+- `Rbac.hasAllRoles(user, roleNames[], guardName?): Promise<boolean>`
+
+### User-Permission Operations
+- `Rbac.getUserPermissions(user): Promise<PermissionRecord[]>`
+- `Rbac.givePermission(user, permissionName, guardName?): Promise<void>`
+- `Rbac.revokePermission(user, permissionName, guardName?): Promise<void>`
+- `Rbac.revokeAllPermissions(user): Promise<void>`
+- `Rbac.syncPermissions(user, permissionNames[], guardName?): Promise<void>`
+- `Rbac.hasPermission(user, permissionName, guardName?): Promise<boolean>`
+- `Rbac.hasAnyPermission(user, permissionNames[], guardName?): Promise<boolean>`
+- `Rbac.hasAllPermissions(user, permissionNames[], guardName?): Promise<boolean>`
+
+### Role-Permission Operations
+- `Rbac.getRolePermissions(roleId): Promise<PermissionRecord[]>`
+- `Rbac.givePermissionToRole(roleName, permissionName, guardName?): Promise<void>`
+- `Rbac.revokePermissionFromRole(roleName, permissionName, guardName?): Promise<void>`
+- `Rbac.syncRolePermissions(roleName, permissionNames[], guardName?): Promise<void>`
+
+### withRbac Mixin
+`withRbac(user)` — adds `hasRole()`, `hasPermission()`, `assignRole()`, `givePermission()`, etc. to any user object
+
+### RBAC Types
+```typescript
+interface RoleRecord { id, name, guard_name, description?, created_at?, updated_at? }
+interface PermissionRecord { id, name, guard_name, description?, created_at?, updated_at? }
+interface RbacStore { findRoleByName, createRole, deleteRole, getAllRoles, findPermissionByName, createPermission, ... }
+```
+
+## Session Auth (session-auth.ts)
+
+- `SessionAuth.login(email, password): Promise<{ user, sessionId }>`
+- `SessionAuth.logout(sessionId): void`
+- `SessionAuth.user(sessionId): Promise<UserModel | undefined>`
+- `SessionAuth.check(sessionId): boolean`
+- `SessionAuth.refresh(sessionId, ttlMs?): boolean`
+
+Internal: in-memory Map with 10k session limit, 5-minute eviction interval, timing-safe password comparison with dummy bcrypt hash.
+
+## Email Verification (email-verification.ts)
+
+- `EmailVerification.isVerified(user): boolean`
+- `EmailVerification.send(user): Promise<void>`
+- `EmailVerification.verify(userId, token): Promise<EmailVerificationResult>`
+- `EmailVerification.resend(user): Promise<EmailVerificationResult>`
+
+## Password Reset (password/reset.ts)
+
+```typescript
+const actions = passwordResets(email)
+await actions.sendEmail()
+const valid = await actions.verifyToken(token)
+const result = await actions.resetPassword(token, newPassword)
+```
+
+## Registration (register.ts)
+
+- `register(credentials: NewUser): Promise<{ token: AuthToken }>`
+
+## User Helpers (user.ts)
+
+- `authUser(): Promise<UserModel | undefined>`
+- `check(): Promise<boolean>`
+- `id(): Promise<number | undefined>`
+- `email(): Promise<string | undefined>`
+- `name(): Promise<string | undefined>`
+- `isAuthenticated(): Promise<boolean>`
+- `logout(): Promise<void>`
+- `refresh(): Promise<void>`
+
+## Passkey/WebAuthn (passkey.ts)
+
+- `getUserPasskeys(userId): Promise<PasskeyAttribute[]>`
+- `getUserPasskey(userId, passkeyId): Promise<PasskeyAttribute | undefined>`
+- `setCurrentRegistrationOptions(user, verified): Promise<void>`
+
+### Re-exported from @stacksjs/ts-auth
+- `generateRegistrationOptions`, `generateAuthenticationOptions`
+- `verifyRegistrationResponse`, `verifyAuthenticationResponse`
+- `startRegistration`, `startAuthentication` (browser)
+- `browserSupportsWebAuthn`, `browserSupportsWebAuthnAutofill`
+- `platformAuthenticatorIsAvailable`
+
+## Auth Middleware (middleware.ts)
+
+```typescript
+export const authMiddlewareHandler = {
+  name: 'auth',
+  handle: authMiddleware, // validates bearer token, throws 401
+}
+```
+
+## Rate Limiter (rate-limiter.ts)
+
+```typescript
+class RateLimiter {
+  static MAX_ATTEMPTS = 5
+  static LOCKOUT_DURATION = 15 * 60 * 1000  // 15 minutes
+  static MAX_STORE_SIZE = 10_000
+  static EVICTION_INTERVAL = 5 * 60 * 1000  // 5 minutes
+
+  static isRateLimited(email): boolean
+  static recordFailedAttempt(email): void
+  static resetAttempts(email): void
+  static validateAttempt(email): void  // throws HttpError 429
+}
+```
+
+## Authorizable Mixin (authorizable.ts)
+
+```typescript
+const authUser = withAuthorization(user)
+await authUser.can('edit-post', post)
+await authUser.cannot('delete-post', post)
+await authUser.canAny(['edit', 'delete'], post)
+await authUser.canAll(['edit', 'publish'], post)
+await authUser.authorize('edit-post', post)  // throws if denied
+```
+
+## Configuration
+
+### config/auth.ts
+```typescript
+{
+  default: 'api',
+  guards: { api: { driver: 'token', provider: 'users' } },
+  providers: { users: { driver: 'database', table: 'users' } },
+  username: 'email',      // AUTH_USERNAME_FIELD env
+  password: 'password',   // AUTH_PASSWORD_FIELD env
+  tokenExpiry: 30,         // days, AUTH_TOKEN_EXPIRY env
+  tokenRotation: 7,        // days, AUTH_TOKEN_ROTATION env
+  defaultAbilities: ['*'],
+  defaultTokenName: 'auth_token',
+  passwordReset: { expire: 60, throttle: 60 }
+}
+```
+
+### config/hashing.ts
+```typescript
+{
+  driver: 'bcrypt',         // 'bcrypt' | 'argon2'
+  bcrypt: { rounds: 12 },
+  argon2: { memory: 65536, time: 3 }
+}
+```
+
+### config/security.ts
+```typescript
+{
+  firewall: {
+    enabled: true,
+    countryCodes: [],
+    ipAddresses: { allowlist: [], blocklist: [] },
+    rateLimitPerMinute: 500,
+    useIpReputationLists: true,
+    useKnownBadInputsRuleSet: true
+  }
+}
+```
+
+## Middleware Aliases (app/Middleware.ts)
+
+Available middleware names: `maintenance`, `auth`, `guest`, `api`, `team`, `logger`, `abilities`, `can`, `throttle`, `local`, `development`, `staging`, `production`, `env.local`, `env.development`, `env.staging`, `env.production`, `role`, `permission`, `verified` (EnsureEmailIsVerified)
+
+## Application Gates Example (app/Gates.ts)
+
+```typescript
+Gate.define('access-admin', (user) => user?.email?.endsWith('@stacksjs.org') ?? false)
+Gate.define('edit-settings', (user) => !!user)
+Gate.define('view-dashboard', (user) => !!user)
+```
+
+## Default API Routes
+
+- `POST /login` → LoginAction (validates email + password)
+- `POST /register` → RegisterAction
+- `POST /auth/refresh` → RefreshTokenAction
+- `POST /auth/token` → CreateTokenAction
+- `GET /auth/tokens` → ListTokensAction (auth middleware)
+- `DELETE /auth/tokens/{id}` → RevokeTokenAction (auth middleware)
+- `GET /me` → GetMeAction (auth middleware)
+- `POST /logout` → LogoutAction (auth middleware)
+
+## User Model Traits
+
+```typescript
+// User model uses:
+traits: {
+  useAuth: { usePasskey: true },
+  useUuid: true,
+  useTimestamps: true,
+  useSocials: ['github'],
+}
+```
+
+## Gotchas
+
+- Auth depends on `@stacksjs/ts-auth` for TOTP and passkey functions
+- Password hashing defaults to bcrypt with 12 rounds (config/hashing.ts)
+- Rate limiter uses in-memory Map, resets on server restart — not shared across workers
+- Session auth also uses in-memory Map with 10k limit — for SPA cookie auth
+- Token format is `tokenId|plainText` — the `|` separates the encrypted ID from the plain token
+- The `parseToken()` helper splits on `|` to extract both parts
+- Bearer tokens come from the `Authorization: Bearer <token>` header
+- `Auth.user()` internally calls `getBearerToken()` → `parseToken()` → `getTokenFromId()` → validates hash
+- RBAC has an internal cache (`userRoles`, `userPermissions`, `rolePermissions`) — call `Rbac.flushCache()` after direct DB changes
+- Gate `before` callbacks can short-circuit — return `true` to allow, `null` to continue checking
+- `withRbac()` and `withAuthorization()` return new objects with methods mixed in
+- The `RbacStore` interface must be implemented and set via `Rbac.setStore()` for RBAC to work
+- Password reset tokens expire after 60 minutes by default
+- Default token abilities are `['*']` — wildcard access
+- Token expiry defaults to 30 days
+- Session auth uses timing-safe bcrypt comparison even for failed lookups (dummy hash prevents timing attacks)
+
+## Build
+
+```bash
+cd storage/framework/core/auth && bun build.ts
+```