@viktorbarzin/auth 0.0.0-stage → 1.0.0

package/dist/app-auth.js

@@ -0,0 +1,588 @@
+/**
+ * App-side sign-in against Authentik (ADR-0001, Identity and access):
+ * Better Auth's generic OAuth with PKCE and a verified id_token, sessions in
+ * the app's database (Drizzle adapter), host-only `__Host-` cookies, exact
+ * trustedOrigins, sessions capped at 7 days and never extended, and no
+ * `offline_access`. Plus bearer tokens for non-browser clients, the 15-minute
+ * membership re-check, request + approve, and the CSRF origin check.
+ *
+ * Sign-in goes through `<basePath>/start` and `<basePath>/finish`, not Better
+ * Auth's own /sign-in/social over HTTP. Everything here takes a Request and
+ * returns a Response or data; the app wires it into its framework's routes
+ * and middleware.
+ */
+import { getLogger } from "@viktorbarzin/log";
+import { createDiscoveredVerifier, } from "@viktorbarzin/oidc-token";
+import { ApiError, createErrorResponder, errorResponse, } from "@viktorbarzin/runtime";
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { APIError, getOAuthState } from "better-auth/api";
+import { genericOAuth, } from "better-auth/plugins/generic-oauth";
+import { and, asc, eq } from "drizzle-orm";
+import { AuthentikUnavailable, createAuthentikClient } from "./authentik.js";
+import { DEFAULTS, } from "./config.js";
+import { isSameOriginRequest } from "./csrf.js";
+import { createMembershipChecker, fileAccessRequest, getAccessRequest, readMemberCheck, recordClaimedGroups, saveMemberCheck, } from "./membership.js";
+import { authMetrics } from "./metrics.js";
+import { LOGIN_PARAM, pathWithReturn, safeReturnPath, signInPaths, } from "./return-path.js";
+import { accessRequests, authAccount, betterAuthModels } from "./schema.js";
+/** Better Auth endpoints an app does not use; refused over HTTP (404). */
+export const DISABLED_PATHS = [
+    "/sign-in/social",
+    "/sign-in/oauth2",
+    "/sign-in/email",
+    "/sign-up/email",
+    "/update-user",
+    "/delete-user",
+    "/change-email",
+    "/change-password",
+    "/set-password",
+    "/request-password-reset",
+    "/reset-password",
+    "/link-social",
+    "/unlink-account",
+    "/list-accounts",
+    "/account-info",
+    "/get-access-token",
+    "/refresh-token",
+    "/update-session",
+];
+/** How often a missing provider (discovery failed at init) may trigger a rebuild. */
+const REBUILD_INTERVAL_MS = 10_000;
+/** The config with every default filled in. */
+function resolve(config) {
+    const publicOrigins = config.publicOrigins.map((origin) => new URL(origin).origin);
+    return {
+        ...config,
+        publicOrigins,
+        providerId: config.providerId ?? DEFAULTS.providerId,
+        basePath: config.basePath ?? DEFAULTS.basePath,
+        scopes: config.scopes ?? [...DEFAULTS.scopes],
+        sessionMaxAgeSeconds: config.sessionMaxAgeSeconds ?? DEFAULTS.sessionMaxAgeSeconds,
+        cookiePrefix: config.cookiePrefix ?? `__Host-${config.appSlug}`,
+        clientIpHeader: config.clientIpHeader ?? DEFAULTS.clientIpHeader,
+        apiTokenAudiences: config.apiTokenAudiences ?? (config.oidc ? [config.oidc.clientId] : []),
+        guestUsername: config.guestUsername ?? DEFAULTS.guestUsername,
+        membershipMaxAgeMs: config.membershipMaxAgeMs ?? DEFAULTS.membershipMaxAgeMs,
+        adminRecheckMaxAgeMs: config.adminRecheckMaxAgeMs ?? DEFAULTS.adminRecheckMaxAgeMs,
+        // The dev user stands in only while sign-in is off. With OIDC configured,
+        // a stray DEV_USER would otherwise make every anonymous caller an admin.
+        devUser: config.oidc ? null : (config.devUser ?? null),
+        streamPaths: config.streamPaths ?? [...DEFAULTS.streamPaths],
+        loggerPrefix: config.loggerPrefix ?? config.appSlug,
+    };
+}
+function buildBetterAuth(cfg, oidc, secret, onVerifiedProfile) {
+    const baseURL = cfg.publicOrigins[0];
+    if (!baseURL)
+        throw new Error("publicOrigins must be set when OIDC sign-in is enabled");
+    return betterAuth({
+        appName: cfg.appName,
+        baseURL,
+        basePath: cfg.basePath,
+        secret,
+        trustedOrigins: cfg.publicOrigins,
+        database: drizzleAdapter(cfg.db(), {
+            provider: "pg",
+            schema: betterAuthModels,
+        }),
+        user: { modelName: "auth_user" },
+        session: {
+            modelName: "auth_session",
+            expiresIn: cfg.sessionMaxAgeSeconds,
+            // An absolute cap: the expiry is never pushed out.
+            disableSessionRefresh: true,
+            cookieCache: { enabled: false },
+        },
+        account: {
+            modelName: "auth_account",
+            // Never link accounts by email: users are keyed on sub.
+            accountLinking: { enabled: false },
+            encryptOAuthTokens: true,
+        },
+        verification: { modelName: "auth_verification" },
+        emailAndPassword: { enabled: false },
+        disabledPaths: [...DISABLED_PATHS],
+        telemetry: { enabled: false },
+        advanced: {
+            // The rate limiter (on in production) keys on the client IP. Behind a
+            // CDN and Traefik, X-Forwarded-For carries several hops; the ingress's
+            // real-ip plugin overwrites this header with the TCP peer's address,
+            // so a client cannot spoof it.
+            ipAddress: { ipAddressHeaders: [cfg.clientIpHeader] },
+            // `__Host-` needs Secure, Path=/ and no Domain; Better Auth would add
+            // its own `__Secure-` prefix with useSecureCookies.
+            cookiePrefix: cfg.cookiePrefix,
+            useSecureCookies: false,
+            defaultCookieAttributes: {
+                secure: true,
+                sameSite: "lax",
+                path: "/",
+                httpOnly: true,
+            },
+        },
+        plugins: [
+            genericOAuth({
+                config: [
+                    {
+                        providerId: cfg.providerId,
+                        name: cfg.providerId,
+                        discoveryUrl: oidc.discoveryUrl,
+                        requireIdTokenVerification: true,
+                        clientId: oidc.clientId,
+                        clientSecret: oidc.clientSecret,
+                        // No offline_access: web sign-in gets no refresh token.
+                        scopes: cfg.scopes,
+                        pkce: true,
+                        disableProviderLogout: true,
+                        overrideUserInfo: true,
+                        mapProfileToUser: onVerifiedProfile,
+                    },
+                ],
+            }),
+        ],
+    });
+}
+function redirect(location, extra) {
+    const headers = new Headers(extra);
+    headers.set("location", location);
+    headers.set("cache-control", "no-store");
+    return new Response(null, { status: 302, headers });
+}
+/** Copy every Set-Cookie from Better Auth's headers onto a response. */
+function withCookies(response, from) {
+    for (const cookie of from.getSetCookie())
+        response.headers.append("set-cookie", cookie);
+    return response;
+}
+function authKey(cfg) {
+    return JSON.stringify([
+        cfg.appName,
+        cfg.publicOrigins,
+        cfg.betterAuthSecret,
+        cfg.oidc,
+        cfg.providerId,
+        cfg.basePath,
+        cfg.scopes,
+        cfg.sessionMaxAgeSeconds,
+        cfg.cookiePrefix,
+        cfg.clientIpHeader,
+    ]);
+}
+/**
+ * The app's identity layer. `config` is re-read on every call (cheap; the app
+ * builds it from the environment); the Better Auth instance is rebuilt only
+ * when its settings change.
+ */
+export function createAppAuth(config) {
+    const current = () => resolve(config());
+    let devUserIgnoredLogged = false;
+    const loggers = new Map();
+    const logger = (part) => {
+        const cfg = config();
+        if (cfg.logger)
+            return cfg.logger;
+        const name = `${cfg.loggerPrefix ?? cfg.appSlug}.${part}`;
+        let found = loggers.get(name);
+        if (!found) {
+            found = getLogger(name);
+            loggers.set(name, found);
+        }
+        return found;
+    };
+    const metrics = () => {
+        const m = config().metrics;
+        return authMetrics({
+            ...(m?.registry ? { registry: m.registry } : {}),
+            prefix: m?.prefix ?? DEFAULTS.metricsPrefix,
+        });
+    };
+    const authentik = () => {
+        const cfg = config();
+        return createAuthentikClient({
+            ...cfg.authentik,
+            usersGroup: cfg.groups.users,
+            logger: logger("authentik"),
+        });
+    };
+    const membership = createMembershipChecker({
+        authentik,
+        groups: () => config().groups,
+        defaultMaxAgeMs: () => current().membershipMaxAgeMs,
+        metrics,
+        log: logger("membership"),
+    });
+    let instance = null;
+    let lastRebuild = 0;
+    let verifier = null;
+    async function enrich(db, sub, username) {
+        const hook = config().enrich;
+        return hook ? hook(db, { sub, username }) : {};
+    }
+    /** The anonymous guest came back: retry with prompt=login once, then stop on the error page. */
+    async function redirectGuest(cfg) {
+        metrics().signIns.inc({ outcome: "guest" });
+        const paths = signInPaths(cfg.basePath);
+        const state = await getOAuthState().catch(() => null);
+        const callback = new URL(state?.callbackURL ?? paths.finish, "http://app.invalid");
+        const returnTo = callback.searchParams.get("return") ?? "/";
+        const retried = callback.searchParams.has(LOGIN_PARAM);
+        const location = retried
+            ? `${paths.error}?error=guest_session`
+            : pathWithReturn(paths.start, returnTo, true);
+        logger("auth").info("guest session at the identity provider; asking for a real login", { retried });
+        throw new APIError("FOUND", undefined, { location });
+    }
+    /**
+     * Runs on every sign-in, after Better Auth verified the id_token (issuer,
+     * audience, signature, nonce): records the membership answer the token
+     * carries and, for a non-member in request mode, an access request.
+     */
+    async function onVerifiedProfile(profile) {
+        const cfg = current();
+        const sub = typeof profile.sub === "string" ? profile.sub : String(profile.sub ?? "");
+        const username = typeof profile.preferred_username === "string"
+            ? profile.preferred_username
+            : "";
+        if (!sub || !username) {
+            throw new APIError("UNAUTHORIZED", {
+                message: "the identity provider sent no sub or username",
+            });
+        }
+        if (username === cfg.guestUsername)
+            await redirectGuest(cfg);
+        const email = typeof profile.email === "string" && profile.email !== ""
+            ? profile.email
+            : null;
+        const name = typeof profile.name === "string" && profile.name !== ""
+            ? profile.name
+            : username;
+        const db = cfg.db();
+        await recordClaimedGroups(db, sub, username, profile.groups, "id_token", cfg.groups);
+        await enrich(db, sub, username);
+        const answer = await membership.current(db, sub, username);
+        if (!answer.member && cfg.signup === "request")
+            await fileAccessRequest(db, { sub, username, email, name });
+        metrics().signIns.inc({ outcome: answer.member ? "member" : "pending" });
+        logger("auth").info("signed in", {
+            sub,
+            user: username,
+            member: answer.member,
+        });
+        return {
+            name,
+            // Better Auth needs an email; it is never used to authorize (users are keyed on sub).
+            email: email ?? `${sub}@users.${cfg.appSlug}.invalid`,
+            emailVerified: profile.email_verified === true,
+            image: undefined,
+        };
+    }
+    function getAuth() {
+        const cfg = current();
+        if (!cfg.oidc || !cfg.betterAuthSecret)
+            return null;
+        const key = authKey(cfg);
+        if (instance?.key !== key)
+            instance = {
+                auth: buildBetterAuth(cfg, cfg.oidc, cfg.betterAuthSecret, onVerifiedProfile),
+                key,
+            };
+        return instance.auth;
+    }
+    /**
+     * The instance with the provider registered. Better Auth skips a provider
+     * whose discovery fetch failed at init; rebuild (at most every 10 s) so a
+     * provider blip at pod start does not disable sign-in until a restart.
+     */
+    async function getAuthWithProvider() {
+        const auth = getAuth();
+        if (!auth)
+            return null;
+        const providerId = current().providerId;
+        const registered = async (a) => (await a.$context).socialProviders.some((provider) => provider.id === providerId);
+        if (await registered(auth))
+            return auth;
+        const now = Date.now();
+        if (now - lastRebuild >= REBUILD_INTERVAL_MS) {
+            lastRebuild = now;
+            instance = null;
+            const rebuilt = getAuth();
+            if (rebuilt && (await registered(rebuilt)))
+                return rebuilt;
+        }
+        logger("auth").warning("the identity provider is not registered; discovery failed");
+        return null;
+    }
+    function tokenVerifier() {
+        const cfg = current();
+        if (!cfg.oidc)
+            return null;
+        const key = JSON.stringify([cfg.oidc.discoveryUrl, cfg.apiTokenAudiences]);
+        if (verifier?.key !== key) {
+            verifier = {
+                key,
+                verifier: createDiscoveredVerifier({
+                    discoveryUrl: cfg.oidc.discoveryUrl,
+                    audiences: cfg.apiTokenAudiences,
+                    onOutcome: (outcome) => metrics().tokenVerifications.inc({ outcome }),
+                    logger: logger("tokens"),
+                }),
+            };
+        }
+        return verifier.verifier;
+    }
+    async function userFromToken(token) {
+        const cfg = current();
+        if (token.preferredUsername === cfg.guestUsername)
+            return null;
+        const db = cfg.db();
+        if (!(await readMemberCheck(db, token.sub)))
+            await recordClaimedGroups(db, token.sub, token.preferredUsername, token.groups, "token", cfg.groups);
+        const answer = await membership.current(db, token.sub, token.preferredUsername);
+        const extra = await enrich(db, token.sub, token.preferredUsername);
+        return {
+            ...extra,
+            sub: token.sub,
+            username: token.preferredUsername,
+            via: "token",
+            ...answer,
+        };
+    }
+    async function sessionUser(request) {
+        if (!request.headers.get("cookie"))
+            return null;
+        const auth = getAuth();
+        if (!auth)
+            return null;
+        const found = await auth.api.getSession({
+            headers: request.headers,
+            query: { disableCookieCache: true, disableRefresh: true },
+        });
+        if (!found)
+            return null;
+        const cfg = current();
+        const db = cfg.db();
+        const [account] = await db
+            .select({ sub: authAccount.accountId })
+            .from(authAccount)
+            .where(and(eq(authAccount.userId, found.user.id), eq(authAccount.providerId, cfg.providerId)))
+            .limit(1);
+        if (!account)
+            return null;
+        const sub = account.sub;
+        // The username the verified id_token carried at the last sign-in.
+        const username = (await readMemberCheck(db, sub))?.username ?? found.user.name;
+        if (username === cfg.guestUsername)
+            return null;
+        const answer = await membership.current(db, sub, username);
+        const extra = await enrich(db, sub, username);
+        return { ...extra, sub, username, via: "session", ...answer };
+    }
+    async function resolveUser(request) {
+        if (request.headers.has("authorization")) {
+            const check = tokenVerifier();
+            if (!check) {
+                metrics().tokenVerifications.inc({ outcome: "not_configured" });
+                return null;
+            }
+            const token = await check.verifyRequest(request);
+            return token ? userFromToken(token) : null;
+        }
+        const fromSession = await sessionUser(request);
+        if (fromSession)
+            return fromSession;
+        const cfg = current();
+        if (!devUserIgnoredLogged && cfg.oidc && config().devUser) {
+            devUserIgnoredLogged = true;
+            logger("auth").error("devUser is ignored because OIDC sign-in is configured");
+        }
+        if (cfg.devUser) {
+            const extra = await enrich(cfg.db(), null, cfg.devUser);
+            return {
+                ...extra,
+                sub: null,
+                username: cfg.devUser,
+                via: "dev",
+                member: true,
+                admin: true,
+            };
+        }
+        return null;
+    }
+    async function requireUser(request) {
+        const user = await resolveUser(request);
+        if (!user)
+            throw new ApiError(401, "unauthorized", "not signed in");
+        if (!user.member)
+            throw new ApiError(403, "access_pending", "waiting for approval");
+        return user;
+    }
+    async function requireAdmin(user) {
+        if (user.via === "dev")
+            return;
+        if (!user.sub)
+            throw new ApiError(403, "forbidden", "admins only");
+        const cfg = current();
+        // A fresh answer for an admin action; when the provider cannot say, the
+        // last answer stands, as for every other check.
+        const answer = await membership.current(cfg.db(), user.sub, user.username, {
+            maxAgeMs: cfg.adminRecheckMaxAgeMs,
+        });
+        if (!answer.admin)
+            throw new ApiError(403, "forbidden", "admins only");
+    }
+    return {
+        getAuth,
+        async startSignIn(request) {
+            const cfg = current();
+            const url = new URL(request.url);
+            const returnTo = safeReturnPath(url.searchParams.get("return"));
+            const forceLogin = url.searchParams.has(LOGIN_PARAM);
+            const auth = await getAuthWithProvider();
+            if (!auth)
+                return errorResponse(503, "auth_unavailable", "sign-in is not available right now");
+            const paths = signInPaths(cfg.basePath);
+            const { headers, response } = await auth.api.signInSocial({
+                body: {
+                    provider: cfg.providerId,
+                    callbackURL: pathWithReturn(paths.finish, returnTo, forceLogin),
+                    errorCallbackURL: paths.error,
+                    disableRedirect: true,
+                    ...(forceLogin ? { additionalParams: { prompt: "login" } } : {}),
+                },
+                headers: request.headers,
+                returnHeaders: true,
+            });
+            if (!response.url)
+                throw new Error("Better Auth returned no authorization URL");
+            return withCookies(redirect(response.url), headers);
+        },
+        finishSignIn(request) {
+            return redirect(safeReturnPath(new URL(request.url).searchParams.get("return")));
+        },
+        async handleAuthRequest(request) {
+            const auth = getAuth();
+            if (!auth)
+                return errorResponse(404, "not_found", "sign-in is not configured");
+            const response = await auth.handler(request);
+            if (response.status >= 500) {
+                logger("auth").warning("auth endpoint failed", {
+                    path: new URL(request.url).pathname,
+                    status: response.status,
+                });
+            }
+            return response;
+        },
+        signInRedirect(returnTo) {
+            if (!getAuth())
+                return null;
+            return redirect(pathWithReturn(signInPaths(current().basePath).start, returnTo, false));
+        },
+        startUrl(returnTo, forceLogin) {
+            return pathWithReturn(signInPaths(current().basePath).start, returnTo, forceLogin);
+        },
+        resolveUser,
+        requireUser,
+        async handleApi(request, fn, toError) {
+            const respond = toError ?? createErrorResponder({ logger: logger("api") });
+            try {
+                return await fn(await requireUser(request));
+            }
+            catch (err) {
+                return respond(err, request);
+            }
+        },
+        async accessStatus(request, opts = {}) {
+            let user = await resolveUser(request);
+            if (!user)
+                return {
+                    signedIn: false,
+                    username: null,
+                    member: false,
+                    admin: false,
+                    requestedAt: null,
+                };
+            const cfg = current();
+            const db = cfg.db();
+            if (opts.recheck && user.sub) {
+                const answer = await membership.current(db, user.sub, user.username, {
+                    maxAgeMs: 0,
+                });
+                user = { ...user, ...answer };
+            }
+            const pending = user.sub && !user.member ? await getAccessRequest(db, user.sub) : null;
+            return {
+                signedIn: true,
+                username: user.username,
+                member: user.member,
+                admin: user.admin,
+                requestedAt: pending?.status === "pending"
+                    ? pending.requestedAt.toISOString()
+                    : null,
+            };
+        },
+        requireAdmin,
+        async listPendingRequests(admin) {
+            await requireAdmin(admin);
+            const rows = await current()
+                .db()
+                .select()
+                .from(accessRequests)
+                .where(eq(accessRequests.status, "pending"))
+                .orderBy(asc(accessRequests.requestedAt));
+            return rows.map((row) => ({
+                sub: row.sub,
+                username: row.username,
+                email: row.email,
+                name: row.name,
+                requestedAt: row.requestedAt.toISOString(),
+            }));
+        },
+        async approveRequest(admin, sub) {
+            await requireAdmin(admin);
+            const cfg = current();
+            const db = cfg.db();
+            const request = await getAccessRequest(db, sub);
+            if (!request || request.status !== "pending")
+                throw new ApiError(404, "not_found", "no pending request for that person");
+            try {
+                const client = authentik();
+                const user = await client.findUser(request.sub, request.username);
+                if (!user || !user.isActive)
+                    throw new ApiError(409, "conflict", "that Authentik account no longer exists");
+                await client.addToUsersGroup(user.pk);
+                await saveMemberCheck(db, request.sub, request.username, { member: true, admin: user.groups.includes(cfg.groups.admins) }, "api");
+            }
+            catch (err) {
+                if (err instanceof AuthentikUnavailable) {
+                    logger("access").warning("approval failed: Authentik did not answer", { sub, error: err.message });
+                    throw new ApiError(502, "authentik_unavailable", "Authentik did not accept the change; try again");
+                }
+                throw err;
+            }
+            await db
+                .update(accessRequests)
+                .set({
+                status: "approved",
+                decidedBy: admin.username,
+                decidedAt: new Date(),
+            })
+                .where(and(eq(accessRequests.sub, sub), eq(accessRequests.status, "pending")));
+            logger("access").info("access request approved", {
+                sub,
+                user: request.username,
+                by: admin.username,
+            });
+        },
+        currentMembership(sub, username, opts) {
+            return membership.current(current().db(), sub, username, opts);
+        },
+        csrfRejection(request) {
+            const cfg = current();
+            if (isSameOriginRequest(request, cfg.publicOrigins, cfg.streamPaths))
+                return null;
+            metrics().csrfRejections.inc();
+            return errorResponse(403, "forbidden", "cross-origin request refused");
+        },
+    };
+}

