@owlmeans/server-oidc-rp 0.1.18-rc.3 → 0.1.18-rc.30

package/README.md

@@ -1,108 +1,221 @@
 # @owlmeans/server-oidc-rp
 
-Server-side OIDC relying party — registers the OIDC guard, wrapping service, gate, and IdP-side client wiring.
-
-## Overview
-
-- `appendOidcGuard(context)` — registers the OIDC guard service
-- `makeOidcWrappingService()` / `makeOidcGate()` — token wrapping service and gate factory
-- `setupOidcGuard(modules, coguards?, extras?)` — attaches the OIDC guard to module declarations
-- `setupAuthServiceModules(...)` — wires external auth modules
-- `makeOidcClientService()` / `OidcClientService` — IdP-side client (e.g., Keycloak admin)
-- Subpath `./auth` — admin-client constants like `OIDC_ADMIN_CLIENT`
+The server-side OIDC relying party. An application uses it when users sign in through an OIDC or
+OAuth provider (an OIDC IAM, Google): it reads provider descriptors from `cfg.oidc.providers`, runs
+discovery and the code exchange, registers the OIDC and Google plugins in the auth manager, and keeps
+OIDC-wrapped tokens fresh. It also supplies the OIDC guard and UMA2 gate for a product whose
+authorization is the provider's own grants. A product that uses the provider only to log in and keeps
+authorization in local records uses `@owlmeans/server-auth-identity` plus its own `GateService`
+instead of the guard and gate. Being a provider is `@owlmeans/server-oidc-provider`, the browser side
+is `@owlmeans/web-oidc-rp`, and `appendIam()` from `@owlmeans/server-iam` performs the standard
+registrations with the IAM gate.
 
 ## Installation
 
 ```bash
-bun add @owlmeans/server-oidc-rp
-```
-
-## Usage
-
-Register services in `context.ts`:
-
-```typescript
-import {
-  appendOidcGuard, makeOidcWrappingService, makeOidcGate, makeOidcClientService
-} from '@owlmeans/server-oidc-rp'
-
-context.registerService(makeOidcWrappingService())
-context.registerService(makeOidcGate())
-context.registerService(makeOidcClientService())
-appendOidcGuard<C, T>(context)
+bun add @owlmeans/server-oidc-rp@^0.1.18-rc.29
 ```
 
-Wire onto modules in `modules.ts`:
+## Concepts
+
+- **Provider descriptor** — an entry of `cfg.oidc.providers`: `clientId`, `secret`, either
+  `discoveryUrl` or `service` + `basePath`, optional `extraScopes`, `entityId`, `internal`, `def`.
+- **Client service** — `OidcClientService` (`oidc-client`), the only way to reach a descriptor and
+  the `OidcClientAdapter` that performs grants, refresh and introspection.
+- **Account linking** — the optional `AccountLinkingService` named by
+  `cfg.oidc.accountLinkingService`, which maps a provider profile onto a local `AuthPayload`.
+- **Wrapped token** — a bearer that wraps a provider token set; the `WRAPPED_OIDC` service
+  re-validates it (refresh or introspection) once `OIDC_WRAP_FRESHNESS` has passed.
+- **UMA2 gate** — `makeOidcGate()` under `OIDC_GATE`, admitting a request only when the token's
+  permission claim grants what the gate params ask for.
+- **Token cache** — records in `AUTH_CACHE` whose ids are prefixed with `OIDC_TOKEN_STORE`; there is
+  no separate resource.
 
-```typescript
-import { setupOidcGuard, setupAuthServiceModules } from '@owlmeans/server-oidc-rp'
-
-setupOidcGuard(appModules)
-setupAuthServiceModules(appModules)
-```
+## Usage
 
-Configure providers in `config.ts`:
+### Configure providers
 
-```typescript
+```ts
+import { GOOGLE_SERVICE } from '@owlmeans/oidc'
 import { OIDC_ADMIN_CLIENT } from '@owlmeans/server-oidc-rp/auth'
+import { AUTH_IDENTITY_LINKING } from '@owlmeans/server-auth-identity'
 
 cfg.oidc ??= {}
 cfg.oidc.providers ??= []
+cfg.oidc.accountLinkingService = AUTH_IDENTITY_LINKING
+
+// an internal admin client of the IAM; the issuer is reassembled from the `my-app-iam` service host
 cfg.oidc.providers.push({
   clientId: OIDC_ADMIN_CLIENT,
   basePath: 'realms/master',
-  service: OIDC_PRODUCT,
-  secret: '/etc/master-secret/oidc-admin-secret',
-  internal: true
+  service: 'my-app-iam',
+  secret: process.env.IAM_ADMIN_SECRET!,
+  internal: true,
+})
+
+// Google login; on a Google descriptor extraScopes is the whole scope
+cfg.oidc.providers.push({
+  clientId: process.env.GOOGLE_CLIENT_ID!,
+  secret: process.env.GOOGLE_CLIENT_SECRET!,
+  service: GOOGLE_SERVICE,
+  extraScopes: 'openid profile email',
 })
 ```
 
-Use the IdP-side client in a service:
+### Login-only: provider sign-in, local authorization
 
-```typescript
-import { DEFAULT_ALIAS as OIDC_SERVICE } from '@owlmeans/server-oidc-rp'
-import type { OidcClientService } from '@owlmeans/server-oidc-rp'
+The API context registers the client service; the process that serves the auth manager imports the
+plugin module once.
 
