@checkstack/auth-backend 0.0.2

package/src/schema.ts

@@ -0,0 +1,173 @@
+import {
+  pgTable,
+  text,
+  boolean,
+  timestamp,
+  primaryKey,
+} from "drizzle-orm/pg-core";
+
+// --- Better Auth Schema ---
+// Tables use pgTable (schemaless) - runtime schema is set via search_path
+export const user = pgTable("user", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  email: text("email").notNull().unique(),
+  emailVerified: boolean("email_verified").notNull(),
+  image: text("image"),
+  createdAt: timestamp("created_at").notNull(),
+  updatedAt: timestamp("updated_at").notNull(),
+});
+
+export const session = pgTable("session", {
+  id: text("id").primaryKey(),
+  expiresAt: timestamp("expires_at").notNull(),
+  token: text("token").notNull().unique(),
+  createdAt: timestamp("created_at").notNull(),
+  updatedAt: timestamp("updated_at").notNull(),
+  ipAddress: text("ip_address"),
+  userAgent: text("user_agent"),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id),
+});
+
+export const account = pgTable("account", {
+  id: text("id").primaryKey(),
+  accountId: text("account_id").notNull(),
+  providerId: text("provider_id").notNull(),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id),
+  accessToken: text("access_token"),
+  refreshToken: text("refresh_token"),
+  idToken: text("id_token"),
+  accessTokenExpiresAt: timestamp("access_token_expires_at"),
+  refreshTokenExpiresAt: timestamp("refresh_token_expires_at"),
+  scope: text("scope"),
+  password: text("password"),
+  createdAt: timestamp("created_at").notNull(),
+  updatedAt: timestamp("updated_at").notNull(),
+});
+
+export const verification = pgTable("verification", {
+  id: text("id").primaryKey(),
+  identifier: text("identifier").notNull(),
+  value: text("value").notNull(),
+  expiresAt: timestamp("expires_at").notNull(),
+  createdAt: timestamp("created_at"),
+  updatedAt: timestamp("updated_at"),
+});
+
+// --- RBAC Schema ---
+export const role = pgTable("role", {
+  id: text("id").primaryKey(), // 'admin', 'user', 'anonymous'
+  name: text("name").notNull(),
+  description: text("description"),
+  isSystem: boolean("is_system").default(false), // Prevent deletion of core roles
+});
+
+export const permission = pgTable("permission", {
+  id: text("id").primaryKey(), // 'core.manage-users', etc.
+  description: text("description"),
+});
+
+export const rolePermission = pgTable(
+  "role_permission",
+  {
+    roleId: text("role_id")
+      .notNull()
+      .references(() => role.id),
+    permissionId: text("permission_id")
+      .notNull()
+      .references(() => permission.id),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.roleId, t.permissionId] }),
+  })
+);
+
+export const userRole = pgTable(
+  "user_role",
+  {
+    userId: text("user_id")
+      .notNull()
+      .references(() => user.id),
+    roleId: text("role_id")
+      .notNull()
+      .references(() => role.id),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.userId, t.roleId] }),
+  })
+);
+
+/**
+ * Tracks authenticated default permissions that have been disabled by admins.
+ * When a plugin registers a permission with isAuthenticatedDefault=true, it gets assigned
+ * to the "users" role unless it's in this table.
+ */
+export const disabledDefaultPermission = pgTable(
+  "disabled_default_permission",
+  {
+    permissionId: text("permission_id")
+      .primaryKey()
+      .references(() => permission.id),
+    disabledAt: timestamp("disabled_at").notNull(),
+  }
+);
+
+/**
+ * Tracks public default permissions that have been disabled by admins.
+ * When a plugin registers a permission with isPublicDefault=true, it gets assigned
+ * to the "anonymous" role unless it's in this table.
+ */
+export const disabledPublicDefaultPermission = pgTable(
+  "disabled_public_default_permission",
+  {
+    permissionId: text("permission_id")
+      .primaryKey()
+      .references(() => permission.id),
+    disabledAt: timestamp("disabled_at").notNull(),
+  }
+);
+
+// --- External Applications Schema ---
+
+/**
+ * External applications (API keys) for programmatic API access.
+ * Applications have roles assigned like users and authenticate via Bearer tokens.
+ */
+export const application = pgTable("application", {
+  id: text("id").primaryKey(), // UUID
+  name: text("name").notNull(),
+  description: text("description"),
+  // Hashed secret (bcrypt) - never stored in plain text
+  secretHash: text("secret_hash").notNull(),
+  // User who created this application
+  createdById: text("created_by_id")
+    .notNull()
+    .references(() => user.id),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+  // Track when the application was last used for API calls
+  lastUsedAt: timestamp("last_used_at"),
+});
+
+/**
+ * Application-to-Role mapping for RBAC.
+ * Similar to userRole but for external applications.
+ */
+export const applicationRole = pgTable(
+  "application_role",
+  {
+    applicationId: text("application_id")
+      .notNull()
+      .references(() => application.id, { onDelete: "cascade" }),
+    roleId: text("role_id")
+      .notNull()
+      .references(() => role.id),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.applicationId, t.roleId] }),
+  })
+);

