@sovereignfs/sdk 1.25.0 → 2.0.0

package/src/index.ts

@@ -1,160 +0,0 @@
-import * as auth from './auth';
-import { activity } from './activity';
-import { connections } from './connections';
-import { data } from './data';
-import { directory } from './directory';
-import * as db from './db';
-import { e2ee } from './e2ee';
-import { env } from './env';
-import * as mailer from './mailer';
-import { notifications } from './notifications';
-import * as platform from './platform';
-import { plugins } from './plugins';
-import { portability } from './portability';
-import { secrets } from './secrets';
-import { storage } from './storage';
-import { billing, events } from './unimplemented';
-
-/**
- * The Sovereign SDK — the only contract between a plugin and the platform.
- *
- * **Stable surface (covered by the v1.0.0 semver guarantee** — see
- * `docs/sdk-stability.md`): `auth`, `db`, `mailer`, `platform`. These are
- * implemented and will not change in breaking ways without a major bump +
- * migration note (NFR-04).
- *
- * **Experimental / reserved (NOT covered by the stability guarantee):** `data`
- * (cross-plugin data sharing, RFC 0002), `activity` (activity log, RFC 0005),
- * `portability` (user data export/import, RFC 0007), `env` (plugin-scoped env
- * vars, RFC 0018), `notifications` (notification center, RFC 0015),
- * `directory` (member selection, RFC 0041), `secrets` (plugin secret vault,
- * RFC 0043), `storage` (plugin file storage, RFC 0044), `connections`
- * (external provider connections, RFC 0049), `e2ee` (client-side encryption
- * profile persistence, RFC 0060 — profile/device plumbing only; see
- * `e2ee-crypto`/`e2ee-device`/`e2ee-object`/`e2ee-state` for the browser-only
- * crypto and state helpers that produce the ciphertext these methods store),
- * `plugins` (dependency discovery and cross-plugin references, RFC 0051),
- * `billing` (plugin monetization / entitlement gating, RFC 0003), `events`.
- * `data`, `activity`, `portability`, `env`, `notifications`, `directory`,
- * `secrets`, `storage`, `connections`, `e2ee`, and `plugins` are implemented;
- * `billing` and `events` throw `NotImplementedError` until their backing
- * mechanisms ship. Their shape may change before they stabilise.
- */
-export const sdk = {
-  // Stable (v1.0.0).
-  auth,
-  db,
-  mailer,
-  platform,
-  // Experimental / reserved — shape may change; some throw until implemented.
-  data,
-  storage,
-  directory,
-  notifications,
-  secrets,
-  connections,
-  e2ee,
-  events,
-  activity,
-  portability,
-  plugins,
-  env,
-  billing,
-};
-
-export { provideHost } from './host';
-export type { SdkHost } from './host';
-/**
- * Client-side CMK/DEK crypto and state helpers (RFC 0060) — browser-only
- * (WebCrypto/IndexedDB). Deliberately NOT re-exported here: this barrel also
- * reaches server-only modules (e.g. `activity.ts`'s `next/headers` import),
- * and Next.js's client/server boundary check flags the whole module graph
- * reachable from an import — not just the specific named export used — so a
- * `'use client'` component importing anything from `@sovereignfs/sdk`
- * directly would fail to build. Import from the dedicated subpaths instead:
- *
- * ```ts
- * import { generateCmk, wrapCmkWithRecoverySecret } from '@sovereignfs/sdk/e2ee-crypto';
- * import { getOrCreateDeviceId, storeDeviceKey } from '@sovereignfs/sdk/e2ee-device';
- * import { encryptBlob, encryptJson } from '@sovereignfs/sdk/e2ee-object';
- * import { getE2eeLocalState } from '@sovereignfs/sdk/e2ee-state';
- * ```
- *
- * Types are erased at compile time (no runtime module graph), so they stay
- * exported from the main barrel below for convenience.
- */
-export type { RecoveryWrappedCmk, WrappedCmk, WrappedDek } from './e2ee-crypto';
-export type { EncryptedBlob, EncryptedJson } from './e2ee-object';
-export type { E2eeLocalState } from './e2ee-state';
-export {
-  NotImplementedError,
-  NotAuthenticatedError,
-  ConsentRequiredError,
-  EntitlementRequiredError,
-} from './errors';
-export type { DataContractRef, DataContractResolver } from './data';
-export type {
-  ExportContext,
-  ExportOptions,
-  ImportContext,
-  PluginExportSection,
-  ExportSecretMetadata,
-  ExportResolver,
-  ImportHandler,
-  DeletionContext,
-  DeletionResult,
-  DeletionHandler,
-} from './portability';
-export type {
-  PluginAvailability,
-  PluginContractSummary,
-  PluginListFilter,
-  ConsentStatus,
-  PluginReference,
-} from './plugins';
-export type {
-  Session,
-  SessionUser,
-  ActiveSession,
-  ChangePasswordInput,
-  DirectoryUser,
-  MailOptions,
-  PlatformConfig,
-  ProviderConfig,
-  ProviderConfigSource,
-  ResolveUsersInput,
-  SearchUsersInput,
-  ActivityLogEntry,
-  DrizzleClient,
-  SendNotificationInput,
-  ConnectionContext,
-  ConnectionListFilter,
-  ConnectionOAuthState,
-  ConnectionRef,
-  ConnectionScope,
-  ConnectionStatus,
-  CreateConnectionInput,
-  MarkConnectionErrorInput,
-  OAuthStateInput,
-  SanitizedConnectionError,
-  CreateSecretInput,
-  ScheduleContext,
-  ScheduleHandler,
-  SecretContext,
-  SecretRef,
-  SecretScope,
-  StorageContext,
-  StorageObject,
-  StoragePutInput,
-  E2eeProfile,
-  E2eeProfileStatus,
-  E2eeRecoveryWrapper,
-  E2eeDeviceEnrollment,
-  E2eeState,
-  E2eeContext,
-  CreateE2eeProfileInput,
-  SetE2eeRecoveryWrapperInput,
-  EnrollE2eeDeviceInput,
-  UpdateSecretInput,
-  UpdateConnectionInput,
-} from './types';

