@rine-network/cli 0.10.2 → 0.11.1

package/dist/main.js

@@ -1,8 +1,9 @@
 import { createRequire } from "node:module";
 import { Command } from "commander";
-import { HttpClient, RineApiError, UUID_RE, addMlsGroupMember, agentKeysExist, cacheToken, decryptGroupMessage, decryptMessage, encryptGroupMessage, encryptMessage, encryptMlsGroupMessage, externalJoinMlsGroup, fetchAgents, fetchAndIngestPendingSKDistributions, fetchOAuthToken, fetchRecipientKeys, formatError, fromBase64Url, generateAgentKeys, generatePqKeyPair, getAgentPublicKeys, getCredentialEntry, getOrCreateSenderKey, getOrRefreshToken, ingestSenderKeyDistribution, initMlsGroup, isBareAgentName, listMyInvites, loadAgentKeys, loadCredentials, loadMlsState, loadTokenCache, normalizeHandle, performAgentCreation, performRegistration, processMlsWelcomes, resolveAgent, resolveApiUrl, resolveConfigDir, resolveHandleViaWebFinger, resolveToUuid, saveAgentKeys, saveCredentials, savePqEncryptionKey, saveTokenCache, sendGroupInviteNotification, syncMlsGroup, toBase64Url, validateEncryptionKey, validateSigningKey, validateSlug } from "@rine-network/core";
+import { HttpClient, RineApiError, UUID_RE, addMlsGroupMember, agentKeysExist, buildIssueCertDeps, cacheToken, connectTunnel, decryptGroupMessage, decryptMessage, deleteHookSecret, encryptGroupMessage, encryptMessage, encryptMlsGroupMessage, ensureCert, externalJoinMlsGroup, fetchAgents, fetchAndIngestPendingSKDistributions, fetchOAuthToken, fetchRecipientKeys, formatError, fromBase64Url, generateAgentKeys, generateHookSecret, generatePqKeyPair, getAgentPublicKeys, getCredentialEntry, getOrCreateSenderKey, getOrRefreshToken, handleWebhookRequest, ingestSenderKeyDistribution, initMlsGroup, isBareAgentName, isValidHookName, listMyInvites, loadAgentKeys, loadCredentials, loadHookSecret, loadMlsState, loadTokenCache, normalizeHandle, performAgentCreation, performRegistration, processMlsWelcomes, resolveAgent, resolveApiUrl, resolveConfigDir, resolveHandleViaWebFinger, resolveToUuid, revokeAndWipeCache, saveAgentKeys, saveCredentials, saveHookSecret, savePqEncryptionKey, saveTokenCache, sendGroupInviteNotification, startTlsListener, syncMlsGroup, toBase64Url, validateEncryptionKey, validateSigningKey, validateSlug } from "@rine-network/core";
 import readline from "node:readline";
 import * as fs from "node:fs";
+import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { createEventSource } from "eventsource-client";
 //#region src/output.ts
@@ -905,6 +906,106 @@ function registerGroup(program) {
 	}));
 }
 //#endregion
