@seamless-auth/oidc-provider 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# @seamless-auth/oidc-provider
+
+## 0.1.0
+
+### Minor Changes
+
+- 793a30c: Refresh tokens, authorization codes and device codes are now single use under concurrency too. The API's consume answers whether this request marked the record used (`@seamless-auth/types` 0.34.0). A request that loses gets `invalid_grant`. A lost refresh is handled as refresh token reuse, which ends the first-party session, and a lost code revokes its grant, as a sequential reuse does. A token request whose session ended while it ran now gets `invalid_grant` instead of a server error.
+- dcf17cc: Sign users in to OIDC apps with the authorization code flow and PKCE, discovery and userinfo. Interactions finish only after a first-party sign-in through this service's own adapter, through four JSON routes the hosted pages call: `GET /interaction/:uid/details`, and `POST /interaction/:uid/login`, `/consent` and `/abort`. The provider grant is saved against the first-party session before its auth context is read, and every stored record and signature names that session, so the API's grant binding holds. ID tokens carry the scope claims plus `acr`, `amr` and `auth_time` from the API.
+  
+  - A recovery session cannot finish a sign-in, and `prompt=login` or `max_age` refuse a session older than the request.
+  - First-party clients have consent implied. Third-party clients do not exist while `third_party_clients_enabled` is off, and see the consent page on every authorization when it is on.
+  - The interaction routes refuse a state change unless `Sec-Fetch-Site` is `same-origin` or the `Origin` is the issuer's, so a sibling subdomain cannot drive them.
+  
+  Needs fells-code/seamless-auth-api#524 for a session signed in to more than one app.
+- 1697942: Client authentication per ADR D6. Confidential clients use `private_key_jwt` by default, and each assertion is single-use through the API's replay store (a replay is `invalid_client`, not a 500). Public clients use `none` with PKCE. `client_secret_basic` and `client_secret_post` are offered only when the API allows client secrets (`allow_client_secrets`, read at startup), and only work for clients opted in on the API.
+  
+  A presented secret is checked with `POST /oidc/clients/:id/verify-secret` before the library runs. When the API accepts it, the request carries a one-time value in its place, and the client's metadata carries that value for that request only, so this service never holds a client's real secret. `client_secret_jwt` and HS* algorithms are never offered.
+- 2532a7c: `pkce.required` is now per client. PKCE stays required unless the API sends `urn:seamless:pkce_required: false` for a confidential client (`@seamless-auth/types` 0.34.0), as RFC 9700 section 2.1.1 allows. Such a client must send `nonce` on any code request without PKCE that asks for an ID token, or gets `invalid_request`, unless the API also sends `urn:seamless:nonce_required: false`. A code request without `openid` still needs PKCE, since a nonce only binds an ID token. An opt-out on a public client is ignored, so PKCE stays required for it.
+- d3b779e: Apply each application's `accessTokenTtlSeconds`, `idTokenTtlSeconds` and `refreshTokenTtlSeconds`, which the API now sends as `urn:seamless:access_token_ttl`, `urn:seamless:id_token_ttl` and `urn:seamless:refresh_token_ttl` client metadata (`@seamless-auth/types` 0.34.0). An access token for a resource takes the shorter of the resource's and the application's lifetime. Unset values keep the defaults (600 seconds for access and ID tokens, 14 days for refresh tokens), and `ttl.RefreshToken` is now set explicitly, keeping the library's rule that a public browser app's rotated token never outlives the one it replaced.
+- 4c74314: The device authorization grant (RFC 8628) for first-party clients with the device flow turned on: `/device/auth` returns an 8-character base-20 user code (about 34.5 bits) that lives 10 minutes and an `interval` of 5 seconds, and `/device` is the verification page in the hosted UI. The page names the app and warns, before any sign-in, to continue only on a device you started yourself. Every approval signs in again, even in a browser that is already signed in. Polling sooner than the interval gets `slow_down` and a longer interval, per device code. Code entry is limited to 10 a minute per address and 600 a minute per instance. Device-flow tokens never carry `acr`, including after a refresh, and `acr_values` and `max_age` are refused on device requests (ADR D10). Sign requests now name the grant (`grantType`), which needs `@seamless-auth/types` 0.34.0 and the API with edge contract version 2.
+- 4d9492a: Hosted login and consent pages. A SPA on `@seamless-auth/react`, served by this service at `/interaction/:uid` and the bundled sign-in paths (`/login`, `/verify-email-otp`, `/register-passkey` and the rest), signs users in through this service's own first-party adapter, so every enabled method and every first-party protection applies. It finishes the interaction once the user is signed in, sends a recovery session to enrollment, and has the user sign in again when the app asks for `prompt=login` or `max_age`.
+  
+  - Third-party clients get a consent page naming the client, the host it sends you back to, and what it asks for.
+  - Branding is read from the API's config when a page is served (`app_name` today), with no build step. A config change shows within 30 seconds.
+  - Every page gets a strict CSP: scripts from this origin only, styles from this origin or carrying the response's nonce, `frame-ancestors 'none'`, plus `no-store`, `nosniff` and `no-referrer`.
+  - The adapter routes under `/auth` now need `Sec-Fetch-Site: same-origin` or the issuer's `Origin` for a state change, like the interaction routes.
+  - The resume cookie is now `__Host-oidc_resume` with `Path=/`, and resuming an authorization other than the one it names is refused.
+  - The package ships the built pages in `dist/ui`. `createOidcEdge` takes `uiDir` to serve another build.
+- a167b9d: The hosted pages take their branding from the API's `hosted_ui` system config, read from `GET /oidc/config` on each page load like `app_name`. `appName` overrides the name, `logoUrl` shows a logo (its origin is added to the page's `img-src`), `colors` and `fontFamily` become CSS variables in a `<style>` carrying the response's nonce. A branded palette replaces the dark palette, since it was chosen against a light page. The bundled sign-in screens now take their accent, text, surface and border colors from the same variables, so branding reaches every screen. Needs `@seamless-auth/types` with `hostedUi` on the config response.
+- a6de395: Token introspection (RFC 7662) and revocation (RFC 7009) at `/token/introspection` and `/token/revocation`, listed in discovery.
+  
+  - A client may introspect its own tokens. A resource server, registered as a confidential application linked to its resource, may introspect tokens whose `aud` is that resource. Every answer comes from the API's store, so a token whose session has ended is inactive at once.
+  - JWT access tokens are now stored under their `jti` when issued, so they can be introspected and revoked. A presented JWT is mapped back to its record only after its signature checks out against the provider's keys, and the `jti` alone is not accepted as a token.
+  - Revoking a refresh token ends that app's grant and its tokens, not the user's first-party session. Each revocation is recorded in the API's audit log as `token_revoked`.
+  - Both endpoints are limited to 1200 requests a minute per client IP, per instance.
+- a81ad61: First release of the Seamless Auth OpenID Provider service, on `oidc-provider` 9.13 and `@seamless-auth/express`. It stores every provider model through the API's `/oidc/payloads/*` routes, reads clients from the API's registry, and signs every token through `POST /oidc/sign`, so it holds no private key and no database. The configuration is locked to the code flow with PKCE for every client, refresh rotation, no dev interactions and no dynamic registration. At startup it checks `GET /oidc/config` and refuses to run when the API has the provider disabled or speaks a different `/oidc/*` contract version. It answers only requests for the issuer's own origin. Ships as a Docker image and as an npm package that exports `createOidcEdge` for mounting into an Express app.
+  
+  Requires a Seamless Auth API with the v0.21 `/oidc/*` routes and `@seamless-auth/types` 0.34.0.
+- 45ea34c: Refresh token reuse detection and the client credentials grant.
+  
+  - A rotated refresh token presented again still revokes the grant, and now also asks the API to end the first-party session it was issued under (`POST /oidc/sessions/:id/revoke`, reason `refresh_token_reuse`).
+  - A refresh reads the session's auth context, so the refreshed ID token carries the current `acr`, `amr` and `auth_time`. Before this, any step-up after sign-in made `/oidc/sign` refuse every later refresh.
+  - `client_credentials` is on for clients registered for it. The token is an RFC 9068 JWT for a resource (the one named with `resource`, or the client's only linked one, else `invalid_target`), with `sub` and `client_id` set to the client and scopes cut to what it is allowed there.
+- 30b4115: Issue access tokens for a named API. With `resource=<identifier>` (RFC 8707) the access token is an RFC 9068 JWT (`typ: at+jwt`) whose `aud` is the resource, carrying only the scopes the application is allowed there and the resource's own lifetime, read from the API's `GET /oidc/clients/:id/resources`. A resource the application is not linked to is refused with `invalid_target`. A resource named once at authorization is used at the token endpoint too. Without `resource`, the access token is the same opaque userinfo token as before. First-party apps have resource scopes granted with the sign-in. The consent page lists them for third-party apps.
+  
+  Needs fells-code/seamless-auth-api#533 and `@seamless-auth/types` with `OidcEdgeRoutes.clientResources`.
+- b31200c: RP-initiated logout at `/session/end`, confirmed on a hosted page. Signing out ends the provider session and the first-party session behind it through the API, which sends OpenID Back-Channel Logout tokens to every app the user signed in to with it. Signing out of the asking app only ends that app's grant. Discovery now lists `end_session_endpoint`, `backchannel_logout_supported` and `backchannel_logout_session_supported`, and ID tokens carry `sid` for clients registered for back-channel logout. Needs the API with back-channel logout (fells-code/seamless-auth-api#409).
+- b3048a8: Honour `acr_values`, `max_age` and `prompt=login` from the API's auth context, with step-up in the hosted pages.
+  
+  - Every authorization from an existing provider session reads `GET /oidc/sessions/:id/auth-context` and carries the reported `acr`, `amr` and `auth_time` into the tokens, so a step-up made elsewhere shows up on the next authorization and `/oidc/sign` never sees a stale value. A session the API reports as ended or in recovery goes back to sign-in.
+  - `acr_values` is met when the session's acr ranks at least the weakest value asked for (`phrh` satisfies `phr`). `max_age` is met by the API's `auth_time`, or an authentication during the request.
+  - `POST /interaction/:uid/login` answers `409 { error: 'step_up_required', methods }` instead of `reauthentication_required`. The pages run the step-up through the adapter (`/step-up/webauthn/*`, or `/totp/verify-mfa` for freshness on a session with no acr), then post again with `{ "afterStepUp": true }`. If the requirement is still not met, the client receives `unmet_authentication_requirements`.
+  
+  Needs fells-code/seamless-auth-api#529.
+
+### Patch Changes
+
+- 1397fcd: Document how the provider meets OAuth 2.1 and RFC 9700 in `docs/oauth-security.md`, with the test behind each row, and cover RFC 8252 native clients (loopback redirects on any port, the IPv6 loopback, private-use schemes, and refusal of any other host, path or scheme). No behaviour change.
+- dfd86f2: Depend on `@seamless-auth/types` `^0.34.0`, the stable release, instead of the 0.34.0 prerelease.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,274 @@
-# Temporary Holding Version
+# Seamless Auth OpenID Provider
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The OpenID Provider for [Seamless Auth](https://seamlessauth.com). Any app that speaks OpenID
+Connect (Grafana, GitLab, Argo CD, Auth.js and the rest) can sign users in with Seamless Auth
+through this service, with no Seamless SDK.
+
+It is the public "login edge" in front of a private Seamless Auth API:
+
+```
+any OIDC app ──► seamless-auth-oidc-provider (public: OIDC endpoints, hosted pages, cookies)
+                      │   service token, like any adapter
+                      ▼
+               Seamless Auth API (private, no cookies) ── Postgres
+```
+
+- Built on [`oidc-provider`](https://github.com/panva/node-oidc-provider) 9.x.
+- Holds no private keys and no database. The API signs every token after checking its claims,
+  and stores all provider state.
+- Code flow with PKCE (a confidential client can be opted out, and then sends `nonce` unless that is waived too), refresh rotation always on, `private_key_jwt` for confidential
+  clients, and shared secrets only for clients opted in on the API.
+
+The design is in
+[ADR 0001](https://github.com/fells-code/seamless-auth-api/blob/main/docs/adr/0001-openid-provider.md).
+
+> **Status:** under construction for Seamless Auth v0.21. Discovery, the authorization code
+> flow with PKCE, userinfo and the hosted login and consent pages work. The remaining grants
+> land in the open [issues](https://github.com/fells-code/seamless-auth-oidc-provider/issues).
+
+## Requirements
+
+- Node 22 or newer.
+- A Seamless Auth API with the provider enabled (`oidc_provider_enabled`), `oidc_issuer` set
+  to this service's public URL, and the provider signing keys (`OIDC_JWKS_*`) configured.
+- This service's hostname must be the API's `rpid` or a subdomain of it, so passkeys work on the
+  hosted pages.
+- HTTPS. Provider cookies are `__Host-` cookies, which browsers only accept over TLS.
+
+## Run the image
+
+```bash
+docker run -p 5314:5314 --env-file .env ghcr.io/fells-code/seamless-auth-oidc-provider:latest
+```
+
+## Configuration
+
+| Variable                      | Required | Description                                                                                                                                                                                            |
+| ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `SEAMLESS_API_URL`            | yes      | The private API, as this service reaches it.                                                                                                                                                           |
+| `SEAMLESS_API_ISSUER`         | no       | The API's `ISSUER`, when it differs from `SEAMLESS_API_URL`.                                                                                                                                           |
+| `SEAMLESS_OIDC_SERVICE_TOKEN` | yes      | This service's own service token secret, `SEAMLESS_OIDC_SERVICE_TOKEN` on the API. It must differ from the adapters' `SEAMLESS_SERVICE_TOKEN`, which this service never holds. At least 32 characters. |
+| `SEAMLESS_JWKS_KID`           | no       | The `kid` on the service tokens this service signs.                                                                                                                                                    |
+| `SEAMLESS_COOKIE_SECRET`      | yes      | Signs the first-party session cookies. At least 32 characters.                                                                                                                                         |
+| `OIDC_COOKIE_KEYS`            | yes      | Comma-separated provider cookie keys. The first signs, the rest verify.                                                                                                                                |
+| `TRUST_PROXY`                 | no       | `true` when TLS ends at a proxy in front of this service.                                                                                                                                              |
+| `PORT`                        | no       | Defaults to `5314`.                                                                                                                                                                                    |
+
+The issuer comes from the API (`oidc_issuer`), not from this service's environment. The service
+answers only requests for the issuer's own scheme and host, and refuses to start when the API
+has the provider disabled or speaks a different version of the `/oidc/*` contract.
+
+## Endpoints
+
+| Path                                | What                                              |
+| ----------------------------------- | ------------------------------------------------- |
+| `/.well-known/openid-configuration` | Discovery                                         |
+| `/authorize`, `/token`, `/userinfo` | Authorization code with PKCE, and userinfo        |
+| `/jwks`                             | The provider's public keys, read from the API     |
+| `/auth/*`                           | This service's first-party adapter, for the pages |
+| `GET /interaction/:uid/details`     | What the current interaction needs, for the pages |
+| `POST /interaction/:uid/login`      | Finishes login, or answers `step_up_required`     |
+| `POST /interaction/:uid/consent`    | Grants what the client asked for                  |
+| `POST /interaction/:uid/abort`      | Returns `access_denied` to the client             |
+| `/session/end`                      | RP-initiated logout, confirmed on a hosted page   |
+| `/device/auth`, `/device`           | Device authorization grant and its hosted page    |
+
+The interaction routes are for the hosted pages only. A state change needs `Sec-Fetch-Site:
+same-origin` or an `Origin` equal to the issuer's, so a page on a sibling subdomain cannot
+drive them.
+
+## Step-up (`acr_values`, `max_age`, `prompt=login`)
+
+Discovery lists `acr_values_supported: ["phr", "phrh"]`. `phrh` (a device-bound passkey with
+user verification) satisfies a request for `phr`. On every authorization from an existing
+session this service reads the session's auth context from the API and decides from what the
+API reports, never from its own copy:
+
+- `acr_values` is met when the session's acr ranks at least the weakest value asked for.
+- `max_age` is met when the API's `auth_time` is within it, or the user authenticated during
+  this request. `prompt=login` needs the latter.
+
+When either falls short, the hosted pages ask the user to confirm it is them on the same
+session: a passkey, or an authenticator app code when only freshness is missing on a session
+with no acr (an app code never earns an acr). The pages then read the context again and copy
+`acr`, `amr` and `auth_time` into the tokens unchanged. If the step-up still falls short, for
+example a synced passkey when `phrh` was asked for, the app gets
+`unmet_authentication_requirements` rather than a token with a lower acr.
+
+## Access tokens for an API (`resource`)
+
+An app that calls an API of its own asks for a token for it with `resource=<identifier>`
+(RFC 8707), using an identifier the API's registry lists under `/admin/resources` and links to
+the application under `/admin/applications/:id/resources`. The access token is then an RFC
+9068 JWT (`typ: at+jwt`) whose `aud` is that identifier, carrying `client_id`, `sub`, `scope`
+and `jti`, with only the scopes the application is allowed there and the resource's own
+lifetime. The API checks the same links again before it signs, so an API configured for one
+identifier can reject every token minted for another.
+
+- A resource the application is not linked to is refused with `invalid_target`.
+- An app that named one resource at authorization gets its token without repeating
+  `resource` at the token endpoint.
+- Without `resource` the access token stays an opaque one for `/userinfo`, as before. A token
+  for a resource is not accepted at `/userinfo`.
+- First-party apps have the scopes granted with the sign-in. Third-party apps list them on the
+  consent page.
+
+## Token lifetimes
+
+An application's own `accessTokenTtlSeconds`, `idTokenTtlSeconds` and `refreshTokenTtlSeconds`
+(admin routes) apply to its tokens. Unset ones use the defaults: 600 seconds for access and ID
+tokens, 14 days for refresh tokens. An access token for a resource with its own lifetime gets
+the shorter of the two. A rotated refresh token for a browser app that cannot bind it to a key
+keeps what was left of the one it replaced, whatever the application's lifetime. The grant
+behind them lives at least as long as the application's refresh tokens. The API also
+ends every record when the first-party session behind it ends.
+
+## Refresh tokens and client credentials
+
+- **Refresh.** A client registered for `refresh_token` gets one with `offline_access`, which
+  the library honours only on a request with `prompt=consent` (OpenID Connect Core 11). Refresh
+  tokens rotate on every use. A used one presented again revokes the grant and every token
+  under it, and the API ends the first-party session it was issued under. Two refreshes
+  racing with the same token cannot both rotate: the API's consume says which one marked it
+  used, and the other is handled as that same reuse. A refreshed ID
+  token carries the session's current `acr`, `amr` and `auth_time`, so a step-up since the
+  sign-in shows up on the next refresh.
+- **Client credentials.** A confidential client registered for `client_credentials` gets an
+  RFC 9068 JWT whose `sub` and `client_id` are the client itself, only ever for a resource:
+  the one named with `resource`, or the client's only linked resource. Scopes are cut to what
+  the client is allowed there. An application with account notices turned on also gets the
+  built-in `<issuer>/seamless` resource with `notices:send`, which the API lists for it, for
+  `POST /applications/account-notices` on the API.
+
+## Introspection and revocation
+
+`/token/introspection` (RFC 7662) and `/token/revocation` (RFC 7009) are listed in discovery
+and take the same client authentication as `/token`.
+
+- **Introspection.** A client may introspect its own tokens. A resource server registers as a
+  confidential application linked to its resource, and may then introspect tokens whose `aud`
+  is that resource. Any other caller gets `{ "active": false }`. Every answer is read from the
+  API's store, so a token whose first-party session has ended is inactive at once.
+- **JWT access tokens.** The library keeps no record of a JWT, so this service stores one
+  under its `jti` when it is issued and maps a presented JWT back to it, after checking the
+  signature against the provider's own keys. The `jti` alone is never accepted as a token.
+  A resource server that verifies JWTs locally still accepts one until it expires; one that
+  introspects sees revocation immediately.
+- **Revocation.** A client revokes its own refresh or access token. Revoking a refresh token
+  ends the grant and every token under it, not the user's first-party session, so the user's
+  other apps stay signed in. Each revocation is recorded in the API's audit log
+  (`token_revoked`).
+- **Rate limit.** 1200 requests a minute per client IP across both endpoints, per instance.
+
+## Logout
+
+`/session/end` (OpenID RP-Initiated Logout 1.0) takes `id_token_hint` or `client_id`, and a
+`post_logout_redirect_uri` registered for the client. The hosted page asks before anything
+ends:
+
+- **Sign out** ends the provider session and the first-party session it was made under
+  (through the API's `/oidc/sessions/:id/revoke`, reason `provider_logout`), and clears the
+  adapter cookies. Every other app the user signed in to with it is signed out too.
+- **Only sign out of** the asking app ends that app's grant and keeps the session.
+
+Back-channel logout (OpenID Back-Channel Logout 1.0) is sent by the API, not by this service.
+The API holds the keys and sees every way a session ends (this logout, admin revoke, sign-out
+everywhere, eviction), so a client with a `backchannelLogoutUri` gets a `logout+jwt` token
+whichever one it was. Discovery lists `backchannel_logout_supported` and
+`backchannel_logout_session_supported`, and ID tokens for such a client carry `sid`.
+
+## Device authorization grant
+
+`/device/auth` (RFC 8628) is for apps that cannot open a browser: TVs, consoles, CLIs. It is
+off unless an admin enables the device flow on a first-party application (ADR D10).
+
+- **Codes.** User codes are 8 characters from the RFC's base-20 set (`BCDF-GHJK`), about 34.5
+  bits, typed case-insensitively and with or without the dash. They live 10 minutes. The
+  device code works once.
+- **Polling.** The response carries `interval: 5`. A poll sooner than that gets `slow_down`
+  and five more seconds, tracked per device code on each instance.
+- **Approval.** `/device` is a hosted page. Before any sign-in, the confirmation page names the
+  app, shows the code, and says to continue only on a device you started yourself (RFC 8628
+  section 5.4). Every approval signs in again, so a browser that is already signed in still
+  confirms with the passkey. Code entry is limited to 10 a minute per address and 600 a
+  minute per instance.
+- **Assurance.** Device-flow tokens never carry `acr`, after a refresh too, and device requests
+  with `acr_values` or `max_age` are refused. The passkey proves who approved, not who holds
+  the device. The API refuses `acr` on any token whose sign request names the device grant.
+
+## Security defaults
+
+The configuration is locked to OAuth 2.1 and RFC 9700: the code flow with `S256` PKCE for
+every client (unless an admin opts a confidential client out, RFC 9700 section 2.1.1, in
+which case it must send `nonce` whenever it asks for an ID token, unless an admin waives
+that as well), exact redirect matching (with RFC 8252 loopback ports for native apps), refresh
+rotation, `iss` on authorization responses and audience-restricted access tokens. The full
+matrix, with the test behind each row, is in [docs/oauth-security.md](docs/oauth-security.md).
+
+## Client authentication
+
+| Client                                    | Authentication                                |
+| ----------------------------------------- | --------------------------------------------- |
+| Confidential (server-side apps, services) | `private_key_jwt`, each assertion used once   |
+| Public (SPA, native, CLI)                 | `none`, with PKCE                             |
+| Confidential, opted in to a shared secret | `client_secret_basic` or `client_secret_post` |
+
+Shared secrets are for apps that support nothing else. They need `allow_client_secrets` on
+the API (read when this service starts) and a per-client opt-in there. This service never
+holds a client's secret: it asks the API to check a presented one, then hands the library a
+one-time stand-in for that request. `client_secret_jwt` and HS\* algorithms are never offered.
+
+## Hosted pages
+
+The login and consent pages are a SPA in `ui/`, built on `@seamless-auth/react` and shipped
+in `dist/ui`. They sign users in through this service's own adapter routes (`/auth/*`), the
+same way any Seamless app does, then finish the OIDC interaction.
+
+- **Methods.** Every method the API has enabled in `login_methods`, through the SDK's bundled
+  screens. A recovery session goes to enrollment before it can finish a sign-in.
+- **Consent.** First-party clients have consent implied. Third-party clients see the client
+  name, the host they are sent back to and the requested scopes, on every authorization.
+- **Branding.** The app name comes from the API's config each time a page is served, so a
+  config change needs no build and no restart.
+- **Headers.** A strict CSP (`script-src 'self'`, styles from this origin or with the
+  response's nonce, `frame-ancestors 'none'`), `no-store`, `nosniff` and `no-referrer`.
+
+Every cookie this service sets is `__Host-` (host-only, `Secure`, `Path=/`), so serve it over
+HTTPS, including in development: the library refuses to set a `Secure` cookie on a plain
+HTTP request.
+
+## Embed in an Express app
+
+```ts
+import express from 'express';
+import { createOidcEdge } from '@seamless-auth/oidc-provider';
+
+const edge = await createOidcEdge({
+  apiUrl: process.env.SEAMLESS_API_URL!,
+  serviceSecret: process.env.SEAMLESS_OIDC_SERVICE_TOKEN!,
+  cookieKeys: process.env.OIDC_COOKIE_KEYS!.split(','),
+  adapterCookieSecret: process.env.SEAMLESS_COOKIE_SECRET!,
+  trustProxy: true,
+});
+
+const app = express();
+app.set('trust proxy', 1);
+app.use(edge.router);
+app.listen(5314);
+```
+
+Mount `edge.router` at the root of the app that serves the issuer's origin.
+
+## Development
+
+```bash
+nvm use
+npm ci
+npm run typecheck && npm run lint && npm run format:check && npm run coverage && npm run build
+```
+
+See [AGENTS.md](AGENTS.md) for the repo's standards and [RELEASES.md](RELEASES.md) for releases.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

package/dist/adapter.d.ts

@@ -0,0 +1,44 @@
+import type { Adapter, AdapterFactory, AdapterPayload } from 'oidc-provider';
+import { errors } from 'oidc-provider';
+import type { OidcApiClient } from './apiClient.js';
+import type { EdgeConfigCache } from './configCache.js';
+import { DevicePollThrottle } from './deviceFlow.js';
+/** A client assertion or proof presented twice. Answered as `invalid_client`, not a 500. */
+export declare class ReplayDetectedError extends errors.InvalidClientAuth {
+    constructor();
+}
+export declare class UnsupportedModelError extends Error {
+    constructor(name: string, operation: string);
+}
+/** Stores one library model through the API's `/oidc/payloads/*` routes. */
+export declare class ApiPayloadAdapter implements Adapter {
+    #private;
+    constructor(name: string, client: OidcApiClient, polls?: DevicePollThrottle);
+    upsert(id: string, payload: AdapterPayload, expiresIn?: number): Promise<void>;
+    find(id: string): Promise<AdapterPayload | undefined>;
+    findByUserCode(userCode: string): Promise<AdapterPayload | undefined>;
+    findByUid(uid: string): Promise<AdapterPayload | undefined>;
+    consume(id: string): Promise<void>;
+    destroy(id: string): Promise<void>;
+    revokeByGrantId(grantId: string): Promise<void>;
+}
+/**
+ * Reads clients from the API's registry. Clients are managed there, never here. A third-party
+ * client does not exist while `third_party_clients_enabled` is off (ADR D10).
+ *
+ * The registry never returns a secret. A client on a shared-secret method gets the one-time
+ * value `verifyClientSecrets` set for a secret the API accepted on this request, and otherwise
+ * a random value nothing can present, which the library needs to load the client at all.
+ */
+export declare class ApiClientAdapter implements Adapter {
+    #private;
+    constructor(client: OidcApiClient, config: EdgeConfigCache);
+    find(id: string): Promise<AdapterPayload | undefined>;
+    upsert(): Promise<void>;
+    findByUserCode(): Promise<undefined>;
+    findByUid(): Promise<undefined>;
+    consume(): Promise<void>;
+    destroy(): Promise<void>;
+    revokeByGrantId(): Promise<void>;
+}
+export declare function createApiAdapterFactory(client: OidcApiClient, config: EdgeConfigCache): AdapterFactory;