@hyper.authio/server 0.0.0-stage → 0.7.0

package/README.md

@@ -1,3 +1,145 @@
-# 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, unless `resource` is set. |
+| `resource` | | The API's own resource identifier (RFC 8707); added to `audiences` and used for RFC 9728. |
+| `resourceMetadata` | off | `true` (or the URL) adds `resource_metadata="{origin}/.well-known/oauth-protected-resource{path}"` to `401` challenges (RFC 9728). |
+| `requiredScopes` | | Scopes every request must carry (all); `authioBearer` answers `403 insufficient_scope`. |
+| `clientEncryptionKey`, `clientEncryptionKeyPath` | | Decrypts access tokens Authio encrypts to this key (RSA-OAEP, RSA-OAEP-256) and validates them locally. RSA1_5 is refused (`legacy_algorithm`), even with `allowLegacyEncryptionAlgorithms`. |
+| `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 tokens (or encrypted ones without the key). |
+| `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 (plus `resource_metadata` when turned on). Its
+`reason` names why, with the outcome names of `conformance/tokens.json` (`expired`, `invalid_audience`,
+`not_access_token`, `reference_token`, `decryption_failed`, …, and `inactive` / `unconfirmed` for introspection). A
+token addressed elsewhere is described with the audience the API accepts; introspection failures fail closed.
+
+### Protected resource metadata (RFC 9728)
+
+```ts
+import { createProtectedResourceMetadata, protectedResourceMetadataPath } from "@hyper.authio/server";
+
+const verifier = createAuthioVerifier({ issuer, resource: "https://orders.example.com/api", resourceMetadata: true });
+const path = protectedResourceMetadataPath(verifier.resource!); // /.well-known/oauth-protected-resource/api
+const document = createProtectedResourceMetadata({ issuer, resource: verifier.resource!, scopesSupported: ["orders:read"] });
+```
+
+## 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.kind;           // "user" | "client" | "consumer" | "account_credential"
+user.credentialForm; // "client_secret" | "personal_access_token" | "api_key" | "consumer_api_key" (machines only)
+user.consumerName; user.credentialId; user.credentialName; user.ownerUserId; user.ownerUsername; user.accountId;
+user.credentialRealm; user.credentialClient;          // what an account credential is limited to
+user.impersonated; user.impersonator;                 // an administrator acting as the person (act.sub)
+user.delegated; user.delegationId; user.actorChain;   // clients acting for the person (act.client_id), outermost first
+user.authTime;       // auth_time, in seconds
+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. The caller fields follow
+`conformance/callers.json`; `AuthioUser.fromIntrospection(answer)` reads an introspection answer the same way.
+
+## 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`, `requireRecentAuthentication`, `requireCallerKind`,
+`requireClient`, combined with `allOf` and `anyOf`. `authorize` checks every rule and joins their messages.
+
+**Step-up (RFC 9470)**: `requireAuthenticationLevel(2, { maxAge: 300 })`, `requireAuthenticationMethod("otp")` and
+`requireRecentAuthentication(300)` refuse with `insufficient_user_authentication`, `acrValues` (the level asked for;
+`2` for `mfa`/`otp`/`mca`, `3` for `swk`/`hwk`) and `maxAge`, so the challenge reads
+`Bearer error="insufficient_user_authentication", error_description="…", acr_values="2", max_age=300`. A client
+answers it with `createStepUpAuthorizationUrl` from `@hyper.authio/client`.
+
+## 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