@viktorbarzin/auth 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# @viktorbarzin/auth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+App-side sign-in against Authentik, built on Better Auth 1.7:
+
+- generic OAuth with PKCE and a verified id_token, sessions in the app's own
+  database (Drizzle adapter), host-only `__Host-` cookies, exact trusted
+  origins, a 7-day absolute session cap, no `offline_access`, and a single
+  `prompt=login` retry when the provider answers with its anonymous guest;
+- caller resolution: a bearer JWT, else the session cookie, else a dev user;
+- a membership re-check against the Authentik API every 15 minutes, which
+  fails closed when the app cannot ask and keeps the last answer when the
+  provider is unreachable;
+- request and approve sign-up, the explicit CSRF origin check, and identity
+  metrics.
+
+<!-- typecheck-preamble
+import type { AuthDb } from "@viktorbarzin/auth";
+declare const pool: { getDb(): AuthDb };
+declare const env: Record<string, string | undefined>;
+declare const discoveryUrl: string, clientId: string, clientSecret: string;
+declare const apiUrl: string | null, readerToken: string | null, approverToken: string | null, usersGroupPk: string | null;
+declare const isDevOrTest: boolean;
+-->
+```ts
+import { createAppAuth } from "@viktorbarzin/auth";
+
+export const appAuth = createAppAuth(() => ({
+	appName: "My App",
+	appSlug: "myapp",
+	db: () => pool.getDb(),
+	publicOrigins: ["https://myapp.example"],
+	betterAuthSecret: env.BETTER_AUTH_SECRET ?? null,
+	oidc: { discoveryUrl, clientId, clientSecret },
+	authentik: { apiUrl, readerToken, approverToken, usersGroupPk },
+	groups: { users: "My App Users", admins: "My App Admins", agents: "My App Agents" },
+	signup: "request",
+	// Honoured only while `oidc` is null; pass it only in development and test.
+	devUser: isDevOrTest ? (env.DEV_USER ?? null) : null,
+}));
+
+// routes: <basePath>/start → appAuth.startSignIn, <basePath>/finish → appAuth.finishSignIn,
+//         <basePath>/$ → appAuth.handleAuthRequest
+// middleware: appAuth.csrfRejection(request) ?? next()
+// /api routes: appAuth.handleApi(request, async (user) => Response.json(...))
+```
+
+The config function is read on every call; the Better Auth instance is
+rebuilt only when its settings change. Every name, URL, group, path, cookie
+prefix, timing and metric prefix is a config input (see `AppAuthConfig`).
+
+| Export | |
+|---|---|
+| `createAppAuth(config)` | `startSignIn`, `finishSignIn`, `handleAuthRequest`, `signInRedirect`, `startUrl`, `resolveUser`, `requireUser` (401 `unauthorized`, 403 `access_pending`), `handleApi`, `accessStatus`, `requireAdmin`, `listPendingRequests`, `approveRequest` (404 / 409 / 502), `currentMembership`, `csrfRejection`, `getAuth` |
+| `enrich(db, { sub, username })` (config) | extra per-user fields, looked up on each resolved request and once at sign-in |
+| `safeReturnPath`, `isSameOriginRequest`, `needsOriginCheck`, `membershipFromGroups` | the pure checks |
+| `createAuthentikClient`, `AuthentikUnavailable`, `AuthentikNotConfigured` | the three Authentik API calls |
+| metrics (prefix `p`, default `auth`) | `p_membership_checks_total{outcome}`, `p_api_token_verifications_total{outcome}`, `p_csrf_rejections_total`, `p_sign_ins_total{outcome}` |
+| `@viktorbarzin/auth/schema` | `auth_user`, `auth_session`, `auth_account`, `auth_verification`, `member_checks`, `access_requests` for the app's Drizzle schema |
+| `@viktorbarzin/auth/testing` | `startMockAuthentik` (OIDC provider plus the API calls), `startBuiltServer`, `CookieJar`, `follow` |
+
+A schema change is a major version: apps regenerate their migrations.
+Peers: `better-auth` >=1.7.7 <1.8 (the callback path changed in 1.7),
+`drizzle-orm` ^0.45, `prom-client` ^15.1 and the other `@viktorbarzin`
+packages.

package/dist/app-auth.d.ts

