[!CAUTION] This is a work in progress and may not be suitable for production use.

Installation

npm install securio
# or
yarn add securio
# or
pnpm add securio
# or
bun install securio

Features

• TOTP generation/validation (Google Authenticator compatible)
• Base32 encoding/decoding
• Complete Passkey/WebAuthn support with automatic browser environment checks
• ALL window and browser compatibility checks handled internally (no manual window.PublicKeyCredential checks needed)
• Automatic credential creation and authentication with comprehensive error handling
• WebAuthn browser compatibility detection and HTTPS requirement validation
• TOTP QR code generation (with dynamic import of qrcode)
• Fully documented with JSDoc for all public APIs
• Universal support (Node.js + Browser)

Usage

TOTP (Time-based One-Time Password)

import { generateSecret, generateTOTP, verifyTOTP } from "securio";

// Generate a new Base32 secret
const secret = generateSecret();

// Generate a TOTP token (async)
const token = await generateTOTP(secret);

// Verify a TOTP token (async)
const isValid = await verifyTOTP(secret, token);

Generate otpauth:// URL

import { generateOTPAuthURL } from "securio";

const url = generateOTPAuthURL({
  issuer: "MyApp",
  accountName: "[email protected]",
  secret, // Base32 secret
});
// Use this URL to generate a QR code for authenticator apps

Generate TOTP QR Code (as Data URL)

import { generateTOTPQRCode } from "securio";

const dataUrl = await generateTOTPQRCode({
  issuer: "MyApp",
  accountName: "[email protected]",
  secret,
});
// Use the dataUrl in an <img src="..."> tag

Base32 Encoding/Decoding

import { encodeBase32, decodeBase32 } from "securio";

const encoded = encodeBase32(new Uint8Array([1, 2, 3, 4]));
const decoded = decodeBase32(encoded);

Passkey/WebAuthn

Basic Challenge and Verification

import { createChallenge, verifyPasskeyResponse } from "securio";

const challenge = createChallenge(); // Uint8Array
// ... send challenge to client, receive clientDataJSON ...
const isValid = verifyPasskeyResponse(challenge, clientDataJSON);

Complete Passkey Registration and Authentication

Securio handles ALL browser environment checks automatically - no need for manual window.PublicKeyCredential or navigator.credentials checks!

import { 
  isWebAuthnSupported, 
  createPasskey, 
  authenticatePasskey,
  verifyPasskeyResponse 
} from "securio";

// Optional: Check WebAuthn support (all browser checks handled internally)
const support = isWebAuthnSupported();
if (!support.supported) {
  console.error('WebAuthn not supported:', support.error);
  return;
}

let storedCredentialId: string | undefined; // Store this after registration

// Registration - No manual browser checks needed! 
// createPasskey() handles all window.PublicKeyCredential and navigator.credentials checks
try {
  const userId = new TextEncoder().encode("user123");
  const credential = await createPasskey(
    "example.com",          // RP ID
    "Example App",          // RP Name  
    userId,                 // User ID
    "user123",              // Username
    "User 123"              // Display Name
  );

  // Store the credential ID for later authentication
  storedCredentialId = new Uint8Array(credential.rawId);
  
  console.log('Passkey created successfully:', credential);
} catch (error) {
  console.error('Registration failed:', error.message);
}

// Authentication - No manual browser checks needed!
// authenticatePasskey() handles all window and navigator checks automatically
try {
  const allowCredentials = [
    { id: storedCredentialId, type: "public-key" }
  ];
  
  const credential = await authenticatePasskey(allowCredentials);
  console.log('Authentication successful:', credential);
} catch (error) {
  console.error('Authentication failed:', error.message);
}

Manual Options (Advanced Usage)

import { getRegistrationOptions, getAuthenticationOptions } from "securio";

// Get registration options for manual credential creation
const regOptions = await getRegistrationOptions(
  "example.com", 
  "Example App", 
  userId, 
  "user123", 
  "User 123"
);

// Get authentication options for manual credential retrieval
const authOptions = await getAuthenticationOptions(
  undefined, // challenge (will be generated)
  allowCredentials
);

Examples

API Documentation

All public APIs are fully documented with JSDoc. You can view inline documentation in your editor or generate HTML docs using TypeScript tools.

Licensing notes

Securio

Securio is licensed under the Infinite Clause License 1.0 (ICL-1.0).

QR Code Generation

The QR code generation functionality is dynamically imported from the qrcode package, which is licensed under the MIT License.

Passkey/WebAuthn

The Passkey/WebAuthn functionality is based on the WebAuthn API, which is part of the W3C standards and does not have a specific license. It is intended for use in web applications and is supported by modern browsers.

Logo

The Securio logo is a custom design and is not licensed under any specific terms. It is free to use for the purpose of promoting the Securio library. It is not to be used in a way that suggests endorsement by the Securio project or its maintainers without permission.