@ultimabase/password 0.0.0-stage → 0.1.1

package/src/models.ts

@@ -0,0 +1,190 @@
+// password's own models (D-110, D-113, D-114, D-117): each user's hash, and
+// what the sign-in limit and the hourly limits count.
+import ipaddr from 'ipaddr.js'
+import type { Field, ModelOf, ScalarOptions } from 'ultimabase'
+import { defineModel, master, PublicError } from 'ultimabase'
+
+const M = { as: master }
+const limit = 10
+const ceiling = 100
+const window = 15 * 60 * 1000
+const requests = 10
+export const hour: number = 60 * 60 * 1000
+
+type HashFields = {
+	readonly userId: Field<string, { readonly unique: true }>
+	readonly hash: Field<string, ScalarOptions<string>>
+	/** New each time the password is set, kept when it is rehashed. */
+	readonly stamp: Field<string, { readonly unique: true }>
+}
+
+export const PasswordHash: ModelOf<'PasswordHash', HashFields, []> =
+	defineModel({
+		name: 'PasswordHash',
+		fields: (f) => ({
+			userId: f.string({ unique: true }),
+			hash: f.string(),
+			stamp: f.string({ unique: true }),
+		}),
+	})
+
+type AttemptFields = {
+	readonly subject: Field<string, ScalarOptions<string>>
+	readonly address: Field<string, ScalarOptions<string>>
+	readonly at: Field<Date, ScalarOptions<Date>>
+}
+
+export const PasswordAttempt: ModelOf<'PasswordAttempt', AttemptFields, []> =
+	defineModel({
+		name: 'PasswordAttempt',
+		fields: (f) => ({
+			subject: f.string(),
+			address: f.string(),
+			at: f.dateTime(),
+		}),
+		indexes: [{ fields: ['subject', 'address'] }, { fields: ['at'] }],
+	})
+
+type RequestFields = {
+	readonly kind: Field<string, ScalarOptions<string>>
+	/** An address's network, or a user for the emails it receives. */
+	readonly subject: Field<string, ScalarOptions<string>>
+	readonly at: Field<Date, ScalarOptions<Date>>
+}
+
+export const PasswordRequest: ModelOf<'PasswordRequest', RequestFields, []> =
+	defineModel({
+		name: 'PasswordRequest',
+		fields: (f) => ({
+			kind: f.string(),
+			subject: f.string(),
+			at: f.dateTime(),
+		}),
+		indexes: [{ fields: ['kind', 'subject'] }, { fields: ['at'] }],
+	})
+
+/**
+ * What the limits count for `address`: an IPv6 address's /64 network, the
+ * IPv4 address an IPv4-mapped one holds, in any notation, any other as it is
+ * (D-114).
+ */
+export function networkOf(address: string): string {
+	if (!ipaddr.IPv6.isValid(address)) return address
+	const ip = ipaddr.IPv6.parse(address)
+	if (ip.isIPv4MappedAddress()) return ip.toIPv4Address().toString()
+	const prefix = ip.parts.slice(0, 4).map((group) => group.toString(16))
+	return `${prefix.join(':')}::/64`
+}
+
+const tooMany = (oldest: Date, span: number, now: number): PublicError =>
+	new PublicError('TOO_MANY_ATTEMPTS', 'Too many attempts: try again later.', {
+		details: {
+			retryAfter: Math.max(
+				Math.ceil((oldest.getTime() + span - now) / 1000),
+				1,
+			),
+		},
+	})
+
+/** Where an attempt comes from; `undefined` for server code, not counted. */
+export type Attempt =
+	{ readonly subject: string; readonly address: string } | undefined
+
+/** The `n`th most recent failure but `id` matching `where`, if there is one. */
+async function nth(
+	where: { readonly subject?: string; readonly address?: string },
+	id: string,
+	n: number,
+): Promise<Date | undefined> {
+	const failures = await PasswordAttempt.findMany(
+		{ where: { ...where, id: { not: id } }, orderBy: { at: 'desc' }, take: n },
+		M,
+	)
+	return failures[n - 1]?.at
+}
+
+/**
+ * Counts an attempt as failed until `run` succeeds, so concurrent attempts
+ * cannot pass the limit (D-113, D-114). Within 15 minutes, the 11th from one
+ * address on a subject is refused, as the 101st on it or from the address;
+ * a success clears its address's count, a busy refusal is not counted.
+ */
+export async function limited<T>(
+	attempt: Attempt,
+	run: () => Promise<T>,
+): Promise<T> {
+	if (attempt === undefined) return run()
+	const { subject } = attempt
+	const address = networkOf(attempt.address)
+	const now = Date.now()
+	const since = new Date(now - window)
+	await PasswordAttempt.deleteMany({ where: { at: { lte: since } } }, M)
+	const { id } = await PasswordAttempt.create(
+		{ data: { subject, address, at: new Date(now) } },
+		M,
+	)
+	// Several may be reached: the latest says when to retry.
+	const [oldest] = [
+		await nth({ subject, address }, id, limit),
+		await nth({ subject }, id, ceiling),
+		await nth({ address }, id, ceiling),
+	]
+		.filter((at) => at !== undefined)
+		.toSorted((a, b) => b.getTime() - a.getTime())
+	if (oldest !== undefined) {
+		await PasswordAttempt.deleteMany({ where: { id } }, M)
+		throw tooMany(oldest, window, now)
+	}
+	try {
+		const result = await run()
+		await PasswordAttempt.deleteMany({ where: { subject, address } }, M)
+		return result
+	} catch (error) {
+		if (error instanceof PublicError && error.code === 'TOO_MANY_ATTEMPTS') {
+			await PasswordAttempt.deleteMany({ where: { id } }, M)
+		}
+		throw error
+	}
+}
+
+/** What the hourly limits count (D-114, D-117). */
+export type RequestKind = 'signUp' | 'reset' | 'verify' | 'email'
+
+/**
+ * Counts a request of `kind` from `subject`; past `most` within one hour,
+ * the refusal instead, and the request is not counted. It is counted before
+ * the others are, so concurrent requests cannot pass the limit (D-114).
+ */
+export async function hourly(
+	kind: RequestKind,
+	subject: string,
+	most: number,
+): Promise<PublicError | undefined> {
+	const now = Date.now()
+	await PasswordRequest.deleteMany(
+		{ where: { at: { lte: new Date(now - hour) } } },
+		M,
+	)
+	const { id } = await PasswordRequest.create(
+		{ data: { kind, subject, at: new Date(now) } },
+		M,
+	)
+	const where = { kind, subject, id: { not: id } }
+	const recent = await PasswordRequest.findMany(
+		{ where, orderBy: { at: 'desc' }, take: most },
+		M,
+	)
+	const oldest = recent[most - 1]
+	if (oldest === undefined) return undefined
+	await PasswordRequest.deleteMany({ where: { id } }, M)
+	return tooMany(oldest.at, hour, now)
+}
+
+/** Refuses the eleventh request of `kind` from `address` within one hour (D-114, D-117). */
+export async function requestLimited(
+	kind: RequestKind,
+	address: string,
+): Promise<void> {
+	const refused = await hourly(kind, networkOf(address), requests)
+	if (refused !== undefined) throw refused
+}

