ajo-kit-auth 0.1.0

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "ajo-kit-auth",
+  "version": "0.1.0",
+  "description": "Authentication and authorization for ajo-kit applications",
+  "type": "module",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "kit": {
+    "alias": "auth",
+    "serverOnly": true,
+    "migrations": "./dist/migrations/"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js",
+      "import": "./dist/index.js"
+    },
+    "./ability": {
+      "types": "./src/ability.client.ts",
+      "default": "./dist/ability.js",
+      "import": "./dist/ability.js"
+    }
+  },
+  "dependencies": {
+    "argon2": "^0.44.0"
+  },
+  "devDependencies": {
+    "ajo-kit": "^0.1.0"
+  },
+  "peerDependencies": {
+    "ajo-kit": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "keywords": [
+    "ajo",
+    "authentication",
+    "authorization",
+    "security",
+    "sqlite"
+  ],
+  "author": "Cristian Falcone",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cristianfalcone/ajo-kit.git",
+    "directory": "packages/ajo-kit-auth"
+  },
+  "bugs": {
+    "url": "https://github.com/cristianfalcone/ajo-kit/issues"
+  },
+  "homepage": "https://github.com/cristianfalcone/ajo-kit/tree/main/packages/ajo-kit-auth#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm -w exec tsx scripts/package-build.ts ajo-kit-auth",
+    "test": "pnpm -w exec vitest run packages/ajo-kit-auth/tests"
+  }
+}

package/src/ability.client.ts

@@ -0,0 +1,77 @@
+/** Ability string used by account grants and bearer API tokens. */
+export type Ability = string
+
+const full = '*'
+const wildcarded = (ability: Ability) => ability === full
+	? null
+	: ability.endsWith(':*')
+		? ability.slice(0, -2)
+		: null
+
+/** Returns true when grants include the required ability. */
+export function can(grants: readonly Ability[] | undefined, required: Ability): boolean {
+
+	if (!grants) return false
+	if (grants.includes(full)) return true
+	if (grants.includes(required)) return true
+
+	const [resource] = required.split(':')
+
+	return grants.includes(`${resource}:*`)
+}
+
+/** Returns true when grants include every required ability. */
+export const all = (grants: readonly Ability[], required: readonly Ability[]) =>
+	required.every(ability => can(grants, ability))
+
+/** Removes duplicate and redundant grants while preserving stable order. */
+export function compact(grants: readonly Ability[]): Ability[] {
+
+	const unique = [...new Set(grants)]
+
+	if (unique.includes(full)) return [full]
+
+	const resources = new Set(unique.map(wildcarded).filter(resource => resource !== null))
+
+	return unique.filter(grant => {
+		const resource = wildcarded(grant)
+		if (resource) return true
+
+		return !resources.has(grant.split(':')[0])
+	})
+}
+
+/** Merges ability grant sets with duplicate and wildcard compaction. */
+export const merge = (...sets: (readonly Ability[])[]): Ability[] =>
+	compact(sets.flat())
+
+/** Returns the effective grants allowed by both grant sets. */
+export function intersect(left: readonly Ability[], right: readonly Ability[]): Ability[] {
+
+	const grants: Ability[] = []
+
+	for (const a of compact(left)) {
+		for (const b of compact(right)) {
+			const grant = overlap(a, b)
+			if (grant) grants.push(grant)
+		}
+	}
+
+	return compact(grants)
+}
+
+function overlap(left: Ability, right: Ability): Ability | null {
+
+	if (left === full) return right
+	if (right === full) return left
+	if (left === right) return left
+
+	const l = wildcarded(left)
+	const r = wildcarded(right)
+
+	if (l && r) return l === r ? left : null
+	if (l && can([left], right)) return right
+	if (r && can([right], left)) return left
+
+	return null
+}

package/src/account.ts

@@ -0,0 +1,42 @@
+import { merge, type Ability } from './ability.client'
+import { db } from './store'
+import type { Role } from './types'
+
+/** Parsed ability bundle assigned through one user role. */
+export type Grant = {
+	name: Role
+	abilities: Ability[]
+}
+
+function parse(value: string): Ability[] {
+	try {
+		const abilities = JSON.parse(value)
+
+		return Array.isArray(abilities) && abilities.every(ability => typeof ability === 'string')
+			? abilities
+			: []
+	} catch {
+		return []
+	}
+}
+
+/** Loads role ability bundles for an auth user. */
+export async function grants(user: number): Promise<Grant[]> {
+	const roles = await db()
+		.selectFrom('members')
+		.innerJoin('roles', 'roles.id', 'members.role')
+		.select(['roles.name', 'roles.abilities'])
+		.where('members.user', '=', user)
+		.orderBy('roles.id')
+		.execute()
+
+	return roles.map(role => ({
+		name: role.name as Role,
+		abilities: parse(role.abilities),
+	}))
+}
+
+/** Resolves the effective account abilities from all assigned roles. */
+export async function abilities(user: number): Promise<Ability[]> {
+	return merge(...(await grants(user)).map(role => role.abilities))
+}

