@opentdf/sdk 0.1.0-beta.1701

package/package.json

@@ -0,0 +1,126 @@
+{
+  "name": "@opentdf/sdk",
+  "version": "0.1.0-beta.1701",
+  "description": "OpenTDF for the Web",
+  "homepage": "https://github.com/opentdf/web-sdk",
+  "bugs": {
+    "url": "https://github.com/opentdf/web-sdk/issues"
+  },
+  "files": [
+    "dist/*/src/**",
+    "dist/*/tdf3/**",
+    "dist/*/*.json",
+    "src/**",
+    "tdf3/**",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/opentdf/web-sdk.git",
+    "directory": "lib"
+  },
+  "license": "BSD-3-Clause-Clear",
+  "author": "Virtru",
+  "types": "./dist/types/tdf3/index.d.ts",
+  "main": "./dist/cjs/tdf3/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/types/tdf3/index.d.ts",
+      "require": "./dist/cjs/tdf3/index.js",
+      "import": "./dist/web/tdf3/index.js"
+    },
+    "./assertions": {
+      "default": {
+        "types": "./dist/types/tdf3/src/assertions.d.ts",
+        "require": "./dist/cjs/tdf3/src/assertions.js",
+        "import": "./dist/web/tdf3/src/assertions.js"
+      }
+    },
+    "./encodings": {
+      "default": {
+        "types": "./dist/types/src/encodings/index.d.ts",
+        "require": "./dist/cjs/src/encodings/index.js",
+        "import": "./dist/web/src/encodings/index.js"
+      }
+    },
+    "./nano": {
+      "types": "./dist/types/src/index.d.ts",
+      "require": "./dist/cjs/src/index.js",
+      "import": "./dist/web/src/index.js"
+    }
+  },
+  "scripts": {
+    "build": "npm run clean && tsc && tsc --project tsconfig.commonjs.json && ../scripts/add-module-types.sh",
+    "build:watch": "tsc --watch",
+    "clean": "rm -rf {build,coverage,dist,tests/mocha/dist}",
+    "coverage:merge": "for x in mocha wtr; do cp coverage/$x/coverage-final.json coverage/$x.json; done; nyc report --reporter text --reporter lcov -t coverage --lines 75 --statements 75 --branches 70 --functions 65 --check-coverage >coverage/coverage.txt",
+    "doc": "typedoc --out dist/docs src/index.ts",
+    "format": "prettier --write \"{src,tdf3,tests}/**/*.ts\"",
+    "license-check": "license-checker-rseidelsohn --production --onlyAllow 'Apache-2.0; BSD; CC-BY-4.0; ISC; MIT'",
+    "lint": "eslint ./src/**/*.ts ./tdf3/**/*.ts ./tests/**/*.ts",
+    "prepack": "npm run build",
+    "test": "npm run build && npm run test:with-server",
+    "test:with-server": "node dist/web/tests/server.js & trap \"node dist/web/tests/stopServer.js\" EXIT; npm run test:mocha && npm run test:wtr && npm run test:browser && npm run coverage:merge",
+    "test:browser": "npx webpack --config webpack.test.config.cjs && npx karma start karma.conf.cjs",
+    "test:mocha": "c8 --exclude=\"dist/web/tests/**/*\" --report-dir=./coverage/mocha mocha 'dist/web/tests/mocha/**/*.spec.js' --file dist/web/tests/mocha/setup.js && npx c8 report --reporter=json --report-dir=./coverage/mocha",
+    "test:wtr": "web-test-runner",
+    "watch": "(trap 'kill 0' SIGINT; npm run build && (npm run build:watch & npm run test -- --watch))"
+  },
+  "dependencies": {
+    "axios": "^1.6.1",
+    "axios-retry": "^3.9.0",
+    "base64-js": "^1.5.1",
+    "browser-fs-access": "^0.34.1",
+    "buffer-crc32": "^0.2.13",
+    "dpop": "^1.2.0",
+    "eventemitter3": "^5.0.1",
+    "jose": "^4.14.4",
+    "json-canonicalize": "^1.0.6",
+    "streamsaver": "^2.0.6",
+    "uuid": "~9.0.0"
+  },
+  "devDependencies": {
+    "@esm-bundle/chai": "~4.3.4-fix.0",
+    "@types/buffer-crc32": "^0.2.4",
+    "@types/chai": "~4.3.5",
+    "@types/jest": "^29.5.3",
+    "@types/jsdom": "^21.1.7",
+    "@types/jsonwebtoken": "~9.0.2",
+    "@types/mocha": "~10.0.1",
+    "@types/node": "^20.4.5",
+    "@types/send": "^0.17.1",
+    "@types/sinon": "~10.0.15",
+    "@types/streamsaver": "^2.0.1",
+    "@types/uuid": "~9.0.2",
+    "@types/wicg-file-system-access": "^2020.9.6",
+    "@typescript-eslint/eslint-plugin": "^6.2.1",
+    "@typescript-eslint/parser": "^6.2.1",
+    "@web/dev-server-esbuild": "^1.0.3",
+    "@web/dev-server-rollup": "^0.6.4",
+    "@web/test-runner": "^0.19.0",
+    "@web/test-runner-commands": "^0.9.0",
+    "audit-ci": "^6.6.1",
+    "c8": "^8.0.1",
+    "chai": "^4.3.7",
+    "colors": "^1.4.0",
+    "eslint": "^8.46.0",
+    "eslint-config-prettier": "^8.9.0",
+    "glob": "^10.3.3",
+    "jsdom": "^25.0.1",
+    "karma": "^6.4.4",
+    "karma-chrome-launcher": "^3.2.0",
+    "karma-mocha": "^2.0.1",
+    "license-checker-rseidelsohn": "^4.2.6",
+    "mocha": "^10.8.2",
+    "nyc": "^17.1.0",
+    "prettier": "^3.3.3",
+    "process": "^0.11.10",
+    "rollup": "^4.25.0",
+    "sinon": "~15.2.0",
+    "tsconfig-paths": "^4.2.0",
+    "typedoc": "^0.24.8",
+    "typescript": "5.1.6",
+    "webpack": "^5.96.1",
+    "webpack-cli": "^5.1.4"
+  }
+}

