@dotrino/identity 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 seyacat
+
+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

@@ -0,0 +1,166 @@
+# @dotrino/identity
+
+Identidad de usuario y rating de peers compartidos entre las apps de Dotrino. Funciona aunque las apps vivan en orígenes distintos: usa un **vault iframe** alojado en un origin estable que guarda la información en su propio `localStorage` y expone una API por `postMessage`.
+
+## Cómo funciona
+
+```
+┌────────────────────┐    postMessage    ┌────────────────────────┐
+│  app (cualquier    │ ◀───────────────▶ │  vault iframe          │
+│  origin: chat,     │                   │  origin: id.closer     │
+│  qrshare, chess…)  │                   │  .click                │
+│                    │                   │  - keypair ECDSA P-256 │
+│  import {Identity} │                   │  - keypair ECDH P-256  │
+└────────────────────┘                   │  - peers + ratings     │
+                                         └────────────────────────┘
+```
+
+Como todas las apps cargan el vault desde el mismo origin, comparten el mismo `localStorage` aunque ellas estén en orígenes distintos. **Las claves privadas nunca salen del vault** — las apps reciben firmas (de la ECDSA) y plaintext descifrado (de la ECDH) pero nunca las llaves.
+
+## Instalación
+
+```bash
+npm install @dotrino/identity
+```
+
+## Uso
+
+```js
+import { Identity } from '@dotrino/identity'
+
+const id = await Identity.connect({
+  vaultUrl: 'https://id.dotrino.com/'   // por defecto
+})
+
+console.log('my publickey JWK:', id.me.publickey)
+
+// Identificar a un peer (handshake challenge/response)
+const { nonce } = await id.makeChallenge()
+// envía nonce al peer por el canal que sea (proxy, postMessage, etc.)
+// el peer ejecuta await id.signChallenge(nonce) y te devuelve { nonce, publickey, signature }
+const verification = await id.verifyResponse(response)
+if (verification.ok) {
+  console.log('peer verificado:', verification.publickey)
+  await id.setNickname(verification.publickey, 'Bob de chess')
+  await id.setRating(verification.publickey, 4, 'buen rival')
+}
+
+const peers = await id.listPeers()
+```
+
+## Hosting del vault
+
+Para que distintas apps compartan datos, todas deben apuntar al **mismo `vaultUrl`**. La carpeta `vault/` de este paquete es un sitio estático (HTML + JS) listo para subir a:
+
+- Un dominio dedicado: `id.dotrino.com`
+- O temporalmente: `https://id.dotrino.com/vault/`
+
+Importante: subir vía HTTPS y configurar `Content-Security-Policy: frame-ancestors *` (o lista de orígenes permitidos) para permitir que las apps lo embeban.
+
+## API
+
+### `Identity.connect(options?)`
+Inicializa el iframe y resuelve cuando el vault está listo.
+
+| opción       | tipo     | default                       |
+|--------------|----------|-------------------------------|
+| `vaultUrl`   | string   | `https://id.dotrino.com/` |
+| `timeoutMs`  | number   | `5000`                        |
+
+### Identidad propia
+
+- `id.me`                            → `{ publickey, nickname? }`
+- `id.setMyNickname(nickname)`
+
+### Handshake
+
+- `id.makeChallenge()`               → `{ nonce }`
+- `id.signChallenge(nonce)`          → `{ nonce, publickey, encryptionPubkey, signature }`
+- `id.verifyResponse(response)`      → `{ ok, publickey?, encryptionPubkey?, peer? }`
+
+### Peer book
+
+- `id.getPeer(publickey)`
+- `id.setNickname(publickey, nickname)`
+- `id.setRating(publickey, rating, notes?)` — produce un envelope firmado y lo guarda como `peer.myRating` (rating 0–5).
+- `id.mergeEndorsements(subject, [signedRatings], askerPubkey?)` — para web-of-trust: valida firmas, dedupea por `(ratedBy, subject)`, cap 50.
+- `id.getRatingsForSubject(subject)` → `{ mine, endorsements }` para responder a un `RATING_QUERY`.
+- `id.recordQuery(askerPubkey, subject?)` — contabiliza consultas para el suspicion modifier.
+- `id.listPeers()`, `id.forgetPeer(publickey)`
+
+### Contactos compartidos (0.6.0+)
+
+Mismo registro de `peers` que arriba, pero filtrado por flag `isContact: true`. Cualquier app del ecosistema (chat, chess, messenger, extensión) puede añadir/leer contactos del mismo address book.
+
+- `id.addContact({ publickey, nickname?, encryptionPubkey?, lastToken?, notes? })`
+- `id.updateContact(publickey, patch)` — patch limitado a `nickname`, `encryptionPubkey`, `lastToken`, `contactNotes`.
+- `id.removeContact(publickey)` — quita el flag `isContact` pero conserva ratings/endorsements.
+- `id.listContacts()` → array filtrado, ordenado por `lastSeen` desc.
+
+### Encripción E2E (0.5.0+)
+
+- `id.getEncryptionPubkey()` → JWK string del propio peer.
+- `id.encrypt(recipients, plaintext)` → `{v:1, iv, ct, wrap}` envelope. `recipients` = `[{token, encryptionPubkey}]`. AES-256-GCM con clave efímera por mensaje, envuelta para cada destinatario vía ECDH(P-256). El campo `token` puede ser cualquier identificador estable (en messenger se usa la pubkey del destinatario para sobrevivir cambios de token del proxy).
+- `id.decrypt(senderEncryptionPubkey, myToken, envelope)` → `{ plaintext }`. Forward-secrecy por mensaje (clave simétrica nueva cada vez).
+
+### Firma genérica (0.7.0+)
+
+- `id.signData(data)` → `{ signature, publickey }` con encoding canonical-JSON. Lo usa el messenger para construir sobres `identify` que el proxy verifica con su `verifySignatureWithJWK`.
+
+### Backup / migración
+
+- `id.exportIdentity()` → blob JSON con `privateJwk` (ECDSA), `encPrivateJwk` (ECDH), `me`, `peers`. **Sensible** — el host app es responsable de guardarlo de manera segura.
+- `id.importIdentity(blob)` → reemplaza la identidad local. Soporta blobs v1 (sin ECDH) y v2 (con ambas keys).
+
+### Auto-sync con Google Drive (0.8.0+)
+
+Backup automático y sincronización multi-dispositivo de la identidad (claves + contactos + ratings + endorsements) usando Google Drive como almacén opaco. **Google nunca ve tus datos en claro**: el blob se cifra en el navegador con AES-256-GCM y una clave derivada por PBKDF2 (600 000 iteraciones) de una passphrase elegida por el usuario.
+
+Topología:
+- El blob se guarda en la carpeta especial `appDataFolder` de Drive (oculta para el usuario, no contamina su Drive).
+- Scope OAuth requerido: solo `https://www.googleapis.com/auth/drive.appdata`.
+- El cliente OAuth (Google Cloud Console → Web application) debe tener `https://id.dotrino.com` (y/o `http://localhost:5173` para dev) como Authorized JavaScript Origin.
+- El sync corre **dentro del iframe del vault**: las claves privadas nunca cruzan el postMessage boundary.
+
+```js
+// 1. Conectar Google (popup OAuth, una vez por origen)
+await id.syncConnect('123456789-abc...apps.googleusercontent.com')
+
+// 2. Desbloquear con passphrase (≥12 chars). Se guarda en sessionStorage del vault
+//    (per-tab) y se borra al cerrar la pestaña.
+await id.syncUnlock('mi-passphrase-larga-y-secreta')
+
+// 3. A partir de aquí: pull-on-unlock + push debounced (5s) + pull periódico (2 min).
+//    Cualquier mutación local (setRating, addContact, mergeEndorsements...) marca
+//    dirty automáticamente.
+
+// Eventos de estado
+id.onSync(({ status, error }) => console.log('sync:', status, error || ''))
+// status: connected | unlocked | syncing | synced | conflict | offline | error | locked | disconnected
+
+// Forzar pull+push inmediato
+await id.syncNow()
+
+// Bloquear (limpia la passphrase de memoria)
+await id.syncLock()
+```
+
+**Estrategia de merge** (al hacer pull, si remoto tiene cambios):
+- Keypairs ECDSA/ECDH: **nunca se sobreescriben**. Solo se adopta el remoto si local está vacío (primer setup en device nuevo).
+- Contact metadata (nickname, notes, encryptionPubkey, rating): last-writer-wins por `lastSeen`.
+- `myRating`: el envelope firmado con mayor `issuedAt` gana.
+- `endorsements`: unión dedup por `ratedBy`; firmas re-verificadas antes de aceptar.
+- Concurrencia: optimistic-lock con `If-Match: <etag>` en Drive. Si 412, pull → merge → push (3 reintentos).
+
+**Trade-off**: si el usuario pierde la passphrase, el blob es irrecuperable. Es coherente con E2E — ni Google ni el desarrollador pueden recuperarlo.
+
+## Diseño
+
+- **Una sola identidad por navegador**, persistente entre apps que apuntan al mismo vault.
+- **Sin servidor**: todo en `localStorage` del vault.
+- **Replay protection**: cada `makeChallenge` registra el nonce; `verifyResponse` exige que el nonce sea reciente (≤ 5 min).
+- **Privacidad**: la clave privada vive solo en el vault, las apps nunca la ven.
+
+## Licencia
+
+MIT

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@dotrino/identity",
+  "version": "0.10.0",
+  "description": "Identidad y rating de usuarios compartidos entre apps de Dotrino (vault iframe + postMessage)",
+  "type": "module",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./node": {
+      "import": "./src/node.js"
+    },
+    "./capabilities": {
+      "import": "./vault/capabilities.js"
+    },
+    "./vault/core.js": "./vault/core.js"
+  },
+  "files": [
+    "src",
+    "vault",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "identity",
+    "rating",
+    "dotrino",
+    "vault",
+    "cross-origin"
+  ],
+  "author": "seyacat",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imdotrino/dotrino-identity.git"
+  },
+  "devDependencies": {
+    "fake-indexeddb": "^6.2.5"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,187 @@
+export interface IdentityOptions {
+  vaultUrl?: string
+  timeoutMs?: number
+}
+
+export interface Me {
+  publickey: string
+  encryptionPubkey?: string
+  nickname?: string
+}
+
+export interface EnvelopeV1 {
+  v: 1
+  iv: string
+  ct: string
+  wrap: Record<string, { iv: string; ct: string }>
+}
+
+export interface EncryptRecipient {
+  token: string
+  encryptionPubkey: string
+}
+
+export interface SignedRating {
+  subject: string
+  rating: number
+  notes: string
+  ratedBy: string
+  issuedAt: number
+  signature: string
+}
+
+export interface QueryStats {
+  queriesMade: number
+  queriesKnown: number
+}
+
+export interface PeerInfo {
+  publickey: string
+  encryptionPubkey?: string
+  nickname?: string
+  rating?: number
+  notes?: string
+  myRating?: SignedRating | null
+  endorsements?: SignedRating[]
+  queryStats?: QueryStats
+  firstSeen?: number
+  lastSeen?: number
+}
+
+export interface Challenge {
+  nonce: string
+}
+
+export interface ChallengeResponse {
+  nonce: string
+  publickey: string
+  encryptionPubkey?: string
+  signature: string
+}
+
+export interface VerifyResult {
+  ok: boolean
+  publickey?: string
+  encryptionPubkey?: string | null
+  peer?: PeerInfo
+}
+
+export interface IdentityExport {
+  version: number
+  privateJwk: Record<string, any>
+  publicJwk: Record<string, any>
+  me: Me | null
+  peers: Record<string, PeerInfo>
+  exportedAt: string
+}
+
+export class Identity {
+  static connect (options?: IdentityOptions): Promise<Identity>
+  static current (): Identity | null
+  constructor (options?: IdentityOptions)
+  ready (): Promise<Identity>
+  destroy (): void
+  readonly me: Me | null
+  makeChallenge (): Promise<Challenge>
+  signChallenge (nonce: string): Promise<ChallengeResponse>
+  verifyResponse (response: ChallengeResponse): Promise<VerifyResult>
+  getPeer (publickey: string): Promise<PeerInfo | null>
+  setNickname (publickey: string, nickname: string): Promise<PeerInfo>
+  setRating (publickey: string, rating: number, notes?: string): Promise<PeerInfo>
+  listPeers (): Promise<PeerInfo[]>
+  forgetPeer (publickey: string): Promise<void>
+  addContact (input: {
+    publickey: string
+    nickname?: string
+    encryptionPubkey?: string
+    lastToken?: string
+    notes?: string
+  }): Promise<PeerInfo>
+  updateContact (
+    publickey: string,
+    patch: Partial<{ nickname: string; encryptionPubkey: string; lastToken: string; contactNotes: string }>
+  ): Promise<PeerInfo | null>
+  removeContact (publickey: string): Promise<PeerInfo | null>
+  listContacts (): Promise<PeerInfo[]>
+  signData (data: any): Promise<{ signature: string; publickey: string }>
+  setMyNickname (nickname: string): Promise<{ me: Me }>
+  getEncryptionPubkey (): Promise<string>
+  encrypt (recipients: EncryptRecipient[], plaintext: string): Promise<EnvelopeV1>
+  decrypt (
+    senderEncryptionPubkey: string,
+    myToken: string,
+    envelope: EnvelopeV1
+  ): Promise<{ plaintext: string }>
+  mergeEndorsements (
+    subject: string,
+    endorsements: SignedRating[],
+    askerPubkey?: string
+  ): Promise<{ merged: number; total: number }>
+  getRatingsForSubject (
+    subject: string
+  ): Promise<{ mine: SignedRating | null; endorsements: SignedRating[] }>
+  recordQuery (askerPubkey: string, subject?: string): Promise<PeerInfo | null>
+  /** Firma un certificado de delegación de capacidad para una sub-clave de dispositivo. */
+  signDelegation (sub: string, scope: string | string[], opts?: DelegationOpts): Promise<{ cert: CapabilityCert }>
+  /** Revoca una delegación por su nonce. */
+  revokeDelegation (nonce: string): Promise<{ ok: true; revokedAt: number }>
+  /** Lista las delegaciones emitidas + la lista de revocación. */
+  listDelegations (): Promise<{ issued: IssuedDelegation[]; revoked: { nonce: string; revokedAt: number }[] }>
+  exportIdentity (): Promise<IdentityExport>
+  importIdentity (blob: IdentityExport | Record<string, any>): Promise<{ me: Me }>
+  syncConnect (clientId: string): Promise<{ accessToken: string; expiresAt: number }>
+  syncDisconnect (): Promise<void>
+  syncUnlock (passphrase: string): Promise<{ ok: boolean }>
+  syncLock (): Promise<void>
+  syncStatus (): Promise<SyncStatus>
+  syncNow (): Promise<SyncStatus>
+  onSync (handler: (event: SyncEvent) => void): () => void
+  on (event: 'peer_updated' | 'me_updated' | 'sync', handler: (payload: any) => void): () => void
+}
+
+export interface SyncStatus {
+  kind?: 'identity' | 'store'
+  connected: boolean
+  unlocked: boolean
+  dirty: boolean
+  lastError?: string | null
+}
+
+export interface SyncEvent {
+  kind: 'identity' | 'store'
+  status: 'connected' | 'disconnected' | 'unlocked' | 'locked' | 'syncing' | 'synced' | 'conflict' | 'offline' | 'error'
+  error?: string
+  ts: number
+}
+
+// ----- delegación de capacidad (sub-clave de dispositivo con scope/exp/revocación) -----
+
+/** Certificado de delegación firmado por la maestra (`iss`) para una sub-clave (`sub`). */
+export interface CapabilityCert {
+  v: 1
+  iss: string            // pubkey JWK string de la identidad maestra (emisor)
+  sub: string            // pubkey JWK string de la clave de dispositivo (sujeto)
+  scope: string | string[]
+  iat: number            // ms epoch
+  exp: number            // ms epoch (tope MAX_DELEGATION_MS)
+  nonce: string          // mango de revocación
+  sig: string            // base64 de la firma cruda ECDSA de la maestra sobre el cuerpo canónico
+}
+export interface DelegationOpts { ttlMs?: number; exp?: number; nonce?: string; label?: string }
+export interface IssuedDelegation { nonce: string; sub: string; scope: string | string[]; iat: number; exp: number; label?: string; revokedAt?: number }
+/** Sub-clave de dispositivo generada localmente (la privada nunca va a la maestra). */
+export interface DeviceKey { publickey: string; privateJwk: JsonWebKey; publicJwk: JsonWebKey; label: string; createdAt: number; deviceId: string }
+
+export const MAX_DELEGATION_MS: number
+export const DEFAULT_DELEGATION_MS: number
+/** Genera una sub-clave de dispositivo `D` (corre EN el dispositivo). */
+export function makeDeviceKey (opts?: { label?: string }): Promise<DeviceKey>
+/** id corto y estable de un pubkey (sha-256 hex de los campos canónicos del JWK). */
+export function pubkeyId (publicJwkStr: string): Promise<string>
+/** Firma datos con una clave de dispositivo (formato byte-idéntico a signData). */
+export function signWithDevice (args: { privateJwk: JsonWebKey; data: any }): Promise<{ signature: string; publickey: string }>
+/** Verifica un certificado de delegación (firma de la maestra + exp + scope + sub + revocación). */
+export function verifyDelegation (args: { cert: CapabilityCert; expectedScope?: string; expectedSub?: string; now?: number; revoked?: ((nonce: string) => boolean) | Set<string> | Record<string, any> }): Promise<{ ok: boolean; reason?: string; iss?: string; sub?: string; scope?: string | string[]; iat?: number; exp?: number; nonce?: string }>
+/** Verifica la cadena de una acción/pin delegado: D firmó + cert prueba D←P + scope/exp/revocación. */
+export function verifyChain (args: { data: any; signature: string; cert: CapabilityCert; expectedScope?: string; trustedIssuer?: string; now?: number; revoked?: ((nonce: string) => boolean) | Set<string> | Record<string, any> }): Promise<{ ok: boolean; reason?: string; issuer?: string; device?: string }>
+