@dotrino/remote-agent 0.33.0 → 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 CHANGED
@@ -1,29 +1,56 @@
1
1
  {
2
2
  "name": "@dotrino/remote-agent",
3
- "version": "0.33.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
- ".": "./index.js",
9
- "./agent": "./src/agent.js",
10
- "./client": "./src/client.js",
11
- "./link": "./src/link.js",
12
- "./browser-link": "./src/browser-link.js",
13
- "./discover": "./src/discover.js",
14
- "./node-globals": "./node-globals.js",
15
- "./instances": "./src/instances.js"
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",
package/src/agent.js CHANGED
@@ -33,6 +33,7 @@ import { HS, ACK, DATA, PING, PONG, ERROR, VMSG, SIGN_SCOPE, SESSION_TTL_MS, SES
33
33
  import { loadLink, saveLink, dataDir, renewalReason, storeRenewedCert } from './link.js'
34
34
  import { declare } from '@dotrino/compat'
35
35
  import { VAULT_PROTOCOL, VAULT_SPEAKS } from '@dotrino/vault/protocol'
36
+ /** @typedef {import('./shapes.js').DotrinoActa} DotrinoActa */
36
37
 
37
38
  const PKG_VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
38
39
 
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
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
@@ -13,6 +13,7 @@
13
13
  * Sin acta no se sabe, y no saber es que no.
14
14
  */
15
15
  import { memberCan, samePubkey } from '@dotrino/identity/acta'
16
+ /** @typedef {import('./shapes.js').DotrinoActa} DotrinoActa */
16
17
 
17
18
  /**
18
19
  * @param {DotrinoActa | null | undefined} acta
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.
@@ -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";
@@ -0,0 +1,2 @@
1
+ export * from "./e2e.js";
2
+ export * from "./protocol.js";
@@ -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
+ }