@viktorbarzin/auth 0.0.0-stage → 1.0.0

package/dist/schema.js

@@ -0,0 +1,110 @@
+/**
+ * The identity tables an app adds to its own schema
+ * (`export * from "@viktorbarzin/auth/schema"` in the app's Drizzle schema).
+ *
+ * - auth_user, auth_session, auth_account, auth_verification: Better Auth's
+ *   tables (Drizzle adapter). Property names are the field names Better Auth
+ *   uses; columns are snake_case.
+ * - member_checks: the last membership answer per OIDC `sub`, re-asked every
+ *   15 minutes.
+ * - access_requests: request + approve sign-up.
+ *
+ * Changing a column here is a breaking change: apps regenerate migrations.
+ */
+import { boolean, index, pgTable, text, timestamp, uniqueIndex, varchar, } from "drizzle-orm/pg-core";
+const tz = { withTimezone: true, mode: "date" };
+export const authUser = pgTable("auth_user", {
+    id: text("id").primaryKey(),
+    name: text("name").notNull(),
+    email: text("email").notNull().unique(),
+    emailVerified: boolean("email_verified").default(false).notNull(),
+    image: text("image"),
+    createdAt: timestamp("created_at", tz).notNull(),
+    updatedAt: timestamp("updated_at", tz)
+        .$onUpdate(() => new Date())
+        .notNull(),
+});
+export const authSession = pgTable("auth_session", {
+    id: text("id").primaryKey(),
+    expiresAt: timestamp("expires_at", tz).notNull(),
+    token: text("token").notNull().unique(),
+    createdAt: timestamp("created_at", tz).notNull(),
+    updatedAt: timestamp("updated_at", tz)
+        .$onUpdate(() => new Date())
+        .notNull(),
+    ipAddress: text("ip_address"),
+    userAgent: text("user_agent"),
+    userId: text("user_id")
+        .notNull()
+        .references(() => authUser.id, { onDelete: "cascade" }),
+}, (table) => [index("auth_session_user_id_idx").on(table.userId)]);
+export const authAccount = pgTable("auth_account", {
+    id: text("id").primaryKey(),
+    /** The provider's subject: the OIDC `sub`. */
+    accountId: text("account_id").notNull(),
+    providerId: text("provider_id").notNull(),
+    userId: text("user_id")
+        .notNull()
+        .references(() => authUser.id, { onDelete: "cascade" }),
+    accessToken: text("access_token"),
+    refreshToken: text("refresh_token"),
+    idToken: text("id_token"),
+    accessTokenExpiresAt: timestamp("access_token_expires_at", tz),
+    refreshTokenExpiresAt: timestamp("refresh_token_expires_at", tz),
+    scope: text("scope"),
+    password: text("password"),
+    createdAt: timestamp("created_at", tz).notNull(),
+    updatedAt: timestamp("updated_at", tz)
+        .$onUpdate(() => new Date())
+        .notNull(),
+}, (table) => [
+    index("auth_account_user_id_idx").on(table.userId),
+    uniqueIndex("auth_account_provider_subject_key").on(table.providerId, table.accountId),
+]);
+export const authVerification = pgTable("auth_verification", {
+    id: text("id").primaryKey(),
+    identifier: text("identifier").notNull(),
+    value: text("value").notNull(),
+    expiresAt: timestamp("expires_at", tz).notNull(),
+    createdAt: timestamp("created_at", tz).notNull(),
+    updatedAt: timestamp("updated_at", tz)
+        .$onUpdate(() => new Date())
+        .notNull(),
+}, (table) => [index("auth_verification_identifier_idx").on(table.identifier)]);
+/** The last membership answer for a subject, from the id_token, a bearer token or the provider's API. */
+export const memberChecks = pgTable("member_checks", {
+    sub: varchar("sub", { length: 255 }).primaryKey(),
+    username: varchar("username", { length: 255 }).notNull(),
+    member: boolean("member").notNull(),
+    admin: boolean("admin").notNull(),
+    /** "id_token", "token" or "api". */
+    source: varchar("source", { length: 16 }).notNull(),
+    checkedAt: timestamp("checked_at", tz).notNull(),
+});
+/** A signed-in person who is not in the app's users group yet. */
+export const accessRequests = pgTable("access_requests", {
+    sub: varchar("sub", { length: 255 }).primaryKey(),
+    username: varchar("username", { length: 255 }).notNull(),
+    email: varchar("email", { length: 320 }),
+    name: varchar("name", { length: 255 }),
+    /** "pending" or "approved". */
+    status: varchar("status", { length: 16 }).notNull(),
+    requestedAt: timestamp("requested_at", tz).defaultNow().notNull(),
+    decidedBy: varchar("decided_by", { length: 255 }),
+    decidedAt: timestamp("decided_at", tz),
+});
+export const authSchema = {
+    authUser,
+    authSession,
+    authAccount,
+    authVerification,
+    memberChecks,
+    accessRequests,
+};
+/** The Better Auth Drizzle adapter's schema map, keyed by model name. */
+export const betterAuthModels = {
+    auth_user: authUser,
+    auth_session: authSession,
+    auth_account: authAccount,
+    auth_verification: authVerification,
+};