package/src/mailer.ts

@@ -1,7 +0,0 @@
-import { requireHost } from './host';
-import type { MailOptions } from './types';
-
-/** Sends an email via the platform mailer. No-ops when SMTP is not configured. */
-export async function send(options: MailOptions): Promise<void> {
-  await requireHost().mailer.send(options);
-}

package/src/notifications.ts

@@ -1,36 +0,0 @@
-import { requireHost } from './host';
-import type { SendNotificationInput } from './types';
-
-function getPluginId(headers: Headers): string | null {
-  return headers.get('x-sovereign-plugin-id');
-}
-
-/**
- * Notification Center SDK surface (RFC 0015).
- *
- * Requires the `notifications:send` manifest permission.
- * The runtime injects source identity from the request context.
- */
-export const notifications = {
-  /**
-   * Send a notification to a user.
-   *
-   * The `source` and `sourceType` fields are set by the runtime from the
-   * calling plugin's ID (injected via `x-sovereign-plugin-id` header) — plugins
-   * cannot forge sender identity.
-   *
-   * @example
-   * ```ts
-   * await sdk.notifications.send({
-   *   recipientUserId: userId,
-   *   title: 'Your export is ready',
-   *   url: '/myPlugin/exports',
-   *   category: 'info',
-   * });
-   * ```
-   */
-  async send(input: SendNotificationInput, requestHeaders?: Headers): Promise<void> {
-    const pluginId = requestHeaders ? (getPluginId(requestHeaders) ?? 'unknown') : 'unknown';
-    return requireHost().notifications.send(input, pluginId);
-  },
-};

package/src/platform.ts

