@udibo/oauth2 0.40.1 → 0.42.0

package/dist/adapters/hono/log.d.ts

@@ -1,8 +1,3 @@
-/**
- * Request logging that removes query values, including OAuth callback credentials.
- *
- * @module hono/log
- */
 import type { MiddlewareHandler } from "hono";
 /**
  * Produces a request target with every query value replaced by `[redacted]`.
@@ -26,14 +21,24 @@ import type { MiddlewareHandler } from "hono";
  */
 export declare function redactedRequestTarget(url: string | URL): string;
 /**
- * Logs Hono requests and responses without any query values. Mount before
- * authentication routes so OAuth callback codes and state stay out of logs.
- * Logs method, redacted target, response status, and elapsed milliseconds;
- * does not log headers or bodies. Paths and parameter names remain visible.
+ * Logs each Hono request as one line, written when the response is ready,
+ * without any query values. Mount before authentication routes so OAuth
+ * callback codes and state stay out of logs. Logs method, redacted target,
+ * response status and elapsed milliseconds; does not log headers or bodies.
+ * Paths and parameter names remain visible. A request whose handler throws
+ * something Hono does not answer (a non-`Error`) is still logged, as `500`.
+ *
+ * A request this middleware sees while it is handling another one (the app
+ * calling its own `fetch` from a handler or a server-rendered page's loader) is
+ * folded into the outer request's line, in brackets, in completion order,
+ * instead of writing its own. One that completes after the outer response was
+ * ready gets its own line, marked `(in-process)`; that includes a request
+ * started later from a timer or promise the outer request created. Each
+ * `requestLogger()` call folds only the requests it sees itself, so a sub-app
+ * with its own logger writes to its own sink.
  *
  * @param print Receives each log line; defaults to `console.log`, resolved per line.
- * @returns Middleware emitting a request line and, after downstream completion,
- * a response line.
+ * @returns Middleware emitting one line per request after downstream completion.
  *
  * @example
  * ```ts
@@ -43,6 +48,7 @@ export declare function redactedRequestTarget(url: string | URL): string;
  * const app = new Hono();
  * app.use(requestLogger());
  * app.get("/", (c) => c.text("Hello"));
+ * // --> GET /?code=[redacted] 200 3ms
  * ```
  */
 export declare function requestLogger(print?: (line: string) => void): MiddlewareHandler;

package/dist/adapters/hono/log.js

