@maravilla-labs/platform 0.3.5 → 0.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/platform",
-  "version": "0.3.5",
+  "version": "0.3.8",
   "description": "Universal platform client for Maravilla runtime",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -173,4 +173,10 @@ export function clearPlatformCache(): void {
   if (typeof globalThis !== 'undefined') {
     globalThis.__maravilla_platform = undefined;
   }
-}
+}
+
+export {
+  runWithRequest,
+  getCurrentRequestStore,
+  type RequestStore,
+} from './request-scope.js';

package/src/media.ts

@@ -50,9 +50,10 @@ export class RemoteMediaService implements MediaService {
   ) {}
 
   private async fetch(url: string, options: RequestInit = {}) {
+    const { getRequestAuthHeader } = await import('./request-scope.js');
     const response = await fetch(url, {
       ...options,
-      headers: { ...this.headers, ...options.headers },
+      headers: { ...this.headers, ...getRequestAuthHeader(), ...options.headers },
     });
 
     if (!response.ok) {

package/src/remote-client.ts

@@ -1,5 +1,6 @@
 import type { KvNamespace, KvListResult, Database, DbFindOptions, Storage, RealtimeService, PresenceService, AuthService, AuthCaller, AuthUser, AuthSession, AuthField, RegisterOptions, LoginOptions, UserListFilter, UserListResponse, UpdateUserOptions, PolicyService, VectorIndexSpec, VectorIndexDescriptor, VectorQueryWithFilter, VectorSearchHit, IndexSpec, IndexDescriptor, Workflows, WorkflowHandle, WorkflowRun, WorkflowStepRecord } from './types.js';
 import { RemoteMediaService } from './media.js';
+import { getRequestAuthHeader } from './request-scope.js';
 
 /**
  * Remote KV namespace implementation that communicates with a development server.
@@ -23,7 +24,7 @@ class RemoteKvNamespace implements KvNamespace {
   private async fetch(url: string, options: RequestInit = {}) {
     const response = await fetch(url, {
       ...options,
-      headers: { ...this.headers, ...options.headers },
+      headers: { ...this.headers, ...getRequestAuthHeader(), ...options.headers },
     });
 
     if (!response.ok && response.status !== 404) {
@@ -94,7 +95,7 @@ class RemoteDatabase implements Database {
   private async fetch(url: string, options: RequestInit = {}) {
     const response = await fetch(url, {
       ...options,
-      headers: { ...this.headers, ...options.headers },
+      headers: { ...this.headers, ...getRequestAuthHeader(), ...options.headers },
     });
 
     if (!response.ok && response.status !== 404) {
@@ -228,7 +229,7 @@ class RemoteStorage implements Storage {
   private async fetch(url: string, options: RequestInit = {}) {
     const response = await fetch(url, {
       ...options,
-      headers: { ...this.headers, ...options.headers },
+      headers: { ...this.headers, ...getRequestAuthHeader(), ...options.headers },
     });
 
     if (!response.ok && response.status !== 404) {
@@ -245,16 +246,24 @@ class RemoteStorage implements Storage {
     headers: Record<string, string>;
     expiresIn: number;
   }> {
-    // For development, return a direct upload URL to the dev server
-    // The dev server supports PUT directly to /api/storage/{key}
+    // Pre-flight Layer-2 gate: dev-server runs the bucket policy with
+    // `action: "upload-url"` and returns the upload URL on success
+    // (or 403 on denial). Mirrors prod's
+    // platform.storage.generateUploadUrl behaviour.
+    const res = await this.fetch(`${this.baseUrl}/api/storage/upload-url`, {
+      method: 'POST',
+      body: JSON.stringify({ key, content_type: contentType, size_limit: options?.sizeLimit }),
+    });
+    const data = (await res.json()) as { url: string; method: string; headers: Record<string, string>; expiresIn: number };
+    // The dev-server returns a relative URL; absolutise it. Prepend
+    // tenant headers so direct PUTs by the caller still carry the
+    // X-Tenant-Id (Authorization will be re-added at fetch time by
+    // getRequestAuthHeader if a request scope is bound).
     return {
-      url: `${this.baseUrl}/api/storage/${encodeURIComponent(key)}`,
-      method: 'PUT',
-      headers: {
-        'Content-Type': contentType,
-        ...this.headers, // Include tenant headers
-      },
-      expiresIn: 3600, // 1 hour
+      url: data.url.startsWith('http') ? data.url : `${this.baseUrl}${data.url}`,
+      method: data.method,
+      headers: { ...data.headers, ...this.headers },
+      expiresIn: data.expiresIn,
     };
   }
 
@@ -264,13 +273,16 @@ class RemoteStorage implements Storage {
     headers: Record<string, string>;
     expiresIn: number;
   }> {
-    // For development, return a direct download URL to the dev server
-    // In production, this would call the actual storage service for presigned URLs
+    const res = await this.fetch(`${this.baseUrl}/api/storage/download-url`, {
+      method: 'POST',
+      body: JSON.stringify({ key, expires_in: options?.expiresIn }),
+    });
+    const data = (await res.json()) as { url: string; method: string; headers: Record<string, string>; expiresIn: number };
     return {
-      url: `${this.baseUrl}/api/storage/${encodeURIComponent(key)}`,
-      method: 'GET',
-      headers: {},
-      expiresIn: options?.expiresIn || 3600, // Default 1 hour
+      url: data.url.startsWith('http') ? data.url : `${this.baseUrl}${data.url}`,
+      method: data.method,
+      headers: data.headers,
+      expiresIn: data.expiresIn,
     };
   }
 
@@ -434,7 +446,7 @@ class RemotePresenceService implements PresenceService {
   async join(channel: string, userId: string, metadata?: any): Promise<boolean> {
     const res = await fetch(`${this.baseUrl}/api/realtime/presence/${encodeURIComponent(channel)}/join`, {
       method: 'POST',
-      headers: this.headers,
+      headers: { ...this.headers, ...getRequestAuthHeader() },
       body: JSON.stringify({ userId, metadata }),
     });
     const data = await res.json() as any;
@@ -444,7 +456,7 @@ class RemotePresenceService implements PresenceService {
   async leave(channel: string, userId: string): Promise<boolean> {
     const res = await fetch(`${this.baseUrl}/api/realtime/presence/${encodeURIComponent(channel)}/leave`, {
       method: 'POST',
-      headers: this.headers,
+      headers: { ...this.headers, ...getRequestAuthHeader() },
       body: JSON.stringify({ userId }),
     });
     const data = await res.json() as any;
@@ -453,7 +465,7 @@ class RemotePresenceService implements PresenceService {
 
   async members(channel: string): Promise<Array<{ userId: string; metadata?: any; lastSeen?: number }>> {
     const res = await fetch(`${this.baseUrl}/api/realtime/presence/${encodeURIComponent(channel)}`, {
-      headers: this.headers,
+      headers: { ...this.headers, ...getRequestAuthHeader() },
     });
     const data = await res.json() as any;
     return data.members ?? [];
@@ -470,14 +482,14 @@ class RemoteRealtimeService implements RealtimeService {
   async publish(channel: string, data: any, options?: { userId?: string }): Promise<void> {
     await fetch(`${this.baseUrl}/api/realtime/publish`, {
       method: 'POST',
-      headers: this.headers,
+      headers: { ...this.headers, ...getRequestAuthHeader() },
       body: JSON.stringify({ channel, data, userId: options?.userId }),
     });
   }
 
   async channels(): Promise<string[]> {
     const res = await fetch(`${this.baseUrl}/api/realtime/channels`, {
-      headers: this.headers,
+      headers: { ...this.headers, ...getRequestAuthHeader() },
     });
     const data = await res.json() as any;
     return data.channels ?? [];
@@ -498,7 +510,7 @@ class RemoteAuthService implements AuthService {
   private async post(path: string, body?: any): Promise<any> {
     const res = await fetch(`${this.baseUrl}/api/platform/auth${path}`, {
       method: 'POST',
-      headers: this.headers,
+      headers: { ...this.headers, ...getRequestAuthHeader() },
       body: body !== undefined ? JSON.stringify(body) : undefined,
     });
     if (!res.ok) {
@@ -577,6 +589,156 @@ class RemoteAuthService implements AuthService {
     return this.post('/oauth/callback', { provider, code: params.code, state: params.state });
   }
 
+  // ── Groups ──
+
+  async createGroup(options: any): Promise<any> {
+    return this.post('/groups/create', options);
+  }
+  async listGroups(): Promise<any[]> {
+    return this.post('/groups/list', {});
+  }
+  async getGroup(groupId: string): Promise<any> {
+    return this.post('/groups/get', { group_id: groupId });
+  }
+  async updateGroup(groupId: string, options: any): Promise<any> {
+    return this.post('/groups/update', { group_id: groupId, ...options });
+  }
+  async deleteGroup(groupId: string): Promise<void> {
+    await this.post('/groups/delete', { group_id: groupId });
+  }
+  async addUserToGroup(userId: string, groupId: string): Promise<void> {
+    await this.post('/groups/add-user', { user_id: userId, group_id: groupId });
+  }
+  async removeUserFromGroup(userId: string, groupId: string): Promise<void> {
+    await this.post('/groups/remove-user', { user_id: userId, group_id: groupId });
+  }
+  async getUserGroups(userId: string): Promise<any[]> {
+    return this.post('/groups/get-user-groups', { user_id: userId });
+  }
+  async getGroupMembers(groupId: string): Promise<any[]> {
+    return this.post('/groups/get-members', { group_id: groupId });
+  }
+  async getGroupPermissions(groupId: string): Promise<any[]> {
+    return this.post('/groups/get-permissions', { group_id: groupId });
+  }
+  async setGroupPermissions(groupId: string, permissions: any[]): Promise<void> {
+    await this.post('/groups/set-permissions', { group_id: groupId, permissions });
+  }
+
+  // ── Circles ──
+
+  async createCircle(options: any): Promise<any> {
+    return this.post('/circles/create', options);
+  }
+  async listCircles(): Promise<any[]> {
+    return this.post('/circles/list', {});
+  }
+  async getCircle(circleId: string): Promise<any> {
+    return this.post('/circles/get', { circle_id: circleId });
+  }
+  async updateCircle(circleId: string, options: any): Promise<any> {
+    return this.post('/circles/update', { circle_id: circleId, ...options });
+  }
+  async deleteCircle(circleId: string): Promise<void> {
+    await this.post('/circles/delete', { circle_id: circleId });
+  }
+  async addCircleMember(circleId: string, options: any): Promise<void> {
+    await this.post('/circles/add-member', { circle_id: circleId, ...options });
+  }
+  async removeCircleMember(circleId: string, userId: string): Promise<void> {
+    await this.post('/circles/remove-member', { circle_id: circleId, user_id: userId });
+  }
+  async getCircleMembers(circleId: string): Promise<any[]> {
+    return this.post('/circles/get-members', { circle_id: circleId });
+  }
+  async getUserCircles(userId: string): Promise<any[]> {
+    return this.post('/circles/get-user-circles', { user_id: userId });
+  }
+
+  // ── Resources ──
+
+  async createResource(options: any): Promise<any> {
+    return this.post('/resources/create', options);
+  }
+  async listResources(): Promise<any[]> {
+    return this.post('/resources/list', {});
+  }
+  async updateResource(resourceId: string, options: any): Promise<any> {
+    return this.post('/resources/update', { resource_id: resourceId, ...options });
+  }
+  async deleteResource(resourceId: string): Promise<void> {
+    await this.post('/resources/delete', { resource_id: resourceId });
+  }
+
+  // ── Relation types ──
+
+  async createRelationType(options: any): Promise<any> {
+    return this.post('/relation-types/create', options);
+  }
+  async listRelationTypes(): Promise<any[]> {
+    return this.post('/relation-types/list', {});
+  }
+  async updateRelationType(id: string, options: any): Promise<any> {
+    return this.post('/relation-types/update', { id, ...options });
+  }
+  async deleteRelationType(id: string): Promise<void> {
+    await this.post('/relation-types/delete', { id });
+  }
+
+  // ── Profile ──
+
+  async getProfile(userId: string): Promise<Record<string, any>> {
+    return this.post('/profile/get', { user_id: userId });
+  }
+  async setProfile(userId: string, data: Record<string, any>): Promise<void> {
+    await this.post('/profile/set', { user_id: userId, data });
+  }
+
+  // ── Auth config ──
+
+  async getAuthConfig(): Promise<any> {
+    return this.post('/config/get', {});
+  }
+  async setAuthConfig(config: any): Promise<void> {
+    await this.post('/config/set', config);
+  }
+
+  // ── Stewardship sub-namespace ──
+
+  readonly stewardship = {
+    resolve: (userId: string) => this.post('/stewardship/resolve', { user_id: userId }),
+    createOverride: (options: any) =>
+      this.post('/stewardship/create-override', options),
+    revoke: async (id: string) => {
+      await this.post('/stewardship/revoke', { id });
+    },
+    checkPermission: async (
+      stewardId: string,
+      wardId: string,
+      resource: string,
+      action: string,
+    ): Promise<boolean> => {
+      const r = await this.post('/stewardship/check-permission', {
+        steward_id: stewardId,
+        ward_id: wardId,
+        resource,
+        action,
+      });
+      return Boolean((r as any)?.allowed);
+    },
+    createActAs: (stewardId: string, wardId: string) =>
+      this.post('/stewardship/create-act-as', { steward_id: stewardId, ward_id: wardId }),
+    listAudit: (
+      userId: string,
+      options: { limit?: number; offset?: number } = {},
+    ) =>
+      this.post('/stewardship/list-audit', {
+        user_id: userId,
+        limit: options.limit ?? 50,
+        offset: options.offset ?? 0,
+      }),
+  };
+
   withAuth<T extends (request: Request & { user: AuthUser }) => Promise<Response>>(
     handler: T
   ): (request: Request) => Promise<Response> {
@@ -610,32 +772,95 @@ class RemoteAuthService implements AuthService {
 
   // ── Request-scoped identity + authorization ──
   //
-  // These APIs operate on per-request state inside the platform runtime and
-  // don't have a remote equivalent. Throw so callers get a clear message
-  // instead of silently wrong behavior.
-
-  setCurrentUser(_token: string | null): Promise<void> {
-    return Promise.reject(new Error(
-      'platform.auth.setCurrentUser is only available inside the Maravilla runtime. ' +
-      'Remote clients should pass the Authorization header with each request instead.'
-    ));
+  // In dev mode the SDK uses Node's AsyncLocalStorage (via
+  // request-scope.ts) to track per-request state — tenants must wrap
+  // their inbound request handler with `runWithRequest(...)`. Without
+  // that wrapper, set/get/can fall back to clear errors / anonymous
+  // results so the misuse is obvious rather than silent.
+
+  async setCurrentUser(token: string | null): Promise<void> {
+    const { getCurrentRequestStore } = await import('./request-scope.js');
+    const store = getCurrentRequestStore();
+    if (!store) {
+      // No active request scope (e.g. background task / one-shot
+      // script / test that didn't wrap). Silent no-op matches the
+      // runtime's op_auth_set_current_user behaviour when
+      // REQUEST_CTX isn't set
+      // (crates/runtime/src/ops/platform/ops_authz.rs:90-114).
+      // The Maravilla Vite plugin auto-opens a scope for every dev
+      // HTTP request, so SvelteKit/RR hook code reaches this branch
+      // only outside the request lifecycle.
+      return;
+    }
+    if (!token) {
+      store.token = undefined;
+      store.user = undefined;
+      return;
+    }
+    store.token = token;
+    store.user = await this.validate(token);
   }
 
   getCurrentUser(): AuthCaller {
-    throw new Error(
-      'platform.auth.getCurrentUser is only available inside the Maravilla runtime. ' +
-      'Remote clients have no per-request caller context.'
-    );
+    // Synchronous read: ALS module is already loaded by the time
+    // setCurrentUser ran, OR we just return anonymous.
+    // Use require-style import via a cached reference to keep this sync.
+    const mod = (RemoteAuthService as any)._requestScope as
+      | typeof import('./request-scope.js')
+      | undefined;
+    const store = mod?.getCurrentRequestStore?.();
+    const user = store?.user;
+    if (!user) {
+      return mod?.anonymousCaller?.() ?? {
+        user_id: '',
+        email: '',
+        is_admin: false,
+        roles: [],
+        is_anonymous: true,
+      };
+    }
+    return {
+      user_id: user.id,
+      email: user.email,
+      is_admin: false,
+      roles: user.groups ?? [],
+      is_anonymous: false,
+    };
   }
 
-  can(_action: string, _resourceId: string, _node?: Record<string, unknown> | null): Promise<boolean> {
-    return Promise.reject(new Error(
-      'platform.auth.can is only available inside the Maravilla runtime. ' +
-      'Remote clients cannot evaluate per-request policies because there is no bound caller.'
-    ));
+  async can(
+    action: string,
+    resourceId: string,
+    node?: Record<string, unknown> | null,
+  ): Promise<boolean> {
+    const { getCurrentRequestStore } = await import('./request-scope.js');
+    const store = getCurrentRequestStore();
+    const token = store?.token;
+    if (!token) {
+      // No bound user → fail-closed, like the runtime evaluator.
+      return false;
+    }
+    const r = await this.post('/can', {
+      token,
+      action,
+      resource_id: resourceId,
+      node: node ?? null,
+    });
+    return Boolean((r as any)?.allowed);
   }
 }
 
+// Cache the request-scope module on the class so getCurrentUser can read
+// it synchronously (required by the AuthService interface — getCurrentUser
+// is sync). Lazy-load on first setCurrentUser/can call (which is async).
+import('./request-scope.js')
+  .then((mod) => {
+    (RemoteAuthService as any)._requestScope = mod;
+  })
+  .catch(() => {
+    // Non-Node environment — getCurrentUser will return anonymous.
+  });
+
 /**
  * Remote stub for the per-request Layer 2 policy toggle. The toggle lives in
  * per-request state inside the runtime and has no remote equivalent.
@@ -670,7 +895,7 @@ class RemoteWorkflows implements Workflows {
   private async request(path: string, options: RequestInit = {}): Promise<Response> {
     const response = await fetch(`${this.baseUrl}${path}`, {
       ...options,
-      headers: { ...this.headers, ...options.headers },
+      headers: { ...this.headers, ...getRequestAuthHeader(), ...options.headers },
     });
     if (!response.ok && response.status !== 404) {
       const error = await response.text();

package/src/request-scope.ts

@@ -0,0 +1,133 @@
+/**
+ * Per-request scope for the SDK's remote client. Mirrors the runtime's
+ * `REQUEST_CTX` (a `tokio::task_local!` in Rust) so that
+ * `platform.auth.setCurrentUser(token)`, `getCurrentUser()`, and `can()`
+ * — plus future per-request state like the Layer-2 policy toggle —
+ * have a place to live when the SDK is running outside the runtime
+ * (Vite SSR, Node.js HTTP servers, edge workers that expose Node APIs).
+ *
+ * Implementation: Node's `AsyncLocalStorage`. Tenant code wraps each
+ * inbound request with `runWithRequest(async () => { ... })` so the
+ * store stays scoped to the request's async chain. `setCurrentUser`
+ * / `can` read and write that store; if a tenant forgets to wrap, the
+ * methods either no-op (set) or throw a clear error (get/can).
+ */
+
+import type { AuthCaller, AuthUser } from './types.js';
+
+export interface RequestStore {
+  /** Bound access-token JWT (set by `auth.setCurrentUser`). */
+  token?: string;
+  /** Bound user (cached so `getCurrentUser` doesn't re-validate). */
+  user?: AuthUser;
+  /** Whether Layer-2 policy enforcement is enabled for this request. */
+  policyEnabled: boolean;
+}
+
+// Lazy-loaded so this module is safe to import in non-Node environments
+// (browsers, edge workers) where `node:async_hooks` doesn't exist. Calls
+// to runWithRequest in those environments fall back to a synchronous
+// no-op scope (the fn just runs `fn()`).
+let alsImpl: { run: (s: RequestStore, fn: () => any) => any; getStore: () => RequestStore | undefined } | null = null;
+
+async function ensureAls() {
+  if (alsImpl) return alsImpl;
+  try {
+    // Dynamic import keeps non-Node environments from crashing at module
+    // load time. `node:async_hooks` is unconditionally available in Node.
+    const { AsyncLocalStorage } = await import('node:async_hooks');
+    const inner = new AsyncLocalStorage<RequestStore>();
+    alsImpl = {
+      run: (s, fn) => inner.run(s, fn),
+      getStore: () => inner.getStore(),
+    };
+  } catch {
+    // Non-Node: stub. Note that without ALS, concurrent requests will
+    // share the same `cachedStore`, which is wrong — but in non-Node
+    // SDK environments the per-request use case typically doesn't
+    // apply (browser code is single-threaded per page).
+    let cached: RequestStore | undefined;
+    alsImpl = {
+      run: (s, fn) => {
+        const prev = cached;
+        cached = s;
+        try {
+          return fn();
+        } finally {
+          cached = prev;
+        }
+      },
+      getStore: () => cached,
+    };
+  }
+  return alsImpl;
+}
+
+/**
+ * Wrap a function in a fresh request scope. **Rarely needed** — the
+ * Maravilla Vite plugin (`@maravilla-labs/vite-plugin`) auto-opens a
+ * scope around every inbound dev HTTP request, so tenant code
+ * (SvelteKit `hooks.server.ts`, RR/Remix loaders, etc.) reaches
+ * `setCurrentUser/getCurrentUser/can` with a scope already active.
+ *
+ * Reach for `runWithRequest` only when the SDK runs **outside** an
+ * HTTP request: standalone Node scripts, test fixtures, custom
+ * servers that don't go through Vite. Inside an active scope,
+ * `platform.auth.setCurrentUser/getCurrentUser/can` operate on a
+ * per-request store keyed by Node's `AsyncLocalStorage`.
+ *
+ * @example
+ * ```ts
+ * // Test fixture that needs to bind a user before exercising the SDK
+ * await runWithRequest(async () => {
+ *   await getPlatform().auth.setCurrentUser(testToken);
+ *   const result = await getPlatform().env.DB.find('users', {});
+ *   expect(result).toEqual(...);
+ * });
+ * ```
+ */
+export async function runWithRequest<T>(fn: () => Promise<T> | T): Promise<T> {
+  const als = await ensureAls();
+  return als.run({ policyEnabled: true }, () => Promise.resolve(fn())) as Promise<T>;
+}
+
+/**
+ * Read the current request's store, if any. Returns undefined when
+ * called outside a `runWithRequest` scope. Used by `RemoteAuthService`
+ * and (future) other Remote* services to source per-request state.
+ *
+ * Note: the `als` may not yet be initialised when this is called; in
+ * that case the function returns undefined synchronously. Subsequent
+ * `runWithRequest` calls will populate it.
+ */
+export function getCurrentRequestStore(): RequestStore | undefined {
+  return alsImpl?.getStore();
+}
+
+/**
+ * Construct an anonymous `AuthCaller` snapshot — used by
+ * `auth.getCurrentUser()` when no identity is bound.
+ */
+export function anonymousCaller(): AuthCaller {
+  return {
+    user_id: '',
+    email: '',
+    is_admin: false,
+    roles: [],
+    is_anonymous: true,
+  };
+}
+
+/**
+ * Return `Authorization: Bearer <token>` if a token is bound in the
+ * current request store, else an empty object. Every Remote* service's
+ * fetch helper merges this so dev-server can identify the caller and
+ * (eventually) enforce Layer-2 policies on KV/DB/Storage ops.
+ *
+ * Synchronous so it can be called from inside `headers: { ... }`
+ * literals without forcing each fetch helper to be re-shaped.
+ */
+export function getRequestAuthHeader(): Record<string, string> {
+  const token = alsImpl?.getStore()?.token;
+  return token ? { Authorization: `Bearer ${token}` } : {};
+}