@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 +3 -0
- package/package.json +5 -1
- package/src/access.js +193 -0
- package/src/agent.js +45 -15
- package/src/catch-up.js +21 -0
- package/src/membership.js +16 -1
- package/types/src/access.d.ts +82 -0
- package/types/src/agent.d.ts +5 -5
- package/types/src/catch-up.d.ts +13 -0
- package/types/src/membership.d.ts +12 -0
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.
|
|
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
|
-
|
|
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)
|
|
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.
|
|
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
|
-
|
|
467
|
-
const revTimer = setInterval(
|
|
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
|
-
|
|
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
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
s._ingest(p.env
|
|
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
|
|
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
|
-
|
|
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
|
+
};
|
package/types/src/agent.d.ts
CHANGED
|
@@ -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
|
-
|
|
144
|
-
|
|
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 {
|
package/types/src/catch-up.d.ts
CHANGED
|
@@ -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;
|