@sovereignfs/sdk 1.25.0

package/dist/e2ee-state-U-GEJ7oL.d.ts

@@ -0,0 +1,411 @@
+interface SessionUser {
+    id: string;
+    tenantId: string;
+    email: string;
+    name: string | null;
+    image: string | null;
+    role: string;
+    /** Effective capability strings derived from the role preset (RFC 0021). */
+    capabilities: readonly string[];
+}
+interface Session {
+    user: SessionUser;
+    /** Session expiry as a Unix timestamp (seconds). */
+    expiresAt: number;
+}
+/** An authenticated session for the current user (SRS ACC-05). */
+interface ActiveSession {
+    /** Opaque session token — pass to `sdk.auth.revokeSession` to end it. */
+    token: string;
+    /** Whether this is the session making the current request. */
+    current: boolean;
+    /** Raw User-Agent string of the device that created the session, if known. */
+    userAgent: string | null;
+    ipAddress: string | null;
+    /** Creation, last-active, and expiry as ISO 8601 strings. */
+    createdAt: string;
+    updatedAt: string;
+    expiresAt: string;
+}
+interface ChangePasswordInput {
+    currentPassword: string;
+    newPassword: string;
+}
+/** Display-safe user shape returned by `sdk.directory` (RFC 0041). */
+interface DirectoryUser {
+    id: string;
+    email: string;
+    name: string | null;
+    image: string | null;
+}
+interface SearchUsersInput {
+    query: string;
+    limit?: number;
+}
+interface ResolveUsersInput {
+    ids: string[];
+}
+interface MailOptions {
+    to: string | string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    from?: string;
+}
+interface PlatformConfig {
+    /**
+     * Name of the default tenant row — set in Console › Settings › Instance name.
+     * In v1 (single-tenant) this is the platform-wide workspace name.
+     * Multi-tenant deployments (post-v1) will surface per-tenant names separately.
+     */
+    tenantName: string;
+    inviteOnly: boolean;
+    version: string;
+    /** Instance name; falls back to tenantName when no white-label name is configured. */
+    instanceName: string;
+    /** Validated 6-digit hex colour overriding --sv-color-accent, or undefined when unset. */
+    instancePrimaryColor?: string;
+    /**
+     * Stable UUID that uniquely identifies this Sovereign installation.
+     * Generated once at bootstrap and never changes. Use this to identify the
+     * instance in federated contexts, license checks, or analytics.
+     */
+    instanceId: string;
+}
+/**
+ * An activity event a plugin records via `sdk.activity.log()` (RFC 0005 —
+ * reserved surface, not yet implemented). The plugin supplies only the event
+ * shape; the runtime injects the actor, tenant, and emitting plugin and forces
+ * the event to be user-scoped, so a plugin cannot forge actor identity.
+ */
+interface ActivityLogEntry {
+    /** Dotted action verb, e.g. `"list.created"`. Namespaced by the runtime per plugin. */
+    action: string;
+    /** The user this event is about, if any — drives the user's personal-feed visibility. */
+    subjectUserId?: string;
+    /** Generic target kind, e.g. `"list"`. */
+    targetType?: string;
+    /** Generic target id, e.g. the list id. */
+    targetId?: string;
+    /** Human-readable one-line summary. */
+    summary?: string;
+    /** Structured detail (before/after, etc.). Avoid PII beyond what is necessary. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * The Drizzle client returned by `sdk.db.getClient()` — the live platform
+ * Drizzle instance. Kept opaque (`unknown`) at the contract level so the
+ * published SDK takes no dependency on a specific dialect's Drizzle types;
+ * plugins type their own queries through their schema.
+ */
+type DrizzleClient = unknown;
+/**
+ * Input to `sdk.notifications.send()` (RFC 0015).
+ * The runtime auto-populates `source`, `sourceType`, and `tenantId` from
+ * request context — plugins never set those.
+ */
+interface SendNotificationInput {
+    /** User ID of the intended recipient. */
+    recipientUserId: string;
+    /** Short notification headline. */
+    title: string;
+    /** Optional longer body text. */
+    body?: string;
+    /** In-app route to navigate to when the notification is clicked. */
+    url?: string;
+    /**
+     * Category tag — drives mute preferences.
+     * Built-in categories: `'info'` (default), `'announcement'`, `'security'`.
+     * Custom plugin categories are allowed; `'security'` cannot be muted.
+     */
+    category?: string;
+    /**
+     * Optional URL to an image shown in the OS push notification (the Push
+     * API's `icon` option — not an `@sovereignfs/ui` `<Icon>` name; nothing
+     * in-app reads this field today). Defaults to the sending plugin's own
+     * `/plugin-icons/<pluginId>.svg` when unset — only set this to override
+     * with a notification-specific image instead of the plugin's own icon.
+     */
+    icon?: string;
+}
+/** Plugin-scoped file storage object metadata (RFC 0044). */
+interface StorageObject {
+    id: string;
+    pluginId: string;
+    ownerUserId: string | null;
+    key: string;
+    contentType: string;
+    size: number;
+    checksum: string;
+    /** The `metadata` passed to `put()`, round-tripped back on `get()`/`list()`. */
+    metadata: Record<string, unknown> | null;
+    createdAt: number;
+    updatedAt: number;
+}
+interface StoragePutInput {
+    key: string;
+    body: Blob | ArrayBuffer | Uint8Array;
+    contentType: string;
+    /** Owner of the object. Omit for a plugin-scoped (not per-user) object. */
+    ownerUserId?: string;
+    metadata?: Record<string, unknown> | null;
+}
+interface StorageContext {
+    tenantId: string;
+    pluginId: string;
+    userId: string | null;
+}
+/**
+ * Client-side encryption profile shapes (RFC 0060, epic task 8.9). Persisted
+ * via `sdk.e2ee`; the browser-only crypto that produces/consumes the
+ * ciphertext these methods store lives in `e2ee-crypto`/`e2ee-device`/
+ * `e2ee-object`/`e2ee-state`. Distinct from server-side field crypto
+ * (`sdk.crypto.encryptField()`, RFC 0008): the runtime can decrypt a
+ * server-side field; it can never decrypt a client-side encrypted object.
+ *
+ * The Client Master Key (CMK) itself never exists server-side, plaintext or
+ * otherwise — only wrapped copies (`E2eeRecoveryWrapper`/
+ * `E2eeDeviceEnrollment`) and non-sensitive KDF/algorithm metadata do.
+ */
+type E2eeProfileStatus = 'active' | 'disabled';
+/** Whether the current user has set up client-side encryption at all. */
+interface E2eeProfile {
+    id: string;
+    userId: string;
+    status: E2eeProfileStatus;
+    /** e.g. `'AES-GCM-256'` — the algorithm used to encrypt objects under the CMK. */
+    cmkAlgorithm: string;
+    createdAt: number;
+    updatedAt: number;
+}
+/** The CMK wrapped by a key derived from the user's recovery secret. One per user. */
+interface E2eeRecoveryWrapper {
+    id: string;
+    userId: string;
+    wrappedCmk: string;
+    kdfAlgorithm: string;
+    /** Opaque JSON-encoded KDF parameters (iterations, memory cost, etc.). */
+    kdfParams: string;
+    kdfSalt: string;
+    algorithmVersion: string;
+    createdAt: number;
+    updatedAt: number;
+}
+/** The CMK wrapped by one enrolled device's own key. Many per user. */
+interface E2eeDeviceEnrollment {
+    id: string;
+    userId: string;
+    deviceId: string;
+    deviceLabel: string | null;
+    wrappedCmk: string;
+    algorithmVersion: string;
+    createdAt: number;
+    lastUsedAt: number | null;
+    /** `null` while the device is still enrolled. */
+    revokedAt: number | null;
+}
+/**
+ * Normalized state a plugin checks before touching client-side encrypted
+ * data — the SDK never hides the recovery model (RFC 0060 "SDK
+ * responsibilities"). `unsupported` means the browser lacks required
+ * WebCrypto primitives.
+ */
+type E2eeState = 'not-set-up' | 'locked' | 'unlocked' | 'unsupported';
+/** No plugin scoping — one profile per user, regardless of caller. */
+interface E2eeContext {
+    tenantId: string;
+    userId: string;
+}
+interface CreateE2eeProfileInput {
+    cmkAlgorithm: string;
+}
+interface SetE2eeRecoveryWrapperInput {
+    wrappedCmk: string;
+    kdfAlgorithm: string;
+    kdfParams: string;
+    kdfSalt: string;
+    algorithmVersion: string;
+}
+interface EnrollE2eeDeviceInput {
+    deviceId: string;
+    deviceLabel: string | null;
+    wrappedCmk: string;
+    algorithmVersion: string;
+}
+/** Runtime-created secret scope for the experimental plugin vault (RFC 0043). */
+type SecretScope = 'user' | 'plugin' | 'instance';
+/** Metadata returned for a stored secret. Plaintext values are never included. */
+interface SecretRef {
+    id: string;
+    scope: SecretScope;
+    label: string;
+    metadata: Record<string, unknown> | null;
+    createdAt: number;
+    updatedAt: number;
+    lastUsedAt: number | null;
+}
+interface CreateSecretInput {
+    scope: SecretScope;
+    label: string;
+    value: string;
+    metadata?: Record<string, unknown> | null;
+}
+interface UpdateSecretInput {
+    id: string;
+    value: string;
+}
+interface SecretContext {
+    tenantId: string;
+    pluginId: string;
+    userId: string | null;
+    capabilities: readonly string[];
+}
+/** Runtime-created external provider connection scope (RFC 0049). */
+type ConnectionScope = 'user' | 'plugin' | 'instance';
+/** Metadata status for a plugin-owned external provider connection. */
+type ConnectionStatus = 'connected' | 'needs_reauth' | 'paused' | 'disconnected' | 'error';
+/** Metadata returned for an external connection. Secret values are never included. */
+interface ConnectionRef {
+    id: string;
+    scope: ConnectionScope;
+    provider: string;
+    label: string;
+    status: ConnectionStatus;
+    secretRef: string | null;
+    metadata: Record<string, unknown> | null;
+    lastCheckedAt: number | null;
+    lastUsedAt: number | null;
+    lastError: SanitizedConnectionError | null;
+    createdAt: number;
+    updatedAt: number;
+    disconnectedAt: number | null;
+}
+interface CreateConnectionInput {
+    scope: ConnectionScope;
+    provider: string;
+    label: string;
+    secretRef?: string | null;
+    metadata?: Record<string, unknown> | null;
+}
+interface ConnectionListFilter {
+    provider?: string;
+    scope?: ConnectionScope;
+    includeDisconnected?: boolean;
+}
+interface UpdateConnectionInput {
+    label?: string;
+    status?: ConnectionStatus;
+    metadata?: Record<string, unknown> | null;
+    secretRef?: string | null;
+    lastCheckedAt?: number | null;
+}
+interface SanitizedConnectionError {
+    code?: string;
+    message: string;
+    retryable?: boolean;
+    status?: number;
+}
+interface MarkConnectionErrorInput {
+    error: SanitizedConnectionError;
+    status?: Extract<ConnectionStatus, 'error' | 'needs_reauth'>;
+}
+interface OAuthStateInput {
+    provider: string;
+    callbackPath: string;
+    nonce?: string;
+    metadata?: Record<string, unknown> | null;
+    expiresInSeconds?: number;
+}
+interface ConnectionOAuthState {
+    pluginId: string;
+    provider: string;
+    userId: string;
+    callbackPath: string;
+    nonce: string;
+    metadata: Record<string, unknown> | null;
+    expiresAt: number;
+}
+/** Source summary for effective external provider configuration (Task 3.27). */
+type ProviderConfigSource = 'env' | 'console' | 'mixed' | 'missing';
+/** Server-side effective external provider config for the calling plugin. */
+interface ProviderConfig {
+    provider: string;
+    label: string;
+    configured: boolean;
+    source: ProviderConfigSource;
+    publicValues: Record<string, string>;
+    secretValues: Record<string, string>;
+    callbackUrl: string | null;
+    scopes: readonly string[];
+    missingRequired: readonly string[];
+}
+interface ConnectionContext {
+    tenantId: string;
+    pluginId: string;
+    userId: string | null;
+    capabilities: readonly string[];
+}
+/**
+ * Context passed to a plugin's schedule handler (RFC 0046, Phase 1 subset).
+ * There is no originating HTTP request — the platform's in-process scheduler
+ * invokes handlers directly — so the runtime supplies synthetic `headers`
+ * pre-stamped with the calling plugin's identity. Pass them to SDK methods
+ * that attribute by request headers (e.g.
+ * `sdk.notifications.send(input, ctx.headers)`).
+ */
+interface ScheduleContext {
+    /** The invoking plugin's manifest id (e.g. `fs.sovereign.tasks`). */
+    pluginId: string;
+    /** The schedule's manifest-declared id (e.g. `due-reminders`). */
+    scheduleId: string;
+    /** Synthetic headers carrying `x-sovereign-plugin-id` for SDK attribution. */
+    headers: Headers;
+}
+/**
+ * A plugin's schedule handler — the **default export** of a manifest-declared
+ * `schedules[].entry` module. Invoked server-side every `intervalMinutes`
+ * while the plugin is installed and enabled.
+ *
+ * Handlers must be idempotent: the interval is a floor, not an exact cadence,
+ * and restarts or multiple replicas can invoke a handler again sooner than
+ * the interval — claim work with conditional updates before acting on it.
+ * Thrown errors are caught and logged by the platform; there are no retries
+ * in Phase 1.
+ */
+type ScheduleHandler = (ctx: ScheduleContext) => Promise<void>;
+
+/**
+ * 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.
+ */
+
+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. */
+declare function browserSupportsE2ee(): boolean;
+/**
+ * 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.
+ */
+declare function classifyE2eeLocalState(profile: E2eeProfile | null, devices: E2eeDeviceEnrollment[], deviceId: string, deviceKey: CryptoKey | null): E2eeLocalState;
+/**
+ * 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.
+ */
+declare function getE2eeLocalState(profile: E2eeProfile | null, devices: E2eeDeviceEnrollment[]): Promise<E2eeLocalState>;
+
+export { type ActiveSession as A, type E2eeLocalState as B, type ChangePasswordInput as C, type DrizzleClient as D, type E2eeContext as E, type E2eeProfileStatus as F, type E2eeState as G, type ProviderConfigSource as H, type SanitizedConnectionError as I, type ScheduleContext as J, type ScheduleHandler as K, type SessionUser as L, type MailOptions as M, type UpdateSecretInput as N, type OAuthStateInput as O, type PlatformConfig as P, browserSupportsE2ee as Q, type ResolveUsersInput as R, type Session as S, classifyE2eeLocalState as T, type UpdateConnectionInput as U, getE2eeLocalState as V, type SearchUsersInput as a, type DirectoryUser as b, type ActivityLogEntry as c, type SendNotificationInput as d, type StoragePutInput as e, type StorageContext as f, type StorageObject as g, type E2eeProfile as h, type CreateE2eeProfileInput as i, type E2eeRecoveryWrapper as j, type SetE2eeRecoveryWrapperInput as k, type EnrollE2eeDeviceInput as l, type E2eeDeviceEnrollment as m, type CreateSecretInput as n, type SecretContext as o, type SecretRef as p, type SecretScope as q, type CreateConnectionInput as r, type ConnectionContext as s, type ConnectionRef as t, type ConnectionListFilter as u, type MarkConnectionErrorInput as v, type ConnectionOAuthState as w, type ProviderConfig as x, type ConnectionScope as y, type ConnectionStatus as z };

package/dist/e2ee-state.d.ts

@@ -0,0 +1 @@
+export { B as E2eeLocalState, Q as browserSupportsE2ee, T as classifyE2eeLocalState, V as getE2eeLocalState } from './e2ee-state-U-GEJ7oL.js';

package/dist/e2ee-state.js

@@ -0,0 +1,36 @@
+import {
+  getDeviceKey,
+  getOrCreateDeviceId
+} from "./chunk-NQLGPAL6.js";
+import "./chunk-MLKGABMK.js";
+
+// src/e2ee-state.ts
+function browserSupportsE2ee() {
+  return typeof indexedDB !== "undefined" && typeof crypto !== "undefined" && typeof crypto.subtle !== "undefined";
+}
+function classifyE2eeLocalState(profile, devices, deviceId, deviceKey) {
+  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 };
+}
+async function getE2eeLocalState(profile, devices) {
+  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);
+}
+export {
+  browserSupportsE2ee,
+  classifyE2eeLocalState,
+  getE2eeLocalState
+};