@synqauth/react-native 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aerosol
+
+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

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# @synqauth/react-native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Synq for React Native: sign-in through the system browser, with tokens in the device's secure storage.
+
+Synq is customer identity for businesses: an OpenID Connect issuer for each of your brands, with Solana wallet, social, email and passkey sign-in. The documentation is at [docs.synq.build](https://docs.synq.build).
+
+This package is at 0.x and hasn't been published yet: its API can change in any release until Synq's first customer depends on it.
+
+## Usage
+
+Register a native app with a redirect URI your app owns: an https link it claims (an iOS universal link, an Android App Link), or a scheme of its own, a reverse domain name such as `com.example.app:/callback`. Then:
+
+```tsx
+import 'react-native-quick-crypto' // a WebCrypto polyfill: Hermes has none
+import * as SecureStore from 'expo-secure-store'
+import * as WebBrowser from 'expo-web-browser'
+import { SynqNativeProvider, createSynqNative, useAuth, useSession } from '@synqauth/react-native'
+
+const issuer = 'https://acme.auth.synq.build'
+const synq = createSynqNative({
+  issuer,
+  clientId: 'app_…',
+  redirectUri: 'https://app.example.com/synq/callback',
+  webBrowser: WebBrowser,
+  secureStore: SecureStore,
+})
+
+// <SynqNativeProvider synq={synq} issuer={issuer}> around the app, then:
+const { isSignedIn } = useSession()
+const { signIn, signOut } = useAuth()
+```
+
+Sign-in opens the system browser (ASWebAuthenticationSession on iOS, Custom Tabs on Android), never an embedded web view. The session, refresh token included, stays in the device's secure storage.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+import { AccountClient, AuthorizationUrlOptions, IdTokenClaims, Session, SynqClient, SynqError, SynqStorage } from "@synqauth/js";
+import { ReactNode } from "react";
+//#region src/storage.d.ts
+/** The part of `expo-secure-store` the SDK uses: pass the module itself. */
+interface SecureStoreModule {
+  getItemAsync(key: string): Promise<string | null>;
+  setItemAsync(key: string, value: string): Promise<void>;
+  deleteItemAsync(key: string): Promise<void>;
+}
+/**
+ * The most one item holds: iOS's keychain takes more, but `expo-secure-store`
+ * warns past 2048 bytes, and a session's tokens are bigger than that.
+ */
+export declare const CHUNK_SIZE = 1800;
+/**
+ * The device's secure storage (the iOS keychain, Android's keystore) as a
+ * `SynqStorage`, through `expo-secure-store`: the session's tokens, the
+ * refresh token included, and a sign-in's transaction. A value too big for
+ * one item is split across several (`<key>.0`, `<key>.1`...), with the count
+ * under the key itself. One app is one process, so the lock is in memory.
+ */
+export declare function secureStorage(store: SecureStoreModule): SynqStorage;
+//#endregion
+//#region src/client.d.ts
+/** The part of `expo-web-browser` the SDK uses: pass the module itself. */
+interface WebBrowserModule {
+  openAuthSessionAsync(url: string, redirectUrl: string): Promise<{
+    type: 'success';
+    url: string;
+  } | {
+    type: string;
+  }>;
+}
+/** What `createSynqNative` takes: the app at the brand, and the two Expo modules it runs on. */
+interface SynqNativeOptions {
+  /** The brand's issuer URL. */
+  issuer: string;
+  /** The app's client id: a native app, registered with the redirect URI below. */
+  clientId: string;
+  /**
+   * Where Synq sends the browser back to, one of the app's registered
+   * redirect URIs: an https link the app claims (a universal link, an App
+   * Link) or a scheme of its own, a reverse domain name such as
+   * `com.example.app:/callback` (RFC 8252). Never plain http.
+   */
+  redirectUri: string;
+  /** Where the browser lands after signing out: one of the app's registered post-logout URIs. */
+  postLogoutRedirectUri?: string;
+  /** The scopes: `openid offline_access` by default, so the session lasts past its first access token. */
+  scope?: string;
+  /** The API the access token is for: a registered API's identifier. */
+  resource?: string;
+  /** `expo-web-browser`, which opens the system browser (ASWebAuthenticationSession, Custom Tabs). */
+  webBrowser: WebBrowserModule;
+  /** `expo-secure-store`, where the session and the refresh token are kept. */
+  secureStore: SecureStoreModule;
+  /** The `fetch` to call Synq with: the global one by default, `expo/fetch`'s included. */
+  fetch?: typeof fetch;
+}
+/**
+ * Synq in a React Native app: `@synqauth/js`'s client, signing in through
+ * the system browser (never an embedded web view, which can read what the
+ * person types) with PKCE and a callback on a link or scheme the app owns,
+ * and keeping the session in the device's secure storage.
+ */
+interface SynqNative {
+  /** The underlying `@synqauth/js` client: tokens, refresh, events. */
+  readonly client: SynqClient;
+  /** The API the session's access token is for, as given. */
+  readonly resource: string | undefined;
+  /**
+   * Opens the brand's sign-in in the system browser and finishes it when the
+   * app's link comes back. Rejects with `cancelled` when the person closes it.
+   */
+  signIn(options?: AuthorizationUrlOptions): Promise<Session>;
+  /**
+   * Ends the session on the device and at Synq. With `browser`, also signs
+   * the person out of the brand's session in the system browser, which asks
+   * them first; without it, the browser's session at Synq stays.
+   */
+  signOut(options?: {
+    browser?: boolean;
+  }): Promise<void>;
+}
+/** Synq for a React Native app: the system browser for sign-in, the device's secure storage for the session. */
+export declare function createSynqNative(options: SynqNativeOptions): SynqNative;
+//#endregion
+//#region src/provider.d.ts
+/** A call's outcome: its data, or the `SynqError` it failed with. */
+type SynqResult<T> = {
+  readonly data: T;
+  readonly error: null;
+} | {
+  readonly data: null;
+  readonly error: SynqError;
+};
+/** What `SynqNativeProvider` takes. */
+interface SynqNativeProviderProps {
+  /** The client `createSynqNative` made, once, outside any component. */
+  synq: SynqNative;
+  /** The brand's issuer, as given to `createSynqNative`: for the account API. */
+  issuer: string;
+  children?: ReactNode;
+}
+/**
+ * Gives the hooks the device's session: it reads it once from secure
+ * storage, then follows every sign-in, refresh and sign-out.
+ */
+export declare function SynqNativeProvider({ synq, issuer, children }: SynqNativeProviderProps): import("react").JSX.Element;
+/** What `useSession()` answers: whether the device's session is read yet, and who is signed in. */
+interface UseSession {
+  readonly isLoaded: boolean;
+  readonly isSignedIn: boolean;
+  readonly session: Session | null;
+}
+/** The device's session. */
+export declare function useSession(): UseSession;
+/** What `useUser()` answers: the ID token's claims, and the brand's account API for the person. */
+interface UseUser {
+  readonly isLoaded: boolean;
+  /** Who signed in, from the ID token; null when nobody is. */
+  readonly user: IdTokenClaims | null;
+  /**
+   * The brand's account API with the session's token, when the session's
+   * token is for it (`createSynqNative({ resource: accountApiUrl(issuer) })`).
+   */
+  readonly account: AccountClient | null;
+}
+/** Who is signed in, and their account. */
+export declare function useUser(): UseUser;
+/** What `useAuth()` answers: signing in and out, each answering `{ data, error }`. */
+interface UseAuth {
+  readonly isLoaded: boolean;
+  readonly isSignedIn: boolean;
+  /** Opens the brand's sign-in in the system browser. A closed browser is the error `cancelled`. */
+  signIn(options?: AuthorizationUrlOptions): Promise<SynqResult<Session>>;
+  /** Ends the session; with `browser`, at the brand in the system browser too. */
+  signOut(options?: {
+    browser?: boolean;
+  }): Promise<SynqResult<null>>;
+}
+/** Signing in and out. */
+export declare function useAuth(): UseAuth;
+//#endregion
+export type { SecureStoreModule, SynqNative, SynqNativeOptions, SynqNativeProviderProps, SynqResult, UseAuth, UseSession, UseUser, WebBrowserModule };

package/dist/index.js

@@ -0,0 +1,256 @@
+import { SynqError, accountApiUrl, createAccountClient, createSynqClient, isSynqError } from "@synqauth/js";
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/storage.ts
+/**
+* The most one item holds: iOS's keychain takes more, but `expo-secure-store`
+* warns past 2048 bytes, and a session's tokens are bigger than that.
+*/
+const CHUNK_SIZE = 1800;
+/** A secure-store key: the store takes letters, digits, `.`, `-` and `_` only. */
+function safeKey(key) {
+	return key.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+/**
+* The device's secure storage (the iOS keychain, Android's keystore) as a
+* `SynqStorage`, through `expo-secure-store`: the session's tokens, the
+* refresh token included, and a sign-in's transaction. A value too big for
+* one item is split across several (`<key>.0`, `<key>.1`...), with the count
+* under the key itself. One app is one process, so the lock is in memory.
+*/
+function secureStorage(store) {
+	const locks = /* @__PURE__ */ new Map();
+	async function remove(key) {
+		const base = safeKey(key);
+		const head = await store.getItemAsync(base);
+		const count = head?.startsWith("chunks:") ? Number(head.slice(7)) : 0;
+		for (let i = 0; i < count; i++) await store.deleteItemAsync(`${base}.${i}`);
+		await store.deleteItemAsync(base);
+	}
+	return {
+		holdsRefreshTokens: true,
+		async get(key) {
+			const base = safeKey(key);
+			const head = await store.getItemAsync(base);
+			if (head === null || !head.startsWith("chunks:")) return head?.slice(6) ?? null;
+			const count = Number(head.slice(7));
+			const parts = [];
+			for (let i = 0; i < count; i++) {
+				const part = await store.getItemAsync(`${base}.${i}`);
+				if (part === null) return null;
+				parts.push(part);
+			}
+			return parts.join("");
+		},
+		async set(key, value) {
+			await remove(key);
+			const base = safeKey(key);
+			if (value.length <= 1800) {
+				await store.setItemAsync(base, `value:${value}`);
+				return;
+			}
+			const count = Math.ceil(value.length / CHUNK_SIZE);
+			for (let i = 0; i < count; i++) await store.setItemAsync(`${base}.${i}`, value.slice(i * CHUNK_SIZE, (i + 1) * CHUNK_SIZE));
+			await store.setItemAsync(base, `chunks:${count}`);
+		},
+		remove,
+		lock(name, fn) {
+			const run = (locks.get(name) ?? Promise.resolve()).then(fn, fn);
+			const settled = run.then(() => void 0, () => void 0);
+			locks.set(name, settled);
+			settled.then(() => {
+				if (locks.get(name) === settled) locks.delete(name);
+			});
+			return run;
+		}
+	};
+}
+//#endregion
+//#region src/client.ts
+/** A WebCrypto the SDK needs for PKCE: Hermes has none, so the app installs one first. */
+function assertWebCrypto() {
+	const crypto = globalThis.crypto;
+	if (typeof crypto?.subtle?.digest !== "function" || typeof crypto.getRandomValues !== "function") throw new SynqError("invalid_options", "@synqauth/react-native needs WebCrypto (crypto.subtle and getRandomValues): install a polyfill such as react-native-quick-crypto's install() before creating the client");
+}
+/**
+* `fetch`, answering the global `Response`. Expo (SDK 52 on) replaces the
+* global `fetch` with `expo/fetch`, whose responses are its own class: not
+* React Native's `Response`, which has no `Symbol.toStringTag` either, so
+* oauth4webapi refuses every one ("must be an instance of Response"). Such
+* a response is read whole and handed on as a `Response`; Synq's answers
+* are small JSON.
+*/
+function standardResponses(fetcher) {
+	return async (input, init) => {
+		const response = await fetcher(input, init);
+		if (response instanceof Response) return response;
+		const status = response.status;
+		return new Response(status === 204 || status === 205 || status === 304 ? null : await response.arrayBuffer(), {
+			status,
+			statusText: response.statusText,
+			headers: response.headers
+		});
+	};
+}
+/** Synq for a React Native app: the system browser for sign-in, the device's secure storage for the session. */
+function createSynqNative(options) {
+	assertWebCrypto();
+	if (/^http:/i.test(options.redirectUri)) throw new SynqError("invalid_options", "A mobile app's redirect URI is an https link it claims (a universal link or App Link) or a scheme of its own, not http");
+	const storage = secureStorage(options.secureStore);
+	const client = createSynqClient({
+		issuer: options.issuer,
+		clientId: options.clientId,
+		redirectUri: options.redirectUri,
+		postLogoutRedirectUri: options.postLogoutRedirectUri,
+		scope: options.scope ?? "openid offline_access",
+		resource: options.resource,
+		storage,
+		transactionStorage: storage,
+		fetch: standardResponses(options.fetch ?? ((input, init) => globalThis.fetch(input, init)))
+	});
+	return {
+		client,
+		resource: options.resource,
+		async signIn(signInOptions) {
+			const url = await client.authorizationUrl(signInOptions);
+			const result = await options.webBrowser.openAuthSessionAsync(url.href, options.redirectUri);
+			if (result.type !== "success" || !("url" in result)) throw new SynqError("cancelled", "The person closed the sign-in");
+			return client.handleCallback(result.url);
+		},
+		async signOut({ browser = false } = {}) {
+			const url = await client.signOut();
+			if (browser && url && options.postLogoutRedirectUri) await options.webBrowser.openAuthSessionAsync(url.href, options.postLogoutRedirectUri);
+		}
+	};
+}
+//#endregion
+//#region src/provider.tsx
+const SynqContext = createContext(null);
+/**
+* Gives the hooks the device's session: it reads it once from secure
+* storage, then follows every sign-in, refresh and sign-out.
+*/
+function SynqNativeProvider({ synq, issuer, children }) {
+	const [state, setState] = useState({
+		status: "loading",
+		session: null
+	});
+	useEffect(() => {
+		let live = true;
+		const unsubscribe = synq.client.subscribe((event) => {
+			if (!live) return;
+			setState(event.session ? {
+				status: "signed-in",
+				session: event.session
+			} : {
+				status: "signed-out",
+				session: null
+			});
+		});
+		synq.client.getSession().then((session) => {
+			if (!live) return;
+			setState((current) => current.status !== "loading" ? current : session ? {
+				status: "signed-in",
+				session
+			} : {
+				status: "signed-out",
+				session: null
+			});
+		}, () => {
+			if (live) setState({
+				status: "signed-out",
+				session: null
+			});
+		});
+		return () => {
+			live = false;
+			unsubscribe();
+		};
+	}, [synq]);
+	const value = useMemo(() => ({
+		synq,
+		state,
+		issuer
+	}), [
+		synq,
+		state,
+		issuer
+	]);
+	return /* @__PURE__ */ jsx(SynqContext.Provider, {
+		value,
+		children
+	});
+}
+function useSynq() {
+	const context = useContext(SynqContext);
+	if (!context) throw new Error("Synq hooks need a <SynqNativeProvider> above them");
+	return context;
+}
+/** The device's session. */
+function useSession() {
+	const { state } = useSynq();
+	return {
+		isLoaded: state.status !== "loading",
+		isSignedIn: state.status === "signed-in",
+		session: state.session
+	};
+}
+/** Who is signed in, and their account. */
+function useUser() {
+	const { synq, state, issuer } = useSynq();
+	const account = useMemo(() => state.session && synq.resource === accountApiUrl(issuer) ? createAccountClient({
+		issuer,
+		accessToken: () => synq.client.getAccessToken()
+	}) : null, [
+		synq,
+		state.session,
+		issuer
+	]);
+	return {
+		isLoaded: state.status !== "loading",
+		user: state.session?.claims ?? null,
+		account
+	};
+}
+/** Signing in and out. */
+function useAuth() {
+	const { synq, state } = useSynq();
+	const signIn = useCallback(async (options) => {
+		try {
+			return {
+				data: await synq.signIn(options),
+				error: null
+			};
+		} catch (error) {
+			return {
+				data: null,
+				error: asSynqError(error)
+			};
+		}
+	}, [synq]);
+	const signOut = useCallback(async (options) => {
+		try {
+			await synq.signOut(options);
+			return {
+				data: null,
+				error: null
+			};
+		} catch (error) {
+			return {
+				data: null,
+				error: asSynqError(error)
+			};
+		}
+	}, [synq]);
+	return {
+		isLoaded: state.status !== "loading",
+		isSignedIn: state.status === "signed-in",
+		signIn,
+		signOut
+	};
+}
+function asSynqError(error) {
+	return isSynqError(error) ? error : new SynqError("network_error", String(error), { cause: error });
+}
+//#endregion
+export { CHUNK_SIZE, SynqNativeProvider, createSynqNative, secureStorage, useAuth, useSession, useUser };

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@synqauth/react-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "description": "Synq for React Native: sign-in through the system browser, with tokens in the device's secure storage.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aerosol-build/synq.git",
+    "directory": "packages/react-native"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@synqauth/js": "0.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "10.4.2",
+    "@testing-library/react": "16.3.3",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@vitest/coverage-v8": "5.0.2",
+    "jsdom": "30.1.1",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "vitest": "5.0.2"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "typecheck": "tsc",
+    "test": "vitest run --coverage"
+  }
 }