@sovereignfs/sdk 1.25.0 → 2.0.1

package/src/auth.ts

@@ -1,134 +0,0 @@
-import { headers } from 'next/headers';
-import { NotAuthenticatedError } from './errors';
-
-// v1 is single-tenant; every session belongs to this tenant id.
-const DEFAULT_TENANT_ID = 'default';
-import { markCurrentSessions, type RawSession } from './sessions';
-import type { ActiveSession, ChangePasswordInput, Session } from './types';
-
-const AUTH_URL =
-  process.env.SOVEREIGN_AUTH_URL ?? `http://localhost:${process.env.AUTH_PORT ?? '3001'}`;
-
-/** Returns the current user session from runtime-injected headers, or null if unauthenticated. */
-export async function getSession(): Promise<Session | null> {
-  const h = await headers();
-  const id = h.get('x-sovereign-user-id');
-  if (!id) return null;
-  const role = h.get('x-sovereign-user-role') ?? 'platform:user';
-  const capsRaw = h.get('x-sovereign-user-capabilities');
-  const capabilities: readonly string[] = capsRaw ? (JSON.parse(capsRaw) as string[]) : [];
-  return {
-    user: {
-      id,
-      // v1 is single-tenant, so every session belongs to the default tenant.
-      // Multi-tenant deployments will source this from the verified session.
-      tenantId: DEFAULT_TENANT_ID,
-      email: h.get('x-sovereign-user-email') ?? '',
-      name: h.get('x-sovereign-user-name') ?? null,
-      image: h.get('x-sovereign-user-image') ?? null,
-      role,
-      capabilities,
-    },
-    expiresAt: Number(h.get('x-sovereign-session-expires-at') ?? 0),
-  };
-}
-
-/**
- * Return true if the given session has the named capability (RFC 0021).
- * Plugins should call this instead of comparing `session.user.role` directly
- * to avoid coupling to the role-preset details.
- */
-export function hasCapability(session: Session | null, capability: string): boolean {
-  return session?.user.capabilities.includes(capability) ?? false;
-}
-
-/** Returns the current user session, throwing `NotAuthenticatedError` if unauthenticated. */
-export async function requireSession(): Promise<Session> {
-  const session = await getSession();
-  if (!session) throw new NotAuthenticatedError();
-  return session;
-}
-
-/**
- * Call a better-auth endpoint server-side, forwarding the caller's session
- * cookie. better-auth enforces a CSRF Origin check on state-changing routes,
- * so we send its own base URL as the trusted Origin.
- */
-async function authFetch(path: string, method: 'GET' | 'POST', body?: unknown): Promise<Response> {
-  const cookie = (await headers()).get('cookie') ?? '';
-  // No explicit `cache` option: under Next 15 fetch is uncached by default, so
-  // these credentialed calls are never cached — and the SDK stays free of
-  // Next-specific RequestInit fields so it type-checks standalone.
-  return fetch(`${AUTH_URL}${path}`, {
-    method,
-    headers: {
-      cookie,
-      origin: AUTH_URL,
-      ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
-    },
-    body: body === undefined ? undefined : JSON.stringify(body),
-  });
-}
-
-/** Build an error message including better-auth's response body, for diagnosis. */
-async function authError(res: Response, action: string): Promise<Error> {
-  const body = await res.text().catch(() => '');
-  const detail = body ? ` — ${body}` : '';
-  return new Error(`${action} (${String(res.status)})${detail}`);
-}
-
-/**
- * Change the current user's password (SRS ACC-04). Requires the current
- * password; the current session is preserved (other sessions are kept too).
- * Throws with better-auth's message on failure (e.g. wrong current password).
- */
-export async function changePassword(input: ChangePasswordInput): Promise<void> {
-  const res = await authFetch('/api/auth/change-password', 'POST', {
-    currentPassword: input.currentPassword,
-    newPassword: input.newPassword,
-    revokeOtherSessions: false,
-  });
-  if (!res.ok) {
-    const message = ((await res.json().catch(() => null)) as { message?: string } | null)?.message;
-    throw new Error(message ?? `Failed to change password (${String(res.status)}).`);
-  }
-}
-
-/** List the current user's active sessions, current one first (SRS ACC-05). */
-export async function listSessions(): Promise<ActiveSession[]> {
-  const [listRes, sessionRes] = await Promise.all([
-    authFetch('/api/auth/list-sessions', 'GET'),
-    authFetch('/api/auth/get-session', 'GET'),
-  ]);
-  if (!listRes.ok) {
-    throw await authError(listRes, 'Failed to list sessions');
-  }
-  const raw = (await listRes.json()) as RawSession[];
-  const currentToken = sessionRes.ok
-    ? (((await sessionRes.json()) as { session?: { token?: string } } | null)?.session?.token ??
-      null)
-    : null;
-  return markCurrentSessions(raw, currentToken);
-}
-
-/** Revoke a session by its token (SRS ACC-06). */
-export async function revokeSession(token: string): Promise<void> {
-  const res = await authFetch('/api/auth/revoke-session', 'POST', { token });
-  if (!res.ok) {
-    throw await authError(res, 'Failed to revoke session');
-  }
-}
-
-/**
- * Sign the current user out (SRS AUTH-02): ends the active session on the auth
- * server. The caller is responsible for clearing the runtime's `session_data`
- * cache cookies and redirecting — the platform's logout route does both.
- */
-export async function signOut(): Promise<void> {
-  // Pass an empty body so `authFetch` sends `Content-Type: application/json` —
-  // better-auth's sign-out rejects requests without it (415).
-  const res = await authFetch('/api/auth/sign-out', 'POST', {});
-  if (!res.ok) {
-    throw await authError(res, 'Failed to sign out');
-  }
-}

