@db3.ai/app 0.1.0-beta.1

package/src/auth/AuthProvider.ts

@@ -0,0 +1,251 @@
+import {
+	ActiveRecord,
+	PasswordField,
+	type FieldBuilder,
+} from '../db';
+import type * as auth from './contracts';
+import {
+	defaultPasswordHash,
+	type PasswordHash,
+} from './passwordHash';
+
+export const PASSWORD_AUTH_PROVIDER = 'password';
+
+/** Safe provider metadata suitable for account-management screens. */
+export interface AuthProviderSummary {
+	/** Persistent provider-row identifier used for scoped removal. */
+	id: string;
+	/** Stable provider name such as password or google. */
+	provider: string;
+	/** Human-friendly provider label. */
+	label: string | null;
+	/** Email address reported or owned by the provider. */
+	email: string | null;
+	/** Avatar URL reported by the provider. */
+	avatarUrl: string | null;
+	/** Most recent successful login through this provider. */
+	lastLoginAt: string | null;
+	/** Time the provider was linked to the account. */
+	createdAt: string | null;
+}
+
+/**
+ * Persisted authentication method linked to one user account.
+ *
+ * Password, Google, magic-link, and future login mechanisms all share this
+ * model. Provider-specific verification happens in the auth service or a
+ * provider driver; this model owns the durable account-to-provider link.
+ */
+export class AuthProvider extends ActiveRecord {
+	static override table = 'auth_providers';
+	static override primaryKey = 'id';
+	static override comment = 'Authentication provider linked to a user account. Password credentials and external login identities share this table.';
+
+	/**
+	 * Defines the provider link, credential, and display metadata columns.
+	 *
+	 * @param field - Framework field builder.
+	 * @returns Field definitions for the auth provider table.
+	 */
+	static override fields(field: FieldBuilder) {
+		return {
+			id: field.ulid(),
+
+			userId: field.string({
+				column: 'user_id',
+				required: true,
+				maxLength: 255,
+				length: 255,
+				comment: 'User account this authentication provider belongs to.',
+				indexes: [
+					{
+						name: 'auth_providers_user_id_index',
+						columns: ['user_id'],
+					},
+					{
+						name: 'auth_providers_user_provider_unique',
+						columns: ['user_id', 'provider'],
+						unique: true,
+					},
+					{
+						name: 'auth_providers_provider_user_id_unique',
+						columns: ['provider', 'provider_user_id'],
+						unique: true,
+					},
+				],
+			}),
+
+			provider: field.string({
+				required: true,
+				maxLength: 64,
+				length: 64,
+				comment: 'Stable provider name such as password, google, or magic_link.',
+			}),
+
+			providerUserId: field.string({
+				column: 'provider_user_id',
+				required: true,
+				maxLength: 255,
+				length: 255,
+				comment: 'Stable provider-owned user id. For password this is the normalized email address.',
+			}),
+
+			label: field.string({
+				maxLength: 255,
+				length: 255,
+				comment: 'Human-friendly label for settings screens.',
+			}),
+
+			email: field.email({
+				maxLength: 255,
+				length: 255,
+				comment: 'Email address reported or proven by this provider.',
+			}),
+
+			emailVerifiedAt: field.timestamp({
+				column: 'email_verified_at',
+				comment: 'When this provider proved the linked email address.',
+			}),
+
+			name: field.string({
+				maxLength: 255,
+				length: 255,
+				comment: 'Display name reported by the provider.',
+			}),
+
+			avatarUrl: field.string({
+				column: 'avatar_url',
+				maxLength: 2048,
+				length: 2048,
+				comment: 'Avatar URL reported by the provider.',
+			}),
+
+			password: field.password({
+				required: false,
+				minLength: 12,
+				comment: 'Password hash for the built-in password provider. Null for external providers.',
+			}),
+
+			profile: field.jsonText<Record<string, unknown>>({
+				column: 'profile_json',
+				comment: 'Safe provider metadata captured during verification.',
+			}),
+
+			lastLoginAt: field.timestamp({
+				column: 'last_login_at',
+				comment: 'Last time this provider was used to authenticate.',
+			}),
+
+			createdAt: field.timestamp({
+				column: 'created_at',
+				auto: 'create',
+			}),
+
+			updatedAt: field.timestamp({
+				column: 'updated_at',
+				auto: 'update',
+			}),
+		};
+	}
+
+	/**
+	 * Applies normalized provider metadata to this row.
+	 *
+	 * @param profile - Provider profile returned by a driver.
+	 */
+	public applyProfile(profile: auth.AuthProviderProfile): void {
+		this.provider = profile.provider;
+		this.providerUserId = profile.providerUserId;
+		this.email = profile.email ?? null;
+		this.emailVerifiedAt = profile.emailVerifiedAt ?? null;
+		this.name = profile.name ?? null;
+		this.avatarUrl = profile.avatarUrl ?? null;
+		this.label = profile.label ?? providerLabel(profile);
+		this.profile = profile.profile ?? null;
+	}
+
+	/**
+	 * Marks this provider as used for authentication.
+	 *
+	 * @param date - Login time to store.
+	 */
+	public markUsed(date = new Date()): void {
+		this.lastLoginAt = date;
+	}
+
+	/**
+	 * Returns true when this provider stores a local password credential.
+	 *
+	 * @returns Whether this row is the built-in password provider.
+	 */
+	public isPasswordProvider(): boolean {
+		return this.provider === PASSWORD_AUTH_PROVIDER;
+	}
+
+	/**
+	 * Returns settings-safe provider metadata.
+	 *
+	 * Password hashes, provider-owned identifiers, and raw profile metadata are
+	 * deliberately excluded from this projection.
+	 *
+	 * @returns Provider summary for account-management APIs.
+	 */
+	public toSummary(): AuthProviderSummary {
+		return {
+			id: String(this.id),
+			provider: this.provider ?? '',
+			label: this.label,
+			email: this.email,
+			avatarUrl: this.avatarUrl,
+			lastLoginAt: this.lastLoginAt?.toISOString() ?? null,
+			createdAt: this.createdAt?.toISOString() ?? null,
+		};
+	}
+
+	/**
+	 * Verifies a plaintext password against the provider password hash.
+	 *
+	 * @param plainText - Password supplied by the user.
+	 * @param passwordHash - Password hashing service to use.
+	 * @returns True when the password matches this provider.
+	 */
+	public verifyPassword(
+		plainText: string,
+		passwordHash: PasswordHash = defaultPasswordHash,
+	): Promise<boolean> {
+		const passwordField = this.getBoundField('password');
+
+		if (!(passwordField instanceof PasswordField)) {
+			throw new Error('AuthProvider password field is not a password field.');
+		}
+
+		return passwordField.verifyPassword(plainText, passwordHash);
+	}
+
+	declare id: string | null;
+	declare userId: string | null;
+	declare provider: string | null;
+	declare providerUserId: string | null;
+	declare label: string | null;
+	declare email: string | null;
+	declare emailVerifiedAt: Date | null;
+	declare name: string | null;
+	declare avatarUrl: string | null;
+	declare password: null;
+	declare profile: Record<string, unknown> | null;
+	declare lastLoginAt: Date | null;
+	declare createdAt: Date | null;
+	declare updatedAt: Date | null;
+}
+
+/**
+ * Builds a compact default settings label for a provider profile.
+ *
+ * @param profile - Normalized provider profile.
+ * @returns Provider settings label.
+ */
+function providerLabel(profile: auth.AuthProviderProfile): string {
+	if (profile.provider === PASSWORD_AUTH_PROVIDER) return 'Password';
+	if (profile.email) return `${profile.provider}: ${profile.email}`;
+	return profile.provider;
+}

