fireproof-storage / fireproof-storage/fireproof
Add InPageReactStrategy for component-based authentication
- Dominant language
- TypeScript
- Stars
- 973
- Forks
- 58
- PR merge metrics
- No merged PRs in 30d
Description
## Problem
Currently, Fireproof's authentication strategies require either:
1. **SimpleTokenStrategy** - Pre-configured tokens (no user auth flow)
2. **RedirectStrategy** - Popup windows that can be blocked and redirect to external dashboard
3. **IframeStrategy** - Incomplete implementation with broken `waitForToken()`
This creates friction for React applications that want to:
- Integrate authentication naturally into their existing UI
- Use their preferred auth providers (Clerk, Auth0, Firebase, etc.)
- Avoid popup blockers and external redirects
- Maintain consistent UX within their application
## Proposed Solution
Create an **InPageReactStrategy** that allows consumers to provide their own React authentication component while maintaining the `TokenStrategie` interface.
### Design Overview
```typescript
export class InPageReactStrategy implements TokenStrategie {
constructor(AuthComponent: React.ComponentType) {
this.authComponent = AuthComponent;
}
open() {
// Render consumer's auth component into DOM
ReactDOM.render(createElement(this.authComponent, {
deviceId,
onToken: (tokenAndClaims) => this.handleToken(tokenAndClaims),
onClose: () => this.cleanup()
}), containerElement);
}
// ... implement other TokenStrategie methods
}
```
### Consumer Usage
```typescript
// Consumer provides their own auth component
function MyAuthComponent({ deviceId, onToken, onClose }: AuthComponentProps) {
const { getToken } = useAuth(); // Clerk, Auth0, etc.
const handleAuth = async () => {
const providerToken = await getToken();
// Exchange via consumer's backend
const response = await fetch('/api/fireproof-token', {
headers: { Authorization: `Bearer ${providerToken}` }
});
const { token } = await response.json();
onToken({ token, claims: decodeJwt(token) });
};
return (
Sign in to continue
Authenticate
);
}
// Use with Fireproof
const strategy = new InPageReactStrategy(MyAuthComponent);
const { database } = useFireproof("mydb", { strategy });
```
## Benefits
1. **Framework Native** - Works naturally with React patterns
2. **Provider Agnostic** - Consumer chooses any auth provider
3. **No Popup Blockers** - Renders inline components
4. **Consistent UX** - Matches application's design system
5. **Clean Separation** - Fireproof handles token interface, consumer handles auth provider
6. **Backend Token Exchange** - Secure server-side token exchange pattern
## Implementation Details
### Interface Definition
```typescript
interface AuthComponentProps {
deviceId: string;
onToken: (token: TokenAndClaims) => void;
onClose: () => void;
ledger?: string;
tenant?: string;
}
```
### Strategy Implementation
- `open()` - Render React component into DOM container
- `tryToken()` - Return cached token if available
- `waitForToken()` - Return Promise that resolves when component calls `onToken`
- `stop()` - Cleanup DOM and unmount component
### Token Exchange Flow
1. Consumer's React component handles auth provider integration
2. Component gets provider token (Clerk, Auth0, etc.)
3. Component calls consumer's API endpoint with provider token
4. Backend verifies provider token and exchanges for Fireproof token
5. Component calls `onToken()` with Fireproof token
6. Strategy resolves `waitForToken()` Promise
## Migration Path
This approach moves auth provider integration (like Clerk) from the Fireproof dashboard to the consumer side, providing:
- Better separation of concerns
- More flexibility for consumers
- Reduced complexity in Fireproof core
- Provider-agnostic authentication strategy
## Files to Modify
- `use-fireproof/in-page-react-strategy.ts` - New strategy implementation
- `use-fireproof/index.ts` - Export new strategy
- Documentation and examples
## Related
This addresses authentication UX issues while maintaining the existing `TokenStrategie` interface established in `core/types/protocols/cloud/gateway-control.ts:19`.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.