@agent-device/proxy 0.21.28-nightly.20261014.57 → 0.21.28

package/README.md

@@ -5,7 +5,8 @@ The proxy behind `agent-device proxy`, as a library. Embed it in your own gatewa
 
 The proxy:
 
-- authenticates clients with a token you choose, and never exposes the daemon's own token;
+- authenticates clients with a token you choose, or with your own check, and never exposes the
+  daemon's own token;
 - forwards only the routes a remote client needs: `/health`, `/rpc`, uploads, artifacts, and
   request diagnostics;
 - refuses install sources that name a file on the daemon host;
@@ -89,13 +90,53 @@ const proxy = createDaemonProxy({
 `upstreamFetch` receives a `Request` addressed to `upstreamBaseUrl` and must resolve with the
 daemon's `Response`. Abort the exchange when `request.signal` aborts.
 
+### Authenticate each client yourself
+
+One `clientToken` is shared by every client. To give each client its own credential, pass
+`authenticate` instead. It receives each client request (with its JSON body on `/rpc`) and returns
+the tenant the client acts as, or `null` to refuse it with a 401:
+
+```ts
+const proxy = createDaemonProxy({
+  upstreamBaseUrl: 'http://127.0.0.1:4310',
+  upstreamToken: daemonToken,
+  authenticate: async (request) => {
+    const account = await accounts.findByApiKey(request.headers.get('authorization'));
+    return account ? { tenantId: account.id } : null;
+  },
+});
+```
+
+The proxy then sends every authenticated request to the daemon as that tenant, whatever tenant the
+client named, and isolates its sessions from other tenants' sessions. `GET /health` is not
+authenticated and carries no tenant. A tenant id is 1-128 letters, numbers, dots, underscores or
+hyphens; any other id fails the request with a 500. On `/rpc` the proxy accepts only
+`agent_device.command` and the `agent_device.lease.*` methods (or the same names spelled
+`agent-device.command` and `agent-device.lease.*`), and refuses others with a 401.
+
+Clients upload files with a ticket that names the headers to send. The proxy builds that ticket
+from the daemon ticket's `content-type` and the client's own credential, so it never carries the
+daemon's token. By default the credential is the client's `authorization` and
+`x-agent-device-token` headers. If your clients use another header, such as a cookie or an API key
+header, return it as `uploadHeaders` so the upload passes `authenticate` too:
+
+```ts
+authenticate: async (request) => {
+  const apiKey = request.headers.get('x-api-key');
+  if (!apiKey) return null;
+  const account = await accounts.findByApiKey(apiKey);
+  return account ? { tenantId: account.id, uploadHeaders: { 'x-api-key': apiKey } } : null;
+},
+```
+
 ## Options
 
 | Option | Default | Meaning |
 | --- | --- | --- |
 | `upstreamBaseUrl` | required | Base URL of the daemon's HTTP server. |
 | `upstreamToken` | required | The daemon's auth token. |
-| `clientToken` | required | Token clients must send as their daemon auth token. |
+| `clientToken` | required without `authenticate` | Token clients must send as their daemon auth token. |
+| `authenticate` | none | Authenticates each client and names its tenant; replaces `clientToken`. |
 | `upstreamFetch` | global `fetch` | Sends one request to the daemon. |
 | `maxRpcBodyBytes` | 1 MiB | Larger `/rpc` bodies get a 400 response. |
 | `upstreamTimeoutMs` | 5 minutes | Longest time one daemon request may take, including its body. |

package/dist/index.d.mts

@@ -6,17 +6,42 @@ import http from "node:http";
  * WebSocket tunnel. Abort the exchange when `request.signal` aborts.
  */
 type DaemonProxyUpstreamFetch = (request: Request) => Promise<Response>;
+/** The client an `authenticate` call admitted. */
+type DaemonProxyAuthenticatedClient = {
+  /** The tenant every request from this client acts as. */
+  tenantId: string;
+  /**
+   * The credential headers an upload ticket gives this client, so its direct upload passes
+   * `authenticate` again. Defaults to the client's own `authorization` and
+   * `x-agent-device-token` request headers, when it sent them.
+   */
+  uploadHeaders?: Record<string, string>;
+};
+/**
+ * Authenticates one client request and names the client it admits, or returns `null` to refuse
+ * it. The request carries the client's headers and, for `/rpc`, its JSON body.
+ */
+type DaemonProxyAuthenticate = (request: Request) => Promise<DaemonProxyAuthenticatedClient | null> | DaemonProxyAuthenticatedClient | null;
 type DaemonProxyOptions = {
   /** Base URL of the upstream agent-device daemon HTTP server. */
   upstreamBaseUrl: string;
   /** Auth token of the upstream daemon. Never leaves the proxy. */
   upstreamToken: string;
-  /** Token proxy clients must present as their daemon auth token. */
-  clientToken: string;
   maxRpcBodyBytes?: number;
   upstreamTimeoutMs?: number;
   upstreamFetch?: DaemonProxyUpstreamFetch;
-};
+} & ({
+  /** Token proxy clients must present as their daemon auth token. */
+  clientToken: string;
+  authenticate?: undefined;
+} | {
+  clientToken?: undefined;
+  /**
+   * Replaces the `clientToken` check. Every forwarded request acts as the returned tenant,
+   * with its sessions isolated from other tenants.
+   */
+  authenticate: DaemonProxyAuthenticate;
+});
 type DaemonProxy = {
   /** Identifies this proxy instance in its health payload, so clients notice a restart. */
   readonly instanceId: string;
@@ -33,4 +58,4 @@ declare function createDaemonProxyServer(options: DaemonProxyOptions): http.Serv
 /** Serves a proxy from any `node:http` or `node:https` server; upload tickets follow its scheme. */
 declare function createDaemonProxyRequestListener(proxy: DaemonProxy): http.RequestListener;
 //#endregion
-export { type DaemonProxy, type DaemonProxyOptions, type DaemonProxyUpstreamFetch, createDaemonProxy, createDaemonProxyRequestListener, createDaemonProxyServer };
+export { type DaemonProxy, type DaemonProxyAuthenticate, type DaemonProxyAuthenticatedClient, type DaemonProxyOptions, type DaemonProxyUpstreamFetch, createDaemonProxy, createDaemonProxyRequestListener, createDaemonProxyServer };

package/dist/index.mjs

@@ -31,6 +31,18 @@ function buildDaemonHttpAuthHeaders(token) {
 		"x-agent-device-token": normalizedToken
 	};
 }
+/** The tenant id every daemon route accepts, trimmed, or `undefined` when it breaks the rule. */
+function normalizeTenantId(raw) {
+	if (!raw) return void 0;
+	const value = raw.trim();
+	if (!value) return void 0;
+	if (!/^[a-zA-Z0-9._-]{1,128}$/.test(value)) return void 0;
+	return value;
+}
+/** Whether `sessionName` lies beneath the `<tenant>:` prefix tenant isolation names sessions with. */
+function isTenantOwnedSessionName(tenant, sessionName) {
+	return sessionName.startsWith(`${tenant}:`);
+}
 const DAEMON_HTTP_INSTANCE_HEADER = "x-agent-device-instance";
 const DAEMON_HTTP_UPSTREAM_INSTANCE_HEADER = "x-agent-device-upstream-instance";
 const DAEMON_HTTP_INSTANCE_MISMATCH_HEADER = "x-agent-device-instance-mismatch";
@@ -98,6 +110,8 @@ function readRecord(value) {
 }
 //#endregion
 //#region src/daemon-proxy.ts
+/** The client request headers an upload ticket repeats when `authenticate` names none. */
+const DEFAULT_UPLOAD_CREDENTIAL_HEADERS = Object.keys(buildDaemonHttpAuthHeaders("client"));
 const DEFAULT_MAX_RPC_BODY_BYTES = 1048576;
 const DEFAULT_UPSTREAM_TIMEOUT_MS = 3e5;
 const DAEMON_PROXY_PREFIX = `${DAEMON_HTTP_BASE_PATH}/`;
@@ -149,7 +163,14 @@ async function handleProxyRequest(request, options, instanceId) {
 	if (!isSupportedDaemonRoute(route, request.method)) return new Response(new TextEncoder().encode("Not found"), { status: 404 });
 	let rpcBody;
 	if (route === "/rpc") rpcBody = await readRequestText(request, options.maxRpcBodyBytes, "Proxy request body is too large.");
-	if (!isAuthorized(request, options.clientToken, rpcBody)) return unauthorizedResponse(route, readJsonRpcId(rpcBody));
+	const caller = await authenticateCaller(request, options, rpcBody);
+	if (!caller) return unauthorizedResponse(route, readJsonRpcId(rpcBody));
+	if (caller.tenantId && !isRouteWithinTenant(route, caller.tenantId)) return Response.json({
+		ok: false,
+		error: "Session is outside this tenant",
+		code: "UNAUTHORIZED"
+	}, { status: 401 });
+	if (caller.tenantId && route === "/rpc" && !isTenantStampedRpcMethod(rpcBody)) return tenantRpcMethodRefusedResponse(readJsonRpcId(rpcBody));
 	const staleInstance = refuseStaleProxyInstance(request, route, readJsonRpcId(rpcBody), instanceId);
 	if (staleInstance) return staleInstance;
 	if (carriesUnbackedHostPathInstallSource(rpcBody)) return hostPathInstallSourceRefusedResponse(readJsonRpcId(rpcBody));
@@ -157,9 +178,61 @@ async function handleProxyRequest(request, options, instanceId) {
 		request,
 		route,
 		options,
-		rpcBody
+		rpcBody,
+		caller
 	});
 }
