moai-adk 0.32.8__py3-none-any.whl → 0.41.2__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-platform-firebase-auth/reference.md

@@ -0,0 +1,382 @@
+# Firebase Authentication Reference
+
+Extended reference documentation for Firebase Authentication covering advanced patterns, configuration guides, and security best practices.
+
+---
+
+## Context7 Documentation Access
+
+For the latest Firebase Authentication documentation, use Context7 MCP tools:
+
+Step 1: Resolve library ID using resolve-library-id with query "firebase"
+
+Step 2: Fetch documentation using get-library-docs with the resolved Context7 ID and topic "authentication"
+
+This provides access to the most current API documentation, breaking changes, and best practices.
+
+---
+
+## Firebase Console Configuration
+
+### Authentication Provider Setup
+
+Navigate to Firebase Console at console.firebase.google.com, select your project, then go to Authentication section.
+
+Sign-in Method Configuration:
+- Enable desired providers under Sign-in method tab
+- Configure OAuth credentials for social providers
+- Set up authorized domains for web applications
+- Configure email templates for email-based authentication
+
+### OAuth Provider Configuration
+
+Google Sign-In:
+- Automatically configured with Firebase project
+- Configure OAuth consent screen in Google Cloud Console
+- Add authorized domains and redirect URIs
+
+Facebook Login:
+- Create Facebook App at developers.facebook.com
+- Copy App ID and App Secret to Firebase Console
+- Configure OAuth redirect URI from Firebase Console
+
+Apple Sign-In:
+- Enable Sign In with Apple in Apple Developer Console
+- Configure Service ID for web authentication
+- Generate private key for server-to-server communication
+- Add team ID, key ID, and private key to Firebase Console
+
+Twitter/X:
+- Create Twitter App at developer.twitter.com
+- Copy API Key and API Secret to Firebase Console
+
+GitHub:
+- Create GitHub OAuth App at github.com/settings/developers
+- Copy Client ID and Client Secret to Firebase Console
+
+Microsoft:
+- Register application in Azure Portal
+- Configure as multi-tenant or single-tenant
+- Copy Application ID and Client Secret to Firebase Console
+
+---
+
+## Admin SDK Setup
+
+### Node.js Initialization
+
+```typescript
+import { initializeApp, cert } from 'firebase-admin/app';
+import { getAuth } from 'firebase-admin/auth';
+
+// Initialize with service account
+initializeApp({
+  credential: cert('./service-account-key.json')
+});
+
+// Or use default credentials (Cloud Functions, Cloud Run)
+initializeApp();
+
+const auth = getAuth();
+```
+
+### Python Initialization
+
+```python
+import firebase_admin
+from firebase_admin import credentials, auth
+
+cred = credentials.Certificate('./service-account-key.json')
+firebase_admin.initialize_app(cred)
+```
+
+### Go Initialization
+
+```go
+import (
+    "context"
+    firebase "firebase.google.com/go/v4"
+    "google.golang.org/api/option"
+)
+
+opt := option.WithCredentialsFile("./service-account-key.json")
+app, err := firebase.NewApp(context.Background(), nil, opt)
+client, err := app.Auth(context.Background())
+```
+
+---
+
+## Multi-Factor Authentication
+
+### Enrollment Flow
+
+```typescript
+import { multiFactor, PhoneMultiFactorGenerator, PhoneAuthProvider } from 'firebase/auth';
+
+const enrollMFA = async (phoneNumber: string) => {
+  const user = auth.currentUser;
+  if (!user) throw new Error('Not signed in');
+
+  const mfUser = multiFactor(user);
+  const session = await mfUser.getSession();
+
+  const phoneAuthProvider = new PhoneAuthProvider(auth);
+  const verificationId = await phoneAuthProvider.verifyPhoneNumber(
+    { phoneNumber, session },
+    recaptchaVerifier
+  );
+
+  // User enters verification code
+  const code = await promptUserForCode();
+
+  const credential = PhoneAuthProvider.credential(verificationId, code);
+  const assertion = PhoneMultiFactorGenerator.assertion(credential);
+
+  await mfUser.enroll(assertion, 'Phone');
+};
+```
+
+### Sign-In with MFA Challenge
+
+```typescript
+import { getMultiFactorResolver } from 'firebase/auth';
+
+try {
+  await signInWithEmailAndPassword(auth, email, password);
+} catch (error: any) {
+  if (error.code === 'auth/multi-factor-auth-required') {
+    const resolver = getMultiFactorResolver(auth, error);
+
+    // Show available second factors
+    const hints = resolver.hints;
+
+    // Verify with selected factor
+    const phoneAuthProvider = new PhoneAuthProvider(auth);
+    const verificationId = await phoneAuthProvider.verifyPhoneNumber(
+      { multiFactorHint: hints[0], session: resolver.session },
+      recaptchaVerifier
+    );
+
+    const code = await promptUserForCode();
+    const credential = PhoneAuthProvider.credential(verificationId, code);
+    const assertion = PhoneMultiFactorGenerator.assertion(credential);
+
+    await resolver.resolveSignIn(assertion);
+  }
+}
+```
+
+---
+
+## Cloud Functions Auth Triggers
+
+### User Lifecycle Events
+
+```typescript
+import { auth } from 'firebase-functions';
+import { getFirestore, FieldValue } from 'firebase-admin/firestore';
+
+// On user creation
+export const onUserCreate = auth.user().onCreate(async (user) => {
+  await getFirestore().collection('users').doc(user.uid).set({
+    email: user.email,
+    displayName: user.displayName,
+    photoURL: user.photoURL,
+    createdAt: FieldValue.serverTimestamp(),
+    providers: user.providerData.map(p => p.providerId)
+  });
+});
+
+// On user deletion
+export const onUserDelete = auth.user().onDelete(async (user) => {
+  // Clean up user data
+  const batch = getFirestore().batch();
+
+  batch.delete(getFirestore().collection('users').doc(user.uid));
+
+  const userDocs = await getFirestore()
+    .collection('userContent')
+    .where('userId', '==', user.uid)
+    .get();
+
+  userDocs.forEach(doc => batch.delete(doc.ref));
+
+  await batch.commit();
+});
+```
+
+### Blocking Functions
+
+```typescript
+import { beforeUserCreated, beforeUserSignedIn } from 'firebase-functions/v2/identity';
+
+// Validate before user creation
+export const validateUserCreate = beforeUserCreated((event) => {
+  const user = event.data;
+
+  // Domain restriction
+  if (!user.email?.endsWith('@company.com')) {
+    throw new HttpsError('permission-denied', 'Unauthorized email domain');
+  }
+
+  // Set initial claims
+  return {
+    customClaims: { role: 'member' }
+  };
+});
+
+// Validate before sign-in
+export const validateSignIn = beforeUserSignedIn((event) => {
+  const user = event.data;
+
+  // Check if user is disabled in external system
+  // Return undefined to allow, throw to block
+
+  return;
+});
+```
+
+---
+
+## Session Management
+
+### Persistence Options
+
+```typescript
+import {
+  setPersistence,
+  browserLocalPersistence,
+  browserSessionPersistence,
+  inMemoryPersistence
+} from 'firebase/auth';
+
+// Persist across browser sessions (default)
+await setPersistence(auth, browserLocalPersistence);
+
+// Clear on tab close
+await setPersistence(auth, browserSessionPersistence);
+
+// No persistence (memory only)
+await setPersistence(auth, inMemoryPersistence);
+```
+
+### Session Cookies (Server-Side)
+
+```typescript
+// Server: Create session cookie
+const expiresIn = 60 * 60 * 24 * 5 * 1000; // 5 days
+const sessionCookie = await getAuth().createSessionCookie(idToken, { expiresIn });
+
+// Set cookie in response
+res.cookie('session', sessionCookie, {
+  maxAge: expiresIn,
+  httpOnly: true,
+  secure: true,
+  sameSite: 'strict'
+});
+
+// Verify session cookie
+const decodedClaims = await getAuth().verifySessionCookie(sessionCookie, true);
+```
+
+---
+
+## Firebase Auth Emulator
+
+### Configuration
+
+```typescript
+import { connectAuthEmulator } from 'firebase/auth';
+
+if (process.env.NODE_ENV === 'development') {
+  connectAuthEmulator(auth, 'http://localhost:9099');
+}
+```
+
+### Emulator Features
+
+Test Phone Numbers:
+- Configure test phone numbers in Firebase Console
+- Use any 6-digit code for verification
+- No actual SMS sent
+
+Emulator UI:
+- Access at localhost:4000 when running emulator suite
+- View and manage test users
+- Inspect authentication state
+
+Programmatic User Creation:
+- Create users via Emulator REST API
+- Useful for test setup
+
+---
+
+## Security Best Practices
+
+Token Validation:
+- Always verify ID tokens server-side for sensitive operations
+- Check token expiration and issuer claims
+- Use Admin SDK verifyIdToken method
+
+Rate Limiting:
+- Firebase automatically rate limits authentication requests
+- Implement additional rate limiting for sensitive operations
+- Monitor failed authentication attempts
+
+Secure Configuration:
+- Never expose service account keys in client code
+- Use environment variables for sensitive configuration
+- Rotate API keys periodically
+
+Custom Claims Security:
+- Never trust client-provided claims
+- Validate claims server-side before granting access
+- Use Security Rules for claim-based access control
+
+---
+
+## Error Codes Reference
+
+Common Authentication Errors:
+- auth/user-not-found: No user with provided identifier
+- auth/wrong-password: Invalid password
+- auth/email-already-in-use: Email already registered
+- auth/weak-password: Password does not meet requirements
+- auth/invalid-email: Malformed email address
+- auth/user-disabled: User account is disabled
+- auth/too-many-requests: Rate limit exceeded
+- auth/network-request-failed: Network connectivity issue
+
+Social Provider Errors:
+- auth/popup-closed-by-user: User closed popup before completion
+- auth/popup-blocked: Browser blocked popup window
+- auth/account-exists-with-different-credential: Email linked to different provider
+- auth/cancelled-popup-request: Multiple popup requests
+
+Phone Auth Errors:
+- auth/invalid-phone-number: Malformed phone number
+- auth/invalid-verification-code: Wrong SMS code
+- auth/code-expired: Verification code expired
+- auth/quota-exceeded: SMS quota exceeded
+
+---
+
+## Platform SDK Versions
+
+Web SDK:
+- Firebase JS SDK v9+ (modular)
+- Legacy v8 (compat mode available)
+
+Mobile SDKs:
+- iOS: FirebaseAuth via Swift Package Manager or CocoaPods
+- Android: firebase-auth via Gradle
+
+Cross-Platform:
+- Flutter: firebase_auth package
+- React Native: @react-native-firebase/auth
+
+---
+
+Version: 1.0.0
+Last Updated: 2025-12-07
+Parent Skill: moai-platform-firebase-auth

