feat(auth0-api-js): add ProtectedResourceMetadata (#60)

patrickkang · web-flow · commit 4ed876752062 · 2025-09-12T14:47:54.000+02:00
* adds ProtectedResourceMetadata class

* fix the export

* update README to include how to serve PRM

* refactor: builder pattern

* update README for ProtectedResourceMetadataBuilder usage

* fix readme to use single quotes
diff --git a/packages/auth0-api-js/README.md b/packages/auth0-api-js/README.md
@@ -26,11 +26,10 @@ This library requires Node.js 20 LTS and newer LTS versions.
 
 Create an instance of the `ApiClient`. This instance will be imported and used anywhere we need access to the methods.
 
-
 ```ts
 import { ApiClient } from '@auth0/auth0-api-js';
 
-const apiClient = new apiClient({
+const apiClient = new ApiClient({
   domain: '<AUTH0_DOMAIN>',
   audience: '<AUTH0_AUDIENCE>',
 });
@@ -44,29 +43,64 @@ The `AUTH0_AUDIENCE` is the identifier of the API. You can find this in the API
 The SDK's `verifyAccessToken` method can be used to verify the access token.
 
 ```ts
-const apiClient = new apiClient({
+const apiClient = new ApiClient({
   domain: '<AUTH0_DOMAIN>',
   audience: '<AUTH0_AUDIENCE>',
 });
 
 const accessToken = '...';
-const decodedAndVerfiedToken = await apiClient.verifyAccessToken({
-  accessToken
+const decodedAndVerifiedToken = await apiClient.verifyAccessToken({
+  accessToken,
 });
 ```
 
-the SDK automatically validates claims like `iss`, `aud`, `exp`, and `nbf`, you can also pass additional claims to be required by configuring `requiredClaims`:
+The SDK automatically validates claims like `iss`, `aud`, `exp`, and `nbf`. You can also pass additional claims to be required by configuring `requiredClaims`:
 
 ```ts
-const apiClient = new apiClient({
+const apiClient = new ApiClient({
   domain: '<AUTH0_DOMAIN>',
   audience: '<AUTH0_AUDIENCE>',
 });
 
 const accessToken = '...';
-const decodedAndVerfiedToken = await apiClient.verifyAccessToken({
+const decodedAndVerifiedToken = await apiClient.verifyAccessToken({
   accessToken,
-  requiredClaims: ['my_custom_claim']
+  requiredClaims: ['my_custom_claim'],
+});
+```
+
+### 4. Protected Resource Metadata (RFC 9728)
+
+The SDK supports OAuth 2.0 Protected Resource Metadata as defined in [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728):
+
+```ts
+import {
+  ProtectedResourceMetadataBuilder,
+  AuthorizationScheme,
+  TokenEndpointAuthMethod,
+  SigningAlgorithm,
+} from '@auth0/auth0-api-js';
+
+const resourceServerUrl = 'https://api.example.com';
+const authServers = ['https://your-tenant.us.auth0.com'];
+
+const metadata = new ProtectedResourceMetadataBuilder(resourceServerUrl, authServers)
+  .withBearerMethodsSupported([AuthorizationScheme.BEARER])
+  .withTokenEndpointAuthMethodsSupported([
+    TokenEndpointAuthMethod.CLIENT_SECRET_BASIC,
+    TokenEndpointAuthMethod.CLIENT_SECRET_POST,
+    TokenEndpointAuthMethod.PRIVATE_KEY_JWT,
+  ])
+  .withTokenEndpointAuthSigningAlgValuesSupported([
+    SigningAlgorithm.RS256,
+    SigningAlgorithm.ES256,
+  ])
+  .withScopesSupported(['read', 'write', 'admin'])
+  .build();
+
+// Serve metadata from the standard RFC 9728 endpoint
+app.get('/.well-known/oauth-protected-resource', (req, res) => {
+  res.json(metadata.toJSON());
 });
 ```
 
diff --git a/packages/auth0-api-js/src/index.ts b/packages/auth0-api-js/src/index.ts
@@ -1,3 +1,4 @@
 export { ApiClient } from './api-client.js';
+export * from './protected-resource-metadata.js';
 export * from './errors.js';
 export * from './types.js';
diff --git a/packages/auth0-api-js/src/protected-resource-metadata.spec.ts b/packages/auth0-api-js/src/protected-resource-metadata.spec.ts
@@ -0,0 +1,213 @@
+import { describe, it, expect } from "vitest";
+import {
+  ProtectedResourceMetadataBuilder,
+  AuthorizationScheme,
+  TokenEndpointAuthMethod,
+  SigningAlgorithm,
+} from "./protected-resource-metadata.js";
+import { MissingRequiredArgumentError } from "./errors.js";
+
+describe("ProtectedResourceMetadataBuilder", () => {
+  const VALID_RESOURCE = "http://localhost:3001/mcp";
+  const VALID_AUTH_SERVERS = ["https://a0-mcp.us.auth0.com"];
+
+  describe("constructor", () => {
+    it("should create builder instance with required parameters", () => {
+      const builder = new ProtectedResourceMetadataBuilder(
+        VALID_RESOURCE,
+        VALID_AUTH_SERVERS
+      );
+      const metadata = builder.build();
+      const json = metadata.toJSON();
+
+      expect(json.resource).toBe(VALID_RESOURCE);
+      expect(json.authorization_servers).toEqual(VALID_AUTH_SERVERS);
+      expect(json.authorization_servers).not.toBe(VALID_AUTH_SERVERS); // Should be a copy
+    });
+
+    it("should throw error for invalid parameters", () => {
+      expect(
+        () => new ProtectedResourceMetadataBuilder("", VALID_AUTH_SERVERS)
+      ).toThrow(MissingRequiredArgumentError);
+
+      expect(
+        () => new ProtectedResourceMetadataBuilder("   ", VALID_AUTH_SERVERS)
+      ).toThrow(MissingRequiredArgumentError);
+
+      expect(
+        () => new ProtectedResourceMetadataBuilder(VALID_RESOURCE, [])
+      ).toThrow(MissingRequiredArgumentError);
+    });
+  });
+
+  describe("builder methods", () => {
+    it("should build complex metadata with fluent interface", () => {
+      const metadata = new ProtectedResourceMetadataBuilder(
+        VALID_RESOURCE,
+        VALID_AUTH_SERVERS
+      )
+        .withBearerMethodsSupported([AuthorizationScheme.BEARER])
+        .withTokenEndpointAuthMethodsSupported([
+          TokenEndpointAuthMethod.CLIENT_SECRET_BASIC,
+          TokenEndpointAuthMethod.CLIENT_SECRET_POST,
+          TokenEndpointAuthMethod.PRIVATE_KEY_JWT,
+        ])
+        .withTokenEndpointAuthSigningAlgValuesSupported([
+          SigningAlgorithm.RS256,
+          SigningAlgorithm.ES256,
+        ])
+        .withScopesSupported(["read", "write", "admin"])
+        .build();
+
+      const json = metadata.toJSON();
+      expect(json.resource).toBe(VALID_RESOURCE);
+      expect(json.authorization_servers).toEqual(VALID_AUTH_SERVERS);
+      expect(json.bearer_methods_supported).toEqual([
+        AuthorizationScheme.BEARER,
+      ]);
+      expect(json.token_endpoint_auth_methods_supported).toEqual([
+        TokenEndpointAuthMethod.CLIENT_SECRET_BASIC,
+        TokenEndpointAuthMethod.CLIENT_SECRET_POST,
+        TokenEndpointAuthMethod.PRIVATE_KEY_JWT,
+      ]);
+      expect(json.token_endpoint_auth_signing_alg_values_supported).toEqual([
+        SigningAlgorithm.RS256,
+        SigningAlgorithm.ES256,
+      ]);
+      expect(json.scopes_supported).toEqual(["read", "write", "admin"]);
+    });
+
+    it("should support builder chaining", () => {
+      const baseBuilder = new ProtectedResourceMetadataBuilder(
+        VALID_RESOURCE,
+        VALID_AUTH_SERVERS
+      );
+      const scopes = ["read", "write"];
+      const builderWithScopes = baseBuilder.withScopesSupported(scopes);
+
+      // Both references point to the same builder instance
+      expect(builderWithScopes).toBe(baseBuilder);
+
+      const metadata = baseBuilder.build();
+      const json = metadata.toJSON();
+
+      // The builder should have the scopes that were added
+      expect(json.scopes_supported).toEqual(scopes);
+
+      // Test array cloning - returned arrays should be copies
+      expect(json.scopes_supported).not.toBe(scopes);
+      expect(json.authorization_servers).not.toBe(VALID_AUTH_SERVERS);
+    });
+  });
+
+  describe("serialization", () => {
+    it("should convert to JSON with only defined properties", () => {
+      const jwksUri = "https://example.com/.well-known/jwks.json";
+      const metadata = new ProtectedResourceMetadataBuilder(
+        VALID_RESOURCE,
+        VALID_AUTH_SERVERS
+      )
+        .withJwksUri(jwksUri)
+        .withScopesSupported(["read", "write"])
+        .build();
+
+      const json = metadata.toJSON();
+
+      expect(json).toEqual({
+        resource: VALID_RESOURCE,
+        authorization_servers: VALID_AUTH_SERVERS,
+        jwks_uri: jwksUri,
+        scopes_supported: ["read", "write"],
+      });
+    });
+
+    it("should serialize metadata correctly", () => {
+      const metadata = new ProtectedResourceMetadataBuilder(
+        VALID_RESOURCE,
+        VALID_AUTH_SERVERS
+      )
+        .withScopesSupported(["read", "write"])
+        .withBearerMethodsSupported([AuthorizationScheme.BEARER])
+        .withTokenEndpointAuthMethodsSupported([
+          TokenEndpointAuthMethod.CLIENT_SECRET_BASIC,
+        ])
+        .build();
+
+      const json = metadata.toJSON();
+
+      expect(json.resource).toBe(VALID_RESOURCE);
+      expect(json.authorization_servers).toEqual(VALID_AUTH_SERVERS);
+      expect(json.scopes_supported).toEqual(["read", "write"]);
+      expect(json.bearer_methods_supported).toEqual([
+        AuthorizationScheme.BEARER,
+      ]);
+      expect(json.token_endpoint_auth_methods_supported).toEqual([
+        TokenEndpointAuthMethod.CLIENT_SECRET_BASIC,
+      ]);
+
+      // Arrays in JSON should be copies, not the same references
+      expect(json.authorization_servers).not.toBe(VALID_AUTH_SERVERS);
+      expect(json.scopes_supported).not.toBe(["read", "write"]);
+    });
+
+    it("should only include defined properties in JSON output", () => {
+      const metadata = new ProtectedResourceMetadataBuilder(
+        VALID_RESOURCE,
+        VALID_AUTH_SERVERS
+      )
+        .withScopesSupported(["read"])
+        .build();
+
+      const json = metadata.toJSON();
+
+      expect(json).toHaveProperty("resource");
+      expect(json).toHaveProperty("authorization_servers");
+      expect(json).toHaveProperty("scopes_supported");
+      expect(json).not.toHaveProperty("jwks_uri");
+      expect(json).not.toHaveProperty("bearer_methods_supported");
+    });
+  });
+
+  describe("data integrity", () => {
+    it("should return immutable JSON arrays", () => {
+      const metadata = new ProtectedResourceMetadataBuilder(
+        VALID_RESOURCE,
+        VALID_AUTH_SERVERS
+      )
+        .withScopesSupported(["read", "write"])
+        .build();
+
+      const json = metadata.toJSON();
+      const json2 = metadata.toJSON();
+
+      // Each call to toJSON should return new array instances
+      expect(json.authorization_servers).not.toBe(json2.authorization_servers);
+      expect(json.scopes_supported).not.toBe(json2.scopes_supported);
+
+      // But with same content
+      expect(json.authorization_servers).toEqual(json2.authorization_servers);
+      expect(json.scopes_supported).toEqual(json2.scopes_supported);
+    });
+
+    it("should not share array references with input data", () => {
+      const scopes = ["read", "write"];
+      const authServers = [...VALID_AUTH_SERVERS];
+
+      const metadata = new ProtectedResourceMetadataBuilder(
+        VALID_RESOURCE,
+        authServers
+      )
+        .withScopesSupported(scopes)
+        .build();
+
+      const json = metadata.toJSON();
+
+      // Modifying original arrays should not affect the metadata
+      scopes.push("admin");
+      authServers.push("new-server");
+
+      expect(json.scopes_supported).toEqual(["read", "write"]);
+      expect(json.authorization_servers).toEqual(VALID_AUTH_SERVERS);
+    });
+  });
+});
diff --git a/packages/auth0-api-js/src/protected-resource-metadata.ts b/packages/auth0-api-js/src/protected-resource-metadata.ts