-const oidc = context.service<OidcClientService>(OIDC_SERVICE)
+```ts
+// context.ts
+import { makeOidcClientService } from '@owlmeans/server-oidc-rp'
+
+context.registerService(makeOidcClientService())
+appendAuthIdentityResources(context, AUTH_IDENTITY_DB_ALIAS)
+context.registerService(makeMyAppGate()) // a GateService over IdentityProfile scopes
 ```
 
-## API
+```ts
+// entrypoints.ts of the service that hosts the auth manager
+import { entrypoints as authManagerEntrypoints } from '@owlmeans/server-auth/manager'
+import '@owlmeans/server-oidc-rp/auth/plugins' // registers OIDC_CLIENT_AUTH and GOOGLE_CLIENT_AUTH
+```
 
-### Service factories
+### Provider-authorized: guard, gate and bindings
 
-- `appendOidcGuard<C, T>(context): T` — register the OIDC guard
-- `makeOidcWrappingService(alias?)` — token-wrapping service
-- `makeOidcGate(alias?)` — gate factory
-- `makeOidcClientService(alias?)` — IdP-side client (used to call OIDC admin API)
+```ts
+// context.ts
+import {
+  appendOidcGuard, makeOidcClientService, makeOidcGate, makeOidcWrappingService,
+} from '@owlmeans/server-oidc-rp'
 
-### Module wiring
+context.registerService(makeOidcClientService())
+context.registerService(makeOidcWrappingService())
+context.registerService(makeOidcGate())
+appendOidcGuard<C, T>(context)
+```
 
-- `setupOidcGuard(modules, coguards?, extras?)` — attach guard to module declarations
-- `setupAuthServiceModules(modules, ...)` — register external auth modules
+```ts
+// entrypoints.ts
+import { withOidcGuard } from '@owlmeans/oidc'
+import { makeAuthServiceEntrypoints, oidcEntrypoints } from '@owlmeans/server-oidc-rp'
+import { bindAll } from '@owlmeans/server-entrypoint'
+import { protocols } from '@owlmeans/entrypoint'
+
+// decorate first, then make handlers from and bind the decorated objects
+export const configuredProtocols = withOidcGuard(appProtocols)
+
+export const serverBindings = [
+  ...bindAll(protocols(configuredProtocols.api), [invoice.list, invoice.pay]),
+  ...oidcEntrypoints,
+  ...bindAll(makeAuthServiceEntrypoints('my-app-auth-api')),
+]
+```
+
+### Call a provider with the client service
+
+```ts
+import { GOOGLE_SERVICE } from '@owlmeans/oidc'
+import { DEFAULT_ALIAS as OIDC_CLIENT, requestedScope } from '@owlmeans/server-oidc-rp'
+import type { OidcClientService } from '@owlmeans/server-oidc-rp'
+import { OIDC_ADMIN_CLIENT } from '@owlmeans/server-oidc-rp/auth'
 
-### Constants
+const oidc = context.service<OidcClientService>(OIDC_CLIENT)
 
-- `DEFAULT_ALIAS` — `'oidc-client'`
-- `OIDC_TOKEN_STORE`, `PROVIDER_CACHE_TTL`, `OIDC_AUTH_LIFTETIME`, `OIDC_WRAP_FRESHNESS`
-- `./auth` subpath: `OIDC_ADMIN_CLIENT` and related admin-client constants
+const admin = oidc.findProvider(provider => provider.clientId === OIDC_ADMIN_CLIENT && provider.internal === true)
+if (admin != null) {
+  const client = await oidc.getClient(admin.clientId)
+  const { access_token } = await client.grantWithCredentials()
+  // call the provider's admin API with access_token
+}
 
-### Types
+const google = oidc.findProvider(provider => provider.service === GOOGLE_SERVICE)
+const scope = requestedScope(google?.extraScopes) // base scopes + extras, deduplicated
+```
+
+### Read the provider token set behind a request
 