package/src/utils/auth-error-redirect.ts

@@ -0,0 +1,42 @@
+/**
+ * Utilities for handling authentication error redirects
+ * to the frontend error page with proper encoding.
+ */
+
+/**
+ * Encode error message for URL (better-auth uses underscores for spaces)
+ * @param message - The error message to encode
+ * @returns The encoded message with spaces replaced by underscores
+ */
+export function encodeAuthError(message: string): string {
+  return message.replaceAll(" ", "_");
+}
+
+/**
+ * Build auth error redirect URL
+ * @param errorMessage - User-friendly error message
+ * @param frontendUrl - Frontend base URL (defaults to VITE_FRONTEND_URL env var)
+ * @returns The full redirect URL to the error page
+ */
+export function buildAuthErrorUrl(
+  errorMessage: string,
+  frontendUrl?: string
+): string {
+  const base =
+    frontendUrl || process.env.VITE_FRONTEND_URL || "http://localhost:5173";
+  const encoded = encodeAuthError(errorMessage);
+  return `${base}/auth/error?error=${encodeURIComponent(encoded)}`;
+}
+
+/**
+ * Create HTTP redirect response to auth error page
+ * @param errorMessage - User-friendly error message
+ * @param frontendUrl - Optional frontend base URL
+ * @returns HTTP redirect Response to the error page
+ */
+export function redirectToAuthError(
+  errorMessage: string,
+  frontendUrl?: string
+): Response {
+  return Response.redirect(buildAuthErrorUrl(errorMessage, frontendUrl), 302);
+}

