@owlmeans/auth-common 0.1.18-rc.9 → 0.1.18

package/README.md

@@ -1,10 +1,10 @@
 # @owlmeans/auth-common
 
-Predefined authentication modules, guards, and constants shared between server and client packages.
+Predefined authentication protocols, guards, and constants shared between server and client packages.
 
 ## Overview
 
-- Exports standard auth module definitions (login, init, rely, dispatcher) ready to register in any app
+- Exports the immutable `authProtocols` and `managerProtocols` trees for login, init, rely, and dispatcher flows
 - Provides `DEFAULT_GUARD` and `GUARD_ED25519` constants for protecting routes
 - Implements the Basic ED25519 signature guard service for cryptographic request authentication
 - Headers: `BED255_NONCE_HEADER`, `BED255_TIME_HEADER` for auth challenge/response
@@ -12,35 +12,41 @@ Predefined authentication modules, guards, and constants shared between server a
 ## Installation
 
 ```bash
-bun add @owlmeans/auth-common
+bun add @owlmeans/auth-common@^0.1.18
 ```
 
 ## Usage
 
-Register the built-in auth modules and protect a route:
+Import the shared declarations and bind them only through the server or browser package that owns
+the runtime behaviour:
 
 ```typescript
-import { modules } from '@owlmeans/auth-common'
+import { authProtocols } from '@owlmeans/auth-common'
 import { GUARD_ED25519, DEFAULT_GUARD } from '@owlmeans/auth-common'
 
-// Add auth modules to your app (includes /authentication, /login, /dispatcher routes)
-await main(context, [...modules, ...appModules])
+// Call the exact registered declaration; do not look up auth routes by an alias string.
+await context.entrypoint(authProtocols.dispatcherAuthenticate).call({ body: token })
 ```
 
 Protect a route with the ED25519 signature guard (re-exported via `@owlmeans/server-app`):
 
 ```typescript
 import { GUARD_ED25519 } from '@owlmeans/auth-common'
-import { module, guard } from '@owlmeans/server-app'
-
-const adminModule = module(route('admin', '/api/admin'), guard(GUARD_ED25519))
+import { contract, protocol, typed } from '@owlmeans/entrypoint'
+import { route } from '@owlmeans/route'
+
+const adminProtocol = protocol(
+  route('admin', '/api/admin'),
+  contract(typed<AdminResponse>()),
+  { guards: GUARD_ED25519 },
+)
 ```
 
 ## API
 
-### `modules`
+### `authProtocols`
 
-Array of pre-built `CommonModule` instances covering the standard auth flow:
+Immutable shared declarations covering the standard auth flow:
 - `AUTHEN` — backend `/authentication` base route
 - `AUTHEN_INIT` — POST `/authentication/init` (allowance request)
 - `AUTHEN_AUTHEN` — POST `/authentication/authenticate` (credential submission)
@@ -48,6 +54,14 @@ Array of pre-built `CommonModule` instances covering the standard auth flow:
 - `CAUTHEN`, `CAUTHEN_AUTHEN` — frontend auth routes
 - `DISPATCHER` — frontend dispatcher route (sticky, handles redirect auth tokens)
 