+//#region src/commands/hook.ts
+const SIGNATURE_HEADER = "X-Hub-Signature-256";
+const CONTENT_TYPE = "application/json";
+function registerHook(program) {
+	const hook = program.command("hook").description("Manage inbound webhook funnel hooks");
+	hook.command("create").description("Allocate a funnel hook and print its GitHub setup (secret shown once)").option("--agent <id>", "Agent ID (defaults to your agent)").option("--name <name>", "Hook name (default: default)", "default").action(withClient(program, async ({ client, gOpts, apiUrl, configDir }, opts) => {
+		if (!isValidHookName(opts.name)) {
+			printError(`Invalid hook name '${opts.name}': use lowercase letters, digits and hyphens (max 32).`);
+			process.exitCode = 2;
+			return;
+		}
+		const agentId = await resolveAgent(apiUrl, await fetchAgents(client), opts.agent, gOpts.as);
+		const secret = generateHookSecret();
+		saveHookSecret(configDir, agentId, opts.name, secret);
+		let created;
+		try {
+			created = await client.post(`/agents/${agentId}/funnel/hooks`, { hook_name: opts.name });
+		} catch (err) {
+			deleteHookSecret(configDir, agentId, opts.name);
+			throw err;
+		}
+		printCreated(created, opts.name, secret, gOpts.json);
+	}));
+	hook.command("list").description("List your agent's funnel hooks").option("--agent <id>", "Agent ID (defaults to your agent)").action(withClient(program, async ({ client, gOpts, apiUrl }, opts) => {
+		const agentId = await resolveAgent(apiUrl, await fetchAgents(client), opts.agent, gOpts.as);
+		const data = await client.get(`/agents/${agentId}/funnel/hooks`, {});
+		if (gOpts.json) printJson(data);
+		else printTable(data.items.map((h) => ({
+			Name: h.hook_name,
+			Hostname: h.hostname,
+			Active: h.active,
+			Created: h.created_at
+		})));
+	}));
+	hook.command("delete").description("Delete a funnel hook and purge its local secret").option("--agent <id>", "Agent ID (defaults to your agent)").requiredOption("--name <name>", "Hook name to delete").option("--yes", "Skip confirmation prompt").action(withClient(program, async ({ client, gOpts, apiUrl, configDir }, opts) => {
+		const agentId = await resolveAgent(apiUrl, await fetchAgents(client), opts.agent, gOpts.as);
+		if (!opts.yes && !gOpts.json) {
+			if (!await promptConfirm(`Delete funnel hook '${opts.name}'?`)) return;
+		}
+		try {
+			await client.delete(`/agents/${agentId}/funnel/hooks/${opts.name}`);
+		} catch (err) {
+			if (opts.yes && err instanceof RineApiError && err.status === 404) {
+				deleteHookSecret(configDir, agentId, opts.name);
+				printMutationOk("Funnel hook already absent", gOpts.json);
+				return;
+			}
+			throw err;
+		}
+		deleteHookSecret(configDir, agentId, opts.name);
+		printMutationOk("Funnel hook deleted", gOpts.json);
+	}));
+}
+/** Print the print-once GitHub setup block (the secret is shown exactly once). */
+function printCreated(created, name, secret, json) {
+	const publicUrl = `https://${created.hostname}/${name}`;
+	if (json) {
+		printJson({
+			hook: {
+				name: created.hook_name,
+				hostname: created.hostname,
+				agent_id: created.agent_id
+			},
+			public_url: publicUrl,
+			secret,
+			signature_header: SIGNATURE_HEADER,
+			content_type: CONTENT_TYPE
+		});
+		return;
+	}
+	printTable([
+		{
+			Field: "Hook",
+			Value: created.hook_name
+		},
+		{
+			Field: "Hostname",
+			Value: created.hostname
+		},
+		{
+			Field: "Payload URL",
+			Value: publicUrl
+		},
+		{
+			Field: "Content type",
+			Value: CONTENT_TYPE
+		},
+		{
+			Field: "Signature header",
+			Value: SIGNATURE_HEADER
+		},
+		{
+			Field: "Secret",
+			Value: secret
+		}
+	]);
+	console.log(`\nGitHub: Settings → Webhooks → Payload URL = ${publicUrl}, Content type = ${CONTENT_TYPE}, Secret = the secret above.`);
+	console.log("Save this secret now — it is not stored on rine and cannot be retrieved.");
+}
+//#endregion
 //#region src/commands/keys.ts
 function getKeysDir(configDir, agentId) {
 	return join(configDir, "keys", agentId);
@@ -1352,68 +1453,6 @@ function registerMessages(program) {
 	addMessageCommands(program.command("message").description("Message operations (aliases: send/read/inbox/reply)"), program);
 }
 //#endregion
-//#region src/commands/poll-token.ts
-function registerPollToken(program) {
-	program.command("poll-token").description("Generate or revoke a poll token for inbox monitoring").option("--agent <id>", "Agent ID (auto-resolved for single-agent orgs)").option("--revoke", "Revoke the poll token").action(withClient(program, async ({ client, gOpts, profileName, configDir, apiUrl }, opts) => {
-		const agentId = await resolveAgent(apiUrl, await fetchAgents(client), opts.agent, gOpts.as);
-		if (opts.revoke) {
-			await client.delete(`/agents/${agentId}/poll-token`);
-			const creds = loadCredentials(configDir);
-			if (creds[profileName]) {
-				delete creds[profileName].poll_url;
-				saveCredentials(configDir, creds);
-			}
-			printMutationOk("Poll token revoked", gOpts.json);
-			return;
-		}
-		const data = await client.post(`/agents/${agentId}/poll-token`, {});
-		const creds = loadCredentials(configDir);
-		if (creds[profileName]) {
-			creds[profileName].poll_url = data.poll_url;
-			saveCredentials(configDir, creds);
-		}
-		if (gOpts.json) printJson(data);
-		else {
-			console.log(`Poll URL: ${data.poll_url}`);
-			console.log("Credentials updated.");
-		}
-	}));
-}
-//#endregion
-//#region src/commands/org.ts
-function renderOrg(data, opts) {
-	if (opts.json) {
-		printJson(data);
-		return;
-	}
-	printTable([{
-		ID: data.id,
-		Name: data.name,
-		"Contact Email": data.contact_email ?? "",
-		Country: data.country_code ?? "",
-		Created: data.created_at
-	}]);
-}
-function registerOrg(program) {
-	const org = program.command("org").description("Organization management");
-	org.command("get").description("Get organization details").action(withClient(program, async ({ client, gOpts }) => {
-		renderOrg(await client.get("/org"), gOpts);
-	}));
-	org.command("update").description("Update organization details").option("--name <name>", "Organization name").option("--contact-email <email>", "Contact email address").option("--country-code <cc>", "ISO country code (e.g. DE)").action(withClient(program, async ({ client, gOpts }, opts) => {
-		const body = {};
-		if (opts.name) body.name = opts.name;
-		if (opts.contactEmail) body.contact_email = opts.contactEmail;
-		if (opts.countryCode) body.country_code = opts.countryCode;
-		if (Object.keys(body).length === 0) {
-			printError("At least one of --name, --contact-email, --country-code is required");
-			process.exitCode = 2;
-			return;
-		}
-		await client.patch("/org", body);
-		printMutationOk("Org updated", gOpts.json);
-	}));
-}
-//#endregion
 //#region src/commands/onboard.ts
 function registerOnboard(program) {
 	program.command("onboard").description("Register a new organization and create your first agent").requiredOption("--email <email>", "Email address").requiredOption("--name <name>", "Organization name").requiredOption("--slug <slug>", "Organization slug").requiredOption("--agent <agent-name>", "Name for the first agent").option("--[no-]human-oversight", "Require human oversight (default: true)").option("--unlisted", "Mark agent as unlisted (not in public directory)").action(withErrorHandler(program, async (gOpts, opts) => {
@@ -1479,6 +1518,68 @@ function registerOnboard(program) {
 	}));
 }
 //#endregion
+//#region src/commands/org.ts
+function renderOrg(data, opts) {
+	if (opts.json) {
+		printJson(data);
+		return;
+	}
+	printTable([{
+		ID: data.id,
+		Name: data.name,
+		"Contact Email": data.contact_email ?? "",
+		Country: data.country_code ?? "",
+		Created: data.created_at
+	}]);
+}
+function registerOrg(program) {
+	const org = program.command("org").description("Organization management");
+	org.command("get").description("Get organization details").action(withClient(program, async ({ client, gOpts }) => {
+		renderOrg(await client.get("/org"), gOpts);
+	}));
+	org.command("update").description("Update organization details").option("--name <name>", "Organization name").option("--contact-email <email>", "Contact email address").option("--country-code <cc>", "ISO country code (e.g. DE)").action(withClient(program, async ({ client, gOpts }, opts) => {
+		const body = {};
+		if (opts.name) body.name = opts.name;
+		if (opts.contactEmail) body.contact_email = opts.contactEmail;
+		if (opts.countryCode) body.country_code = opts.countryCode;
+		if (Object.keys(body).length === 0) {
+			printError("At least one of --name, --contact-email, --country-code is required");
+			process.exitCode = 2;
+			return;
+		}
+		await client.patch("/org", body);
+		printMutationOk("Org updated", gOpts.json);
+	}));
+}
+//#endregion
+//#region src/commands/poll-token.ts
+function registerPollToken(program) {
+	program.command("poll-token").description("Generate or revoke a poll token for inbox monitoring").option("--agent <id>", "Agent ID (auto-resolved for single-agent orgs)").option("--revoke", "Revoke the poll token").action(withClient(program, async ({ client, gOpts, profileName, configDir, apiUrl }, opts) => {
+		const agentId = await resolveAgent(apiUrl, await fetchAgents(client), opts.agent, gOpts.as);
+		if (opts.revoke) {
+			await client.delete(`/agents/${agentId}/poll-token`);
+			const creds = loadCredentials(configDir);
+			if (creds[profileName]) {
+				delete creds[profileName].poll_url;
+				saveCredentials(configDir, creds);
+			}
+			printMutationOk("Poll token revoked", gOpts.json);
+			return;
+		}
+		const data = await client.post(`/agents/${agentId}/poll-token`, {});
+		const creds = loadCredentials(configDir);
+		if (creds[profileName]) {
+			creds[profileName].poll_url = data.poll_url;
+			saveCredentials(configDir, creds);
+		}
+		if (gOpts.json) printJson(data);
+		else {
+			console.log(`Poll URL: ${data.poll_url}`);
+			console.log("Credentials updated.");
+		}
+	}));
+}
+//#endregion
 //#region src/commands/register.ts
 function registerRegister(program) {
 	program.command("register").description("Register a new organization (two-step PoW flow)").requiredOption("--email <email>", "Email address").requiredOption("--name <name>", "Organization name").requiredOption("--slug <slug>", "Organization slug").action(withErrorHandler(program, async (gOpts, opts) => {
@@ -1504,6 +1605,246 @@ function registerRegister(program) {
 	}));
 }
 //#endregion
+//#region src/commands/relay.ts
+function emitLifecycle$1(json, data) {
+	if (json) console.log(JSON.stringify({
+		event: "lifecycle",
+		data
+	}));
+}
+function jitteredDelayMs$1(backoffSeconds) {
+	return Math.round(backoffSeconds * (.5 + Math.random()) * 1e3);
+}
+function sleep(ms) {
+	return new Promise((r) => setTimeout(r, ms));
+}
+/**
+* Parse --port into a valid TCP port. `0` is accepted as "OS-assign an ephemeral
+* port" (it is NOT coerced to the default — that was the L3 footgun); a
+* non-integer or out-of-range value throws a clear error rather than silently
+* falling back. The default flag value "8443" parses straight through.
+*/
+function parsePort(raw) {
+	const port = Number(raw);
+	if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error(`Invalid --port '${raw}': expected an integer 0-65535.`);
+	return port;
+}
+function isRevoked(err) {
+	return typeof err === "object" && err !== null && err.revoked === true;
+}
+/**
+* Resolve the HMAC secret: --secret-env > --secret-file > the persisted file.
+* Returns "" (and warns, naming the three sources tried) when none is found — an
+* empty secret can never match GitHub's real signature, so every request drops
+* safely rather than relaying an unverified body.
+*/
+function resolveSecret(opts, configDir, agentId) {
+	if (opts.secretEnv) {
+		const v = process.env[opts.secretEnv];
+		if (v) return v.trim();
+	}
+	if (opts.secretFile) return readFileSync(opts.secretFile, "utf-8").trim();
+	const stored = loadHookSecret(configDir, agentId, opts.hook);
+	if (stored) return stored;
+	process.stderr.write(`No hook secret found (tried --secret-env, --secret-file, and ${configDir}/funnel/${agentId}/${opts.hook}.secret) — all inbound requests will fail verification until one is provided.\n`);
+	return "";
+}
+function registerRelay(program) {
+	program.command("relay").description("Run the inbound webhook funnel relay (long-lived foreground daemon)").option("--agent <id>", "Agent ID (defaults to your agent)").option("--hook <name>", "Hook name to relay", "default").option("--port <n>", "Local TLS listener port", "8443").option("--secret-file <path>", "Read the HMAC secret from a file").option("--secret-env <VAR>", "Read the HMAC secret from an env var").option("--staging", "Use the Let's Encrypt staging CA (dev)").option("--verbose", "Verbose reconnect logging").action(async (opts) => {
+		try {
+			const gOpts = program.opts();
+			const configDir = resolveConfigDir();
+			const apiUrl = resolveApiUrl();
+			const { client, profileName, entry } = await createClient(configDir, apiUrl, gOpts.profile);
+			const agentId = await resolveAgent(apiUrl, await fetchAgents(client), opts.agent, gOpts.as);
+			if (!agentKeysExist(configDir, agentId)) {
+				printError(`Agent identity keys not found under ${configDir}/keys/${agentId}/ — register first.`);
+				process.exitCode = 2;
+				return;
+			}
+			await runRelayLoop({
+				opts,
+				gOpts,
+				configDir,
+				apiUrl,
+				agentId,
+				client,
+				profileName,
+				entry
+			});
+		} catch (err) {
+			printError(err instanceof Error ? err.message : String(err));
+			process.exitCode = 1;
+		}
+	});
+}
+async function runRelayLoop(ctx) {
+	const { opts, gOpts, configDir, apiUrl, agentId, client, profileName, entry } = ctx;
+	const json = gOpts.json;
+	const port = parsePort(opts.port);
+	const secret = resolveSecret(opts, configDir, agentId);
+	const options = { staging: opts.staging };
+	let backoff = 1;
+	let attempt = 0;
+	let stopped = false;
+	let lastDeps;
+	let certHandle;
+	process.on("SIGINT", () => {
+		stopped = true;
+		process.exitCode = 0;
+	});
+	while (!stopped) {
+		attempt++;
+		let listener;
+		try {
+			const { hostname, control_ws_url: controlWsUrl } = await resolveHook(client, agentId, opts.hook);
+			certHandle = hookLabel(hostname);
+			lastDeps = await buildIssueCertDeps({
+				configDir,
+				options,
+				http: client,
+				agentId
+			});
+			const cert = await ensureCert({
+				handle: certHandle,
+				agentId,
+				delegationId: certHandle,
+				configDir,
+				options,
+				deps: lastDeps
+			});
+			emitLifecycle$1(json, {
+				state: "cert_ready",
+				hostname
+			});
+			const ref = {};
+			const tunnel = await connectTunnel({
+				controlWsUrl,
+				token: await getOrRefreshToken(configDir, apiUrl, entry, profileName, {
+					force: false,
+					envToken: process.env.RINE_TOKEN
+				}),
+				agentId,
+				hostname,
+				openLocalPipe: (frame) => {
+					if (!ref.live) throw new Error("listener not ready");
+					return ref.live.openLocalPipe(frame);
+				}
+			});
+			emitLifecycle$1(json, { state: "tunnel_connected" });
+			const live = await startTlsListener({
+				port,
+				certPem: cert.certPem,
+				keyPem: cert.keyPem,
+				onRequest: (req) => handleWebhookRequest({
+					configDir,
+					agentId,
+					hookName: opts.hook,
+					secret,
+					client,
+					emitLifecycle: (ev) => json && console.log(JSON.stringify(ev))
+				}, req).then(() => void 0)
+			});
+			listener = live;
+			ref.live = live;
+			emitLifecycle$1(json, {
+				state: "listener_ready",
+				port: live.port
+			});
+			backoff = 1;
+			const close = await waitForClose(tunnel, () => stopped);
+			tunnel.close();
+			live.close();
+			if (stopped) break;
+			if (close?.clean !== false) {
+				emitLifecycle$1(json, {
+					state: "tunnel_reconnecting",
+					attempt: attempt + 1,
+					backoff_ms: 0,
+					reason: "server_close"
+				});
+				backoff = 1;
+			} else {
+				const delay = jitteredDelayMs$1(backoff);
+				emitLifecycle$1(json, {
+					state: "tunnel_reconnecting",
+					attempt: attempt + 1,
+					backoff_ms: delay,
+					reason: "error"
+				});
+				await sleep(delay);
+				backoff = Math.min(backoff * 2, 30);
+			}
+		} catch (err) {
+			listener?.close();
+			if (stopped) break;
+			if (isRevoked(err)) {
+				emitLifecycle$1(json, { state: "tunnel_revoked" });
+				if (lastDeps && certHandle) await revokeAndWipeCache({
+					handle: certHandle,
+					configDir,
+					options,
+					deps: lastDeps
+				}).catch(() => {});
+				process.exitCode = 1;
+				return;
+			}
+			const delay = jitteredDelayMs$1(backoff);
+			emitLifecycle$1(json, {
+				state: "tunnel_reconnecting",
+				attempt: attempt + 1,
+				backoff_ms: delay,
+				reason: "error"
+			});
+			if (opts.verbose) process.stderr.write(`Reconnecting (attempt ${attempt + 1}, error): ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+			await sleep(delay);
+			backoff = Math.min(backoff * 2, 30);
+		}
+	}
+	emitLifecycle$1(json, {
+		state: "stopped",
+		reason: "signal"
+	});
+}
+/**
+* Resolve when the tunnel WS closes (carrying the classified close so the caller
+* can pick clean-vs-error reconnect) OR a SIGINT arrives (resolves `undefined`;
+* the caller's `stopped` flag short-circuits before the reconnect branch).
+*/
+function waitForClose(tunnel, isStopped) {
+	return new Promise((resolve) => {
+		if (isStopped()) return resolve(void 0);
+		tunnel.onClose((close) => resolve(close));
+		process.once("SIGINT", () => {
+			tunnel.close();
+			resolve(void 0);
+		});
+	});
+}
+/**
+* The server hook row — the SINGLE source of truth, used VERBATIM. Its
+* `hostname` (the `{hook}--{slug}.hook.rine.network` form) goes into the BIND and
+* (via its label) the cert CN/SAN; its `control_ws_url` is the broker control-WS
+* endpoint the relay dials. NEITHER is reconstructed client-side: a fabricated
+* `<uuid>.hook.rine.network` matches no funnel_hook row (BIND would NAK, the cert
+* would never match GitHub's TLS), and the API base resolves to the primary IP /
+* Caddy, which has no funnel route. On a missing row or a transient lookup
+* failure we THROW so the loop backs off and retries.
+*/
+async function resolveHook(client, agentId, hookName) {
+	const hook = (await client.get(`/agents/${agentId}/funnel/hooks`, {}))?.items?.find((h) => h.hook_name === hookName);
+	if (!hook?.hostname || !hook.control_ws_url) throw new Error(`No funnel hook '${hookName}' found for agent ${agentId} — run \`rine hook create --name ${hookName}\` first.`);
+	return hook;
+}
+/**
+* The DNS LABEL of a hook hostname — everything before `.hook.rine.network`. The
+* cert is issued for this label via hookFqdn(label), so the leaf's CN/SAN equals
+* the public hostname GitHub connects to (no name mismatch on the TLS handshake).
+*/
+function hookLabel(hostname) {
+	return hostname.endsWith(".hook.rine.network") ? hostname.slice(0, -18) : hostname;
+}
+//#endregion
 //#region src/commands/stream.ts
 function emitLifecycle(gOpts, monitor, data) {
 	if (gOpts.json) {
@@ -1789,8 +2130,10 @@ registerMessages(program);
 registerGroup(program);
 registerDiscover(program);
 registerWebhook(program);
+registerHook(program);
 registerKeys(program);
 registerStream(program);
+registerRelay(program);
 registerPollToken(program);
 program.parse();
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rine-network/cli",
-  "version": "0.10.2",
+  "version": "0.11.1",
   "description": "CLI client for rine.network \u2014 EU-first messaging infrastructure for AI agents",
   "author": "mmmbs <mmmbs@proton.me>",
   "license": "EUPL-1.2",
@@ -28,7 +28,7 @@
     "dev": "tsx src/main.ts"
   },
   "dependencies": {
-    "@rine-network/core": "^0.5.2",
+    "@rine-network/core": "^0.6.1",
     "commander": "^12.0.0",
     "eventsource-client": "^1.1.0"
   },