create-bcp-app 0.1.7 → 0.1.9

package/README.md

@@ -18,6 +18,9 @@ Select a database:
   3) PostgreSQL
   4) SQLite
   5) MongoDB
+Select authentication:
+  1) None
+  2) JWT Cookie
 ```
 
 ## Generated application defaults
@@ -75,8 +78,71 @@ import "bcp/server-only";
 
 This prevents database code from being used in a page/client module graph. Query the database from an API route and call that API from client components.
 
+For MySQL, the generated helper exports a reusable `db` pool and caches that pool on `globalThis` during development so hot reloads do not create a new connection pool every time:
+
+```ts
+import {
+    db,
+} from "@/lib/database";
+
+const [rows] =
+    await db.query(
+        "SELECT 1"
+    );
+```
+
+The generated MySQL `.env.example` uses separate connection settings:
+
+```dotenv
+DB_HOST=localhost
+DB_PORT=3306
+DB_USER=
+DB_PASSWORD=
+DB_NAME=bcp_app
+```
+
 The generator intentionally installs database drivers directly and does not force an ORM.
 
+### JWT Cookie authentication
+
+Selecting `JWT Cookie` creates a secure-by-default authentication foundation:
+
+```text
+lib/
+└─ auth.ts
+
+app/api/auth/
+├─ login/route.ts
+├─ logout/route.ts
+└─ me/route.ts
+```
+
+The preset uses the session primitives from `bcp/server` and adds this environment variable:
+
+```dotenv
+BCP_SESSION_SECRET=
+```
+
+Set `BCP_SESSION_SECRET` to a cryptographically random secret of at least 32 bytes before using authentication.
+
+The generated `authenticateCredentials(email, password)` intentionally returns `null` until the application connects it to its own user table and password-hash verification. This prevents a newly generated application from accepting unverified credentials or trusting identity data sent directly by the browser.
+
+After implementing credential verification, the generated flow is:
+
+```text
+POST /api/auth/login
+  -> authenticateCredentials()
+  -> createSession()
+  -> HttpOnly JWT cookie
+
+GET /api/auth/me
+  -> getSession()
+  -> current user
+
+POST /api/auth/logout
+  -> destroySession()
+```
+
 ## Options
 
 ```text
@@ -84,7 +150,8 @@ The generator intentionally installs database drivers directly and does not forc
 --tailwind                Enable Tailwind CSS without prompting
 --no-tailwind             Disable Tailwind CSS without prompting
 --database <database>     none | mysql | postgresql | sqlite | mongodb
--y, --yes                 Accept defaults (Tailwind enabled, no database)
+--auth <preset>           none | jwt-cookie
+-y, --yes                 Accept defaults (Tailwind enabled, no database, no auth)
 --bcp <specifier>         Override dependencies.bcp
 -h, --help                Show help
 ```
@@ -92,13 +159,14 @@ The generator intentionally installs database drivers directly and does not forc
 Examples:
 
 ```bash
-npx create-bcp-app my-app --tailwind --database mysql
+npx create-bcp-app my-app --tailwind --database mysql --auth jwt-cookie
 npx create-bcp-app my-app --no-tailwind --database mongodb
+npx create-bcp-app my-app --auth jwt-cookie
 npx create-bcp-app my-app --yes
 ```
 
 The `--bcp` option is primarily useful for prerelease and local package testing, for example:
 
 ```bash
