space-data-module-sdk 0.1.0

package/src/transport/pki.js

@@ -0,0 +1,140 @@
+import { canonicalBytes } from "../auth/canonicalize.js";
+import {
+  base64ToBytes,
+  bytesToBase64,
+  hexToBytes,
+  toUint8Array,
+} from "../utils/encoding.js";
+import {
+  aesGcmDecrypt,
+  aesGcmEncrypt,
+  hkdfBytes,
+  randomBytes,
+  x25519PublicKey,
+  x25519SharedSecret,
+} from "../utils/wasmCrypto.js";
+
+const HKDF_SALT_LABEL = new TextEncoder().encode("space-data-module-sdk");
+
+function normalizePublicKey(value) {
+  if (typeof value === "string") {
+    return hexToBytes(value);
+  }
+  return toUint8Array(value);
+}
+
+function normalizePrivateKey(value) {
+  if (typeof value === "string") {
+    return hexToBytes(value);
+  }
+  return toUint8Array(value);
+}
+
+async function deriveSharedSecret(privateKey, publicKey) {
+  return x25519SharedSecret(
+    normalizePrivateKey(privateKey),
+    normalizePublicKey(publicKey),
+  );
+}
+
+async function deriveAesKey(sharedSecret, salt, context) {
+  return hkdfBytes(
+    sharedSecret,
+    salt,
+    new TextEncoder().encode(context),
+    32,
+  );
+}
+
+export async function generateX25519Keypair() {
+  const privateKey = await randomBytes(32);
+  const publicKey = await x25519PublicKey(privateKey);
+  return {
+    publicKey,
+    privateKey,
+  };
+}
+
+export async function encryptBytesForRecipient({
+  plaintext,
+  recipientPublicKey,
+  context = "space-data-module-sdk/package",
+  senderKeyPair = null,
+} = {}) {
+  if (!recipientPublicKey) {
+    throw new Error("encryptBytesForRecipient requires recipientPublicKey.");
+  }
+  const sender = senderKeyPair ?? (await generateX25519Keypair());
+  const salt = await randomBytes(32);
+  salt.set(
+    HKDF_SALT_LABEL.slice(0, Math.min(HKDF_SALT_LABEL.length, salt.length)),
+  );
+  const iv = await randomBytes(12);
+  const sharedSecret = await deriveSharedSecret(
+    sender.privateKey,
+    recipientPublicKey,
+  );
+  const aesKey = await deriveAesKey(sharedSecret, salt, context);
+  const { ciphertext, tag } = await aesGcmEncrypt(
+    aesKey,
+    toUint8Array(plaintext),
+    iv,
+  );
+  const packedCiphertext = new Uint8Array(ciphertext.length + tag.length);
+  packedCiphertext.set(ciphertext, 0);
+  packedCiphertext.set(tag, ciphertext.length);
+  return {
+    version: 1,
+    scheme: "x25519-hkdf-aes-256-gcm",
+    context,
+    senderPublicKeyBase64: bytesToBase64(sender.publicKey),
+    saltBase64: bytesToBase64(salt),
+    ivBase64: bytesToBase64(iv),
+    ciphertextBase64: bytesToBase64(packedCiphertext),
+  };
+}
+
+export async function decryptBytesFromEnvelope({
+  envelope,
+  recipientPrivateKey,
+} = {}) {
+  if (!envelope || !recipientPrivateKey) {
+    throw new Error(
+      "decryptBytesFromEnvelope requires envelope and recipientPrivateKey.",
+    );
+  }
+  const sharedSecret = await deriveSharedSecret(
+    recipientPrivateKey,
+    base64ToBytes(envelope.senderPublicKeyBase64),
+  );
+  const aesKey = await deriveAesKey(
+    sharedSecret,
+    base64ToBytes(envelope.saltBase64),
+    envelope.context,
+  );
+  const packedCiphertext = base64ToBytes(envelope.ciphertextBase64);
+  if (packedCiphertext.length < 16) {
+    throw new Error("Encrypted envelope payload is truncated.");
+  }
+  const ciphertext = packedCiphertext.slice(0, packedCiphertext.length - 16);
+  const tag = packedCiphertext.slice(packedCiphertext.length - 16);
+  return aesGcmDecrypt(
+    aesKey,
+    ciphertext,
+    tag,
+    base64ToBytes(envelope.ivBase64),
+  );
+}
+
+export async function encryptJsonForRecipient(options = {}) {
+  return encryptBytesForRecipient({
+    ...options,
+    plaintext: canonicalBytes(options.payload ?? {}),
+  });
+}
+
+export async function decryptJsonFromEnvelope(options = {}) {
+  const bytes = await decryptBytesFromEnvelope(options);
+  return JSON.parse(new TextDecoder().decode(bytes));
+}
+

