@hyper.authio/testing 0.0.0-stage → 0.7.0

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @hyper.authio/testing
 
-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.
+An in-memory Authio realm served over HTTP on loopback, for tests of code built on `@hyper.authio/client`,
+`@hyper.authio/server` or `@hyper.authio/express`.
+
+```bash
+npm install -D @hyper.authio/testing
+```
+
+```ts
+import { FakeAuthio, ManualClock, createWebhookDelivery } from "@hyper.authio/testing";
+
+const authio = await FakeAuthio.start({
+  realm: "acme",
+  clients: [{ clientId: "orders-api", clientSecret: "secret" }],
+  users: [{ sub: "u-1", username: "alice", password: "p", claims: { user_resource_access: { editor: { orders: ["read"] } } } }],
+});
+
+const token = await authio.issueAccessToken({
+  sub: "u-1",
+  audience: "https://orders.example.com",
+  scope: "orders:read",
+  claims: { groups: ["finance"], org_id: "o-1" },
+});
+
+// point the SDK at authio.issuer, then:
+await authio.close();
+```
+
+- Endpoints: discovery (every endpoint it advertises is served), JWKS, authorization, token (client credentials,
+  authorization code with ID tokens, refresh with rotation, token exchange including connected accounts, password,
+  device code, personal access token), introspection (answered according to who asks, like Authio), revocation,
+  UserInfo (JSON, or a signed JWT with `userInfoAsJwt`), device authorization and end session.
+- Sign-in: `authorize(url)` follows an authorization URL as a browser would and returns the callback URL (or, for
+  `response_mode=web_message`, the posted parameters). It signs in `signInAs`, the `login_hint` or the first user;
+  honours PKCE (S256, plain), `prompt` (`none` answers `login_required` without a session, `login` signs in again),
+  `max_age`, `acr_values`, and sends RFC 9207 `iss` (`omitAuthorizationIssuer` leaves it out). ID tokens carry `nonce`,
+  `sid`, `auth_time`, `acr`, `amr` and `at_hash`. `createAuthorizationCode` still mints a code directly.
+- Sign-out: the end-session endpoint checks `post_logout_redirect_uri`, echoes `state`, and posts a logout token to the
+  `backchannelLogoutUri` of every client of the session (`backchannelDeliveries`); `deliverBackchannelLogout` and
+  `createLogoutToken` do it by hand. Ending a session revokes its refresh tokens; `revokeRefreshTokens({ sub | sid })`
+  and `revokeToken(token)` revoke them by hand.
+- Refresh tokens carry the session's `sid` through refreshes and are introspectable by the client they were issued to
+  (`token_type` `Refresh`), as a BFF's session check needs.
+- JWE: a client with `encryption: { key, algorithm }` (RSA-OAEP or RSA-OAEP-256) gets its ID tokens, UserInfo, and
+  optionally access and logout tokens encrypted; `issueAccessToken({ encryptTo })` mints one directly.
+- Personal access tokens: `personalAccessTokens: [{ token: "pat_…", sub, clientId? }]`.
+- Client authentication: `client_secret_basic`, `client_secret_post`, `private_key_jwt` (register `publicKey`) and
+  `none`.
+- `issueAccessToken` options: `expiresIn` (negative for an expired token), `type` (`ID` for a non-access token),
+  `issuer`, `untrusted` (a signature that does not verify).
+- `failures.set("token", [{ status: 503 }])` answers the next calls to an endpoint with errors; `deviceOutcomes`
+  scripts device polling; `connectionResponder` scripts connected-account exchanges; `requests` records every call.
+- `ManualClock` moves only when told to: device polling and cache expiry run instantly.
+- `createWebhookDelivery(type, data, secret)` builds a signed delivery (`body`, `headers`).
+
+## License
+
+MIT