package/src/utils/user.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect, mock } from "bun:test";
+import { enrichUser } from "./user";
+import { User } from "better-auth/types";
+
+// Mock Drizzle DB
+const createMockDb = (data: { roles?: unknown[]; permissions?: unknown[] }) => {
+  const mockDb: any = {
+    select: mock(() => mockDb),
+    from: mock(() => mockDb),
+    innerJoin: mock(() => mockDb),
+    where: mock(() => mockDb),
+  };
+
+  // Mock thenable for different chains
+  // eslint-disable-next-line unicorn/no-thenable
+  mockDb.then = (resolve: (arg0: unknown) => void) => {
+    // Determine which call this is based on the 'from' call
+    // const lastFrom =
+    //   mockDb.from.mock.calls[mockDb.from.mock.calls.length - 1][0];
+
+    // We need to look at the schema name or some identifier.
+    // Since we are mocking the schema as well, we can check equality.
+    // However, for a simple mock, we can just alternate or use a counter.
+
+    // In enrichUser:
+    // 1. select from userRole (inner join role)
+    // 2. select from rolePermission (inner join permission) -> for each role
+
+    // Let's use a simpler approach: track call count for this specific mock instance
+    if (!mockDb._callCount) mockDb._callCount = 0;
+    mockDb._callCount++;
+
+    if (mockDb._callCount === 1) {
+      return resolve(data.roles || []);
+    }
+    return resolve(data.permissions || []);
+  };
+
+  return mockDb;
+};
+
+describe("enrichUser", () => {
+  const baseUser: User = {
+    id: "user-1",
+    email: "test@example.com",
+    emailVerified: true,
+    name: "Test User",
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+
+  it("should enrich user with admin role and wildcard permission", async () => {
+    const mockDb = createMockDb({
+      roles: [{ roleId: "admin" }],
+    });
+
+    const result = await enrichUser(baseUser, mockDb);
+
+    expect(result.roles).toContain("admin");
+    expect(result.permissions).toContain("*");
+  });
+
+  it("should enrich user with custom roles and permissions", async () => {
+    const mockDb = createMockDb({
+      roles: [{ roleId: "editor" }, { roleId: "viewer" }],
+      permissions: [{ permissionId: "blog.read" }],
+    });
+
+    // Note: Our simple mock returns the same permissions for ALL roles if there are multiple roles.
+    // In enrichUser, it loops through roles.
+    // If we have 2 roles, enrichUser will call select from rolePermission twice.
+    // Our mock needs to handle multiple calls if we want to be precise.
+
+    let callCount = 0;
+    // eslint-disable-next-line unicorn/no-thenable
+    mockDb.then = (resolve: (arg0: unknown) => void) => {
+      callCount++;
+      if (callCount === 1) return resolve([{ roleId: "editor" }]);
+      if (callCount === 2) return resolve([{ permissionId: "blog.edit" }]);
+      return resolve([]);
+    };
+
+    const result = await enrichUser(baseUser, mockDb);
+
+    expect(result.roles).toContain("editor");
+    expect(result.permissions).toContain("blog.edit");
+  });
+
+  it("should handle user with no roles", async () => {
+    const mockDb = createMockDb({
+      roles: [],
+    });
+
+    const result = await enrichUser(baseUser, mockDb);
+
+    expect(result.roles).toEqual([]);
+    expect(result.permissions).toEqual([]);
+  });
+});

package/src/utils/user.ts

@@ -0,0 +1,62 @@
+import { User } from "better-auth/types";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { eq } from "drizzle-orm";
+import type { RealUser } from "@checkstack/backend-api";
+import * as schema from "../schema";
+
+/**
+ * Enriches a better-auth User with roles and permissions from the database.
+ * Returns a RealUser type for use in the RPC context.
+ */
+export const enrichUser = async (
+  user: User,
+  db: NodePgDatabase<typeof schema>
+): Promise<RealUser> => {
+  // 1. Get Roles
+  const userRoles = await db
+    .select({
+      roleName: schema.role.name,
+      roleId: schema.role.id,
+    })
+    .from(schema.userRole)
+    .innerJoin(schema.role, eq(schema.role.id, schema.userRole.roleId))
+    .where(eq(schema.userRole.userId, user.id));
+
+  const roles = userRoles.map((r) => r.roleId);
+  const permissions = new Set<string>();
+
+  // 2. Get Permissions for each role
+  for (const roleId of roles) {
+    if (roleId === "admin") {
+      permissions.add("*");
+      continue;
+    }
+
+    const rolePermissions = await db
+      .select({
+        permissionId: schema.permission.id,
+      })
+      .from(schema.rolePermission)
+      .innerJoin(
+        schema.permission,
+        eq(schema.permission.id, schema.rolePermission.permissionId)
+      )
+      .where(eq(schema.rolePermission.roleId, roleId));
+
+    for (const p of rolePermissions) {
+      permissions.add(p.permissionId);
+    }
+  }
+
+  return {
+    // Spread user first to preserve additional properties
+    ...user,
+    // Override with required RealUser fields
+    type: "user",
+    id: user.id,
+    email: user.email,
+    name: user.name,
+    roles,
+    permissions: [...permissions],
+  };
+};

package/src/utils/validate-schema.test.ts

@@ -0,0 +1,85 @@
+import { describe, test, expect } from "bun:test";
+import { validateStrategySchema } from "./validate-schema";
+import { z } from "zod";
+
+describe("validateStrategySchema", () => {
+  test("should pass for schema with all defaults", () => {
+    const validSchema = z.object({
+      enabled: z.boolean().default(false),
+      url: z.string().default("https://example.com"),
+      timeout: z.number().default(5000),
+    });
+
+    expect(() =>
+      validateStrategySchema(validSchema, "test-strategy")
+    ).not.toThrow();
+  });
+
+  test("should pass for schema with all optional fields", () => {
+    const validSchema = z.object({
+      enabled: z.boolean().default(false),
+      url: z.string().optional(),
+      timeout: z.number().optional(),
+    });
+
+    expect(() =>
+      validateStrategySchema(validSchema, "test-strategy")
+    ).not.toThrow();
+  });
+
+  test("should throw for schema with required fields without defaults", () => {
+    const invalidSchema = z.object({
+      enabled: z.boolean().default(false),
+      url: z.string(), // Required, no default
+      baseDN: z.string(), // Required, no default
+    });
+
+    expect(() =>
+      validateStrategySchema(invalidSchema, "test-strategy")
+    ).toThrow(
+      /Strategy "test-strategy" has invalid configuration schema.*url, baseDN/
+    );
+  });
+
+  test("should throw for nested objects with required fields", () => {
+    const invalidSchema = z.object({
+      enabled: z.boolean().default(false),
+      settings: z.object({
+        host: z.string(), // Required, no default
+        port: z.number().default(443),
+      }),
+    });
+
+    expect(() =>
+      validateStrategySchema(invalidSchema, "test-strategy")
+    ).toThrow(/settings/);
+  });
+
+  test("should include helpful error message", () => {
+    const invalidSchema = z.object({
+      url: z.string(),
+    });
+
+    try {
+      validateStrategySchema(invalidSchema, "my-strategy");
+      expect.unreachable("Should have thrown");
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error);
+      const message = (error as Error).message;
+      expect(message).toContain("my-strategy");
+      expect(message).toContain("url");
+      expect(message).toContain("missing defaults");
+      expect(message).toContain("optional or have default values");
+    }
+  });
+
+  test("should pass for schema with only enabled field", () => {
+    const validSchema = z.object({
+      enabled: z.boolean().default(false),
+    });
+
+    expect(() =>
+      validateStrategySchema(validSchema, "test-strategy")
+    ).not.toThrow();
+  });
+});