@@ -1,10 +0,0 @@
-import { requireHost } from './host';
-import type { PlatformConfig } from './types';
-
-/**
- * Returns the platform runtime configuration (SRS PLT-06). Async by contract:
- * the platform DB is dialect-agnostic and Postgres has no synchronous query.
- */
-export async function getConfig(): Promise<PlatformConfig> {
-  return requireHost().platform.getConfig();
-}

package/src/plugins.ts

@@ -1,146 +0,0 @@
-import { headers } from 'next/headers';
-import type { DataContractRef } from './data';
-import { requireHost } from './host';
-
-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 [];
-  }
-}
-
-/** A data contract a plugin declares in its manifest `data.provides`. */
-export interface PluginContractSummary {
-  contract: string;
-  version: number;
-}
-
-/**
- * Discovery status of an installed plugin, scoped to the requesting user
- * (RFC 0051). Never exposes private provider data — only install/enable
- * status, launch availability, and declared (not consented) contracts.
- */
-export interface PluginAvailability {
-  id: string;
-  name: string;
-  routePrefix: string;
-  icon?: string;
-  /** Always `true` — `get()`/`list()` only ever return installed plugins. */
-  installed: true;
-  /** Whether the plugin is enabled instance-wide (Console toggle / example default). */
-  enabled: boolean;
-  /**
-   * Whether the *current* user could launch this plugin right now: enabled,
-   * not blocked by an `adminOnly` gate the user lacks `console:access` for,
-   * and not paywalled by an unmet entitlement (RFC 0003). `false` when called
-   * without an authenticated user in context.
-   */
-  availableToUser: boolean;
-  /** Data contracts this plugin exposes (`data.provides`), if any. */
-  providesContracts: PluginContractSummary[];
-}
-
-export interface PluginListFilter {
-  /** Only return plugins that declare this contract name in `data.provides`. */
-  providesContract?: string;
-}
-
-/**
- * Whether the current user has an active consent grant for a (consumer,
- * provider, contract, version) tuple. `'not_granted'` covers both "never
- * granted" and "revoked" — the platform does not distinguish the two once a
- * grant is inactive; a consumer that needs to tell them apart should compare
- * against its own last-known cached state.
- */
-export type ConsentStatus = 'granted' | 'not_granted';
-
-/**
- * A standard, opaque reference to another plugin's record (RFC 0051). Store
- * this shape (or split it into columns) in your own tables to point at a
- * sibling plugin's data without a direct foreign key or copying private data.
- * `resourceId` is opaque to the consumer — the provider decides its shape.
- *
- * References are never authorization: every dereference still goes through
- * `sdk.data.query()` (or a tool contract) and the current user's live
- * consent. Treat a stored reference as a nullable link — the provider may be
- * uninstalled, disabled, have revoked consent, or have deleted the resource.
- */
-export interface PluginReference {
-  /** The provider plugin's manifest `id`. */
-  providerId: string;
-  /** Provider-local resource kind (e.g. `"contact"`, `"invoice"`). */
-  resourceType: string;
-  /** Opaque to the consumer — a UUID, slug, or compound key the provider defines. */
-  resourceId: string;
-  /** The data contract this reference was resolved through, if any. */
-  contract?: string;
-  /** Contract major version at the time this reference was captured. */
-  version?: number;
-  /** A cached, possibly-stale display label — show it when the provider is unavailable. */
-  labelSnapshot?: string;
-  /** Consumer-defined extra metadata. */
-  metadata?: unknown;
-  /** ISO-8601 timestamp of when this reference was created. */
-  linkedAt: string;
-}
-
-async function requestContext(): Promise<{
-  userId: string | null;
-  capabilities: readonly string[];
-}> {
-  const h = await headers();
-  return {
-    userId: h.get('x-sovereign-user-id'),
-    capabilities: parseCapabilities(h.get('x-sovereign-user-capabilities')),
-  };
-}
-
-/**
- * Plugin dependency discovery and cross-plugin references (RFC 0051).
- *
- * Lets a plugin check whether an optional sibling plugin is installed,
- * enabled, and available to the current user before offering an integration,
- * and defines the standard `PluginReference` shape for storing opaque links
- * to another plugin's records. Complements `sdk.data` (RFC 0002, which reads
- * the data) and RFC 0047 plugin tools (which act on it).
- *
- * ```ts
- * const crm = await sdk.plugins.get('io.openfs.sovereign.crm');
- * if (crm?.availableToUser) {
- *   // offer a "Link to contact" action
- * }
- *
- * const status = await sdk.plugins.getConsentStatus({
- *   providerId: 'io.openfs.sovereign.crm',
- *   contract: 'crm.contacts',
- *   version: 1,
- * });
- * ```
- */
-export const plugins = {
-  /** Discover one installed plugin's status. `null` when not installed. */
-  async get(id: string): Promise<PluginAvailability | null> {
-    const { userId, capabilities } = await requestContext();
-    return requireHost().plugins.get(id, userId, capabilities);
-  },
-
-  /** Discover installed plugins, optionally filtered to those providing a contract. */
-  async list(filter?: PluginListFilter): Promise<PluginAvailability[]> {
-    const { userId, capabilities } = await requestContext();
-    return requireHost().plugins.list(filter, userId, capabilities);
-  },
-
-  /** Whether the current user has granted this plugin's requested data contract. */
-  async getConsentStatus(ref: DataContractRef): Promise<ConsentStatus> {
-    const h = await headers();
-    const consumerId = h.get('x-sovereign-plugin-id');
-    const userId = h.get('x-sovereign-user-id');
-    if (!consumerId || !userId) return 'not_granted';
-    return requireHost().plugins.getConsentStatus(ref, consumerId, userId);
-  },
-};

