@sovereignfs/sdk 1.25.0

package/src/__tests__/sdk.test.ts

@@ -0,0 +1,427 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+import { provideHost } from '../host';
+import { ConsentRequiredError, NotAuthenticatedError, NotImplementedError, sdk } from '../index';
+
+// A minimal mock host — lets us test SDK delegation without a real runtime.
+const mockDbClient = { select: () => ({}), insert: () => ({}) };
+const mockConfig = {
+  tenantName: 'Test Workspace',
+  inviteOnly: false,
+  version: '0.6.0',
+  instanceName: 'Test Workspace',
+  instanceId: 'test-instance-uuid',
+};
+const mockDataResolvers = new Map<string, (...args: unknown[]) => Promise<unknown[]>>();
+const mockExporters = new Map<string, unknown>();
+const mockImporters = new Map<string, unknown>();
+
+beforeAll(() => {
+  provideHost({
+    db: {
+      async getClient() {
+        return mockDbClient;
+      },
+    },
+    mailer: {
+      async send() {
+        /* no-op */
+      },
+    },
+    platform: {
+      async getConfig() {
+        return mockConfig;
+      },
+    },
+    directory: {
+      async searchUsers() {
+        return [];
+      },
+      async resolveUsers() {
+        return [];
+      },
+    },
+    data: {
+      provide(contract, resolver) {
+        mockDataResolvers.set(contract, resolver as (...args: unknown[]) => Promise<unknown[]>);
+      },
+      async query(_ref, _consumerId, _userId, _tenantId, _params) {
+        return [];
+      },
+    },
+    activity: {
+      async log(_entry, _actorId, _pluginId) {
+        /* no-op */
+      },
+    },
+    portability: {
+      provideExport(pluginId, resolver) {
+        mockExporters.set(pluginId, resolver);
+      },
+      provideImport(pluginId, handler) {
+        mockImporters.set(pluginId, handler);
+      },
+      provideDelete(_pluginId, _handler) {
+        /* no-op */
+      },
+    },
+    plugins: {
+      async get(id) {
+        if (id !== 'com.example.notes') return null;
+        return {
+          id,
+          name: 'Notes',
+          routePrefix: '/notes',
+          installed: true,
+          enabled: true,
+          availableToUser: true,
+          providesContracts: [],
+        };
+      },
+      async list() {
+        return [];
+      },
+      async getConsentStatus() {
+        return 'not_granted';
+      },
+    },
+    notifications: {
+      async send(_input, _pluginId) {
+        /* no-op */
+      },
+    },
+    secrets: {
+      async create(input) {
+        return {
+          id: 'secret-1',
+          scope: input.scope,
+          label: input.label,
+          metadata: input.metadata ?? null,
+          createdAt: 1,
+          updatedAt: 1,
+          lastUsedAt: null,
+        };
+      },
+      async get(_id) {
+        return 'secret';
+      },
+      async list() {
+        return [];
+      },
+      async update(_id, _value) {
+        return {
+          id: 'secret-1',
+          scope: 'user',
+          label: 'Updated',
+          metadata: null,
+          createdAt: 1,
+          updatedAt: 2,
+          lastUsedAt: null,
+        };
+      },
+      async delete(_id) {
+        /* no-op */
+      },
+    },
+    connections: {
+      async create(input) {
+        return {
+          id: 'conn-1',
+          scope: input.scope,
+          provider: input.provider,
+          label: input.label,
+          status: 'connected',
+          secretRef: input.secretRef ?? null,
+          metadata: input.metadata ?? null,
+          lastCheckedAt: null,
+          lastUsedAt: null,
+          lastError: null,
+          createdAt: 1,
+          updatedAt: 1,
+          disconnectedAt: null,
+        };
+      },
+      async list() {
+        return [];
+      },
+      async get() {
+        return null;
+      },
+      async update(_id, input) {
+        return {
+          id: 'conn-1',
+          scope: 'user',
+          provider: 'email.google',
+          label: input.label ?? 'Google Mail',
+          status: input.status ?? 'connected',
+          secretRef: input.secretRef ?? null,
+          metadata: input.metadata ?? null,
+          lastCheckedAt: input.lastCheckedAt ?? null,
+          lastUsedAt: null,
+          lastError: null,
+          createdAt: 1,
+          updatedAt: 2,
+          disconnectedAt: null,
+        };
+      },
+      async disconnect() {
+        /* no-op */
+      },
+      async markUsed() {
+        /* no-op */
+      },
+      async markError(_id, input) {
+        return {
+          id: 'conn-1',
+          scope: 'user',
+          provider: 'email.google',
+          label: 'Google Mail',
+          status: input.status ?? 'error',
+          secretRef: null,
+          metadata: null,
+          lastCheckedAt: null,
+          lastUsedAt: null,
+          lastError: input.error,
+          createdAt: 1,
+          updatedAt: 2,
+          disconnectedAt: null,
+        };
+      },
+      async createOAuthState() {
+        return 'state';
+      },
+      async verifyOAuthState() {
+        return {
+          pluginId: 'com.example.notes',
+          provider: 'email.google',
+          userId: 'u1',
+          callbackPath: '/connections/google/callback',
+          nonce: 'nonce',
+          metadata: null,
+          expiresAt: 2,
+        };
+      },
+      async getProviderConfig(provider) {
+        return {
+          provider,
+          label: 'Google Mail',
+          configured: true,
+          source: 'console',
+          publicValues: { clientId: 'client-id' },
+          secretValues: { clientSecret: 'client-secret' },
+          callbackUrl: 'https://example.test/notes/connections/google/callback',
+          scopes: ['user'],
+          missingRequired: [],
+        };
+      },
+    },
+    storage: {
+      async put(input) {
+        return {
+          id: 'obj-1',
+          pluginId: 'com.example.notes',
+          ownerUserId: input.ownerUserId ?? null,
+          key: input.key,
+          contentType: input.contentType,
+          size: 3,
+          checksum: 'checksum',
+          metadata: input.metadata ?? null,
+          createdAt: 1,
+          updatedAt: 1,
+        };
+      },
+      async get(_key) {
+        return null;
+      },
+      async delete(_key) {
+        /* no-op */
+      },
+      async list() {
+        return [];
+      },
+      async getSignedUrl(_key) {
+        return 'https://example.test/api/storage/signed-token';
+      },
+    },
+    e2ee: {
+      async getProfile() {
+        return null;
+      },
+      async createProfile(input, context) {
+        return {
+          id: 'profile-1',
+          userId: context.userId,
+          status: 'active',
+          cmkAlgorithm: input.cmkAlgorithm,
+          createdAt: 1,
+          updatedAt: 1,
+        };
+      },
+      async getRecoveryWrapper() {
+        return null;
+      },
+      async setRecoveryWrapper(input, context) {
+        return { id: 'wrapper-1', userId: context.userId, ...input, createdAt: 1, updatedAt: 1 };
+      },
+      async enrollDevice(input, context) {
+        return {
+          id: 'device-1',
+          userId: context.userId,
+          ...input,
+          createdAt: 1,
+          lastUsedAt: null,
+          revokedAt: null,
+        };
+      },
+      async listDevices() {
+        return [];
+      },
+      async revokeDevice(_id) {
+        /* no-op */
+      },
+    },
+  });
+});
+
+describe('sdk surface', () => {
+  it('exposes the full v1 stable surface', () => {
+    expect(typeof sdk.auth.getSession).toBe('function');
+    expect(typeof sdk.auth.requireSession).toBe('function');
+    expect(typeof sdk.auth.changePassword).toBe('function');
+    expect(typeof sdk.auth.listSessions).toBe('function');
+    expect(typeof sdk.auth.revokeSession).toBe('function');
+    expect(typeof sdk.auth.signOut).toBe('function');
+    expect(typeof sdk.db.getClient).toBe('function');
+    expect(typeof sdk.mailer.send).toBe('function');
+    expect(typeof sdk.platform.getConfig).toBe('function');
+  });
+
+  it('exposes the directory surface (RFC 0041)', () => {
+    expect(typeof sdk.directory.searchUsers).toBe('function');
+    expect(typeof sdk.directory.resolveUsers).toBe('function');
+  });
+
+  it('exposes the stable data surface (RFC 0002)', () => {
+    expect(typeof sdk.data.query).toBe('function');
+    expect(typeof sdk.data.provide).toBe('function');
+  });
+
+  it('exposes the activity surface (RFC 0005)', () => {
+    expect(typeof sdk.activity.log).toBe('function');
+  });
+
+  it('exposes the portability surface (RFC 0007)', () => {
+    expect(typeof sdk.portability.provideExport).toBe('function');
+    expect(typeof sdk.portability.provideImport).toBe('function');
+  });
+
+  it('exposes the plugins discovery surface (RFC 0051)', () => {
+    expect(typeof sdk.plugins.get).toBe('function');
+    expect(typeof sdk.plugins.list).toBe('function');
+    expect(typeof sdk.plugins.getConsentStatus).toBe('function');
+  });
+
+  it('exposes the env surface (RFC 0018)', () => {
+    expect(typeof sdk.env.get).toBe('function');
+  });
+
+  it('exposes the experimental / reserved surface', () => {
+    expect(typeof sdk.storage.put).toBe('function');
+    expect(typeof sdk.storage.get).toBe('function');
+    expect(typeof sdk.storage.delete).toBe('function');
+    expect(typeof sdk.storage.list).toBe('function');
+    expect(typeof sdk.storage.getSignedUrl).toBe('function');
+    expect(typeof sdk.notifications.send).toBe('function');
+    expect(typeof sdk.secrets.create).toBe('function');
+    expect(typeof sdk.secrets.get).toBe('function');
+    expect(typeof sdk.secrets.list).toBe('function');
+    expect(typeof sdk.secrets.update).toBe('function');
+    expect(typeof sdk.secrets.delete).toBe('function');
+    expect(typeof sdk.connections.create).toBe('function');
+    expect(typeof sdk.connections.list).toBe('function');
+    expect(typeof sdk.connections.get).toBe('function');
+    expect(typeof sdk.connections.update).toBe('function');
+    expect(typeof sdk.connections.disconnect).toBe('function');
+    expect(typeof sdk.connections.markUsed).toBe('function');
+    expect(typeof sdk.connections.markError).toBe('function');
+    expect(typeof sdk.connections.createOAuthState).toBe('function');
+    expect(typeof sdk.connections.verifyOAuthState).toBe('function');
+    expect(typeof sdk.connections.getProviderConfig).toBe('function');
+    expect(typeof sdk.events.publish).toBe('function');
+    expect(typeof sdk.events.subscribe).toBe('function');
+    expect(typeof sdk.e2ee.getProfile).toBe('function');
+    expect(typeof sdk.e2ee.createProfile).toBe('function');
+    expect(typeof sdk.e2ee.getRecoveryWrapper).toBe('function');
+    expect(typeof sdk.e2ee.setRecoveryWrapper).toBe('function');
+    expect(typeof sdk.e2ee.enrollDevice).toBe('function');
+    expect(typeof sdk.e2ee.listDevices).toBe('function');
+    expect(typeof sdk.e2ee.revokeDevice).toBe('function');
+  });
+});
+
+describe('sdk.db', () => {
+  it('getClient delegates to the registered host', async () => {
+    const client = await sdk.db.getClient();
+    expect(client).toBe(mockDbClient);
+  });
+});
+
+describe('sdk.platform', () => {
+  it('getConfig delegates to the registered host', async () => {
+    const config = await sdk.platform.getConfig();
+    expect(config.tenantName).toBe('Test Workspace');
+    expect(config.inviteOnly).toBe(false);
+    expect(config.version).toBe('0.6.0');
+    expect(config.instanceId).toBe('test-instance-uuid');
+  });
+});
+
+describe('sdk — host guard', () => {
+  it('requireHost throws when no host is registered', async () => {
+    // Import requireHost directly to test the guard without a registered host.
+    // We have a host registered in beforeAll, so we test the error message shape
+    // by verifying our mock is returned (if it were null it would throw).
+    const client = await sdk.db.getClient();
+    expect(client).toBeDefined();
+  });
+});
+
+describe('sdk — experimental surfaces throw NotImplementedError', () => {
+  it('notifications.send delegates to the registered host (RFC 0015)', async () => {
+    // No longer throws NotImplementedError — now delegates to the host.
+    await expect(
+      sdk.notifications.send({ recipientUserId: 'u1', title: 'Test' }),
+    ).resolves.toBeUndefined();
+  });
+
+  it('events.publish / events.subscribe', () => {
+    expect(() => sdk.events.publish('e', {})).toThrow(NotImplementedError);
+    expect(() => sdk.events.subscribe('e', () => undefined)).toThrow(NotImplementedError);
+  });
+
+  it('data.provide delegates to the registered host (RFC 0002)', () => {
+    const resolver = async () => [{ id: 1 }];
+    sdk.data.provide('test-contract', resolver);
+    expect(mockDataResolvers.get('test-contract')).toBe(resolver);
+  });
+
+  it('activity.log is implemented (RFC 0005)', () => {
+    // activity.log delegates to the host via next/headers (requires request context);
+    // we verify the method exists and is a function — runtime mediation is tested
+    // indirectly via the host mock wired in beforeAll.
+    expect(typeof sdk.activity.log).toBe('function');
+  });
+});
+
+describe('sdk — error classes', () => {
+  it('NotAuthenticatedError', () => {
+    const err = new NotAuthenticatedError();
+    expect(err.name).toBe('NotAuthenticatedError');
+    expect(err).toBeInstanceOf(Error);
+  });
+
+  it('ConsentRequiredError', () => {
+    const err = new ConsentRequiredError();
+    expect(err.name).toBe('ConsentRequiredError');
+    expect(err).toBeInstanceOf(Error);
+  });
+});

