create-aziz-app 3.1.1 → 3.1.3

package/template/docs/11-authentication.md

@@ -1,171 +1,171 @@
-# 11 · Authentication
-
-There's no built-in auth. Because API routes run in Node and the browser client is flexible, you can add JWT-based, session-based (cookies), or OAuth flows yourself.
-
-## Principles
-
-- **Don't trust the browser.** Auth must be checked in **API routes** (server), not just hidden in UI.
-- **Protect routes.** Return `401`/`403` from API handlers when unauthorized.
-- **Send credentials in requests.** Use `Authorization: Bearer <token>` or rely on `HttpOnly` cookies.
-- **Keep secrets in `.env`.** Never put `JWT_SECRET` in page/components.
-
-## JWT (stateless) — minimal example
-
-### 1. Install
-
-```bash
-npm install jsonwebtoken
-```
-
-### 2. `api/login.js`
-
-```js
-// api/login.js
-const { NextResponse } = require('../_framework/next-response');
-const jwt = require('jsonwebtoken');
-
-const SECRET = process.env.JWT_SECRET || 'change-me';
-
-module.exports = {
-    POST: async (request) => {
-        const { email, password } = await request.json();
-        if (!email || !password) return NextResponse.json({ error: 'Missing fields' }, { status: 400 });
-
-        // Fake user check for demo — replace with DB lookup + bcrypt
-        if (email === 'demo@example.com' && password === 'demo') {
-            const token = jwt.sign({ sub: 'u_123', email }, SECRET, { expiresIn: '7d' });
-            return NextResponse.json({ token });
-        }
-        return NextResponse.json({ error: 'Invalid credentials' }, { status: 401 });
-    },
-};
-```
-
-### 3. `api/me.js` (protected)
-
-```js
-// api/me.js
-const { NextResponse } = require('../_framework/next-response');
-const jwt = require('jsonwebtoken');
-
-const SECRET = process.env.JWT_SECRET || 'change-me';
-
-function getUser(req) {
-    const auth = req.headers.authorization || '';
-    if (!auth.startsWith('Bearer ')) return null;
-    const token = auth.slice(7);
-    try {
-        return jwt.verify(token, SECRET);
-    } catch {
-        return null;
-    }
-}
-
-module.exports = {
-    GET: async (request) => {
-        const user = getUser(request);
-        if (!user) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-        return NextResponse.json({ user });
-    },
-};
-```
-
-### 4. Browser usage
-
-```js
-async function login() {
-    const res = await api.post('/api/login', { email: 'demo@example.com', password: 'demo' });
-    localStorage.setItem('token', res.token);
-    api.setHeaders({ Authorization: `Bearer ${res.token}` });
-}
-
-async function me() {
-    const res = await api.get('/api/me');
-    console.log(res.user);
-}
-```
-
-If you prefer not to keep in `localStorage`, have the login endpoint set an **HttpOnly + Secure + SameSite** cookie via `NextResponse.cookies.set` and send it on every request (the browser does this automatically). Then read `request.cookies` on the server.
-
-## Sessions with cookies (HttpOnly)
-
-```js
-const sessions = new Map(); // in-memory; replace with Redis for multi-instance
-
-module.exports.POST = async (request) => {
-    const { email, password } = await request.json();
-    if (email !== 'demo@example.com' || password !== 'demo') {
-        return NextResponse.json({ error: 'Invalid' }, { status: 401 });
-    }
-    const sid = crypto.randomUUID();
-    sessions.set(sid, { user: { id: 1, email } });
-    const res = NextResponse.json({ ok: true });
-    res.cookies.set('sid', sid, { httpOnly: true, secure: true, sameSite: 'lax', maxAge: 86400 });
-    return res;
-};
-```
-
-Then check `request.cookies.sid` against `sessions`.
-
-## Protecting pages (UI guard)
-
-You can gate the UI in a page. The server remains the source of truth.
-
-```js
-export default function Dashboard() {
-    const [ok, setOk] = useState(false);
-
-    useEffect(() => {
-        api.get('/api/me')
-            .then(() => setOk(true))
-            .catch(() => navigate('/login'));
-    }, []);
-
-    if (!ok) return <p>Checking auth…</p>;
-    return <h1>Dashboard</h1>;
-}
-```
-
-## Protecting with roles
-
-Attach a `role` to the token/session and check it:
-
-```js
-function requireRole(role) {
-    return async (request) => {
-        const user = getUser(request);
-        if (!user) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-        if (user.role !== role) return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
-        return NextResponse.json({ ok: true, user });
-    };
-}
-
-module.exports.GET = requireRole('admin');
-```
-
-## Passwords
-
-**Never** compare plain text. Use `bcrypt` or `argon2`:
-
-```bash
-npm install bcryptjs
-```
-
-```js
-const bcrypt = require('bcryptjs');
-const hash = await bcrypt.hash(password, 10);
-const ok = await bcrypt.compare(plain, hash);
-```
-
-## Quick checklist
-
-- [ ] Put secrets in `.env` (don't commit)
-- [ ] Verify auth on **every protected API** call
-- [ ] Return `401` for missing/invalid, `403` for insufficient
-- [ ] Use `HttpOnly` cookies for browser-only apps, or `Authorization` header for SPAs calling external
-- [ ] Don't assume client-side redirects are enough
-- [ ] Keep token expiry short, refresh if needed
-
-## Continue
-
-→ [Production & Deployment](./12-production-and-deployment.md)
+# 11 · Authentication
+
+There's no built-in auth. Because API routes run in Node and the browser client is flexible, you can add JWT-based, session-based (cookies), or OAuth flows yourself.
+
+## Principles
+
+- **Don't trust the browser.** Auth must be checked in **API routes** (server), not just hidden in UI.
+- **Protect routes.** Return `401`/`403` from API handlers when unauthorized.
+- **Send credentials in requests.** Use `Authorization: Bearer <token>` or rely on `HttpOnly` cookies.
+- **Keep secrets in `.env`.** Never put `JWT_SECRET` in page/components.
+
+## JWT (stateless) — minimal example
+
+### 1. Install
+
+```bash
+npm install jsonwebtoken
+```
+
+### 2. `api/login.js`
+
+```js
+// api/login.js
+const { NextResponse } = require('../_framework/next-response');
+const jwt = require('jsonwebtoken');
+
+const SECRET = process.env.JWT_SECRET || 'change-me';
+
+module.exports = {
+    POST: async (request) => {
+        const { email, password } = await request.json();
+        if (!email || !password) return NextResponse.json({ error: 'Missing fields' }, { status: 400 });
+
+        // Fake user check for demo — replace with DB lookup + bcrypt
+        if (email === 'demo@example.com' && password === 'demo') {
+            const token = jwt.sign({ sub: 'u_123', email }, SECRET, { expiresIn: '7d' });
+            return NextResponse.json({ token });
+        }
+        return NextResponse.json({ error: 'Invalid credentials' }, { status: 401 });
+    },
+};
+```
+
+### 3. `api/me.js` (protected)
+
+```js
+// api/me.js
+const { NextResponse } = require('../_framework/next-response');
+const jwt = require('jsonwebtoken');
+
+const SECRET = process.env.JWT_SECRET || 'change-me';
+
+function getUser(req) {
+    const auth = req.headers.authorization || '';
+    if (!auth.startsWith('Bearer ')) return null;
+    const token = auth.slice(7);
+    try {
+        return jwt.verify(token, SECRET);
+    } catch {
+        return null;
+    }
+}
+
+module.exports = {
+    GET: async (request) => {
+        const user = getUser(request);
+        if (!user) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+        return NextResponse.json({ user });
+    },
+};
+```
+
+### 4. Browser usage
+
+```js
+async function login() {
+    const res = await api.post('/api/login', { email: 'demo@example.com', password: 'demo' });
+    localStorage.setItem('token', res.token);
+    api.setHeaders({ Authorization: `Bearer ${res.token}` });
+}
+
+async function me() {
+    const res = await api.get('/api/me');
+    console.log(res.user);
+}
+```
+
+If you prefer not to keep in `localStorage`, have the login endpoint set an **HttpOnly + Secure + SameSite** cookie via `NextResponse.cookies.set` and send it on every request (the browser does this automatically). Then read `request.cookies` on the server.
+
+## Sessions with cookies (HttpOnly)
+
+```js
+const sessions = new Map(); // in-memory; replace with Redis for multi-instance
+
+module.exports.POST = async (request) => {
+    const { email, password } = await request.json();
+    if (email !== 'demo@example.com' || password !== 'demo') {
+        return NextResponse.json({ error: 'Invalid' }, { status: 401 });
+    }
+    const sid = crypto.randomUUID();
+    sessions.set(sid, { user: { id: 1, email } });
+    const res = NextResponse.json({ ok: true });
+    res.cookies.set('sid', sid, { httpOnly: true, secure: true, sameSite: 'lax', maxAge: 86400 });
+    return res;
+};
+```
+
+Then check `request.cookies.sid` against `sessions`.
+
+## Protecting pages (UI guard)
+
+You can gate the UI in a page. The server remains the source of truth.
+
+```js
+export default function Dashboard() {
+    const [ok, setOk] = useState(false);
+
+    useEffect(() => {
+        api.get('/api/me')
+            .then(() => setOk(true))
+            .catch(() => navigate('/login'));
+    }, []);
+
+    if (!ok) return <p>Checking auth…</p>;
+    return <h1>Dashboard</h1>;
+}
+```
+
+## Protecting with roles
+
+Attach a `role` to the token/session and check it:
+
+```js
+function requireRole(role) {
+    return async (request) => {
+        const user = getUser(request);
+        if (!user) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+        if (user.role !== role) return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
+        return NextResponse.json({ ok: true, user });
+    };
+}
+
+module.exports.GET = requireRole('admin');
+```
+
+## Passwords
+
+**Never** compare plain text. Use `bcrypt` or `argon2`:
+
+```bash
+npm install bcryptjs
+```
+
+```js
+const bcrypt = require('bcryptjs');
+const hash = await bcrypt.hash(password, 10);
+const ok = await bcrypt.compare(plain, hash);
+```
+
+## Quick checklist
+
+- [ ] Put secrets in `.env` (don't commit)
+- [ ] Verify auth on **every protected API** call
+- [ ] Return `401` for missing/invalid, `403` for insufficient
+- [ ] Use `HttpOnly` cookies for browser-only apps, or `Authorization` header for SPAs calling external
+- [ ] Don't assume client-side redirects are enough
+- [ ] Keep token expiry short, refresh if needed
+
+## Continue
+
+→ [Production & Deployment](./12-production-and-deployment.md)

package/template/docs/12-production-and-deployment.md

@@ -1,121 +1,121 @@
-# 12 · Production & Deployment
-
-Aziz.js doesn't "bundle" to a huge build — it serves your source, compiles JSX on demand, and serves `/_modules/*` straight from `node_modules`. There's nothing to compile to a `dist/` directory.
-
-## npm scripts
-
-```json
-{
-  "scripts": {
-    "dev":   "node scripts/dev-server.js",
-    "build": "node scripts/dev-server.js --production",
-    "start": "node scripts/dev-server.js --production"
-  }
-}
-```
-
-**Running with `--production` (or `NODE_ENV=production`) changes behavior:**
-
-- **No WebSocket live reload** server/client — the client script becomes an empty no-op.
-- **Cache headers**: HTML/JSON are `no-cache` (check ETag), most static assets get long-lived cache with `ETag` still checked.
-- **No verbose "Browser connected" / watcher spam** in the logs.
-- **Routes manifest still served** same way.
-
-## Locally testing production
-
-```bash
-npm run build  # or npm start
-# Server runs at http://localhost:3000 with production headers
-```
-
-Visiting `/_framework/routes.json` returns `"dev": false` in production.
-
-## Deploying to a host
-
-Any host that can run **Node.js 18+** works. Examples: Render, Railway, Fly.io, Hetzner, DigitalOcean, Vercel (with a custom Node server), or a VPS.
-
-### 1) Prepare the project
-
-```bash
-cd my-app
-npm ci        # clean install in CI/host
-```
-
-### 2) Environment variables
-
-Set anything your API routes need: `MONGODB_URI`, `JWT_SECRET`, `PORT` etc. The server reads `process.env.PORT`.
-
-### 3) Start it
-
-On the host, run:
-
-```bash
-NODE_ENV=production node scripts/dev-server.js
-```
-
-Or `npm start` if you prefer.
-
-If the platform requires a specific `start` command and binds to `$PORT`, this is fine — the server already respects `process.env.PORT`.
-
-### 4) Proxy / reverse proxy (optional but recommended)
-
-Put Nginx, Caddy, or your load balancer in front for:
-
-- HTTPS termination
-- Compression (gzip/brotli)
-- Caching static assets aggressively
-- Forwarding `X-Forwarded-For` / real IPs (the dev server doesn't trust proxy headers — treat as internal unless you add it)
-
-Caddy example:
-
-```txt
-example.com {
-  reverse_proxy localhost:3000
-  encode zstd gzip
-}
-```
-
-## Static hosting?
-
-You **cannot** just drop `template/` into a static S3 bucket. API routes (`api/**` and `app/api/**/route.js`) run on the **Node server**. The browser needs the dev server to:
-
-- serve transformed JS (JSX → h())
-- serve the route manifest
-- resolve bare imports via `/_modules/*`
-- handle `/api/*`
-
-If you want a 100% static site, you'd need a separate SSR/bundler — that's not what this lightweight framework does.
-
-## Security notes
-
-- **Path traversal**: the server confines all static file requests to the project root. Attempts to escape (e.g. `..%2f..%2fpackage.json`) return `403`.
-- **API CORS**: preflight `OPTIONS` and responses include permissive CORS headers — tighten if you only serve from one origin.
-- **JWT secrets**: never commit `.env`. Don't ship `node_modules` unnecessarily in git.
-- **Dependencies**: only `@babel/standalone` in `devDependencies` (needed to transform JSX on-the-fly). Your own deps go in `dependencies`.
-- **ETag**: conditional requests use strong-ish ETag based on `mtimeMs`+`size`; fine for this use case.
-
-## What "production mode" doesn't do
-
-- No code splitting / tree shaking
-- No minification of JS/CSS (though you can pre-minify and reference extra files)
-- No image optimization
-- No prerendering/SSG
-- No `.env` auto-loading (you must set environment variables)
-
-This is by design for simplicity and speed. For most small–medium apps it's perfectly usable.
-
-## Performance tips
-
-- **Lean deps**: avoid pulling huge libraries unless needed (the `/_modules` transform isn't magic; it still ships bytes).
-- **Memoize** in hooks (`useMemo`, `useCallback`) for expensive computations.
-- **Keep keys stable** in lists (`key={id}`).
-- **Use HTTP caching** via a proxy for immutable assets (`.woff2`, images) if you add them.
-- **Close DB connections** or use a proper pool (the examples above do a singleton pool).
-
-## Health check (optional)
-
-You can hit `/api/hello` to quickly verify the server is up.
-
-## Continue
-
-→ [Internals](./13-internals.md)
+# 12 · Production & Deployment
+
+Aziz.js doesn't "bundle" to a huge build — it serves your source, compiles JSX on demand, and serves `/_modules/*` straight from `node_modules`. There's nothing to compile to a `dist/` directory.
+
+## npm scripts
+
+```json
+{
+  "scripts": {
+    "dev":   "node scripts/dev-server.js",
+    "build": "node scripts/dev-server.js --production",
+    "start": "node scripts/dev-server.js --production"
+  }
+}
+```
+
+**Running with `--production` (or `NODE_ENV=production`) changes behavior:**
+
+- **No WebSocket live reload** server/client — the client script becomes an empty no-op.
+- **Cache headers**: HTML/JSON are `no-cache` (check ETag), most static assets get long-lived cache with `ETag` still checked.
+- **No verbose "Browser connected" / watcher spam** in the logs.
+- **Routes manifest still served** same way.
+
+## Locally testing production
+
+```bash
+npm run build  # or npm start
+# Server runs at http://localhost:3000 with production headers
+```
+
+Visiting `/_framework/routes.json` returns `"dev": false` in production.
+
+## Deploying to a host
+
+Any host that can run **Node.js 18+** works. Examples: Render, Railway, Fly.io, Hetzner, DigitalOcean, Vercel (with a custom Node server), or a VPS.
+
+### 1) Prepare the project
+
+```bash
+cd my-app
+npm ci        # clean install in CI/host
+```
+
+### 2) Environment variables
+
+Set anything your API routes need: `MONGODB_URI`, `JWT_SECRET`, `PORT` etc. The server reads `process.env.PORT`.
+
+### 3) Start it
+
+On the host, run:
+
+```bash
+NODE_ENV=production node scripts/dev-server.js
+```
+
+Or `npm start` if you prefer.
+
+If the platform requires a specific `start` command and binds to `$PORT`, this is fine — the server already respects `process.env.PORT`.
+
+### 4) Proxy / reverse proxy (optional but recommended)
+
+Put Nginx, Caddy, or your load balancer in front for:
+
+- HTTPS termination
+- Compression (gzip/brotli)
+- Caching static assets aggressively
+- Forwarding `X-Forwarded-For` / real IPs (the dev server doesn't trust proxy headers — treat as internal unless you add it)
+
+Caddy example:
+
+```txt
+example.com {
+  reverse_proxy localhost:3000
+  encode zstd gzip
+}
+```
+
+## Static hosting?
+
+You **cannot** just drop `template/` into a static S3 bucket. API routes (`api/**` and `app/api/**/route.js`) run on the **Node server**. The browser needs the dev server to:
+
+- serve transformed JS (JSX → h())
+- serve the route manifest
+- resolve bare imports via `/_modules/*`
+- handle `/api/*`
+
+If you want a 100% static site, you'd need a separate SSR/bundler — that's not what this lightweight framework does.
+
+## Security notes
+
+- **Path traversal**: the server confines all static file requests to the project root. Attempts to escape (e.g. `..%2f..%2fpackage.json`) return `403`.
+- **API CORS**: preflight `OPTIONS` and responses include permissive CORS headers — tighten if you only serve from one origin.
+- **JWT secrets**: never commit `.env`. Don't ship `node_modules` unnecessarily in git.
+- **Dependencies**: only `@babel/standalone` in `devDependencies` (needed to transform JSX on-the-fly). Your own deps go in `dependencies`.
+- **ETag**: conditional requests use strong-ish ETag based on `mtimeMs`+`size`; fine for this use case.
+
+## What "production mode" doesn't do
+
+- No code splitting / tree shaking
+- No minification of JS/CSS (though you can pre-minify and reference extra files)
+- No image optimization
+- No prerendering/SSG
+- No `.env` auto-loading (you must set environment variables)
+
+This is by design for simplicity and speed. For most small–medium apps it's perfectly usable.
+
+## Performance tips
+
+- **Lean deps**: avoid pulling huge libraries unless needed (the `/_modules` transform isn't magic; it still ships bytes).
+- **Memoize** in hooks (`useMemo`, `useCallback`) for expensive computations.
+- **Keep keys stable** in lists (`key={id}`).
+- **Use HTTP caching** via a proxy for immutable assets (`.woff2`, images) if you add them.
+- **Close DB connections** or use a proper pool (the examples above do a singleton pool).
+
+## Health check (optional)
+
+You can hit `/api/hello` to quickly verify the server is up.
+
+## Continue
+
+→ [Internals](./13-internals.md)