@strav/auth 0.2.13

package/src/jwt/verify.ts

@@ -0,0 +1,183 @@
+import type { JWTPayload, JWTHeader, JWTVerifyOptions } from './types.ts'
+import {
+  base64urlDecode,
+  verifyHmacSignature,
+  getUnixTimestamp,
+  getHashAlgorithm,
+} from './utils.ts'
+
+/**
+ * Verify a JWT and return its payload.
+ * Zero external dependencies.
+ *
+ * @param token - The JWT string to verify
+ * @param secret - The secret key for HMAC
+ * @param options - Verification options
+ * @returns The verified payload
+ * @throws If the token is invalid, expired, or doesn't meet requirements
+ */
+export async function verifyJWT<T extends JWTPayload = JWTPayload>(
+  token: string,
+  secret: Uint8Array | string,
+  options: JWTVerifyOptions = {}
+): Promise<T> {
+  const {
+    issuer,
+    audience,
+    subject,
+    algorithms = ['HS256', 'HS384', 'HS512'],
+    requiredClaims = [],
+  } = options
+
+  // Split token into parts
+  const parts = token.split('.')
+  if (parts.length !== 3) {
+    throw new Error('Invalid JWT format')
+  }
+
+  const [encodedHeader, encodedPayload, signature] = parts
+
+  // Decode header and payload
+  let header: JWTHeader
+  let payload: JWTPayload
+
+  try {
+    header = JSON.parse(base64urlDecode(encodedHeader!))
+    payload = JSON.parse(base64urlDecode(encodedPayload!))
+  } catch (error) {
+    throw new Error('Invalid JWT encoding')
+  }
+
+  // Verify algorithm is allowed
+  if (!algorithms.includes(header.alg as any)) {
+    throw new Error(`Algorithm ${header.alg} is not allowed`)
+  }
+
+  // Verify signature
+  const message = `${encodedHeader}.${encodedPayload}`
+  const hashAlg = getHashAlgorithm(header.alg)
+  const isValidSignature = verifyHmacSignature(message, signature!, secret, hashAlg)
+
+  if (!isValidSignature) {
+    throw new Error('Invalid JWT signature')
+  }
+
+  // Verify temporal claims
+  const now = getUnixTimestamp()
+
+  if (payload.exp !== undefined && now >= payload.exp) {
+    throw new Error('JWT has expired')
+  }
+
+  if (payload.nbf !== undefined && now < payload.nbf) {
+    throw new Error('JWT is not yet valid')
+  }
+
+  // Verify issuer
+  if (issuer !== undefined) {
+    const expectedIssuers = Array.isArray(issuer) ? issuer : [issuer]
+    if (!expectedIssuers.includes(payload.iss!)) {
+      throw new Error('Invalid JWT issuer')
+    }
+  }
+
+  // Verify audience
+  if (audience !== undefined) {
+    const expectedAudiences = Array.isArray(audience) ? audience : [audience]
+    const tokenAudiences = Array.isArray(payload.aud) ? payload.aud : [payload.aud]
+
+    const hasValidAudience = expectedAudiences.some(exp =>
+      tokenAudiences.includes(exp)
+    )
+
+    if (!hasValidAudience) {
+      throw new Error('Invalid JWT audience')
+    }
+  }
+
+  // Verify subject
+  if (subject !== undefined && payload.sub !== subject) {
+    throw new Error('Invalid JWT subject')
+  }
+
+  // Check required claims
+  for (const claim of requiredClaims) {
+    if (!(claim in payload)) {
+      throw new Error(`Missing required claim: ${claim}`)
+    }
+  }
+
+  return payload as T
+}
+
+/**
+ * Verify an access token and return the user ID.
+ *
+ * @param token - The JWT access token
+ * @param secret - The secret key
+ * @param options - Additional verification options
+ * @returns The user ID from the token
+ */
+export async function verifyAccessToken(
+  token: string,
+  secret: Uint8Array | string,
+  options: JWTVerifyOptions = {}
+): Promise<string> {
+  const payload = await verifyJWT(token, secret, {
+    ...options,
+    requiredClaims: ['sub', 'type', ...(options.requiredClaims || [])],
+  })
+
+  if (payload.type !== 'access') {
+    throw new Error('Invalid token type')
+  }
+
+  return payload.sub!
+}
+
+/**
+ * Verify a refresh token.
+ *
+ * @param token - The JWT refresh token
+ * @param secret - The secret key
+ * @param options - Additional verification options
+ * @returns The user ID from the token
+ */
+export async function verifyRefreshToken(
+  token: string,
+  secret: Uint8Array | string,
+  options: JWTVerifyOptions = {}
+): Promise<string> {
+  const payload = await verifyJWT(token, secret, {
+    ...options,
+    requiredClaims: ['sub', 'type', ...(options.requiredClaims || [])],
+  })
+
+  if (payload.type !== 'refresh') {
+    throw new Error('Invalid token type')
+  }
+
+  return payload.sub!
+}
+
+/**
+ * Decode a JWT without verifying it.
+ * WARNING: Only use this when you need to read claims before verification.
+ * Always verify tokens for authentication!
+ *
+ * @param token - The JWT string
+ * @returns The decoded payload (unverified)
+ */
+export function decodeJWT(token: string): JWTPayload {
+  const parts = token.split('.')
+  if (parts.length !== 3) {
+    throw new Error('Invalid JWT format')
+  }
+
+  try {
+    const payload = JSON.parse(base64urlDecode(parts[1]!))
+    return payload
+  } catch (error) {
+    throw new Error('Invalid JWT encoding')
+  }
+}

