@maravilla-labs/types 0.1.35 → 0.2.1

package/index.d.ts

@@ -203,6 +203,64 @@ export interface Storage {
      */
     getMetadata(key: string): Promise<StorageMetadata>;
 }
+/**
+ * Authenticated user record
+ */
+export interface AuthUser {
+    id: string;
+    email: string;
+    email_verified: boolean;
+    status: 'active' | 'suspended' | 'deactivated';
+    provider: string;
+    groups: string[];
+    created_at: number;
+    updated_at: number;
+    last_login_at?: number;
+}
+
+/**
+ * Session returned after login or refresh
+ */
+export interface AuthSession {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+    user: AuthUser;
+}
+
+/**
+ * Custom registration field
+ */
+export interface AuthField {
+    key: string;
+    label: string;
+    field_type: string;
+    required: boolean;
+    show_on_register: boolean;
+}
+
+/**
+ * Auth service for end-user authentication
+ */
+export interface AuthService {
+    register(options: { email: string; password: string; profile?: Record<string, any> }): Promise<AuthUser>;
+    login(options: { email: string; password: string }): Promise<AuthSession>;
+    validate(accessToken: string): Promise<AuthUser>;
+    refresh(refreshToken: string): Promise<AuthSession>;
+    logout(sessionId: string): Promise<void>;
+    getUser(userId: string): Promise<AuthUser | null>;
+    listUsers(filter?: { limit?: number; offset?: number; status?: string; email_contains?: string }): Promise<{ users: AuthUser[]; total: number; limit: number; offset: number }>;
+    updateUser(userId: string, update: { email?: string; status?: string; profile?: Record<string, any> }): Promise<AuthUser>;
+    deleteUser(userId: string): Promise<void>;
+    sendVerification(userId: string): Promise<{ token: string }>;
+    verifyEmail(token: string): Promise<void>;
+    sendPasswordReset(email: string): Promise<{ token: string }>;
+    resetPassword(token: string, newPassword: string): Promise<void>;
+    changePassword(userId: string, oldPassword: string, newPassword: string): Promise<void>;
+    getFieldConfig(): Promise<{ fields: AuthField[] }>;
+    withAuth<T extends (request: Request & { user: AuthUser }) => Promise<Response>>(handler: T): (request: Request) => Promise<Response>;
+}
+
 /**
  * Main platform interface available in runtime
  */