package/src/auth/AuthToken.ts

@@ -0,0 +1,239 @@
+import {
+	createHash,
+	randomBytes,
+} from 'node:crypto';
+
+import {
+	ActiveRecord,
+	type FieldBuilder,
+} from '../db';
+
+export interface CreateAuthTokenOptions {
+	/** Human-friendly session name displayed to the user. */
+	name?: string;
+	/** Absolute token expiry. Null creates a non-expiring token. */
+	expiresAt?: Date | null;
+	/** Latest client IP address observed for the session. */
+	ipAddress?: string | null;
+	/** Raw user-agent string captured when the session was created. */
+	userAgent?: string | null;
+	/** Parsed browser name, such as Chrome or Mobile Safari. */
+	browser?: string | null;
+	/** Parsed operating-system name, such as macOS or iOS. */
+	operatingSystem?: string | null;
+	/** Parsed device label, such as iPhone or Desktop. */
+	device?: string | null;
+}
+
+/**
+ * Request metadata refreshed when a bearer token is authenticated.
+ */
+export interface AuthTokenUsage {
+	/** Latest client IP address observed for the session. */
+	ipAddress?: string | null;
+}
+
+/**
+ * Safe session information suitable for account-management APIs.
+ */
+export interface AuthSessionData {
+	id: string;
+	name: string | null;
+	ipAddress: string | null;
+	browser: string | null;
+	operatingSystem: string | null;
+	device: string | null;
+	expiresAt: string | null;
+	lastUsedAt: string | null;
+	createdAt: string | null;
+}
+
+/**
+ * Persisted bearer token for API/mobile clients.
+ *
+ * The raw token is only returned to the client once. The database stores a
+ * SHA-256 hash so a token table leak does not expose immediately usable bearer
+ * tokens.
+ */
+export class AuthToken extends ActiveRecord {
+	static override table = 'auth_tokens';
+	static override primaryKey = 'id';
+
+	static override fields(field: FieldBuilder) {
+		return {
+			id: field.ulid(),
+
+			userId: field.string({
+				column: 'user_id',
+				required: true,
+				maxLength: 255,
+				length: 255,
+				indexes: [
+					{
+						name: 'auth_tokens_user_id_index',
+						columns: ['user_id'],
+					},
+				],
+			}),
+
+			tokenHash: field.string({
+				column: 'token_hash',
+				required: true,
+				unique: true,
+				maxLength: 64,
+				length: 64,
+				hidden: true,
+			}),
+
+			name: field.string({
+				maxLength: 120,
+				length: 120,
+			}),
+
+			ipAddress: field.string({
+				column: 'ip_address',
+				maxLength: 45,
+				length: 45,
+				comment: 'Latest client IP address observed while this session was active.',
+			}),
+
+			userAgent: field.text({
+				column: 'user_agent',
+				hidden: true,
+				comment: 'Raw client user-agent captured when this session was created.',
+			}),
+
+			browser: field.string({
+				maxLength: 64,
+				length: 64,
+				comment: 'Parsed browser name used for account session displays.',
+			}),
+
+			operatingSystem: field.string({
+				column: 'operating_system',
+				maxLength: 64,
+				length: 64,
+				comment: 'Parsed operating-system name used for account session displays.',
+			}),
+
+			device: field.string({
+				maxLength: 120,
+				length: 120,
+				comment: 'Parsed device model or category used for account session displays.',
+			}),
+
+			expiresAt: field.timestamp({
+				column: 'expires_at',
+			}),
+
+			lastUsedAt: field.timestamp({
+				column: 'last_used_at',
+			}),
+
+			revokedAt: field.timestamp({
+				column: 'revoked_at',
+				comment: 'When this bearer session was explicitly revoked.',
+			}),
+
+			createdAt: field.timestamp({
+				column: 'created_at',
+				auto: 'create',
+			}),
+		};
+	}
+
+	declare id: string | null;
+	declare userId: string | null;
+	declare tokenHash: string | null;
+	declare name: string | null;
+	declare ipAddress: string | null;
+	declare userAgent: string | null;
+	declare browser: string | null;
+	declare operatingSystem: string | null;
+	declare device: string | null;
+	declare expiresAt: Date | null;
+	declare lastUsedAt: Date | null;
+	declare revokedAt: Date | null;
+	declare createdAt: Date | null;
+
+	/**
+	 * Generates a cryptographically random bearer token.
+	 *
+	 * @returns Plaintext bearer token shown to the client once.
+	 */
+	static generatePlainTextToken(): string {
+		return randomBytes(32).toString('base64url');
+	}
+
+	/**
+	 * Hashes a plaintext bearer token for persistent lookup.
+	 *
+	 * @param token - Plaintext bearer token.
+	 * @returns SHA-256 token hash.
+	 */
+	static hashToken(token: string): string {
+		return createHash('sha256').update(token).digest('hex');
+	}
+
+	/**
+	 * Returns whether the token has passed its expiry time.
+	 *
+	 * @param date - Comparison time.
+	 * @returns True when the session is expired.
+	 */
+	isExpired(date = new Date()): boolean {
+		return this.expiresAt !== null && this.expiresAt <= date;
+	}
+
+	/**
+	 * Returns whether the session can currently authenticate.
+	 *
+	 * @param date - Comparison time.
+	 * @returns True when the token is neither revoked nor expired.
+	 */
+	isActive(date = new Date()): boolean {
+		return this.revokedAt === null && !this.isExpired(date);
+	}
+
+	/**
+	 * Records token activity and optional request metadata.
+	 *
+	 * @param date - Activity time.
+	 * @param usage - Request metadata observed during authentication.
+	 */
+	markUsed(date = new Date(), usage: AuthTokenUsage = {}): void {
+		this.lastUsedAt = date;
+
+		if (usage.ipAddress) {
+			this.ipAddress = usage.ipAddress;
+		}
+	}
+
+	/**
+	 * Permanently revokes this session.
+	 *
+	 * @param date - Revocation time.
+	 */
+	revoke(date = new Date()): void {
+		this.revokedAt = date;
+	}
+
+	/**
+	 * Returns safe session information without the token hash or raw user agent.
+	 *
+	 * @returns Session data for account-management APIs.
+	 */
+	toSessionData(): AuthSessionData {
+		return {
+			id: String(this.id),
+			name: this.name,
+			ipAddress: this.ipAddress,
+			browser: this.browser,
+			operatingSystem: this.operatingSystem,
+			device: this.device,
+			expiresAt: this.expiresAt?.toISOString() ?? null,
+			lastUsedAt: this.lastUsedAt?.toISOString() ?? null,
+			createdAt: this.createdAt?.toISOString() ?? null,
+		};
+	}
+}

