Registry / auth-security / superagent-d2l-session-auth

superagent-d2l-session-auth

JSON →
library2.0.1jsnpmunverified

superagent-d2l-session-auth is a JavaScript plugin designed to integrate D2L (Brightspace) session authentication with `superagent` HTTP requests. It acts as a `superagent` middleware, automatically adding the necessary D2L authentication headers to outbound requests by leveraging the `frau-jwt` library internally. The current stable version is 2.0.1, which includes a fix for `trustedHost` casing sensitivity. While specific release cadence is not explicitly stated, the project appears to be actively maintained by Brightspace, with updates addressing functionality and compatibility. Its primary differentiator is its specialized function within the Brightspace ecosystem, providing a streamlined way to handle D2L session-based authentication for applications using `superagent`, particularly within iframed contexts.

auth-securityhttp-networking
npm install superagent-d2l-session-auth
github ↗package ↗
INSTALL
IMPORT
SIG · SUPERAGENT-D2L-SES
S
superagent-d2l-session-auth
auth-securityjavascriptv2.0.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

auth
✓ import auth from 'superagent-d2l-session-auth'
✗ const auth = require('superagent-d2l-session-auth')
The primary export is a factory function. While the README shows CommonJS, ESM is the modern approach.
authFactory
✓ const auth = require('superagent-d2l-session-auth')()
✗ const auth = require('superagent-d2l-session-auth')
The default export is a factory function that must be called to create the plugin instance.
framedAuthFactory
✓ const auth = require('superagent-d2l-session-auth/framed')()
✗ const auth = require('superagent-d2l-session-auth/framed')
For strictly iframed applications, import from the 'framed' path and call it as a factory function.

Demonstrates how to initialize the `superagent-d2l-session-auth` plugin and attach it to a `superagent` request for D2L API interaction.

const request = require('superagent'); const auth = require('superagent-d2l-session-auth')({ scope: '*:*:*', trustedHost: 'school.brightspace.com' // Replace with your D2L domain }); // Example using a placeholder D2L API endpoint request .get('https://school.brightspace.com/d2l/api/lp/1.5/users/whoami') .use(auth) .end(function(err, res) { if(err) { console.error('Failed to fetch user info: ' + err.status + ' ' + (err.response ? err.response.text : '')); return; } const user = res.body; console.log('Hello, ' + user.FirstName + ' ' + user.LastName); });
Debug
Known issues
breakingStarting from version `0.12.0`, `superagent` was changed to a peer dependency. Users must explicitly install `superagent` in their project, as it is no longer bundled.
fix
Ensure `superagent` is installed as a direct dependency in your project: `npm install superagent` or `yarn add superagent`.
affects: >=0.12.0
deprecatedThe use of the `X-D2L-App-Id` header for authentication was deprecated starting from version `0.1.0`. Relying on this header may lead to authentication failures in newer D2L environments.
fix
Transition to using the standard D2L session authentication flow provided by the plugin, which leverages `frau-jwt` for token management.
affects: >=0.1.0
gotchaPrior to version `1.0.1`, the `trustedHost` option in the plugin configuration was case-sensitive. Incorrect casing could prevent tokens from being sent to the specified host.
fix
Upgrade to version `1.0.1` or newer. If upgrading is not possible, ensure the `trustedHost` option exactly matches the case of the target D2L host.
affects: <1.0.1
gotchaThe library primarily uses and demonstrates CommonJS `require()` syntax. While bundlers can handle ESM `import` in many environments, direct `import` might fail in older Node.js versions or certain browser contexts without proper module configuration.
fix
For CommonJS environments, use `const auth = require('superagent-d2l-session-auth')()`. For ESM, ensure your project is configured for `type: module` in `package.json` or use a bundler.
affects: >=0.0.1
Errors
Common errors & fixes
Error: Cannot find module 'superagent'
`superagent` is a peer dependency and was not installed in the project.
fix
Run `npm install superagent` or `yarn add superagent` to add `superagent` to your project's dependencies.
TypeError: auth is not a function
The main export of `superagent-d2l-session-auth` is a factory function that must be called to produce the actual plugin.
fix
Call the imported `auth` function to get the plugin instance: `const auth = require('superagent-d2l-session-auth')()` or `import createAuth from 'superagent-d2l-session-auth'; const auth = createAuth();`.
ReferenceError: require is not defined
Attempting to use CommonJS `require()` syntax in an ECMAScript Module (ESM) environment (e.g., Node.js with `type: module` or a browser).
fix
Use ESM `import` syntax: `import createAuth from 'superagent-d2l-session-auth'; const auth = createAuth();`.
SyntaxError: Cannot use import statement outside a module
Attempting to use ESM `import` syntax in a CommonJS environment (e.g., Node.js without `type: module` in `package.json`).
fix
Use CommonJS `require()` syntax: `const auth = require('superagent-d2l-session-auth')();`.
Upgrade
Version history
2.0.1latest on npm
Audit
Dependencies
superagentrequiredThis package is a superagent plugin and requires superagent to function. It is a peer dependency.
Agent activity
23 hits · last 30 days
node
20
OpenAI (training)
1
Resources
githubhttps://github.com/Brightspace/superagent-d2l-session-auth ↗
packagehttps://www.npmjs.com/package/superagent-d2l-session-auth ↗
superagent-d2l-session-auth — npm install superagent-d2l-session-auth · libregistry