@the9ines/bolt-core 0.5.1

package/README.md

@@ -0,0 +1,53 @@
+# @the9ines/bolt-core
+
+Core crypto primitives and utilities for the Bolt Protocol.
+
+## Scope
+
+This package provides transport-agnostic building blocks consumed by all Bolt ecosystem products:
+
+- **Crypto**: NaCl box seal/open, ephemeral keypair generation
+- **Peer codes**: Generation and validation using unambiguous base32 alphabet
+- **Hashing**: SHA-256, file hashing, hex encoding
+- **SAS**: Short Authentication String computation per Bolt Protocol spec
+- **Errors**: Core error types (BoltError, EncryptionError, ConnectionError, TransferError)
+- **Constants**: Protocol constants (nonce length, chunk size, key sizes, etc.)
+- **Encoding**: Base64 encode/decode helpers
+
+## What this package does NOT include
+
+- WebRTC, WebSocket, or any transport logic
+- Signaling or discovery
+- UI components
+- Handshake state machines or HELLO message handling
+- Identity persistence or TOFU pinning
+
+## Usage
+
+```typescript
+import {
+  sealBoxPayload,
+  openBoxPayload,
+  generateEphemeralKeyPair,
+  generateSecurePeerCode,
+  computeSas,
+  DEFAULT_CHUNK_SIZE,
+} from '@the9ines/bolt-core';
+
+// Generate ephemeral keys for a connection
+const myKeys = generateEphemeralKeyPair();
+
+// Encrypt a chunk
+const sealed = sealBoxPayload(plaintext, remotePubKey, myKeys.secretKey);
+
+// Decrypt a chunk
+const opened = openBoxPayload(sealed, remotePubKey, myKeys.secretKey);
+```
+
+## Build
+
+```bash
+npm install
+npm run build   # tsc -> dist/
+npm run test    # vitest
+```

package/dist/constants.d.ts

@@ -0,0 +1,26 @@
+/** NaCl box nonce length in bytes */
+export declare const NONCE_LENGTH = 24;
+/** X25519 public key length in bytes */
+export declare const PUBLIC_KEY_LENGTH = 32;
+/** X25519 secret key length in bytes */
+export declare const SECRET_KEY_LENGTH = 32;
+/** Default plaintext chunk size in bytes (16KB) */
+export declare const DEFAULT_CHUNK_SIZE = 16384;
+/** Peer code length in characters */
+export declare const PEER_CODE_LENGTH = 6;
+/** Unambiguous base32 alphabet for peer codes (no 0/O, 1/I/L) */
+export declare const PEER_CODE_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+/** SAS display length in hex characters */
+export declare const SAS_LENGTH = 6;
+/** Current Bolt Protocol version */
+export declare const BOLT_VERSION = 1;
+/** Transfer ID length in bytes (§14) */
+export declare const TRANSFER_ID_LENGTH = 16;
+/** SAS entropy in bits (§14) */
+export declare const SAS_ENTROPY = 24;
+/** File hash algorithm identifier (§14) */
+export declare const FILE_HASH_ALGORITHM = "SHA-256";
+/** File hash length in bytes (§14) */
+export declare const FILE_HASH_LENGTH = 32;
+/** Capability namespace prefix (§14) — all capability strings start with this */
+export declare const CAPABILITY_NAMESPACE = "bolt.";

package/dist/constants.js

