Brightspace Auth Token Provisioning

Common errors

• Cannot find package 'brightspace-auth-keys' imported from ...

  cause The `brightspace-auth-keys` package is a peer dependency but was not installed in your project.
  fix Install the peer dependency: `npm install brightspace-auth-keys` or `yarn add brightspace-auth-keys`.

• TypeError: AuthTokenProvisioner is not a constructor

  cause Attempting to use `require('brightspace-auth-provisioning')` and then calling it as a default export, or using `import AuthTokenProvisioner from '...'`. The class is a named export.
  fix For CommonJS, use `const { AuthTokenProvisioner } = require('brightspace-auth-provisioning');`. For ES Modules, use `import { AuthTokenProvisioner } from 'brightspace-auth-provisioning';`.

• Error: privateKey is not a KeyObject

  cause The object returned by `keyLookup` has a `key` property that is not an instance of `node:crypto.KeyObject`.
  fix Ensure that the `key` property in the object returned by `keyLookup` is a properly instantiated `KeyObject`. Use `crypto.createPrivateKey()` to convert PEM strings or other formats.

Warnings

• breaking Version 9.x (and potentially prior major versions) requires Node.js runtime version 20.x or higher. Running on older Node.js versions will result in errors.
  Fix: Upgrade your Node.js environment to version 20.x or newer. Use `nvm install 20 && nvm use 20` or similar version management tools.
• gotcha The `keyLookup` option for `AuthTokenProvisioner` must return a Promise resolving to an object where the `key` property is a `node:crypto.KeyObject`, not a raw key string or buffer. Incorrect key types will lead to signing errors.
  Fix: Ensure that your `keyLookup` function correctly loads and returns a `KeyObject` (e.g., from a PEM string using `crypto.createPrivateKey`).
• breaking Major version updates (e.g., v6.x to v7.x, v7.x to v8.x, v8.x to v9.x) typically introduce breaking changes in the API or required options. Always consult the release notes when upgrading between major versions.
  Fix: Review the specific release notes or changelog for the version you are upgrading to and adapt your code accordingly. Pay close attention to constructor options and method signatures.

Install

• npm install brightspace-auth-provisioning npm
• yarn add brightspace-auth-provisioning yarn
• pnpm add brightspace-auth-provisioning pnpm

Imports

• AuthTokenProvisioner
  wrong:

  const AuthTokenProvisioner = require('brightspace-auth-provisioning');

  correct:

  import { AuthTokenProvisioner } from 'brightspace-auth-provisioning';

  While the README shows CommonJS `require`, modern Node.js projects (especially with `node >=20.x`) typically use ES Modules. Both are generally supported, but `import` is preferred for new code.
• AbstractProvisioningCache
  wrong:

  const AbstractProvisioningCache = require('brightspace-auth-provisioning').AbstractProvisioningCache;

  correct:

  import { AbstractProvisioningCache } from 'brightspace-auth-provisioning';

  This is an abstract class intended for extension, available as a named export. Ensure you import it correctly for type hinting or extension.
• AuthTokenProvisioner
  wrong:

  import AuthTokenProvisioner from 'brightspace-auth-provisioning';

  correct:

  const { AuthTokenProvisioner } = require('brightspace-auth-provisioning');

  The primary class is a named export, not a default export. Using `require` directly on the package returns an object with named exports.

Quickstart

This quickstart demonstrates how to instantiate `AuthTokenProvisioner`, provide a `keyLookup` function returning a `KeyObject`, and then use it to provision an access token with specified claims.

import { AuthTokenProvisioner } from 'brightspace-auth-provisioning';
import { KeyObject, generateKeyPairSync } from 'node:crypto';

async function provisionExampleToken() {
  // Generate a dummy key pair for demonstration purposes
  // In a real application, you would load this securely
  const { privateKey } = generateKeyPairSync('ec', {
    namedCurve: 'P-256',
    publicKeyEncoding: { type: 'spki', format: 'pem' },
    privateKeyEncoding: { type: 'pkcs8', format: 'pem' }
  });

  const provisioner = new AuthTokenProvisioner({
    issuer: 'ece083bc-e6ac-11e4-8e1b-54ee750fffa4', // Replace with your service's issuer GUID
    keyLookup: async () => {
      return {
        kid: '0a9e68f6-e6ad-11e4-8ab6-54ee750fffa4', // Replace with your key ID
        key: privateKey, // Must be a node:crypto KeyObject
        alg: 'ES256'
      };
    }
  });

  try {
    const token = await provisioner.provisionToken({
      user: '32647',
      impersonator: '30882',
      tenant: '5492ff8a-e6ad-11e4-84d6-54ee750fffa4',
      scopes: ['updates:feed-items:read', 'core:*:*'],
      fsid: 'eyJhbGciOiJIUzI1Ni...' // Optional Caliper FSID
    });
    console.log('Successfully provisioned token:', token);
    return token;
  } catch (error) {
    console.error('Error provisioning token:', error);
    throw error;
  }
}

provisionExampleToken();