@sovereignfs/sdk 1.25.0 → 2.0.0

package/src/e2ee-device.ts

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

package/src/e2ee-object.ts

@@ -1,118 +0,0 @@
-/**
- * Encrypt/decrypt helpers for plugin object content under a per-object Data
- * Encryption Key (DEK) (RFC 0060 step 4). Pure WebCrypto, browser-only in
- * practice (also runs in Node for testing). Callers are responsible for
- * generating the DEK (`generateDek` in `e2ee-crypto.ts`) and wrapping it
- * under the unlocked CMK (`wrapDekWithCmk`) before storing the wrapped DEK
- * alongside the ciphertext this module produces — this module only ever
- * touches the unwrapped DEK, never the CMK.
- *
- * Two shapes are covered, matching RFC 0060's plaintext/encrypted metadata
- * split:
- * - `encryptBlob`/`decryptBlob` — binary payloads (document images, etc.)
- *   meant to travel through `sdk.storage` as opaque ciphertext.
- * - `encryptJson`/`decryptJson` — the "encrypted metadata" half of an
- *   object's fields (human-readable title, notes, document number, etc.),
- *   as opposed to the plaintext routing metadata (object id, plugin id,
- *   storage key) plugins keep server-visible.
- *
- * Each result carries its own IV and `algorithmVersion` so a future cipher
- * change is versioned per-object, not global — mirrors the wrapped-key shapes
- * in `e2ee-crypto.ts`.
- */
-
-const AES_GCM_IV_BYTES = 12;
-
-export const OBJECT_ALGORITHM_VERSION = 'v1';
-
-/** Encrypted binary payload — the `ciphertext` Blob is safe to upload as opaque bytes. */
-export interface EncryptedBlob {
-  ciphertext: Blob;
-  /** Base64url IV used for this encryption. */
-  iv: string;
-  algorithmVersion: string;
-  /** The original `Blob.type`, needed to reconstruct it on decrypt. */
-  contentType: string;
-}
-
-/** Encrypted JSON metadata — safe to store server-side as opaque ciphertext. */
-export interface EncryptedJson {
-  /** Base64url ciphertext of the UTF-8 JSON-serialized value. */
-  ciphertext: string;
-  /** Base64url IV used for this encryption. */
-  iv: 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;
-}
-
-/** Encrypt a `Blob` (e.g. a document image) under the given DEK. */
-export async function encryptBlob(dek: CryptoKey, blob: Blob): Promise<EncryptedBlob> {
-  const iv = crypto.getRandomValues(new Uint8Array(AES_GCM_IV_BYTES));
-  const plaintext = await blob.arrayBuffer();
-  const ciphertext = await crypto.subtle.encrypt(
-    { name: 'AES-GCM', iv: iv as BufferSource },
-    dek,
-    plaintext,
-  );
-  return {
-    ciphertext: new Blob([ciphertext], { type: 'application/octet-stream' }),
-    iv: toBase64Url(iv),
-    algorithmVersion: OBJECT_ALGORITHM_VERSION,
-    contentType: blob.type,
-  };
-}
-
-/** Decrypt a `Blob` previously produced by `encryptBlob` with the matching DEK. */
-export async function decryptBlob(dek: CryptoKey, encrypted: EncryptedBlob): Promise<Blob> {
-  const iv = fromBase64Url(encrypted.iv);
-  const ciphertext = await encrypted.ciphertext.arrayBuffer();
-  const plaintext = await crypto.subtle.decrypt(
-    { name: 'AES-GCM', iv: iv as BufferSource },
-    dek,
-    ciphertext,
-  );
-  return new Blob([plaintext], { type: encrypted.contentType });
-}
-
-/** Encrypt a JSON-serializable value (e.g. an object's human-readable metadata) under the given DEK. */
-export async function encryptJson<T>(dek: CryptoKey, value: T): Promise<EncryptedJson> {
-  const iv = crypto.getRandomValues(new Uint8Array(AES_GCM_IV_BYTES));
-  const plaintext = new TextEncoder().encode(JSON.stringify(value));
-  const ciphertext = await crypto.subtle.encrypt(
-    { name: 'AES-GCM', iv: iv as BufferSource },
-    dek,
-    plaintext,
-  );
-  return {
-    ciphertext: toBase64Url(ciphertext),
-    iv: toBase64Url(iv),
-    algorithmVersion: OBJECT_ALGORITHM_VERSION,
-  };
-}
-
-/** Decrypt a JSON value previously produced by `encryptJson` with the matching DEK. */
-export async function decryptJson<T>(dek: CryptoKey, encrypted: EncryptedJson): Promise<T> {
-  const iv = fromBase64Url(encrypted.iv);
-  const ciphertext = fromBase64Url(encrypted.ciphertext);
-  const plaintext = await crypto.subtle.decrypt(
-    { name: 'AES-GCM', iv: iv as BufferSource },
-    dek,
-    ciphertext as BufferSource,
-  );
-  return JSON.parse(new TextDecoder().decode(plaintext)) as T;
-}

