ideal-auth 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ramon Malcolm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,533 @@
+# ideal-auth
+
+Auth primitives for the JS ecosystem. Zero framework dependencies. Inspired by Laravel's `Auth` and `Hash` facades.
+
+Provide a cookie bridge (3 functions) once during setup, and `auth().login(user)` just works — handles session creation, cookie encryption, and storage internally via [iron-session](https://github.com/vvo/iron-session).
+
+## Install
+
+```bash
+bun add ideal-auth
+```
+
+## Generate Secret
+
+```bash
+bunx ideal-auth secret
+```
+
+```
+IDEAL_AUTH_SECRET=aLThikMgJKMBB5WZLE-lCaOQUdgPWU8BHRv99bkYaVY
+```
+
+Copy the output into your `.env` file. The secret must be at least 32 characters.
+
+## Quick Start
+
+```typescript
+// lib/auth.ts
+import { createAuth, createHash } from 'ideal-auth';
+import { cookies } from 'next/headers';
+import { db } from '@/lib/db';
+
+export const hash = createHash({ rounds: 12 });
+
+export const auth = createAuth({
+  secret: process.env.IDEAL_AUTH_SECRET!, // 32+ characters
+
+  cookie: {
+    get: async (name) => (await cookies()).get(name)?.value,
+    set: async (name, value, opts) => (await cookies()).set(name, value, opts),
+    delete: async (name) => (await cookies()).delete(name),
+  },
+
+  hash,
+
+  resolveUser: async (id) => {
+    return db.user.findUnique({ where: { id } });
+  },
+
+  resolveUserByCredentials: async (credentials) => {
+    return db.user.findUnique({ where: { email: credentials.email } });
+  },
+});
+```
+
+```typescript
+// Server Action
+'use server';
+import { auth } from '@/lib/auth';
+
+// Call auth() once per request and reuse the instance — it caches the
+// session payload and user, so subsequent calls avoid redundant work.
+const session = auth();
+
+// Login with credentials (password verified automatically)
+const success = await session.attempt({ email, password });
+
+// Login with a user object directly
+await session.login(user);
+
+// Login by user ID
+await session.loginById('user-123');
+
+// Check session
+const isLoggedIn = await session.check();
+const currentUser = await session.user();
+const userId = await session.id();
+
+// Logout
+await session.logout();
+```
+
+## API
+
+### `createAuth(config)`
+
+Returns a function `auth()` that creates an `AuthInstance` on each call.
+
+#### Config
+
+| Field | Type | Required | Default |
+| --- | --- | --- | --- |
+| `secret` | `string` | Yes | — |
+| `cookie` | `CookieBridge` | Yes | — |
+| `resolveUser` | `(id: string) => Promise<User \| null>` | Yes | — |
+| `hash` | `HashInstance` | No | — |
+| `resolveUserByCredentials` | `(creds: Record<string, any>) => Promise<User \| null>` | No | — |
+| `credentialKey` | `string` | No | `'password'` |
+| `passwordField` | `string` | No | `'password'` |
+| `attemptUser` | `(creds: Record<string, any>) => Promise<User \| null>` | No | — |
+| `session.cookieName` | `string` | No | `'ideal_session'` |
+| `session.maxAge` | `number` (seconds) | No | `604800` (7 days) |
+| `session.rememberMaxAge` | `number` (seconds) | No | `2592000` (30 days) |
+| `session.cookie` | `Partial<ConfigurableCookieOptions>` | No | secure in prod, sameSite lax, path / (`httpOnly` is always `true` — not configurable) |
+
+#### AuthInstance Methods
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| `login(user, options?)` | `Promise<void>` | Set session cookie for the given user |
+| `loginById(id, options?)` | `Promise<void>` | Resolve user by ID, then set session cookie |
+| `attempt(credentials, options?)` | `Promise<boolean>` | Find user, verify password, login if valid |
+| `logout()` | `Promise<void>` | Delete session cookie |
+| `check()` | `Promise<boolean>` | Is the session valid? |
+| `user()` | `Promise<User \| null>` | Get the authenticated user |
+| `id()` | `Promise<string \| null>` | Get the authenticated user's ID |
+
+All login methods accept an optional `LoginOptions` object:
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `remember` | `boolean` | `undefined` | `true`: use `rememberMaxAge` (30 days). `false`: session cookie (expires when browser closes). Omitted: use default `maxAge` (7 days). |
+
+```typescript
+const session = auth();
+
+// Remember me — 30-day persistent cookie
+await session.attempt({ email, password }, { remember: true });
+
+// No remember — session cookie, expires when browser closes
+await session.login(user, { remember: false });
+
+// Default — 7-day cookie
+await session.login(user);
+```
+
+#### `attempt()` — Two Modes
+
+**Laravel-style (recommended):** Provide `hash` and `resolveUserByCredentials` in config. `attempt()` strips the credential key (default `password`) from the credentials, looks up the user with the remaining fields, and calls `hash.verify()` against the stored hash automatically.
+
+```typescript
+const auth = createAuth({
+  // ...
+  hash,
+  resolveUserByCredentials: async (creds) => {
+    return db.user.findUnique({ where: { email: creds.email } });
+  },
+});
+
+const session = auth();
+await session.attempt({ email, password }); // password verified internally
+```
+
+**Manual (escape hatch):** Provide `attemptUser` for full control over lookup and verification. Takes precedence over the Laravel-style config if both are provided.
+
+```typescript
+const auth = createAuth({
+  // ...
+  attemptUser: async (creds) => {
+    const user = await db.user.findUnique({ where: { email: creds.email } });
+    if (!user) return null;
+    if (!(await hash.verify(creds.password, user.password))) return null;
+    return user;
+  },
+});
+```
+
+---
+
+### `createHash(config?)`
+
+Returns a `HashInstance` using bcrypt.
+
+| Option | Type | Default |
+| --- | --- | --- |
+| `rounds` | `number` | `12` |
+
+```typescript
+import { createHash } from 'ideal-auth';
+
+const hash = createHash({ rounds: 12 });
+
+const hashed = await hash.make('password');
+const valid  = await hash.verify('password', hashed); // true
+```
+
+---
+
+### Crypto Utilities
+
+Standalone functions for tokens, signing, and encryption. No framework dependencies — uses `node:crypto`.
+
+#### `generateToken(bytes?)`
+
+Generate a cryptographically secure random hex string.
+
+```typescript
+import { generateToken } from 'ideal-auth';
+
+const token = generateToken();     // 64 hex chars (32 bytes)
+const short = generateToken(16);   // 32 hex chars (16 bytes)
+```
+
+#### `signData(data, secret)` / `verifySignature(data, signature, secret)`
+
+HMAC-SHA256 signing with timing-safe comparison.
+
+```typescript
+import { signData, verifySignature } from 'ideal-auth';
+
+const sig = signData('user:123:reset', secret);
+const valid = verifySignature('user:123:reset', sig, secret); // true
+```
+
+#### `encrypt(plaintext, secret)` / `decrypt(ciphertext, secret)`
+
+AES-256-GCM encryption with scrypt key derivation. Output is base64url-encoded.
+
+```typescript
+import { encrypt, decrypt } from 'ideal-auth';
+
+const encrypted = await encrypt('sensitive data', secret);
+const decrypted = await decrypt(encrypted, secret); // 'sensitive data'
+```
+
+#### `timingSafeEqual(a, b)`
+
+Constant-time string comparison to prevent timing attacks.
+
+```typescript
+import { timingSafeEqual } from 'ideal-auth';
+
+timingSafeEqual('abc', 'abc'); // true
+timingSafeEqual('abc', 'xyz'); // false
+```
+
+---
+
+### `createTokenVerifier(config)`
+
+Signed, expiring tokens for password resets, email verification, magic links, invites — any flow that needs a one-time, time-limited token tied to a user. Create one instance per use case with its own secret/expiry. You handle delivery (email, SMS) — ideal-auth handles the token lifecycle.
+
+#### Config
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `secret` | `string` | — | Secret for HMAC signing (required) |
+| `expiryMs` | `number` | `3600000` (1 hour) | Token lifetime in milliseconds |
+
+#### Password Reset
+
+```typescript
+import { createTokenVerifier, createHash } from 'ideal-auth';
+
+const passwordReset = createTokenVerifier({
+  secret: process.env.IDEAL_AUTH_SECRET! + '-reset',
+  expiryMs: 60 * 60 * 1000, // 1 hour
+});
+
+// Forgot password — generate token, send it via email (POST body, not URL query)
+const token = passwordReset.createToken(user.id);
+await sendEmail(user.email, `https://example.com/reset/${token}`);
+
+// Reset password — verify token
+const result = passwordReset.verifyToken(token);
+if (!result) throw new Error('Invalid or expired token');
+
+// IMPORTANT: Invalidate the token by checking iatMs against the user's last
+// password change. Tokens are stateless — without this check, a token remains
+// valid until expiry even after the password is changed.
+if (result.iatMs < user.passwordChangedAt) throw new Error('Token already used');
+
+// result.userId is now available — update the password
+const hash = createHash();
+await db.user.update({
+  where: { id: result.userId },
+  data: { password: await hash.make(newPassword), passwordChangedAt: Date.now() },
+});
+```
+
+#### Email Verification
+
+```typescript
+import { createTokenVerifier } from 'ideal-auth';
+
+const emailVerification = createTokenVerifier({
+  secret: process.env.IDEAL_AUTH_SECRET! + '-email',
+  expiryMs: 24 * 60 * 60 * 1000, // 24 hours
+});
+
+// After registration — generate token, send verification email
+const token = emailVerification.createToken(user.id);
+await sendEmail(user.email, `https://example.com/verify/${token}`);
+
+// Verify — validate token from the URL
+const result = emailVerification.verifyToken(token);
+if (!result) throw new Error('Invalid or expired token');
+
+// Mark user as verified
+await db.user.update({
+  where: { id: result.userId },
+  data: { emailVerifiedAt: new Date() },
+});
+```
+
+Use different secrets (or suffixes) per use case so tokens aren't interchangeable between flows.
+
+**Token invalidation:** Tokens are stateless and valid until expiry. `verifyToken()` returns `iatMs` (issued-at timestamp in milliseconds) so you can reject tokens issued before a relevant event (e.g. password change, email already verified). You must implement this check — the library does not track token usage.
+
+---
+
+### Two-Factor Authentication (TOTP)
+
+`createTOTP()` provides TOTP (RFC 6238) generation and verification — no framework dependencies.
+
+#### Setup Flow
+
+```typescript
+import { createTOTP } from 'ideal-auth';
+
+const totp = createTOTP();
+
+// 1. Generate a secret for the user
+const secret = totp.generateSecret();
+// Store `secret` in your database (encrypted) for the user
+
+// 2. Generate a QR code URI for the user to scan
+const uri = totp.generateQrUri({
+  secret,
+  issuer: 'MyApp',
+  account: user.email,
+});
+// Render `uri` as a QR code (use any QR library)
+
+// 3. Verify the first code to confirm setup
+const valid = totp.verify(codeFromUser, secret);
+if (valid) {
+  // Mark 2FA as enabled for the user
+}
+```
+
+#### Login Verification
+
+```typescript
+const totp = createTOTP();
+
+// After password login, prompt for TOTP code
+const valid = totp.verify(codeFromUser, user.totpSecret);
+if (!valid) {
+  throw new Error('Invalid 2FA code');
+}
+```
+
+**Replay protection:** A valid TOTP code can be verified multiple times within the acceptance window (default 90 seconds). For mission-critical apps, store the last used time step per user and reject codes at or before that step.
+
+#### Config
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `digits` | `number` | `6` | Number of digits in the code |
+| `period` | `number` | `30` | Time step in seconds |
+| `window` | `number` | `1` | Window of ±N steps to account for clock drift |
+
+#### Recovery Codes
+
+Generate backup codes for users who lose access to their authenticator app.
+
+```typescript
+import { generateRecoveryCodes, verifyRecoveryCode, createHash } from 'ideal-auth';
+
+const hash = createHash();
+
+// Generate codes — returns plain codes to show the user AND hashed codes to store
+const { codes, hashed } = await generateRecoveryCodes(hash);
+// Show `codes` to the user once, store `hashed` in the database
+
+// Verify a recovery code during login
+const { valid, remaining } = await verifyRecoveryCode(code, user.hashedRecoveryCodes, hash);
+if (valid) {
+  // Update stored hashes to `remaining` (removes the used code)
+  await db.user.update({ where: { id: user.id }, data: { recoveryCodes: remaining } });
+}
+```
+
+---
+
+### Rate Limiting
+
+In-memory rate limiter. Provide a custom `RateLimitStore` for Redis/DB-backed limiting.
+
+```typescript
+import { createRateLimiter } from 'ideal-auth';
+
+const limiter = createRateLimiter({
+  maxAttempts: 5,
+  windowMs: 60_000, // 1 minute
+});
+
+const result = await limiter.attempt('login:user@example.com');
+// { allowed: true, remaining: 4, resetAt: Date }
+
+// Reset after successful login
+await limiter.reset('login:user@example.com');
+```
+
+#### Full Login Action Example (Next.js)
+
+```typescript
+'use server';
+
+import { redirect } from 'next/navigation';
+import { headers } from 'next/headers';
+import { auth } from '@/lib/auth';
+import { createRateLimiter } from 'ideal-auth';
+
+const limiter = createRateLimiter({
+  maxAttempts: 5,
+  windowMs: 60_000,
+});
+
+export async function loginAction(formData: FormData) {
+  const email = formData.get('email') as string;
+  const password = formData.get('password') as string;
+
+  // NOTE: x-forwarded-for is only trustworthy behind a reverse proxy you
+  // control (e.g. Vercel, Cloudflare, nginx). Without one, it's spoofable.
+  const headerStore = await headers();
+  const ip = headerStore.get('x-forwarded-for') ?? '127.0.0.1';
+  const key = `login:${ip}`;
+
+  const { allowed, remaining, resetAt } = await limiter.attempt(key);
+
+  if (!allowed) {
+    const seconds = Math.ceil((resetAt.getTime() - Date.now()) / 1000);
+    redirect(`/?error=rate_limit&retry=${seconds}`);
+  }
+
+  const session = auth();
+  const success = await session.attempt({ email, password });
+
+  if (!success) {
+    redirect(`/?error=invalid&remaining=${remaining}`);
+  }
+
+  await limiter.reset(key);
+  redirect('/');
+}
+```
+
+#### Custom Store
+
+Implement the `RateLimitStore` interface for persistent storage:
+
+```typescript
+import { createRateLimiter, type RateLimitStore } from 'ideal-auth';
+
+class RedisRateLimitStore implements RateLimitStore {
+  async increment(key: string, windowMs: number) {
+    // Redis INCR + PEXPIRE logic
+    return { count, resetAt };
+  }
+  async reset(key: string) {
+    // Redis DEL
+  }
+}
+
+const limiter = createRateLimiter({
+  maxAttempts: 5,
+  windowMs: 60_000,
+  store: new RedisRateLimitStore(),
+});
+```
+
+---
+
+## How It Works
+
+Sessions are **stateless, encrypted cookies** powered by iron-session (AES-256-GCM + HMAC integrity).
+
+1. **`login(user)`** — Creates a `SessionPayload { uid, iat, exp }`, seals it with iron-session, writes the encrypted string to the cookie via the bridge.
+2. **`check()` / `user()` / `id()`** — Reads the cookie via the bridge, unseals the payload, checks expiry. `user()` additionally calls `resolveUser(id)` to fetch the full user.
+3. **`logout()`** — Deletes the cookie via the bridge.
+
+No session IDs. No server-side storage. The encrypted cookie *is* the session.
+
+---
+
+## Cookie Bridge
+
+The bridge decouples ideal-auth from any framework. Three functions:
+
+```typescript
+interface CookieBridge {
+  get(name: string): Promise<string | undefined> | string | undefined;
+  set(name: string, value: string, options: CookieOptions): Promise<void> | void;
+  delete(name: string): Promise<void> | void;
+}
+```
+
+**Next.js** (App Router):
+
+```typescript
+import { cookies } from 'next/headers';
+
+cookie: {
+  get: async (name) => (await cookies()).get(name)?.value,
+  set: async (name, value, opts) => (await cookies()).set(name, value, opts),
+  delete: async (name) => (await cookies()).delete(name),
+}
+```
+
+**Express / Hono / any framework** — adapt to your framework's cookie API.
+
+---
+
+## Dependencies
+
+| Package | Purpose |
+| --- | --- |
+| `iron-session` | Session sealing/unsealing (AES-256-GCM + HMAC) |
+| `bcryptjs` | Password hashing |
+
+Zero framework imports. Works in Node, Bun, Deno, and edge runtimes.
+
+## Support
+
+If this saved you time, consider supporting the project:
+
+[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow?logo=buy-me-a-coffee&logoColor=white)](https://buymeacoffee.com/ramonmalcolm)
+
+## License
+
+[MIT](./LICENSE.md)

package/dist/auth-instance.d.ts

@@ -0,0 +1,17 @@
+import type { AnyUser, AuthInstance, ConfigurableCookieOptions, CookieBridge, HashInstance } from './types';
+interface AuthInstanceDeps<TUser extends AnyUser> {
+    secret: string;
+    cookie: CookieBridge;
+    cookieName: string;
+    maxAge: number;
+    rememberMaxAge: number;
+    cookieOptions: ConfigurableCookieOptions;
+    resolveUser: (id: string) => Promise<TUser | null>;
+    hash?: HashInstance;
+    resolveUserByCredentials?: (credentials: Record<string, any>) => Promise<TUser | null>;
+    credentialKey: string;
+    passwordField: string;
+    attemptUser?: (credentials: Record<string, any>) => Promise<TUser | null>;
+}
+export declare function createAuthInstance<TUser extends AnyUser>(deps: AuthInstanceDeps<TUser>): AuthInstance<TUser>;
+export {};

package/dist/auth-instance.js

@@ -0,0 +1,92 @@
+import { seal, unseal } from './session/seal';
+import { buildCookieOptions } from './session/cookie';
+export function createAuthInstance(deps) {
+    let cachedPayload;
+    let cachedUser;
+    async function readSession() {
+        if (cachedPayload !== undefined)
+            return cachedPayload;
+        const raw = await deps.cookie.get(deps.cookieName);
+        if (!raw) {
+            cachedPayload = null;
+            return null;
+        }
+        cachedPayload = await unseal(raw, deps.secret);
+        return cachedPayload;
+    }
+    async function writeSession(user, options) {
+        const maxAge = options?.remember ? deps.rememberMaxAge : deps.maxAge;
+        const now = Math.floor(Date.now() / 1000);
+        const payload = {
+            uid: String(user.id),
+            iat: now,
+            exp: now + maxAge,
+        };
+        const sealed = await seal(payload, deps.secret);
+        const opts = options?.remember === false
+            ? buildCookieOptions(undefined, deps.cookieOptions)
+            : buildCookieOptions(maxAge, deps.cookieOptions);
+        await deps.cookie.set(deps.cookieName, sealed, opts);
+        cachedPayload = payload;
+        cachedUser = user;
+    }
+    return {
+        async login(user, options) {
+            await writeSession(user, options);
+        },
+        async loginById(id, options) {
+            const user = await deps.resolveUser(id);
+            if (!user)
+                throw new Error('Login failed');
+            await writeSession(user, options);
+        },
+        async attempt(credentials, options) {
+            // Escape hatch: attemptUser handles everything
+            if (deps.attemptUser) {
+                const user = await deps.attemptUser(credentials);
+                if (!user)
+                    return false;
+                await writeSession(user, options);
+                return true;
+            }
+            // Laravel-style: strip password, resolve user, verify hash
+            if (deps.hash && deps.resolveUserByCredentials) {
+                const { [deps.credentialKey]: password, ...lookup } = credentials;
+                const user = await deps.resolveUserByCredentials(lookup);
+                if (!user)
+                    return false;
+                const storedHash = user[deps.passwordField];
+                if (!storedHash || !(await deps.hash.verify(password, storedHash))) {
+                    return false;
+                }
+                await writeSession(user, options);
+                return true;
+            }
+            throw new Error('Provide either attemptUser() or both hash + resolveUserByCredentials in config to use attempt()');
+        },
+        async logout() {
+            await deps.cookie.delete(deps.cookieName);
+            cachedPayload = null;
+            cachedUser = null;
+        },
+        async check() {
+            const session = await readSession();
+            return session !== null;
+        },
+        async user() {
+            if (cachedUser !== undefined)
+                return cachedUser;
+            const session = await readSession();
+            if (!session) {
+                cachedUser = null;
+                return null;
+            }
+            cachedUser = await deps.resolveUser(session.uid);
+            return cachedUser;
+        },
+        async id() {
+            const session = await readSession();
+            return session?.uid ?? null;
+        },
+    };
+}

package/dist/auth.d.ts

@@ -0,0 +1,2 @@
+import type { AnyUser, AuthInstance, AuthConfig } from './types';
+export declare function createAuth<TUser extends AnyUser = AnyUser>(config: AuthConfig<TUser>): () => AuthInstance<TUser>;

package/dist/auth.js

@@ -0,0 +1,25 @@
+import { createAuthInstance } from './auth-instance';
+const SESSION_DEFAULTS = {
+    cookieName: 'ideal_session',
+    maxAge: 60 * 60 * 24 * 7, // 7 days
+    rememberMaxAge: 60 * 60 * 24 * 30, // 30 days
+};
+export function createAuth(config) {
+    if (!config.secret || config.secret.length < 32) {
+        throw new Error('secret must be at least 32 characters');
+    }
+    return () => createAuthInstance({
+        secret: config.secret,
+        cookie: config.cookie,
+        cookieName: config.session?.cookieName ?? SESSION_DEFAULTS.cookieName,
+        maxAge: config.session?.maxAge ?? SESSION_DEFAULTS.maxAge,
+        rememberMaxAge: config.session?.rememberMaxAge ?? SESSION_DEFAULTS.rememberMaxAge,
+        cookieOptions: config.session?.cookie ?? {},
+        resolveUser: config.resolveUser,
+        hash: config.hash,
+        resolveUserByCredentials: config.resolveUserByCredentials,
+        credentialKey: config.credentialKey ?? 'password',
+        passwordField: config.passwordField ?? 'password',
+        attemptUser: config.attemptUser,
+    });
+}

package/dist/bin/ideal-auth.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};