-`OidcClientService`, RP config types — exported from the root entry.
+```ts
+import { AUTH_CACHE } from '@owlmeans/server-auth'
+import { OIDC_TOKEN_STORE } from '@owlmeans/server-oidc-rp'
+import type { OidcTokenSetParameters } from '@owlmeans/server-oidc-rp'
+import type { Resource, ResourceRecord } from '@owlmeans/resource'
+import { decodeJwt } from 'jose'
 
-## Product-Viable Integration Notes
+interface TokenRecord extends ResourceRecord { payload?: OidcTokenSetParameters }
 
-- `makeOidcClientService()` reads provider descriptors from `cfg.oidc.providers`, including Google and internal admin providers.
-- Use `findProvider(predicate)`, `hasProvider(params)`, and `entityToClientId(params)` for provider lookup rather than ad hoc config scans.
-- `setupAuthServiceModules(managerModules, AUTH_API)` wires provider-list and token-update endpoints protected by `GUARD_ED25519`.
-- If OIDC/Google is only the login provider and local identity records hold authorization, do not re-add `appendOidcGuard()`, `makeOidcGate()`, or `setupOidcGuard()` as product authorization. Use a product-specific `GateService` over local profile scopes.
+const record = await context.resource<Resource<TokenRecord>>(AUTH_CACHE)
+  .load(`${OIDC_TOKEN_STORE}:token:${request.auth!.token}`)
 
-## Related Packages
+// only the id_token is a JWT; an access token is opaque
+const claims = record?.payload?.id_token != null ? decodeJwt(record.payload.id_token) : undefined
+```
+
+## API
 
