Implement RFC 8707 resource indicators

README.md

@@ -304,6 +304,49 @@ const verified = await client.verify(subjects, accessToken)
 console.log(verified.subject)
 ```
 
+#### Resource Indicators
+
+Use the `resource` parameter to request audience‑restricted access tokens.
+
+- Request a single resource at authorization:
+
+```ts
+const { challenge, url } = await client.authorize(redirect_uri, "code", {
+  pkce: true,
+  resource: ["https://api.myserver.com/"],
+})
+```
+
+- Request consent for a small set, then select one at the token step:
+
+```ts
+const { challenge, url } = await client.authorize(redirect_uri, "code", {
+  pkce: true,
+  resource: ["https://api.myserver.com/", "https://files.myserver.com/"],
+})
+
+// Later at the token step, pick one resource
+const exchanged = await client.exchange(
+  code,
+  redirect_uri,
+  challenge.verifier,
+  { resource: ["https://api.myserver.com/"] },
+)
+```
+
+- Introduce a resource during refresh (when allowed by the original grant):
+
+```ts
+const refreshed = await client.refresh(refreshToken, {
+  resource: ["https://api.myserver.com/"],
+})
+```
+
+Notes:
+
+- The server mints single‑audience access tokens only. If multiple `resource` values are sent to `/token`, the request is rejected with `invalid_target`.
+- Resource values must be absolute URIs without fragments. Prefer network‑addressable locations (for example, `https://api.myserver.com/`).
+
 ---
 
 OpenAuth is created by the maintainers of [SST](https://sst.dev).

packages/openauth/src/client.ts

@@ -178,6 +178,19 @@ export interface AuthorizeOptions {
    * If there's only one provider configured, the user will be redirected to that.
    */
   provider?: string
+  /**
+   * Which resource(s) to request access to at authorization.
+   *
+   * ```ts
+   * {
+   *   resource: ["https://api.myapp.com/", "https://files.myapp.com/"]
+   * }
+   * ```
+   *
+   * If multiple are provided, the server
+   * will record them but will require selecting one when exchanging the token.
+   */
+  resources?: string[]
 }
 
 export interface AuthorizeResult {
@@ -203,6 +216,14 @@ export interface AuthorizeResult {
   url: string
 }
 
+// exchange options
+export interface ExchangeOptions {
+  /**
+   * The resource to request access to.
+   */
+  resource?: string
+}
+
 /**
  * Returned when the exchange is successful.
  */
@@ -239,6 +260,11 @@ export interface RefreshOptions {
    * Optionally, pass in the access token.
    */
   access?: string
+  /**
+   * Optionally specify a resource when refreshing.
+   * The server may restrict this to the set originally authorized.
+   */
+  resource?: string
 }
 
 /**
@@ -436,6 +462,7 @@ export interface Client {
     code: string,
     redirectURI: string,
     verifier?: string,
+    opts?: ExchangeOptions,
   ): Promise<ExchangeSuccess | ExchangeError>
   /**
    * Refreshes the tokens if they have expired. This is used in an SPA app to maintain the
@@ -588,6 +615,15 @@ export function createClient(input: ClientInput): Client {
       result.searchParams.set("response_type", response)
       result.searchParams.set("state", challenge.state)
       if (opts?.provider) result.searchParams.set("provider", opts.provider)
+
+      if (opts?.resources) {
+        const resources = Array.isArray(opts.resources)
+          ? opts.resources
+          : [opts.resources]
+
+        for (const r of resources) result.searchParams.append("resource", r)
+      }
+
       if (opts?.pkce && response === "code") {
         const pkce = await generatePKCE()
         result.searchParams.set("code_challenge_method", "S256")
@@ -622,19 +658,26 @@ export function createClient(input: ClientInput): Client {
       code: string,
       redirectURI: string,
       verifier?: string,
+      opts?: ExchangeOptions,
     ): Promise<ExchangeSuccess | ExchangeError> {
+      const params = new URLSearchParams({
+        code,
+        redirect_uri: redirectURI,
+        grant_type: "authorization_code",
+        client_id: input.clientID,
+        code_verifier: verifier || "",
+      })
+
+      if (opts?.resource) {
+        params.set("resource", opts.resource)
+      }
+
       const tokens = await f(issuer + "/token", {
         method: "POST",
         headers: {
           "Content-Type": "application/x-www-form-urlencoded",
         },
-        body: new URLSearchParams({
-          code,
-          redirect_uri: redirectURI,
-          grant_type: "authorization_code",
-          client_id: input.clientID,
-          code_verifier: verifier || "",
-        }).toString(),
+        body: params.toString(),
       })
       const json = (await tokens.json()) as any
       if (!tokens.ok) {
@@ -669,15 +712,19 @@ export function createClient(input: ClientInput): Client {
           }
         }
       }
+      const params = new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: refresh,
+      })
+
+      if (opts?.resource) params.set("resource", opts.resource)
+
       const tokens = await f(issuer + "/token", {
         method: "POST",
         headers: {
           "Content-Type": "application/x-www-form-urlencoded",
         },
-        body: new URLSearchParams({
-          grant_type: "refresh_token",
-          refresh_token: refresh,
-        }).toString(),
+        body: params.toString(),
       })
       const json = (await tokens.json()) as any
       if (!tokens.ok) {
@@ -717,7 +764,7 @@ export function createClient(input: ClientInput): Client {
             subject: {
               type: result.payload.type,
               properties: validated.value,
-            } as any,
+            } as VerifyResult<T>["subject"],
           }
         return {
           err: new InvalidSubjectError(),

packages/openauth/src/error.ts

@@ -22,6 +22,7 @@ export class OauthError extends Error {
     public error:
       | "invalid_request"
       | "invalid_grant"
+      | "invalid_target"
       | "unauthorized_client"
       | "access_denied"
       | "unsupported_grant_type"