@db3.ai/app 0.1.0-beta.1

package/dist/auth/providers/GoogleAuthProvider.js

@@ -0,0 +1,305 @@
+import { createPublicKey, createVerify, } from 'node:crypto';
+export const GOOGLE_AUTH_PROVIDER = 'google';
+const GOOGLE_JWKS_URL = 'https://www.googleapis.com/oauth2/v3/certs';
+const GOOGLE_ISSUERS = new Set([
+    'accounts.google.com',
+    'https://accounts.google.com',
+]);
+/**
+ * Provider driver for Google Sign-In ID tokens.
+ *
+ * This provider verifies a Google-signed ID token and translates the verified
+ * claims into the framework's normalized provider profile. It intentionally
+ * does not store OAuth access or refresh tokens.
+ */
+export class GoogleAuthProvider {
+    provider = GOOGLE_AUTH_PROVIDER;
+    clientIds;
+    hostedDomain;
+    jwksUrl;
+    fetcher;
+    staticJwks;
+    clockSkewSeconds;
+    now;
+    jwksCache = null;
+    /**
+     * Creates a Google auth provider.
+     *
+     * @param options - Google provider verification options.
+     */
+    constructor(options = {}) {
+        this.clientIds = normalizeStringArray([
+            ...(options.clientIds ?? []),
+            options.clientId,
+        ]);
+        this.hostedDomain = normalizeOptionalString(options.hostedDomain);
+        this.jwksUrl = options.jwksUrl ?? GOOGLE_JWKS_URL;
+        this.fetcher = options.fetch ?? fetch;
+        this.staticJwks = options.jwks ?? null;
+        this.clockSkewSeconds = options.clockSkewSeconds ?? 60;
+        this.now = options.now ?? (() => new Date());
+    }
+    /**
+     * Verifies a Google ID token and returns the normalized provider profile.
+     *
+     * @param input - Google credential payload.
+     * @returns Normalized Google provider profile, or null when verification fails.
+     */
+    async verify(input) {
+        if (!isGoogleAuthProviderInput(input))
+            return null;
+        if (!this.csrfTokensMatch(input))
+            return null;
+        const idToken = input.credential ?? input.idToken;
+        if (!idToken)
+            return null;
+        const verified = await this.verifyIdToken(idToken);
+        if (!verified)
+            return null;
+        const email = normalizeOptionalString(verified.payload.email);
+        const emailVerified = verified.payload.email_verified === true || verified.payload.email_verified === 'true';
+        const hostedDomain = normalizeOptionalString(verified.payload.hd);
+        const issuedAt = typeof verified.payload.iat === 'number'
+            ? new Date(verified.payload.iat * 1000)
+            : new Date(this.nowMs());
+        return {
+            provider: this.provider,
+            providerUserId: verified.payload.sub,
+            email,
+            emailVerifiedAt: googleIsAuthoritativeForEmail(email, emailVerified, hostedDomain)
+                ? issuedAt
+                : null,
+            name: normalizeOptionalString(verified.payload.name),
+            avatarUrl: normalizeOptionalString(verified.payload.picture),
+            label: email ? `Google: ${email}` : 'Google',
+            profile: {
+                emailVerified,
+                hostedDomain,
+                givenName: normalizeOptionalString(verified.payload.given_name),
+                familyName: normalizeOptionalString(verified.payload.family_name),
+                locale: normalizeOptionalString(verified.payload.locale),
+            },
+        };
+    }
+    /**
+     * Checks whether supplied CSRF values match when either value is present.
+     *
+     * @param input - Google credential payload.
+     * @returns True when CSRF values are absent or exactly match.
+     */
+    csrfTokensMatch(input) {
+        const bodyToken = input.g_csrf_token ?? input.csrfToken;
+        const cookieToken = input.csrfCookie;
+        if (!bodyToken && !cookieToken)
+            return true;
+        return Boolean(bodyToken && cookieToken && bodyToken === cookieToken);
+    }
+    /**
+     * Verifies a compact JWT from Google.
+     *
+     * @param idToken - Compact Google ID token.
+     * @returns Verified header and payload, or null when invalid.
+     */
+    async verifyIdToken(idToken) {
+        if (this.clientIds.length === 0) {
+            throw new Error('Google auth provider requires at least one configured client id.');
+        }
+        const parts = idToken.split('.');
+        if (parts.length !== 3)
+            return null;
+        const [encodedHeader, encodedPayload, encodedSignature] = parts;
+        const header = decodeJwtPart(encodedHeader);
+        const payload = decodeJwtPart(encodedPayload);
+        if (!header || !payload)
+            return null;
+        if (header.alg !== 'RS256')
+            return null;
+        if (typeof header.kid !== 'string' || !header.kid)
+            return null;
+        if (!this.claimsAreValid(payload))
+            return null;
+        const keys = await this.jwks();
+        const key = keys.find(candidate => candidate.kid === header.kid);
+        if (!key)
+            return null;
+        const verified = verifyJwtSignature(`${encodedHeader}.${encodedPayload}`, encodedSignature, key);
+        if (!verified)
+            return null;
+        return {
+            header,
+            payload: payload,
+        };
+    }
+    /**
+     * Validates the required Google ID-token claims.
+     *
+     * @param payload - Decoded JWT payload.
+     * @returns True when required claims are acceptable.
+     */
+    claimsAreValid(payload) {
+        if (typeof payload.sub !== 'string' || !payload.sub)
+            return false;
+        if (typeof payload.iss !== 'string' || !GOOGLE_ISSUERS.has(payload.iss))
+            return false;
+        if (!audienceMatches(payload.aud, this.clientIds))
+            return false;
+        if (typeof payload.exp !== 'number')
+            return false;
+        if (payload.exp + this.clockSkewSeconds < Math.floor(this.nowMs() / 1000))
+            return false;
+        const hostedDomain = normalizeOptionalString(payload.hd);
+        if (this.hostedDomain && hostedDomain !== this.hostedDomain) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Returns Google JWKs, using cache-control when keys are fetched remotely.
+     *
+     * @returns Google signing keys.
+     */
+    async jwks() {
+        if (this.staticJwks)
+            return this.staticJwks;
+        const now = this.nowMs();
+        if (this.jwksCache && this.jwksCache.expiresAt > now) {
+            return this.jwksCache.keys;
+        }
+        const response = await this.fetcher(this.jwksUrl);
+        if (!response.ok) {
+            throw new Error(`Unable to fetch Google JWKs: ${response.status} ${response.statusText}`);
+        }
+        const body = await response.json();
+        const keys = Array.isArray(body.keys) ? body.keys : [];
+        const maxAgeSeconds = cacheControlMaxAge(response.headers.get('cache-control')) ?? 3600;
+        this.jwksCache = {
+            expiresAt: now + maxAgeSeconds * 1000,
+            keys,
+        };
+        return keys;
+    }
+    /**
+     * Returns the current time in milliseconds.
+     *
+     * @returns Current epoch milliseconds.
+     */
+    nowMs() {
+        const value = this.now();
+        return value instanceof Date ? value.getTime() : value;
+    }
+}
+/**
+ * Checks whether a value looks like Google provider input.
+ *
+ * @param value - Unknown input value.
+ * @returns True when the value can be inspected as provider input.
+ */
+function isGoogleAuthProviderInput(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * Decodes a base64url-encoded JWT part as JSON.
+ *
+ * @param part - Encoded JWT header or payload.
+ * @returns Parsed JSON object, or null when invalid.
+ */
+function decodeJwtPart(part) {
+    try {
+        const json = Buffer.from(part, 'base64url').toString('utf8');
+        const parsed = JSON.parse(json);
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Verifies an RS256 JWT signature against a JWK.
+ *
+ * @param signingInput - Encoded JWT header and payload.
+ * @param encodedSignature - Base64url-encoded signature.
+ * @param key - JWK selected by JWT key id.
+ * @returns True when the signature is valid.
+ */
+function verifyJwtSignature(signingInput, encodedSignature, key) {
+    try {
+        const verifier = createVerify('RSA-SHA256');
+        verifier.update(signingInput);
+        verifier.end();
+        return verifier.verify(createPublicKey({
+            key,
+            format: 'jwk',
+        }), Buffer.from(encodedSignature, 'base64url'));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Checks whether a token audience matches one of the configured client ids.
+ *
+ * @param audience - JWT audience claim.
+ * @param clientIds - Accepted client ids.
+ * @returns True when one audience is accepted.
+ */
+function audienceMatches(audience, clientIds) {
+    if (typeof audience === 'string')
+        return clientIds.includes(audience);
+    if (Array.isArray(audience))
+        return audience.some(value => {
+            return typeof value === 'string' && clientIds.includes(value);
+        });
+    return false;
+}
+/**
+ * Parses a cache-control max-age value.
+ *
+ * @param header - Cache-Control header value.
+ * @returns Max age in seconds, or null when absent.
+ */
+function cacheControlMaxAge(header) {
+    if (!header)
+        return null;
+    const match = header.match(/(?:^|,)\s*max-age=(\d+)\s*(?:,|$)/i);
+    return match ? Number(match[1]) : null;
+}
+/**
+ * Normalizes a list of optional strings.
+ *
+ * @param values - String values to normalize.
+ * @returns Trimmed non-empty strings.
+ */
+function normalizeStringArray(values) {
+    return values
+        .map(value => normalizeOptionalString(value))
+        .filter((value) => Boolean(value));
+}
+/**
+ * Normalizes an optional string.
+ *
+ * @param value - Unknown string value.
+ * @returns Trimmed string, or null when absent.
+ */
+function normalizeOptionalString(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.trim();
+    return normalized || null;
+}
+/**
+ * Determines whether Google is authoritative for an email claim.
+ *
+ * @param email - Email claim.
+ * @param emailVerified - Google email_verified claim.
+ * @param hostedDomain - Google hosted domain claim.
+ * @returns True when Google can be treated as current email owner.
+ */
+function googleIsAuthoritativeForEmail(email, emailVerified, hostedDomain) {
+    if (!emailVerified || !email)
+        return false;
+    if (email.toLowerCase().endsWith('@gmail.com'))
+        return true;
+    return Boolean(hostedDomain);
+}

package/dist/auth/providers/PasswordAuthProvider.d.ts

@@ -0,0 +1,115 @@
+import { AuthProvider } from '../AuthProvider.js';
+import type * as auth from '../contracts/index.js';
+import type { PasswordCredentials } from '../Auth.js';
+import type { UserIdentity, UserIdentityModel } from '../UserIdentity.js';
+import { type PasswordHash } from '../passwordHash.js';
+/**
+ * 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 declare class PasswordAuthProvider<TIdentity extends UserIdentity = UserIdentity> implements auth.AuthProviderDriver<PasswordCredentials, TIdentity> {
+    readonly provider = "password";
+    private readonly IdentityModel;
+    private readonly ProviderModel;
+    private readonly passwordHash;
+    /**
+     * Creates a password auth provider.
+     *
+     * @param options - Password provider dependencies configured at app startup.
+     */
+    constructor(options: PasswordAuthProviderOptions<TIdentity>);
+    /**
+     * 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.
+     */
+    verify(input: PasswordCredentials): Promise<auth.AuthProviderProfile | null>;
+    /**
+     * 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.
+     */
+    setPassword(user: TIdentity, password: string): Promise<AuthProvider>;
+    /**
+     * 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.
+     */
+    changePassword(user: TIdentity, currentPassword: string, nextPassword: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    link(user: TIdentity, input: unknown): Promise<AuthProvider | null>;
+    /**
+     * Finds a password provider by normalized email identity.
+     *
+     * @param identity - Normalized email identity.
+     * @returns Matching password provider row, or null.
+     */
+    private findProvider;
+    /**
+     * Finds the password provider linked to a user.
+     *
+     * @param userId - User primary key.
+     * @returns Matching password provider row, or null.
+     */
+    private findUserProvider;
+    /**
+     * 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;
+    /**
+     * Reads the configured identity value from a user.
+     *
+     * @param user - User model to inspect.
+     * @returns Normalized identity value, or null when missing.
+     */
+    private userIdentityValue;
+}
+/**
+ * Checks whether a value can be used as password credentials.
+ *
+ * @param value - Unknown credential payload.
+ * @returns True when a password string is present.
+ */
+export declare function isPasswordCredentials(value: unknown): value is PasswordCredentials;
+/**
+ * Normalizes an auth identity value for provider matching.
+ *
+ * @param value - Unknown identity value.
+ * @returns Lowercase trimmed identity string, or null.
+ */
+export declare function normalizeIdentity(value: unknown): string | null;

package/dist/auth/providers/PasswordAuthProvider.js

@@ -0,0 +1,195 @@
+import { AuthProvider, PASSWORD_AUTH_PROVIDER } from '../AuthProvider.js';
+import { defaultPasswordHash } from '../passwordHash.js';
+/**
+ * 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 {
+    provider = PASSWORD_AUTH_PROVIDER;
+    IdentityModel;
+    ProviderModel;
+    passwordHash;
+    /**
+     * Creates a password auth provider.
+     *
+     * @param options - Password provider dependencies configured at app startup.
+     */
+    constructor(options) {
+        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) {
+        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, password) {
+        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, currentPassword, nextPassword) {
+        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, input) {
+        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.
+     */
+    async findProvider(identity) {
+        return this.ProviderModel
+            .query()
+            .where('provider', this.provider)
+            .where('providerUserId', identity)
+            .first();
+    }
+    /**
+     * Finds the password provider linked to a user.
+     *
+     * @param userId - User primary key.
+     * @returns Matching password provider row, or null.
+     */
+    async findUserProvider(userId) {
+        return this.ProviderModel
+            .query()
+            .where('userId', userId)
+            .where('provider', this.provider)
+            .first();
+    }
+    /**
+     * Reads a user primary key as a non-empty string.
+     *
+     * @param user - User model to inspect.
+     * @returns Primary key string, or null when missing.
+     */
+    userPrimaryKey(user) {
+        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.
+     */
+    userIdentityValue(user) {
+        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) {
+    return typeof value === 'object'
+        && value !== null
+        && typeof value.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) {
+    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) {
+    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/dist/auth/providers/index.d.ts

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

package/dist/auth/providers/index.js

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

package/dist/auth/providers/resolveAuthProviders.d.ts

@@ -0,0 +1,29 @@
+import { AuthProvider } from '../AuthProvider.js';
+import type * as auth from '../contracts/index.js';
+import type { PasswordHash } from '../passwordHash.js';
+import type { UserIdentity, UserIdentityModel } from '../UserIdentity.js';
+/**
+ * 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 declare function resolveAuthProviders<TIdentity extends UserIdentity>(providers: auth.AuthProviderRegistry<TIdentity>, options: AuthProviderFactoryOptions<TIdentity>): Record<string, auth.AuthProviderDriver<unknown, TIdentity>>;