@ultimabase/password 0.0.0-stage → 0.1.1

package/src/functions.ts

@@ -0,0 +1,102 @@
+// password's functions (D-113, D-114): `signUp`, `signIn` and `changePassword`, each
+// taking one named input and returning `SignedIn`.
+import type { ExposedModel, FunctionShape, OutputSpec } from 'ultimabase'
+import { allow, defineFunction, defineType, PublicError } from 'ultimabase'
+import type { State } from './core.ts'
+import {
+	attemptOf,
+	checkCurrent,
+	createUser,
+	setPassword,
+	signedIn,
+	verified,
+} from './core.ts'
+import type { Mailer } from './email-functions.ts'
+import { later } from './email-functions.ts'
+import type { Property } from './input.ts'
+import { requestLimited } from './models.ts'
+import {
+	changePasswordInput,
+	outputSchema,
+	signInInput,
+	signUpInput,
+} from './input.ts'
+
+/** `User.nullable()`, which `ExposedModel.model` holds but does not type. */
+function nullable(model: ExposedModel['model']): OutputSpec {
+	const make: unknown = Reflect.get(model, 'nullable')
+	if (typeof make !== 'function')
+		throw new TypeError(`${model.name} is not a model.`)
+	// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- a `defineModel` value's `nullable()` (D-109).
+	return Reflect.apply(make, model, []) as OutputSpec
+}
+
+/**
+ * The functions, `signUp` only when sign-up is open; each is public. With a
+ * `mailer`, `signUp` sends the verification email (D-117).
+ */
+export function passwordFunctions(
+	stateOf: () => State,
+	users: ExposedModel,
+	fields: ReadonlyMap<string, Property> | false,
+	mailer: Mailer | undefined,
+): readonly FunctionShape[] {
+	const SignedIn = defineType({
+		name: 'SignedIn',
+		fields: {
+			token: outputSchema<string>({ type: 'string' }),
+			expiresAt: outputSchema<Date>({ type: 'string', format: 'date-time' }),
+			user: nullable(users.model),
+		},
+	})
+	const signUp = defineFunction({
+		name: 'signUp',
+		input: signUpInput(fields === false ? new Map() : fields),
+		output: SignedIn,
+		run: async ({ input: { input }, client }) => {
+			const state = stateOf()
+			if (client !== undefined) await requestLimited('signUp', client.address)
+			const { email, password, ...data } = input
+			const { user, stamp } = await createUser(state, email, password, data)
+			if (mailer !== undefined) {
+				later(state, async () => {
+					await mailer('verify', user.id, email)
+				})
+			}
+			return signedIn(state, { userId: user.id, stamp }, client)
+		},
+	}).with({ access: allow.public })
+	const signIn = defineFunction({
+		name: 'signIn',
+		input: signInInput,
+		output: SignedIn,
+		run: async ({ input: { input }, client }) => {
+			const state = stateOf()
+			const { email, password } = input
+			const attempt = attemptOf(email, client)
+			const checked = await verified(state, email, password, attempt)
+			return signedIn(state, checked, client)
+		},
+	}).with({ access: allow.public })
+	const changePassword = defineFunction({
+		name: 'changePassword',
+		input: changePasswordInput,
+		output: SignedIn,
+		run: async ({ input: { input }, caller, client }) => {
+			if (caller.kind !== 'user') {
+				throw new PublicError(
+					'UNAUTHENTICATED',
+					'changePassword needs a signed-in user.',
+				)
+			}
+			const state = stateOf()
+			const { id } = caller.user
+			await checkCurrent(id, input.currentPassword, attemptOf(id, client))
+			const stamp = await setPassword(state, id, input.newPassword)
+			return signedIn(state, { userId: id, stamp }, client)
+		},
+	}).with({ access: allow.public })
+	return fields === false
+		? [signIn, changePassword]
+		: [signUp, signIn, changePassword]
+}

package/src/hash.ts