@@ -0,0 +1,26 @@
+/** NaCl box nonce length in bytes */
+export const NONCE_LENGTH = 24;
+/** X25519 public key length in bytes */
+export const PUBLIC_KEY_LENGTH = 32;
+/** X25519 secret key length in bytes */
+export const SECRET_KEY_LENGTH = 32;
+/** Default plaintext chunk size in bytes (16KB) */
+export const DEFAULT_CHUNK_SIZE = 16384;
+/** Peer code length in characters */
+export const PEER_CODE_LENGTH = 6;
+/** Unambiguous base32 alphabet for peer codes (no 0/O, 1/I/L) */
+export const PEER_CODE_ALPHABET = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789';
+/** SAS display length in hex characters */
+export const SAS_LENGTH = 6;
+/** Current Bolt Protocol version */
+export const BOLT_VERSION = 1;
+/** Transfer ID length in bytes (§14) */
+export const TRANSFER_ID_LENGTH = 16;
+/** SAS entropy in bits (§14) */
+export const SAS_ENTROPY = 24;
+/** File hash algorithm identifier (§14) */
+export const FILE_HASH_ALGORITHM = 'SHA-256';
+/** File hash length in bytes (§14) */
+export const FILE_HASH_LENGTH = 32;
+/** Capability namespace prefix (§14) — all capability strings start with this */
+export const CAPABILITY_NAMESPACE = 'bolt.';

package/dist/crypto.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Generate a fresh ephemeral X25519 keypair for a single connection.
+ * Discard after session ends.
+ */
+export declare function generateEphemeralKeyPair(): {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+};
+/**
+ * Seal a plaintext payload using NaCl box (XSalsa20-Poly1305).
+ *
+ * Wire format: base64(nonce || ciphertext)
+ * This matches the exact format used by all current product repos.
+ *
+ * @param plaintext - Raw bytes to encrypt
+ * @param remotePublicKey - Receiver's ephemeral public key (32 bytes)
+ * @param senderSecretKey - Sender's ephemeral secret key (32 bytes)
+ * @returns base64-encoded string of nonce + ciphertext
+ */
+export declare function sealBoxPayload(plaintext: Uint8Array, remotePublicKey: Uint8Array, senderSecretKey: Uint8Array): string;
+/**
+ * Open a sealed payload using NaCl box.open.
+ *
+ * Expects wire format: base64(nonce || ciphertext)
+ *
+ * @param sealed - base64-encoded string from sealBoxPayload
+ * @param senderPublicKey - Sender's ephemeral public key (32 bytes)
+ * @param receiverSecretKey - Receiver's ephemeral secret key (32 bytes)
+ * @returns Decrypted plaintext bytes
+ */
+export declare function openBoxPayload(sealed: string, senderPublicKey: Uint8Array, receiverSecretKey: Uint8Array): Uint8Array;

package/dist/crypto.js

@@ -0,0 +1,54 @@
+import tweetnacl from 'tweetnacl';
+const { box, randomBytes } = tweetnacl;
+import { toBase64, fromBase64 } from './encoding.js';
+import { EncryptionError } from './errors.js';
+/**
+ * Generate a fresh ephemeral X25519 keypair for a single connection.
+ * Discard after session ends.
+ */
+export function generateEphemeralKeyPair() {
+    return box.keyPair();
+}
+/**
+ * Seal a plaintext payload using NaCl box (XSalsa20-Poly1305).
+ *
+ * Wire format: base64(nonce || ciphertext)
+ * This matches the exact format used by all current product repos.
+ *
+ * @param plaintext - Raw bytes to encrypt
+ * @param remotePublicKey - Receiver's ephemeral public key (32 bytes)
+ * @param senderSecretKey - Sender's ephemeral secret key (32 bytes)
+ * @returns base64-encoded string of nonce + ciphertext
+ */
+export function sealBoxPayload(plaintext, remotePublicKey, senderSecretKey) {
+    const nonce = randomBytes(box.nonceLength);
+    const encrypted = box(plaintext, nonce, remotePublicKey, senderSecretKey);
+    if (!encrypted)
+        throw new EncryptionError('Encryption returned null');
+    const combined = new Uint8Array(nonce.length + encrypted.length);
+    combined.set(nonce);
+    combined.set(encrypted, nonce.length);
+    return toBase64(combined);
+}
+/**
+ * Open a sealed payload using NaCl box.open.
+ *
+ * Expects wire format: base64(nonce || ciphertext)
+ *
+ * @param sealed - base64-encoded string from sealBoxPayload
+ * @param senderPublicKey - Sender's ephemeral public key (32 bytes)
+ * @param receiverSecretKey - Receiver's ephemeral secret key (32 bytes)
+ * @returns Decrypted plaintext bytes
+ */
+export function openBoxPayload(sealed, senderPublicKey, receiverSecretKey) {
+    const data = fromBase64(sealed);
+    if (data.length < box.nonceLength) {
+        throw new EncryptionError('Sealed payload too short');
+    }
+    const nonce = data.slice(0, box.nonceLength);
+    const ciphertext = data.slice(box.nonceLength);
+    const decrypted = box.open(ciphertext, nonce, senderPublicKey, receiverSecretKey);
+    if (!decrypted)
+        throw new EncryptionError('Decryption failed');
+    return decrypted;
+}