package/src/access.ts

@@ -0,0 +1,198 @@
+import { type AuthProvider } from './auth/auth.js';
+import {
+  InvalidFileError,
+  NetworkError,
+  PermissionDeniedError,
+  ServiceError,
+  UnauthenticatedError,
+} from './errors.js';
+import { pemToCryptoPublicKey, validateSecureUrl } from './utils.js';
+
+export class RewrapRequest {
+  signedRequestToken = '';
+}
+
+export class RewrapResponse {
+  entityWrappedKey = '';
+  sessionPublicKey = '';
+}
+
+/**
+ * Get a rewrapped access key to the document, if possible
+ * @param url Key access server rewrap endpoint
+ * @param requestBody a signed request with an encrypted document key
+ * @param authProvider Authorization middleware
+ * @param clientVersion
+ */
+export async function fetchWrappedKey(
+  url: string,
+  requestBody: RewrapRequest,
+  authProvider: AuthProvider,
+  clientVersion: string
+): Promise<RewrapResponse> {
+  const req = await authProvider.withCreds({
+    url,
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'virtru-ntdf-version': clientVersion,
+    },
+    body: JSON.stringify(requestBody),
+  });
+
+  try {
+    const response = await fetch(req.url, {
+      method: req.method,
+      mode: 'cors', // no-cors, *cors, same-origin
+      cache: 'no-cache', // *default, no-cache, reload, force-cache, only-if-cached
+      credentials: 'same-origin', // include, *same-origin, omit
+      headers: req.headers,
+      redirect: 'follow', // manual, *follow, error
+      referrerPolicy: 'no-referrer', // no-referrer, *no-referrer-when-downgrade, origin, origin-when-cross-origin, same-origin, strict-origin, strict-origin-when-cross-origin, unsafe-url
+      body: req.body as BodyInit,
+    });
+
+    if (!response.ok) {
+      switch (response.status) {
+        case 400:
+          throw new InvalidFileError(
+            `400 for [${req.url}]: rewrap failure [${await response.text()}]`
+          );
+        case 401:
+          throw new UnauthenticatedError(`401 for [${req.url}]`);
+        case 403:
+          throw new PermissionDeniedError(`403 for [${req.url}]`);
+        default:
+          throw new NetworkError(
+            `${req.method} ${req.url} => ${response.status} ${response.statusText}`
+          );
+      }
+    }
+
+    return response.json();
+  } catch (e) {
+    throw new NetworkError(`unable to fetch wrapped key from [${url}]: ${e}`);
+  }
+}
+
+export type KasPublicKeyAlgorithm = 'ec:secp256r1' | 'rsa:2048';
+
+/**
+ * Information about one of a KAS's published public keys.
+ * A KAS may publish multiple keys with a given algorithm type.
+ */
+export type KasPublicKeyInfo = {
+  /** The locator to the given KAS associated with this key */
+  url: string;
+
+  /** The encryption algorithm the key is to be used with. */
+  algorithm: KasPublicKeyAlgorithm;
+
+  /** If present, an identifier which is tied to this specific key. */
+  kid?: string;
+
+  /** The key value, encoded within a PEM envelope */
+  publicKey: string;
+
+  /** A subtle crypto version of the key.
+   * This can be used for wrapping key data for key access objects (with RSA)
+   * or to derive key data (with EC keys). */
+  key: Promise<CryptoKey>;
+};
+
+async function noteInvalidPublicKey(url: string, r: Promise<CryptoKey>): Promise<CryptoKey> {
+  try {
+    return await r;
+  } catch (e) {
+    if (e instanceof TypeError) {
+      throw new ServiceError(`invalid public key from [${url}]`, e);
+    }
+    throw e;
+  }
+}
+
+/**
+ * If we have KAS url but not public key we can fetch it from KAS, fetching
+ * the value from `${kas}/kas_public_key`.
+ */
+export async function fetchECKasPubKey(kasEndpoint: string): Promise<KasPublicKeyInfo> {
+  validateSecureUrl(kasEndpoint);
+  const pkUrlV2 = `${kasEndpoint}/v2/kas_public_key?algorithm=ec:secp256r1&v=2`;
+  const kasPubKeyResponseV2 = await fetch(pkUrlV2);
+  if (!kasPubKeyResponseV2.ok) {
+    switch (kasPubKeyResponseV2.status) {
+      case 404:
+        // v2 not implemented, perhaps a legacy server
+        break;
+      case 401:
+        throw new UnauthenticatedError(`401 for [${pkUrlV2}]`);
+      case 403:
+        throw new PermissionDeniedError(`403 for [${pkUrlV2}]`);
+      default:
+        throw new NetworkError(
+          `${pkUrlV2} => ${kasPubKeyResponseV2.status} ${kasPubKeyResponseV2.statusText}`
+        );
+    }
+    // most likely a server that does not implement v2 endpoint, so no key identifier
+    const pkUrlV1 = `${kasEndpoint}/kas_public_key?algorithm=ec:secp256r1`;
+    const r2 = await fetch(pkUrlV1);
+    if (!r2.ok) {
+      switch (r2.status) {
+        case 401:
+          throw new UnauthenticatedError(`401 for [${pkUrlV2}]`);
+        case 403:
+          throw new PermissionDeniedError(`403 for [${pkUrlV2}]`);
+        default:
+          throw new NetworkError(
+            `unable to load KAS public key from [${pkUrlV1}]. Received [${r2.status}:${r2.statusText}]`
+          );
+      }
+    }
+    const pem = await r2.json();
+    return {
+      key: noteInvalidPublicKey(pkUrlV1, pemToCryptoPublicKey(pem)),
+      publicKey: pem,
+      url: kasEndpoint,
+      algorithm: 'ec:secp256r1',
+    };
+  }
+  const jsonContent = await kasPubKeyResponseV2.json();
+  const { publicKey, kid }: KasPublicKeyInfo = jsonContent;
+  if (!publicKey) {
+    throw new NetworkError(
+      `invalid response from public key endpoint [${JSON.stringify(jsonContent)}]`
+    );
+  }
+  return {
+    key: noteInvalidPublicKey(pkUrlV2, pemToCryptoPublicKey(publicKey)),
+    publicKey,
+    url: kasEndpoint,
+    algorithm: 'ec:secp256r1',
+    ...(kid && { kid }),
+  };
+}
+
+const origin = (u: string): string => {
+  try {
+    return new URL(u).origin;
+  } catch (e) {
+    console.log(`invalid kas url: [${u}]`);
+    throw e;
+  }
+};
+
+export class OriginAllowList {
+  origins: string[];
+  allowAll: boolean;
+  constructor(urls: string[], allowAll?: boolean) {
+    this.origins = urls.map(origin);
+    urls.forEach(validateSecureUrl);
+    this.allowAll = !!allowAll;
+  }
+  allows(url: string): boolean {
+    if (this.allowAll) {
+      return true;
+    }
+    return this.origins.includes(origin(url));
+  }
+}

