@maravilla-labs/platform 0.1.35 → 0.1.38

package/src/config.ts

@@ -0,0 +1,219 @@
+/**
+ * @fileoverview Typed schema for `maravilla.config.{ts,yaml,json}` files.
+ *
+ * Declares your project's auth settings (resources, groups, relations,
+ * registration fields, OAuth providers, security policy, branding) alongside
+ * your code. The Maravilla adapter reads this at build time and reconciles
+ * the settings into delivery on deploy.
+ *
+ * ```typescript
+ * import { defineConfig } from '@maravilla-labs/platform/config';
+ *
+ * export default defineConfig({
+ *   auth: {
+ *     resources: [
+ *       { name: 'todos', title: 'Todos', actions: ['read', 'write'],
+ *         policy: 'auth.user_id == node.owner' },
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * Omitted sections leave the DB alone — partial adoption is explicitly
+ * supported. List-based sections (`resources`, `groups`, `relations`,
+ * `oauth`) are upserted and never auto-delete DB-only entries. Singleton
+ * sections (`registration`, `security`, `branding`) are replaced wholesale
+ * when declared.
+ */
+
+/**
+ * String value that may either be a literal secret or a reference to an
+ * environment variable on the **tenant** (resolved server-side at
+ * reconcile time, never shipped plaintext in the manifest).
+ *
+ * Accepted forms:
+ *   - `"literal-value"` — inline (not recommended for real secrets)
+ *   - `"${env.VAR_NAME}"` — string-template form
+ *   - `{ env: "VAR_NAME" }` — object form
+ */
+export type SecretRef = string | { env: string };
+
+// ── Resources + policies ──
+
+export interface ResourceDefinition {
+  /** URL-safe slug. Used as the resource key in code (e.g. the KV namespace). */
+  name: string;
+  /** Human-readable title for the admin UI. */
+  title: string;
+  /** Optional longer description. */
+  description?: string;
+  /** Actions this resource supports, e.g. `['read', 'write', 'delete']`. */
+  actions: string[];
+  /**
+   * Optional raisin-rel policy expression. Evaluated on every KV/DB/
+   * realtime/media op that targets this resource. Leave empty to skip
+   * Layer 2 for this resource — tenant + owner isolation still applies.
+   */
+  policy?: string;
+}
+
+// ── Groups ──
+
+export interface GroupPermissionDefinition {
+  /** Must match a `ResourceDefinition.name`. */
+  resource_name: string;
+  /** Actions this group is granted on the resource. */
+  actions: string[];
+}
+
+export interface GroupDefinition {
+  /** Unique group name per tenant. */
+  name: string;
+  /** Optional description for the admin UI. */
+  description?: string;
+  /** Resource permissions granted to the group. Replaces the group's current permissions when declared. */
+  permissions?: GroupPermissionDefinition[];
+}
+
+// ── Relations ──
+
+export interface RelationTypeDefinition {
+  /** Uppercase identifier used in policies (`... VIA 'STEWARDS'`). */
+  relation_name: string;
+  /** Human-readable title. */
+  title: string;
+  description?: string;
+  /** Grouping for the admin UI (e.g. `"family"`, `"work"`). */
+  category?: string;
+  icon?: string;
+  color?: string;
+  /** Name of the inverse relation type, if one exists. */
+  inverse_relation_name?: string;
+  /** When true, membership in this relation implies stewardship rights. */
+  implies_stewardship?: boolean;
+  /** When true, the relation can only target users flagged as minors. */
+  requires_minor?: boolean;
+  /** When true, the relation is symmetric (A→B implies B→A). */
+  bidirectional?: boolean;
+}
+
+// ── Registration fields ──
+
+export interface RegistrationFieldDefinition {
+  /** Field key used as the form field name + in profile data. */
+  key: string;
+  /** Display label. */
+  label: string;
+  /** One of: text, email, phone, date, number, select, boolean, url, textarea. */
+  field_type: string;
+  required: boolean;
+  show_on_register: boolean;
+  /** Optional validation metadata — passed through to the UI. */
+  validation?: Record<string, unknown>;
+}
+
+export interface RegistrationConfig {
+  /** Ordered list of custom registration fields. Declaring this replaces the full list. */
+  fields: RegistrationFieldDefinition[];
+}
+
+// ── OAuth providers ──
+
+export interface OAuthProviderDefinition {
+  enabled: boolean;
+  client_id: string;
+  /** Prefer `{ env: "VAR_NAME" }` or `"${env.VAR_NAME}"`. */
+  client_secret: SecretRef;
+  scopes: string[];
+  /** Only for `custom_oidc`. */
+  discovery_url?: string;
+}
+
+export interface OAuthProvidersConfig {
+  google?: OAuthProviderDefinition;
+  github?: OAuthProviderDefinition;
+  okta?: OAuthProviderDefinition;
+  custom_oidc?: OAuthProviderDefinition;
+}
+
+// ── Security ──
+
+export interface PasswordPolicyDefinition {
+  min_length: number;
+  require_uppercase: boolean;
+  require_number: boolean;
+  require_special: boolean;
+}
+
+export interface SessionConfigDefinition {
+  access_token_ttl_secs: number;
+  refresh_token_ttl_secs: number;
+  max_sessions_per_user: number;
+  require_email_verification: boolean;
+}
+
+export interface SecurityConfig {
+  password_policy?: PasswordPolicyDefinition;
+  session?: SessionConfigDefinition;
+}
+
+// ── Branding ──
+
+export interface BrandingConfig {
+  app_name?: string;
+  logo_url?: string;
+  primary_color?: string;
+  secondary_color?: string;
+  welcome_message?: string;
+  welcome_subtitle?: string;
+  /** `"centered"`, `"split-left"`, `"split-right"`, or `"fullscreen"`. */
+  layout?: string;
+  background_image_url?: string;
+  /** 0–100 percentage. */
+  background_focal_point?: { x: number; y: number };
+  background_gradient?: string;
+  /** `"light"`, `"dark"`, or `"auto"`. */
+  color_mode?: string;
+  font_family?: string;
+  terms_url?: string;
+  privacy_url?: string;
+  /** Raw CSS merged into the hosted auth pages. */
+  custom_css?: string;
+}
+
+// ── Top-level shape ──
+
+export interface AuthConfigBlock {
+  resources?: ResourceDefinition[];
+  groups?: GroupDefinition[];
+  relations?: RelationTypeDefinition[];
+  registration?: RegistrationConfig;
+  oauth?: OAuthProvidersConfig;
+  security?: SecurityConfig;
+  branding?: BrandingConfig;
+}
+
+export interface MaravillaConfig {
+  /** All project-level auth settings. Every field is optional — partial adoption is supported. */
+  auth?: AuthConfigBlock;
+}
+
+/**
+ * Identity function that returns the config unchanged — exists purely so the
+ * TypeScript compiler can infer `MaravillaConfig` and give you IntelliSense
+ * on every field.
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig } from '@maravilla-labs/platform/config';
+ *
+ * export default defineConfig({
+ *   auth: {
+ *     resources: [{ name: 'todos', title: 'Todos', actions: ['read', 'write'] }],
+ *   },
+ * });
+ * ```
+ */
+export function defineConfig(config: MaravillaConfig): MaravillaConfig {
+  return config;
+}

