@tonycletus/web-crypto-room

Small Web Crypto helpers for ephemeral room-code based apps.

Use this package when two browser clients need to derive the same symmetric key from a short room code and encrypt small messages with the Web Crypto API.

This package is intentionally boring:

• room code generation
• HKDF-SHA256 key derivation
• AES-256-GCM encryption/decryption
• base64 helpers

It does not provide a complete security product, authentication model, or backend authorization layer.

Install

npm install @tonycletus/web-crypto-room
pnpm add @tonycletus/web-crypto-room
yarn add @tonycletus/web-crypto-room

Quick Start

import { deriveRoomKey, encryptText, decryptText, generateRoomCode } from "@tonycletus/web-crypto-room";

const code = generateRoomCode();
const key = await deriveRoomKey(code);
const ciphertext = await encryptText("hello", key);
const plaintext = await decryptText(ciphertext, key);

Binary Payloads

import { deriveRoomKey, encryptBytes, decryptBytes } from "@tonycletus/web-crypto-room";

const key = await deriveRoomKey("ABC123");
const encoded = new TextEncoder().encode("hello");

const encrypted = await encryptBytes(encoded, key);
const decrypted = await decryptBytes(encrypted, key);

Room Codes

import { generateRoomCode, normalizeRoomCode } from "@tonycletus/web-crypto-room";

const code = generateRoomCode({ length: 6 });
const normalized = normalizeRoomCode("abc 123"); // "ABC123"

The default alphabet avoids ambiguous characters where practical, but you should still treat room codes as low-entropy shared secrets.

API

• generateRoomCode(options?)
• normalizeRoomCode(code)
• deriveRoomKey(roomCode, options?)
• encryptText(text, key)
• decryptText(payload, key)
• encryptBytes(bytes, key)
• decryptBytes(payload, key)
• bytesToBase64(bytes)
• base64ToBytes(value)

Security Notes

Short room codes are convenient, but they are not passwords. Use short TTLs, rate limiting, and avoid storing long-lived secrets behind low-entropy codes.

This package does not provide authentication, authorization, replay protection, server validation, abuse prevention, or a complete protocol. Review your full application threat model before using it for sensitive data.