@db3.ai/app 0.1.0-beta.1

package/dist/auth/AuthProvider.d.ts

@@ -0,0 +1,104 @@
+import { ActiveRecord, PasswordField, type FieldBuilder } from '../db/index.js';
+import type * as auth from './contracts/index.js';
+import { type PasswordHash } from './passwordHash.js';
+export declare 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 declare class AuthProvider extends ActiveRecord {
+    static table: string;
+    static primaryKey: string;
+    static comment: string;
+    /**
+     * Defines the provider link, credential, and display metadata columns.
+     *
+     * @param field - Framework field builder.
+     * @returns Field definitions for the auth provider table.
+     */
+    static fields(field: FieldBuilder): {
+        id: import("../db/index.js").UlidField;
+        userId: import("../db/index.js").StringField;
+        provider: import("../db/index.js").StringField;
+        providerUserId: import("../db/index.js").StringField;
+        label: import("../db/index.js").StringField;
+        email: import("../db/index.js").EmailField;
+        emailVerifiedAt: import("../db/index.js").TimestampField;
+        name: import("../db/index.js").StringField;
+        avatarUrl: import("../db/index.js").StringField;
+        password: PasswordField;
+        profile: import("../db/index.js").JsonStringField<Record<string, unknown>>;
+        lastLoginAt: import("../db/index.js").TimestampField;
+        createdAt: import("../db/index.js").TimestampField;
+        updatedAt: import("../db/index.js").TimestampField;
+    };
+    /**
+     * Applies normalized provider metadata to this row.
+     *
+     * @param profile - Provider profile returned by a driver.
+     */
+    applyProfile(profile: auth.AuthProviderProfile): void;
+    /**
+     * Marks this provider as used for authentication.
+     *
+     * @param date - Login time to store.
+     */
+    markUsed(date?: Date): void;
+    /**
+     * Returns true when this provider stores a local password credential.
+     *
+     * @returns Whether this row is the built-in password provider.
+     */
+    isPasswordProvider(): boolean;
+    /**
+     * 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.
+     */
+    toSummary(): AuthProviderSummary;
+    /**
+     * 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.
+     */
+    verifyPassword(plainText: string, passwordHash?: PasswordHash): Promise<boolean>;
+    id: string | null;
+    userId: string | null;
+    provider: string | null;
+    providerUserId: string | null;
+    label: string | null;
+    email: string | null;
+    emailVerifiedAt: Date | null;
+    name: string | null;
+    avatarUrl: string | null;
+    password: null;
+    profile: Record<string, unknown> | null;
+    lastLoginAt: Date | null;
+    createdAt: Date | null;
+    updatedAt: Date | null;
+}

package/dist/auth/AuthProvider.js