-- [`@owlmeans/oidc`](../oidc) — shared `OIDC_GATE`, `OIDC_GUARD`, types
-- [`@owlmeans/server-auth`](../server-auth) — works alongside the OIDC guard for token verification
-- [`@owlmeans/server-context`](../server-context) — base context where services are registered
-- [`@owlmeans/auth-common`](../auth-common) — `DEFAULT_GUARD` co-attached via `setupOidcGuard`
+### Root export
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `makeOidcClientService(alias = DEFAULT_ALIAS)` | function | The relying-party service over `cfg.oidc.providers` |
+| `makeOidcWrappingService()` | function | Registers `WRAPPED_OIDC`, which refreshes and re-issues wrapped tokens |
+| `makeOidcGate(alias = OIDC_GATE)` | function | UMA2 gate; throws `AuthForbidden` without a matching permission |
+| `appendOidcGuard<C, T>(context, opts?)` | function | Register the OIDC guard; `opts` is `OidcGuardOptions` from `@owlmeans/oidc` |
+| `oidcEntrypoints` | const | Server bindings of `oidcProtocols.init` and `oidcProtocols.authenticate` |
+| `makeAuthServiceEntrypoints(serviceAlias, prefix = 'oidc-api')` | function | Provider-list and token-update protocol declarations guarded by `GUARD_ED25519` |
+| `requestedScope(extraScopes?)` | function | `OIDC_RP_BASE_SCOPES` plus a descriptor's extras, deduplicated |
+| `createGateModel(ctx)` | function | Permission model: `loadPermissions(auth, params)` |
+| `extractPermissionSets(claim)` | function | Validate a permissions claim into `PermissionSet[]` or `undefined` |
+| `authService` | const | Aliases `authService.provider.list`, `authService.auth.update` |
+| `DEFAULT_ALIAS` | const | `'oidc-client'` |
+| `DEF_OIDC_ACCOUNT_LINKING`, `DEF_OIDC_PROVIDER_API` | const | Default aliases of the linking and provider-API seams |
+| `OIDC_TOKEN_STORE` | const | Record-id prefix inside `AUTH_CACHE` — not a resource alias |
+| `OIDC_AUTH_LIFTETIME` | const | 24 h TTL of a stored token record |
+| `OIDC_WRAP_FRESHNESS` | const | Window inside which a validated record is returned unchanged |
+| `PROVIDER_CACHE_TTL` | const | Exported but unused |
+| `OidcClientService`, `OidcClientAdapter` | type | Client service and per-provider adapter |
+| `OidcTokenSet`, `OidcTokenSetParameters`, `OidcGrantChecks`, `OidcServerMetadata`, `OidcIntrospectionResponse`, `OidcClientDescriptor` | type | Owned replacements for `openid-client` types |
+| `AccountLinkingService`, `AccountMeta`, `ProviderApiService` | type | Optional seams |
+| `OidcRpConfig`, `Config`, `Context` | type | `cfg.oidc` with `accountLinkingService?` / `providerApiService?`, and the server shapes |
+
+### Subpaths
+
+| Subpath | Symbol | Purpose |
+|---|---|---|
+| `./auth` | `OIDC_ADMIN_CLIENT` | `'admin-cli'` — the IAM admin client id |
+| `./auth/plugins` | side-effect import, `plugins` | Registers `OIDC_CLIENT_AUTH` and `GOOGLE_CLIENT_AUTH` in the `@owlmeans/server-auth` manager registry |
+
+## Common pitfalls
+
+- A product that only logs in through the provider and authorizes against local identity records
+  must not adopt `appendOidcGuard()` or `makeOidcGate()` as its authorization.
+- Register the wrapping service whenever the guard is registered, or wrapped tokens expire
+  mid-session.
+- Resolve descriptors through `OidcClientService` (`findProvider`, `hasProvider`, `getConfig`,
+  `getDefault`, `entityToClientId`); never scan `cfg.oidc.providers` in application code.
+- `registerTemporaryProvider` is reference-counted — pair every call with
+  `unregisterTemporaryProvider`.
+- Decode only `id_token`. An access token's format is provider-private; use `introspect` when its
+  contents are needed.
+- PKCE verifiers are consume-once: a repeated exchange for one authorization code fails even though
+  the first one succeeded.
+- The token cache is `AUTH_CACHE` at `${OIDC_TOKEN_STORE}:…` ids; `context.resource(OIDC_TOKEN_STORE)`
+  resolves nothing.
+- The provider client's allowlist must include every scope `requestedScope` yields, or the provider
+  rejects the whole request with `invalid_scope`.
+- A server context has no `.url()` on a frontend entrypoint; compose absolute URLs with
+  `makeSecurityHelper(ctx).makeUrl(entry.address(), entry.path())` from `@owlmeans/config`.
+
+## Related packages
+
+- [`@owlmeans/oidc`](../oidc) — shared OIDC types, `withOidcGuard`, `OIDC_GATE`, `oidcProtocols`
+- [`@owlmeans/server-auth`](../server-auth) — `AUTH_CACHE` and the manager plugin registry
+- [`@owlmeans/server-auth-identity`](../server-auth-identity) — local identity behind account linking
+- [`@owlmeans/server-iam`](../server-iam) — `appendIam()` with the IAM gate
+- [`@owlmeans/server-oidc-provider`](../server-oidc-provider) — the provider side
+- [`@owlmeans/web-oidc-rp`](../web-oidc-rp) — the browser side
+- [`@owlmeans/auth-common`](../auth-common) — `DEFAULT_GUARD`, which `withOidcGuard()` decorates
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -112,7 +225,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.22
 ```
 
 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-oidc-rp",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.509Z",
+  "version": "0.1.18-rc.30",
+  "generatedAt": "2026-09-15T12:38:15.193Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/server-oidc-rp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: server-oidc-rp
-description: How to use @owlmeans/server-oidc-rp — OIDC relying party. appendOidcGuard(), makeOidcWrappingService(), makeOidcGate() to wire OIDC into a server context; setupOidcGuard() to attach the guard to module declarations. Auto-invoked when importing server-oidc-rp helpers.
+description: How to use @owlmeans/server-oidc-rp — the server-side OIDC relying party — appendOidcGuard, oidcEntrypoints and makeAuthServiceEntrypoints, the OidcClientService and its adapter, the requested-scope contract, the UMA2 gate, the wrapped-token service, and the owned public types that keep openid-client out of the public surface. Auto-invoked when importing server-oidc-rp helpers or configuring identity providers on a server.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,93 +8,225 @@ user-invocable: false
 # @owlmeans/server-oidc-rp
 
 **Layer:** Server
-**Install:** `"@owlmeans/server-oidc-rp": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/server-oidc-rp": "^0.1.18-rc.30"` in `dependencies`
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `appendOidcGuard<C, T>(context)` | Add OIDC auth guard to context |
-| `makeOidcWrappingService()` | OIDC token service factory |
-| `makeOidcGate()` | OIDC gate factory (used by guards) |
-| `setupOidcGuard(modules, options?)` | Wire OIDC guard onto module declarations |
-| `requestedScope(extraScopes?)` | The `scope` of an authorization request — base scopes + provider extras |
-| Constants | OIDC service / guard aliases |
-| `OidcRp` types | RP-side config and token shapes |
+| `makeOidcClientService(alias?)` | The relying-party service: reads `cfg.oidc.providers`, runs discovery, hands back client adapters |
+| `makeOidcWrappingService()` | Registers `WRAPPED_OIDC` — refreshes and re-issues an OIDC-wrapped token before it goes stale |
+| `makeOidcGate(alias?)` | The UMA2 gate, registered under `OIDC_GATE` |
+| `appendOidcGuard<C, T>(context, opts?)` | Registers the OIDC guard on a server context. `opts` is `OidcGuardOptions` (`@owlmeans/oidc`) and is forwarded to the base guard unchanged |
+| `oidcEntrypoints` | Server-local bindings for the shared `oidcProtocols.init` and `.authenticate` declarations |
+| `makeAuthServiceEntrypoints(serviceAlias, prefix?)` | Returns provider-list and token-update protocol declarations, guarded by `GUARD_ED25519`. `prefix` defaults to `oidc-api` |
+| `requestedScope(extraScopes?)` | The `scope` of an authorization request — base scopes plus the provider's extras, deduplicated |
+| `createGateModel(ctx)` | The UMA2 permission model — `loadPermissions(auth, params)` |
+| `extractPermissionSets(claim)` | Shape-validates a `permissions` claim into `PermissionSet[]`, or `undefined` |
+| `authService` | The service entrypoint aliases: `authService.provider.list`, `authService.auth.update` |
+| `DEFAULT_ALIAS` | `'oidc-client'` — the relying-party service alias |
+| `DEF_OIDC_ACCOUNT_LINKING`, `DEF_OIDC_PROVIDER_API` | Default aliases of the two optional seams below |
+| `OIDC_TOKEN_STORE` | The **record-id prefix** this package composes cache ids from — not a resource alias. See "Where the tokens are cached" |
+| `OIDC_AUTH_LIFTETIME` | 24 h — the TTL a stored token record is saved with |
+| `OIDC_WRAP_FRESHNESS` | How long a validated record stays fresh: inside this window of its last validation the wrapping service returns the token unchanged, past it the token is re-validated and re-issued |
+| `PROVIDER_CACHE_TTL` | Exported, but its only use in the package is commented out — it configures nothing |
+| `AccountLinkingService` | Optional seam: turn a provider profile into a local `AuthPayload` (`getLinkedProfile`, `linkProfile`, `linkCredentials`, `getOwnerProfiles`, `getOwnerCredentials`) |
+| `ProviderApiService` | Optional seam onto the provider's own admin API (`getUserDetails`, `getSettings`) |
+| `OidcRpConfig` | `cfg.oidc` plus `accountLinkingService?` and `providerApiService?` |
+
+### Subpath exports
+
+- `./auth` — `OIDC_ADMIN_CLIENT` (`'admin-cli'`)
+- `./auth/plugins` — importing it registers the `OIDC_CLIENT_AUTH` and `GOOGLE_CLIENT_AUTH` plugins
+  into the `@owlmeans/server-auth` manager registry
+
+## Wiring
 
