@hyper.authio/server 0.1.1 → 0.8.0

package/README.md

@@ -30,19 +30,56 @@ 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. |
-| `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. |
+| `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 and validates them locally. Without it nothing is decrypted. RSA1_5 is refused (`legacy_algorithm`), even with `allowLegacyEncryptionAlgorithms`. |
+| `encryptionAlgorithms`, `encryptionMethods` | `RSA-OAEP`, `RSA-OAEP-256`; the CBC-HS methods | The JWE `alg` and `enc` accepted, as registered in Authio (AES-GCM may be listed; RSA1_5 cannot: Node cannot decrypt it). |
+| `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), with `tokenEndpointAuthMethod` as the client is registered. 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* | |
+| `accessTokenSignedResponseAlg` | RS*, PS*, ES* (never HS*) | The algorithm (or several) access tokens are signed with, as the client is registered in Authio. HS256/384/512 are verified with the `clientSecret` of `client: { clientId, clientSecret }` (at least 32, 48 or 64 bytes). |
 | `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.
+`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"] });
+```
+
+### Access tokens signed with the client secret (HS*)
+
+Authio signs a client's access tokens with the algorithm of its access token setting. When that is HS256, HS384 or
+HS512, the signature is made with the client secret: only who holds the secret validates the token locally, so that is
+the client's own API.
+
+```ts
+const verifier = createAuthioVerifier({
+  issuer,
+  audiences: "storefront",
+  accessTokenSignedResponseAlg: "HS256",
+  client: { clientId: "storefront", clientSecret: process.env.AUTHIO_CLIENT_SECRET! }, // 32+ bytes for HS256
+});
+```
+
+Third-party APIs never get the secret: they validate such tokens with introspection (`introspection:
+"introspectionOnly"` and their own introspection client). Without `accessTokenSignedResponseAlg`, an HS* token is
+refused (`invalid_algorithm`) with a description naming both ways. `authioBearer` and the MCP packages take the same
+option.
 
 ## The caller
 
@@ -50,6 +87,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 +108,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 +126,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