+async function authenticateCaller(request, options, rpcBody) {
+	if (!options.authenticate) return isAuthorized(request, options.clientToken ?? "", rpcBody) ? { uploadHeaders: buildDaemonHttpAuthHeaders(options.clientToken) } : null;
+	const result = await options.authenticate(new Request(request.url, {
+		method: request.method,
+		headers: request.headers,
+		signal: request.signal,
+		...rpcBody !== void 0 ? { body: rpcBody } : {}
+	}));
+	if (!result) return null;
+	const tenantId = normalizeTenantId(typeof result.tenantId === "string" ? result.tenantId : void 0);
+	if (!tenantId) throw new AppError("COMMAND_FAILED", "Proxy authenticate returned an invalid tenantId", { hint: "Return a tenantId of 1-128 letters, digits, \".\", \"_\" or \"-\"." });
+	return {
+		tenantId,
+		uploadHeaders: result.uploadHeaders ?? defaultUploadHeaders(request)
+	};
+}
+function defaultUploadHeaders(request) {
+	const headers = {};
+	for (const name of DEFAULT_UPLOAD_CREDENTIAL_HEADERS) {
+		const value = request.headers.get(name);
+		if (value !== null) headers[name] = value;
+	}
+	return headers;
+}
+/**
+* The daemon does not partition a tenant it did not attest itself, so the proxy confines the
+* diagnostics route to the sessions the daemon named beneath `<tenant>:`. Other routes pass.
+*/
+function isRouteWithinTenant(route, tenantId) {
+	if (!isRequestDiagnosticsRoute(route)) return true;
+	try {
+		return isTenantOwnedSessionName(tenantId, decodeURIComponent(route.split("/")[2] ?? ""));
+	} catch {
+		return false;
+	}
+}
+/** The RPC methods whose every tenant field `stampRpcTenant` sets. */
+const TENANT_STAMPED_RPC_METHODS = /* @__PURE__ */ new Set([
+	"agent_device.command",
+	"agent-device.command",
+	"agent_device.lease.allocate",
+	"agent-device.lease.allocate",
+	"agent_device.lease.heartbeat",
+	"agent-device.lease.heartbeat",
+	"agent_device.lease.release",
+	"agent-device.lease.release"
+]);
+function isTenantStampedRpcMethod(rpcBody) {
+	const method = readJsonRpcMethod(rpcBody);
+	return method !== void 0 && TENANT_STAMPED_RPC_METHODS.has(method);
+}
 async function proxyHealthResponse(request, options, instanceId) {
 	const [upstream, { readVersion }, { readHostCpuArch }] = await Promise.all([
 		readUpstreamHealth(request, options),
@@ -192,11 +265,11 @@ async function readUpstreamHealth(request, options) {
 	}
 }
 async function forwardProxyRequest(params) {
-	const { request, route, options, rpcBody } = params;
-	const body = resolveUpstreamBody(request, route, rpcBody, options.upstreamToken);
+	const { request, route, options, rpcBody, caller } = params;
+	const body = resolveUpstreamBody(request, route, rpcBody, options.upstreamToken, caller.tenantId);
 	const upstreamResponse = await options.upstreamFetch(new Request(buildUpstreamUrl(options.upstreamBaseUrl, route, request.url), {
 		method: request.method,
-		headers: buildUpstreamHeaders(request.headers, options.upstreamToken, route),
+		headers: buildUpstreamHeaders(request.headers, options.upstreamToken, route, caller.tenantId),
 		signal: upstreamSignal(request, options),
 		...body ? {
 			body,
@@ -208,7 +281,7 @@ async function forwardProxyRequest(params) {
 		request,
 		upstreamResponse,
 		headers,
-		clientToken: options.clientToken
+		uploadHeaders: caller.uploadHeaders
 	});
 	return new Response(upstreamResponse.body, {
 		status: upstreamResponse.status,
@@ -238,15 +311,15 @@ function routeResponseHeaders(route) {
 	return [];
 }
 async function rewrittenUploadPreflightResponse(params) {
-	const { request, upstreamResponse, headers, clientToken } = params;
+	const { request, upstreamResponse, headers, uploadHeaders } = params;
 	const text = await upstreamResponse.text();
 	headers.set("content-type", upstreamResponse.headers.get("content-type") ?? "application/json");
-	return new Response(rewriteUploadPreflightResponse(text, request, clientToken), {
+	return new Response(rewriteUploadPreflightResponse(text, request, uploadHeaders), {
 		status: upstreamResponse.status,
 		headers
 	});
 }
-function rewriteUploadPreflightResponse(body, request, clientToken) {
+function rewriteUploadPreflightResponse(body, request, uploadHeaders) {
 	let parsed;
 	try {
 		parsed = JSON.parse(body);
@@ -255,20 +328,26 @@ function rewriteUploadPreflightResponse(body, request, clientToken) {
 	}
 	if (!parsed || typeof parsed !== "object") return body;
 	const record = parsed;
-	if (!record.upload || typeof record.upload.url !== "string") return body;
-	const rewrittenUrl = rewriteUploadDirectUrl(record.upload.url, request);
-	if (!rewrittenUrl) return body;
-	const headers = record.upload.headers && typeof record.upload.headers === "object" ? { ...record.upload.headers } : {};
-	Object.assign(headers, buildDaemonHttpAuthHeaders(clientToken));
+	if (!record.upload || typeof record.upload !== "object") return body;
+	const rewrittenUrl = typeof record.upload.url === "string" ? rewriteUploadDirectUrl(record.upload.url, request) : null;
 	return JSON.stringify({
 		...parsed,
 		upload: {
 			...record.upload,
-			url: rewrittenUrl,
-			headers
+			...rewrittenUrl ? { url: rewrittenUrl } : {},
+			headers: {
+				...upstreamTicketContentType(record.upload.headers),
+				...rewrittenUrl ? uploadHeaders : {}
+			}
 		}
 	});
 }
+/** The only upstream ticket header a client ticket repeats; daemon credentials never pass. */
+function upstreamTicketContentType(headers) {
+	if (!headers || typeof headers !== "object") return {};
+	for (const [name, value] of Object.entries(headers)) if (name.toLowerCase() === "content-type" && typeof value === "string") return { "content-type": value };
+	return {};
+}
 function rewriteUploadDirectUrl(upstreamUrl, request) {
 	let parsed;
 	try {
@@ -290,7 +369,8 @@ function normalizeProxyOptions(options) {
 	return {
 		upstreamBaseUrl: normalizeBaseUrl(options.upstreamBaseUrl, "upstreamBaseUrl"),
 		upstreamToken: normalizeToken(options.upstreamToken, "upstreamToken"),
-		clientToken: normalizeToken(options.clientToken, "clientToken"),
+		clientToken: options.authenticate ? void 0 : normalizeToken(options.clientToken ?? "", "clientToken"),
+		authenticate: options.authenticate,
 		maxRpcBodyBytes: options.maxRpcBodyBytes ?? DEFAULT_MAX_RPC_BODY_BYTES,
 		upstreamTimeoutMs: options.upstreamTimeoutMs ?? DEFAULT_UPSTREAM_TIMEOUT_MS,
 		upstreamFetch: options.upstreamFetch ?? ((request) => fetch(request))
@@ -352,12 +432,13 @@ function buildUpstreamInstancePreconditionHeaders(requestHeaders) {
 	const expectedUpstreamInstance = requestHeaders.get(DAEMON_HTTP_UPSTREAM_INSTANCE_HEADER);
 	return expectedUpstreamInstance !== null ? { [DAEMON_HTTP_INSTANCE_HEADER]: expectedUpstreamInstance } : {};
 }
-function buildUpstreamHeaders(requestHeaders, upstreamToken, route) {
+function buildUpstreamHeaders(requestHeaders, upstreamToken, route, tenantId) {
 	const headers = new Headers();
 	for (const name of FORWARDED_REQUEST_HEADERS) {
 		const value = requestHeaders.get(name);
 		if (value?.trim()) headers.set(name, value);
 	}
+	if (tenantId) headers.set(DAEMON_HTTP_TENANT_HEADER, tenantId);
 	if (route === "/rpc" && !headers.has("content-type")) headers.set("content-type", "application/json");
 	if (route === "/rpc") {
 		headers.set(DAEMON_HTTP_NETWORK_ACCESS_HEADER, DAEMON_HTTP_PUBLIC_NETWORK_ACCESS);
@@ -366,9 +447,9 @@ function buildUpstreamHeaders(requestHeaders, upstreamToken, route) {
 	for (const [name, value] of Object.entries(buildDaemonHttpAuthHeaders(upstreamToken))) headers.set(name, value);
 	return headers;
 }
-function resolveUpstreamBody(request, route, rpcBody, upstreamToken) {
+function resolveUpstreamBody(request, route, rpcBody, upstreamToken, tenantId) {
 	if (request.method === "GET" || request.method === "HEAD") return null;
-	if (route === "/rpc") return rewriteRpcToken(rpcBody ?? "", upstreamToken);
+	if (route === "/rpc") return rewriteRpcParams(rpcBody ?? "", upstreamToken, tenantId);
 	return request.body;
 }
 async function readRequestText(request, maxBodyBytes, tooLargeMessage) {
@@ -403,14 +484,33 @@ function resolveRequestToken(request, rpcBody) {
 	}
 	return "";
 }
-function rewriteRpcToken(body, upstreamToken) {
+function rewriteRpcParams(body, upstreamToken, tenantId) {
 	const parsed = JSON.parse(body);
 	parsed.params = {
 		...parsed.params ?? {},
 		token: upstreamToken
 	};
+	if (tenantId) stampRpcTenant(parsed.params, tenantId);
 	return JSON.stringify(parsed);
 }
+/**
+* Sets the tenant everywhere the daemon reads it — `meta` for commands, `tenantId` for lease
+* calls — with tenant session isolation, overwriting whatever the client sent.
+*/
+function stampRpcTenant(params, tenantId) {
+	params.tenantId = tenantId;
+	params.meta = {
+		...asRecord(params.meta),
+		tenantId,
+		sessionIsolation: "tenant"
+	};
+	const flags = asRecord(params.flags);
+	if (flags.tenant !== void 0) flags.tenant = tenantId;
+	if (flags.sessionIsolation !== void 0) flags.sessionIsolation = "tenant";
+}
+function asRecord(value) {
+	return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
 function readJsonRpcToken(body) {
 	try {
 		const parsed = JSON.parse(body);
@@ -419,6 +519,15 @@ function readJsonRpcToken(body) {
 		return "";
 	}
 }
+function readJsonRpcMethod(body) {
+	if (!body) return void 0;
+	try {
+		const { method } = JSON.parse(body);
+		return typeof method === "string" ? method : void 0;
+	} catch {
+		return;
+	}
+}
 function readJsonRpcId(body) {
 	if (!body) return null;
 	try {
@@ -460,6 +569,18 @@ function unauthorizedResponse(route, rpcId) {
 		code: "UNAUTHORIZED"
 	}, { status: 401 });
 }
+function tenantRpcMethodRefusedResponse(rpcId) {
+	const error = new AppError("UNAUTHORIZED", "This RPC method cannot act as an authenticated tenant through the proxy", { hint: "Use agent_device.command or the agent_device.lease methods." });
+	return Response.json({
+		jsonrpc: "2.0",
+		id: rpcId,
+		error: {
+			code: -32001,
+			message: error.message,
+			data: normalizeError(error)
+		}
+	}, { status: 401 });
+}
 function proxyErrorResponse(error) {
 	const normalized = normalizeError(error);
 	return Response.json({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-device/proxy",
-  "version": "0.21.28-nightly.20261014.57",
+  "version": "0.21.28",
   "type": "module",
   "description": "Transport-neutral authenticating proxy in front of an agent-device daemon.",
   "license": "MIT",
@@ -25,9 +25,9 @@
     "dist"
   ],
   "devDependencies": {
-    "@agent-device/host-kit": "0.0.0",
+    "@agent-device/contracts": "0.0.0",
     "@agent-device/kernel": "0.0.0",
-    "@agent-device/contracts": "0.0.0"
+    "@agent-device/host-kit": "0.0.0"
   },
   "scripts": {
     "build": "tsdown --config tsdown.config.ts"