-## Requested scope
-
-Every authorization request this package builds gets its `scope` from `requestedScope(cfg.extraScopes)`
-— `OIDC_RP_BASE_SCOPES` (`@owlmeans/oidc`) plus the provider descriptor's `extraScopes`, deduplicated.
-Both request sites (`actions/init.ts` for the browser-starts-server-finishes flow, and the
-`oidc-client` auth plugin) call it; never write a scope literal at a call site, and never let the two
-drift apart.
-
-The provider's client registration must allow every scope this yields. A provider supports `email`
-as soon as it declares `claims.email` — and then rejects the whole request with
-`invalid_scope: requested scope is not allowed` if the client's own allowlist omits it, rather than
-dropping the scope. A client provisioned by an older revision therefore stays broken until its
-allowlist is backfilled.
-
-## Subpath Exports
-
-- `./auth` — auth integration helpers
-- `./auth/plugins` — pluggable token verifiers
-
-## Usage
-
-### In `context.ts`
 ```typescript
-import { appendOidcGuard, makeOidcWrappingService, makeOidcGate } from '@owlmeans/server-oidc-rp'
+import { appendOidcGuard, makeOidcWrappingService, makeOidcGate, makeOidcClientService } from '@owlmeans/server-oidc-rp'
 
+context.registerService(makeOidcClientService())
 context.registerService(makeOidcWrappingService())
 context.registerService(makeOidcGate())
 appendOidcGuard<C, T>(context)
 ```
 
-### In `modules.ts`
 ```typescript
-import { setupOidcGuard } from '@owlmeans/server-oidc-rp'
-setupOidcGuard(appModules)
+import { withOidcGuard } from '@owlmeans/oidc'
+import { oidcEntrypoints, makeAuthServiceEntrypoints } from '@owlmeans/server-oidc-rp'
+import { bindAll } from '@owlmeans/server-entrypoint'
+
+export const configuredProtocols = withOidcGuard(protocols)
+export const serverBindings = [
+  ...bindAll(configuredProtocols.api),
+  ...oidcEntrypoints,
+  ...bindAll(makeAuthServiceEntrypoints('my-auth-api')),
+]
 ```
 
-### Configure OIDC providers in `config.ts`
+Decorate the application tree before binding it; do not mutate declarations or append protocol
+objects to a server entrypoint list. `oidcEntrypoints` are bindings and are spread once. The
+auth-service helper returns declarations, so bind those declarations in the serving app.
+
 ```typescript
+// config
 cfg.oidc ??= {}
 cfg.oidc.providers ??= []
 cfg.oidc.providers.push({
   clientId: OIDC_ADMIN_CLIENT,
   basePath: 'realms/master',
-  service: OIDC_PRODUCT,
+  // the alias of a registered service whose host the issuer is reassembled from;
+  // a provider reachable by its own URL carries `discoveryUrl` instead
+  service: 'my-iam',
   secret: '/etc/master-secret/oidc-admin-secret',
   internal: true
 })
 ```
 
