@db3.ai/app 0.1.0-beta.1

package/src/auth/providers/PasswordAuthProvider.ts

@@ -0,0 +1,256 @@
+import { AuthProvider, PASSWORD_AUTH_PROVIDER } from '../AuthProvider';
+import type * as auth from '../contracts';
+import type { PasswordCredentials } from '../Auth';
+import type { UserIdentity, UserIdentityModel } from '../UserIdentity';
+import { defaultPasswordHash, type PasswordHash } from '../passwordHash';
+
+/**
+ * Construction options for the password auth provider.
+ */
+export interface PasswordAuthProviderOptions<TIdentity extends UserIdentity = UserIdentity> {
+	/**
+	 * User identity model configured for the host app.
+	 */
+	identityModel: UserIdentityModel<TIdentity>;
+
+	/**
+	 * Provider-link model configured for the auth service.
+	 */
+	providerModel?: typeof AuthProvider;
+
+	/**
+	 * Password hashing service used to verify stored hashes.
+	 */
+	passwordHash?: PasswordHash;
+}
+
+/**
+ * Provider driver for first-party email and password authentication.
+ *
+ * The password provider is not OAuth, but it still satisfies the same provider
+ * contract by proving control of a provider-owned identity: the account email
+ * plus a valid password hash stored on `auth_providers`.
+ */
+export class PasswordAuthProvider<TIdentity extends UserIdentity = UserIdentity> implements auth.AuthProviderDriver<PasswordCredentials, TIdentity> {
+	readonly provider = PASSWORD_AUTH_PROVIDER;
+	private readonly IdentityModel: UserIdentityModel<TIdentity>;
+	private readonly ProviderModel: typeof AuthProvider;
+	private readonly passwordHash: PasswordHash;
+
+	/**
+	 * Creates a password auth provider.
+	 *
+	 * @param options - Password provider dependencies configured at app startup.
+	 */
+	constructor(options: PasswordAuthProviderOptions<TIdentity>) {
+		this.IdentityModel = options.identityModel;
+		this.ProviderModel = options.providerModel ?? AuthProvider;
+		this.passwordHash = options.passwordHash ?? defaultPasswordHash;
+	}
+
+	/**
+	 * Verifies submitted password credentials against the stored provider row.
+	 *
+	 * @param input - Submitted password credential payload.
+	 * @returns Normalized password provider profile, or null when verification fails.
+	 */
+	async verify(input: PasswordCredentials): Promise<auth.AuthProviderProfile | null> {
+		if (!isPasswordCredentials(input)) return null;
+
+		const identity = normalizeIdentity(input[this.IdentityModel.identityField]);
+
+		if (!identity) return null;
+
+		const provider = await this.findProvider(identity);
+
+		if (!provider) return null;
+		if (!await provider.verifyPassword(input.password, this.passwordHash)) return null;
+
+		return profileFromProvider(provider);
+	}
+
+	/**
+	 * Creates or replaces the password provider for a user.
+	 *
+	 * @param user - User who owns the password provider.
+	 * @param password - Plaintext password to hash and store.
+	 * @returns Saved password provider row.
+	 */
+	async setPassword(
+		user: TIdentity,
+		password: string,
+	): Promise<AuthProvider> {
+		const userId = this.userPrimaryKey(user);
+		const email = this.userIdentityValue(user);
+
+		if (!userId) {
+			throw new Error('Cannot set a password provider for a user without an ID.');
+		}
+
+		if (!email) {
+			throw new Error('Cannot set a password provider for a user without an identity email.');
+		}
+
+		const provider = await this.findUserProvider(userId)
+			?? new this.ProviderModel({});
+
+		provider.userId = userId;
+		provider.provider = this.provider;
+		provider.providerUserId = email;
+		provider.email = email;
+		provider.label = 'Password';
+		provider.set('password', password);
+
+		await provider.save();
+
+		return provider;
+	}
+
+	/**
+	 * Changes a user's password after verifying the current password.
+	 *
+	 * @param user - User whose password should change.
+	 * @param currentPassword - Current plaintext password.
+	 * @param nextPassword - Replacement plaintext password.
+	 * @returns True when the password provider was changed.
+	 */
+	async changePassword(
+		user: TIdentity,
+		currentPassword: string,
+		nextPassword: string,
+	): Promise<boolean> {
+		const userId = this.userPrimaryKey(user);
+
+		if (!userId) return false;
+
+		const provider = await this.findUserProvider(userId);
+
+		if (!provider || !await provider.verifyPassword(currentPassword, this.passwordHash)) {
+			return false;
+		}
+
+		provider.set('password', nextPassword);
+		await provider.save();
+
+		return true;
+	}
+
+	/**
+	 * Links the password provider to an existing user.
+	 *
+	 * @param user - User receiving the password provider.
+	 * @param input - Submitted password credential payload.
+	 * @returns Saved provider row, or null when no password was supplied.
+	 */
+	async link(
+		user: TIdentity,
+		input: unknown,
+	): Promise<AuthProvider | null> {
+		const password = isPasswordCredentials(input) ? input.password : '';
+
+		if (!password) return null;
+
+		return this.setPassword(user, password);
+	}
+
+	/**
+	 * Finds a password provider by normalized email identity.
+	 *
+	 * @param identity - Normalized email identity.
+	 * @returns Matching password provider row, or null.
+	 */
+	private async findProvider(identity: string): Promise<AuthProvider | null> {
+		return this.ProviderModel
+			.query()
+			.where('provider', this.provider)
+			.where('providerUserId', identity)
+			.first() as Promise<AuthProvider | null>;
+	}
+
+	/**
+	 * Finds the password provider linked to a user.
+	 *
+	 * @param userId - User primary key.
+	 * @returns Matching password provider row, or null.
+	 */
+	private async findUserProvider(userId: string): Promise<AuthProvider | null> {
+		return this.ProviderModel
+			.query()
+			.where('userId', userId)
+			.where('provider', this.provider)
+			.first() as Promise<AuthProvider | null>;
+	}
+
+	/**
+	 * Reads a user primary key as a non-empty string.
+	 *
+	 * @param user - User model to inspect.
+	 * @returns Primary key string, or null when missing.
+	 */
+	private userPrimaryKey(user: TIdentity): string | null {
+		const value = user.get(this.IdentityModel.primaryKey);
+
+		return value === null || value === undefined || value === ''
+			? null
+			: String(value);
+	}
+
+	/**
+	 * Reads the configured identity value from a user.
+	 *
+	 * @param user - User model to inspect.
+	 * @returns Normalized identity value, or null when missing.
+	 */
+	private userIdentityValue(user: TIdentity): string | null {
+		return normalizeIdentity(user.get(this.IdentityModel.identityField));
+	}
+}
+
+/**
+ * Checks whether a value can be used as password credentials.
+ *
+ * @param value - Unknown credential payload.
+ * @returns True when a password string is present.
+ */
+export function isPasswordCredentials(value: unknown): value is PasswordCredentials {
+	return typeof value === 'object'
+		&& value !== null
+		&& typeof (value as PasswordCredentials).password === 'string';
+}
+
+/**
+ * Normalizes an auth identity value for provider matching.
+ *
+ * @param value - Unknown identity value.
+ * @returns Lowercase trimmed identity string, or null.
+ */
+export function normalizeIdentity(value: unknown): string | null {
+	if (typeof value !== 'string') return null;
+
+	const normalized = value.trim().toLowerCase();
+
+	return normalized || null;
+}
+
+/**
+ * Builds a provider profile from a stored provider row.
+ *
+ * @param provider - Stored password provider row.
+ * @returns Normalized provider profile.
+ */
+function profileFromProvider(provider: AuthProvider): auth.AuthProviderProfile {
+	if (!provider.provider || !provider.providerUserId) {
+		throw new Error('Cannot build an auth provider profile from an incomplete provider row.');
+	}
+
+	return {
+		provider: provider.provider,
+		providerUserId: provider.providerUserId,
+		email: provider.email,
+		emailVerifiedAt: provider.emailVerifiedAt,
+		name: provider.name,
+		avatarUrl: provider.avatarUrl,
+		label: provider.label,
+		profile: provider.profile,
+	};
+}

