@hyper.authio/client 0.1.1 → 0.7.0

package/README.md

@@ -1,8 +1,10 @@
 # @hyper.authio/client
 
-The Authio client for Node.js 20.19+ and edge runtimes: discovery, every grant, client authentication with a secret
-or `private_key_jwt`, introspection, revocation, UserInfo, a cached client-credentials `fetch`, the roles and
-permissions of a token, and webhook verification. Its only dependency is [`jose`](https://github.com/panva/jose).
+The Authio client for Node.js 20.19+ and edge runtimes: discovery, interactive sign-in (PKCE, ID tokens, end session,
+back-channel logout tokens, step-up), every grant, client authentication with a secret or `private_key_jwt`,
+introspection, revocation, UserInfo, JWE, a cached client-credentials `fetch`, account credentials for the Admin API,
+the roles and permissions of a token, and webhook verification. Its only dependency is
+[`jose`](https://github.com/panva/jose).
 
 ```bash
 npm install @hyper.authio/client
@@ -25,10 +27,14 @@ const authio = createAuthioClient({
 | `issuer`, or `authority` + `realm` | | The realm's issuer. Must be HTTPS, except on loopback or with `requireHttps: false`. |
 | `clientId` | | Required. |
 | `clientAuthentication` | `private_key_jwt` with only a key, else `client_secret_basic` | Also `client_secret_post` and `none` (a public client). |
-| `clientSecret` | | For `client_secret_basic` / `client_secret_post`. |
+| `clientSecret` | | For `client_secret_basic` / `client_secret_post`. A function returning the secret is called for every request, so a rotated secret is used without a restart. |
 | `clientPrivateKey`, `clientPrivateKeyPath`, `clientKeyId`, `clientSigningAlgorithm` | RS256 for RSA, the curve's ES algorithm for EC | For `private_key_jwt`: PEM (PKCS#8, PKCS#1, SEC1) or JWK; the file is re-read when it changes; RSA keys need 2048 bits. |
 | `clientAssertionLifetime` | 120 s | At most 3600. |
-| `clientEncryptionKey` | | The client's own key, to read a UserInfo Authio answers encrypted. |
+| `clientEncryptionKey`, `clientEncryptionKeyPath` | | The private half of the client's encryption key (JWK or PEM, or a function returning it; the path is Node only), to read ID tokens, UserInfo and logout tokens Authio encrypts (RSA-OAEP, RSA-OAEP-256). |
+| `allowLegacyEncryptionAlgorithms` | `false` | Accepted for parity; RSA1_5 stays refused in Node, which cannot decrypt it (`legacy_algorithm`). |
+| `redirectUri`, `postLogoutRedirectUri` | | Defaults for sign-in and sign-out requests. |
+| `clockSkew` | 30 s | Tolerated on ID tokens, logout tokens and signed UserInfo. |
+| `validAlgorithms` | RS*, PS*, ES* | Accepted signing algorithms for those tokens. |
 | `discoveryCacheDuration` | 3600 s | |
 | `httpTimeout` | 30 s | |
 | `tokenRefreshSkew` | 60 s | How early cached tokens are renewed (at most half their lifetime). |
@@ -37,6 +43,62 @@ const authio = createAuthioClient({
 Every endpoint is read from the discovery document, which is cached, read once for concurrent callers, and refused
 when it names another issuer.
 
+Option names follow the shared `conformance/options.md`; there are no aliases for older names.
+
+## Sign people in
+
+```ts
+const authio = createAuthioClient({
+  issuer, clientId: "storefront", clientAuthentication: "none", // or a secret / private key for a confidential client
+  redirectUri: "https://shop.example.com/callback",
+});
+
+// 1. Send the person to Authio, keeping the transaction (session, encrypted cookie…).
+const { url, transaction } = await authio.createAuthorizationUrl({
+  scopes: ["openid", "profile", "offline_access"],
+  resource: "https://orders.example.com",   // RFC 8707
+  organization: "acme-europe",              // optional: sign in for one organization
+  prompt: "login",                          // none | login | select_account | consent
+  maxAge: 900, acrValues: "2", loginHint, uiLocales: "pt-BR", idpHint: "google",
+});
+
+// 2. On the callback: state and iss (RFC 9207) are checked, the code is redeemed with the PKCE verifier,
+//    and the ID token validated (nonce, at_hash, auth_time against maxAge).
+const { tokens, idToken } = await authio.handleAuthorizationCallback(request.url, transaction);
+```
+
+PKCE uses S256 unless `codeChallengeMethod: "plain"` is asked for. `popup: true` sets `display=popup` and
+`response_mode=web_message`; pass the parameters the popup posted to the opener to `handleAuthorizationCallback`. A
+callback that is not for the transaction throws `AuthioCallbackError` (`reason`: `state_mismatch`, `issuer_mismatch`,
+`missing_issuer`, `missing_code`); an OAuth error Authio sent back (`login_required` after `prompt: "none"`, for one)
+throws `AuthioProtocolError`.
+
+### ID tokens and sign-out
+
+```ts
+const claims = await authio.validateIdToken(idToken, { nonce, accessToken, maxAge }); // AuthioTokenValidationError otherwise
+const logoutUrl = await authio.createEndSessionUrl({ idTokenHint, postLogoutRedirectUri, state });
+const logout = await authio.validateLogoutToken(form.logout_token); // { subject, sessionId, tokenId, claims }
+```
+
+ID tokens are checked against the realm's JWKS (cached, re-read on an unknown `kid`): `iss`, `aud` = the client id,
+`exp` with `clockSkew`, payload `typ` = `ID`, `azp` when there are several audiences, `nonce`, `at_hash` (hash of the
+signing algorithm) and `auth_time` against `maxAge`. An encrypted ID token is decrypted with `clientEncryptionKey`
+first. A back-channel logout token must be typed `logout+jwt`, carry the back-channel event, no `nonce`, and a `sub`
+or `sid`. Every refusal is an `AuthioTokenValidationError` whose `reason` uses the outcome names of
+`conformance/tokens.json` (`invalid_nonce`, `invalid_at_hash`, `invalid_logout_token`, `expired`, …). In Express,
+`authioBackchannelLogout` from `@hyper.authio/express` is the endpoint.
+
+### Step-up
+
+When an API answers `403` with `WWW-Authenticate: Bearer error="insufficient_user_authentication", acr_values="2",
+max_age=300` (RFC 9470):
+
+```ts
+const challenge = parseAuthioBearerChallenge(response.headers.get("www-authenticate"));
+const { url, transaction } = await authio.createStepUpAuthorizationUrl(challenge!); // acr_values, max_age, prompt=login for max_age=0
+```
+
 ## Grants
 
 ```ts
@@ -45,6 +107,7 @@ await authio.tokens.authorizationCode({ code, redirectUri, codeVerifier });
 await authio.tokens.refresh({ refreshToken });             // store the rotated refresh_token it returns
 await authio.tokens.exchange({ subjectToken, resource });  // on-behalf-of (RFC 8693)
 await authio.tokens.password({ username, password });
+await authio.tokens.personalAccessToken({ token: "pat_…", clientId: "billing-api" }); // clientId only for a consumer's PAT
 
 const device = await authio.tokens.deviceAuthorization({ scopes: "openid" });
 console.log(device.verification_uri_complete);
@@ -52,13 +115,16 @@ const token = await authio.tokens.pollDevice(device);      // waits, slows down,
 
 const connection = await authio.tokens.exchangeForConnection({ subjectToken, provider: "github" });
 switch (connection.status) {
-  case "granted": /* connection.accessToken */ break;
+  case "granted": /* accessToken, issuedTokenType, tokenType, expiresIn, scope, connectionId, provider, providerType, externalAccount */ break;
   case "required": /* send the person to connection.connectUri */ break;
-  case "selection_required": /* ask again with connectionId */ break;
-  case "refused": /* connection.error */ break;
+  case "selection_required": /* ask again with one of connection.connections[].id (label, externalLogin) */ break;
+  case "refused": /* connection.error, connection.errorCode */ break;
 }
 ```
 
+Device polling waits `interval`, keeps polling on `authorization_pending`, adds 5 seconds on `slow_down`, and stops
+with the error on `access_denied` and `expired_token` (`toDevicePollOutcome` tells which).
+
 OAuth errors throw `AuthioProtocolError` (`error`, `errorDescription`, `errorCode`, `status`); `error` is
 `http_{status}` when Authio sent none, `invalid_response` when a success body could not be read. Tokens print as
 `[redacted]` in `console.log` and `util.inspect`, and serialize normally.
@@ -84,6 +150,27 @@ const info = await authio.userInfo(accessToken); // JSON, or a signed / encrypte
 Authio answers introspection according to who asks: a token requested for a resource is active only to the client
 that resource server names as its introspection client.
 
+## Admin API credentials
+
+```ts
+import { createAuthioAccountCredential, readAuthioAdminResponse } from "@hyper.authio/client";
+
+const credential = createAuthioAccountCredential({
+  authority: "https://auth.example.com",
+  credential: process.env.AUTHIO_CREDENTIAL, // ak_…, cs_… or pat_…
+  credentialId: process.env.AUTHIO_CREDENTIAL_ID, // needed for a cs_ secret
+});
+const response = await credential.fetch("https://auth.example.com/api/v1/admin/realms");
+const { data } = await readAuthioAdminResponse(response); // { items, totalCount, pageNumber, pageSize } for a listing; AuthioAdminError otherwise
+```
+
+`ak_` and `pat_` go directly as `Authorization: Bearer` (or `x-api-key` with `presentAs`); a `cs_` secret is exchanged
+at `{authority}/realms/authio` with `client_credentials` and the `client_id` `cred_{id}`, and a `pat_` may be exchanged
+with the `personal_access_token` grant (`exchangePersonalAccessToken: true`). The `fetch` retries an idempotent request
+once after `Retry-After` on `429`/`503`. `AuthioAdminError` carries `status` (the HTTP one), `errorCode`,
+`notifications`, `requestId` (body or `X-Request-Id`) and `retryAfterSeconds`; `parseAuthioAdminEnvelope` reads an
+answer you fetched yourself. The full Admin client comes in a later release.
+
 ## Roles and permissions
 
 ```ts
@@ -110,9 +197,15 @@ const result = await verifyWebhookSignature(request.headers["x-authio-signature"
 if (!result.valid) return reply(401);
 
 const event = parseWebhookEvent(rawBody);
-const user = asUserEvent(event); // typed data for user_created / user_updated / user_deleted, else undefined
+const user = asUserEvent(event); // { id, username, emailConfirmed, … } for user_created / user_updated / user_deleted, else undefined
 ```
 
+Every event type has its accessor (`asLoginEvent`, `asUserLockedOutEvent`, `asTokenRevokedEvent`,
+`asKeysRotatedEvent`, `asTokenReuseDetectedEvent`, `asAdminResourceEvent`, `asUserSuspensionEvent`,
+`asAttackDetectedEvent`, `asCredentialCompromisedEvent`, `asPingEvent`), which exposes every member of `data` in
+camelCase with its value unchanged; `event.data` stays as delivered (snake_case). An unknown type still parses
+(`isKnownWebhookEventType` is `false`, `event.data` is the raw JSON).
+
 The signature is HMAC-SHA256 of `{t}.{body}`, compared in constant time; the timestamp must be within 5 minutes.
 [`@hyper.authio/server`](../server/README.md) adds deduplication and dispatch.