@sovereignfs/sdk 1.25.0

package/dist/index.js

@@ -0,0 +1,652 @@
+import {
+  __export
+} from "./chunk-MLKGABMK.js";
+
+// src/auth.ts
+var auth_exports = {};
+__export(auth_exports, {
+  changePassword: () => changePassword,
+  getSession: () => getSession,
+  hasCapability: () => hasCapability,
+  listSessions: () => listSessions,
+  requireSession: () => requireSession,
+  revokeSession: () => revokeSession,
+  signOut: () => signOut
+});
+import { headers } from "next/headers";
+
+// src/errors.ts
+var NotImplementedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NotImplementedError";
+  }
+};
+var NotAuthenticatedError = class extends Error {
+  constructor() {
+    super("No authenticated session. The caller must be within an authenticated request.");
+    this.name = "NotAuthenticatedError";
+  }
+};
+var ConsentRequiredError = class extends Error {
+  constructor(message = "User consent is required to access this plugin data.") {
+    super(message);
+    this.name = "ConsentRequiredError";
+  }
+};
+var EntitlementRequiredError = class extends Error {
+  constructor(message = "An active entitlement is required to access this feature.") {
+    super(message);
+    this.name = "EntitlementRequiredError";
+  }
+};
+
+// src/sessions.ts
+function markCurrentSessions(sessions, currentToken) {
+  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;
+  });
+}
+
+// src/auth.ts
+var DEFAULT_TENANT_ID = "default";
+var AUTH_URL = process.env.SOVEREIGN_AUTH_URL ?? `http://localhost:${process.env.AUTH_PORT ?? "3001"}`;
+async function getSession() {
+  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 = capsRaw ? JSON.parse(capsRaw) : [];
+  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)
+  };
+}
+function hasCapability(session, capability) {
+  return session?.user.capabilities.includes(capability) ?? false;
+}
+async function requireSession() {
+  const session = await getSession();
+  if (!session) throw new NotAuthenticatedError();
+  return session;
+}
+async function authFetch(path, method, body) {
+  const cookie = (await headers()).get("cookie") ?? "";
+  return fetch(`${AUTH_URL}${path}`, {
+    method,
+    headers: {
+      cookie,
+      origin: AUTH_URL,
+      ...body === void 0 ? {} : { "Content-Type": "application/json" }
+    },
+    body: body === void 0 ? void 0 : JSON.stringify(body)
+  });
+}
+async function authError(res, action) {
+  const body = await res.text().catch(() => "");
+  const detail = body ? ` \u2014 ${body}` : "";
+  return new Error(`${action} (${String(res.status)})${detail}`);
+}
+async function changePassword(input) {
+  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))?.message;
+    throw new Error(message ?? `Failed to change password (${String(res.status)}).`);
+  }
+}
+async function listSessions() {
+  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();
+  const currentToken = sessionRes.ok ? (await sessionRes.json())?.session?.token ?? null : null;
+  return markCurrentSessions(raw, currentToken);
+}
+async function revokeSession(token) {
+  const res = await authFetch("/api/auth/revoke-session", "POST", { token });
+  if (!res.ok) {
+    throw await authError(res, "Failed to revoke session");
+  }
+}
+async function signOut() {
+  const res = await authFetch("/api/auth/sign-out", "POST", {});
+  if (!res.ok) {
+    throw await authError(res, "Failed to sign out");
+  }
+}
+
+// src/activity.ts
+import { headers as headers2 } from "next/headers";
+
+// src/host.ts
+var HOST_KEY = /* @__PURE__ */ Symbol.for("@sovereignfs/sdk:host");
+function holder() {
+  return globalThis;
+}
+function provideHost(host) {
+  holder()[HOST_KEY] = host;
+}
+function requireHost() {
+  const host = holder()[HOST_KEY];
+  if (!host) {
+    throw new Error(
+      "@sovereignfs/sdk: no runtime host is registered. SDK methods run inside the Sovereign runtime \u2014 start the platform with `pnpm dev` or `pnpm sv dev` and ensure the plugin is installed."
+    );
+  }
+  return host;
+}
+
+// src/activity.ts
+var activity = {
+  async log(entry) {
+    const h = await headers2();
+    const actorId = h.get("x-sovereign-user-id");
+    const pluginId = h.get("x-sovereign-plugin-id");
+    await requireHost().activity.log(entry, actorId, pluginId);
+  }
+};
+
+// src/connections.ts
+import { headers as headers3 } from "next/headers";
+var DEFAULT_TENANT_ID2 = "default";
+function parseCapabilities(raw) {
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((cap) => typeof cap === "string") : [];
+  } catch {
+    return [];
+  }
+}
+async function connectionContext() {
+  const h = await headers3();
+  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_ID2,
+    pluginId,
+    userId: h.get("x-sovereign-user-id"),
+    capabilities: parseCapabilities(h.get("x-sovereign-user-capabilities"))
+  };
+}
+function requireUserForUserScope(scope, userId) {
+  if ((scope === void 0 || scope === "user") && !userId) throw new NotAuthenticatedError();
+}
+var connections = {
+  async create(input) {
+    const context = await connectionContext();
+    requireUserForUserScope(input.scope, context.userId);
+    return requireHost().connections.create(input, context);
+  },
+  async list(filter) {
+    const context = await connectionContext();
+    requireUserForUserScope(filter?.scope, context.userId);
+    return requireHost().connections.list(filter, context);
+  },
+  async get(id) {
+    const context = await connectionContext();
+    return requireHost().connections.get(id, context);
+  },
+  async update(id, input) {
+    const context = await connectionContext();
+    return requireHost().connections.update(id, input, context);
+  },
+  async disconnect(id) {
+    const context = await connectionContext();
+    return requireHost().connections.disconnect(id, context);
+  },
+  async markUsed(id) {
+    const context = await connectionContext();
+    return requireHost().connections.markUsed(id, context);
+  },
+  async markError(id, input) {
+    const context = await connectionContext();
+    return requireHost().connections.markError(id, input, context);
+  },
+  async createOAuthState(input) {
+    const context = await connectionContext();
+    requireUserForUserScope("user", context.userId);
+    return requireHost().connections.createOAuthState(input, context);
+  },
+  async verifyOAuthState(state) {
+    const context = await connectionContext();
+    requireUserForUserScope("user", context.userId);
+    return requireHost().connections.verifyOAuthState(state, context);
+  },
+  async getProviderConfig(provider) {
+    const context = await connectionContext();
+    return requireHost().connections.getProviderConfig(provider, context);
+  }
+};
+
+// src/data.ts
+import { headers as headers4 } from "next/headers";
+var DEFAULT_TENANT_ID3 = "default";
+var 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(contract, resolver) {
+    requireHost().data.provide(contract, resolver);
+  },
+  /** Consumer: read a provider plugin's contract for the current user (consent-gated). */
+  async query(ref, params) {
+    const h = await headers4();
+    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_ID3,
+      params
+    );
+    return result;
+  }
+};
+
+// src/directory.ts
+import { headers as headers5 } from "next/headers";
+var DEFAULT_TENANT_ID4 = "default";
+var directory = {
+  /**
+   * Search active users in the current tenant by display name or email.
+   * Results include only display-safe profile fields.
+   */
+  async searchUsers(input) {
+    const h = await headers5();
+    const userId = h.get("x-sovereign-user-id");
+    if (!userId) throw new NotAuthenticatedError();
+    return requireHost().directory.searchUsers(input, userId, DEFAULT_TENANT_ID4);
+  },
+  /**
+   * Resolve explicit user IDs already stored by a plugin into display-safe
+   * profile rows for active users.
+   */
+  async resolveUsers(input) {
+    const h = await headers5();
+    const userId = h.get("x-sovereign-user-id");
+    if (!userId) throw new NotAuthenticatedError();
+    return requireHost().directory.resolveUsers(input, userId, DEFAULT_TENANT_ID4);
+  }
+};
+
+// src/db.ts
+var db_exports = {};
+__export(db_exports, {
+  getClient: () => getClient
+});
+import { headers as headers6 } from "next/headers";
+async function getClient() {
+  let pluginId = null;
+  try {
+    const h = await headers6();
+    pluginId = h.get("x-sovereign-plugin-id");
+  } catch {
+  }
+  return requireHost().db.getClient(pluginId);
+}
+
+// src/e2ee.ts
+import { headers as headers7 } from "next/headers";
+var DEFAULT_TENANT_ID5 = "default";
+async function e2eeContext() {
+  const h = await headers7();
+  const userId = h.get("x-sovereign-user-id");
+  if (!userId) throw new NotAuthenticatedError();
+  return { tenantId: DEFAULT_TENANT_ID5, userId };
+}
+var e2ee = {
+  async getProfile() {
+    const context = await e2eeContext();
+    return requireHost().e2ee.getProfile(context);
+  },
+  async createProfile(input) {
+    const context = await e2eeContext();
+    return requireHost().e2ee.createProfile(input, context);
+  },
+  async getRecoveryWrapper() {
+    const context = await e2eeContext();
+    return requireHost().e2ee.getRecoveryWrapper(context);
+  },
+  async setRecoveryWrapper(input) {
+    const context = await e2eeContext();
+    return requireHost().e2ee.setRecoveryWrapper(input, context);
+  },
+  async enrollDevice(input) {
+    const context = await e2eeContext();
+    return requireHost().e2ee.enrollDevice(input, context);
+  },
+  async listDevices() {
+    const context = await e2eeContext();
+    return requireHost().e2ee.listDevices(context);
+  },
+  async revokeDevice(id) {
+    const context = await e2eeContext();
+    return requireHost().e2ee.revokeDevice(id, context);
+  }
+};
+
+// src/env.ts
+import { headers as headers8 } from "next/headers";
+var env = {
+  async get(key) {
+    const h = await headers8();
+    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;
+  }
+};
+
+// src/mailer.ts
+var mailer_exports = {};
+__export(mailer_exports, {
+  send: () => send
+});
+async function send(options) {
+  await requireHost().mailer.send(options);
+}
+
+// src/notifications.ts
+function getPluginId(headers13) {
+  return headers13.get("x-sovereign-plugin-id");
+}
+var 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, requestHeaders) {
+    const pluginId = requestHeaders ? getPluginId(requestHeaders) ?? "unknown" : "unknown";
+    return requireHost().notifications.send(input, pluginId);
+  }
+};
+
+// src/platform.ts
+var platform_exports = {};
+__export(platform_exports, {
+  getConfig: () => getConfig
+});
+async function getConfig() {
+  return requireHost().platform.getConfig();
+}
+
+// src/plugins.ts
+import { headers as headers9 } from "next/headers";
+function parseCapabilities2(raw) {
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((cap) => typeof cap === "string") : [];
+  } catch {
+    return [];
+  }
+}
+async function requestContext() {
+  const h = await headers9();
+  return {
+    userId: h.get("x-sovereign-user-id"),
+    capabilities: parseCapabilities2(h.get("x-sovereign-user-capabilities"))
+  };
+}
+var plugins = {
+  /** Discover one installed plugin's status. `null` when not installed. */
+  async get(id) {
+    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) {
+    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) {
+    const h = await headers9();
+    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);
+  }
+};
+
+// src/portability.ts
+import { headers as headers10 } from "next/headers";
+var portability = {
+  /** Provider: register this plugin's export resolver. */
+  async provideExport(resolver) {
+    const pluginId = (await headers10()).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) {
+    const pluginId = (await headers10()).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) {
+    const pluginId = (await headers10()).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);
+  }
+};
+
+// src/secrets.ts
+import { headers as headers11 } from "next/headers";
+var DEFAULT_TENANT_ID6 = "default";
+function parseCapabilities3(raw) {
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((cap) => typeof cap === "string") : [];
+  } catch {
+    return [];
+  }
+}
+async function secretContext() {
+  const h = await headers11();
+  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_ID6,
+    pluginId,
+    userId: h.get("x-sovereign-user-id"),
+    capabilities: parseCapabilities3(h.get("x-sovereign-user-capabilities"))
+  };
+}
+function requireUserForUserScope2(scope, userId) {
+  if (scope === "user" && !userId) throw new NotAuthenticatedError();
+}
+var secrets = {
+  async create(input) {
+    const context = await secretContext();
+    requireUserForUserScope2(input.scope, context.userId);
+    return requireHost().secrets.create(input, context);
+  },
+  async get(id) {
+    const context = await secretContext();
+    return requireHost().secrets.get(id, context);
+  },
+  async list(scope) {
+    const context = await secretContext();
+    if (scope) requireUserForUserScope2(scope, context.userId);
+    return requireHost().secrets.list(scope, context);
+  },
+  async update(id, value) {
+    const context = await secretContext();
+    return requireHost().secrets.update(id, value, context);
+  },
+  async delete(id) {
+    const context = await secretContext();
+    return requireHost().secrets.delete(id, context);
+  }
+};
+
+// src/storage.ts
+import { headers as headers12 } from "next/headers";
+var DEFAULT_TENANT_ID7 = "default";
+async function storageContext() {
+  const h = await headers12();
+  const pluginId = h.get("x-sovereign-plugin-id");
+  if (!pluginId) {
+    throw new Error(
+      "sdk.storage requires a plugin route context (x-sovereign-plugin-id header missing)."
+    );
+  }
+  return {
+    tenantId: DEFAULT_TENANT_ID7,
+    pluginId,
+    userId: h.get("x-sovereign-user-id")
+  };
+}
+var storage = {
+  async put(input) {
+    const context = await storageContext();
+    return requireHost().storage.put(input, context);
+  },
+  async get(key) {
+    const context = await storageContext();
+    return requireHost().storage.get(key, context);
+  },
+  async delete(key) {
+    const context = await storageContext();
+    return requireHost().storage.delete(key, context);
+  },
+  async list(prefix) {
+    const context = await storageContext();
+    return requireHost().storage.list(prefix, context);
+  },
+  /** Create a short-lived, read-only download URL for an object (default 5 minutes, max 1 hour). */
+  async getSignedUrl(key, options) {
+    const context = await storageContext();
+    return requireHost().storage.getSignedUrl(key, options, context);
+  }
+};
+
+// src/unimplemented.ts
+var events = {
+  publish(_event, _payload) {
+    throw new NotImplementedError("sdk.events.publish() is not implemented in Sovereign v1.");
+  },
+  subscribe(_event, _handler) {
+    throw new NotImplementedError("sdk.events.subscribe() is not implemented in Sovereign v1.");
+  }
+};
+var billing = {
+  /**
+   * Returns the current user's active entitlement for the calling plugin, or
+   * `null` when no entitlement exists. Use this to branch UI by tier.
+   */
+  getEntitlement(_headers) {
+    throw new NotImplementedError("sdk.billing.getEntitlement() is not yet implemented.");
+  },
+  /**
+   * Asserts that the current user has an active entitlement for the calling
+   * plugin. Throws `EntitlementRequiredError` when absent. Use for in-plugin
+   * feature gating (route-level access is already gated by the middleware).
+   */
+  requireEntitlement(_headers) {
+    throw new EntitlementRequiredError(
+      "sdk.billing.requireEntitlement() is not yet implemented \u2014 no entitlement check performed."
+    );
+  }
+};
+
+// src/index.ts
+var sdk = {
+  // Stable (v1.0.0).
+  auth: auth_exports,
+  db: db_exports,
+  mailer: mailer_exports,
+  platform: platform_exports,
+  // Experimental / reserved — shape may change; some throw until implemented.
+  data,
+  storage,
+  directory,
+  notifications,
+  secrets,
+  connections,
+  e2ee,
+  events,
+  activity,
+  portability,
+  plugins,
+  env,
+  billing
+};
+export {
+  ConsentRequiredError,
+  EntitlementRequiredError,
+  NotAuthenticatedError,
+  NotImplementedError,
+  provideHost,
+  sdk
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@sovereignfs/sdk",
+  "version": "1.25.0",
+  "type": "module",
+  "description": "Sovereign SDK — the plugin↔platform contract (types and interfaces).",
+  "license": "AGPL-3.0-or-later",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./e2ee-crypto": {
+      "types": "./dist/e2ee-crypto.d.ts",
+      "default": "./dist/e2ee-crypto.js"
+    },
+    "./e2ee-device": {
+      "types": "./dist/e2ee-device.d.ts",
+      "default": "./dist/e2ee-device.js"
+    },
+    "./e2ee-object": {
+      "types": "./dist/e2ee-object.d.ts",
+      "default": "./dist/e2ee-object.js"
+    },
+    "./e2ee-state": {
+      "types": "./dist/e2ee-state.d.ts",
+      "default": "./dist/e2ee-state.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "peerDependencies": {
+    "next": ">=15.0.0"
+  },
+  "devDependencies": {
+    "next": "^15.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "@sovereignfs/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  },
+  "types": "./dist/index.d.ts"
+}