@certible/seb-node

A TypeScript library for creating Safe Exam Browser (SEB) configuration files and working with SEB Config Keys.

Installation

npm install @certible/seb-node

Usage

Server-side (Node.js)

Import from the main package for server-side operations:

import { writeFileSync } from 'node:fs';
import { generateSEBConfig } from '@certible/seb-node';

// Create a basic SEB configuration
const result = await generateSEBConfig({
  startURL: 'https://exam.example.com',
  allowQuit: false,
  browserViewMode: 1, // Fullscreen
  URLFilterEnable: true,
  URLFilterRules: [
    {
      active: true,
      expression: 'example.com',
      action: 1, // Allow
    },
  ],
});

// Save to file
writeFileSync('exam.seb', result.data);
console.log(`Created SEB file (${result.size} bytes)`);

Encrypted Configuration

Create a password-protected SEB file:

const result = await generateSEBConfig(
  {
    startURL: 'https://exam.example.com',
    allowQuit: false,
  },
  {
    encrypt: true,
    password: 'your-secure-password',
  }
);

Without Validation

Skip schema validation for custom configurations:

const result = await generateSEBConfig(
  {
    startURL: 'https://exam.example.com',
    customField: 'custom-value', // Not in schema
  },
  {
    validate: false,
  }
);

Config Key Generation and Verification

The Config Key feature allows exam systems to verify that SEB clients are using the correct configuration.

Server-side: Generate Config Key

import { generateConfigKey } from '@certible/seb-node';

const config = {
  startURL: 'https://exam.example.com',
  allowQuit: false,
  browserViewMode: 1,
  sendBrowserExamKey: true,
};

// Generate the Config Key (64-char hex string)
const configKey = generateConfigKey(config);
console.log('Config Key:', configKey);
// e.g., "81aad4ab9dfd447cc479e6a4a7c9a544e2cafc7f3adeb68b2a21efad68eca4dc"

Server-side: Verify Config Key from HTTP Headers

When SEB sends requests, it includes the Config Key hash in the X-SafeExamBrowser-ConfigKeyHash header:

import { verifyConfigKeyHash } from '@certible/seb-node';

app.get('/exam', (req, res) => {
  const configKey = '81aad4ab9dfd447cc479e6a4a7c9a544e2cafc7f3adeb68b2a21efad68eca4dc';
  const requestURL = `${req.protocol}://${req.get('host')}${req.originalUrl}`;
  const receivedHash = req.headers['x-safeexambrowser-configkeyhash'];

  const isValid = verifyConfigKeyHash(requestURL, configKey, receivedHash);
});

Client-side: Access SEB Keys via JavaScript API

In your web application running inside SEB, import from the /web export:

import { getSEBKeys, isSEBAvailable } from '@certible/seb-node/web';

const keys = getSEBKeys();

if (keys.isAvailable) {
  console.log('Config Key:', keys.configKey);
  console.log('Browser Exam Key:', keys.browserExamKey);
  console.log('SEB Version:', keys.version);
}

Note: The Config Key and Browser Exam Key obtained via getSEBKeys are hashed with the current URL. In single-page applications (SPAs), SEB will not update the hash, so ensure that the URL for the hash reflects the correct state when verifying keys.

Import Paths

// Server-side: Main package
import { generateConfigKey, generateSEBConfig, verifyConfigKeyHash } from '@certible/seb-node';

// Client-side: Web export (smaller bundle, browser-only code)
import { getSEBKeys, isSEBAvailable } from '@certible/seb-node/web';

Resources

• Safe Exam Browser Developer Documentation
• SEB Config Key Documentation
• SEB JavaScript API Demo

License

MPL-2 License - see the LICENSE file for details.

Related Projects

• laravel-seb - Laravel package for SEB integration
• Safe Exam Browser - Official SEB website

About

This package is developed and maintained by Certible.