ideal-auth 0.4.0 → 0.5.0

package/README.md

@@ -12,17 +12,19 @@ Provide a cookie bridge (3 functions) once during setup, and `auth().login(user)
 bun add ideal-auth
 ```
 
-## Generate Secret
+## Generate Secrets
 
 ```bash
+# Session secret (required — used by createAuth)
 bunx ideal-auth secret
-```
+# IDEAL_AUTH_SECRET=aLThikMgJKMBB5WZLE-lCaOQUdgPWU8BHRv99bkYaVY
 
-```
-IDEAL_AUTH_SECRET=aLThikMgJKMBB5WZLE-lCaOQUdgPWU8BHRv99bkYaVY
+# Encryption key (optional — used by encrypt/decrypt for data at rest)
+bunx ideal-auth encryption-key
+# ENCRYPTION_KEY=9546dd9fa461ce15f0aacd6e1b461b52
 ```
 
-Copy the output into your `.env` file. The secret must be at least 32 characters.
+Copy the output into your `.env` file. `IDEAL_AUTH_SECRET` must be at least 32 characters. `ENCRYPTION_KEY` is only needed if you use `encrypt()`/`decrypt()` (e.g., encrypting TOTP secrets or access tokens at rest).
 
 ## Quick Start
 
@@ -94,12 +96,13 @@ Returns a function `auth()` that creates an `AuthInstance` on each call.
 | --- | --- | --- | --- |
 | `secret` | `string` | Yes | — |
 | `cookie` | `CookieBridge` | Yes | — |
-| `resolveUser` | `(id: string) => Promise<User \| null>` | Yes | — |
+| `resolveUser` | `(id: string) => Promise<User \| null \| undefined>` | Yes (unless `sessionFields` is provided) | — |
+| `sessionFields` | `(keyof User & string)[]` | Yes (unless `resolveUser` is provided) | — |
 | `hash` | `HashInstance` | No | — |
-| `resolveUserByCredentials` | `(creds: Record<string, any>) => Promise<User \| null>` | No | — |
+| `resolveUserByCredentials` | `(creds: Record<string, any>) => Promise<User \| null \| undefined>` | No | — |
 | `credentialKey` | `string` | No | `'password'` |
 | `passwordField` | `string` | No | `'password'` |
-| `attemptUser` | `(creds: Record<string, any>) => Promise<User \| null>` | No | — |
+| `attemptUser` | `(creds: Record<string, any>) => Promise<User \| null \| undefined>` | No | — |
 | `session.cookieName` | `string` | No | `'ideal_session'` |
 | `session.maxAge` | `number` (seconds) | No | `604800` (7 days) |
 | `session.rememberMaxAge` | `number` (seconds) | No | `2592000` (30 days) |

package/dist/auth-instance.d.ts

@@ -6,13 +6,13 @@ interface AuthInstanceDeps<TUser extends AnyUser> {
     maxAge: number;
     rememberMaxAge: number;
     cookieOptions: ConfigurableCookieOptions;
-    resolveUser?: (id: string) => Promise<TUser | null>;
+    resolveUser?: (id: string) => Promise<TUser | null | undefined>;
     sessionFields?: (keyof TUser & string)[];
     hash?: HashInstance;
-    resolveUserByCredentials?: (credentials: Record<string, any>) => Promise<TUser | null>;
+    resolveUserByCredentials?: (credentials: Record<string, any>) => Promise<TUser | null | undefined>;
     credentialKey: string;
     passwordField: string;
-    attemptUser?: (credentials: Record<string, any>) => Promise<TUser | null>;
+    attemptUser?: (credentials: Record<string, any>) => Promise<TUser | null | undefined>;
 }
 export declare function createAuthInstance<TUser extends AnyUser>(deps: AuthInstanceDeps<TUser>): AuthInstance<TUser>;
 export {};

package/dist/auth-instance.js

