@withmata/blueprints 0.2.0

package/blueprints/features/auth-better-auth/files/db/drizzle.config.ts

@@ -0,0 +1,21 @@
+// =============================================================================
+// Drizzle Kit Config — Auth Database
+// =============================================================================
+// Used by drizzle-kit to generate and run migrations for the auth database.
+//
+// Place this in your DB package: packages/db/drizzle/auth/drizzle.config.ts
+// =============================================================================
+
+import { config } from "dotenv";
+import { defineConfig } from "drizzle-kit";
+
+config({ path: "./.env" });
+
+const AUTH_DATABASE_URL = process.env.AUTH_DATABASE_URL!;
+
+export default defineConfig({
+  schema: "./src/auth/schema.ts",
+  out: "./drizzle/auth",
+  dialect: "postgresql", // CONFIGURE: "postgresql" | "mysql" | "sqlite"
+  dbCredentials: { url: AUTH_DATABASE_URL },
+});

package/blueprints/features/auth-better-auth/files/middleware/route-protection.ts

@@ -0,0 +1,84 @@
+// =============================================================================
+// Next.js Middleware — Route Protection
+// =============================================================================
+// Protects routes by checking for the Better Auth session cookie.
+// This is a COOKIE-PRESENCE CHECK only — actual session validation happens
+// server-side in the auth middleware.
+//
+// Route classification:
+//   - Public:    /auth/* — accessible without auth
+//   - Protected: everything else — redirects to /auth if no session cookie
+//   - Onboarding: /onboarding/* — accessible if authenticated
+//
+// Usage: Export this as middleware.ts in your Next.js app root, or integrate
+// into your existing middleware.
+// =============================================================================
+
+import type { NextRequest } from "next/server";
+import { NextResponse } from "next/server";
+
+// CONFIGURE: adjust these route lists for your app
+const publicRoutes = ["/auth", "/auth/"];
+const publicPrefixes = ["/auth/"];
+
+const onboardingRoutes = ["/onboarding", "/onboarding/"];
+const onboardingPrefixes = ["/onboarding/"];
+
+function isPublicRoute(pathname: string): boolean {
+  if (publicRoutes.includes(pathname)) return true;
+  return publicPrefixes.some((prefix) => pathname.startsWith(prefix));
+}
+
+function isOnboardingRoute(pathname: string): boolean {
+  if (onboardingRoutes.includes(pathname)) return true;
+  return onboardingPrefixes.some((prefix) => pathname.startsWith(prefix));
+}
+
+export async function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+  // Skip for static files and API routes
+  if (
+    pathname.startsWith("/_next") ||
+    pathname.startsWith("/api") ||
+    pathname.includes(".")
+  ) {
+    return NextResponse.next();
+  }
+
+  // Check for Better Auth session cookie
+  const sessionToken =
+    request.cookies.get("better-auth.session_token")?.value ||
+    request.cookies.get("__Secure-better-auth.session_token")?.value;
+
+  const isAuthenticated = !!sessionToken;
+
+  // Public routes — allow access
+  if (isPublicRoute(pathname)) {
+    // If authenticated and on /auth (exact), redirect to home
+    if (isAuthenticated && pathname === "/auth") {
+      return NextResponse.redirect(new URL("/", request.url));
+    }
+    return NextResponse.next();
+  }
+
+  // Protected routes — require auth
+  if (!isAuthenticated) {
+    const signInUrl = new URL("/auth", request.url);
+    signInUrl.searchParams.set("returnUrl", pathname);
+    return NextResponse.redirect(signInUrl);
+  }
+
+  // Onboarding routes — allow for authenticated users
+  if (isOnboardingRoute(pathname)) {
+    return NextResponse.next();
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: [
+    "/((?!api|_next/static|_next/image|favicon.ico).*)",
+  ],
+};

package/blueprints/features/auth-better-auth/files/server/auth-db.ts