package/dist/encoding.d.ts

@@ -0,0 +1,4 @@
+/** Encode a Uint8Array to a base64 string */
+export declare function toBase64(data: Uint8Array): string;
+/** Decode a base64 string to a Uint8Array */
+export declare function fromBase64(base64: string): Uint8Array;

package/dist/encoding.js

@@ -0,0 +1,10 @@
+import tweetnacl_util from 'tweetnacl-util';
+const { encodeBase64, decodeBase64 } = tweetnacl_util;
+/** Encode a Uint8Array to a base64 string */
+export function toBase64(data) {
+    return encodeBase64(data);
+}
+/** Decode a base64 string to a Uint8Array */
+export function fromBase64(base64) {
+    return decodeBase64(base64);
+}

package/dist/errors.d.ts

@@ -0,0 +1,26 @@
+export declare class BoltError extends Error {
+    details?: unknown | undefined;
+    constructor(message: string, details?: unknown | undefined);
+}
+export declare class EncryptionError extends BoltError {
+    constructor(message: string, details?: unknown);
+}
+export declare class ConnectionError extends BoltError {
+    constructor(message: string, details?: unknown);
+}
+export declare class TransferError extends BoltError {
+    constructor(message: string, details?: unknown);
+}
+export declare class IntegrityError extends BoltError {
+    constructor(message?: string);
+}
+/**
+ * Canonical wire error code registry — 22 codes (11 PROTOCOL + 11 ENFORCEMENT).
+ * Every error frame sent on the wire MUST use a code from this array.
+ * Implementations MUST reject inbound error frames carrying codes not listed here.
+ */
+export declare const WIRE_ERROR_CODES: readonly ["VERSION_MISMATCH", "ENCRYPTION_FAILED", "INTEGRITY_FAILED", "REPLAY_DETECTED", "TRANSFER_FAILED", "LIMIT_EXCEEDED", "CONNECTION_LOST", "PEER_NOT_FOUND", "ALREADY_CONNECTED", "INVALID_STATE", "KEY_MISMATCH", "DUPLICATE_HELLO", "ENVELOPE_REQUIRED", "ENVELOPE_UNNEGOTIATED", "ENVELOPE_DECRYPT_FAIL", "ENVELOPE_INVALID", "HELLO_PARSE_ERROR", "HELLO_DECRYPT_FAIL", "HELLO_SCHEMA_ERROR", "INVALID_MESSAGE", "UNKNOWN_MESSAGE_TYPE", "PROTOCOL_VIOLATION"];
+/** A valid wire error code string from PROTOCOL.md §10. */
+export type WireErrorCode = (typeof WIRE_ERROR_CODES)[number];
+/** Type guard: returns true if `x` is a canonical wire error code. */
+export declare function isValidWireErrorCode(x: unknown): x is WireErrorCode;

package/dist/errors.js

