@owlmeans/server-auth-identity 0.1.18-rc.2 → 0.1.18-rc.21

package/README.md

@@ -7,12 +7,12 @@ Mongo-backed local identity resources and provider account linking for OwlMeans
 - Registers three Mongo resources: local accounts, local profiles, and provider credentials.
 - Provides `IdentityLinkingService` to map external provider profile details into an OwlMeans `AuthPayload`.
 - Keeps external provider identity separate from local product identity and authorization scopes.
-- Designed to work with `@owlmeans/server-auth`, `@owlmeans/server-oidc-rp`, and product-specific module gates.
+- Designed to work with `@owlmeans/server-auth`, `@owlmeans/server-oidc-rp`, and product-specific entrypoint gates.
 
 ## Installation
 
 ```bash
-bun add @owlmeans/server-auth-identity
+bun add @owlmeans/server-auth-identity@^0.1.18-rc.12
 ```
 
 ## Usage
@@ -43,9 +43,10 @@ import { AUTH_IDENTITY_PROFILE } from '@owlmeans/server-auth-identity'
 import type { IdentityProfileResource } from '@owlmeans/server-auth-identity'
 
 const profiles = context.resource<IdentityProfileResource>(AUTH_IDENTITY_PROFILE)
-const profile = await profiles.load(profileId, 'profileId')
+const profile = await profiles.load({ profileId })
+const scoped = await profiles.load({ entityId, profileId })
 
-const { items } = await profiles.list({ entityId, profileId } as any)
+const { items, total } = await profiles.list({ entityId })
 ```
 
 ## API
@@ -83,7 +84,7 @@ const { items } = await profiles.list({ entityId, profileId } as any)
 - Google/OIDC login is only the provider bootstrap path; durable authorization data lives in `IdentityProfile`.
 - Backend contexts should register `appendAuthService(context)`, then `appendAuthIdentityResources(context)`, then product gate services.
 - Product gates should read `AUTH_IDENTITY_PROFILE`, verify `entityId`, reject expired or blocked profiles, and compare gate params against profile scopes.
-- `Resource.pick()` is destructive and deletes the matching record. Never use `pick()` for gate or handler reads; use `load()` or `list()`.
+- `Resource.take()` is destructive and deletes the record it returns. Never use `take()` for gate or handler reads; use `load(where)` or `list(where)`.
 
 ## Related Packages
 
@@ -101,7 +102,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-rc.20
 ```
 
 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,
   "package": "@owlmeans/server-auth-identity",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.498Z",
+  "version": "0.1.18-rc.21",
+  "generatedAt": "2026-09-12T14:18:54.780Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/server-auth-identity/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: server-auth-identity
-description: How to use @owlmeans/server-auth-identity — Mongo-backed local identity resources (account, profile, credentials) and IdentityLinkingService for provider account linking. Auto-invoked when importing appendAuthIdentityResources, identity resource aliases, or IdentityLinkingService.
+description: How to use @owlmeans/server-auth-identity — the Mongo-backed local identity store behind provider logins. Registers the organization-entity registry plus account, profile and credentials resources, the IdentityLinkingService that maps an external provider account onto one local identity, and the EntityResolverService that turns the slug on a token into a stable entity id. Auto-invoked when importing appendAuthIdentityResources, an identity resource alias, IdentityLinkingService or the entity resolver.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,61 +8,108 @@ user-invocable: false
 # @owlmeans/server-auth-identity
 
 **Layer:** Server
-**Install:** `"@owlmeans/server-auth-identity": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/server-auth-identity": "^0.1.18-rc.21"` in `dependencies`
+
+The local identity store a deployment owns when it does not delegate identity to an external IAM.
+It answers two questions: *who is this person here* (account / profile / credentials) and *which
+organization entity is this* (the org-entity registry and its resolver).
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `appendAuthIdentityResources(context, dbAlias?)` | Register all three identity resources + linking service on a context |
-| `makeIdentityAccountResource(dbAlias?)` | Mongo resource for `IdentityAccount` (one per user) |
-| `makeIdentityProfileResource(dbAlias?)` | Mongo resource for `IdentityProfile` (ties user to entity + role) |
-| `makeIdentityCredentialsResource(dbAlias?)` | Mongo resource for `IdentityCredentials` (provider link per profile) |
-| `makeIdentityLinkingService()` | Service implementing `IdentityLinkingService` — links external providers to local profiles |
+| `appendAuthIdentityResources(context, dbAlias?)` | Register the four resources, the linking service and the entity resolver in one call |
+| `makeOrgEntityResource(dbAlias?)` | Mongo resource for `OrgEntity` — the organization-entity registry |
+| `makeIdentityAccountResource(dbAlias?)` | Mongo resource for `IdentityAccount` (one per person) |
+| `makeIdentityProfileResource(dbAlias?)` | Mongo resource for `IdentityProfile` (one person inside one organization entity, with a role) |
+| `makeIdentityCredentialsResource(dbAlias?)` | Mongo resource for `IdentityCredentials` (one provider link per profile) |
+| `makeIdentityLinkingService()` | The `IdentityLinkingService` implementation |
+| `makeEntityResolverService(alias?)` | The `EntityResolverService` implementation, cached for 30 s per resolved value |
+| `AUTH_IDENTITY_ORG_ENTITY` | Resource alias `'auth-identity:org-entity'` |
 | `AUTH_IDENTITY_ACCOUNT` | Resource alias `'auth-identity:account'` |
 | `AUTH_IDENTITY_PROFILE` | Resource alias `'auth-identity:profile'` |
 | `AUTH_IDENTITY_CREDENTIALS` | Resource alias `'auth-identity:credentials'` |
 | `AUTH_IDENTITY_LINKING` | Service alias `'auth-identity:linking'` |