@@ -213,6 +271,8 @@ export interface Platform {
     db: Database;
     /** Storage service instance */
     storage: Storage;
+    /** Auth service for end-user authentication */
+    auth: AuthService;
     /** Legacy aliases for compatibility */
     env: {
         KV: KvStore;

package/index.ts

@@ -234,6 +234,138 @@ export interface Storage {
   getMetadata(key: string): Promise<StorageMetadata>;
 }
 
+// Stewardship Types
+
+/** Delegation mode for stewardship overrides */
+export type DelegationMode = 'full' | 'scoped';
+
+/** Status of a stewardship override */
+export type StewardshipStatus = 'active' | 'suspended' | 'revoked' | 'expired';
+
+/** A scoped permission entry */
+export interface ScopedPermission {
+  /** Resource name */
+  resource: string;
+  /** Allowed actions on the resource */
+  actions: string[];
+}
+
+/** A stewardship override record */
+export interface StewardshipOverride {
+  id: string;
+  steward_id: string;
+  ward_id: string;
+  delegation_mode: DelegationMode;
+  scoped_permissions: ScopedPermission[];
+  valid_from?: number;
+  valid_until?: number;
+  status: StewardshipStatus;
+  reason?: string;
+  source: string;
+  source_circle_id?: string;
+  source_relation_type_id?: string;
+  created_at: number;
+  updated_at: number;
+}
+
+/** Options for creating a stewardship override */
+export interface CreateStewardshipOverrideRequest {
+  steward_id: string;
+  ward_id: string;
+  delegation_mode?: DelegationMode;
+  scoped_permissions?: ScopedPermission[];
+  valid_from?: number;
+  valid_until?: number;
+  reason?: string;
+}
+
+/** Result of resolving stewardship for a user */
+export interface StewardshipResolution {
+  /** Users who are stewards of this user */
+  stewards: StewardshipOverride[];
+  /** Users this user is a steward of */
+  wards: StewardshipOverride[];
+}
+
+/** Context for acting as another user */
+export interface ActAsContext {
+  steward_id: string;
+  ward_id: string;
+  delegation_mode: DelegationMode;
+  scoped_permissions: ScopedPermission[];
+  session_token: string;
+  expires_at: number;
+}
+
+/** An entry in the stewardship audit log */
+export interface StewardshipAuditEntry {
+  id: string;
+  performed_by: string;
+  on_behalf_of: string;
+  action: string;
+  resource?: string;
+  details?: Record<string, any>;
+  created_at: number;
+}
+
+/** Options for listing audit log entries */
+export interface AuditListOptions {
+  limit?: number;
+  offset?: number;
+}
+
+/** Stewardship service interface */
+export interface Stewardship {
+  resolve(userId: string): Promise<StewardshipResolution>;
+  createOverride(options: CreateStewardshipOverrideRequest): Promise<StewardshipOverride>;
+  revoke(id: string): Promise<void>;
+  checkPermission(stewardId: string, wardId: string, resource: string, action: string): Promise<boolean>;
+  createActAs(stewardId: string, wardId: string): Promise<ActAsContext>;
+  listAudit(userId: string, options?: AuditListOptions): Promise<StewardshipAuditEntry[]>;
+}
+
+// Resource Types
+
+/** A platform resource definition */
+export interface Resource {
+  id: string;
+  resource_name: string;
+  title: string;
+  description?: string;
+  actions: string[];
+  created_at: number;
+  updated_at: number;
+}
+
+/** Options for creating a resource */
+export interface CreateResourceRequest {
+  resource_name: string;
+  title: string;
+  description?: string;
+  actions?: string[];
+}
+
+// Circle Types
+
+/** Circle membership entry */
+export interface CircleMembership {
+  user_id: string;
+  email: string;
+  relationship: string;
+  is_primary_contact: boolean;
+  joined_at: number;
+}
+
+/** A circle */
+export interface Circle {
+  id: string;
+  name: string;
+  metadata?: Record<string, any>;
+  member_count: number;
+  created_at: number;
+  updated_at: number;
+}
+
 // Platform Types
 
 /**
@@ -246,6 +378,39 @@ export interface Platform {
   db: Database;
   /** Storage service instance */
   storage: Storage;
+  /** Auth service with stewardship, resources, and circle helpers */
+  auth: {
+    register(options: { email: string; password: string; profile?: Record<string, any> }): Promise<any>;
+    login(options: { email: string; password: string }): Promise<any>;
+    validate(accessToken: string): Promise<any>;
+    refresh(refreshToken: string): Promise<any>;
+    logout(sessionId: string): Promise<void>;
+    getUser(userId: string): Promise<any>;
+    listUsers(filter?: Record<string, any>): Promise<any>;
+    updateUser(userId: string, update: Record<string, any>): Promise<any>;
+    deleteUser(userId: string): Promise<void>;
+    sendVerification(userId: string): Promise<any>;
+    verifyEmail(token: string): Promise<void>;
+    sendPasswordReset(email: string): Promise<any>;
+    resetPassword(token: string, newPassword: string): Promise<void>;
+    changePassword(userId: string, oldPassword: string, newPassword: string): Promise<void>;
+    getFieldConfig(): Promise<any>;
+    getOAuthUrl(provider: string, options?: { redirectUri?: string }): Promise<any>;
+    handleOAuthCallback(provider: string, params: { code: string; state: string }): Promise<any>;
+
+    /** Stewardship (guardian/ward delegation) */
+    stewardship: Stewardship;
+
+    /** List available resources */
+    listResources(): Promise<Resource[]>;
+    /** Create a resource definition */
+    createResource(options: CreateResourceRequest): Promise<Resource>;
+
+    /** Get circle members */
+    getCircleMembers(circleId: string): Promise<CircleMembership[]>;
+    /** Get circles a user belongs to */
+    getUserCircles(userId: string): Promise<Circle[]>;
+  };
   /** Legacy aliases for compatibility */
   env: {
     KV: KvStore;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/types",
-  "version": "0.1.35",
+  "version": "0.2.1",
   "description": "TypeScript definitions for Maravilla Runtime platform APIs",
   "main": "index.ts",
   "types": "index.ts",