@@ -1,3 +1,9 @@
+/**
+ * Request logging that removes query values, including OAuth callback credentials.
+ *
+ * @module hono/log
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
 /**
  * Produces a request target with every query value replaced by `[redacted]`.
  * Keeps the pathname and percent-encoded parameter names, including repeats,
@@ -28,15 +34,28 @@ export function redactedRequestTarget(url) {
         .join("&");
     return `${pathname}?${query}`;
 }
+function summary(method, url, status, started) {
+    return `${method} ${redactedRequestTarget(url)} ${status} ${Date.now() - started}ms`;
+}
 /**
- * Logs Hono requests and responses without any query values. Mount before
- * authentication routes so OAuth callback codes and state stay out of logs.
- * Logs method, redacted target, response status, and elapsed milliseconds;
- * does not log headers or bodies. Paths and parameter names remain visible.
+ * Logs each Hono request as one line, written when the response is ready,
+ * without any query values. Mount before authentication routes so OAuth
+ * callback codes and state stay out of logs. Logs method, redacted target,
+ * response status and elapsed milliseconds; does not log headers or bodies.
+ * Paths and parameter names remain visible. A request whose handler throws
+ * something Hono does not answer (a non-`Error`) is still logged, as `500`.
+ *
+ * A request this middleware sees while it is handling another one (the app
+ * calling its own `fetch` from a handler or a server-rendered page's loader) is
+ * folded into the outer request's line, in brackets, in completion order,
+ * instead of writing its own. One that completes after the outer response was
+ * ready gets its own line, marked `(in-process)`; that includes a request
+ * started later from a timer or promise the outer request created. Each
+ * `requestLogger()` call folds only the requests it sees itself, so a sub-app
+ * with its own logger writes to its own sink.
  *
  * @param print Receives each log line; defaults to `console.log`, resolved per line.
- * @returns Middleware emitting a request line and, after downstream completion,
- * a response line.
+ * @returns Middleware emitting one line per request after downstream completion.
  *
  * @example
  * ```ts
@@ -46,15 +65,39 @@ export function redactedRequestTarget(url) {
  * const app = new Hono();
  * app.use(requestLogger());
  * app.get("/", (c) => c.text("Hello"));
+ * // --> GET /?code=[redacted] 200 3ms
  * ```
  */
 export function requestLogger(print) {
     const emit = print ?? ((line) => console.log(line));
+    const outerRequest = new AsyncLocalStorage();
     return async (c, next) => {
-        const target = redactedRequestTarget(c.req.url);
-        emit(`<-- ${c.req.method} ${target}`);
-        const start = Date.now();
-        await next();
-        emit(`--> ${c.req.method} ${target} ${c.res.status} ${Date.now() - start}ms`);
+        const started = Date.now();
+        const outer = outerRequest.getStore();
+        let status = 500;
+        if (outer) {
+            try {
+                await next();
+                status = c.res.status;
+            }
+            finally {
+                const call = summary(c.req.method, c.req.url, status, started);
+                if (outer.answered)
+                    emit(`--> (in-process) ${call}`);
+                else
+                    outer.calls.push(call);
+            }
+            return;
+        }
+        const request = { calls: [], answered: false };
+        try {
+            await outerRequest.run(request, next);
+            status = c.res.status;
+        }
+        finally {
+            request.answered = true;
+            const calls = request.calls.length === 0 ? "" : ` [${request.calls.join(", ")}]`;
+            emit(`--> ${summary(c.req.method, c.req.url, status, started)}${calls}`);
+        }
     };
 }

package/dist/errors.d.ts

@@ -159,6 +159,11 @@ export declare const InsufficientPermissionsError: OAuth2ErrorClass;
  * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1
  */
 export declare const UnsupportedResponseTypeError: OAuth2ErrorClass;
+/**
+ * The requested resource is missing, malformed or not allowed by the server's
+ * resource policy (RFC 8707 section 2). Descriptions should not echo targets.
+ */
+export declare const InvalidTargetError: OAuth2ErrorClass;
 /**
  * The requested scope is invalid, unknown, or malformed.
  *

package/dist/errors.js

@@ -205,6 +205,15 @@ export const UnsupportedResponseTypeError = createHttpErrorClass({
         error: "unsupported_response_type",
     },
 });
+/**
+ * The requested resource is missing, malformed or not allowed by the server's
+ * resource policy (RFC 8707 section 2). Descriptions should not echo targets.
+ */
+export const InvalidTargetError = createHttpErrorClass({
+    name: "Invalid Target",
+    status: 400,
+    extensions: { error: "invalid_target" },
+});
 /**
  * The requested scope is invalid, unknown, or malformed.
  *

package/dist/models/token.d.ts

@@ -18,6 +18,13 @@ export interface Token<Client extends ClientInterface, User, Scope extends Abstr
     client: Client;
     /** The user this token was issued for (if applicable). */
     user?: User;
+    /**
+     * Exact resource URI accepted by an opted-in client-credentials policy
+     * (RFC 8707). Persist and restore it on every token read; never derive it
+     * from a later request or the client's current configuration. Absent for
+     * legacy issuance. Resource authority still belongs to the application.
+     */
+    resource?: string;
     /** The scope granted to this token. */
     scope?: Scope | null;
     /**

package/dist/server/_resource-indicator.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Read zero or one absolute resource URI without a fragment, preserving its
+ * exact spelling. Multiple values, including equal repeats, are refused.
+ * Call only after opting into the single-resource policy.
+ * @throws {InvalidTargetError} For an empty, repeated, non-string or malformed value.
+ */
+export declare function resourceIndicatorOf(body: FormData): string | undefined;

package/dist/server/_resource-indicator.js

