@hyper.authio/bff 0.0.0-stage → 0.8.0

package/README.md

@@ -1,3 +1,264 @@
-# Temporary Holding Version
+# @hyper.authio/bff
 
-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.
+A **Backend-for-Frontend** for [Authio](https://github.com/LeonardoFerreira1209/authio-node) on Express 4 and 5. It
+lets a browser SPA (React, Angular, Vue, plain JavaScript…) sign in with Authio **without ever holding a token**,
+following the BFF pattern of the IETF draft *OAuth 2.0 for Browser-Based Applications*. The Node counterpart of
+`Authio.AspNetCore.Bff`: same endpoints, same cookie, same anti-forgery header, same option names. Built on
+[`@hyper.authio/client`](../client/README.md).
+
+```bash
+npm install @hyper.authio/bff
+```
+
+## Why a BFF
+
+Tokens kept in the browser (local storage, session storage, memory) can be stolen by any script that runs on the page,
+and refresh tokens outlive the page. With a BFF:
+
+- the SPA and the BFF share an origin; the browser only holds an `HttpOnly`, `Secure`, `SameSite=Lax`, host-only
+  cookie (`__Host-authio`) that carries a signed random session id and nothing else;
+- the BFF is a **confidential client**: it runs the authorization code flow with PKCE, keeps the access, refresh and
+  ID tokens **server-side** (encrypted in the session store), refreshes them, and attaches the access token when it
+  calls APIs on the person's behalf;
+- every API call from the SPA carries a custom header (`X-CSRF: 1`), which a cross-site page cannot add without a CORS
+  preflight, so the cookie cannot be abused by CSRF.
+
+## Register the client at Authio
+
+- **Type**: confidential, with a secret (`client_secret_basic` by default, or `tokenEndpointAuthMethod:
+  "client_secret_post"`), or with `private_key_jwt` (`clientPrivateKey` or `clientPrivateKeyPath`, and
+  `clientKeyId`).
+- **PKCE**: required with S256 is the recommended setting, mirrored by `checks: ["pkce", "state", "nonce"]` and
+  `codeChallengeMethod: "S256"`. The BFF checks only what `checks` lists: left out, it checks nothing.
+- **Redirect URI**: `https://<your-app>/signin-oidc` (`callbackPath`).
+- **Post-logout redirect URI**: `https://<your-app>/signout-callback-oidc` (`signedOutCallbackPath`).
+- **Back-channel logout URI**: `https://<your-app>/bff/backchannel-logout`.
+- **Front-channel logout URI** (optional, with `frontChannelLogout: true`): `https://<your-app>/bff/frontchannel-logout`,
+  with the session required so Authio sends `iss` and `sid`.
+- **Scopes**: `openid profile email offline_access` (`offline_access` gives the refresh token), plus `roles` if you set
+  `requestRoles`, plus your API scopes.
+- **Resources** (optional): the API resource identifiers you ask for with `resource` or use with remote APIs; allow
+  the **token exchange** grant if a remote API needs a token for a specific resource or a narrower scope set.
+
+## Setup
+
+```ts
+import express from "express";
+import { authioBff } from "@hyper.authio/bff";
+
+const app = express();
+
+const bff = authioBff({
+  authority: "https://auth.example.com",
+  realm: "acme",
+  clientId: "acme-web",
+  clientSecret: () => process.env.AUTHIO_CLIENT_SECRET!, // read on every call: a rotated secret needs no restart
+  checks: ["pkce", "state", "nonce"], // the client requires PKCE with S256: mirror it, nothing is checked by default
+  codeChallengeMethod: "S256",
+  cookieSecret: process.env.BFF_COOKIE_SECRET!, // 32+ characters; an array rotates them
+  requestRoles: true,
+  resource: "https://orders.example.com", // the session's token is addressed to the orders API
+});
+
+app.use(bff); // /bff/login, /bff/logout, /bff/user, /bff/silent-login, /bff/backchannel-logout, /bff/frontchannel-logout, /signin-oidc, /signout-callback-oidc
+
+// Remote APIs: mount them before any body parser, so the body is streamed through.
+app.use("/api/orders", bff.remoteApi("https://orders.example.com"));
+app.use("/api/inventory", bff.remoteApi("https://inventory.example.com", { tokenMode: "clientCredentials", scopes: ["inventory:read"] }));
+app.use("/api/billing", bff.remoteApi("https://billing.example.com", { resource: "https://billing.example.com" }));
+
+app.use(express.json());
+
+// Local APIs: the anti-forgery header and a session are required; req.authioBff holds the session, never a token.
+app.get("/api/me", bff.api(), (req, res) => res.json({ name: req.authioBff!.claims.name }));
+
+app.get("/api/report", bff.api(), async (req, res) => {
+  const reports = bff.userFetch(req, res, { resource: "https://reports.example.com" });
+  const answer = await reports("https://reports.example.com/monthly");
+
+  res.status(answer.status).json(await answer.json());
+});
+
+app.use(express.static("dist")); // the SPA
+
+app.listen(5000);
+```
+
+`app.set("trust proxy", 1)` behind a reverse proxy, so the redirect URIs are built with `https`; or set
+`redirectUri` and `postLogoutRedirectUri` explicitly.
+
+## The SPA side
+
+```js
+const api = (url, init = {}) => fetch(url, { ...init, credentials: "same-origin", headers: { ...init.headers, "X-CSRF": "1" } });
+
+const response = await api("/bff/user");
+
+if (response.status === 401) {
+  window.location.href = "/bff/login?returnUrl=" + encodeURIComponent(location.pathname);
+} else {
+  const claims = await response.json();
+  const logoutUrl = claims.find((claim) => claim.type === "bff:logout_url").value;
+}
+```
+
+| Endpoint | Behaviour |
+| --- | --- |
+| `GET /bff/login` | Starts the sign-in. `returnUrl` (local only, else `400`), `organization`, `prompt` (`none`, `login`, `select_account`, `consent`), `login_hint`, `ui_locales`, `max_age`, `resource` (must be `resource` or one of `allowedResources`, else `400 invalid_target`). A failure comes back as `returnUrl?error=<code>` (`access_denied`, `login_required`, `login_failed`…). |
+| `GET /signin-oidc` | The callback: finds the sealed sign-in cookie (by `state` with the `state` check), checks the RFC 9207 `iss` and the configured `checks`, redeems the code (with the PKCE verifier with `pkce`), validates the ID token (`nonce` with `nonce`, `at_hash`), reads the access token's claims once its signature verifies, creates the session and replaces any previous one. |
+| `GET /bff/user` | With `X-CSRF: 1`: `[{ "type", "value" }]` — the session's claims (strings, one entry per array element), one `role` per Authio role and one `permission` (`resource:method`) per grant from the `*_resource_access` claims, `bff:session_expires_in` (seconds) and `bff:logout_url`. `401` without the header (`antiforgery_required`) or without a session (`unauthorized`), never a redirect. |
+| `GET\|POST /bff/logout` | With the session's `sid` (from `bff:logout_url`) or `X-CSRF: 1`, optionally `returnUrl`: revokes the refresh token, deletes the session, clears the cookie and redirects to Authio's end-session endpoint with `id_token_hint`, `post_logout_redirect_uri` and a sealed `state`; `/signout-callback-oidc` then sends the browser to `returnUrl`. Without `sid` or the header, a signed-in person cannot be logged out by another site (`400`). |
+| `GET /bff/silent-login` | A `prompt=none` sign-in for a hidden iframe; `/bff/silent-login-callback` posts `{ source: "authio-bff-silent-login", isLoggedIn, error }` to the parent window (same origin only). |
+| `POST /bff/backchannel-logout` | Authio's back-channel logout: validates the `logout_token` (`validateLogoutToken`) and deletes every session of that Authio session (`sid`), or of the person (`sub`) when the token names no `sid`. `400 invalid_request` for a missing or invalid token. |
+| `GET /bff/frontchannel-logout` | With `frontChannelLogout: true`, Authio's front-channel logout iframe: checks `iss` (`validateFrontChannelLogout`) and deletes every session of the `sid` it names, or the browser's own session when it names none; answers an empty page. `400 invalid_request` for another issuer or a `sid` without `iss`; `404` when turned off. |
+
+## Calling APIs
+
+**Local APIs**: `bff.api()` answers `401 antiforgery_required` without the header and `401 unauthorized` without a
+session; `bff.api({ optional: true })` lets anonymous calls through, `{ requireAntiForgery: false }` drops the header
+check. `bff.getUserAccessToken(req, res, { resource?, scopes? })` and `bff.userFetch(req, res, …)` hand the person's
+token to your own code.
+
+**Remote APIs**: `bff.remoteApi(destination, options)` forwards everything below its mount path to `destination`,
+strips the browser's cookies, the anti-forgery header and any incoming `Authorization`, attaches the token, drops
+upstream `Set-Cookie`, streams both bodies, and answers `502` when the API cannot be reached.
+
+| `tokenMode` | Token |
+| --- | --- |
+| `user` (default) | The person's access token; anonymous calls get `401`. |
+| `userOrNone` | The person's token when signed in, otherwise none. |
+| `clientCredentials` | A client-credentials token of the BFF (cached by `@hyper.authio/client`), whoever is signed in. |
+| `userOrClientCredentials` | The person's token when signed in, otherwise a client-credentials token. |
+| `none` | No token. |
+
+With `resource` or `scopes`, a user token is obtained by **token exchange** (RFC 8693, the result carries `act`) and
+cached per session, resource and scopes; a client-credentials token is asked for them directly. When a remote API
+answers `401` to a user call, the BFF introspects the session and ends it if Authio says it is gone
+(`validateSessionOnUnauthorized`). `requireAntiForgery: false` is meant for anonymous APIs only.
+
+### Tokens for an API protected by Authio
+
+An API protected with `@hyper.authio/express` or `Authio.AspNetCore` accepts only tokens addressed to it (`aud` = the
+resource identifier in its `audiences`). Either make the session's token the API's with `resource` (or
+`/bff/login?resource=…`, allowed by `allowedResources`), or give the remote API a `resource` so the session's token is
+exchanged for one addressed to it. Keep `offline_access` when you set `resource`: the session check introspects the
+refresh token, which stays addressed to the BFF.
+
+## Tokens and sessions
+
+- **Refresh**: the access token is refreshed `tokenRefreshSkew` (60 s) before it expires, under a lock per session, so
+  concurrent requests share one refresh (Authio rotates refresh tokens and treats a late reuse as a replay). The rotated
+  refresh token is stored before the lock is released. A refused refresh (`invalid_grant`) ends the session; a network
+  error keeps the current token while it lasts. An ID token the refresh returns is validated (signature, `iss`, `aud`,
+  `exp`, `at_hash`, the same `sub`) before it is stored; one that does not validate ends the session.
+- **Claims**: the session's claims are the validated ID token's, plus the claims only the access token carries
+  (`*_resource_access`, `org_id`, `org_alias`, `account_id`) once the access token's signature, `iss` and `exp` verify
+  (`client.readAccessTokenClaims`), plus UserInfo's with `getClaimsFromUserInfoEndpoint`.
+- **Session check** (`sessionValidation: "introspection"`, the default): every `sessionValidationInterval` (300 s) the
+  refresh token (or the access token when there is none) is introspected; an inactive answer ends the session. Needs a
+  confidential client.
+- **Lifetime**: `sessionLifetime` (8 h) without activity; renewed once half of it has passed (`slidingExpiration`).
+  The cookie is a browser-session cookie; the server-side expiry decides.
+- **Cookie**: `__Host-authio=<64 hex>.<HMAC-SHA256>`, `HttpOnly`, `Secure`, `SameSite=Lax` (or `strict`), `Path=/`, no
+  `Domain`. A tampered or unknown cookie is cleared.
+- **Store**: in memory by default. For several instances, implement `AuthioBffSessionStore` over a shared store; the
+  BFF encrypts each session (AES-256-GCM, from `cookieSecret`) before it reaches the store and keeps only `sessionId`
+  (`sid`), `subject` (`sub`) and `expiresAt` in clear, for indexing.
+
+```ts
+import type { AuthioBffSessionStore, AuthioBffStoredSession } from "@hyper.authio/bff";
+
+const redisStore = (redis: Redis): AuthioBffSessionStore => ({
+  async get(key) {
+    const value = await redis.get(key);
+
+    return value ? (JSON.parse(value) as AuthioBffStoredSession) : undefined;
+  },
+  async set(session) {
+    const ttl = Math.max(1, Math.ceil((session.expiresAt - Date.now()) / 1000));
+
+    await redis.multi()
+      .set(session.key, JSON.stringify(session), "EX", ttl)
+      .sadd(`sid:${session.sessionId}`, session.key).expire(`sid:${session.sessionId}`, ttl)
+      .sadd(`sub:${session.subject}`, session.key).expire(`sub:${session.subject}`, ttl)
+      .exec();
+  },
+  async delete(key) {
+    await redis.del(key);
+  },
+  async deleteBySessionId(sessionId) {
+    const keys = await redis.smembers(`sid:${sessionId}`);
+
+    if (keys.length > 0) await redis.del(...keys, `sid:${sessionId}`);
+  },
+  async deleteBySubject(subject) {
+    const keys = await redis.smembers(`sub:${subject}`);
+
+    if (keys.length > 0) await redis.del(...keys, `sub:${subject}`);
+  },
+});
+```
+
+The refresh lock is local to the process, as in .NET: with several instances, keep a person on one instance (sticky
+sessions) or rely on Authio's short refresh-token reuse leeway.
+
+## Options
+
+The client takes the names of [`conformance/options.md`](../../conformance/options.md) (`issuer` or `authority` +
+`realm`, `clientId`, `clientSecret`, `tokenEndpointAuthMethod`, `clientPrivateKey`, `clientKeyId`,
+`clientEncryptionKey`, `encryptionAlgorithms`, `encryptionMethods`, `idTokenSignedResponseAlg`, `tokenRefreshSkew`,
+`requireHttps`, `clock`…), or an existing `client`. They mirror the client as it is registered in Authio, and an
+option left out is off:
+
+| In the console | Options |
+| --- | --- |
+| PKCE required, S256 | `checks: ["pkce", "state", "nonce"]`, `codeChallengeMethod: "S256"` |
+| PKCE required, plain only | `checks: ["pkce", "state", "nonce"]`, `codeChallengeMethod: "plain"` |
+| PKCE off | `checks: ["state", "nonce"]` |
+| `client_secret_post` | `clientSecret`, `tokenEndpointAuthMethod: "client_secret_post"` |
+| ID token signing algorithm HS256 | `clientSecret`, `idTokenSignedResponseAlg: "HS256"` |
+| Access token signing algorithm HS256 | `clientSecret`, `accessTokenSignedResponseAlg: "HS256"` |
+| Front-channel logout URI with the session required | `frontChannelLogout: true` |
+
+`checks`, `codeChallengeMethod` and `responseMode` (only `query`: the BFF reads the callback itself) are read even with
+an existing `client`. The BFF's own options are those of `Authio.AspNetCore.Bff` (`Authio:Bff`), in camelCase, with
+durations in seconds:
+
+| Option | Default | |
+| --- | --- | --- |
+| `cookieSecret` | — (required) | 32+ characters; an array rotates: the first protects, every one is accepted. |
+| `store` | in memory | `AuthioBffSessionStore`. |
+| `endpointPrefix` | `/bff` | Where the BFF endpoints are served. |
+| `scopes` | `openid profile email offline_access` | Sent as configured; `openid` is not added. Without it there is no ID token, and the session is built from the verified access token. |
+| `requestRoles` | `false` | Adds `roles`, so the session carries `*_resource_access`. |
+| `getClaimsFromUserInfoEndpoint` | `false` | Adds UserInfo's claims to the session. |
+| `organization`, `resource`, `prompt`, `uiLocales`, `maxAge` | — | Sent on every sign-in unless the login request names one. |
+| `allowedResources` | `[]` | What `/bff/login?resource=` may ask for. |
+| `additionalAuthorizationParameters` | `{}` | Extra authorize parameters. |
+| `requireIssuerParameter` | `true` | Refuses a callback without `iss` (RFC 9207). |
+| `callbackPath`, `signedOutCallbackPath` | `/signin-oidc`, `/signout-callback-oidc` | Registered at Authio. |
+| `redirectUri`, `postLogoutRedirectUri` | built from the request | Absolute URIs, when the request's origin is not the public one. |
+| `defaultReturnUrl` | `/` | Local only. |
+| `cookieName`, `cookieSameSite` | `__Host-authio`, `lax` | The name must start with `__Host-` or `__Secure-`. |
+| `sessionLifetime`, `slidingExpiration` | `28800`, `true` | |
+| `sessionValidation`, `sessionValidationInterval` | `introspection`, `300` | `none` turns the check off. |
+| `revokeRefreshTokenOnLogout` | `true` | |
+| `antiForgeryHeaderName`, `antiForgeryHeaderValue` | `X-CSRF`, `1` | |
+| `sessionKeyPrefix` | `authio-bff:` | The prefix of the store keys. |
+| `backChannelLogout` | `true` | Serves `/bff/backchannel-logout`. |
+| `frontChannelLogout` | `false` | Serves `/bff/frontchannel-logout`. |
+| `onError` | — | Errors the BFF recovers from (failed revocation, introspection or refresh, refused logout token or ID token, an access token that does not verify, failed sign-in). |
+
+Every invalid option is named at once, in one `AuthioConfigurationError`, when `authioBff()` runs.
+
+## Differences from Authio.AspNetCore.Bff
+
+- `cookieSecret` is required: ASP.NET Core protects the cookie and the stored tickets with Data Protection, which Node
+  does not have. It signs the cookie (HMAC-SHA256) and encrypts the stored sessions and the sign-in cookie
+  (AES-256-GCM).
+- The session store is this package's own interface (indexed by `sid` and `sub`, so back-channel logout deletes the
+  sessions) rather than `IDistributedCache` with logout markers.
+- `AsAuthioBffApiEndpoint()`/`[AuthioBffApi]` + `RequireAuthorization()` are one middleware, `bff.api()`;
+  `AddAuthioBffUserToken()` on an `HttpClient` is `bff.userFetch()`; `MapAuthioRemoteApi` is `bff.remoteApi()` mounted
+  with `app.use`. There is no `403` access-denied answer: Express has no authorization policies to refuse with.
+- YARP's per-request settings (`RequestConfig`, `HttpClientName`) become a `fetch` option on the remote API.