package/src/portability.ts

@@ -1,176 +0,0 @@
-import { headers } from 'next/headers';
-import { requireHost } from './host';
-import type { PluginReference } from './plugins';
-
-/** Supplied by the runtime to an export resolver — scoped to the current user. */
-export interface ExportContext {
-  userId: string;
-  tenantId: string;
-  /** User-selected export scope (RFC 0052). */
-  options: ExportOptions;
-}
-
-/** User-selectable export scope, gathered by the Account Data tab. */
-export interface ExportOptions {
-  /** Whether to include plugin-contributed file blobs. Defaults to `true`. */
-  includeFiles: boolean;
-}
-
-/** Supplied by the runtime to an import handler — scoped to the importing user. */
-export interface ImportContext {
-  userId: string;
-  tenantId: string;
-  /**
-   * Maps an id from the source bundle to the id minted on this instance.
-   * Stable within one import: the same `originalId` always yields the same new
-   * id, so a plugin can preserve internal references (FKs) without breakage.
-   */
-  remapId(originalId: string): string;
-}
-
-/** Metadata about one of the plugin's own secrets, without its plaintext value. */
-export interface ExportSecretMetadata {
-  /** The secret's user-facing label (e.g. "Personal API key"). */
-  label: string;
-  /** The secret's provider/purpose (e.g. "openai", "smtp"). */
-  provider: string;
-  /** Whether a value is currently stored — never the value itself. */
-  exists: boolean;
-}
-
-/** One plugin's slice of a user's export. */
-export interface PluginExportSection {
-  /** The contributing plugin's manifest `id`. */
-  pluginId: string;
-  /**
-   * The installed manifest `version` of the contributing plugin, for provenance.
-   * A resolver may omit this — the runtime always overwrites it with the
-   * installed manifest's actual `version` before writing the bundle, so a
-   * plugin cannot misreport its own version.
-   */
-  pluginVersion?: string;
-  /** The plugin's own data-format version (for forward/backward compatibility). */
-  schemaVersion: number;
-  /** Plugin-defined JSON payload (rows, references). */
-  data: unknown;
-  /** Optional binary attachments, keyed by relative path within the section. */
-  blobs?: Record<string, Uint8Array>;
-  /**
-   * Metadata for secrets this plugin owns, scoped to the current user.
-   * Plaintext secret values must never appear here or anywhere in the export.
-   */
-  secretMetadata?: ExportSecretMetadata[];
-  /** Non-fatal notices about this section (e.g. a file that was skipped). */
-  warnings?: string[];
-  /**
-   * Opaque links this plugin holds to other plugins' records (RFC 0051).
-   * Exported and imported as **inert metadata only** — the platform never
-   * dereferences them, whether or not the referenced provider plugin is also
-   * part of the same export. Importing a reference never grants access to
-   * the provider plugin; a live dereference still goes through
-   * `sdk.data.query()` and the current user's consent.
-   */
-  references?: PluginReference[];
-}
-
-/** Produces one plugin's export section for the current user. */
-export type ExportResolver = (ctx: ExportContext) => Promise<PluginExportSection>;
-
-/** Restores one plugin's export section into the importing user's account. */
-export type ImportHandler = (section: PluginExportSection, ctx: ImportContext) => Promise<void>;
-
-/** Supplied to a deletion handler — scoped to the user being deleted. */
-export interface DeletionContext {
-  userId: string;
-  tenantId: string;
-  /** The plugin's own Drizzle client (same as `sdk.db.getClient()`). */
-  db: unknown;
-}
-
-/** What a deletion handler must return. */
-export interface DeletionResult {
-  /** Number of rows (or objects) deleted. */
-  deleted: number;
-  /** Non-fatal errors encountered during cleanup. */
-  errors?: string[];
-}
-
-/** Cleans up one plugin's user data when a user account is deleted. */
-export type DeletionHandler = (ctx: DeletionContext) => Promise<DeletionResult>;
-
-/**
- * User data portability (RFC 0007, RFC 0052) — self-service export / restore /
- * migration.
- *
- * A plugin opts in by registering an **export resolver** and an **import
- * handler** (declare `data:export` / `data:import` in the manifest `permissions`).
- * Both are runtime-mediated: the runtime supplies `ctx.userId` / `ctx.tenantId`,
- * so a plugin only ever reads or writes the **current user's own slice** — never
- * another user's, another plugin's, or another tenant's data.
- *
- * ```ts
- * // register from your plugin's server code (a route handler or server
- * // component that runs when the plugin is loaded):
- * await sdk.portability.provideExport(async (ctx) => ({
- *   pluginId: 'com.example.tasks',
- *   schemaVersion: 1,
- *   data: await collectMyRowsFor(ctx.userId),
- *   // only when ctx.options.includeFiles is true — large attachments should
- *   // respect the user's export scope choice:
- *   blobs: ctx.options.includeFiles ? await collectMyBlobsFor(ctx.userId) : undefined,
- *   secretMetadata: await listMySecretMetadataFor(ctx.userId), // never plaintext
- * }));
- *
- * await sdk.portability.provideImport(async (section, ctx) => {
- *   await restoreMyRowsFor(section.data, ctx); // use ctx.remapId for references
- * });
- * ```
- *
- * The platform exports/imports its own data (profile, preferences, avatar)
- * directly; plugins contribute the rest. The user drives it from the
- * Account → Data tab, including whether to include files/attachments
- * (`ctx.options.includeFiles`). A resolver that throws is excluded from the
- * bundle and recorded in the manifest's `failures` list — one plugin's failure
- * never aborts the whole export.
- *
- * Registration reads the calling plugin's id from the request context, so these
- * must run inside a plugin route (where `x-sovereign-plugin-id` is injected) —
- * hence they are async. Registrations are in-process and reset on restart.
- */
-export const portability = {
-  /** Provider: register this plugin's export resolver. */
-  async provideExport(resolver: ExportResolver): Promise<void> {
-    const pluginId = (await headers()).get('x-sovereign-plugin-id');
-    if (!pluginId) {
-      throw new Error(
-        'sdk.portability.provideExport() must be called from a plugin route context ' +
-          '(x-sovereign-plugin-id header missing).',
-      );
-    }
-    requireHost().portability.provideExport(pluginId, resolver);
-  },
-
-  /** Provider: register this plugin's import handler. */
-  async provideImport(handler: ImportHandler): Promise<void> {
-    const pluginId = (await headers()).get('x-sovereign-plugin-id');
-    if (!pluginId) {
-      throw new Error(
-        'sdk.portability.provideImport() must be called from a plugin route context ' +
-          '(x-sovereign-plugin-id header missing).',
-      );
-    }
-    requireHost().portability.provideImport(pluginId, handler);
-  },
-
-  /** Provider: register this plugin's deletion handler (RFC 0033). */
-  async provideDelete(handler: DeletionHandler): Promise<void> {
-    const pluginId = (await headers()).get('x-sovereign-plugin-id');
-    if (!pluginId) {
-      throw new Error(
-        'sdk.portability.provideDelete() must be called from a plugin route context ' +
-          '(x-sovereign-plugin-id header missing).',
-      );
-    }
-    requireHost().portability.provideDelete(pluginId, handler);
-  },
-};