@@ -0,0 +1,18 @@
+// =============================================================================
+// Auth Database Connection
+// =============================================================================
+// Creates a Drizzle ORM instance connected to the auth-specific PostgreSQL
+// database. This is separate from the app's core database.
+//
+// CONFIGURE: If using a different database driver (e.g. @neondatabase/serverless),
+// swap the import and connection setup accordingly.
+// =============================================================================
+
+import * as schema from "{{SCOPE}}/db/auth"; // CONFIGURE: your DB package path
+import { drizzle } from "drizzle-orm/node-postgres";
+import pg from "pg";
+import { env } from "./env.js";
+
+const pool = new pg.Pool({ connectionString: env.AUTH_DATABASE_URL });
+
+export const authDb = drizzle(pool, { schema });

package/blueprints/features/auth-better-auth/files/server/auth.ts

@@ -0,0 +1,159 @@
+// =============================================================================
+// Better Auth Server Configuration
+// =============================================================================
+// This is the core auth configuration. It is FRAMEWORK-AGNOSTIC — mount it on
+// Hono, Next.js API routes, Express, Fastify, or any supported platform.
+// See BLUEPRINT.md > Platform Integration for mounting instructions.
+//
+// Source: extracted from a production Turborepo monorepo.
+// =============================================================================
+
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { openAPI } from "better-auth/plugins";
+import { organization } from "better-auth/plugins/organization";
+import { Resend } from "resend"; // CONFIGURE: swap email provider if needed
+import { authDb } from "./auth-db.js";
+import { env } from "./env.js";
+
+// CONFIGURE: Replace with your email provider
+const resend = new Resend(env.RESEND_API_KEY);
+
+// Environment detection for local dev cookie fix
+const isLocalDev = env.FRONTEND_DOMAIN.includes("localhost");
+
+const auth = betterAuth({
+  // CORS: Which origins can make auth requests
+  trustedOrigins: [env.FRONTEND_DOMAIN],
+
+  emailAndPassword: {
+    enabled: true,
+    requireEmailVerification: true,
+    sendResetPassword: async ({ user, token }) => {
+      const resetUrl = `${env.FRONTEND_DOMAIN}/auth/reset-password/${token}`;
+      try {
+        await resend.emails.send({
+          from: "{{APP_NAME}} <{{EMAIL_FROM}}>", // CONFIGURE: your app name and email
+          to: user.email,
+          subject: "Reset your password",
+          html: `
+            <div style="font-family: sans-serif; max-width: 480px; margin: 0 auto; padding: 24px;">
+              <h2>Reset your password</h2>
+              <p>We received a request to reset the password for your {{APP_NAME}} account.</p>
+              <a href="${resetUrl}" style="display: inline-block; padding: 12px 24px; background-color: #000; color: #fff; text-decoration: none; border-radius: 6px; margin-top: 16px;">
+                Reset Password
+              </a>
+              <p style="margin-top: 24px; font-size: 14px; color: #666;">
+                This link expires in 1 hour. If you didn't request this, you can safely ignore this email.
+              </p>
+              <p style="margin-top: 16px; font-size: 14px; color: #666;">
+                Or copy and paste this link into your browser:<br/>
+                <a href="${resetUrl}">${resetUrl}</a>
+              </p>
+            </div>
+          `,
+        });
+      } catch (error) {
+        console.error("Failed to send reset password email:", error);
+      }
+    },
+  },
+
+  // CONFIGURE: Add/remove social providers as needed
+  // See: https://www.better-auth.com/docs/authentication/social-sign-in
+  socialProviders: {
+    google: {
+      clientId: env.GOOGLE_CLIENT_ID,
+      clientSecret: env.GOOGLE_CLIENT_SECRET,
+    },
+  },
+
+  // Database adapter — uses Drizzle with PostgreSQL
+  database: drizzleAdapter(authDb, {
+    provider: "pg", // CONFIGURE: "pg" | "mysql" | "sqlite"
+  }),
+
+  // Account linking: merge accounts when user signs in with different providers
+  account: {
+    accountLinking: {
+      enabled: true,
+    },
+  },
+
+  // Session configuration
+  session: {
+    expiresIn: 60 * 60 * 24 * 30, // CONFIGURE: 30 days default
+    updateAge: 60 * 60 * 24, // Refresh session every 24 hours
+    cookieCache: {
+      enabled: true,
+      maxAge: 60 * 5, // 5-minute cookie cache avoids DB round-trip per request
+    },
+  },
+
+  // CONFIGURE: Add custom fields to the user model
+  user: {
+    additionalFields: {
+      currentOrganizationId: {
+        type: "string",
+        required: false,
+        input: false, // Server-managed, not settable via signup
+      },
+    },
+  },
+
+  // CONFIGURE: Add/remove plugins
+  plugins: [
+    openAPI(), // Optional: exposes OpenAPI spec at /api/auth/reference
+    // CONFIGURE: Remove organization() if you don't need multi-tenancy
+    organization({
+      allowUserToCreateOrganization: true,
+      organizationLimit: 10, // CONFIGURE: max orgs per user
+      creatorRole: "owner",
+      membershipLimit: 100, // CONFIGURE: max members per org
+      disableOrganizationDeletion: true,
+      sendInvitationEmail: async (data) => {
+        const inviteUrl = `${env.FRONTEND_DOMAIN}/auth/invite/${data.id}?email=${encodeURIComponent(data.email)}`;
+        const inviterName = data.inviter.user.name;
+        const orgName = data.organization.name;
+
+        try {
+          await resend.emails.send({
+            from: "{{APP_NAME}} <{{EMAIL_FROM}}>", // CONFIGURE: your app name and email
+            to: data.email,
+            subject: `${inviterName} invited you to join ${orgName}`,
+            html: `
+              <div style="font-family: sans-serif; max-width: 480px; margin: 0 auto; padding: 24px;">
+                <h2>You're invited!</h2>
+                <p><strong>${inviterName}</strong> has invited you to join <strong>${orgName}</strong> on {{APP_NAME}}.</p>
+                <a href="${inviteUrl}" style="display: inline-block; padding: 12px 24px; background-color: #000; color: #fff; text-decoration: none; border-radius: 6px; margin-top: 16px;">
+                  Accept Invitation
+                </a>
+                <p style="margin-top: 24px; font-size: 14px; color: #666;">
+                  Or copy and paste this link into your browser:<br/>
+                  <a href="${inviteUrl}">${inviteUrl}</a>
+                </p>
+              </div>
+            `,
+          });
+        } catch (error) {
+          console.error("Failed to send invitation email:", error);
+        }
+      },
+    }),
+  ],
+
+  // Local dev: share cookies across localhost ports (e.g. frontend:3000, backend:4000)
+  // In production with proper domain setup, this isn't needed.
+  ...(isLocalDev && {
+    advanced: {
+      crossSubDomainCookies: {
+        enabled: true,
+        domain: "localhost",
+      },
+    },
+  }),
+});
+
+export type Auth = typeof auth;
+
+export default auth;

