dataspace-client-sdk-node 0.1.2 → 0.2.1

package/src/client.ts

@@ -1,6 +1,9 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { createDidcommPlainMessage } from './builders.js';
 import { buildConsentClaimsSimpleWithCid } from 'gdc-common-utils-ts/utils/consent';
+import { generateServiceId } from 'gdc-common-utils-ts/utils/did';
+import { submitDidcomm, type DidcommFetchInit } from 'gdc-common-utils-ts/utils/didcomm-submit';
+import { ClaimsOfferSchemaorg, ClaimsPersonSchemaorg } from 'gdc-common-utils-ts/constants/schemaorg';
 import {
   MedicationStatementClaimsFhirApi,
   MedicationStatementClaimsFhirApiExtended,
@@ -17,6 +20,7 @@ import type {
   GrantProfessionalAccessSimpleResult,
   DigitalTwinGenerationInput,
   EmployeeDeviceActivationInput,
+  EndpointSelector,
   EmployeeDeviceActivationSimpleInput,
   EmployeeDeviceActivationResult,
   FamilyOrganizationSummary,
@@ -31,6 +35,7 @@ import type {
   PollOptions,
   PollResult,
   OfferPreview,
+  OfferInfo,
   RouteContext,
   SmartTokenExchangeInput,
   SmartTokenExchangeResult,
@@ -163,6 +168,19 @@ export class DataspaceNodeClient {
     return this;
   }
 
+  /**
+   * Builds a deterministic endpoint id for token cache and auth/session reuse.
+   * If `providerDid` is provided, returns a full DID service id:
+   *   did:web:...#section:format:resourceType:action
+   * Otherwise returns the canonical fragment without '#':
+   *   section:format:resourceType:action
+   */
+  public getEndpointId(selector: EndpointSelector, providerDid?: string): string {
+    const fragment = generateServiceId(selector); // #section:format:resourceType:action
+    if (providerDid) return `${providerDid}${fragment}`;
+    return fragment.replace(/^#/, '');
+  }
+
   private resolveSimplePollOptions(timeoutSeconds?: number, intervalSeconds?: number): PollOptions | undefined {
     const pollOptions: PollOptions = {};
     if (Number.isFinite(Number(timeoutSeconds))) {
@@ -518,14 +536,16 @@ export class DataspaceNodeClient {
       ctx,
       apiKey,
       scopes,
-      endpointId = `pkce:${apiKey.slice(0, 8)}`,
+      tokenCacheKey = `pkce:${apiKey.slice(0, 8)}`,
+      endpointId,
       codeVerifier = randomUUID(),
       pollOptions,
     } = options;
 
-    const cached = this._tokenCache.get(endpointId);
+    const cacheKey = String(tokenCacheKey || endpointId || '').trim() || `pkce:${apiKey.slice(0, 8)}`;
+    const cached = this._tokenCache.get(cacheKey);
     if (cached && cached.expiresAt > Date.now() + 30_000) {
-      return { status: 'cached', endpointId, accessToken: cached.accessToken, tokenType: cached.tokenType, scopes: cached.scopes };
+      return { status: 'cached', tokenCacheKey: cacheKey, endpointId: cacheKey, accessToken: cached.accessToken, tokenType: cached.tokenType, scopes: cached.scopes };
     }
 
     const controllerPublicJwk = await this.resolveControllerPublicJwk(options);
@@ -544,7 +564,7 @@ export class DataspaceNodeClient {
       pollOptions,
     );
     if (dcrPoll.status !== 200) {
-      return { status: 'failed', step: '_dcr', endpointId, accessToken: '', tokenType: 'Bearer', scopes };
+      return { status: 'failed', step: '_dcr', tokenCacheKey: cacheKey, endpointId: cacheKey, accessToken: '', tokenType: 'Bearer', scopes };
     }
 
     // Step 2: Code – PKCE S256 challenge
@@ -565,7 +585,7 @@ export class DataspaceNodeClient {
     const codeBody = (codePoll.body as Record<string, unknown>) ?? {};
     const code = String(codeBody['code'] ?? '').trim();
     if (codePoll.status !== 200 || !code) {
-      return { status: 'failed', step: '_code', endpointId, accessToken: '', tokenType: 'Bearer', scopes };
+      return { status: 'failed', step: '_code', tokenCacheKey: cacheKey, endpointId: cacheKey, accessToken: '', tokenType: 'Bearer', scopes };
     }
 
     // Step 3: Token – exchange code + verifier for id_token
@@ -585,7 +605,7 @@ export class DataspaceNodeClient {
     const tokenBody = (tokenPoll.body as Record<string, unknown>) ?? {};
     const idToken = String(tokenBody['id_token'] ?? '').trim();
     if (tokenPoll.status !== 200 || !idToken) {
-      return { status: 'failed', step: '_token', endpointId, accessToken: '', tokenType: 'Bearer', scopes };
+      return { status: 'failed', step: '_token', tokenCacheKey: cacheKey, endpointId: cacheKey, accessToken: '', tokenType: 'Bearer', scopes };
     }
 
     // Step 4: Exchange – id_token → SMART bearer
@@ -608,7 +628,7 @@ export class DataspaceNodeClient {
     const exchangeBody = (exchangePoll.body as Record<string, unknown>) ?? {};
     const accessToken = String(exchangeBody['access_token'] ?? '').trim();
     if (exchangePoll.status !== 200 || !accessToken) {
-      return { status: 'failed', step: '_exchange', endpointId, accessToken: '', tokenType: 'Bearer', scopes };
+      return { status: 'failed', step: '_exchange', tokenCacheKey: cacheKey, endpointId: cacheKey, accessToken: '', tokenType: 'Bearer', scopes };
     }
 
     const tokenType = String(exchangeBody['token_type'] ?? 'Bearer');
@@ -616,22 +636,22 @@ export class DataspaceNodeClient {
     const grantedScopes = grantedScope ? grantedScope.split(' ').filter(Boolean) : scopes;
     const expiresIn = Number(exchangeBody['expires_in'] ?? 0);
 
-    this._tokenCache.set(endpointId, {
+    this._tokenCache.set(cacheKey, {
       accessToken,
       tokenType,
       scopes: grantedScopes,
       expiresAt: Date.now() + expiresIn * 1000,
     });
 
-    return { status: 'fetched', endpointId, accessToken, tokenType, scopes: grantedScopes };
+    return { status: 'fetched', tokenCacheKey: cacheKey, endpointId: cacheKey, accessToken, tokenType, scopes: grantedScopes };
   }
 
   /**
    * Returns the cached SMART bearer for the given endpointId if still valid (>30s remaining).
    * Returns `undefined` if not cached or expired.
    */
-  public getCachedBearerToken(endpointId: string): string | undefined {
-    const cached = this._tokenCache.get(endpointId);
+  public getCachedBearerToken(tokenCacheKey: string): string | undefined {
+    const cached = this._tokenCache.get(tokenCacheKey);
     if (cached && cached.expiresAt > Date.now() + 30_000) {
       return cached.accessToken;
     }
@@ -647,7 +667,8 @@ export class DataspaceNodeClient {
     const {
       clientId,
       scopes,
-      endpointId = `smart-backend:${clientId}`,
+      tokenCacheKey = `smart-backend:${clientId}`,
+      endpointId,
       tokenUrl,
       tokenPath = '/token',
       audience,
@@ -655,12 +676,14 @@ export class DataspaceNodeClient {
       additionalTokenFields,
     } = options;
 
-    const cached = this._tokenCache.get(endpointId);
+    const cacheKey = String(tokenCacheKey || endpointId || '').trim() || `smart-backend:${clientId}`;
+    const cached = this._tokenCache.get(cacheKey);
     if (cached && cached.expiresAt > Date.now() + 30_000) {
       return {
         status: 'cached',
         profile: 'smart-backend.v1',
-        endpointId,
+        tokenCacheKey: cacheKey,
+        endpointId: cacheKey,
         accessToken: cached.accessToken,
         tokenType: cached.tokenType,
         scopes: cached.scopes,
@@ -694,7 +717,8 @@ export class DataspaceNodeClient {
       return {
         status: 'failed',
         profile: 'smart-backend.v1',
-        endpointId,
+        tokenCacheKey: cacheKey,
+        endpointId: cacheKey,
         statusCode: response.status,
         response,
       };
@@ -706,7 +730,7 @@ export class DataspaceNodeClient {
     const expiresIn = Number(body.expires_in ?? 0);
     const expiresAt = Date.now() + expiresIn * 1000;
 
-    this._tokenCache.set(endpointId, {
+    this._tokenCache.set(cacheKey, {
       accessToken,
       tokenType,
       scopes: grantedScopes,
@@ -716,7 +740,8 @@ export class DataspaceNodeClient {
     return {
       status: 'fetched',
       profile: 'smart-backend.v1',
-      endpointId,
+      tokenCacheKey: cacheKey,
+      endpointId: cacheKey,
       statusCode: response.status,
       accessToken,
       tokenType,
@@ -730,13 +755,13 @@ export class DataspaceNodeClient {
    * Exchange token payload against gateway token endpoint and cache the result.
    */
   public async requestSmartToken(input: SmartTokenExchangeInput): Promise<SmartTokenExchangeResult> {
-    const endpointId = String(input.endpointId || '').trim();
-    if (!endpointId) {
-      throw new Error('requestSmartToken requires endpointId.');
+    const tokenCacheKey = String(input.tokenCacheKey || input.endpointId || '').trim();
+    if (!tokenCacheKey) {
+      throw new Error('requestSmartToken requires tokenCacheKey.');
     }
 
     const normalizedScopes = Array.from(new Set((input.scopes || []).filter(Boolean))).sort();
-    const cached = this._tokenCache.get(endpointId);
+    const cached = this._tokenCache.get(tokenCacheKey);
     if (cached && cached.expiresAt > Date.now() + 30_000) {
       return {
         status: 'cached',
@@ -764,7 +789,7 @@ export class DataspaceNodeClient {
       : String(body.scope ?? '').trim().split(' ').filter(Boolean);
     const resolvedScopes = grantedScopes.length ? grantedScopes : normalizedScopes;
     const expiresIn = Number(body.expires_in ?? 0);
-    this._tokenCache.set(endpointId, {
+    this._tokenCache.set(tokenCacheKey, {
       accessToken,
       tokenType,
       scopes: resolvedScopes,
@@ -794,9 +819,9 @@ export class DataspaceNodeClient {
         : undefined,
     );
     const normalizedScopes = Array.from(new Set((input.scopes || []).filter(Boolean))).sort();
-    const endpointId = String(input.endpointId || `smart:${routeCtx.tenantId}:${normalizedScopes.join(',')}`).trim();
-    if (!endpointId) {
-      throw new Error('requestSmartTokenSimple requires endpointId (or non-empty scopes).');
+    const tokenCacheKey = String(input.tokenCacheKey || input.endpointId || `smart:${routeCtx.tenantId}:${normalizedScopes.join(',')}`).trim();
+    if (!tokenCacheKey) {
+      throw new Error('requestSmartTokenSimple requires tokenCacheKey (or non-empty scopes).');
     }
     const pollOptions = this.resolveSimplePollOptions(input.timeoutSeconds, input.intervalSeconds);
 
@@ -831,7 +856,7 @@ export class DataspaceNodeClient {
     const grantedScopes = String(exchangeBody.scope || '').trim().split(' ').filter(Boolean);
     const resolvedScopes = grantedScopes.length ? grantedScopes : normalizedScopes;
     const expiresIn = Number(exchangeBody.expires_in ?? 0);
-    this._tokenCache.set(endpointId, {
+    this._tokenCache.set(tokenCacheKey, {
       accessToken,
       tokenType,
       scopes: resolvedScopes,
@@ -999,6 +1024,34 @@ export class DataspaceNodeClient {
   // ---- Generic batch API --------------------------------------------------
 
   /**
+   * POST a DIDComm bundle payload.
+   * This is the preferred high-level method for DIDComm submission of
+   * FHIR/API bundles (batch, transaction, message, etc.).
+   *
+   * Returns immediately with the HTTP response — pair with `pollUntilComplete` or use `submitAndPoll`.
+   */
+  public async submitBundle(
+    path: string,
+    payload: { thid?: string } & Record<string, unknown>,
+    options?: {
+      mode?: 'plain' | 'strict';
+      recipientEncryptionJwk?: PublicJwk;
+      walletContext?: WalletContext;
+    },
+  ): Promise<SubmitResponse> {
+    const mode = options?.mode ?? 'plain';
+    if (mode === 'strict') {
+      if (!options?.recipientEncryptionJwk || !options?.walletContext) {
+        throw new Error('submitBundle strict mode requires recipientEncryptionJwk and walletContext.');
+      }
+      return this.submitBatchEncrypted(path, payload, options.recipientEncryptionJwk, options.walletContext);
+    }
+    return this.submitBatch(path, payload);
+  }
+
+  /**
+   * @deprecated Use `submitBundle` instead.
+   *
    * POST a DIDComm plaintext payload to a batch submit path.
    * Use this for all `_batch` routes (family registration, observations, tasks, etc.).
    * Content-Type: `application/didcomm-plaintext+json`.
@@ -1006,14 +1059,18 @@ export class DataspaceNodeClient {
    * Returns immediately with the HTTP response — pair with `pollUntilComplete` or use `submitAndPoll`.
    */
   public async submitBatch(path: string, payload: unknown): Promise<SubmitResponse> {
-    const response = await this.doPost(path, payload, 'application/didcomm-plaintext+json');
-    const body = await this.parseResponseBody(response);
-
-    return {
-      status: response.status,
-      location: response.headers.get('location') ?? undefined,
-      body,
-    };
+    const url = /^https?:\/\//.test(path)
+      ? path
+      : `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+    const result = await submitDidcomm({
+      mode: 'plain',
+      url,
+      payload: payload as Record<string, unknown>,
+      defaultHeaders: this.defaultHeaders,
+      bearerToken: this.bearerToken,
+      fetcher: (requestUrl: string, init: DidcommFetchInit) => fetch(requestUrl, init),
+    });
+    return { status: result.status, location: result.location, body: result.body };
   }
 
   /**
@@ -1038,42 +1095,34 @@ export class DataspaceNodeClient {
     const publicJwks = await this.wallet.getPublicJwks(walletContext);
     const signingJwk = publicJwks.find((jwk) => jwk.use === 'sig' || jwk.alg === 'ES384') ?? publicJwks[0];
 
-    // Step 1: sign payload claims as compact JWS
-    const compactJws = await this.wallet.signCompactJws(walletContext, {
-      header: {
-        typ: 'application/didcomm-signed+json',
-        alg: 'ES384',
-        ...(signingJwk?.kid ? { kid: signingJwk.kid } : {}),
-      },
-      claims: payload as Record<string, unknown>,
-    });
-
-    // Step 2: encrypt JWS string as compact JWE (RSA-OAEP-256 + A256GCM, cty: JWS)
-    const compactJwe = await this.wallet.buildCompactJwe(walletContext, {
-      plaintext: compactJws,
-      recipientJwk: recipientEncryptionJwk,
-      contentType: 'JWS',
-    });
-
-    // Step 3: POST the JWE token directly (not JSON-serialised)
     const url = /^https?:\/\//.test(path)
       ? path
       : `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
-    const headers: Record<string, string> = {
-      ...this.defaultHeaders,
-      'Content-Type': 'application/didcomm-encrypted+json',
-      Accept: 'application/json, application/didcomm-plaintext+json, */*',
-    };
-    if (this.bearerToken) {
-      headers.Authorization = `Bearer ${this.bearerToken}`;
-    }
-    const response = await fetch(url, { method: 'POST', headers, body: compactJwe });
-    const body = await this.parseResponseBody(response);
-    return {
-      status: response.status,
-      location: response.headers.get('location') ?? undefined,
-      body,
-    };
+    const result = await submitDidcomm({
+      mode: 'strict',
+      url,
+      payload,
+      defaultHeaders: this.defaultHeaders,
+      bearerToken: this.bearerToken,
+      recipientEncryptionJwk,
+      signCompactJws: async (claims: Record<string, unknown>) =>
+        this.wallet!.signCompactJws(walletContext, {
+          header: {
+            typ: 'application/didcomm-signed+json',
+            alg: 'ES384',
+            ...(signingJwk?.kid ? { kid: signingJwk.kid } : {}),
+          },
+          claims,
+        }),
+      encryptCompactJwe: async (compactJws: string, recipientJwk: unknown) =>
+        this.wallet!.buildCompactJwe(walletContext, {
+          plaintext: compactJws,
+          recipientJwk: recipientJwk as PublicJwk,
+          contentType: 'JWS',
+        }),
+      fetcher: (requestUrl: string, init: DidcommFetchInit) => fetch(requestUrl, init),
+    });
+    return { status: result.status, location: result.location, body: result.body };
   }
 
   /**
@@ -1091,6 +1140,14 @@ export class DataspaceNodeClient {
     };
   }
 
+  /**
+   * Legacy JSON submit for non-bundle payloads (openid/token/resource JSON bodies).
+   * Keeps JSON flows explicit and semantically separated from DIDComm bundle flows.
+   */
+  public async submitLegacyJson(path: string, payload: unknown): Promise<SubmitResponse> {
+    return this.postJson(path, payload);
+  }
+
   /**
    * POST a multipart/form-data payload.
    * Use for file upload endpoints. Prefer `uploadConversionFile` for DataConversion uploads.
@@ -1568,9 +1625,9 @@ export class DataspaceNodeClient {
       'org.schema.Service.category': hostCtx.sector,
       'org.schema.Service.identifier': resolvedServiceDid,
       ...(serviceProviderUrl ? { 'org.schema.Service.url': serviceProviderUrl } : {}),
-      'org.schema.Person.hasOccupation': controllerRole,
-      ...(controllerEmail ? { 'org.schema.Person.email': controllerEmail } : {}),
-      ...(controllerTelephone ? { 'org.schema.Person.telephone': controllerTelephone } : {}),
+      [ClaimsPersonSchemaorg.hasOccupation]: controllerRole,
+      ...(controllerEmail ? { [ClaimsPersonSchemaorg.email]: controllerEmail } : {}),
+      ...(controllerTelephone ? { [ClaimsPersonSchemaorg.telephone]: controllerTelephone } : {}),
     };
 
     const activation = await this.activateOrganizationInGatewayFromIcaProof(
@@ -1675,8 +1732,8 @@ export class DataspaceNodeClient {
   public getOfferIdFromResponse(result: SubmitAndPollResult | PollResult | unknown): string | undefined {
     const entry = this.getFirstDidcommDataEntryFromResponse(result);
     const offerId = String(
-      (entry as any)?.meta?.claims?.['org.schema.Offer.identifier']
-      || (entry as any)?.resource?.meta?.claims?.['org.schema.Offer.identifier']
+      (entry as any)?.meta?.claims?.[ClaimsOfferSchemaorg.identifier]
+      || (entry as any)?.resource?.meta?.claims?.[ClaimsOfferSchemaorg.identifier]
       || '',
     ).trim();
     return offerId || undefined;
@@ -1688,23 +1745,51 @@ export class DataspaceNodeClient {
   public getOfferPreviewFromResponse(result: SubmitAndPollResult | PollResult | unknown): OfferPreview {
     const entry = this.getFirstDidcommDataEntryFromResponse(result) as any;
     const claims = entry?.meta?.claims || entry?.resource?.meta?.claims || {};
-    const seatsRaw = claims['org.schema.Offer.eligibleQuantity.value'];
+    const seatsRaw = claims[ClaimsOfferSchemaorg.eligibleQuantityValue];
     const seats =
       typeof seatsRaw === 'number'
         ? seatsRaw
         : (typeof seatsRaw === 'string' && seatsRaw.trim() ? Number(seatsRaw) : undefined);
     return {
       offerId: this.getOfferIdFromResponse(result),
-      amount: claims['org.schema.Offer.price'],
-      currency: claims['org.schema.Offer.priceCurrency'],
+      amount: claims[ClaimsOfferSchemaorg.price],
+      currency: claims[ClaimsOfferSchemaorg.priceCurrency],
       seats: Number.isFinite(seats as number) ? seats : undefined,
-      planName: claims['org.schema.Offer.itemOffered.name'],
-      sku: claims['org.schema.Offer.itemOffered.sku'],
-      paymentMethod: claims['org.schema.Offer.acceptedPaymentMethod'],
-      checkoutUrl: claims['org.schema.Offer.checkoutPageURLTemplate'],
+      planName: claims[ClaimsOfferSchemaorg.itemOfferedName],
+      sku: claims[ClaimsOfferSchemaorg.itemOfferedSku],
+      paymentMethod: claims[ClaimsOfferSchemaorg.acceptedPaymentMethod],
+      checkoutUrl: claims[ClaimsOfferSchemaorg.checkoutPageURLTemplate],
     };
   }
 
+  /**
+   * Alias of `getOfferPreviewFromResponse` with business naming.
+   */
+  public getOfferInfoFromResponse(result: SubmitAndPollResult | PollResult | unknown): OfferInfo {
+    return this.getOfferPreviewFromResponse(result);
+  }
+
+  /**
+   * Extract activation code from response payload or claims.
+   * Supports common response shapes used in onboarding and license issuance flows.
+   */
+  public getActivationCodeFromResponse(result: SubmitAndPollResult | PollResult | unknown): string | undefined {
+    const root = (result as any)?.poll?.body || (result as any)?.body || {};
+    const byBody =
+      String(root?.activationCode || root?.body?.activationCode || '').trim();
+    if (byBody) return byBody;
+
+    const entry = this.getFirstDidcommDataEntryFromResponse(result) as any;
+    const claims = entry?.meta?.claims || entry?.resource?.meta?.claims || {};
+    const byClaims = String(
+      claims['org.schema.IndividualProduct.serialNumber']
+      || claims['org.schema.Offer.serialNumber']
+      || claims['activationCode']
+      || '',
+    ).trim();
+    return byClaims || undefined;
+  }
+
   /**
    * Throws when first DIDComm entry contains a business-level error status.
    */
@@ -1912,9 +1997,9 @@ export class DataspaceNodeClient {
       '@context': 'org.schema',
       'org.schema.Organization.alternateName': alternateName,
       'org.schema.Service.category': routeCtx.sector,
-      'org.schema.Person.hasOccupation': controllerRole,
-      ...(controllerEmail ? { 'org.schema.Person.email': controllerEmail } : {}),
-      ...(controllerTelephone ? { 'org.schema.Person.telephone': controllerTelephone } : {}),
+      [ClaimsPersonSchemaorg.hasOccupation]: controllerRole,
+      ...(controllerEmail ? { [ClaimsPersonSchemaorg.email]: controllerEmail } : {}),
+      ...(controllerTelephone ? { [ClaimsPersonSchemaorg.telephone]: controllerTelephone } : {}),
       ...(input.additionalClaims || {}),
     };
     const pollOptions = this.resolveSimplePollOptions(input.timeoutSeconds, input.intervalSeconds);
@@ -2179,10 +2264,15 @@ export class DataspaceNodeClient {
 
   private async parseResponseBody(response: Response): Promise<unknown> {
     const contentType = response.headers.get('content-type') || '';
+    const raw = await response.text();
+    if (!raw) return {};
     if (contentType.includes('application/json') || contentType.includes('application/didcomm-plaintext+json')) {
-      return response.json().catch(() => ({}));
+      try {
+        return JSON.parse(raw);
+      } catch {
+        return {};
+      }
     }
-    const text = await response.text();
-    return text;
+    return raw;
   }
 }

package/src/index.ts

@@ -4,5 +4,6 @@
 // See subjectVaultPhoneResolution.test.ts for context and migration plan.
 export * from './types.js';
 export * from './builders.js';
+export * from './vp-token.js';
 export * from './client.js';
 export * from './sdk/dataspace-wallet-sdk-node/index.js';

package/src/types.ts

@@ -206,6 +206,15 @@ export type OfferPreview = {
   checkoutUrl?: string;
 };
 
+export type OfferInfo = OfferPreview;
+
+export type EndpointSelector = {
+  section: string;
+  format: string;
+  resourceType: string;
+  action: string;
+};
+
 /**
  * Input for organization activation in GW using ICA-derived proof material.
  *
@@ -526,6 +535,8 @@ export type BackendPkceAuthOptions = {
   /** Requested scopes for the SMART bearer token. */
   scopes: string[];
   /** Cache key for the resulting bearer token. Defaults to `pkce:<apiKey prefix>`. */
+  tokenCacheKey?: string;
+  /** @deprecated Use `tokenCacheKey`. */
   endpointId?: string;
   /** PKCE code verifier. Auto-generated with randomUUID if not provided. */
   codeVerifier?: string;
@@ -536,6 +547,8 @@ export type BackendPkceAuthOptions = {
 export type BackendPkceAuthResult = {
   /** `fetched`: new token obtained. `cached`: valid token already in cache. `failed`: flow error. */
   status: 'fetched' | 'cached' | 'failed';
+  tokenCacheKey: string;
+  /** @deprecated Use `tokenCacheKey`. */
   endpointId: string;
   accessToken: string;
   tokenType: string;
@@ -547,6 +560,8 @@ export type BackendPkceAuthResult = {
 export type BackendSmartAuthOptions = {
   clientId: string;
   scopes: string[];
+  tokenCacheKey?: string;
+  /** @deprecated Use `tokenCacheKey`. */
   endpointId?: string;
   tokenUrl?: string;
   tokenPath?: string;
@@ -560,6 +575,8 @@ export type BackendSmartAuthOptions = {
 export type BackendSmartAuthResult = {
   status: 'fetched' | 'cached' | 'failed';
   profile: 'smart-backend.v1';
+  tokenCacheKey: string;
+  /** @deprecated Use `tokenCacheKey`. */
   endpointId: string;
   accessToken?: string;
   tokenType?: string;
@@ -570,7 +587,9 @@ export type BackendSmartAuthResult = {
 };
 
 export type SmartTokenExchangeInput = {
-  endpointId: string;
+  tokenCacheKey: string;
+  /** @deprecated Use `tokenCacheKey`. */
+  endpointId?: string;
   scopes: string[];
   exchangePayload: Record<string, unknown>;
   path?: string;
@@ -582,6 +601,8 @@ export type SmartTokenRequestSimpleInput = {
   sector?: string;
   idToken: string;
   scopes: string[];
+  tokenCacheKey?: string;
+  /** @deprecated Use `tokenCacheKey`. */
   endpointId?: string;
   timeoutSeconds?: number;
   intervalSeconds?: number;

package/src/vp-token.ts

@@ -0,0 +1,91 @@
+export type VpTokenHeader = {
+  alg: string;
+  typ?: string;
+  kid?: string;
+  [key: string]: unknown;
+};
+
+export type VpTokenPayload = {
+  iss: string;
+  sub?: string;
+  aud?: string;
+  jti?: string;
+  iat?: number;
+  exp?: number;
+  nonce?: string;
+  vp: {
+    '@context'?: unknown;
+    type?: unknown;
+    holder?: string;
+    verifiableCredential: string[];
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+};
+
+function toB64UrlJson(input: unknown): string {
+  return Buffer.from(JSON.stringify(input), 'utf-8').toString('base64url');
+}
+
+function fallbackId(): string {
+  const rand = Math.random().toString(36).slice(2, 10);
+  return `id-${Date.now()}-${rand}`;
+}
+
+export function generateUuidLike(): string {
+  const fn = (globalThis as any)?.crypto?.randomUUID;
+  if (typeof fn === 'function') return fn.call((globalThis as any).crypto);
+  return fallbackId();
+}
+
+export function buildEpochWindow(ttlSeconds = 300): { iat: number; exp: number } {
+  const iat = Math.floor(Date.now() / 1000);
+  return { iat, exp: iat + Math.max(1, Math.floor(ttlSeconds)) };
+}
+
+export function createVP(input?: Partial<VpTokenPayload>): VpTokenPayload {
+  const ttl = input?.exp && input?.iat ? undefined : buildEpochWindow(300);
+  const jti = input?.jti || generateUuidLike();
+  const nonce = input?.nonce || generateUuidLike();
+  return {
+    iss: String(input?.iss || ''),
+    sub: input?.sub,
+    aud: input?.aud,
+    jti,
+    iat: input?.iat ?? ttl?.iat,
+    exp: input?.exp ?? ttl?.exp,
+    nonce,
+    vp: {
+      '@context': ['https://www.w3.org/2018/credentials/v1'],
+      type: ['VerifiablePresentation'],
+      holder: input?.vp?.holder || input?.iss || '',
+      verifiableCredential: [],
+      ...(input?.vp || {}),
+    },
+  };
+}
+
+export function addVC(vpPayload: VpTokenPayload, vcJwt: string): VpTokenPayload {
+  const v = String(vcJwt || '').trim();
+  if (v) vpPayload.vp.verifiableCredential.push(v);
+  return vpPayload;
+}
+
+export function prepareForSignature(header: VpTokenHeader, payload: VpTokenPayload): {
+  encodedHeader: string;
+  encodedPayload: string;
+  signingInput: string;
+} {
+  const encodedHeader = toB64UrlJson(header);
+  const encodedPayload = toB64UrlJson(payload);
+  return { encodedHeader, encodedPayload, signingInput: `${encodedHeader}.${encodedPayload}` };
+}
+
+export function prepareBytesForSignature(header: VpTokenHeader, payload: VpTokenPayload): Uint8Array {
+  const { signingInput } = prepareForSignature(header, payload);
+  return new TextEncoder().encode(signingInput);
+}
+
+export function buildVpTokenCompact(encodedHeader: string, encodedPayload: string, signatureBase64Url: string): string {
+  return `${encodedHeader}.${encodedPayload}.${String(signatureBase64Url || '').trim()}`;
+}