@sovereignfs/sdk 1.25.0

package/src/__tests__/e2ee-crypto.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from 'vitest';
+import {
+  generateCmk,
+  generateDek,
+  generateDeviceKey,
+  generateRecoverySecret,
+  unwrapCmkWithDeviceKey,
+  unwrapCmkWithRecoverySecret,
+  unwrapDekWithCmk,
+  wrapCmkWithDeviceKey,
+  wrapCmkWithRecoverySecret,
+  wrapDekWithCmk,
+} from '../e2ee-crypto';
+
+/** Encrypt/decrypt a probe value with a CMK to prove two `CryptoKey` handles are the same key. */
+async function roundTripsThrough(cmk: CryptoKey): Promise<string> {
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const plaintext = new TextEncoder().encode('probe-value');
+  const ciphertext = await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv: iv as BufferSource },
+    cmk,
+    plaintext,
+  );
+  return `${Buffer.from(iv).toString('base64')}:${Buffer.from(ciphertext).toString('base64')}`;
+}
+
+async function decrypts(cmk: CryptoKey, token: string): Promise<string> {
+  const [ivB64, ctB64] = token.split(':');
+  const iv = new Uint8Array(Buffer.from(ivB64 ?? '', 'base64'));
+  const ciphertext = new Uint8Array(Buffer.from(ctB64 ?? '', 'base64'));
+  const plaintext = await crypto.subtle.decrypt(
+    { name: 'AES-GCM', iv: iv as BufferSource },
+    cmk,
+    ciphertext as BufferSource,
+  );
+  return new TextDecoder().decode(plaintext);
+}
+
+describe('generateRecoverySecret', () => {
+  it('produces a grouped, high-entropy, non-ambiguous secret', () => {
+    const secret = generateRecoverySecret();
+    expect(secret).toMatch(/^[A-Z2-9]{5}(-[A-Z2-9]{5}){3}$/);
+    expect(secret).not.toMatch(/[01IOL]/);
+    expect(generateRecoverySecret()).not.toBe(generateRecoverySecret());
+  });
+});
+
+describe('recovery-secret CMK wrap/unwrap', () => {
+  it('round-trips: unwrapping with the correct secret recovers the same CMK', async () => {
+    const cmk = await generateCmk();
+    const secret = generateRecoverySecret();
+    const wrapped = await wrapCmkWithRecoverySecret(cmk, secret);
+
+    const unwrapped = await unwrapCmkWithRecoverySecret(wrapped, secret);
+
+    const token = await roundTripsThrough(cmk);
+    expect(await decrypts(unwrapped, token)).toBe('probe-value');
+  });
+
+  it('rejects the wrong recovery secret', async () => {
+    const cmk = await generateCmk();
+    const wrapped = await wrapCmkWithRecoverySecret(cmk, generateRecoverySecret());
+
+    await expect(unwrapCmkWithRecoverySecret(wrapped, generateRecoverySecret())).rejects.toThrow();
+  });
+
+  it('never puts the CMK or secret in the wrapped output', async () => {
+    const cmk = await generateCmk();
+    const secret = generateRecoverySecret();
+    const wrapped = await wrapCmkWithRecoverySecret(cmk, secret);
+
+    const serialized = JSON.stringify(wrapped);
+    expect(serialized).not.toContain(secret);
+    // The wrapped ciphertext is base64url — a plaintext raw AES key would
+    // never appear as a readable substring of it in any case, but assert the
+    // shape is opaque ciphertext, not something structured/inspectable.
+    expect(wrapped.wrappedCmk).toMatch(/^[A-Za-z0-9_-]+$/);
+  });
+
+  it('produces a different salt/ciphertext on every call (fresh IV and salt)', async () => {
+    const cmk = await generateCmk();
+    const secret = generateRecoverySecret();
+    const first = await wrapCmkWithRecoverySecret(cmk, secret);
+    const second = await wrapCmkWithRecoverySecret(cmk, secret);
+
+    expect(first.kdfSalt).not.toBe(second.kdfSalt);
+    expect(first.wrappedCmk).not.toBe(second.wrappedCmk);
+  });
+});
+
+describe('device-key CMK wrap/unwrap', () => {
+  it('round-trips: unwrapping with the same device key recovers the same CMK', async () => {
+    const cmk = await generateCmk();
+    const deviceKey = await generateDeviceKey();
+    const wrapped = await wrapCmkWithDeviceKey(cmk, deviceKey);
+
+    const unwrapped = await unwrapCmkWithDeviceKey(wrapped, deviceKey);
+
+    const token = await roundTripsThrough(cmk);
+    expect(await decrypts(unwrapped, token)).toBe('probe-value');
+  });
+
+  it('rejects unwrapping with a different device key', async () => {
+    const cmk = await generateCmk();
+    const deviceKey = await generateDeviceKey();
+    const otherDeviceKey = await generateDeviceKey();
+    const wrapped = await wrapCmkWithDeviceKey(cmk, deviceKey);
+
+    await expect(unwrapCmkWithDeviceKey(wrapped, otherDeviceKey)).rejects.toThrow();
+  });
+
+  it('generates a non-extractable device key', async () => {
+    const deviceKey = await generateDeviceKey();
+    expect(deviceKey.extractable).toBe(false);
+  });
+});
+
+describe('per-object DEK wrap/unwrap', () => {
+  it('round-trips: unwrapping with the same CMK recovers the same DEK', async () => {
+    const cmk = await generateCmk();
+    const dek = await generateDek();
+    const wrapped = await wrapDekWithCmk(dek, cmk);
+
+    const unwrapped = await unwrapDekWithCmk(wrapped, cmk);
+
+    const token = await roundTripsThrough(dek);
+    expect(await decrypts(unwrapped, token)).toBe('probe-value');
+  });
+
+  it('rejects unwrapping with a different CMK', async () => {
+    const cmk = await generateCmk();
+    const otherCmk = await generateCmk();
+    const dek = await generateDek();
+    const wrapped = await wrapDekWithCmk(dek, cmk);
+
+    await expect(unwrapDekWithCmk(wrapped, otherCmk)).rejects.toThrow();
+  });
+
+  it('produces a `wrappedDek` field, distinct from a wrapped CMK', async () => {
+    const cmk = await generateCmk();
+    const dek = await generateDek();
+    const wrapped = await wrapDekWithCmk(dek, cmk);
+
+    expect(wrapped).toHaveProperty('wrappedDek');
+    expect(wrapped.wrappedDek).toMatch(/^[A-Za-z0-9_-]+$/);
+  });
+
+  it('produces a different ciphertext on every call (fresh IV)', async () => {
+    const cmk = await generateCmk();
+    const dek = await generateDek();
+    const first = await wrapDekWithCmk(dek, cmk);
+    const second = await wrapDekWithCmk(dek, cmk);
+
+    expect(first.wrappedDek).not.toBe(second.wrappedDek);
+  });
+});