moai_adk/templates/.claude/skills/moai-platform-firestore/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: "moai-platform-firestore"
+description: "Firebase Firestore specialist covering NoSQL patterns, real-time sync, offline caching, and Security Rules. Use when building mobile-first apps with offline support, implementing real-time listeners, or configuring Firestore security."
+version: 2.0.0
+category: "platform"
+modularized: true
+user-invocable: false
+tags: ['firestore', 'firebase', 'nosql', 'realtime', 'offline', 'mobile']
+updated: 2026-01-08
+status: "active"
+context7-libraries: ['/firebase/firebase-docs']
+related-skills: ['moai-platform-firebase-auth', 'moai-lang-flutter', 'moai-lang-typescript']
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
+---
+
+# moai-platform-firestore: Firebase Firestore Specialist
+
+## Quick Reference
+
+Firebase Firestore Expertise: NoSQL document database with real-time synchronization, offline-first architecture, Security Rules, Cloud Functions triggers, and mobile-optimized SDKs.
+
+### Core Capabilities
+
+Real-time Sync: Automatic synchronization across all connected clients
+Offline Caching: IndexedDB persistence with automatic sync when online
+Security Rules: Declarative field-level access control
+Cloud Functions: Document triggers for server-side processing
+Composite Indexes: Complex query optimization
+
+### When to Use Firestore
+
+- Mobile-first applications with offline support
+- Real-time collaborative features
+- Cross-platform apps (iOS, Android, Web, Flutter)
+- Projects requiring Google Cloud integration
+- Apps with flexible, evolving data structures
+
+### Context7 Documentation Access
+
+Step 1: Resolve the Firebase library ID
+- Use mcp__context7__resolve-library-id with libraryName "firebase"
+- Returns the Context7-compatible library ID
+
+Step 2: Fetch Firestore documentation
+- Use mcp__context7__get-library-docs with the resolved ID
+- Set topic to specific area: "firestore security-rules", "firestore offline", "firestore real-time"
+- Allocate 6000-8000 tokens for comprehensive coverage
+
+### Module Index
+
+This skill is organized into specialized modules for deep implementation guidance:
+
+Security Rules Module (modules/security-rules.md):
+- Basic rule structure and syntax
+- Role-based access control patterns
+- Custom claims integration
+- Field-level validation
+- Testing and debugging rules
+
+Offline and Caching Module (modules/offline-cache.md):
+- Persistent cache configuration
+- Multi-tab manager setup
+- Cache size optimization
+- Sync status handling
+- Network state management
+
+Real-time Listeners Module (modules/realtime-listeners.md):
+- Snapshot listener patterns
+- Metadata handling for pending writes
+- Query subscription optimization
+- Listener lifecycle management
+- Error handling strategies
+
+Transactions Module (modules/transactions.md):
+- Atomic batch operations
+- Transaction patterns and constraints
+- Distributed counter implementation
+- Conflict resolution strategies
+- Performance considerations
+
+---
+
+## Implementation Guide
+
+### Firestore Initialization with Offline Persistence
+
+```typescript
+import { initializeApp } from 'firebase/app'
+import {
+  initializeFirestore,
+  persistentLocalCache,
+  persistentMultipleTabManager,
+  CACHE_SIZE_UNLIMITED
+} from 'firebase/firestore'
+
+const app = initializeApp({
+  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
+  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
+  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID
+})
+
+export const db = initializeFirestore(app, {
+  localCache: persistentLocalCache({
+    tabManager: persistentMultipleTabManager(),
+    cacheSizeBytes: CACHE_SIZE_UNLIMITED
+  })
+})
+```
+
+### Basic Security Rules Structure
+
+```javascript
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    match /users/{userId} {
+      allow read, write: if request.auth.uid == userId;
+    }
+
+    match /documents/{docId} {
+      allow read: if resource.data.isPublic == true
+        || request.auth.uid == resource.data.ownerId
+        || request.auth.uid in resource.data.collaborators;
+      allow create: if request.auth != null
+        && request.resource.data.ownerId == request.auth.uid;
+      allow update, delete: if request.auth.uid == resource.data.ownerId;
+    }
+  }
+}
+```
+
+### Real-time Listener with Metadata
+
+```typescript
+import { collection, query, where, orderBy, onSnapshot } from 'firebase/firestore'
+
+export function subscribeToDocuments(userId: string, callback: (docs: any[]) => void) {
+  const q = query(
+    collection(db, 'documents'),
+    where('collaborators', 'array-contains', userId),
+    orderBy('createdAt', 'desc')
+  )
+
+  return onSnapshot(q, { includeMetadataChanges: true }, (snapshot) => {
+    callback(snapshot.docs.map((doc) => ({
+      id: doc.id,
+      ...doc.data(),
+      _pending: doc.metadata.hasPendingWrites,
+      _fromCache: doc.metadata.fromCache
+    })))
+  })
+}
+```
+
+### Composite Indexes Configuration
+
+```json
+{
+  "indexes": [
+    {
+      "collectionGroup": "documents",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "organizationId", "order": "ASCENDING" },
+        { "fieldPath": "createdAt", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "documents",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "tags", "arrayConfig": "CONTAINS" },
+        { "fieldPath": "createdAt", "order": "DESCENDING" }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Performance and Pricing
+
+### Performance Characteristics
+
+Read Latency: 50-200ms (varies by region)
+Write Latency: 100-300ms
+Real-time Propagation: 100-500ms
+Offline Sync: Automatic on reconnection
+
+### Free Tier (2024)
+
+Storage: 1GB
+Daily Reads: 50,000
+Daily Writes: 20,000
+Daily Deletes: 20,000
+
+---
+
+## Works Well With
+
+- moai-platform-firebase-auth - Firebase Authentication integration
+- moai-lang-flutter - Flutter SDK patterns
+- moai-lang-typescript - TypeScript client patterns
+- moai-domain-mobile - Mobile architecture patterns
+- moai-quality-security - Security Rules best practices
+
+---
+
+## Additional Resources
+
+- reference.md - Extended documentation and best practices
+- examples.md - Complete working code examples
+- modules/security-rules.md - Security Rules deep dive
+- modules/offline-cache.md - Offline persistence patterns
+- modules/realtime-listeners.md - Real-time subscription patterns
+- modules/transactions.md - Batch and transaction operations
+
+---
+
+Status: Production Ready
+Generated with: MoAI-ADK Skill Factory v2.0
+Last Updated: 2026-01-06
+Platform: Firebase Firestore