@tangentfeed/crypto 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sreeraj T A
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @tangentfeed/crypto
+
+End-to-end encryption for tangentfeed: XChaCha20-Poly1305 with HKDF key derivation, and scrypt for passphrases.
+
+Cell values are encrypted before they enter the operation log, so storage, transports, and relays only ever hold ciphertext.
+
+Part of [tangentfeed](https://github.com/sreerajta/tangentfeed). MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { Cipher, Json } from '@tangentfeed/core';
+export { DeviceKey, SIGNING_DOMAIN, canonicalJson, deviceIdFromPublicKey, generateDeviceKey, signPayload, verifyPayload } from '@tangentfeed/core';
+
+/**
+ * SpaceCipher — PROTOCOL.md §7 reference implementation.
+ *
+ * Scheme:
+ *   key    = HKDF-SHA256(ikm = space secret, salt = "", info = "tangentfeed/v1/cells", len = 32)
+ *   nonce  = 24 random bytes, fresh per encryption
+ *   AAD    = op id (UTF-8)
+ *   value  = "e1:" + base64( nonce || XChaCha20-Poly1305(plaintext) )
+ *   plaintext = canonical JSON of the cell value (§8.1)
+ *
+ * Why AAD = op id: a ciphertext lifted from one op and pasted into another
+ * fails authentication instead of silently relocating data between cells.
+ * Why random nonces: 192-bit nonces make collisions negligible without any
+ * counter state, which matters for a system where devices write offline and
+ * can be restored from backups.
+ *
+ * Passphrase support uses scrypt (interactive parameters) so a human-memorable
+ * secret is not directly usable as key material.
+ */
+
+declare class SpaceCipher implements Cipher {
+    private readonly key;
+    /** Construct from raw 32-byte key material (the "space secret"). */
+    constructor(secret: Uint8Array);
+    /**
+     * Derive a cipher from a human passphrase. The salt must be identical on
+     * every device in the space; the space id is a good, non-secret choice.
+     */
+    static fromPassphrase(passphrase: string, salt: string): Promise<SpaceCipher>;
+    /** Generate a fresh random space secret (to be shared out of band, e.g. by QR). */
+    static generateSecret(): Uint8Array;
+    encrypt(value: Json, opId: string): string;
+    decrypt(value: Json, opId: string): Json;
+}
+
+export { SpaceCipher };

package/dist/index.js

@@ -0,0 +1,108 @@
+// src/index.ts
+import { xchacha20poly1305 } from "@noble/ciphers/chacha.js";
+import { hkdf } from "@noble/hashes/hkdf.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { scrypt } from "@noble/hashes/scrypt.js";
+import {
+  CIPHER_PREFIX,
+  DecryptError,
+  canonicalJson,
+  isEncryptedValue
+} from "@tangentfeed/core";
+import {
+  SIGNING_DOMAIN,
+  canonicalJson as canonicalJson2,
+  deviceIdFromPublicKey,
+  generateDeviceKey,
+  signPayload,
+  verifyPayload
+} from "@tangentfeed/core";
+var CELL_INFO = "tangentfeed/v1/cells";
+var NONCE_BYTES = 24;
+var KEY_BYTES = 32;
+var utf8 = new TextEncoder();
+var fromUtf8 = new TextDecoder();
+var SpaceCipher = class _SpaceCipher {
+  key;
+  /** Construct from raw 32-byte key material (the "space secret"). */
+  constructor(secret) {
+    if (secret.length < 16) {
+      throw new Error("space secret must be at least 16 bytes; use fromPassphrase for text");
+    }
+    this.key = hkdf(sha256, secret, new Uint8Array(0), utf8.encode(CELL_INFO), KEY_BYTES);
+  }
+  /**
+   * Derive a cipher from a human passphrase. The salt must be identical on
+   * every device in the space; the space id is a good, non-secret choice.
+   */
+  static async fromPassphrase(passphrase, salt) {
+    const secret = await scryptAsync(utf8.encode(passphrase), utf8.encode(salt));
+    return new _SpaceCipher(secret);
+  }
+  /** Generate a fresh random space secret (to be shared out of band, e.g. by QR). */
+  static generateSecret() {
+    const b = new Uint8Array(KEY_BYTES);
+    globalThis.crypto.getRandomValues(b);
+    return b;
+  }
+  encrypt(value, opId) {
+    const nonce = new Uint8Array(NONCE_BYTES);
+    globalThis.crypto.getRandomValues(nonce);
+    const plaintext = utf8.encode(canonicalJson(value));
+    const ct = xchacha20poly1305(this.key, nonce, utf8.encode(opId)).encrypt(plaintext);
+    const packed = new Uint8Array(nonce.length + ct.length);
+    packed.set(nonce, 0);
+    packed.set(ct, nonce.length);
+    return CIPHER_PREFIX + base64Encode(packed);
+  }
+  decrypt(value, opId) {
+    if (!isEncryptedValue(value)) return value;
+    let packed;
+    try {
+      packed = base64Decode(value.slice(CIPHER_PREFIX.length));
+    } catch {
+      throw new DecryptError("value is not valid base64");
+    }
+    if (packed.length <= NONCE_BYTES) throw new DecryptError("ciphertext too short");
+    const nonce = packed.subarray(0, NONCE_BYTES);
+    const ct = packed.subarray(NONCE_BYTES);
+    let pt;
+    try {
+      pt = xchacha20poly1305(this.key, nonce, utf8.encode(opId)).decrypt(ct);
+    } catch {
+      throw new DecryptError("authentication failed (wrong key or tampered data)");
+    }
+    try {
+      return JSON.parse(fromUtf8.decode(pt));
+    } catch {
+      throw new DecryptError("decrypted payload is not valid JSON");
+    }
+  }
+};
+async function scryptAsync(pw, salt) {
+  return scrypt(pw, salt, { N: 2 ** 15, r: 8, p: 1, dkLen: KEY_BYTES });
+}
+function base64Encode(bytes) {
+  if (typeof btoa === "function") {
+    let bin = "";
+    for (const b of bytes) bin += String.fromCharCode(b);
+    return btoa(bin);
+  }
+  return Buffer.from(bytes).toString("base64");
+}
+function base64Decode(s) {
+  if (typeof atob === "function") {
+    const bin = atob(s);
+    return Uint8Array.from(bin, (c) => c.charCodeAt(0));
+  }
+  return new Uint8Array(Buffer.from(s, "base64"));
+}
+export {
+  SIGNING_DOMAIN,
+  SpaceCipher,
+  canonicalJson2 as canonicalJson,
+  deviceIdFromPublicKey,
+  generateDeviceKey,
+  signPayload,
+  verifyPayload
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@tangentfeed/crypto",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@noble/ciphers": "^2.0.0",
+    "@noble/hashes": "^2.0.0",
+    "@tangentfeed/core": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "fast-check": "^3.19.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "description": "End-to-end encryption for tangentfeed (XChaCha20-Poly1305)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sreerajta/tangentfeed.git",
+    "directory": "packages/crypto"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}