package/src/secrets.ts

@@ -1,68 +0,0 @@
-import { headers } from 'next/headers';
-import { NotAuthenticatedError } from './errors';
-import { requireHost } from './host';
-import type { CreateSecretInput, SecretContext, SecretRef, SecretScope } 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 secretContext(): Promise<SecretContext> {
-  const h = await headers();
-  const pluginId = h.get('x-sovereign-plugin-id');
-  if (!pluginId) {
-    throw new Error(
-      'sdk.secrets 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: SecretScope, userId: string | null): void {
-  if (scope === 'user' && !userId) throw new NotAuthenticatedError();
-}
-
-/** Experimental platform-managed plugin secret vault (RFC 0043). */
-export const secrets = {
-  async create(input: CreateSecretInput): Promise<SecretRef> {
-    const context = await secretContext();
-    requireUserForUserScope(input.scope, context.userId);
-    return requireHost().secrets.create(input, context);
-  },
-
-  async get(id: string): Promise<string | null> {
-    const context = await secretContext();
-    return requireHost().secrets.get(id, context);
-  },
-
-  async list(scope?: SecretScope): Promise<SecretRef[]> {
-    const context = await secretContext();
-    if (scope) requireUserForUserScope(scope, context.userId);
-    return requireHost().secrets.list(scope, context);
-  },
-
-  async update(id: string, value: string): Promise<SecretRef> {
-    const context = await secretContext();
-    return requireHost().secrets.update(id, value, context);
-  },
-
-  async delete(id: string): Promise<void> {
-    const context = await secretContext();
-    return requireHost().secrets.delete(id, context);
-  },
-};

package/src/sessions.ts

@@ -1,36 +0,0 @@
-import type { ActiveSession } from './types';
-
-/** The session fields better-auth's list-sessions returns that we surface. */
-export interface RawSession {
-  token: string;
-  userAgent?: string | null;
-  ipAddress?: string | null;
-  createdAt: string;
-  updatedAt: string;
-  expiresAt: string;
-}
-
-/**
- * Project better-auth sessions into the SDK's `ActiveSession` shape, flag the
- * one matching the current request's token, and order it first, then the rest
- * newest-first (SRS ACC-05). Pure — the network fetch lives in `auth.ts`.
- */
-export function markCurrentSessions(
-  sessions: readonly RawSession[],
-  currentToken: string | null,
-): ActiveSession[] {
-  return sessions
-    .map((s) => ({
-      token: s.token,
-      current: s.token === currentToken,
-      userAgent: s.userAgent ?? null,
-      ipAddress: s.ipAddress ?? null,
-      createdAt: s.createdAt,
-      updatedAt: s.updatedAt,
-      expiresAt: s.expiresAt,
-    }))
-    .sort((a, b) => {
-      if (a.current !== b.current) return a.current ? -1 : 1;
-      return a.createdAt < b.createdAt ? 1 : -1;
-    });
-}