From 31aed5115a1b58c5615fd01e804438a1e9ac86e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mat=C4=9Bj=20Such=C3=A1nek?= <16311043+immakermatty@users.noreply.github.com> Date: Sun, 8 Nov 2026 17:51:53 +0000 Subject: [PATCH] Docs: name the application roles by decision 0234 The README "Who came and with which role" section and the doc comments of appAccess / AppAccess (TypeScript and Python) now say Application Admin and Application User instead of a lowercase "application admin" or a bare "user", and map them once to the stable appRole / app_role values "admin" and "user", which do not change. "The Environment's assignee" becomes the Environment's Assigned User. One test title and one test comment follow the same names. No code, field, value or header changes. Co-Authored-By: Claude Opus 5.5 --- README.md | 27 ++++++++++++++--------- proof/gateway.ts | 2 +- python/src/lazurio_module_kit/__init__.py | 16 ++++++++------ src/index.ts | 8 ++++--- test/index.test.ts | 5 +++-- 5 files changed, 34 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 9825a55..f18eb58 100644 --- a/README.md +++ b/README.md @@ -70,12 +70,14 @@ try { ## Who came and with which role Lazurio decides who may open a Module's App and with which application role, -application admin or application user, and the Organization decides in the -Module's code what each role may do (Lazurio decision 0231). `appAccess` is the -only way a Module learns it, and its answer is the stable contract: its fields -and values never change meaning or disappear, and new information comes as new -fields. The contract is the Module Standard's "Who came and with which role" -in Lazurio Platform (`docs/module-standard.md`). +Application Admin or Application User, and the Organization decides in the +Module's code what each role may do (Lazurio decisions 0231 and 0234). +`appRole` carries the role as a stable value, `"admin"` for the Application +Admin and `"user"` for the Application User; the values do not change with the +names. `appAccess` is the only way a Module learns it, and its answer is the +stable contract: its fields and values never change meaning or disappear, and +new information comes as new fields. The contract is the Module Standard's +"Who came and with which role" in Lazurio Platform (`docs/module-standard.md`). ```ts import { appAccess } from "@lazurio/module-kit"; @@ -93,7 +95,7 @@ Every answer has the same five fields: | `entry` | `appRole` | `person` | `source` | `reason` | When | | --- | --- | --- | --- | --- | --- | | `environment` | `admin` | subject and username | `gateway` | `null` | the person has the whole Environment where the App runs | -| `app` | `admin` or `user` | subject and username | `gateway` | `null` | the person has this App only, with the role the Organization gave them | +| `app` | `admin` or `user` | subject and username | `gateway` | `null` | the person has this App only, with the application role the Organization gave them | | `local` | `admin` | `null` | `null` | `not-hosted`, `not-through-gateway`, `local-entry` | from inside the Environment: no gateway in front of the App (a person's own computer), a request to a loopback address (a sibling, a script, an agent), or the Environment browser's local entry | | `unknown` | `null` | `null` | `null` | `no-identity` | through the gateway without a valid statement, or a `Host` that is neither the App's hostname nor loopback: no role, show "unavailable" | @@ -111,9 +113,10 @@ role. names the new person. - **Remember a person by `subject`**, show `username` (`null` when the gateway named none). Never fill in a name from the browser, the operating system - account or the Environment's assignee. + account or the Environment's Assigned User. - **Finer roles are the Module's.** Approvers, technicians and the like live in - the Module's own data, keyed by `subject`. Lazurio keeps only the two roles. + the Module's own data, keyed by `subject`. Lazurio keeps only the two + application roles, Application Admin and Application User. - **Its boundary is the Environment.** A process on the Environment that reaches the App's loopback port could send anything, as it could read the App's data. The statement holds against visitors who have only the App, not against the @@ -126,7 +129,7 @@ role. renders the Lazurio workspace gateway from a Machines checkout, runs it with Caddy in front of a TypeScript App and a Python App and checks every Host form a client can send: the App's hostname as is, in upper case, with `:443` or -another port (the gateway's statement counts: `environment`/admin with a +another port (the gateway's statement counts: `environment`/`admin` with a person, `unknown` without one, nothing without a session) and with a trailing dot (refused by the gateway itself). A client's forged statement never counts and no request through the gateway is `local`. It needs Caddy, OpenSSL and uv, @@ -135,7 +138,9 @@ so it is not part of `bun test`. Python: `app_access(headers, "app")` takes the request headers as a mapping (matched case-insensitively; a repeated header reads as none) and returns `AppAccess(entry, app_role, person, source, reason)` with -`AppPerson(subject, username)` or `None`, by the same rules. +`AppPerson(subject, username)` or `None`, by the same rules; `app_role` takes +the same values, `"admin"` for the Application Admin and `"user"` for the +Application User. ## Bun.serve diff --git a/proof/gateway.ts b/proof/gateway.ts index fd41394..ad21232 100644 --- a/proof/gateway.ts +++ b/proof/gateway.ts @@ -3,7 +3,7 @@ // front of two Apps, one reading `appAccess` (TypeScript) and one reading // `app_access` (Python). It shows that a request through the gateway, with // the App's hostname in any letter case, with a port or a trailing dot, -// counts only by the gateway's statement: a person is `environment`/admin, an +// counts only by the gateway's statement: a person is `environment`/`admin`, an // admitted session without a person is `unknown`, a client's forged statement // never counts, and no such request is ever `local`. // diff --git a/python/src/lazurio_module_kit/__init__.py b/python/src/lazurio_module_kit/__init__.py index 716f19c..8b2a985 100644 --- a/python/src/lazurio_module_kit/__init__.py +++ b/python/src/lazurio_module_kit/__init__.py @@ -171,13 +171,15 @@ class AppAccess: the same contract as ``appAccess`` of the TypeScript package, with the same five fields in every answer. - ``entry`` is ``environment`` (the whole Environment, so ``app_role`` is - ``admin``), ``app`` (this App only, with the role the Organization gave), - ``local`` (a request from inside the Environment: an application admin - without a name) or ``unknown`` (no role). With a person ``source`` says - who stated it and ``reason`` is ``None``; without one ``source`` is - ``None`` and ``reason`` says why. Fields and values never change meaning - or disappear.""" + ``app_role`` carries the application role of decision 0234 as a stable + value: ``admin`` is the Application Admin and ``user`` the Application + User. ``entry`` is ``environment`` (the whole Environment, so ``app_role`` + is ``admin``), ``app`` (this App only, with the application role the + Organization gave), ``local`` (a request from inside the Environment: an + Application Admin without a name) or ``unknown`` (no role). With a person + ``source`` says who stated it and ``reason`` is ``None``; without one + ``source`` is ``None`` and ``reason`` says why. Fields and values never + change meaning or disappear.""" entry: Entry app_role: AppRole | None diff --git a/src/index.ts b/src/index.ts index 95fe1e1..9412fd9 100644 --- a/src/index.ts +++ b/src/index.ts @@ -354,16 +354,18 @@ export type AppPerson = Readonly<{ * change meaning or disappear, and new information comes as new fields. * * - `environment`: the person has the whole Environment where the App runs, - * so they are an application admin. + * so they are an Application Admin. * - `app`: the person has this App only, with the application role the * Organization gave them. * - `local`: a request from inside the Environment (a person's own computer * with no gateway, a sibling or a script on the Environment, or the - * Environment browser's local entry): an application admin without a name. + * Environment browser's local entry): an Application Admin without a name. * - `unknown`: a request that came through the gateway without identity * (a gateway without this capability): no application role at all. * - * What application admin and application user may do is the Organization's + * `appRole` carries the application role of decision 0234 as a stable value: + * `"admin"` is the Application Admin and `"user"` the Application User. What + * an Application Admin and an Application User may do is the Organization's * rule in the Module's code, enforced on the server for every request. The * answer is no key to data and signs nothing. */ export type AppAccess = diff --git a/test/index.test.ts b/test/index.test.ts index 189face..255ff83 100644 --- a/test/index.test.ts +++ b/test/index.test.ts @@ -526,7 +526,7 @@ describe("appAccess", () => { reason, }) as const; - test("the whole Environment: an application admin with the person", () => { + test("the whole Environment: an Application Admin with the person", () => { expect(appAccess(through(person()), "app", HOSTED)).toEqual({ entry: "environment", appRole: "admin", @@ -602,7 +602,8 @@ describe("appAccess", () => { `${HOST}.`, `Deals.Vm-01.Example.Lazurio.Io.:443`, ]) { - // A visitor with this App only stays a user, never a local admin. + // A visitor with this App only stays an Application User, never a local + // Application Admin. expect( appAccess( through(