package/src/connections.ts

@@ -1,106 +0,0 @@
-import { headers } from 'next/headers';
-import { NotAuthenticatedError } from './errors';
-import { requireHost } from './host';
-import type {
-  ConnectionContext,
-  ConnectionListFilter,
-  ConnectionOAuthState,
-  ConnectionRef,
-  ConnectionScope,
-  CreateConnectionInput,
-  MarkConnectionErrorInput,
-  OAuthStateInput,
-  ProviderConfig,
-  UpdateConnectionInput,
-} from './types';
-
-const DEFAULT_TENANT_ID = 'default';
-
-function parseCapabilities(raw: string | null): readonly string[] {
-  if (!raw) return [];
-  try {
-    const parsed = JSON.parse(raw) as unknown;
-    return Array.isArray(parsed)
-      ? parsed.filter((cap): cap is string => typeof cap === 'string')
-      : [];
-  } catch {
-    return [];
-  }
-}
-
-async function connectionContext(): Promise<ConnectionContext> {
-  const h = await headers();
-  const pluginId = h.get('x-sovereign-plugin-id');
-  if (!pluginId) {
-    throw new Error(
-      'sdk.connections requires a plugin route context (x-sovereign-plugin-id header missing).',
-    );
-  }
-  return {
-    tenantId: DEFAULT_TENANT_ID,
-    pluginId,
-    userId: h.get('x-sovereign-user-id'),
-    capabilities: parseCapabilities(h.get('x-sovereign-user-capabilities')),
-  };
-}
-
-function requireUserForUserScope(scope: ConnectionScope | undefined, userId: string | null): void {
-  if ((scope === undefined || scope === 'user') && !userId) throw new NotAuthenticatedError();
-}
-
-/** Experimental platform-managed external connection metadata API (RFC 0049). */
-export const connections = {
-  async create(input: CreateConnectionInput): Promise<ConnectionRef> {
-    const context = await connectionContext();
-    requireUserForUserScope(input.scope, context.userId);
-    return requireHost().connections.create(input, context);
-  },
-
-  async list(filter?: ConnectionListFilter): Promise<ConnectionRef[]> {
-    const context = await connectionContext();
-    requireUserForUserScope(filter?.scope, context.userId);
-    return requireHost().connections.list(filter, context);
-  },
-
-  async get(id: string): Promise<ConnectionRef | null> {
-    const context = await connectionContext();
-    return requireHost().connections.get(id, context);
-  },
-
-  async update(id: string, input: UpdateConnectionInput): Promise<ConnectionRef> {
-    const context = await connectionContext();
-    return requireHost().connections.update(id, input, context);
-  },
-
-  async disconnect(id: string): Promise<void> {
-    const context = await connectionContext();
-    return requireHost().connections.disconnect(id, context);
-  },
-
-  async markUsed(id: string): Promise<void> {
-    const context = await connectionContext();
-    return requireHost().connections.markUsed(id, context);
-  },
-
-  async markError(id: string, input: MarkConnectionErrorInput): Promise<ConnectionRef> {
-    const context = await connectionContext();
-    return requireHost().connections.markError(id, input, context);
-  },
-
-  async createOAuthState(input: OAuthStateInput): Promise<string> {
-    const context = await connectionContext();
-    requireUserForUserScope('user', context.userId);
-    return requireHost().connections.createOAuthState(input, context);
-  },
-
-  async verifyOAuthState(state: string): Promise<ConnectionOAuthState> {
-    const context = await connectionContext();
-    requireUserForUserScope('user', context.userId);
-    return requireHost().connections.verifyOAuthState(state, context);
-  },
-
-  async getProviderConfig(provider: string): Promise<ProviderConfig> {
-    const context = await connectionContext();
-    return requireHost().connections.getProviderConfig(provider, context);
-  },
-};