package/src/auth/providers/index.ts

@@ -0,0 +1,3 @@
+export * from './GoogleAuthProvider';
+export * from './PasswordAuthProvider';
+export * from './resolveAuthProviders';

package/src/auth/providers/resolveAuthProviders.ts

@@ -0,0 +1,166 @@
+import { AuthProvider, PASSWORD_AUTH_PROVIDER } from '../AuthProvider';
+import type * as auth from '../contracts';
+import type { PasswordHash } from '../passwordHash';
+import type { UserIdentity, UserIdentityModel } from '../UserIdentity';
+import { GOOGLE_AUTH_PROVIDER, GoogleAuthProvider, type GoogleAuthProviderOptions } from './GoogleAuthProvider';
+import { PasswordAuthProvider } from './PasswordAuthProvider';
+
+/**
+ * Dependencies needed while constructing auth providers.
+ */
+export interface AuthProviderFactoryOptions<TIdentity extends UserIdentity = UserIdentity> {
+	/**
+	 * User identity model configured for the host app.
+	 */
+	identityModel: UserIdentityModel<TIdentity>;
+
+	/**
+	 * Provider-link model configured for the auth service.
+	 */
+	providerModel?: typeof AuthProvider;
+
+	/**
+	 * Password hashing service configured for the auth service.
+	 */
+	passwordHash: PasswordHash;
+}
+
+/**
+ * Builds provider driver instances from app auth provider config.
+ *
+ * @param providers - Provider registry from explicit auth options or app config.
+ * @param options - Construction dependencies shared by provider instances.
+ * @returns Enabled provider driver instances keyed by provider name.
+ */
+export function resolveAuthProviders<TIdentity extends UserIdentity>(
+	providers: auth.AuthProviderRegistry<TIdentity>,
+	options: AuthProviderFactoryOptions<TIdentity>,
+): Record<string, auth.AuthProviderDriver<unknown, TIdentity>> {
+	const registry: Record<string, auth.AuthProviderDriver<unknown, TIdentity>> = {};
+
+	for (const [provider, config] of Object.entries(providers)) {
+		const driver = resolveAuthProvider(provider, config, options);
+
+		if (driver) {
+			registry[provider] = driver;
+		}
+	}
+
+	return registry;
+}
+
+/**
+ * Builds one provider driver from its config entry.
+ *
+ * @param provider - Provider registry key.
+ * @param config - Provider config entry.
+ * @param factoryOptions - Construction dependencies shared by provider instances.
+ * @returns Provider driver, or null when disabled.
+ */
+function resolveAuthProvider<TIdentity extends UserIdentity>(
+	provider: string,
+	config: auth.AuthProviderConfig<TIdentity>,
+	factoryOptions: AuthProviderFactoryOptions<TIdentity>,
+): auth.AuthProviderDriver<unknown, TIdentity> | null {
+	if (config === false) return null;
+	if (isAuthProviderDriver<TIdentity>(config)) return config;
+
+	const options = config === true
+		? {}
+		: config;
+
+	if (options.enabled === false) return null;
+
+	const driver = typeof options.driver === 'string'
+		? options.driver
+		: provider;
+
+	switch (driver) {
+		case PASSWORD_AUTH_PROVIDER:
+			return new PasswordAuthProvider<TIdentity>({
+				identityModel: factoryOptions.identityModel,
+				providerModel: factoryOptions.providerModel,
+				passwordHash: factoryOptions.passwordHash,
+			}) as auth.AuthProviderDriver<unknown, TIdentity>;
+
+		case GOOGLE_AUTH_PROVIDER:
+			return new GoogleAuthProvider<TIdentity>(
+				googleOptionsFromConfig(options),
+			) as auth.AuthProviderDriver<unknown, TIdentity>;
+
+		default:
+			throw new Error(`Unknown auth provider driver "${driver}".`);
+	}
+}
+
+/**
+ * Checks whether a config entry is already a provider driver.
+ *
+ * @param value - Config value to inspect.
+ * @returns True when the value satisfies the provider driver contract.
+ */
+function isAuthProviderDriver<TIdentity extends UserIdentity>(
+	value: unknown,
+): value is auth.AuthProviderDriver<unknown, TIdentity> {
+	return typeof value === 'object'
+		&& value !== null
+		&& typeof (value as auth.AuthProviderDriver<unknown, TIdentity>).provider === 'string'
+		&& typeof (value as auth.AuthProviderDriver<unknown, TIdentity>).verify === 'function';
+}
+
+/**
+ * Converts generic config values into Google provider options.
+ *
+ * @param options - Generic provider config object.
+ * @returns Google provider options.
+ */
+function googleOptionsFromConfig(options: auth.AuthProviderOptions): GoogleAuthProviderOptions {
+	const {
+		driver: _driver,
+		enabled: _enabled,
+		clientId,
+		clientIds,
+		hostedDomain,
+		...rest
+	} = options;
+
+	return {
+		...rest,
+		clientId: stringOption(clientId),
+		clientIds: stringArrayOption(clientIds),
+		hostedDomain: stringOption(hostedDomain),
+	} as GoogleAuthProviderOptions;
+}
+
+/**
+ * Reads an optional string config value.
+ *
+ * @param value - Unknown config value.
+ * @returns String value, or undefined.
+ */
+function stringOption(value: unknown): string | undefined {
+	return typeof value === 'string' && value.trim()
+		? value.trim()
+		: undefined;
+}
+
+/**
+ * Reads an optional string array config value.
+ *
+ * @param value - Unknown config value.
+ * @returns String array value.
+ */
+function stringArrayOption(value: unknown): string[] | undefined {
+	if (typeof value === 'string') {
+		return value
+			.split(',')
+			.map(item => item.trim())
+			.filter(Boolean);
+	}
+
+	if (!Array.isArray(value)) return undefined;
+
+	return value
+		.map(item => stringOption(item))
+		.filter((item): item is string => Boolean(item));
+}