+| `AUTH_IDENTITY_DB_ALIAS` | `'auth-identity'` — the suggested db-config alias whose `resourcePrefix` scopes the prefix to identity collections only |
+| `AUTH_IDENTITY_ORG_ENTITY_COLLECTION`, `AUTH_IDENTITY_ACCOUNT_COLLECTION`, `AUTH_IDENTITY_PROFILE_COLLECTION`, `AUTH_IDENTITY_CREDENTIALS_COLLECTION` | Colon-free Mongo collection base names (`org-entity`, `account`, `profile`, `credentials`) |
+| `MAX_ENTITY_SLUG_ATTEMPTS` | How many word slugs to try before giving up minting a free one |
+| `LOGIN_SERVICE_PREFIX`, `EXTERNAL_KEY_DELIMITER` | `'service'` and `':'` — the grammar of every derived key below |
+
+The resource **aliases** keep their colon-delimited form and are lookup keys only; the Mongo
+collection names are the colon-free `*_COLLECTION` values, optionally prefixed by the db config's
+`resourcePrefix`.
 
 ## Types
 
 | Type | Description |
 |------|-------------|
-| `IdentityAccount` | `Profile & ResourceRecord` — `id`, `credential` (unique entity slug) |
-| `IdentityProfile` | `Profile & ResourceRecord` — `id`, `profileId`, `userId?`, `role`, `entityId`, `scopes`, `expiresAt?` |
-| `IdentityCredentials` | `AuthCredentials & ResourceRecord` — `profileId`, `type`, `userId` (external key), `credential` (login-service key) |
+| `OrgEntity` | `id`, `slug`, `formerSlugs?`, `iamKey`, `names?`, `createdAt`, `updatedAt?` |
+| `IdentityAccount` | `Profile` without `entitySlug`, plus `id`, `credential`, `entityId?` |
+| `IdentityProfile` | `Profile` without `entitySlug`, plus `id`, `profileId`, `userId?`, `role`, `entityId?`, `expiresAt?` |
+| `IdentityCredentials` | `AuthCredentials` + `profileId` |
 | `IdentityLinkingService` | `getLinkedProfile`, `linkProfile`, `linkCredentials`, `getOwnerProfiles`, `getOwnerCredentials` |
+| `AccountMeta` | `{ username, force? }` — the second argument to `linkProfile` |
+| `OrgEntityResource`, `IdentityAccountResource`, `IdentityProfileResource`, `IdentityCredentialsResource` | Typed `MongoResource` aliases |
+| `IdentityConfig`, `IdentityContext` | Server config/context shapes |
+| `GoogleUserInfo` | The Google userinfo claim set |
+| `EmailIdentityArgs`, `EmailIdentityPayload`, `IdentityIamExtension` | Declaration-only seam for an IAM-backed email find-or-create |
+
+The three `*Identity*` seam types are declarations and nothing more: no function in this
+package accepts or returns them, and no consumer imports them. An email login is wired through
+`IdentityLinkingService.getLinkedProfile` / `linkProfile`, which is what the OTP plugin does.
+
+## The organization entity
+
+The customer organization is an **organization entity**, and this package is the registry that owns
+it. Two values name one organization and they never substitute for each other:
+
+- **`entityId`** — `OrgEntity.id`. Stable, never on the wire. Every account, profile and
+  organization-scoped record keys on it.
+- **`entitySlug`** — `OrgEntity.slug`. Renameable, human-readable, and the only organization value
+  an auth payload carries. Every `AuthPayload` this service returns carries `entitySlug`, resolved
+  from the stored `entityId`; an id that no longer resolves yields `undefined` rather than leaking a
+  raw id where a consumer would read it as a slug.
+
+A rename is one write to `OrgEntity`, because nothing else stores the slug. The retired name moves
+into `formerSlugs` and keeps resolving, so tokens minted before the rename and third-party records
+still quoting the old value keep working.
+
+`iamKey` is frozen at creation and never recomputed. It is what systems that cannot be renamed —
+an IAM realm, a namespace, a storage prefix — are told once; `mintName(id, key, mint)` is the
+read-before-mint that freezes such a derived name into `OrgEntity.names`.
+
+Registering the resolver is also the signal that this deployment **has** organizations: without it
+`request.entity` stays undefined and every consumer falls back to treating the token's slug as the
+only entity value there is.
 
 ## Usage
 