@@ -0,0 +1,67 @@
+export class BoltError extends Error {
+    constructor(message, details) {
+        super(message);
+        this.details = details;
+        this.name = 'BoltError';
+    }
+}
+export class EncryptionError extends BoltError {
+    constructor(message, details) {
+        super(message, details);
+        this.name = 'EncryptionError';
+    }
+}
+export class ConnectionError extends BoltError {
+    constructor(message, details) {
+        super(message, details);
+        this.name = 'ConnectionError';
+    }
+}
+export class TransferError extends BoltError {
+    constructor(message, details) {
+        super(message, details);
+        this.name = 'TransferError';
+    }
+}
+export class IntegrityError extends BoltError {
+    constructor(message = 'File integrity check failed') {
+        super(message);
+        this.name = 'IntegrityError';
+    }
+}
+// ── Wire Error Code Registry (PROTOCOL.md §10, v0.1.3-spec) ──────────
+/**
+ * Canonical wire error code registry — 22 codes (11 PROTOCOL + 11 ENFORCEMENT).
+ * Every error frame sent on the wire MUST use a code from this array.
+ * Implementations MUST reject inbound error frames carrying codes not listed here.
+ */
+export const WIRE_ERROR_CODES = [
+    // PROTOCOL class (11)
+    'VERSION_MISMATCH',
+    'ENCRYPTION_FAILED',
+    'INTEGRITY_FAILED',
+    'REPLAY_DETECTED',
+    'TRANSFER_FAILED',
+    'LIMIT_EXCEEDED',
+    'CONNECTION_LOST',
+    'PEER_NOT_FOUND',
+    'ALREADY_CONNECTED',
+    'INVALID_STATE',
+    'KEY_MISMATCH',
+    // ENFORCEMENT class (11)
+    'DUPLICATE_HELLO',
+    'ENVELOPE_REQUIRED',
+    'ENVELOPE_UNNEGOTIATED',
+    'ENVELOPE_DECRYPT_FAIL',
+    'ENVELOPE_INVALID',
+    'HELLO_PARSE_ERROR',
+    'HELLO_DECRYPT_FAIL',
+    'HELLO_SCHEMA_ERROR',
+    'INVALID_MESSAGE',
+    'UNKNOWN_MESSAGE_TYPE',
+    'PROTOCOL_VIOLATION',
+];
+/** Type guard: returns true if `x` is a canonical wire error code. */
+export function isValidWireErrorCode(x) {
+    return typeof x === 'string' && WIRE_ERROR_CODES.includes(x);
+}

package/dist/hash.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Compute SHA-256 hash of data.
+ */
+export declare function sha256(data: ArrayBuffer | Uint8Array): Promise<ArrayBuffer>;
+/**
+ * Convert ArrayBuffer to hex string.
+ */
+export declare function bufferToHex(buffer: ArrayBuffer): string;
+/**
+ * Compute SHA-256 hash of a File or Blob and return hex string.
+ */
+export declare function hashFile(file: Blob): Promise<string>;

package/dist/hash.js

@@ -0,0 +1,25 @@
+/**
+ * Compute SHA-256 hash of data.
+ */
+export async function sha256(data) {
+    if (data instanceof Uint8Array) {
+        return await crypto.subtle.digest('SHA-256', data);
+    }
+    return await crypto.subtle.digest('SHA-256', data);
+}
+/**
+ * Convert ArrayBuffer to hex string.
+ */
+export function bufferToHex(buffer) {
+    return Array.from(new Uint8Array(buffer))
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+/**
+ * Compute SHA-256 hash of a File or Blob and return hex string.
+ */
+export async function hashFile(file) {
+    const buffer = await file.arrayBuffer();
+    const hash = await sha256(buffer);
+    return bufferToHex(hash);
+}

package/dist/identity.d.ts

@@ -0,0 +1,24 @@
+import { BoltError } from './errors.js';
+/** Long-lived X25519 identity keypair. Persisted by the transport layer. */
+export interface IdentityKeyPair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}
+/**
+ * Generate a persistent identity keypair (X25519).
+ *
+ * Identity keys are long-lived and stored by the transport layer.
+ * They MUST NOT be sent through the signaling server — identity
+ * material travels only inside encrypted DataChannel messages (HELLO).
+ */
+export declare function generateIdentityKeyPair(): IdentityKeyPair;
+/**
+ * Thrown when a peer's identity public key does not match a previously
+ * pinned value. This is a TOFU violation — the session MUST be aborted.
+ */
+export declare class KeyMismatchError extends BoltError {
+    readonly peerCode: string;
+    readonly expected: Uint8Array;
+    readonly received: Uint8Array;
+    constructor(peerCode: string, expected: Uint8Array, received: Uint8Array);
+}