package/src/utils/validate-schema.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+
+/**
+ * Validates that a Zod schema can be safely used with ConfigService.
+ * Checks for required fields without defaults that would fail when no config exists.
+ *
+ * @param schema - The Zod schema to validate
+ * @param strategyId - The strategy ID for error messages
+ * @throws Error if the schema has required fields without defaults
+ */
+export function validateStrategySchema(
+  schema: z.ZodTypeAny,
+  strategyId: string
+): void {
+  // Try to parse an empty object to see if the schema has required fields
+  const result = schema.safeParse({});
+
+  if (!result.success) {
+    const requiredFields = result.error.issues
+      .filter((err) => {
+        // Filter for invalid_type errors where undefined was received
+        if (err.code !== "invalid_type") return false;
+
+        // Use type assertion since TypeScript types don't expose 'received'
+        // but it exists at runtime for invalid_type errors
+        const received = (err as unknown as { received: unknown }).received;
+        return received === undefined;
+      })
+      .map((err) => err.path.join("."));
+
+    if (requiredFields.length > 0) {
+      throw new Error(
+        `Strategy "${strategyId}" has invalid configuration schema: ` +
+          `The following required fields are missing defaults: ${requiredFields.join(
+            ", "
+          )}. ` +
+          `All fields in a strategy schema must either be optional or have default values ` +
+          `to ensure graceful initialization when no configuration exists in the database.`
+      );
+    }
+
+    // If there are other validation errors besides missing required fields,
+    // it might be okay (e.g., format validation), so we don't throw
+  }
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ]
+}