onethenticator-core

A low-level, high-performance, and environment-agnostic core engine for TOTP (Time-based One-Time Password) and Google Authenticator migration.

onethenticator-core is built to be the reliable, cryptographic foundation for any 2FA application. Whether you're building a browser extension, a mobile app, or a server-side service, this library provides the raw power you need without the bloat.

🌟 Why onethenticator-core?

Most 2FA libraries are either tied to a specific environment (like Node.js) or come with heavy dependencies. onethenticator-core is different:

• Works Everywhere: From Chrome Extensions to Cloudflare Workers.
• Zero Dependencies: Keeps your bundle small and your security surface area minimal.
• Pure & Predictable: No global state, no hidden side-effects, just pure logic.
• Ready for Everyone: Simple APIs that hide the complexity of RFC 6238 and Protobuf parsing.

🚀 Design Philosophy

This library is a pure engine. It is built with a strict "no side-effects" policy:

• Stateless: No global state or internal caching.
• Deterministic: Given the same input, you always get the same output.
• Environment-Agnostic: Works in Browsers, Node.js, Cloudflare Workers, and Deno (via Web Crypto API).
• Minimal: Zero external dependencies.

🛠 Features

• TOTP (RFC 6238): Full implementation with support for custom digits (6 or 8) and time steps.
• Google Authenticator Migration: Parse binary migration payloads (protobuf) from QR codes.
• Otpauth URL Parsing: Robust parsing of standard otpauth:// URIs.
• Encoding Utilities: High-performance Base32 and UTF-8 encoding/decoding.
• Invisible Steganography: Hide arbitrary UTF-8 strings inside invisible Unicode variation selectors with XOR obfuscation and signature verification.
• TypeScript Optimized: Strict type safety and clear interfaces.

📦 Installation

npm install onethenticator-core

💻 Usage

Generating TOTP Codes

Generate a 6-digit code from a Base32 secret.

import { generateTOTP } from 'onethenticator-core';

// Simple usage (defaults to 6 digits, 30s step)
const code = await generateTOTP('JBSWY3DPEHPK3PXP');
console.log(`Current Code: ${code}`);

// Custom options for advanced use-cases
const code8 = await generateTOTP('JBSWY3DPEHPK3PXP', {
  digits: 8,
  step: 60,
  timestamp: Date.now()
});

Parsing Migration Payloads

Easily import accounts from Google Authenticator "Transfer Accounts" QR codes.

import { parseMigrationToOtpAccounts } from 'onethenticator-core';

// Binary data captured from a migration QR code
const binaryPayload = new Uint8Array([...]);
const accounts = parseMigrationToOtpAccounts(binaryPayload);

accounts.forEach(acc => {
  console.log(`Imported: ${acc.issuer} (${acc.name})`);
});

Parsing Otpauth URIs

Parse standard OTP URLs into manageable objects.

import { parseOtpAuthURL } from 'onethenticator-core';

const uri = 'otpauth://totp/GitHub:user?secret=JBSWY3DPEHPK3PXP&issuer=GitHub';
const account = parseOtpAuthURL(uri);

console.log(account.issuer); // "GitHub"
console.log(account.secret); // "JBSWY3DPEHPK3PXP"

Encoding Utilities

Fast, memory-efficient encoding for cryptographic operations.

import { encodeBase32, decodeBase32 } from 'onethenticator-core';

const data = new TextEncoder().encode('Hello World');
const base32 = encodeBase32(data); // "JBSWY3DPEBLW64TMMQ======"

const decoded = decodeBase32(base32);

Invisible Steganography

Hide a UTF-8 string inside invisible Unicode characters that can be embedded in any text.

import { Invisible } from 'onethenticator-core';

const invisible = new Invisible('my-secret-seed');

// Encode — returns a string of invisible Unicode characters
const hidden = invisible.encode('Hello World');
console.log(hidden.length); // looks empty when pasted into plain text

// Embed inside visible text
const carrier = `Some visible text${hidden}with hidden data`;

// Decode — extract and verify the hidden string
const result = invisible.decode(hidden);
if ('ok' in result) {
  console.log(result.ok); // "Hello World"
} else {
  console.error(result.error); // 'invalid_signature' | 'invalid_invisible_character' | 'invalid_utf8'
}

🔒 Security Principles

• No Trusted Environment: Does not assume a secure context (though it requires crypto.subtle).
• No Persistence: Does not handle storage (localStorage, DB, etc.). Applications must manage secrets securely.
• No Network: Does not make any external requests.
• Minimal Protobuf: Implements a custom, minimal Protobuf reader to avoid heavy dependencies and potential attack vectors.

⚖️ License

MIT