package/src/utils/crypto.js

@@ -0,0 +1,8 @@
+export function getCrypto() {
+  throw new Error(
+    "Direct WebCrypto access is forbidden. Use the WASM crypto helpers instead.",
+  );
+}
+
+export { randomBytes, sha256Bytes } from "./wasmCrypto.js";
+

package/src/utils/encoding.js

@@ -0,0 +1,54 @@
+function assertByteValue(value) {
+  if (!Number.isInteger(value) || value < 0 || value > 255) {
+    throw new TypeError("Expected byte values in range 0..255.");
+  }
+}
+
+export function toUint8Array(value) {
+  if (value instanceof Uint8Array) {
+    return value;
+  }
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  }
+  if (value instanceof ArrayBuffer) {
+    return new Uint8Array(value);
+  }
+  if (Array.isArray(value)) {
+    value.forEach(assertByteValue);
+    return Uint8Array.from(value);
+  }
+  throw new TypeError(
+    "Expected Uint8Array, ArrayBuffer, ArrayBufferView, or byte array.",
+  );
+}
+
+export function bytesToHex(bytes) {
+  return Array.from(toUint8Array(bytes), (byte) =>
+    byte.toString(16).padStart(2, "0"),
+  ).join("");
+}
+
+export function hexToBytes(hex) {
+  const normalized = String(hex ?? "")
+    .trim()
+    .replace(/^0x/i, "")
+    .toLowerCase();
+  if (normalized.length === 0 || normalized.length % 2 !== 0) {
+    throw new TypeError("Expected even-length hex string.");
+  }
+  const bytes = new Uint8Array(normalized.length / 2);
+  for (let index = 0; index < normalized.length; index += 2) {
+    bytes[index / 2] = parseInt(normalized.slice(index, index + 2), 16);
+  }
+  return bytes;
+}
+
+export function bytesToBase64(bytes) {
+  return Buffer.from(toUint8Array(bytes)).toString("base64");
+}
+
+export function base64ToBytes(base64) {
+  return new Uint8Array(Buffer.from(String(base64 ?? "").trim(), "base64"));
+}
+

package/src/utils/wasmCrypto.js

@@ -0,0 +1,70 @@
+import { toUint8Array } from "./encoding.js";
+
+let walletPromise = null;
+
+export async function getWasmWallet() {
+  if (!walletPromise) {
+    walletPromise = (async () => {
+      const module = await import("hd-wallet-wasm");
+      const init = module.default ?? module.createHDWallet;
+      return init();
+    })();
+  }
+
+  return walletPromise;
+}
+
+export async function randomBytes(length) {
+  const wallet = await getWasmWallet();
+  return wallet.utils.getRandomBytes(length);
+}
+
+export async function sha256Bytes(value) {
+  const wallet = await getWasmWallet();
+  return wallet.utils.sha256(toUint8Array(value));
+}
+
+export async function hkdfBytes(ikm, salt, info, length) {
+  const wallet = await getWasmWallet();
+  return wallet.utils.hkdf(
+    toUint8Array(ikm),
+    toUint8Array(salt),
+    toUint8Array(info),
+    length,
+  );
+}
+
+export async function x25519PublicKey(privateKey) {
+  const wallet = await getWasmWallet();
+  return wallet.curves.x25519.publicKey(toUint8Array(privateKey));
+}
+
+export async function x25519SharedSecret(privateKey, publicKey) {
+  const wallet = await getWasmWallet();
+  return wallet.curves.x25519.ecdh(
+    toUint8Array(privateKey),
+    toUint8Array(publicKey),
+  );
+}
+
+export async function aesGcmEncrypt(key, plaintext, iv, aad = null) {
+  const wallet = await getWasmWallet();
+  return wallet.utils.aesGcm.encrypt(
+    toUint8Array(key),
+    toUint8Array(plaintext),
+    toUint8Array(iv),
+    aad ? toUint8Array(aad) : undefined,
+  );
+}
+
+export async function aesGcmDecrypt(key, ciphertext, tag, iv, aad = null) {
+  const wallet = await getWasmWallet();
+  return wallet.utils.aesGcm.decrypt(
+    toUint8Array(key),
+    toUint8Array(ciphertext),
+    toUint8Array(tag),
+    toUint8Array(iv),
+    aad ? toUint8Array(aad) : undefined,
+  );
+}
+