package/src/confirm.ts

@@ -0,0 +1,54 @@
+import type { Request } from 'ajo-kit'
+
+const stamps = new Map<string, number>()
+
+const key = (user: number, kind: 'session' | 'token', id: string) => `${kind}:${user}:${id}`
+const segment = (user: number) => `:${user}:`
+
+/** Returns the current session/token confirmation key for a request. */
+export function credential(req: Request): string | null {
+	if (!req.user) return null
+	if (req.token) return key(req.user.id, 'token', req.token.id)
+	if (req.session) return key(req.user.id, 'session', req.session.id)
+	return null
+}
+
+/** Stamps the current credential as recently password-confirmed. */
+export function stamp(req: Request): boolean {
+	const id = credential(req)
+	if (!id) return false
+	stamps.set(id, Date.now())
+	return true
+}
+
+/** Returns true when the current credential was confirmed recently. */
+export function check(req: Request, window = 180_000): boolean {
+	const id = credential(req)
+	if (!id) return false
+	const at = stamps.get(id)
+	if (!at) return false
+	return Date.now() - at < window
+}
+
+/** Clears the confirmation stamp for the current credential. */
+export function clear(req: Request): void {
+	const id = credential(req)
+	if (id) stamps.delete(id)
+}
+
+/** Clears the confirmation stamp for a specific session. */
+export function clearSession(user: number, id: string): void {
+	stamps.delete(key(user, 'session', id))
+}
+
+/** Clears the confirmation stamp for a specific bearer token. */
+export function clearToken(user: number, id: string): void {
+	stamps.delete(key(user, 'token', id))
+}
+
+/** Clears every confirmation stamp for a user. */
+export function clearUser(user: number): void {
+	for (const id of stamps.keys()) {
+		if (id.includes(segment(user))) stamps.delete(id)
+	}
+}

package/src/cookie.ts

@@ -0,0 +1,34 @@
+import type { Request, Response } from 'ajo-kit'
+
+const name = 'session'
+const secure = () => process.env.NODE_ENV === 'production' ? '; Secure' : ''
+const base = () => `HttpOnly; SameSite=Lax; Path=/${secure()}`
+
+/** Reads one cookie by exact name and rejects duplicates. */
+export const parse = (header: string | undefined, key: string) => {
+	let value: string | undefined
+
+	for (const part of header?.split(';') ?? []) {
+		const trimmed = part.trim()
+		const index = trimmed.indexOf('=')
+		if (index === -1) continue
+		if (trimmed.slice(0, index) !== key) continue
+		if (value !== undefined) return
+		value = trimmed.slice(index + 1)
+	}
+
+	return value
+}
+
+/** Reads the session cookie from a request. */
+export const read = (req: Request) => parse(req.headers.cookie, name)
+
+/** Writes the session cookie to a response. */
+export const write = (res: Response, value: string, remember = false) => {
+	const age = remember ? 31536000 : 2592000
+	res.setHeader('Set-Cookie', `${name}=${value}; ${base()}; Max-Age=${age}`)
+}
+
+/** Clears the session cookie on a response. */
+export const clear = (res: Response) =>
+	res.setHeader('Set-Cookie', `${name}=; ${base()}; Max-Age=0`)

package/src/csrf.ts

