@atlasauth/expo-passkeys 0.1.0

package/README.md

@@ -0,0 +1,68 @@
+# @atlasauth/expo-passkeys
+
+Passkey registration and sign-in for Expo & React Native, a thin companion to
+[`@atlasauth/expo`](../expo).
+
+The server describes the WebAuthn ceremony (`begin`), the platform authenticator
+performs it, and the result is POSTed back (`finish`). On the web the browser
+runs the ceremony with `navigator.credentials`; on native there is no
+`navigator`, so this package delegates the ceremony to
+[`react-native-passkey`](https://github.com/f-23/react-native-passkey) — an
+**optional peer you pass in** — and owns only the two HTTP calls and the body
+mapping between them.
+
+## Native dependency
+
+```sh
+npx expo install react-native-passkey
+```
+
+`react-native-passkey` is a native module: it needs a config plugin and a
+**custom dev client / prebuild** (it does not run in Expo Go), plus an associated
+domain (iOS `webcredentials:`) / Digital Asset Links (Android) for your RP id.
+This package never imports it, so the import stays optional and your build keeps
+compiling without it.
+
+## Register (signed-in user)
+
+```ts
+import { Passkey } from 'react-native-passkey';
+import { registerPasskey } from '@atlasauth/expo-passkeys';
+import { useAuth } from '@atlasauth/expo';
+
+const { getToken } = useAuth();
+
+await registerPasskey({
+  config: {
+    frontendApi: 'https://fapi.your-instance.atlasauth.net',
+    publishableKey: 'pk_live_…',
+    getToken, // the /me/passkeys route is authenticated
+  },
+  passkey: Passkey,
+  name: 'My iPhone',
+});
+```
+
+## Sign in
+
+```ts
+import { Passkey } from 'react-native-passkey';
+import { authenticateWithPasskey } from '@atlasauth/expo-passkeys';
+
+const result = await authenticateWithPasskey({
+  config: {
+    frontendApi: 'https://fapi.your-instance.atlasauth.net',
+    publishableKey: 'pk_live_…',
+  },
+  passkey: Passkey,
+});
+
+if (result.status === 'complete' && result.ticket) {
+  // hand result.ticket to @atlasauth/expo to exchange for a session
+} else if (result.status === 'needs_more') {
+  // a second factor is still owed — result.attemptId / result.attemptStatus
+}
+```
+
+`toRegistrationFinishBody` / `toAssertionFinishBody` are exported as pure helpers
+if you want to drive the two HTTP calls yourself.

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+import { FapiClient } from '@atlasauth/js';
+/**
+ * How a helper reaches an Atlas instance. The begin/finish FAPI calls run from
+ * the device, so — unlike the web, where a cookie carries the session — the
+ * app's session token (for the signed-in `me` routes) rides in an
+ * `Authorization: Bearer` header. `getToken` is optional: a sign-in ceremony has
+ * no session yet, a register ceremony does.
+ */
+export interface AtlasFapiConfig {
+    /** The instance's FAPI origin, e.g. `https://fapi.acme.atlasauth.net`. */
+    frontendApi: string;
+    /** The publishable key — sent as `x-publishable-key` on every request. */
+    publishableKey: string;
+    /** The current session token, for authenticated (`/me/*`) routes. */
+    getToken?: () => string | null | Promise<string | null>;
+    /** Injectable for tests; defaults to the platform `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/** Build a bearer-authenticated `@atlasauth/js` FapiClient from the config. */
+export declare function createFapiClient(config: AtlasFapiConfig): FapiClient;

package/dist/client.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFapiClient = createFapiClient;
+const js_1 = require("@atlasauth/js");
+/** Build a bearer-authenticated `@atlasauth/js` FapiClient from the config. */
+function createFapiClient(config) {
+    const base = config.fetchImpl ?? fetch;
+    const fetchImpl = async (input, init) => {
+        const headers = new Headers(init?.headers);
+        const token = config.getToken ? await config.getToken() : null;
+        if (token)
+            headers.set('authorization', `Bearer ${token}`);
+        return base(input, { ...init, headers });
+    };
+    return new js_1.FapiClient({
+        publishableKey: config.publishableKey,
+        baseUrl: config.frontendApi,
+        fetchImpl,
+    });
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":";;AAqBA,4CAaC;AAlCD,sCAA2C;AAoB3C,+EAA+E;AAC/E,SAAgB,gBAAgB,CAAC,MAAuB;IACtD,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,IAAI,KAAK,CAAC;IACvC,MAAM,SAAS,GAAiB,KAAK,EAAE,KAAwB,EAAE,IAAkB,EAAE,EAAE;QACrF,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC3C,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QAC/D,IAAI,KAAK;YAAE,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,UAAU,KAAK,EAAE,CAAC,CAAC;QAC3D,OAAO,IAAI,CAAC,KAAK,EAAE,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IAC3C,CAAC,CAAC;IACF,OAAO,IAAI,eAAU,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,OAAO,EAAE,MAAM,CAAC,WAAW;QAC3B,SAAS;KACV,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @atlasauth/expo-passkeys — passkey register / sign-in for Expo & React Native.
+ *
+ * Passkeys on native are a two-call dance that mirrors the web (see
+ * `@atlasauth/js`'s `createPasskey` / `getPasskeyAssertion`): the server's
+ * `begin` response describes the ceremony, the platform authenticator performs
+ * it, and the result is POSTed to `finish`. The browser runs the ceremony with
+ * `navigator.credentials`; on native there is no `navigator`, so this helper
+ * delegates the ceremony to `react-native-passkey` (an optional peer, passed in)
+ * and owns only the two HTTP calls and the body mapping between them.
+ *
+ *   register: POST /v1/client/me/passkeys/begin → Passkey.create → /finish
+ *   sign in : POST /v1/client/sign_ins/passkey/begin → Passkey.get → /finish
+ */
+import type { FieldError, PasskeyAssertionBody, PasskeyRegistrationBody } from '@atlasauth/js';
+import { type AtlasFapiConfig } from './client';
+import type { PasskeyCreateResult, PasskeyGetResult, ReactNativePasskey } from './passkey-native';
+export * from './client';
+export * from './passkey-native';
+/** Map a `begin` response + a `Passkey.create` result to the `/finish` body. */
+export declare function toRegistrationFinishBody(begin: Record<string, unknown>, credential: PasskeyCreateResult, name?: string): PasskeyRegistrationBody;
+/** Map a `begin` response + a `Passkey.get` result to the `/finish` body. */
+export declare function toAssertionFinishBody(begin: Record<string, unknown>, assertion: PasskeyGetResult): PasskeyAssertionBody;
+export interface RegisterPasskeyResult {
+    ok: boolean;
+    errors: FieldError[];
+}
+/**
+ * Register a passkey for the signed-in user. Requires `config.getToken` (the
+ * `/me/*` route is authenticated). Runs begin → platform ceremony → finish.
+ */
+export declare function registerPasskey(opts: {
+    config: AtlasFapiConfig;
+    passkey: ReactNativePasskey;
+    /** A human label for the credential (shown in the user's device list). */
+    name?: string;
+}): Promise<RegisterPasskeyResult>;
+export interface PasskeySignInResult {
+    status: 'complete' | 'needs_more' | 'error';
+    /** Present when complete — exchange it for a session token. */
+    ticket?: string;
+    attemptId?: string;
+    attemptStatus?: string;
+    errors: FieldError[];
+}
+/**
+ * Sign in with a passkey. Runs begin → platform ceremony → finish and returns
+ * the attempt outcome: `complete` carries a one-time `ticket` to exchange for a
+ * session (hand it to `@atlasauth/expo`), `needs_more` means a factor is still
+ * owed.
+ */
+export declare function authenticateWithPasskey(opts: {
+    config: AtlasFapiConfig;
+    passkey: ReactNativePasskey;
+}): Promise<PasskeySignInResult>;

package/dist/index.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * @atlasauth/expo-passkeys — passkey register / sign-in for Expo & React Native.
+ *
+ * Passkeys on native are a two-call dance that mirrors the web (see
+ * `@atlasauth/js`'s `createPasskey` / `getPasskeyAssertion`): the server's
+ * `begin` response describes the ceremony, the platform authenticator performs
+ * it, and the result is POSTed to `finish`. The browser runs the ceremony with
+ * `navigator.credentials`; on native there is no `navigator`, so this helper
+ * delegates the ceremony to `react-native-passkey` (an optional peer, passed in)
+ * and owns only the two HTTP calls and the body mapping between them.
+ *
+ *   register: POST /v1/client/me/passkeys/begin → Passkey.create → /finish
+ *   sign in : POST /v1/client/sign_ins/passkey/begin → Passkey.get → /finish
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toRegistrationFinishBody = toRegistrationFinishBody;
+exports.toAssertionFinishBody = toAssertionFinishBody;
+exports.registerPasskey = registerPasskey;
+exports.authenticateWithPasskey = authenticateWithPasskey;
+const client_1 = require("./client");
+__exportStar(require("./client"), exports);
+__exportStar(require("./passkey-native"), exports);
+/* ── pure body mapping (unit-tested without a device) ──────────────────────── */
+/** Map a `begin` response + a `Passkey.create` result to the `/finish` body. */
+function toRegistrationFinishBody(begin, credential, name) {
+    return {
+        // Echo the server's challenge string — the server matched/stored it.
+        challenge: begin.challenge,
+        attestation_object: credential.response.attestationObject,
+        client_data_json: credential.response.clientDataJSON,
+        ...(name ? { name } : {}),
+    };
+}
+/** Map a `begin` response + a `Passkey.get` result to the `/finish` body. */
+function toAssertionFinishBody(begin, assertion) {
+    return {
+        handle: begin.handle,
+        challenge: begin.challenge,
+        credential_id: assertion.rawId ?? assertion.id ?? '',
+        authenticator_data: assertion.response.authenticatorData,
+        client_data_json: assertion.response.clientDataJSON,
+        signature: assertion.response.signature,
+    };
+}
+/**
+ * Register a passkey for the signed-in user. Requires `config.getToken` (the
+ * `/me/*` route is authenticated). Runs begin → platform ceremony → finish.
+ */
+async function registerPasskey(opts) {
+    const client = (0, client_1.createFapiClient)(opts.config);
+    const begin = await client.post('/v1/client/me/passkeys/begin', {});
+    if (!begin.ok || !begin.data)
+        return { ok: false, errors: begin.errors };
+    const credential = await opts.passkey.create(begin.data);
+    const body = toRegistrationFinishBody(begin.data, credential, opts.name);
+    const finish = await client.post('/v1/client/me/passkeys/finish', body);
+    return { ok: finish.ok, errors: finish.errors };
+}
+/**
+ * Sign in with a passkey. Runs begin → platform ceremony → finish and returns
+ * the attempt outcome: `complete` carries a one-time `ticket` to exchange for a
+ * session (hand it to `@atlasauth/expo`), `needs_more` means a factor is still
+ * owed.
+ */
+async function authenticateWithPasskey(opts) {
+    const client = (0, client_1.createFapiClient)(opts.config);
+    const begin = await client.post('/v1/client/sign_ins/passkey/begin', {});
+    if (!begin.ok || !begin.data)
+        return { status: 'error', errors: begin.errors };
+    const assertion = await opts.passkey.get(begin.data);
+    const body = toAssertionFinishBody(begin.data, assertion);
+    const finish = await client.post('/v1/client/sign_ins/passkey/finish', body);
+    if (!finish.ok || !finish.data)
+        return { status: 'error', errors: finish.errors };
+    return {
+        status: finish.data.ticket ? 'complete' : 'needs_more',
+        ...(finish.data.ticket ? { ticket: finish.data.ticket } : {}),
+        ...(finish.data.id ? { attemptId: finish.data.id } : {}),
+        ...(finish.data.status ? { attemptStatus: finish.data.status } : {}),
+        errors: [],
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/passkey-native.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The slice of [`react-native-passkey`](https://github.com/f-23/react-native-passkey)
+ * this helper uses, declared structurally.
+ *
+ * `react-native-passkey` is an OPTIONAL peer that bridges to the platform
+ * authenticator (iOS ASAuthorization / Android Credential Manager). This package
+ * never imports it — the app passes the `Passkey` object in — so the package
+ * compiles and typechecks without the native module, and without a config plugin
+ * / prebuild in CI. The real `Passkey` is structurally compatible with the shapes
+ * below.
+ *
+ * `Passkey.create` / `Passkey.get` accept the server's WebAuthn options JSON
+ * verbatim (the `begin` response) and return the ceremony result with base64url
+ * string fields — exactly what the Atlas `finish` routes want.
+ */
+/** Result of `Passkey.create` — a WebAuthn attestation. */
+export interface PasskeyCreateResult {
+    id?: string;
+    rawId?: string;
+    response: {
+        attestationObject: string;
+        clientDataJSON: string;
+    };
+}
+/** Result of `Passkey.get` — a WebAuthn assertion. */
+export interface PasskeyGetResult {
+    id?: string;
+    rawId?: string;
+    response: {
+        authenticatorData: string;
+        clientDataJSON: string;
+        signature: string;
+        userHandle?: string | null;
+    };
+}
+/** The `Passkey` object `react-native-passkey` exports. */
+export interface ReactNativePasskey {
+    create(request: Record<string, unknown>): Promise<PasskeyCreateResult>;
+    get(request: Record<string, unknown>): Promise<PasskeyGetResult>;
+}

package/dist/passkey-native.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * The slice of [`react-native-passkey`](https://github.com/f-23/react-native-passkey)
+ * this helper uses, declared structurally.
+ *
+ * `react-native-passkey` is an OPTIONAL peer that bridges to the platform
+ * authenticator (iOS ASAuthorization / Android Credential Manager). This package
+ * never imports it — the app passes the `Passkey` object in — so the package
+ * compiles and typechecks without the native module, and without a config plugin
+ * / prebuild in CI. The real `Passkey` is structurally compatible with the shapes
+ * below.
+ *
+ * `Passkey.create` / `Passkey.get` accept the server's WebAuthn options JSON
+ * verbatim (the `begin` response) and return the ceremony result with base64url
+ * string fields — exactly what the Atlas `finish` routes want.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=passkey-native.js.map

package/dist/passkey-native.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"passkey-native.js","sourceRoot":"","sources":["../src/passkey-native.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@atlasauth/expo-passkeys",
+  "version": "0.1.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@atlasauth/js": "0.2.0"
+  },
+  "peerDependencies": {
+    "react-native": ">=0.73",
+    "react-native-passkey": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "react-native": {
+      "optional": true
+    },
+    "react-native-passkey": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}