@korajs/auth 1.0.0-beta.12 → 1.0.0-beta.13

package/src/tokens/jwt.ts

@@ -0,0 +1,236 @@
+import { createHmac } from 'node:crypto'
+
+// ============================================================================
+// Base64url helpers
+// ============================================================================
+
+/**
+ * Encodes a UTF-8 string to base64url format (RFC 7515).
+ * Base64url uses the URL-safe alphabet (- instead of +, _ instead of /)
+ * and strips trailing padding characters.
+ *
+ * @param input - The UTF-8 string to encode
+ * @returns Base64url-encoded string
+ */
+export function base64urlEncode(input: string): string {
+	return Buffer.from(input, 'utf-8').toString('base64url')
+}
+
+/**
+ * Decodes a base64url-encoded string back to UTF-8.
+ *
+ * @param input - The base64url-encoded string to decode
+ * @returns Decoded UTF-8 string
+ */
+export function base64urlDecode(input: string): string {
+	return Buffer.from(input, 'base64url').toString('utf-8')
+}
+
+// ============================================================================
+// Internal signing
+// ============================================================================
+
+/**
+ * Computes an HMAC-SHA256 signature and returns it as a base64url string.
+ * Uses Node.js crypto module for synchronous signing.
+ */
+function hmacSha256Base64url(data: string, secret: string): string {
+	return createHmac('sha256', secret).update(data).digest('base64url')
+}
+
+// ============================================================================
+// JWT operations
+// ============================================================================
+
+/** Pre-encoded JWT header. Only HS256 is supported; the header never changes. */
+const ENCODED_HEADER = base64urlEncode(JSON.stringify({ alg: 'HS256', typ: 'JWT' }))
+
+/**
+ * Creates a signed JWT (HS256) from a payload and secret.
+ *
+ * The token is structured as `header.payload.signature` per RFC 7519.
+ * Only HMAC-SHA256 is supported. The header is always `{"alg":"HS256","typ":"JWT"}`.
+ *
+ * @param payload - The claims to include in the token. Must be JSON-serializable.
+ * @param secret - The HMAC-SHA256 secret key used for signing.
+ * @returns A signed JWT string in the format `header.payload.signature`
+ *
+ * @example
+ * ```typescript
+ * const token = encodeJwt(
+ *   { sub: 'user-123', exp: Math.floor(Date.now() / 1000) + 900 },
+ *   'my-secret'
+ * )
+ * ```
+ */
+export function encodeJwt(payload: Record<string, unknown>, secret: string): string {
+	const encodedPayload = base64urlEncode(JSON.stringify(payload))
+	const signingInput = `${ENCODED_HEADER}.${encodedPayload}`
+	const signature = hmacSha256Base64url(signingInput, secret)
+	return `${signingInput}.${signature}`
+}
+
+/**
+ * Decodes a JWT without verifying its signature.
+ *
+ * Use this only when you need to inspect claims (e.g., reading `exp` to decide
+ * whether to attempt a refresh) and do NOT need to trust the token's authenticity.
+ * For trusted reads, use {@link verifyJwt} instead.
+ *
+ * @param token - The JWT string to decode
+ * @returns The decoded payload as a record, or null if the token is malformed
+ *
+ * @example
+ * ```typescript
+ * const claims = decodeJwt(token)
+ * if (claims && typeof claims.sub === 'string') {
+ *   console.log('User:', claims.sub)
+ * }
+ * ```
+ */
+export function decodeJwt(token: string): Record<string, unknown> | null {
+	const parts = token.split('.')
+	if (parts.length !== 3) {
+		return null
+	}
+
+	const payloadSegment = parts[1]
+	if (payloadSegment === undefined) {
+		return null
+	}
+
+	try {
+		const decoded = base64urlDecode(payloadSegment)
+		const parsed: unknown = JSON.parse(decoded)
+		if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+			return null
+		}
+		return parsed as Record<string, unknown>
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Decodes a JWT and verifies its HMAC-SHA256 signature.
+ *
+ * Returns the payload only if the signature is valid. Returns null if the token
+ * is malformed, has an invalid signature, or cannot be parsed.
+ *
+ * This function does NOT check expiration. Use {@link isExpired} separately
+ * to check the `exp` claim, allowing callers to distinguish between
+ * "invalid signature" (security issue) and "expired" (normal lifecycle).
+ *
+ * @param token - The JWT string to verify
+ * @param secret - The HMAC-SHA256 secret key that was used to sign the token
+ * @returns The decoded payload if the signature is valid, or null otherwise
+ *
+ * @example
+ * ```typescript
+ * const claims = verifyJwt(token, 'my-secret')
+ * if (claims === null) {
+ *   throw new Error('Invalid token signature')
+ * }
+ * if (isExpired(claims)) {
+ *   throw new Error('Token has expired')
+ * }
+ * ```
+ */
+export function verifyJwt(token: string, secret: string): Record<string, unknown> | null {
+	// Callers ultimately trace back to request bodies (handleRefresh,
+	// handleSignOut, handleDeviceRegister, handleDeviceVerify all pass a body
+	// field straight through to validateToken -> verifyJwt). A malformed or
+	// missing field means `token` is not actually a string at runtime despite
+	// the type, and `.split` would throw, turning one bad request into a
+	// process-crashing uncaught exception. Treat non-string input as "not a
+	// valid token" instead, same as any other malformed token shape.
+	if (typeof token !== 'string') {
+		return null
+	}
+	const parts = token.split('.')
+	if (parts.length !== 3) {
+		return null
+	}
+
+	const headerSegment = parts[0]
+	const payloadSegment = parts[1]
+	const signatureSegment = parts[2]
+
+	if (
+		headerSegment === undefined ||
+		payloadSegment === undefined ||
+		signatureSegment === undefined
+	) {
+		return null
+	}
+
+	// Validate the header to prevent algorithm confusion attacks.
+	// Only HS256 is supported; reject any token claiming a different algorithm.
+	if (headerSegment !== ENCODED_HEADER) {
+		return null
+	}
+
+	// Recompute signature and compare
+	const signingInput = `${headerSegment}.${payloadSegment}`
+	const expectedSignature = hmacSha256Base64url(signingInput, secret)
+
+	// Constant-time comparison to prevent timing attacks.
+	// Both strings are base64url-encoded HMAC outputs, so they are ASCII-safe
+	// and we can compare byte-by-byte without early exit.
+	if (expectedSignature.length !== signatureSegment.length) {
+		return null
+	}
+	let mismatch = 0
+	for (let i = 0; i < expectedSignature.length; i++) {
+		// Bitwise OR accumulates differences without short-circuiting
+		mismatch |= expectedSignature.charCodeAt(i) ^ signatureSegment.charCodeAt(i)
+	}
+	if (mismatch !== 0) {
+		return null
+	}
+
+	// Decode the payload
+	try {
+		const decoded = base64urlDecode(payloadSegment)
+		const parsed: unknown = JSON.parse(decoded)
+		if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+			return null
+		}
+		return parsed as Record<string, unknown>
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Clock skew tolerance in seconds. Allows for minor clock differences
+ * between servers in multi-server deployments.
+ */
+const CLOCK_SKEW_TOLERANCE_SECONDS = 5
+
+/**
+ * Checks whether a token payload has expired based on its `exp` claim.
+ *
+ * The `exp` claim is expected to be in seconds since the Unix epoch (per JWT spec).
+ * Includes a small clock skew tolerance (5 seconds) to handle minor time
+ * differences between servers. If the `exp` claim is missing or is not a number,
+ * the token is considered non-expiring and this function returns false.
+ *
+ * @param payload - An object with an optional `exp` field (seconds since epoch)
+ * @returns true if the token has expired, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const claims = verifyJwt(token, secret)
+ * if (claims && isExpired(claims)) {
+ *   // Token signature is valid but it has expired -- attempt refresh
+ * }
+ * ```
+ */
+export function isExpired(payload: { exp?: number }): boolean {
+	if (typeof payload.exp !== 'number') {
+		return false
+	}
+	const nowSeconds = Math.floor(Date.now() / 1000)
+	return nowSeconds >= payload.exp + CLOCK_SKEW_TOLERANCE_SECONDS
+}

package/src/tokens/postgres-token-revocation-store.ts

@@ -0,0 +1,140 @@
+import { ensurePostgresSchema } from '../postgres/ensure-schema'
+import type { ConsumeResult, TokenRevocationStore } from './token-manager'
+
+/**
+ * Minimal postgres-js tagged-template client.
+ */
+export type PostgresRevocationClient = (
+	template: TemplateStringsArray,
+	...args: unknown[]
+) => Promise<Record<string, unknown>[]>
+
+/**
+ * PostgreSQL-backed {@link TokenRevocationStore} (postgres-js).
+ *
+ * Shared by every server instance using the database. `consume` is one
+ * `INSERT ... ON CONFLICT DO NOTHING RETURNING`, so exactly one concurrent
+ * caller, on any instance, consumes a refresh token (AUTH-6).
+ *
+ * @example
+ * ```typescript
+ * const userStore = await createPostgresUserStore({ connectionString })
+ * const revocationStore = userStore.getTokenRevocationStore()
+ * ```
+ */
+export class PostgresTokenRevocationStore implements TokenRevocationStore {
+	private readonly ready: Promise<void>
+
+	constructor(private readonly sql: PostgresRevocationClient) {
+		this.ready = this.ensureTables()
+	}
+
+	private async ensureTables(): Promise<void> {
+		// Concurrency-safe on an empty database shared by several instances.
+		await ensurePostgresSchema(this.sql, async (sql) => {
+			await sql`
+				CREATE TABLE IF NOT EXISTS auth_token_revocations (
+					jti TEXT PRIMARY KEY,
+					expires_at BIGINT NOT NULL
+				)
+			`
+			await sql`
+				CREATE TABLE IF NOT EXISTS auth_token_consumptions (
+					jti TEXT PRIMARY KEY,
+					consumed_at BIGINT NOT NULL,
+					expires_at BIGINT NOT NULL
+				)
+			`
+			await sql`
+				CREATE TABLE IF NOT EXISTS auth_token_cutoffs (
+					kind TEXT NOT NULL,
+					subject_id TEXT NOT NULL,
+					revoked_before BIGINT NOT NULL,
+					PRIMARY KEY (kind, subject_id)
+				)
+			`
+		})
+	}
+
+	async isRevoked(jti: string): Promise<boolean> {
+		await this.ready
+		const rows = await this.sql`SELECT 1 FROM auth_token_revocations WHERE jti = ${jti}`
+		return rows.length > 0
+	}
+
+	async revoke(jti: string, expiresAt: number): Promise<void> {
+		await this.ready
+		await this.sql`
+			INSERT INTO auth_token_revocations (jti, expires_at) VALUES (${jti}, ${expiresAt})
+			ON CONFLICT (jti) DO NOTHING
+		`
+	}
+
+	async consume(jti: string, expiresAt: number): Promise<ConsumeResult> {
+		await this.ready
+		const now = Date.now()
+		const inserted = await this.sql`
+			INSERT INTO auth_token_consumptions (jti, consumed_at, expires_at)
+			VALUES (${jti}, ${now}, ${expiresAt})
+			ON CONFLICT (jti) DO NOTHING
+			RETURNING consumed_at
+		`
+		if (inserted.length === 1) return { firstUse: true, consumedAt: now }
+		const rows = await this.sql`SELECT consumed_at FROM auth_token_consumptions WHERE jti = ${jti}`
+		const consumedAt = rows[0]?.consumed_at
+		return { firstUse: false, consumedAt: consumedAt === undefined ? now : Number(consumedAt) }
+	}
+
+	async isConsumed(jti: string): Promise<boolean> {
+		await this.ready
+		const rows = await this.sql`SELECT 1 FROM auth_token_consumptions WHERE jti = ${jti}`
+		return rows.length > 0
+	}
+
+	async revokeAllForDevice(deviceId: string, before: number = Date.now()): Promise<void> {
+		await this.setCutoff('device', deviceId, before)
+	}
+
+	async getDeviceRevokedBefore(deviceId: string): Promise<number | null> {
+		return this.getCutoff('device', deviceId)
+	}
+
+	async revokeAllForUser(userId: string, before: number = Date.now()): Promise<void> {
+		await this.setCutoff('user', userId, before)
+	}
+
+	async getUserRevokedBefore(userId: string): Promise<number | null> {
+		return this.getCutoff('user', userId)
+	}
+
+	/** Delete revocations and consumptions whose tokens have expired. */
+	async cleanup(): Promise<void> {
+		await this.ready
+		const nowSeconds = Math.floor(Date.now() / 1000)
+		await this.sql`DELETE FROM auth_token_revocations WHERE expires_at < ${nowSeconds}`
+		await this.sql`DELETE FROM auth_token_consumptions WHERE expires_at < ${nowSeconds}`
+	}
+
+	private async setCutoff(
+		kind: 'device' | 'user',
+		subjectId: string,
+		before: number,
+	): Promise<void> {
+		await this.ready
+		await this.sql`
+			INSERT INTO auth_token_cutoffs (kind, subject_id, revoked_before)
+			VALUES (${kind}, ${subjectId}, ${before})
+			ON CONFLICT (kind, subject_id)
+			DO UPDATE SET revoked_before = GREATEST(auth_token_cutoffs.revoked_before, EXCLUDED.revoked_before)
+		`
+	}
+
+	private async getCutoff(kind: 'device' | 'user', subjectId: string): Promise<number | null> {
+		await this.ready
+		const rows = await this.sql`
+			SELECT revoked_before FROM auth_token_cutoffs WHERE kind = ${kind} AND subject_id = ${subjectId}
+		`
+		const value = rows[0]?.revoked_before
+		return value === undefined ? null : Number(value)
+	}
+}

package/src/tokens/sqlite-token-revocation-store.ts

@@ -0,0 +1,121 @@
+import type { ConsumeResult, TokenRevocationStore } from './token-manager'
+
+/**
+ * Minimal better-sqlite3 subset to avoid a hard dependency on the package.
+ */
+export interface SqliteRevocationDatabase {
+	exec(source: string): void
+	prepare(source: string): {
+		run(...params: unknown[]): { changes: number }
+		get(...params: unknown[]): unknown
+	}
+}
+
+/**
+ * SQLite-backed {@link TokenRevocationStore} (better-sqlite3).
+ *
+ * Revocations survive restarts and are shared by every process using the same
+ * database file. `consume` is a single `INSERT ... ON CONFLICT DO NOTHING`, so it
+ * is atomic: better-sqlite3 executes statements synchronously under SQLite's
+ * write lock.
+ *
+ * @example
+ * ```typescript
+ * const userStore = await createSqliteUserStore({ filename: './auth.db' })
+ * const revocationStore = userStore.getTokenRevocationStore()
+ * ```
+ */
+export class SqliteTokenRevocationStore implements TokenRevocationStore {
+	constructor(private readonly db: SqliteRevocationDatabase) {
+		this.db.exec(`
+			CREATE TABLE IF NOT EXISTS auth_token_revocations (
+				jti TEXT PRIMARY KEY,
+				expires_at INTEGER NOT NULL
+			);
+			CREATE TABLE IF NOT EXISTS auth_token_consumptions (
+				jti TEXT PRIMARY KEY,
+				consumed_at INTEGER NOT NULL,
+				expires_at INTEGER NOT NULL
+			);
+			CREATE TABLE IF NOT EXISTS auth_token_cutoffs (
+				kind TEXT NOT NULL,
+				subject_id TEXT NOT NULL,
+				revoked_before INTEGER NOT NULL,
+				PRIMARY KEY (kind, subject_id)
+			);
+		`)
+	}
+
+	async isRevoked(jti: string): Promise<boolean> {
+		return (
+			this.db.prepare('SELECT 1 FROM auth_token_revocations WHERE jti = ?').get(jti) !== undefined
+		)
+	}
+
+	async revoke(jti: string, expiresAt: number): Promise<void> {
+		this.db
+			.prepare(
+				'INSERT INTO auth_token_revocations (jti, expires_at) VALUES (?, ?) ON CONFLICT(jti) DO NOTHING',
+			)
+			.run(jti, expiresAt)
+	}
+
+	async consume(jti: string, expiresAt: number): Promise<ConsumeResult> {
+		const now = Date.now()
+		const inserted = this.db
+			.prepare(
+				'INSERT INTO auth_token_consumptions (jti, consumed_at, expires_at) VALUES (?, ?, ?) ON CONFLICT(jti) DO NOTHING',
+			)
+			.run(jti, now, expiresAt)
+		if (inserted.changes === 1) return { firstUse: true, consumedAt: now }
+		const row = this.db
+			.prepare('SELECT consumed_at FROM auth_token_consumptions WHERE jti = ?')
+			.get(jti) as { consumed_at: number } | undefined
+		return { firstUse: false, consumedAt: row ? Number(row.consumed_at) : now }
+	}
+
+	async isConsumed(jti: string): Promise<boolean> {
+		return (
+			this.db.prepare('SELECT 1 FROM auth_token_consumptions WHERE jti = ?').get(jti) !== undefined
+		)
+	}
+
+	async revokeAllForDevice(deviceId: string, before: number = Date.now()): Promise<void> {
+		this.setCutoff('device', deviceId, before)
+	}
+
+	async getDeviceRevokedBefore(deviceId: string): Promise<number | null> {
+		return this.getCutoff('device', deviceId)
+	}
+
+	async revokeAllForUser(userId: string, before: number = Date.now()): Promise<void> {
+		this.setCutoff('user', userId, before)
+	}
+
+	async getUserRevokedBefore(userId: string): Promise<number | null> {
+		return this.getCutoff('user', userId)
+	}
+
+	/** Delete revocations and consumptions whose tokens have expired. */
+	async cleanup(): Promise<void> {
+		const nowSeconds = Math.floor(Date.now() / 1000)
+		this.db.prepare('DELETE FROM auth_token_revocations WHERE expires_at < ?').run(nowSeconds)
+		this.db.prepare('DELETE FROM auth_token_consumptions WHERE expires_at < ?').run(nowSeconds)
+	}
+
+	private setCutoff(kind: 'device' | 'user', subjectId: string, before: number): void {
+		this.db
+			.prepare(
+				`INSERT INTO auth_token_cutoffs (kind, subject_id, revoked_before) VALUES (?, ?, ?)
+				 ON CONFLICT(kind, subject_id) DO UPDATE SET revoked_before = MAX(revoked_before, excluded.revoked_before)`,
+			)
+			.run(kind, subjectId, before)
+	}
+
+	private getCutoff(kind: 'device' | 'user', subjectId: string): number | null {
+		const row = this.db
+			.prepare('SELECT revoked_before FROM auth_token_cutoffs WHERE kind = ? AND subject_id = ?')
+			.get(kind, subjectId) as { revoked_before: number } | undefined
+		return row ? Number(row.revoked_before) : null
+	}
+}