package/src/auth/Eas.ts

@@ -0,0 +1,79 @@
+import axios, { type AxiosResponse, type RawAxiosRequestConfig } from 'axios';
+
+import { AppIdAuthProvider, HttpRequest } from './auth.js';
+
+const { request } = axios;
+
+// Required `any` below is to match type from axios library.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type RequestFunctor = <T = any, R = AxiosResponse<T>>(config: RawAxiosRequestConfig) => Promise<R>;
+
+/**
+ * Client for EAS interaction, specifically fetching entity object.
+ */
+class Eas {
+  authProvider: AppIdAuthProvider;
+
+  endpoint: string;
+
+  requestFunctor: RequestFunctor;
+
+  /**
+   * Create an object for accessing an Entity Attribute Service.
+   * @param {object} config - options to  configure this EAS accessor
+   * @param {AuthProvider|function} config.authProvider - interceptor for `http-request.Request` object manipulation
+   * @param {string} config.endpoint - the URI to connect to
+   * @param {function} [config.requestFunctor=request] - http request async function object
+   */
+  constructor({
+    authProvider,
+    endpoint,
+    requestFunctor,
+  }: {
+    authProvider: AppIdAuthProvider;
+    endpoint: string;
+    requestFunctor?: RequestFunctor;
+  }) {
+    this.authProvider = authProvider;
+    this.endpoint = endpoint;
+    this.requestFunctor = requestFunctor || request;
+  }
+
+  /**
+   * Request an entity object for the current user.
+   * @param {object} config - options for the request
+   * @param {string} config.publicKey - String encoded public key from the keypair to be used with any subsequent requests refering to the returned EO
+   * @param {object} [config.etc] - additional parameters to be passed to the EAS entity-object endpoint
+   */
+  async fetchEntityObject({ publicKey, ...etc }: { publicKey: string }) {
+    // Create a skeleton http request for EAS.
+    const incredibleHttpReq: HttpRequest = {
+      url: this.endpoint,
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: { publicKey, ...etc },
+    };
+
+    // Delegate modifications to the auth provider.
+    // TODO: Handle various exception cases from interface docs.
+    const httpReq = await this.authProvider.withCreds(incredibleHttpReq);
+
+    // Execute the http request using axios.
+    const axiosParams: RawAxiosRequestConfig = {
+      method: httpReq.method,
+      headers: httpReq.headers,
+      url: httpReq.url,
+      params: undefined,
+      data: undefined,
+    };
+    // Allow the authProvider to change the method.
+    if (httpReq.method === 'POST' || httpReq.method === 'PATCH' || httpReq.method === 'PUT') {
+      axiosParams.data = httpReq.body;
+    } else {
+      axiosParams.params = httpReq.body;
+    }
+    return (await this.requestFunctor(axiosParams)).data;
+  }
+}
+
+export default Eas;

