@hyper.authio/client 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,121 @@
-# Temporary Holding Version
+# @hyper.authio/client
 
-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 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).
+
+```bash
+npm install @hyper.authio/client
+```
+
+## Configure
+
+```ts
+import { createAuthioClient } from "@hyper.authio/client";
+
+const authio = createAuthioClient({
+  issuer: "https://auth.example.com/realms/acme", // or authority + realm
+  clientId: "orders-worker",
+  clientSecret: process.env.AUTHIO_CLIENT_SECRET,
+});
+```
+
+| Option | Default | |
+| --- | --- | --- |
+| `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`. |
+| `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. |
+| `discoveryCacheDuration` | 3600 s | |
+| `httpTimeout` | 30 s | |
+| `tokenRefreshSkew` | 60 s | How early cached tokens are renewed (at most half their lifetime). |
+| `fetch`, `clock` | global `fetch`, system clock | Replace them in tests. |
+
+Every endpoint is read from the discovery document, which is cached, read once for concurrent callers, and refused
+when it names another issuer.
+
+## Grants
+
+```ts
+await authio.tokens.clientCredentials({ scopes: ["orders:read"], resource: "https://orders.example.com" });
+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 });
+
+const device = await authio.tokens.deviceAuthorization({ scopes: "openid" });
+console.log(device.verification_uri_complete);
+const token = await authio.tokens.pollDevice(device);      // waits, slows down, throws access_denied / expired_token
+
+const connection = await authio.tokens.exchangeForConnection({ subjectToken, provider: "github" });
+switch (connection.status) {
+  case "granted": /* connection.accessToken */ break;
+  case "required": /* send the person to connection.connectUri */ break;
+  case "selection_required": /* ask again with connectionId */ break;
+  case "refused": /* connection.error */ break;
+}
+```
+
+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.
+
+## Machine-to-machine calls
+
+```ts
+const ordersFetch = authio.clientCredentialsFetch({ scopes: "orders:read", resource: "https://orders.example.com" });
+await ordersFetch("https://orders.example.com/orders");
+```
+
+The token is cached per scopes and resource, renewed before expiry with one request for concurrent callers, and on a
+`401` dropped and retried once. `authio.clientCredentials.getToken()` gives the token itself.
+
+## Introspection, revocation, UserInfo
+
+```ts
+const result = await authio.introspect(token); // { active, sub, scope, …, and Authio's extra members }
+await authio.revoke(refreshToken, { tokenTypeHint: "refresh_token" });
+const info = await authio.userInfo(accessToken); // JSON, or a signed / encrypted JWT verified for you
+```
+
+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.
+
+## Roles and permissions
+
+```ts
+import { parseResourceAccess } from "@hyper.authio/client";
+
+const access = parseResourceAccess(jwtPayload);   // or introspection answer, or [type, value] pairs
+access.roles;                                     // ["billing-admin", "viewer"]
+access.permissions;                               // { invoice: ["read", "write"], report: ["read"] }
+access.grants("invoice", "write");                // true, case-insensitive
+access.grants("report", "read", ["user"]);        // only roles from user_resource_access
+access.fromSource("client");                      // the client's roles
+```
+
+The seven `*_resource_access` claims (`user`, `realm`, `client`, `plan`, `consumer`, `secret`, `system`) are merged.
+A claim that is not exactly `{ role: { resource: [method] } }` contributes nothing, as in Authio's own check. To
+protect an API, use [`@hyper.authio/server`](../server/README.md), which also reads groups, mapper claims and the rest.
+
+## Webhooks
+
+```ts
+import { verifyWebhookSignature, parseWebhookEvent, asUserEvent } from "@hyper.authio/client";
+
+const result = await verifyWebhookSignature(request.headers["x-authio-signature"], rawBody, secret);
+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
+```
+
+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.
+
+## License
+
+MIT