@@ -106,7 +106,7 @@ export function createAuthInstance(deps) {
             }
             // Database-backed: resolve user via callback
             if (deps.resolveUser) {
-                cachedUser = await deps.resolveUser(session.uid);
+                cachedUser = (await deps.resolveUser(session.uid)) ?? null;
                 return cachedUser;
             }
             cachedUser = null;

package/dist/types.d.ts

@@ -27,7 +27,7 @@ export interface SessionPayload {
 export interface LoginOptions {
     remember?: boolean;
 }
-export interface AuthConfig<TUser extends AnyUser = AnyUser> {
+interface AuthConfigBase<TUser extends AnyUser> {
     secret: string;
     cookie: CookieBridge;
     session?: {
@@ -36,33 +36,39 @@ export interface AuthConfig<TUser extends AnyUser = AnyUser> {
         rememberMaxAge?: number;
         cookie?: Partial<ConfigurableCookieOptions>;
     };
-    resolveUser?: (id: string) => Promise<TUser | null>;
-    /**
-     * Fields from the user object to store in the session cookie.
-     * When provided, `resolveUser` is not needed — `user()` returns
-     * the stored fields directly from the cookie.
-     *
-     * The `id` field is always stored. List only additional fields.
-     * Keep the total small — session cookies have a ~4KB size limit.
-     *
-     * Cannot be used together with `resolveUser`.
-     *
-     * **Staleness:** Data is snapshotted at login time. If a user's role
-     * or permissions change server-side, the cookie retains the old values
-     * until the user re-logs in. For authorization-critical fields (role,
-     * permissions, subscription tier), prefer `resolveUser` to get fresh
-     * data on every request.
-     *
-     * **ID type:** `user()` always returns `id` as a `string` on subsequent
-     * requests (read from cookie), even if the original `TUser.id` was a number.
-     */
-    sessionFields?: (keyof TUser & string)[];
     hash?: HashInstance;
-    resolveUserByCredentials?: (credentials: Record<string, any>) => Promise<TUser | null>;
+    resolveUserByCredentials?: (credentials: Record<string, any>) => Promise<TUser | null | undefined>;
     credentialKey?: string;
     passwordField?: string;
-    attemptUser?: (credentials: Record<string, any>) => Promise<TUser | null>;
-}
+    attemptUser?: (credentials: Record<string, any>) => Promise<TUser | null | undefined>;
+}
+/** Database-backed: `user()` calls `resolveUser(id)` on every request. */
+interface AuthConfigWithResolveUser<TUser extends AnyUser> extends AuthConfigBase<TUser> {
+    resolveUser: (id: string) => Promise<TUser | null | undefined>;
+    /** Cannot use `sessionFields` together with `resolveUser`. */
+    sessionFields?: never;
+}
+/**
+ * Cookie-backed: `user()` reads declared fields from the session cookie.
+ *
+ * The `id` field is always stored. List only additional fields.
+ * Keep the total small — session cookies have a ~4KB size limit.
+ *
+ * **Staleness:** Data is snapshotted at login time. If a user's role
+ * or permissions change server-side, the cookie retains the old values
+ * until the user re-logs in. For authorization-critical fields (role,
+ * permissions, subscription tier), prefer `resolveUser` to get fresh
+ * data on every request.
+ *
+ * **ID type:** `user()` always returns `id` as a `string` on subsequent
+ * requests (read from cookie), even if the original `TUser.id` was a number.
+ */
+interface AuthConfigWithSessionFields<TUser extends AnyUser> extends AuthConfigBase<TUser> {
+    /** Cannot use `resolveUser` together with `sessionFields`. */
+    resolveUser?: never;
+    sessionFields: (keyof TUser & string)[];
+}
+export type AuthConfig<TUser extends AnyUser = AnyUser> = AuthConfigWithResolveUser<TUser> | AuthConfigWithSessionFields<TUser>;
 export interface HashConfig {
     rounds?: number;
 }
@@ -125,3 +131,4 @@ export interface RecoveryCodeResult {
     valid: boolean;
     remaining: string[];
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ideal-auth",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Auth primitives for the JS ecosystem. Zero framework dependencies.",
   "scripts": {
     "build": "tsc",

package/skills/ideal-auth/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ideal-auth
-description: Auth primitives for the JS ecosystem. Covers login, logout, session, register, signup, sign in, sign out, password, 2FA, two-factor, TOTP, MFA, ideal-auth, cookie bridge, middleware, route protection, rate limit, rate limiting, password reset, forgot password, email verification, remember me, recovery code, CSRF, encrypt, decrypt, hash, bcrypt, token, secret, session cookie, multi-tenant, cross-domain, tenant, transfer token, federated logout, OAuth redirect, central login, login session, attemptUser, sessionFields, cookie-backed session, resolveUser, token refresh, refresh token, access token, OIDC.
+description: Auth primitives for the JS ecosystem. Covers login, logout, session, register, signup, sign in, sign out, password, 2FA, two-factor, TOTP, MFA, ideal-auth, cookie bridge, middleware, route protection, rate limit, rate limiting, password reset, forgot password, email verification, remember me, recovery code, CSRF, encrypt, decrypt, hash, bcrypt, token, secret, session cookie, multi-tenant, cross-domain, tenant, transfer token, federated logout, OAuth redirect, central login, login session, attemptUser, sessionFields, cookie-backed session, resolveUser, token refresh, refresh token, access token, OIDC, passkey, passkeys, WebAuthn, passwordless, biometric, fingerprint.
 ---
 
 You are an expert on `ideal-auth`, the auth primitives library for the JS ecosystem. You have complete knowledge of its API, patterns, security model, and framework integrations. Use this knowledge to help users implement authentication correctly.
@@ -1622,6 +1622,53 @@ await auth().login(user, { remember: true });
 
 ---
 
+## Passkeys (WebAuthn)
+
+Passkeys use public-key cryptography for passwordless authentication. ideal-auth handles the session after verification — the WebAuthn protocol is handled by `@simplewebauthn/server` and `@simplewebauthn/browser`.
+
+No `hash` or `bcryptjs` needed — there are no passwords.
+
+### Flow
+
+```
+Registration: browser creates key pair → store public key in DB
+Authentication: server sends challenge → browser signs it → server verifies → auth().login(user)
+```
+
+### After WebAuthn verification, create session with ideal-auth
+
+```ts
+import { verifyAuthenticationResponse } from '@simplewebauthn/server';
+import { auth } from './auth';
+
+const verification = await verifyAuthenticationResponse({
+  response: body,
+  expectedChallenge,
+  expectedOrigin: origin,
+  expectedRPID: rpID,
+  credential: { id: passkey.id, publicKey: Buffer.from(passkey.publicKey, 'base64url'), counter: passkey.counter },
+});
+
+if (verification.verified) {
+  // Update signature counter (replay protection)
+  await db.passkey.update({ where: { id: passkey.id }, data: { counter: Number(verification.authenticationInfo.newCounter) } });
+
+  const user = await db.user.findUnique({ where: { id: passkey.userId } });
+  await auth().login(user); // session created — done
+}
+```
+
+### Key points
+- Install: `bun add @simplewebauthn/server @simplewebauthn/browser`
+- Store challenges in httpOnly cookies (5-min expiry), not client-side
+- Always update the signature counter after authentication
+- Set `rpID` to root domain (e.g., `example.com`) — works across subdomains
+- `userVerification: 'preferred'` for most apps, `'required'` for high-security
+- Passkeys with user verification can replace 2FA (biometric/PIN is the second factor)
+- Rate limit the options and verify endpoints
+
+---
+
 ## Open Redirect Prevention
 
 Always validate redirect URLs after login. Never redirect to user-supplied absolute URLs.