package/dist/testing/built-server.d.ts

@@ -0,0 +1,50 @@
+export declare function freePort(): Promise<number>;
+export interface BuiltServer {
+    origin: string;
+    /** The METRICS_PORT listener (/metrics), separate from the app port; null when not started. */
+    metricsOrigin: string | null;
+    /** Every stdout and stderr line so far. */
+    logs: string[];
+    /** Send a signal to the server process. */
+    kill(signal: NodeJS.Signals): void;
+    /** Resolves with the exit code once the process has exited. */
+    exited: Promise<number>;
+    stop(): Promise<void>;
+}
+/** Env keys that must not leak from the developer's shell into the server under test. */
+export declare const SCRUBBED_ENV: string[];
+export interface StartBuiltServerOptions {
+    /** The built entry, e.g. `<app>/.output/server/index.mjs`. */
+    entry: string;
+    env: Record<string, string>;
+    /** Working directory; defaults to two levels above the entry (the app root). */
+    cwd?: string;
+    /** Start the METRICS_PORT listener too. Default true. */
+    metricsPort?: boolean;
+    /** Extra env computed from the chosen port, e.g. PUBLIC_ORIGINS. */
+    origin?: (port: number) => Record<string, string>;
+    /** How long to wait for /healthz. Default 15 s. */
+    startTimeoutMs?: number;
+}
+export declare function startBuiltServer(opts: StartBuiltServerOptions): Promise<BuiltServer>;
+/** A minimal cookie jar for one origin. */
+export declare class CookieJar {
+    readonly cookies: Map<string, string>;
+    /** Every Set-Cookie header seen, attributes included. */
+    readonly raw: string[];
+    store(response: Response): void;
+    header(): string;
+}
+export interface Hop {
+    url: string;
+    status: number;
+    location: string | null;
+}
+/**
+ * Follow redirects by hand like a browser would, keeping cookies for
+ * `appOrigin`. Returns every hop and the final response.
+ */
+export declare function follow(start: string, jar: CookieJar, appOrigin: string, maxHops?: number): Promise<{
+    hops: Hop[];
+    response: Response;
+}>;

package/dist/testing/built-server.js

