authkit-react-native 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 Joshua Baker
+
+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,131 @@
+# AuthKit for React Native
+
+WorkOS AuthKit integration for React Native. Handles the full OAuth 2.0 PKCE flow, token storage, automatic session restoration, and token refresh — built on Zustand and Expo modules.
+
+For server-side auth proxy examples (Hono, Next.js), see the [`examples/`](examples/) directory.
+
+## Installation
+
+```bash
+npx expo install authkit-react-native zustand expo-auth-session expo-secure-store expo-web-browser @react-native-async-storage/async-storage
+```
+
+## Client Usage
+
+### Create the hook
+
+Create a `useAuth` hook that your app imports everywhere. The store is created at module scope so the session begins restoring immediately on app launch.
+
+```typescript
+// hooks/useAuth.ts
+import { createAuthStore } from "authkit-react-native";
+import { useStore } from "zustand";
+
+const authStore = createAuthStore({
+  authorizationEndpoint: `${process.env.EXPO_PUBLIC_API_URL}/v1/auth/authorize`,
+  tokenEndpoint: `${process.env.EXPO_PUBLIC_API_URL}/v1/auth/token`,
+  revocationEndpoint: `${process.env.EXPO_PUBLIC_API_URL}/v1/auth/revoke`,
+});
+
+export function useAuth() {
+  return useStore(authStore);
+}
+```
+
+### Protected routes
+
+Because the store lives outside React, there's no provider to wrap your app in. Just call `useAuth()` in a layout to gate routes while the session is loading:
+
+```tsx
+// app/(auth)/_layout.tsx
+import { useAuth } from "@/hooks/useAuth";
+import { Redirect, Stack } from "expo-router";
+
+export default function AuthLayout() {
+  const { user, isLoading } = useAuth();
+
+  if (isLoading) return <Loading />;
+  if (!user) return <Redirect href="/sign-in" />;
+
+  return <Stack />;
+}
+```
+
+### Sign in
+
+Call `signIn()` to open the WorkOS AuthKit sign-in page. Returns `true` on success, `false` if the user cancelled.
+
+```tsx
+import { useAuth } from "@/hooks/useAuth";
+
+function SignInScreen() {
+  const { signIn } = useAuth();
+
+  return (
+    <>
+      <Button title="Sign in" onPress={() => signIn()} />
+      <Button
+        title="Sign up"
+        onPress={() => signIn({ screenHint: "sign-up" })}
+      />
+    </>
+  );
+}
+```
+
+### Sign out
+
+`signOut()` revokes the token and clears storage. It does not show any confirmation UI — add that in your app:
+
+```tsx
+import { useAuth } from "@/hooks/useAuth";
+import { Alert } from "react-native";
+
+function SignOutButton() {
+  const { user, signOut } = useAuth();
+
+  const handleSignOut = () => {
+    Alert.alert(
+      user?.email
+        ? `Are you sure you want to sign out as ${user.email}?`
+        : "Are you sure you want to sign out?",
+      undefined,
+      [
+        { text: "Cancel", style: "cancel" },
+        { text: "Sign out", style: "destructive", onPress: () => signOut() },
+      ],
+    );
+  };
+
+  return <Button title="Sign out" onPress={handleSignOut} />;
+}
+```
+
+## Bare React Native (without Expo)
+
+This package is built around Expo modules but works in any React Native app. Expo packages can be used in bare React Native projects by adding the Expo modules runtime:
+
+1. Install the `expo` package:
+   ```bash
+   npm install expo
+   npx install-expo-modules
+   ```
+2. Install the peer dependencies using `npx expo install` (handles native linking):
+   ```bash
+   npx expo install expo-auth-session expo-secure-store expo-web-browser @react-native-async-storage/async-storage zustand
+   ```
+3. Ensure your app's URL scheme is configured for the OAuth redirect. In `app.json` or your native project's `Info.plist` / `AndroidManifest.xml`, register a deep link scheme (e.g., `myapp://`).
+
+After that, usage is identical to the examples above.
+
+## Configuration
+
+| Option                  | Required | Default             | Description                                                               |
+| ----------------------- | -------- | ------------------- | ------------------------------------------------------------------------- |
+| `authorizationEndpoint` | \*       | WorkOS default      | OAuth authorize URL. Required unless `clientId` is provided.              |
+| `clientId`              | \*       | —                   | WorkOS client ID. Required when using the default authorization endpoint. |
+| `tokenEndpoint`         | Yes      | —                   | Token exchange URL.                                                       |
+| `revocationEndpoint`    | Yes      | —                   | Token revocation URL.                                                     |
+| `redirectUri`           | No       | `makeRedirectUri()` | OAuth redirect URI.                                                       |
+| `storageKeyPrefix`      | No       | `"workos"`          | Prefix for SecureStore/AsyncStorage keys.                                 |
+| `devMode`               | No       | `false`             | Logs errors to the console when enabled.                                  |

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import * as zustand from 'zustand';
+
+type ClientIdOrAuthorizationEndpoint = {
+    clientId?: string;
+    authorizationEndpoint: string;
+} | {
+    clientId: string;
+    authorizationEndpoint?: string;
+};
+type AuthConfig = ClientIdOrAuthorizationEndpoint & {
+    tokenEndpoint: string;
+    revocationEndpoint: string;
+    redirectUri?: string;
+    storageKeyPrefix?: string;
+    devMode?: boolean;
+};
+type User = {
+    id: string;
+    email: string;
+    emailVerified: boolean;
+    profilePictureUrl: string | null;
+    firstName: string | null;
+    lastName: string | null;
+    lastSignInAt: string | null;
+    locale: string | null;
+    createdAt: string;
+    updatedAt: string;
+    externalId: string | null;
+    metadata: Record<string, string>;
+};
+type Impersonator = {
+    email: string;
+    reason: string | null;
+};
+type AuthenticationMethod = "SSO" | "Password" | "Passkey" | "AppleOAuth" | "BitbucketOAuth" | "GitHubOAuth" | "GitLabOAuth" | "GoogleOAuth" | "LinkedInOAuth" | "MicrosoftOAuth" | "SalesforceOAuth" | "VercelOAuth" | "MagicAuth" | "CrossAppAuth" | "Impersonation";
+type AuthSessionInfo = {
+    user: User;
+    organizationId?: string;
+    impersonator?: Impersonator;
+    authenticationMethod?: AuthenticationMethod;
+};
+type AuthState = {
+    isLoading: boolean;
+} & Partial<AuthSessionInfo> & {
+    signIn: (options?: {
+        screenHint?: "sign-up" | "sign-in";
+    }) => Promise<boolean>;
+    signOut: () => Promise<void>;
+    getAccessToken: (options?: {
+        forceRefresh?: boolean;
+    }) => Promise<string | null>;
+};
+
+declare function createAuthStore(config: AuthConfig): zustand.StoreApi<AuthState>;
+
+export { type AuthConfig, type AuthSessionInfo, type AuthState, type AuthenticationMethod, type Impersonator, type User, createAuthStore };