@@ -0,0 +1,185 @@
+import { ActiveRecord, PasswordField, } from '../db/index.js';
+import { defaultPasswordHash, } from './passwordHash.js';
+export const PASSWORD_AUTH_PROVIDER = 'password';
+/**
+ * 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 table = 'auth_providers';
+    static primaryKey = 'id';
+    static 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 fields(field) {
+        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({
+                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.
+     */
+    applyProfile(profile) {
+        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.
+     */
+    markUsed(date = new Date()) {
+        this.lastLoginAt = date;
+    }
+    /**
+     * Returns true when this provider stores a local password credential.
+     *
+     * @returns Whether this row is the built-in password provider.
+     */
+    isPasswordProvider() {
+        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.
+     */
+    toSummary() {
+        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.
+     */
+    verifyPassword(plainText, passwordHash = defaultPasswordHash) {
+        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);
+    }
+}
+/**
+ * Builds a compact default settings label for a provider profile.
+ *
+ * @param profile - Normalized provider profile.
+ * @returns Provider settings label.
+ */
+function providerLabel(profile) {
+    if (profile.provider === PASSWORD_AUTH_PROVIDER)
+        return 'Password';
+    if (profile.email)
+        return `${profile.provider}: ${profile.email}`;
+    return profile.provider;
+}

package/dist/auth/AuthToken.d.ts

@@ -0,0 +1,123 @@
+import { ActiveRecord, type FieldBuilder } from '../db/index.js';
+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 declare class AuthToken extends ActiveRecord {
+    static table: string;
+    static primaryKey: string;
+    static fields(field: FieldBuilder): {
+        id: import("../db/index.js").UlidField;
+        userId: import("../db/index.js").StringField;
+        tokenHash: import("../db/index.js").StringField;
+        name: import("../db/index.js").StringField;
+        ipAddress: import("../db/index.js").StringField;
+        userAgent: import("../db/index.js").TextField;
+        browser: import("../db/index.js").StringField;
+        operatingSystem: import("../db/index.js").StringField;
+        device: import("../db/index.js").StringField;
+        expiresAt: import("../db/index.js").TimestampField;
+        lastUsedAt: import("../db/index.js").TimestampField;
+        revokedAt: import("../db/index.js").TimestampField;
+        createdAt: import("../db/index.js").TimestampField;
+    };
+    id: string | null;
+    userId: string | null;
+    tokenHash: string | null;
+    name: string | null;
+    ipAddress: string | null;
+    userAgent: string | null;
+    browser: string | null;
+    operatingSystem: string | null;
+    device: string | null;
+    expiresAt: Date | null;
+    lastUsedAt: Date | null;
+    revokedAt: Date | null;
+    createdAt: Date | null;
+    /**
+     * Generates a cryptographically random bearer token.
+     *
+     * @returns Plaintext bearer token shown to the client once.
+     */
+    static generatePlainTextToken(): string;
+    /**
+     * Hashes a plaintext bearer token for persistent lookup.
+     *
+     * @param token - Plaintext bearer token.
+     * @returns SHA-256 token hash.
+     */
+    static hashToken(token: string): string;
+    /**
+     * Returns whether the token has passed its expiry time.
+     *
+     * @param date - Comparison time.
+     * @returns True when the session is expired.
+     */
+    isExpired(date?: Date): boolean;
+    /**
+     * Returns whether the session can currently authenticate.
+     *
+     * @param date - Comparison time.
+     * @returns True when the token is neither revoked nor expired.
+     */
+    isActive(date?: Date): boolean;
+    /**
+     * Records token activity and optional request metadata.
+     *
+     * @param date - Activity time.
+     * @param usage - Request metadata observed during authentication.
+     */
+    markUsed(date?: Date, usage?: AuthTokenUsage): void;
+    /**
+     * Permanently revokes this session.
+     *
+     * @param date - Revocation time.
+     */
+    revoke(date?: Date): void;
+    /**
+     * Returns safe session information without the token hash or raw user agent.
+     *
+     * @returns Session data for account-management APIs.
+     */
+    toSessionData(): AuthSessionData;
+}

package/dist/auth/AuthToken.js

@@ -0,0 +1,156 @@
+import { createHash, randomBytes, } from 'node:crypto';
+import { ActiveRecord, } from '../db/index.js';
+/**
+ * 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 table = 'auth_tokens';
+    static primaryKey = 'id';
+    static fields(field) {
+        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',
+            }),
+        };
+    }
+    /**
+     * Generates a cryptographically random bearer token.
+     *
+     * @returns Plaintext bearer token shown to the client once.
+     */
+    static generatePlainTextToken() {
+        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) {
+        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()) {
+        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()) {
+        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 = {}) {
+        this.lastUsedAt = date;
+        if (usage.ipAddress) {
+            this.ipAddress = usage.ipAddress;
+        }
+    }
+    /**
+     * Permanently revokes this session.
+     *
+     * @param date - Revocation time.
+     */
+    revoke(date = new Date()) {
+        this.revokedAt = date;
+    }
+    /**
+     * Returns safe session information without the token hash or raw user agent.
+     *
+     * @returns Session data for account-management APIs.
+     */
+    toSessionData() {
+        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/dist/auth/PasswordResetToken.d.ts

@@ -0,0 +1,33 @@
+import { ActiveRecord, type FieldBuilder } from '../db/index.js';
+/**
+ * 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 declare class PasswordResetToken extends ActiveRecord {
+    static table: string;
+    static primaryKey: string;
+    static fields(field: FieldBuilder): {
+        id: import("../db/index.js").UlidField;
+        userId: import("../db/index.js").StringField;
+        email: import("../db/index.js").EmailField;
+        tokenHash: import("../db/index.js").StringField;
+        expiresAt: import("../db/index.js").TimestampField;
+        usedAt: import("../db/index.js").TimestampField;
+        createdAt: import("../db/index.js").TimestampField;
+    };
+    id: string | null;
+    userId: string | null;
+    email: string | null;
+    tokenHash: string | null;
+    expiresAt: Date | null;
+    usedAt: Date | null;
+    createdAt: Date | null;
+    static generatePlainTextToken(): string;
+    static hashToken(token: string): string;
+    isExpired(date?: Date): boolean;
+    isUsed(): boolean;
+    isUsable(date?: Date): boolean;
+    markUsed(date?: Date): void;
+}

package/dist/auth/PasswordResetToken.js

@@ -0,0 +1,64 @@
+import { createHash, randomBytes, } from 'node:crypto';
+import { ActiveRecord, } from '../db/index.js';
+/**
+ * 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 table = 'password_reset_tokens';
+    static primaryKey = 'id';
+    static fields(field) {
+        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',
+            }),
+        };
+    }
+    static generatePlainTextToken() {
+        return randomBytes(32).toString('base64url');
+    }
+    static hashToken(token) {
+        return createHash('sha256').update(token).digest('hex');
+    }
+    isExpired(date = new Date()) {
+        return this.expiresAt !== null && this.expiresAt <= date;
+    }
+    isUsed() {
+        return this.usedAt !== null;
+    }
+    isUsable(date = new Date()) {
+        return !this.isUsed() && !this.isExpired(date);
+    }
+    markUsed(date = new Date()) {
+        this.usedAt = date;
+    }
+}