signatur 1.0.0 → 1.2.0

package/README.md

@@ -18,17 +18,26 @@ Supported file format include:
 
 ## Configuration
 
-| Name              | Type  | Default                              | Description                                                                                                                                            |
-| ----------------- | ----- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `BASE_URL`        | `str` | `http://localhost:3000`              | The base URL that is going to be used in the construction of external URLs for Signatur.                                                               |
-| `SIGNATUR_KEY`    | `str` | `None`                               | Secret key that should be passed in protected calls so that the server side "trusts" the client side (authentication).                                 |
-| `HEADLESS_URL`    | `str` | `https://headless.stage.hive.pt`     | The base URL to be used to access [Headless](https://github.com/hivesolutions/headless).                                                               |
-| `PRINT_URL`       | `str` | `https://colony-print.stage.hive.pt` | Base URL of the [Colony Print](http://colony-print.hive.pt) service used for both the engraving job and the receipt printing.                          |
-| `PRINT_NODE`      | `str` | `default`                            | Name of the Colony Print node to use when printing the report receipt.                                                                                 |
-| `PRINT_PRINTER`   | `str` | `printer`                            | Name of the printer (within the receipt node) to use when printing the report receipt.                                                                 |
-| `PRINT_KEY`       | `str` | `null`                               | Secret key used to authenticate against Colony Print; shared by both the engraving job and the receipt printing.                                       |
-| `ENGRAVE_NODE`    | `str` | value of `PRINT_NODE`                | Name of the Colony Print node to use when sending an engraving job; falls back to `PRINT_NODE` so existing single-printer deployments keep working.    |
-| `ENGRAVE_PRINTER` | `str` | value of `PRINT_PRINTER`             | Name of the printer (within the engrave node) to use when sending an engraving job; falls back to `PRINT_PRINTER` for the same backward compat reason. |
+| Name                  | Type   | Default                              | Description                                                                                                                                                                                                                     |
+| --------------------- | ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BASE_URL`            | `str`  | `http://localhost:3000`              | The base URL that is going to be used in the construction of external URLs for Signatur.                                                                                                                                        |
+| `SESSION_SECRET`      | `str`  | `signatur`                           | HMAC signing key for the `signatur.sid` cookie-session. Comma separated to support rotation: the first entry signs new cookies, the rest still validate previously issued ones. Changing the key invalidates all live sessions. |
+| `SESSION_MAX_AGE`     | `int`  | `15552000000`                        | Lifetime of the `signatur.sid` cookie in milliseconds; the default is ~6 months and the cookie is not rolling, so even active users are logged out once it elapses.                                                             |
+| `SIGNATUR_KEY`        | `str`  | `None`                               | Secret key that should be passed in protected calls so that the server side "trusts" the client side (authentication).                                                                                                          |
+| `HEADLESS_URL`        | `str`  | `https://headless.stage.hive.pt`     | The base URL to be used to access [Headless](https://github.com/hivesolutions/headless).                                                                                                                                        |
+| `PRINT_URL`           | `str`  | `https://colony-print.stage.hive.pt` | Base URL of the [Colony Print](http://colony-print.hive.pt) service used for both the engraving job and the receipt printing.                                                                                                   |
+| `PRINT_NODE`          | `str`  | `default`                            | Name of the Colony Print node to use when printing the report receipt.                                                                                                                                                          |
+| `PRINT_PRINTER`       | `str`  | `printer`                            | Name of the printer (within the receipt node) to use when printing the report receipt.                                                                                                                                          |
+| `PRINT_KEY`           | `str`  | `null`                               | Secret key used to authenticate against Colony Print; shared by both the engraving job and the receipt printing.                                                                                                                |
+| `ENGRAVE_NODE`        | `str`  | value of `PRINT_NODE`                | Name of the Colony Print node to use when sending an engraving job; falls back to `PRINT_NODE` so existing single-printer deployments keep working.                                                                             |
+| `ENGRAVE_PRINTER`     | `str`  | value of `PRINT_PRINTER`             | Name of the printer (within the engrave node) to use when sending an engraving job; falls back to `PRINT_PRINTER` for the same backward compat reason.                                                                          |
+| `FEATURE_CALLIGRAPHY` | `bool` | `false`                              | Base value of the calligraphy feature flag; when set to a truthy value (`1`, `true`, `yes`, `on`) the calligraphy mode controls render on `/viewport`. May be overridden per session through the `Features` tab on `/settings`. |
+
+## Authentication
+
+Every interactive route is gated behind a session login. The list of valid users lives in `config/users.json` (gitignored, with a `config/users.json.example` checked into the repository) as an array of `{ "username": "...", "password_hash": "$2a$...", "role": "admin" | "user" }` entries; the `role` controls whether the user can reach the admin-only surfaces (`/settings`, `/settings/diagnostics`, `/profiles/*`) or just the basic engraving flow.
+
+New users are added through the `npm run user:add <username> <role> [password]` helper which prompts for the password twice (no echo) when the third positional argument is omitted, bcrypts the value at cost 10 and rewrites `config/users.json` in place; passing the password as the optional third argument skips the interactive prompts so the same helper can be driven from CI scripts or container entrypoints, while the running application picks every change up automatically through `fs.watch` so no restart is required. The bare `/login` and `/logout` routes, the `/info` endpoint, the static assets and the engine `/convert` endpoint (key authenticated through `SIGNATUR_KEY`) stay public.
 
 ## Query Parameters
 
@@ -126,6 +135,8 @@ The configuration is resolved through a three step fallback chain so existing si
 
 The settings page exposes a `Printing` readout that shows the server side base value next to the effective resolved value for each entry, so an operator can verify at a glance which side is active.
 
+When the engraving job is submitted, the confirm modal walks the multifont array of the print payload, rewrites every `Cool Emojis` entry into the underlying engraving glyph name through the active `coolemojis.mapping.json` and then resolves the engraving `.f3s` payload of every referenced font through a `GET /settings/fonts/resolve?names=...` call. The resulting `{ name: base64 }` map is attached to the gravo print payload as the `extra_fonts` field that colony print plumbs through to gravo pilot on a per print job basis (see [hivesolutions/colony-print#20](https://github.com/hivesolutions/colony-print/issues/20) and [hivesolutions/gravo-pilot#22](https://github.com/hivesolutions/gravo-pilot/issues/22) for the receiving end).
+
 ### Configuration keys
 
 | `localStorage` key | Scenario | Server side fallback                            | Description                                                                         |
@@ -172,13 +183,58 @@ The same configuration can also be edited through the `Configure` modal accessib
 
 ### Adding New Emoji
 
-To add a new emoji to the system the following steps should be followed:
+To add a new emoji to the system, sign in as an admin and use the `Emojis` tab on `/settings`:
+
+1. Upload the replacement `coolemojis.ttf` (display) and, when the catalog of recognised characters changes, the companion `coolemojis.mapping.json`.
+2. Upload the matching engraving glyph as a `.f3s` file in the `Engraving glyphs` section. The filename must match a value declared on the mapping (e.g. `1101.coracao.f3s`).
+3. The next time the engraving viewport is opened the new glyphs are picked up automatically; shipping the `.f3s` payload to colony print on every print job through the `extra_fonts` field of the gravo print payload is tracked in #56.
+
+The admin UI replaces the previous manual file drop. The on disk layout it owns is documented in [Font Management](#font-management).
+
+### Adding New Fonts
+
+To add a new text font (Helvetica, Roman, Script, etc.) to the system, sign in as an admin and use the `Fonts` tab on `/settings`:
+
+1. Pick a lowercase hyphenated font name (e.g. `helvetica4l`).
+2. Upload both halves together: the display `.ttf` (browser font) and the engraving `.f3s` (engraving machine font). Both halves are required so the two surfaces stay in sync.
+3. The `Fonts` tab lists every installed font with both halves status; use the per row delete button to remove stale entries.
+
+## Font Management
+
+The on disk font catalog owned by the admin UI lives under `static/fonts/`:
+
+```text
+static/fonts/
+  coolemojis.ttf                  display, browser (Emojis tab)
+  coolemojis.mapping.json         display to engraving bridge (Emojis tab)
+  helvetica4l.ttf                 display, browser (Fonts tab)
+  ...
+  f3s/
+    emoji/                        engraving glyphs (Emojis tab)
+      1101.coracao.f3s
+      ...
+    fonts/                        engraving text fonts (Fonts tab)
+      helvetica4l.f3s
+      ...
+```
+
+Filename invariants are validated server side:
+
+* emoji `.f3s` files match `^[a-z0-9]+(?:[-.][a-z0-9]+)*\.f3s$` so the existing `1101.coracao` dotted form keeps working alongside a hyphenated form
+* text font names match `^[a-z0-9]+(?:-[a-z0-9]+)*$` so both halves land at the canonical `<name>.ttf` and `<name>.f3s` paths
+
+The following HTTP endpoints back the UI. Every entry is gated by `lib.requireAdmin` except the resolver at the bottom, which is callable by any signed in user so the print confirm modal can attach the engraving payloads to the print envelope without elevating privileges:
 
-1. Determine the right file name for the new emoji font file (e.g. `coolemojis.ttf` for laser and `coolemojisp.ttf` for pantogrpah)
-2. Place the new font file in the `static/fonts` directory
-3. Add the new emoji "characters" to the `emoji` array in the `viewport.ejs` file
-4. Test the using the local machine `yarn && yarn dev`
-5. Release a new version of the system (Docker Image)
+| Method | Path                                       | Notes                                                                                         |
+| ------ | ------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| `POST` | `/settings/emojis`                         | Replace the Cool Emojis `.ttf` and, optionally, the companion mapping JSON.                   |
+| `GET`  | `/settings/emojis/f3s`                     | List installed emoji engraving glyphs as `{ fonts: [{ name, size, mtime }, ...] }`.           |
+| `POST` | `/settings/emojis/f3s`                     | Upload one emoji engraving glyph; form fields are `filename` plus the `file` payload.         |
+| `POST` | `/settings/emojis/f3s/:filename/delete`    | Delete one emoji engraving glyph by filename.                                                 |
+| `GET`  | `/settings/fonts`                          | List installed text fonts as `{ fonts: [{ name, ttf, f3s }, ...] }` rows.                     |
+| `POST` | `/settings/fonts`                          | Upload one paired text font; form fields are `name` plus the `ttf` and `f3s` file payloads.   |
+| `POST` | `/settings/fonts/:name/delete`             | Delete both halves of a text font by canonical name.                                          |
+| `GET`  | `/settings/fonts/resolve?names=a,b,c`      | Resolve font names into a `{ fonts: { name: base64 } }` engraving payload map.                |
 
 ## License