package/src/__tests__/sessions.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import { markCurrentSessions, type RawSession } from '../sessions';
+
+function raw(token: string, createdAt: string, extra: Partial<RawSession> = {}): RawSession {
+  return {
+    token,
+    createdAt,
+    updatedAt: createdAt,
+    expiresAt: '2026-12-31T00:00:00.000Z',
+    ...extra,
+  };
+}
+
+describe('markCurrentSessions', () => {
+  it('flags the session whose token matches the current one', () => {
+    const out = markCurrentSessions(
+      [raw('a', '2026-06-01T00:00:00.000Z'), raw('b', '2026-06-02T00:00:00.000Z')],
+      'b',
+    );
+    expect(out.find((s) => s.token === 'b')?.current).toBe(true);
+    expect(out.find((s) => s.token === 'a')?.current).toBe(false);
+  });
+
+  it('orders the current session first', () => {
+    const out = markCurrentSessions(
+      [raw('old', '2026-06-01T00:00:00.000Z'), raw('cur', '2026-05-01T00:00:00.000Z')],
+      'cur',
+    );
+    expect(out[0]?.token).toBe('cur');
+  });
+
+  it('orders the rest newest-first', () => {
+    const out = markCurrentSessions(
+      [
+        raw('older', '2026-06-01T00:00:00.000Z'),
+        raw('newer', '2026-06-03T00:00:00.000Z'),
+        raw('cur', '2026-01-01T00:00:00.000Z'),
+      ],
+      'cur',
+    );
+    expect(out.map((s) => s.token)).toEqual(['cur', 'newer', 'older']);
+  });
+
+  it('marks none current when the token is null', () => {
+    const out = markCurrentSessions([raw('a', '2026-06-01T00:00:00.000Z')], null);
+    expect(out.every((s) => !s.current)).toBe(true);
+  });
+
+  it('normalises missing userAgent/ipAddress to null', () => {
+    const out = markCurrentSessions([raw('a', '2026-06-01T00:00:00.000Z')], 'a');
+    expect(out[0]?.userAgent).toBeNull();
+    expect(out[0]?.ipAddress).toBeNull();
+  });
+
+  it('passes through userAgent/ipAddress when present', () => {
+    const out = markCurrentSessions(
+      [raw('a', '2026-06-01T00:00:00.000Z', { userAgent: 'Firefox', ipAddress: '10.0.0.1' })],
+      'a',
+    );
+    expect(out[0]?.userAgent).toBe('Firefox');
+    expect(out[0]?.ipAddress).toBe('10.0.0.1');
+  });
+});

