flet-box 1.0.3 → 1.0.5

package/docs/server/security.md

@@ -0,0 +1,196 @@
+# Authentication and security
+
+## Start securely
+
+Use `runSecureServer()` as the default starting point for a real API:
+
+```javascript
+import { Api, runSecureServer } from "flet-box-server";
+
+const routes = Api({
+  "/health": { GET: () => ({ ok: true }) },
+});
+
+runSecureServer(routes, {
+  port: 3000,
+  docs: true,
+  rateLimit: { max: 100, windowMs: 60_000 },
+});
+```
+
+This enables security middleware, input cleaning, validation, malicious-content blocking, and rate limiting according to the server options.
+
+## JWT login
+
+The security database supports a password grant through a token handler. A development login request looks like this:
+
+```javascript
+const response = await fetch("http://localhost:3000/login", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    grant_type: "password",
+    username: process.env.ADMIN_USERNAME,
+    password: process.env.ADMIN_PASSWORD,
+  }),
+});
+
+const { access_token } = await response.json();
+```
+
+Send the token with protected requests:
+
+```javascript
+fetch("http://localhost:3000/private", {
+  headers: {
+    Authorization: `Bearer ${access_token}`,
+  },
+});
+```
+
+## Protect a route
+
+```javascript
+import { authenticate } from "flet-box-server";
+
+const routes = Api({
+  "/private": {
+    GET: {
+      handler: ({ req }) => ({
+        user: req.user,
+        secret: "private data",
+      }),
+      middleware: [authenticate],
+    },
+  },
+});
+```
+
+`authenticate` rejects missing or invalid bearer tokens with status `401` and adds the verified payload to `req.user`.
+
+## Roles
+
+Use `hasRole()` after authentication:
+
+```javascript
+import { authenticate, hasRole } from "flet-box-server";
+
+const routes = Api({
+  "/admin": {
+    GET: {
+      handler: () => ({ area: "admin" }),
+      middleware: [authenticate, hasRole("admin")],
+    },
+  },
+});
+```
+
+A user must be authenticated before roles can be checked.
+
+## Optional authentication
+
+Use `optionalAuth` when a route works for visitors but can provide extra data to logged-in users:
+
+```javascript
+import { optionalAuth } from "flet-box-server";
+
+middleware: [optionalAuth]
+```
+
+## Input sanitization
+
+`securityCheck` can:
+
+- Check blocked IPs, paths, and user agents.
+- Sanitize request body, query, and path parameters.
+- Apply security headers.
+- Apply CORS rules.
+
+Do not treat sanitization as a replacement for validation. Validate the expected type and business rules too.
+
+## Malicious-content blocking
+
+`blockMalicious` checks body, params, and query values against known suspicious patterns and returns `403` when a pattern is detected.
+
+Use it as route middleware when appropriate:
+
+```javascript
+middleware: [authenticate, blockMalicious, securityCheck]
+```
+
+False positives are possible. Review the accepted input for your application instead of blindly allowing all content.
+
+## Schema validation
+
+Use `SchemaValidator` for explicit validation:
+
+```javascript
+import { SchemaValidator } from "flet-box-server";
+
+const validator = new SchemaValidator({
+  name: { type: "string", required: true, minLength: 2 },
+  age: { type: "number", min: 0 },
+  email: { type: "email", required: true },
+});
+
+const result = validator.validate({
+  name: "Ada",
+  age: 36,
+  email: "ada@example.com",
+});
+
+if (!result.valid) {
+  console.log(result.errors);
+}
+```
+
+Supported validation concepts include strings, numbers, booleans, email, URL, date, UUID, arrays, objects, required fields, ranges, lengths, enums, defaults, and custom patterns.
+
+## Rate limiting
+
+Create a route limiter:
+
+```javascript
+import { rateLimit } from "flet-box-server";
+
+const limiter = rateLimit({
+  max: 10,
+  windowMs: 60_000,
+  message: "Too many requests",
+});
+
+const routes = Api({
+  "/login": {
+    POST: {
+      handler: login,
+      middleware: [limiter],
+    },
+  },
+});
+```
+
+For multiple server instances, use a shared store such as Redis rather than only an in-memory map.
+
+## Security headers and CORS
+
+`securityCheck` applies headers such as content-type protection, frame protection, referrer policy, and content security policy.
+
+CORS origins can be configured with the environment variable:
+
+```bash
+CORS_ORIGINS=https://my-app.example.com,https://admin.example.com
+```
+
+Avoid `*` with credentials in production. Use an explicit allowlist.
+
+## Production checklist
+
+- Set a long random `JWT_SECRET`.
+- Remove hardcoded admin users and passwords.
+- Never commit SMTP, Twilio, Redis, or cloud credentials.
+- Use HTTPS.
+- Restrict CORS origins.
+- Enable validation and rate limiting.
+- Review sanitization false positives.
+- Store verification codes and sessions in a shared store when scaling.
+- Log security events without logging passwords or tokens.