package/src/e2ee-state.ts

@@ -1,72 +0,0 @@
-/**
- * Locked/unlocked state detection for client-side encryption (RFC 0060 SDK
- * responsibility: "returning normalized unsupported/locked/error states").
- * Consolidates the checks every consumer of `sdk.e2ee` needs before touching
- * encrypted data — browser support, this device's local wrapping key, and
- * whether this device has an active (non-revoked) enrollment — into one
- * reusable helper instead of each plugin (Account today, Wallet later)
- * reimplementing the same logic inline.
- */
-import type { E2eeDeviceEnrollment, E2eeProfile, E2eeState } from './types';
-import { getDeviceKey, getOrCreateDeviceId } from './e2ee-device';
-
-export interface E2eeLocalState {
-  state: E2eeState;
-  /** Null only when `state` is `'unsupported'` or `'not-set-up'`. */
-  deviceId: string | null;
-  /** This device's local wrapping key — present only when `state` is `'unlocked'`. */
-  deviceKey: CryptoKey | null;
-  /** This device's active enrollment record — present only when `state` is `'unlocked'`. */
-  activeEnrollment: E2eeDeviceEnrollment | null;
-}
-
-/** True when the current environment has the WebCrypto and IndexedDB primitives E2EE needs. */
-export function browserSupportsE2ee(): boolean {
-  return (
-    typeof indexedDB !== 'undefined' &&
-    typeof crypto !== 'undefined' &&
-    typeof crypto.subtle !== 'undefined'
-  );
-}
-
-/**
- * Pure classification given already-resolved inputs — no IndexedDB access,
- * so it's trivially unit-testable. `getE2eeLocalState` below is the
- * convenience wrapper that actually reads this device's local key.
- */
-export function classifyE2eeLocalState(
-  profile: E2eeProfile | null,
-  devices: E2eeDeviceEnrollment[],
-  deviceId: string,
-  deviceKey: CryptoKey | null,
-): E2eeLocalState {
-  if (!profile) {
-    return { state: 'not-set-up', deviceId: null, deviceKey: null, activeEnrollment: null };
-  }
-  const activeEnrollment =
-    devices.find((d) => d.deviceId === deviceId && d.revokedAt === null) ?? null;
-  if (deviceKey && activeEnrollment) {
-    return { state: 'unlocked', deviceId, deviceKey, activeEnrollment };
-  }
-  return { state: 'locked', deviceId, deviceKey: null, activeEnrollment: null };
-}
-
-/**
- * Resolve this device's current E2EE state against the user's profile and
- * enrollment list (typically loaded server-side and passed in by the
- * caller). Reads this device's local wrapping key from IndexedDB.
- */
-export async function getE2eeLocalState(
-  profile: E2eeProfile | null,
-  devices: E2eeDeviceEnrollment[],
-): Promise<E2eeLocalState> {
-  if (!browserSupportsE2ee()) {
-    return { state: 'unsupported', deviceId: null, deviceKey: null, activeEnrollment: null };
-  }
-  if (!profile) {
-    return { state: 'not-set-up', deviceId: null, deviceKey: null, activeEnrollment: null };
-  }
-  const deviceId = getOrCreateDeviceId();
-  const deviceKey = await getDeviceKey(deviceId);
-  return classifyE2eeLocalState(profile, devices, deviceId, deviceKey);
-}