+`@owlmeans/server-auth`, `@owlmeans/client-auth`, and the OIDC packages export local runtime
+binding arrays for the declarations they serve. Keep those arrays local to the runtime; application
+code uses this tree's protocol objects.
+
+### `managerProtocols`
+
+Immutable shared manager protocol tree for profile-to-organization mapping and auth delegation.
+
 ### Guard Constants
 
 ```typescript
@@ -66,15 +80,15 @@ BED255_CASHE_RESOURCE // resource alias for nonce cache
 ## Product-Viable Integration Notes
 
 - `DEFAULT_GUARD` protects manager routes after bearer authentication is installed by `@owlmeans/server-auth`.
-- Product authorization composes a custom gate inside `guard(DEFAULT_GUARD, gate(VIABLE_AUTH_GATE, [...]))` rather than using `OIDC_GATE` for Google login flows.
+- Product authorization composes a custom gate in the protocol options rather than using `OIDC_GATE` for Google login flows.
 - `GUARD_ED25519` remains the service-to-service guard for internal/publisher/payment/auth-service calls.
-- The browser-side alias from `@owlmeans/client-auth` must match the default guard name so shared module declarations elevate consistently.
+- The browser-side binding from `@owlmeans/client-auth` uses the same protocol references as the shared declarations.
 
 ## Related Packages
 
 - [`@owlmeans/auth`](../auth) — auth type definitions and schemas
-- [`@owlmeans/server-auth`](../server-auth) — server guard implementation
-- [`@owlmeans/client-auth`](../client-auth) — client auth service
+- [`@owlmeans/server-auth`](../server-auth) — server bindings and guard implementation
+- [`@owlmeans/client-auth`](../client-auth) — browser bindings and auth service
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -84,7 +98,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "package": "@owlmeans/auth-common",
-  "version": "0.1.18-rc.8",
-  "generatedAt": "2026-08-27T16:32:18.484Z",
+  "version": "0.1.18",
+  "generatedAt": "2026-10-28T00:31:34.721Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/auth-common/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: auth-common
-description: How to use @owlmeans/auth-common — shared authentication guard aliases (DEFAULT_GUARD, GUARD_ED25519) and middleware shared between server and client. Auto-invoked when importing guard constants or shared auth modules.
+description: How to use @owlmeans/auth-common — the auth vocabulary both sides of the wire share, covering guard aliases (DEFAULT_GUARD, GUARD_ED25519), the shared auth protocol trees, the Ed25519 signature guard, the TRUSTED-record trust() helper, and the organization-entity resolver contract (ENTITY_RESOLVER, makeEntityScope). Auto-invoked when importing guard constants, shared auth protocols, or entity-resolution helpers.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,46 +8,147 @@ user-invocable: false
 # @owlmeans/auth-common
 
 **Layer:** Core
-**Install:** `"@owlmeans/auth-common": "^0.1.18-rc.8"` in `dependencies`
+**Install:** `"@owlmeans/auth-common": "^0.1.18"` in `dependencies`
+
+Everything a server and a browser must agree on to talk authentication: aliases, the shared
+protocol declarations, the signature guard, and the contract for resolving the organization
+entity a token names.
 
 ## Key Exports
 
+### Aliases and constants
+
+| Export | Value / description |
+|--------|---------------------|
+| `DEF_AUTH_SRV` / `DEFAULT_GUARD` | `'auth'` — the canonical auth guard alias, the same string on both sides |
+| `GUARD_ED25519` | `'guard:ed25519-basic-signature'` — the Ed25519 request-signature guard |
+| `TOKEN_UPDATE` | `'auth-token-refresh'` |
+| `WEB_API` | `'web-auth-api'` — service alias of the auth manager's web API |
+| `DISPATCHER_PATH` / `SURROGATE_PATH` | `'/dispatcher'` / `'/surrogate'` — both reserved; an application must never declare its own route at either |
+| `ENTITY_RESOLVER` | `'entity-resolver'` — the organization-entity resolver's service alias |
+| `ENTITY_SLUG_PATTERN` | A lowercase DNS label. Slugs compose hostnames, cluster object names and OIDC client ids, so anything needing sanitising is rejected where it is chosen |
+| `RELY_PIN_PERFIX`, `RELY_TOKEN_PREFIX`, `RELY_CALL_TIMEOUT`, `RELY_ACTION_TIMEOUT` | Rely-handshake constants |
+| `BED255_TIME_HEADER`, `BED255_NONCE_HEADER`, `BED255_SIG_TTL`, `BED255_CASHE_RESOURCE` | Ed25519 signature-guard headers, replay window and nonce-cache alias |
+| `authApi` | Alias tree for the manager API entrypoints (`profile`, `entity`, `auth`) |
+
+### Entrypoints, guard and middleware
+
 | Export | Description |
 |--------|-------------|
-| `DEFAULT_GUARD` | Alias for the default authentication guard |
-| `GUARD_ED25519` | Alias for the Ed25519 signature guard |
-| `AUTH_API` | Alias of the auth service module group |
-| Auth modules | Shared module declarations registered in both server and client |
-| Middleware | Cross-side auth middleware helpers |
+| `authProtocols` | The shared auth protocol tree — `AUTHEN*`, `CAUTHEN*`, `DISPATCHER`, `DISPATCHER_SURROGATE`, `DISPATCHER_AUTHEN`. Server and client packages bind the entries they serve |
+| `managerProtocols` | The auth-manager web API protocol tree (profile → entity slug, auth delegation) |
+| `makeBasicEd25519Guard(resource, opts?)` | The `GUARD_ED25519` guard service: signs outgoing requests as a client, verifies time/nonce/signature as a server |
+| `authMiddleware` | Loading-stage context middleware that attaches the guard's token to every guarded backend entrypoint's `invoke`/`call` |
+| `SurrogateQuery`, `SurrogateQuerySchema` | The surrogate window's `intent` / `next` / `method` query |
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| `AuthService` | `GuardService` + `authenticate(token)`, `update(token)`, `user()`, `store<T>()` — the client-side auth manager contract |
+| `AuthorizationService` | `isAllowed(permissions, token?, thr?)`, `update(token?, thr?)` |
+| `TrustedRecord` | A `ConfigRecord` carrying a known signing identity's `name`, `credential` (public key) and optional `secret` |
+| `AuthRequest` | An `AbstractRequest` whose `query` is an `AuthToken` |
+| `AuthUIParams` | `{ type? }` — the typed login route's params |
+| `OrgEntityRef` | `{ id, slug, formerSlugs?, iamKey }` |
+| `EntityResolverService` | `resolve`, `byId`, `mintSlug`, `rename`, `mintName` — see below |
+| `ProfileToEntityIdRequest` / `ProfileToEntityIdResponse` | The manager API body/response that maps a `profileId` to an `entitySlug` |
+
+### Subpath `./utils`
+
+| Export | Description |
+|--------|-------------|
+| `trust(context, resource, userName, field = 'name')` | Load a `TrustedRecord` from a config resource and return `{ user, key }`, where `key` is a signing `KeyPairModel` when the record has a `secret` and a verify-only one otherwise |
+| `extractAuthToken(req, type?, onlyValue?)` | Pull the `authorization` header, optionally requiring an `AuthroizationType` prefix |
+| `Config`, `Context` | The minimal context shape `trust` needs |
+
+## The organization entity
 
-## Subpath Exports
+The customer organization is an **organization entity**. Two values name it and they are not
+interchangeable:
 
-- `./utils` — shared auth utility functions
+- **`entitySlug`** — renameable, human-readable, and the only organization value on the wire. It is
+  what a token, a URL, a query param and a form carry.
+- **`entityId`** — the stable record id. It never travels; it is what database rows, permission
+  grants and third-party records key on, and it is why a rename costs one write.
+
+`EntityResolverService` is the contract between the two. It is registered **only** by an
+implementation that actually stores organizations (`@owlmeans/server-auth-identity` registers one);
+a deployment backed by an external IAM registers none, and every consumer must treat an unresolved
+entity as ordinary rather than exceptional.
+
+```typescript
+import { makeEntityScope } from '@owlmeans/auth-common'
+
+const scope = makeEntityScope(request)   // once at the top of a handler, never stored
+```
+
+| Helper | What it answers |
+|--------|-----------------|
+| `scope.attachEntity(context)` | Resolve the slug on `request.auth` and set `request.entity`, canonicalizing a retired slug to the current one. Keeps an entity the guard already attached when its `slug` equals the token's exactly, and drops one that does not. Otherwise a no-op when no resolver is registered; throws `AuthenFailed('entity')` when the token names an organization that will not resolve |
+| `scope.entityKeyOf()` | The value to store and query organization-scoped records by — `req.entity?.id`, falling back to the token's slug where no resolver exists |
+| `scope.requireEntityKey()` | Same, throwing `AuthorizationError` when the request carries no organization |
+| `scope.requireEntity()` | The full `ResolvedEntity` (`id`, `slug`, `iamKey`), throwing `AuthorizationError` when nothing resolved |
+
+`scope.attachEntity(context)` must be called wherever authentication is **established** — the HTTP
+boundary, and any socket that authenticates after its connection is already open. A path that
+authenticates without it leaves `request.entity` empty and its handlers silently compare a slug
+against stored ids.
+
+A guard may attach the entity itself when its authority names the organization — the OIDC guard does
+for a session of a tenanted client (`@owlmeans/oidc`), whose relying party has no registry to
+resolve from. `scope.attachEntity` trusts that attachment only while its `slug` is the token's
+`authHelper.entitySlugOf(request.auth)`; on any mismatch it removes it and resolves as if nothing
+had been attached, so a stale or foreign entity can never reach a handler. That attached entity is
+keyed by the organization's frozen IAM key (`{ id: entityKey, slug, iamKey: entityKey }`) — the
+registry's record id never leaves the provider — so on such a relying party
+`scope.requireEntityKey()` answers the `entityKey`, which survives a rename exactly as a record id
+would.
+
+Never build a user-facing name (a hostname, a display label) from `scope.entityKeyOf()`. Those want
+the current slug, `req.entity?.slug`.
 
 ## Usage
 
-Use guard aliases when declaring modules so both client and server agree on the guard name:
+Declare an entrypoint with a guard so both sides agree on the alias, and compose authorization as a
+gate inside the same options object:
 
 ```typescript