package/dist/identity.js

@@ -0,0 +1,26 @@
+import tweetnacl from 'tweetnacl';
+const { box } = tweetnacl;
+import { BoltError } from './errors.js';
+/**
+ * Generate a persistent identity keypair (X25519).
+ *
+ * Identity keys are long-lived and stored by the transport layer.
+ * They MUST NOT be sent through the signaling server — identity
+ * material travels only inside encrypted DataChannel messages (HELLO).
+ */
+export function generateIdentityKeyPair() {
+    return box.keyPair();
+}
+/**
+ * Thrown when a peer's identity public key does not match a previously
+ * pinned value. This is a TOFU violation — the session MUST be aborted.
+ */
+export class KeyMismatchError extends BoltError {
+    constructor(peerCode, expected, received) {
+        super(`Identity key mismatch for peer ${peerCode}`);
+        this.peerCode = peerCode;
+        this.expected = expected;
+        this.received = received;
+        this.name = 'KeyMismatchError';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { NONCE_LENGTH, PUBLIC_KEY_LENGTH, SECRET_KEY_LENGTH, DEFAULT_CHUNK_SIZE, PEER_CODE_LENGTH, PEER_CODE_ALPHABET, SAS_LENGTH, BOLT_VERSION, TRANSFER_ID_LENGTH, SAS_ENTROPY, FILE_HASH_ALGORITHM, FILE_HASH_LENGTH, CAPABILITY_NAMESPACE, } from './constants.js';
+export { toBase64, fromBase64 } from './encoding.js';
+export { generateEphemeralKeyPair, sealBoxPayload, openBoxPayload } from './crypto.js';
+export { generateSecurePeerCode, generateLongPeerCode, isValidPeerCode, normalizePeerCode, } from './peer-code.js';
+export { sha256, bufferToHex, hashFile } from './hash.js';
+export { computeSas } from './sas.js';
+export { generateIdentityKeyPair, KeyMismatchError } from './identity.js';
+export type { IdentityKeyPair } from './identity.js';
+export { BoltError, EncryptionError, ConnectionError, TransferError, IntegrityError } from './errors.js';
+export { WIRE_ERROR_CODES, isValidWireErrorCode } from './errors.js';
+export type { WireErrorCode } from './errors.js';

package/dist/index.js

@@ -0,0 +1,18 @@
+// Constants (§14)
+export { NONCE_LENGTH, PUBLIC_KEY_LENGTH, SECRET_KEY_LENGTH, DEFAULT_CHUNK_SIZE, PEER_CODE_LENGTH, PEER_CODE_ALPHABET, SAS_LENGTH, BOLT_VERSION, TRANSFER_ID_LENGTH, SAS_ENTROPY, FILE_HASH_ALGORITHM, FILE_HASH_LENGTH, CAPABILITY_NAMESPACE, } from './constants.js';
+// Encoding
+export { toBase64, fromBase64 } from './encoding.js';
+// Crypto primitives
+export { generateEphemeralKeyPair, sealBoxPayload, openBoxPayload } from './crypto.js';
+// Peer codes
+export { generateSecurePeerCode, generateLongPeerCode, isValidPeerCode, normalizePeerCode, } from './peer-code.js';
+// Hashing
+export { sha256, bufferToHex, hashFile } from './hash.js';
+// SAS
+export { computeSas } from './sas.js';
+// Identity
+export { generateIdentityKeyPair, KeyMismatchError } from './identity.js';
+// Errors
+export { BoltError, EncryptionError, ConnectionError, TransferError, IntegrityError } from './errors.js';
+// Wire error code registry (PROTOCOL.md §10)
+export { WIRE_ERROR_CODES, isValidWireErrorCode } from './errors.js';

package/dist/peer-code.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Generate a cryptographically secure 6-character peer code.
+ * Uses rejection sampling to eliminate modulo bias.
+ */
+export declare function generateSecurePeerCode(): string;
+/**
+ * Generate a longer peer code with dash separator.
+ * Format: XXXX-XXXX (~40 bits of entropy)
+ * Uses rejection sampling to eliminate modulo bias.
+ */
+export declare function generateLongPeerCode(): string;
+/**
+ * Validate peer code format.
+ * Accepts 6-char or 8-char (with optional dash) codes using the unambiguous alphabet.
+ */
+export declare function isValidPeerCode(code: string): boolean;
+/**
+ * Normalize peer code for comparison (remove dashes, uppercase).
+ */
+export declare function normalizePeerCode(code: string): string;

package/dist/peer-code.js

@@ -0,0 +1,56 @@
+import { PEER_CODE_ALPHABET } from './constants.js';
+// Rejection sampling threshold: largest multiple of N that fits in a byte.
+// N = 31 (PEER_CODE_ALPHABET.length), MAX = floor(256/31) * 31 = 248.
+// Bytes >= MAX are discarded to eliminate modulo bias.
+const REJECTION_MAX = Math.floor(256 / PEER_CODE_ALPHABET.length) * PEER_CODE_ALPHABET.length;
+/**
+ * Fill `out` with `count` unbiased alphabet indices via rejection sampling.
+ * Bytes >= REJECTION_MAX are discarded; survivors use byte % N.
+ */
+function fillUnbiased(count) {
+    const N = PEER_CODE_ALPHABET.length;
+    const result = [];
+    while (result.length < count) {
+        const batch = new Uint8Array(count - result.length + 4); // small over-request
+        crypto.getRandomValues(batch);
+        for (let i = 0; i < batch.length && result.length < count; i++) {
+            if (batch[i] < REJECTION_MAX) {
+                result.push(PEER_CODE_ALPHABET[batch[i] % N]);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Generate a cryptographically secure 6-character peer code.
+ * Uses rejection sampling to eliminate modulo bias.
+ */
+export function generateSecurePeerCode() {
+    return fillUnbiased(6).join('');
+}
+/**
+ * Generate a longer peer code with dash separator.
+ * Format: XXXX-XXXX (~40 bits of entropy)
+ * Uses rejection sampling to eliminate modulo bias.
+ */
+export function generateLongPeerCode() {
+    const chars = fillUnbiased(8);
+    return chars.slice(0, 4).join('') + '-' + chars.slice(4).join('');
+}
+/**
+ * Validate peer code format.
+ * Accepts 6-char or 8-char (with optional dash) codes using the unambiguous alphabet.
+ */
+export function isValidPeerCode(code) {
+    const normalized = code.replace(/-/g, '').toUpperCase();
+    if (normalized.length !== 6 && normalized.length !== 8) {
+        return false;
+    }
+    return normalized.split('').every(char => PEER_CODE_ALPHABET.includes(char));
+}
+/**
+ * Normalize peer code for comparison (remove dashes, uppercase).
+ */
+export function normalizePeerCode(code) {
+    return code.replace(/-/g, '').toUpperCase();
+}

package/dist/sas.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Compute a 6-character SAS (Short Authentication String) per PROTOCOL.md.
+ *
+ * SAS_input = SHA-256( sort32(identityA, identityB) || sort32(ephemeralA, ephemeralB) )
+ * Display first 6 hex chars uppercase.
+ *
+ * @param identityA - Raw 32-byte identity public key of peer A
+ * @param identityB - Raw 32-byte identity public key of peer B
+ * @param ephemeralA - Raw 32-byte ephemeral public key of peer A
+ * @param ephemeralB - Raw 32-byte ephemeral public key of peer B
+ * @returns 6-character uppercase hex string (24 bits of entropy)
+ */
+export declare function computeSas(identityA: Uint8Array, identityB: Uint8Array, ephemeralA: Uint8Array, ephemeralB: Uint8Array): Promise<string>;

package/dist/sas.js

@@ -0,0 +1,53 @@
+import { sha256, bufferToHex } from './hash.js';
+import { PUBLIC_KEY_LENGTH, SAS_LENGTH } from './constants.js';
+// CANONICAL: computeSas() is the ONLY SAS implementation in the Bolt ecosystem.
+// SAS verification is not yet surfaced in products. No SAS logic may exist in
+// transport or product packages. See scripts/verify-no-shadow-sas.sh.
+/**
+ * Lexicographically sort two 32-byte values and concatenate them.
+ */
+function sort32(a, b) {
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i]) {
+            const first = a[i] < b[i] ? a : b;
+            const second = a[i] < b[i] ? b : a;
+            const result = new Uint8Array(first.length + second.length);
+            result.set(first);
+            result.set(second, first.length);
+            return result;
+        }
+    }
+    // Keys are identical — concatenate as-is
+    const result = new Uint8Array(a.length + b.length);
+    result.set(a);
+    result.set(b, a.length);
+    return result;
+}
+/**
+ * Compute a 6-character SAS (Short Authentication String) per PROTOCOL.md.
+ *
+ * SAS_input = SHA-256( sort32(identityA, identityB) || sort32(ephemeralA, ephemeralB) )
+ * Display first 6 hex chars uppercase.
+ *
+ * @param identityA - Raw 32-byte identity public key of peer A
+ * @param identityB - Raw 32-byte identity public key of peer B
+ * @param ephemeralA - Raw 32-byte ephemeral public key of peer A
+ * @param ephemeralB - Raw 32-byte ephemeral public key of peer B
+ * @returns 6-character uppercase hex string (24 bits of entropy)
+ */
+export async function computeSas(identityA, identityB, ephemeralA, ephemeralB) {
+    if (identityA.length !== PUBLIC_KEY_LENGTH || identityB.length !== PUBLIC_KEY_LENGTH) {
+        throw new Error(`Identity keys must be ${PUBLIC_KEY_LENGTH} bytes`);
+    }
+    if (ephemeralA.length !== PUBLIC_KEY_LENGTH || ephemeralB.length !== PUBLIC_KEY_LENGTH) {
+        throw new Error(`Ephemeral keys must be ${PUBLIC_KEY_LENGTH} bytes`);
+    }
+    const sortedIdentity = sort32(identityA, identityB);
+    const sortedEphemeral = sort32(ephemeralA, ephemeralB);
+    const combined = new Uint8Array(sortedIdentity.length + sortedEphemeral.length);
+    combined.set(sortedIdentity);
+    combined.set(sortedEphemeral, sortedIdentity.length);
+    const hash = await sha256(combined);
+    const hex = bufferToHex(hash);
+    return hex.substring(0, SAS_LENGTH).toUpperCase();
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@the9ines/bolt-core",
+  "version": "0.5.1",
+  "description": "Bolt Protocol core crypto primitives and utilities",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "audit-exports": "node scripts/audit-exports.mjs",
+    "generate-vectors": "node scripts/print-test-vectors.mjs",
+    "check-vectors": "node scripts/print-test-vectors.mjs --check",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "tweetnacl": "^1.0.3",
+    "tweetnacl-util": "^0.15.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.3",
+    "vitest": "^4.0.18"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/the9ines/bolt-core-sdk.git"
+  },
+  "license": "MIT"
+}