@iskra-bun/auth-kit 0.1.0 → 0.2.0

package/src/better-auth-config.ts

@@ -1,10 +1,11 @@
-import { betterAuth, type Auth as BetterAuthInstance } from "better-auth";
-import { drizzleAdapter, type DB as DrizzleAdapterDb } from "better-auth/adapters/drizzle";
-import { genericOAuth } from "better-auth/plugins/generic-oauth";
-import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
-import type { MySqlDatabase, MySqlQueryResultHKT, PreparedQueryHKTBase } from "drizzle-orm/mysql-core";
-import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";
-import { pgSchema, mysqlSchema, sqliteSchema } from "./schema";
+import { betterAuth, type Auth as BetterAuthInstance, type BetterAuthOptions } from 'better-auth';
+import { drizzleAdapter, type DB as DrizzleAdapterDb } from 'better-auth/adapters/drizzle';
+import { genericOAuth, type GenericOAuthUserInfo } from 'better-auth/plugins/generic-oauth';
+import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
+import type { MySqlDatabase, MySqlQueryResultHKT, PreparedQueryHKTBase } from 'drizzle-orm/mysql-core';
+import type { BaseSQLiteDatabase } from 'drizzle-orm/sqlite-core';
+import { pgSchema, mysqlSchema, sqliteSchema } from './schema';
+import { isProductionEnv } from '@iskra-bun/core';
 
 /**
  * The Drizzle database handle auth-kit accepts. A union of the supported dialect
@@ -15,19 +16,85 @@ import { pgSchema, mysqlSchema, sqliteSchema } from "./schema";
 export type AuthKitDrizzleDb =
     | PgDatabase<PgQueryResultHKT, Record<string, unknown>>
     | MySqlDatabase<MySqlQueryResultHKT, PreparedQueryHKTBase, Record<string, unknown>>
-    | BaseSQLiteDatabase<"sync" | "async", unknown, Record<string, unknown>>;
+    | BaseSQLiteDatabase<'sync' | 'async', unknown, Record<string, unknown>>;
 
 /** Minimum length, in characters, for the session-signing secret. */
 const MIN_SECRET_LENGTH = 32;
 
