@chidchanun/bcp 0.1.14 → 0.1.16

package/docs/authentication.md

@@ -0,0 +1,201 @@
+# Authentication
+
+BCP Framework 0.1.16 adds a server-only authentication layer through `bcp/auth`.
+It builds on the signed JWT cookie/session primitives from `bcp/server` and provides a higher-level API for application authentication.
+
+## Environment
+
+Set a session secret with at least 32 bytes:
+
+```env
+BCP_SESSION_SECRET=replace-with-a-long-random-secret-at-least-32-bytes
+```
+
+The default cookie is `bcp_session`. It is HttpOnly, uses `SameSite=Lax`, has a 12-hour lifetime, and is Secure automatically when `NODE_ENV=production`.
+
+## Basic usage
+
+```ts
+import {
+    auth,
+    login,
+    logout,
+} from "bcp/auth";
+
+export async function POST() {
+    await login({
+        id: 42,
+        email: "user@example.com",
+        role: "admin",
+    });
+
+    return Response.json({
+        ok: true,
+    });
+}
+```
+
+Read the current authenticated session:
+
+```ts
+import {
+    auth,
+} from "bcp/auth";
+
+const session =
+    await auth<{
+        id: number;
+        email: string;
+        role: string;
+    }>();
+
+if (!session) {
+    // Not authenticated.
+}
+
+console.log(
+    session?.user.id
+);
+```
+
+`getSession()` is an alias for `auth()` when that naming is clearer in application code.
+
+## Typed auth factory
+
+For application-wide types and cookie settings, create a typed auth instance:
+
+```ts
+import {
+    createAuth,
+} from "bcp/auth";
+
+interface AppUser {
+    id: number;
+    email: string;
+    role: "admin" | "user";
+}
+
+interface AppSessionData {
+    tenantId: string;
+}
+
+export const appAuth =
+    createAuth<
+        AppUser,
+        AppSessionData
+    >({
+        cookieName:
+            "app_session",
+        expiresIn:
+            60 * 60 * 8,
+        issuer:
+            "my-app",
+        audience:
+            "web",
+    });
+```
+
+Login with typed session data:
+
+```ts
+await appAuth.login(
+    {
+        id: 42,
+        email: "user@example.com",
+        role: "admin",
+    },
+    {
+        data: {
+            tenantId:
+                "tenant-1",
+        },
+    }
+);
+```
+
+Read it later:
+
+```ts
+const session =
+    await appAuth.auth();
+
+console.log(
+    session?.user.email
+);
+console.log(
+    session?.data?.tenantId
+);
+```
+
+## Logout
+
+```ts
+await logout();
+```
+
+Or with a factory:
+
+```ts
+await appAuth.logout();
+```
+
+Logout expires the configured authentication cookie.
+
+## Session rotation
+
+Each auth login receives a unique `sid` (session identifier). `rotateSession()` keeps the current user and session data but issues a new `sid`, JWT, expiry window, and cookie.
+
+```ts
+const rotated =
+    await appAuth.rotateSession();
+
+if (rotated) {
+    console.log(
+        rotated.sid
+    );
+}
+```
+
+Rotation returns `null` when no valid auth session exists.
+
+A useful policy is to rotate after a security-sensitive event such as a privilege change or successful re-authentication.
+
+## Session shape
+
+An authenticated session contains the user, optional application session data, and signed JWT claims:
+
+```ts
+{
+    sid: string;
+    user: AppUser;
+    data?: AppSessionData;
+    iat: number;
+    exp: number;
+    iss?: string;
+    aud?: string | string[];
+}
+```
+
+## Security notes
+
+- `bcp/auth` is server-only and must not be imported into pages or client islands.
+- Never put passwords, password hashes, API secrets, access keys, or other sensitive credentials in the auth user/session payload. JWT cookie payloads are signed, not encrypted.
+- Keep `BCP_SESSION_SECRET` out of source control and use a strong random value of at least 32 bytes.
+- Authentication verifies identity/session state. Application authorization such as roles and permissions belongs in route guards or server actions.
+- Use HTTPS in production so Secure cookies are transmitted only over encrypted connections.
+
+## create-bcp-app
+
+When `JWT Cookie` authentication is selected, generated applications use `createAuth()` internally and expose helpers from `lib/auth.ts`:
+
+```ts
+import {
+    auth,
+    getSession,
+    login,
+    logout,
+    rotateSession,
+} from "@/lib/auth";
+```
+
+The generated `authenticateCredentials()` intentionally returns `null` until the application implements its own user lookup and password verification strategy.

