@neodaten/auth-native 0.0.0-stage → 0.0.1-reserva.0

package/README.md

@@ -1,3 +1,201 @@
-# Temporary Holding Version
+# @neodaten/auth-native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cliente de identidad para apps React Native del ecosistema. La app entra por el login hospedado del
+emisor del proyecto (`…/p/<slug>`) con `authorization_code` + PKCE S256 y renueva con el refresh
+rotativo. Sin dependencias: usa `fetch`, `crypto.getRandomValues` y un almacén seguro que inyecta la
+app.
+
+## Uso
+
+```ts
+import { crearClienteDeIdentidadNativa, type AlmacenSeguro } from '@neodaten/auth-native';
+
+const identidad = crearClienteDeIdentidadNativa({
+  emisor: 'https://auth.neodaten.com/p/luup',
+  coreApiUrl: 'https://auth.neodaten.com/api',
+  clienteId: 'luup-ios',
+  recurso: 'urn:neodaten:api:luup',
+  redireccion: 'com.crashapp.neodaten:/oauth/callback',
+  almacen,
+  proveedorDeAtestacion,
+});
+
+const login = await identidad.abrirLoginHospedado();
+login.url;
+login.decidir({ url, esMarcoPrincipal });
+await login.completar(urlDelRegreso);
+const token = await identidad.tokenDeAcceso();
+await identidad.cerrarSesion();
+```
+
+- `abrirLoginHospedado()` lee el discovery (el `issuer` tiene que ser el emisor configurado), genera
+  PKCE, `state` y `nonce`, y con `proveedorDeAtestacion` pide el ticket de atestación
+  (`/auth/atestacion/reto` y `/auth/atestacion/ticket`) y lo manda como `atestacion`. Sin proveedor
+  abre sin ticket.
+- `origenDelLogin` es el origen de login-web cuando no comparte host con el emisor (en local,
+  `http://localhost:3305`). Por omisión es el del emisor; tiene que ser https salvo localhost o
+  loopback con un emisor también local, y nunca se toma del regreso.
+- `decidir()` solo carga los orígenes del emisor, del `authorization_endpoint` y del login; Turnstile
+  (`challenges.cloudflare.com`) solo dentro de un iframe. El regreso a `redireccion` desde el marco
+  principal es el `callback`; lo demás se descarta.
+- `completar()` se usa una sola vez: valida `state` e `iss`, canjea el código con el
+  `code_verifier`, valida el id_token (firma ES256 con el JWKS del emisor, `iss`, `aud`/`azp`,
+  `nonce`, `exp`, `iat`, `sub`) y guarda la sesión en el almacén.
+- `cerrarSesion()` revoca el refresh y borra el almacén.
+- Firma: con `crypto.subtle` se verifica ES256 contra el JWKS del emisor. Sin él (Hermes) no se
+  verifica la firma y se confía en el TLS del canje (OIDC Core 3.1.3.7, punto 6): el id_token solo
+  se toma de la respuesta del endpoint de token (que tiene que ser https, salvo localhost con un
+  emisor también local), nunca de la URL, y se siguen exigiendo `iss`,
+  `aud`, `azp`, `nonce`, `exp` e `iat`. PKCE usa un SHA-256 propio. Solo hace falta
+  `crypto.getRandomValues`; sin él, `abrirLoginHospedado()` da `sin_criptografia`.
+- La aplicación tiene que ser NATIVE en la consola, con `<bundle>:/oauth/callback` como URL de
+  retorno y de cierre de sesión.
+
+## Pantalla
+
+```tsx
+import { PantallaDeLoginHospedado } from '@neodaten/auth-native/pantalla';
+
+<PantallaDeLoginHospedado
+  login={login}
+  alEntrar={() => navegar('inicio')}
+  alFallar={(error) => mostrar(error)}
+  alDescartarEnlace={(url) => registrar(url)}
+/>;
+```
+
+WebView a pantalla completa, incógnita, sin cache ni cookies compartidas, sin puente JS, sin
+ventanas nuevas ni archivos locales. Toda navegación pasa por `login.decidir()`
+(`originWhitelist: ['*']` para que react-native-webview no mande las URLs ajenas a
+`Linking.openURL`). Requiere `react` y `react-native-webview` >=13.15.0 <15 en la app.
+
+## Desbloqueo con Face ID, Touch ID o huella
+
+`AlmacenConDesbloqueo` extiende `AlmacenSeguro`: guarda la sesión en el llavero normal y, con el
+desbloqueo activo, mueve el refresh a un elemento del llavero que solo se abre con la biometría del
+set actual del dispositivo (`BIOMETRY_CURRENT_SET`, `WHEN_PASSCODE_SET_THIS_DEVICE_ONLY`). La app
+solo crea el almacén con el adaptador de su librería, se lo pasa al cliente y conecta un interruptor
+en Mi cuenta.
+
+```ts
+almacen.desbloqueoDisponible(); // Promise<boolean>: si es false, no se muestra el interruptor
+almacen.desbloqueoActivo(); // Promise<boolean>
+almacen.activarDesbloqueo(); // pide el biométrico y protege el refresh
+almacen.desactivarDesbloqueo(); // pide el biométrico y regresa el refresh al llavero normal
+almacen.bloquear(); // olvida el desbloqueo en memoria; la siguiente lectura vuelve a pedirlo
+```
+
+- Con el desbloqueo activo, la primera lectura de la sesión (`tokenDeAcceso()`, `renovar()`) pide
+  el biométrico una vez; mientras la app siga viva usa el refresh desbloqueado en memoria. Para
+  volver a pedirlo al regresar a primer plano, llama `almacen.bloquear()` desde `AppState`.
+- Si cancelan o el sistema rechaza el aviso, sale `ErrorDeIdentidad` con `desbloqueo_cancelado`: la
+  sesión se conserva y la app ofrece `TEXTOS_DEL_DESBLOQUEO.entrarConCodigo`, que abre el login
+  hospedado.
+- Si el sistema invalidó la llave (cambiaron los rostros o las huellas), sale
+  `desbloqueo_invalidado`: el paquete ya borró la sesión local y la app manda al login.
+- `cerrarSesion()` borra todo y apaga el desbloqueo. Si no confirman el biométrico, igual borra la
+  sesión local, solo que no puede revocar el refresh.
+- Errores al activar: `desbloqueo_no_disponible` (sin biometría), `sin_sesion` y
+  `desbloqueo_cancelado`. `esErrorDeDesbloqueo(error)` reconoce los dos de la lectura.
+- Con expo-secure-store en Android, guardar en el elemento protegido también pide el biométrico, así
+  que cada rotación del refresh con el desbloqueo activo lo vuelve a pedir. En iOS no: el elemento se
+  borra y se crea de nuevo, y crear no pide autenticación.
+- Con react-native-keychain en Android, una llave invalidada se reporta igual que una cancelación:
+  llega como `desbloqueo_cancelado` y se resuelve al entrar con código, que reemplaza la llave.
+
+Los textos (`TEXTOS_DEL_DESBLOQUEO`) están en español de México y cada adaptador acepta los propios
+como segundo argumento:
+
+```ts
+import { TEXTOS_DEL_DESBLOQUEO } from '@neodaten/auth-native';
+
+const textos = { ...TEXTOS_DEL_DESBLOQUEO, motivo: 'Confirma que eres tú para ver tus pedidos.' };
+```
+
+### App Expo (COMA, conductor de OneChain, Baki, PROTEQA)
+
+```ts
+import * as SecureStore from 'expo-secure-store';
+import { crearAlmacenExpo } from '@neodaten/auth-native/expo';
+
+const almacen = crearAlmacenExpo(SecureStore);
+const identidad = crearClienteDeIdentidadNativa({ ...opciones, almacen });
+```
+
+Usa `requireAuthentication: true`, `keychainAccessible: WHEN_PASSCODE_SET_THIS_DEVICE_ONLY` y
+`authenticationPrompt` con el motivo; la disponibilidad sale de `canUseBiometricAuthentication()`.
+En `app.json`, el plugin declara el texto de Face ID:
+
+```json
+[
+  "expo-secure-store",
+  { "faceIDPermission": "Usamos Face ID para que entres a tu cuenta sin escribir un código." }
+]
+```
+
+### App RN CLI (Luup)
+
+```ts
+import * as Keychain from 'react-native-keychain';
+import { crearAlmacenKeychain } from '@neodaten/auth-native/keychain';
+
+const almacen = crearAlmacenKeychain(Keychain);
+const identidad = crearClienteDeIdentidadNativa({ ...opciones, almacen });
+```
+
+Usa `accessControl: BIOMETRY_CURRENT_SET`, `accessible: WHEN_PASSCODE_SET_THIS_DEVICE_ONLY` y, en
+Android, `storage: STORAGE_TYPE.RSA`: se cifra con la llave pública sin pedir el biométrico y solo
+descifrar lo pide, así la rotación del refresh no interrumpe. El valor cabe en un bloque RSA de 2048
+bits (hasta 245 bytes). La llave de Android que crea la librería acepta también el código del
+dispositivo y no se invalida al cambiar las huellas. La disponibilidad sale de `getSupportedBiometryType()`. En `ios/<App>/Info.plist`:
+
+```xml
+<key>NSFaceIDUsageDescription</key>
+<string>Usamos Face ID para que entres a tu cuenta sin escribir un código.</string>
+```
+
+Ninguna de las dos entradas suma dependencias: la app inyecta el módulo y el paquete lo tipa con una
+interfaz que coincide con su API pública.
+
+## Bienvenida con la última cuenta y passkey
+
+Después de «Salir», la bienvenida saluda a la última cuenta y entra con la passkey del sistema (Face ID, Touch ID o huella) sin abrir el login hospedado. La passkey se sigue creando en el login hospedado, con la oferta que aparece tras el SMS.
+
+**Requisitos en el core:**
+
+- la aplicación nativa de primera parte tiene `settings.passkeyEnLaBienvenida`;
+- el proyecto admite passkey como primer factor.
+
+**El cliente recibe un `ProveedorDePasskey`:**
+
+- `biometria()` devuelve `'rostro' | 'huella' | 'otra'`, o `null` si el sistema no admite passkeys;
+- `firmar(opcionesJson)` recibe `PublicKeyCredentialRequestOptionsJSON` y devuelve el `AuthenticationResponseJSON` como texto. Si la persona cancela, rechaza con `ErrorDeIdentidad('acceso_cancelado')`. Si no hay credencial en el dispositivo, rechaza con `ErrorDeIdentidad('sin_passkey')`.
+
+```ts
+const cliente = crearClienteDeIdentidadNativa({ ...opciones, proveedorDePasskey });
+const { estado, entrando, error, entrarConPasskey, usarOtraCuenta } = useBienvenida(cliente);
+const resultado = await entrarConPasskey();
+```
+
+Qué significa cada `resultado`:
+
+- `'dentro'`: la sesión ya está guardada.
+- `'cancelado'`: no se hace nada.
+- `'abrir_login'`: se abre el login hospedado.
+- `'reintentar'`: hay que mostrar `error`.
+
+**Qué se guarda y cuándo se borra:**
+
+- La última cuenta (`neodaten.ultima-cuenta`) guarda solo `sub`, nombre, el teléfono enmascarado a cuatro dígitos y `tienePasskey`.
+- Se escribe en cada login y en cada renovación.
+- `cerrarSesion()` la conserva y `usarOtraCuenta()` la borra.
+- Los alcances por omisión incluyen `profile phone` para que el `id_token` traiga el nombre, el teléfono y `tiene_passkey`.
+
+El contrato completo del reto y del grant `urn:neodaten:grant-type:passkey` está en la descripción OpenAPI de `POST /api/oidc/{proyecto}/nativa/passkey/reto`.
+
+## Publicación
+
+`pnpm --filter @neodaten/auth-native empaquetar` compila a `dist/` con `tsc`. El workflow
+`publicar-auth-native.yml` publica en npm con procedencia al empujar el tag `auth-native-v<versión>`
+sobre un commit de `main`; la versión del tag tiene que coincidir con la de `package.json`. En npm
+hay que dar de alta la publicación de confianza para este paquete y este workflow.

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@neodaten/auth-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1-reserva.0",
+  "type": "module",
+  "description": "Cliente de identidad para apps React Native: login hospedado con código y PKCE, refresh rotativo y almacén seguro inyectado.",
+  "sideEffects": false,
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./pantalla": "./src/pantalla/index.ts",
+    "./expo": "./src/expo/index.ts",
+    "./keychain": "./src/keychain/index.ts",
+    "./bienvenida": "./src/bienvenida/index.ts"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Neodaten/n360.git",
+    "directory": "packages/auth-native"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      },
+      "./pantalla": {
+        "types": "./dist/pantalla/index.d.ts",
+        "import": "./dist/pantalla/index.js"
+      },
+      "./expo": {
+        "types": "./dist/expo/index.d.ts",
+        "import": "./dist/expo/index.js"
+      },
+      "./keychain": {
+        "types": "./dist/keychain/index.d.ts",
+        "import": "./dist/keychain/index.js"
+      },
+      "./bienvenida": {
+        "types": "./dist/bienvenida/index.d.ts",
+        "import": "./dist/bienvenida/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "empaquetar": "tsc -p tsconfig.empaquetado.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "react": "catalog:",
+    "react-native-webview": ">=13.15.0 <15",
+    "react-native": ">=0.80.0"
+  },
+  "devDependencies": {
+    "@neodaten/eslint-config": "workspace:*",
+    "@neodaten/tsconfig": "workspace:*",
+    "@types/react": "catalog:",
+    "react": "catalog:",
+    "react-native": "0.86.3",
+    "react-native-webview": "14.0.1",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}