@sovereignfs/sdk 1.25.0

package/src/connections.ts

@@ -0,0 +1,106 @@
+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

@@ -0,0 +1,88 @@
+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

@@ -0,0 +1,34 @@
+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

@@ -0,0 +1,31 @@
+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

@@ -0,0 +1,260 @@
+/**
+ * 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);
+}

package/src/e2ee-device.ts

@@ -0,0 +1,75 @@
+/**
+ * Browser-only persistence for this device's local E2EE wrapping key
+ * (RFC 0060). The key itself is generated non-extractable
+ * (`e2ee-crypto.ts#generateDeviceKey`) so it must be persisted via
+ * IndexedDB — the only Web storage API that can hold a live `CryptoKey`
+ * across page loads (`localStorage`/cookies cannot serialize one).
+ *
+ * The device id is a random UUID, not sensitive on its own (it is just a
+ * label distinguishing this browser/device's enrollment row from others) and
+ * is stored in `localStorage` alongside the IndexedDB key entry.
+ */
+
+const DB_NAME = 'sovereign-e2ee';
+const DB_VERSION = 1;
+const STORE_NAME = 'device-keys';
+const DEVICE_ID_STORAGE_KEY = 'sovereign:e2ee:deviceId';
+
+function openDb(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(DB_NAME, DB_VERSION);
+    request.onupgradeneeded = () => {
+      if (!request.result.objectStoreNames.contains(STORE_NAME)) {
+        request.result.createObjectStore(STORE_NAME);
+      }
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error('Failed to open IndexedDB.'));
+  });
+}
+
+/** This browser/device's stable id — generated once, persisted in `localStorage`. */
+export function getOrCreateDeviceId(): string {
+  const existing = localStorage.getItem(DEVICE_ID_STORAGE_KEY);
+  if (existing) return existing;
+  const id = crypto.randomUUID();
+  localStorage.setItem(DEVICE_ID_STORAGE_KEY, id);
+  return id;
+}
+
+/** Persist this device's local wrapping key, keyed by device id. */
+export async function storeDeviceKey(deviceId: string, key: CryptoKey): Promise<void> {
+  const db = await openDb();
+  await new Promise<void>((resolve, reject) => {
+    const tx = db.transaction(STORE_NAME, 'readwrite');
+    tx.objectStore(STORE_NAME).put(key, deviceId);
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error ?? new Error('Failed to store device key.'));
+  });
+  db.close();
+}
+
+/** Read this device's local wrapping key, or `null` if never enrolled on this device/browser. */
+export async function getDeviceKey(deviceId: string): Promise<CryptoKey | null> {
+  const db = await openDb();
+  const result = await new Promise<CryptoKey | null>((resolve, reject) => {
+    const tx = db.transaction(STORE_NAME, 'readonly');
+    const request = tx.objectStore(STORE_NAME).get(deviceId);
+    request.onsuccess = () => resolve((request.result as CryptoKey | undefined) ?? null);
+    request.onerror = () => reject(request.error ?? new Error('Failed to read device key.'));
+  });
+  db.close();
+  return result;
+}
+
+/** Remove this device's local wrapping key (e.g. after the user revokes it from another device). */
+export async function forgetDeviceKey(deviceId: string): Promise<void> {
+  const db = await openDb();
+  await new Promise<void>((resolve, reject) => {
+    const tx = db.transaction(STORE_NAME, 'readwrite');
+    tx.objectStore(STORE_NAME).delete(deviceId);
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error ?? new Error('Failed to remove device key.'));
+  });
+  db.close();
+}