package/docs/services/README.md

@@ -0,0 +1,79 @@
+# Services: FletBox data & network helpers
+
+This directory is the reference index for the services that ship with FletBox — the helpers that connect your app to the **outside world**: browser storage and the network.
+
+Services are plain JavaScript functions and objects. You import them from `flet-box`:
+
+```javascript
+import { saveData, getData, httpGet, subscribeRam } from "flet-box";
+```
+
+> **Services vs. Tools.** *Services* talk to the outside world (storage, network) and may be async or stateful. *Tools* are pure helpers that turn input into a value. Find tools in the [tools index](../tools/README.md).
+
+For a task-oriented walkthrough of the three storage layers, read the [Frontend services guide](../guides/frontend-services.md). This index lists everything the framework actually exports today, grouped by layer, and **links to a full reference page for each layer** (every function with its signature and return value). The implementation lives in `src/services/` and every name below is present in `src/index.js`.
+
+## The four layers
+
+| Page | Layer | Lifetime |
+| --- | --- | --- |
+| [RamStore](RamStore.md) | In-memory reactive state (backs `useState`) | While the page runs |
+| [Session](Session.md) | `sessionStorage` | The tab session |
+| [Storage](Storage.md) | `localStorage` | Until cleared |
+| [HTTP client](http.md) | `fetch`-based network calls | Per request |
+
+## RamStore — in-memory reactive state
+
+RAM storage, alive while the page runs. Backs `useState`'s keys.
+
+- `RamStore` — class/instance access.
+- `saveRam(key, value)`, `getRam(key)`, `getAllRam()`, `getAllRamKeys()`, `hasRam(key)`, `updateRam(key, value)`, `deleteRam(key)`, `clearAllRam()`, `getRamItemCount()`, `isRamAvailable()`.
+- `subscribeRam(callback)` — subscribe to any RAM change; returns an unsubscribe function.
+
+> Full detail, examples, and notes → [RamStore reference](RamStore.md).
+
+## Session — tab-scoped storage
+
+Backed by `sessionStorage`: lives for the tab session, lost when the tab closes.
+
+- `Session` — class/instance access.
+- `saveSession(key, value)` (async), `getSession(key)` (async), `getSessionSync(key)`, `updateSession(key, value)`, `deleteSession(key)`, `clearAllSession()`, `hasSession(key)`, `getAllSessionKeys()`, `getAllSessionData()`, `getSessionSize()`, `deleteSessionByPrefix(prefix)`, `deleteSessionBySuffix(suffix)`, `getSessionItemCount()`, `isSessionAvailable()`.
+
+> Full detail, examples, and notes → [Session reference](Session.md).
+
+## Storage — persistent data
+
+Backed by `localStorage`: survives browser restarts until cleared.
+
+- `Storage` — class/instance access.
+- `saveData(key, value)` (async), `getData(key)` (async), `getDataSync(key)`, `updateData(key, value)`, `deleteData(key)`, `clearAllData()`, `hasData(key)`, `getAllKeys()`, `getAllData()`, `getStorageSize()`, `deleteDataByPrefix(prefix)`, `deleteDataBySuffix(suffix)`, `getItemCount()`, `isStorageAvailable()`.
+
+> Full detail, examples, and notes → [Storage reference](Storage.md).
+
+## HTTP client
+
+A small `fetch`-based client.
+
+- `httpGet(url, options)`, `httpPost(url, options)`, `httpPut(url, options)`, `httpPatch(url, options)`, `httpDelete(url, options)` — all take a single options object with `body`, `params`, `headers`, and `timeout`.
+- `httpRequest(method, url, options)` — generic request; see `HttpRequestOptions` in `src/index.d.ts`.
+
+> Full detail, examples, and notes → [HTTP reference](http.md).
+
+> **Security.** Never store passwords, private keys, or security secrets in any of these services. Browser storage is readable by anyone with access to the device, and any token in frontend code is visible to the user. Protect sensitive data with server-side authorization.
+
+## Where to go next
+
+- [Frontend services guide](../guides/frontend-services.md) — the practical walkthrough for storage and HTTP.
+- [Guides index](../guides/README.md) — every FletBox guide in reading order.
+- [State guide](../guides/state.md) — `useState` and RAM-backed reactivity.
+- [Tools index](../tools/README.md) — the pure helper functions.
+- [Widgets](../widget/README.md) — the widget book.
+
+---
+
+## Continue reading
+
+- **Previous:** [Frontend services guide](../guides/frontend-services.md)
+- **Next:** [RamStore](RamStore.md)
+- **Index:** [Guides index](../guides/README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 9 · State, Router & Services** (chapter opener).

package/docs/services/RamStore.md

@@ -0,0 +1,84 @@
+# RamStore
+
+## Overview
+`RamStore` is the **in-memory** reactive store. It keeps data in a JavaScript `Map` while the page is open, notifies subscribers when any key changes, and powers `useState` under the hood. Everything is lost when the page reloads — that is its job.
+
+## When to use
+- Share live values between widgets (the state engine behind `useState`).
+- Keep temporary UI data — form steps, current filters, draft objects — that must disappear on reload.
+
+## Import
+
+```javascript
+import { saveRam, getRam, subscribeRam, RamStore } from "flet-box";
+```
+
+Every function also exists as a method of the exported `RamStore` object, for an object-style API.
+
+## Functions
+
+| Function | Signature | Returns | Description |
+| --- | --- | --- | --- |
+| `saveRam` | `saveRam(key, value)` | `boolean` | Store or replace `value` under `key` and notify subscribers. |
+| `getRam` | `getRam(key)` | `T \| null` | Read the value, or `null` if the key does not exist. |
+| `getAllRam` | `getAllRam()` | `Record<string, any>` | Every stored key/value pair. |
+| `getAllRamKeys` | `getAllRamKeys()` | `string[]` | All stored keys. |
+| `hasRam` | `hasRam(key)` | `boolean` | Is the key present? |
+| `updateRam` | `updateRam(key, value)` | `boolean` | Replace the value (same as `saveRam`). |
+| `deleteRam` | `deleteRam(key)` | `boolean` | Remove a key. |
+| `clearAllRam` | `clearAllRam()` | `boolean` | Remove everything. |
+| `subscribeRam` | `subscribeRam(callback)` | `() => void` | Subscribe to changes, returns an unsubscribe function. |
+| `getRamItemCount` | `getRamItemCount()` | `number` | How many keys are stored. |
+| `isRamAvailable` | `isRamAvailable()` | `boolean` | Always `true` in a browser; kept for API symmetry with the other stores. |
+
+The subscribe callback receives `(key, newValue, oldValue)`. Use your stored key as the first argument to filter.
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { saveRam, getRam } from "flet-box";
+
+saveRam("cart", [{ id: 1 }, { id: 2 }]);
+const cart = getRam("cart");
+```
+
+### Full example
+
+```javascript
+import { saveRam, subscribeRam, deleteRam } from "flet-box";
+
+const unsubscribe = subscribeRam((key, newValue, oldValue) => {
+  console.log(`${key}: ${oldValue} → ${newValue}`);
+});
+
+saveRam("theme", "dark"); // logs: theme: null → dark
+deleteRam("theme");       // logs: theme: dark → null
+
+// stop listening:
+unsubscribe();
+```
+
+## Notes
+
+- This is the store behind `useState`. When you call `setCount(...)`, FletBox saves through `RamStore` and re-renders registered widgets.
+- Values can be any JSON-safe data: strings, numbers, booleans, arrays, objects.
+- There is no expiration and no persistence. For data that survives a reload, use [Storage](Storage.md).
+- Synchronous and dependency-free: subscribe handlers run in order and errors in one handler never break the others.
+
+## Related pages
+- [Session](Session.md) — tab-scoped persistence.
+- [Storage](Storage.md) — persistent storage.
+- [Frontend services guide](../guides/frontend-services.md) — choosing a storage layer.
+- [State guide](../guides/state.md) — `useState` and reactivity.
+
+---
+
+## Continue reading
+
+- **Previous:** [Services index](README.md)
+- **Next:** [Session](Session.md)
+- **Index:** [Services index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 9 · State, Router & Services** (1 of 4).

package/docs/services/Session.md

@@ -0,0 +1,84 @@
+# Session
+
+## Overview
+`Session` is the **tab-scoped** store, backed by `sessionStorage`. Data lives while the tab is open and disappears when the tab or the browser closes. It works with strings, numbers, booleans, arrays, and objects.
+
+## When to use
+- Remember something for "this visit only": a cart while the user is on the page, a wizard step, a temporary token (see the security note).
+- Keep data between multiple widgets that must not survive a full page reload more than once.
+
+## Import
+
+```javascript
+import { saveSession, getSession, Session } from "flet-box";
+```
+
+Every function also exists as a method of the exported `Session` object. The API mirrors [RamStore](RamStore.md) and [Storage](Storage.md) so you can swap the layer without rewriting your calls.
+
+## Functions
+
+| Function | Signature | Returns | Description |
+| --- | --- | --- | --- |
+| `saveSession` | `saveSession(key, value)` | `boolean` | Store `value` under `key` in `sessionStorage`. |
+| `getSession` | `getSession(key)` | `T \| null` | Read the value (async-safe wrapper). |
+| `getSessionSync` | `getSessionSync(key)` | `T \| null` | Read the value synchronously. |
+| `updateSession` | `updateSession(key, value)` | `boolean` | Replace the value. |
+| `deleteSession` | `deleteSession(key)` | `boolean` | Remove one key. |
+| `clearAllSession` | `clearAllSession()` | `boolean` | Remove every key for this tab session. |
+| `hasSession` | `hasSession(key)` | `boolean` | Is the key present? |
+| `getAllSessionKeys` | `getAllSessionKeys()` | `string[]` | All stored keys. |
+| `getAllSessionData` | `getAllSessionData()` | `Record<string, any>` | Every key/value pair. |
+| `getSessionSize` | `getSessionSize()` | `number` | Approximate size in bytes. |
+| `deleteSessionByPrefix` | `deleteSessionByPrefix(prefix)` | `number` | Delete every key starting with `prefix`; returns the count. |
+| `deleteSessionBySuffix` | `deleteSessionBySuffix(suffix)` | `number` | Delete every key ending with `suffix`; returns the count. |
+| `getSessionItemCount` | `getSessionItemCount()` | `number` | How many keys are stored. |
+| `isSessionAvailable` | `isSessionAvailable()` | `boolean` | Is `sessionStorage` available? |
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { saveSession, getSession } from "flet-box";
+
+saveSession("wizard-step", 3);
+const step = getSession("wizard-step");
+```
+
+### Full example
+
+```javascript
+import { saveSession, getSessionSync, deleteSessionByPrefix } from "flet-box";
+
+saveSession("form.name", "Ada");
+saveSession("form.age", 36);
+saveSession("draft-note", "hello");
+
+getSessionSync("form.name"); // "Ada"
+
+// remove all dashboard form keys at once:
+const removed = deleteSessionByPrefix("form.");
+console.log(removed); // 2
+```
+
+## Notes
+
+- `sessionStorage` survives a *refresh* (F5) but not a new tab or a closed browser.
+- Objects and arrays are serialized (and restored) as JSON automatically.
+- Use `getSessionSync` inside hot paths where you cannot wait for a promise.
+- **Security.** Never store passwords, private keys, or security tokens in browser storage — it is readable by anyone with access to the device. Protect sensitive data with server-side authorization.
+
+## Related pages
+- [RamStore](RamStore.md) — the in-memory reactive store.
+- [Storage](Storage.md) — persistent storage.
+- [Frontend services guide](../guides/frontend-services.md) — choosing a storage layer.
+
+---
+
+## Continue reading
+
+- **Previous:** [RamStore](RamStore.md)
+- **Next:** [Storage](Storage.md)
+- **Index:** [Services index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 9 · State, Router & Services** (2 of 4).

package/docs/services/Storage.md

@@ -0,0 +1,88 @@
+# Storage
+
+## Overview
+`Storage` is the **persistent** store, backed by `localStorage`. Data survives browser restarts until it is cleared — this is the layer for preferences, drafts, or saved documents. It works with strings, numbers, booleans, arrays, and objects.
+
+## When to use
+- Remember settings and user data between visits.
+- Cache what the user has written (drafts, recent items) across reloads.
+- Pair with [Session](Session.md) for short-lived data and [RamStore](RamStore.md) for live reactive state.
+
+## Import
+
+```javascript
+import { saveData, getData, Storage } from "flet-box";
+```
+
+Every function also exists as a method of the exported `Storage` object. The API mirrors [RamStore](RamStore.md) and [Session](Session.md) so you can swap the layer without rewriting your calls.
+
+## Functions
+
+| Function | Signature | Returns | Description |
+| --- | --- | --- | --- |
+| `saveData` | `saveData(key, value)` | `boolean` | Persist `value` under `key` in `localStorage`. |
+| `getData` | `getData(key)` | `T \| null` | Read the value (async-safe wrapper). |
+| `getDataSync` | `getDataSync(key)` | `T \| null` | Read the value synchronously. |
+| `updateData` | `updateData(key, value)` | `boolean` | Replace the value. |
+| `deleteData` | `deleteData(key)` | `boolean` | Remove one key. |
+| `clearAllData` | `clearAllData()` | `boolean` | Remove every key. |
+| `hasData` | `hasData(key)` | `boolean` | Is the key present? |
+| `getAllKeys` | `getAllKeys()` | `string[]` | All stored keys. |
+| `getAllData` | `getAllData()` | `Record<string, any>` | Every key/value pair. |
+| `getStorageSize` | `getStorageSize()` | `number` | Approximate size in bytes. |
+| `deleteDataByPrefix` | `deleteDataByPrefix(prefix)` | `number` | Delete every key starting with `prefix`; returns the count. |
+| `deleteDataBySuffix` | `deleteDataBySuffix(suffix)` | `number` | Delete every key ending with `suffix`; returns the count. |
+| `getItemCount` | `getItemCount()` | `number` | How many keys are stored. |
+| `isStorageAvailable` | `isStorageAvailable()` | `boolean` | Is `localStorage` available? |
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { saveData, getData } from "flet-box";
+
+saveData("settings", { theme: "dark", fontSize: 18 });
+const settings = getData("settings");
+```
+
+### Full example
+
+```javascript
+import { saveData, getDataSync, hasData, deleteDataByPrefix } from "flet-box";
+
+if (!hasData("drafts")) {
+  saveData("drafts", []);
+}
+
+saveData("drafts.1", "WIP chapter");
+saveData("drafts.2", "README draft");
+
+getDataSync("drafts.1"); // "WIP chapter"
+
+// clean up this feature's keys:
+deleteDataByPrefix("drafts.");
+```
+
+## Notes
+
+- Data survives restarts and new tabs, until you remove it. It is shared across tabs of the same origin.
+- Objects and arrays are serialized (and restored) as JSON automatically.
+- `localStorage` is limited (about 5 MB per origin) and synchronous — keep the values small.
+- Use `getDataSync` when you need the value immediately.
+- **Security.** Never store passwords, private keys, or security tokens in browser storage — it is readable by anyone with access to the device. Protect sensitive data with server-side authorization.
+
+## Related pages
+- [RamStore](RamStore.md) — the in-memory reactive store.
+- [Session](Session.md) — tab-scoped persistence.
+- [Frontend services guide](../guides/frontend-services.md) — choosing a storage layer.
+
+---
+
+## Continue reading
+
+- **Previous:** [Session](Session.md)
+- **Next:** [HTTP client](http.md)
+- **Index:** [Services index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 9 · State, Router & Services** (3 of 4).

package/docs/services/http.md

@@ -0,0 +1,86 @@
+# HTTP client
+
+## Overview
+FletBox ships a small `fetch`-based HTTP client. Five shortcuts — `httpGet`, `httpPost`, `httpPut`, `httpPatch`, `httpDelete` — and one generic function, `httpRequest`, handle requests with JSON bodies, query parameters, custom headers, and timeouts. Every call returns a `Promise`.
+
+## When to use
+- Talk to a REST API from your FletBox app.
+- Stick to one consistent client instead of wrapping `fetch` yourself.
+
+## Import
+
+```javascript
+import { httpGet, httpPost, httpRequest } from "flet-box";
+```
+
+## Options
+
+`options` is an object (the type is `HttpRequestOptions`) that extends the browser `RequestInit`:
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `body` | any | Request body. Objects/arrays are JSON-stringified automatically when you pass them (set `Content-Type: application/json`). |
+| `headers` | `Record<string, string>` | Extra headers merged with the defaults. |
+| `params` | `Record<string, string \| number \| boolean \| null \| undefined>` | Query parameters appended to the URL. |
+| `timeout` | number | Abort the request after this many ms. |
+| …plus `RequestInit` | — | `method`, `credentials`, `mode`, `signal`, etc. |
+
+## Functions
+
+| Function | Signature | Returns | Description |
+| --- | --- | --- | --- |
+| `httpRequest` | `httpRequest(method, url, options?)` | `Promise<T>` | Any HTTP method with full options. |
+| `httpGet` | `httpGet(url, options?)` | `Promise<T>` | `GET` shortcut. |
+| `httpPost` | `httpPost(url, options?)` | `Promise<T>` | `POST` shortcut. |
+| `httpPut` | `httpPut(url, options?)` | `Promise<T>` | `PUT` shortcut. |
+| `httpPatch` | `httpPatch(url, options?)` | `Promise<T>` | `PATCH` shortcut. |
+| `httpDelete` | `httpDelete(url, options?)` | `Promise<T>` | `DELETE` shortcut. |
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { httpGet, httpPost } from "flet-box";
+
+const users = await httpGet("/api/users");
+const created = await httpPost("/api/users", {
+  body: { name: "Ada" },
+  headers: { "Content-Type": "application/json" },
+});
+```
+
+### Full example
+
+```javascript
+import { httpGet } from "flet-box";
+
+const result = await httpGet("https://api.example.com/search", {
+  params: { q: "fletbox", page: 1, perPage: 20 },
+  timeout: 8000, // give up after 8 seconds
+});
+
+console.log(result.items);
+```
+
+## Notes
+
+- Responses are parsed as JSON automatically when possible.
+- `params` values are appended as query strings; `null`/`undefined` values are skipped.
+- A `timeout` aborts the request with an error once the time is reached.
+- The client depends only on the browser `fetch` API — no external library.
+
+## Related pages
+- [Frontend services guide](../guides/frontend-services.md) — choosing storage vs. network.
+- [Frontend services](../services/README.md) — the full services map.
+- [Tools](../tools/README.md) — the helper functions (next chapter).
+
+---
+
+## Continue reading
+
+- **Previous:** [Storage](Storage.md)
+- **Next:** [Tools index](../tools/README.md) — Chapter 10
+- **Index:** [Services index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 9 · State, Router & Services** (4 of 4).