package/src/cache/Cache.ts

@@ -0,0 +1,151 @@
+import { createCacheDriver } from './drivers/createCacheDriver';
+import type * as cache from './contracts';
+
+/**
+ * Application cache service exposed through `app().cache`.
+ *
+ * The framework owns cache naming and lifecycle while Cache Manager currently
+ * supplies storage behavior through memory and Redis Keyv adapters.
+ *
+ * @example
+	 * const summary = await app().cache.getOrSet(`notes:v1:${ownerId}:summary`, async () => {
+	 * 	return { count: await Note.where('owner', ownerId).count() };
+ * }, {
+ * 	ttl: 60_000,
+ * });
+ */
+export class Cache implements cache.CacheDriver {
+	readonly #driver: cache.CacheDriver;
+	#closePromise: Promise<void> | null = null;
+
+	/**
+	 * Creates the configured cache service.
+	 *
+	 * @param options - Named cache-store configuration.
+	 * @param driver - Optional concrete driver used by focused tests or providers.
+	 */
+	constructor(
+		options: cache.CacheOptions = {},
+		driver?: cache.CacheDriver,
+	) {
+		this.#driver = driver ?? createCacheDriver(options);
+	}
+
+	/**
+	 * Retrieves a cached value.
+	 *
+	 * @param key - Stable application cache key.
+	 * @returns Cached value or undefined after a miss.
+	 */
+	async get<TValue>(key: string): Promise<TValue | undefined> {
+		return this.#driver.get<TValue>(cacheKey(key));
+	}
+
+	/**
+	 * Stores one defined cache value.
+	 *
+	 * @param key - Stable application cache key.
+	 * @param value - Defined value to retain.
+	 * @param options - Optional per-write TTL.
+	 * @returns The stored value.
+	 */
+	async set<TValue>(
+		key: string,
+		value: TValue,
+		options: cache.CacheSetOptions = {},
+	): Promise<TValue> {
+		return this.#driver.set(
+			cacheKey(key),
+			definedCacheValue(value, key),
+			options,
+		);
+	}
+
+	/**
+	 * Returns a cached value or computes and stores it after a miss.
+	 *
+	 * Cache Manager coalesces concurrent misses for the same key within this
+	 * process, so the factory runs once while other callers await its result.
+	 *
+	 * @param key - Stable application cache key.
+	 * @param factory - Value producer invoked after a cache miss.
+	 * @param options - TTL and optional background-refresh controls.
+	 * @returns Cached or newly resolved value.
+	 */
+	async getOrSet<TValue>(
+		key: string,
+		factory: cache.CacheValueFactory<TValue>,
+		options: cache.CacheGetOrSetOptions<TValue> = {},
+	): Promise<TValue> {
+		const normalizedKey = cacheKey(key);
+
+		return this.#driver.getOrSet(normalizedKey, async () => {
+			const value = await factory();
+
+			return definedCacheValue(value, normalizedKey);
+		}, options);
+	}
+
+	/**
+	 * Removes one cache key.
+	 *
+	 * @param key - Cache key to remove.
+	 * @returns True when the driver accepted the deletion.
+	 */
+	async forget(key: string): Promise<boolean> {
+		return this.#driver.forget(cacheKey(key));
+	}
+
+	/**
+	 * Removes every key owned by the configured store.
+	 */
+	async clear(): Promise<void> {
+		await this.#driver.clear();
+	}
+
+	/**
+	 * Releases resources held by the configured cache driver.
+	 */
+	async close(): Promise<void> {
+		this.#closePromise ??= this.#driver.close();
+		await this.#closePromise;
+	}
+}
+
+/**
+ * Validates and normalizes an application cache key.
+ *
+ * @param key - Candidate cache key.
+ * @returns Trimmed non-empty cache key.
+ */
+function cacheKey(key: string): string {
+	const normalized = key.trim();
+
+	if (!normalized) {
+		throw new Error('Cache keys must be non-empty strings.');
+	}
+
+	return normalized;
+}
+
+/**
+ * Rejects undefined because it represents a cache miss in Cache Manager.
+ *
+ * Null, false, zero, and empty strings remain valid cached values.
+ *
+ * @param value - Candidate cache value.
+ * @param key - Cache key used in the validation error.
+ * @returns Defined cache value.
+ */
+function definedCacheValue<TValue>(
+	value: TValue,
+	key: string,
+): Exclude<TValue, undefined> {
+	if (value === undefined) {
+		throw new TypeError(
+			`Cache value for "${key}" cannot be undefined because undefined represents a cache miss.`,
+		);
+	}
+
+	return value as Exclude<TValue, undefined>;
+}