package/blueprints/features/auth-better-auth/files/server/env.ts

@@ -0,0 +1,44 @@
+// =============================================================================
+// Auth Environment Variables — Server-Side
+// =============================================================================
+// Validates auth-related environment variables at startup using t3-env + Zod.
+//
+// CONFIGURE: This is a RECOMMENDED pattern. If you prefer a different env
+// validation approach, adapt accordingly. The key requirement is that all
+// auth env vars are validated before the server starts.
+//
+// NOTE: This file only includes auth-related variables. Your project will
+// likely have additional env vars — merge them into your project's env.ts.
+// =============================================================================
+
+import "dotenv/config";
+import { createEnv } from "@t3-oss/env-core";
+import { z } from "zod";
+
+export const env = createEnv({
+  server: {
+    // Server
+    PORT: z.preprocess(
+      (str) => parseInt(String(str), 10) || undefined,
+      z.number().min(1),
+    ),
+
+    // Auth
+    FRONTEND_DOMAIN: z.url(), // Frontend URL for CORS, email links, trusted origins
+    BETTER_AUTH_URL: z.url(), // Base URL where auth API is accessible (OAuth callback target)
+    BETTER_AUTH_SECRET: z.string().min(1), // Generate with: openssl rand -base64 32
+
+    // Database
+    AUTH_DATABASE_URL: z.url(), // PostgreSQL connection URL for auth database
+
+    // Social providers — CONFIGURE: add/remove as needed
+    GOOGLE_CLIENT_ID: z.string().min(1),
+    GOOGLE_CLIENT_SECRET: z.string().min(1),
+
+    // Email — CONFIGURE: swap if using a different email provider
+    RESEND_API_KEY: z.string().min(1),
+  },
+
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+});

