@ultimabase/password 0.1.2 → 0.2.0

package/src/models.ts

@@ -86,9 +86,15 @@ const tooMany = (oldest: Date, span: number, now: number): PublicError =>
 		},
 	})
 
-/** Where an attempt comes from; `undefined` for server code, not counted. */
+/**
+ * Where an attempt comes from: a client's address, none for server code
+ * that is still counted (D-161), `undefined` for server code that is not.
+ */
 export type Attempt =
-	{ readonly subject: string; readonly address: string } | undefined
+	{ readonly subject: string; readonly address?: string } | undefined
+
+/** What an attempt without an address is stored with; no address is it. */
+const server = 'server'
 
 /** The `n`th most recent failure but `id` matching `where`, if there is one. */
 async function nth(
@@ -103,11 +109,30 @@ async function nth(
 	return failures[n - 1]?.at
 }
 
+/**
+ * The failures but `id` that refuse the attempt: from one address, the 10th
+ * on the subject or the 100th on it or from the address; without one, the
+ * 10th on the subject from anywhere, and no address is filled (D-161).
+ */
+async function reached(
+	subject: string,
+	address: string | undefined,
+	id: string,
+): Promise<readonly (Date | undefined)[]> {
+	if (address === undefined) return [await nth({ subject }, id, limit)]
+	return [
+		await nth({ subject, address }, id, limit),
+		await nth({ subject }, id, ceiling),
+		await nth({ address }, id, ceiling),
+	]
+}
+
 /**
  * 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.
+ * address on a subject is refused, as the 101st on it or from the address,
+ * and the 11th without an address on a subject (D-161); a success clears
+ * its address's count, a busy refusal is not counted.
  */
 export async function limited<T>(
 	attempt: Attempt,
@@ -115,7 +140,9 @@ export async function limited<T>(
 ): Promise<T> {
 	if (attempt === undefined) return run()
 	const { subject } = attempt
-	const address = networkOf(attempt.address)
+	const network =
+		attempt.address === undefined ? undefined : networkOf(attempt.address)
+	const address = network ?? server
 	const now = Date.now()
 	const since = new Date(now - window)
 	await PasswordAttempt.deleteMany({ where: { at: { lte: since } } }, M)
@@ -124,11 +151,7 @@ export async function limited<T>(
 		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),
-	]
+	const [oldest] = (await reached(subject, network, id))
 		.filter((at) => at !== undefined)
 		.toSorted((a, b) => b.getTime() - a.getTime())
 	if (oldest !== undefined) {

package/src/plugin.ts

@@ -26,11 +26,20 @@ import manifest from '../package.json' with { type: 'json' }
 import type { SignedIn, State } from './core.ts'
 import {
 	attemptOf,
+	checkCurrent,
 	createUser,
 	setPassword,
 	signedIn,
 	verified,
 } from './core.ts'
+import {
+	created,
+	committed,
+	creating,
+	readsEmail,
+	updated,
+	updating,
+} from './email-field.ts'
 import type { SendEmail } from './email-functions.ts'
 import { emailFunctions, mailerOf } from './email-functions.ts'
 import { passwordFunctions } from './functions.ts'
@@ -87,6 +96,15 @@ export interface PasswordCommands<F> {
 		args: { readonly id: string; readonly password: string },
 		options?: Options,
 	): Promise<void>
+	/**
+	 * Checks the user's current password before a sensitive action, as
+	 * Master or as the user; opens no session. Always counted: with a
+	 * `client` as changePassword, otherwise 10 failures per user (D-161).
+	 */
+	checkPassword(
+		args: { readonly id: string; readonly password: string },
+		options?: SignInOptions,
+	): Promise<void>
 }
 
 /** password's types (D-57). */
@@ -96,6 +114,11 @@ export interface Password extends PluginTypes {
 	readonly appOptions: PasswordOptions
 	readonly addedFields: {
 		readonly emailVerified: Field<boolean, { readonly default: false }>
+		/** The password account's email (D-162). */
+		readonly email: Field<
+			string | null,
+			{ readonly optional: true; readonly unique: true }
+		>
 	}
 	readonly commands: PasswordCommands<this['fields']>
 }
@@ -111,6 +134,15 @@ function stateOf(auth: AuthApi): State {
 	return state
 }
 
+/** Deletes the user's hash, links and email requests (D-113, D-160). */
+async function forget(userId: string): Promise<void> {
+	const where = { userId }
+	await PasswordHash.deleteMany({ where }, M)
+	await PasswordToken.deleteMany({ where }, M)
+	const emails = { kind: 'email', subject: userId }
+	await PasswordRequest.deleteMany({ where: emails }, M)
+}
+
 /** 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.
@@ -211,6 +243,22 @@ function configOf(
 const callerOf = (options: Options | undefined): Identity =>
 	options?.as ?? { kind: 'anonymous' }
 
+/** Refuses `command` on user `id` but as Master or as that user. */
+function selfOrMaster(
+	options: Options | undefined,
+	id: string,
+	command: string,
+): void {
+	const caller = callerOf(options)
+	const self = caller.kind === 'user' && caller.user.id === id
+	if (!self && !isMaster(caller)) {
+		throw new PublicError(
+			'ACCESS_DENIED',
+			`User.${command} runs as Master or as the user.`,
+		)
+	}
+}
+
 const definition = definePlugin<Password>({
 	name: 'password',
 	manifest,
@@ -221,15 +269,31 @@ const definition = definePlugin<Password>({
 		emailVerified: f.boolean({ default: false }).with({
 			access: { create: () => false, update: () => false },
 		}),
+		// Only Master writes it; the hooks keep the account in step (D-162).
+		email: f.string({ optional: true, unique: true }).with({
+			access: { read: readsEmail, create: () => false, update: () => false },
+		}),
 	}),
 	hooks: {
+		// The email and the password account stay one (D-162).
+		beforeCreate: ({ data }) => {
+			creating(data)
+		},
+		afterCreate: async ({ record, plugins }) => {
+			await created(stateOf(plugins.auth), record)
+		},
+		beforeUpdate: async ({ record, data, plugins }) => {
+			await updating(stateOf(plugins.auth), record, data)
+		},
+		afterUpdate: async ({ record, previous, plugins }) => {
+			await updated(stateOf(plugins.auth), record, previous)
+		},
+		afterUpdateCommit: ({ record, previous, plugins }) => {
+			committed(stateOf(plugins.auth), record, previous)
+		},
 		// 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)
+			await forget(record.id)
 		},
 	},
 	commands: ({ queries, plugins }) => {
@@ -258,17 +322,20 @@ const definition = definePlugin<Password>({
 				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.',
-					)
-				}
+				selfOrMaster(options, id, 'setPassword')
 				const state = stateOf(plugins.auth)
 				await setPassword(state, id, valid(passwordOf, password, 'password'))
 			},
+			checkPassword: async ({ id, password }, options) => {
+				selfOrMaster(options, id, 'checkPassword')
+				const client = options?.client
+				// Counted without a client too: the check guards an action (D-161).
+				await checkCurrent(
+					id,
+					password,
+					attemptOf(id, client) ?? { subject: id },
+				)
+			},
 		}
 	},
 	// The functions are built before the APIs (D-89): they read the state
@@ -277,7 +344,20 @@ const definition = definePlugin<Password>({
 		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() })
+		const { sendEmail } = options
+		const sending = new Set<Promise<void>>()
+		states.set(auth, { auth, users, signUp, logger, sending, sendEmail })
+		// A closed account keeps its row, without a password, an email or a
+		// verified one (D-160, D-162).
+		auth.onCloseAccount(async (userId) => {
+			await forget(userId)
+			const where = { id: userId }
+			const user = await users.queries.findUnique({ where }, M)
+			if (user === null) return
+			if (user.email === null && user.emailVerified !== true) return
+			const data = { email: null, emailVerified: false }
+			await users.queries.update({ where, data }, M)
+		})
 	},
 	// The emails under way still query: they end before the database closes.
 	stop: async ({ plugins }) => {

package/src/tokens.ts

@@ -10,21 +10,33 @@ const M = { as: master }
 const emails = 3
 
 /** What an email's token lets its holder do. */
-export type EmailKind = 'reset' | 'verify'
+export type EmailKind = 'reset' | 'verify' | 'emailChange'
 
-/** 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
-}
+/**
+ * What `sendEmail` receives: the application writes the text and the link.
+ * `'emailChanged'` tells the old address its email changed (D-162).
+ */
+export type Email =
+	| {
+			readonly kind: EmailKind
+			/** The address the link goes to, normalized. */
+			readonly to: string
+			/** What the link carries, for the function its kind names. */
+			readonly token: string
+			readonly userId: string
+	  }
+	| {
+			readonly kind: 'emailChanged'
+			/** The old address. */
+			readonly to: string
+			readonly newEmail: string
+			readonly userId: string
+	  }
 
 const lifetimes: Readonly<Record<EmailKind, number>> = {
 	reset: hour,
 	verify: 24 * hour,
+	emailChange: hour,
 }
 
 type TokenFields = {
@@ -33,6 +45,8 @@ type TokenFields = {
 	/** 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>>
+	/** The address the email went to (D-162). */
+	readonly email: Field<string | null, { readonly optional: true }>
 }
 
 export const PasswordToken: ModelOf<'PasswordToken', TokenFields, []> =
@@ -43,6 +57,7 @@ export const PasswordToken: ModelOf<'PasswordToken', TokenFields, []> =
 			kind: f.string(),
 			hash: f.string({ unique: true }),
 			expiresAt: f.dateTime(),
+			email: f.string({ optional: true }),
 		}),
 		indexes: [{ fields: ['userId', 'kind'] }, { fields: ['expiresAt'] }],
 	})