+/**
+ * Pieces of the sample secrets docs and `.env.example` files ship. Compared
+ * without case, `-`, `_`, `.` or spaces, so `change-me` also matches
+ * `changeme` and `CHANGE_ME`.
+ */
+const PLACEHOLDER_SECRET_MARKERS = ['change-me', 'dev-secret', 'dev-only', 'your-secret', 'placeholder'];
+
+const normalizeSecret = (value: string) => value.toLowerCase().replace(/[-_.\s]/g, '');
+
+/** The placeholder marker `secret` contains, if any. */
+function placeholderMarker(secret: string): string | undefined {
+    const normalized = normalizeSecret(secret);
+    return PLACEHOLDER_SECRET_MARKERS.find((marker) => normalized.includes(normalizeSecret(marker)));
+}
+
+/** Hosts a production baseURL may reach over plain http (e.g. docker compose on one machine). */
+const LOCAL_HOSTNAMES = new Set(['localhost', '127.0.0.1', '[::1]']);
+
+/**
+ * The origin better-auth runs on: `baseURL`, else `BETTER_AUTH_URL`, else
+ * `http://localhost:3000` outside production. It decides the cookies'
+ * `Secure` flag and is a trusted origin, so production requires one and it
+ * must be https (plain http only for localhost, 127.0.0.1 and [::1]). `who`
+ * prefixes the error messages.
+ */
+export function resolveAuthBaseURL(baseURL?: string, who = 'createBetterAuth'): string {
+    const resolved = baseURL || process.env.BETTER_AUTH_URL;
+    if (resolved) {
+        assertHttpsInProduction(resolved, who);
+        return resolved;
+    }
+    if (isProductionEnv()) {
+        throw new Error(
+            `${who}: set baseURL (or BETTER_AUTH_URL) to the app's public origin in production, ` +
+                'e.g. "https://app.example.com"; without it cookies are sent without Secure.',
+        );
+    }
+    return 'http://localhost:3000';
+}
+
+/**
+ * better-auth marks the session cookies Secure only for an https baseURL, so
+ * an http:// one in production sent them over plain HTTP as well.
+ */
+function assertHttpsInProduction(baseURL: string, who: string): void {
+    if (!isProductionEnv()) return;
+    let url: URL;
+    try {
+        url = new URL(baseURL);
+    } catch {
+        return; // an invalid URL is reported by the caller
+    }
+    if (url.protocol === 'https:' || LOCAL_HOSTNAMES.has(url.hostname)) return;
+    throw new Error(
+        `${who}: baseURL "${baseURL}" must use https in production: better-auth marks the session cookies ` +
+            'Secure only for an https baseURL. Plain http is allowed only for localhost, 127.0.0.1 and [::1].',
+    );
+}
+
 export interface BetterAuthConfigOptions {
     db: AuthKitDrizzleDb;
-    adapterType: "postgres" | "mysql" | "sqlite";
+    adapterType: 'postgres' | 'mysql' | 'sqlite';
     secret: string;
+    /**
+     * The app's public origin. Defaults to `BETTER_AUTH_URL`, then (outside
+     * production only) `http://localhost:3000`; must be https in production
+     * unless it is localhost. See `resolveAuthBaseURL`.
+     */
     baseURL?: string;
     basePath?: string;
     trustedOrigins?: string[];
     enableEmailPassword?: boolean;
+    /** Reject `/sign-up/email` (accounts are provisioned another way). Default false. */
+    disableSignUp?: boolean;
     disableCSRFCheck?: boolean;
     /**
      * Cookie-cache lifetime in seconds. This is the session-revocation lag: a
@@ -36,8 +103,19 @@ export interface BetterAuthConfigOptions {
      * frequent DB lookups). Defaults to 300 (5 minutes).
      */
     cookieCacheMaxAge?: number;
-    // deno-lint-ignore no-explicit-any
-    socialProviders?: Record<string, any>;
+    /**
+     * `false` turns off better-auth's own rate limiter (on by default in
+     * production), e.g. when the app limits the auth routes itself.
+     */
+    rateLimit?: false;
+    /**
+     * Request headers better-auth reads the client IP from, for its rate
+     * limiter and the sessions' `ipAddress` (default `x-forwarded-for`, first
+     * entry). Without a usable one, every client shares one rate-limit bucket.
+     */
+    ipAddressHeaders?: string[];
+    /** better-auth's socialProviders option, as is. */
+    socialProviders?: BetterAuthOptions['socialProviders'];
     oidcConfig?: {
         clientId: string;
         clientSecret: string;
@@ -46,18 +124,91 @@ export interface BetterAuthConfigOptions {
         authorizationEndpoint?: string;
         tokenEndpoint?: string;
         userinfoEndpoint?: string;
+        /**
+         * @deprecated Ignored: better-auth takes the JWKS only from the
+         * discovery document's `jwks_uri`; point `discoveryEndpoint` at a
+         * document that has the right one instead.
+         */
         jwksEndpoint?: string;
         discoveryEndpoint?: string;
         scopes?: string[];
         pkce?: boolean;
-        mapping?: {
-            id?: string;
-            email?: string;
-            emailVerified?: string;
-            name?: string;
-            image?: string;
-            extraFields?: Record<string, string>;
-        };
+        /** Claim names to read the user's fields from, instead of the standard ones. */
+        mapping?: OidcClaimMapping;
+    };
+}
+
+/** Claim names `mapOidcProfile` reads the user's fields from. */
+export interface OidcClaimMapping {
+    /**
+     * @deprecated Ignored: better-auth always takes the account's identity
+     * from the verified `sub` claim.
+     */
+    id?: string;
+    email?: string;
+    /** The claim is read as verified when it is `true` or `"true"`. */
+    emailVerified?: string;
+    name?: string;
+    image?: string;
+    /**
+     * @deprecated Ignored: extra user fields need better-auth
+     * `user.additionalFields`, which `createBetterAuth` does not declare.
+     */
+    extraFields?: Record<string, string>;
+}
+
+/**
+ * The local user fields for an OIDC login (standard claims, with the common
+ * non-standard fallbacks). A claim named in `mapping` is read instead of the
+ * standard one when the profile has it. No `id`: better-auth takes the
+ * account's identity from the verified `sub` (accountSubject) and ignores one
+ * returned here.
+ */
+export function mapOidcProfile(profile: GenericOAuthUserInfo, mapping: OidcClaimMapping = {}) {
+    const str = (v: unknown) => (typeof v === 'string' && v !== '' ? v : undefined);
+    const claim = (name: string | undefined) => (name ? profile[name] : undefined);
+    const isTrue = (v: unknown) => v === true || v === 'true';
+    const standardVerified = profile.emailVerified === true || isTrue(profile.email_verified);
+    const mappedEmail = str(claim(mapping.email));
+    // better-auth links a login to the local user with the same email when it
+    // is verified, so a flag must vouch for the address actually returned.
+    // A mapped flag pairs with the mapped email (or with the standard one when
+    // mapping.email is not set); the standard flag only vouches for the
+    // standard email.
+    const pairedFlag = mappedEmail !== undefined || !mapping.email ? claim(mapping.emailVerified) : undefined;
+    let emailVerified: boolean;
+    if (pairedFlag !== undefined && pairedFlag !== null) emailVerified = isTrue(pairedFlag);
+    else if (mappedEmail !== undefined) emailVerified = mappedEmail === profile.email && standardVerified;
+    else emailVerified = standardVerified;
+    return {
+        email: mappedEmail ?? profile.email,
+        name: str(claim(mapping.name)) ?? (profile.name || str(profile.preferred_username)),
+        image: str(claim(mapping.image)) ?? str(profile.picture) ?? profile.image,
+        emailVerified,
+    };
+}
+
+/**
+ * The generic-oauth provider config for `oidcConfig`. The endpoints left
+ * unset come from the issuer's discovery document: better-auth fills only
+ * the ones not given, so a default here (e.g. Keycloak's
+ * `/protocol/openid-connect/*` paths) would override discovery for every
+ * other provider.
+ */
+export function oidcProviderConfig(oidcConfig: NonNullable<BetterAuthConfigOptions['oidcConfig']>) {
+    return {
+        providerId: oidcConfig.providerId || 'oidc',
+        clientId: oidcConfig.clientId,
+        clientSecret: oidcConfig.clientSecret,
+        authorizationUrl: oidcConfig.authorizationEndpoint || undefined,
+        tokenUrl: oidcConfig.tokenEndpoint || undefined,
+        userInfoUrl: oidcConfig.userinfoEndpoint || undefined,
+        discoveryUrl: oidcConfig.discoveryEndpoint || `${oidcConfig.issuer}/.well-known/openid-configuration`,
+        scopes: oidcConfig.scopes || ['openid', 'email', 'profile'],
+        // Secure default: PKCE on. Disabling exposes auth-code
+        // interception/injection and requires an explicit false.
+        pkce: oidcConfig.pkce !== undefined ? oidcConfig.pkce : true,
+        mapProfileToUser: (profile: GenericOAuthUserInfo) => mapOidcProfile(profile, oidcConfig.mapping),
     };
 }
 
@@ -66,14 +217,16 @@ export function createBetterAuth(options: BetterAuthConfigOptions): BetterAuthIn
         db,
         adapterType,
         secret,
-        baseURL = "http://localhost:3000",
-        basePath = "/api/auth",
+        basePath = '/api/auth',
         trustedOrigins = [],
         enableEmailPassword = true,
+        disableSignUp = false,
         disableCSRFCheck = false,
         cookieCacheMaxAge = 5 * 60,
         socialProviders,
         oidcConfig,
+        rateLimit,
+        ipAddressHeaders,
     } = options;
 
     // A weak or empty secret signs forgeable sessions, so reject it before