-import { entrypoint, guard, gate } from '@owlmeans/entrypoint'
-import { route } from '@owlmeans/route'
+import { contract, protocol, typed } from '@owlmeans/entrypoint'
+import { route, backend } from '@owlmeans/route'
 import { DEFAULT_GUARD } from '@owlmeans/auth-common'
-import { OIDC_GATE } from '@owlmeans/oidc'
 
-entrypoint(
-  route(manager.back.account.base, '/account'),
-  guard(DEFAULT_GUARD, gate(OIDC_GATE, [`my-service-account-{entity}`]))
+// PRODUCT_GATE is the consuming app's own gate alias, registered as a GateService on its context.
+protocol(
+  route('api:account', '/account', backend()),
+  contract(typed<Account>()),
+  { guards: DEFAULT_GUARD, gate: { alias: PRODUCT_GATE, params: ['my-service-account-{entity}'] } },
 )
 ```
 
-## Product-Viable Usage Notes
+`{entity}` is a placeholder each **gate service** substitutes for itself — this package declares
+neither the token nor the substitution. `@owlmeans/server-iam` substitutes the resolved id
+(`server-iam` → "`{entity}` in a permission name"); `@owlmeans/server-oidc-rp`'s gate model the
+token's slug only; both write `'-'` when neither is available. Read the gate you are wiring first.
+
+## Rules
 
-- Manager API modules use `DEFAULT_GUARD` for bearer-token authentication and compose product authorization with `gate(VIABLE_AUTH_GATE, [...])` inside the same `guard(...)` options object.
-- Internal service-to-service routes still use `GUARD_ED25519`, including publisher/project command paths and auth service helper modules.
-- `DEFAULT_GUARD` is the guard alias shared across server and web; `@owlmeans/client-auth` exports the matching client alias.
-- OIDC gates are not required when OIDC is only the login/bootstrap provider. In product-viable, OIDC/Google login issues local bearer auth, and a product-specific gate checks local identity scopes.
+- `DEFAULT_GUARD` is the bearer-token guard shared by server and web; `@owlmeans/client-auth` exports
+  the matching client-side alias as `DEFAULT_ALIAS`.
+- `GUARD_ED25519` is for service-to-service calls, where the caller signs the request rather than
+  presenting a bearer token. Give it a Redis-backed nonce cache (`BED255_CASHE_RESOURCE`) in any
+  deployment that runs more than one replica, or replay protection is per-process only. The guard
+  accepts only canonical timestamps inside its symmetric 60-second window and claims the
+  credential-and-nonce pair until that timestamp's absolute expiry; a replay-store error refuses
+  authentication rather than disabling deduplication.
+- OIDC used only to sign in authorizes with a product gate, not `OIDC_GATE` (`server-oidc-rp` → Rules).
+- The trust resource (`TRUSTED`, from `@owlmeans/config`) is the system's source of truth for known
+  signing identities — the auth service, peer services, wallet providers, supervisors.
 
 ## Depends On
 
-- `@owlmeans/auth` — types and errors
-- `@owlmeans/entrypoint` — entrypoint/guard/gate helpers
+- `@owlmeans/auth` — types, errors, entrypoint aliases
+- `@owlmeans/entrypoint` — `entrypoint` / `guard` / `gate`, `GuardService`, `ResolvedEntity`
+- `@owlmeans/route` — route builders for the shared protocol trees
+- `@owlmeans/basic-keys` — key pairs behind `trust()` and the Ed25519 guard
+- `@owlmeans/basic-ids`, `@owlmeans/context`, `@owlmeans/resource`, `@owlmeans/client-entrypoint`

package/build/consts.d.ts

@@ -45,4 +45,13 @@ export declare const authApi: {
         delegate: string;
     };
 };
+/**
+ * The request header an authenticated call carries, re-exported for the packages that only depend
+ * on this half of the vocabulary.
+ *
+ * One spelling, one home: it is declared by `@owlmeans/auth` and named here so a client-side
+ * package does not have to take a dependency on the whole auth package to recognise its own
+ * bearer on a request it is about to send.
+ */
+export { AUTH_HEADER } from '@owlmeans/auth';
 //# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe,cAAc,CAAA;AAE1C,eAAO,MAAM,iBAAiB,gBAAgB,CAAA;AAE9C,eAAO,MAAM,iBAAiB,MAAM,CAAA;AAEpC,eAAO,MAAM,mBAAmB,MAAM,CAAA;AAEtC,eAAO,MAAM,eAAe,gBAAgB,CAAA;AAE5C;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,eAAe,CAAA;AAE1C,eAAO,MAAM,YAAY,SAAS,CAAA;AAElC,eAAO,MAAM,aAAa,SAAe,CAAA;AAEzC,eAAO,MAAM,YAAY,uBAAuB,CAAA;AAEhD,eAAO,MAAM,OAAO,iBAAiB,CAAA;AAErC,+FAA+F;AAC/F,eAAO,MAAM,eAAe,oBAAoB,CAAA;AAEhD;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,QAA2C,CAAA;AAE3E,eAAO,MAAM,OAAO;IAClB,OAAO;QACL,IAAI;QACJ,UAAU;;IAEZ,MAAM;QACJ,IAAI;QACJ,GAAG;QACH,OAAO;YACL,IAAI;YACJ,IAAI;YACJ,IAAI;;;IAGR,IAAI;QACF,IAAI;QACJ,QAAQ;;CAEX,CAAA"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe,cAAc,CAAA;AAE1C,eAAO,MAAM,iBAAiB,gBAAgB,CAAA;AAE9C,eAAO,MAAM,iBAAiB,MAAM,CAAA;AAEpC,eAAO,MAAM,mBAAmB,MAAM,CAAA;AAEtC,eAAO,MAAM,eAAe,gBAAgB,CAAA;AAE5C;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,eAAe,CAAA;AAE1C,eAAO,MAAM,YAAY,SAAS,CAAA;AAElC,eAAO,MAAM,aAAa,SAAe,CAAA;AAEzC,eAAO,MAAM,YAAY,uBAAuB,CAAA;AAEhD,eAAO,MAAM,OAAO,iBAAiB,CAAA;AAErC,+FAA+F;AAC/F,eAAO,MAAM,eAAe,oBAAoB,CAAA;AAEhD;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,QAA2C,CAAA;AAE3E,eAAO,MAAM,OAAO;IAClB,OAAO;QACL,IAAI;QACJ,UAAU;;IAEZ,MAAM;QACJ,IAAI;QACJ,GAAG;QACH,OAAO;YACL,IAAI;YACJ,IAAI;YACJ,IAAI;;;IAGR,IAAI;QACF,IAAI;QACJ,QAAQ;;CAEX,CAAA;AAGD;;;;;;;GAOG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA"}

package/build/consts.js

@@ -45,4 +45,13 @@ export const authApi = {
         delegate: 'api:auth:delegate',
     },
 };
+/**
+ * The request header an authenticated call carries, re-exported for the packages that only depend
+ * on this half of the vocabulary.
+ *
+ * One spelling, one home: it is declared by `@owlmeans/auth` and named here so a client-side
+ * package does not have to take a dependency on the whole auth package to recognise its own
+ * bearer on a request it is about to send.
+ */
+export { AUTH_HEADER } from '@owlmeans/auth';
 //# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -1 +1 @@
-{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAA;AAE1C,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAA;AAE9C,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAA;AAEpC,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAA;AAEtC,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAAA;AAE5C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,YAAY,CAAA;AAE1C,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAA;AAElC,MAAM,CAAC,MAAM,aAAa,GAAG,YAAY,CAAA;AAEzC,MAAM,CAAC,MAAM,YAAY,GAAG,oBAAoB,CAAA;AAEhD,MAAM,CAAC,MAAM,OAAO,GAAG,cAAc,CAAA;AAErC,+FAA+F;AAC/F,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAA;AAEhD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,wCAAwC,CAAA;AAE3E,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,OAAO,EAAE;QACP,IAAI,EAAE,aAAa;QACnB,UAAU,EAAE,0BAA0B;KACvC;IACD,MAAM,EAAE;QACN,IAAI,EAAE,YAAY;QAClB,GAAG,EAAE,gBAAgB;QACrB,OAAO,EAAE;YACP,IAAI,EAAE,oBAAoB;YAC1B,IAAI,EAAE,yBAAyB;YAC/B,IAAI,EAAE,yBAAyB;SAChC;KACF;IACD,IAAI,EAAE;QACJ,IAAI,EAAE,UAAU;QAChB,QAAQ,EAAE,mBAAmB;KAC9B;CACF,CAAA"}
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAA;AAE1C,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAA;AAE9C,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAA;AAEpC,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAA;AAEtC,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAAA;AAE5C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,YAAY,CAAA;AAE1C,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAA;AAElC,MAAM,CAAC,MAAM,aAAa,GAAG,YAAY,CAAA;AAEzC,MAAM,CAAC,MAAM,YAAY,GAAG,oBAAoB,CAAA;AAEhD,MAAM,CAAC,MAAM,OAAO,GAAG,cAAc,CAAA;AAErC,+FAA+F;AAC/F,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAA;AAEhD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,wCAAwC,CAAA;AAE3E,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,OAAO,EAAE;QACP,IAAI,EAAE,aAAa;QACnB,UAAU,EAAE,0BAA0B;KACvC;IACD,MAAM,EAAE;QACN,IAAI,EAAE,YAAY;QAClB,GAAG,EAAE,gBAAgB;QACrB,OAAO,EAAE;YACP,IAAI,EAAE,oBAAoB;YAC1B,IAAI,EAAE,yBAAyB;YAC/B,IAAI,EAAE,yBAAyB;SAChC;KACF;IACD,IAAI,EAAE;QACJ,IAAI,EAAE,UAAU;QAChB,QAAQ,EAAE,mBAAmB;KAC9B;CACF,CAAA;AAGD;;;;;;;GAOG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA"}

package/build/entity/types.d.ts

@@ -0,0 +1,52 @@
+import type { BasicContext } from '@owlmeans/context';
+import type { ResolvedEntity } from '@owlmeans/entrypoint';
+/** The organization entity one request acts for — built once at the top of a handler, never stored. */
+export interface EntityScope {
+    /**
+     * The value a handler should store and query organization-scoped records by.
+     *
+     * Prefers the entity's stable id, which is the whole point of resolving one: records keyed by it
+     * survive a rename untouched. Falls back to the slug on the token for deployments that register no
+     * resolver — there the slug IS the only identifier the system has, and refusing to serve them
+     * would break every installation backed by an external IAM.
+     *
+     * Never use this to compose a user-facing name (a hostname, a display label). Those want the
+     * current slug, `req.entity?.slug`, precisely because it can change.
+     */
+    entityKeyOf: () => string | undefined;
+    /**
+     * `entityKeyOf` for handlers that cannot proceed without an organization.
+     *
+     * @throws {AuthorizationError} when the request carries no organization at all.
+     */
+    requireEntityKey: () => string;
+    /**
+     * The full resolved entity, for handlers that need the slug or the frozen key as well as the id.
+     *
+     * @throws {AuthorizationError} when no resolver is registered or the entity did not resolve.
+     */
+    requireEntity: () => ResolvedEntity;
+    /**
+     * Resolve the organization a just-authenticated request acts for, and attach it.
+     *
+     * Called wherever authentication is ESTABLISHED — the HTTP boundary, and any socket that
+     * authenticates on its own once the connection is already open. Both need it for the same reason:
+     * the token names the organization by a slug that can move, while everything downstream keys on
+     * the record. A path that authenticates without calling this leaves `request.entity` empty, and
+     * its handlers quietly fall back to comparing a slug against stored ids — which surfaces as "this
+     * project does not exist" rather than as a missing resolution, and costs an afternoon to find.
+     *
+     * An entity the guard already attached is kept while its slug is exactly the token's: a guard
+     * whose authority names the organization itself (an OIDC session of a tenanted client) is the only
+     * source such a deployment has, because the registry that owns the organization is not its own.
+     * One whose slug differs is never trusted — it is dropped, and resolution proceeds as if it had
+     * not been there.
+     *
+     * Otherwise a no-op when no resolver is registered: such a deployment has no organization store,
+     * and the slug is the only identifier it has.
+     *
+     * @throws {AuthenFailed} when the token names an organization that cannot be resolved.
+     */
+    attachEntity: (context: BasicContext<any>) => Promise<ResolvedEntity | undefined>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/entity/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/entity/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE1D,uGAAuG;AACvG,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;OAUG;IACH,WAAW,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IACrC;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,MAAM,CAAA;IAC9B;;;;OAIG;IACH,aAAa,EAAE,MAAM,cAAc,CAAA;IACnC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,EAAE,CAAC,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAA;CAClF"}

package/build/entity/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/entity/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/entity/types.ts"],"names":[],"mappings":""}

package/build/entity.d.ts

@@ -1,43 +1,11 @@
 import type { AbstractRequest, ResolvedEntity } from '@owlmeans/entrypoint';
 import type { BasicContext } from '@owlmeans/context';
-/**
- * The value a handler should store and query organization-scoped records by.
- *
- * Prefers the entity's stable id, which is the whole point of resolving one: records keyed by it
- * survive a rename untouched. Falls back to the slug on the token for deployments that register no
- * resolver — there the slug IS the only identifier the system has, and refusing to serve them
- * would break every installation backed by an external IAM.
- *
- * Never use this to compose a user-facing name (a hostname, a display label). Those want the
- * current slug, `req.entity?.slug`, precisely because it can change.
- */
+import type { EntityScope } from './entity/types.js';
+export declare const makeEntityScope: (req: AbstractRequest) => EntityScope;
+/** @deprecated compat:factory-refactor — use `makeEntityScope(req).entityKeyOf()` */
 export declare const entityKeyOf: (req: AbstractRequest) => string | undefined;
-/**
- * `entityKeyOf` for handlers that cannot proceed without an organization.
- *
- * @throws {AuthorizationError} when the request carries no organization at all.
- */
+/** @deprecated compat:factory-refactor — use `makeEntityScope(req).requireEntityKey()` */
 export declare const requireEntityKey: (req: AbstractRequest) => string;
-/**
- * The full resolved entity, for handlers that need the slug or the frozen key as well as the id.
- *
- * @throws {AuthorizationError} when no resolver is registered or the entity did not resolve.
- */
-export declare const requireEntity: (req: AbstractRequest) => ResolvedEntity;
-/**
- * Resolve the organization a just-authenticated request acts for, and attach it.
- *
- * Called wherever authentication is ESTABLISHED — the HTTP boundary, and any socket that
- * authenticates on its own once the connection is already open. Both need it for the same reason:
- * the token names the organization by a slug that can move, while everything downstream keys on
- * the record. A path that authenticates without calling this leaves `request.entity` empty, and
- * its handlers quietly fall back to comparing a slug against stored ids — which surfaces as "this
- * project does not exist" rather than as a missing resolution, and costs an afternoon to find.
- *
- * A no-op when no resolver is registered: such a deployment has no organization store, and the
- * slug is the only identifier it has.
- *
- * @throws {AuthenFailed} when the token names an organization that cannot be resolved.
- */
+/** @deprecated compat:factory-refactor — use `makeEntityScope(request).attachEntity(context)` */
 export declare const attachEntity: (context: BasicContext<any>, request: AbstractRequest) => Promise<ResolvedEntity | undefined>;
 //# sourceMappingURL=entity.d.ts.map

package/build/entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAKrD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,QAAS,eAAe,KAAG,MAAM,GAAG,SAClB,CAAA;AAE1C;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,QAAS,eAAe,KAAG,MAOvD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,QAAS,eAAe,KAAG,cAMpD,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,YACd,YAAY,CAAC,GAAG,CAAC,WAAW,eAAe,KACnD,OAAO,CAAC,cAAc,GAAG,SAAS,CAiBpC,CAAA"}
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD,eAAO,MAAM,eAAe,QAAS,eAAe,KAAG,WAgDtD,CAAA;AAED,qFAAqF;AACrF,eAAO,MAAM,WAAW,QAAS,eAAe,KAAG,MAAM,GAAG,SAA+C,CAAA;AAE3G,0FAA0F;AAC1F,eAAO,MAAM,gBAAgB,QAAS,eAAe,KAAG,MAAiD,CAAA;AAEzG,iGAAiG;AACjG,eAAO,MAAM,YAAY,YACd,YAAY,CAAC,GAAG,CAAC,WAAW,eAAe,KACnD,OAAO,CAAC,cAAc,GAAG,SAAS,CAAyD,CAAA"}

package/build/entity.js

@@ -1,68 +1,47 @@
-import { AuthenFailed, AuthorizationError, entitySlugOf } from '@owlmeans/auth';
+import { AuthenFailed, AuthorizationError, authHelper } from '@owlmeans/auth';
 import { ENTITY_RESOLVER } from './consts.js';
-/**
- * The value a handler should store and query organization-scoped records by.
- *
- * Prefers the entity's stable id, which is the whole point of resolving one: records keyed by it
- * survive a rename untouched. Falls back to the slug on the token for deployments that register no
- * resolver — there the slug IS the only identifier the system has, and refusing to serve them
- * would break every installation backed by an external IAM.
- *
- * Never use this to compose a user-facing name (a hostname, a display label). Those want the
- * current slug, `req.entity?.slug`, precisely because it can change.
- */
-export const entityKeyOf = (req) => req.entity?.id ?? entitySlugOf(req.auth);
-/**
- * `entityKeyOf` for handlers that cannot proceed without an organization.
- *
- * @throws {AuthorizationError} when the request carries no organization at all.
- */
-export const requireEntityKey = (req) => {
-    const key = entityKeyOf(req);
-    if (key == null || key === '') {
-        throw new AuthorizationError();
-    }
-    return key;
-};
-/**
- * The full resolved entity, for handlers that need the slug or the frozen key as well as the id.
- *
- * @throws {AuthorizationError} when no resolver is registered or the entity did not resolve.
- */
-export const requireEntity = (req) => {
-    if (req.entity == null) {
-        throw new AuthorizationError();
-    }
-    return req.entity;
-};
-/**
- * Resolve the organization a just-authenticated request acts for, and attach it.
- *
- * Called wherever authentication is ESTABLISHED — the HTTP boundary, and any socket that
- * authenticates on its own once the connection is already open. Both need it for the same reason:
- * the token names the organization by a slug that can move, while everything downstream keys on
- * the record. A path that authenticates without calling this leaves `request.entity` empty, and
- * its handlers quietly fall back to comparing a slug against stored ids — which surfaces as "this
- * project does not exist" rather than as a missing resolution, and costs an afternoon to find.
- *
- * A no-op when no resolver is registered: such a deployment has no organization store, and the
- * slug is the only identifier it has.
- *
- * @throws {AuthenFailed} when the token names an organization that cannot be resolved.
- */
-export const attachEntity = async (context, request) => {
-    const slug = entitySlugOf(request.auth);
-    if (slug == null || !context.hasService(ENTITY_RESOLVER)) {
-        return undefined;
-    }
-    const entity = await context.service(ENTITY_RESOLVER).resolve(slug);
-    if (entity == null) {
-        throw new AuthenFailed('entity');
-    }
-    // Canonicalize: a request that arrived under a retired slug continues under the current one, so
-    // nothing echoing the value back can re-publish a name the organization has dropped.
-    request.auth.entitySlug = entity.slug;
-    request.entity = entity;
-    return entity;
+export const makeEntityScope = (req) => {
+    const entityKeyOf = () => req.entity?.id ?? authHelper.entitySlugOf(req.auth);
+    const requireEntityKey = () => {
+        const key = entityKeyOf();
+        if (key == null || key === '') {
+            throw new AuthorizationError();
+        }
+        return key;
+    };
+    const requireEntity = () => {
+        if (req.entity == null) {
+            throw new AuthorizationError();
+        }
+        return req.entity;
+    };
+    const attachEntity = async (context) => {
+        const slug = authHelper.entitySlugOf(req.auth);
+        if (req.entity != null) {
+            if (slug != null && req.entity.slug === slug) {
+                return req.entity;
+            }
+            req.entity = undefined;
+        }
+        if (slug == null || !context.hasService(ENTITY_RESOLVER)) {
+            return undefined;
+        }
+        const entity = await context.service(ENTITY_RESOLVER).resolve(slug);
+        if (entity == null) {
+            throw new AuthenFailed('entity');
+        }
+        // Canonicalize: a request that arrived under a retired slug continues under the current one, so
+        // nothing echoing the value back can re-publish a name the organization has dropped.
+        req.auth.entitySlug = entity.slug;
+        req.entity = entity;
+        return entity;
+    };
+    return { entityKeyOf, requireEntityKey, requireEntity, attachEntity };
 };
+/** @deprecated compat:factory-refactor — use `makeEntityScope(req).entityKeyOf()` */
+export const entityKeyOf = (req) => makeEntityScope(req).entityKeyOf();
+/** @deprecated compat:factory-refactor — use `makeEntityScope(req).requireEntityKey()` */
+export const requireEntityKey = (req) => makeEntityScope(req).requireEntityKey();
+/** @deprecated compat:factory-refactor — use `makeEntityScope(request).attachEntity(context)` */
+export const attachEntity = async (context, request) => await makeEntityScope(request).attachEntity(context);
 //# sourceMappingURL=entity.js.map

package/build/entity.js.map

@@ -1 +1 @@
-{"version":3,"file":"entity.js","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAE/E,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,GAAoB,EAAsB,EAAE,CACtE,GAAG,CAAC,MAAM,EAAE,EAAE,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAE1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,GAAoB,EAAU,EAAE;IAC/D,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC,CAAA;IAC5B,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QAC9B,MAAM,IAAI,kBAAkB,EAAE,CAAA;IAChC,CAAC;IAED,OAAO,GAAG,CAAA;AACZ,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,GAAoB,EAAkB,EAAE;IACpE,IAAI,GAAG,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,kBAAkB,EAAE,CAAA;IAChC,CAAC;IAED,OAAO,GAAG,CAAC,MAAM,CAAA;AACnB,CAAC,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAC/B,OAA0B,EAAE,OAAwB,EACf,EAAE;IACvC,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IACvC,IAAI,IAAI,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QACzD,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAwB,eAAe,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1F,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;QACnB,MAAM,IAAI,YAAY,CAAC,QAAQ,CAAC,CAAA;IAClC,CAAC;IAED,gGAAgG;IAChG,qFAAqF;IACrF,OAAO,CAAC,IAAK,CAAC,UAAU,GAAG,MAAM,CAAC,IAAI,CAAA;IACtC,OAAO,CAAC,MAAM,GAAG,MAAM,CAAA;IAEvB,OAAO,MAAM,CAAA;AACf,CAAC,CAAA"}
+{"version":3,"file":"entity.js","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAE7E,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAG7C,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,GAAoB,EAAe,EAAE;IACnE,MAAM,WAAW,GAAG,GAAuB,EAAE,CAC3C,GAAG,CAAC,MAAM,EAAE,EAAE,IAAI,UAAU,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAErD,MAAM,gBAAgB,GAAG,GAAW,EAAE;QACpC,MAAM,GAAG,GAAG,WAAW,EAAE,CAAA;QACzB,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;YAC9B,MAAM,IAAI,kBAAkB,EAAE,CAAA;QAChC,CAAC;QAED,OAAO,GAAG,CAAA;IACZ,CAAC,CAAA;IAED,MAAM,aAAa,GAAG,GAAmB,EAAE;QACzC,IAAI,GAAG,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,IAAI,kBAAkB,EAAE,CAAA;QAChC,CAAC;QAED,OAAO,GAAG,CAAC,MAAM,CAAA;IACnB,CAAC,CAAA;IAED,MAAM,YAAY,GAAG,KAAK,EAAE,OAA0B,EAAuC,EAAE;QAC7F,MAAM,IAAI,GAAG,UAAU,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAC9C,IAAI,GAAG,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;YACvB,IAAI,IAAI,IAAI,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;gBAC7C,OAAO,GAAG,CAAC,MAAM,CAAA;YACnB,CAAC;YACD,GAAG,CAAC,MAAM,GAAG,SAAS,CAAA;QACxB,CAAC;QAED,IAAI,IAAI,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;YACzD,OAAO,SAAS,CAAA;QAClB,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAwB,eAAe,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;QAC1F,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;YACnB,MAAM,IAAI,YAAY,CAAC,QAAQ,CAAC,CAAA;QAClC,CAAC;QAED,gGAAgG;QAChG,qFAAqF;QACrF,GAAG,CAAC,IAAK,CAAC,UAAU,GAAG,MAAM,CAAC,IAAI,CAAA;QAClC,GAAG,CAAC,MAAM,GAAG,MAAM,CAAA;QAEnB,OAAO,MAAM,CAAA;IACf,CAAC,CAAA;IAED,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,CAAA;AACvE,CAAC,CAAA;AAED,qFAAqF;AACrF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,GAAoB,EAAsB,EAAE,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAA;AAE3G,0FAA0F;AAC1F,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,GAAoB,EAAU,EAAE,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,gBAAgB,EAAE,CAAA;AAEzG,iGAAiG;AACjG,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAC/B,OAA0B,EAAE,OAAwB,EACf,EAAE,CAAC,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,CAAA"}