package/src/auth/auth.ts

@@ -0,0 +1,141 @@
+import { type JWTHeaderParameters, type JWTPayload, type KeyLike, SignJWT } from 'jose';
+
+export type HttpMethod =
+  | 'GET'
+  | 'HEAD'
+  | 'POST'
+  | 'PUT'
+  | 'DELETE'
+  | 'CONNECT'
+  | 'OPTIONS'
+  | 'TRACE'
+  | 'PATCH';
+
+/**
+ * Generic HTTP request interface used by AuthProvider implementers.
+ */
+export class HttpRequest {
+  headers: Record<string, string>;
+
+  method: HttpMethod;
+
+  params?: object;
+
+  url: string;
+
+  body?: BodyInit | null | unknown;
+
+  constructor() {
+    this.headers = {};
+    this.params = {};
+    this.method = 'POST';
+    this.url = '';
+  }
+}
+
+/**
+ * Appends the given `newHeaders` to the headers listed in HttpRequest, overwriting
+ * any with the same name. NOTE: Case sensitive.
+ * @param httpReq the source request
+ * @param newHeaders header name/value pairs
+ * @returns an updated variant of the request
+ */
+export function withHeaders(httpReq: HttpRequest, newHeaders: Record<string, string>): HttpRequest {
+  const headers = {
+    ...httpReq.headers,
+    ...newHeaders,
+  };
+  return { ...httpReq, headers };
+}
+
+function getTimestampInSeconds() {
+  return Math.floor(Date.now() / 1000);
+}
+
+/**
+ * Generate a JWT (or JWS-ed object)
+ * @param toSign the data to sign. Interpreted as JWTPayload but AFAIK this isn't required
+ * @param privateKey an RSA key
+ * @returns the signed object, with a JWS header. This may be a JWT.
+ */
+export async function reqSignature(
+  toSign: unknown,
+  privateKey: KeyLike,
+  jwtProtectedHeader: JWTHeaderParameters = { alg: 'RS256' }
+) {
+  const now = getTimestampInSeconds();
+  const anHour = 3600;
+  return new SignJWT(toSign as JWTPayload)
+    .setProtectedHeader(jwtProtectedHeader)
+    .setIssuedAt(now - anHour)
+    .setExpirationTime(now + anHour)
+    .sign(privateKey);
+}
+
+/**
+ * A utility type for getting and updating a bearer token to associate with
+ * HTTP requests to the backend services, notably rewrap and upsert endpoints.
+ *
+ * In the TDF protocol, this bearer token will be a wrapper around a signed
+ * ephemeral key, to be included in
+ * [the claims object](https://github.com/opentdf/spec/blob/main/schema/ClaimsObject.md).
+ */
+export type AuthProvider = {
+  /**
+   * This function should be called if the consumer of this auth provider
+   * changes the client keypair, or wishes to set the keypair after creating
+   * the object.
+   *
+   * Calling this function will (optionally) trigger a forcible token refresh
+   * using the cached refresh token, and update the auth server config with the
+   * current key.
+   *
+   * @param signingKey the client signing key pair. Will be bound
+   * to the OIDC token and require a DPoP header, when set.
+   */
+  updateClientPublicKey(signingKey?: CryptoKeyPair): Promise<void>;
+
+  /**
+   * Augment the provided http request with custom auth info to be used by backend services.
+   *
+   * @param httpReq - Required. An http request pre-populated with the data public key.
+   */
+  withCreds(httpReq: HttpRequest): Promise<HttpRequest>;
+};
+
+export function isAuthProvider(a?: unknown): a is AuthProvider {
+  if (!a || typeof a != 'object') {
+    return false;
+  }
+  return 'withCreds' in a;
+}
+
+/**
+ * An AuthProvider encapsulates all logic necessary to authenticate to a backend service, in the
+ * vein of <a href="https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html">AWS.Credentials</a>.
+ * <br/><br/>
+ * The client will call into its configured AuthProvider to decorate remote TDF service calls with necessary
+ * authentication info. This approach allows the client to be agnostic to the auth scheme, allowing for
+ * methods like identify federation and custom service credentials to be used and changed at the developer's will.
+ * <br/><br/>
+ * This class is not intended to be used on its own. See the documented subclasses for public-facing implementations.
+ * <ul>
+ * <li><a href="EmailCodeAuthProvider.html">EmailCodeAuthProvider</li>
+ * <li><a href="GoogleAuthProvider.html">GoogleAuthProvider</li>
+ * <li><a href="O365AuthProvider.html">O365AuthProvider</li>
+ * <li><a href="OutlookAuthProvider.html">OutlookAuthProvider</li>
+ * <li><a href="VirtruCredentialsAuthProvider.html">VirtruCredentialsAuthProvider</li>
+ * </ul>
+ */
+export abstract class AppIdAuthProvider {
+  /**
+   * Augment the provided http request with custom auth info to be used by backend services.
+   *
+   * @param httpReq - Required. An http request pre-populated with the data public key.
+   */
+  abstract withCreds(httpReq: HttpRequest): Promise<HttpRequest>;
+
+  abstract _getName(): string;
+}
+
+export default AppIdAuthProvider;