@@ -83,27 +236,36 @@ export function createBetterAuth(options: BetterAuthConfigOptions): BetterAuthIn
             `auth secret must be at least ${MIN_SECRET_LENGTH} characters; received ${secret ? secret.length : 0}`,
         );
     }
+    // A sample secret left in production is public: with it anyone can sign
+    // the session cookie cache, which is trusted without a database lookup,
+    // and so forge a session for any user.
+    const marker = isProductionEnv() ? placeholderMarker(secret) : undefined;
+    if (marker) {
+        throw new Error(
+            `auth secret looks like a placeholder (it contains "${marker}"); in production set a random secret ` +
+                `of at least ${MIN_SECRET_LENGTH} characters, e.g. from \`openssl rand -base64 32\``,
+        );
+    }
 
+    const baseURL = resolveAuthBaseURL(options.baseURL);
     const baseOrigin = new URL(baseURL).origin;
-    const allTrustedOrigins = trustedOrigins.includes(baseOrigin)
-        ? trustedOrigins
-        : [baseOrigin, ...trustedOrigins];
+    const allTrustedOrigins = trustedOrigins.includes(baseOrigin) ? trustedOrigins : [baseOrigin, ...trustedOrigins];
 
     let schema;
-    let provider: "pg" | "mysql" | "sqlite";
+    let provider: 'pg' | 'mysql' | 'sqlite';
 
     switch (adapterType) {
-        case "postgres":
+        case 'postgres':
             schema = pgSchema;
-            provider = "pg";
+            provider = 'pg';
             break;
-        case "mysql":
+        case 'mysql':
             schema = mysqlSchema;
-            provider = "mysql";
+            provider = 'mysql';
             break;
-        case "sqlite":
+        case 'sqlite':
             schema = sqliteSchema;
-            provider = "sqlite";
+            provider = 'sqlite';
             break;
         default:
             throw new Error(`Unsupported adapter type: ${adapterType}`);
@@ -111,47 +273,12 @@ export function createBetterAuth(options: BetterAuthConfigOptions): BetterAuthIn
 
     const database = drizzleAdapter(db as unknown as DrizzleAdapterDb, {
         provider,
-        schema
+        schema,
     });
 
     const plugins = [];
     if (oidcConfig) {
-        const authorizationUrl = oidcConfig.authorizationEndpoint ||
-            `${oidcConfig.issuer}/protocol/openid-connect/auth`;
-        const tokenUrl = oidcConfig.tokenEndpoint ||
-            `${oidcConfig.issuer}/protocol/openid-connect/token`;
-        const userInfoUrl = oidcConfig.userinfoEndpoint ||
-            `${oidcConfig.issuer}/protocol/openid-connect/userinfo`;
-
-        plugins.push(
-            genericOAuth({
-                config: [
-                    {
-                        providerId: oidcConfig.providerId || "oidc",
-                        clientId: oidcConfig.clientId,
-                        clientSecret: oidcConfig.clientSecret,
-                        authorizationUrl,
-                        tokenUrl,
-                        userInfoUrl,
-                        discoveryUrl: oidcConfig.discoveryEndpoint ||
-                            `${oidcConfig.issuer}/.well-known/openid-configuration`,
-                        scopes: oidcConfig.scopes || ["openid", "email", "profile"],
-                        // Secure default: PKCE on. Disabling exposes auth-code
-                        // interception/injection and requires an explicit false.
-                        pkce: oidcConfig.pkce !== undefined ? oidcConfig.pkce : true,
-                        mapProfileToUser: (profile: any) => {
-                            return {
-                                id: profile.sub || profile.id,
-                                email: profile.email,
-                                name: profile.name || profile.preferred_username,
-                                image: profile.picture || profile.image,
-                                emailVerified: profile.email_verified || false,
-                            };
-                        },
-                    },
-                ],
-            }),
-        );
+        plugins.push(genericOAuth({ config: [oidcProviderConfig(oidcConfig)] }));
     }
 
     return betterAuth({
@@ -162,9 +289,10 @@ export function createBetterAuth(options: BetterAuthConfigOptions): BetterAuthIn
         trustedOrigins: allTrustedOrigins,
         emailAndPassword: enableEmailPassword
             ? {
-                enabled: true,
-                autoSignIn: true,
-            }
+                  enabled: true,
+                  autoSignIn: true,
+                  disableSignUp,
+              }
             : undefined,
         socialProviders: Object.keys(socialProviders || {}).length > 0 ? socialProviders : undefined,
         plugins,
@@ -176,9 +304,16 @@ export function createBetterAuth(options: BetterAuthConfigOptions): BetterAuthIn
                 maxAge: cookieCacheMaxAge,
             },
         },
