@hyper.authio/server 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# @hyper.authio/server
 
-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.
+Protect a Node.js API with Authio, in any framework: token validation, the caller with every form of permission
+Authio issues, authorization rules, a webhook receiver, and calls to downstream APIs. For Express, use
+[`@hyper.authio/express`](../express/README.md), built on this package.
+
+```bash
+npm install @hyper.authio/server
+```
+
+## Validate tokens
+
+```ts
+import { createAuthioVerifier, AuthioBearerError } from "@hyper.authio/server";
+
+const verifier = createAuthioVerifier({
+  issuer: "https://auth.example.com/realms/acme",
+  audiences: "https://orders.example.com", // the API's resource identifier (RFC 8707)
+});
+
+try {
+  const user = await verifier.verifyAuthorizationHeader(request.headers.authorization);
+} catch (error) {
+  if (error instanceof AuthioBearerError) {
+    response.setHeader("WWW-Authenticate", error.wwwAuthenticate);
+    response.statusCode = 401;
+  }
+}
+```
+
+| Option | Default | |
+| --- | --- | --- |
+| `audiences` | | Required. |
+| `introspection` | `none` | `none`: local JWT validation. `activeCheck`: then confirmed active by introspection (cached per `jti`), so a revoked token, an ended session or a suspension is refused before the token expires. `introspectionOnly`: introspection alone, for opaque or encrypted tokens. |
+| `client` | | The API's confidential client, needed by introspection: an `AuthioClient` or `{ clientId, clientSecret }` (or a private key). It must be the resource server's introspection client. |
+| `introspectionCacheDuration` | 30 s | Never past the token's expiry; only active answers are kept. |
+| `clockSkew` | 30 s | |
+| `validAlgorithms` | RS*, PS*, ES* | |
+| `rejectNonAccessTokens` | `true` | Refuses a token whose `typ` is not `Bearer` (an ID token, for one). |
+| `roleClaims` | `["role"]` | Claims holding flat role names (a Role claim mapper). |
+| `groupClaims` | `["groups"]` | Claims holding group names (a Group claim mapper). |
+
+A refusal is an `AuthioBearerError` whose `wwwAuthenticate` is `Bearer` when the request had no token, and
+`Bearer error="invalid_token", error_description="…"` otherwise. A token addressed elsewhere is described with the
+audience the API accepts; introspection failures fail closed.
+
+## The caller
+
+`AuthioUser` reads every form of permission, the same way from a JWT or an introspection answer:
+
+```ts
+user.subject; user.clientId; user.scopes;
+user.roles;          // *_resource_access roles, then flat role claims
+user.permissions;    // { orders: ["read", "write"] }
+user.resourceAccess; // per-source entries: user, realm, client, plan, consumer, secret, system
+user.groups;         // from the group claims
+user.organizationId; user.organizationAlias; user.authenticationLevel; user.authenticationMethods; user.actor;
+user.claims;         // every claim, for claim-mapper claims and the person's own claims
+
+user.hasPermission("orders", "read");
+user.hasPermission("orders", "read", { sources: ["realm", "client"] });
+user.hasRole("admin", { sources: ["user"] });
+user.hasGroup("finance");
+user.hasClaim("department", "finance", "sales");
+```
+
+The raw token is kept as `user.token`, not enumerable, so it stays out of logs and JSON.
+
+## Authorize
+
+```ts
+import { authorize, requirePermission, requireGroup, requireAuthenticationLevel, allOf, anyOf, AuthioForbiddenError } from "@hyper.authio/server";
+
+const refusal = authorize(user, requirePermission("orders", "write"), anyOf(requireGroup("finance"), requireAuthenticationLevel(2)));
+
+if (refusal) {
+  const error = new AuthioForbiddenError(refusal);
+  // 403, with error.wwwAuthenticate when the refusal is about scopes (insufficient_scope) or the sign-in
+  // (insufficient_user_authentication); toProblemDetails(error) for an RFC 9457 body.
+}
+```
+
+Rules: `requireScope`, `requireRole`, `requirePermission`, `requireGroup`, `requireClaim`, `requireOrganization`,
+`requireAuthenticationLevel`, `requireAuthenticationMethod`, `requireClient`, combined with `allOf` and `anyOf`.
+`authorize` checks every rule and joins their messages.
+
+## Webhooks
+
+```ts
+import { createAuthioWebhooks } from "@hyper.authio/server";
+
+const webhooks = createAuthioWebhooks({ secret: process.env.AUTHIO_WEBHOOK_SECRET })
+  .on("user_created", async (event) => { /* event.data.username */ })
+  .on("*", (event) => log(event.type));
+
+const outcome = await webhooks.handle({ body: rawBody, headers: request.headers });
+response.statusCode = outcome.status; // 200 handled or duplicate, 400, 401, 413, 500
+```
+
+Deliveries are deduplicated by `X-Authio-Event-Id` for 24 hours in memory (or a store you pass); a handler that
+throws releases the id so the redelivery runs. Several `secrets` are accepted while one is rotated.
+
+## Downstream APIs
+
+```ts
+import { createForwardingFetch, createOnBehalfOf } from "@hyper.authio/server";
+
+const sameAudience = createForwardingFetch(user);  // forwards the caller's own token
+const billing = createOnBehalfOf({ client: authioClient, resource: "https://billing.example.com", scopes: "invoices:read" });
+await billing.fetch(user)("https://billing.example.com/invoices"); // exchanged once, cached, retried once on 401
+```
+
+## License
+
+MIT