@strav/auth 0.2.13

package/README.md

@@ -0,0 +1,168 @@
+# @strav/auth
+
+Authentication primitives for the [Strav](https://strav.dev) framework. Provides unopinionated, composable utilities for building secure authentication systems.
+
+## Install
+
+```bash
+bun add @strav/auth
+```
+
+Requires `@strav/kernel` as a peer dependency.
+
+## Features
+
+- **JWT Management** - Sign and verify JWTs using the jose library
+- **Token Utilities** - Signed opaque tokens, magic links, refresh tokens
+- **TOTP/2FA** - Time-based one-time passwords and recovery codes
+- **Password Validation** - Strength checking and policy enforcement
+- **OAuth Helpers** - State management for OAuth flows
+
+## Usage
+
+### JWT Operations
+
+```ts
+import { signJWT, verifyJWT, createAccessToken, verifyAccessToken } from '@strav/auth'
+
+// Sign a JWT
+const token = await signJWT(
+  { userId: 123, role: 'admin' },
+  'your-secret-key',
+  { expiresIn: '1h', issuer: 'my-app' }
+)
+
+// Verify a JWT
+const payload = await verifyJWT(token, 'your-secret-key', {
+  issuer: 'my-app'
+})
+
+// Create access/refresh token pairs
+const accessToken = await createAccessToken(userId, secret)
+const userId = await verifyAccessToken(accessToken, secret)
+```
+
+### TOTP / Two-Factor Authentication
+
+```ts
+import { generateSecret, verifyTotp, totpUri, generateRecoveryCodes } from '@strav/auth'
+
+// Generate a secret for a user
+const { raw, base32 } = generateSecret()
+
+// Create QR code URI for authenticator apps
+const uri = totpUri({
+  secret: base32,
+  issuer: 'MyApp',
+  account: 'user@example.com'
+})
+
+// Verify a TOTP code
+const valid = await verifyTotp(raw, '123456')
+
+// Generate recovery codes
+const codes = generateRecoveryCodes(8)
+```
+
+### Password Validation
+
+```ts
+import { validatePassword, calculatePasswordStrength, generatePassword } from '@strav/auth'
+
+// Validate against a policy
+const result = validatePassword(password, {
+  minLength: 12,
+  requireUppercase: true,
+  requireNumbers: true,
+  requireSpecialChars: true
+})
+
+if (!result.valid) {
+  console.log(result.errors)
+}
+
+// Calculate password strength
+const strength = calculatePasswordStrength(password)
+console.log(strength.score, strength.label) // 0-4, "Very Weak" to "Very Strong"
+
+// Generate a secure password
+const password = generatePassword(16)
+```
+
+### Signed Opaque Tokens
+
+```ts
+import { createSignedToken, verifySignedToken } from '@strav/auth'
+
+// Create an encrypted, tamper-proof token
+const token = createSignedToken(
+  { sub: userId, typ: 'password-reset' },
+  60 // expires in 60 minutes
+)
+
+// Verify and decode
+const payload = verifySignedToken(token)
+```
+
+### Magic Links
+
+```ts
+import { createMagicLinkToken, verifyMagicLinkToken } from '@strav/auth'
+
+// Create a magic link token
+const token = createMagicLinkToken(userId, {
+  email: 'user@example.com',
+  redirect: '/dashboard',
+  expiresInMinutes: 15
+})
+
+// Verify the token
+const payload = verifyMagicLinkToken(token)
+```
+
+### OAuth State Management
+
+```ts
+import { createOAuthStateStore } from '@strav/auth'
+
+// Create a state store (implement storage backend)
+const stateStore = createOAuthStateStore({
+  async store(state) { /* save to Redis/DB */ },
+  async retrieve(value) { /* fetch from storage */ },
+  async delete(value) { /* remove from storage */ },
+  ttl: 600 // 10 minutes
+})
+
+// Generate state for OAuth flow
+const stateValue = await stateStore.generate({
+  redirect: '/dashboard',
+  data: { provider: 'github' }
+})
+
+// Verify state after OAuth callback
+const state = await stateStore.verify(stateValue)
+```
+
+## Architecture
+
+This package provides low-level authentication primitives without imposing any specific authentication flow or pattern. It's designed to be:
+
+- **Unopinionated** - Build any authentication pattern you need
+- **Composable** - Mix and match utilities as required
+- **Secure** - Uses modern standards and best practices
+- **Framework-agnostic** - Works with any HTTP framework
+
+## Migrating from @strav/jina
+
+If you're using the deprecated `@strav/jina` package, you can migrate by:
+
+1. Installing `@strav/auth`
+2. Replacing jina's TOTP/token utilities with auth equivalents
+3. Building your own authentication handlers using these primitives
+4. Removing the jina dependency
+
+The main difference is that `@strav/auth` doesn't provide pre-built routes or handlers - you implement those yourself using the utilities provided.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@strav/auth",
+  "version": "0.2.13",
+  "type": "module",
+  "description": "Authentication primitives for the Strav framework",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts",
+    "./jwt": "./src/jwt/index.ts",
+    "./tokens": "./src/tokens/index.ts",
+    "./totp": "./src/totp/index.ts",
+    "./oauth": "./src/oauth/index.ts",
+    "./validation": "./src/validation/index.ts"
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "tsconfig.json"
+  ],
+  "peerDependencies": {
+    "@strav/kernel": "0.2.13"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @strav/auth - Authentication primitives for the Strav framework
+ *
+ * A collection of unopinionated, composable authentication utilities
+ * for building secure authentication systems.
+ */
+
+// JWT utilities
+export * from './jwt/index.ts'
+
+// Token management
+export * from './tokens/index.ts'
+
+// TOTP / Two-factor authentication
+export * from './totp/index.ts'
+
+// OAuth utilities
+export * from './oauth/index.ts'
+
+// Password validation
+export * from './validation/index.ts'

package/src/jwt/index.ts

@@ -0,0 +1,24 @@
+// JWT signing
+export {
+  signJWT,
+  createAccessToken,
+  createRefreshToken
+} from './sign.ts'
+
+// JWT verification
+export {
+  verifyJWT,
+  verifyAccessToken,
+  verifyRefreshToken,
+  decodeJWT
+} from './verify.ts'
+
+// Types
+export type {
+  JWTPayload,
+  JWTHeader,
+  JWTAlgorithm,
+  JWTSignOptions,
+  JWTVerifyOptions,
+  JWTKeyPair
+} from './types.ts'

package/src/jwt/sign.ts

@@ -0,0 +1,129 @@
+import type { JWTPayload, JWTHeader, JWTSignOptions, JWTAlgorithm } from './types.ts'
+import {
+  base64urlEncode,
+  createHmacSignature,
+  parseExpirationTime,
+  getUnixTimestamp,
+  getHashAlgorithm,
+} from './utils.ts'
+
+/**
+ * Sign a JWT using built-in crypto with sensible defaults.
+ * Zero external dependencies.
+ *
+ * @param payload - The JWT payload
+ * @param secret - The secret key for HMAC
+ * @param options - Additional JWT options
+ * @returns Signed JWT string
+ */
+export async function signJWT(
+  payload: JWTPayload,
+  secret: Uint8Array | string,
+  options: JWTSignOptions = {}
+): Promise<string> {
+  const {
+    algorithm = 'HS256',
+    expiresIn,
+    notBefore,
+    issuer,
+    audience,
+    subject,
+    jwtId,
+  } = options
+
+  // Build the payload with standard claims
+  const now = getUnixTimestamp()
+  const jwtPayload: JWTPayload = {
+    ...payload,
+    iat: now,
+  }
+
+  // Set standard claims if provided
+  if (expiresIn) {
+    const expSeconds = parseExpirationTime(expiresIn)
+    jwtPayload.exp = now + expSeconds
+  }
+  if (notBefore) {
+    const nbfSeconds = typeof notBefore === 'number'
+      ? notBefore
+      : parseExpirationTime(notBefore)
+    jwtPayload.nbf = now + nbfSeconds
+  }
+  if (issuer) jwtPayload.iss = issuer
+  if (audience) jwtPayload.aud = audience
+  if (subject) jwtPayload.sub = subject
+  if (jwtId) jwtPayload.jti = jwtId
+
+  // Build the header
+  const header: JWTHeader = {
+    alg: algorithm,
+    typ: 'JWT',
+  }
+
+  // Encode header and payload
+  const encodedHeader = base64urlEncode(JSON.stringify(header))
+  const encodedPayload = base64urlEncode(JSON.stringify(jwtPayload))
+
+  // Create the message to sign
+  const message = `${encodedHeader}.${encodedPayload}`
+
+  // Sign the message
+  const hashAlg = getHashAlgorithm(algorithm)
+  const signature = createHmacSignature(message, secret, hashAlg)
+
+  // Return the complete JWT
+  return `${message}.${signature}`
+}
+
+/**
+ * Create an access token with user claims.
+ *
+ * @param userId - User identifier
+ * @param secret - Secret key
+ * @param claims - Additional claims to include
+ * @param options - JWT options
+ */
+export async function createAccessToken(
+  userId: string | number,
+  secret: Uint8Array | string,
+  claims: Record<string, unknown> = {},
+  options: JWTSignOptions = {}
+): Promise<string> {
+  return signJWT(
+    {
+      sub: String(userId),
+      type: 'access',
+      ...claims,
+    },
+    secret,
+    {
+      expiresIn: '15m',
+      ...options,
+    }
+  )
+}
+
+/**
+ * Create a longer-lived refresh token.
+ *
+ * @param userId - User identifier
+ * @param secret - Secret key
+ * @param options - JWT options
+ */
+export async function createRefreshToken(
+  userId: string | number,
+  secret: Uint8Array | string,
+  options: JWTSignOptions = {}
+): Promise<string> {
+  return signJWT(
+    {
+      sub: String(userId),
+      type: 'refresh',
+    },
+    secret,
+    {
+      expiresIn: '30d',
+      ...options,
+    }
+  )
+}

package/src/jwt/types.ts

@@ -0,0 +1,80 @@
+/**
+ * JWT type definitions for the auth package.
+ * Zero external dependencies.
+ */
+
+/**
+ * Standard JWT payload claims.
+ */
+export interface JWTPayload {
+  /** Issuer */
+  iss?: string
+  /** Subject */
+  sub?: string
+  /** Audience */
+  aud?: string | string[]
+  /** Expiration time (seconds since Unix epoch) */
+  exp?: number
+  /** Not before time (seconds since Unix epoch) */
+  nbf?: number
+  /** Issued at (seconds since Unix epoch) */
+  iat?: number
+  /** JWT ID */
+  jti?: string
+  /** Additional claims */
+  [key: string]: unknown
+}
+
+/**
+ * JWT header.
+ */
+export interface JWTHeader {
+  /** Algorithm */
+  alg: string
+  /** Type (usually "JWT") */
+  typ?: string
+  /** Additional header params */
+  [key: string]: unknown
+}
+
+export type JWTAlgorithm =
+  | 'HS256' | 'HS384' | 'HS512'  // HMAC (supported)
+
+export interface JWTSignOptions {
+  /** Algorithm to use for signing (default: HS256) */
+  algorithm?: JWTAlgorithm
+  /** Expiration time (e.g., '15m', '1h', '7d') */
+  expiresIn?: string | number
+  /** Not before time */
+  notBefore?: string | number
+  /** Token issuer */
+  issuer?: string
+  /** Token audience */
+  audience?: string | string[]
+  /** Token subject */
+  subject?: string
+  /** JWT ID */
+  jwtId?: string
+}
+
+export interface JWTVerifyOptions {
+  /** Allowed algorithms */
+  algorithms?: JWTAlgorithm[]
+  /** Expected issuer */
+  issuer?: string | string[]
+  /** Expected audience */
+  audience?: string | string[]
+  /** Expected subject */
+  subject?: string
+  /** Required claims that must be present */
+  requiredClaims?: string[]
+}
+
+export interface JWTKeyPair {
+  /** Private key for signing */
+  privateKey: Uint8Array | string
+  /** Public key for verification */
+  publicKey: Uint8Array | string
+  /** Key algorithm */
+  algorithm: JWTAlgorithm
+}

package/src/jwt/utils.ts

@@ -0,0 +1,109 @@
+/**
+ * JWT utility functions - zero external dependencies.
+ * Uses only Node.js/Bun built-in crypto APIs.
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto'
+
+/**
+ * Base64url encode a string or buffer.
+ */
+export function base64urlEncode(data: string | Buffer): string {
+  const buffer = typeof data === 'string' ? Buffer.from(data) : data
+  return buffer.toString('base64url')
+}
+
+/**
+ * Base64url decode a string.
+ */
+export function base64urlDecode(data: string): string {
+  return Buffer.from(data, 'base64url').toString('utf8')
+}
+
+/**
+ * Create HMAC signature for JWT.
+ */
+export function createHmacSignature(
+  message: string,
+  secret: string | Uint8Array,
+  algorithm: 'sha256' | 'sha384' | 'sha512'
+): string {
+  const key = typeof secret === 'string' ? secret : Buffer.from(secret)
+  return createHmac(algorithm, key)
+    .update(message)
+    .digest('base64url')
+}
+
+/**
+ * Verify HMAC signature with timing-safe comparison.
+ */
+export function verifyHmacSignature(
+  message: string,
+  signature: string,
+  secret: string | Uint8Array,
+  algorithm: 'sha256' | 'sha384' | 'sha512'
+): boolean {
+  const expected = createHmacSignature(message, secret, algorithm)
+  const expectedBuffer = Buffer.from(expected)
+  const signatureBuffer = Buffer.from(signature)
+
+  // Must be same length for timingSafeEqual
+  if (expectedBuffer.length !== signatureBuffer.length) {
+    return false
+  }
+
+  return timingSafeEqual(expectedBuffer, signatureBuffer)
+}
+
+/**
+ * Parse expiration time strings like "15m", "1h", "30d" to seconds.
+ */
+export function parseExpirationTime(exp: string | number): number {
+  if (typeof exp === 'number') {
+    return exp
+  }
+
+  const match = exp.match(/^(\d+)([smhd])$/)
+  if (!match) {
+    throw new Error(`Invalid expiration time format: ${exp}`)
+  }
+
+  const value = parseInt(match[1]!, 10)
+  const unit = match[2]!
+
+  switch (unit) {
+    case 's':
+      return value
+    case 'm':
+      return value * 60
+    case 'h':
+      return value * 3600
+    case 'd':
+      return value * 86400
+    default:
+      throw new Error(`Invalid time unit: ${unit}`)
+  }
+}
+
+/**
+ * Get Unix timestamp in seconds.
+ */
+export function getUnixTimestamp(): number {
+  return Math.floor(Date.now() / 1000)
+}
+
+/**
+ * Map algorithm string to hash algorithm.
+ */
+export function getHashAlgorithm(alg: string): 'sha256' | 'sha384' | 'sha512' {
+  switch (alg) {
+    case 'HS256':
+      return 'sha256'
+    case 'HS384':
+      return 'sha384'
+    case 'HS512':
+      return 'sha512'
+    default:
+      throw new Error(`Unsupported algorithm: ${alg}`)
+  }
+}