package/src/oauth/index.ts

@@ -0,0 +1,7 @@
+// OAuth state management
+export {
+  generateOAuthState,
+  createOAuthStateStore,
+  createMemoryOAuthStateStore,
+  type OAuthState
+} from './state.ts'

package/src/oauth/state.ts

@@ -0,0 +1,117 @@
+import { randomHex } from '@strav/kernel'
+
+/**
+ * OAuth state parameter management for CSRF protection.
+ */
+
+export interface OAuthState {
+  /** Random state value */
+  value: string
+  /** Redirect URI after OAuth */
+  redirect?: string
+  /** Additional data to preserve */
+  data?: Record<string, unknown>
+  /** Creation timestamp */
+  createdAt: number
+}
+
+/**
+ * Generate a secure OAuth state parameter.
+ *
+ * @param options - State options
+ * @returns State object with secure random value
+ */
+export function generateOAuthState(options: {
+  redirect?: string
+  data?: Record<string, unknown>
+} = {}): OAuthState {
+  return {
+    value: randomHex(16),
+    redirect: options.redirect,
+    data: options.data,
+    createdAt: Date.now(),
+  }
+}
+
+/**
+ * Create an OAuth state store with expiration.
+ *
+ * @param options - Store configuration
+ * @returns State store methods
+ */
+export function createOAuthStateStore(options: {
+  /** Store state (e.g., in Redis, database, or memory) */
+  store: (state: OAuthState) => Promise<void>
+  /** Retrieve state by value */
+  retrieve: (value: string) => Promise<OAuthState | null>
+  /** Delete state after use */
+  delete: (value: string) => Promise<void>
+  /** TTL in seconds (default: 600 = 10 minutes) */
+  ttl?: number
+}) {
+  const ttl = options.ttl || 600
+
+  return {
+    /**
+     * Generate and store a new state.
+     */
+    async generate(params?: { redirect?: string; data?: Record<string, unknown> }): Promise<string> {
+      const state = generateOAuthState(params)
+      await options.store(state)
+      return state.value
+    },
+
+    /**
+     * Verify a state parameter and retrieve its data.
+     */
+    async verify(value: string): Promise<OAuthState | null> {
+      const state = await options.retrieve(value)
+
+      if (!state) {
+        return null
+      }
+
+      // Check expiration
+      const age = (Date.now() - state.createdAt) / 1000
+      if (age > ttl) {
+        await options.delete(value)
+        return null
+      }
+
+      // Delete after successful verification (one-time use)
+      await options.delete(value)
+      return state
+    },
+  }
+}
+
+/**
+ * Simple in-memory OAuth state store for development.
+ * WARNING: Do not use in production - states are lost on restart!
+ */
+export function createMemoryOAuthStateStore(ttl: number = 600) {
+  const states = new Map<string, OAuthState>()
+
+  // Cleanup expired states periodically
+  const cleanup = setInterval(() => {
+    const now = Date.now()
+    for (const [value, state] of states.entries()) {
+      if ((now - state.createdAt) / 1000 > ttl) {
+        states.delete(value)
+      }
+    }
+  }, 60000) // Every minute
+
+  return createOAuthStateStore({
+    async store(state) {
+      states.set(state.value, state)
+    },
+    async retrieve(value) {
+      return states.get(value) || null
+    },
+    async delete(value) {
+      states.delete(value)
+    },
+    ttl,
+  })
+}