package/src/auth/oidc-clientcredentials-provider.ts

@@ -0,0 +1,32 @@
+import { ConfigurationError } from '../errors.js';
+import { AuthProvider, type HttpRequest } from './auth.js';
+import { AccessToken, type ClientSecretCredentials } from './oidc.js';
+
+export class OIDCClientCredentialsProvider implements AuthProvider {
+  oidcAuth: AccessToken;
+
+  constructor({
+    clientId,
+    clientSecret,
+    oidcOrigin,
+  }: Partial<ClientSecretCredentials> & Omit<ClientSecretCredentials, 'exchange'>) {
+    if (!clientId || !clientSecret) {
+      throw new ConfigurationError('clientId & clientSecret required for client credentials flow');
+    }
+
+    this.oidcAuth = new AccessToken({
+      exchange: 'client',
+      clientId,
+      clientSecret,
+      oidcOrigin,
+    });
+  }
+
+  async updateClientPublicKey(signingKey: CryptoKeyPair): Promise<void> {
+    await this.oidcAuth.refreshTokenClaimsWithClientPubkeyIfNeeded(signingKey);
+  }
+
+  async withCreds(httpReq: HttpRequest): Promise<HttpRequest> {
+    return this.oidcAuth.withCreds(httpReq);
+  }
+}