package/docs/database-migrations.md

@@ -0,0 +1,105 @@
+# Database Migrations
+
+BCP Framework `0.1.15` adds MySQL migration commands to the `bcp` CLI.
+
+## Requirements
+
+Database migrations currently use the MySQL adapter from `bcp/database`.
+
+Configure the same environment variables used by your application:
+
+```env
+DB_HOST=localhost
+DB_PORT=3306
+DB_USER=root
+DB_PASSWORD=
+DB_NAME=bcp_app
+```
+
+A project using migrations must have `mysql2` installed. Applications created with the MySQL preset already include it.
+
+## Create a migration
+
+```bash
+bcp db create create_users
+```
+
+BCP creates an ordered TypeScript file in `migrations/`:
+
+```text
+migrations/
+  20260827040506_create_users.ts
+```
+
+A generated migration exports `up()` and `down()`:
+
+```ts
+import type {
+    TransactionDatabase,
+} from "bcp/database";
+
+export async function up(
+    db: TransactionDatabase
+): Promise<void> {
+    await db.execute(`
+        CREATE TABLE users (
+            id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+            email VARCHAR(255) NOT NULL UNIQUE
+        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+    `);
+}
+
+export async function down(
+    db: TransactionDatabase
+): Promise<void> {
+    await db.execute(
+        "DROP TABLE users"
+    );
+}
+```
+
+Migration filenames use a UTC timestamp prefix so migrations have a stable execution order.
+
+## Run pending migrations
+
+```bash
+bcp db migrate
+```
+
+BCP creates the internal `_bcp_migrations` table when needed, detects files that have not been applied, and runs all pending migrations in filename order.
+
+All migrations applied by one `bcp db migrate` command share the same batch number. Each individual migration runs inside its own database transaction. The migration record is inserted in the same transaction as `up()`.
+
+## Check status
+
+```bash
+bcp db status
+```
+
+The command reports applied and pending migration files together with the batch number for applied migrations.
+
+## Roll back
+
+```bash
+bcp db rollback
+```
+
+Rollback reverses only the latest migration batch. Migrations in that batch run from newest to oldest, and each `down()` runs in a transaction together with removal of its migration record.
+
+BCP refuses to roll back an applied migration when its migration file is missing.
+
+## Project root
+
+All database commands support the normal BCP project-root option:
+
+```bash
+bcp db status --root ./apps/admin
+```
+
+## Environment files
+
+Database commands load the BCP development environment files before connecting, so the same local database settings used by `bcp dev` can be reused by migration commands.
+
+## Current scope
+
+`0.1.15` migration execution supports MySQL. PostgreSQL, SQLite and MongoDB presets remain available to `create-bcp-app`, but framework-managed migrations for those adapters are planned for later releases.

package/docs/releases/0.1.16.md

@@ -0,0 +1,53 @@
+# BCP Framework 0.1.16
+
+## Authentication Core
+
+BCP 0.1.16 introduces the server-only `bcp/auth` entrypoint.
+
+### New APIs
+
+- `auth()` reads and validates the current authentication session.
+- `getSession()` is an auth-focused alias for `auth()`.
+- `login(user, options)` creates an authenticated JWT cookie session.
+- `logout(options)` expires the authentication cookie.
+- `rotateSession(options)` preserves the authenticated user/session data while issuing a new session identifier and token.
+- `createAuth<User, SessionData>(defaults)` creates a typed application auth instance with shared cookie/token configuration.
+
+### Session identity
+
+Every login now receives a random UUID `sid`. Session rotation always issues a new `sid`, so rotation produces a distinct signed token even if it happens within the same second.
+
+### Security
+
+- `bcp/auth` is exported as server-only in the package manifest.
+- The client-boundary validator blocks `bcp/auth` from page/client graphs.
+- The same validator now explicitly blocks direct `bcp/database` imports from client graphs as well.
+- Existing JWT signing, expiration, issuer/audience validation, HttpOnly cookies, production Secure defaults, and minimum 32-byte session secrets remain provided by the underlying session runtime.
+
+### create-bcp-app
+
+The JWT Cookie preset now uses the framework auth core through `createAuth()` while keeping the existing starter helper names and API routes compatible.
+
+Generated `lib/auth.ts` also exposes:
+
+```ts
+export const auth = frameworkAuth.auth;
+export const getSession = frameworkAuth.getSession;
+export const login = frameworkAuth.login;
+export const logout = frameworkAuth.logout;
+export const rotateSession = frameworkAuth.rotateSession;
+```
+
+`authenticateCredentials()` still returns `null` until the application implements its own user lookup and password verification.
+
+### Tests
+
+0.1.16 adds regression coverage for:
+
+- typed login/read/logout lifecycle;
+- typed `createAuth()` defaults;
+- session rotation and changing `sid` values;
+- invalid auth payload rejection;
+- published `bcp/auth` export wiring;
+- client-boundary blocking for auth/database;
+- JWT Cookie scaffold integration with the framework auth core.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",
@@ -48,6 +48,11 @@
       "browser": "./packages/client/src/server-only.browser.mjs",
       "default": "./packages/client/src/database.ts"
     },
