@rakomi/react-native 0.1.0 → 0.3.0

package/COMPLIANCE.md

@@ -4,21 +4,24 @@ Regulatory cross-reference for tenants in EU-regulated industries.
 
 ## CRA — Reg. (EU) 2024/2847 (Cyber Resilience Act)
 
-This package is a "product with digital elements" under CRA Annex I. Same posture as `@rakomi/node` and `@rakomi/react`.
+This package is a "product with digital elements" under CRA Art. 3(1). Same posture as `@rakomi/node` and `@rakomi/react`.
 
 | CRA reference | Compliance posture |
 |---|---|
 | Art. 13 — Vulnerability handling | Documented secure vulnerability-handling process; vulnerability records retained with the technical documentation. Internal fix targets (e.g. 14 days for High severity) are an operational SLA, **not** a statutory deadline. See `SECURITY.md`. |
 | Art. 14 — Reporting of actively exploited vulnerabilities & severe incidents | Statutory reporting to the designated authority on the CRA timeline (early warning → notification → final report) and informing impacted users; published advisories via GitHub Security Advisories. See `SECURITY.md`. |
-| Annex I — Essential cybersecurity requirements | Secure defaults: fixed asymmetric token-signature verification, PKCE with S256 challenge (RFC 7636), biometric opt-in, ephemeral session, minimal attack surface. |
+| Annex I — Essential cybersecurity requirements | Secure defaults: fixed asymmetric token-signature verification, PKCE with S256 challenge (RFC 7636), biometric opt-in, ephemeral session, minimal attack surface. **Passkeys:** no passkey library is bundled or depended on by **this package** — the OS ceremony is reached through a module the host supplies. Read that precisely: it removes third-party ceremony code from *our* dependency tree and therefore from *our* SBOM; the module you wire **is** on the credential path and is **your** supply-chain surface, so account for it in yours. The bridge itself carries no bearer token, emits nothing to telemetry or the console, and an unwired adapter fails closed (`PASSKEY_NOT_SUPPORTED`) rather than falling back to a different ceremony. |
 
 ## GDPR — Reg. (EU) 2016/679
 
 | Article | Posture |
 |---|---|
-| Art. 25 — Data protection by design | No PII collected client-side beyond what API requires; analytics opt-in via `onEvent` only. |
+| Art. 25 — Data protection by design | No PII collected client-side beyond what API requires; analytics opt-in via `onEvent` only. **Passkeys — sign-in:** identified sign-in takes an opaque, server-issued user handle, never an email or a username. **Passkeys — registration (state this plainly):** the registration options the server issues carry the account's `user.name` / `user.displayName`, which today is the user's **email address**. It crosses the bridge to the host-supplied module and is passed to the platform credential provider, which stores it with the credential and may **sync it to the user's platform account** (iCloud Keychain / Google Password Manager). This is inherent to WebAuthn — the value is what the user is shown when they pick a passkey — not a choice this SDK makes, and it is disclosed here rather than glossed. The SDK adds no identifier of its own. **Errors:** the credential-envelope validator names the failing FIELD, never its VALUE; error messages relayed from the server or from the host's own callbacks are passed through verbatim and are the tenant's surface to control. |
 | Art. 28 — Processor obligations | SDK is a data-processor adjunct; tenant is data controller. DPA covers the relationship. |
-| Art. 32 — Security of processing | Pseudonymisation + encryption at rest (Keychain) + access control (biometric opt-in). |
+| Art. 32 — Security of processing | Pseudonymisation + encryption at rest (Keychain) + access control (biometric opt-in). **Passkeys — key material:** the private key is created and held by the platform credential provider; it never enters SDK memory and the SDK holds no passkey material at rest. No access token, step-up token or bearer secret reaches the ceremony adapter. |
+| Art. 32 — Security of processing (session integrity) | A completed ceremony whose session was **not** actually stored is reported as a failure, never as a success — the SDK re-reads the token runtime and matches the session identity before it reports a sign-in. |
+| Art. 32 — Security of processing (re-authentication gate) | Management actions (list / rename / delete) are re-authentication-gated. **The gate is enforced by the API, not by this SDK** — the SDK transmits the step-up token it is given and does not itself decide whether one is sufficient. Stated here because an SDK compliance doc must not claim credit for a server-side control. |
+| Art. 9 — Special categories (negative scope) | **No biometric data is processed by this SDK.** A fingerprint or face is consumed by the operating system to unlock the authenticator; the SDK receives only the resulting assertion. It never reads, stores, transmits or infers a biometric template, so Art. 9's special-category regime is not engaged by anything this library does. (Whether YOUR app processes biometrics for other purposes is your assessment.) |
 
 ## eIDAS 2 — Reg. (EU) 2024/1183 (EUDI Wallet)
 
