@dotrino/remote-agent 0.37.0 → 0.38.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -42,6 +42,7 @@ Provee lo común — y **solo** eso:
42
42
  | `@dotrino/remote-agent/discover` | navegador | `listAgentsByLabel`, `probeAgents` |
43
43
  | `@dotrino/remote-agent/update` | Node | `startSelfUpdate`, `vaultHooks`: el agente se actualiza solo (CONVENCIONES §15) y se reinicia cuando está libre (0.36.0; necesita `@dotrino/update`) |
44
44
  | `@dotrino/remote-agent/instances` | Node | `resolveInstance`, `listInstances`, `lockInstance`, `instancesRoot` |
45
+ | `@dotrino/remote-agent/access` | Node | La clave de la máquina (opcional): `setAccessCode`, `makeGate` (freno por agente, aviso por aparato), `makeLock` (el candado de cada sesión: `unlock` → `unlocked`). Venía de Terminal (0.38.0) |
45
46
  | `@dotrino/remote-agent/service` | Node | `makeService`: el agente como servicio del usuario (systemd de usuario o inicio automático del escritorio en Linux, LaunchAgent en macOS, `HKCU\…\Run` + supervisor en Windows). Sin `sudo` (0.37.0) |
46
47
 
47
48
  ## Uso
@@ -234,6 +235,8 @@ extraerlo luego a este paquete.
234
235
 
235
236
  ## Seguridad
236
237
 
238
+ **Permiso por producto (0.38.0).** `needs: ['desktop']` (o `terminal`) no solo se declara a la bóveda: se exige a quien saluda. Sin él, `ra.error` con `reason: 'missing-cap'` y `caps` con lo que falta; si se lo quitan con la sesión abierta, se le cierra. Un `ra.data` solo cambia por dónde se contesta (y renueva la sesión) si su sobre abre con la llave de la sesión; un saludo con la firma mal no despierta a la bóveda; los avisos de bloqueo van con freno (auditoría del 2026-11-16).
239
+
237
240
  - **Autorización = el ACTA, en las dos puntas** (0.24.0). El papel (`cert`) prueba quién
238
241
  lo emitió —una selladora del acta— pero no caduca, así que el de un aparato quitado sigue
239
242
  bien firmado. Lo que decide es `canGreet(acta, pub)` (`src/membership.js`): el acta
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dotrino/remote-agent",
3
- "version": "0.37.0",
3
+ "version": "0.38.0",
4
4
  "description": "Middleware compartido del ecosistema Dotrino para apps de agente remoto cifrado punto a punto (handshake E2E, emparejamiento SAS con vault, revocación, descubrimiento). Lo consumen dotrino-terminal (PTY) y dotrino-ia (chat con IA).",
5
5
  "type": "module",
6
6
  "main": "./index.js",
@@ -45,6 +45,10 @@
45
45
  "./service": {
46
46
  "types": "./types/src/service.d.ts",
47
47
  "import": "./src/service.js"
48
+ },
49
+ "./access": {
50
+ "types": "./types/src/access.d.ts",
51
+ "import": "./src/access.js"
48
52
  }
49
53
  },
