@dotrino/identity 0.83.1 → 0.85.0

package/README.md

@@ -143,6 +143,54 @@ const v = await verifyAssertion(prueba, { audience: 'https://proxy.dotrino.com',
 - **Verificar no necesita el iframe ni clave alguna**: `@dotrino/identity/assertion` es un
   módulo puro y lo puede importar un servidor.
 
+**Y su hermana, para lo que se publica** (0.84.0+). Un pin de geo o una atestación de
+reputación se firman y se sueltan: no hay nadie al otro lado que pueda dar un reto de
+antemano, así que ahí no cabe una prueba entera — lo que falta es el destinatario, y solo
+eso. Sin él, un pin firmado para geo lo acepta igual reputación.
+
+```js
+import { verifySignedFor } from '@dotrino/identity/assertion'
+
+const pin = { op: 'pin', aud: 'https://geo.dotrino.com', lat, lon, iat: Date.now() }
+const { signature, publickey, chain } = await id.signData(pin)
+// en el servidor:
+const v = await verifySignedFor({ data: pin, signature, publickey, chain, audience: 'https://geo.dotrino.com' })
+```
+
+`aud` es obligatorio igual que en la prueba; `exp` es opcional, porque la caducidad de lo
+publicado la lleva el servicio (el TTL del pin) y no el cuerpo.
+
+### Entrar sin enrolar: las sesiones (0.85.0+)
+
+Enlazar un aparato y entrar en uno no son lo mismo. Enlazar mete una llave en el acta —hay
+que sellarla, o sea despertar a la selladora y tener el perfil abierto— y salir es sellar
+otra vez. Nadie hace eso para abrir una aplicación en un navegador prestado.
+
+Una **sesión** es la otra puerta: una llave que vive en ese navegador y un **papel** con
+vencimiento que la respalda, firmado por un aparato tuyo que sí está en el acta.
+
+```js
+import { openSession } from '@dotrino/identity/session-flow'   // el que entra
+import { grantSession } from '@dotrino/identity/session-flow'  // el que respalda
+import { verifySession } from '@dotrino/identity/session'      // quien recibe algo suyo
+```
+
+El QR va **al revés** que en el emparejamiento: lo muestra quien quiere entrar, y lo escanea
+el teléfono — quien entra puede no tener cámara, el teléfono siempre la tiene.
+
+Lo que hace que esto no sea una llave maestra de repuesto:
+
+- **Nunca amplía**: cada alcance exige que el aparato que firmó lo tenga **hoy**, y se
+  comprueba contra el acta al verificar, no solo al emitir.
+- **Lista negra fija**: jamás `secrets`, `admin`, `approve`, `sealer`, `passwords`,
+  `unattended` ni `replica`, aunque el aparato los tenga.
+- **Vence por reloj** (8 h por defecto, tope 24). Es la excepción deliberada a *los papeles
+  ya no caducan por reloj*: un certificado describe pertenencia, que dura; una sesión **es**
+  temporal.
+- **Muere con su aparato**: si quitas del acta al que la respalda, sus sesiones caen solas.
+  Sin avisar a nadie ni perseguir papeles.
+- **No se re-delega**: una sesión no abre otra sesión.
+
 Diseño y hacia dónde va (inicio de sesión y federación):
 [`dotrino-vault/docs/inicio-de-sesion.md`](../dotrino-vault/docs/inicio-de-sesion.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotrino/identity",
-  "version": "0.83.1",
+  "version": "0.85.0",
   "description": "Identidad y rating de usuarios compartidos entre apps de Dotrino (vault iframe + postMessage)",
   "type": "module",
   "main": "src/index.js",
@@ -33,6 +33,12 @@
     },
     "./keyid": {
       "import": "./vault/keyid.js"
+    },
+    "./session": {
+      "import": "./vault/session.js"
+    },
+    "./session-flow": {
+      "import": "./vault/sessionFlow.js"
     }
   },
   "files": [

package/src/index.d.ts

@@ -270,3 +270,47 @@ export function claimsAllowed (scopes?: string[]): Set<string>
 export function assertionBody (args: { sub: string; aud: string; nonce: string; scopes?: string[]; claims?: AssertionClaims; iat: number; exp: number }): Omit<Assertion, 'signature' | 'publickey' | 'chain'>
 /** ¿Vale esta prueba, PARA MÍ y AHORA? `audience` y `nonce` son obligatorios; sin modo permisivo. */
 export function verifyAssertion (assertion: Assertion, opts: { audience: string; nonce: string; expectedProfileId?: string | null; now?: number; maxSkewMs?: number }): Promise<VerifiedAssertion>
+/** ¿Este contenido firmado (un pin, una atestación) va dirigido a mí? `aud` obligatorio; `exp` opcional. */
+export function verifySignedFor (args: { data: any; signature: string; publickey: string; chain: any[]; audience: string; expectedProfileId?: string | null; now?: number; maxSkewMs?: number }): Promise<{ ok: boolean; reason?: string; profileId?: string; signer?: string; seq?: number; aud?: string }>
+
+// ----- Sesiones: entrar sin enrolar (`@dotrino/identity/session`) -----
+
+export type SessionScope = 'id:whoami' | 'vault:store'
+
+export interface SessionPaper {
+  v: 1
+  op: 'session'
+  sid: string        // el identificador que el usuario ve para poder cerrarla
+  s: string          // pubkey de la sesión (vive en el aparato prestado)
+  by: string         // pubkey del aparato que la respalda (miembro del acta)
+  origin: string     // dónde vale
+  scopes: SessionScope[]
+  iat: number
+  exp: number        // vence por reloj: una sesión ES temporal
+  sig: string        // firma del aparato que respalda
+}
+
+export interface VerifiedSession {
+  ok: boolean
+  reason?: string
+  profileId?: string
+  seq?: number
+  sid?: string
+  s?: string
+  by?: string
+  origin?: string
+  scopes?: SessionScope[]
+  exp?: number
+}
+
+export const SESSION_SCOPES: readonly SessionScope[]
+export const SESSION_FORBIDDEN: readonly string[]
+export const SESSION_DEFAULT_TTL_MS: number
+export const SESSION_MAX_TTL_MS: number
+export function newSessionId (): string
+export function cleanSessionScopes (scopes?: string[]): SessionScope[]
+export function signSession (args: { sid: string; s: string; by: string; origin: string; scopes?: string[]; ttlMs?: number; now?: number }, sign: (body: any) => Promise<any>): Promise<SessionPaper>
+/** ¿Vale este papel AHORA? La cadena de actas es obligatoria: sin ella no se puede juzgar. */
+export function verifySession (paper: SessionPaper, opts: { chain: any[]; expectedProfileId?: string | null; origin?: string | null; now?: number; maxSkewMs?: number }): Promise<VerifiedSession>
+/** ¿Firmó esta sesión esto, y su papel lo cubría? */
+export function verifySessionSigned (args: { data: any; signature: string; session: SessionPaper; chain: any[]; scope?: SessionScope | null; origin?: string | null; expectedProfileId?: string | null; now?: number }): Promise<VerifiedSession>

package/src/index.js

@@ -740,4 +740,4 @@ export { makeDeviceKey, makeDeviceEncKey, importDeviceEncKey, signWithDevice, ve
 // PARA QUIÉN vale una firma, y hasta cuándo. Verificar NO necesita el iframe ni la clave
 // de nadie, así que un servicio puede importarlo suelto (`@dotrino/identity/assertion`, que
 // no arrastra el cliente del vault); aquí se reexporta para quien ya tiene esto cargado.
-export { verifyAssertion, newAssertionNonce, cleanScopes, claimsAllowed, assertionBody, SCOPES, SCOPE_CLAIMS, ASSERTION_MAX_TTL_MS, ASSERTION_DEFAULT_TTL_MS, ASSERTION_MAX_SKEW_MS } from '../vault/assertion.js'
+export { verifyAssertion, verifySignedFor, newAssertionNonce, cleanScopes, claimsAllowed, assertionBody, SCOPES, SCOPE_CLAIMS, ASSERTION_MAX_TTL_MS, ASSERTION_DEFAULT_TTL_MS, ASSERTION_MAX_SKEW_MS } from '../vault/assertion.js'

package/vault/assertion.js

@@ -174,4 +174,42 @@ export async function verifyAssertion (assertion, opts = {}) {
   return { ok: true, profileId: v.profileId, signer: v.signer, seq: v.seq, scopes: [...a.scopes], claims: { ...(a.claims || {}) }, aud: a.aud, exp: a.exp }
 }
 
-export default { ASSERTION_V, ASSERTION_MAX_TTL_MS, ASSERTION_DEFAULT_TTL_MS, ASSERTION_MAX_SKEW_MS, SCOPES, SCOPE_CLAIMS, newAssertionNonce, cleanScopes, claimsAllowed, assertionBody, verifyAssertion }
+/**
+ * ¿ESTE CONTENIDO FIRMADO VA DIRIGIDO A MÍ? La otra mitad del destinatario, y **no es lo
+ * mismo que una prueba**: conviene tener claras las dos, porque confundirlas lleva a pedir
+ * un reto donde no hay quien lo emita.
+ *
+ *   · **Prueba** (`verifyAssertion`) — autenticación INTERACTIVA: alguien me habla, yo le
+ *     mando un reto y quiero saber quién es AHORA. Lleva `nonce` porque hay dos partes.
+ *   · **Contenido dirigido** (esto) — un pin de geo, una atestación de reputación: se
+ *     firma y se publica, sin nadie al otro lado que pueda dar un reto de antemano. Lo que
+ *     falta ahí es `aud`, y solo `aud`: sin él, un pin firmado para geo lo acepta igual
+ *     reputación.
+ *
+ * `aud` es obligatorio, como en la prueba. `exp` es OPCIONAL, y esa es la diferencia real:
+ * lo publicado tiene su propia caducidad (el TTL del pin, la vigencia de la atestación) y
+ * quien la lleva es el servicio; si el cuerpo trae `exp`, se respeta.
+ */
+/**
+ * @param {{ data?: any, signature?: string, publickey?: string, chain?: any[], audience?: string, expectedProfileId?: string|null, now?: number, maxSkewMs?: number }} [args]
+ */
+export async function verifySignedFor (args = {}) {
+  const { data, signature, publickey, chain, audience, expectedProfileId = null, now = Date.now(), maxSkewMs = ASSERTION_MAX_SKEW_MS } = args
+  if (typeof audience !== 'string' || !audience.trim()) return { ok: false, reason: 'no-audience' }
+  if (!data || typeof data !== 'object') return { ok: false, reason: 'shape' }
+  if (typeof data.aud !== 'string' || !data.aud) return { ok: false, reason: 'sin-destinatario' }
+  if (data.aud !== audience.trim()) return { ok: false, reason: 'otro-destinatario' }
+  if (data.exp != null) {
+    if (!Number.isFinite(data.exp)) return { ok: false, reason: 'shape' }
+    if (data.exp <= now) return { ok: false, reason: 'vencida' }
+  }
+  if (data.iat != null) {
+    if (!Number.isFinite(data.iat)) return { ok: false, reason: 'shape' }
+    if (data.iat > now + maxSkewMs) return { ok: false, reason: 'del-futuro' }
+  }
+  const v = await verifySignedBy({ data, signature, publickey, chain, expectedProfileId })
+  if (!v.ok) return { ok: false, reason: 'firma:' + v.reason }
+  return { ok: true, profileId: v.profileId, signer: v.signer, seq: v.seq, aud: data.aud }
+}
+
+export default { ASSERTION_V, ASSERTION_MAX_TTL_MS, ASSERTION_DEFAULT_TTL_MS, ASSERTION_MAX_SKEW_MS, SCOPES, SCOPE_CLAIMS, newAssertionNonce, cleanScopes, claimsAllowed, assertionBody, verifyAssertion, verifySignedFor }

package/vault/session.js

@@ -0,0 +1,176 @@
+/**
+ * session.js — ENTRAR SIN ENROLAR.
+ *
+ * El ecosistema tenía muchas formas de ENLAZAR un aparato y ninguna de ENTRAR en uno. Y no
+ * son lo mismo: enlazar mete una llave en el acta —hay que sellarla, o sea despertar a la
+ * selladora y tener el perfil abierto— y salir es sellar otra vez. Nadie hace eso para
+ * abrir una aplicación en un navegador prestado.
+ *
+ * Una SESIÓN es la otra puerta: una llave que vive en ese navegador y un PAPEL con
+ * vencimiento que la respalda, firmado por un aparato tuyo que sí está en el acta. No toca
+ * el acta, no necesita la selladora, y cerrar es inmediato.
+ *
+ *     llave de sesión  ←  papel  ←  aparato (miembro del acta)  ←  cadena  ←  perfil
+ *
+ * ESTO CREA UNA SEGUNDA AUTORIDAD, y por eso va acotada aquí y no en cada app:
+ *
+ *   · **Nunca amplía.** Un papel no concede lo que su firmante no tiene. Se comprueba
+ *     contra el acta al verificar, no solo al emitir: quien emite podría mentir.
+ *   · **Lista negra fija.** Una sesión jamás lleva `secrets`, `admin`, `approve`,
+ *     `sealer`, `passwords`, `unattended` ni `replica` — ni aunque el aparato los tenga.
+ *   · **Vence por reloj.** Es la excepción deliberada a «los papeles ya no caducan por
+ *     reloj»: un certificado describe pertenencia, que dura; una sesión ES temporal, y su
+ *     vencimiento es la mitad del producto.
+ *   · **No se re-delega.** Una sesión no abre otra sesión. No hay operación para eso.
+ *   · **Muere con su aparato.** Si revocas al que la respalda, su certificado deja de
+ *     valer contra el acta y todos sus papeles caen con él. Sale gratis del modelo, y por
+ *     eso `verifySession` EXIGE el acta: sin ella no se puede juzgar.
+ *
+ * Módulo PURO: sin red, sin kv, sin iframe.
+ */
+import { verifyDeviceSig } from './capabilities.js'
+import { memberCan, verifySealerChain } from './acta.js'
+import { canonicalStringify } from './core.js'
+
+export const SESSION_V = 1
+
+/** Cuánto dura una sesión. Horas, no meses: es un rato en un aparato que no es tuyo. */
+export const SESSION_DEFAULT_TTL_MS = 8 * 60 * 60 * 1000
+export const SESSION_MAX_TTL_MS = 24 * 60 * 60 * 1000
+/** Tolerancia de reloj para el arranque (no para el vencimiento). */
+export const SESSION_MAX_SKEW_MS = 60 * 1000
+
+/**
+ * Lo que una sesión puede llegar a hacer. Lista CERRADA y corta a propósito: es lo de bajo
+ * riesgo, lo que haría inviable la sesión si hubiera que preguntarle al teléfono cada vez.
+ *
+ *   · `id:whoami`      — decir quién eres (identificarse ante el transporte).
+ *   · `vault:store`    — leer y escribir en el almacén del perfil, si el papel lo dice.
+ *
+ * Firmar POR LA PERSONA no está aquí, y es deliberado: eso se le pide al aparato que
+ * respalda, que es quien tiene una llave que el acta reconoce.
+ */
+export const SESSION_SCOPES = Object.freeze(['id:whoami', 'vault:store'])
+
+/**
+ * Lo que una sesión NUNCA lleva, dijera lo que dijera el papel. Está aparte de la lista
+ * blanca a propósito: si mañana alguien añade un alcance a `SESSION_SCOPES` sin pensarlo,
+ * esto sigue cortando lo que no puede pasar.
+ */
+export const SESSION_FORBIDDEN = Object.freeze(['secrets', 'admin', 'approve', 'sealer', 'passwords', 'unattended', 'replica'])
+
+/** Qué capacidad del acta hace falta para conceder cada alcance de sesión. */
+const SCOPE_NEEDS = Object.freeze({ 'id:whoami': null, 'vault:store': 'store' })
+
+const enc = (s) => new TextEncoder().encode(s)
+const isStr = (v) => typeof v === 'string' && !!v
+
+/** Un identificador de sesión: lo que se enseña al usuario para que pueda cerrarla. */
+export const newSessionId = () => crypto.randomUUID()
+
+/** Normaliza los alcances pedidos: solo los del catálogo, sin repetidos y en orden estable. */
+export function cleanSessionScopes (scopes) {
+  const list = [...new Set((Array.isArray(scopes) ? scopes : []).filter((s) => SESSION_SCOPES.includes(s)))].sort()
+  return list.length ? list : ['id:whoami']
+}
+
+/** El cuerpo que firma el aparato que respalda. Un solo sitio: quien firma y quien verifica miran lo mismo. */
+export function sessionBody ({ sid, s, by, origin, scopes, iat, exp }) {
+  if (!isStr(sid)) throw new Error('session: sid required')
+  if (!isStr(s)) throw new Error('session: s (session pubkey) required')
+  if (!isStr(by)) throw new Error('session: by (backing device pubkey) required')
+  if (!isStr(origin)) throw new Error('session: origin required')
+  if (!Number.isFinite(iat) || !Number.isFinite(exp)) throw new Error('session: iat/exp required')
+  if (exp <= iat) throw new Error('session: exp must be after iat')
+  if (exp - iat > SESSION_MAX_TTL_MS) throw new Error('session: lifetime over the cap')
+  return { v: SESSION_V, op: 'session', sid, s, by, origin: origin.trim(), scopes: cleanSessionScopes(scopes), iat, exp }
+}
+
+/**
+ * Firma un papel de sesión. Lo llama el APARATO que respalda, con su propia llave.
+ *
+ * `sign` recibe el cuerpo y devuelve la firma (o el paquete del vault). No se le pasa la
+ * privada: este módulo no toca llaves.
+ */
+export async function signSession ({ sid, s, by, origin, scopes, ttlMs, now = Date.now() }, sign) {
+  if (typeof sign !== 'function') throw new Error('session: sign(body) required')
+  const ttl = Math.min(Math.max(Number(ttlMs) || SESSION_DEFAULT_TTL_MS, 60000), SESSION_MAX_TTL_MS)
+  const body = sessionBody({ sid, s, by, origin, scopes, iat: now, exp: now + ttl })
+  const firmado = await sign(body)
+  const sig = typeof firmado === 'string' ? firmado : firmado?.signature
+  if (!isStr(sig)) throw Object.assign(new Error('session: sign() returned no signature'), { code: 'no-signature' })
+  return { ...body, sig }
+}
+
+/**
+ * ¿Vale este papel de sesión, AHORA?
+ *
+ * `chain` es la cadena de actas del perfil, y es obligatoria: sin ella no se puede saber si
+ * el aparato que respalda sigue siendo de la casa —que es lo que hace que quitar un aparato
+ * se lleve por delante sus sesiones—. Devuelve `{ ok, profileId, scopes, sid, exp }` o
+ * `{ ok:false, reason }`.
+ */
+export async function verifySession (paper, { chain, expectedProfileId = null, origin = null, now = Date.now(), maxSkewMs = SESSION_MAX_SKEW_MS } = {}) {
+  const p = paper
+  if (!p || typeof p !== 'object') return { ok: false, reason: 'shape' }
+  if (p.v !== SESSION_V || p.op !== 'session') return { ok: false, reason: 'shape' }
+  if (!isStr(p.sid) || !isStr(p.s) || !isStr(p.by) || !isStr(p.origin) || !isStr(p.sig)) return { ok: false, reason: 'shape' }
+  if (!Number.isFinite(p.iat) || !Number.isFinite(p.exp) || !Array.isArray(p.scopes)) return { ok: false, reason: 'shape' }
+
+  if (p.exp <= p.iat) return { ok: false, reason: 'vigencia-invalida' }
+  if (p.exp - p.iat > SESSION_MAX_TTL_MS) return { ok: false, reason: 'vigencia-excesiva' }
+  if (p.exp <= now) return { ok: false, reason: 'vencida' }
+  if (p.iat > now + maxSkewMs) return { ok: false, reason: 'del-futuro' }
+
+  // DÓNDE vale. Un papel para una aplicación no vale en otra: el origen va firmado dentro.
+  if (origin != null && p.origin !== String(origin).trim()) return { ok: false, reason: 'otro-origen' }
+
+  if (p.scopes.some((s) => !SESSION_SCOPES.includes(s))) return { ok: false, reason: 'alcance-desconocido' }
+  if (p.scopes.some((s) => SESSION_FORBIDDEN.includes(s))) return { ok: false, reason: 'alcance-prohibido' }
+
+  // EL ACTA MANDA, y por eso hace falta: dice si el aparato que respalda sigue siendo del
+  // perfil y qué puede. Sin ella no se juzga, en vez de dar por bueno lo que diga el papel.
+  const c = await verifySealerChain(chain, { expectedProfileId })
+  if (!c.ok) return { ok: false, reason: 'cadena:' + c.reason }
+  const acta = chain[chain.length - 1]
+
+  // PRIMERO, ¿ES DE LA CASA? Y en este orden a propósito: si al aparato lo quitaron, el
+  // motivo tiene que decir eso y no «le falta un permiso», que manda a mirar al sitio
+  // equivocado. Es además el invariante que hace barata la revocación — quitar un aparato
+  // se lleva sus sesiones sin avisar a nadie ni perseguir papeles.
+  if (!(acta.members || []).some((m) => m?.pub === p.by)) return { ok: false, reason: 'aparato-no-es-del-perfil' }
+
+  // Y DESPUÉS, NUNCA AMPLÍA: cada alcance exige que el aparato que firmó lo tenga HOY. Se
+  // comprueba aquí y no solo al emitir, porque quien emite es precisamente quien podría
+  // mentir — y porque el acta de hoy puede haberle quitado lo que tenía ayer.
+  for (const s of p.scopes) {
+    const cap = SCOPE_NEEDS[s]
+    if (cap && !memberCan(acta, p.by, cap)) return { ok: false, reason: 'aparato-sin-' + cap }
+  }
+
+  const { sig, ...body } = p
+  if (!(await verifyDeviceSig({ publickey: p.by, data: body, signature: sig }))) return { ok: false, reason: 'firma-invalida' }
+
+  return { ok: true, profileId: c.profileId, seq: c.seq, sid: p.sid, s: p.s, by: p.by, origin: p.origin, scopes: [...p.scopes], exp: p.exp }
+}
+
+/**
+ * ¿Firmó ESTA SESIÓN esto, y podía?
+ *
+ * Es lo que llama quien recibe algo de una sesión: comprueba la firma de la llave de
+ * sesión, el papel que la respalda y —si se pide— que el alcance cubra lo que se pretende.
+ */
+export async function verifySessionSigned ({ data, signature, session, chain, scope = null, origin = null, expectedProfileId = null, now = Date.now() } = {}) {
+  if (!data || !isStr(signature)) return { ok: false, reason: 'shape' }
+  const v = await verifySession(session, { chain, expectedProfileId, origin, now })
+  if (!v.ok) return v
+  if (scope && !v.scopes.includes(scope)) return { ok: false, reason: 'fuera-de-alcance' }
+  if (!(await verifyDeviceSig({ publickey: v.s, data, signature }))) return { ok: false, reason: 'firma-invalida' }
+  return { ok: true, profileId: v.profileId, sid: v.sid, scopes: v.scopes, exp: v.exp }
+}
+
+export default {
+  SESSION_V, SESSION_DEFAULT_TTL_MS, SESSION_MAX_TTL_MS, SESSION_MAX_SKEW_MS,
+  SESSION_SCOPES, SESSION_FORBIDDEN, newSessionId, cleanSessionScopes,
+  sessionBody, signSession, verifySession, verifySessionSigned
+}

package/vault/sessionFlow.js

@@ -0,0 +1,151 @@
+/**
+ * sessionFlow.js — LAS DOS PUNTAS DE «ENTRAR».
+ *
+ * El papel de sesión lo define `session.js`; aquí está cómo se consigue: un navegador que
+ * no te conoce enseña una invitación, un aparato tuyo la lee y le da el papel.
+ *
+ *     navegador nuevo                         aparato que respalda (con cámara)
+ *     ──────────────────                      ─────────────────────────────────
+ *     genera su llave S
+ *     muestra QR + código  ──── escanea ────►  ve qué aplicación y qué pide
+ *                                              [Permitir] → firma el papel
+ *                          ◄──── sellado ────  { paper, chain }
+ *     comprueba y entra
+ *
+ * TRES COSAS QUE NO SON DETALLE:
+ *
+ *   · **El QR va al revés que en el emparejamiento.** Allí lo muestra la bóveda; aquí lo
+ *     muestra QUIEN QUIERE ENTRAR, porque quien entra puede no tener cámara y el teléfono
+ *     siempre la tiene.
+ *   · **El código corto es el freno del reenvío**, igual que el SAS del emparejamiento:
+ *     quien intercepte la invitación no puede enseñar el código correcto en la pantalla que
+ *     el dueño está mirando.
+ *   · **Va sellado.** Es un mensaje dirigido y el proxio no cifra (CONVENCIONES §4.1). El
+ *     papel no es un secreto —lo verifica cualquiera—, pero decir en claro «esta persona
+ *     acaba de entrar en tal aplicación» sí cuenta algo.
+ *
+ * El transporte se INYECTA (`@dotrino/proxy-client`), como en geo y en reputación: este
+ * pilar no abre conexiones ni sabe de proxios.
+ */
+import { signSession, verifySession, newSessionId, cleanSessionScopes, SESSION_DEFAULT_TTL_MS } from './session.js'
+
+export const SESSION_OP = Object.freeze({
+  GRANT: 'session.grant',   // aparato → navegador: aquí tienes tu papel
+  DENY: 'session.deny',     // aparato → navegador: no
+  CLOSE: 'session.close'    // aparato → navegador: se acabó, bórrala
+})
+
+/** El código corto que el humano compara. Seis dígitos, como el del emparejamiento. */
+export function sessionCode (sid) {
+  let h = 0
+  for (const c of String(sid)) h = (h * 31 + c.charCodeAt(0)) >>> 0
+  return String(h % 1000000).padStart(6, '0')
+}
+
+/**
+ * Lo que viaja en el QR. Corto a propósito: un QR más denso se lee peor con poca luz, que
+ * es justo cuando alguien intenta entrar desde un aparato prestado.
+ */
+export function buildInvite ({ sid, s, encPub, origin, scopes, proxy }) {
+  return { v: 1, t: 'session', sid, s, encPub, origin, scopes: cleanSessionScopes(scopes), proxy }
+}
+
+/** Lee una invitación, venga del QR o pegada a mano. `null` si no es una. */
+export function parseInvite (raw) {
+  try {
+    const o = typeof raw === 'string' ? JSON.parse(raw) : raw
+    if (!o || o.t !== 'session' || o.v !== 1) return null
+    if (typeof o.sid !== 'string' || typeof o.s !== 'string' || typeof o.origin !== 'string') return null
+    return { ...o, scopes: cleanSessionScopes(o.scopes) }
+  } catch (_) { return null }
+}
+
+/**
+ * LADO DEL QUE ENTRA. Genera la sesión, publica la invitación y espera el papel.
+ *
+ * `transport` es un cliente ya conectado e identificado bajo la llave de sesión (`s`): así
+ * el aparato que responde puede escribirle por pubkey. `onInvite` recibe lo que hay que
+ * enseñar —la invitación y el código— para que la app pinte el QR con `@dotrino/qr`.
+ *
+ * Devuelve `{ paper, chain, profileId }` cuando alguien concede, o lanza si se deniega o
+ * se agota la espera. No guarda nada: dónde vive la sesión lo decide quien llama.
+ */
+export async function openSession ({ transport, sessionPubkey, encPub, origin, scopes, onInvite, timeoutMs = 5 * 60 * 1000, sid = newSessionId() } = {}) {
+  if (!transport || typeof transport.on !== 'function') throw new Error('openSession: transport required')
+  if (typeof sessionPubkey !== 'string' || !sessionPubkey) throw new Error('openSession: sessionPubkey required')
+  if (typeof origin !== 'string' || !origin.trim()) throw new Error('openSession: origin required')
+
+  const invite = buildInvite({ sid, s: sessionPubkey, encPub, origin: origin.trim(), scopes, proxy: transport.url })
+  onInvite?.({ invite, code: sessionCode(sid), qr: JSON.stringify(invite) })
+
+  return await new Promise((resolve, reject) => {
+    let listo = false
+    const fin = (fn, arg) => { if (!listo) { listo = true; clearTimeout(reloj); off?.(); fn(arg) } }
+    const reloj = setTimeout(() => fin(reject, Object.assign(new Error('nadie abrió la sesión a tiempo'), { code: 'session-timeout' })), timeoutMs)
+    const off = transport.on('message', async (_from, payload, meta) => {
+      const p = typeof payload === 'string' ? (() => { try { return JSON.parse(payload) } catch (_) { return null } })() : payload
+      if (!p || p.sid !== sid) return
+      if (p.op === SESSION_OP.DENY) return fin(reject, Object.assign(new Error('la sesión no se concedió'), { code: 'session-denied' }))
+      if (p.op !== SESSION_OP.GRANT) return
+      // NO SE ACEPTA LO QUE VENGA EN CLARO. El sellado es del pilar del transporte; aquí
+      // solo se comprueba que llegó sellado, que es lo que la app puede saber.
+      if (meta && meta.sealed === false) return
+      const v = await verifySession(p.paper, { chain: p.chain, origin: origin.trim() })
+      if (!v.ok) return fin(reject, Object.assign(new Error('el papel de sesión no vale: ' + v.reason), { code: 'session-invalid' }))
+      if (p.paper.s !== sessionPubkey) return fin(reject, Object.assign(new Error('el papel es para otra llave'), { code: 'session-invalid' }))
+      fin(resolve, { paper: p.paper, chain: p.chain, profileId: v.profileId, sid, scopes: v.scopes, exp: v.exp })
+    })
+  })
+}
+
+/**
+ * LADO DEL QUE RESPALDA. Firma el papel y se lo manda al que espera.
+ *
+ * `sign` firma con la llave de ESTE aparato (la que el acta nombra) y `chain` es la cadena
+ * del perfil: las dos cosas viajan juntas porque por separado no sirven.
+ *
+ * `scopes` acota lo que se concede: por omisión, lo que pidió la invitación. Quien llama
+ * puede recortarlo —nunca ampliarlo, que de eso ya se encarga `verifySession`.
+ */
+export async function grantSession ({ transport, invite, by, sign, chain, scopes, ttlMs = SESSION_DEFAULT_TTL_MS, now = Date.now() } = {}) {
+  const inv = parseInvite(invite)
+  if (!inv) throw new Error('grantSession: invitación ilegible')
+  if (typeof by !== 'string' || !by) throw new Error('grantSession: by (this device pubkey) required')
+  if (typeof sign !== 'function') throw new Error('grantSession: sign(body) required')
+  if (!Array.isArray(chain) || !chain.length) throw new Error('grantSession: chain required')
+
+  const pedidos = cleanSessionScopes(scopes ?? inv.scopes)
+  const paper = await signSession({ sid: inv.sid, s: inv.s, by, origin: inv.origin, scopes: pedidos, ttlMs, now }, sign)
+  await enviar(transport, inv, { op: SESSION_OP.GRANT, sid: inv.sid, paper, chain })
+  return paper
+}
+
+/** Decir que no, en vez de dejar al otro mirando una pantalla que no avanza. */
+export async function denySession ({ transport, invite } = {}) {
+  const inv = parseInvite(invite)
+  if (!inv) throw new Error('denySession: invitación ilegible')
+  await enviar(transport, inv, { op: SESSION_OP.DENY, sid: inv.sid })
+}
+
+/**
+ * CERRARLA. Se avisa a la sesión para que se borre en el acto; lo que la corta de verdad es
+ * que el papel vence y nadie lo renueva —y que quitar el aparato se lleva todos los suyos.
+ */
+export async function closeSession ({ transport, sessionPubkey, encPub, sid } = {}) {
+  if (typeof sessionPubkey !== 'string' || !sessionPubkey) throw new Error('closeSession: sessionPubkey required')
+  await enviar(transport, { s: sessionPubkey, encPub }, { op: SESSION_OP.CLOSE, sid })
+}
+
+/** Sellado siempre que se pueda: el proxio no cifra (CONVENCIONES §4.1). */
+async function enviar (transport, inv, payload) {
+  if (!transport || typeof transport.sendByPubkey !== 'function') throw new Error('sessionFlow: transport required')
+  if (inv.encPub && typeof transport.sendSealed === 'function') {
+    return transport.sendSealed([inv.s], payload, { peerEncPub: inv.encPub })
+  }
+  // Sin llave de cifrado del otro lado no se puede sellar. Se dice en vez de mandarlo en
+  // claro por su cuenta: quien llama decide si eso le vale.
+  if (!inv.encPub) throw Object.assign(new Error('sessionFlow: la invitación no trae encPub; no se puede sellar'), { code: 'unsealed' })
+  return transport.sendByPubkey(inv.s, payload)
+}
+
+export default { SESSION_OP, sessionCode, buildInvite, parseInvite, openSession, grantSession, denySession, closeSession }

package/vault/vendor/proxy-client/VERSION.txt

@@ -1,4 +1,4 @@
-Copia vendorizada de @dotrino/proxy-client@0.17.0 (dotrino-proxy-client/src/{index,client,signature,canonical,sealing,webrtc}.js).
+Copia vendorizada de @dotrino/proxy-client@0.18.2 (dotrino-proxy-client/src/{index,client,signature,canonical,sealing,webrtc}.js).
 NO se edita a mano: la escribe `node vendor.mjs` y la vigila test/vendor-up-to-date.test.mjs.
 sealing.js resuelve @dotrino/identity/content de forma PEREZOSA (= ../../content.js
 por el import map): solo se carga si de verdad se sella algo.

package/vault/vendor/proxy-client/client.js

@@ -487,6 +487,41 @@ export class WebSocketProxyClient {
    *   esperar a `identify` por eso retrasaría todo lo que viene después para ganar algo que
    *   solo hace falta cuando se negocie el primer canal.
    */
+  /**
+   * PARA QUIÉN firmamos cuando le hablamos a ESTE proxio. Sale de la URL a la que estamos
+   * conectados: quien levanta su propio proxio tiene otro destinatario, y con un valor fijo
+   * un sobre firmado para el nuestro valdría ante el suyo.
+   */
+  get audience () { return String(this.url || '').replace(/\/+$/, '') }
+
+  /**
+   * IDENTIFICARSE, ARMANDO EL SOBRE AQUÍ. Doce repos lo escribían a mano
+   * (`{op:'identify', publickey, token, ts}` + firma), o sea el protocolo copiado doce
+   * veces: al añadirle el destinatario habría que acertar en los doce, y quien escribiera
+   * el trece lo haría sin él.
+   *
+   * `sign` es lo que firma (normalmente `(d) => identity.signData(d)`); acepta tanto la
+   * firma en texto como el paquete del vault.
+   */
+  async identifyAs ({ publickey, sign, cert, acta } = {}) {
+    if (typeof sign !== 'function') throw new Error('identifyAs requires sign(data)')
+    if (!publickey) throw new Error('identifyAs requires publickey')
+    if (!this.token) throw new Error('identifyAs: not connected yet (no token)')
+    // El `token` lo da el proxio al conectar y va firmado aquí dentro: es el reto de esta
+    // conexión, y por eso este sobre no necesita otro. Lo que le faltaba era decir a quién
+    // se lo estamos dando.
+    const data = { op: 'identify', aud: this.audience, publickey, token: this.token, ts: Date.now() }
+    const firmado = await sign(data)
+    const signature = typeof firmado === 'string' ? firmado : firmado?.signature
+    // «No pude firmar» y «se cayó la red» son cosas distintas, y se distinguen por el
+    // `code`: la bóveda usa esto para saber si su llave de comunicación firma todavía, y
+    // tragarse un fallo de red como si fuera lo primero la mandaría al camino equivocado.
+    if (typeof signature !== 'string') {
+      throw Object.assign(new Error('identifyAs: sign() returned no signature'), { code: 'no-signature' })
+    }
+    return this.identify({ data, signature, cert, acta, sign })
+  }
+
   identify ({ data, signature, cert, acta, sign }) {
     if (!data || !signature) throw new Error('identify requires {data, signature}')
     const msg = { type: 'identify', data, signature }

package/vault/vendor/vault/VERSION.txt

@@ -1,4 +1,4 @@
-Copia vendorizada de @dotrino/vault@0.61.0 (dotrino-vault/lib/src/{index,enroll,protocol}.js).
+Copia vendorizada de @dotrino/vault@0.62.1 (dotrino-vault/lib/src/{index,enroll,protocol}.js).
 NO se edita a mano: la escribe `node vendor.mjs` y la vigila test/vendor-up-to-date.test.mjs.
 index.js importa ./enroll.js y ./protocol.js (relativos, van en esta misma copia),
 @dotrino/identity/{capabilities,acta} (= ../../{capabilities,acta}.js) y

package/vault/vendor/vault/index.js

@@ -97,9 +97,8 @@ export async function startDeviceVault (identity, { proxyUrl, client: injectedCl
   const selfCert = await getSelfCert()
   const identify = async () => {
     if (!client.token) return
-    const data = { op: 'identify', publickey: iss, token: client.token, ts: Date.now() }
-    const { signature } = await identity.signData(data)
-    await client.identify({ data, signature, cert: selfCert })
+    // El sobre lo arma el pilar (`identifyAs`), que le pone el destinatario.
+    await client.identifyAs({ publickey: iss, sign: (d) => identity.signData(d), cert: selfCert })
   }
   await identify()
   client.on('token', () => identify().catch(() => {}))