-## Product-Viable Usage Notes
+A consumer that only needs the IAM defaults calls `appendIam()` from `@owlmeans/server-iam`, which
+performs the four registrations above with the IAM gate in place of `makeOidcGate()`.
 
-- Viable uses `makeOidcClientService()` to read provider descriptors from `cfg.oidc.providers`, including Google and internal admin providers.
-- `findProvider(predicate)`, `hasProvider(params)`, and `entityToClientId(params)` are the preferred provider lookup helpers; avoid scanning config ad hoc in downstream code.
-- `setupAuthServiceModules(managerModules, AUTH_API)` exposes provider-list and token-update service modules protected by `GUARD_ED25519`.
-- When a downstream app uses OIDC/Google only for login and maps users into `@owlmeans/server-auth-identity`, do not reintroduce `appendOidcGuard()`, `makeOidcGate()`, or `setupOidcGuard()` as product authorization. Use a product-specific `GateService` over local identity data.
+## Resolving a provider
+
+`OidcClientService` is the only way to reach a provider descriptor. Use `findProvider(predicate)`,
+`hasProvider(params)`, `getConfig(clientId | partial)`, `getDefault()` and
+`entityToClientId(params)` rather than scanning `cfg.oidc.providers` in downstream code.
+`registerTemporaryProvider` / `unregisterTemporaryProvider` add a descriptor learned at runtime and
+are reference-counted, so every registration needs its matching removal.
+
+`getConfiguration` prefers `discoveryUrl` verbatim; it falls back to `service` + `basePath` and fails
+with `AuthManagerError('oidc.client.basepath')` or `('oidc.client.service')` when neither is usable.
+`getClient` returns an `OidcClientAdapter`: `getMetadata`, `getClientId`, `getConfig`, `makeAuthUrl`,
+`grantWithCredentials`, `grantWithCode`, `refresh` and `introspect`. That adapter is the whole
+supported surface — no `openid-client` object is ever handed out.
+
+## Requested scope
+
+`requestedScope(extraScopes)` is `OIDC_RP_BASE_SCOPES` (`@owlmeans/oidc`) plus the provider
+descriptor's `extraScopes`, deduplicated and trimmed. The two generic request sites — the
+browser-starts-server-finishes init handler and the `oidc-client` auth plugin — both build their
+`scope` from it, and neither may grow a scope literal.
+
+The `GOOGLE_CLIENT_AUTH` plugin is the exception, and it behaves differently on purpose: it sends
+the descriptor's `extraScopes` as the **whole** scope, falling back to `'openid profile email'` when
+the descriptor names none. So on a Google descriptor `extraScopes` replaces the base scopes instead
+of extending them, and adding a scope to `OIDC_RP_BASE_SCOPES` does not reach it.
+
+The provider's client registration must allow every scope this yields. A provider supports `email`
+as soon as it declares `claims.email` — and then rejects the whole request with
+`invalid_scope: requested scope is not allowed` if the client's own allowlist omits it, rather than
+dropping the scope. A client provisioned by an older revision stays broken until its allowlist is
+backfilled.
+
+## Only the `id_token` is a JWT
+
+`id_token` is a JWT by specification; an **access token's format is provider-private**. `oidc-provider`
+issues opaque access tokens by default, so `decodeJwt(tokenSet.access_token)` (`jose`) throws
+`JWTInvalid: Invalid JWT`. Inside the exchange handler that failure surfaces as a 500 on the
+`DISPATCHER_OIDC` endpoint *after* the code exchange already succeeded, which reads as a broken login
+rather than as the log line it came from. Decode only `tokenSet.id_token` — every claim this package
+needs (`sub`, the `PERMISSIONS_CLAIM` grant) lives there. This applies to debug logging too: a
+`console.log` argument is evaluated before the call, so a throwing decode in a log statement fails the
+request just as hard as one in real logic. Never introspect an access token locally; use the
+provider's introspection endpoint (`introspect`) when its contents are genuinely needed.
+
+## Where the tokens are cached
+
+There is no dedicated resource. The cache is `AUTH_CACHE` from `@owlmeans/server-auth`, and
+`OIDC_TOKEN_STORE` is only the prefix of the ids written into it:
+
+| Record id | Holds |
+|---|---|
+| `${OIDC_TOKEN_STORE}:verifier:<challenge or state>` | The PKCE verifier and the client it belongs to, until the exchange takes it |
+| `${OIDC_TOKEN_STORE}:exchange:<exchange token>` | The token set from a completed code exchange, short-lived, deleted when the process step consumes it |
+| `${OIDC_TOKEN_STORE}:token:<bearer token>` | The live token set for an issued bearer token, saved with `OIDC_AUTH_LIFTETIME` |
+
+A consumer that needs the provider token set behind the request it is serving reads
+`context.resource(AUTH_CACHE)` at `${OIDC_TOKEN_STORE}:token:<token>` — never
+`context.resource(OIDC_TOKEN_STORE)`, which resolves nothing.
+
+## PKCE verifiers are consume-once
+
+The verifier cached at init is read back with the resource's `take` — a delete-and-return. The
+exchange therefore succeeds exactly once per authorization code: a repeated exchange (a React effect
+that runs twice for one `code`, a retried request) fails with `resource:unknown-record` even though
+the first attempt worked. Callers guard against re-entry rather than expecting the read to be
+idempotent.
+
+## `entityId` in the browser-starts-server-finishes flow
+
+The init handler resolves the OIDC client two ways: via `getDefault()` (a provider flagged `def: true`,
+matched without looking at `entityId` at all) or, only when no default exists, via a remote provider
+lookup keyed by the caller-supplied `entityId`. The cached verifier record carries `entityId` **only**
+when that second path actually used it to resolve the client. The exchange step later calls
+`getConfig({ clientId, ...(entityId != null ? { entityId } : {}) })`, which requires an exact match on
+every field it is given; a stored `entityId` that was never validated against the registered provider
+— a caller-side default or placeholder, say — makes the exchange fail with a bare `AuthenFailed()`
+even though the same default provider is trivially available again at exchange time.
+
+## Building the redirect URI: the init handler has no `url()`
+
+`init.ts` runs on the SERVER, but `DISPATCHER` (`@owlmeans/auth`) is a FRONTEND route
+(`frontend({ service: DISPATCHER })` in `@owlmeans/auth-common`'s entrypoints) — the browser page
+the identity provider redirects back to. `.url()` is attached to an entrypoint reference only by
+`@owlmeans/client-entrypoint`, for a browser context that can resolve its own address; a server
+context's `context.entrypoint(DISPATCHER)` is a `CommonEntrypoint` and has no such method. Typing
+the call as `ClientEntrypoint<string>` (which does declare `.url()`) type-checks and builds clean
+but throws at request time: `context.entrypoint(DISPATCHER).url is not a function`. This shipped
+unnoticed for a long time because it is unreachable until a caller's own OIDC login FLOW actually
+reaches the step that calls `authenticate()` — a consumer whose flow config never reaches that step
+never exercises this line, so the fault surfaces only in a fully wired application, and only on the
+very first sign-in attempt.
+
+The fix — and the pattern for anywhere else in this package (or a consumer) that needs an absolute
+URL for a route it does not own — is the one `@owlmeans/server-oidc-provider`'s interaction `url`
+callback already uses: type the reference as `CommonEntrypoint`, then compose the address from
+`.path()` and `.address()` through `makeSecurityHelper(ctx).makeUrl(entry.address(), entry.path())`
+(`@owlmeans/config`). A route with path params (this one has none) needs its own substitution
+first, the way the interaction URL substitutes `:uid` before qualifying it. Typing the reference as
+`CommonEntrypoint` rather than `ClientEntrypoint` is itself the regression guard: calling `.url()`
+on it is now a compile error, not a runtime one.
 
 ## Public type contract (isolation principle)
 
-`openid-client` types **never appear in this package's public exports**. All public types are OwlMeans-owned:
+`openid-client` types **never appear in this package's public exports**. All public types are
+OwlMeans-owned:
 
 | Owned type | Replaces upstream | Description |
 |---|---|---|
-| `OidcTokenSet` | `TokenEndpointResponse & TokenEndpointResponseHelpers` | `access_token`, `refresh_token`, `id_token`, `token_type`, `expires_in`, `scope` |
-| `OidcTokenSetParameters` | `TokenEndpointResponse` | Subset without helper methods |
+| `OidcTokenSet` | `TokenEndpointResponse & TokenEndpointResponseHelpers` | `access_token`, `refresh_token`, `id_token`, `token_type`, `expires_in`, `scope`, `claims()` |
+| `OidcTokenSetParameters` | `TokenEndpointResponse` | The same without the helper method |
 | `OidcGrantChecks` | `AuthorizationCodeGrantChecks` | `{ pkceCodeVerifier?: string; idTokenExpected?: boolean }` |
 | `OidcServerMetadata` | `ServerMetadata` | Issuer and endpoint metadata |
-| `OidcIntrospectionResponse` | `IntrospectionResponse` | Active, scope, sub, client_id |
+| `OidcIntrospectionResponse` | `IntrospectionResponse` | `active`, `scope`, `sub`, `client_id`, … |
 | `OidcClientDescriptor` | `Configuration` (opaque) | Pass-through; consumers must never read its internals |
 
-Upstream `openid-client` types are imported **only** in `src/service.ts`; mappings happen at the method boundaries. This keeps future library swaps confined to that one file.
+What the owned names guarantee is the **exported** surface, not the internal imports. The type module
+imports `Configuration`, `ServerMetadata`, `TokenEndpointResponse` and `TokenEndpointResponseHelpers`
+from `openid-client` in order to alias them under those names; the service module imports the
+functional `openid-client` API; and `jose`'s `decodeJwt` is read directly by the token wrapper, the
+`oidc-client` auth plugin and the exchange handler. A library swap touches every one of those
+modules — what the owned names buy is that it stops there and never reaches a consumer. See
+[[oidc-versions]].
+
+## Rules
+
+- An application that uses an identity provider **only to log in**, and then maps the subject onto a
+  local identity through `@owlmeans/server-auth-identity`, must not adopt `appendOidcGuard()` or
+  `makeOidcGate()` as its authorization mechanism. Those decide against the
+  provider's grants; a product that owns its own identity records declares its own `GateService` over
+  them.
+- The browser starts the flow and the server finishes it: the exchange, the account linking and the
+  bearer token an application actually carries are all produced here.
+- Register the wrapping service whenever the guard is registered — an OIDC-wrapped token that nothing
+  refreshes expires mid-session.
 
 ## Depends On
 
-- `@owlmeans/oidc`, `@owlmeans/server-auth`, `@owlmeans/server-context`, `@owlmeans/server-entrypoint`
-- `@owlmeans/auth-common`, `@owlmeans/basic-keys`
-- `openid-client@6.8.4` (exact), `jose@6.2.3` (exact) — see [[oidc-versions]]
+- `@owlmeans/oidc`, `@owlmeans/server-auth`, `@owlmeans/server-context`, `@owlmeans/server-entrypoint`,
+  `@owlmeans/server-api`, `@owlmeans/auth`, `@owlmeans/auth-common`, `@owlmeans/basic-envelope`,
+  `@owlmeans/client-entrypoint`, `@owlmeans/config`, `@owlmeans/context`, `@owlmeans/did`,
+  `@owlmeans/entrypoint`, `@owlmeans/resource`, `@owlmeans/route`, `@noble/hashes`, `@scure/base`,
+  `dayjs`
+- `ajv` (peer)
+- `openid-client@6.8.4` (exact), `jose@6.2.5` (exact) — see [[oidc-versions]]

package/build/actions/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/actions/init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AAkBzE,eAAO,MAAM,IAAI,EAAE,sBA0FjB,CAAA"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/actions/init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AAoBzE,eAAO,MAAM,IAAI,EAAE,sBAiGjB,CAAA"}