50
54
  "files": [
package/src/access.js ADDED
@@ -0,0 +1,193 @@
1
+ /**
2
+ * access.js — la CLAVE de esta máquina (un PIN o una contraseña), opcional.
3
+ *
4
+ * Venía de `dotrino-terminal/agent/access.js` y ahora es común (dueño, 2026-11-16: el escritorio
5
+ * remoto también la lleva). Sin clave puesta no cambia nada: entra cualquier aparato de la cuenta
6
+ * con los permisos del producto. Con clave, además hay que escribirla en cada conexión remota.
7
+ * Lo que corre en ESTA máquina (las ventanas de Terminal por su socket local) no la pide: es del
8
+ * mismo usuario que ya puede leer este archivo.
9
+ *
10
+ * Por el cable: la sesión que todavía no la escribió recibe `{ type: 'fail', code: 'locked' }`
11
+ * a cualquier cosa que pida; manda `{ type: 'unlock', code }` y recibe `{ type: 'unlocked' }`, o
12
+ * `fail` con `bad-code` / `wait` (`retryMs`). Ver `makeLock`.
13
+ *
14
+ * En el disco queda la sal y el resumen (scrypt), nunca la clave. La clave viaja dentro de la
15
+ * sesión cifrada entre el aparato y el agente, así que el proxio no la ve.
16
+ *
17
+ * Los fallos se frenan POR AGENTE y no por sesión: quien prueba claves puede abrir otra
18
+ * conexión, y eso no le da intentos nuevos. A los TRES seguidos (dueño, 2026-10-07) empieza
19
+ * la espera, que se dobla con cada fallo más: es un bloqueo LOCAL de este servicio, nada más.
20
+ *
21
+ * Y a los tres fallos seguidos de UN MISMO aparato se avisa (`onIncident`): la bóveda se lo
22
+ * pone en la mesa a quien aprueba, que bloquea o ignora desde el teléfono. Avisar no decide
23
+ * nada aquí; el freno de arriba sigue igual.
24
+ */
25
+ import crypto from 'node:crypto'
26
+ import fs from 'node:fs'
27
+ import path from 'node:path'
28
+
29
+ export const ACCESS_FILE = 'access.json'
30
+ export const MIN_LENGTH = 4
31
+ /** Fallos seguidos que se dejan pasar sin esperar: al tercero empieza la espera. */
32
+ export const FREE_TRIES = 3
33
+ /** Fallos seguidos de un mismo aparato que disparan el aviso a la bóveda. */
34
+ export const INCIDENT_AFTER = 3
35
+ const BASE_WAIT_MS = 30_000
36
+ const MAX_WAIT_MS = 60 * 60_000
37
+ const SCRYPT = { N: 1 << 15, r: 8, p: 1, maxmem: 64 * 1024 * 1024 }
38
+
39
+ /** @typedef {Error & { code?: string, retryMs?: number }} Thrown */
40
+
41
+ /** @type {(code: string, message: string, extra?: object) => Error & { code: string }} */
42
+ const fail = (code, message, extra = {}) => Object.assign(new Error(message), { code, ...extra })
43
+ /** @param {string} dir */
44
+ const file = (dir) => path.join(dir, ACCESS_FILE)
45
+ /** @type {(secret: unknown, salt: Buffer, params: import('node:crypto').ScryptOptions) => Buffer} */
46
+ const digest = (secret, salt, params) => crypto.scryptSync(String(secret).normalize('NFKC'), salt, 32, params)
47
+
48
+ /** Si esta máquina tiene clave. Un archivo que existe y no se puede leer NO es «sin clave»: se lanza. */
49
+ /** @param {string} dir */
50
+ export function hasAccessCode (dir) {
51
+ return readRecord(dir) !== null
52
+ }
53
+
54
+ /**
55
+ * @param {string} dir
56
+ * @returns {{ v: 1, salt: string, hash: string, params: import('node:crypto').ScryptOptions } | null}
57
+ */
58
+ function readRecord (dir) {
59
+ let raw
60
+ try { raw = fs.readFileSync(file(dir), 'utf8') } catch (e) {
61
+ if (/** @type {Thrown} */ (e).code === 'ENOENT') return null
62
+ throw fail('access-unreadable', `cannot read ${ACCESS_FILE}: ${/** @type {Thrown} */ (e).message}`)
63
+ }
64
+ let r
65
+ try { r = JSON.parse(raw) } catch (_) { throw fail('access-unreadable', `${ACCESS_FILE} is not valid JSON`) }
66
+ if (r?.v !== 1 || typeof r.salt !== 'string' || typeof r.hash !== 'string' || !r.params) {
67
+ throw fail('access-unreadable', `${ACCESS_FILE} has an unknown shape`)
68
+ }
69
+ return r
70
+ }
71
+
72
+ /**
73
+ * Pone o cambia la clave.
74
+ * @param {string} dir
75
+ * @param {unknown} secret
76
+ */
77
+ export function setAccessCode (dir, secret) {
78
+ if (typeof secret !== 'string' || secret.length < MIN_LENGTH) throw fail('too-short', `the code needs at least ${MIN_LENGTH} characters`)
79
+ const salt = crypto.randomBytes(16)
80
+ const record = { v: 1, salt: salt.toString('base64'), hash: digest(secret, salt, SCRYPT).toString('base64'), params: SCRYPT }
81
+ const tmp = file(dir) + '.tmp'
82
+ fs.writeFileSync(tmp, JSON.stringify(record), { mode: 0o600 })
83
+ fs.renameSync(tmp, file(dir))
84
+ }
85
+
86
+ /**
87
+ * Quita la clave.
88
+ * @param {string} dir
89
+ */
90
+ export function clearAccessCode (dir) {
91
+ fs.rmSync(file(dir), { force: true })
92
+ }
93
+
94
+ /**
95
+ * Si `secret` es la clave de esta máquina. Sin frenos: para la orden local que la cambia.
96
+ * @param {string} dir
97
+ * @param {unknown} secret
98
+ */
99
+ export function checkAccessCode (dir, secret) {
100
+ const r = readRecord(dir)
101
+ if (!r) throw fail('no-access-code', 'this machine has no code')
102
+ const want = Buffer.from(r.hash, 'base64')
103
+ const got = digest(secret ?? '', Buffer.from(r.salt, 'base64'), r.params)
104
+ return want.length === got.length && crypto.timingSafeEqual(want, got)
105
+ }
106
+
107
+ /**
108
+ * La puerta de un agente: comprueba la clave y frena los fallos seguidos. Una por agente,
109
+ * compartida por todas sus sesiones.
110
+ * @param {string} dir
111
+ * @param {{ now?: () => number, onIncident?: ((i: { device: string, tries: number }) => void) | null }} [opts]
112
+ * `onIncident`: un mismo aparato (`device`, su pubkey) falló `INCIDENT_AFTER` veces seguidas.
113
+ * Se llama UNA vez por racha; la racha se corta al acertar.
114
+ */
115
+ export function makeGate (dir, { now = Date.now, onIncident = null } = {}) {
116
+ let fails = 0
117
+ let until = 0
118
+ /** Fallos seguidos por aparato: el aviso es sobre QUIÉN, y el freno sobre el agente. */
119
+ const byDevice = new Map()
120
+ return {
121
+ /** Si hay que escribir la clave para entrar. Lanza `access-unreadable` si no se puede saber. */
122
+ required: () => hasAccessCode(dir),
123
+ /**
124
+ * Lanza `wait` (con `retryMs`) o `bad-code`; si no lanza, la clave era la buena.
125
+ * `device` es quién la escribió (pubkey), para contar sus fallos y avisar.
126
+ */
127
+ /**
128
+ * @param {unknown} secret
129
+ * @param {string | null} [device]
130
+ */
131
+ check (secret, device = null) {
132
+ const left = until - now()
133
+ if (left > 0) throw fail('wait', 'too many wrong codes', { retryMs: left })
134
+ if (checkAccessCode(dir, secret)) { fails = 0; until = 0; if (device) byDevice.delete(device); return }
135
+ fails++
136
+ if (fails >= FREE_TRIES) until = now() + Math.min(BASE_WAIT_MS * 2 ** (fails - FREE_TRIES), MAX_WAIT_MS)
137
+ if (device) {
138
+ const n = (byDevice.get(device) || 0) + 1
139
+ byDevice.set(device, n)
140
+ if (n === INCIDENT_AFTER && onIncident) { try { onIncident({ device, tries: n }) } catch (_) {} }
141
+ }
142
+ throw fail('bad-code', 'wrong code', until ? { retryMs: until - now() } : {})
143
+ }
144
+ }
145
+ }
146
+
147
+ /**
148
+ * El candado de UNA sesión: hasta que escribe la clave (si la máquina tiene), no pasa nada más.
149
+ * Una vez escrita vale para esa conexión. Sin `gate` (lo local), siempre pasa.
150
+ *
151
+ * session.on('message', (msg) => {
152
+ * if (lock.handle(msg)) return // era el `unlock`: ya contestó
153
+ * if (!lock.mayPass()) return // ya contestó `locked` (o que no se puede saber)
154
+ * …
155
+ * })
156
+ *
157
+ * No saber si hay clave (el archivo no se puede leer) es no pasar, y se dice.
158
+ * @param {{ gate: ReturnType<typeof makeGate> | null, device?: string | null,
159
+ * send: (msg: object) => unknown }} o
160
+ */
161
+ export function makeLock ({ gate, device = null, send }) {
162
+ let unlocked = false
163
+ /** @type {(code: string, message: string, extra?: object) => unknown} */
164
+ const failMsg = (code, message, extra = {}) => send({ type: 'fail', code, message, ...extra })
165
+ /** @param {unknown} e */
166
+ const failWith = (e) => {
167
+ const t = /** @type {Thrown} */ (e)
168
+ failMsg(t.code || 'access-unreadable', t.message, t.retryMs ? { retryMs: t.retryMs } : {})
169
+ }
170
+ return {
171
+ get unlocked () { return unlocked || !gate },
172
+ /** True si esta sesión puede seguir; si no, ya contestó por qué. */
173
+ mayPass () {
174
+ if (!gate || unlocked) return true
175
+ try {
176
+ if (!gate.required()) return true
177
+ } catch (e) { failWith(e); return false }
178
+ failMsg('locked', 'this machine asks for its code')
179
+ return false
180
+ },
181
+ /** Si `msg` es el `unlock`, lo atiende y devuelve true. @param {any} msg */
182
+ handle (msg) {
183
+ if (!msg || msg.type !== 'unlock') return false
184
+ if (!gate) { send({ type: 'unlocked' }); return true }
185
+ try {
186
+ if (gate.required()) gate.check(msg.code, device)
187
+ unlocked = true
188
+ send({ type: 'unlocked' })
189
+ } catch (e) { failWith(e) }
190
+ return true
191
+ }
192
+ }
193
+ }
package/src/agent.js CHANGED
@@ -25,10 +25,13 @@ import { verifyChain, signWithDevice, verifyDeviceSig, pubkeyId, keyLabel } from
25
25
  import { sealersOf, memberCan, checkVaultReply } from '@dotrino/identity/acta'
26
26
  import { sendToVault, acceptReply } from '@dotrino/identity/vault-seal'
27
27
  import { adoptRecord } from './record.js'
28
- import { canGreet } from './membership.js'
28
+ import { canGreet, missingCaps } from './membership.js'
29
29
  import { installNodeGlobals } from '../node-globals.js'
30
30
  import { makeEphemeral, deriveKey, seal, open } from '../e2e.js'
31
- import { makeCatchUp } from './catch-up.js'
31
+ import { makeCatchUp, makeThrottle } from './catch-up.js'
32
+
33
+ /** Fallos de `verifyChain` que un acta más nueva no arregla: el saludo no prueba ni quién lo firmó. */
34
+ const PRE_AUTH = new Set(['shape', 'no-device-pubkey', 'bad-action-signature', 'cert-device-mismatch'])
32
35
  import { HS, ACK, DATA, PING, PONG, ERROR, VMSG, SIGN_SCOPE, SESSION_TTL_MS, SESSION_GONE_MS, REVOKE_REFRESH_MS, DEFAULT_PROXY } from '../protocol.js'
33
36
  import { loadLink, saveLink, dataDir, renewalReason, storeRenewedCert } from './link.js'
34
37
  import { declare } from '@dotrino/compat'
@@ -125,10 +128,13 @@ export class AgentSession {
125
128
 
126
129
  /** Lo que llega se entrega en el orden en que llegó, tarde lo que tarde en descifrarse cada uno. */
127
130
  /** @param {{ iv: string, ct: string }} env */
128
- _ingest (env) {
131
+ /** @param {any} env @param {() => void} [onOpen] solo si el sobre abre, antes de repartirlo */
132
+ _ingest (env, onOpen) {
129
133
  const opened = open(this.key, env).then((msg) => ({ msg }), () => null)
130
134
  this._in = (this._in || Promise.resolve()).then(() => opened).then((r) => {
131
- if (r) for (const h of this._h.message) { try { h(r.msg) } catch (_) {} }
135
+ if (!r) return
136
+ if (onOpen) onOpen()
137
+ for (const h of this._h.message) { try { h(r.msg) } catch (_) {} }
132
138
  })
133
139
  return this._in
134
140
  }
@@ -161,7 +167,9 @@ export class AgentSession {
161
167
  * @param {string} [opts.product] qué producto es (`accounts`, `terminal-agent`…), para el anuncio a la bóveda.
162
168
  * @param {string} [opts.version] su versión. Sin `product`/`version` se anuncia como `remote-agent`.
163
169
  * @param {string[]} [opts.needs] los permisos del acta que necesita, además de `sign`, que lo
164
- * añade este pilar: sin él no se abre ninguna sesión (`@dotrino/compat` ≥ 0.5.0).
170
+ * añade este pilar: sin él no se abre ninguna sesión (`@dotrino/compat` ≥ 0.5.0). Desde 0.38.0
171
+ * también se EXIGEN a quien saluda: un aparato sin ellos no abre sesión (`missing-cap`), y si
172
+ * se los quitan con la sesión abierta, se le cierra.
165
173
  *
166
174
  * Devuelve además el **`client`** (el `WebSocketProxyClient` ya conectado e
167
175
  * identificado bajo la pubkey de esta máquina). Se expone a propósito: un agente
@@ -181,6 +189,8 @@ export async function startRemoteAgent (opts = {}) {
181
189
  product: opts.product || 'remote-agent', version: opts.version || PKG_VERSION,
182
190
  protocol: VAULT_PROTOCOL, speaks: VAULT_SPEAKS, needs: ['sign', ...(opts.needs || [])]
183
191
  })
192
+ /** Lo que se exige a quien saluda, además de `sign` (`terminal`, `desktop`…). */
193
+ const NEEDS = Object.freeze([...(opts.needs || [])])
184
194
  const master = /** @type {string} */ (link.iss) // comprobado arriba
185
195
  const myPub = link.device.publickey
186
196
  const myId = await keyLabel(myPub)
@@ -439,7 +449,8 @@ export async function startRemoteAgent (opts = {}) {
439
449
  const acta = trustedActa()
440
450
  for (const [sid, s] of sessions) {
441
451
  const reason = !canGreet(acta, s.device) ? 'not-in-record'
442
- : (s._certNonce && revokedSet.has(s._certNonce)) ? 'revoked' : null
452
+ : missingCaps(acta, s.device, NEEDS).length ? 'missing-cap'
453
+ : (s._certNonce && revokedSet.has(s._certNonce)) ? 'revoked' : null
443
454
  if (!reason) continue
444
455
  send(s.from, { type: ERROR, code: 'unauthorized', reason, sid, error: 'unauthorized: ' + reason })
445
456
  s.close(); sessions.delete(sid)
@@ -460,11 +471,16 @@ export async function startRemoteAgent (opts = {}) {
460
471
  }
461
472
 
462
473
  const vaultTick = async () => { await refreshRevocations(); await renewCertIfNeeded() }
474
+ // En cada tic se mira también la caché del proxio: si el agente se perdió el aviso de que
475
+ // quitaron un aparato y la bóveda está apagada, esa sesión no espera a que la bóveda vuelva.
476
+ const tick = async () => { try { await actaFromProxy() } catch (_) {} await vaultTick() }
463
477
  /** Trae el acta ahora (con freno) y dice si AVANZÓ: solo entonces merece juzgar otra vez. */
464
478
  // Ponerse al día mira primero la caché del proxio y, si no trae nada que encadene, la bóveda.
465
479
  const catchUp = makeCatchUp({ refresh: async () => { if (!await actaFromProxy()) await vaultTick() }, seq: () => link.actaSeq ?? null })
466
- vaultTick()
467
- const revTimer = setInterval(vaultTick, REVOKE_REFRESH_MS); revTimer.unref?.()
480
+ tick()
481
+ const revTimer = setInterval(tick, REVOKE_REFRESH_MS); revTimer.unref?.()
482
+ // Un aviso de bloqueo lo puede mandar cualquiera: trae la lista firmada, pero con freno.
483
+ const refreshBlocked = makeThrottle(() => refreshRevocations())
468
484
 
469
485
  const ttlMs = opts.sessionTtlMs ?? SESSION_TTL_MS
470
486
  // UNA SESIÓN QUE VENCE SE LE DICE AL CLIENTE en ese momento, con el mismo `unknown-session`
@@ -506,8 +522,11 @@ export async function startRemoteAgent (opts = {}) {
506
522
  return { chk: { ...chk, device: /** @type {string} */ (chk.device) } } // ok: verifyChain dice qué aparato firmó
507
523
  }
508
524
  let verdict = await judge()
509
- const known = (/** @type {Awaited<ReturnType<typeof judge>>} */ v) => !!v.chk && canGreet(trustedActa(), v.chk.device)
510
- if ((verdict.error || !known(verdict)) && await catchUp()) verdict = await judge()
525
+ const known = (/** @type {Awaited<ReturnType<typeof judge>>} */ v) => !!v.chk && canGreet(trustedActa(), v.chk.device) && !missingCaps(trustedActa(), v.chk.device, NEEDS).length
526
+ // Solo se pregunta a la bóveda si un acta más nueva podría cambiar el veredicto: un saludo
527
+ // cuya firma no vale (o mal formado) no la despierta, por mucho que lleguen.
528
+ const couldChange = (/** @type {Awaited<ReturnType<typeof judge>>} */ v) => v.chk ? !known(v) : !PRE_AUTH.has(/** @type {string} */ (v.reason))
529
+ if (couldChange(verdict) && await catchUp()) verdict = await judge()
511
530
  if (verdict.error) return send(from, { type: ERROR, code: verdict.code, reason: verdict.reason, error: verdict.error })
512
531
  const chk = /** @type {NonNullable<typeof verdict.chk>} */ (verdict.chk) // sin error hay chk
513
532
  // CERT ∩ ACTA. `verifyChain` comprueba QUIÉN EMITIÓ el papel; que el APARATO siga siendo
@@ -527,6 +546,13 @@ export async function startRemoteAgent (opts = {}) {
527
546
  if (!canGreet(trustedActa(), chk.device)) {
528
547
  return send(from, { type: ERROR, code: 'unauthorized', reason: 'not-in-record', error: 'unauthorized: not-in-record' })
529
548
  }
549
+ // EL PERMISO DEL PRODUCTO (`terminal`, `desktop`…). Se dice cuál falta, para que la app
550
+ // pueda enseñar la orden que lo concede (`dotrino-vault caps <ID> +desktop`).
551
+ const lacking = missingCaps(trustedActa(), chk.device, NEEDS)
552
+ if (lacking.length) {
553
+ audit('session-refused', { reason: 'missing-cap', caps: lacking, device: (await pubkeyId(chk.device)).slice(0, 8).toUpperCase() })
554
+ return send(from, { type: ERROR, code: 'unauthorized', reason: 'missing-cap', caps: lacking, error: 'unauthorized: missing-cap ' + lacking.join(',') })
555
+ }
530
556
  // BLOQUEADO por un aprobador: está en el acta y su papel vale, y aun así no entra. Se le
531
557
  // dice con su código, que no es lo mismo que un papel viejo ni que una revocación.
532
558
  if (blockedSet.has(chk.device)) {
@@ -568,10 +594,14 @@ export async function startRemoteAgent (opts = {}) {
568
594
  // se reinició, o venció) y vuelve a saludar solo, en vez de quedarse con un error. Se
569
595
  // comprueba por el código, no por la frase.
570
596
  if (!s) return send(from, { type: ERROR, code: 'unknown-session', sid: p.sid, error: 'unknown or expired session' })
571
- s._exp = Date.now() + ttlMs
572
- s.from = from
573
- if (s._gone) { clearTimeout(s._gone); s._gone = null }
574
- s._ingest(p.env).catch(() => send(from, { type: ERROR, error: 'invalid envelope' }))
597
+ // Quién es, por dónde contestarle y que sigue vivo cambian SOLO con un sobre que abre la
598
+ // llave de la sesión: el `sid` viaja a la vista, y con él cualquiera desviaba la salida a su
599
+ // token, mantenía viva la sesión o se colaba en `acceptDirectFrom`.
600
+ s._ingest(p.env, () => {
601
+ s._exp = Date.now() + ttlMs
602
+ s.from = from
603
+ if (s._gone) { clearTimeout(s._gone); s._gone = null }
604
+ }).catch(() => send(from, { type: ERROR, error: 'invalid envelope' }))
575
605
  }
576
606
 
577
607
  // LA CONEXIÓN DEL CLIENTE SE FUE: su sesión no se queda 30 minutos. El proxio avisa de que ese
@@ -635,7 +665,7 @@ export async function startRemoteAgent (opts = {}) {
635
665
  /** @param {any} payload */
636
666
  async function onAdminEvent (payload) {
637
667
  const ev = payload.body?.ev
638
- if (ev === 'blocked' || ev === 'unblocked') return refreshRevocations()
668
+ if (ev === 'blocked' || ev === 'unblocked') return refreshBlocked()
639
669
  if (payload.acta && await recordActa(payload.acta)) return
640
670
  if (typeof payload.acta?.seq === 'number' && payload.acta.seq > (link.actaSeq ?? -1)) await catchUp()
641
671
  }
package/src/catch-up.js CHANGED
@@ -32,3 +32,24 @@ export function makeCatchUp ({ refresh, seq, minGapMs = CATCH_UP_GAP_MS, now = D
32
32
  return running
33
33
  }
34
34
  }
35
+
36
+ /**
37
+ * UN AVISO QUE CUALQUIERA PUEDE MANDAR no dispara el trabajo cada vez: como mucho una vez cada
38
+ * `minGapMs`, y lo que llegue mientras tanto se junta en UNA llamada al final del hueco (así un
39
+ * aviso de verdad entre basura no se pierde: llega tarde, como mucho `minGapMs`).
40
+ * @param {() => Promise<unknown>} fn
41
+ * @param {{ minGapMs?: number, now?: () => number, setTimer?: (f: () => void, ms: number) => unknown }} [o]
42
+ * @returns {() => void}
43
+ */
44
+ export function makeThrottle (fn, { minGapMs = CATCH_UP_GAP_MS, now = Date.now, setTimer = (f, ms) => { const t = setTimeout(f, ms); t.unref?.(); return t } } = {}) {
45
+ let last = -Infinity
46
+ let pending = false
47
+ const run = () => { last = now(); Promise.resolve().then(fn).catch(() => {}) }
48
+ return () => {
49
+ if (pending) return
50
+ const wait = last + minGapMs - now()
51
+ if (wait <= 0) return run()
52
+ pending = true
53
+ setTimer(() => { pending = false; run() }, wait)
54
+ }
55
+ }
package/src/membership.js CHANGED
@@ -25,4 +25,19 @@ export function canGreet (acta, pub) {
25
25
  return (acta.members || []).some((m) => samePubkey(m?.pub, pub)) && memberCan(acta, pub, 'sign')
26
26
  }
27
27
 
28
- export default { canGreet }
28
+ /**
29
+ * Los permisos de PRODUCTO que le faltan a ese aparato (`terminal`, `desktop`…): los que el
30
+ * agente declara en `needs`, además de `sign` (dueño, 2026-11-16, tras la auditoría: con solo
31
+ * `sign`, cualquier aparato del acta —un bot, un navegador prestado— abría una consola o el
32
+ * escritorio en todas las máquinas). Sin acta faltan todos: no hay con qué decir que sí.
33
+ * @param {DotrinoActa | null | undefined} acta
34
+ * @param {unknown} pub
35
+ * @param {readonly string[]} needs
36
+ * @returns {string[]}
37
+ */
38
+ export function missingCaps (acta, pub, needs) {
39
+ if (!acta || typeof pub !== 'string' || !pub) return [...needs]
40
+ return needs.filter((c) => !memberCan(acta, pub, c))
41
+ }
42
+
43
+ export default { canGreet, missingCaps }
@@ -0,0 +1,82 @@
1
+ /** Si esta máquina tiene clave. Un archivo que existe y no se puede leer NO es «sin clave»: se lanza. */
2
+ /** @param {string} dir */
3
+ export function hasAccessCode(dir: string): boolean;
4
+ /**
5
+ * Pone o cambia la clave.
6
+ * @param {string} dir
7
+ * @param {unknown} secret
8
+ */
9
+ export function setAccessCode(dir: string, secret: unknown): void;
10
+ /**
11
+ * Quita la clave.
12
+ * @param {string} dir
13
+ */
14
+ export function clearAccessCode(dir: string): void;
15
+ /**
16
+ * Si `secret` es la clave de esta máquina. Sin frenos: para la orden local que la cambia.
17
+ * @param {string} dir
18
+ * @param {unknown} secret
19
+ */
20
+ export function checkAccessCode(dir: string, secret: unknown): boolean;
21
+ /**
22
+ * La puerta de un agente: comprueba la clave y frena los fallos seguidos. Una por agente,
23
+ * compartida por todas sus sesiones.
24
+ * @param {string} dir
25
+ * @param {{ now?: () => number, onIncident?: ((i: { device: string, tries: number }) => void) | null }} [opts]
26
+ * `onIncident`: un mismo aparato (`device`, su pubkey) falló `INCIDENT_AFTER` veces seguidas.
27
+ * Se llama UNA vez por racha; la racha se corta al acertar.
28
+ */
29
+ export function makeGate(dir: string, { now, onIncident }?: {
30
+ now?: () => number;
31
+ onIncident?: ((i: {
32
+ device: string;
33
+ tries: number;
34
+ }) => void) | null;
35
+ }): {
36
+ /** Si hay que escribir la clave para entrar. Lanza `access-unreadable` si no se puede saber. */
37
+ required: () => boolean;
38
+ /**
39
+ * Lanza `wait` (con `retryMs`) o `bad-code`; si no lanza, la clave era la buena.
40
+ * `device` es quién la escribió (pubkey), para contar sus fallos y avisar.
41
+ */
42
+ /**
43
+ * @param {unknown} secret
44
+ * @param {string | null} [device]
45
+ */
46
+ check(secret: unknown, device?: string | null): void;
47
+ };
48
+ /**
49
+ * El candado de UNA sesión: hasta que escribe la clave (si la máquina tiene), no pasa nada más.
50
+ * Una vez escrita vale para esa conexión. Sin `gate` (lo local), siempre pasa.
51
+ *
52
+ * session.on('message', (msg) => {
53
+ * if (lock.handle(msg)) return // era el `unlock`: ya contestó
54
+ * if (!lock.mayPass()) return // ya contestó `locked` (o que no se puede saber)
55
+ * …
56
+ * })
57
+ *
58
+ * No saber si hay clave (el archivo no se puede leer) es no pasar, y se dice.
59
+ * @param {{ gate: ReturnType<typeof makeGate> | null, device?: string | null,
60
+ * send: (msg: object) => unknown }} o
61
+ */
62
+ export function makeLock({ gate, device, send }: {
63
+ gate: ReturnType<typeof makeGate> | null;
64
+ device?: string | null;
65
+ send: (msg: object) => unknown;
66
+ }): {
67
+ readonly unlocked: boolean;
68
+ /** True si esta sesión puede seguir; si no, ya contestó por qué. */
69
+ mayPass(): boolean;
70
+ /** Si `msg` es el `unlock`, lo atiende y devuelve true. @param {any} msg */
71
+ handle(msg: any): boolean;
72
+ };
73
+ export const ACCESS_FILE: "access.json";
74
+ export const MIN_LENGTH: 4;
75
+ /** Fallos seguidos que se dejan pasar sin esperar: al tercero empieza la espera. */
76
+ export const FREE_TRIES: 3;
77
+ /** Fallos seguidos de un mismo aparato que disparan el aviso a la bóveda. */
78
+ export const INCIDENT_AFTER: 3;
79
+ export type Thrown = Error & {
80
+ code?: string;
81
+ retryMs?: number;
82
+ };
@@ -18,7 +18,9 @@
18
18
  * @param {string} [opts.product] qué producto es (`accounts`, `terminal-agent`…), para el anuncio a la bóveda.
19
19
  * @param {string} [opts.version] su versión. Sin `product`/`version` se anuncia como `remote-agent`.
20
20
  * @param {string[]} [opts.needs] los permisos del acta que necesita, además de `sign`, que lo
21
- * añade este pilar: sin él no se abre ninguna sesión (`@dotrino/compat` ≥ 0.5.0).
21
+ * añade este pilar: sin él no se abre ninguna sesión (`@dotrino/compat` ≥ 0.5.0). Desde 0.38.0
22
+ * también se EXIGEN a quien saluda: un aparato sin ellos no abre sesión (`missing-cap`), y si
23
+ * se los quitan con la sesión abierta, se le cierra.
22
24
  *
23
25
  * Devuelve además el **`client`** (el `WebSocketProxyClient` ya conectado e
24
26
  * identificado bajo la pubkey de esta máquina). Se expone a propósito: un agente
@@ -140,10 +142,8 @@ export class AgentSession {
140
142
  on(ev: "message" | "close", cb: (msg?: any) => void): this;
141
143
  /** Lo que llega se entrega en el orden en que llegó, tarde lo que tarde en descifrarse cada uno. */
142
144
  /** @param {{ iv: string, ct: string }} env */
143
- _ingest(env: {
144
- iv: string;
145
- ct: string;
146
- }): Promise<void>;
145
+ /** @param {any} env @param {() => void} [onOpen] solo si el sobre abre, antes de repartirlo */
146
+ _ingest(env: any, onOpen?: () => void): Promise<void>;
147
147
  close(): void;
148
148
  }
149
149
  declare namespace _default {
@@ -8,6 +8,19 @@ export function makeCatchUp({ refresh, seq, minGapMs, now }: {
8
8
  minGapMs?: number;
9
9
  now?: () => number;
10
10
  }): () => Promise<boolean>;
11
+ /**
12
+ * UN AVISO QUE CUALQUIERA PUEDE MANDAR no dispara el trabajo cada vez: como mucho una vez cada
13
+ * `minGapMs`, y lo que llegue mientras tanto se junta en UNA llamada al final del hueco (así un
14
+ * aviso de verdad entre basura no se pierde: llega tarde, como mucho `minGapMs`).
15
+ * @param {() => Promise<unknown>} fn
16
+ * @param {{ minGapMs?: number, now?: () => number, setTimer?: (f: () => void, ms: number) => unknown }} [o]
17
+ * @returns {() => void}
18
+ */
19
+ export function makeThrottle(fn: () => Promise<unknown>, { minGapMs, now, setTimer }?: {
20
+ minGapMs?: number;
21
+ now?: () => number;
22
+ setTimer?: (f: () => void, ms: number) => unknown;
23
+ }): () => void;
11
24
  /**
12
25
  * catch-up.js — ponerse al día con la bóveda ANTES de rechazar a alguien.
13
26
  *
@@ -5,8 +5,20 @@
5
5
  * @returns {boolean}
6
6
  */
7
7
  export function canGreet(acta: DotrinoActa | null | undefined, pub: unknown): boolean;
8
+ /**
9
+ * Los permisos de PRODUCTO que le faltan a ese aparato (`terminal`, `desktop`…): los que el
10
+ * agente declara en `needs`, además de `sign` (dueño, 2026-11-16, tras la auditoría: con solo
11
+ * `sign`, cualquier aparato del acta —un bot, un navegador prestado— abría una consola o el
12
+ * escritorio en todas las máquinas). Sin acta faltan todos: no hay con qué decir que sí.
13
+ * @param {DotrinoActa | null | undefined} acta
14
+ * @param {unknown} pub
15
+ * @param {readonly string[]} needs
16
+ * @returns {string[]}
17
+ */
18
+ export function missingCaps(acta: DotrinoActa | null | undefined, pub: unknown, needs: readonly string[]): string[];
8
19
  declare namespace _default {
9
20
  export { canGreet };
21
+ export { missingCaps };
10
22
  }
11
23
  export default _default;
12
24
  export type DotrinoActa = import("./shapes.js").DotrinoActa;