package/src/auth/oidc-externaljwt-provider.ts

@@ -0,0 +1,41 @@
+import { ConfigurationError } from '../errors.js';
+import { type AuthProvider, type HttpRequest } from './auth.js';
+import { AccessToken, type ExternalJwtCredentials } from './oidc.js';
+
+export class OIDCExternalJwtProvider implements AuthProvider {
+  oidcAuth: AccessToken;
+  externalJwt?: string;
+
+  constructor({
+    clientId,
+    externalJwt,
+    oidcOrigin,
+  }: Partial<ExternalJwtCredentials> & Omit<ExternalJwtCredentials, 'exchange'>) {
+    if (!clientId || !externalJwt) {
+      throw new ConfigurationError('external JWT exchange reequires client id and jwt');
+    }
+
+    this.oidcAuth = new AccessToken({
+      exchange: 'external',
+      clientId,
+      oidcOrigin,
+      externalJwt,
+    });
+
+    this.externalJwt = externalJwt;
+  }
+
+  async updateClientPublicKey(signingKey: CryptoKeyPair): Promise<void> {
+    this.oidcAuth.refreshTokenClaimsWithClientPubkeyIfNeeded(signingKey);
+  }
+
+  async withCreds(httpReq: HttpRequest): Promise<HttpRequest> {
+    //If we've been seeded with an externally-issued JWT, consume it
+    //and exchange it for a Virtru bearer token.
+    if (this.externalJwt) {
+      await this.oidcAuth.exchangeForRefreshToken();
+      delete this.externalJwt;
+    }
+    return this.oidcAuth.withCreds(httpReq);
+  }
+}

package/src/auth/oidc-refreshtoken-provider.ts

@@ -0,0 +1,41 @@
+import { ConfigurationError } from '../errors.js';
+import { type AuthProvider, type HttpRequest } from './auth.js';
+import { AccessToken, type RefreshTokenCredentials } from './oidc.js';
+
+export class OIDCRefreshTokenProvider implements AuthProvider {
+  oidcAuth: AccessToken;
+  refreshToken?: string;
+
+  constructor({
+    clientId,
+    refreshToken,
+    oidcOrigin,
+  }: Partial<RefreshTokenCredentials> & Omit<RefreshTokenCredentials, 'exchange'>) {
+    if (!clientId || !refreshToken) {
+      throw new ConfigurationError('refresh token or client id missing');
+    }
+
+    this.oidcAuth = new AccessToken({
+      exchange: 'refresh',
+      clientId,
+      refreshToken: refreshToken,
+      oidcOrigin,
+    });
+    this.refreshToken = refreshToken;
+  }
+
+  async updateClientPublicKey(signingKey: CryptoKeyPair): Promise<void> {
+    await this.oidcAuth.refreshTokenClaimsWithClientPubkeyIfNeeded(signingKey);
+  }
+
+  async withCreds(httpReq: HttpRequest): Promise<HttpRequest> {
+    //If we've been seeded with an externally-issued refresh token, consume it
+    //and exchange it for a Virtru bearer token - if it's already been consumed,
+    //skip this step
+    if (this.refreshToken) {
+      await this.oidcAuth.exchangeForRefreshToken();
+      delete this.refreshToken;
+    }
+    return this.oidcAuth.withCreds(httpReq);
+  }
+}