@@ -50,10 +65,11 @@ export const PasswordToken: ModelOf<'PasswordToken', TokenFields, []> =
 const hashOf = (token: string): string =>
 	createHash('sha256').update(token).digest('base64url')
 
-/** A new token of `kind` for `userId`, which replaces the older one. */
+/** A new token of `kind` for `userId`, sent to `email`; it replaces the older one. */
 export async function issueToken(
 	userId: string,
 	kind: EmailKind,
+	email: string,
 ): Promise<string> {
 	const now = Date.now()
 	await PasswordToken.deleteMany(
@@ -64,7 +80,7 @@ export async function issueToken(
 	const token = randomBytes(32).toString('base64url')
 	const expiresAt = new Date(now + lifetimes[kind])
 	await PasswordToken.create(
-		{ data: { userId, kind, hash: hashOf(token), expiresAt } },
+		{ data: { userId, kind, hash: hashOf(token), expiresAt, email } },
 		M,
 	)
 	return token
@@ -73,11 +89,14 @@ export async function issueToken(
 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. */
+/**
+ * The user a token of `kind` was issued to, and the address it was sent to;
+ * a wrong, used or expired one fails.
+ */
 export async function redeemToken(
 	token: string,
 	kind: EmailKind,
-): Promise<string> {
+): Promise<{ readonly userId: string; readonly email: string | null }> {
 	const hash = hashOf(token)
 	const stored = await PasswordToken.findUnique({ where: { hash } }, M)
 	if (stored?.kind !== kind) throw invalidLink()
@@ -86,7 +105,7 @@ export async function redeemToken(
 	if (count === 0 || stored.expiresAt.getTime() <= Date.now()) {
 		throw invalidLink()
 	}
-	return stored.userId
+	return { userId: stored.userId, email: stored.email }
 }
 
 /**