@@ -26,7 +29,8 @@ End-of-2026 mandate. The `NativeAuthAdapter` exposes a typed forward-compat slot
 
 ## NIS2 — Dir. (EU) 2022/2555
 
-Tenants in essential / important sectors can attest that their auth-provider meets the NIS2 Art. 21 measures by referencing this SDK's posture in their conformity self-assessment:
+NIS2 Art. 21 measures are obligations on the **entity**, and no supplier's posture discharges them. What
+this SDK offers is *input* to your own risk assessment, not an attestation:
 
 - Risk-management measures: cryptographic + access controls documented in `SECURITY.md`.
 - Incident handling: statutory reporting of actively exploited vulnerabilities / severe incidents per CRA Art. 14 (early warning, notification, final report); see `SECURITY.md`.
@@ -34,7 +38,33 @@ Tenants in essential / important sectors can attest that their auth-provider mee
 
 ## DORA — Reg. (EU) 2022/2554
 
-For financial-sector tenants — the SDK's MFA + passkey roadmap satisfies SCA requirements (PSD2 RTS / PSD3-PSR forthcoming).
+For financial-sector tenants, DORA governs ICT risk management (Art. 5–15) and ICT third-party risk
+(Art. 28–30). What this SDK offers as *input* to those obligations, as one ICT component you consume:
+
+- A CycloneDX SBOM and npm build provenance (SLSA Build L2) with every release — supporting your ICT
+  risk-management and supply-chain analysis. (Your Art. 28(3) register of information records the
+  **contractual arrangement** for the Rakomi service, not this library artefact.)
+- Vulnerability handling per CRA Art. 13 + Annex I Part II, and statutory reporting per CRA Art. 14;
+  see `SECURITY.md`.
+
+## Strong Customer Authentication (PSD2 / RTS 2018/389)
+
+**This SDK makes no SCA claim and no assurance-level (AAL / eIDAS LoA) claim.** SCA is a property of a
+payment flow, assessed by the payment service provider against its own deployment; a library cannot
+satisfy it, and nothing in this document should be quoted as if it could. Two things are worth stating
+because they are the parts a PSP most often assumes wrongly:
+
+- **Dynamic linking (RTS Art. 5) is NOT provided.** This SDK authenticates a *user*, not a
+  *transaction*: it accepts no amount and no payee, and binds neither into the signed challenge. A
+  payment initiation requiring dynamic linking cannot be built on this SDK's passkey flow alone.
+- **A platform passkey is not necessarily device-bound.** On both iOS and Android a passkey is, by
+  default, **synced** through the platform account (iCloud Keychain / Google Password Manager), and the
+  SDK cannot tell a synced credential from a device-bound one — the WebAuthn signals that would hint at
+  it are opaque relays we neither interpret nor vouch for. Any element analysis under RTS Art. 7 or Art. 9
+  (including whether the elements are independent on a multi-purpose device, per Art. 9(2)–(3)) is
+  therefore the PSP's assessment, on evidence this SDK does not supply.
+
+PSD3/PSR are proposals and, as at 2026-07, are not in force; nothing here anticipates their final text.
 
 ## Apple App Store / Google Play Data Safety
 

package/README.md