+        ...(rateLimit === false ? { rateLimit: { enabled: false } } : {}),
         advanced: {
             disableCSRFCheck,
-            generateId: () => crypto.randomUUID().replace(/-/g, ""),
+            // Pinned: left unset, better-auth skips its Origin check (CSRF on
+            // cookie requests) and its callbackURL/redirectTo validation (open
+            // redirects) whenever it thinks it runs under test: NODE_ENV=test,
+            // or any TEST variable other than "false" (TEST=0 included).
+            disableOriginCheck: false,
+            generateId: () => crypto.randomUUID().replace(/-/g, ''),
+            ...(ipAddressHeaders ? { ipAddress: { ipAddressHeaders } } : {}),
         },
     }) as unknown as BetterAuthInstance;
 }

package/src/index.ts

@@ -1,9 +1,13 @@
 export {
     createBetterAuth,
+    mapOidcProfile,
+    oidcProviderConfig,
+    resolveAuthBaseURL,
     type Auth,
     type AuthKitDrizzleDb,
     type BetterAuthConfigOptions,
-} from "./better-auth-config";
+    type OidcClaimMapping,
+} from './better-auth-config';
 
 export {
     pgUser,
@@ -21,7 +25,7 @@ export {
     sqliteAccount,
     sqliteVerification,
     sqliteSchema,
-} from "./schema";
+} from './schema';
 
 export type {
     User,
@@ -36,4 +40,4 @@ export type {
     PasswordResetRequest,
     PasswordResetConfirm,
     EmailVerificationRequest,
-} from "./types";
+} from './types';