URICrypt TypeScript Implementation

A TypeScript implementation of URICrypt, a prefix-preserving encryption scheme for URIs as specified in draft-denis-uricrypt.

Installation

# Using bun
bun add uricrypt

# Using npm
npm install uricrypt

# Using yarn
yarn add uricrypt

Usage

import { URICrypt } from './src';

// Create URICrypt instance with secret key and context
const secretKey = new Uint8Array([/* 16+ bytes */]);
const context = 'application-context';
const uricrypt = new URICrypt(secretKey, context);

// Encrypt a URI
const originalUri = 'https://example.com/path/to/resource';
const encryptedUri = uricrypt.encrypt(originalUri);

// Decrypt the URI
const decryptedUri = uricrypt.decrypt(encryptedUri);

API Reference

Constructor

new URICrypt(secretKey: Uint8Array, context?: string)

• secretKey: Must be at least 16 bytes long, maximum 255 bytes
• context: Optional context string for domain separation, maximum 255 bytes

Methods

encrypt(uri: string): string

Encrypts a URI using the URICrypt algorithm. Returns the encrypted URI with the original scheme preserved.

decrypt(encryptedUri: string): string

Decrypts a URICrypt-encrypted URI. Throws an error if decryption fails due to invalid ciphertext or wrong key.

Supported URI Formats

• Full URIs: https://example.com/path/to/resource
• Path-only URIs: /path/to/resource
• URIs with query parameters: https://example.com/search?q=test
• URIs with fragments: https://example.com/page#section
• Combined query and fragment: /api/users?id=123#profile

Development Commands

# Run tests
bun test

# Type checking
bunx tsc --noEmit

# Build for distribution
bun run build

# Run the example
bun run dev

Security Properties

• Prefix Preservation: Enables systems relying on URI prefixes to work with encrypted URIs
• Authentication: Each component is authenticated using SIV (Synthetic Initialization Vector)
• Domain Separation: Different contexts produce completely independent ciphertexts
• Key Commitment: Each ciphertext can only be decrypted with the exact key used for encryption
• Chained Encryption: Each URI component depends on all previous components for security

References

• draft-denis-uricrypt - URICrypt specification