-### Register in context
+### Register in a context
 
 ```typescript
 import { appendAuthIdentityResources } from '@owlmeans/server-auth-identity'
 
-// In your makeContext factory, after appendMongo/appendRedis/appendAuthService:
+// in makeContext, after the Mongo/Redis services and appendAuthService:
 appendAuthIdentityResources(context)
 ```
 
-This registers three Mongo resources and the linking service in one call.
-
-### Read a profile (gate / handler)
+### Read a profile (gate or handler)
 
 ```typescript
 import { AUTH_IDENTITY_PROFILE } from '@owlmeans/server-auth-identity'
 import type { IdentityProfileResource } from '@owlmeans/server-auth-identity'
+import { requireEntityKey } from '@owlmeans/auth-common'
 
-const profileRes = ctx.resource<IdentityProfileResource>(AUTH_IDENTITY_PROFILE)
-
-// Single-field indexed lookup (read-only):
-const profile = await profileRes.load(profileId, 'profileId')
+const profiles = ctx.resource<IdentityProfileResource>(AUTH_IDENTITY_PROFILE)
+const entityId = requireEntityKey(req)
 
-// Multi-field criteria lookup (read-only):
-const { items } = await profileRes.list({ entityId, profileId } as any)
-const profile = items[0] ?? null
+const profile = await profiles.load({ entityId, profileId })
+const { items } = await profiles.list({ entityId }, { sort: [{ field: 'createdAt', order: 'desc' }] })
 ```
 
-### Link an external provider to a local profile
+Query profiles by `entityId`, never by the slug — `requireEntityKey` hands you the resolved id.
+
+### Link a provider account to a local identity
 
 ```typescript
 import { AUTH_IDENTITY_LINKING } from '@owlmeans/server-auth-identity'
@@ -70,47 +117,75 @@ import type { IdentityLinkingService } from '@owlmeans/server-auth-identity'
 
 const linking = ctx.service<IdentityLinkingService>(AUTH_IDENTITY_LINKING)
 
-// First login — creates account + profile + credentials:
-const payload = await linking.linkProfile(providerDetails, { username: 'display name' })
-
-// Subsequent logins — finds existing profile by external key:
-const payload = await linking.getLinkedProfile(providerDetails)
-```
-
-Both return `AuthPayload` with `{ type, role, userId, profileId, entityId, scopes }`.
-
-### ProviderProfileDetails shape (input)
-
-```typescript
-interface ProviderProfileDetails {
-  type: string       // e.g. 'google'
-  service: string    // e.g. 'google' (provider service alias)
-  userId: string     // provider subject (sub claim)
-  profileId?: string // optional existing profile to link to
+const details = {
+  type: 'google-oauth',   // the AuthenticationType
+  service: 'google',      // the provider service alias
+  clientId: 'google',     // the provider client this login came through
+  userId: providerSub,    // the provider's subject claim
 }
-```
-
-## Key Derivation Conventions
-
-- **Profile userId**: the account's mongo id — a **declared ObjectId reference**
-  (`resource.reference('userId', AUTH_IDENTITY_ACCOUNT)`): stored as `ObjectId`, exchanged
-  as a string, auto-indexed and auto-migrated at boot. The only reference in the trio.
-- **Account credential**: unique Base58 slug (16 chars) — serves as the local `entityId`
-- **Profile profileId**: `"{type}:{accountId}"` — stable across provider re-links; a composite key, NOT a reference
-- **Credentials userId** (external key): `"{type}:{service}:{providerSub}"` — uniquely identifies the external account. Same name as `profile.userId`, entirely different meaning — never convert or compare across the two
-- **Credentials credential** (login-service key): `"service:{type}:{service}"` — groups credentials by provider
 