@@ -0,0 +1,67 @@
+/** Single-resource syntax for opted-in machine issuance. @module */
+import { InvalidTargetError } from "../errors.js";
+const PATH = /^(?:[A-Za-z0-9._~!$&'()*+,;=:@/-]|%[A-Fa-f0-9]{2})*$/;
+const QUERY = /^(?:[A-Za-z0-9._~!$&'()*+,;=:@/?-]|%[A-Fa-f0-9]{2})*$/;
+const USER_INFO = /^(?:[A-Za-z0-9._~!$&'()*+,;=:-]|%[A-Fa-f0-9]{2})*$/;
+const REG_NAME = /^(?:[A-Za-z0-9._~!$&'()*+,;=-]|%[A-Fa-f0-9]{2})*$/;
+const IP_FUTURE = /^v[0-9a-f]+\.[A-Za-z0-9._~!$&'()*+,;=:-]+$/i;
+function validAuthority(authority) {
+    const at = authority.indexOf("@");
+    if (at !== authority.lastIndexOf("@"))
+        return false;
+    if (at !== -1 && !USER_INFO.test(authority.slice(0, at)))
+        return false;
+    const hostPort = authority.slice(at + 1);
+    if (hostPort.startsWith("[")) {
+        const end = hostPort.indexOf("]");
+        if (end === -1 || !/^(?::[0-9]*)?$/.test(hostPort.slice(end + 1)))
+            return false;
+        const literal = hostPort.slice(1, end);
+        if (IP_FUTURE.test(literal))
+            return true;
+        try {
+            // Native parsing validates an IPv6 literal; no lookup or request occurs.
+            return new URL(`http://[${literal}]`).hostname.startsWith("[");
+        }
+        catch {
+            return false;
+        }
+    }
+    const colon = hostPort.lastIndexOf(":");
+    return colon === -1
+        ? REG_NAME.test(hostPort)
+        : REG_NAME.test(hostPort.slice(0, colon)) &&
+            /^[0-9]*$/.test(hostPort.slice(colon + 1));
+}
+function absoluteUri(value) {
+    const uri = /^[A-Za-z][A-Za-z0-9+.-]*:([^?#]*)(?:\?([^#]*))?$/.exec(value);
+    if (!uri || (uri[2] !== undefined && !QUERY.test(uri[2])))
+        return false;
+    let path = uri[1];
+    if (path.startsWith("//")) {
+        const slash = path.indexOf("/", 2);
+        const authority = slash === -1 ? path.slice(2) : path.slice(2, slash);
+        if (!validAuthority(authority))
+            return false;
+        path = slash === -1 ? "" : path.slice(slash);
+    }
+    return PATH.test(path);
+}
+/**
+ * Read zero or one absolute resource URI without a fragment, preserving its
+ * exact spelling. Multiple values, including equal repeats, are refused.
+ * Call only after opting into the single-resource policy.
+ * @throws {InvalidTargetError} For an empty, repeated, non-string or malformed value.
+ */
+export function resourceIndicatorOf(body) {
+    const values = body.getAll("resource");
+    if (values.length === 0)
+        return undefined;
+    const resource = values[0];
+    if (values.length !== 1 ||
+        typeof resource !== "string" ||
+        !absoluteUri(resource)) {
+        throw new InvalidTargetError("invalid resource");
+    }
+    return resource;
+}

package/dist/server/authorization-server.js

@@ -1162,6 +1162,8 @@ export class AuthorizationServer extends ResourceServer {
                 if (tokenType === "access_token") {
                     response.token_type = "Bearer";
                 }
+                if (token.resource !== undefined)
+                    response.aud = token.resource;
                 if (token.scope) {
                     response.scope = token.scope.toString();
                 }

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

@@ -70,7 +70,13 @@ export declare class ClientCredentialsGrant<Client extends ClientInterface, User
      * `ClientServiceInterface.getUser` resolves for the client, and is left
      * unset when it resolves nothing — a user-less machine token, not a failure.
      *
+     * Resource indicators are opt-in through `tokenService.acceptedResource`:
+     * its presence validates one absolute resource URI and requires explicit
+     * policy acceptance. Its absence preserves legacy extension handling.
+     *
      * @throws {InvalidScopeError} If the requested scope is rejected.
+     * @throws {InvalidTargetError} If opted-in resource validation or policy refuses.
+     * @throws {ServerError} If storage drops or changes an accepted target.
      */
     token(request: Request, client: Client, body: FormData): Promise<Token<Client, User, S>>;
 }

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

@@ -3,7 +3,8 @@
  * RFC 6749 Section 4.4.
  * @module
  */
-import { InvalidClientError } from "../../errors.js";
+import { InvalidClientError, InvalidTargetError, ServerError, } from "../../errors.js";
+import { resourceIndicatorOf } from "../_resource-indicator.js";
 import { authenticateClientCredentials } from "../client-authentication.js";
 import { AbstractGrant, } from "./grant.js";
 /**
@@ -71,7 +72,13 @@ export class ClientCredentialsGrant extends AbstractGrant {
      * `ClientServiceInterface.getUser` resolves for the client, and is left
      * unset when it resolves nothing — a user-less machine token, not a failure.
      *
+     * Resource indicators are opt-in through `tokenService.acceptedResource`:
+     * its presence validates one absolute resource URI and requires explicit
+     * policy acceptance. Its absence preserves legacy extension handling.
+     *
      * @throws {InvalidScopeError} If the requested scope is rejected.
+     * @throws {InvalidTargetError} If opted-in resource validation or policy refuses.
+     * @throws {ServerError} If storage drops or changes an accepted target.
      */
     async token(request, client, body) {
         const { tokenService, clientService } = await this.resolveServices(request);
@@ -80,7 +87,19 @@ export class ClientCredentialsGrant extends AbstractGrant {
         const user = await clientService.getUser(client);
         const acceptedScope = await this.acceptedScope(client, user, scope, tokenService);
         scope = acceptedScope ?? undefined;
-        const token = await this.generateToken(client, user, scope, tokenService);
-        return await tokenService.save(token);
+        let resource;
+        const resourcePolicy = tokenService.acceptedResource;
+        if (resourcePolicy !== undefined) {
+            resource = resourceIndicatorOf(body);
+            if ((await resourcePolicy.call(tokenService, client, user, resource, scope)) !== true) {
+                throw new InvalidTargetError("invalid resource");
+            }
+        }
+        const token = await this.generateToken(client, user, scope, tokenService, undefined, undefined, resource);
+        const saved = await tokenService.save(token);
+        if (resourcePolicy !== undefined && saved.resource !== resource) {
+            throw new ServerError("token storage did not preserve resource");
+        }
+        return saved;
     }
 }

package/dist/server/grants/grant.d.ts

@@ -150,9 +150,11 @@ export declare abstract class AbstractGrant<Client extends ClientInterface, User
      * for tokens with no user. `familyExpiresAt` is the ceiling of an existing
      * rotation family the token joins (the refresh grant passes it); the
      * expiries are clamped to it before the access token string is generated,
-     * so a signed token's `exp` matches the stored expiry.
+     * so a signed token's `exp` matches the stored expiry. `resource` is the
+     * exact URI accepted by the client-credentials resource policy; it is
+     * retained in the token and passed to audience-aware generation.
      */
-    generateToken(client: Client, user: User | undefined, scope: Scope | null | undefined, tokenService: TokenServiceInterface<Client, User, Scope>, authenticationContext?: AuthenticationContext, familyExpiresAt?: Date): Promise<Token<Client, User, Scope>>;
+    generateToken(client: Client, user: User | undefined, scope: Scope | null | undefined, tokenService: TokenServiceInterface<Client, User, Scope>, authenticationContext?: AuthenticationContext, familyExpiresAt?: Date, resource?: string): Promise<Token<Client, User, Scope>>;
     /**
      * Authenticates the client presenting this grant's token request against the
      * grant's own `clientService`, from the credentials the request presents.

package/dist/server/grants/grant.js

@@ -118,13 +118,17 @@ export class AbstractGrant {
      * for tokens with no user. `familyExpiresAt` is the ceiling of an existing
      * rotation family the token joins (the refresh grant passes it); the
      * expiries are clamped to it before the access token string is generated,
-     * so a signed token's `exp` matches the stored expiry.
+     * so a signed token's `exp` matches the stored expiry. `resource` is the
+     * exact URI accepted by the client-credentials resource policy; it is
+     * retained in the token and passed to audience-aware generation.
      */
-    async generateToken(client, user, scope, tokenService, authenticationContext, familyExpiresAt) {
+    async generateToken(client, user, scope, tokenService, authenticationContext, familyExpiresAt, resource) {
         const event = user === undefined
             ? undefined
             : snapshotAuthenticationContext(authenticationContext);
         const token = { accessToken: "", client };
+        if (resource !== undefined)
+            token.resource = resource;
         if (event)
             token.authenticationContext = event;
         if (user !== undefined)
@@ -162,7 +166,17 @@ export class AbstractGrant {
         }
         if (ceiling)
             this.capAtFamilyExpiry(result, ceiling);
-        result.accessToken = await tokenService.generateAccessToken(client, user, scope, event, result.accessTokenExpiresAt);
+        const generation = [
+            client,
+            user,
+            scope,
+            event,
+            result.accessTokenExpiresAt,
+        ];
+        result.accessToken =
+            resource === undefined
+                ? await tokenService.generateAccessToken(...generation)
+                : await tokenService.generateAccessToken(...generation, resource);
         return result;
     }
     /**

package/dist/server/grants/refresh-token.d.ts

@@ -115,6 +115,8 @@ export declare class RefreshTokenGrant<Client extends ClientInterface, User, S e
      * claimed it.
      * @throws {InvalidClientError} If the token was issued to another client.
      * @throws {InvalidScopeError} If the requested scope exceeds the original grant.
+     * @throws {InvalidTargetError} If a stored parent is resource-bound; refreshing
+     * such a grant is unsupported and refuses before spending the parent.
      */
     token(request: Request, client: Client, body: FormData): Promise<RefreshToken<Client, User, S>>;
 }

package/dist/server/grants/refresh-token.js

@@ -3,7 +3,7 @@
  * RFC 6749 Section 6.
  * @module
  */
-import { InvalidClientError, InvalidGrantError, InvalidRequestError, InvalidScopeError, } from "../../errors.js";
+import { InvalidClientError, InvalidGrantError, InvalidRequestError, InvalidScopeError, InvalidTargetError, } from "../../errors.js";
 import { AbstractGrant, } from "./grant.js";
 const REPLAY_GRACE_CLOCK_TOLERANCE_SECONDS = 300;
 /**
@@ -56,6 +56,8 @@ export class RefreshTokenGrant extends AbstractGrant {
      * claimed it.
      * @throws {InvalidClientError} If the token was issued to another client.
      * @throws {InvalidScopeError} If the requested scope exceeds the original grant.
+     * @throws {InvalidTargetError} If a stored parent is resource-bound; refreshing
+     * such a grant is unsupported and refuses before spending the parent.
      */
     async token(request, client, body) {
         const { tokenService } = await this.resolveServices(request);
@@ -92,6 +94,11 @@ export class RefreshTokenGrant extends AbstractGrant {
         if (client.id.toString() !== tokenClient.id.toString()) {
             throw new InvalidClientError("refresh_token was issued to another client");
         }
+        if (currentToken.resource !== undefined) {
+            // Resource-bound refresh is not implemented. Never spend the parent or
+            // issue a successor that silently loses its audience restriction.
+            throw new InvalidTargetError("resource-bound refresh is not supported");
+        }
         // RFC 6749 §6: a requested scope may only narrow, never exceed, the original grant.
         let nextScope = scope;
         const requestedScopeText = body.get("scope");

package/dist/server/mod.d.ts

@@ -15,7 +15,7 @@ export { AbstractScope, BasicScope } from "../models/scope.ts";
 export type { ScopeConstructor } from "../models/scope.ts";
 export { Authorization, authorizationFromClaims, } from "../models/authorization.ts";
 export type { AuthorizationFailure, AuthorizationInit, OrganizationContext, RequireConditions, } from "../models/authorization.ts";
-export { AccessDeniedError, AccountSelectionRequiredError, AuthorizationPendingError, ConsentRequiredError, ExpiredTokenError, InsufficientPermissionsError, InsufficientScopeError, InteractionRequiredError, InvalidClientError, InvalidGrantError, InvalidRequestError, InvalidScopeError, InvalidTokenError, isOAuth2Error, LoginRequiredError, OAuth2Error, ServerError, SlowDownError, TemporarilyUnavailableError, toOAuth2Error, UnauthorizedClientError, UnsupportedGrantTypeError, UnsupportedResponseTypeError, UnsupportedTokenTypeError, } from "../errors.ts";
+export { AccessDeniedError, AccountSelectionRequiredError, AuthorizationPendingError, ConsentRequiredError, ExpiredTokenError, InsufficientPermissionsError, InsufficientScopeError, InteractionRequiredError, InvalidClientError, InvalidGrantError, InvalidRequestError, InvalidScopeError, InvalidTokenError, InvalidTargetError, isOAuth2Error, LoginRequiredError, OAuth2Error, ServerError, SlowDownError, TemporarilyUnavailableError, toOAuth2Error, UnauthorizedClientError, UnsupportedGrantTypeError, UnsupportedResponseTypeError, UnsupportedTokenTypeError, } from "../errors.ts";
 export type { OAuth2ErrorClass, OAuth2ProblemDetailsExtensions, } from "../errors.ts";
 export { type AuthenticationOutcome, satisfiesAuthenticationRequest, } from "./authentication-request.ts";
 export type { TokenReaderInterface } from "./services/token.ts";

package/dist/server/mod.js

@@ -10,6 +10,6 @@
  */
 export { AbstractScope, BasicScope } from "../models/scope.js";
 export { Authorization, authorizationFromClaims, } from "../models/authorization.js";
-export { AccessDeniedError, AccountSelectionRequiredError, AuthorizationPendingError, ConsentRequiredError, ExpiredTokenError, InsufficientPermissionsError, InsufficientScopeError, InteractionRequiredError, InvalidClientError, InvalidGrantError, InvalidRequestError, InvalidScopeError, InvalidTokenError, isOAuth2Error, LoginRequiredError, OAuth2Error, ServerError, SlowDownError, TemporarilyUnavailableError, toOAuth2Error, UnauthorizedClientError, UnsupportedGrantTypeError, UnsupportedResponseTypeError, UnsupportedTokenTypeError, } from "../errors.js";
+export { AccessDeniedError, AccountSelectionRequiredError, AuthorizationPendingError, ConsentRequiredError, ExpiredTokenError, InsufficientPermissionsError, InsufficientScopeError, InteractionRequiredError, InvalidClientError, InvalidGrantError, InvalidRequestError, InvalidScopeError, InvalidTokenError, InvalidTargetError, isOAuth2Error, LoginRequiredError, OAuth2Error, ServerError, SlowDownError, TemporarilyUnavailableError, toOAuth2Error, UnauthorizedClientError, UnsupportedGrantTypeError, UnsupportedResponseTypeError, UnsupportedTokenTypeError, } from "../errors.js";
 export { satisfiesAuthenticationRequest, } from "./authentication-request.js";
 export { checkRedirectUriPattern, isRedirectUriPattern, matchRedirectUri, } from "./redirect-uri.js";

package/dist/server/services/token.d.ts

@@ -49,6 +49,19 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      * @returns The accepted scope, null/undefined to accept as-is, or false to reject.
      */
     acceptedScope(client: Client, user: User | undefined, scope?: Scope | null): Promise<Scope | null | undefined | false>;
+    /**
+     * Opts client-credentials issuance into one RFC 8707 resource per token.
+     * Called after client authentication and scope acceptance, even when no
+     * resource was supplied. Only `true` accepts; other results refuse with
+     * `invalid_target`. The URI is validated and passed unchanged; decide
+     * resource availability, client authority and scope compatibility here.
+     *
+     * Leave this method absent to preserve legacy extension-parameter behavior.
+     * Enabling it requires persisting `Token.resource` and forwarding the sixth
+     * `generateAccessToken` argument to signed-token generation. Other grants
+     * do not support resource indicators yet.
+     */
+    acceptedResource?(client: Client, user: User | undefined, resource: string | undefined, scope?: Scope | null): Promise<boolean>;
     /**
      * Generates an access token string. `user` is `undefined` for a client
      * acting as its own resource owner (client credentials) — a signed-token
@@ -60,8 +73,11 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      * a signed token's `exp` never outlives what the server itself honors; the
      * grants always pass it, and a wrapper that drops it leaves offline
      * verifiers accepting the token past its stored expiry.
+     * `resource`, when supplied by an opted-in machine grant, is the accepted
+     * target URI. A signed token must restrict its audience to this value;
+     * dropping it can issue a token for a different API.
      */
-    generateAccessToken(client: Client, user: User | undefined, scope?: Scope | null, authenticationContext?: AuthenticationContext, expiresAt?: Date): Promise<string>;
+    generateAccessToken(client: Client, user: User | undefined, scope?: Scope | null, authenticationContext?: AuthenticationContext, expiresAt?: Date, resource?: string): Promise<string>;
     /** Generates a refresh token string. */
     generateRefreshToken(client: Client, user: User, scope?: Scope | null): Promise<string | undefined>;
     /**
@@ -99,6 +115,8 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      * Persists either token kind and returns the saved record. Preserve
      * `authenticationContext` on save and every read, including refresh and
      * revoked records; never reconstruct it from a user's current session.
+     * Preserve `resource` exactly too when resource policy is enabled. The
+     * client-credentials grant refuses a saved result that loses its binding.
      */
     save(token: Token<Client, User, Scope> | RefreshToken<Client, User, Scope>): Promise<Token<Client, User, Scope> | RefreshToken<Client, User, Scope>>;
     /** Revokes a token record. Resolves true if a token was revoked. */
@@ -342,7 +360,7 @@ export declare abstract class AbstractTokenService<Client extends ClientInterfac
      */
     acceptedScope(_client: Client, _user: User | undefined, scope?: Scope | null): Promise<Scope | null | undefined | false>;
     /** Generates an opaque access token string. Override to issue a different format. */
-    generateAccessToken(_client: Client, _user: User | undefined, _scope?: Scope | null, _authenticationContext?: AuthenticationContext, _expiresAt?: Date): Promise<string>;
+    generateAccessToken(_client: Client, _user: User | undefined, _scope?: Scope | null, _authenticationContext?: AuthenticationContext, _expiresAt?: Date, _resource?: string): Promise<string>;
     /** Generates an opaque refresh token string. Override to issue a different format. */
     generateRefreshToken(_client: Client, _user: User, _scope?: Scope | null): Promise<string | undefined>;
     /** Computes the access token expiry as now plus {@linkcode accessTokenLifetime}. */

package/dist/server/services/token.js

@@ -52,7 +52,7 @@ export class AbstractTokenService {
         return Promise.resolve(scope);
     }
     /** Generates an opaque access token string. Override to issue a different format. */
-    generateAccessToken(_client, _user, _scope, _authenticationContext, _expiresAt) {
+    generateAccessToken(_client, _user, _scope, _authenticationContext, _expiresAt, _resource) {
         return Promise.resolve(crypto.randomUUID());
     }
     /** Generates an opaque refresh token string. Override to issue a different format. */

package/dist/server/signing-keys.d.ts

@@ -180,6 +180,8 @@ export declare function createJwtAccessTokenGenerator(options: {
      * The `aud` claim — per RFC 9068 an identifier of the resource server(s)
      * the token is intended for (e.g. `https://api.example.com`). Defaults to
      * the client id, which single-resource validators must then accept.
+     * An accepted resource passed as the returned function's sixth argument
+     * overrides this default, restricting the JWT to that exact target.
      */
     audience?: string;
     /**
@@ -214,4 +216,4 @@ export declare function createJwtAccessTokenGenerator(options: {
     id: string;
 }, user: unknown, scope?: {
     toString(): string;
-} | null, authenticationContext?: AuthenticationContext, expiresAt?: Date) => Promise<string>;
+} | null, authenticationContext?: AuthenticationContext, expiresAt?: Date, resource?: string) => Promise<string>;

package/dist/server/signing-keys.js

@@ -212,7 +212,7 @@ export async function verifyJwt(jwt, publicJwk, options = {}) {
 export function createJwtAccessTokenGenerator(options) {
     const lifetime = options.lifetimeSeconds ?? 3600;
     const subjectOf = options.subjectOf ?? defaultSubjectOf;
-    return async (client, user, scope, authenticationContext, expiresAt) => {
+    return async (client, user, scope, authenticationContext, expiresAt, resource) => {
         const event = user
             ? snapshotAuthenticationContext(authenticationContext)
             : undefined;
@@ -229,7 +229,7 @@ export function createJwtAccessTokenGenerator(options) {
             iss: options.issuer,
             sub: user ? subjectOf(user) : client.id,
             client_id: client.id,
-            aud: options.audience ?? client.id,
+            aud: resource ?? options.audience ?? client.id,
             iat: now,
             exp: Math.min(now + lifetime, storedExp),
             jti: crypto.randomUUID(),

package/dist/testing/contract/token.d.ts

@@ -54,6 +54,13 @@ export interface TokenServiceContractOptions<C extends ClientInterface, U extend
      * vocabulary, for example `"openid"`. Defaults to `"read"`.
      */
     supportedScope?: string;
+    /**
+     * A resource URI whose exact token save/read round trip to check. Supply it
+     * when this store supports opted-in resource-bound machine issuance; leave
+     * absent for stores that only support legacy issuance. This tests storage,
+     * not the application's resource authorization policy.
+     */
+    supportedResource?: string;
     /**
      * Returns a new rotation-family id the store accepts as a
      * {@linkcode RefreshToken.familyId}, distinct on every call. The family cases

package/dist/testing/contract/token.js

@@ -89,6 +89,23 @@ export function runTokenServiceContractTests(options) {
             assert(claimed);
             await tokenService.save(next);
         }
+        if (options.supportedResource !== undefined) {
+            for (const withUser of [false, true]) {
+                it(`preserves the exact resource through save and lookup with${withUser ? "" : "out"} a user`, async () => {
+                    const resource = options.supportedResource;
+                    const token = {
+                        accessToken: await tokenService.generateAccessToken(client, withUser ? user : undefined),
+                        client,
+                        scope: makeScope(supportedScope),
+                        resource,
+                        ...(withUser ? { user } : {}),
+                    };
+                    expect((await tokenService.save(token)).resource).toBe(resource);
+                    const read = await tokenService.getToken(token.accessToken);
+                    expect(read?.resource, "a store must retain the accepted target, not just return its input from save").toBe(resource);
+                });
+            }
+        }
         describe("generateAccessToken / generateRefreshToken", () => {
             it("produces unique access tokens", async () => {
                 const a = await tokenService.generateAccessToken(client, user);

package/dist/testing/services.js

@@ -307,6 +307,8 @@ export class MemoryTokenService {
             scope: stored.scope,
             authenticationContext: snapshotAuthenticationContext(stored.authenticationContext),
         };
+        if (stored.resource !== undefined)
+            token.resource = stored.resource;
         if (stored.refreshTokenHash) {
             return {
                 ...token,
@@ -352,6 +354,8 @@ export class MemoryTokenService {
             scope: token.scope,
             authenticationContext: snapshotAuthenticationContext(token.authenticationContext),
         };
+        if (token.resource !== undefined)
+            stored.resource = token.resource;
         if (token.code)
             stored.codeHash = await sha256Hash(token.code);
         if (token.codeVerifierHash) {

package/package.json

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