+    "./auth": {
+      "types": "./packages/client/src/auth.ts",
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/auth.ts"
+    },
     "./server": {
       "types": "./packages/client/src/server.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",

package/packages/bundler/src/client-boundary.ts

@@ -22,7 +22,13 @@ const MODULE_EXTENSIONS = [
     ".cjs",
 ] as const;
 
-const SERVER_ONLY_IMPORTS = new Set(["bcp/server","bcp/server-only"])
+const SERVER_ONLY_IMPORTS =
+    new Set([
+        "bcp/server",
+        "bcp/server-only",
+        "bcp/database",
+        "bcp/auth",
+    ]);
 
 export function validateClientBoundaries(
     routes: Route[],
@@ -129,13 +135,17 @@ function visitClientModule(
             source
         )
     ) {
-        if (SERVER_ONLY_IMPORTS.has(specifier)){
+        if (
+            SERVER_ONLY_IMPORTS.has(
+                specifier
+            )
+        ) {
             throw new Error(
                 `BCP Framework: ${formatApplicationPath(
                     rootDirectory,
                     filePath
                 )} imports ${specifier} but is reachable from the client bundle for ${routeName}. Move the server dependency behind an API route.`
-            )
+            );
         }
 
         const dependency =

package/packages/cli/src/args.ts

@@ -7,9 +7,17 @@ export type CliCommand =
   | "start"
   | "routes"
   | "update"
+  | "db"
   | "help"
   | "version";
 
+export type DatabaseCliAction =
+  | "migrate"
+  | "status"
+  | "rollback"
+  | "create"
+  | "help";
+
 export interface CliOptions {
   command: CliCommand;
 
@@ -24,6 +32,10 @@ export interface CliOptions {
   updateCheck?: boolean;
 
   updateDryRun?: boolean;
+
+  dbAction?: DatabaseCliAction;
+
+  dbMigrationName?: string;
 }
 
 export function parseCliArgs(
@@ -49,6 +61,12 @@ export function parseCliArgs(
   let updateDryRun =
     false;
 
+  let dbAction:
+    DatabaseCliAction | undefined;
+
+  let dbMigrationName:
+    string | undefined;
+
   let commandSet = false;
 
   for (
@@ -62,7 +80,14 @@ export function parseCliArgs(
       argument === "-h" ||
       argument === "--help"
     ) {
-      command = "help";
+      if (
+        commandSet &&
+        command === "db"
+      ) {
+        dbAction = "help";
+      } else {
+        command = "help";
+      }
       continue;
     }
 
@@ -221,6 +246,44 @@ export function parseCliArgs(
       continue;
     }
 
+    if (
+      commandSet &&
+      command === "db"
+    ) {
+      if (
+        dbAction === undefined
+      ) {
+        if (
+          argument === "migrate" ||
+          argument === "status" ||
+          argument === "rollback" ||
+          argument === "create" ||
+          argument === "help"
+        ) {
+          dbAction =
+            argument;
+          continue;
+        }
+
+        throw new Error(
+          `Unknown database command: ${argument}`
+        );
+      }
+
+      if (
+        dbAction === "create" &&
+        dbMigrationName === undefined
+      ) {
+        dbMigrationName =
+          argument;
+        continue;
+      }
+
+      throw new Error(
+        `Unexpected argument: ${argument}`
+      );
+    }
+
     if (commandSet) {
       throw new Error(
         `Unexpected argument: ${argument}`
@@ -233,6 +296,7 @@ export function parseCliArgs(
       argument === "start" ||
       argument === "routes" ||
       argument === "update" ||
+      argument === "db" ||
       argument === "help" ||
       argument === "version"
     ) {
@@ -266,6 +330,12 @@ export function parseCliArgs(
     updateTarget,
     updateCheck,
     updateDryRun,
+    ...(command === "db"
+      ? {
+          dbAction,
+          dbMigrationName,
+        }
+      : {}),
   };
 }