package/src/plugin.ts

@@ -0,0 +1,310 @@
+// `passwordPlugin()` and `password()` (D-113): a sign-in method, an ordinary
+// plugin with its functions, its models, its commands and its options.
+import type { Auth, AuthApi } from '@ultimabase/auth'
+import { authPlugin } from '@ultimabase/auth'
+import type {
+	Client,
+	ExposedModel,
+	Field,
+	Identity,
+	Payload,
+	PluginOf,
+	PluginTypes,
+	Queries,
+	Register,
+	UseOf,
+	UserOf,
+} from 'ultimabase'
+import {
+	definePlugin,
+	isMaster,
+	master,
+	PublicError,
+	Refused,
+} from 'ultimabase'
+import manifest from '../package.json' with { type: 'json' }
+import type { SignedIn, State } from './core.ts'
+import {
+	attemptOf,
+	createUser,
+	setPassword,
+	signedIn,
+	verified,
+} from './core.ts'
+import type { SendEmail } from './email-functions.ts'
+import { emailFunctions, mailerOf } from './email-functions.ts'
+import { passwordFunctions } from './functions.ts'
+import type { Credentials, Property } from './input.ts'
+import { emailOf, fieldProperty, passwordOf, valid } from './input.ts'
+import { PasswordAttempt, PasswordHash, PasswordRequest } from './models.ts'
+import { PasswordToken } from './tokens.ts'
+
+/** The user fields a sign-up may take; any name before the user is registered. */
+export type UserField = Register extends { readonly user: unknown }
+	? Extract<
+			Exclude<keyof UserOf<Register>, 'id' | 'createdAt' | 'updatedAt'>,
+			string
+		>
+	: string
+
+export interface PasswordOptions {
+	/** The user fields `signUp` takes besides the email and the password; `false` closes sign-up. */
+	readonly signUp?: readonly UserField[] | false
+	/**
+	 * Sends an email that carries a token: a reset or a verification link
+	 * the application writes. Without it, no function sends one (D-117).
+	 */
+	readonly sendEmail?: SendEmail
+}
+
+type Options = { readonly as?: Identity }
+/** A transport's client, which counts the attempt and gets the cookie (D-115). */
+type SignInOptions = Options & { readonly client?: Client }
+type CreateData<F> = Parameters<Queries<F>['create']>[0]['data']
+type UserRow<F> = Payload<F, {}>
+
+/** password's commands on the user model (D-113). */
+export interface PasswordCommands<F> {
+	/** Creates the user, its account and its hash; opens no session. */
+	signUp(
+		args: Credentials & { readonly data: CreateData<F> },
+		options?: Options,
+	): Promise<UserRow<F>>
+	/**
+	 * Opens a session; with a `client`, counted and with its cookie as the
+	 * signIn function, otherwise never limited.
+	 */
+	signIn(
+		args: Credentials,
+		options?: SignInOptions,
+	): Promise<SignedIn<UserRow<F>>>
+	/**
+	 * Replaces the password and ends every session, as Master or as the user.
+	 * It takes no current password: check the user's intent first, as
+	 * changePassword does.
+	 */
+	setPassword(
+		args: { readonly id: string; readonly password: string },
+		options?: Options,
+	): Promise<void>
+}
+
+/** password's types (D-57). */
+export interface Password extends PluginTypes {
+	readonly name: 'password'
+	readonly requires: Auth
+	readonly appOptions: PasswordOptions
+	readonly addedFields: {
+		readonly emailVerified: Field<boolean, { readonly default: false }>
+	}
+	readonly commands: PasswordCommands<this['fields']>
+}
+
+const M = { as: master }
+const states = new WeakMap<AuthApi, State>()
+/** The `create` of each model whose `use` lists `password()`. */
+const using = new WeakSet<object>()
+
+function stateOf(auth: AuthApi): State {
+	const state = states.get(auth)
+	if (state === undefined) throw new Error('password has not started.')
+	return state
+}
+
+/** The one model whose `use` lists `password()`. */
+function usersOf(models: readonly ExposedModel[]): ExposedModel {
+	// oxlint-disable-next-line typescript/unbound-method -- compared by identity, never called.
+	const users = models.filter(({ queries }) => using.has(queries.create))
+	const [first, second] = users
+	if (first === undefined) {
+		throw new Refused(
+			'passwordPlugin() needs the user model to list it: add `use: [password()]` to defineUser.',
+		)
+	}
+	if (second !== undefined) {
+		throw new Refused(
+			`${first.schema.name} and ${second.schema.name} both use password(): only the user model does.`,
+		)
+	}
+	return first
+}
+
+const reserved = new Set([
+	'id',
+	'createdAt',
+	'updatedAt',
+	'email',
+	'password',
+	'emailVerified',
+])
+
+/** The listed fields' properties; an unknown, a reserved or a missing one stops startup. */
+function signUpFields(
+	users: ExposedModel,
+	listed: readonly string[],
+): ReadonlyMap<string, Property> {
+	const { name, fields } = users.schema
+	const where = `passwordPlugin({ signUp })`
+	const properties = new Map<string, Property>()
+	for (const field of listed) {
+		const found = fields.find((each) => each.name === field)
+		if (found === undefined || reserved.has(field)) {
+			throw new Refused(
+				`${where}: ${name}.${field} is not a field sign-up may take.`,
+			)
+		}
+		properties.set(
+			field,
+			fieldProperty(
+				found,
+				users.required.includes(field),
+				where,
+				users.validators[field],
+			),
+		)
+	}
+	const missing = users.required.filter((field) => !properties.has(field))
+	if (missing.length > 0) {
+		throw new Refused(
+			`${where}: ${name} needs ${missing.join(', ')} to be created; list them.`,
+		)
+	}
+	return properties
+}
+
+/** A sign-up's data, checked against the list unless the caller is Master. */
+function signUpData(state: State, data: object, caller: Identity): object {
+	if (isMaster(caller)) return data
+	if (state.signUp === false) {
+		throw new PublicError('ACCESS_DENIED', 'Sign-up is closed.')
+	}
+	const { signUp } = state
+	const issues = Object.keys(data)
+		.filter((key) => !signUp.has(key))
+		.map((key) => ({ path: ['data', key], message: 'Unknown field.' }))
+	if (issues.length > 0) {
+		throw new PublicError(
+			'VALIDATION_FAILED',
+			'Sign-up takes the listed fields only.',
+			{
+				details: { issues },
+			},
+		)
+	}
+	return data
+}
+
+/** The user model and the sign-up fields, `false` when sign-up is closed. */
+function configOf(
+	options: PasswordOptions,
+	models: readonly ExposedModel[],
+): {
+	readonly users: ExposedModel
+	readonly fields: ReadonlyMap<string, Property> | false
+} {
+	const users = usersOf(models)
+	const listed = options.signUp ?? []
+	const fields = listed === false ? false : signUpFields(users, listed)
+	return { users, fields }
+}
+
+const callerOf = (options: Options | undefined): Identity =>
+	options?.as ?? { kind: 'anonymous' }
+
+const definition = definePlugin<Password>({
+	name: 'password',
+	manifest,
+	requires: { auth: authPlugin },
+	models: [PasswordHash, PasswordAttempt, PasswordRequest, PasswordToken],
+	addedFields: (f) => ({
+		// Only Master confirms an email: rules read it (D-117).
+		emailVerified: f.boolean({ default: false }).with({
+			access: { create: () => false, update: () => false },
+		}),
+	}),
+	hooks: {
+		// The user's hash and tokens go with them (D-113, D-117).
+		afterDelete: async ({ record }) => {
+			const where = { userId: record.id }
+			await PasswordHash.deleteMany({ where }, M)
+			await PasswordToken.deleteMany({ where }, M)
+			const emails = { kind: 'email', subject: record.id }
+			await PasswordRequest.deleteMany({ where: emails }, M)
+		},
+	},
+	commands: ({ queries, plugins }) => {
+		using.add(queries.create)
+		return {
+			signUp: async ({ email, password, data }, options) => {
+				const state = stateOf(plugins.auth)
+				const checked = signUpData(state, data, callerOf(options))
+				const { user } = await createUser(
+					state,
+					valid(emailOf, email, 'email'),
+					valid(passwordOf, password, 'password'),
+					checked,
+				)
+				// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the user model's row, created by its own queries.
+				return user as UserRow<Password['addedFields']>
+			},
+			signIn: async ({ email, password }, options) => {
+				const state = stateOf(plugins.auth)
+				const subject = valid(emailOf, email, 'email')
+				const client = options?.client
+				const attempt = attemptOf(subject, client)
+				const checked = await verified(state, subject, password, attempt)
+				const opened = await signedIn(state, checked, client)
+				// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the user model's row, read by its own queries.
+				return opened as SignedIn<UserRow<Password['addedFields']>>
+			},
+			setPassword: async ({ id, password }, options) => {
+				const caller = callerOf(options)
+				const self = caller.kind === 'user' && caller.user.id === id
+				if (!self && !isMaster(caller)) {
+					throw new PublicError(
+						'ACCESS_DENIED',
+						'User.setPassword runs as Master or as the user.',
+					)
+				}
+				const state = stateOf(plugins.auth)
+				await setPassword(state, id, valid(passwordOf, password, 'password'))
+			},
+		}
+	},
+	// The functions are built before the APIs (D-89): they read the state
+	// when they run, and `api` stores it once auth's API exists.
+	api: ({ options, plugins, models, logger }) => {
+		const { users, fields } = configOf(options, models)
+		const signUp = fields === false ? false : new Set(fields.keys())
+		const { auth } = plugins
+		states.set(auth, { auth, users, signUp, logger, sending: new Set() })
+	},
+	// The emails under way still query: they end before the database closes.
+	stop: async ({ plugins }) => {
+		await Promise.all(stateOf(plugins.auth).sending)
+	},
+	functions: ({ options, plugins, models }) => {
+		const { users, fields } = configOf(options, models)
+		const state = () => stateOf(plugins.auth)
+		const { sendEmail } = options
+		const mailer = sendEmail === undefined ? undefined : mailerOf(sendEmail)
+		return [
+			...passwordFunctions(state, users, fields, mailer),
+			...(mailer === undefined ? [] : emailFunctions(state, mailer)),
+		]
+	},
+})
+
+/**
+ * The password sign-in method; it requires `authPlugin()`.
+ *
+ * Known and kept (D-115): `signUp` refuses a taken email with
+ * `UNIQUE_VIOLATION`, which tells that the email has an account until email
+ * verification can hide it; a hundred failures on one account within 15
+ * minutes, from any addresses, lock it for everyone, and a hundred from one
+ * address lock that address out of every account (D-114); `SignedIn`
+ * holds the token even when the cookie is set.
+ */
+export const passwordPlugin: PluginOf<Password> = definition.plugin
+/** The user model's entry: its commands, and its hash deleted with it. */
+export const password: UseOf<Password> = definition.use

