{"_id":"@al-hamoud/firebase-supabase-bridge","_rev":"4-f8cb19e69b0577dc601b02e569e6583d","name":"@al-hamoud/firebase-supabase-bridge","dist-tags":{"latest":"2.0.1"},"versions":{"1.0.0":{"name":"@al-hamoud/firebase-supabase-bridge","version":"1.0.0","keywords":["firebase","supabase","postgresql","authentication","auth-bridge","enterprise-auth","business-logic","zero-rate-limiting","claims","jwt","phone-auth","monads","result-type"],"author":{"name":"Opena-app"},"license":"MIT","_id":"@al-hamoud/firebase-supabase-bridge@1.0.0","maintainers":[{"name":"al-hamoud","email":"ihsan.alhamoud@gmail.com"}],"homepage":"https://github.com/Opena-app/firebase-auth-claims#readme","bugs":{"url":"https://github.com/Opena-app/firebase-auth-claims/issues"},"dist":{"shasum":"389418ff54fd7ce17e2f290d16819c570f89c391","tarball":"https://registry.npmjs.org/@al-hamoud/firebase-supabase-bridge/-/firebase-supabase-bridge-1.0.0.tgz","fileCount":36,"integrity":"sha512-xl+/s0I42dYmiwtNLNHeXzP5p9Ytcd4o2J68x81tGLUGqs2jvLTvn7mRFcldUf2g7YqpfaBHMSbHNDLR+BahQw==","signatures":[{"sig":"MEUCIQCZyW7UUiecmSn1kOp9pAIRajF9MAb+R/Pni8bmsNmsDAIgaq3+sIOYgosP9z41UXrtqE8V9WMK7kwzxcoFnb+SnNU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":112475},"main":"lib/dist/index.js","types":"lib/dist/index.d.ts","engines":{"node":">=14.0.0"},"gitHead":"a2354a42b41f5a8817816565d6edc7eba9b1e877","scripts":{"dev":"npm run build:config && firebase emulators:start","lint":"cd functions && npm run lint","test":"cd functions && npm test","build":"npm run build:config && cd functions && npm run build","serve":"npm run build:config && firebase serve","setup":"cp .env.example .env && echo 'Please edit .env with your Firebase configuration'","deploy":"npm run build && firebase deploy","build:lib":"npm run build:lib:clean && npm run build:lib:compile && npm run build:lib:types","test:core":"cd functions && npm test -- --testNamePattern=\"^((?!Performance|Scalability|Load).)*$\"","publish:dry":"npm publish --dry-run","build:config":"node build-config.js","publish:beta":"npm publish --tag beta","prepublishOnly":"npm run build:lib && npm run test:core","publish:latest":"npm publish","security:check":"cd functions && npm run security:audit","build:lib:clean":"rimraf lib/dist","build:lib:types":"tsc -p lib/tsconfig.json --declaration --emitDeclarationOnly --outDir lib/dist","build:lib:compile":"tsc -p lib/tsconfig.json"},"_npmUser":{"name":"al-hamoud","email":"ihsan.alhamoud@gmail.com"},"repository":{"url":"git+https://github.com/Opena-app/firebase-auth-claims.git","type":"git"},"_npmVersion":"11.5.2","description":"Enterprise Firebase Auth + Supabase/PostgreSQL bridge with zero rate limiting and comprehensive business logic support","directories":{},"_nodeVersion":"22.19.0","dependencies":{"rate-limiter-flexible":"^7.3.0"},"_hasShrinkwrap":false,"devDependencies":{"rimraf":"^5.0.10","typescript":"^5.9.2","@types/node":"^18.19.127"},"peerDependencies":{"firebase-admin":">=11.0.0","firebase-functions":">=4.0.0","@supabase/supabase-js":">=2.0.0"},"_npmOperationalInternal":{"tmp":"tmp/firebase-supabase-bridge_1.0.0_1758959179962_0.33089297050540867","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@al-hamoud/firebase-supabase-bridge","version":"1.0.1","keywords":["firebase","supabase","postgresql","authentication","auth-bridge","enterprise-auth","business-logic","zero-rate-limiting","claims","jwt","phone-auth","monads","result-type"],"author":{"name":"Opena-app"},"license":"MIT","_id":"@al-hamoud/firebase-supabase-bridge@1.0.1","maintainers":[{"name":"al-hamoud","email":"ihsan.alhamoud@gmail.com"}],"homepage":"https://github.com/Opena-app/firebase-auth-claims#readme","bugs":{"url":"https://github.com/Opena-app/firebase-auth-claims/issues"},"dist":{"shasum":"ab540221168e511e01ce8fa62e43fc66fa053ff2","tarball":"https://registry.npmjs.org/@al-hamoud/firebase-supabase-bridge/-/firebase-supabase-bridge-1.0.1.tgz","fileCount":36,"integrity":"sha512-5Ln94scY3nhP5u7/J4eIsIfwf9nvf/mC4JyStBfZPwE9tJnbDIn48SMCqATbnJgwQ63sFbLn6/4XAfa61Hrg2A==","signatures":[{"sig":"MEUCIQCSk+I1WaKJU/2o05ZDDVeWd4x1AkVwCqZs1w3SvVzBXAIgSWvLSG81DmUi2wrm/qdpI3xgWwGL2y1cOZslfLUECG8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":112475},"main":"lib/dist/index.js","types":"lib/dist/index.d.ts","engines":{"node":">=14.0.0"},"gitHead":"88bcca812c5126f66b74657b966ef1ca11b1267f","scripts":{"dev":"npm run build:config && firebase emulators:start","lint":"cd functions && npm run lint","test":"cd functions && npm test","build":"npm run build:config && cd functions && npm run build","serve":"npm run build:config && firebase serve","setup":"cp .env.example .env && echo 'Please edit .env with your Firebase configuration'","deploy":"npm run build && firebase deploy","build:lib":"npm run build:lib:clean && npm run build:lib:compile && npm run build:lib:types","test:core":"cd functions && npm test -- --testNamePattern=\"^((?!Performance|Scalability|Load).)*$\"","publish:dry":"npm publish --dry-run","build:config":"node build-config.js","publish:beta":"npm publish --tag beta","prepublishOnly":"npm run build:lib && npm run test:core","publish:latest":"npm publish","security:check":"cd functions && npm run security:audit","build:lib:clean":"rimraf lib/dist","build:lib:types":"tsc -p lib/tsconfig.json --declaration --emitDeclarationOnly --outDir lib/dist","build:lib:compile":"tsc -p lib/tsconfig.json"},"_npmUser":{"name":"al-hamoud","email":"ihsan.alhamoud@gmail.com"},"repository":{"url":"git+https://github.com/Opena-app/firebase-auth-claims.git","type":"git"},"_npmVersion":"11.5.2","description":"Enterprise Firebase Auth + Supabase/PostgreSQL bridge with zero rate limiting and comprehensive business logic support","directories":{},"_nodeVersion":"22.19.0","dependencies":{"rate-limiter-flexible":"^7.3.0"},"_hasShrinkwrap":false,"devDependencies":{"rimraf":"^5.0.10","typescript":"^5.9.2","@types/node":"^18.19.127"},"peerDependencies":{"firebase-admin":">=11.0.0","firebase-functions":">=4.0.0","@supabase/supabase-js":">=2.0.0"},"_npmOperationalInternal":{"tmp":"tmp/firebase-supabase-bridge_1.0.1_1758959683513_0.6812090067496939","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@al-hamoud/firebase-supabase-bridge","version":"2.0.0","keywords":["firebase","supabase","postgresql","authentication","auth-bridge","enterprise-auth","business-logic","zero-rate-limiting","claims","jwt","phone-auth","monads","result-type"],"author":{"name":"Opena-app"},"license":"MIT","_id":"@al-hamoud/firebase-supabase-bridge@2.0.0","maintainers":[{"name":"al-hamoud","email":"ihsan.alhamoud@gmail.com"}],"homepage":"https://github.com/Opena-app/firebase-auth-claims#readme","bugs":{"url":"https://github.com/Opena-app/firebase-auth-claims/issues"},"dist":{"shasum":"5f51895dd5eb679390941169c076cd073ec5c336","tarball":"https://registry.npmjs.org/@al-hamoud/firebase-supabase-bridge/-/firebase-supabase-bridge-2.0.0.tgz","fileCount":36,"integrity":"sha512-O9BE4lLSvibqqhiIanrYOHw3ed1VkNs0FURWItFjf/ToCc47opp8DEjwpkC50yVoUwVfeJwZv223YPGcC0AByg==","signatures":[{"sig":"MEQCIBugA8BIF5qMaixm74q6NSisjKzy7hxPGF16ssddkKQ+AiB+ZBbtwzulnc36pLKVmbq64/5cPIsjkfsR/aDDZafZCA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":117398},"main":"lib/dist/index.js","types":"lib/dist/index.d.ts","engines":{"node":">=14.0.0"},"gitHead":"ec4825feb32930f09fae9a7e60ea38dd8d7d4076","scripts":{"dev":"npm run build:config && firebase emulators:start","lint":"cd functions && npm run lint","test":"cd functions && npm test","build":"npm run build:config && cd functions && npm run build","serve":"npm run build:config && firebase serve","setup":"cp .env.example .env && echo 'Please edit .env with your Firebase configuration'","deploy":"npm run build && firebase deploy","build:lib":"npm run build:lib:clean && npm run build:lib:compile && npm run build:lib:types","test:core":"cd functions && npm test -- --testNamePattern=\"^((?!Performance|Scalability|Load).)*$\"","publish:dry":"npm publish --dry-run","build:config":"node build-config.js","publish:beta":"npm publish --tag beta","prepublishOnly":"npm run build:lib && npm run test:core","publish:latest":"npm publish","security:check":"cd functions && npm run security:audit","build:lib:clean":"rimraf lib/dist","build:lib:types":"tsc -p lib/tsconfig.json --declaration --emitDeclarationOnly --outDir lib/dist","build:lib:compile":"tsc -p lib/tsconfig.json"},"_npmUser":{"name":"al-hamoud","email":"ihsan.alhamoud@gmail.com"},"repository":{"url":"git+https://github.com/Opena-app/firebase-auth-claims.git","type":"git"},"_npmVersion":"11.5.2","description":"Enterprise Firebase Auth + Supabase/PostgreSQL bridge with zero rate limiting and comprehensive business logic support","directories":{},"_nodeVersion":"22.19.0","dependencies":{"rate-limiter-flexible":"^7.3.0"},"_hasShrinkwrap":false,"devDependencies":{"rimraf":"^5.0.10","typescript":"^5.9.2","@types/node":"^18.19.127"},"peerDependencies":{"firebase-admin":">=11.0.0","firebase-functions":">=4.0.0","@supabase/supabase-js":">=2.0.0"},"_npmOperationalInternal":{"tmp":"tmp/firebase-supabase-bridge_2.0.0_1759309015818_0.9215662338280814","host":"s3://npm-registry-packages-npm-production"}},"2.0.1":{"name":"@al-hamoud/firebase-supabase-bridge","version":"2.0.1","description":"Enterprise Firebase Auth + Supabase/PostgreSQL bridge with zero rate limiting and comprehensive business logic support","main":"lib/dist/index.js","types":"lib/dist/index.d.ts","scripts":{"build:config":"node build-config.js","dev":"npm run build:config && firebase emulators:start","build":"npm run build:config && cd functions && npm run build","build:lib":"npm run build:lib:clean && npm run build:lib:compile && npm run build:lib:types","build:lib:clean":"rimraf lib/dist","build:lib:compile":"tsc -p lib/tsconfig.json","build:lib:types":"tsc -p lib/tsconfig.json --declaration --emitDeclarationOnly --outDir lib/dist","test:core":"cd functions && npm test -- --testNamePattern=\"^((?!Performance|Scalability|Load).)*$\"","prepublishOnly":"npm run build:lib && npm run test:core","publish:dry":"npm publish --dry-run","publish:beta":"npm publish --tag beta","publish:latest":"npm publish","deploy":"npm run build && firebase deploy","serve":"npm run build:config && firebase serve","setup":"cp .env.example .env && echo 'Please edit .env with your Firebase configuration'","security:check":"cd functions && npm run security:audit","test":"cd functions && npm test","lint":"cd functions && npm run lint"},"dependencies":{},"devDependencies":{"@types/node":"^18.19.127","rimraf":"^5.0.10","typescript":"^5.9.2"},"keywords":["firebase","supabase","postgresql","authentication","auth-bridge","enterprise-auth","business-logic","zero-rate-limiting","claims","jwt","phone-auth","monads","result-type"],"author":{"name":"Opena-app"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Opena-app/firebase-auth-claims.git"},"bugs":{"url":"https://github.com/Opena-app/firebase-auth-claims/issues"},"homepage":"https://github.com/Opena-app/firebase-auth-claims#readme","engines":{"node":">=14.0.0"},"peerDependencies":{"@supabase/supabase-js":">=2.0.0","firebase-admin":">=11.0.0","firebase-functions":">=4.0.0"},"_id":"@al-hamoud/firebase-supabase-bridge@2.0.1","gitHead":"8ba4ab25c41ff9313b95498dbe865f8995bc13c7","_nodeVersion":"22.19.0","_npmVersion":"11.5.2","dist":{"integrity":"sha512-bwCvHiYk+I42Zj5yyXAAG/ivbd6afA5AVeEHAGakprWwR8+KBOed6cTaDC20+dGplRQPct813OR4qXSSraDRqQ==","shasum":"15efeb9248c5797657290ba90067be5fbcda1a2b","tarball":"https://registry.npmjs.org/@al-hamoud/firebase-supabase-bridge/-/firebase-supabase-bridge-2.0.1.tgz","fileCount":36,"unpackedSize":117357,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICHU6O8ubhOEt/gkuFZM0CC/9pDMkfsJ/bnaUhml0JobAiEA5ooah0KkOVyZwR2TQworF4DV0GWwdevRcGDxnf/lxWo="}]},"_npmUser":{"name":"al-hamoud","email":"ihsan.alhamoud@gmail.com"},"directories":{},"maintainers":[{"name":"al-hamoud","email":"ihsan.alhamoud@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/firebase-supabase-bridge_2.0.1_1759309826187_0.5246482713834701"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-27T07:46:19.843Z","modified":"2025-10-01T09:10:26.847Z","1.0.0":"2025-09-27T07:46:20.144Z","1.0.1":"2025-09-27T07:54:43.727Z","2.0.0":"2025-10-01T08:56:56.006Z","2.0.1":"2025-10-01T09:10:26.384Z"},"bugs":{"url":"https://github.com/Opena-app/firebase-auth-claims/issues"},"author":{"name":"Opena-app"},"license":"MIT","homepage":"https://github.com/Opena-app/firebase-auth-claims#readme","keywords":["firebase","supabase","postgresql","authentication","auth-bridge","enterprise-auth","business-logic","zero-rate-limiting","claims","jwt","phone-auth","monads","result-type"],"repository":{"type":"git","url":"git+https://github.com/Opena-app/firebase-auth-claims.git"},"description":"Enterprise Firebase Auth + Supabase/PostgreSQL bridge with zero rate limiting and comprehensive business logic support","maintainers":[{"name":"al-hamoud","email":"ihsan.alhamoud@gmail.com"}],"readme":"# 🔐 Firebase Auth + PostgreSQL — Enterprise Authentication System\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![Firebase](https://img.shields.io/badge/Firebase-FFCA28?style=flat&logo=firebase&logoColor=black)](https://firebase.google.com/)\n[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-336791?style=flat&logo=postgresql&logoColor=white)](https://www.postgresql.org/)\n[![Supabase](https://img.shields.io/badge/Supabase-3ECF8E?style=flat&logo=supabase&logoColor=white)](https://supabase.com/)\n![Tests](https://img.shields.io/badge/Tests-74%20Passing-brightgreen)\n\nA production-ready hybrid authentication system combining **Firebase Auth** for authentication with **PostgreSQL/Supabase** for 100% database-native business logic. Features **zero rate limiting**, **monad-based error handling**, and **PostgreSQL-first architecture** for maximum performance.\n\n**Live System:** https://supa-claims-bridge-001.web.app\n\n---\n\n## ✨ Features\n\n### 🔥 **Firebase Authentication** (Enhanced)\n- **Phone OTP Authentication**: Production-ready SMS verification\n- **JWT Token Generation**: Secure token handling with custom claims\n- **Zero Rate Limiting**: No artificial restrictions on legitimate usage\n- **Security Headers**: HTTPS-only, API restrictions, CORS protection\n\n### 🗄️ **PostgreSQL Business Logic** (Zero Rate Limiting Architecture)  \n- **100% Database-Native**: All business operations in PostgreSQL functions\n- **Zero Cold Starts**: Instant response times vs Firebase Functions\n- **Row Level Security**: Database-enforced data isolation  \n- **Audit Trails**: Complete operation logging (not for limiting)\n- **No Rate Limiting**: Unlimited legitimate operations\n- **Monad Error Handling**: Consistent Result<T,E> pattern throughout\n\n### 🛡️ **Enterprise Security**\n- **Defense-in-Depth**: Multi-layer security validation\n- **Claims Versioning**: Future-proof JWT schema evolution  \n- **Input Validation**: Strict parameter and role validation\n- **Search Path Security**: Protection against injection attacks\n\n> Details: [Architecture & Security](./Architecture-and-Security.md), [Claims Versioning](./CLAIMS-VERSIONING-SUMMARY.md), [Rate Limiting](./Rate-Limiting.md).\n\n---\n\n## 🧩 Functions Overview\n\n- **Blocking Triggers**\n  - `authBeforeUserCreated` — set initial claims at sign-up\n  - `authBeforeUserSignedIn` — ensure roles/claims on every sign-in\n\n- **Callable HTTPS**\n  - `setCustomClaimsForUser` — update a single user’s claims\n  - `bulkSetCustomClaims` — admin bulk operations (hardened flow)\n  - `verifyTokenClaims` — debug/inspect decoded token + claims\n\nSource pointers and constraints live under `functions/src/` (types/validators/limiter). See the Developer Guide for dev/test/deploy.  \n\n---\n\n## � Architecture\n\nThis system uses a **hybrid architecture** combining Firebase Authentication with PostgreSQL business logic:\n\n### 🔄 **Authentication Flow** (Firebase)\n1. **Phone OTP**: User authenticates via Firebase Phone Auth\n2. **JWT Generation**: Firebase issues secure tokens with user identity  \n3. **Token Validation**: PostgreSQL validates Firebase JWTs for business operations\n\n### 🗄️ **Business Logic Flow** (PostgreSQL)\n1. **Client requests** a business role via Supabase RPC call\n2. **PostgreSQL function** validates Firebase JWT and request parameters\n3. **Database operation** updates user business role with audit logging\n4. **Response** confirms role assignment with security validation\n\n### 🛡️ **Security Architecture**\n- ✅ **Firebase JWT Validation**: PostgreSQL verifies Firebase token authenticity\n- ✅ **Row Level Security**: Database-enforced data isolation per user\n- ✅ **Rate Limiting**: PostgreSQL-native request throttling  \n- ✅ **Audit Logging**: Complete operation history in database\n- ✅ **Input Validation**: Strict parameter checking in PostgreSQL functions\n- ✅ **Search Path Security**: Protection against SQL injection attacks\n\nRead: [Architecture & Security](./Architecture-and-Security.md)\n\n---\n\n## 🚦 Rate Limiting (Configurable)\n\n- **Dual Rate Limits**: X1 requests per Y1 seconds **AND** X2 requests per Y2 seconds\n- **Environment Configurable**: Set limits via `.env` variables (`VITE_RATE_LIMIT_1_REQUESTS`, etc.)\n- **Default**: 1 request/minute AND 3 requests/15 minutes (original Firebase behavior)\n- **Database Enforced**: PostgreSQL-native rate limiting with complete audit trails\n- **Flexible Examples**: 5/minute + 20/hour (dev), 1/2min + 2/hour (enterprise)\n\nReference: [Configurable Rate Limiting Guide](./CONFIGURABLE-RATE-LIMITING-GUIDE.md)\n\n---\n\n## 🔄 Claims Versioning\n\n- Adds `claims_v` to new claims writes; utilities handle legacy vs modern formats.  \n- Version helpers: `getCurrentClaimsVersion()`, `getClaimsVersion(claims)`, etc.  \n- Validates claims size (~900 bytes enforced) before updates.\n\nSummary & examples: [CLAIMS-VERSIONING-SUMMARY.md](./CLAIMS-VERSIONING-SUMMARY.md)\n\n---\n\n---\n\n## 📚 Documentation\n\n### 🚀 Getting Started\n- **[Quick Setup Guide](./docs/guides/quick-setup.md)** - Get up and running in minutes\n- **[Deployment Guide](./docs/guides/deployment.md)** - Deploy to Firebase & Supabase\n- **[Architecture Overview](./docs/guides/architecture.md)** - System design and principles\n\n### � Development\n- **[Testing Guide](./docs/guides/testing.md)** - Comprehensive testing documentation\n- **[Troubleshooting Guide](./docs/guides/troubleshooting.md)** - Common issues and solutions\n- **[API Reference](./docs/api-reference.md)** - Complete API documentation\n- **[Integration Guide](./docs/integration-guide.md)** - Client integration examples\n\n### 📦 NPM Package\n- **[NPM Package](https://www.npmjs.com/package/@al-hamoud/firebase-supabase-bridge)** - Install via npm\n- **[Package README](./lib/README.md)** - Package-specific documentation\n- **[Release Process](./RELEASE-PROCESS.md)** - How to publish new versions\n\n### 🔐 Security & Operations\n- **[Security Checklist](./docs-archive/doc/SECURITY-IMPLEMENTATION-CHECKLIST.md)** - Security hardening guide\n- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute\n- **[Changelog](./CHANGELOG.md)** - Version history and changes\n\n---\n\n## �🛠️ Quick Setup\n\n### Prerequisites\n- ✅ Firebase Project with Phone Authentication enabled\n- ✅ Supabase Project for PostgreSQL database\n- ✅ Node.js 18+ installed\n- ✅ Firebase CLI installed (`npm install -g firebase-tools`)\n\n### Installation\n\n1. **Clone the repository:**\n   ```bash\n   git clone https://github.com/Opena-app/firebase-auth-claims.git\n   cd firebase-auth-claims\n   ```\n\n2. **Install dependencies:**\n   ```bash\n   npm install\n   cd functions && npm install && cd ..\n   ```\n\n3. **Configure environment:**\n   ```bash\n   cp .env.example .env\n   # Edit .env with your Firebase and Supabase credentials\n   ```\n\n4. **Build configuration:**\n   ```bash\n   npm run build:config\n   ```\n\n5. **Deploy to Firebase:**\n   ```bash\n   firebase deploy --only hosting\n   ```\n\nFor detailed setup instructions, see the **[Quick Setup Guide](./docs/guides/quick-setup.md)**.\n\n---\n\n## 💻 Usage Example\n\n### Client Integration\n\n```javascript\nimport { initializeApp } from 'firebase/app';\nimport { getAuth, signInWithPhoneNumber } from 'firebase/auth';\nimport { createClient } from '@supabase/supabase-js';\n\n// Initialize Firebase\nconst app = initializeApp(window.FIREBASE_CONFIG);\nconst auth = getAuth(app);\n\n// Initialize Supabase\nconst supabase = createClient(\n  window.SUPABASE_CONFIG.url,\n  window.SUPABASE_CONFIG.publishableKey\n);\n\n// Authenticate with phone\nconst confirmationResult = await signInWithPhoneNumber(\n  auth,\n  '+447746506658',\n  recaptchaVerifier\n);\nawait confirmationResult.confirm('123456');\n\n// Set business role via PostgreSQL\nconst { data, error } = await supabase.rpc('set_user_business_role', {\n  target_uid: auth.currentUser.uid,\n  new_role: 'super-admin',\n  admin_uid: auth.currentUser.uid\n});\n\nif (data.success) {\n  console.log('✅ Role set:', data.business_role);\n  // Refresh token to get updated claims\n  await auth.currentUser.getIdToken(true);\n}\n```\n\n### NPM Package Usage\n\n```bash\nnpm install @al-hamoud/firebase-supabase-bridge\n```\n\n```typescript\nimport { \n  Result, \n  ok, \n  err, \n  safeValidateUserId,\n  AUTH_CONSTRAINTS \n} from '@al-hamoud/firebase-supabase-bridge';\n\n// Use Result monad for error handling\nconst userIdResult = safeValidateUserId('firebase-user-123');\nif (userIdResult.isOk()) {\n  console.log('Valid user ID:', userIdResult.value);\n} else {\n  console.error('Invalid:', userIdResult.error.message);\n}\n```\n\n---\n\n## 🧪 Testing\n\nRun the comprehensive test suite:\n\n```bash\ncd functions\nnpm test                    # Run all tests\nnpm test -- --coverage      # With coverage report\nnpm test -- --watch         # Watch mode for development\n```\n\n**Test Coverage:** 74+ passing tests covering authentication, business logic, security, and performance.\n\nSee the **[Testing Guide](./docs/guides/testing.md)** for detailed testing documentation.\n\n---\n\n## 🚀 Live Demo\n\n**Production System:** https://supa-claims-bridge-001.web.app\n\nFeatures:\n- Phone OTP authentication  \n- Custom business roles (super-admin, admin, member)\n- Real-time JWT custom claims\n- PostgreSQL business logic\n- Zero rate limiting\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our **[Contributing Guide](./CONTRIBUTING.md)** for details.\n\n### Quick Contribution Steps:\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes and add tests\n4. Run tests: `npm test`\n5. Commit: `git commit -m 'feat: add amazing feature'`\n6. Push: `git push origin feature/amazing-feature`\n7. Open a Pull Request\n\n---\n\n## 📄 License\n\nMIT © [al-hamoud](https://github.com/al-hamoud) — see [LICENSE](./LICENSE).\n\n---\n\n## 🔗 Links\n\n- **Live System:** https://supa-claims-bridge-001.web.app\n- **NPM Package:** https://www.npmjs.com/package/@al-hamoud/firebase-supabase-bridge\n- **GitHub Repository:** https://github.com/Opena-app/firebase-auth-claims\n- **Issue Tracker:** https://github.com/Opena-app/firebase-auth-claims/issues\n- **Firebase Console:** https://console.firebase.google.com/project/supa-claims-bridge-001\n- **Supabase Dashboard:** https://app.supabase.com\n\n---\n\n**Built with ❤️ for enterprise-grade authentication systems**\n\n---\n\n## � Usage & Deployment\n\n### Deploy PostgreSQL Functions\n```bash\n# Deploy business logic to your PostgreSQL/Supabase database\npsql -h YOUR_DB_HOST -d YOUR_DB_NAME -f postgresql-business-logic-complete.sql\n\n# Deploy Firebase JWT integration\npsql -h YOUR_DB_HOST -d YOUR_DB_NAME -f postgresql-firebase-jwt-fix.sql\n```\n\n### Client Integration\n```javascript\n// Initialize Firebase Auth and Supabase\nimport { initializeApp } from 'firebase/app';\nimport { getAuth } from 'firebase/auth';\nimport { createClient } from '@supabase/supabase-js';\n\n// Set business role using Supabase RPC with Firebase authentication\ntry {\n  const { data, error } = await supabase.rpc('set_user_business_role_firebase', {\n    firebase_uid: firebase_user.uid,\n    business_role: 'merchant'\n  });\n  \n  if (error) throw error;\n  console.log('Role set successfully:', data);\n} catch (error) {\n  console.error('Error setting role:', error);\n}\n```\n\n### 🧑‍💻 Developer Guide\n- **Database**: PostgreSQL 14+ with Supabase recommended\n- **Authentication**: Firebase Auth with Phone provider\n- **Testing**: End-to-end tests with Firebase Auth + PostgreSQL\n- **Security**: RLS policies and audit logging enabled\n\nFull setup: [Developer Guide](./Developer-Guide.md)\n\n---\n\n## 🌐 Web Tester (Invisible reCAPTCHA) + Firebase Hosting\n\nThis repo includes a lightweight web tester (`public/index.html` + `styles.css`) to:\n- Sign in with phone (Invisible reCAPTCHA)  \n- Call `verifyTokenClaims` once or in bursts (to exercise rate limits)\n\n**Setup (Option A — Firebase Hosting):**\n1. `firebase init hosting` → `public` dir, SPA = **No**  \n2. Put `index.html` and `styles.css` in `public/`  \n3. Deploy: `firebase deploy --only hosting`  \n4. Ensure **Authentication → Settings → Authorized domains** contains your `*.web.app`, `*.firebaseapp.com`, `localhost`  \n5. For heavy testing, prefer **Auth Emulator** or **test phone numbers** to avoid SMS throttling\n\n> The tester uses modular v10 SDK and manages the reCAPTCHA verifier correctly to avoid duplicate renders. Buttons include a burst tester to observe limiting.\n\n---\n\n## 🔒 Security Implementation Checklist\n\nA pragmatic, phased checklist (API key restrictions, authorized domains, billing alerts, etc.) is included to harden your project. Start with referrer/API restrictions and domain whitelisting; add monitoring next.\n\nChecklist: [SECURITY-IMPLEMENTATION-CHECKLIST.md](./SECURITY-IMPLEMENTATION-CHECKLIST.md)\n\n---\n\n## 🤝 Contributing & Release\n\n- Dev prerequisites, scripts, and CI expectations\n- Release checklist (tests, secrets, limits, deploy, monitor)\n- PR template & quality gates\n\nStart here:  \n- [Contributing](./CONTRIBUTING.md)  \n- [Contributing & Release](./Contributing-and-Release.md)  \n- [Pull Request Template](./pull_request_template.md)\n\n---\n\n## 📄 License\n\nMIT — see [LICENSE](./LICENSE).\n\n---\n\n## 📚 Doc Index (paths fixed)\n\n- **Architecture & Security** → `./Architecture-and-Security.md`  \n- **Rate Limiting** → `./Rate-Limiting.md`  \n- **Admin Operations & Claims** → `./Admin-Operations-and-Claims.md`  \n- **Claims Versioning Summary** → `./CLAIMS-VERSIONING-SUMMARY.md`  \n- **Developer Guide** → `./Developer-Guide.md`  \n- **Security Checklist** → `./SECURITY-IMPLEMENTATION-CHECKLIST.md`  \n- **Contributing** → `./CONTRIBUTING.md` / `./Contributing-and-Release.md`\n\n---\n\n### Credits\n\nBuilt with a security-first, SSOT architecture, and comprehensive tests.\n","readmeFilename":"README.md"}