feat: Provide request claims during introspection

joachimvh · joachimvh · commit 1e6e6f4175a8 · 2025-10-07T14:18:26.000+02:00
diff --git a/packages/css/src/uma/UmaClient.ts b/packages/css/src/uma/UmaClient.ts
@@ -24,13 +24,15 @@ export interface Claims {
 export interface UmaPermission {
   resource_id: string,
   resource_scopes: string[],
+  policies?: string[],
   exp?: number,
   iat?: number,
   nbf?: number,
 }
 
 export type UmaClaims = JWTPayload & {
   permissions?: UmaPermission[],
+  requestClaims?: NodeJS.Dict<unknown>,
 }
 
 export interface UmaConfig {
@@ -232,7 +234,7 @@ export class UmaClient implements SingleThreaded {
     }
 
     const jwt = await res.json();
-    if (jwt.active !== 'true') throw new Error(`The provided UMA RPT is not active.`);
+    if (jwt.active !== true) throw new Error(`The provided UMA RPT is not active.`);
 
     return await this.verifyTokenData(jwt, config.issuer, config.jwks_uri);
   }
diff --git a/packages/uma/src/dialog/BaseNegotiator.ts b/packages/uma/src/dialog/BaseNegotiator.ts
@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { ClaimSet } from '../credentials/ClaimSet';
 import { Ticket } from '../ticketing/Ticket';
 import { Verifier } from '../credentials/verify/Verifier';
 import { TokenFactory } from '../tokens/TokenFactory';
@@ -50,7 +51,7 @@ export class BaseNegotiator implements Negotiator {
     this.logger.debug(`Processing ticket. ${JSON.stringify(ticket)}`);
 
     // Process pushed credentials
-    const updatedTicket = await this.processCredentials(input, ticket);
+    const { ticket: updatedTicket, claims } = await this.processCredentials(input, ticket);
     this.logger.debug(`resolved result ${JSON.stringify(updatedTicket)}`);
 
     // Try to resolve ticket ...
@@ -61,7 +62,7 @@ export class BaseNegotiator implements Negotiator {
     if (resolved.success) {
 
       // Retrieve / create instantiated policy
-      const { token, tokenType } = await this.tokenFactory.serialize({ permissions: resolved.value });
+      const { token, tokenType } = await this.tokenFactory.serialize({ permissions: resolved.value }, claims);
       this.logger.debug(`Minted token ${JSON.stringify(token)}`);
 
       // TODO:: test logging
@@ -129,7 +130,8 @@ export class BaseNegotiator implements Negotiator {
    *
    * @returns An updated Ticket in which the Credentials have been validated.
    */
-  protected async processCredentials(input: DialogInput, ticket: Ticket): Promise<Ticket> {
+  protected async processCredentials(input: DialogInput, ticket: Ticket):
+    Promise<{ ticket: Ticket, claims?: ClaimSet }> {
     const { claim_token: token, claim_token_format: format } = input;
 
     if (token || format) {
@@ -138,10 +140,10 @@ export class BaseNegotiator implements Negotiator {
 
       const claims = await this.verifier.verify({ token, format });
 
-      return await this.ticketingStrategy.validateClaims(ticket, claims);
+      return { ticket: await this.ticketingStrategy.validateClaims(ticket, claims), claims };
     }
 
-    return ticket;
+    return { ticket };
   }
 
   /**
diff --git a/packages/uma/src/dialog/ContractNegotiator.ts b/packages/uma/src/dialog/ContractNegotiator.ts
@@ -57,7 +57,7 @@ export class ContractNegotiator extends BaseNegotiator {
     this.logger.debug(`Processing ticket. ${JSON.stringify(ticket)}`);
 
     // Process pushed credentials
-    const updatedTicket = await this.processCredentials(input, ticket);
+    const { ticket: updatedTicket } = await this.processCredentials(input, ticket);
     this.logger.debug(`Processed credentials ${JSON.stringify(updatedTicket)}`);
 
     // TODO:
diff --git a/packages/uma/src/routes/Introspection.ts b/packages/uma/src/routes/Introspection.ts
@@ -1,4 +1,5 @@
 import { BadRequestHttpError, getLoggerFor, UnauthorizedHttpError } from '@solid/community-server';
+import { ClaimSet } from '../credentials/ClaimSet';
 import { TokenFactory } from '../tokens/TokenFactory';
 import { HttpHandler, HttpHandlerContext, HttpHandlerResponse } from '../util/http/models/HttpHandler';
 import { verifyRequest } from '../util/HttpMessageSignatures';
@@ -8,8 +9,10 @@ type IntrospectionResponse = {
   active : boolean,
   permissions: {
     resource_id: string,
-    resource_scopes: string[]
+    resource_scopes: string[],
+    policies?: string[],
   }[],
+  requestClaims?: ClaimSet,
   exp?: number,
   iat?: number,
   nbf?: number,
@@ -43,10 +46,10 @@ export class IntrospectionHandler extends HttpHandler {
     const token = new URLSearchParams(request.body as Record<string, string>).get('token');
     try {
       if (!token) throw new Error('could not extract token from request body')
-      const unsignedToken = await this.tokenFactory.deserialize(token);
+      const { token: unsignedToken, claims } = await this.tokenFactory.deserialize(token);
       return {
         status: 200,
-        body: { ...unsignedToken, active: true },
+        body: { ...unsignedToken, requestClaims: claims, active: true },
       };
     } catch (e) {
       this.logger.warn(`Token introspection failed: ${e}`)
diff --git a/packages/uma/src/tokens/JwtTokenFactory.ts b/packages/uma/src/tokens/JwtTokenFactory.ts
@@ -7,10 +7,9 @@ import {
   KeyValueStorage
 } from '@solid/community-server';
 import { randomUUID } from 'node:crypto';
+import { ClaimSet } from '../credentials/ClaimSet';
 import { SerializedToken , TokenFactory} from './TokenFactory';
 import { AccessToken } from './AccessToken';
-import { array, reType } from '../util/ReType';
-import { Permission } from '../views/Permission';
 
 const AUD = 'solid';
 
@@ -35,7 +34,7 @@ export class JwtTokenFactory extends TokenFactory {
   constructor(
     protected readonly keyGen: JwkGenerator,
     protected readonly issuer: string,
-    protected readonly tokenStore: KeyValueStorage<string, AccessToken>,
+    protected readonly tokenStore: KeyValueStorage<string, { token: AccessToken, claims?: ClaimSet }>,
     protected readonly params: JwtTokenParams = { expirationTime: '30m', aud: 'solid' },
   ) {
     super();
@@ -44,9 +43,10 @@ export class JwtTokenFactory extends TokenFactory {
   /**
    * Serializes an Access Token into a JWT
    * @param {AccessToken} token - authenticated and authorized principal
+   * @param claims - claims used to acquire this token
    * @return {Promise<SerializedToken>} - access token response
    */
-  public async serialize(token: AccessToken): Promise<SerializedToken> {
+  public async serialize(token: AccessToken, claims?: ClaimSet): Promise<SerializedToken> {
     const key = await this.keyGen.getPrivateKey();
     const jwk = await importJWK(key, key.alg);
     const jwt = await new SignJWT({ permissions: token.permissions, contract: token.contract })
@@ -59,37 +59,21 @@ export class JwtTokenFactory extends TokenFactory {
       .sign(jwk);
 
     this.logger.debug(`Issued new JWT Token ${JSON.stringify(token)}`);
-    await this.tokenStore.set(jwt, token);
+    await this.tokenStore.set(jwt, { token, claims });
     return { token: jwt, tokenType: 'Bearer' };
   }
 
   /**
    * Deserializes a JWT into an Access Token
    * @param {string} token - JWT access token
-   * @return {Promise<AccessToken>} - deserialized access token
+   * @return {Promise<AccessToken>} - deserialized access token and claims
    */
-  public async deserialize(token: string): Promise<AccessToken> {
-    const key = await this.keyGen.getPublicKey();
-    const jwk = await importJWK(key, key.alg);
-    try {
-      const { payload } = await jwtVerify(token, jwk, {
-        issuer: this.issuer,
-        audience: this.params.aud ?? AUD,
-      });
-
-      if (!payload.permissions) {
-        throw new Error('missing required "permissions" claim.');
-      }
-
-      const permissions = payload.permissions;
-
-      reType(permissions, array(Permission));
-
-      return { permissions };
-    } catch (error: unknown) {
-      const msg = `Invalid Access Token provided, error while parsing: ${createErrorMessage(error)}`;
-      this.logger.warn(msg);
-      throw new BadRequestHttpError(msg);
+  public async deserialize(token: string): Promise<{ token: AccessToken, claims?: ClaimSet }> {
+    // TODO: might want to move this behaviour outside of this class as it is the same for all factories
+    const result = await this.tokenStore.get(token);
+    if (!result) {
+      throw new BadRequestHttpError('Invalid Access Token provided');
     }
+    return result;
   }
 }
diff --git a/packages/uma/src/tokens/OpaqueTokenFactory.ts b/packages/uma/src/tokens/OpaqueTokenFactory.ts
@@ -1,5 +1,6 @@
-import { KeyValueStorage } from '@solid/community-server';
+import { BadRequestHttpError, KeyValueStorage } from '@solid/community-server';
 import { randomUUID } from 'node:crypto';
+import { ClaimSet } from '../credentials/ClaimSet';
 import {AccessToken} from './AccessToken';
 import {SerializedToken, TokenFactory} from './TokenFactory';
 
@@ -11,28 +12,22 @@ export class OpaqueTokenFactory extends TokenFactory {
    *
    * @param {KeyValueStorage<string, AccessToken>} tokenStore
    */
-  constructor(private tokenStore: KeyValueStorage<string, AccessToken>) {
+  constructor(protected readonly tokenStore: KeyValueStorage<string, { token: AccessToken, claims?: ClaimSet }>) {
     super();
   }
 
-  /**
-   *
-   * @param {AccessToken} token
-   * @return {Promise<SerializedToken>}
-   */
-  public async serialize(token: AccessToken): Promise<SerializedToken> {
+  public async serialize(token: AccessToken, claims?: ClaimSet): Promise<SerializedToken> {
     const serialized = randomUUID();
-    await this.tokenStore.set(serialized, token);
+    await this.tokenStore.set(serialized, { token, claims });
     return {tokenType: 'Bearer', token: serialized};
   }
 
-  /**
-   *
-   * @param {string} token
-   */
-  public async deserialize(token: string): Promise<AccessToken> {
-    const retrieved = await this.tokenStore.get(token);
-    if (retrieved) return retrieved;
-    throw new Error('Token string not recognized.');
+  public async deserialize(token: string): Promise<{ token: AccessToken, claims?: ClaimSet }> {
+    // TODO: might want to move this behaviour outside of this class as it is the same for all factories
+    const result = await this.tokenStore.get(token);
+    if (!result) {
+      throw new BadRequestHttpError('Invalid Access Token provided');
+    }
+    return result;
   }
 }
diff --git a/packages/uma/src/tokens/TokenFactory.ts b/packages/uma/src/tokens/TokenFactory.ts
@@ -1,3 +1,4 @@
+import { ClaimSet } from '../credentials/ClaimSet';
 import {AccessToken} from './AccessToken';
 
 export interface SerializedToken {
@@ -11,6 +12,6 @@ export interface SerializedToken {
  * and deserializing gathered tokens
  */
 export abstract class TokenFactory {
-  public abstract serialize(token: AccessToken): Promise<SerializedToken>;
-  public abstract deserialize(token: string): Promise<AccessToken>;
+  public abstract serialize(token: AccessToken, claims?: ClaimSet): Promise<SerializedToken>;
+  public abstract deserialize(token: string): Promise<{ token: AccessToken, claims?: ClaimSet }>;
 }

Original file line number	Diff line number	Diff line change
`@@ -24,13 +24,15 @@ export interface Claims {`
`24`	`24`	`export interface UmaPermission {`
`25`	`25`	`resource_id: string,`
`26`	`26`	`resource_scopes: string[],`
	`27`	`+ policies?: string[],`
`27`	`28`	`exp?: number,`
`28`	`29`	`iat?: number,`
`29`	`30`	`nbf?: number,`
`30`	`31`	`}`
`31`	`32`
`32`	`33`	`export type UmaClaims = JWTPayload & {`
`33`	`34`	`permissions?: UmaPermission[],`
	`35`	`+ requestClaims?: NodeJS.Dict<unknown>,`
`34`	`36`	`}`
`35`	`37`
`36`	`38`	`export interface UmaConfig {`
`@@ -232,7 +234,7 @@ export class UmaClient implements SingleThreaded {`
`232`	`234`	`}`
`233`	`235`
`234`	`236`	`const jwt = await res.json();`
`235`		- if (jwt.active !== 'true') throw new Error(`The provided UMA RPT is not active.`);
	`237`	+ if (jwt.active !== true) throw new Error(`The provided UMA RPT is not active.`);
`236`	`238`
`237`	`239`	`return await this.verifyTokenData(jwt, config.issuer, config.jwks_uri);`
`238`	`240`	`}`