@@ -0,0 +1,144 @@
+// Password hashes (D-113): Argon2id from `node:crypto`, stored as a PHC string,
+// a few at a time (D-114).
+import { argon2, randomBytes, timingSafeEqual } from 'node:crypto'
+import { availableParallelism } from 'node:os'
+import { PublicError } from 'ultimabase'
+
+type Parameters = {
+	readonly memory: number
+	readonly passes: number
+	readonly parallelism: number
+}
+
+/** OWASP's first Argon2id setting: 19 MiB, two passes, one lane. */
+const current: Parameters = { memory: 19456, passes: 2, parallelism: 1 }
+const tagLength = 32
+const phc =
+	/^\$argon2id\$v=19\$m=(\d+),t=(\d+),p=(\d+)\$([A-Za-z0-9+/]+)\$([A-Za-z0-9+/]+)$/
+
+const unpadded = (bytes: Buffer): string =>
+	bytes.toString('base64').replace(/=+$/, '')
+
+/** The computations that run at once, and how many more may wait (D-114). */
+export const lanes: number = availableParallelism()
+export const waiting = 64
+let running = 0
+const queue: (() => void)[] = []
+
+/** Runs `run` when a lane is free; refuses it when the queue is full. */
+async function queued<T>(run: () => Promise<T>): Promise<T> {
+	if (running < lanes) running += 1
+	else if (queue.length < waiting) {
+		await new Promise<void>((resolve) => queue.push(resolve))
+	} else {
+		throw new PublicError(
+			'TOO_MANY_ATTEMPTS',
+			'The server is busy: try again.',
+			{
+				details: { retryAfter: 1 },
+			},
+		)
+	}
+	try {
+		return await run()
+	} finally {
+		// The lane goes to the next computation waiting, or is freed.
+		const next = queue.shift()
+		if (next === undefined) running -= 1
+		else next()
+	}
+}
+
+async function derive(
+	password: string,
+	nonce: Buffer,
+	parameters: Parameters,
+	length: number,
+): Promise<Buffer> {
+	return queued(async () => compute(password, nonce, parameters, length))
+}
+
+async function compute(
+	password: string,
+	nonce: Buffer,
+	parameters: Parameters,
+	length: number,
+): Promise<Buffer> {
+	return new Promise((resolve, reject) => {
+		argon2(
+			'argon2id',
+			{ message: password, nonce, tagLength: length, ...parameters },
+			(error, key) => {
+				if (error === null) resolve(key)
+				else reject(error)
+			},
+		)
+	})
+}
+
+/** The PHC string of `password`, with a new 16-byte salt. */
+export async function hashPassword(password: string): Promise<string> {
+	const salt = randomBytes(16)
+	const key = await derive(password, salt, current, tagLength)
+	const { memory, passes, parallelism } = current
+	return `$argon2id$v=19$m=${memory},t=${passes},p=${parallelism}$${unpadded(salt)}$${unpadded(key)}`
+}
+
+/**
+ * Whether a stored hash is one this plugin could verify: up to 256 MiB, 16
+ * passes and 16 lanes, and a tag of 16 to 64 bytes, so a tampered row
+ * neither exhausts the server nor matches too easily.
+ */
+const bounded = (
+	{ memory, passes, parallelism }: Parameters,
+	length: number,
+): boolean =>
+	parallelism >= 1 &&
+	parallelism <= 16 &&
+	memory >= 8 * parallelism &&
+	memory <= 262_144 &&
+	passes >= 1 &&
+	passes <= 16 &&
+	length >= 16 &&
+	length <= 64
+
+/**
+ * Whether `password` matches `stored`, and whether `stored` was made with
+ * other parameters, so a sign-in rehashes it.
+ */
+export async function verifyPassword(
+	password: string,
+	stored: string,
+): Promise<{ readonly valid: boolean; readonly stale: boolean }> {
+	const parts = phc.exec(stored)
+	if (parts === null) throw new Error('A stored password hash is not Argon2id.')
+	const [, m, t, p, salt = '', hash = ''] = parts
+	const parameters = {
+		memory: Number(m),
+		passes: Number(t),
+		parallelism: Number(p),
+	}
+	const expected = Buffer.from(hash, 'base64')
+	if (!bounded(parameters, expected.length)) {
+		throw new Error('A stored password hash has out-of-bounds parameters.')
+	}
+	const key = await derive(
+		password,
+		Buffer.from(salt, 'base64'),
+		parameters,
+		expected.length,
+	)
+	const stale =
+		parameters.memory !== current.memory ||
+		parameters.passes !== current.passes ||
+		parameters.parallelism !== current.parallelism ||
+		expected.length !== tagLength
+	return { valid: timingSafeEqual(key, expected), stale }
+}
+
+let dummy: Promise<string> | undefined
+/** A hash no password matches, checked for an unknown email (D-113). */
+export async function dummyHash(): Promise<string> {
+	dummy ??= hashPassword(randomBytes(32).toString('base64'))
+	return dummy
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+// `@ultimabase/password` (D-113): sign-up and sign-in with an email and a
+// password, hashed with Argon2id, the attempts limited.
+export type { SignedIn } from './core.ts'
+export type { SendEmail } from './email-functions.ts'
+export type { Credentials } from './input.ts'
+export type {
+	Password,
+	PasswordCommands,
+	PasswordOptions,
+	UserField,
+} from './plugin.ts'
+export type { Email, EmailKind } from './tokens.ts'
+export { password, passwordPlugin } from './plugin.ts'

package/src/input.ts

@@ -0,0 +1,360 @@
+// The functions' inputs (D-109, D-113): Standard Schemas written here, each
+// with the JSON Schema a transport types its arguments from (D-45).
+import type { SchemaField } from 'ultimabase'
+import { PublicError, Refused } from 'ultimabase'
+import { decimalPattern, issueOf } from 'ultimabase/internal'
+
+type Node = { readonly [key: string]: unknown }
+type Read = { readonly value: unknown } | { readonly message: string }
+type Issue = { readonly path: readonly string[]; readonly message: string }
+type Scalar = Extract<SchemaField, { readonly kind: 'scalar' }>
+type Result<O> = { readonly value: O } | { readonly issues: readonly Issue[] }
+
+/** Standard Schema with its JSON Schema export (standardschema.dev), copied as its specification asks. */
+interface StandardSchema<I, O> {
+	readonly '~standard': {
+		readonly version: 1
+		readonly vendor: string
+		readonly validate: (value: unknown) => Result<O>
+		readonly jsonSchema: {
+			readonly input: () => Node
+			readonly output: () => Node
+		}
+		readonly types?: { readonly input: I; readonly output: O }
+	}
+}
+
+/** One property of an input: how it reads a value, and its JSON Schema. */
+export interface Property {
+	readonly read: (value: unknown) => Read
+	readonly json: Node
+	readonly required: boolean
+	/** The shared nodes its JSON Schema refers to, lifted to the root's. */
+	readonly defs?: Node
+}
+
+const isObject = (value: unknown): value is Node =>
+	typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const text = (value: unknown): Read =>
+	typeof value === 'string' ? { value } : { message: 'Expected a string.' }
+
+/** The email trimmed, lowercased and in NFC, the account's subject (D-113, D-115). */
+export function emailOf(value: unknown): Read {
+	if (typeof value !== 'string') return { message: 'Expected a string.' }
+	const email = value.trim().toLowerCase().normalize('NFC')
+	if (email.length > 254 || !/^[^\s@]+@[^\s@]+$/.test(email)) {
+		return { message: 'Expected an email address.' }
+	}
+	return { value: email }
+}
+
+/** How a password is typed does not change it: NFKC (D-115, NIST SP 800-63B). */
+export const normalized = (password: string): string =>
+	password.normalize('NFKC')
+
+/** A password to store, normalized: 8 to 256 characters, no other rule (D-113). */
+export function passwordOf(value: unknown): Read {
+	if (typeof value !== 'string') return { message: 'Expected a string.' }
+	const password = normalized(value)
+	const length = Array.from(password).length
+	if (length < 8 || length > 256) {
+		return { message: 'A password has 8 to 256 characters.' }
+	}
+	return { value: password }
+}
+
+/** `read`'s value, or a `VALIDATION_FAILED` naming `path`. */
+export function valid<T>(
+	read: (value: unknown) => Read,
+	value: T,
+	path: string,
+): T {
+	const result = read(value)
+	if ('message' in result) {
+		const issues = [{ path: [path], message: result.message }]
+		throw new PublicError('VALIDATION_FAILED', `${path}: ${result.message}`, {
+			details: { issues },
+		})
+	}
+	// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- emailOf and passwordOf return the string they were given, normalized.
+	return result.value as T
+}
+
+/** A property of `read`, whose JSON Schema is `json`. */
+export const property = (
+	read: Property['read'],
+	json: Node,
+	required = true,
+): Property => ({ read, json, required })
+
+const [smallest, largest] = [-2_147_483_648, 2_147_483_647]
+
+/**
+ * A field's check, the kernel's (D-127, D-132, D-139): a date may come as an
+ * ISO string, and an optional field takes `null`.
+ */
+function readOf(field: Scalar): Property['read'] {
+	return (given) => {
+		if (given === null && field.optional && !field.list) return { value: given }
+		const value =
+			field.type === 'dateTime' && typeof given === 'string'
+				? new Date(given)
+				: given
+		const message = issueOf(value, field)
+		return message === undefined ? { value } : { message }
+	}
+}
+
+function jsonOf(field: Scalar): Node {
+	const { type, values = [], optional } = field
+	if (field.list) {
+		const items = jsonOf({ ...field, list: false, optional: false })
+		return {
+			type: 'array',
+			items: type === 'string' ? { ...items, minLength: 1 } : items,
+		}
+	}
+	const integer = field.integer === true
+	const base =
+		type === 'dateTime' ||
+		type === 'date' ||
+		type === 'enum' ||
+		type === 'decimal'
+			? 'string'
+			: integer
+				? 'integer'
+				: type
+	return {
+		type: optional ? [base, 'null'] : base,
+		...(integer ? { minimum: smallest, maximum: largest } : {}),
+		...(type === 'decimal' ? { pattern: decimalPattern } : {}),
+		...(type === 'dateTime' ? { format: 'date-time' } : {}),
+		...(type === 'date' ? { format: 'date' } : {}),
+		...(type === 'enum' ? { enum: optional ? [...values, null] : values } : {}),
+	}
+}
+
+/** A json field's input JSON Schema, `{}` without an export (D-125). */
+function exported(schema: object | undefined): Node {
+	const standard: unknown = schema && Reflect.get(schema, '~standard')
+	const exporter = isObject(standard) ? standard['jsonSchema'] : undefined
+	const input = isObject(exporter) ? exporter['input'] : undefined
+	if (typeof input !== 'function') return {}
+	try {
+		const node: unknown = Reflect.apply(input, exporter, [
+			{ target: 'draft-2020-12' },
+		])
+		return isObject(node) ? node : {}
+	} catch {
+		// A schema it cannot export takes any JSON value, as a field without one.
+		return {}
+	}
+}
+
+/** A json field: any value read here, its schema run by the kernel (D-125). */
+function jsonProperty(
+	field: Scalar,
+	required: boolean,
+	schema: object | undefined,
+): Property {
+	const { $schema: _, $defs: defs, ...json } = exported(schema)
+	const typed = Object.keys(json).length > 0
+	return {
+		read: (value) => ({ value }),
+		json: typed && field.optional ? { anyOf: [json, { type: 'null' }] } : json,
+		required,
+		...(isObject(defs) ? { defs } : {}),
+	}
+}
+
+/**
+ * A user field a client may send at sign-up, a json one with its `validate`;
+ * a relation stops startup (D-113, D-125).
+ */
+export function fieldProperty(
+	field: SchemaField,
+	required: boolean,
+	where: string,
+	schema?: object,
+): Property {
+	if (field.kind !== 'scalar') {
+		throw new Refused(
+			`${where}: ${field.name} is a relation, which sign-up does not take.`,
+		)
+	}
+	if (field.type === 'json') return jsonProperty(field, required, schema)
+	return property(readOf(field), jsonOf(field), required)
+}
+
+/** An object of `properties`, which refuses any other key. */
+function objectRead(
+	properties: ReadonlyMap<string, Property>,
+	value: unknown,
+	path: readonly string[],
+	issues: Issue[],
+): Node {
+	if (!isObject(value)) {
+		issues.push({ path, message: 'Expected an object.' })
+		return {}
+	}
+	const output: { [key: string]: unknown } = {}
+	for (const key of Object.keys(value)) {
+		if (!properties.has(key)) {
+			issues.push({ path: [...path, key], message: 'Unknown field.' })
+		}
+	}
+	for (const [key, { read, required }] of properties) {
+		const given = value[key]
+		if (given === undefined) {
+			if (required) issues.push({ path: [...path, key], message: 'Required.' })
+			continue
+		}
+		const result = read(given)
+		if ('message' in result) {
+			issues.push({ path: [...path, key], message: result.message })
+		} else output[key] = result.value
+	}
+	return output
+}
+
+function objectJson(properties: ReadonlyMap<string, Property>): Node {
+	const required = [...properties].filter(([, each]) => each.required)
+	return {
+		type: 'object',
+		properties: Object.fromEntries(
+			[...properties].map(([key, each]) => [key, each.json]),
+		),
+		required: required.map(([key]) => key),
+		additionalProperties: false,
+	}
+}
+
+/** What a named input's `run` reads, under `input` (D-109). */
+export type Named<O> = { readonly input: O }
+
+/**
+ * One `input` argument of the object `id`, typed `SignUpInput` over GraphQL
+ * for the id `SignUp`; the email is normalized, the dates read (D-113).
+ */
+export function namedInput<O extends object>(
+	id: string,
+	properties: ReadonlyMap<string, Property>,
+): StandardSchema<Named<O>, Named<O>> {
+	const json = (): Node => ({
+		$schema: 'https://json-schema.org/draft/2020-12/schema',
+		type: 'object',
+		properties: { input: { $ref: `#/$defs/${id}` } },
+		required: ['input'],
+		additionalProperties: false,
+		$defs: Object.assign(
+			{},
+			...[...properties.values()].map((each) => each.defs),
+			{ [id]: objectJson(properties) },
+		),
+	})
+	const validate = (value: unknown) => {
+		const issues: Issue[] = []
+		const root = isObject(value) ? value : {}
+		const input = objectRead(properties, root['input'], ['input'], issues)
+		if (!isObject(value))
+			issues.push({ path: [], message: 'Expected an object.' })
+		// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- each property of O was read by its check above.
+		return issues.length > 0 ? { issues } : { value: { input: input as O } }
+	}
+	return {
+		'~standard': Object.freeze({
+			version: 1,
+			vendor: 'ultimabase-password',
+			validate,
+			jsonSchema: { input: json, output: json },
+		}),
+	}
+}
+
+const string = { type: 'string' }
+const email = property(emailOf, { type: 'string', format: 'email' })
+
+/** What `signIn` and `User.signIn` take. */
+export type Credentials = { readonly email: string; readonly password: string }
+
+type ChangePassword = {
+	readonly currentPassword: string
+	readonly newPassword: string
+}
+type SignUp = Credentials & { readonly [field: string]: unknown }
+
+export const signInInput: StandardSchema<
+	Named<Credentials>,
+	Named<Credentials>
+> = namedInput(
+	'SignIn',
+	new Map([
+		['email', email],
+		['password', property(text, string)],
+	]),
+)
+
+export const changePasswordInput: StandardSchema<
+	Named<ChangePassword>,
+	Named<ChangePassword>
+> = namedInput(
+	'ChangePassword',
+	new Map([
+		['currentPassword', property(text, string)],
+		['newPassword', property(passwordOf, string)],
+	]),
+)
+
+type ResetPassword = { readonly token: string; readonly password: string }
+
+/** What `requestPasswordReset` takes (D-117). */
+export const requestResetInput: StandardSchema<
+	Named<{ readonly email: string }>,
+	Named<{ readonly email: string }>
+> = namedInput('RequestPasswordReset', new Map([['email', email]]))
+
+/** What `resetPassword` takes: the email's token and the new password (D-117). */
+export const resetPasswordInput: StandardSchema<
+	Named<ResetPassword>,
+	Named<ResetPassword>
+> = namedInput(
+	'ResetPassword',
+	new Map([
+		['token', property(text, string)],
+		['password', property(passwordOf, string)],
+	]),
+)
+
+/** What `verifyEmail` takes: the email's token (D-117). */
+export const verifyEmailInput: StandardSchema<
+	Named<{ readonly token: string }>,
+	Named<{ readonly token: string }>
+> = namedInput('VerifyEmail', new Map([['token', property(text, string)]]))
+
+/** The email, the password and the listed user fields, by their names. */
+export const signUpInput = (
+	fields: ReadonlyMap<string, Property>,
+): StandardSchema<Named<SignUp>, Named<SignUp>> =>
+	namedInput(
+		'SignUp',
+		new Map([
+			['email', email],
+			['password', property(passwordOf, string)],
+			...fields,
+		]),
+	)
+
+/** An output's schema: typed and exported, never validated (D-45). */
+export function outputSchema<T>(node: Node): StandardSchema<T, T> {
+	const json = (): Node => node
+	return {
+		'~standard': Object.freeze({
+			version: 1,
+			vendor: 'ultimabase-password',
+			// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- an output is typed by its function, never validated (D-45).
+			validate: (value: unknown) => ({ value: value as T }),
+			jsonSchema: { input: json, output: json },
+		}),
+	}
+}