@hyper.authio/server 0.1.1 → 0.7.0

package/README.md

@@ -30,8 +30,12 @@ try {
 
 | 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. |
+| `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 | |
@@ -41,8 +45,20 @@ try {
 | `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.
+`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
 
@@ -50,6 +66,13 @@ audience the API accepts; introspection failures fail closed.
 
 ```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
@@ -64,7 +87,8 @@ 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 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
 
@@ -81,8 +105,14 @@ if (refusal) {
 ```
 
 Rules: `requireScope`, `requireRole`, `requirePermission`, `requireGroup`, `requireClaim`, `requireOrganization`,
-`requireAuthenticationLevel`, `requireAuthenticationMethod`, `requireClient`, combined with `allOf` and `anyOf`.
-`authorize` checks every rule and joins their messages.
+`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