@@ -0,0 +1,157 @@
+/**
+ * Helpers for HTTP tests against an app's built server: start it on a free
+ * 127.0.0.1 port (plus a METRICS_PORT listener), a cookie jar, and a redirect
+ * follower that behaves like a browser.
+ */
+import { dirname, resolve } from "node:path";
+export async function freePort() {
+    const probe = Bun.serve({
+        hostname: "127.0.0.1",
+        port: 0,
+        fetch: () => new Response(),
+    });
+    const port = probe.port;
+    await probe.stop(true);
+    return port;
+}
+/** Env keys that must not leak from the developer's shell into the server under test. */
+export const SCRUBBED_ENV = [
+    "DEV_USER",
+    "PUBLIC_ORIGINS",
+    "OIDC_DISCOVERY_URL",
+    "OIDC_CLIENT_ID",
+    "OIDC_CLIENT_SECRET",
+    "OIDC_CLIENT_SECRET_FILE",
+    "BETTER_AUTH_SECRET",
+    "BETTER_AUTH_SECRET_FILE",
+    "API_TOKEN_AUDIENCES",
+    "AUTHENTIK_API_URL",
+    "AUTHENTIK_READER_TOKEN",
+    "AUTHENTIK_READER_TOKEN_FILE",
+    "AUTHENTIK_APPROVER_TOKEN",
+    "AUTHENTIK_APPROVER_TOKEN_FILE",
+    "AUTHENTIK_USERS_GROUP_ID",
+    "DATABASE_URL",
+    "DATABASE_PASSWORD_FILE",
+    "METRICS_PORT",
+];
+export async function startBuiltServer(opts) {
+    const port = await freePort();
+    const metricsPort = opts.metricsPort === false ? null : await freePort();
+    const origin = `http://127.0.0.1:${port}`;
+    const base = { ...process.env };
+    for (const key of SCRUBBED_ENV)
+        delete base[key];
+    const proc = Bun.spawn([process.execPath, opts.entry], {
+        cwd: opts.cwd ?? resolve(dirname(opts.entry), "../.."),
+        env: {
+            ...base,
+            NODE_ENV: "test",
+            LOG_LEVEL: "INFO",
+            HOST: "127.0.0.1",
+            PORT: String(port),
+            ...(metricsPort === null ? {} : { METRICS_PORT: String(metricsPort) }),
+            ...(opts.origin?.(port) ?? {}),
+            ...opts.env,
+        },
+        stdout: "pipe",
+        stderr: "pipe",
+    });
+    const logs = [];
+    const pump = async (stream) => {
+        const decoder = new TextDecoder();
+        for await (const chunk of stream)
+            logs.push(...decoder.decode(chunk).split("\n").filter(Boolean));
+    };
+    void pump(proc.stdout);
+    void pump(proc.stderr);
+    const deadline = Date.now() + (opts.startTimeoutMs ?? 15_000);
+    for (;;) {
+        try {
+            const res = await fetch(`${origin}/healthz`);
+            if (res.ok)
+                break;
+        }
+        catch {
+            // not listening yet
+        }
+        if (proc.exitCode !== null || Date.now() > deadline) {
+            proc.kill(9);
+            throw new Error(`server did not start:\n${logs.join("\n")}`);
+        }
+        await Bun.sleep(100);
+    }
+    return {
+        origin,
+        metricsOrigin: metricsPort === null ? null : `http://127.0.0.1:${metricsPort}`,
+        logs,
+        kill: (signal) => proc.kill(signal),
+        exited: proc.exited,
+        async stop() {
+            proc.kill();
+            // Graceful shutdown waits for open streams; do not wait long.
+            const exited = await Promise.race([
+                proc.exited.then(() => true),
+                Bun.sleep(2_000).then(() => false),
+            ]);
+            if (!exited) {
+                proc.kill(9);
+                await proc.exited;
+            }
+        },
+    };
+}
+/** A minimal cookie jar for one origin. */
+export class CookieJar {
+    cookies = new Map();
+    /** Every Set-Cookie header seen, attributes included. */
+    raw = [];
+    store(response) {
+        for (const header of response.headers.getSetCookie()) {
+            this.raw.push(header);
+            const [pair, ...attributes] = header.split(";");
+            const eq = (pair ?? "").indexOf("=");
+            const name = (pair ?? "").slice(0, eq).trim();
+            const value = (pair ?? "").slice(eq + 1).trim();
+            const expired = attributes.some((a) => {
+                const [k, v] = a.trim().split("=");
+                if (k?.toLowerCase() === "max-age")
+                    return Number(v) <= 0;
+                if (k?.toLowerCase() === "expires")
+                    return new Date(v ?? "").getTime() < Date.now();
+                return false;
+            });
+            if (expired || value === "")
+                this.cookies.delete(name);
+            else
+                this.cookies.set(name, value);
+        }
+    }
+    header() {
+        return [...this.cookies].map(([k, v]) => `${k}=${v}`).join("; ");
+    }
+}
+/**
+ * Follow redirects by hand like a browser would, keeping cookies for
+ * `appOrigin`. Returns every hop and the final response.
+ */
+export async function follow(start, jar, appOrigin, maxHops = 12) {
+    const hops = [];
+    let url = start;
+    for (let i = 0; i < maxHops; i++) {
+        const target = new URL(url);
+        const headers = {};
+        if (target.origin === appOrigin && jar.cookies.size > 0)
+            headers.cookie = jar.header();
+        const response = await fetch(url, { redirect: "manual", headers });
+        if (target.origin === appOrigin)
+            jar.store(response);
+        const location = response.headers.get("location");
+        hops.push({ url, status: response.status, location });
+        if (response.status < 300 || response.status >= 400 || !location) {
+            return { hops, response };
+        }
+        url = new URL(location, url).toString();
+    }
+    throw new Error(`too many redirects: ${hops.map((h) => h.url).join(" -> ")}`);
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Test helpers for apps using @viktorbarzin/auth: a mock Authentik (OIDC
+ * provider plus the /api/v3 calls the package makes) and helpers for HTTP
+ * tests against a built server. Never import this from app code.
+ */
+export { type BuiltServer, CookieJar, follow, freePort, type Hop, SCRUBBED_ENV, type StartBuiltServerOptions, startBuiltServer, } from "./built-server.js";
+export { type AuthorizeRecord, type MockAuthentik, type MockAuthentikOptions, type MockUser, startMockAuthentik, } from "./mock-authentik.js";

package/dist/testing/index.js

@@ -0,0 +1,7 @@
+/**
+ * Test helpers for apps using @viktorbarzin/auth: a mock Authentik (OIDC
+ * provider plus the /api/v3 calls the package makes) and helpers for HTTP
+ * tests against a built server. Never import this from app code.
+ */
+export { CookieJar, follow, freePort, SCRUBBED_ENV, startBuiltServer, } from "./built-server.js";
+export { startMockAuthentik, } from "./mock-authentik.js";

package/dist/testing/mock-authentik.d.ts

@@ -0,0 +1,70 @@
+import { type JWTPayload } from "jose";
+export interface MockUser {
+    pk: number;
+    uid: string;
+    username: string;
+    email: string | null;
+    name: string;
+    isActive: boolean;
+    groups: string[];
+}
+export interface AuthorizeRecord {
+    clientId: string;
+    scope: string;
+    prompt: string | null;
+    codeChallengeMethod: string | null;
+    nonce: string | null;
+    user: string;
+}
+export interface MockAuthentik {
+    /** The provider's issuer, e.g. http://127.0.0.1:1234/application/o/<slug>/ */
+    issuer: string;
+    discoveryUrl: string;
+    apiUrl: string;
+    clientId: string;
+    clientSecret: string;
+    readerToken: string;
+    approverToken: string;
+    usersGroupPk: string;
+    /** The users group's name: the group lookup answers it and add_user adds it. */
+    usersGroup: string;
+    users: Map<string, MockUser>;
+    /** Who the browser is signed in as at the provider: a username, or null (no session). */
+    session: string | null;
+    /** Who logs in when the provider shows its login form (no session, or prompt=login). */
+    loginAs: string | null;
+    authorizations: AuthorizeRecord[];
+    tokenRequests: Array<{
+        grantType: string;
+        scope: string;
+    }>;
+    apiCalls: Array<{
+        method: string;
+        path: string;
+        token: string | null;
+    }>;
+    /** Fail every /api/v3 call with this status (simulate an outage). */
+    apiFailure: number | null;
+    addUser(user: Partial<MockUser> & {
+        username: string;
+    }): MockUser;
+    /** Sign an access token for bearer tests. */
+    mintAccessToken(claims: JWTPayload, options?: {
+        alg?: string;
+        expiresIn?: string | number;
+        audience?: string;
+    }): Promise<string>;
+    stop(): Promise<void>;
+}
+export interface MockAuthentikOptions {
+    clientId: string;
+    clientSecret?: string;
+    /** The application slug in the issuer path. Defaults to clientId. */
+    slug?: string;
+    /** Defaults to "App Users". */
+    usersGroup?: string;
+    users?: Array<Partial<MockUser> & {
+        username: string;
+    }>;
+}
+export declare function startMockAuthentik(options: MockAuthentikOptions): Promise<MockAuthentik>;