package/dist/authentik.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The few Authentik API calls an app makes (base `<apiUrl>/api/v3`):
+ *
+ * - find a user and their groups (reader token):
+ *   `GET /core/users/?username=<u>&include_groups=true`
+ * - find the users group's pk by name (reader token), when it is not configured:
+ *   `GET /core/groups/?name=<n>`
+ * - add a user to the users group (approver token):
+ *   `POST /core/groups/<group_pk>/add_user/` with `{"pk": <user_pk>}`
+ *
+ * Users are keyed on `sub` and never authorized by name: a username lookup
+ * only counts when the user's `uid` equals the `sub` the app holds (the
+ * provider's sub_mode hashed_user_id makes `sub` the user's `uid`).
+ */
+import type { Logger } from "@viktorbarzin/log";
+import { type AuthentikSettings } from "./config.js";
+/** The provider did not give an answer this module can believe. */
+export declare class AuthentikUnavailable extends Error {
+    constructor(message: string);
+}
+/**
+ * The app cannot ask at all: no API URL or token configured. A configuration
+ * error, not an outage, so callers that keep the last answer through an
+ * outage must not keep it through this.
+ */
+export declare class AuthentikNotConfigured extends AuthentikUnavailable {
+    constructor(message: string);
+}
+export interface AuthentikUser {
+    pk: number;
+    uid: string;
+    username: string;
+    isActive: boolean;
+    groups: string[];
+}
+export interface AuthentikClient {
+    findUser(sub: string, username: string): Promise<AuthentikUser | null>;
+    usersGroupPk(): Promise<string>;
+    addToUsersGroup(userPk: number): Promise<void>;
+}
+export declare function createAuthentikClient(cfg: AuthentikSettings & {
+    usersGroup: string;
+    logger?: Logger;
+}): AuthentikClient;