@@ -2,9 +2,27 @@
 
 React Native / Expo SDK for [Rakomi](https://rakomi.com) — EU-native auth-as-a-service.
 
-> **Status:** `0.1.0` — initial. API surface frozen for parity with `@rakomi/react`.
-> Token-manager runtime, JWKS verification, social-provider deep-link auto-handler,
-> bare-RN adapter example, and the demo app land in subsequent 0.x patches.
+> **Status: PREVIEW.** `@rakomi/react-native` is a pre-1.0 package — no stability or support
+> guarantee (SemVer 2.0.0 §4). The exported hook and component **surface** is frozen for parity with
+> [`@rakomi/react`](https://www.npmjs.com/package/@rakomi/react), and every name below is exported
+> and type-checked, but not every export's **behavior** is wired to the network yet.
+>
+> **Works today:** social sign-in via the system browser (`<SignIn providers={[...]} />` /
+> `startSocialSignIn()`), magic link, email OTP, registration, MFA (TOTP), passkeys
+> (sign-in/step-up/register/list/rename/delete), session management (`useAuth`, `useSession`,
+> `getToken`), `<UserButton>`, `<SignedIn>`/`<SignedOut>`, `<Protect>`, `useOrganization` /
+> `useOrganizationList` (JWT-claim reads), `useAuthConfig`, `useBranding`, `useBaasPlans`,
+> `useBaasSubscription`.
+>
+> **Not yet wired — calls resolve/return an error placeholder, no network request is made:**
+> `useAuth().signIn()` (direct email+password) and `useAuth().switchOrganization()`;
+> `useLinkedAccounts().link()`/`.unlink()`; `useAnonymousSignin().signInAnonymously()`. `<SignIn />`
+> renders social providers and MFA TOTP entry only — there is no password field in the pre-built
+> component. `<UserProfile>` and `<Feature>` are marked preview individually below. Each of these is
+> also called out at its own symbol in the [full reference docs](https://docs.rakomi.dev/sdk/react-native/authentication/#what-works-today).
+>
+> Token-manager runtime, JWKS verification, social-provider deep-link auto-handler, a bare-RN adapter
+> example, and a demo app land in subsequent 0.x releases.
 
 ## Install
 
@@ -36,16 +54,263 @@ export default function App() {
 }
 ```
 
-## What's included in 0.1.0
+## What's included
 
 - **`<RakomiProvider>`** — context provider. Freezes the native adapter on mount. AppState debounce 300ms. Connectivity transitions wired.
-- **Hooks (parity-locked):** `useAuth`, `useUser`, `useSession`, `useFlag`, `useOrganization`, `useOrganizationList`, `useLinkedAccounts`, `useTranslation`, `useAuthConfig`, `useBranding`, `useAnonymousSignin`, `useBaasPlans`, `useBaasSubscription`. Type-level parity with `@rakomi/react` is enforced by CI.
-- **Components:** `<SignIn />` (password + social + MFA TOTP), `<SignUp />`, `<UserButton />`, `<UserProfile />` (preview), `<SignedIn>`, `<SignedOut>`, `<Protect>`, `<Feature>`. RN primitives only — no HTML, no WebView.
+- **Hooks (parity-locked):** `useAuth`, `useUser`, `useSession`, `useFlag`, `useOrganization`, `useOrganizationList`, `useLinkedAccounts` (preview), `useTranslation`, `useAuthConfig`, `useBranding`, `useAnonymousSignin` (preview), `useBaasPlans`, `useBaasSubscription`. Type-level parity with `@rakomi/react` is enforced by CI — see the status banner above for which hooks make real network calls today.
+- **Components:** `<SignIn />` (social + MFA TOTP — no password field), `<SignUp />`, `<UserButton />`, `<UserProfile />` (preview), `<SignedIn>`, `<SignedOut>`, `<Protect>`, `<Feature>` (preview — reads the JWT directly, no live evaluation). RN primitives only — no HTML, no WebView.
 - **OAuth (RFC 8252):** PKCE S256, 32-byte state with single-use 60s TTL + constant-time comparison, system browser via `expo-web-browser` (`preferEphemeralSession: true` default), confused-deputy guard on callback ingest.
 - **Native adapter contract:** `NativeAuthAdapter` interface with forward-compat slots (`verifiers` for EUDI, `dpopProver` for DPoP, `par` for RFC 9126 PAR).
 - **`tokenCache` injection sugar** — replace storage without re-implementing the full adapter.
 - **HKDF-style storage key derivation** — domain-separated per tenant + per purpose.
 
+## Passkeys (WebAuthn)
+
+`usePasskeys()` is the whole passkey surface: sign-in, step-up, registration, and management
+(list / rename / delete). Passkeys give you **passwordless** sign-in. They are **phishing-resistant**
+only because the operating system binds the credential to your app's associated domain — on iOS
+through your **Associated Domains** entitlement, on Android through your **Digital Asset Links** file.
+If either is missing or wrong the OS **refuses** the ceremony; the SDK cannot and does not substitute
+for that configuration. (The reassuring half: a misconfiguration does not silently weaken anything —
+it stops the ceremony outright.)
+
+The flow is not "biometric sign-in", and calling it that in your UI would be untrue for a share of your
+users: user verification is performed by the **device's screen lock — biometrics *or* passcode** — and
+the SDK cannot distinguish them, nor does it want to.
+
+The SDK does **not** ship a passkey library and does **not** depend on one. The OS ceremony
+(the system passkey sheet) belongs to your app: you supply a native module, the SDK talks to it
+through one small contract. That keeps a third-party module off the credential path, keeps Expo Go
+working for apps that never use passkeys, and lets you pick whichever community wrapper you already
+trust.
+
+### Wiring the ceremony adapter
+
+**With a native module of your own** (or a community wrapper's module):
+
+```tsx
+import {
+  createDefaultExpoAdapter,
+  createNativePasskeyAdapter,
+  RakomiProvider,
+} from '@rakomi/react-native';
+import { NativeModules } from 'react-native';
+
+const passkeys = createNativePasskeyAdapter({ module: NativeModules.MyPasskeyModule });
+
+// `nativeAdapter` is normally optional (it defaults to the Expo adapter). To ADD passkeys you must
+// name it explicitly — spread the default and attach the slot. There is no `passkeys` shorthand prop.
+<RakomiProvider
+  publishableKey={process.env.EXPO_PUBLIC_RAKOMI_KEY!}
+  baseUrl="https://api.rakomi.com"
+  redirectUri="myapp://callback"
+  nativeAdapter={{ ...createDefaultExpoAdapter(), passkeys }}
+>
+  {/* … */}
+</RakomiProvider>
+```
+
+**With a community wrapper whose API is not the module shape** — write a four-line shim; the contract
+is deliberately tiny:
+
+```ts
+import { createNativePasskeyAdapter } from '@rakomi/react-native';
+import { Passkey } from 'some-passkey-wrapper'; // whichever wrapper you already trust
+
+const passkeys = createNativePasskeyAdapter({
+  module: {
+    isPasskeySupported: () => Passkey.isSupported(),
+    // The SDK's contract is STRING in, STRING out. Most community wrappers are OBJECT in, OBJECT out —
+    // so the shim parses on the way in and serialises on the way out. Getting this backwards
+    // double-encodes the request (the wrapper receives a JSON string where it expects an object) and is
+    // the single most common wiring bug; check your wrapper's signature, do not copy this blindly.
+    createPasskey: (requestJson: string) =>
+      Passkey.create(JSON.parse(requestJson)).then((credential) => JSON.stringify(credential)),
+    getPasskey: (requestJson: string) =>
+      Passkey.get(JSON.parse(requestJson)).then((credential) => JSON.stringify(credential)),
+    // Implement this if your wrapper can dismiss an open sheet — it is what narrows the
+    // orphaned-credential window described below.
+    cancelPasskeyRequest: () => Passkey.cancel?.(),
+  },
+});
+```
+
+### Using the hook
+
+```tsx
+const {
+  isSupported,            // null until probed; false = this device cannot run a ceremony
+  signInWithPasskey,      // no session needed
+  stepUpWithPasskey,      // mints a step-up token — needs a session AND an existing passkey
+  registerPasskey, listPasskeys, renamePasskey, deletePasskey, // all need a step-up token
+  passkeys,               // `undefined` until you call listPasskeys(); `[]` means "none"
+  error, isSigningIn, isRegistering, isSteppingUp, isLoading, isMutating,
+} = usePasskeys();
+```
+
+`passkeys` starts as **`undefined`**, not `[]`. The difference is not pedantry: `[]` says "this user has
+no passkeys" and `undefined` says "we have not looked". An empty-state UI keyed on `passkeys?.length === 0`
+renders "no passkeys yet" before the first `listPasskeys()` has even run.
+
+### Step-up tokens — read this before building an "Add a passkey" button
+
+Every management action (`registerPasskey`, `listPasskeys`, `renamePasskey`, `deletePasskey`) requires a
+**step-up token**: changing which keys can sign you in is itself a sensitive act, so the server demands a
+fresh re-authentication for it. The SDK never mints or stores one for you.
+
+**There is a chicken-and-egg here, and it will bite you first.** `stepUpWithPasskey()` re-authenticates
+with an **existing passkey** — so it cannot mint the token needed to register the user's **first** one.
+For that first registration, obtain a step-up token through another factor (your app's password or MFA
+step-up endpoint), then pass it to `registerPasskey({ stepUpToken })`. Once the user has a passkey,
+`stepUpWithPasskey()` is the smooth path for every subsequent management action.
+
+Treat a step-up token as **single-use and short-lived**: mint a fresh one per gated action rather than
+caching one across a management screen. (`stepUpWithPasskey()` returns its `expiresIn`.) The server's
+reuse semantics are not something the SDK guarantees, so the defensive reading is the correct one.
+
+### The bridge contract
+
+| Module member | Required | Shape |
+|---|---|---|
+| `isPasskeySupported()` | yes | `Promise<boolean>` — the device can run a passkey ceremony at all |
+| `createPasskey(requestJson)` | yes | `Promise<string>` — the registration credential, serialised |
+| `getPasskey(requestJson)` | yes | `Promise<string>` — the authentication credential, serialised |
+| `isPlatformAuthenticatorAvailable()` | no | `Promise<boolean>` — is there a *platform* authenticator, not just any |
+| `cancelPasskeyRequest()` | no | `Promise<void> \| void` — dismiss an open sheet when the ceremony is abandoned |
+
+Implement `cancelPasskeyRequest` if your module can: without it, a ceremony abandoned by your app (a
+screen unmounts, a timeout fires) can leave the OS sheet standing, and a registration abandoned after
+the credential provider already created the credential leaves the user holding a passkey the server
+never learned about (see *Orphaned credentials* below).
+
+**Strings, not objects — and this is not a style preference.** The RN bridge serialises through JSON
+and **drops `undefined`**, which silently deletes optional members. A request that arrives with
+`residentKey` missing is a *different* request from one that arrives with `residentKey: 'required'`,
+and the sheet the user sees changes accordingly. Passing the request as a string we build ourselves
+is the only way to guarantee the bytes the OS gets are the bytes the server signed off on.
+
+Every binary field is **base64url without padding** (`A–Z a–z 0–9 - _`, no `=`). Standard base64 —
+with `+`, `/`, `=` — is rejected, and it is the single most common wiring bug: an authenticator that
+returns standard base64 must be re-encoded in your shim, not "fixed" server-side.
+
+### iOS ≠ Android
+
+The two platforms fail differently, and the SDK maps both onto one vocabulary so your UI does not
+have to branch:
+
+| What happened | Code your UI handles |
+|---|---|
+| The user dismissed the sheet | `PASSKEY_CEREMONY_CANCELLED` |
+| The device cannot do passkeys, or no adapter is wired | `PASSKEY_NOT_SUPPORTED` |
+| The credential is already registered for this user | `PASSKEY_ALREADY_REGISTERED` |
+| The action needs a fresh re-authentication first | `PASSKEY_STEP_UP_REQUIRED` |
+| Your module broke the contract (returned a non-credential) | `PASSKEY_ADAPTER_ERROR` — an integration bug, never a retry |
+| Sign-in succeeded but the tenant demands another factor | `PASSKEY_ADDITIONAL_STEP_REQUIRED` — **no tokens are issued**; route the user into your MFA flow, do not show "failed" |
+| The user tried to delete their only sign-in method | `PASSKEY_LAST_METHOD` — "add another method first", not a generic failure |
+| The phone was offline | `PASSKEY_NETWORK_ERROR` — retryable; do **not** sign the user out |
+| The session is genuinely gone | `PASSKEY_SESSION_EXPIRED` — re-authenticate |
+| Too many attempts | `PASSKEY_RATE_LIMITED` (`retryAfterMs` when the server sent one) |
+| Anything else the OS reported | `PASSKEY_CEREMONY_FAILED` (retryable) |
+
+Every error carries a `nextAction` (`retry` / `abort` / `none`) — branch on that rather than on the code
+when all you need is "should the user try again". `PASSKEY_ADDITIONAL_STEP_REQUIRED` is the one most
+likely to be mishandled: it arrives on a **successful** ceremony (HTTP 200) and simply means the tenant
+requires a further factor before a session is issued.
+
+Treat `PASSKEY_CEREMONY_CANCELLED` as a non-event — no error banner. It is by far the most frequent
+outcome, and it also covers **system-initiated** dismissal (a swipe-down, an incoming call, the app
+being backgrounded), not just a deliberate "Cancel". Users who dismissed a sheet on purpose do not
+want to be told they failed.
+
+**Mapping platform exceptions in your module.** Your native module reports failures with a `code`;
+these are the codes the bridge understands, and everything else is re-thrown unchanged and surfaces
+as `PASSKEY_CEREMONY_FAILED`:
+
+| Platform exception | Your module's `code` |
+|---|---|
+| iOS `ASAuthorizationError.canceled` | `PASSKEY_CANCELLED` |
+| iOS `ASAuthorizationError.failed` / `.invalidResponse` | *(re-throw unchanged)* |
+| iOS — passkeys unavailable on this OS version | `PASSKEY_UNSUPPORTED` |
+| Android `GetCredentialCancellationException` / `CreateCredentialCancellationException` | `PASSKEY_CANCELLED` |
+| Android `GetCredentialUnsupportedException` / `CreateCredentialUnsupportedException` | `PASSKEY_UNSUPPORTED` |
+| Android `CreateCredentialNoCreateOptionException` (no credential provider) | `PASSKEY_UNSUPPORTED` — fall back immediately, do not retry |
+| Android `NoCredentialException` (the user has no passkey here) | `PASSKEY_NO_CREDENTIAL` |
+| A community wrapper's own error codes | map them onto the three above, or re-throw |
+| **Everything else** | **re-throw unchanged** → the SDK reports `PASSKEY_CEREMONY_FAILED` |
+
+That last row is a known, documented compromise: the SDK's error vocabulary is closed and deliberately
+small, so a platform-specific cause that has no code of its own arrives as a generic retryable failure.
+Do **not** rewrite an error's `name` in your shim to force a different classification — the SDK reads
+the `code`, and a renamed error is a lie the whole taxonomy then propagates.
+
+**Development builds show request headers.** A host's network inspector / debugging interceptor can see
+the passkey requests, including the `X-Step-Up-Token` header. That is a property of your development
+build, not of the SDK: the token is held in memory for the duration of the call and never written to
+device storage. Do not log headers in production builds.
+
+### Deployment prerequisite — RP-ID binding
+
+Passkeys are bound to a **relying-party identifier** (your domain), and the OS refuses to run a
+ceremony for an app that cannot prove it belongs to that domain. Before a single passkey works you
+must publish the association files and declare the entitlement:
+
+- **iOS** — an `apple-app-site-association` file served over HTTPS at your domain, plus the
+  Associated Domains entitlement (`webcredentials:example.com`).
+- **Android** — a Digital Asset Links (`assetlinks.json`) file at your domain listing your app's
+  signing-certificate fingerprint.
+
+Until both are in place the ceremony fails on the device with no useful message. These two files are
+the prerequisite that turns "passwordless" into "phishing-resistant": with the Associated Domains
+entitlement and the Digital Asset Links file in place, the OS will only offer a credential to an app
+it has verified against the domain that credential was created for — and without them it offers
+nothing at all.
+
+### Symptom → cause
+
+| Symptom | Cause |
+|---|---|
+| The sheet never appears | No association file / entitlement (see above), or `isSupported()` is false |
+| Every ceremony returns `PASSKEY_CEREMONY_FAILED` on a real device | The request is being mutated in your shim — pass the JSON string through untouched |
+| It works in a debug build, not in a release build | Android: the release signing certificate is not in `assetlinks.json` |
+| A field is missing on the OS side | Your wrapper passes objects, not the request string — `undefined` was dropped across the bridge |
+| Sign-in succeeds on the device but the app stays signed out | The token submission was rejected — the hook reports this rather than claiming success |
+
+A generic ceremony failure on a first integration is, in practice, almost always a missing or incorrect
+associated-domains / `assetlinks.json` configuration. The error vocabulary cannot tell you that (the OS
+does not tell *us*), so this line is the diagnostics: check the association files first, before you
+suspect the SDK or your module.
+
+**Two components, one sheet.** The passkey sheet is an operating-system modal: there is exactly one, for
+the whole device. If a sign-in button in your header and a passkey screen in your settings both call
+`usePasskeys()`, the SDK's lock lets only one of them open a ceremony — the second call is refused
+locally with `PASSKEY_INVALID_INPUT` ("a ceremony is already in progress") and surfaces in that hook's
+`error`. Note the busy flags (`isSigningIn`, `isSteppingUp`, …) are **per hook instance**: they tell you
+about *your* component's call, not about the other one's. If you have two entry points on one screen,
+drive both from a single `usePasskeys()` instance, or render one of them behind the other's busy state.
+
+**Expo Go and emulators.** Expo Go cannot load a custom native module, so passkeys need a development
+build. An Android emulator without Google Play services has no credential provider; an iOS simulator
+needs a signed-in Apple account. A device is the only environment that proves the wiring.
+
+**Orphaned credentials.** If registration succeeds on the device but the server never records it, the
+authenticator holds a credential the server does not know about. Registering again with the same
+authenticator returns `PASSKEY_ALREADY_REGISTERED` — that is the documented way out, not an error to
+hide.
+
+**Signing in as a different user — call `signOut()` first, and here is what happens if you don't.** A
+passkey sign-in while another user's session is live is **not** an account switch. The token runtime
+detects the change of subject and **clears the existing session** — user A is signed out — and the hook
+then reports `PASSKEY_REQUEST_FAILED`. Its `nextAction` is `retry`, and a retry *will* succeed (the old
+session is already gone), so from the user's seat it looks like "the first tap logged me out and did
+nothing; the second tap worked". Gate your UI on the current session instead: sign out, then sign in.
+
+**Bearer, not DPoP, on the passkey legs today.** The tokens a passkey sign-in returns are used exactly
+like any other token this SDK issues; sender-constraining them is a separate concern from the ceremony.
+
+**Expo web.** `usePasskeys()` on RN targets the native ceremony. There is no browser fallback here —
+without a wired adapter the hook fails closed with `PASSKEY_NOT_SUPPORTED` rather than quietly
+switching to a different ceremony. For the web, use `@rakomi/react`.
+
 ## Security defaults
 
 - Refresh tokens stored in `expo-secure-store` with `keychainAccessible: AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY` (no iCloud Keychain sync).

package/SECURITY.md

@@ -11,7 +11,7 @@ While these packages remain pre-1.0 (`0.x`), they carry **no stability or suppor
 From version **1.0** onward, Rakomi maintains the current (N) and previous (N-1) MAJOR in parallel, with N-1 receiving
 security-only fixes. The CRA support period for each MAJOR is determined in accordance with
 **CRA Art. 13(8)** — at least five years, or the product's expected use time where shorter. The authoritative, machine-readable support windows are published at
-[`https://rakomi.com/.well-known/sdk-support.json`](https://rakomi.com/.well-known/sdk-support.json)
+[`https://api.rakomi.com/.well-known/sdk-support.json`](https://api.rakomi.com/.well-known/sdk-support.json)
 and rendered for humans on the [SDK Support & Lifecycle page](https://rakomi.com/sdk-support). This
 document points at that single source rather than re-typing dated rows.
 

package/THIRD-PARTY-NOTICES

@@ -1,6 +1,6 @@
 THIRD-PARTY SOFTWARE NOTICES AND INFORMATION
 
-For the npm package: @rakomi/react-native@0.1.0
+For the npm package: @rakomi/react-native@0.3.0
 
 This package's published bundle (`dist/`) INLINES the third-party components listed below.
 Their copyright and permission notices are reproduced verbatim, as required by their licenses