@udibo/oauth2 0.12.1 → 0.13.0

package/README.md

@@ -5,15 +5,15 @@ Udibo's identity service, or host an authorization server for your own app. The
 package includes clients, authorization and resource servers, Hono middleware,
 React bindings, and optional login flows over your own database.
 
-**Udibo's managed identity service is in private beta.** See
-[udibo.com](https://www.udibo.com/) for access. The self-hosted examples run
-locally without a hosted account.
+Using Udibo's managed identity service requires a Udibo account; see
+[udibo.com](https://www.udibo.com/) for how to get one. The self-hosted examples
+run locally without a hosted account.
 
 ## Choose your path
 
 | Your application needs                      | Start here                                                                                                                |
 | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| Udibo to handle sign-in                     | [Use Udibo's identity service](docs/guides/use-udibo.md) — private-beta access required                                   |
+| Udibo to handle sign-in                     | [Use Udibo's identity service](docs/guides/use-udibo.md) — requires a Udibo account                                       |
 | Its own login and authorization server      | [Run the quickstart](docs/quickstart.md), then [host authorization for your app](docs/guides/become-an-oauth-provider.md) |
 | An API that accepts access tokens           | [Protect an API](docs/guides/protect-an-api.md)                                                                           |
 | A React application with server-held tokens | [Juniper starter](templates/juniper/README.md) or [React Router starter](templates/react-router/README.md)                |

package/esm/server/grants/client-credentials.d.ts

@@ -21,6 +21,16 @@ export type ClientCredentialsGrantOptions<Client extends ClientInterface, User,
  * Used for machine-to-machine authentication where the client itself
  * is the resource owner. Does not support refresh tokens.
  *
+ * **Only confidential clients may use it.** RFC 6749 §4.4 restricts this grant
+ * to confidential clients, so a request that presents no client secret — a
+ * public client, or a confidential client leaving its secret out — is refused
+ * with 401 `invalid_client`. Register a machine client with a secret and send
+ * that secret with HTTP Basic or as `client_secret` in the body. The grant
+ * relies on `ClientServiceInterface.getAuthenticated` refusing a public client
+ * that presents a secret, which `runClientServiceContractTests` pins. A client
+ * service written before 0.9.2 must pass `runClientServiceContractTests`, or
+ * `client_credentials` is not limited to confidential clients.
+ *
  * **The token need not carry a user.** RFC 6749 §4.4 has no resource owner, so
  * a `ClientServiceInterface.getUser` that resolves nothing is the conformant
  * case, not an error: the grant issues a token whose {@linkcode Token.user} is
@@ -37,6 +47,20 @@ export declare class ClientCredentialsGrant<Client extends ClientInterface, User
     readonly issuesIdToken = false;
     /** Creates the grant from its {@linkcode ClientCredentialsGrantOptions}. */
     constructor(options: ClientCredentialsGrantOptions<Client, User, S>);
+    /**
+     * Authenticates the client from a request that must carry its client
+     * secret, by HTTP Basic or in the body. Credentials are read through
+     * {@linkcode getClientCredentials} and checked by the grant's
+     * `clientService.getAuthenticated`.
+     *
+     * A subclass that authenticates clients by other means, such as a signed
+     * client assertion, overrides this method and must itself admit only
+     * confidential clients.
+     *
+     * @throws {InvalidClientError} If the request presents no non-empty client
+     * secret, or authentication fails.
+     */
+    getAuthenticatedClient(request: Request, body: FormData): Promise<Client>;
     /**
      * Handles a token request for the client credentials grant. Issues an access
      * token (never a refresh token) to the client acting as its own resource

package/esm/server/grants/client-credentials.js

@@ -3,6 +3,8 @@
  * RFC 6749 Section 4.4.
  * @module
  */
+import { InvalidClientError } from "../../errors.js";
+import { authenticateClientCredentials } from "../client-authentication.js";
 import { AbstractGrant, } from "./grant.js";
 /**
  * The client credentials grant type.
@@ -11,6 +13,16 @@ import { AbstractGrant, } from "./grant.js";
  * Used for machine-to-machine authentication where the client itself
  * is the resource owner. Does not support refresh tokens.
  *
+ * **Only confidential clients may use it.** RFC 6749 §4.4 restricts this grant
+ * to confidential clients, so a request that presents no client secret — a
+ * public client, or a confidential client leaving its secret out — is refused
+ * with 401 `invalid_client`. Register a machine client with a secret and send
+ * that secret with HTTP Basic or as `client_secret` in the body. The grant
+ * relies on `ClientServiceInterface.getAuthenticated` refusing a public client
+ * that presents a secret, which `runClientServiceContractTests` pins. A client
+ * service written before 0.9.2 must pass `runClientServiceContractTests`, or
+ * `client_credentials` is not limited to confidential clients.
+ *
  * **The token need not carry a user.** RFC 6749 §4.4 has no resource owner, so
  * a `ClientServiceInterface.getUser` that resolves nothing is the conformant
  * case, not an error: the grant issues a token whose {@linkcode Token.user} is
@@ -29,6 +41,27 @@ export class ClientCredentialsGrant extends AbstractGrant {
     constructor(options) {
         super({ ...options, allowRefreshToken: false });
     }
+    /**
+     * Authenticates the client from a request that must carry its client
+     * secret, by HTTP Basic or in the body. Credentials are read through
+     * {@linkcode getClientCredentials} and checked by the grant's
+     * `clientService.getAuthenticated`.
+     *
+     * A subclass that authenticates clients by other means, such as a signed
+     * client assertion, overrides this method and must itself admit only
+     * confidential clients.
+     *
+     * @throws {InvalidClientError} If the request presents no non-empty client
+     * secret, or authentication fails.
+     */
+    async getAuthenticatedClient(request, body) {
+        const credentials = this.getClientCredentials(request, body);
+        if (!credentials.clientSecret) {
+            throw new InvalidClientError("client authentication failed");
+        }
+        const { clientService } = await this.resolveServices(request);
+        return await authenticateClientCredentials(credentials, clientService);
+    }
     /**
      * Handles a token request for the client credentials grant. Issues an access
      * token (never a refresh token) to the client acting as its own resource

package/esm/utils/url.d.ts

@@ -13,7 +13,9 @@ import "../_dnt.polyfills.js";
  * that some browsers resolve as a host, and any value containing a C0 control
  * character or `DEL` — browsers strip TAB/CR/LF before parsing a URL, so
  * `/<TAB>/evil.com` would otherwise navigate to `evil.com`. Anything else
- * collapses to `fallback` (default `/`).
+ * collapses to `fallback` (default `/`), which is returned verbatim. The
+ * fallback is trusted caller configuration; do not pass user-controlled input
+ * there.
  *
  * Percent-encoded control characters (`/%09/x`) are safe and pass through: a
  * browser does not decode them before parsing, so they stay on the origin.
@@ -34,17 +36,17 @@ import "../_dnt.polyfills.js";
  * ```
  */
 export declare function safeReturnTo(value: string | null | undefined, fallback?: string): string;
-/** Options for {@link loginContinuation}. */
+/** Trusted application configuration for {@link loginContinuation}. */
 export interface LoginContinuationOptions {
     /**
-     * The authorization endpoint (absolute URL or path). When `returnTo` points at
-     * it, the flow is **resumed** (the in-flight authorize request already carries
+     * Trusted authorization endpoint (absolute URL or path). When `returnTo` points
+     * at it, the flow is **resumed** (the in-flight authorize request already carries
      * its `state`). Omit it and every `returnTo` starts a fresh login.
      */
     authorizeEndpoint?: string;
-    /** The login path to start a fresh login. Defaults to `"/auth/login"`. */
+    /** Trusted login path for a fresh login. Defaults to `"/auth/login"`. */
     loginPath?: string;
-    /** Fallback when `returnTo` is missing/unsafe. Defaults to `"/"`. */
+    /** Trusted fallback for missing/unsafe `returnTo`. Defaults to `"/"`. */
     defaultReturnTo?: string;
 }
 /**
@@ -61,6 +63,7 @@ export interface LoginContinuationOptions {
  *
  * Pure and client-safe — the same logic behind `HonoBff.loginContinuation`
  * (server) and `BffClient.loginContinuation` (browser). `returnTo` is
- * open-redirect-guarded via {@link safeReturnTo}.
+ * open-redirect-guarded via {@link safeReturnTo}. The fallback, authorization
+ * endpoint and login path are trusted application configuration.
  */
 export declare function loginContinuation(returnTo: string | null | undefined, options?: LoginContinuationOptions): string;

package/esm/utils/url.js

@@ -22,7 +22,9 @@ function hasControlCharacter(value) {
  * that some browsers resolve as a host, and any value containing a C0 control
  * character or `DEL` — browsers strip TAB/CR/LF before parsing a URL, so
  * `/<TAB>/evil.com` would otherwise navigate to `evil.com`. Anything else
- * collapses to `fallback` (default `/`).
+ * collapses to `fallback` (default `/`), which is returned verbatim. The
+ * fallback is trusted caller configuration; do not pass user-controlled input
+ * there.
  *
  * Percent-encoded control characters (`/%09/x`) are safe and pass through: a
  * browser does not decode them before parsing, so they stay on the origin.
@@ -74,7 +76,8 @@ export function safeReturnTo(value, fallback = "/") {
  *
  * Pure and client-safe — the same logic behind `HonoBff.loginContinuation`
  * (server) and `BffClient.loginContinuation` (browser). `returnTo` is
- * open-redirect-guarded via {@link safeReturnTo}.
+ * open-redirect-guarded via {@link safeReturnTo}. The fallback, authorization
+ * endpoint and login path are trusted application configuration.
  */
 export function loginContinuation(returnTo, options = {}) {
     const safe = safeReturnTo(returnTo, options.defaultReturnTo ?? "/");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udibo/oauth2",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "A flexible OAuth2 toolkit: framework-agnostic authorization & resource servers, a typed client, Hono adapters (including a backend-for-frontend), and React bindings.",
   "repository": {
     "type": "git",