package/src/data.ts

@@ -1,88 +0,0 @@
-import { headers } from 'next/headers';
-import { ConsentRequiredError } from './errors';
-import { requireHost } from './host';
-
-// v1 is single-tenant.
-const DEFAULT_TENANT_ID = 'default';
-
-/**
- * A reference to a versioned data contract exposed by a *provider* plugin, used
- * by a *consumer* plugin to request it.
- */
-export interface DataContractRef {
-  /** The provider plugin's manifest `id`. */
-  providerId: string;
-  /** The named, read-only contract the provider exposes (e.g. `"expenses"`). */
-  contract: string;
-  /** Contract major version the consumer was built against. */
-  version: number;
-}
-
-/**
- * A resolver a provider registers to answer read requests for one of its
- * contracts. The runtime invokes it only for consumers that hold an active
- * user consent grant, already scoped to the requesting user and tenant.
- */
-export type DataContractResolver<TParams = unknown, TRow = unknown> = (
-  params: TParams,
-) => Promise<TRow[]>;
-
-/**
- * Cross-plugin data sharing (RFC 0002) — consent-gated, pull-based, read-only
- * channel between plugins.
- *
- * **Provider** — register a resolver for each contract your plugin exposes
- * (declare it in the manifest `data.provides` array and add `data:provide` to
- * `permissions`):
- *
- * ```ts
- * sdk.data.provide('expenses', async ({ since }) => getExpenses({ since }));
- * ```
- *
- * **Consumer** — query a provider's contract (declare the contract in the
- * manifest `data.consumes` array and add `data:consume` to `permissions`).
- * Throws `ConsentRequiredError` when the current user has not yet granted
- * consent for this (consumer, provider, contract) triple:
- *
- * ```ts
- * const rows = await sdk.data.query(
- *   { providerId: 'com.example.finance', contract: 'expenses', version: 1 },
- *   { since: '2025-01-01' },
- * );
- * ```
- *
- * Consent is managed by the user in the Account → Data tab.
- */
-export const data = {
-  /**
-   * Provider: register a resolver for one of the contracts this plugin exposes.
-   * Call this before any consumer can query the contract — typically at the top
-   * of a route handler or server component that runs when the plugin is loaded.
-   * Registrations are in-process and reset on server restart.
-   */
-  provide<TParams = unknown, TRow = unknown>(
-    contract: string,
-    resolver: DataContractResolver<TParams, TRow>,
-  ): void {
-    requireHost().data.provide(contract, resolver as DataContractResolver);
-  },
-
-  /** Consumer: read a provider plugin's contract for the current user (consent-gated). */
-  async query<TParams = unknown, TRow = unknown>(
-    ref: DataContractRef,
-    params?: TParams,
-  ): Promise<TRow[]> {
-    const h = await headers();
-    const consumerId = h.get('x-sovereign-plugin-id');
-    const userId = h.get('x-sovereign-user-id');
-    if (!userId) throw new ConsentRequiredError();
-    const result = await requireHost().data.query(
-      ref,
-      consumerId,
-      userId,
-      DEFAULT_TENANT_ID,
-      params,
-    );
-    return result as TRow[];
-  },
-};

