@rakomi/react-native 0.0.0 → 0.2.0

package/COMPLIANCE.md

@@ -0,0 +1,90 @@
+# Compliance — `@rakomi/react-native`
+
+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 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. **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. Proving test: `test/passkey-native-adapter.test.ts` (`@asserts CTRL-CRA-ANNEXI-SECURE-DEFAULT`). |
+
+## 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. **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). **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. Proving test: `test/use-passkeys.test.tsx` (`@asserts CTRL-GDPR-32-NO-SECRET-TO-ADAPTER` — 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. Proving test: `test/use-passkeys.test.tsx` (the session-confirmation polarities). |
+| 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)
+
+End-of-2026 mandate. The `NativeAuthAdapter` exposes a typed forward-compat slot (`verifiers?: AttestationVerifier[]`) to non-breakingly add EUDI PID verification once the EU Wallet implementing acts publish.
+
+## NIS2 — Dir. (EU) 2022/2555
+
+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`.
+- Supply-chain security: SBOM (CycloneDX) shipped with every release; npm build provenance (SLSA Build L2) attached to every published package.
+
+## DORA — Reg. (EU) 2022/2554
+
+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
+
+Tenant fills the privacy nutrition labels. The SDK's data collection (consumer-app perspective):
+
+- **User ID** — for app functionality (sign-in / sign-out lifecycle).
+- **No** location, browsing history, advertising data, or third-party shipping by default.
+
+## WCAG 2.2 AA / EAA (Dir. 2019/882)
+
+Mobile accessibility:
+
+- Every interactive element has `accessibilityLabel` + `accessibilityRole` (verified by component snapshot tests).
+- Keyboard hints (`textContentType`, `autoComplete`, `keyboardType`) appropriate for OTP / email / password.
+- TOTP input uses `oneTimeCode` (iOS auto-fill); Android SMS Retriever is out-of-scope here (deferred).
+
+## OWASP MASVS L1 + Mobile Top 10 (2024)
+
+See `SECURITY.md` for the per-control mapping.
+
+## EU AI Act — Reg. (EU) 2024/1689
+
+This SDK does **NO AI inference**. Negative-scope statement for tenant comfort.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CRE8EVE Sp. z o.o.
+
+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,328 @@
-# @rakomi/react-native
+# `@rakomi/react-native`
 
-Name reserved. The first stable release is published with build provenance from rakomidev/rakomi-js.
+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.
+
+## Install
+
+```sh
+# Expo-managed (recommended)
+expo install @rakomi/react-native expo-secure-store expo-web-browser expo-crypto expo-linking expo-local-authentication
+npm install @react-native-community/netinfo
+
+# Bare React Native
+npm install @rakomi/react-native react-native-keychain react-native-inappbrowser-reborn react-native-quick-crypto
+```
+
+## Quickstart
+
+```tsx
+import { RakomiProvider, SignedIn, SignedOut, UserButton, SignIn } from '@rakomi/react-native';
+
+export default function App() {
+  return (
+    <RakomiProvider
+      publishableKey={process.env.EXPO_PUBLIC_RAKOMI_KEY!}
+      baseUrl="https://api.rakomi.com"
+      redirectUri="myapp://callback"
+    >
+      <SignedIn><UserButton /></SignedIn>
+      <SignedOut><SignIn /></SignedOut>
+    </RakomiProvider>
+  );
+}
+```
+
+## What's included in 0.1.0
+
+- **`<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.
+- **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).
+- Access tokens in-memory only (≤15min lifetime).
+- WebView is **banned** in this package (RFC 8252 + ESLint guard).
+- `Math.random` is **banned** (`expo-crypto.getRandomBytesAsync` is the only randomness source).
+- `redirect: 'error'` on every fetch (SSRF guard — redirects are never auto-followed).
+
+## Compliance
+
+See [`SECURITY.md`](./SECURITY.md) and [`COMPLIANCE.md`](./COMPLIANCE.md) for OWASP MASVS L1 mapping, Mobile Top-10, GDPR Art. 32, CRA (Reg. 2024/2847) Art. 13/14, and threat model.
+
+## Anti-patterns to avoid in consumer apps
+
+- ❌ Don't store refresh tokens in `AsyncStorage` — it's not encrypted at rest.
+- ❌ Don't ship without `expo prebuild` only if you're using bare-RN with custom native modules. Default Expo-managed flows do **not** require `expo prebuild`.
+- ❌ Don't use generic redirect schemes (`rakomi://`) in production — register reverse-DNS (`com.example.myapp:/oauth/callback`) to defeat custom-scheme hijacking.
+
+## Threat model — what the SDK does NOT defend against
+
+- Jailbroken / rooted devices at runtime (consumer adds `react-native-jail-monkey` if needed).
+- Cloned / repackaged apps (use Play Integrity API / DeviceCheck on the consumer side).
+- Hostile in-process npm dependencies (no JS-side mitigation; supply-chain hygiene is the consumer's responsibility).
+
+## Publisher webhooks
+
+`verifyPublisherWebhook` verifies Rakomi publisher-app webhook deliveries (Standard Webhooks
+HMAC-SHA256, replay defence, key-rotation tolerance). See the canonical
+[publisher-webhook receiver contract](https://docs.rakomi.dev/guides/publisher-webhooks/).
+
+## License
+
+See [`LICENSE`](./LICENSE).

package/SECURITY.md

@@ -0,0 +1,206 @@
+# Security Policy
+
+## Supported Versions
+
+This policy covers the four JS-family SDK packages: `@rakomi/node`, `@rakomi/sdk-core`,
+`@rakomi/react`, and `@rakomi/react-native`.
+
+While these packages remain pre-1.0 (`0.x`), they carry **no stability or support guarantee**
+(SemVer 2.0.0 §4); the latest `0.x` line receives security updates on a best-effort basis.
+
+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://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.
+
+Vulnerabilities in peer dependencies (e.g., React) are out of Rakomi's direct scope, but Rakomi will update minimum peer dependency versions when a peer dependency has a known critical CVE affecting SDK users.
+
+## Reporting a Vulnerability
+
+**Please do NOT open a public GitHub issue for security vulnerabilities.**
+
+We support two reporting channels:
+
+1. **Email:** security@rakomi.com (preferred for initial contact)
+2. **GitHub Private Vulnerability Reporting:** [Submit via GitHub Security](https://github.com/rakomidev/rakomi-js/security/advisories/new) — each report automatically receives a GHSA tracking identifier (GHSA-xxxx-xxxx-xxxx).
+
+For encrypted communication, a PGP public key is available at:
+`https://rakomi.com/rakomi-security-pgp-key.asc`
+
+Include the key fingerprint from this file (section 14) for out-of-band verification when sending encrypted reports.
+
+## Response Targets
+
+We strive to meet these response targets. Actual response times may vary based on issue complexity and team availability.
+
+| Severity | First Response | Fix Target | Disclosure |
+|----------|---------------|------------|------------|
+| Critical (actively exploited) | without undue delay (target: 24h) | 72h patch/mitigation | Designated EU authority notified within 24h (CRA Art. 14) |
+| High | without undue delay (target: 48h) | 14 days | Coordinated after fix |
+| Medium | 5 business days | 90 days | Coordinated after fix |
+| Low | 5 business days | Next release cycle | Changelog note |
+
+Severity is assessed using industry-standard vulnerability scoring criteria.
+
+Rakomi is maintained by a small team. During periods of reduced availability, the auto-reply from security@rakomi.com will confirm receipt and provide the PGP key. For actively exploited vulnerabilities, we will respond as quickly as humanly possible.
+
+## Coordinated Vulnerability Disclosure (CVD) Policy
+
+We follow a coordinated disclosure model with a **90-day embargo** period from the date of acknowledgment. During this time:
+
+- Rakomi will work to develop and release a fix
+- We will keep the reporter updated on progress at least every 7 business days for Critical/High severity issues
+- We will notify the reporter when a fix is released
+- After 90 days, we will publish a security advisory regardless of fix status
+
+We may request an extension if the fix requires significant infrastructure changes, and we will coordinate with the reporter before any deadline extension.
+
+## Safe Harbor
+
+We will not pursue legal action against researchers who follow this disclosure policy and act in good faith. We consider security research conducted in accordance with this policy to be:
+- Conducted lawfully and in good faith under applicable EU law
+- Not subject to legal action by CRE8EVE Sp. z o.o.
+
+Safe harbor **does not extend to**:
+- Accessing or modifying other users' data
+- Performing denial of service attacks
+- Social engineering employees or users
+- Exfiltrating data beyond what is necessary to demonstrate the vulnerability
+- Any activity that violates applicable law
+
+## Scope
+
+**In scope:**
+- `@rakomi/node`, `@rakomi/sdk-core`, `@rakomi/react`, and `@rakomi/react-native` SDK source code and published npm packages
+- Security properties of API interactions initiated by the SDKs (request signing, token verification, credential handling)
+- Authentication flow logic within the SDKs
+
+**Out of scope:**
+- Social engineering attacks against Rakomi employees or users
+- Denial of service attacks
+- Physical security
+- Vulnerabilities in third-party services used by Rakomi's backend
+- Vulnerabilities in peer dependencies (e.g., React) — reported to the relevant maintainer, but Rakomi will update minimum peer dependency versions when a peer dependency has a known critical CVE affecting SDK users
+
+This policy applies to the official `@rakomi/node`, `@rakomi/sdk-core`, `@rakomi/react`, and `@rakomi/react-native` packages distributed via npmjs.com. Forks and derivatives are maintained by their respective authors. Customers in regulated sectors (healthcare, finance) may have additional notification obligations beyond this general policy — contact security@rakomi.com for sector-specific compliance documentation.
+
+## EU Authority Reporting
+
+It is our **policy** to report actively exploited vulnerabilities and severe security incidents
+having an impact on the security of our products to the relevant EU authority in accordance with
+**CRA Art. 14**, on the statutory timeline: an early warning, followed by a fuller notification, and
+a final report.
+
+We report to the national coordinator CSIRT designated for our Member State of main establishment
+(Poland), which is our live reporting channel today; onboarding to the EU single reporting platform
+is in progress, and that platform is the documented onward path as it becomes available to
+manufacturers.
+
+## Security Update Notifications
+
+Consumers of Rakomi SDKs can receive security update notifications through:
+- **GitHub Security Advisories** on this repository (subscribe via GitHub "Watch" → "Security alerts")
+- **npm audit:** `npm audit` or `pnpm audit` will flag known vulnerabilities in installed versions
+
+In accordance with CRA Art. 14(8), after becoming aware of an actively exploited vulnerability or a severe incident having an impact on the security of our products, we will inform impacted users (and, where appropriate, all users) — together with any available risk-mitigation or corrective measures — through the above channels.
+
+## Manufacturer Identification
+
+**Legal entity:** CRE8EVE Sp. z o.o.
+**Registered address:** Tulipanowa 4, 72-003 Dobra, Poland (EU)
+**Contact:** security@rakomi.com (role-based — no personal mailbox or phone is published)
+**Products covered:** `@rakomi/node`, `@rakomi/sdk-core`, `@rakomi/react`, `@rakomi/react-native` (published on npmjs.com)
+
+The manufacturer is itself EU-established (Poland), so no CRA Art. 18 Authorised Representative is required (Art. 18 applies to manufacturers established outside the Union). CRA conformity assessment (Art. 32): these are Class I important products (Annex III). The internal-control procedure (Annex VIII, Module A — manufacturer self-assessment, no notified-body involvement) is available for a Class I product **only where harmonised standards, common specifications, or a European cybersecurity certification scheme at assurance level at least 'substantial' are applied in full** (Art. 32(2)); otherwise a third-party route — EU-type examination plus conformity to type (modules B+C), or full quality assurance (module H) — is required. The applicable route will be confirmed against the harmonised standards in force at the CRA application date. The EU Declaration of Conformity and CE marking attach at the CRA application date (Dec 2027) and are not yet issued. See the full manufacturer record at https://docs.rakomi.dev/compliance/manufacturer/.
+
+## Export Control / Cryptography Notice
+
+The four `@rakomi/*` SDK packages incorporate and invoke cryptography — they verify asymmetric
+digital signatures (JWT/token verification), compare key material in constant time, and rely on the
+host platform's TLS for transport security. They are distributed as **publicly available, mass-market
+software** with cryptographic functionality the end user cannot readily modify.
+
+- **EU — Regulation (EU) 2021/821 (Dual-Use):** the SDKs qualify for the **mass-market** treatment
+  under the Cryptography Note (Note 3) to Category 5, Part 2 of Annex I — generally available to the
+  public, sold without restriction, and not designed for the user to alter the cryptographic
+  functionality. No export authorisation is required for their distribution within or from the EU, and —
+  unlike the US path — the EU decontrol is **self-executing**, with no notification or filing step.
+- **US — Export Administration Regulations (EAR):** the cryptographic functionality is classifiable
+  under **ECCN 5D002**. As **publicly available** open-source software the source code is **not
+  subject to the EAR** (15 CFR §734.7(a)), and the corresponding object code is distributed under the
+  mass-market provisions. The one-time email notification of the public source-code URL to the U.S.
+  BIS and NSA is filed at first public release (15 CFR §742.15(b)).
+
+This notice is provided for transparency and is **not legal advice**. Downstream redistributors are
+responsible for their own export, import, and use obligations in their jurisdiction.
+
+## Post-Market Surveillance
+
+Rakomi monitors SDK health after release through:
+- Automated dependency vulnerability scanning (npm audit, Dependabot)
+- Runtime error patterns derived from API logs (SDK version reported in User-Agent header)
+- Periodic security review of SDK code per the internal security review process
+
+This constitutes the "effective and regular tests and reviews of the security of the product with digital elements" required under CRA Annex I, Part II, point (3). The coordinated-vulnerability-disclosure policy required under CRA Annex I, Part II, point (5) is set out in the "Coordinated Vulnerability Disclosure (CVD) Policy" section above.
+
+## No Bounty Program
+
+Rakomi does not currently operate a paid bug bounty program. We deeply appreciate responsible disclosure and will acknowledge researchers in security advisories (with their consent).
+
+## Reference: security.txt
+
+This policy is referenced in our machine-readable security contact file (RFC 9116):
+`/.well-known/security.txt` — deployed at `https://rakomi.com/.well-known/security.txt`
+
+---
+
+## What to Include in Your Report
+
+*(ISO/IEC 29147:2018 §6.5)*
+
+To help us triage efficiently, please include:
+
+1. **Affected package** name and version (e.g., @rakomi/node 0.2.0)
+2. **Reproduction steps** — a minimal, reproducible example
+3. **Impact assessment** — what an attacker could achieve
+4. **Proof of concept** — if available (do not use real user data)
+5. **Reporter contact** — so we can keep you updated
+
+Reports that do not include reproduction steps or fall outside the defined scope may be closed without a tracking ID.
+
+## Report Tracking
+
+*(ISO/IEC 29147:2018 §6.6)*
+
+Each report receives a unique tracking identifier upon acknowledgment. For reports submitted via GitHub Private Vulnerability Reporting, the GHSA identifier (e.g., GHSA-xxxx-xxxx-xxxx) serves as the tracking ID. For email reports, we will direct you to also submit via GitHub PVR for formal tracking.
+
+## Status Updates
+
+*(ISO/IEC 29147:2018 §6.4)*
+
+We provide status updates at least every **7 business days** for Critical/High severity issues, and upon resolution for Medium/Low severity issues.
+
+## CVE Assignment
+
+Confirmed vulnerabilities with sufficient impact will receive CVE identifiers via GitHub's CNA (CVE Numbering Authority) program.
+
+## Reporter Data Privacy
+
+*(GDPR Art. 6(1)(f) + Art. 13/14)*
+
+Reporter personal data (name, email) is processed under GDPR Art. 6(1)(f) legitimate interest for vulnerability coordination. This data is:
+- Retained for the duration of the vulnerability lifecycle plus 2 years
+- Not shared with third parties except as required for CVE assignment or regulatory reporting (e.g., ENISA, national CSIRT)
+- Accessible to the reporter upon request (GDPR Art. 15)
+- Deletable upon request after vulnerability closure (GDPR Art. 17, where not overridden by regulatory retention obligations)
+
+To exercise your GDPR rights, contact security@rakomi.com.
+
+## PGP Key Fingerprint
+
+The PGP public key for encrypted communication is available at:
+`https://rakomi.com/rakomi-security-pgp-key.asc`
+
+Verify the key fingerprint through an independent channel (e.g., LinkedIn, Twitter/X, or a direct phone call) before sending sensitive information.