Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 16 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand All @@ -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" |

Expand All @@ -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
Expand All @@ -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,
Expand All @@ -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

Expand Down
2 changes: 1 addition & 1 deletion proof/gateway.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
//
Expand Down
16 changes: 9 additions & 7 deletions python/src/lazurio_module_kit/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 5 additions & 3 deletions src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 =
Expand Down
5 changes: 3 additions & 2 deletions test/index.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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(
Expand Down
Loading