package/src/db.ts

@@ -1,34 +0,0 @@
-import { headers } from 'next/headers';
-import { requireHost } from './host';
-import type { DrizzleClient } from './types';
-
-/**
- * Returns the Drizzle client for this plugin's database.
- *
- * **Shared plugins** (the default, `database` omitted or `"shared"`) receive
- * the platform DB. Tables must be slug-prefixed (e.g. `tasks_lists`) and carry
- * a `tenant_id` column. `sdk.db.getClient()` is unchanged for these plugins —
- * isolation is transparent to the caller.
- *
- * **Isolated plugins** (`database: "isolated"` in the manifest) receive a
- * dedicated Drizzle instance backed by their own SQLite file or Postgres
- * schema. No slug prefix is required inside an isolated store. Tables should
- * still carry `tenant_id` for multi-tenancy readiness.
- *
- * The plugin ID is read from the `x-sovereign-plugin-id` request header
- * injected by the runtime middleware. Outside a plugin route context (e.g.
- * instrumentation startup code) the platform DB is returned.
- *
- * Async by contract: the platform DB is dialect-agnostic and Postgres has no
- * synchronous query (SRS §3.6).
- */
-export async function getClient(): Promise<DrizzleClient> {
-  let pluginId: string | null = null;
-  try {
-    const h = await headers();
-    pluginId = h.get('x-sovereign-plugin-id');
-  } catch {
-    // Outside a Next.js request context — no plugin ID available.
-  }
-  return requireHost().db.getClient(pluginId);
-}

package/src/directory.ts

@@ -1,31 +0,0 @@
-import { headers } from 'next/headers';
-import { NotAuthenticatedError } from './errors';
-import { requireHost } from './host';
-import type { DirectoryUser, ResolveUsersInput, SearchUsersInput } from './types';
-
-const DEFAULT_TENANT_ID = 'default';
-
-/** Privacy-preserving user directory for member selection and sharing flows. */
-export const directory = {
-  /**
-   * Search active users in the current tenant by display name or email.
-   * Results include only display-safe profile fields.
-   */
-  async searchUsers(input: SearchUsersInput): Promise<DirectoryUser[]> {
-    const h = await headers();
-    const userId = h.get('x-sovereign-user-id');
-    if (!userId) throw new NotAuthenticatedError();
-    return requireHost().directory.searchUsers(input, userId, DEFAULT_TENANT_ID);
-  },
-
-  /**
-   * Resolve explicit user IDs already stored by a plugin into display-safe
-   * profile rows for active users.
-   */
-  async resolveUsers(input: ResolveUsersInput): Promise<DirectoryUser[]> {
-    const h = await headers();
-    const userId = h.get('x-sovereign-user-id');
-    if (!userId) throw new NotAuthenticatedError();
-    return requireHost().directory.resolveUsers(input, userId, DEFAULT_TENANT_ID);
-  },
-};

package/src/e2ee-crypto.ts

