aegis-auth-kit

v1.0.5

Published

4 months ago

AegisSDK — Universal authentication orchestration SDK — configurable passcode hashing (Argon2id, scrypt, PBKDF2, bcrypt), biometric/WebAuthn, envelope encryption, policy engine with lockouts, fallback chains, and step-up auth.

AegisSDK

Universal Authentication & Security Orchestration SDK for modern Node.js and web applications.

AegisSDK provides a configurable, policy-driven security layer built on vetted cryptographic primitives. Instead of writing custom hashing, session logic, lockout timers, and WebAuthn ceremonies from scratch, developers can leverage AegisSDK to orchestrate security across passcodes, biometric hardware, secure envelopes, and granular lockout policies.

Architecture & How It Works

AegisSDK coordinates security through five primary modules, which are orchestrated together by the main client instance:

graph TD
    Client[Client App] --> AF[AegisSDK Client]
    AF --> PM[PasscodeManager]
    AF --> BM[WebAuthnManager]
    AF --> SS[SecureStore]
    AF --> PE[PolicyEngine]
    AF --> EB[EventBus]
    
    PM --> Argon2id[Argon2idAdapter]
    PM --> Scrypt[ScryptAdapter]
    PM --> PBKDF2[Pbkdf2Adapter]
    PM --> Bcrypt[BcryptAdapter]

1. Passcode Hashing Module

Supports four industry-standard secure hashing algorithms, with automatic upgrade/rehash recommendations:

Argon2id: Memory-hard, CPU-hard, side-channel resistant hashing (using the native argon2 package).
scrypt: Memory-hard hashing using Node's native crypto module.
PBKDF2: Highly compatible hash function using HMAC-SHA-256 or HMAC-SHA-512.
bcrypt: CPU-hard hashing with a custom-engineered TypeScript adapter using scrypt as a safe expansion factor to bypass the historic 72-byte password length limit.

2. WebAuthn & Biometric Orchestration

Uses FIDO2 / WebAuthn specifications through @simplewebauthn/server:

Generates registration and authentication options based on security policies.
Leverages pluggable credential stores (e.g., in-memory or database-backed).
Enforces user verification, attestation requirements, and client-side options.

3. Secure Envelope Storage

Implements authenticated encryption with additional authenticated data (AAD) to ensure storage tamper resistance:

Ciphers supported: aes-256-gcm (default) and chacha20-poly1305 (optimized for non-AES-NI hardware).
Data is stored in a structured, versioned binary envelope: [Version (1B)] | [Cipher ID (1B)] | [Salt (32B)] | [IV (12B)] | [Auth Tag (16B)] | [Ciphertext (Variable)]
Master key derivation via custom salt and passcode, with configurable platform key integration.

4. Policy Engine

A stateful engine enforcing security postures:

Exponential Lockout: Configurable attempt limits, base lockouts, and multipliers.
Step-Up Authentication: Intercepts actions (e.g., "transfer_funds") and triggers step-up biometric verification if a session has expired.
Dynamic Fallbacks: Configurable fallback chain if biometrics/hardware keys are unavailable.

5. Event Bus

A pub/sub model for tracking attempts, lockouts, fallback escalations, and warnings, making it simple to connect to audit logs, SIEMs, or local analytics.

Installation

npm install aegis-auth-kit

Note: AegisSDK requires Node.js >= 18.

Presets & Safety Floors

AegisSDK is designed around the principle of "configurable trust." It defines three named presets matching different security levels, as well as strict safety floors that prevent insecure configurations (unless explicitly bypassed via iKnowThisIsDangerous).

Quick Start

1. Initializing AegisSDK

Initialize using a preset or custom settings:

import { AegisSDK } from 'aegis-auth-kit';

// Initialize with the standard balanced preset
const auth = new AegisSDK({ preset: 'balanced' });

2. Passcode Hashing & Verification