-npx create-bcp-app my-app --bcp file:../bcp-0.1.7.tgz
+npx create-bcp-app my-app --bcp file:../bcp-0.1.8.tgz
 ```

package/bin/create-bcp-app.mjs

@@ -14,7 +14,9 @@ import {
     createBcpApp,
 } from "../src/index.mjs";
 import {
+    AUTH_CHOICES,
     DATABASE_CHOICES,
+    normalizeAuth,
     normalizeDatabase,
 } from "../src/project-options.mjs";
 
@@ -39,6 +41,8 @@ let tailwind =
     undefined;
 let database =
     undefined;
+let auth =
+    undefined;
 let acceptDefaults =
     false;
 
@@ -105,6 +109,28 @@ for (
         continue;
     }
 
+    if (
+        value === "--auth"
+    ) {
+        const nextValue =
+            args[
+                index + 1
+            ];
+
+        if (!nextValue) {
+            fail(
+                "--auth requires a value."
+            );
+        }
+
+        auth =
+            normalizeAuth(
+                nextValue
+            );
+        index++;
+        continue;
+    }
+
     if (
         value === "--bcp"
     ) {
@@ -156,6 +182,7 @@ if (!projectDirectory) {
             await resolveInteractiveOptions({
                 tailwind,
                 database,
+                auth,
                 acceptDefaults,
             });
 
@@ -168,6 +195,8 @@ if (!projectDirectory) {
                     selected.tailwind,
                 database:
                     selected.database,
+                auth:
+                    selected.auth,
                 packageManager:
                     "npm",
             });
@@ -191,6 +220,9 @@ if (!projectDirectory) {
         console.log(
             `Database: ${formatDatabaseName(result.database)}`
         );
+        console.log(
+            `Authentication: ${formatAuthName(result.auth)}`
+        );
         console.log("");
         console.log(
             "Next steps:"
@@ -221,12 +253,15 @@ if (!projectDirectory) {
 async function resolveInteractiveOptions({
     tailwind: selectedTailwind,
     database: selectedDatabase,
+    auth: selectedAuth,
     acceptDefaults: useDefaults,
 }) {
     let resolvedTailwind =
         selectedTailwind;
     let resolvedDatabase =
         selectedDatabase;
+    let resolvedAuth =
+        selectedAuth;
 
     const interactive =
         Boolean(
@@ -244,6 +279,11 @@ async function resolveInteractiveOptions({
                     resolvedDatabase ??
                     "none"
                 ),
+            auth:
+                normalizeAuth(
+                    resolvedAuth ??
+                    "none"
+                ),
         };
     }
 
@@ -257,6 +297,11 @@ async function resolveInteractiveOptions({
                     resolvedDatabase ??
                     "none"
                 ),
+            auth:
+                normalizeAuth(
+                    resolvedAuth ??
+                    "none"
+                ),
         };
     }
 
@@ -294,6 +339,16 @@ async function resolveInteractiveOptions({
                     prompt
                 );
         }
+
+        if (
+            resolvedAuth ===
+            undefined
+        ) {
+            resolvedAuth =
+                await askAuth(
+                    prompt
+                );
+        }
     } finally {
         prompt.close();
     }
@@ -307,6 +362,10 @@ async function resolveInteractiveOptions({
             normalizeDatabase(
                 resolvedDatabase
             ),
+        auth:
+            normalizeAuth(
+                resolvedAuth
+            ),
     };
 }
 
@@ -427,6 +486,77 @@ async function askDatabase(
     }
 }
 
+async function askAuth(
+    prompt
+) {
+    const labels = {
+        none: "None",
+        "jwt-cookie":
+            "JWT Cookie",
+    };
+
+    console.log(
+        "Select authentication:"
+    );
+
+    AUTH_CHOICES.forEach(
+        (
+            value,
+            index
+        ) => {
+            console.log(
+                `  ${index + 1}) ${labels[value]}`
+            );
+        }
+    );
+
+    while (true) {
+        const answer =
+            (
+                await prompt.question(
+                    "Authentication (1): "
+                )
+            ).trim();
+
+        if (!answer) {
+            return "none";
+        }
+
+        const index =
+            Number(
+                answer
+            ) - 1;
+
+        if (
+            Number.isInteger(
+                index
+            ) &&
+            index >= 0 &&
+            index <
+                AUTH_CHOICES.length
+        ) {
+            return AUTH_CHOICES[
+                index
+            ];
+        }
+
+        const normalized =
+            answer.toLowerCase();
+
+        if (
+            AUTH_CHOICES.includes(
+                normalized
+            )
+        ) {
+            return normalized;
+        }
+
+        console.log(
+            "Choose a number from the list or enter an authentication preset name."
+        );
+    }
+}
+
 function formatDatabaseName(
     value
 ) {
@@ -442,6 +572,19 @@ function formatDatabaseName(
         value;
 }
 
+function formatAuthName(
+    value
+) {
+    const names = {
+        none: "None",
+        "jwt-cookie":
+            "JWT Cookie",
+    };
+
+    return names[value] ??
+        value;
+}
+
 function printHelp() {
     console.log(`
 create-bcp-app
