despia-base44-oauth 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 despia-native
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,240 @@
+# despia-base44-oauth
+
+Native-safe OAuth for React + Base44 apps running inside the **Despia native runtime**. Uses Despia's secure browser transport (iOS: ASWebAuthenticationSession, Android: Chrome Custom Tabs) and the required `oauth/` deeplink prefix to close the browser and return tokens to your WebView.
+
+## Prerequisites
+
+Your app must have these installed:
+
+| Package | Required | Notes |
+|---------|----------|-------|
+| `react` | Yes | 17+ |
+| `react-router-dom` | Yes | 6+ |
+| `despia-native` | Yes | Despia SDK – required for Despia native apps. You should already have this. |
+| `@base44/sdk` | Yes | Base44 JavaScript SDK – for `base44.auth.loginWithProvider()` and `base44.auth.setToken()` |
+
+**Important:** `despia-native` is **required** when your app runs in the Despia wrapper. Import it as the default export: `import despia from 'despia-native'`. Do not create mock implementations. This package uses `despia-native` internally for the `oauth://` protocol.
+
+This package expects a Base44 client with `auth.loginWithProvider(provider, fromUrl?)` and `auth.setToken(token, saveToStorage?)`, matching the [@base44/sdk](https://www.npmjs.com/package/@base44/sdk) auth module. Supported providers: `google`, `microsoft`, `facebook`.
+
+**Custom login required:** You must build a custom login page using Base44's framework. The prebuilt Base44 login UI does not support custom deeplink-based native OAuth integrations (Despia secure browser + `oauth/` deeplink handoff). Use `<Base44OAuthButton>` or `useBase44OAuth` in your own login page.
+
+## Install
+
+```bash
+npm install despia-base44-oauth despia-native @base44/sdk
+```
+
+```bash
+# Or with pnpm
+pnpm add despia-base44-oauth despia-native @base44/sdk
+
+# Or with yarn
+yarn add despia-base44-oauth despia-native @base44/sdk
+```
+
+## Despia OAuth URL Protocols
+
+This package uses Despia's two OAuth protocols:
+
+| Protocol | Purpose |
+|----------|---------|
+| `oauth://?url={url}` | **Opens** secure browser (ASWebAuth / Chrome Custom Tabs) |
+| `{scheme}://oauth/{path}?params` | **Closes** browser, returns to WebView. The `oauth/` segment is **required** – without it the browser stays open. |
+
+Deeplink examples:
+- `myapp://oauth/auth?access_token=xxx` ✓ Browser closes, app receives `/auth?access_token=xxx`
+- `myapp://auth?access_token=xxx` ✗ Browser stays open (user stuck)
+
+## Setup
+
+### 1. Base44OAuthProvider
+
+Wrap your app with `Base44OAuthProvider` and pass your Base44 client. The client must expose `auth.loginWithProvider(provider, fromUrl?)` and `auth.setToken(token, saveToStorage?)`.
+
+**Inside Base44-generated apps** (client is pre-configured):
+
+```tsx
+import { Base44OAuthProvider, OAuthRoutes } from 'despia-base44-oauth';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+import { base44 } from '@/api/base44Client';
+
+function App() {
+  return (
+    <Base44OAuthProvider base44={base44}>
+      <BrowserRouter>
+        <Routes>
+          <Route path="/" element={<Home />} />
+          <Route path="/login" element={<Login />} />
+          <Route path="/*" element={<OAuthRoutes deeplink="myapp" />} />
+        </Routes>
+      </BrowserRouter>
+    </Base44OAuthProvider>
+  );
+}
+```
+
+**External apps** (create client yourself):
+
+```tsx
+import { Base44OAuthProvider, OAuthRoutes } from 'despia-base44-oauth';
+import { createClient } from '@base44/sdk';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+
+const base44 = createClient({ appId: 'your-app-id' });
+
+function App() {
+  return (
+    <Base44OAuthProvider base44={base44}>
+      <BrowserRouter>
+        <Routes>
+          <Route path="/" element={<Home />} />
+          <Route path="/login" element={<Login />} />
+          <Route path="/*" element={<OAuthRoutes deeplink="myapp" />} />
+        </Routes>
+      </BrowserRouter>
+    </Base44OAuthProvider>
+  );
+}
+```
+
+### 2. Custom login page
+
+Create a custom login page and use `<Base44OAuthButton>` or `useBase44OAuth` for OAuth. The prebuilt Base44 login does not support the Despia native OAuth flow.
+
+### 3. OAuthRoutes
+
+`<OAuthRoutes deeplink="myapp" />` registers these internal routes:
+
+| Route | Where it runs | Purpose |
+|-------|---------------|---------|
+| `/__despia_oauth/start` | Secure browser (native) or web redirect | Initiates OAuth, calls Base44 `loginWithProvider` |
+| `/__despia_oauth/finish` | Secure browser only | Parses tokens, redirects to `{scheme}://oauth/auth?access_token=...` |
+| `/auth` (default) | WebView | Applies token via `base44.auth.setToken`, navigates to `next` |
+
+Optional props:
+
+```tsx
+<OAuthRoutes
+  deeplink="myapp"
+  applyPath="/auth"
+  loginPath="/login"
+/>
+```
+
+### 4. Configure Deeplink Scheme in Despia
+
+Configure your Despia project so deeplinks with the `oauth/` prefix are intercepted and the WebView is navigated to the matching path with query params. Example:
+
+- Deeplink: `myapp://oauth/auth?access_token=xxx&next=/&state=yyy`
+- Despia intercepts → closes secure browser → navigates WebView to: `https://your-app.com/auth?access_token=xxx&next=/&state=yyy`
+
+## Usage
+
+### Base44OAuthButton
+
+```tsx
+import { Base44OAuthButton } from 'despia-base44-oauth';
+
+<Base44OAuthButton
+  deeplink="myapp"
+  provider="google"
+  next="/"
+/>
+```
+
+**Props:**
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `deeplink` | string | yes | Deeplink scheme **without** `://` (e.g. `"myapp"`) |
+| `provider` | string | yes | OAuth provider: `"google"`, `"microsoft"`, or `"facebook"` (per @base44/sdk) |
+| `next` | string | no | Relative path after success (default: `"/"`) |
+| `children` | ReactNode | no | Button label (default: `"Sign in with {provider}"`) |
+
+**Behavior:**
+
+- **Despia native runtime:** Calls `despia('oauth://?url=...')` to open secure browser, then loads the start route which triggers Base44 OAuth.
+- **Web browser:** Calls `base44.auth.loginWithProvider(provider, next)` directly.
+
+### useBase44OAuth
+
+Programmatic OAuth start:
+
+```tsx
+import { useBase44OAuth } from 'despia-base44-oauth';
+
+function MyComponent() {
+  const { start, busy, error } = useBase44OAuth({ deeplink: 'myapp' });
+
+  return (
+    <button
+      disabled={busy}
+      onClick={() => start({ provider: 'google', next: '/dashboard' })}
+    >
+      {busy ? 'Starting…' : 'Sign in with Google'}
+    </button>
+  );
+}
+```
+
+## Deeplink Format
+
+- Pass the scheme **without** `://`: `"myapp"`, not `"myapp://"`.
+- Valid scheme pattern: `/^[a-zA-Z][a-zA-Z0-9+.-]*$/`.
+- Invalid values (e.g. containing `://`) throw a clear error in development.
+
+## Platform Detection
+
+Detect Despia runtime and platform via user agent:
+
+```tsx
+import { isDespiaNative, isDespiaIOS, isDespiaAndroid } from 'despia-base44-oauth';
+
+if (isDespiaNative()) {
+  // Running in Despia native runtime
+  if (isDespiaIOS()) {
+    // iOS – e.g. Apple JS SDK for Sign in with Apple (no browser needed)
+  } else if (isDespiaAndroid()) {
+    // Android
+  }
+}
+```
+
+- `isDespiaNative()`: `navigator.userAgent` includes `"despia"` (case-insensitive).
+- `isDespiaIOS()`: Despia + `"iphone"` or `"ipad"` in user agent.
+- `isDespiaAndroid()`: Despia + `"android"` in user agent.
+
+## Security
+
+- **State:** Random `state` for replay protection, stored in `sessionStorage`.
+- **next:** Only relative paths starting with `/` allowed; absolute URLs and schemes rejected.
+- **Token parsing:** Supports query (`?access_token=...`) and hash (`#access_token=...`).
+- **Flow TTL:** One active flow at a time; expires after 2 minutes; cleared on success or error.
+
+## Integration with Despia SDK
+
+This package relies on `despia-native` for the OAuth transport. When running in the Despia native runtime, it uses:
+
+```javascript
+despia(`oauth://?url=${encodeURIComponent(oauthUrl)}`);
+```
+
+Per Despia docs: always use the real SDK (`import despia from 'despia-native'`). Mock implementations will not work on actual devices. The SDK provides command queuing, variable watching, and type safety for TypeScript, React, and other frameworks.
+
+## Exports (Stable for AI)
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `OAuthRoutes` | Component | Registers `/__despia_oauth/start`, `/__despia_oauth/finish`, `/auth` |
+| `Base44OAuthButton` | Component | OAuth button; native → secure browser, web → Base44 redirect |
+| `useBase44OAuth` | Hook | `{ start, busy, error }` for programmatic OAuth |
+| `Base44OAuthProvider` | Component | Provides Base44 client via context; expects `base44.auth` |
+| `Base44Auth`, `Base44Client` | Type | Types for the auth interface used by this package |
+| `isDespiaNative` | Function | `true` if userAgent includes `"despia"` |
+| `isDespiaIOS` | Function | `true` if Despia + iPhone/iPad |
+| `isDespiaAndroid` | Function | `true` if Despia + Android |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,89 @@
+import React from 'react';
+
+interface OAuthRoutesProps {
+    /** Deeplink scheme WITHOUT "://" (e.g. "myapp", "coolapp") */
+    deeplink: string;
+    /** Path for the apply route (default: "/auth") */
+    applyPath?: string;
+    /** Path for "Try again" fallback (default: "/login") */
+    loginPath?: string;
+}
+/**
+ * Provides internal OAuth routes:
+ * - /__despia_oauth/start
+ * - /__despia_oauth/finish
+ * - /auth (or applyPath)
+ */
+declare function OAuthRoutes({ deeplink, applyPath, loginPath, }: OAuthRoutesProps): React.ReactElement;
+
+interface Base44OAuthButtonProps {
+    /** Deeplink scheme WITHOUT "://" */
+    deeplink: string;
+    /** OAuth provider (e.g. "google", "github") */
+    provider: string;
+    /** Relative path to navigate after success (default: "/") */
+    next?: string;
+    /** Optional children; default: "Sign in with {provider}" */
+    children?: React.ReactNode;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Additional props passed to the button */
+    [key: string]: unknown;
+}
+/**
+ * OAuth button: in Despia native, opens secure session; in web, uses Base44 redirect.
+ */
+declare function Base44OAuthButton({ deeplink, provider, next, children, disabled, ...rest }: Base44OAuthButtonProps): React.ReactElement;
+
+interface UseBase44OAuthOptions {
+    /** Deeplink scheme WITHOUT "://" */
+    deeplink: string;
+    /** Path for the apply route (default: "/auth") - informational, routes use OAuthRoutes config */
+    applyPath?: string;
+}
+interface UseBase44OAuthReturn {
+    start: (args: {
+        provider: string;
+        next?: string;
+    }) => Promise<void>;
+    busy: boolean;
+    error: Error | null;
+}
+/**
+ * Hook for programmatic OAuth start. Same behavior as Base44OAuthButton.
+ */
+declare function useBase44OAuth({ deeplink }: UseBase44OAuthOptions): UseBase44OAuthReturn;
+
+/**
+ * Compatible with @base44/sdk auth module:
+ * - loginWithProvider(provider, fromUrl?) - redirects to OAuth provider
+ * - setToken(token, saveToStorage?) - sets JWT for API requests
+ */
+interface Base44Auth {
+    loginWithProvider: (provider: string, fromUrl?: string) => void | Promise<void>;
+    setToken: (token: string, saveToStorage?: boolean) => void | Promise<void>;
+}
+interface Base44Client {
+    auth: Base44Auth;
+}
+declare function Base44OAuthProvider({ base44, children, }: {
+    base44: Base44Client;
+    children: React.ReactNode;
+}): React.ReactElement;
+declare function useBase44Auth(): Base44Auth;
+
+/**
+ * Returns true if the app is running inside the Despia native wrapper.
+ * Detection is based on userAgent including "despia" (case-insensitive).
+ */
+declare function isDespiaNative(): boolean;
+/**
+ * Returns true if running in Despia on iOS (iPhone or iPad).
+ */
+declare function isDespiaIOS(): boolean;
+/**
+ * Returns true if running in Despia on Android.
+ */
+declare function isDespiaAndroid(): boolean;
+
+export { type Base44Auth, type Base44Client, Base44OAuthButton, type Base44OAuthButtonProps, Base44OAuthProvider, OAuthRoutes, type OAuthRoutesProps, type UseBase44OAuthOptions, type UseBase44OAuthReturn, isDespiaAndroid, isDespiaIOS, isDespiaNative, useBase44Auth, useBase44OAuth };

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+import React from 'react';
+
+interface OAuthRoutesProps {
+    /** Deeplink scheme WITHOUT "://" (e.g. "myapp", "coolapp") */
+    deeplink: string;
+    /** Path for the apply route (default: "/auth") */
+    applyPath?: string;
+    /** Path for "Try again" fallback (default: "/login") */
+    loginPath?: string;
+}
+/**
+ * Provides internal OAuth routes:
+ * - /__despia_oauth/start
+ * - /__despia_oauth/finish
+ * - /auth (or applyPath)
+ */
+declare function OAuthRoutes({ deeplink, applyPath, loginPath, }: OAuthRoutesProps): React.ReactElement;
+
+interface Base44OAuthButtonProps {
+    /** Deeplink scheme WITHOUT "://" */
+    deeplink: string;
+    /** OAuth provider (e.g. "google", "github") */
+    provider: string;
+    /** Relative path to navigate after success (default: "/") */
+    next?: string;
+    /** Optional children; default: "Sign in with {provider}" */
+    children?: React.ReactNode;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Additional props passed to the button */
+    [key: string]: unknown;
+}
+/**
+ * OAuth button: in Despia native, opens secure session; in web, uses Base44 redirect.
+ */
+declare function Base44OAuthButton({ deeplink, provider, next, children, disabled, ...rest }: Base44OAuthButtonProps): React.ReactElement;
+
+interface UseBase44OAuthOptions {
+    /** Deeplink scheme WITHOUT "://" */
+    deeplink: string;
+    /** Path for the apply route (default: "/auth") - informational, routes use OAuthRoutes config */
+    applyPath?: string;
+}
+interface UseBase44OAuthReturn {
+    start: (args: {
+        provider: string;
+        next?: string;
+    }) => Promise<void>;
+    busy: boolean;
+    error: Error | null;
+}
+/**
+ * Hook for programmatic OAuth start. Same behavior as Base44OAuthButton.
+ */
+declare function useBase44OAuth({ deeplink }: UseBase44OAuthOptions): UseBase44OAuthReturn;
+
+/**
+ * Compatible with @base44/sdk auth module:
+ * - loginWithProvider(provider, fromUrl?) - redirects to OAuth provider
+ * - setToken(token, saveToStorage?) - sets JWT for API requests
+ */
+interface Base44Auth {
+    loginWithProvider: (provider: string, fromUrl?: string) => void | Promise<void>;
+    setToken: (token: string, saveToStorage?: boolean) => void | Promise<void>;
+}
+interface Base44Client {
+    auth: Base44Auth;
+}
+declare function Base44OAuthProvider({ base44, children, }: {
+    base44: Base44Client;
+    children: React.ReactNode;
+}): React.ReactElement;
+declare function useBase44Auth(): Base44Auth;
+
+/**
+ * Returns true if the app is running inside the Despia native wrapper.
+ * Detection is based on userAgent including "despia" (case-insensitive).
+ */
+declare function isDespiaNative(): boolean;
+/**
+ * Returns true if running in Despia on iOS (iPhone or iPad).
+ */
+declare function isDespiaIOS(): boolean;
+/**
+ * Returns true if running in Despia on Android.
+ */
+declare function isDespiaAndroid(): boolean;
+
+export { type Base44Auth, type Base44Client, Base44OAuthButton, type Base44OAuthButtonProps, Base44OAuthProvider, OAuthRoutes, type OAuthRoutesProps, type UseBase44OAuthOptions, type UseBase44OAuthReturn, isDespiaAndroid, isDespiaIOS, isDespiaNative, useBase44Auth, useBase44OAuth };