@@ -0,0 +1,80 @@
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import { origin, type Request, type Response } from 'ajo-kit'
+import { generate } from './session'
+import { parse } from './cookie'
+import * as secret from './secret'
+
+const NAME = 'XSRF-TOKEN'
+const secure = () => process.env.NODE_ENV === 'production' ? '; Secure' : ''
+
+const sign = (session: string, token: string) =>
+	createHmac('sha256', secret.value()).update(`${session}:${token}`).digest('hex')
+
+const equal = (left: string, right: string) => {
+	const a = Buffer.from(left, 'hex')
+	const b = Buffer.from(right, 'hex')
+
+	return a.length === b.length && timingSafeEqual(a, b)
+}
+
+const seal = (session: string) => {
+	const token = generate()
+	return `${token}.${sign(session, token)}`
+}
+
+const signed = (req: Request, token: string) => {
+	if (!req.session) return false
+
+	const parts = token.split('.')
+	if (parts.length !== 2) return false
+
+	const [plain, mac] = parts
+	if (!plain || !mac) return false
+
+	return equal(mac, sign(req.session.id, plain))
+}
+
+/** Sets a readable session-bound XSRF cookie and returns its token. */
+export function set(req: Request, res: Response) {
+	if (!req.session) throw new Error('CSRF token requires a session')
+
+	const token = seal(req.session.id)
+	res.setHeader('Set-Cookie', `${NAME}=${token}; Path=/; SameSite=Lax${secure()}`)
+	return token
+}
+
+/** Validates signed session-bound CSRF or same-origin proof. */
+export function verify(req: Request): boolean {
+
+	// 1. Check signed double-submit token
+
+	const cookie = parse(req.headers.cookie, NAME)
+	const header = req.headers['x-xsrf-token'] as string | undefined
+
+	if (cookie && cookie === header && signed(req, header)) return true
+
+	// 2. Check same-origin (Origin or Referer matches host)
+
+	const source = req.headers.origin
+	const referer = req.headers.referer
+
+	if (!source && !referer) return false
+
+	const base = origin(req)
+
+	if (source) {
+		try {
+			const url = new URL(source)
+			if (url.origin === base) return true
+		} catch {}
+	}
+
+	if (referer) {
+		try {
+			const url = new URL(referer)
+			if (url.origin === base) return true
+		} catch {}
+	}
+
+	return false
+}

package/src/guard.ts