package/src/auth/PasswordResetToken.ts

@@ -0,0 +1,93 @@
+import {
+	createHash,
+	randomBytes,
+} from 'node:crypto';
+
+import {
+	ActiveRecord,
+	type FieldBuilder,
+} from '../db';
+
+/**
+ * Single-use password reset token.
+ *
+ * The raw token is only sent in email. The database stores a SHA-256 hash so
+ * reset-token table leaks do not expose usable reset links.
+ */
+export class PasswordResetToken extends ActiveRecord {
+	static override table = 'password_reset_tokens';
+	static override primaryKey = 'id';
+
+	static override fields(field: FieldBuilder) {
+		return {
+			id: field.ulid(),
+
+			userId: field.string({
+				column: 'user_id',
+				required: true,
+				maxLength: 255,
+				length: 255,
+			}),
+
+			email: field.email({
+				required: true,
+				maxLength: 255,
+				length: 255,
+			}),
+
+			tokenHash: field.string({
+				column: 'token_hash',
+				required: true,
+				unique: true,
+				maxLength: 64,
+				length: 64,
+			}),
+
+			expiresAt: field.timestamp({
+				column: 'expires_at',
+				required: true,
+			}),
+
+			usedAt: field.timestamp({
+				column: 'used_at',
+			}),
+
+			createdAt: field.timestamp({
+				column: 'created_at',
+				auto: 'create',
+			}),
+		};
+	}
+
+	declare id: string | null;
+	declare userId: string | null;
+	declare email: string | null;
+	declare tokenHash: string | null;
+	declare expiresAt: Date | null;
+	declare usedAt: Date | null;
+	declare createdAt: Date | null;
+
+	static generatePlainTextToken(): string {
+		return randomBytes(32).toString('base64url');
+	}
+
+	static hashToken(token: string): string {
+		return createHash('sha256').update(token).digest('hex');
+	}
+
+	isExpired(date = new Date()): boolean {
+		return this.expiresAt !== null && this.expiresAt <= date;
+	}
+
+	isUsed(): boolean {
+		return this.usedAt !== null;
+	}
+
+	isUsable(date = new Date()): boolean {
+		return !this.isUsed() && !this.isExpired(date);
+	}
+
+	markUsed(date = new Date()): void {
+		this.usedAt = date;
+	}
+}