@@ -0,0 +1,160 @@
+/**
+ * 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 { type Logger } from "@viktorbarzin/log";
+import { type GenericOAuthUserInfo } from "better-auth/plugins/generic-oauth";
+import { type AccessStatus, type AppAuthConfig, type AuthDb, type AuthUser, type PendingRequestView } from "./config.js";
+import { type Membership, type MembershipOptions } from "./membership.js";
+/** Better Auth endpoints an app does not use; refused over HTTP (404). */
+export declare const DISABLED_PATHS: readonly string[];
+/** The config with every default filled in. */
+declare function resolve<TExtra extends object>(config: AppAuthConfig<TExtra>): {
+    publicOrigins: string[];
+    providerId: string;
+    basePath: string;
+    scopes: string[];
+    sessionMaxAgeSeconds: number;
+    cookiePrefix: string;
+    clientIpHeader: string;
+    apiTokenAudiences: string[];
+    guestUsername: string;
+    membershipMaxAgeMs: number;
+    adminRecheckMaxAgeMs: number;
+    devUser: string | null;
+    streamPaths: string[];
+    loggerPrefix: string;
+    appName: string;
+    appSlug: string;
+    db: () => AuthDb;
+    betterAuthSecret: string | null;
+    oidc: import("./config.js").OidcClientSettings | null;
+    authentik: import("./config.js").AuthentikSettings;
+    groups: import("./config.js").GroupNames;
+    signup: "request" | "open";
+    enrich?: ((db: AuthDb, who: {
+        sub: string | null;
+        username: string;
+    }) => Promise<TExtra>) | undefined;
+    metrics?: {
+        registry?: import("prom-client").Registry;
+        prefix?: string;
+    };
+    logger?: Logger;
+};
+type Resolved<TExtra extends object> = ReturnType<typeof resolve<TExtra>>;
+declare function buildBetterAuth<TExtra extends object>(cfg: Resolved<TExtra>, oidc: NonNullable<AppAuthConfig["oidc"]>, secret: string, onVerifiedProfile: (profile: GenericOAuthUserInfo) => Promise<{
+    name: string;
+    email: string;
+    emailVerified: boolean;
+    image: undefined;
+}>): import("better-auth").Auth<{
+    appName: string;
+    baseURL: string;
+    basePath: string;
+    secret: string;
+    trustedOrigins: string[];
+    database: (options: import("better-auth").BetterAuthOptions) => import("better-auth").DBAdapter<import("better-auth").BetterAuthOptions>;
+    user: {
+        modelName: "auth_user";
+    };
+    session: {
+        modelName: "auth_session";
+        expiresIn: number;
+        disableSessionRefresh: true;
+        cookieCache: {
+            enabled: false;
+        };
+    };
+    account: {
+        modelName: "auth_account";
+        accountLinking: {
+            enabled: false;
+        };
+        encryptOAuthTokens: true;
+    };
+    verification: {
+        modelName: "auth_verification";
+    };
+    emailAndPassword: {
+        enabled: false;
+    };
+    disabledPaths: string[];
+    telemetry: {
+        enabled: false;
+    };
+    advanced: {
+        ipAddress: {
+            ipAddressHeaders: string[];
+        };
+        cookiePrefix: string;
+        useSecureCookies: false;
+        defaultCookieAttributes: {
+            secure: true;
+            sameSite: "lax";
+            path: string;
+            httpOnly: true;
+        };
+    };
+    plugins: [{
+        id: "generic-oauth";
+        version: string;
+        init: (ctx: import("better-auth").AuthContext) => Promise<{
+            context: {
+                socialProviders: import("better-auth").OAuthProvider<object, Partial<import("better-auth").ProviderOptions<object>>>[];
+            };
+        }>;
+        options: import("better-auth/plugins/generic-oauth").GenericOAuthOptions<string>;
+        $ERROR_CODES: {
+            INVALID_OAUTH_CONFIGURATION: import("better-auth").RawError<"INVALID_OAUTH_CONFIGURATION">;
+            TOKEN_URL_NOT_FOUND: import("better-auth").RawError<"TOKEN_URL_NOT_FOUND">;
+        };
+    }];
+}>;
+export type BetterAuthInstance = ReturnType<typeof buildBetterAuth>;
+export interface AppAuth<TExtra extends object> {
+    /** The Better Auth instance, or null when sign-in is not configured. */
+    getAuth(): BetterAuthInstance | null;
+    /** GET <basePath>/start?return=<path>[&login=1]: redirect to the provider. 503 auth_unavailable when it cannot. */
+    startSignIn(request: Request): Promise<Response>;
+    /** GET <basePath>/finish?return=<path>: Better Auth set the session cookie; go back. */
+    finishSignIn(request: Request): Response;
+    /** Everything else under <basePath>: callback, sign-out, get-session, error page. */
+    handleAuthRequest(request: Request): Promise<Response>;
+    /** A redirect into sign-in that comes back to `returnTo`; null when sign-in is off. */
+    signInRedirect(returnTo: string): Response | null;
+    startUrl(returnTo: string, forceLogin: boolean): string;
+    /** The caller, or null. A refused bearer token is null even with a cookie. Membership is not enforced. */
+    resolveUser(request: Request): Promise<(AuthUser & TExtra) | null>;
+    /** The caller, or ApiError 401 unauthorized / 403 access_pending. */
+    requireUser(request: Request): Promise<AuthUser & TExtra>;
+    /** Resolve the caller, run `fn`, map errors to the envelope. */
+    handleApi(request: Request, fn: (user: AuthUser & TExtra) => Promise<Response>, toError?: (err: unknown, request: Request) => Response): Promise<Response>;
+    accessStatus(request: Request, opts?: {
+        recheck?: boolean;
+    }): Promise<AccessStatus>;
+    /** Throws ApiError 403 unless the user is an admin right now (re-checked within adminRecheckMaxAgeMs). */
+    requireAdmin(user: AuthUser): Promise<void>;
+    listPendingRequests(admin: AuthUser): Promise<PendingRequestView[]>;
+    /** 404 not_found / 409 conflict / 502 authentik_unavailable. */
+    approveRequest(admin: AuthUser, sub: string): Promise<void>;
+    currentMembership(sub: string, username: string, opts?: MembershipOptions): Promise<Membership>;
+    /** The 403 envelope for a refused cross-origin request, or null to let it through. */
+    csrfRejection(request: Request): Response | null;
+}
+/**
+ * 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 declare function createAppAuth<TExtra extends object = Record<never, never>>(config: () => AppAuthConfig<TExtra>): AppAuth<TExtra>;
+export {};