@@ -452,23 +595,25 @@ Usage:
 Interactive setup:
   - Choose whether to use Tailwind CSS
   - Choose a database: None, MySQL, PostgreSQL, SQLite or MongoDB
+  - Choose authentication: None or JWT Cookie
 
 Options:
   --no-install              Create files without running npm install
   --tailwind                Enable Tailwind CSS without prompting
   --no-tailwind             Disable Tailwind CSS without prompting
   --database <database>     none | mysql | postgresql | sqlite | mongodb
-  -y, --yes                 Accept defaults (Tailwind enabled, no database)
+  --auth <preset>           none | jwt-cookie
+  -y, --yes                 Accept defaults (Tailwind enabled, no database, no auth)
   --bcp <specifier>         Override the package specifier stored under dependencies.bcp
   -h, --help                Show this help message
 
 Examples:
   npx create-bcp-app my-app
-  npx create-bcp-app my-app --tailwind --database mysql
+  npx create-bcp-app my-app --tailwind --database mysql --auth jwt-cookie
   npx create-bcp-app my-app --no-tailwind --database mongodb
   npx create-bcp-app my-app --yes
   npx create-bcp-app my-app --no-install
-  npx create-bcp-app my-app --bcp file:../bcp-0.1.2.tgz
+  npx create-bcp-app my-app --bcp file:../bcp-0.1.8.tgz
 `);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bcp-app",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Create a new BCP Framework application.",
   "type": "module",
   "license": "MIT",

package/src/index.d.mts

@@ -5,12 +5,17 @@ export type BcpDatabase =
     | "sqlite"
     | "mongodb";
 
+export type BcpAuthPreset =
+    | "none"
+    | "jwt-cookie";
+
 export interface CreateBcpAppOptions {
     projectDirectory: string;
     install?: boolean;
     bcpPackage?: string;
     tailwind?: boolean;
     database?: BcpDatabase;
+    auth?: BcpAuthPreset;
     packageManager?: "npm";
 }
 
@@ -20,6 +25,7 @@ export interface CreateBcpAppResult {
     packageSpecifier: string;
     tailwind: boolean;
     database: BcpDatabase;
+    auth: BcpAuthPreset;
 }
 
 export function createBcpApp(

package/src/index.mjs

@@ -9,6 +9,7 @@ import {
 
 import {
     applyProjectOptions,
+    normalizeAuth,
     normalizeDatabase,
 } from "./project-options.mjs";
 
@@ -42,6 +43,10 @@ export async function createBcpApp(
         normalizeDatabase(
             options.database
         );
+    const auth =
+        normalizeAuth(
+            options.auth
+        );
 
     ensureTargetDirectory(
         targetDirectory
@@ -119,6 +124,7 @@ export async function createBcpApp(
             packageJson,
             tailwind,
             database,
+            auth,
         });
 
     fs.writeFileSync(
@@ -152,6 +158,8 @@ export async function createBcpApp(
             selectedOptions.tailwind,
         database:
             selectedOptions.database,
+        auth:
+            selectedOptions.auth,
     };
 }
 

package/src/project-options.mjs

@@ -9,6 +9,11 @@ export const DATABASE_CHOICES = [
     "mongodb",
 ];
 
+export const AUTH_CHOICES = [
+    "none",
+    "jwt-cookie",
+];
+
 const DATABASE_PRESETS = {
     mysql: {
         dependencies: {
@@ -16,25 +21,68 @@ const DATABASE_PRESETS = {
         },
         devDependencies: {},
         env: [
-            "DATABASE_URL=mysql://root:password@localhost:3306/bcp_app",
+            "DB_HOST=localhost",
+            "DB_PORT=3306",
+            "DB_USER=",
+            "DB_PASSWORD=",
+            "DB_NAME=bcp_app",
         ],
         source: `import "bcp/server-only";
 
 import mysql from "mysql2/promise";
 
