@dotrino/remote-agent 0.32.2 → 0.33.1
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/package.json +41 -14
- package/src/agent.js +32 -13
- package/src/client.js +2 -1
- package/src/discover.js +2 -0
- package/src/link.js +2 -0
- package/src/membership.js +1 -0
- package/src/record.js +1 -0
- package/src/shapes.d.ts +25 -0
- package/types/e2e.d.ts +1 -0
- package/types/index.d.ts +2 -0
- package/types/node-globals.d.ts +8 -0
- package/types/protocol.d.ts +49 -0
- package/types/src/agent.d.ts +153 -0
- package/types/src/browser-link.d.ts +30 -0
- package/types/src/catch-up.d.ts +22 -0
- package/types/src/client.d.ts +181 -0
- package/types/src/discover.d.ts +53 -0
- package/types/src/instances.d.ts +34 -0
- package/types/src/link.d.ts +281 -0
- package/types/src/membership.d.ts +12 -0
- package/types/src/record.d.ts +18 -0
- package/types/src/shapes.d.ts +25 -0
package/package.json
CHANGED
|
@@ -1,29 +1,56 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dotrino/remote-agent",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.33.1",
|
|
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",
|
|
7
|
+
"types": "./types/index.d.ts",
|
|
7
8
|
"exports": {
|
|
8
|
-
".":
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
"./
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
9
|
+
".": {
|
|
10
|
+
"types": "./types/index.d.ts",
|
|
11
|
+
"import": "./index.js"
|
|
12
|
+
},
|
|
13
|
+
"./agent": {
|
|
14
|
+
"types": "./types/src/agent.d.ts",
|
|
15
|
+
"import": "./src/agent.js"
|
|
16
|
+
},
|
|
17
|
+
"./client": {
|
|
18
|
+
"types": "./types/src/client.d.ts",
|
|
19
|
+
"import": "./src/client.js"
|
|
20
|
+
},
|
|
21
|
+
"./link": {
|
|
22
|
+
"types": "./types/src/link.d.ts",
|
|
23
|
+
"import": "./src/link.js"
|
|
24
|
+
},
|
|
25
|
+
"./browser-link": {
|
|
26
|
+
"types": "./types/src/browser-link.d.ts",
|
|
27
|
+
"import": "./src/browser-link.js"
|
|
28
|
+
},
|
|
29
|
+
"./discover": {
|
|
30
|
+
"types": "./types/src/discover.d.ts",
|
|
31
|
+
"import": "./src/discover.js"
|
|
32
|
+
},
|
|
33
|
+
"./node-globals": {
|
|
34
|
+
"types": "./types/node-globals.d.ts",
|
|
35
|
+
"import": "./node-globals.js"
|
|
36
|
+
},
|
|
37
|
+
"./instances": {
|
|
38
|
+
"types": "./types/src/instances.d.ts",
|
|
39
|
+
"import": "./src/instances.js"
|
|
40
|
+
}
|
|
16
41
|
},
|
|
17
42
|
"files": [
|
|
18
43
|
"index.js",
|
|
19
44
|
"e2e.js",
|
|
20
45
|
"protocol.js",
|
|
21
46
|
"node-globals.js",
|
|
22
|
-
"src"
|
|
47
|
+
"src",
|
|
48
|
+
"types"
|
|
23
49
|
],
|
|
24
50
|
"scripts": {
|
|
25
51
|
"test": "node --test 'test/**/*.test.js'",
|
|
26
|
-
"type-check": "tsc --noEmit"
|
|
52
|
+
"type-check": "tsc --noEmit",
|
|
53
|
+
"types": "node scripts/types.mjs"
|
|
27
54
|
},
|
|
28
55
|
"dependencies": {
|
|
29
56
|
"@dotrino/compat": "0.5.0",
|
|
@@ -48,13 +75,13 @@
|
|
|
48
75
|
"p2p"
|
|
49
76
|
],
|
|
50
77
|
"peerDependencies": {
|
|
51
|
-
"@dotrino/identity": ">=0.
|
|
78
|
+
"@dotrino/identity": ">=0.136.0",
|
|
52
79
|
"@dotrino/proxy-client": ">=0.46.0",
|
|
53
80
|
"@dotrino/vault": ">=0.115.0"
|
|
54
81
|
},
|
|
55
82
|
"devDependencies": {
|
|
56
|
-
"@dotrino/identity": "0.
|
|
57
|
-
"@dotrino/proxy-client": "0.
|
|
83
|
+
"@dotrino/identity": "0.136.0",
|
|
84
|
+
"@dotrino/proxy-client": "0.47.0",
|
|
58
85
|
"@dotrino/vault": "0.115.0",
|
|
59
86
|
"@types/node": "22.20.1",
|
|
60
87
|
"@types/ws": "8.18.1",
|
package/src/agent.js
CHANGED
|
@@ -23,6 +23,7 @@ import fs from 'node:fs'
|
|
|
23
23
|
import path from 'node:path'
|
|
24
24
|
import { verifyChain, signWithDevice, verifyDeviceSig, pubkeyId, keyLabel } from '@dotrino/identity/capabilities'
|
|
25
25
|
import { sealersOf, memberCan, checkVaultReply } from '@dotrino/identity/acta'
|
|
26
|
+
import { sendToVault, acceptReply } from '@dotrino/identity/vault-seal'
|
|
26
27
|
import { adoptRecord } from './record.js'
|
|
27
28
|
import { canGreet } from './membership.js'
|
|
28
29
|
import { installNodeGlobals } from '../node-globals.js'
|
|
@@ -32,6 +33,7 @@ import { HS, ACK, DATA, PING, PONG, ERROR, VMSG, SIGN_SCOPE, SESSION_TTL_MS, SES
|
|
|
32
33
|
import { loadLink, saveLink, dataDir, renewalReason, storeRenewedCert } from './link.js'
|
|
33
34
|
import { declare } from '@dotrino/compat'
|
|
34
35
|
import { VAULT_PROTOCOL, VAULT_SPEAKS } from '@dotrino/vault/protocol'
|
|
36
|
+
/** @typedef {import('./shapes.js').DotrinoActa} DotrinoActa */
|
|
35
37
|
|
|
36
38
|
const PKG_VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
|
|
37
39
|
|
|
@@ -236,24 +238,41 @@ export async function startRemoteAgent (opts = {}) {
|
|
|
236
238
|
* @returns {Promise<any>} la respuesta de la bóveda; cada llamador lee sus campos con guardas
|
|
237
239
|
*/
|
|
238
240
|
async function vaultRpc (sendType, okType, payload, timeoutMs = 15000) {
|
|
241
|
+
// SELLADA (`dotrino-vault/docs/sealed-requests.md`): la petición entera a las bóvedas del
|
|
242
|
+
// acta, y la respuesta a una llave de un solo uso (`rek`) que va dentro de lo firmado. Por
|
|
243
|
+
// eso va por una conexión PROPIA y corta: el cliente compartido no puede abrir lo sellado a
|
|
244
|
+
// una llave que no es la suya. Con `opts.client` (solo pruebas, una bóveda de mentira) va
|
|
245
|
+
// por ese transporte tal cual.
|
|
246
|
+
const { makeEncKeypair, WebSocketProxyClient } = await import('@dotrino/proxy-client')
|
|
247
|
+
const rk = opts.client ? null : await makeEncKeypair()
|
|
239
248
|
// QUÉ SOY Y QUÉ NECESITO DEL ACTA, dentro de lo firmado: la bóveda lo apunta y enseña lo que
|
|
240
249
|
// falta en la fila de este aparato (dueño, 2026-10-27). `accounts` se pasó días sin `sign`,
|
|
241
250
|
// renovando un papel que no le servía, sin que ninguna pantalla lo dijera.
|
|
242
|
-
const data = { ...payload, v: MY_DECL }
|
|
251
|
+
const data = { ...payload, ...(rk ? { rek: rk.encPub } : {}), v: MY_DECL }
|
|
243
252
|
const { signature } = await signWithDevice({ privateJwk: link.device.privateJwk, data })
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
253
|
+
const message = { type: sendType, data, signature, cert: link.cert }
|
|
254
|
+
/** @type {any} */
|
|
255
|
+
const via = opts.client || new WebSocketProxyClient({ url: proxyUrl, autoReconnect: false, myEncPrivateKey: rk?.privateKey })
|
|
256
|
+
const warn = (/** @type {string} */ line) => { if (!opts.quiet) console.error('[remote-agent] ' + line) }
|
|
257
|
+
try {
|
|
258
|
+
if (!opts.client) await via.connect()
|
|
259
|
+
return await new Promise((resolve, reject) => {
|
|
260
|
+
// El temporizador se LIMPIA al contestar (y no retiene el bucle de eventos):
|
|
261
|
+
// sin eso, cada consulta al vault dejaba 15 s de espera pendiente y un proceso
|
|
262
|
+
// corto que solo quería preguntar algo se quedaba colgado hasta que vencía.
|
|
263
|
+
const done = (/** @type {(v: any) => void} */ fn, /** @type {unknown} */ v) => { off(); clearTimeout(timer); fn(v) }
|
|
264
|
+
const off = via.on('message', (/** @type {any} */ _f, /** @type {any} */ p, /** @type {any} */ meta) => {
|
|
265
|
+
if (p?.type === okType) {
|
|
266
|
+
if (!opts.client && !acceptReply({ meta, type: okType, warn })) return
|
|
267
|
+
done(resolve, p)
|
|
268
|
+
} else if (p?.type === VMSG.ERROR) done(reject, new Error(p.error))
|
|
269
|
+
})
|
|
270
|
+
const timer = setTimeout(() => done(reject, new Error('timeout')), timeoutMs)
|
|
271
|
+
timer.unref?.()
|
|
272
|
+
if (opts.client) via.sendByPubkey(master, message)
|
|
273
|
+
else sendToVault(via, { dest: master, acta: link.acta || null, payload: message, warn }).catch((e) => done(reject, e))
|
|
252
274
|
})
|
|
253
|
-
|
|
254
|
-
timer.unref?.()
|
|
255
|
-
client.sendByPubkey(master, { type: sendType, data, signature, cert: link.cert })
|
|
256
|
-
})
|
|
275
|
+
} finally { if (!opts.client) { try { via.close() } catch (_) {} } }
|
|
257
276
|
}
|
|
258
277
|
|
|
259
278
|
// --- Revocación: refrescar la lista del vault por el proxy (best-effort) ---
|
package/src/client.js
CHANGED
|
@@ -25,6 +25,8 @@ import { sealersOf, samePubkey, canAdopt } from '@dotrino/identity/acta'
|
|
|
25
25
|
import { makeEphemeral, deriveKey, seal, open } from '../e2e.js'
|
|
26
26
|
import { canGreet } from './membership.js'
|
|
27
27
|
import { HS, ACK, DATA, PING, PONG, ERROR, DEFAULT_PROXY } from '../protocol.js'
|
|
28
|
+
/** @typedef {import('./shapes.js').AgentIdentity} AgentIdentity */
|
|
29
|
+
/** @typedef {import('./shapes.js').DotrinoActa} DotrinoActa */
|
|
28
30
|
|
|
29
31
|
/**
|
|
30
32
|
* El enlace con que se habla a un agente: el de una pestaña (identidad del vault) o el de
|
|
@@ -158,7 +160,6 @@ export class RemoteAgentClient {
|
|
|
158
160
|
|
|
159
161
|
// El agente se reinició: su token ya no existe. El pilar ya mandó ese mensaje por su
|
|
160
162
|
// pubkey; aquí solo se deja de usar el token hasta el próximo saludo.
|
|
161
|
-
// @ts-expect-error proxy-client 0.46.0: su ProxyEvent no lista 'token_gone', que sí emite (src/client.js)
|
|
162
163
|
client.on('token_gone', (/** @type {string} */ token) => {
|
|
163
164
|
this._directPeers.delete(token)
|
|
164
165
|
if (token === this.agentToken) this.agentToken = null
|
package/src/discover.js
CHANGED
|
@@ -22,6 +22,8 @@
|
|
|
22
22
|
*/
|
|
23
23
|
|
|
24
24
|
import { PING, PONG } from '../protocol.js'
|
|
25
|
+
/** @typedef {import('./shapes.js').AgentIdentity} AgentIdentity */
|
|
26
|
+
/** @typedef {import('./shapes.js').DotrinoActa} DotrinoActa */
|
|
25
27
|
|
|
26
28
|
/**
|
|
27
29
|
* @param {AgentIdentity} id instancia de Identity (del vault) ya conectada.
|
package/src/link.js
CHANGED
|
@@ -25,6 +25,8 @@ import { DEFAULT_PROXY, RENEW_BEFORE_MS } from '../protocol.js'
|
|
|
25
25
|
// Estático y no perezoso: `loadLink`/`saveLink` son síncronos y así siguen. Necesita
|
|
26
26
|
// @dotrino/vault >= 0.115.0 (la primera que exporta `atrest`).
|
|
27
27
|
import { atRestFor, isEncrypted } from '@dotrino/vault/atrest'
|
|
28
|
+
/** @typedef {import('./shapes.js').AgentIdentity} AgentIdentity */
|
|
29
|
+
/** @typedef {import('./shapes.js').DotrinoActa} DotrinoActa */
|
|
28
30
|
|
|
29
31
|
/**
|
|
30
32
|
* El papel de un aparato: lo firma la bóveda. `seq` es el del acta con que se emitió; `exp`
|
package/src/membership.js
CHANGED
package/src/record.js
CHANGED
|
@@ -16,6 +16,7 @@
|
|
|
16
16
|
* Sin dependencias de Node: lo usa el agente y se prueba solo.
|
|
17
17
|
*/
|
|
18
18
|
import { canAdopt, verifyActa, samePubkey } from '@dotrino/identity/acta'
|
|
19
|
+
/** @typedef {import('./shapes.js').DotrinoActa} DotrinoActa */
|
|
19
20
|
|
|
20
21
|
/**
|
|
21
22
|
* @param {{ link: import('./link.js').AgentLink, candidate: DotrinoActa | null | undefined, me: string }} args `me` = la llave pública de esta máquina.
|
package/src/shapes.d.ts
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Las formas de datos que aparecen en los tipos publicados de @dotrino/remote-agent. Solo
|
|
3
|
+
* tipos: no hay código aquí. `npm run types` lo copia a `types/src/` junto a los generados.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Lo que un cliente del ecosistema usa de una identidad: el `Identity` del navegador o la que
|
|
8
|
+
* arma `identityFromLink` con la llave de un aparato.
|
|
9
|
+
*/
|
|
10
|
+
export interface AgentIdentity {
|
|
11
|
+
me: { publickey: string, nickname?: string } | null
|
|
12
|
+
signData (data: object): Promise<{ signature: string, publickey?: string, profileId?: string | null, chain?: unknown[] | null } & Record<string, unknown>>
|
|
13
|
+
listVaultDevices (): Promise<{ acta?: DotrinoActa | null } & Record<string, unknown>>
|
|
14
|
+
profileActa? (): Promise<{ acta: DotrinoActa } | null>
|
|
15
|
+
getVaultCert? (): Promise<{ cert: unknown }>
|
|
16
|
+
vaultStatus? (): Promise<Record<string, unknown>>
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/** Un acta (la lista de miembros de una cuenta). Llega de la red: se comprueba antes de usarla. */
|
|
20
|
+
export interface DotrinoActa {
|
|
21
|
+
seq: number
|
|
22
|
+
profileId: string
|
|
23
|
+
members?: Array<{ pub: string, caps?: string[], label?: string, cn?: string } & Record<string, unknown>>
|
|
24
|
+
[k: string]: unknown
|
|
25
|
+
}
|
package/types/e2e.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { makeEphemeral, deriveKey, seal, open, b64 } from "@dotrino/identity/channel";
|
package/types/index.d.ts
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/** localStorage síncrono respaldado por un archivo JSON (solo lo que usan los paquetes). */
|
|
2
|
+
/**
|
|
3
|
+
* @param {string} filePath
|
|
4
|
+
* @returns {Storage}
|
|
5
|
+
*/
|
|
6
|
+
export function fileLocalStorage(filePath: string): Storage;
|
|
7
|
+
/** @param {string} dir dónde vive `transport.json` (la llave de transporte del proxy-client) */
|
|
8
|
+
export function installNodeGlobals(dir: string): void;
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* protocol.js — constantes del protocolo de transporte de `@dotrino/remote-agent`.
|
|
3
|
+
*
|
|
4
|
+
* El protocolo tiene dos capas:
|
|
5
|
+
* 1. Envelope de transporte (visible al relay/proxy): `{ type, sid, env?, ... }`.
|
|
6
|
+
* Usa los tipos `ra.*` de aquí abajo. El proxy solo ve el `type` + ciphertext.
|
|
7
|
+
* 2. Payload de dominio (dentro de `env`, cifrado AES-256-GCM): un objeto
|
|
8
|
+
* arbitrario definido por CADA app (terminal envía `{type:'cmd',...}`,
|
|
9
|
+
* ia envía `{type:'msg',...}`). El paquete no impone su forma.
|
|
10
|
+
*
|
|
11
|
+
* El handshake (HS/ACK) y la liveness (PING/PONG) son comunes; el despacho de
|
|
12
|
+
* payloads de dominio viaja por el tipo `DATA` genérico.
|
|
13
|
+
*/
|
|
14
|
+
export const HS: "ra.hs";
|
|
15
|
+
export const ACK: "ra.hs.ack";
|
|
16
|
+
export const DATA: "ra.data";
|
|
17
|
+
export const PING: "ra.ping";
|
|
18
|
+
export const PONG: "ra.pong";
|
|
19
|
+
export const ERROR: "ra.error";
|
|
20
|
+
export namespace VMSG {
|
|
21
|
+
let DEVICES: string;
|
|
22
|
+
let DEVICES_RESULT: string;
|
|
23
|
+
let REVOKED: string;
|
|
24
|
+
let RENEW: string;
|
|
25
|
+
let RENEWED: string;
|
|
26
|
+
let INCIDENT: string;
|
|
27
|
+
let INCIDENT_RESULT: string;
|
|
28
|
+
let ERROR: string;
|
|
29
|
+
}
|
|
30
|
+
/** El proxio por defecto, cuando el enlace no trae uno. Única definición del paquete. */
|
|
31
|
+
export const DEFAULT_PROXY: "wss://proxy.dotrino.com";
|
|
32
|
+
/** Scope del cert de dispositivo que autoriza a hablar con el agente. */
|
|
33
|
+
export const SIGN_SCOPE: "vault:sign";
|
|
34
|
+
/** Vigencia de una sesión inactiva y refresco de la lista de revocados. */
|
|
35
|
+
export const SESSION_TTL_MS: number;
|
|
36
|
+
export const REVOKE_REFRESH_MS: number;
|
|
37
|
+
/**
|
|
38
|
+
* Cuánto se espera a un cliente cuya conexión se fue antes de cerrarle la sesión. Un cliente
|
|
39
|
+
* que reconecta sigue con su sesión desde un token nuevo: si en este plazo manda algo, se queda.
|
|
40
|
+
*/
|
|
41
|
+
export const SESSION_GONE_MS: number;
|
|
42
|
+
/**
|
|
43
|
+
* RENOVACIÓN del cert de esta máquina. El cert dura 30 días; se pide uno fresco
|
|
44
|
+
* cuando le quedan menos de 7. El margen es amplio a propósito: un agente puede
|
|
45
|
+
* pasar días con el proxy caído o la bóveda apagada, y debe tener muchas ventanas
|
|
46
|
+
* de reintento antes de que el cert venza. Un cert VENCIDO ya no se renueva —ahí
|
|
47
|
+
* toca re-emparejar a mano—, que es exactamente lo que esto viene a evitar.
|
|
48
|
+
*/
|
|
49
|
+
export const RENEW_BEFORE_MS: number;
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Arranca el agente. Devuelve `{ machine, machineId, master, client, reportIncident, isBlocked, checkCap, record, close }`.
|
|
3
|
+
*
|
|
4
|
+
* @param {object} [opts]
|
|
5
|
+
* @param {string} [opts.label] qué agente es (`terminal-agent`, `ia-agent`…): lo contesta el pong
|
|
6
|
+
* para que las apps lo encuentren (`probeAgents`). El nombre del acta es del dueño.
|
|
7
|
+
* @param {string} [opts.proxyUrl] default wss://proxy.dotrino.com.
|
|
8
|
+
* @param {string} [opts.dir] dir del enlace (default dataDir()).
|
|
9
|
+
* @param {import('./link.js').AgentLink | null} [opts.link] enlace ya cargado (override de dir).
|
|
10
|
+
* @param {(session:AgentSession)=>void} [opts.onSession] cada handshake exitoso abre una sesión.
|
|
11
|
+
* @param {()=>void} [opts.onRevoked] se llamó al auto-borrarse por revocación.
|
|
12
|
+
* @param {(o: { machine: string, machineId: string, master: string }) => void} [opts.onReady] agente listo y escuchando.
|
|
13
|
+
* @param {boolean} [opts.quiet] sin logs.
|
|
14
|
+
* @param {number} [opts.sessionGoneMs] cuánto se espera a un cliente cuya conexión se fue (`SESSION_GONE_MS`).
|
|
15
|
+
* @param {number} [opts.sessionTtlMs] cuánto dura una sesión sin mensajes (`SESSION_TTL_MS`, 30 min).
|
|
16
|
+
* @param {number} [opts.netLogMs] cada cuánto van al log las estadísticas de red (5 min).
|
|
17
|
+
* @param {import('@dotrino/proxy-client').WebSocketProxyClient} [opts.client] transporte ya conectado (SOLO pruebas).
|
|
18
|
+
* @param {string} [opts.product] qué producto es (`accounts`, `terminal-agent`…), para el anuncio a la bóveda.
|
|
19
|
+
* @param {string} [opts.version] su versión. Sin `product`/`version` se anuncia como `remote-agent`.
|
|
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).
|
|
22
|
+
*
|
|
23
|
+
* Devuelve además el **`client`** (el `WebSocketProxyClient` ya conectado e
|
|
24
|
+
* identificado bajo la pubkey de esta máquina). Se expone a propósito: un agente
|
|
25
|
+
* que necesite algo más del transporte —anunciarse en un canal, por ejemplo— debe
|
|
26
|
+
* reusar ESTA conexión y no abrir otra. Dos conexiones del mismo aparato al proxy
|
|
27
|
+
* son dos identidades de transporte, dos `identify` y dos colas: exactamente el
|
|
28
|
+
* lío que este middleware existe para evitar.
|
|
29
|
+
*/
|
|
30
|
+
export function startRemoteAgent(opts?: {
|
|
31
|
+
label?: string | undefined;
|
|
32
|
+
proxyUrl?: string | undefined;
|
|
33
|
+
dir?: string | undefined;
|
|
34
|
+
link?: import("./link.js").AgentLink | null | undefined;
|
|
35
|
+
onSession?: ((session: AgentSession) => void) | undefined;
|
|
36
|
+
onRevoked?: (() => void) | undefined;
|
|
37
|
+
onReady?: ((o: {
|
|
38
|
+
machine: string;
|
|
39
|
+
machineId: string;
|
|
40
|
+
master: string;
|
|
41
|
+
}) => void) | undefined;
|
|
42
|
+
quiet?: boolean | undefined;
|
|
43
|
+
sessionGoneMs?: number | undefined;
|
|
44
|
+
sessionTtlMs?: number | undefined;
|
|
45
|
+
netLogMs?: number | undefined;
|
|
46
|
+
client?: import("@dotrino/proxy-client").WebSocketProxyClient | undefined;
|
|
47
|
+
product?: string | undefined;
|
|
48
|
+
version?: string | undefined;
|
|
49
|
+
needs?: string[] | undefined;
|
|
50
|
+
}): Promise<{
|
|
51
|
+
machine: string;
|
|
52
|
+
machineId: string;
|
|
53
|
+
master: string;
|
|
54
|
+
client: import("@dotrino/proxy-client").WebSocketProxyClient;
|
|
55
|
+
reportIncident: ({ kind, about, tries }: {
|
|
56
|
+
kind: string;
|
|
57
|
+
about: string;
|
|
58
|
+
tries?: number | null;
|
|
59
|
+
}) => Promise<{
|
|
60
|
+
id: any;
|
|
61
|
+
approvers: any;
|
|
62
|
+
blocked: boolean;
|
|
63
|
+
}>;
|
|
64
|
+
isBlocked: (pub: string) => boolean;
|
|
65
|
+
checkCap: (pub: string, cap: string) => Promise<{
|
|
66
|
+
ok: true;
|
|
67
|
+
seq: number;
|
|
68
|
+
} | {
|
|
69
|
+
ok: false;
|
|
70
|
+
code: "no-record" | "not-in-record" | "missing-cap";
|
|
71
|
+
}>;
|
|
72
|
+
record: () => DotrinoActa | null;
|
|
73
|
+
close: () => void;
|
|
74
|
+
}>;
|
|
75
|
+
/** Sesión cifrada con un dispositivo cliente. La app recibe esto en `onSession`. */
|
|
76
|
+
export class AgentSession {
|
|
77
|
+
/**
|
|
78
|
+
* @param {{ sid: string, key: CryptoKey, from: string, device: string,
|
|
79
|
+
* send: (to: string, obj: object) => void, isDirect?: ((token: string) => boolean) | null }} o
|
|
80
|
+
*/
|
|
81
|
+
constructor({ sid, key, from, device, send, isDirect }: {
|
|
82
|
+
sid: string;
|
|
83
|
+
key: CryptoKey;
|
|
84
|
+
from: string;
|
|
85
|
+
device: string;
|
|
86
|
+
send: (to: string, obj: object) => void;
|
|
87
|
+
isDirect?: ((token: string) => boolean) | null;
|
|
88
|
+
});
|
|
89
|
+
sid: string;
|
|
90
|
+
key: CryptoKey;
|
|
91
|
+
from: string;
|
|
92
|
+
device: string;
|
|
93
|
+
_send: (to: string, obj: object) => void;
|
|
94
|
+
_isDirect: ((token: string) => boolean) | null;
|
|
95
|
+
/** @type {{ message: Array<(msg: any) => void>, close: Array<() => void> }} */
|
|
96
|
+
_h: {
|
|
97
|
+
message: Array<(msg: any) => void>;
|
|
98
|
+
close: Array<() => void>;
|
|
99
|
+
};
|
|
100
|
+
_closed: boolean;
|
|
101
|
+
/** @type {Promise<void> | undefined} */
|
|
102
|
+
_out: Promise<void> | undefined;
|
|
103
|
+
/** @type {Promise<void> | undefined} */
|
|
104
|
+
_in: Promise<void> | undefined;
|
|
105
|
+
/** Cuándo caduca sin mensajes (ms epoch). Lo pone el agente. */
|
|
106
|
+
_exp: number;
|
|
107
|
+
/**
|
|
108
|
+
* El nonce del papel del cliente, para cortarla si se revoca.
|
|
109
|
+
* @type {string | null}
|
|
110
|
+
*/
|
|
111
|
+
_certNonce: string | null;
|
|
112
|
+
/**
|
|
113
|
+
* El cliente se desconectó: se le espera hasta que salte.
|
|
114
|
+
* @type {ReturnType<typeof setTimeout> | null}
|
|
115
|
+
*/
|
|
116
|
+
_gone: ReturnType<typeof setTimeout> | null;
|
|
117
|
+
/**
|
|
118
|
+
* Envía un payload de dominio cifrado al cliente.
|
|
119
|
+
* @param {unknown} payload
|
|
120
|
+
* @returns {Promise<void>}
|
|
121
|
+
*/
|
|
122
|
+
send(payload: unknown): Promise<void>;
|
|
123
|
+
/**
|
|
124
|
+
* ¿VA YA POR EL CANAL DIRECTO (WebRTC) lo que se le mande a este cliente? Mientras sea
|
|
125
|
+
* `false`, cada `send` da la vuelta por el proxio. Sirve para que la app decida qué manda
|
|
126
|
+
* YA y qué puede esperar: nunca para dejar de mandar (subir de escalón no bloquea).
|
|
127
|
+
*/
|
|
128
|
+
direct(): boolean;
|
|
129
|
+
/**
|
|
130
|
+
* Espera a que abra el canal directo, como mucho `ms`. Resuelve `true` si abrió y `false`
|
|
131
|
+
* si se acabó el plazo o la sesión se cerró — en los dos casos se sigue, por donde haya.
|
|
132
|
+
*/
|
|
133
|
+
/** @param {number} [ms] @returns {Promise<boolean>} */
|
|
134
|
+
whenDirect(ms?: number): Promise<boolean>;
|
|
135
|
+
/**
|
|
136
|
+
* @param {'message' | 'close'} ev `message` recibe lo que mandó el cliente, ya descifrado
|
|
137
|
+
* @param {(msg?: any) => void} cb
|
|
138
|
+
* @returns {this}
|
|
139
|
+
*/
|
|
140
|
+
on(ev: "message" | "close", cb: (msg?: any) => void): this;
|
|
141
|
+
/** Lo que llega se entrega en el orden en que llegó, tarde lo que tarde en descifrarse cada uno. */
|
|
142
|
+
/** @param {{ iv: string, ct: string }} env */
|
|
143
|
+
_ingest(env: {
|
|
144
|
+
iv: string;
|
|
145
|
+
ct: string;
|
|
146
|
+
}): Promise<void>;
|
|
147
|
+
close(): void;
|
|
148
|
+
}
|
|
149
|
+
declare namespace _default {
|
|
150
|
+
export { startRemoteAgent };
|
|
151
|
+
}
|
|
152
|
+
export default _default;
|
|
153
|
+
export type DotrinoActa = import("./shapes.js").DotrinoActa;
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* El enlace de un NAVEGADOR a su bóveda, sacado del pilar de identidad (iframe
|
|
3
|
+
* id.dotrino.com): es lo que necesita `RemoteAgentClient` para hablar con un agente.
|
|
4
|
+
* Antes lo armaba cada app por su cuenta (terminal, ia, eco, content-client).
|
|
5
|
+
*
|
|
6
|
+
* Sin repliegues: si la identidad no contesta, lanza. «No pude preguntar» no es «no
|
|
7
|
+
* estás emparejado», y quien llama tiene que poder distinguirlo.
|
|
8
|
+
*
|
|
9
|
+
* @param {any} id una instancia de `Identity` (`@dotrino/identity`)
|
|
10
|
+
* @returns {Promise<{ paired: false, id: any, expired?: boolean, exp?: number }
|
|
11
|
+
* | { paired: true, id: any, cert: any, iss: string, proxy: string, deviceId: string, scope: string[] }>}
|
|
12
|
+
*/
|
|
13
|
+
export function linkFromIdentity(id: any): Promise<{
|
|
14
|
+
paired: false;
|
|
15
|
+
id: any;
|
|
16
|
+
expired?: boolean;
|
|
17
|
+
exp?: number;
|
|
18
|
+
} | {
|
|
19
|
+
paired: true;
|
|
20
|
+
id: any;
|
|
21
|
+
cert: any;
|
|
22
|
+
iss: string;
|
|
23
|
+
proxy: string;
|
|
24
|
+
deviceId: string;
|
|
25
|
+
scope: string[];
|
|
26
|
+
}>;
|
|
27
|
+
declare namespace _default {
|
|
28
|
+
export { linkFromIdentity };
|
|
29
|
+
}
|
|
30
|
+
export default _default;
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @param {{ refresh: () => Promise<unknown>, seq: () => number | null, minGapMs?: number, now?: () => number }} o
|
|
3
|
+
* @returns {() => Promise<boolean>}
|
|
4
|
+
*/
|
|
5
|
+
export function makeCatchUp({ refresh, seq, minGapMs, now }: {
|
|
6
|
+
refresh: () => Promise<unknown>;
|
|
7
|
+
seq: () => number | null;
|
|
8
|
+
minGapMs?: number;
|
|
9
|
+
now?: () => number;
|
|
10
|
+
}): () => Promise<boolean>;
|
|
11
|
+
/**
|
|
12
|
+
* catch-up.js — ponerse al día con la bóveda ANTES de rechazar a alguien.
|
|
13
|
+
*
|
|
14
|
+
* El agente trae el acta cada pocos minutos. Entre un tic y el siguiente no sabe de un aparato
|
|
15
|
+
* recién emparejado, y lo rechazaba. `makeCatchUp` da una función que trae el acta en el momento
|
|
16
|
+
* y contesta si avanzó — con un freno, porque un saludo lo puede mandar cualquiera y no por eso se
|
|
17
|
+
* le pregunta a la bóveda cada vez.
|
|
18
|
+
*
|
|
19
|
+
* @param {{ refresh: () => Promise<void>, seq: () => (number|null|undefined), minGapMs?: number, now?: () => number }} o
|
|
20
|
+
* @returns {() => Promise<boolean>} true si el acta avanzó (y vale la pena juzgar otra vez).
|
|
21
|
+
*/
|
|
22
|
+
export const CATCH_UP_GAP_MS: 10000;
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
/** @typedef {import('./shapes.js').AgentIdentity} AgentIdentity */
|
|
2
|
+
/** @typedef {import('./shapes.js').DotrinoActa} DotrinoActa */
|
|
3
|
+
/**
|
|
4
|
+
* El enlace con que se habla a un agente: el de una pestaña (identidad del vault) o el de
|
|
5
|
+
* otro agente (`clientLink`).
|
|
6
|
+
* @typedef {object} ClientLink
|
|
7
|
+
* @property {AgentIdentity} id
|
|
8
|
+
* @property {unknown} cert
|
|
9
|
+
* @property {string} [iss]
|
|
10
|
+
* @property {string} [proxy]
|
|
11
|
+
* @property {string} [mode] 'self': el dispositivo es su propio vault
|
|
12
|
+
* @property {DotrinoActa} [acta] un acta ya comprobada, si la trae
|
|
13
|
+
* @property {() => Promise<unknown>} [getSelfCert] modo self: refresca el self-cert
|
|
14
|
+
*/
|
|
15
|
+
/** Un ack del agente tal como llega (se comprueba en `_judgeAck`). */
|
|
16
|
+
/** @typedef {{ type: string, ack: any, signature: string, cert: unknown, sid: string, from?: string }} AgentAck */
|
|
17
|
+
export class RemoteAgentClient {
|
|
18
|
+
/**
|
|
19
|
+
* @param {ClientLink} link
|
|
20
|
+
* enlace del vault (modo vault) o de @dotrino/vault (modo self: el dispositivo
|
|
21
|
+
* es su propio vault; `cert` es el self-cert `P ← P` e `iss` es la propia P).
|
|
22
|
+
* @param {object} [opts] `agentPubkey` es obligatoria: `connect` la comprueba.
|
|
23
|
+
* @param {string} [opts.agentPubkey] dirección (pubkey) del agente destino.
|
|
24
|
+
* @param {string} [opts.proxyUrl] override del proxy del enlace.
|
|
25
|
+
* @param {(() => DotrinoActa | null) | null} [opts.trustedActa] un acta ya COMPROBADA y que alguien mantiene
|
|
26
|
+
* al día (un agente de Node: la de su enlace, que refresca cada 5 min y con los avisos de la
|
|
27
|
+
* bóveda). Con ella el saludo no espera a la bóveda; si no pasa, se le pregunta y se juzga
|
|
28
|
+
* otra vez. Sin ella, la bóveda en cada saludo, como siempre.
|
|
29
|
+
*/
|
|
30
|
+
constructor(link: ClientLink, { agentPubkey, proxyUrl, trustedActa }?: {
|
|
31
|
+
agentPubkey?: string | undefined;
|
|
32
|
+
proxyUrl?: string | undefined;
|
|
33
|
+
trustedActa?: (() => DotrinoActa | null) | null | undefined;
|
|
34
|
+
});
|
|
35
|
+
link: ClientLink;
|
|
36
|
+
trustedActa: (() => DotrinoActa | null) | null;
|
|
37
|
+
agentPubkey: string | undefined;
|
|
38
|
+
proxyUrl: string;
|
|
39
|
+
/** @type {import('@dotrino/proxy-client').WebSocketProxyClient | null} */
|
|
40
|
+
client: import("@dotrino/proxy-client").WebSocketProxyClient | null;
|
|
41
|
+
/** @type {CryptoKey | null} */
|
|
42
|
+
key: CryptoKey | null;
|
|
43
|
+
/** @type {string | null} */
|
|
44
|
+
sid: string | null;
|
|
45
|
+
/** @type {Record<string, Array<(...args: any[]) => void>>} */
|
|
46
|
+
_h: Record<string, Array<(...args: any[]) => void>>;
|
|
47
|
+
/** @type {Promise<void> | null} */
|
|
48
|
+
_resuming: Promise<void> | null;
|
|
49
|
+
/** @type {Promise<void> | undefined} */
|
|
50
|
+
_in: Promise<void> | undefined;
|
|
51
|
+
/** @type {Promise<void> | undefined} */
|
|
52
|
+
_out: Promise<void> | undefined;
|
|
53
|
+
/** @type {unknown} */
|
|
54
|
+
actaCacheError: unknown;
|
|
55
|
+
/** @type {string | null} */
|
|
56
|
+
agentToken: string | null;
|
|
57
|
+
/** @type {Set<string>} */
|
|
58
|
+
_directPeers: Set<string>;
|
|
59
|
+
/**
|
|
60
|
+
* Suscribe a eventos. Devuelve un `off()` para desuscribir. Eventos: message, error, resumed.
|
|
61
|
+
* @param {'message' | 'error' | 'resumed'} ev
|
|
62
|
+
* @param {(...args: any[]) => void} cb
|
|
63
|
+
* @returns {() => void}
|
|
64
|
+
*/
|
|
65
|
+
on(ev: "message" | "error" | "resumed", cb: (...args: any[]) => void): () => void;
|
|
66
|
+
/** @param {string} ev @param {...unknown} args */
|
|
67
|
+
_emit(ev: string, ...args: unknown[]): void;
|
|
68
|
+
/**
|
|
69
|
+
* El acta con la que se juzga al agente. Se pide EN CADA SALUDO, no una vez por cliente:
|
|
70
|
+
* una pestaña vive días, y volver a saludar a una máquina que el dueño quitó entretanto
|
|
71
|
+
* tiene que fallar. `listVaultDevices` devuelve el acta ya COMPROBADA (la adoptada, no la
|
|
72
|
+
* que llegó por la red: identity ≥ 0.126.2, y `identityFromLink` en Node).
|
|
73
|
+
*
|
|
74
|
+
* Si la bóveda no contesta vale la que este aparato ya adoptó (`profileActa`): está
|
|
75
|
+
* comprobada, igual que la que guarda el agente. Es lo mismo que hace `listAgentsByLabel`.
|
|
76
|
+
* Si no hay ninguna, `null` y se corta con `no-record`: sin acta no hay con qué decidir, y
|
|
77
|
+
* no decidir es que no.
|
|
78
|
+
*/
|
|
79
|
+
/** @returns {Promise<DotrinoActa | null>} */
|
|
80
|
+
_acta(): Promise<DotrinoActa | null>;
|
|
81
|
+
_identify(): Promise<void>;
|
|
82
|
+
connect(): Promise<this>;
|
|
83
|
+
/**
|
|
84
|
+
* Un error del agente. Si es que ya no conoce NUESTRA sesión (se reinició: las sesiones
|
|
85
|
+
* viven en su memoria), se vuelve a saludar solo y se avisa con `resumed`; lo que la app
|
|
86
|
+
* tenía abierto allí lo decide la app. Cualquier otro error, o no poder volver a saludar,
|
|
87
|
+
* sale por `error`. Un `unknown-session` de un `sid` que ya no es el nuestro (llegó tarde,
|
|
88
|
+
* de antes de volver a saludar) no dice nada nuevo y se ignora.
|
|
89
|
+
*/
|
|
90
|
+
/** @param {{ code?: string, error?: string, reason?: string, sid?: string }} p */
|
|
91
|
+
_onAgentError(p: {
|
|
92
|
+
code?: string;
|
|
93
|
+
error?: string;
|
|
94
|
+
reason?: string;
|
|
95
|
+
sid?: string;
|
|
96
|
+
}): void;
|
|
97
|
+
/** Vuelve a saludar, una sola vez aunque lleguen varios errores seguidos. */
|
|
98
|
+
/** @returns {Promise<void>} */
|
|
99
|
+
_resume(): Promise<void>;
|
|
100
|
+
/** El saludo: abre una sesión con el agente y deja `sid` y `key`. */
|
|
101
|
+
_handshake(): Promise<void>;
|
|
102
|
+
/**
|
|
103
|
+
* Comprueba el ack y deja `sid` y `key`.
|
|
104
|
+
* @param {AgentAck} res
|
|
105
|
+
* @param {{ privateKey: CryptoKey, pub: string }} eph
|
|
106
|
+
*/
|
|
107
|
+
_checkAck(res: AgentAck, eph: {
|
|
108
|
+
privateKey: CryptoKey;
|
|
109
|
+
pub: string;
|
|
110
|
+
}): Promise<void>;
|
|
111
|
+
/**
|
|
112
|
+
* La más nueva de la caché del proxio que ENCADENE desde `trusted` (`canAdopt`), o `null`.
|
|
113
|
+
* El proxio no es de fiar: lo que no encadena se ignora. Si no se pudo preguntar, el motivo
|
|
114
|
+
* queda en `actaCacheError` y se sigue con la bóveda, que es quien manda.
|
|
115
|
+
*/
|
|
116
|
+
/** @param {DotrinoActa} trusted @returns {Promise<DotrinoActa | null>} */
|
|
117
|
+
_actaFromProxy(trusted: DotrinoActa): Promise<DotrinoActa | null>;
|
|
118
|
+
/**
|
|
119
|
+
* Juzga el ack con `acta` y, si pasa, deja `sid` y `key`.
|
|
120
|
+
* @param {AgentAck} res
|
|
121
|
+
* @param {{ privateKey: CryptoKey, pub: string }} eph
|
|
122
|
+
* @param {DotrinoActa | null} acta
|
|
123
|
+
*/
|
|
124
|
+
_judgeAck(res: AgentAck, eph: {
|
|
125
|
+
privateKey: CryptoKey;
|
|
126
|
+
pub: string;
|
|
127
|
+
}, acta: DotrinoActa | null): Promise<void>;
|
|
128
|
+
/**
|
|
129
|
+
* Envía un payload de dominio cifrado al agente (si se está volviendo a saludar, después).
|
|
130
|
+
* @param {unknown} payload
|
|
131
|
+
* @returns {Promise<void>}
|
|
132
|
+
*/
|
|
133
|
+
send(payload: unknown): Promise<void>;
|
|
134
|
+
/**
|
|
135
|
+
* Sonda de presencia (liveness) sin abrir sesión. Devuelve true si responde.
|
|
136
|
+
* @param {{ timeoutMs?: number }} [o]
|
|
137
|
+
* @returns {Promise<boolean>}
|
|
138
|
+
*/
|
|
139
|
+
ping({ timeoutMs }?: {
|
|
140
|
+
timeoutMs?: number;
|
|
141
|
+
}): Promise<boolean>;
|
|
142
|
+
close(): Promise<void>;
|
|
143
|
+
/** El transporte, que existe desde `connect`. Usarlo antes es un fallo de quien llama. */
|
|
144
|
+
_client(): import("@dotrino/proxy-client").WebSocketProxyClient;
|
|
145
|
+
}
|
|
146
|
+
declare namespace _default {
|
|
147
|
+
export { RemoteAgentClient };
|
|
148
|
+
}
|
|
149
|
+
export default _default;
|
|
150
|
+
export type AgentIdentity = import("./shapes.js").AgentIdentity;
|
|
151
|
+
export type DotrinoActa = import("./shapes.js").DotrinoActa;
|
|
152
|
+
/**
|
|
153
|
+
* El enlace con que se habla a un agente: el de una pestaña (identidad del vault) o el de
|
|
154
|
+
* otro agente (`clientLink`).
|
|
155
|
+
*/
|
|
156
|
+
export type ClientLink = {
|
|
157
|
+
id: AgentIdentity;
|
|
158
|
+
cert: unknown;
|
|
159
|
+
iss?: string | undefined;
|
|
160
|
+
proxy?: string | undefined;
|
|
161
|
+
/**
|
|
162
|
+
* 'self': el dispositivo es su propio vault
|
|
163
|
+
*/
|
|
164
|
+
mode?: string | undefined;
|
|
165
|
+
/**
|
|
166
|
+
* un acta ya comprobada, si la trae
|
|
167
|
+
*/
|
|
168
|
+
acta?: import("./shapes.js").DotrinoActa | undefined;
|
|
169
|
+
/**
|
|
170
|
+
* modo self: refresca el self-cert
|
|
171
|
+
*/
|
|
172
|
+
getSelfCert?: (() => Promise<unknown>) | undefined;
|
|
173
|
+
};
|
|
174
|
+
export type AgentAck = {
|
|
175
|
+
type: string;
|
|
176
|
+
ack: any;
|
|
177
|
+
signature: string;
|
|
178
|
+
cert: unknown;
|
|
179
|
+
sid: string;
|
|
180
|
+
from?: string;
|
|
181
|
+
};
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/** @typedef {import('./shapes.js').AgentIdentity} AgentIdentity */
|
|
2
|
+
/** @typedef {import('./shapes.js').DotrinoActa} DotrinoActa */
|
|
3
|
+
/**
|
|
4
|
+
* @param {AgentIdentity} id instancia de Identity (del vault) ya conectada.
|
|
5
|
+
* @param {string} [label] filtrar por servicio/label exacto (p. ej. `'content'`,
|
|
6
|
+
* `'ia-agent'`). Omitir = todos los que tengan nameOf y no sean `'cli'` (un navegador
|
|
7
|
+
* enrolado queda como `cli` y no atiende a nadie).
|
|
8
|
+
* @param {{ fresh?: boolean }} [opts] `fresh: false`: el acta guardada, sin preguntar a la
|
|
9
|
+
* bóveda (si no hay ninguna guardada, se pregunta igual).
|
|
10
|
+
* @returns {Promise<Array<{sub:string,label:string,cn:string|null}>>} uno por miembro.
|
|
11
|
+
* @throws `code: 'no-record'` si ni la bóveda ni lo guardado dan el acta: no se sabe, y no es «ninguno».
|
|
12
|
+
*/
|
|
13
|
+
export function listAgentsByLabel(id: AgentIdentity, label?: string, { fresh }?: {
|
|
14
|
+
fresh?: boolean;
|
|
15
|
+
}): Promise<Array<{
|
|
16
|
+
sub: string;
|
|
17
|
+
label: string;
|
|
18
|
+
cn: string | null;
|
|
19
|
+
}>>;
|
|
20
|
+
/**
|
|
21
|
+
* QUÉ AGENTE ES CADA UNO, preguntándoselo. Manda un `ra.ping` a cada pubkey por el
|
|
22
|
+
* transporte que se le pase y devuelve los que contestan, con el `kind` que declara el
|
|
23
|
+
* agente al arrancar (`startRemoteAgent({ label })`).
|
|
24
|
+
*
|
|
25
|
+
* Existe porque buscar por el label del ACTA no sirve: ese nombre lo pone el dueño al
|
|
26
|
+
* emparejar («TerminalLocal», «el PC de la oficina»), así que una app que buscaba
|
|
27
|
+
* `terminal-agent` no encontraba nada. Lo que un agente atiende lo sabe el agente.
|
|
28
|
+
*
|
|
29
|
+
* Un agente apagado no contesta y no sale: no se puede saber qué es sin preguntarle.
|
|
30
|
+
*
|
|
31
|
+
* @param {{ on: (ev: 'message', fn: (from: string, p: any) => void) => () => void, sendByPubkey: (to: string, payload: object, opts?: { ephemeral?: boolean }) => unknown } | null} client
|
|
32
|
+
* un WebSocketProxyClient conectado. `p` es lo que llega: se mira su `type` antes de usarlo.
|
|
33
|
+
* @param {string[]} subs pubkeys a preguntar (p. ej. las de `listAgentsByLabel(id)`).
|
|
34
|
+
* @param {{ timeoutMs?: number }} [opts]
|
|
35
|
+
* @returns {Promise<Map<string, { kind: string|null }>>} sub → lo que contestó.
|
|
36
|
+
*/
|
|
37
|
+
export function probeAgents(client: {
|
|
38
|
+
on: (ev: "message", fn: (from: string, p: any) => void) => () => void;
|
|
39
|
+
sendByPubkey: (to: string, payload: object, opts?: {
|
|
40
|
+
ephemeral?: boolean;
|
|
41
|
+
}) => unknown;
|
|
42
|
+
} | null, subs: string[], { timeoutMs }?: {
|
|
43
|
+
timeoutMs?: number;
|
|
44
|
+
}): Promise<Map<string, {
|
|
45
|
+
kind: string | null;
|
|
46
|
+
}>>;
|
|
47
|
+
declare namespace _default {
|
|
48
|
+
export { listAgentsByLabel };
|
|
49
|
+
export { probeAgents };
|
|
50
|
+
}
|
|
51
|
+
export default _default;
|
|
52
|
+
export type AgentIdentity = import("./shapes.js").AgentIdentity;
|
|
53
|
+
export type DotrinoActa = import("./shapes.js").DotrinoActa;
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Raíz de los agentes de un tipo: `~/.dotrino/agent/<kind>` (override de la raíz común con
|
|
3
|
+
* `DOTRINO_AGENT_HOME`, igual que `DOTRINO_ENV_HOME` en dotrino-env).
|
|
4
|
+
* @param {string} kind el tipo de agente, el mismo `label` de `startRemoteAgent` (`ia-agent`).
|
|
5
|
+
*/
|
|
6
|
+
export function instancesRoot(kind: string): string;
|
|
7
|
+
/**
|
|
8
|
+
* Nombres de las instancias enlazadas (las que tienen `link.json`).
|
|
9
|
+
* @param {string} kind
|
|
10
|
+
* @returns {string[]}
|
|
11
|
+
*/
|
|
12
|
+
export function listInstances(kind: string): string[];
|
|
13
|
+
/**
|
|
14
|
+
* La carpeta de la instancia a usar.
|
|
15
|
+
* · con `name`: esa (valida el nombre);
|
|
16
|
+
* · sin nombre y ninguna enlazada: `default`;
|
|
17
|
+
* · sin nombre y UNA enlazada: esa;
|
|
18
|
+
* · sin nombre y VARIAS: se para y se dice cuáles hay. Elegir por el usuario sería adivinar.
|
|
19
|
+
* @param {string} kind
|
|
20
|
+
* @param {string | null} [name]
|
|
21
|
+
* @returns {{ name: string, dir: string }}
|
|
22
|
+
*/
|
|
23
|
+
export function resolveInstance(kind: string, name?: string | null): {
|
|
24
|
+
name: string;
|
|
25
|
+
dir: string;
|
|
26
|
+
};
|
|
27
|
+
/**
|
|
28
|
+
* Candado de la instancia: dos procesos con el MISMO enlace son la misma llave y se
|
|
29
|
+
* estorban. Si ya corre uno vivo, se para y se dice. Devuelve `release()`.
|
|
30
|
+
*/
|
|
31
|
+
/** @param {string} dir @returns {() => void} suelta el candado */
|
|
32
|
+
export function lockInstance(dir: string): () => void;
|
|
33
|
+
export const DEFAULT_NAME: "default";
|
|
34
|
+
export function isValidName(n: unknown): n is string;
|
|
@@ -0,0 +1,281 @@
|
|
|
1
|
+
/** @typedef {import('./shapes.js').AgentIdentity} AgentIdentity */
|
|
2
|
+
/** @typedef {import('./shapes.js').DotrinoActa} DotrinoActa */
|
|
3
|
+
/**
|
|
4
|
+
* El papel de un aparato: lo firma la bóveda. `seq` es el del acta con que se emitió; `exp`
|
|
5
|
+
* solo lo lleva el modelo viejo (por fecha).
|
|
6
|
+
* @typedef {{ seq?: number, exp?: number } & Record<string, unknown>} AgentCert
|
|
7
|
+
*/
|
|
8
|
+
/**
|
|
9
|
+
* El enlace de esta máquina con su cuenta (`link.json`). Con bóveda: `device`, `enc`, `cert`,
|
|
10
|
+
* `iss`, `proxy`. Propio (`self: true`): `device`, `enc` y su génesis en `sealerChain`.
|
|
11
|
+
* @typedef {object} AgentLink
|
|
12
|
+
* @property {{ publickey: string, privateJwk: JsonWebKey }} device
|
|
13
|
+
* @property {{ publickey?: string, privateJwk?: JsonWebKey } & Record<string, unknown>} [enc]
|
|
14
|
+
* @property {AgentCert} [cert]
|
|
15
|
+
* @property {string} [iss] la bóveda con que se enroló
|
|
16
|
+
* @property {string} [proxy]
|
|
17
|
+
* @property {string} [label]
|
|
18
|
+
* @property {string} [ns]
|
|
19
|
+
* @property {number} [at]
|
|
20
|
+
* @property {boolean} [self]
|
|
21
|
+
* @property {DotrinoActa[]} [sealerChain]
|
|
22
|
+
* @property {DotrinoActa} [acta] el acta de confianza (solo si `actaTrusted`)
|
|
23
|
+
* @property {boolean} [actaTrusted]
|
|
24
|
+
* @property {number} [actaSeq] la `seq` del acta más nueva que se ha visto
|
|
25
|
+
* @property {string[]} [blocked] aparatos bloqueados por la bóveda (pubkeys)
|
|
26
|
+
*/
|
|
27
|
+
/** @param {string} [name] @returns {string} */
|
|
28
|
+
export function dataDir(name?: string): string;
|
|
29
|
+
/**
|
|
30
|
+
* Lee el enlace persistido, o `null` si NO EXISTE. Un enlace en claro (anterior a 0.30.0) se
|
|
31
|
+
* lee y se reescribe cifrado en el acto, comprobando antes que se vuelve a leer igual.
|
|
32
|
+
*
|
|
33
|
+
* Si existe y no se puede leer —otro equipo, la máquina cambió, el archivo está roto— LANZA
|
|
34
|
+
* (`link-unreadable`). Devolver `null` diría «no hay enlace», y quien lo llama crearía otro
|
|
35
|
+
* encima del que ya era el aparato: la identidad se perdería en silencio.
|
|
36
|
+
*/
|
|
37
|
+
export function loadLink(dir?: string): AgentLink | null;
|
|
38
|
+
/** Persiste el enlace, cifrado (0600). Exportada porque la RENOVACIÓN del cert lo reescribe. */
|
|
39
|
+
/** @param {string} dir @param {AgentLink} link */
|
|
40
|
+
export function saveLink(dir: string, link: AgentLink): void;
|
|
41
|
+
/**
|
|
42
|
+
* Parsea una invitación de la bóveda a objeto. Acepta TODAS las formas que imprime
|
|
43
|
+
* `dotrino-vault pair` (URL del QR, código compacto, JSON, base64url): es el mismo
|
|
44
|
+
* `parseInvite` del ecosistema. `enroll` ya lo hace solo; esto es para quien quiera
|
|
45
|
+
* mirar la invitación antes (qué bóveda, qué proxy) sin enrolar.
|
|
46
|
+
* @param {string} text
|
|
47
|
+
*/
|
|
48
|
+
export function parseQr(text: string): Promise<{
|
|
49
|
+
sn?: string;
|
|
50
|
+
iss?: string;
|
|
51
|
+
conn?: unknown;
|
|
52
|
+
} & Record<string, unknown>>;
|
|
53
|
+
/** base64url → utf8 (lo usan los tests y algún QR viejo). */
|
|
54
|
+
/** @param {string} s @returns {string} */
|
|
55
|
+
export function b64urlDecode(s: string): string;
|
|
56
|
+
/**
|
|
57
|
+
* Enrola ESTA máquina contra la bóveda y persiste el enlace
|
|
58
|
+
* `{ device, enc, cert, iss, proxy, label, ns?, at }`.
|
|
59
|
+
*
|
|
60
|
+
* El enrolamiento en sí es el del ecosistema —`enrollWithVault` de `@dotrino/vault`—
|
|
61
|
+
* y no se duplica aquí: entiende cualquier invitación, crea las DOS llaves del aparato
|
|
62
|
+
* (firma y **cifrado**: sin la segunda la bóveda no puede sellarle secretos) y
|
|
63
|
+
* verifica el cert. Este módulo solo decide dónde vive.
|
|
64
|
+
*
|
|
65
|
+
* Lo que puede hacer el aparato lo decide la invitación (`dotrino-vault pair --scope …`):
|
|
66
|
+
* no hay tipos de agente, hay permisos. Un bot que publica y lee su cajón se empareja
|
|
67
|
+
* con `pair --service <ns> --scope sign`; pásale `ns` para que el enlace lo recuerde y
|
|
68
|
+
* exija ese permiso en el cert.
|
|
69
|
+
*
|
|
70
|
+
* @param {object} args
|
|
71
|
+
* @param {object|string} args.qr La invitación, en cualquiera de sus formas.
|
|
72
|
+
* @param {string} [args.label='remote-agent'] label del dispositivo (lo filtra el cliente).
|
|
73
|
+
* @param {string} [args.dir=dataDir()] dónde persistir el enlace.
|
|
74
|
+
* @param {string | null} [args.ns] cajón de secretos que lee este agente (si lo hay).
|
|
75
|
+
* @param {(c:{deviceId:string,code:string})=>void} [args.onChallenge] mostrar el CÓDIGO para
|
|
76
|
+
* que un humano lo TIPEE en la bóveda al aprobar (el código NO viaja de aquí).
|
|
77
|
+
* @param {number} [args.timeoutMs=180000]
|
|
78
|
+
* @returns {Promise<AgentLink>}
|
|
79
|
+
*/
|
|
80
|
+
export function enroll({ qr, label, dir, ns, onChallenge, timeoutMs }?: {
|
|
81
|
+
qr: object | string;
|
|
82
|
+
label?: string | undefined;
|
|
83
|
+
dir?: string | undefined;
|
|
84
|
+
ns?: string | null | undefined;
|
|
85
|
+
onChallenge?: ((c: {
|
|
86
|
+
deviceId: string;
|
|
87
|
+
code: string;
|
|
88
|
+
}) => void) | undefined;
|
|
89
|
+
timeoutMs?: number | undefined;
|
|
90
|
+
}): Promise<AgentLink>;
|
|
91
|
+
/**
|
|
92
|
+
* UNA IDENTIDAD PROPIA, SIN BÓVEDA. El aparato cumple el rol cuando no hay pieza dedicada:
|
|
93
|
+
* crea sus llaves (firma y cifrado) y un acta de génesis autofirmada donde él es el único
|
|
94
|
+
* miembro. Es una cuenta de un solo aparato, igual que «este dispositivo es bóveda» en el
|
|
95
|
+
* navegador: `verifySignedFor` la acepta sin saber nada más, porque la raíz de toda cuenta
|
|
96
|
+
* es un acta autofirmada.
|
|
97
|
+
*
|
|
98
|
+
* El enlace queda `{ device, enc, label, self: true, sealerChain: [génesis], at }`, sin
|
|
99
|
+
* `cert` ni `iss`.
|
|
100
|
+
*
|
|
101
|
+
* EMPAREJARLO DESPUÉS CAMBIA LA LLAVE, a propósito (dueño, 2026-11-04): `enroll` crea otra y
|
|
102
|
+
* sobrescribe este enlace. Una llave está en UNA sola cuenta. Si entrara a una bóveda con la
|
|
103
|
+
* misma, seguiría siendo la raíz de su génesis y podría entrar igual a otras bóvedas.
|
|
104
|
+
*
|
|
105
|
+
* @param {{ label?: string, dir?: string }} [args]
|
|
106
|
+
* @returns {Promise<AgentLink>}
|
|
107
|
+
*/
|
|
108
|
+
export function selfLink({ label, dir }?: {
|
|
109
|
+
label?: string;
|
|
110
|
+
dir?: string;
|
|
111
|
+
}): Promise<AgentLink>;
|
|
112
|
+
/**
|
|
113
|
+
* La IDENTIDAD de un agente a partir de su enlace: lo que un cliente del ecosistema
|
|
114
|
+
* espera como `link.id` (`RemoteAgentClient`, `ContentClient`, `listAgentsByLabel`) —
|
|
115
|
+
* `me.publickey`, `signData`, `listVaultDevices`, `getVaultCert`, `vaultStatus`— pero
|
|
116
|
+
* firmando con la llave del aparato en vez de con el pilar del navegador. Así un agente
|
|
117
|
+
* Node puede ser CLIENTE de otro agente (un bot que guarda en el node de contenido)
|
|
118
|
+
* con el mismo código que usa una app.
|
|
119
|
+
*
|
|
120
|
+
* @param {AgentLink} link el enlace (`loadLink(dir)`).
|
|
121
|
+
* @param {{ dir?: string }} [opts] dir para los globals de Node (localStorage del proxy-client).
|
|
122
|
+
* @returns {AgentIdentity}
|
|
123
|
+
*/
|
|
124
|
+
export function identityFromLink(link: AgentLink, { dir }?: {
|
|
125
|
+
dir?: string;
|
|
126
|
+
}): AgentIdentity;
|
|
127
|
+
/**
|
|
128
|
+
* El acta que `listVaultDevices` puede dar por buena. Exportada para las pruebas.
|
|
129
|
+
* @param {AgentLink} link
|
|
130
|
+
* @param {DotrinoActa | null | undefined} candidate la que llegó por la red
|
|
131
|
+
* @param {string} me
|
|
132
|
+
* @returns {Promise<DotrinoActa | null>}
|
|
133
|
+
*/
|
|
134
|
+
export function checkedActa(link: AgentLink, candidate: DotrinoActa | null | undefined, me: string): Promise<DotrinoActa | null>;
|
|
135
|
+
/**
|
|
136
|
+
* POR QUÉ TOCA PEDIR PAPEL NUEVO, o `null` si no toca. Es la única regla de renovación:
|
|
137
|
+
* la usan `renewLink` (agentes que corren una vez) y el tic de `startRemoteAgent`.
|
|
138
|
+
* · `'legacy'`: el papel es del MODELO VIEJO (lleva `exp` y no `seq`). Se cambia sí o sí:
|
|
139
|
+
* se acepta por el repliegue de migración, pero muere en su fecha y con él la máquina.
|
|
140
|
+
* · `'behind'`: el acta que hemos visto va por delante del papel (el dueño cambió permisos).
|
|
141
|
+
* Nunca por calendario: el papel no vence.
|
|
142
|
+
*
|
|
143
|
+
* @param {AgentLink} link
|
|
144
|
+
* @returns {'legacy'|'behind'|null}
|
|
145
|
+
*/
|
|
146
|
+
export function renewalReason(link: AgentLink): "legacy" | "behind" | null;
|
|
147
|
+
/**
|
|
148
|
+
* GUARDA un papel renovado (ya comprobado por quien lo pidió) y lo persiste. SE GUARDA ANTES
|
|
149
|
+
* DE DAR NADA POR BUENO: emitir un papel RETIRA el anterior, así que si esto no se persiste la
|
|
150
|
+
* máquina se queda usando uno revocado y fuera para siempre.
|
|
151
|
+
*
|
|
152
|
+
* El acta que viaja con el papel se adopta SOLO si se puede comprobar (`record.js`): es la que
|
|
153
|
+
* decide quién abre sesión con este agente. El papel sí se guarda siempre.
|
|
154
|
+
*/
|
|
155
|
+
/** @param {{ dir: string, link: AgentLink, cert: AgentCert, acta: DotrinoActa }} o */
|
|
156
|
+
export function storeRenewedCert({ dir, link, cert, acta }: {
|
|
157
|
+
dir: string;
|
|
158
|
+
link: AgentLink;
|
|
159
|
+
cert: AgentCert;
|
|
160
|
+
acta: DotrinoActa;
|
|
161
|
+
}): Promise<void>;
|
|
162
|
+
/**
|
|
163
|
+
* RENUEVA el cert del enlace si vence pronto y lo persiste. Es lo que hace el agente
|
|
164
|
+
* de larga duración en cada tic (`startRemoteAgent`), sacado aquí para los agentes que
|
|
165
|
+
* corren UNA vez (un bot por cron): sin esto su cert muere a los 30 días y hay que
|
|
166
|
+
* re-emparejar una máquina que nunca dejó de ser tuya.
|
|
167
|
+
*
|
|
168
|
+
* El cert nuevo se VERIFICA antes de guardarlo (misma maestra, misma llave, más vida).
|
|
169
|
+
* Un cert ya vencido no se renueva: ahí toca re-emparejar. No lanza: devuelve qué pasó.
|
|
170
|
+
*
|
|
171
|
+
* @param {AgentLink} link el enlace (se muta con el cert nuevo).
|
|
172
|
+
* @param {{ dir?: string, force?: boolean }} [opts]
|
|
173
|
+
* @returns {Promise<{ renewed: boolean, seq?: number | null, reason?: string }>} `seq`: la del papel que queda
|
|
174
|
+
*/
|
|
175
|
+
export function renewLink(link: AgentLink, { dir, force }?: {
|
|
176
|
+
dir?: string;
|
|
177
|
+
force?: boolean;
|
|
178
|
+
}): Promise<{
|
|
179
|
+
renewed: boolean;
|
|
180
|
+
seq?: number | null;
|
|
181
|
+
reason?: string;
|
|
182
|
+
}>;
|
|
183
|
+
/**
|
|
184
|
+
* TRAE LA CADENA DE SELLADORES de la cuenta y la guarda en el enlace: con ella `signData`
|
|
185
|
+
* firma a nombre de la cuenta de forma que `verifySignedFor` lo compruebe desde el génesis.
|
|
186
|
+
* Se comprueba ANTES de guardarla (`verifySealerChain`): una cadena que no encadena o que es
|
|
187
|
+
* de otra cuenta no entra. Un agente que firma de cara a terceros la pide al arrancar y la
|
|
188
|
+
* refresca de vez en cuando. No lanza: devuelve qué pasó.
|
|
189
|
+
*
|
|
190
|
+
* @param {AgentLink} link
|
|
191
|
+
* @param {{ dir?: string }} [opts]
|
|
192
|
+
* @returns {Promise<{ ok: boolean, seq?: number, reason?: string, self?: boolean }>}
|
|
193
|
+
*/
|
|
194
|
+
export function refreshChain(link: AgentLink, { dir }?: {
|
|
195
|
+
dir?: string;
|
|
196
|
+
}): Promise<{
|
|
197
|
+
ok: boolean;
|
|
198
|
+
seq?: number;
|
|
199
|
+
reason?: string;
|
|
200
|
+
self?: boolean;
|
|
201
|
+
}>;
|
|
202
|
+
/**
|
|
203
|
+
* El enlace como lo esperan `ContentClient.connect({ link })` y `RemoteAgentClient`.
|
|
204
|
+
* @param {AgentLink} link
|
|
205
|
+
* @param {{ dir?: string }} [opts]
|
|
206
|
+
*/
|
|
207
|
+
export function clientLink(link: AgentLink, opts?: {
|
|
208
|
+
dir?: string;
|
|
209
|
+
}): {
|
|
210
|
+
id: import("./shapes.js").AgentIdentity;
|
|
211
|
+
cert: AgentCert | undefined;
|
|
212
|
+
iss: string | undefined;
|
|
213
|
+
proxy: string;
|
|
214
|
+
};
|
|
215
|
+
export function isSelfLink(link: AgentLink | null | undefined): boolean;
|
|
216
|
+
export { RENEW_BEFORE_MS };
|
|
217
|
+
declare namespace _default {
|
|
218
|
+
export { dataDir };
|
|
219
|
+
export { loadLink };
|
|
220
|
+
export { saveLink };
|
|
221
|
+
export { parseQr };
|
|
222
|
+
export { enroll };
|
|
223
|
+
export { selfLink };
|
|
224
|
+
export { isSelfLink };
|
|
225
|
+
export { identityFromLink };
|
|
226
|
+
export { clientLink };
|
|
227
|
+
export { renewLink };
|
|
228
|
+
export { renewalReason };
|
|
229
|
+
export { storeRenewedCert };
|
|
230
|
+
export { refreshChain };
|
|
231
|
+
}
|
|
232
|
+
export default _default;
|
|
233
|
+
export type AgentIdentity = import("./shapes.js").AgentIdentity;
|
|
234
|
+
export type DotrinoActa = import("./shapes.js").DotrinoActa;
|
|
235
|
+
/**
|
|
236
|
+
* El papel de un aparato: lo firma la bóveda. `seq` es el del acta con que se emitió; `exp`
|
|
237
|
+
* solo lo lleva el modelo viejo (por fecha).
|
|
238
|
+
*/
|
|
239
|
+
export type AgentCert = {
|
|
240
|
+
seq?: number;
|
|
241
|
+
exp?: number;
|
|
242
|
+
} & Record<string, unknown>;
|
|
243
|
+
/**
|
|
244
|
+
* El enlace de esta máquina con su cuenta (`link.json`). Con bóveda: `device`, `enc`, `cert`,
|
|
245
|
+
* `iss`, `proxy`. Propio (`self: true`): `device`, `enc` y su génesis en `sealerChain`.
|
|
246
|
+
*/
|
|
247
|
+
export type AgentLink = {
|
|
248
|
+
device: {
|
|
249
|
+
publickey: string;
|
|
250
|
+
privateJwk: JsonWebKey;
|
|
251
|
+
};
|
|
252
|
+
enc?: ({
|
|
253
|
+
publickey?: string;
|
|
254
|
+
privateJwk?: JsonWebKey;
|
|
255
|
+
} & Record<string, unknown>) | undefined;
|
|
256
|
+
cert?: AgentCert | undefined;
|
|
257
|
+
/**
|
|
258
|
+
* la bóveda con que se enroló
|
|
259
|
+
*/
|
|
260
|
+
iss?: string | undefined;
|
|
261
|
+
proxy?: string | undefined;
|
|
262
|
+
label?: string | undefined;
|
|
263
|
+
ns?: string | undefined;
|
|
264
|
+
at?: number | undefined;
|
|
265
|
+
self?: boolean | undefined;
|
|
266
|
+
sealerChain?: import("./shapes.js").DotrinoActa[] | undefined;
|
|
267
|
+
/**
|
|
268
|
+
* el acta de confianza (solo si `actaTrusted`)
|
|
269
|
+
*/
|
|
270
|
+
acta?: import("./shapes.js").DotrinoActa | undefined;
|
|
271
|
+
actaTrusted?: boolean | undefined;
|
|
272
|
+
/**
|
|
273
|
+
* la `seq` del acta más nueva que se ha visto
|
|
274
|
+
*/
|
|
275
|
+
actaSeq?: number | undefined;
|
|
276
|
+
/**
|
|
277
|
+
* aparatos bloqueados por la bóveda (pubkeys)
|
|
278
|
+
*/
|
|
279
|
+
blocked?: string[] | undefined;
|
|
280
|
+
};
|
|
281
|
+
import { RENEW_BEFORE_MS } from '../protocol.js';
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/** @typedef {import('./shapes.js').DotrinoActa} DotrinoActa */
|
|
2
|
+
/**
|
|
3
|
+
* @param {DotrinoActa | null | undefined} acta
|
|
4
|
+
* @param {unknown} pub
|
|
5
|
+
* @returns {boolean}
|
|
6
|
+
*/
|
|
7
|
+
export function canGreet(acta: DotrinoActa | null | undefined, pub: unknown): boolean;
|
|
8
|
+
declare namespace _default {
|
|
9
|
+
export { canGreet };
|
|
10
|
+
}
|
|
11
|
+
export default _default;
|
|
12
|
+
export type DotrinoActa = import("./shapes.js").DotrinoActa;
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/** @typedef {import('./shapes.js').DotrinoActa} DotrinoActa */
|
|
2
|
+
/**
|
|
3
|
+
* @param {{ link: import('./link.js').AgentLink, candidate: DotrinoActa | null | undefined, me: string }} args `me` = la llave pública de esta máquina.
|
|
4
|
+
* @returns {Promise<{ adopt: boolean, reason: string }>}
|
|
5
|
+
*/
|
|
6
|
+
export function adoptRecord({ link, candidate, me }: {
|
|
7
|
+
link: import("./link.js").AgentLink;
|
|
8
|
+
candidate: DotrinoActa | null | undefined;
|
|
9
|
+
me: string;
|
|
10
|
+
}): Promise<{
|
|
11
|
+
adopt: boolean;
|
|
12
|
+
reason: string;
|
|
13
|
+
}>;
|
|
14
|
+
declare namespace _default {
|
|
15
|
+
export { adoptRecord };
|
|
16
|
+
}
|
|
17
|
+
export default _default;
|
|
18
|
+
export type DotrinoActa = import("./shapes.js").DotrinoActa;
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Las formas de datos que aparecen en los tipos publicados de @dotrino/remote-agent. Solo
|
|
3
|
+
* tipos: no hay código aquí. `npm run types` lo copia a `types/src/` junto a los generados.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Lo que un cliente del ecosistema usa de una identidad: el `Identity` del navegador o la que
|
|
8
|
+
* arma `identityFromLink` con la llave de un aparato.
|
|
9
|
+
*/
|
|
10
|
+
export interface AgentIdentity {
|
|
11
|
+
me: { publickey: string, nickname?: string } | null
|
|
12
|
+
signData (data: object): Promise<{ signature: string, publickey?: string, profileId?: string | null, chain?: unknown[] | null } & Record<string, unknown>>
|
|
13
|
+
listVaultDevices (): Promise<{ acta?: DotrinoActa | null } & Record<string, unknown>>
|
|
14
|
+
profileActa? (): Promise<{ acta: DotrinoActa } | null>
|
|
15
|
+
getVaultCert? (): Promise<{ cert: unknown }>
|
|
16
|
+
vaultStatus? (): Promise<Record<string, unknown>>
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/** Un acta (la lista de miembros de una cuenta). Llega de la red: se comprueba antes de usarla. */
|
|
20
|
+
export interface DotrinoActa {
|
|
21
|
+
seq: number
|
|
22
|
+
profileId: string
|
|
23
|
+
members?: Array<{ pub: string, caps?: string[], label?: string, cn?: string } & Record<string, unknown>>
|
|
24
|
+
[k: string]: unknown
|
|
25
|
+
}
|