@@ -1,260 +0,0 @@
-/**
- * Client-side Client Master Key (CMK) crypto (RFC 0060). Pure WebCrypto —
- * runs in the browser (or any environment with a global `crypto.subtle`,
- * which includes Node for testing). No plaintext key material or wrapped
- * bytes ever need to leave this module's caller before being sent to the
- * server as opaque ciphertext.
- *
- * Resolves RFC 0060 open question 2 (browser KDF choice): PBKDF2-HMAC-SHA256
- * via native WebCrypto, not Argon2id — Argon2id has no native WebCrypto
- * primitive, and pulling in a WASM implementation is out of scope for this
- * pass. `kdfAlgorithm`/`kdfParams` are stored per-wrapper specifically so a
- * future Argon2id upgrade doesn't require a schema change, only a new
- * `kdfAlgorithm` value and a migration path for existing wrappers.
- *
- * Scope: CMK generation, master-key wrap/unwrap (recovery secret, device
- * key), and per-object Data Encryption Key (DEK) generation/wrap/unwrap.
- * Generic Blob/JSON encrypt/decrypt helpers that use a DEK live in
- * `e2ee-object.ts`; this module only handles key material.
- */
-
-const AES_GCM_KEY_LENGTH = 256;
-const AES_GCM_IV_BYTES = 12;
-const PBKDF2_SALT_BYTES = 16;
-const PBKDF2_ITERATIONS = 600_000; // OWASP 2023 guidance for PBKDF2-HMAC-SHA256
-const RECOVERY_SECRET_ENTROPY_BYTES = 20; // 160 bits
-
-export const CMK_ALGORITHM = 'AES-GCM-256';
-export const KDF_ALGORITHM = 'PBKDF2-SHA256';
-export const WRAP_ALGORITHM_VERSION = 'v1';
-
-/** The CMK both encrypts/decrypts content directly and wraps/unwraps per-object DEKs. */
-const CMK_KEY_USAGES: KeyUsage[] = ['encrypt', 'decrypt', 'wrapKey', 'unwrapKey'];
-/** A DEK only ever encrypts/decrypts object content — it never wraps another key. */
-const DEK_KEY_USAGES: KeyUsage[] = ['encrypt', 'decrypt'];
-
-/** Base64url `iv || ciphertext` for a wrapped key, plus the algorithm version it was wrapped under. */
-interface WrappedKey {
-  value: string;
-  algorithmVersion: string;
-}
-
-/** Ciphertext + metadata needed to unwrap a CMK later. Safe to store server-side as-is. */
-export interface WrappedCmk {
-  /** Base64url `iv || ciphertext`. */
-  wrappedCmk: string;
-  algorithmVersion: string;
-}
-
-/** A `WrappedCmk` plus the KDF metadata needed to re-derive the wrapping key from a secret. */
-export interface RecoveryWrappedCmk extends WrappedCmk {
-  kdfAlgorithm: string;
-  /** JSON-encoded KDF parameters. */
-  kdfParams: string;
-  kdfSalt: string;
-}
-
-/** Ciphertext + metadata needed to unwrap a per-object DEK later. Safe to store server-side as-is. */
-export interface WrappedDek {
-  /** Base64url `iv || ciphertext`. */
-  wrappedDek: string;
-  algorithmVersion: string;
-}
-
-function toBase64Url(bytes: ArrayBuffer | Uint8Array): string {
-  const arr = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
-  let binary = '';
-  for (const byte of arr) binary += String.fromCharCode(byte);
-  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
-}
-
-function fromBase64Url(value: string): Uint8Array {
-  const padded = value.replace(/-/g, '+').replace(/_/g, '/');
-  const withPadding = padded + '='.repeat((4 - (padded.length % 4)) % 4);
-  const binary = atob(withPadding);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
-  return bytes;
-}
-
-function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
-  const out = new Uint8Array(a.length + b.length);
-  out.set(a, 0);
-  out.set(b, a.length);
-  return out;
-}
-
-/**
- * A high-entropy, human-recordable recovery secret. Grouped base32
- * (Crockford-ish alphabet, ambiguous characters removed) rather than a
- * BIP39 word list — no wordlist dependency, ~160 bits of entropy in 32
- * displayed characters across 6 groups (e.g. `AB3DE-FGH2J-...`).
- */
-export function generateRecoverySecret(): string {
-  const alphabet = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789'; // no 0/O, 1/I/L
-  const bytes = crypto.getRandomValues(new Uint8Array(RECOVERY_SECRET_ENTROPY_BYTES));
-  let out = '';
-  for (const byte of bytes) out += alphabet[byte % alphabet.length];
-  return out.match(/.{1,5}/g)?.join('-') ?? out;
-}
-
-/**
- * Generate a new, extractable Client Master Key. Includes `wrapKey`/
- * `unwrapKey` usages (not just `encrypt`/`decrypt`) since the CMK wraps
- * per-object DEKs (`wrapDekWithCmk`/`unwrapDekWithCmk` below) in addition to
- * being itself wrapped by a recovery secret or device key.
- */
-export function generateCmk(): Promise<CryptoKey> {
-  return crypto.subtle.generateKey(
-    { name: 'AES-GCM', length: AES_GCM_KEY_LENGTH },
-    true,
-    CMK_KEY_USAGES,
-  );
-}
-
-async function deriveWrappingKeyFromSecret(secret: string, salt: Uint8Array): Promise<CryptoKey> {
-  const keyMaterial = await crypto.subtle.importKey(
-    'raw',
-    new TextEncoder().encode(secret.normalize('NFKC')),
-    'PBKDF2',
-    false,
-    ['deriveKey'],
-  );
-  return crypto.subtle.deriveKey(
-    { name: 'PBKDF2', salt: salt as BufferSource, iterations: PBKDF2_ITERATIONS, hash: 'SHA-256' },
-    keyMaterial,
-    { name: 'AES-GCM', length: AES_GCM_KEY_LENGTH },
-    false,
-    ['wrapKey', 'unwrapKey'],
-  );
-}
-
-/** Wrap the CMK with a key derived from the user's recovery secret. */
-export async function wrapCmkWithRecoverySecret(
-  cmk: CryptoKey,
-  recoverySecret: string,
-): Promise<RecoveryWrappedCmk> {
-  const salt = crypto.getRandomValues(new Uint8Array(PBKDF2_SALT_BYTES));
-  const wrappingKey = await deriveWrappingKeyFromSecret(recoverySecret, salt);
-  const iv = crypto.getRandomValues(new Uint8Array(AES_GCM_IV_BYTES));
-  const wrapped = await crypto.subtle.wrapKey('raw', cmk, wrappingKey, {
-    name: 'AES-GCM',
-    iv: iv as BufferSource,
-  });
-  return {
-    wrappedCmk: toBase64Url(concatBytes(iv, new Uint8Array(wrapped))),
-    kdfAlgorithm: KDF_ALGORITHM,
-    kdfParams: JSON.stringify({ iterations: PBKDF2_ITERATIONS, hash: 'SHA-256' }),
-    kdfSalt: toBase64Url(salt),
-    algorithmVersion: WRAP_ALGORITHM_VERSION,
-  };
-}
-
-/** Unwrap the CMK given the recovery secret. Throws if the secret is wrong. */
-export async function unwrapCmkWithRecoverySecret(
-  wrapped: RecoveryWrappedCmk,
-  recoverySecret: string,
-): Promise<CryptoKey> {
-  const salt = fromBase64Url(wrapped.kdfSalt);
-  const wrappingKey = await deriveWrappingKeyFromSecret(recoverySecret, salt);
-  const combined = fromBase64Url(wrapped.wrappedCmk);
-  const iv = combined.slice(0, AES_GCM_IV_BYTES);
-  const ciphertext = combined.slice(AES_GCM_IV_BYTES);
-  return crypto.subtle.unwrapKey(
-    'raw',
-    ciphertext as BufferSource,
-    wrappingKey,
-    { name: 'AES-GCM', iv: iv as BufferSource },
-    { name: 'AES-GCM', length: AES_GCM_KEY_LENGTH },
-    true,
-    CMK_KEY_USAGES,
-  );
-}
-
-/**
- * Generate a device-local wrapping key. Non-extractable — once created, no
- * script (including a compromised page on this origin) can ever read its raw
- * bytes back out via `exportKey`; it can only be used, via its `CryptoKey`
- * handle, for wrap/unwrap. Must be persisted with IndexedDB (the only Web
- * storage API that can hold a live `CryptoKey`) — see `e2ee-device.ts`.
- */
-export function generateDeviceKey(): Promise<CryptoKey> {
-  return crypto.subtle.generateKey({ name: 'AES-GCM', length: AES_GCM_KEY_LENGTH }, false, [
-    'wrapKey',
-    'unwrapKey',
-  ]);
-}
-
-async function wrapKeyWith(key: CryptoKey, wrappingKey: CryptoKey): Promise<WrappedKey> {
-  const iv = crypto.getRandomValues(new Uint8Array(AES_GCM_IV_BYTES));
-  const wrapped = await crypto.subtle.wrapKey('raw', key, wrappingKey, {
-    name: 'AES-GCM',
-    iv: iv as BufferSource,
-  });
-  return {
-    value: toBase64Url(concatBytes(iv, new Uint8Array(wrapped))),
-    algorithmVersion: WRAP_ALGORITHM_VERSION,
-  };
-}
-
-async function unwrapKeyWith(
-  wrappedValue: string,
-  wrappingKey: CryptoKey,
-  extractable: boolean,
-  usages: KeyUsage[],
-): Promise<CryptoKey> {
-  const combined = fromBase64Url(wrappedValue);
-  const iv = combined.slice(0, AES_GCM_IV_BYTES);
-  const ciphertext = combined.slice(AES_GCM_IV_BYTES);
-  return crypto.subtle.unwrapKey(
-    'raw',
-    ciphertext as BufferSource,
-    wrappingKey,
-    { name: 'AES-GCM', iv: iv as BufferSource },
-    { name: 'AES-GCM', length: AES_GCM_KEY_LENGTH },
-    extractable,
-    usages,
-  );
-}
-
-/** Wrap the CMK with this device's own key. */
-export async function wrapCmkWithDeviceKey(
-  cmk: CryptoKey,
-  deviceKey: CryptoKey,
-): Promise<WrappedCmk> {
-  const { value, algorithmVersion } = await wrapKeyWith(cmk, deviceKey);
-  return { wrappedCmk: value, algorithmVersion };
-}
-
-/** Unwrap the CMK using this device's own key. */
-export function unwrapCmkWithDeviceKey(
-  wrapped: WrappedCmk,
-  deviceKey: CryptoKey,
-): Promise<CryptoKey> {
-  return unwrapKeyWith(wrapped.wrappedCmk, deviceKey, true, CMK_KEY_USAGES);
-}
-
-/**
- * Generate a new, extractable per-object Data Encryption Key (DEK). One DEK
- * per encrypted object/document — never reused across objects — so
- * compromising a single object's key never exposes any other object (RFC
- * 0060 key hierarchy: CMK wraps DEKs, DEKs encrypt object content).
- */
-export function generateDek(): Promise<CryptoKey> {
-  return crypto.subtle.generateKey(
-    { name: 'AES-GCM', length: AES_GCM_KEY_LENGTH },
-    true,
-    DEK_KEY_USAGES,
-  );
-}
-
-/** Wrap a per-object DEK with the (unlocked) CMK. Safe to store server-side as-is. */
-export async function wrapDekWithCmk(dek: CryptoKey, cmk: CryptoKey): Promise<WrappedDek> {
-  const { value, algorithmVersion } = await wrapKeyWith(dek, cmk);
-  return { wrappedDek: value, algorithmVersion };
-}
-
-/** Unwrap a per-object DEK using the (unlocked) CMK. Throws if the CMK doesn't match. */
-export function unwrapDekWithCmk(wrapped: WrappedDek, cmk: CryptoKey): Promise<CryptoKey> {
-  return unwrapKeyWith(wrapped.wrappedDek, cmk, true, DEK_KEY_USAGES);
-}