package/dist/index.js

@@ -0,0 +1,184 @@
+// src/store.ts
+import {
+  AccessTokenRequest,
+  AuthRequest,
+  makeRedirectUri,
+  RefreshTokenRequest,
+  RevokeTokenRequest,
+  TokenResponse
+} from "expo-auth-session";
+import * as WebBrowser from "expo-web-browser";
+import { createStore } from "zustand";
+
+// src/storage.ts
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import * as SecureStore from "expo-secure-store";
+function createStorage(prefix) {
+  const tokensKey = `${prefix}.tokens`;
+  const metaKey = `${prefix}.meta`;
+  return {
+    async readTokens() {
+      return SecureStore.getItemAsync(tokensKey);
+    },
+    async writeTokens(value) {
+      await SecureStore.setItemAsync(tokensKey, value);
+    },
+    async readMeta() {
+      return AsyncStorage.getItem(metaKey);
+    },
+    async writeMeta(value) {
+      await AsyncStorage.setItem(metaKey, value);
+    },
+    async clear() {
+      await Promise.all([
+        SecureStore.deleteItemAsync(tokensKey),
+        AsyncStorage.removeItem(metaKey)
+      ]);
+    }
+  };
+}
+
+// src/store.ts
+var defaultAuthorizationEndpoint = "https://api.workos.com/user_management/authorize";
+WebBrowser.maybeCompleteAuthSession();
+var emptySession = {
+  user: void 0,
+  organizationId: void 0,
+  impersonator: void 0,
+  authenticationMethod: void 0
+};
+function assertAuthSessionInfo(response) {
+  if (!response || typeof response !== "object" || !("user" in response)) {
+    throw new Error("Invalid authentication response");
+  }
+}
+function createAuthStore(config) {
+  const {
+    clientId = "",
+    redirectUri = makeRedirectUri(),
+    authorizationEndpoint = defaultAuthorizationEndpoint,
+    tokenEndpoint,
+    revocationEndpoint,
+    storageKeyPrefix = "workos",
+    devMode = false
+  } = config;
+  if (authorizationEndpoint === defaultAuthorizationEndpoint && !clientId) {
+    throw new Error(
+      "clientId is required when using default authorizationEndpoint"
+    );
+  }
+  const storage = createStorage(storageKeyPrefix);
+  WebBrowser.warmUpAsync();
+  async function readTokenResponse() {
+    const stored = await storage.readTokens();
+    if (!stored) return null;
+    const requestConfig = JSON.parse(stored);
+    return new TokenResponse(requestConfig);
+  }
+  async function storeTokenResponse(tokenResponse) {
+    assertAuthSessionInfo(tokenResponse.rawResponse);
+    const requestConfig = tokenResponse.getRequestConfig();
+    const { user, organizationId, impersonator, authenticationMethod } = tokenResponse.rawResponse;
+    const meta = { user, organizationId, impersonator, authenticationMethod };
+    await Promise.all([
+      storage.writeTokens(JSON.stringify(requestConfig)),
+      storage.writeMeta(JSON.stringify(meta))
+    ]);
+    return meta;
+  }
+  const store = createStore()((set) => ({
+    isLoading: true,
+    signIn: async ({ screenHint = "sign-in" } = {}) => {
+      const authSessionRequest = new AuthRequest({
+        clientId,
+        redirectUri,
+        extraParams: { provider: "authkit", screen_hint: screenHint }
+      });
+      const authSessionResult = await authSessionRequest.promptAsync({
+        authorizationEndpoint
+      });
+      if (authSessionResult.type === "error") {
+        throw new Error(
+          authSessionResult.error?.description ?? "Unknown error"
+        );
+      }
+      if (authSessionResult.type !== "success") {
+        return false;
+      }
+      if (authSessionRequest.state !== authSessionResult.params.state) {
+        throw new Error("State mismatch");
+      }
+      if (!authSessionRequest.codeVerifier) {
+        throw new Error("Code verifier missing");
+      }
+      const tokenRequest = new AccessTokenRequest({
+        code: authSessionResult.params.code,
+        clientId,
+        redirectUri,
+        extraParams: {
+          code_verifier: authSessionRequest.codeVerifier
+        }
+      });
+      const tokenResponse = await tokenRequest.performAsync({ tokenEndpoint });
+      const meta = await storeTokenResponse(tokenResponse);
+      set(meta);
+      return true;
+    },
+    signOut: async () => {
+      const tokenResponse = await readTokenResponse();
+      if (tokenResponse?.accessToken) {
+        const revokeTokenRequest = new RevokeTokenRequest({
+          clientId,
+          token: tokenResponse.accessToken
+        });
+        await revokeTokenRequest.performAsync({ revocationEndpoint });
+      }
+      await storage.clear();
+      set(emptySession);
+    },
+    getAccessToken: async (options) => {
+      const forceRefresh = options?.forceRefresh ?? false;
+      try {
+        let tokenResponse = await readTokenResponse();
+        if (!tokenResponse) {
+          await storage.clear();
+          set(emptySession);
+          return null;
+        }
+        if (forceRefresh || tokenResponse.shouldRefresh()) {
+          const refreshTokenRequest = new RefreshTokenRequest({
+            refreshToken: tokenResponse.refreshToken,
+            clientId
+          });
+          tokenResponse = await refreshTokenRequest.performAsync({
+            tokenEndpoint
+          });
+          const meta = await storeTokenResponse(tokenResponse);
+          set(meta);
+        }
+        return tokenResponse.accessToken;
+      } catch (error) {
+        if (devMode) console.error(error);
+        await storage.clear();
+        set(emptySession);
+        return null;
+      }
+    }
+  }));
+  (async () => {
+    try {
+      const storedMeta = await storage.readMeta();
+      if (storedMeta !== null) {
+        const meta = JSON.parse(storedMeta);
+        store.setState(meta);
+      }
+      await store.getState().getAccessToken({ forceRefresh: true });
+    } finally {
+      store.setState({ isLoading: false });
+    }
+  })();
+  return store;
+}
+export {
+  createAuthStore
+};

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "authkit-react-native",
+  "version": "0.1.0",
+  "description": "WorkOS AuthKit integration for React Native — OAuth 2.0 PKCE auth with token storage, session restoration, and automatic refresh",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "publishConfig": {
+    "provenance": true
+  },
+  "simple-git-hooks": {
+    "pre-commit": "pnpm lint-staged"
+  },
+  "lint-staged": {
+    "*": "prettier --write --ignore-unknown"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joshuabaker/authkit-react-native.git"
+  },
+  "homepage": "https://github.com/joshuabaker/authkit-react-native#readme",
+  "bugs": {
+    "url": "https://github.com/joshuabaker/authkit-react-native/issues"
+  },
+  "keywords": [
+    "workos",
+    "authkit",
+    "react-native",
+    "expo",
+    "oauth",
+    "pkce",
+    "authentication",
+    "zustand"
+  ],
+  "peerDependencies": {
+    "@react-native-async-storage/async-storage": ">=2",
+    "expo-auth-session": ">=5",
+    "expo-secure-store": ">=13",
+    "expo-web-browser": ">=13",
+    "react": ">=18",
+    "zustand": ">=4"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.6.0",
+    "@changesets/cli": "^2.30.0",
+    "@react-native-async-storage/async-storage": "^2.2.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "expo-auth-session": "^55.0.7",
+    "expo-secure-store": "^55.0.8",
+    "expo-web-browser": "^55.0.9",
+    "lint-staged": "^16.1.0",
+    "prettier": "^3.8.1",
+    "react": "^19.2.0",
+    "simple-git-hooks": "^2.13.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.0",
+    "zustand": "^5.0.12"
+  },
+  "scripts": {
+    "build": "tsup",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "type-check": "tsc --noEmit",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish"
+  }
+}