package/src/__tests__/e2ee-object.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+import { generateDek } from '../e2ee-crypto';
+import { decryptBlob, decryptJson, encryptBlob, encryptJson } from '../e2ee-object';
+
+describe('encryptBlob/decryptBlob', () => {
+  it('round-trips: decrypting with the same DEK recovers the original bytes and content type', async () => {
+    const dek = await generateDek();
+    const original = new Blob(['hello encrypted world'], { type: 'text/plain' });
+
+    const encrypted = await encryptBlob(dek, original);
+    const decrypted = await decryptBlob(dek, encrypted);
+
+    expect(decrypted.type).toBe('text/plain');
+    expect(await decrypted.text()).toBe('hello encrypted world');
+  });
+
+  it('rejects decrypting with a different DEK', async () => {
+    const dek = await generateDek();
+    const otherDek = await generateDek();
+    const encrypted = await encryptBlob(dek, new Blob(['secret']));
+
+    await expect(decryptBlob(otherDek, encrypted)).rejects.toThrow();
+  });
+
+  it('never puts the plaintext in the ciphertext Blob', async () => {
+    const dek = await generateDek();
+    const encrypted = await encryptBlob(dek, new Blob(['a very secret document']));
+
+    const ciphertextText = await encrypted.ciphertext.text();
+    expect(ciphertextText).not.toContain('a very secret document');
+  });
+
+  it('produces a different ciphertext on every call (fresh IV)', async () => {
+    const dek = await generateDek();
+    const blob = new Blob(['same content']);
+
+    const first = await encryptBlob(dek, blob);
+    const second = await encryptBlob(dek, blob);
+
+    expect(first.iv).not.toBe(second.iv);
+  });
+});
+
+describe('encryptJson/decryptJson', () => {
+  interface CardMetadata {
+    title: string;
+    issuer: string;
+    notes?: string;
+  }
+
+  it('round-trips: decrypting with the same DEK recovers the original value', async () => {
+    const dek = await generateDek();
+    const value: CardMetadata = {
+      title: 'Costco',
+      issuer: 'Costco Wholesale',
+      notes: 'expires 2027',
+    };
+
+    const encrypted = await encryptJson(dek, value);
+    const decrypted = await decryptJson<CardMetadata>(dek, encrypted);
+
+    expect(decrypted).toEqual(value);
+  });
+
+  it('rejects decrypting with a different DEK', async () => {
+    const dek = await generateDek();
+    const otherDek = await generateDek();
+    const encrypted = await encryptJson(dek, { title: 'secret' });
+
+    await expect(decryptJson(otherDek, encrypted)).rejects.toThrow();
+  });
+
+  it('never puts the plaintext value in the ciphertext', async () => {
+    const dek = await generateDek();
+    const encrypted = await encryptJson(dek, { documentNumber: 'A1234567' });
+
+    expect(encrypted.ciphertext).not.toContain('A1234567');
+  });
+
+  it('produces a different ciphertext on every call (fresh IV)', async () => {
+    const dek = await generateDek();
+    const value = { title: 'same value' };
+
+    const first = await encryptJson(dek, value);
+    const second = await encryptJson(dek, value);
+
+    expect(first.iv).not.toBe(second.iv);
+    expect(first.ciphertext).not.toBe(second.ciphertext);
+  });
+});