package/src/cache/README.md

@@ -0,0 +1,137 @@
+# Cache
+
+`@db3.ai/app/cache` provides the application cache exposed through
+`app().cache`. The framework owns the public API, config resolution, validation, and
+shutdown lifecycle. Cache Manager currently supplies TTL storage and
+process-local request coalescing.
+
+## Run a note-summary cache
+
+From an independent application prepared using [Installation](https://db3.ai/docs/installation):
+
+```sh
+mkdir -p examples
+cp -R node_modules/@db3.ai/app/src/cache/examples/. examples/
+npx tsx examples/runNoteCache.ts
+```
+
+The real memory-store lab returns `firstLoads: 1` for two concurrent reads and `refreshed: { count: 2 }` after invalidation. A second owner keeps their own value. A failed factory is retried explicitly, an undefined value is rejected, and the isolated store is cleared and closed. No Redis, SQL or network is needed.
+
+Copy the exact test from the [Cache guide](https://db3.ai/docs/cache#testing) to `tests/cache/runNoteCache.test.ts`, then run:
+
+```sh
+npx vitest run tests/cache/runNoteCache.test.ts
+npx tsc --noEmit --target ES2022 --module ESNext --moduleResolution Bundler --types node --skipLibCheck examples/*.ts
+```
+
+Tests exercise the real store and control only the clock for deterministic expiry. The [complete API](https://db3.ai/docs/cache-api) covers service, driver, store and operation contracts.
+
+## Get Or Set
+
+Use `getOrSet(...)` when a value is expensive to compute:
+
+```ts
+const myValue = await app().cache.getOrSet('the_key', async () => {
+	const complexFunctionResult = await myComplexFunction();
+
+	return complexFunctionResult;
+}, {
+	ttl: 300_000,
+});
+```
+
+The factory runs only after a cache miss. Concurrent misses for the same key in
+one process share a single in-flight factory execution.
+
+Coalescing belongs to one cache instance, not a distributed lock. Authorize private data before using an owner-scoped key. Include operation, owner, arguments and a version in the key; the cache never enforces ownership itself. Invalidate affected keys after the source write commits. Do not cache live models or connections.
+
+TTL values are milliseconds. `refreshThreshold` can refresh an expiring entry
+in the background while returning its current value:
+
+```ts
+const website = await app().cache.getOrSet(
+	`website:${websiteId}`,
+	() => loadWebsite(websiteId),
+	{
+		ttl: 300_000,
+		refreshThreshold: 30_000,
+	},
+);
+```
+
+## Other Operations
+
+```ts
+await app().cache.set('feature:enabled', true, {
+	ttl: 60_000,
+});
+
+const enabled = await app().cache.get<boolean>('feature:enabled');
+
+await app().cache.forget('feature:enabled');
+await app().cache.clear();
+```
+
+`undefined` represents a cache miss and cannot be stored. `null`, `false`, zero,
+empty strings, arrays, and objects remain valid values. Prefer values that can
+be cloned and serialized consistently across memory and Redis stores.
+
+## Configuration
+
+Cache stores are configured under the application config:
+
+```ts
+const config = {
+	cache: {
+		default: 'memory',
+		stores: {
+			memory: {
+				driver: 'memory',
+				ttl: 300_000,
+				maxEntries: 1000,
+			},
+		},
+	},
+};
+```
+
+The memory driver uses CacheableMemory behind Cache Manager. It is process-local
+and bounded with least-recently-used eviction. Separate API, queue-worker, and
+scheduler processes do not share memory cache entries.
+
+Redis uses the official `@keyv/redis` adapter:
+
+```ts
+const config = {
+	cache: {
+		default: 'redis',
+		stores: {
+			redis: {
+				driver: 'redis',
+				url: 'redis://127.0.0.1:6379',
+				namespace: 'my-app:cache',
+				ttl: 300_000,
+				connectionTimeoutMs: 5000,
+				clearBatchSize: 1000,
+				throwOnConnectError: true,
+				throwOnErrors: true,
+			},
+		},
+	},
+};
+```
+
+Redis namespaces are mandatory. `clear()` scans and unlinks only keys inside
+that namespace; the framework never enables a broad Redis database flush.
+
+One configured store is selected; named stores do not mean tiering or automatic failover. The local walkthrough tests memory only. Redis delivery and failure handling need real infrastructure tests before release; a Redis configuration example is not proof of a successful connection.
+
+## Lifecycle And Boundaries
+
+`App.close()` disconnects the configured cache store. Applications should use
+the normal framework shutdown lifecycle so Redis connections close cleanly.
+
+Cache is an optimization, not durable storage. Do not rely on it as the only
+copy of application state. Cache Manager read misses and refresh behavior follow
+the selected Keyv store; write, clear, factory, and strict Redis failures reject
+their calling operation.