// Hash a user password
const hash = await auth.passcode.hash('SuperSecurePassword123!');

// Verify a user login
const { valid, needsRehash } = await auth.passcode.verify('SuperSecurePassword123!', hash);

if (valid) {
  console.log("Login successful!");
  if (needsRehash) {
    // If the system's security parameters were upgraded, rehash the passcode now
    const newHash = await auth.passcode.hash('SuperSecurePassword123!');
    // Update newHash in the database...
  }
}

3. Integrated Authentication with Lockout Policy

Instead of calling the passcode manager directly, you can run authentication through the full AegisSDK pipeline to auto-enforce lockouts:

const result = await auth.authenticate(userId, inputPassword, storedHash);

if (result.lockedOut) {
  console.error("Authentication blocked: User is currently locked out.");
} else if (result.valid) {
  console.log("User authenticated successfully.");
} else {
  console.log("Invalid passcode.");
}

WebAuthn & Biometric Guide

WebAuthn registration and verification require a two-step handshake between the client browser and your server-side AegisSDK application.

Registration (Adding a device / Biometric key)

Server-Side Options Generation:

const options = await auth.biometric.generateRegistrationOptions(userId, username, userDisplayName);
// Send options JSON to client browser

Client-Side browser call:

import { startRegistration } from '@simplewebauthn/browser';
   
const credential = await startRegistration(options);
// Send credential JSON back to your server

Server-Side Verification & Storage:

const verification = await auth.biometric.verifyRegistration(userId, credential);
if (verification.verified) {
  console.log("Device registered successfully!");
}

Authentication (Biometric Sign-In)

Server-Side Options Generation:

const options = await auth.biometric.generateAuthenticationOptions(userId);
// Send options JSON to client browser

Client-Side browser call:

import { startAuthentication } from '@simplewebauthn/browser';
   
const assertion = await startAuthentication(options);
// Send assertion JSON back to your server

Server-Side Verification:

const verification = await auth.biometric.verifyAuthentication(userId, assertion);
if (verification.verified) {
  console.log("Biometric authentication successful!");
}

Secure Envelope Storage

Encrypt arbitrary data, sensitive keys, or payloads using structured envelopes.

const sensitivePayload = JSON.stringify({ apiToken: "xyz123", secretSeed: "abc456" });

// Encrypt payload using the user's passcode (key derived dynamically via scrypt)
const envelope = await auth.storage.encrypt(sensitivePayload, "UserPasscode!");

// Decrypt back to plaintext string
const decrypted = await auth.storage.decryptString(envelope, "UserPasscode!");
console.log(JSON.parse(decrypted)); // { apiToken: "xyz123", ... }

Step-Up Auth & Session Management

Enforce step-up checks for sensitive operations. If the user session has expired, the action is blocked, requiring biometric verification.

// Enforce step-up for a specific action
try {
  auth.enforceStepUp(userId, 'transfer_funds');
  // Proceed with the action...
} catch (err) {
  if (err instanceof StepUpRequiredError) {
    // Return step-up instruction to client browser to prompt for biometric check
    console.log("Biometric verification required to perform this action.");
  }
}

// Once biometric verification passes, record the success to refresh the action's session
auth.recordStepUp(userId, 'biometric');

Event Auditing

Listen to authentication success, failures, lockouts, and storage encryption events:

// Listen to all events
auth.events.onAny((event) => {
  console.log(`[AUDIT EVENT] [${event.type}] User: ${event.userId || 'system'}`);
});

// Or listen to specific events
auth.events.on('auth:lockout', (event) => {
  console.warn(`⚠️ User ${event.userId} locked out at ${event.timestamp}! Details:`, event.detail);
});

CLI Configuration Auditor

AegisSDK features a static configuration compliance auditor that rates and scores developer-defined configuration profiles.

To run the auditor:

npx aegis-auth-kit --config ./my-config.json

To view all presets scored:

npx aegis-auth-kit --all-presets