-const connectionString =
-    process.env.DATABASE_URL;
+const globalForDatabase =
+    globalThis as typeof globalThis & {
+        __bcpDb?: mysql.Pool;
+    };
 
-if (!connectionString) {
-    throw new Error(
-        "DATABASE_URL is required for MySQL."
-    );
+export const db =
+    globalForDatabase.__bcpDb ??
+    mysql.createPool({
+        host:
+            process.env.DB_HOST ??
+            "localhost",
+
+        port:
+            Number(
+                process.env.DB_PORT ??
+                3306
+            ),
+
+        user:
+            process.env.DB_USER ??
+            "root",
+
+        password:
+            process.env.DB_PASSWORD ??
+            "",
+
+        database:
+            process.env.DB_NAME ??
+            "bcp_app",
+
+        waitForConnections:
+            true,
+
+        connectionLimit:
+            10,
+
+        queueLimit:
+            0,
+
+        charset:
+            "utf8mb4",
+    });
+
+if (
+    process.env.NODE_ENV !==
+    "production"
+) {
+    globalForDatabase.__bcpDb =
+        db;
 }
 
-export const db =
-    mysql.createPool(
-        connectionString
-    );
+export default db;
 `,
     },
     postgresql: {
@@ -149,6 +197,241 @@ export async function getDatabase() {
     },
 };
 
+const JWT_COOKIE_AUTH_FILES = {
+    "lib/auth.ts": `import "bcp/server-only";
+
+import {
+    createSession,
+    destroySession,
+    getSession,
+} from "bcp/server";
+
+export interface AuthenticatedUser {
+    id: string | number;
+    email: string;
+    role?: string;
+}
+
+export interface UserSession {
+    userId: string | number;
+    email: string;
+    role?: string;
+}
+
+export async function authenticateCredentials(
+    email: string,
+    password: string
+): Promise<AuthenticatedUser | null> {
+    /*
+     * Secure starter behavior: authentication is disabled until the
+     * application verifies the supplied credentials against its own user
+     * store and password-hash strategy.
+     */
+    void email;
+    void password;
+
+    return null;
+}
+
+export async function createUserSession(
+    user: AuthenticatedUser
+): Promise<void> {
+    await createSession({
+        userId:
+            user.id,
+        email:
+            user.email,
+        ...(user.role === undefined
+            ? {}
+            : {
+                role:
+                    user.role,
+            }),
+    });
+}
+
+export function getCurrentUser() {
+    return getSession<UserSession>();
+}
+
+export function clearUserSession() {
+    return destroySession();
+}
+`,
+    "app/api/auth/login/route.ts": `import {
+    json,
+} from "bcp/server";
+
+import {
+    authenticateCredentials,
+    createUserSession,
+} from "@/lib/auth";
+
+export async function POST(
+    request: Request
+) {
+    let body: unknown;
+
+    try {
+        body =
+            await request.json();
+    } catch {
+        return json(
+            {
+                error:
+                    "Invalid JSON body.",
+            },
+            {
+                status:
+                    400,
+            }
+        );
+    }
+
+    if (
+        !body ||
+        typeof body !== "object" ||
+        Array.isArray(body)
+    ) {
+        return json(
+            {
+                error:
+                    "Email and password are required.",
+            },
+            {
+                status:
+                    400,
+            }
+        );
+    }
+
+    const input =
+        body as Record<
+            string,
+            unknown
+        >;
+    const email =
+        typeof input.email ===
+            "string"
+            ? input.email.trim()
+            : "";
+    const password =
+        typeof input.password ===
+            "string"
+            ? input.password
+            : "";
+
+    if (
+        !email ||
+        !password
+    ) {
+        return json(
+            {
+                error:
+                    "Email and password are required.",
+            },
+            {
+                status:
+                    400,
+            }
+        );
+    }
+
+    const user =
+        await authenticateCredentials(
+            email,
+            password
+        );
+
+    if (!user) {
+        return json(
+            {
+                error:
+                    "Invalid credentials.",
+            },
+            {
+                status:
+                    401,
+            }
+        );
+    }
+
+    await createUserSession(
+        user
+    );
+
+    return json({
+        success:
+            true,
+        user: {
+            id:
+                user.id,
+            email:
+                user.email,
+            role:
+                user.role ??
+                null,
+        },
+    });
+}
+`,
+    "app/api/auth/logout/route.ts": `import {
+    json,
+} from "bcp/server";
+
+import {
+    clearUserSession,
+} from "@/lib/auth";
+
+export async function POST() {
+    await clearUserSession();
+
+    return json({
+        success:
+            true,
+    });
+}
+`,
+    "app/api/auth/me/route.ts": `import {
+    json,
+} from "bcp/server";
+
+import {
+    getCurrentUser,
+} from "@/lib/auth";
+
+export async function GET() {
+    const session =
+        await getCurrentUser();
+
+    if (!session) {
+        return json(
+            {
+                error:
+                    "Unauthorized.",
+            },
+            {
+                status:
+                    401,
+            }
+        );
+    }
+
+    return json({
+        user: {
+            id:
+                session.userId,
+            email:
+                session.email,
+            role:
+                session.role ??
+                null,
+        },
+    });
+}
+`,
+};
+
 export function normalizeDatabase(
     value
 ) {
@@ -172,16 +455,44 @@ export function normalizeDatabase(
     return normalized;
 }
 
+export function normalizeAuth(
+    value
+) {
+    const normalized =
+        String(
+            value ?? "none"
+        )
+            .trim()
+            .toLowerCase();
+
+    if (
+        !AUTH_CHOICES.includes(
+            normalized
+        )
+    ) {
+        throw new Error(
+            `Unsupported authentication preset: ${normalized}. Choose one of: ${AUTH_CHOICES.join(", ")}.`
+        );
+    }
+
+    return normalized;
+}
+
 export function applyProjectOptions({
     targetDirectory,
     packageJson,
     tailwind = false,
     database = "none",
+    auth = "none",
 }) {
     const selectedDatabase =
         normalizeDatabase(
             database
         );
+    const selectedAuth =
+        normalizeAuth(
+            auth
+        );
 
     if (tailwind) {
         configureTailwind(
@@ -214,7 +525,17 @@ export function applyProjectOptions({
         );
         appendEnvExample(
             targetDirectory,
-            preset.env
+            preset.env,
+            "Database"
+        );
+    }
+
+    if (
+        selectedAuth ===
+        "jwt-cookie"
+    ) {
+        configureJwtCookieAuth(
+            targetDirectory
         );
     }
 
@@ -225,9 +546,39 @@ export function applyProjectOptions({
             ),
         database:
             selectedDatabase,
+        auth:
+            selectedAuth,
     };
 }
 
+function configureJwtCookieAuth(
+    targetDirectory
+) {
+    for (
+        const [
+            relativePath,
+            source,
+        ]
+        of Object.entries(
+            JWT_COOKIE_AUTH_FILES
+        )
+    ) {
+        writeFile(
+            targetDirectory,
+            relativePath,
+            source
+        );
+    }
+
+    appendEnvExample(
+        targetDirectory,
+        [
+            "BCP_SESSION_SECRET=",
+        ],
+        "Authentication"
+    );
+}
+
 function configureTailwind(
     targetDirectory,
     packageJson
@@ -415,7 +766,8 @@ function appendGitIgnore(
 
 function appendEnvExample(
     targetDirectory,
-    lines
+    lines,
+    section
 ) {
     const filePath =
         path.join(
@@ -434,7 +786,7 @@ function appendEnvExample(
 
     fs.writeFileSync(
         filePath,
-        `${current}${current ? "\n\n" : ""}# Database\n${lines.join("\n")}\n`,
+        `${current}${current ? "\n\n" : ""}# ${section}\n${lines.join("\n")}\n`,
         "utf8"
     );
 }