package/src/__tests__/e2ee-state.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest';
+import type { E2eeDeviceEnrollment, E2eeProfile } from '../types';
+import { classifyE2eeLocalState } from '../e2ee-state';
+
+const profile: E2eeProfile = {
+  id: 'profile-1',
+  userId: 'user-1',
+  status: 'active',
+  cmkAlgorithm: 'AES-GCM-256',
+  createdAt: 0,
+  updatedAt: 0,
+};
+
+function enrollment(overrides: Partial<E2eeDeviceEnrollment> = {}): E2eeDeviceEnrollment {
+  return {
+    id: 'enrollment-1',
+    userId: 'user-1',
+    deviceId: 'device-1',
+    deviceLabel: 'Chrome on macOS',
+    wrappedCmk: 'opaque',
+    algorithmVersion: 'v1',
+    createdAt: 0,
+    lastUsedAt: null,
+    revokedAt: null,
+    ...overrides,
+  };
+}
+
+describe('classifyE2eeLocalState', () => {
+  it('returns not-set-up when there is no profile', () => {
+    const result = classifyE2eeLocalState(null, [], 'device-1', null);
+    expect(result).toEqual({
+      state: 'not-set-up',
+      deviceId: null,
+      deviceKey: null,
+      activeEnrollment: null,
+    });
+  });
+
+  it('returns locked when a profile exists but this device has no local key', () => {
+    const result = classifyE2eeLocalState(profile, [enrollment()], 'device-1', null);
+    expect(result.state).toBe('locked');
+    expect(result.deviceKey).toBeNull();
+  });
+
+  it('returns locked when this device has a local key but no active enrollment record', () => {
+    const fakeKey = {} as CryptoKey;
+    const result = classifyE2eeLocalState(profile, [], 'device-1', fakeKey);
+    expect(result.state).toBe('locked');
+  });
+
+  it('returns locked when this device has a local key but its enrollment was revoked', () => {
+    const fakeKey = {} as CryptoKey;
+    const result = classifyE2eeLocalState(
+      profile,
+      [enrollment({ revokedAt: 12345 })],
+      'device-1',
+      fakeKey,
+    );
+    expect(result.state).toBe('locked');
+  });
+
+  it('returns unlocked when this device has both a local key and an active enrollment', () => {
+    const fakeKey = {} as CryptoKey;
+    const activeEnrollment = enrollment();
+    const result = classifyE2eeLocalState(profile, [activeEnrollment], 'device-1', fakeKey);
+
+    expect(result).toEqual({
+      state: 'unlocked',
+      deviceId: 'device-1',
+      deviceKey: fakeKey,
+      activeEnrollment,
+    });
+  });
+
+  it('only matches the enrollment for this specific device id', () => {
+    const fakeKey = {} as CryptoKey;
+    const otherDeviceEnrollment = enrollment({ deviceId: 'device-2' });
+    const result = classifyE2eeLocalState(profile, [otherDeviceEnrollment], 'device-1', fakeKey);
+
+    expect(result.state).toBe('locked');
+  });
+});