-`AuthPayload.userId` is emitted as `profile.userId ?? profile.profileId`, so a value flowing
-back into a `userId` query may be a composite key — criteria tolerate it (matches nothing)
-by the reference conversion's design.
+// Returning login: find the credential, then its profile.
+let payload = await linking.getLinkedProfile(details)
+// First login by this method: link it to the person's identity, registering one if new.
+payload ??= await linking.linkProfile(details, { username: 'person@example.org' })
+```
 
-## Resource Indexes
+Both return an `AuthPayload` — `{ type, role, userId, profileId, entitySlug, scopes }`.
+
+`linkCredentials(details)` adds a credential row to an already-linked profile named by
+`details.profileId`. `getOwnerProfiles(entityId)` lists an organization's profiles;
+`getOwnerCredentials(userId, entityId?, type?)` returns one profile's credential as an
+`AuthCredentials`.
+
+## One person, one platform identity
+
+`linkProfile` **links** a person the platform already knows and registers only a genuinely new one.
+It matches on the account's `name`, which every shipped provider establishes as a verified email
+before it gets here (Google asserts the address, OTP proves possession of it, the supervisor key is
+a full-trust developer credential). A second sign-in method therefore adds a second **credential**
+to one profile — never a second account, profile or organization entity.
+
+Two rows can legitimately carry one address, and only one of them is a platform login: an
+organization's invited **end user** is a person-shaped row for the generated application to
+authenticate, deliberately separate from the platform credential. They are told apart by the
+profile's `credential`: this service is the only writer of `"service:{type}:{service}"`, so a
+profile carrying one is a platform login and a profile carrying none is somebody's end user.
+
+`linkProfile(details, { username, force: true })` skips the lookup and registers a fresh identity
+regardless. Use it only where a genuinely separate identity is intended.
+
+## Key derivation conventions
+
+- **Account `credential`** — a unique 16-character Base58 slug, the account's own stable key.
+  Generation retries up to five times on a duplicate-key collision; that is the designed behaviour
+  for the slug space, not an error path.
+- **Account / profile `entityId`** — the `OrgEntity` record id. Every first registration creates the
+  entity record **first**, because it owns the id everything else is keyed by and the frozen
+  `iamKey`.
+- **Profile `userId`** — the account's Mongo id, and a **declared ObjectId reference**
+  (`resource.reference('userId', AUTH_IDENTITY_ACCOUNT)`): stored as `ObjectId`, exchanged as a
+  string, auto-indexed and auto-migrated at boot. The only reference in the set.
+- **Profile `profileId`** — `"{type}:{accountId}"`. A composite key, stable across provider
+  re-links, and NOT a reference.
+- **Credentials `userId`** (external key) — `"{type}:{service}:{providerSub}"`. Same field name as
+  `profile.userId`, entirely different meaning; never compare or convert across the two.
+- **Credentials / profile `credential`** (login-service key) — `"service:{type}:{service}"`.
+
+`AuthPayload.userId` is emitted as `profile.userId ?? profile.profileId`, so a value coming back
+into a `userId` query may be a composite key. The reference conversion tolerates it by matching
+nothing.
+
+## Resource indexes
 
 | Resource | Index | Fields | Notes |
 |----------|-------|--------|-------|
+| OrgEntity | `slug` | `{ slug: 1 }` | unique — the only thing between two organizations and one public name |
+| OrgEntity | `iamKey` | `{ iamKey: 1 }` | unique — a duplicate would hand one organization another's realm |
+| OrgEntity | `formerSlugs` | `{ formerSlugs: 1 }` | not unique; a retired slug must stay findable |
 | Account | `credential` | `{ credential: 1 }` | unique |
 | Account | `entityId` | `{ entityId: 1 }` | |
 | Account | `secret` | `{ secret: 1 }` | unique, sparse |
+| Account | `name` | `{ name: 1 }` | not unique — one address is legitimately both a platform account and an end-user row |
 | Profile | `userId` | `{ userId: 1 }` | |
 | Profile | `entityId` | `{ entityId: 1 }` | |
 | Profile | `role` | `{ role: 1, entityId: 1 }` | |
@@ -118,32 +193,42 @@ by the reference conversion's design.
 | Credentials | `provider` | `{ type: 1, userId: 1, credential: 1 }` | unique |
 | Credentials | `profileId` | `{ profileId: 1 }` | |
 
-## Important Gotchas
-
-- **`Resource.pick()` is destructive** — it deletes the record it finds. For read-only identity lookups in gates or handlers, use `load(id, field)` for single-field indexed queries or `list(criteria)` for multi-field queries. Never use `pick()` in authorization checks.
-- **`IdentityLinkingService` is compatible with `AccountLinkingService`** from `@owlmeans/server-oidc-rp` but defined independently to avoid circular dependency. Both return `AuthPayload`.
-- First-login profiles are created with `ALL_SCOPES` and `AuthRole.User` — the gate layer is initially permissive per entity. Restrict scopes as needed for fine-grained authorization.
-- Account `credential` slug generation retries up to 5 times on duplicate key collision — this is the designed behavior for the Base58 slug space.
-
-## Product-Viable Usage Notes
-
-- Register `appendAuthIdentityResources(context)` immediately after `appendAuthService(context)` so guards can authenticate before product gates authorize.
-- Product gates should load `AUTH_IDENTITY_PROFILE` read-only, verify `entityId`, reject expired/blocked profiles, then compare gate params against profile scopes.
-- Google login goes through OIDC provider config, but the durable authorization source is the local `IdentityProfile` record.
-- Account `credential` is the public local entity slug. Keep it separate from Mongo account `id` and provider subject identifiers.
-
-## Relationship to Other Auth Packages
-
-- **`@owlmeans/server-auth`** — manages the auth guard (token verification). This package manages the identity store underneath.
-- **`@owlmeans/server-oidc-rp`** — the OIDC relying party that can call `IdentityLinkingService` during OAuth callback to map external identity to local profile. The linking interface is compatible but independent.
-- **`@owlmeans/oidc`** — provides `ProviderProfileDetails` and `OidcProviderDescriptor` types consumed by the linking service and the OIDC client.
+## Gotchas
+
+- **`Resource.take()` is destructive** — it deletes the record it returns. Identity lookups in gates
+  and handlers use `load(where)`, which answers a multi-field query in one call
+  (`load({ type, userId, credential })`), or `list(where, opts)` for every match. Never `take()` in
+  an authorization check.
+- **`IdentityLinkingService` is compatible with `AccountLinkingService`** from
+  `@owlmeans/server-oidc-rp` but declared independently, to keep the dependency acyclic. Both return
+  `AuthPayload`.
+- First-login profiles are created with `ALL_SCOPES` and `AuthRole.User` — the gate layer starts
+  permissive within one organization entity. Narrow the scopes where finer authorization is needed.
+- `mintSlug` throws `SyntaxError('entity:slug-exhausted')` after `MAX_ENTITY_SLUG_ATTEMPTS` word
+  bases (three numeric suffixes each). `rename` throws `entity:slug-malformed:<slug>` against
+  `ENTITY_SLUG_PATTERN` and `entity:slug-taken:<slug>` for a name any entity has ever answered to.
+- The resolver caches every name a hit was found under — id, slug, former slug, `iamKey` — for 30
+  seconds. A rename is therefore visible to other replicas within that window, which is survivable
+  precisely because the old slug keeps resolving.
+
+## Relationship to other auth packages
+
+- **`@owlmeans/server-auth`** — verifies the bearer token and canonicalizes the slug on the
+  credential through this package's resolver. This package is the store underneath.
+- **`@owlmeans/auth-common`** — declares `EntityResolverService` (implemented here),
+  `ENTITY_RESOLVER` and `OrgEntityRef`, and carries the `entityKeyOf` / `requireEntityKey` /
+  `attachEntity` helpers that read what this package resolves.
+- **`@owlmeans/server-oidc-rp`** — the relying party that calls the linking service during an OAuth
+  callback.
+- **`@owlmeans/server-auth-otp`** — the email-OTP plugin resolves its user through the linking
+  service.
+- **`@owlmeans/oidc`** — supplies `ProviderProfileDetails` and `OidcProviderDescriptor`.
 
 ## Depends On
 
 - `@owlmeans/auth` — `AuthPayload`, `AuthRole`, `ALL_SCOPES`, `Profile`, `AuthCredentials`
-- `@owlmeans/basic-ids` — `createIdOfLength`, `IdStyle`
-- `@owlmeans/context` — `appendContextual`
-- `@owlmeans/mongo-resource` — `makeMongoResource`
-- `@owlmeans/oidc` — `ProviderProfileDetails`
-- `@owlmeans/resource` — `ResourceRecord`
-- `@owlmeans/server-context` — `ServerConfig`, `ServerContext`
+- `@owlmeans/auth-common` — `EntityResolverService`, `ENTITY_RESOLVER`, `ENTITY_SLUG_PATTERN`
+- `@owlmeans/basic-ids` — `createIdOfLength`, `IdStyle`, `generateWordSlug`, `nextSlugCandidate`
+- `@owlmeans/mongo-resource` — `makeMongoResource`, declared references and indexes
+- `@owlmeans/context`, `@owlmeans/resource`, `@owlmeans/oidc`, `@owlmeans/server-context`
+- `mongodb` (peer) — the driver behind the Mongo resources this package registers

package/build/consts.d.ts

@@ -2,10 +2,13 @@ export declare const AUTH_IDENTITY_ACCOUNT = "auth-identity:account";
 export declare const AUTH_IDENTITY_PROFILE = "auth-identity:profile";
 export declare const AUTH_IDENTITY_CREDENTIALS = "auth-identity:credentials";
 export declare const AUTH_IDENTITY_LINKING = "auth-identity:linking";
+export declare const AUTH_IDENTITY_ORG_ENTITY = "auth-identity:org-entity";
 export declare const AUTH_IDENTITY_ACCOUNT_COLLECTION = "account";
 export declare const AUTH_IDENTITY_PROFILE_COLLECTION = "profile";
 export declare const AUTH_IDENTITY_CREDENTIALS_COLLECTION = "credentials";
+export declare const AUTH_IDENTITY_ORG_ENTITY_COLLECTION = "org-entity";
 export declare const AUTH_IDENTITY_DB_ALIAS = "auth-identity";
+export declare const MAX_ENTITY_SLUG_ATTEMPTS = 8;
 export declare const LOGIN_SERVICE_PREFIX = "service";
 export declare const EXTERNAL_KEY_DELIMITER = ":";
 //# 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":"AAKA,eAAO,MAAM,qBAAqB,0BAA0B,CAAA;AAC5D,eAAO,MAAM,qBAAqB,0BAA0B,CAAA;AAC5D,eAAO,MAAM,yBAAyB,8BAA8B,CAAA;AACpE,eAAO,MAAM,qBAAqB,0BAA0B,CAAA;AAM5D,eAAO,MAAM,gCAAgC,YAAY,CAAA;AACzD,eAAO,MAAM,gCAAgC,YAAY,CAAA;AACzD,eAAO,MAAM,oCAAoC,gBAAgB,CAAA;AAIjE,eAAO,MAAM,sBAAsB,kBAAkB,CAAA;AAGrD,eAAO,MAAM,oBAAoB,YAAY,CAAA;AAC7C,eAAO,MAAM,sBAAsB,MAAM,CAAA"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,qBAAqB,0BAA0B,CAAA;AAC5D,eAAO,MAAM,qBAAqB,0BAA0B,CAAA;AAC5D,eAAO,MAAM,yBAAyB,8BAA8B,CAAA;AACpE,eAAO,MAAM,qBAAqB,0BAA0B,CAAA;AAC5D,eAAO,MAAM,wBAAwB,6BAA6B,CAAA;AAMlE,eAAO,MAAM,gCAAgC,YAAY,CAAA;AACzD,eAAO,MAAM,gCAAgC,YAAY,CAAA;AACzD,eAAO,MAAM,oCAAoC,gBAAgB,CAAA;AACjE,eAAO,MAAM,mCAAmC,eAAe,CAAA;AAI/D,eAAO,MAAM,sBAAsB,kBAAkB,CAAA;AAIrD,eAAO,MAAM,wBAAwB,IAAI,CAAA;AAGzC,eAAO,MAAM,oBAAoB,YAAY,CAAA;AAC7C,eAAO,MAAM,sBAAsB,MAAM,CAAA"}

package/build/consts.js

@@ -6,6 +6,7 @@ export const AUTH_IDENTITY_ACCOUNT = 'auth-identity:account';
 export const AUTH_IDENTITY_PROFILE = 'auth-identity:profile';
 export const AUTH_IDENTITY_CREDENTIALS = 'auth-identity:credentials';
 export const AUTH_IDENTITY_LINKING = 'auth-identity:linking';
+export const AUTH_IDENTITY_ORG_ENTITY = 'auth-identity:org-entity';
 // Colon-free Mongo collection base names. The final collection name is
 // `${resourcePrefix}${collection}` — e.g. with the project prefix 'viam-' this yields
 // 'viam-account'. Register the identity resources against a db config that carries the
@@ -13,9 +14,13 @@ export const AUTH_IDENTITY_LINKING = 'auth-identity:linking';
 export const AUTH_IDENTITY_ACCOUNT_COLLECTION = 'account';
 export const AUTH_IDENTITY_PROFILE_COLLECTION = 'profile';
 export const AUTH_IDENTITY_CREDENTIALS_COLLECTION = 'credentials';
+export const AUTH_IDENTITY_ORG_ENTITY_COLLECTION = 'org-entity';
 // Suggested db-config alias for a dedicated config whose resourcePrefix scopes the
 // collection prefix to identity collections only (not the whole database).
 export const AUTH_IDENTITY_DB_ALIAS = 'auth-identity';
+// How many slugs to try before giving up on minting a free one. Collisions are settled against a
+// unique index, so this bounds a retry loop rather than a probability.
+export const MAX_ENTITY_SLUG_ATTEMPTS = 8;
 // Helper prefixes for stable key derivation
 export const LOGIN_SERVICE_PREFIX = 'service';
 export const EXTERNAL_KEY_DELIMITER = ':';

package/build/consts.js.map

@@ -1 +1 @@
-{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,wFAAwF;AACxF,sFAAsF;AACtF,sFAAsF;AACtF,uFAAuF;AACvF,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAA;AAC5D,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAA;AAC5D,MAAM,CAAC,MAAM,yBAAyB,GAAG,2BAA2B,CAAA;AACpE,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAA;AAE5D,uEAAuE;AACvE,sFAAsF;AACtF,uFAAuF;AACvF,2FAA2F;AAC3F,MAAM,CAAC,MAAM,gCAAgC,GAAG,SAAS,CAAA;AACzD,MAAM,CAAC,MAAM,gCAAgC,GAAG,SAAS,CAAA;AACzD,MAAM,CAAC,MAAM,oCAAoC,GAAG,aAAa,CAAA;AAEjE,mFAAmF;AACnF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,sBAAsB,GAAG,eAAe,CAAA;AAErD,4CAA4C;AAC5C,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAA;AAC7C,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAA"}
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,wFAAwF;AACxF,sFAAsF;AACtF,sFAAsF;AACtF,uFAAuF;AACvF,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAA;AAC5D,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAA;AAC5D,MAAM,CAAC,MAAM,yBAAyB,GAAG,2BAA2B,CAAA;AACpE,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAA;AAC5D,MAAM,CAAC,MAAM,wBAAwB,GAAG,0BAA0B,CAAA;AAElE,uEAAuE;AACvE,sFAAsF;AACtF,uFAAuF;AACvF,2FAA2F;AAC3F,MAAM,CAAC,MAAM,gCAAgC,GAAG,SAAS,CAAA;AACzD,MAAM,CAAC,MAAM,gCAAgC,GAAG,SAAS,CAAA;AACzD,MAAM,CAAC,MAAM,oCAAoC,GAAG,aAAa,CAAA;AACjE,MAAM,CAAC,MAAM,mCAAmC,GAAG,YAAY,CAAA;AAE/D,mFAAmF;AACnF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,sBAAsB,GAAG,eAAe,CAAA;AAErD,iGAAiG;AACjG,uEAAuE;AACvE,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAA;AAEzC,4CAA4C;AAC5C,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAA;AAC7C,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAA"}

package/build/helper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIrD,eAAO,MAAM,2BAA2B,YAC7B,YAAY,CAAC,GAAG,CAAC,YAChB,MAAM,KACf,IAKF,CAAA"}
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAKrD,eAAO,MAAM,2BAA2B,YAC7B,YAAY,CAAC,GAAG,CAAC,YAChB,MAAM,KACf,IAUF,CAAA"}

package/build/helper.js

@@ -1,9 +1,15 @@
-import { makeIdentityAccountResource, makeIdentityProfileResource, makeIdentityCredentialsResource } from './resource.js';
+import { makeIdentityAccountResource, makeIdentityProfileResource, makeIdentityCredentialsResource, makeOrgEntityResource } from './resource.js';
 import { makeIdentityLinkingService } from './service.js';
+import { makeEntityResolverService } from './resolver.js';
 export const appendAuthIdentityResources = (context, dbAlias) => {
     context.registerResource(makeIdentityAccountResource(dbAlias));
     context.registerResource(makeIdentityProfileResource(dbAlias));
     context.registerResource(makeIdentityCredentialsResource(dbAlias));
+    context.registerResource(makeOrgEntityResource(dbAlias));
     context.registerService(makeIdentityLinkingService());
+    // Registering the resolver is what tells the server boundary that this deployment HAS
+    // organizations: without it `request.entity` stays undefined and every consumer falls back to
+    // treating the token's slug as the only entity value there is.
+    context.registerService(makeEntityResolverService());
 };
 //# sourceMappingURL=helper.js.map

package/build/helper.js.map

@@ -1 +1 @@
-{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,2BAA2B,EAAE,2BAA2B,EAAE,+BAA+B,EAAE,MAAM,eAAe,CAAA;AACzH,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAA;AAEzD,MAAM,CAAC,MAAM,2BAA2B,GAAG,CACzC,OAA0B,EAC1B,OAAgB,EACV,EAAE;IACR,OAAO,CAAC,gBAAgB,CAAC,2BAA2B,CAAC,OAAO,CAAC,CAAC,CAAA;IAC9D,OAAO,CAAC,gBAAgB,CAAC,2BAA2B,CAAC,OAAO,CAAC,CAAC,CAAA;IAC9D,OAAO,CAAC,gBAAgB,CAAC,+BAA+B,CAAC,OAAO,CAAC,CAAC,CAAA;IAClE,OAAO,CAAC,eAAe,CAAC,0BAA0B,EAAE,CAAC,CAAA;AACvD,CAAC,CAAA"}
+{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,2BAA2B,EAAE,2BAA2B,EAAE,+BAA+B,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAChJ,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAA;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAA;AAEzD,MAAM,CAAC,MAAM,2BAA2B,GAAG,CACzC,OAA0B,EAC1B,OAAgB,EACV,EAAE;IACR,OAAO,CAAC,gBAAgB,CAAC,2BAA2B,CAAC,OAAO,CAAC,CAAC,CAAA;IAC9D,OAAO,CAAC,gBAAgB,CAAC,2BAA2B,CAAC,OAAO,CAAC,CAAC,CAAA;IAC9D,OAAO,CAAC,gBAAgB,CAAC,+BAA+B,CAAC,OAAO,CAAC,CAAC,CAAA;IAClE,OAAO,CAAC,gBAAgB,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAA;IACxD,OAAO,CAAC,eAAe,CAAC,0BAA0B,EAAE,CAAC,CAAA;IACrD,sFAAsF;IACtF,8FAA8F;IAC9F,+DAA+D;IAC/D,OAAO,CAAC,eAAe,CAAC,yBAAyB,EAAE,CAAC,CAAA;AACtD,CAAC,CAAA"}

package/build/index.d.ts

@@ -2,6 +2,7 @@ export * from './consts.js';
 export type * from './types.js';
 export * from './resource.js';
 export * from './service.js';
+export * from './resolver.js';
 export * from './helper.js';
 export * from './iam.js';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,mBAAmB,YAAY,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,mBAAmB,YAAY,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA"}

package/build/index.js

@@ -1,6 +1,7 @@
 export * from './consts.js';
 export * from './resource.js';
 export * from './service.js';
+export * from './resolver.js';
 export * from './helper.js';
 export * from './iam.js';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAE3B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAE3B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA"}

package/build/resolver.d.ts

@@ -0,0 +1,3 @@
+import type { EntityResolverService } from '@owlmeans/auth-common';
+export declare const makeEntityResolverService: (alias?: string) => EntityResolverService;
+//# sourceMappingURL=resolver.d.ts.map

package/build/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../src/resolver.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAgB,MAAM,uBAAuB,CAAA;AA6BhF,eAAO,MAAM,yBAAyB,WAC7B,MAAM,KACZ,qBAkIF,CAAA"}

package/build/resolver.js

@@ -0,0 +1,133 @@
+import { appendContextual } from '@owlmeans/context';
+import { ENTITY_RESOLVER, ENTITY_SLUG_PATTERN } from '@owlmeans/auth-common';
+import { generateWordSlug, nextSlugCandidate } from '@owlmeans/basic-ids';
+import { AUTH_IDENTITY_ORG_ENTITY, MAX_ENTITY_SLUG_ATTEMPTS } from './consts.js';
+/**
+ * How long a resolution is trusted without re-reading the registry.
+ *
+ * Every authenticated request resolves an entity, so an uncached resolver would put a database
+ * round-trip in front of the whole API. The cost of the cache is a rename taking up to this long
+ * to be seen by other replicas — which is survivable precisely because the old slug keeps
+ * resolving through `formerSlugs` rather than failing.
+ */
+const CACHE_TTL = 30_000;
+/** A stored record as the contract exposes it. Persisted records always carry an id. */
+const toRef = (entity) => entity == null ? null : {
+    id: entity.id, slug: entity.slug, formerSlugs: entity.formerSlugs, iamKey: entity.iamKey,
+};
+export const makeEntityResolverService = (alias = ENTITY_RESOLVER) => {
+    // Keyed by every name a caller might arrive with — id, slug, former slug, iamKey — so a hit
+    // costs one lookup regardless of which one it was.
+    const cache = new Map();
+    const now = () => Date.now();
+    const remember = (entity, ...keys) => {
+        const at = now();
+        for (const key of keys) {
+            if (key !== '')
+                cache.set(key, { entity, at });
+        }
+        if (entity != null) {
+            cache.set(entity.id, { entity, at });
+            cache.set(entity.slug, { entity, at });
+            cache.set(entity.iamKey, { entity, at });
+            for (const former of entity.formerSlugs ?? [])
+                cache.set(former, { entity, at });
+        }
+        return entity;
+    };
+    const forget = (entity) => {
+        for (const key of [entity.id, entity.slug, entity.iamKey, ...(entity.formerSlugs ?? [])]) {
+            if (key != null)
+                cache.delete(key);
+        }
+    };
+    const resource = () => service.ctx.resource(AUTH_IDENTITY_ORG_ENTITY);
+    const load = async (value) => {
+        const cached = cache.get(value);
+        if (cached != null && now() - cached.at < CACHE_TTL) {
+            return cached.entity;
+        }
+        const res = resource();
+        // Id first: an id is authoritative, so a slug that happens to look like some other entity's
+        // id can never shadow it. A value that is not a record id simply misses. Then the current
+        // slug, then the names it has retired, then the frozen key external systems still quote.
+        const byId = await res.load(value);
+        if (byId != null)
+            return remember(byId, value);
+        const candidates = [
+            { slug: value },
+            { formerSlugs: { $contains: [value] } },
+            { iamKey: value },
+        ];
+        for (const where of candidates) {
+            const found = await res.load(where);
+            if (found != null)
+                return remember(found, value);
+        }
+        return remember(null, value);
+    };
+    const service = appendContextual(alias, {
+        resolve: async (value) => toRef(await load(value)),
+        byId: async (id) => toRef(remember(await resource().load(id), id)),
+        mintSlug: async () => {
+            const res = resource();
+            // A word slug is picked from 2^22 pairs, so a collision is rare — but "rare" is not "never"
+            // once an installation has many organizations, and the numeric suffix keeps the readable
+            // name rather than rerolling into an unrelated one.
+            for (let attempt = 1; attempt <= MAX_ENTITY_SLUG_ATTEMPTS; ++attempt) {
+                const base = generateWordSlug();
+                for (let suffix = 1; suffix <= 3; ++suffix) {
+                    const candidate = nextSlugCandidate(base, suffix);
+                    const taken = await res.load({
+                        $or: [{ slug: candidate }, { formerSlugs: { $contains: [candidate] } }],
+                    });
+                    if (taken == null)
+                        return candidate;
+                }
+            }
+            throw new SyntaxError('entity:slug-exhausted');
+        },
+        rename: async (id, slug) => {
+            if (!ENTITY_SLUG_PATTERN.test(slug)) {
+                throw new SyntaxError(`entity:slug-malformed:${slug}`);
+            }
+            const res = resource();
+            const entity = await res.get(id);
+            if (entity.slug === slug) {
+                return toRef(entity);
+            }
+            // A slug another entity has ever answered to cannot be taken: tokens and third-party records
+            // quoting it would start resolving to the wrong organization.
+            const taken = await res.load({
+                $or: [{ slug }, { formerSlugs: { $contains: [slug] } }],
+            });
+            if (taken != null && taken.id !== id) {
+                throw new SyntaxError(`entity:slug-taken:${slug}`);
+            }
+            forget(entity);
+            const formerSlugs = [...new Set([...(entity.formerSlugs ?? []), entity.slug])]
+                .filter(former => former !== slug);
+            const updated = await res.update({ ...entity, slug, formerSlugs, updatedAt: new Date() });
+            return toRef(remember(updated));
+        },
+        mintName: async (id, key, mint) => {
+            const res = resource();
+            const entity = await res.get(id);
+            const existing = entity.names?.[key];
+            // Read-before-mint is what freezes the name: the second caller gets the first caller's
+            // answer, so a rename between the two cannot produce two names for one live resource.
+            if (existing != null && existing !== '') {
+                return existing;
+            }
+            const minted = mint(toRef(entity));
+            forget(entity);
+            const updated = await res.update({
+                ...entity, names: { ...entity.names, [key]: minted }, updatedAt: new Date(),
+            });
+            remember(updated);
+            return updated.names?.[key] ?? minted;
+        },
+    });
+    return service;
+};
+//# sourceMappingURL=resolver.js.map