package/src/e2ee.ts

@@ -1,65 +0,0 @@
-import { headers } from 'next/headers';
-import { NotAuthenticatedError } from './errors';
-import { requireHost } from './host';
-import type {
-  CreateE2eeProfileInput,
-  E2eeContext,
-  E2eeDeviceEnrollment,
-  E2eeProfile,
-  E2eeRecoveryWrapper,
-  EnrollE2eeDeviceInput,
-  SetE2eeRecoveryWrapperInput,
-} from './types';
-
-const DEFAULT_TENANT_ID = 'default';
-
-async function e2eeContext(): Promise<E2eeContext> {
-  const h = await headers();
-  const userId = h.get('x-sovereign-user-id');
-  if (!userId) throw new NotAuthenticatedError();
-  return { tenantId: DEFAULT_TENANT_ID, userId };
-}
-
-/**
- * Client-side encryption profile persistence (RFC 0060). Server-side plumbing
- * only — the CMK is generated and wrapped/unwrapped in the browser
- * (`@sovereignfs/sdk/e2ee-crypto`, `@sovereignfs/sdk/e2ee-device`) before any
- * of these methods are called; the server only ever stores/returns opaque
- * ciphertext and non-sensitive KDF/algorithm metadata.
- */
-export const e2ee = {
-  async getProfile(): Promise<E2eeProfile | null> {
-    const context = await e2eeContext();
-    return requireHost().e2ee.getProfile(context);
-  },
-
-  async createProfile(input: CreateE2eeProfileInput): Promise<E2eeProfile> {
-    const context = await e2eeContext();
-    return requireHost().e2ee.createProfile(input, context);
-  },
-
-  async getRecoveryWrapper(): Promise<E2eeRecoveryWrapper | null> {
-    const context = await e2eeContext();
-    return requireHost().e2ee.getRecoveryWrapper(context);
-  },
-
-  async setRecoveryWrapper(input: SetE2eeRecoveryWrapperInput): Promise<E2eeRecoveryWrapper> {
-    const context = await e2eeContext();
-    return requireHost().e2ee.setRecoveryWrapper(input, context);
-  },
-
-  async enrollDevice(input: EnrollE2eeDeviceInput): Promise<E2eeDeviceEnrollment> {
-    const context = await e2eeContext();
-    return requireHost().e2ee.enrollDevice(input, context);
-  },
-
-  async listDevices(): Promise<E2eeDeviceEnrollment[]> {
-    const context = await e2eeContext();
-    return requireHost().e2ee.listDevices(context);
-  },
-
-  async revokeDevice(id: string): Promise<void> {
-    const context = await e2eeContext();
-    return requireHost().e2ee.revokeDevice(id, context);
-  },
-};

package/src/env.ts

@@ -1,37 +0,0 @@
-import { headers } from 'next/headers';
-
-/**
- * Plugin-scoped environment variables (RFC 0018).
- *
- * `sdk.env.get(key)` reads the calling plugin's `SV_PLUGIN_<SLUG>_<KEY>`
- * environment variable, identified by the `x-sovereign-plugin-id` header
- * that the runtime middleware injects on every plugin route request. Returns
- * `null` when the variable is absent or the call is made outside a plugin
- * route context (no `x-sovereign-plugin-id` header).
- *
- * Declare the variable in the manifest `env` field:
- * ```json
- * "env": {
- *   "API_KEY": { "description": "Third-party API key", "secret": true, "scope": "runtime", "required": true }
- * }
- * ```
- *
- * Then read it in a Server Component or Route Handler:
- * ```ts
- * import { sdk } from '@sovereignfs/sdk';
- * const apiKey = await sdk.env.get('API_KEY');
- * ```
- *
- * For `scope: "build"` variables (NEXT_PUBLIC_SV_PLUGIN_*), read the env var
- * directly from `process.env` in client components — Next.js inlines NEXT_PUBLIC_*
- * vars at build time and sdk.env.get is server-only (it uses next/headers).
- */
-export const env = {
-  async get(key: string): Promise<string | null> {
-    const h = await headers();
-    const pluginId = h.get('x-sovereign-plugin-id');
-    if (!pluginId) return null;
-    const slug = pluginId.replace(/[.-]/g, '_').toUpperCase();
-    return process.env[`SV_PLUGIN_${slug}_${key}`] ?? null;
-  },
-};