package/blueprints/features/auth-better-auth/files/server/middleware.ts

@@ -0,0 +1,144 @@
+// =============================================================================
+// Auth Middleware — Hono Reference Implementation
+// =============================================================================
+// This file provides two middleware functions for protecting API routes:
+//   - requireAuth()         — validates session, attaches user to context
+//   - requireOrganization() — validates session + active org membership
+//
+// FRAMEWORK NOTE: This is a Hono implementation. The core pattern is
+// framework-agnostic — `auth.api.getSession({ headers })` works anywhere.
+// Adapt the middleware wrapper for your framework. See BLUEPRINT.md > Platform
+// Integration for examples with Next.js, Express, etc.
+// =============================================================================
+
+import type { Context, MiddlewareHandler, Next } from "hono";
+import auth from "./auth.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type SessionUser = {
+  id: string;
+  email: string;
+  name: string;
+  emailVerified: boolean;
+  image?: string | null;
+  currentOrganizationId?: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+};
+
+export type Session = {
+  id: string;
+  userId: string;
+  token: string;
+  expiresAt: Date;
+  createdAt: Date;
+  updatedAt: Date;
+  ipAddress?: string | null;
+  userAgent?: string | null;
+  activeOrganizationId?: string | null;
+};
+
+export type AuthContext = {
+  user: SessionUser;
+  session: Session;
+};
+
+// ============================================================================
+// Middleware
+// ============================================================================
+
+/**
+ * Validates the session and attaches user info to context.
+ * Returns 401 if no valid session is found.
+ */
+export function requireAuth(): MiddlewareHandler<{
+  Variables: { auth: AuthContext };
+}> {
+  return async (c: Context, next: Next) => {
+    try {
+      // Framework-agnostic core: auth.api.getSession({ headers })
+      const sessionData = await auth.api.getSession({
+        headers: c.req.raw.headers,
+      });
+
+      if (!sessionData || !sessionData.user) {
+        return c.json(
+          { error: "Unauthorized", message: "Valid session required" },
+          401,
+        );
+      }
+
+      c.set("auth", {
+        user: sessionData.user as SessionUser,
+        session: sessionData.session as Session,
+      });
+
+      await next();
+    } catch (error) {
+      console.error("Auth middleware error:", error);
+      return c.json(
+        { error: "Unauthorized", message: "Session validation failed" },
+        401,
+      );
+    }
+  };
+}
+
+/**
+ * Validates session AND checks for active organization.
+ * Returns 401 if no session, 403 if no active organization.
+ *
+ * CONFIGURE: Remove this if not using the organization plugin.
+ */
+export function requireOrganization(): MiddlewareHandler<{
+  Variables: { auth: AuthContext; organizationId: string };
+}> {
+  return async (c: Context, next: Next) => {
+    try {
+      const sessionData = await auth.api.getSession({
+        headers: c.req.raw.headers,
+      });
+
+      if (!sessionData || !sessionData.user) {
+        return c.json(
+          { error: "Unauthorized", message: "Valid session required" },
+          401,
+        );
+      }
+
+      const organizationId = sessionData.session.activeOrganizationId;
+
+      if (!organizationId) {
+        return c.json(
+          { error: "Forbidden", message: "Active organization required" },
+          403,
+        );
+      }
+
+      c.set("auth", {
+        user: sessionData.user as SessionUser,
+        session: sessionData.session as Session,
+      });
+      c.set("organizationId", organizationId);
+
+      await next();
+    } catch (error) {
+      console.error("Auth middleware error:", error);
+      return c.json(
+        { error: "Unauthorized", message: "Session validation failed" },
+        401,
+      );
+    }
+  };
+}
+
+/**
+ * Helper to extract auth context from Hono context in route handlers.
+ * Assumes requireAuth() middleware has already run.
+ */
+export function getAuthContext(c: Context): AuthContext {
+  return c.get("auth") as AuthContext;
+}