package/src/tokens.ts

@@ -0,0 +1,98 @@
+// password's emails (D-117): the tokens their links carry, used once, and
+// the emails each account receives within one hour.
+import { createHash, randomBytes } from 'node:crypto'
+import type { Field, ModelOf, ScalarOptions } from 'ultimabase'
+import { defineModel, master, PublicError } from 'ultimabase'
+import { hour, hourly } from './models.ts'
+
+const M = { as: master }
+/** The emails an account receives within one hour, of either kind. */
+const emails = 3
+
+/** What an email's token lets its holder do. */
+export type EmailKind = 'reset' | 'verify'
+
+/** What `sendEmail` receives: the application writes the text and the link. */
+export interface Email {
+	readonly kind: EmailKind
+	/** The account's email, normalized. */
+	readonly to: string
+	/** What the link carries, for `resetPassword` or `verifyEmail`. */
+	readonly token: string
+	readonly userId: string
+}
+
+const lifetimes: Readonly<Record<EmailKind, number>> = {
+	reset: hour,
+	verify: 24 * hour,
+}
+
+type TokenFields = {
+	readonly userId: Field<string, ScalarOptions<string>>
+	readonly kind: Field<string, ScalarOptions<string>>
+	/** The token's SHA-256: a leaked database gives no working link. */
+	readonly hash: Field<string, { readonly unique: true }>
+	readonly expiresAt: Field<Date, ScalarOptions<Date>>
+}
+
+export const PasswordToken: ModelOf<'PasswordToken', TokenFields, []> =
+	defineModel({
+		name: 'PasswordToken',
+		fields: (f) => ({
+			userId: f.string(),
+			kind: f.string(),
+			hash: f.string({ unique: true }),
+			expiresAt: f.dateTime(),
+		}),
+		indexes: [{ fields: ['userId', 'kind'] }, { fields: ['expiresAt'] }],
+	})
+
+const hashOf = (token: string): string =>
+	createHash('sha256').update(token).digest('base64url')
+
+/** A new token of `kind` for `userId`, which replaces the older one. */
+export async function issueToken(
+	userId: string,
+	kind: EmailKind,
+): Promise<string> {
+	const now = Date.now()
+	await PasswordToken.deleteMany(
+		{ where: { expiresAt: { lte: new Date(now) } } },
+		M,
+	)
+	await PasswordToken.deleteMany({ where: { userId, kind } }, M)
+	const token = randomBytes(32).toString('base64url')
+	const expiresAt = new Date(now + lifetimes[kind])
+	await PasswordToken.create(
+		{ data: { userId, kind, hash: hashOf(token), expiresAt } },
+		M,
+	)
+	return token
+}
+
+const invalidLink = () =>
+	new PublicError('INVALID_CREDENTIALS', 'This link is invalid or has expired.')
+
+/** The user a token of `kind` was issued to; a wrong, used or expired one fails. */
+export async function redeemToken(
+	token: string,
+	kind: EmailKind,
+): Promise<string> {
+	const hash = hashOf(token)
+	const stored = await PasswordToken.findUnique({ where: { hash } }, M)
+	if (stored?.kind !== kind) throw invalidLink()
+	// One delete wins, so a token used twice at once works once.
+	const { count } = await PasswordToken.deleteMany({ where: { hash } }, M)
+	if (count === 0 || stored.expiresAt.getTime() <= Date.now()) {
+		throw invalidLink()
+	}
+	return stored.userId
+}
+
+/**
+ * Counts an email to `userId`; past three within one hour, the refusal
+ * instead, and the email is not counted.
+ */
+export const emailLimited = async (
+	userId: string,
+): Promise<PublicError | undefined> => hourly('email', userId, emails)