package/src/errors.ts

@@ -1,46 +0,0 @@
-/**
- * Thrown by SDK surfaces that have no standalone implementation: the v1 methods
- * that the Sovereign runtime supplies at runtime, and the post-v1 surfaces
- * (storage, notifications, events) that are declared but not yet implemented.
- */
-export class NotImplementedError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'NotImplementedError';
-  }
-}
-
-/** Thrown by `sdk.auth.requireSession()` when no authenticated session is present. */
-export class NotAuthenticatedError extends Error {
-  constructor() {
-    super('No authenticated session. The caller must be within an authenticated request.');
-    this.name = 'NotAuthenticatedError';
-  }
-}
-
-/**
- * Thrown by `sdk.data.query()` when the current user has not granted the calling
- * (consumer) plugin consent to read the requested provider contract — the
- * consent-gated cross-plugin data-sharing mechanism (RFC 0002). Reserved
- * alongside that surface; not raised until the mechanism is implemented.
- */
-export class ConsentRequiredError extends Error {
-  constructor(message = 'User consent is required to access this plugin data.') {
-    super(message);
-    this.name = 'ConsentRequiredError';
-  }
-}
-
-/**
- * Thrown by `sdk.billing.requireEntitlement()` when the current user has no
- * valid (active, unexpired) entitlement for the calling plugin (RFC 0003).
- * The runtime middleware also enforces this at the route level, so most plugins
- * never need to call `requireEntitlement()` directly — it is for in-plugin
- * feature gating by tier.
- */
-export class EntitlementRequiredError extends Error {
-  constructor(message = 'An active entitlement is required to access this feature.') {
-    super(message);
-    this.name = 'EntitlementRequiredError';
-  }
-}

package/src/host.ts