package/build/actions/init.js

@@ -1,6 +1,7 @@
 import { handleBody } from '@owlmeans/server-api';
 import { AuthenPayloadError, AuthUnknown, DISPATCHER } from '@owlmeans/auth';
 import { assertContext } from '@owlmeans/context';
+import { makeSecurityHelper } from '@owlmeans/config';
 import { authService, DEFAULT_ALIAS } from '../consts.js';
 // import {  PROVIDER_CACHE_TTL } from '../consts.js'
 // import type { Client } from 'openid-client'
@@ -35,7 +36,7 @@ export const init = handleBody(async (body, ctx) => {
          * @TODO We need to move it to some remote resource.
          * And make oidc service itself use such a resource to get required client.
          */
-        const [providers] = await context.entrypoint(authService.provider.list).call({
+        const providers = await context.entrypoint(authService.provider.list).call({
             params: { service: context.cfg.alias ?? context.cfg.service },
             query: { entityId }
         });
@@ -72,7 +73,14 @@ export const init = handleBody(async (body, ctx) => {
         client: client.getClientId(),
         ...(entityIdUsedForResolution ? { entityId } : {}),
     }, { ttl: AUTHEN_TIMEFRAME / 1000 });
-    const [dispatcherUrl] = await context.entrypoint(DISPATCHER).call();
+    // The dispatcher is a FRONTEND route, and this is a server context — the entrypoint registered
+    // here has no `url()` (that helper is attached by `@owlmeans/client-entrypoint` only, for a
+    // browser context that can resolve its own address). Assembled the way `server-oidc-provider`'s
+    // interaction URL is: the entrypoint's path, qualified with the address it answers on — the
+    // frontend service's, not this backend's.
+    const dispatcherEntry = context.entrypoint(DISPATCHER);
+    const dispatcherUrl = makeSecurityHelper(context)
+        .makeUrl(dispatcherEntry.address(), dispatcherEntry.path());
     const cfg = client.getConfig();
     const url = client.makeAuthUrl({
         scope: requestedScope(cfg?.extraScopes),