package/src/tokens/index.ts

@@ -0,0 +1,20 @@
+// Signed opaque tokens
+export {
+  createSignedToken,
+  verifySignedToken,
+  type SignedTokenPayload
+} from './signed.ts'
+
+// Magic link tokens
+export {
+  createMagicLinkToken,
+  verifyMagicLinkToken,
+  type MagicLinkPayload
+} from './magic.ts'
+
+// Refresh tokens
+export {
+  generateRefreshToken,
+  createTokenRotation,
+  type RefreshTokenPair
+} from './refresh.ts'

package/src/tokens/magic.ts

@@ -0,0 +1,57 @@
+import { createSignedToken, verifySignedToken } from './signed.ts'
+
+/**
+ * Magic link token utilities for passwordless authentication.
+ */
+
+export interface MagicLinkPayload {
+  sub: string | number
+  typ: 'magic-link'
+  email?: string
+  redirect?: string
+}
+
+/**
+ * Generate a magic link token for passwordless authentication.
+ *
+ * @param userId - The user identifier
+ * @param options - Additional options
+ * @returns Signed token string
+ */
+export function createMagicLinkToken(
+  userId: string | number,
+  options: {
+    email?: string
+    redirect?: string
+    expiresInMinutes?: number
+  } = {}
+): string {
+  const { email, redirect, expiresInMinutes = 15 } = options
+
+  return createSignedToken(
+    {
+      sub: userId,
+      typ: 'magic-link',
+      email,
+      redirect,
+    },
+    expiresInMinutes
+  )
+}
+
+/**
+ * Verify a magic link token.
+ *
+ * @param token - The token to verify
+ * @returns The decoded payload
+ * @throws If the token is invalid or expired
+ */
+export function verifyMagicLinkToken(token: string): MagicLinkPayload {
+  const payload = verifySignedToken<MagicLinkPayload>(token)
+
+  if (payload.typ !== 'magic-link') {
+    throw new Error('Invalid token type')
+  }
+
+  return payload
+}

package/src/tokens/refresh.ts