@@ -1,251 +0,0 @@
-import type { DataContractRef, DataContractResolver } from './data';
-import type { DeletionHandler, ExportResolver, ImportHandler } from './portability';
-import type { ConsentStatus, PluginAvailability, PluginListFilter } from './plugins';
-import type {
-  ActivityLogEntry,
-  DirectoryUser,
-  DrizzleClient,
-  MailOptions,
-  PlatformConfig,
-  ProviderConfig,
-  ResolveUsersInput,
-  SearchUsersInput,
-  SendNotificationInput,
-  CreateSecretInput,
-  ConnectionContext,
-  ConnectionListFilter,
-  ConnectionOAuthState,
-  ConnectionRef,
-  CreateConnectionInput,
-  CreateE2eeProfileInput,
-  E2eeContext,
-  E2eeDeviceEnrollment,
-  E2eeProfile,
-  E2eeRecoveryWrapper,
-  EnrollE2eeDeviceInput,
-  MarkConnectionErrorInput,
-  OAuthStateInput,
-  SecretContext,
-  SecretRef,
-  SecretScope,
-  SetE2eeRecoveryWrapperInput,
-  StorageContext,
-  StorageObject,
-  StoragePutInput,
-  UpdateConnectionInput,
-} from './types';
-
-/**
- * The host interface that the Sovereign runtime provides to the SDK.
- * Every method that touches platform infrastructure (DB, mailer, config) is
- * routed through this interface — the SDK itself has no runtime dependencies.
- */
-export interface SdkHost {
-  db: {
-    /**
-     * `pluginId` is the calling plugin's manifest id, read from the
-     * `x-sovereign-plugin-id` request header by the SDK. `null` means the call
-     * happened outside a plugin route context; the platform DB is returned.
-     */
-    getClient(pluginId: string | null): Promise<DrizzleClient>;
-  };
-  mailer: {
-    send(options: MailOptions): Promise<void>;
-  };
-  platform: {
-    getConfig(): Promise<PlatformConfig>;
-  };
-  directory: {
-    /**
-     * Search active users in the current tenant. `requestingUserId` and
-     * `tenantId` come from runtime-injected request context, not plugin input.
-     */
-    searchUsers(
-      input: SearchUsersInput,
-      requestingUserId: string,
-      tenantId: string,
-    ): Promise<DirectoryUser[]>;
-    /**
-     * Resolve explicit user IDs to display-safe profile fields for active users
-     * in the current tenant.
-     */
-    resolveUsers(
-      input: ResolveUsersInput,
-      requestingUserId: string,
-      tenantId: string,
-    ): Promise<DirectoryUser[]>;
-  };
-  data: {
-    /** Register a resolver for a contract this plugin provides. */
-    provide(contract: string, resolver: DataContractResolver): void;
-    /**
-     * Query a provider plugin's contract for the current user.
-     * `consumerId` and `userId` are read from request headers by the SDK caller.
-     */
-    query(
-      ref: DataContractRef,
-      consumerId: string | null,
-      userId: string | null,
-      tenantId: string,
-      params: unknown,
-    ): Promise<unknown[]>;
-  };
-  activity: {
-    /**
-     * Record one activity event.
-     * `actorId`, `pluginId`, and `tenantId` are injected by the runtime host
-     * from request headers so plugins cannot forge actor identity.
-     */
-    log(entry: ActivityLogEntry, actorId: string | null, pluginId: string | null): Promise<void>;
-  };
-  portability: {
-    /**
-     * Register a plugin's export resolver, keyed by `pluginId` (resolved by the
-     * SDK from the request context). The runtime invokes it at export time.
-     */
-    provideExport(pluginId: string, resolver: ExportResolver): void;
-    /** Register a plugin's import handler, keyed by `pluginId`. */
-    provideImport(pluginId: string, handler: ImportHandler): void;
-    /** Register a plugin's deletion handler (RFC 0033), keyed by `pluginId`. */
-    provideDelete(pluginId: string, handler: DeletionHandler): void;
-  };
-  plugins: {
-    /** Discover one installed plugin's status (RFC 0051), scoped to the given user. */
-    get(
-      id: string,
-      userId: string | null,
-      capabilities: readonly string[],
-    ): Promise<PluginAvailability | null>;
-    /** Discover installed plugins, optionally filtered, scoped to the given user. */
-    list(
-      filter: PluginListFilter | undefined,
-      userId: string | null,
-      capabilities: readonly string[],
-    ): Promise<PluginAvailability[]>;
-    /** Whether `userId` has an active consent grant for `ref`, requested by `consumerId`. */
-    getConsentStatus(
-      ref: DataContractRef,
-      consumerId: string,
-      userId: string,
-    ): Promise<ConsentStatus>;
-  };
-  notifications: {
-    /**
-     * Deliver one notification to a user. The runtime injects `source`,
-     * `sourceType`, and `tenantId` from the request context so the plugin only
-     * supplies the payload fields.
-     */
-    send(input: SendNotificationInput, pluginId: string): Promise<void>;
-  };
-  storage: {
-    put(input: StoragePutInput, context: StorageContext): Promise<StorageObject>;
-    get(
-      key: string,
-      context: StorageContext,
-    ): Promise<(StorageObject & { body: ReadableStream }) | null>;
-    delete(key: string, context: StorageContext): Promise<void>;
-    list(prefix: string | undefined, context: StorageContext): Promise<StorageObject[]>;
-    getSignedUrl(
-      key: string,
-      options: { expiresInSeconds?: number } | undefined,
-      context: StorageContext,
-    ): Promise<string>;
-  };
-  /**
-   * Client-side encryption profile persistence (RFC 0060). Pure metadata
-   * plumbing — no encryption happens here; the CMK is generated and
-   * wrapped/unwrapped entirely in the browser (`@sovereignfs/sdk`'s
-   * `e2ee-crypto`/`e2ee-device` modules) before these methods are ever
-   * called with the resulting ciphertext.
-   */
-  e2ee: {
-    getProfile(context: E2eeContext): Promise<E2eeProfile | null>;
-    createProfile(input: CreateE2eeProfileInput, context: E2eeContext): Promise<E2eeProfile>;
-    getRecoveryWrapper(context: E2eeContext): Promise<E2eeRecoveryWrapper | null>;
-    setRecoveryWrapper(
-      input: SetE2eeRecoveryWrapperInput,
-      context: E2eeContext,
-    ): Promise<E2eeRecoveryWrapper>;
-    enrollDevice(input: EnrollE2eeDeviceInput, context: E2eeContext): Promise<E2eeDeviceEnrollment>;
-    listDevices(context: E2eeContext): Promise<E2eeDeviceEnrollment[]>;
-    revokeDevice(id: string, context: E2eeContext): Promise<void>;
-  };
-  secrets: {
-    create(input: CreateSecretInput, context: SecretContext): Promise<SecretRef>;
-    get(id: string, context: SecretContext): Promise<string | null>;
-    list(scope: SecretScope | undefined, context: SecretContext): Promise<SecretRef[]>;
-    update(id: string, value: string, context: SecretContext): Promise<SecretRef>;
-    delete(id: string, context: SecretContext): Promise<void>;
-  };
-  connections: {
-    create(input: CreateConnectionInput, context: ConnectionContext): Promise<ConnectionRef>;
-    list(
-      filter: ConnectionListFilter | undefined,
-      context: ConnectionContext,
-    ): Promise<ConnectionRef[]>;
-    get(id: string, context: ConnectionContext): Promise<ConnectionRef | null>;
-    update(
-      id: string,
-      input: UpdateConnectionInput,
-      context: ConnectionContext,
-    ): Promise<ConnectionRef>;
-    disconnect(id: string, context: ConnectionContext): Promise<void>;
-    markUsed(id: string, context: ConnectionContext): Promise<void>;
-    markError(
-      id: string,
-      input: MarkConnectionErrorInput,
-      context: ConnectionContext,
-    ): Promise<ConnectionRef>;
-    createOAuthState(input: OAuthStateInput, context: ConnectionContext): Promise<string>;
-    verifyOAuthState(state: string, context: ConnectionContext): Promise<ConnectionOAuthState>;
-    getProviderConfig(provider: string, context: ConnectionContext): Promise<ProviderConfig>;
-  };
-}
-
-/**
- * The host is stored on `globalThis` under a `Symbol.for` key, NOT a plain
- * module-level variable. Next.js compiles instrumentation, route handlers, and
- * server actions into separate bundles, each of which can get its own instance
- * of this module — and dev HMR re-evaluates it on edits, resetting any
- * module-level state. With a per-module `let`, `provideHost()` (called once from
- * `runtime/instrumentation.ts`) would set the host on one instance while a
- * plugin server action reads `null` from another, throwing "no runtime host".
- * A `Symbol.for`-keyed global is shared across every module instance in the same
- * Node process, so the single registration is always visible.
- */
-const HOST_KEY = Symbol.for('@sovereignfs/sdk:host');
-
-interface HostHolder {
-  [HOST_KEY]?: SdkHost | null;
-}
-
-function holder(): HostHolder {
-  return globalThis as unknown as HostHolder;
-}
-
-/**
- * Register the platform host implementation. Called once at runtime startup
- * (via `runtime/instrumentation.ts`) before any request is served.
- *
- * Exported from `@sovereignfs/sdk` so the runtime can call it; plugin code
- * should never need to call this.
- */
-export function provideHost(host: SdkHost): void {
-  holder()[HOST_KEY] = host;
-}
-
-/**
- * Return the registered host implementation, throwing if none is registered
- * (i.e. the SDK is being executed outside the Sovereign runtime).
- */
-export function requireHost(): SdkHost {
-  const host = holder()[HOST_KEY];
-  if (!host) {
-    throw new Error(
-      '@sovereignfs/sdk: no runtime host is registered. ' +
-        'SDK methods run inside the Sovereign runtime — start the platform with `pnpm dev` ' +
-        'or `pnpm sv dev` and ensure the plugin is installed.',
-    );
-  }
-  return host;
-}