From 151d7c4f44089ecc941ca5661a92876c12e6182e Mon Sep 17 00:00:00 2001 From: cproudlock Date: Thu, 27 Aug 2026 12:51:58 -0400 Subject: [PATCH] Anyone not signed in holds the guest role Whether somebody with no account may see something was being answered one feature at a time: a securesend_allow_guests setting, an enable flag per kiosk, and very nearly a third for guides - each with its own settings page, its own vocabulary and its own hand-written branch inside a route. Every one of them answered a permissions question, and this app already administers permissions per role. So a caller with no token is not nobody: they hold the seeded `guest` role. require_permission consults it when there is no identity, which is the entire mechanism. The role is seeded holding NOTHING, so an upgrade opens no door; a site opens one by ticking a box in the same grid it uses for every other role, and closes it the same way. Revocation is read on every request rather than cached, because taking guest access away is what somebody does the moment they realise what they opened, and it has to bite immediately. The redundant @jwt_required() above require_permission is gone from 184 routes. It was belt-and-braces before; now it is actively wrong, because it refuses a request with no token before the permission check can have an opinion, so a grant would appear to do nothing. What a guest may hold is bounded. Any .view or .read permission is grantable. A WRITE has to be blessed by whoever owns it, through the new get_guest_grantable_permissions hook (contract 0.21.0), and Secure Send is the only case that exists: sending a password to a vendor is the one write this product means to offer somebody who never signs in. Everything else is refused by the API and greyed out in the grid rather than warned about - a checkbox that quietly makes deleting an asset anonymous is not a warning anybody reads twice. A guest write records no creator: the trail says when and from where, never who, and that is the reason for the bar. GE-Enforce and Slides gained read permissions so they can be opened to guests without handing out the manage right. Their read routes accept either through require_any_permission, so nothing an existing manager could reach has moved. The navigation endpoint now returns only what the caller can actually reach. Without that a signed-out visitor gets a sidebar of the whole app where every link bounces off the login page, which reads as a broken site rather than as a closed door. A nav item may name several permissions; holding any one is enough, which is what GE-Enforce and Slides need now that a viewer and a manager hold different strings. Two things this found on the way: current_user is a LocalProxy, so `current_user is None` is False for a request with nobody behind it - harmless under a required JWT, an AttributeError the moment verification became optional. And an image pasted into a guide before its first save was never attached to it, so it was visible to editors and invisible to every reader; saving now attaches it, and `flask guides fix-images` repairs what is stored. The guides guest setting written earlier today is gone. Granting guides.view to the guest role replaces it, which is the point. --- CHANGELOG.md | 28 ++++ docs/CONTRACT-STABILITY.md | 1 + docs/PLUGIN-HOOKS.md | 34 ++++ docs/PROJECT-MAP.md | 4 +- frontend/src/views/AppLayout.vue | 23 ++- frontend/src/views/settings/UsersList.vue | 46 +++++- plugins/backups/api/routes.py | 7 - plugins/computers/api/routes.py | 14 -- plugins/geenforce/api/routes.py | 55 ++----- plugins/geenforce/plugin.py | 5 + plugins/guides/api/routes.py | 98 ++++++++--- plugins/guides/cli.py | 46 ++++++ plugins/guides/frontend/routes.js | 13 +- plugins/guides/plugin.py | 4 + plugins/knowledgebase/api/routes.py | 3 - plugins/machines/api/routes.py | 7 - plugins/measuringtools/api/routes.py | 6 - plugins/network/api/routes.py | 12 -- plugins/notifications/api/routes.py | 5 - plugins/printedparts/api/routes.py | 13 -- plugins/printedparts/plugin.py | 3 + plugins/printers/api/asset_routes.py | 18 -- plugins/slides/api/routes.py | 9 +- plugins/slides/plugin.py | 6 +- plugins/tools/plugin.py | 13 ++ plugins/usb/api/routes.py | 6 - plugins/warranty/api/routes.py | 9 - shopdb/__init__.py | 2 +- shopdb/api/__init__.py | 3 +- shopdb/cli/__init__.py | 11 +- shopdb/core/api/apitokens.py | 3 - shopdb/core/api/applications.py | 12 -- shopdb/core/api/assets.py | 13 -- shopdb/core/api/auditlogs.py | 5 - shopdb/core/api/dashboard.py | 20 +++ shopdb/core/api/mappositions.py | 5 - shopdb/core/api/reports.py | 1 - shopdb/core/api/settings.py | 4 - shopdb/core/api/users.py | 32 +++- shopdb/core/models/__init__.py | 4 +- shopdb/core/models/user.py | 82 ++++++++++ shopdb/plugins/base.py | 17 ++ shopdb/utils/authz.py | 131 ++++++++++++++- tests/test_core/test_guest_role.py | 190 ++++++++++++++++++++++ 44 files changed, 783 insertions(+), 240 deletions(-) create mode 100644 tests/test_core/test_guest_role.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a8c36f6..e24d97de 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,34 @@ ADR-007 and ADR-002. ### Added +- **A guest is a role now, not a switch per feature.** Whether somebody with no + account may see something was answered one feature at a time: a + `securesend_allow_guests` setting, an enable flag per kiosk, and very nearly a + third for guides - each with its own settings page and its own hand-written + branch inside a route. It is a permissions question, and this app already + administers permissions per role, so anyone not signed in now holds the + seeded `guest` role. It starts with nothing, so an upgrade opens no door; a + site opens one by ticking a box in the same role grid it uses for everybody + else, and closes it the same way - taking effect on the next request, not the + next restart. `require_permission` consults the role when there is no token, + which is the whole mechanism. + + What a guest may be granted is bounded: any `.view` or `.read` permission, + plus writes a plugin has explicitly declared safe to perform without an + account (`get_guest_grantable_permissions`, contract 0.21.0). Secure Send + declares its create permission, because sending a password to a vendor is the + one write the product means to offer somebody who never signs in. Everything + else is refused by the API and greyed out in the grid rather than warned + about. A guest write records no creator - the audit trail can say when and + from where, never who - and that is the reason for the bar. + + GE-Enforce and Slides gained read permissions (`geenforce.view`, + `slides.view`) so they can be opened to guests without handing out the manage + right; their read routes accept either, so nothing an existing manager could + reach has moved. The navigation endpoint now returns only what the caller can + actually reach, so a signed-out visitor sees the pages that were opened to + them rather than a sidebar of links that bounce off a login page. + - **USB check-in / check-out audit report.** CMMC removable-media tracking is an audit obligation and there was no report for it - answering "who had this drive, and when" meant paging through the check-in/out list by hand. The diff --git a/docs/CONTRACT-STABILITY.md b/docs/CONTRACT-STABILITY.md index 3e31faa8..3ed4d4f2 100644 --- a/docs/CONTRACT-STABILITY.md +++ b/docs/CONTRACT-STABILITY.md @@ -40,6 +40,7 @@ Recorded in the comment block in `shopdb/__init__.py`: | 0.18.0 | Added `DISPLAY_ROLES`, `DISPLAY_ROLE_PATHS` and `normalize_display_role`, and finally exported `DashboardDefault`, which 0.17.0 imported but left out of `__all__`. The role vocabulary became the kiosk's own - `Dashboard`, `Lobby`, `3DPrintRoom` - so a plugin holding its own copy of that map reads core's instead of drifting from it | additive surface (minor) | | 0.19.0 | **BREAKING.** `get_dashboard_widgets` returns DATA AND SHAPE, not a component name. The old shape (`name` + `component` + `size`) named a Vue component per widget, which cannot survive a lean build - a plugin's component may never be staged into the frontend bundle (ADR-013) - and five plugins were declaring widgets that pointed at components nobody had written. A card now declares `id` / `title` / `endpoint` / `render` / `severity` / `permission` / `empty` / `position`; see PLUGIN-HOOKS.md. Also added `send_upload` so a plugin serving user-supplied bytes gets the headers that keep an SVG from running as script | **contract change (minor, pre-1.0)** | | 0.20.0 | The `Asset` model gained `levelid` (which floor plan its `mapx`/`mapy` are pixels of) and `mapverifiedat`; `Location` gained `levelid` too, and `resolve_asset_position` now returns the `levelid` belonging to whichever source supplied the coordinates. A plugin that writes a map position MUST write the level with it - a position without one renders as "level unknown" rather than being drawn on the default drawing, because a marker on the wrong floor plan looks correct (ADR-017) | additive surface (minor) | +| 0.21.0 | Added the `get_guest_grantable_permissions` hook: a plugin names the WRITE permissions a site may grant to the seeded `guest` role, which is who anyone without a token now holds. Reads (`.view`/`.read`) are grantable without a plugin saying anything; anything else is refused. Also exposed `require_any_permission` on `shopdb.api` for a read two different rights should reach | additive optional hook + surface (minor) | The source comment block documents 0.3.0, 0.4.0, 0.6.0, 0.7.0, 0.9.0, 0.10.0, 0.11.0, 0.16.0, 0.18.0 and 0.19.0; 0.12.0 through 0.15.0 and 0.17.0 are recorded diff --git a/docs/PLUGIN-HOOKS.md b/docs/PLUGIN-HOOKS.md index e8850fe7..ae4573de 100644 --- a/docs/PLUGIN-HOOKS.md +++ b/docs/PLUGIN-HOOKS.md @@ -298,6 +298,40 @@ The `Permission` ROWS already in the database are NOT deleted, so roles that already reference them keep working until an admin edits the role. A broken plugin is isolated in prod and re-raised in dev/test. +### `get_guest_grantable_permissions() -> List[str]` + +Names the WRITE permissions this plugin allows a site to grant to the `guest` +role. Added in contract 0.21.0. + +Anyone with no account holds the `guest` role. It is seeded with nothing, and a +site opens a door by granting it a permission in the role grid - which replaced +the per-feature booleans (`securesend_allow_guests`, one per kiosk) that used to +answer the same question one feature at a time. + +Any `.view` or `.read` permission is grantable without a plugin saying anything. +This hook is only for the exception: a write that is genuinely meant to work for +somebody who never signs in. Naming one here does not open it - it makes the +checkbox available, and a site still has to tick it. + +```python +class ToolsPlugin(BasePlugin): + def get_guest_grantable_permissions(self): + # Sending a password to a vendor: the recipient has no account here, + # and often neither does the sender. The unguessable token is the + # authorisation and the link is one-view. + return ['tools.secrets'] +``` + +The bar for naming one: could this action be attributed to nobody, forever, and +still be defensible in the audit log? A guest write records no creator - the +trail says when and from where, never who. Return `[]` (the default) and none of +this plugin's writes can ever be made anonymous; anything not named is refused +by the API when an admin tries to grant it, not merely warned about. + +Consumed by `guest_grantable_permissions()`, which backs the role API's guard on +the guest role and the greyed-out checkboxes in the role grid. A plugin may only +bless permissions that already exist in the catalog, so a typo widens nothing. + ### `get_settings_cards() -> List[Dict]` Returns settings-catalog card definitions. Added in contract 0.7.0 (ADR-010). diff --git a/docs/PROJECT-MAP.md b/docs/PROJECT-MAP.md index a69853e0..89d046ef 100644 --- a/docs/PROJECT-MAP.md +++ b/docs/PROJECT-MAP.md @@ -12,7 +12,7 @@ never by editing this file. | series | value | governed by | |---|---|---| | product `__version__` | `0.12.0` | ADR-007 | -| plugin contract `__contract_version__` | `0.20.0` | ADR-002 | +| plugin contract `__contract_version__` | `0.21.0` | ADR-002 | They move independently. A contract bump is not a release. @@ -88,6 +88,6 @@ Manifest-less directories under `plugins/` are core frontend surface and always ## Size -- test functions defined: **1396** (parametrised cases collect higher) +- test functions defined: **1413** (parametrised cases collect higher) - documented API paths: **305** (`docs/openapi.json`, regenerate with `scripts/gen_openapi.py`) diff --git a/frontend/src/views/AppLayout.vue b/frontend/src/views/AppLayout.vue index 2d37253a..8ea01593 100644 --- a/frontend/src/views/AppLayout.vue +++ b/frontend/src/views/AppLayout.vue @@ -11,7 +11,9 @@ -
+ +
slides.manage); hide it from anyone who lacks it so the // link does not dead-end at the router guard. Admins hold every permission. - const visible = items.filter(item => - !item.permission || authStore.hasPermission(item.permission)) + // + // A signed-out visitor sees only what a plugin has declared guest-reachable. + // Without this the sidebar offers a signed-out reader the whole app and every + // link bounces them to the login page, which reads as a broken site rather + // than as a closed door. + // A nav item may name one permission or several; holding ANY of them is + // enough. GE-Enforce and Slides need that: the page is reachable by a + // manager and by a plain viewer, and they hold different strings. + const holds = item => { + if (!item.permission) return true + const names = Array.isArray(item.permission) ? item.permission : [item.permission] + return names.some(name => authStore.hasPermission(name)) + } + // A signed-out visitor gets whatever the server sent, which is already + // filtered to what the guest role can reach - hasPermission knows nothing + // about guests, so asking it here would hide everything. + const visible = authStore.isAuthenticated ? items.filter(holds) : items const known = new Set(NAV_SECTIONS.map(s => s.key).filter(Boolean)) const bucket = item => { diff --git a/frontend/src/views/settings/UsersList.vue b/frontend/src/views/settings/UsersList.vue index 58fd9aaf..242506da 100644 --- a/frontend/src/views/settings/UsersList.vue +++ b/frontend/src/views/settings/UsersList.vue @@ -225,6 +225,17 @@

Select which actions this role can perform

+ +

+ This role is everyone who is not signed in. + Anything ticked here is readable by anybody who can reach this + site, with no account and no name in the audit log. Greyed-out + permissions cannot be given to guests at all. +

@@ -239,10 +250,14 @@
-