package/src/activity.ts

@@ -0,0 +1,19 @@
+import { headers } from 'next/headers';
+import { requireHost } from './host';
+import type { ActivityLogEntry } from './types';
+
+/**
+ * Activity log (RFC 0005). Records a scoped audit event on behalf of the
+ * current user; the runtime host injects the actor identity and plugin context
+ * so plugins cannot forge them. Plugin-sourced events are always user-scoped.
+ *
+ * Requires the `activity:write` permission in the plugin manifest.
+ */
+export const activity = {
+  async log(entry: ActivityLogEntry): Promise<void> {
+    const h = await headers();
+    const actorId = h.get('x-sovereign-user-id');
+    const pluginId = h.get('x-sovereign-plugin-id');
+    await requireHost().activity.log(entry, actorId, pluginId);
+  },
+};

package/src/auth.ts

@@ -0,0 +1,134 @@
+import { headers } from 'next/headers';
+import { NotAuthenticatedError } from './errors';
+
+// v1 is single-tenant; every session belongs to this tenant id.
+const DEFAULT_TENANT_ID = 'default';
+import { markCurrentSessions, type RawSession } from './sessions';
+import type { ActiveSession, ChangePasswordInput, Session } from './types';
+
+const AUTH_URL =
+  process.env.SOVEREIGN_AUTH_URL ?? `http://localhost:${process.env.AUTH_PORT ?? '3001'}`;
+
+/** Returns the current user session from runtime-injected headers, or null if unauthenticated. */
+export async function getSession(): Promise<Session | null> {
+  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: readonly string[] = capsRaw ? (JSON.parse(capsRaw) as string[]) : [];
+  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),
+  };
+}
+
+/**
+ * Return true if the given session has the named capability (RFC 0021).
+ * Plugins should call this instead of comparing `session.user.role` directly
+ * to avoid coupling to the role-preset details.
+ */
+export function hasCapability(session: Session | null, capability: string): boolean {
+  return session?.user.capabilities.includes(capability) ?? false;
+}
+
+/** Returns the current user session, throwing `NotAuthenticatedError` if unauthenticated. */
+export async function requireSession(): Promise<Session> {
+  const session = await getSession();
+  if (!session) throw new NotAuthenticatedError();
+  return session;
+}
+
+/**
+ * Call a better-auth endpoint server-side, forwarding the caller's session
+ * cookie. better-auth enforces a CSRF Origin check on state-changing routes,
+ * so we send its own base URL as the trusted Origin.
+ */
+async function authFetch(path: string, method: 'GET' | 'POST', body?: unknown): Promise<Response> {
+  const cookie = (await headers()).get('cookie') ?? '';
+  // No explicit `cache` option: under Next 15 fetch is uncached by default, so
+  // these credentialed calls are never cached — and the SDK stays free of
+  // Next-specific RequestInit fields so it type-checks standalone.
+  return fetch(`${AUTH_URL}${path}`, {
+    method,
+    headers: {
+      cookie,
+      origin: AUTH_URL,
+      ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+}
+
+/** Build an error message including better-auth's response body, for diagnosis. */
+async function authError(res: Response, action: string): Promise<Error> {
+  const body = await res.text().catch(() => '');
+  const detail = body ? ` — ${body}` : '';
+  return new Error(`${action} (${String(res.status)})${detail}`);
+}
+
+/**
+ * Change the current user's password (SRS ACC-04). Requires the current
+ * password; the current session is preserved (other sessions are kept too).
+ * Throws with better-auth's message on failure (e.g. wrong current password).
+ */
+export async function changePassword(input: ChangePasswordInput): Promise<void> {
+  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)) as { message?: string } | null)?.message;
+    throw new Error(message ?? `Failed to change password (${String(res.status)}).`);
+  }
+}
+
+/** List the current user's active sessions, current one first (SRS ACC-05). */
+export async function listSessions(): Promise<ActiveSession[]> {
+  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()) as RawSession[];
+  const currentToken = sessionRes.ok
+    ? (((await sessionRes.json()) as { session?: { token?: string } } | null)?.session?.token ??
+      null)
+    : null;
+  return markCurrentSessions(raw, currentToken);
+}
+
+/** Revoke a session by its token (SRS ACC-06). */
+export async function revokeSession(token: string): Promise<void> {
+  const res = await authFetch('/api/auth/revoke-session', 'POST', { token });
+  if (!res.ok) {
+    throw await authError(res, 'Failed to revoke session');
+  }
+}
+
+/**
+ * Sign the current user out (SRS AUTH-02): ends the active session on the auth
+ * server. The caller is responsible for clearing the runtime's `session_data`
+ * cache cookies and redirecting — the platform's logout route does both.
+ */
+export async function signOut(): Promise<void> {
+  // Pass an empty body so `authFetch` sends `Content-Type: application/json` —
+  // better-auth's sign-out rejects requests without it (415).
+  const res = await authFetch('/api/auth/sign-out', 'POST', {});
+  if (!res.ok) {
+    throw await authError(res, 'Failed to sign out');
+  }
+}