@@ -0,0 +1,75 @@
+import { randomHex } from '@strav/kernel'
+
+/**
+ * Refresh token utilities for JWT rotation strategies.
+ */
+
+export interface RefreshTokenPair {
+  /** The access token (short-lived) */
+  accessToken: string
+  /** The refresh token (long-lived) */
+  refreshToken: string
+}
+
+/**
+ * Generate a secure refresh token.
+ *
+ * @param length - Token length in bytes (default: 32)
+ * @returns Hex-encoded refresh token
+ */
+export function generateRefreshToken(length: number = 32): string {
+  return randomHex(length)
+}
+
+/**
+ * Create a token rotation strategy helper.
+ * This is a factory function that returns methods for your specific storage.
+ *
+ * @example
+ * const rotation = createTokenRotation({
+ *   async store(userId, token, expiresAt) {
+ *     await db.refreshTokens.create({ userId, token, expiresAt })
+ *   },
+ *   async verify(token) {
+ *     const record = await db.refreshTokens.findByToken(token)
+ *     if (!record || record.expiresAt < new Date()) return null
+ *     return record.userId
+ *   },
+ *   async revoke(token) {
+ *     await db.refreshTokens.deleteByToken(token)
+ *   }
+ * })
+ */
+export function createTokenRotation(options: {
+  store: (userId: string | number, token: string, expiresAt: Date) => Promise<void>
+  verify: (token: string) => Promise<string | number | null>
+  revoke: (token: string) => Promise<void>
+  revokeAll?: (userId: string | number) => Promise<void>
+}) {
+  return {
+    /**
+     * Generate and store a new refresh token.
+     */
+    async generate(userId: string | number, ttlSeconds: number = 2592000): Promise<string> {
+      const token = generateRefreshToken()
+      const expiresAt = new Date(Date.now() + ttlSeconds * 1000)
+      await options.store(userId, token, expiresAt)
+      return token
+    },
+
+    /**
+     * Verify a refresh token and return the user ID.
+     */
+    verify: options.verify,
+
+    /**
+     * Revoke a specific refresh token.
+     */
+    revoke: options.revoke,
+
+    /**
+     * Revoke all refresh tokens for a user.
+     */
+    revokeAll: options.revokeAll,
+  }
+}

package/src/tokens/signed.ts

@@ -0,0 +1,61 @@
+import { encrypt } from '@strav/kernel'
+
+/**
+ * Signed, opaque token utilities using Strav's encryption.
+ * These tokens are encrypted and tamper-proof.
+ */
+
+export interface SignedTokenPayload {
+  /** User identifier. */
+  sub: string | number
+  /** Token purpose. */
+  typ: string
+  /** Issued at (unix ms). */
+  iat: number
+  /** Expiration (minutes from iat). */
+  exp: number
+  /** Extra data. */
+  [key: string]: unknown
+}
+
+/**
+ * Create a signed, encrypted token using `encrypt.seal()`.
+ * Tamper-proof and opaque — the user cannot read or modify the payload.
+ *
+ * @param data  - The payload to sign.
+ * @param expiresInMinutes - Token lifetime in minutes.
+ */
+export function createSignedToken(
+  data: { sub: string | number; typ: string; [key: string]: unknown },
+  expiresInMinutes: number
+): string {
+  const payload: SignedTokenPayload = {
+    ...data,
+    iat: Date.now(),
+    exp: expiresInMinutes,
+  }
+  return encrypt.seal(payload)
+}
+
+/**
+ * Verify and decode a signed token. Throws if expired or tampered.
+ *
+ * @returns The original payload.
+ * @throws  If the token is invalid, expired, or tampered.
+ */
+export function verifySignedToken<T = SignedTokenPayload>(token: string): T {
+  const payload = encrypt.unseal<SignedTokenPayload>(token)
+
+  if (!payload || typeof payload !== 'object' || !payload.iat) {
+    throw new Error('Invalid token payload.')
+  }
+
+  if (payload.exp) {
+    const expiresAt = payload.iat + payload.exp * 60_000
+    if (Date.now() > expiresAt) {
+      throw new Error('Token has expired.')
+    }
+  }
+
+  return payload as unknown as T
+}

package/src/totp/index.ts

@@ -0,0 +1,15 @@
+// TOTP core functionality
+export {
+  generateSecret,
+  generateTotp,
+  verifyTotp,
+  base32Encode,
+  base32Decode,
+  type TotpOptions
+} from './totp.ts'
+
+// Recovery codes
+export { generateRecoveryCodes } from './recovery.ts'
+
+// QR code URI generation
+export { totpUri } from './uri.ts'

package/src/totp/recovery.ts

@@ -0,0 +1,13 @@
+/**
+ * Recovery code generation for two-factor authentication.
+ */
+
+/** Generate a set of single-use recovery codes (8-char hex each). */
+export function generateRecoveryCodes(count: number): string[] {
+  const codes: string[] = []
+  for (let i = 0; i < count; i++) {
+    const bytes = crypto.getRandomValues(new Uint8Array(4))
+    codes.push(Array.from(bytes, b => b.toString(16).padStart(2, '0')).join(''))
+  }
+  return codes
+}