@ankhorage/expo-runtime 2.3.0 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @ankhorage/expo-runtime
 
+## 2.5.0
+
+### Minor Changes
+
+- b6541d8: Add runtime readiness detection that rejects Expo Go for brokered native OAuth and requires a custom development or standalone build with the configured app scheme.
+
+## 2.4.0
+
+### Minor Changes
+
+- b2e39b8: Classify Expo authentication browser results into neutral OAuth transport responses.
+
 ## 2.3.0
 
 ### Minor Changes

package/README.md

@@ -3,7 +3,7 @@
 
 # EXPO-RUNTIME
 
-![license: MIT](././paradox/badges/license.svg) ![npm: v2.2.0](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
+![license: MIT](././paradox/badges/license.svg) ![npm: v2.4.0](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
 
 Declarative runtime integration for Expo apps: maps app capabilities to permissions, packages, config plugins, providers, and adapters
 

package/dist/oauthBrowserRuntime.d.ts

@@ -0,0 +1,4 @@
+import { type ExpoOAuthBrowserRuntimeReadiness } from './oauthBrowserRuntimeCore';
+export type { ExpoOAuthBrowserRuntimeReadiness } from './oauthBrowserRuntimeCore';
+export declare function resolveExpoOAuthBrowserRuntimeReadiness(): ExpoOAuthBrowserRuntimeReadiness;
+//# sourceMappingURL=oauthBrowserRuntime.d.ts.map

package/dist/oauthBrowserRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauthBrowserRuntime.d.ts","sourceRoot":"","sources":["../src/oauthBrowserRuntime.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,gCAAgC,EAEtC,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,gCAAgC,EAAE,MAAM,2BAA2B,CAAC;AAElF,wBAAgB,uCAAuC,IAAI,gCAAgC,CAE1F"}

package/dist/oauthBrowserRuntime.js

@@ -0,0 +1,6 @@
+import Constants from 'expo-constants';
+import { resolveExpoOAuthBrowserRuntimeReadinessFromExpoGoConfig, } from './oauthBrowserRuntimeCore';
+export function resolveExpoOAuthBrowserRuntimeReadiness() {
+    return resolveExpoOAuthBrowserRuntimeReadinessFromExpoGoConfig(Constants.expoGoConfig);
+}
+//# sourceMappingURL=oauthBrowserRuntime.js.map

package/dist/oauthBrowserRuntime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauthBrowserRuntime.js","sourceRoot":"","sources":["../src/oauthBrowserRuntime.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,gBAAgB,CAAC;AAEvC,OAAO,EAEL,uDAAuD,GACxD,MAAM,2BAA2B,CAAC;AAInC,MAAM,UAAU,uCAAuC;IACrD,OAAO,uDAAuD,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;AACzF,CAAC","sourcesContent":["import Constants from 'expo-constants';\n\nimport {\n  type ExpoOAuthBrowserRuntimeReadiness,\n  resolveExpoOAuthBrowserRuntimeReadinessFromExpoGoConfig,\n} from './oauthBrowserRuntimeCore';\n\nexport type { ExpoOAuthBrowserRuntimeReadiness } from './oauthBrowserRuntimeCore';\n\nexport function resolveExpoOAuthBrowserRuntimeReadiness(): ExpoOAuthBrowserRuntimeReadiness {\n  return resolveExpoOAuthBrowserRuntimeReadinessFromExpoGoConfig(Constants.expoGoConfig);\n}\n"]}

package/dist/oauthBrowserRuntimeCore.d.ts

@@ -0,0 +1,9 @@
+export type ExpoOAuthBrowserRuntimeReadiness = {
+    readonly status: 'ready';
+} | {
+    readonly status: 'unsupported';
+    readonly reason: 'expo-go';
+    readonly message: string;
+};
+export declare function resolveExpoOAuthBrowserRuntimeReadinessFromExpoGoConfig(expoGoConfig: unknown): ExpoOAuthBrowserRuntimeReadiness;
+//# sourceMappingURL=oauthBrowserRuntimeCore.d.ts.map

package/dist/oauthBrowserRuntimeCore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauthBrowserRuntimeCore.d.ts","sourceRoot":"","sources":["../src/oauthBrowserRuntimeCore.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gCAAgC,GACxC;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC5B;IACE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEN,wBAAgB,uDAAuD,CACrE,YAAY,EAAE,OAAO,GACpB,gCAAgC,CAWlC"}

package/dist/oauthBrowserRuntimeCore.js

@@ -0,0 +1,11 @@
+export function resolveExpoOAuthBrowserRuntimeReadinessFromExpoGoConfig(expoGoConfig) {
+    if (expoGoConfig === null) {
+        return { status: 'ready' };
+    }
+    return {
+        status: 'unsupported',
+        reason: 'expo-go',
+        message: 'Brokered OAuth requires a development or standalone build with the configured app scheme; Expo Go cannot provide a stable OAuth callback scheme.',
+    };
+}
+//# sourceMappingURL=oauthBrowserRuntimeCore.js.map

package/dist/oauthBrowserRuntimeCore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauthBrowserRuntimeCore.js","sourceRoot":"","sources":["../src/oauthBrowserRuntimeCore.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,uDAAuD,CACrE,YAAqB;IAErB,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;QAC1B,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAC7B,CAAC;IAED,OAAO;QACL,MAAM,EAAE,aAAa;QACrB,MAAM,EAAE,SAAS;QACjB,OAAO,EACL,kJAAkJ;KACrJ,CAAC;AACJ,CAAC","sourcesContent":["export type ExpoOAuthBrowserRuntimeReadiness =\n  | { readonly status: 'ready' }\n  | {\n      readonly status: 'unsupported';\n      readonly reason: 'expo-go';\n      readonly message: string;\n    };\n\nexport function resolveExpoOAuthBrowserRuntimeReadinessFromExpoGoConfig(\n  expoGoConfig: unknown,\n): ExpoOAuthBrowserRuntimeReadiness {\n  if (expoGoConfig === null) {\n    return { status: 'ready' };\n  }\n\n  return {\n    status: 'unsupported',\n    reason: 'expo-go',\n    message:\n      'Brokered OAuth requires a development or standalone build with the configured app scheme; Expo Go cannot provide a stable OAuth callback scheme.',\n  };\n}\n"]}

package/dist/oauthBrowserTransport.d.ts

@@ -0,0 +1,4 @@
+import type { AuthOAuthAuthorizationResponse } from '@ankhorage/contracts/auth';
+export declare function resolveExpoOAuthBrowserResult(result: unknown): AuthOAuthAuthorizationResponse;
+export declare function resolveExpoOAuthBrowserException(): AuthOAuthAuthorizationResponse;
+//# sourceMappingURL=oauthBrowserTransport.d.ts.map

package/dist/oauthBrowserTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauthBrowserTransport.d.ts","sourceRoot":"","sources":["../src/oauthBrowserTransport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,2BAA2B,CAAC;AAEhF,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,OAAO,GAAG,8BAA8B,CAkB7F;AAED,wBAAgB,gCAAgC,IAAI,8BAA8B,CAQjF"}

package/dist/oauthBrowserTransport.js

@@ -0,0 +1,37 @@
+export function resolveExpoOAuthBrowserResult(result) {
+    if (!isRecord(result))
+        return transportFailed('The Expo authentication browser returned no result.');
+    const type = Reflect.get(result, 'type');
+    if (type === 'success') {
+        const url = Reflect.get(result, 'url');
+        return typeof url === 'string' && url.trim().length > 0
+            ? { type: 'callback', url }
+            : transportFailed('The Expo authentication browser returned no callback URL.');
+    }
+    if (type === 'cancel') {
+        return { type: 'cancelled', reason: 'user_cancelled' };
+    }
+    if (type === 'dismiss') {
+        return { type: 'cancelled', reason: 'browser_dismissed' };
+    }
+    return transportFailed('The Expo authentication browser did not complete the OAuth redirect.');
+}
+export function resolveExpoOAuthBrowserException() {
+    return {
+        type: 'error',
+        error: {
+            code: 'browser_unavailable',
+            message: 'The Expo authentication browser could not be opened.',
+        },
+    };
+}
+function transportFailed(message) {
+    return {
+        type: 'error',
+        error: { code: 'transport_failed', message },
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=oauthBrowserTransport.js.map

package/dist/oauthBrowserTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauthBrowserTransport.js","sourceRoot":"","sources":["../src/oauthBrowserTransport.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,6BAA6B,CAAC,MAAe;IAC3D,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;QACnB,OAAO,eAAe,CAAC,qDAAqD,CAAC,CAAC;IAEhF,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACvC,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;YACrD,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE;YAC3B,CAAC,CAAC,eAAe,CAAC,2DAA2D,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IACzD,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC5D,CAAC;IACD,OAAO,eAAe,CAAC,sEAAsE,CAAC,CAAC;AACjG,CAAC;AAED,MAAM,UAAU,gCAAgC;IAC9C,OAAO;QACL,IAAI,EAAE,OAAO;QACb,KAAK,EAAE;YACL,IAAI,EAAE,qBAAqB;YAC3B,OAAO,EAAE,sDAAsD;SAChE;KACF,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,OAAe;IACtC,OAAO;QACL,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE;KAC7C,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC","sourcesContent":["import type { AuthOAuthAuthorizationResponse } from '@ankhorage/contracts/auth';\n\nexport function resolveExpoOAuthBrowserResult(result: unknown): AuthOAuthAuthorizationResponse {\n  if (!isRecord(result))\n    return transportFailed('The Expo authentication browser returned no result.');\n\n  const type = Reflect.get(result, 'type');\n  if (type === 'success') {\n    const url = Reflect.get(result, 'url');\n    return typeof url === 'string' && url.trim().length > 0\n      ? { type: 'callback', url }\n      : transportFailed('The Expo authentication browser returned no callback URL.');\n  }\n  if (type === 'cancel') {\n    return { type: 'cancelled', reason: 'user_cancelled' };\n  }\n  if (type === 'dismiss') {\n    return { type: 'cancelled', reason: 'browser_dismissed' };\n  }\n  return transportFailed('The Expo authentication browser did not complete the OAuth redirect.');\n}\n\nexport function resolveExpoOAuthBrowserException(): AuthOAuthAuthorizationResponse {\n  return {\n    type: 'error',\n    error: {\n      code: 'browser_unavailable',\n      message: 'The Expo authentication browser could not be opened.',\n    },\n  };\n}\n\nfunction transportFailed(message: string): AuthOAuthAuthorizationResponse {\n  return {\n    type: 'error',\n    error: { code: 'transport_failed', message },\n  };\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/expo-runtime",
   "type": "module",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Declarative runtime integration for Expo apps: maps app capabilities to permissions, packages, config plugins, providers, and adapters",
   "homepage": "https://github.com/ankhorage/expo-runtime#readme",
   "bugs": {
@@ -48,6 +48,20 @@
       "import": "./dist/planning.js",
       "default": "./dist/planning.js"
     },
+    "./oauth-browser": {
+      "react-native": "./src/oauthBrowserTransport.ts",
+      "browser": "./src/oauthBrowserTransport.ts",
+      "types": "./src/oauthBrowserTransport.ts",
+      "import": "./dist/oauthBrowserTransport.js",
+      "default": "./dist/oauthBrowserTransport.js"
+    },
+    "./oauth-browser-runtime": {
+      "react-native": "./src/oauthBrowserRuntime.ts",
+      "browser": "./src/oauthBrowserRuntime.ts",
+      "types": "./src/oauthBrowserRuntime.ts",
+      "import": "./dist/oauthBrowserRuntime.js",
+      "default": "./dist/oauthBrowserRuntime.js"
+    },
     "./media-picker": {
       "react-native": "./src/mediaPicker/index.ts",
       "browser": "./src/mediaPicker/index.ts",
@@ -85,6 +99,7 @@
     "@ankhorage/zora": "^2.8.7",
     "expo": "~54.0.34",
     "expo-camera": "~17.0.10",
+    "expo-constants": "~18.0.13",
     "expo-document-picker": "~14.0.8",
     "expo-file-system": "~19.0.23",
     "expo-image-picker": "~17.0.11",
@@ -92,6 +107,9 @@
     "react-native": "0.81.5"
   },
   "peerDependenciesMeta": {
+    "expo-constants": {
+      "optional": true
+    },
     "expo-document-picker": {
       "optional": true
     },
@@ -112,6 +130,7 @@
     "@types/react": "^19.2.14",
     "expo": "~54.0.34",
     "expo-camera": "~17.0.10",
+    "expo-constants": "~18.0.13",
     "expo-document-picker": "~14.0.8",
     "expo-file-system": "~19.0.23",
     "expo-image-picker": "~17.0.11",

package/src/oauthBrowserRuntime.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resolveExpoOAuthBrowserRuntimeReadinessFromExpoGoConfig } from './oauthBrowserRuntimeCore';
+
+describe('Expo OAuth browser runtime readiness', () => {
+  test('allows a custom native application build', () => {
+    expect(resolveExpoOAuthBrowserRuntimeReadinessFromExpoGoConfig(null)).toEqual({
+      status: 'ready',
+    });
+  });
+
+  test('rejects Expo Go with an actionable development-build requirement', () => {
+    expect(
+      resolveExpoOAuthBrowserRuntimeReadinessFromExpoGoConfig({ debuggerHost: '127.0.0.1:8081' }),
+    ).toEqual({
+      status: 'unsupported',
+      reason: 'expo-go',
+      message:
+        'Brokered OAuth requires a development or standalone build with the configured app scheme; Expo Go cannot provide a stable OAuth callback scheme.',
+    });
+  });
+
+  test('does not serialize Expo Go configuration into readiness output', () => {
+    const readiness = resolveExpoOAuthBrowserRuntimeReadinessFromExpoGoConfig({
+      secretLikeValue: 'do-not-echo',
+    });
+
+    expect(JSON.stringify(readiness)).not.toContain('do-not-echo');
+  });
+});

package/src/oauthBrowserRuntime.ts

@@ -0,0 +1,12 @@
+import Constants from 'expo-constants';
+
+import {
+  type ExpoOAuthBrowserRuntimeReadiness,
+  resolveExpoOAuthBrowserRuntimeReadinessFromExpoGoConfig,
+} from './oauthBrowserRuntimeCore';
+
+export type { ExpoOAuthBrowserRuntimeReadiness } from './oauthBrowserRuntimeCore';
+
+export function resolveExpoOAuthBrowserRuntimeReadiness(): ExpoOAuthBrowserRuntimeReadiness {
+  return resolveExpoOAuthBrowserRuntimeReadinessFromExpoGoConfig(Constants.expoGoConfig);
+}

package/src/oauthBrowserRuntimeCore.ts

@@ -0,0 +1,22 @@
+export type ExpoOAuthBrowserRuntimeReadiness =
+  | { readonly status: 'ready' }
+  | {
+      readonly status: 'unsupported';
+      readonly reason: 'expo-go';
+      readonly message: string;
+    };
+
+export function resolveExpoOAuthBrowserRuntimeReadinessFromExpoGoConfig(
+  expoGoConfig: unknown,
+): ExpoOAuthBrowserRuntimeReadiness {
+  if (expoGoConfig === null) {
+    return { status: 'ready' };
+  }
+
+  return {
+    status: 'unsupported',
+    reason: 'expo-go',
+    message:
+      'Brokered OAuth requires a development or standalone build with the configured app scheme; Expo Go cannot provide a stable OAuth callback scheme.',
+  };
+}

package/src/oauthBrowserTransport.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  resolveExpoOAuthBrowserException,
+  resolveExpoOAuthBrowserResult,
+} from './oauthBrowserTransport';
+
+describe('Expo OAuth browser transport', () => {
+  test('maps a successful browser redirect to a callback response', () => {
+    expect(
+      resolveExpoOAuthBrowserResult({ type: 'success', url: 'ankh://auth/callback?code=abc' }),
+    ).toEqual({ type: 'callback', url: 'ankh://auth/callback?code=abc' });
+  });
+
+  test('maps user cancellation separately from browser dismissal', () => {
+    expect(resolveExpoOAuthBrowserResult({ type: 'cancel' })).toEqual({
+      type: 'cancelled',
+      reason: 'user_cancelled',
+    });
+    expect(resolveExpoOAuthBrowserResult({ type: 'dismiss' })).toEqual({
+      type: 'cancelled',
+      reason: 'browser_dismissed',
+    });
+  });
+
+  test.each(['locked', 'opened'])(
+    'maps %s to a transport failure instead of cancellation',
+    (type) => {
+      expect(resolveExpoOAuthBrowserResult({ type })).toEqual({
+        type: 'error',
+        error: {
+          code: 'transport_failed',
+          message: 'The Expo authentication browser did not complete the OAuth redirect.',
+        },
+      });
+    },
+  );
+
+  test('rejects malformed success and unknown results as transport failures', () => {
+    expect(resolveExpoOAuthBrowserResult({ type: 'success' })).toMatchObject({
+      type: 'error',
+      error: { code: 'transport_failed' },
+    });
+    expect(resolveExpoOAuthBrowserResult(null)).toMatchObject({
+      type: 'error',
+      error: { code: 'transport_failed' },
+    });
+  });
+
+  test('maps a rejected browser invocation to browser unavailable', () => {
+    expect(resolveExpoOAuthBrowserException()).toEqual({
+      type: 'error',
+      error: {
+        code: 'browser_unavailable',
+        message: 'The Expo authentication browser could not be opened.',
+      },
+    });
+  });
+});

package/src/oauthBrowserTransport.ts

@@ -0,0 +1,42 @@
+import type { AuthOAuthAuthorizationResponse } from '@ankhorage/contracts/auth';
+
+export function resolveExpoOAuthBrowserResult(result: unknown): AuthOAuthAuthorizationResponse {
+  if (!isRecord(result))
+    return transportFailed('The Expo authentication browser returned no result.');
+
+  const type = Reflect.get(result, 'type');
+  if (type === 'success') {
+    const url = Reflect.get(result, 'url');
+    return typeof url === 'string' && url.trim().length > 0
+      ? { type: 'callback', url }
+      : transportFailed('The Expo authentication browser returned no callback URL.');
+  }
+  if (type === 'cancel') {
+    return { type: 'cancelled', reason: 'user_cancelled' };
+  }
+  if (type === 'dismiss') {
+    return { type: 'cancelled', reason: 'browser_dismissed' };
+  }
+  return transportFailed('The Expo authentication browser did not complete the OAuth redirect.');
+}
+
+export function resolveExpoOAuthBrowserException(): AuthOAuthAuthorizationResponse {
+  return {
+    type: 'error',
+    error: {
+      code: 'browser_unavailable',
+      message: 'The Expo authentication browser could not be opened.',
+    },
+  };
+}
+
+function transportFailed(message: string): AuthOAuthAuthorizationResponse {
+  return {
+    type: 'error',
+    error: { code: 'transport_failed', message },
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}