@@ -0,0 +1,96 @@
+import type { Middleware, Request, Response } from 'ajo-kit'
+import { Denied, Forbidden, Failure, ajax } from 'ajo-kit'
+import { can } from './ability.client'
+import { check as confirm, credential } from './confirm'
+import { db } from './store'
+
+/** Redirects HTML requests or returns a JSON redirect envelope for AJAX. */
+export const redirect = (to: string | ((req: Request) => string)): Middleware => (req, res) => {
+
+	const target = typeof to === 'function' ? to(req) : to
+	const json = ajax(req)
+
+	res.writeHead(
+		json ? 200 : 302,
+		json
+			? { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' }
+			: { Location: target }
+	)
+	res.end(json ? JSON.stringify({ redirect: target }) : undefined)
+}
+
+/** Runs middleware only when a request condition matches. */
+export const when = (
+	condition: (req: Request, res: Response) => boolean,
+	middleware: Middleware,
+	otherwise?: Middleware
+): Middleware => (req, res, next) => {
+	if (condition(req, res)) return middleware(req, res, next)
+	if (otherwise) return otherwise(req, res, next)
+	next()
+}
+
+/** Requires an authenticated request user. */
+export const auth = (): Middleware => (req, _, next) => {
+	if (!req.user) throw new Denied()
+	next()
+}
+
+/** Redirects guests away from protected browser routes. */
+export const protect = (to = '/login') => when(req => !req.user, redirect(to))
+/** Redirects authenticated users away from guest-only routes. */
+export const guest = (to = '/dashboard') => when(req => !!req.user, redirect(to))
+
+/** Throws when the current account or bearer token lacks required abilities. */
+export function authorize(req: Request, ...required: string[]) {
+
+	if (!req.user) throw new Denied()
+
+	const abilities = req.user.abilities ?? []
+	const missing = required.find(ability => !can(abilities, ability))
+		?? (req.token ? required.find(ability => !can(req.token!.abilities, ability)) : undefined)
+
+	if (missing) throw new Forbidden(`Missing ability: ${missing}`)
+}
+
+/** Middleware variant of authorize() for route stacks. */
+export const ability = (...required: string[]): Middleware => (req, _, next) => {
+	authorize(req, ...required)
+	next()
+}
+
+/** Requires recent password confirmation for the current credential. */
+export const confirmed = (window?: number): Middleware => (req, res, next) => {
+
+	if (!req.user || !credential(req)) throw new Denied()
+
+	if (!confirm(req, window)) {
+		const back = encodeURIComponent(req.originalUrl)
+		return redirect(`/confirm?redirect=${back}`)(req, res, next)
+	}
+
+	next()
+}
+
+/** Requires the authenticated user to have a verified timestamp. */
+export const verified = (): Middleware => async (req, res, next) => {
+
+	if (!req.user) throw new Denied()
+
+	const user = await db()
+		.selectFrom('users')
+		.select(['verified'])
+		.where('id', '=', req.user.id)
+		.executeTakeFirst()
+
+	if (!user?.verified) {
+
+		if (ajax(req)) {
+			throw new Failure(403, 'Email verification required')
+		}
+
+		return redirect('/verify')(req, res, next)
+	}
+
+	next()
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+/** Route guards and imperative authorization helpers. */
+export { auth, protect, guest, ability, confirmed, verified, redirect, when, authorize } from './guard'
+/** Ability matching and set helpers. */
+export { all, can, compact, intersect, merge, type Ability } from './ability.client'
+/** Account role grant helpers. */
+export * as account from './account'
+/** Configures the auth package database accessor. */
+export { configure } from './store'
+/** Password confirmation stamp helpers. */
+export * as confirm from './confirm'
+/** Session cookie helpers. */
+export * as cookie from './cookie'
+/** CSRF token and origin verification helpers. */
+export * as csrf from './csrf'
+/** Guard helper namespace. */
+export * as guard from './guard'
+/** In-memory rate limit helpers. */
+export * as limit from './limit'
+/** Password hashing and verification helpers. */
+export * as password from './password'
+/** Password reset token helpers. */
+export * as reset from './reset'
+/** Cookie session lifecycle helpers. */
+export * as session from './session'
+/** API token lifecycle helpers. */
+export * as token from './token'
+/** Email verification signature helpers. */
+export * as verify from './verify'
+/** Auth and CSRF middleware namespace. */
+export * as wares from './wares'
+/** Auth table and row types. */
+export type { User, New, Session, Token, Role, Auth } from './types'

package/src/limit.ts

@@ -0,0 +1,38 @@
+interface Attempt {
+	count: number
+	reset: number
+}
+
+const store = new Map<string, Attempt>()
+
+/** Returns true when a key is still under the hit limit. */
+export function check(key: string, max = 5): boolean {
+	const entry = store.get(key)
+	if (!entry || Date.now() > entry.reset) return true
+	return entry.count < max
+}
+
+/** Records one hit for a key within the current window. */
+export function hit(key: string, window = 60_000): void {
+
+	const entry = store.get(key)
+	const now = Date.now()
+
+	if (!entry || now > entry.reset) {
+		store.set(key, { count: 1, reset: now + window })
+	} else {
+		entry.count++
+	}
+}
+
+/** Clears all hits for a key. */
+export function clear(key: string): void {
+	store.delete(key)
+}
+
+/** Returns remaining hits before a key reaches the limit. */
+export function remaining(key: string, max = 5): number {
+	const entry = store.get(key)
+	if (!entry || Date.now() > entry.reset) return max
+	return Math.max(0, max - entry.count)
+}

package/src/password.ts

@@ -0,0 +1,12 @@
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.resolve('ajo-kit-auth'))
+const argon2 = require('argon2') as typeof import('argon2')
+
+const options = { type: argon2.argon2id, memoryCost: 19456, timeCost: 2, parallelism: 1 }
+
+/** Hashes a plaintext password with Argon2id. */
+export const hash = (plain: string) => argon2.hash(plain, options)
+
+/** Verifies a plaintext password against an Argon2 hash. */
+export const verify = (plain: string, hashed: string) => argon2.verify(hashed, plain)

package/src/reset.ts

@@ -0,0 +1,40 @@
+import { createHash } from 'node:crypto'
+import { generate } from './session'
+import { db } from './store'
+
+const hash = (plain: string) => createHash('sha256').update(plain).digest('hex')
+const hours = 1
+
+/** Creates a password reset token and returns its plaintext value. */
+export async function create(user: number): Promise<string> {
+
+	await db().deleteFrom('resets').where('user', '=', user).execute()
+
+	const plain = generate()
+	const id = hash(plain)
+	const expiry = new Date(Date.now() + hours * 60 * 60 * 1000).toISOString()
+
+	await db().insertInto('resets').values({ id, user, expiry }).execute()
+
+	return plain
+}
+
+/** Resolves a plaintext reset token to its user id when active. */
+export async function validate(plain: string): Promise<number | null> {
+
+	const id = hash(plain)
+	const reset = await db()
+		.selectFrom('resets')
+		.select(['user', 'expiry'])
+		.where('id', '=', id)
+		.executeTakeFirst()
+
+	if (!reset || new Date(reset.expiry) < new Date()) return null
+
+	return reset.user
+}
+
+/** Deletes expired password reset tokens. */
+export function prune() {
+	return db().deleteFrom('resets').where('expiry', '<', new Date().toISOString()).execute()
+}

package/src/secret.ts

@@ -0,0 +1,18 @@
+const fallback = 'change-in-production'
+const minimum = 32
+const samples = new Set([fallback, 'your-secret-key'])
+
+const production = () => process.env.NODE_ENV === 'production'
+
+/** Returns the app signing secret and fails closed in production. */
+export const value = () => {
+	const secret = process.env.APP_SECRET?.trim() ? process.env.APP_SECRET : undefined
+
+	if (production() && (!secret || secret.length < minimum || samples.has(secret))) {
+		const message = 'APP_SECRET must be set to a strong production secret'
+		console.error(`[security] ${message}`)
+		throw new Error(message)
+	}
+
+	return secret ?? fallback
+}