package/src/index.ts

@@ -64,7 +64,7 @@ declare global {
   var platform: Platform | undefined;
 }
 
-let cachedPlatform: Platform | null = null;
+let cachedPlatform: Platform | undefined = undefined;
 
 /**
  * Get the platform instance. This will:
@@ -167,7 +167,7 @@ export function getPlatform(options?: {
  * ```
  */
 export function clearPlatformCache(): void {
-  cachedPlatform = null;
+  cachedPlatform = undefined;
   if (typeof globalThis !== 'undefined') {
     globalThis.__maravilla_platform = undefined;
   }

package/src/remote-client.ts

@@ -1,4 +1,4 @@
-import type { KvNamespace, KvListResult, Database, DbFindOptions, Storage, RealtimeService, PresenceService } from './types.js';
+import type { KvNamespace, KvListResult, Database, DbFindOptions, Storage, RealtimeService, PresenceService, AuthService, AuthCaller, AuthUser, AuthSession, AuthField, RegisterOptions, LoginOptions, UserListFilter, UserListResponse, UpdateUserOptions, PolicyService } from './types.js';
 import { RemoteMediaService } from './media.js';
 
 /**
@@ -405,6 +405,176 @@ class RemoteRealtimeService implements RealtimeService {
   }
 }
 
+/**
+ * Remote auth service for development environments.
+ * Calls the dev-server's platform auth ops via HTTP.
+ * @internal
+ */
+class RemoteAuthService implements AuthService {
+  constructor(
+    private baseUrl: string,
+    private headers: Record<string, string>
+  ) {}
+
+  private async post(path: string, body?: any): Promise<any> {
+    const res = await fetch(`${this.baseUrl}/api/platform/auth${path}`, {
+      method: 'POST',
+      headers: this.headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Auth error (${res.status}): ${text}`);
+    }
+    if (res.status === 204) return undefined;
+    return res.json();
+  }
+
+  async register(options: RegisterOptions): Promise<AuthUser> {
+    return this.post('/register', options);
+  }
+
+  async login(options: LoginOptions): Promise<AuthSession> {
+    return this.post('/login', options);
+  }
+
+  async validate(accessToken: string): Promise<AuthUser> {
+    return this.post('/validate', { token: accessToken });
+  }
+
+  async refresh(refreshToken: string): Promise<AuthSession> {
+    return this.post('/refresh', { token: refreshToken });
+  }
+
+  async logout(sessionId: string): Promise<void> {
+    await this.post('/logout', { session_id: sessionId });
+  }
+
+  async getUser(userId: string): Promise<AuthUser | null> {
+    return this.post('/get-user', { user_id: userId });
+  }
+
+  async listUsers(filter?: UserListFilter): Promise<UserListResponse> {
+    return this.post('/list-users', filter ?? {});
+  }
+
+  async updateUser(userId: string, update: UpdateUserOptions): Promise<AuthUser> {
+    return this.post('/update-user', { user_id: userId, ...update });
+  }
+
+  async deleteUser(userId: string): Promise<void> {
+    await this.post('/delete-user', { user_id: userId });
+  }
+
+  async sendVerification(userId: string): Promise<{ token: string }> {
+    return this.post('/send-verification', { user_id: userId });
+  }
+
+  async verifyEmail(token: string): Promise<void> {
+    await this.post('/verify-email', { token });
+  }
+
+  async sendPasswordReset(email: string): Promise<{ token: string }> {
+    return this.post('/send-password-reset', { email });
+  }
+
+  async resetPassword(token: string, newPassword: string): Promise<void> {
+    await this.post('/reset-password', { token, new_password: newPassword });
+  }
+
+  async changePassword(userId: string, oldPassword: string, newPassword: string): Promise<void> {
+    await this.post('/change-password', { user_id: userId, old_password: oldPassword, new_password: newPassword });
+  }
+
+  async getFieldConfig(): Promise<{ fields: AuthField[] }> {
+    return this.post('/field-config');
+  }
+
+  async getOAuthUrl(provider: string, options?: { redirectUri?: string }): Promise<{ auth_url: string; state: string }> {
+    return this.post('/oauth/start', { provider, redirect_uri: options?.redirectUri || `/_auth/callback/${provider}` });
+  }
+
+  async handleOAuthCallback(provider: string, params: { code: string; state: string }): Promise<any> {
+    return this.post('/oauth/callback', { provider, code: params.code, state: params.state });
+  }
+
+  withAuth<T extends (request: Request & { user: AuthUser }) => Promise<Response>>(
+    handler: T
+  ): (request: Request) => Promise<Response> {
+    const self = this;
+    return async function(request: Request): Promise<Response> {
+      let token: string | null = null;
+      const authHeader = request.headers.get('Authorization');
+      if (authHeader?.startsWith('Bearer ')) {
+        token = authHeader.slice(7);
+      } else {
+        const cookies = request.headers.get('Cookie') ?? '';
+        const match = cookies.match(/__session=([^;]+)/);
+        if (match) token = match[1];
+      }
+      if (!token) {
+        return new Response(JSON.stringify({ error: 'Authentication required' }), {
+          status: 401, headers: { 'Content-Type': 'application/json' },
+        });
+      }
+      try {
+        const user = await self.validate(token);
+        (request as any).user = user;
+        return handler(request as Request & { user: AuthUser });
+      } catch {
+        return new Response(JSON.stringify({ error: 'Invalid or expired token' }), {
+          status: 401, headers: { 'Content-Type': 'application/json' },
+        });
+      }
+    };
+  }
+
+  // ── 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.'
+    ));
+  }
+
+  getCurrentUser(): AuthCaller {
+    throw new Error(
+      'platform.auth.getCurrentUser is only available inside the Maravilla runtime. ' +
+      'Remote clients have no per-request caller context.'
+    );
+  }
+
+  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.'
+    ));
+  }
+}
+
+/**
+ * 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.
+ */
+class RemotePolicyService implements PolicyService {
+  setEnabled(_enabled: boolean): void {
+    throw new Error(
+      'platform.policy.setEnabled is only available inside the Maravilla runtime.'
+    );
+  }
+
+  isEnabled(): boolean {
+    throw new Error(
+      'platform.policy.isEnabled is only available inside the Maravilla runtime.'
+    );
+  }
+}
+
 /**
  * Create a remote platform client for development environments.
  * 
@@ -446,6 +616,8 @@ export function createRemoteClient(baseUrl: string, tenant: string) {
   const storage = new RemoteStorage(baseUrl, headers);
   const media = new RemoteMediaService(baseUrl, headers);
   const realtime = new RemoteRealtimeService(baseUrl, headers);
+  const auth = new RemoteAuthService(baseUrl, headers);
+  const policy = new RemotePolicyService();
 
   return {
     env: {
@@ -455,5 +627,7 @@ export function createRemoteClient(baseUrl: string, tenant: string) {
     },
     media,
     realtime,
+    auth,
+    policy,
   };
 }