@seip/blue-bird 1.1.2 → 1.1.3

package/AGENTS.md

@@ -251,4 +251,74 @@ await connection.transaction(async (tx) => {
 In production, Nginx is configured to explicitly cache static assets (`.js`, `.css`, `.jpg`, `.png`, etc.) in the user's browser with the `Cache-Control` header (valid for 1 month). 
 HTML and API endpoints (`/api/*`) are not cached by Nginx to ensure they serve dynamic and up-to-date content, relying instead on the Node.js application and Redis for data-layer caching.
 
+## 13. VPS Permissions & Security Hardening
+
+When deploying Blue Bird to Linux VPS servers using Docker Compose orchestration:
+
+### 1. FHS Deployment Standard
+- **Avoid deploying inside `/home/user/`**: User home directories often enforce restrictive traversal permissions (`700`/`750`) or risk cross-user privilege escalation in multi-tenant environments.
+- **Production Standard**: Always deploy in standard Filesystem Hierarchy Standard (FHS) locations:
+  - `/var/www/<project-name>` (Recommended for web applications)
+  - `/srv/<project-name>` (Alternative for site-specific service payloads)
+
+### 2. Permissions & Ownership Matrix
+
+| Path / Target | Recommended Mode | Ownership | Description & Rationale |
+|---|---|---|---|
+| `/var/www/<project-name>` | `755` (`drwxr-xr-x`) | `$(whoami):$(whoami)` | Allows unprivileged Nginx container (`UID 101`) path traversal. |
+| `frontend/` (directories) | `755` (`drwxr-xr-x`) | `$(whoami):$(whoami)` | Directory traversal for static web workers. |
+| `frontend/` (files) | `644` (`-rw-r--r--`) | `$(whoami):$(whoami)` | Public read access for Nginx static serving. |
+| `node_modules/` | Dirs `755`, Files `644` | `$(whoami):$(whoami)` | Strict security. Avoid blanket `chmod -R 755`. |
+| `node_modules/.bin/` | `+x` (`chmod -R +x`) | `$(whoami):$(whoami)` | Preserves execution bits for CLI binaries and symlinks. |
+| `.env` | `600` (`-rw-------`) | `$(whoami):$(whoami)` | Strict isolation for database credentials and JWT keys. Never `777`. |
+| `database/` (SQLite) | Dir `755`, Files `644` | `$(whoami):$(whoami)` | Allows Node.js application process to read/write WAL journals. |
+
+### 3. Container-Level Hardening (Docker)
+- Mount static assets as **read-only (`:ro`)** in `docker-compose.yml` for the Nginx service (e.g. `./frontend:/app/frontend:ro` or `/var/www/<project-name>/frontend:/app/frontend:ro`).
+- Enforces the principle of least privilege: the web server worker cannot write or overwrite host assets even if compromised.
+
+### 4. Production Hardening Commands
+
+```bash
+# 1. Set project ownership to current deploy user
+sudo chown -R $(whoami):$(whoami) /var/www/<project-name>
+cd /var/www/<project-name>
+
+# 2. Ensure parent directory traversal permissions
+chmod 755 /var /var/www /var/www/<project-name>
+
+# 3. Set directory (755) and file (644) permissions for static frontend assets
+find frontend -type d -exec chmod 755 {} +
+find frontend -type f -exec chmod 644 {} +
+
+# 4. Secure node_modules while preserving executable bits in .bin
+find node_modules -type d -exec chmod 755 {} +
+find node_modules -type f -exec chmod 644 {} +
+chmod -R +x node_modules/.bin 2>/dev/null || true
+
+# 5. Restrict environment credentials strictly to owner
+chmod 600 .env
+
+# 6. Set database permissions (for SQLite)
+chmod 755 database 2>/dev/null || true
+chmod 644 database/*.db 2>/dev/null || true
+```
+
+### 5. Failure Modes & Remediation Playbook
+* **Error 13: Permission Denied on static assets (`stat() failed (13: Permission denied)`):**
+  - Cause: Nginx worker (`UID 101`) lacks path traversal (`+x`) or read (`+r`) permissions.
+  - Fix: `chmod 755 /var/www/<project-name> && find frontend -type d -exec chmod 755 {} + && find frontend -type f -exec chmod 644 {} +`
+* **`sh: 1: blue-bird: Permission denied` on CLI:**
+  - Cause: Blanket `chmod 644` stripped execution permissions from binary links in `node_modules/.bin/`.
+  - Fix: `chmod -R +x node_modules/.bin` (or `npm rebuild`)
+* **Docker Inode Desync (404 after `mv` / `rm -rf` directory):**
+  - Cause: Docker volume bind mounts bind to Linux filesystem inodes. Recreating the folder desynchronizes active mounts.
+  - Fix: `npx blue-bird docker stop && npx blue-bird docker start prod` (or `docker compose down && docker compose up -d`)
+* **Real-time Diagnostics:**
+  - Nginx log stream: `docker compose logs -f nginx`
+  - Container visibility check: `docker exec -it <container_name>-nginx su -s /bin/sh nginx -c "ls -la /app/frontend"`
+  - Host path traversal audit: `namei -l /var/www/<project-name>/frontend/css/bluebird.css`
+
+---
+
 _This file can be retrieved by intelligent agents reading its absolute physical path during reasoning._

package/README.md

@@ -504,6 +504,135 @@ To deploy via Docker:
    npx blue-bird docker start prod
    ```
 
+---
+
+### 🛡️ Production VPS Security & Permissions Hardening Guide
+
+When deploying Blue Bird to a Linux VPS (Ubuntu, Debian, AlmaLinux, Rocky Linux), file permissions must strictly balance **least-privilege security** (preventing unauthorized read/write access to sensitive files) with **container accessibility** (allowing unprivileged container users like `nginx` to read static assets).
+
+> [!CAUTION]
+> **Never use `chmod -R 777` in production!** Giving full write permissions to all users creates severe security vulnerabilities, allowing compromised processes or unauthorized local users to modify application code, inject backdoors, or tamper with `.env` secrets.
+
+#### 1. Deployment Directory (Filesystem Hierarchy Standard)
+
+* ❌ **Avoid deploying inside `/home/user/`**: Deploying in home directories introduces security risks in multi-user environments and frequently causes `403 Forbidden` / `stat() failed (13: Permission denied)` errors due to restrictive default parent directory permissions (`700`/`750`). Recklessly loosening `/home/user/` exposes user SSH keys and profile data.
+* ✅ **Recommended Production Standard**: Deploy in dedicated Filesystem Hierarchy Standard (FHS) system directories:
+  * `/var/www/<project-name>` (Standard for web applications and static content)
+  * `/srv/<project-name>` (Alternative standard for site-specific payloads)
+
+#### 2. Recommended Permissions & Ownership Matrix
+
+| Target Directory / File | Mode | Ownership | Description & Security Rationale |
+|---|---|---|---|
+| **Project Root** (`/var/www/<project-name>`) | `755` (`drwxr-xr-x`) | `$(whoami):$(whoami)` | Allows unprivileged container processes (`nginx` UID 101) to traverse down to the project tree. |
+| **Static Frontend Dirs** (`frontend/`) | `755` (`drwxr-xr-x`) | `$(whoami):$(whoami)` | Grants traversal and read access for Nginx static serving. |
+| **Static Frontend Files** (`frontend/**/*`) | `644` (`-rw-r--r--`) | `$(whoami):$(whoami)` | Read-only access for web server worker processes. |
+| **Node Module Dirs** (`node_modules/`) | `755` (`drwxr-xr-x`) | `$(whoami):$(whoami)` | Standard directory access. Avoid blanket `chmod -R 755`. |
+| **Node Module Files** (`node_modules/**/*`) | `644` (`-rw-r--r--`) | `$(whoami):$(whoami)` | Standard read-only permissions for non-binary dependencies. |
+| **Executable Binaries** (`node_modules/.bin/`) | `+x` (`chmod -R +x`) | `$(whoami):$(whoami)` | Grants execution bit exclusively to CLI wrapper symlinks (`npx blue-bird`). |
+| **Environment File** (`.env`) | `600` (`-rw-------`) | `$(whoami):$(whoami)` | Restricts database passwords, JWT secrets, and API keys exclusively to the owning user. Never `644` or `777`. |
+| **Database Directory** (`database/` for SQLite) | `755` (dir) / `644` (file) | `$(whoami):$(whoami)` | Allows the Node.js application process inside the container to read and write WAL journal files. |
+
+#### 3. Container-Level Hardening (Docker)
+
+To enforce the principle of least privilege at the container boundary, explicitly mount static frontend assets in **read-only mode (`:ro`)** inside `docker-compose.yml` for the Nginx service:
+
+```yaml
+services:
+  nginx:
+    image: nginx:alpine
+    volumes:
+      - ./frontend:/app/frontend:ro
+      - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
+```
+
+This guarantees that even in the event of an Nginx worker compromise, static web assets cannot be overwritten or modified from within the container.
+
+#### 4. Applying Secure Permissions on VPS
+
+Run the following chained commands inside your VPS project directory:
+
+```bash
+# 1. Set project ownership to current deploy user
+sudo chown -R $(whoami):$(whoami) /var/www/<project-name>
+cd /var/www/<project-name>
+
+# 2. Ensure parent directory traversal permissions
+chmod 755 /var /var/www /var/www/<project-name>
+
+# 3. Apply safe permissions for static frontend assets
+find frontend -type d -exec chmod 755 {} +
+find frontend -type f -exec chmod 644 {} +
+
+# 4. Secure node_modules while preserving executable bits in .bin
+find node_modules -type d -exec chmod 755 {} +
+find node_modules -type f -exec chmod 644 {} +
+chmod -R +x node_modules/.bin 2>/dev/null || true
+
+# 5. Lock down environment credentials
+chmod 600 .env
+
+# 6. Set database directory permissions (for SQLite)
+chmod 755 database 2>/dev/null || true
+chmod 644 database/*.db 2>/dev/null || true
+```
+
+---
+
+### 🔧 VPS Production Troubleshooting (Problems & Solutions)
+
+#### 1. Static Assets Return 404 / 403 (`Permission denied`)
+* **Symptom:** Opening pages returns 404 or missing CSS/JS (e.g. `/css/bluebird.css`, `/favicon.ico`), and `docker compose logs -f nginx` reports:
+  ```text
+  [crit] stat() "/app/frontend/css/bluebird.css" failed (13: Permission denied)
+  ```
+* **Cause:** The Nginx container runs as an unprivileged user (`nginx`, UID 101 on Alpine). If parent directories lack traversal (`+x`) permissions, or files lack read (`+r`) permissions, Nginx is blocked from reading `/app/frontend`.
+* **Solution:**
+  ```bash
+  # Grant traversal and read permissions:
+  chmod 755 /var/www/<project-name>
+  find frontend -type d -exec chmod 755 {} +
+  find frontend -type f -exec chmod 644 {} +
+  ```
+
+#### 2. `npx blue-bird` fails with `sh: 1: blue-bird: Permission denied`
+* **Symptom:** Running CLI commands like `npx blue-bird docker stop` or `npx blue-bird docker start prod` fails with permission errors.
+* **Cause:** An overly aggressive global `find . -type f -exec chmod 644` stripped execution permissions from binary wrappers and symlinks in `node_modules/.bin/`.
+* **Solution:**
+  ```bash
+  chmod -R +x node_modules/.bin
+  # Or rebuild native binaries:
+  npm rebuild
+  ```
+
+#### 3. 404 Not Found after Folder Renaming or Moving (Docker Inode Desync)
+* **Symptom:** Moving, replacing, or recreating the project folder (e.g. `mv project_old project` or `git clone` / `rm -rf`) while Docker containers were running leads to persistent 404 errors even though files exist on disk.
+* **Cause:** Linux file descriptors and Docker volume mounts bind to disk **inodes**. When a directory is deleted and recreated, Docker mounts remain attached to the stale/dead inode until the container stack is restarted.
+* **Solution:**
+  ```bash
+  docker compose down
+  docker compose up -d
+  # Or with Blue Bird CLI:
+  npx blue-bird docker stop
+  npx blue-bird docker start prod
+  ```
+
+#### 4. Real-time Container Diagnostics
+* **Inspect Nginx logs in real time:**
+  ```bash
+  docker compose logs -f nginx
+  ```
+* **Test file visibility directly as the Nginx container user:**
+  ```bash
+  docker exec -it <container_name>-nginx su -s /bin/sh nginx -c "ls -la /app/frontend/css/bluebird.css"
+  ```
+* **Inspect path traversal permissions on host:**
+  ```bash
+  namei -l /var/www/<project-name>/frontend/css/bluebird.css
+  ```
+
+---
+
 ### B. Standard Standalone PM2 / Node.js Runtime
 
 If you choose to run outside of Docker, you must set up the reverse proxy and databases manually. To deploy in a standard Linux environment using PM2:

package/frontend/about.html

@@ -1,108 +1,157 @@
-<!DOCTYPE html>
-<html lang="en" data-theme="dark">
-
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Blue Bird - About</title>
-    <link rel="canonical" href="https://seip25.github.io/Blue-bird/" />
-    <meta name="description" content="Blue Bird is a fast, structured, and opinionated Express.js framework for developers who want
-                    visual elegance and performance with raw HTML and CSS.">
-    <meta name="keywords" content="">
-    <meta name="author" content="Seip25">
-    <link rel="icon" href="/images/favicon.ico" />
-    <script src="/js/tailwind.js"></script>
-    <script src="/js/utils.js"></script>
-    <style type="text/tailwindcss">
-        @custom-variant dark (&:where(.dark, .dark *));
-    </style>
-</head>
-
-<body class="min-h-screen bg-slate-950 text-white font-sans antialiased selection:bg-blue-500 selection:text-white">
-    <header class="sticky top-0 z-50 px-4 py-3">
-        <div
-            class="max-w-7xl mx-auto flex items-center justify-between backdrop-blur-md bg-slate-900/60 border border-white/10 rounded-2xl px-6 py-3 shadow-lg">
-            <div class="flex items-center space-x-3">
-                <div
-                    class="w-10 h-10 bg-gradient-to-tr from-blue-500 to-indigo-600 rounded-xl flex items-center justify-center shadow-md shadow-blue-500/30">
-                    <svg class="w-6 h-6 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2"
-                            d="M12 19l9 2-9-18-9 18 9-2zm0 0v-8" />
-                    </svg>
-                </div>
-                <span
-                    class="text-xl font-bold tracking-tight bg-gradient-to-r from-blue-400 via-indigo-200 to-white bg-clip-text text-transparent">Blue
-                    Bird</span>
-            </div>
-
-            <nav class="flex space-x-8 text-sm font-medium text-slate-300">
-                <a href="/" class="hover:text-blue-400 transition-colors">Home</a>
-                <a href="/about" class="hover:text-blue-400 transition-colors">About</a>
-            </nav>
-        </div>
-    </header>
-
-    <main class="max-w-7xl mx-auto px-4 pt-12 pb-24">
-
-        <div
-            class="relative py-16 px-6 md:px-12 rounded-3xl overflow-hidden bg-gradient-to-b from-blue-900/20 to-slate-950 border border-white/5 shadow-2xl mb-12">
-            <div class="relative max-w-4xl mx-auto space-y-6 text-center">
-                <h1
-                    class="text-4xl sm:text-5xl font-extrabold tracking-tight bg-gradient-to-r from-blue-400 via-indigo-300 to-white bg-clip-text text-transparent">
-                    About Blue Bird
-                </h1>
-                <p class="text-lg sm:text-xl text-slate-400 leading-relaxed max-w-2xl mx-auto">
-                    Built for performance, simplicity, and raw speed.
-                </p>
-            </div>
-        </div>
-
-        <section class="max-w-4xl mx-auto space-y-12">
-            <article class="p-8 rounded-2xl bg-slate-900/40 border border-white/5 shadow-xl">
-                <h2 class="text-2xl font-bold text-white mb-4">Our Philosophy</h2>
-                <p class="text-slate-400 leading-relaxed mb-4">
-                    Blue Bird was born out of a desire for a clean, performance-first approach to web development. We
-                    believe in harnessing the raw power of Express.js and Nginx, stripping away unnecessary bloat, and
-                    providing developers with a robust foundation that just works.
-                </p>
-                <p class="text-slate-400 leading-relaxed">
-                    By separating the static frontend delivery (handled blazingly fast by Nginx) from the dynamic API
-                    layer (powered by Express and Redis), Blue Bird achieves unparalleled performance out of the box.
-                </p>
-            </article>
-
-            <article class="p-8 rounded-2xl bg-slate-900/40 border border-white/5 shadow-xl">
-                <h2 class="text-2xl font-bold text-white mb-4">Why Blue Bird?</h2>
-                <ul class="space-y-3 text-slate-400">
-                    <li class="flex items-start">
-                        <span class="text-blue-500 mr-2">✓</span>
-                        <span><strong>Zero Config Docker:</strong> Go from development to production seamlessly.</span>
-                    </li>
-                    <li class="flex items-start">
-                        <span class="text-blue-500 mr-2">✓</span>
-                        <span><strong>Military Grade Security:</strong> Built-in AES-256-GCM JWT encryption.</span>
-                    </li>
-                    <li class="flex items-start">
-                        <span class="text-blue-500 mr-2">✓</span>
-                        <span><strong>High Performance:</strong> Redis caching for the data layer and Nginx static
-                            delivery.</span>
-                    </li>
-                    <li class="flex items-start">
-                        <span class="text-blue-500 mr-2">✓</span>
-                        <span><strong>Pure HTML/CSS:</strong> No bloated frontend frameworks. Write code close to the
-                            metal.</span>
-                    </li>
-                </ul>
-            </article>
-        </section>
-    </main>
-
-    <footer class="border-t border-white/5 py-8 bg-slate-950 mt-16">
-        <div class="max-w-7xl mx-auto px-4 text-center text-sm text-slate-500">
-            <p>Powered by Blue Bird Framework. All rights reserved.</p>
-        </div>
-    </footer>
-
-</body>
-
+<!DOCTYPE html>
+<html lang="en" data-theme="dark">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Blue Bird - About</title>
+    <link rel="canonical" href="https://seip25.github.io/Blue-bird/" />
+    <meta name="description"
+        content="Blue Bird is a fast, structured, and opinionated Express.js framework for developers who want visual elegance and performance with raw HTML and CSS.">
+    <meta name="keywords" content="Blue Bird, Express.js, About, Semantic CSS, Architecture">
+    <meta name="author" content="Seip25">
+    <link rel="icon" href="/images/favicon.ico" />
+    <link rel="stylesheet" href="/css/bluebird.css" />
+    <script src="/js/bluebird.js"></script>
+</head>
+
+<body>
+    <header>
+        <nav>
+            <a href="/" class="flex items-center gap-2">
+                <svg width="28" height="28" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"
+                    stroke-linecap="round" stroke-linejoin="round" class="text-blue">
+                    <path d="M12 19l9 2-9-18-9 18 9-2zm0 0v-8" />
+                </svg>
+                <strong class="text-xl text-gradient">Blue Bird</strong>
+            </a>
+        </nav>
+    </header>
+
+    <main>
+        <aside>
+            <h4>Menu</h4>
+            <a href="/">Home</a>
+            <a href="/about" class="active badge badge-glow px-3 py-3">About</a>
+            <a href="https://seip25.github.io/Blue-bird-css/" target="_blank">Blue Bird CSS</a>
+            <a href="https://github.com/seip25/Blue-bird" target="_blank" role="button"
+                class="btn-sm outline">GitHub</a>
+        </aside>
+
+        <div>
+            <section class="hero ">
+                <h1 class="mt-3 text-gradient font-bold">About Blue Bird</h1>
+                <p class="lead">Built for performance, simplicity, and raw speed.</p>
+            </section>
+
+            <article class="mt-6 ">
+                <header>
+                    <h2 class="text-gradient-blue font-semibold">Our Philosophy</h2>
+                </header>
+                <p>
+                    Blue Bird was born out of a desire for a clean, performance-first approach to web development. We
+                    believe in harnessing the raw power of Express.js and Nginx, stripping away unnecessary bloat, and
+                    providing developers with a robust foundation that just works.
+                </p>
+                <p>
+                    By separating the static frontend delivery (handled blazingly fast by Nginx) from the dynamic API
+                    layer (powered by Express and Redis), Blue Bird achieves unparalleled performance out of the box.
+                </p>
+            </article>
+
+            <div class="px-4 py-4  mb-4">
+                <h2 class="text-gradient-blue font-semibold">Why Blue Bird?</h2>
+
+                <div class="grid cols-2 gap-4">
+                    <div>
+                        <details open>
+                            <summary>Zero Config Docker</summary>
+                            <p>Go from development to production seamlessly with ready-to-use
+                                Docker orchestration for
+                                SQLite, MySQL, PostgreSQL, and Redis.</p>
+                        </details>
+                        <details open>
+                            <summary>Military Grade Security</summary>
+                            <p>Built-in AES-256-GCM JWT encryption, secure HttpOnly cookie
+                                sessions, helmet headers, and
+                                route rate limiting.</p>
+                        </details>
+                    </div>
+                    <div>
+                        <details open>
+                            <summary>High Performance Layer</summary>
+                            <p>Redis caching for the data layer and Nginx static delivery with
+                                1-month browser asset
+                                caching.</p>
+                        </details>
+                        <details open>
+                            <summary>Pure Semantic HTML &amp; CSS</summary>
+                            <p>No bloated frontend frameworks or heavy node compile steps. Write
+                                clean, accessible code
+                                close to the metal.</p>
+                        </details>
+                    </div>
+                </div>
+                </article>
+
+                <article class="">
+                    <header>
+                        <h2 class="text-gradient-blue font-semibold">Core Architecture Summary</h2>
+                    </header>
+                    <table class="table table-hover">
+                        <thead>
+                            <tr>
+                                <th>Layer</th>
+                                <th>Technology</th>
+                                <th>Role</th>
+                            </tr>
+                        </thead>
+                        <tbody>
+                            <tr>
+                                <td><strong>Frontend</strong></td>
+                                <td>Pure Semantic HTML5 + <a href="https://seip25.github.io/Blue-bird-css/"
+                                        target="_blank">Blue Bird CSS</a></td>
+                                <td>Static rendering served directly via Nginx</td>
+                            </tr>
+                            <tr>
+                                <td><strong>Backend</strong></td>
+                                <td>Node.js + Express + PM2</td>
+                                <td>High-performance REST API services</td>
+                            </tr>
+                            <tr>
+                                <td><strong>Cache</strong></td>
+                                <td>Redis / In-Memory RAM</td>
+                                <td>Sub-millisecond route &amp; query caching</td>
+                            </tr>
+                            <tr>
+                                <td><strong>Database</strong></td>
+                                <td>SQLite (WAL) / PostgreSQL / MySQL</td>
+                                <td>Unified driver with connection pooling</td>
+                            </tr>
+                        </tbody>
+                    </table>
+                </article>
+
+
+            </div>
+    </main>
+
+    <footer>
+        <div class="footer-content">
+            <p>Powered by <strong class="text-gradient">Blue Bird Framework</strong> &amp;
+                <strong class="text-gradient-blue">
+                    <a href="https://seip25.github.io/Blue-bird-css/" target="_blank">Blue Bird
+                        CSS</a>
+                </strong>.
+            </p>
+            <div class="lang-switcher">
+                <a href="/" class="lang-link">Home</a>
+                <a href="/about" class="lang-link">About</a>
+                <a href="https://github.com/seip25/Blue-bird" target="_blank" class="github-star mt-2">&#9733;
+                    GitHub</a>
+            </div>
+        </div>
+    </footer>
+</body>
+
 </html>