Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

Use the local HTTP mirror for HTTPS agent API calls (#11737)

[._.]/74a778f08ac2
diff --git a/.claude/skills/portos-api/SKILL.md b/.claude/skills/portos-api/SKILL.md
index 4fb4bfefe1..748258b073 100644
--- a/.claude/skills/portos-api/SKILL.md
+++ b/.claude/skills/portos-api/SKILL.md
@@ -19,6 +19,7 @@ node scripts/portos-api.js get /api/api-docs/catalog.json # discover endpoints
- When the user has to do something by hand later (post, reply, upload, sign), schedule it with `POST /api/human-actions/plans` instead of only saying so in chat: each step gets a due time with a UTC offset, explicit `instructions`, and the exact text to paste in `content`. It lands in Review Hub › Actions and notifies them when due. Reuse the same `planKey` to replace a plan. Shape: [docs/API.md › Human Actions](../../../docs/API.md#human-actions).
+- URL order: `PORTOS_URL`, then the agent key file’s URL, then the configured local HTTP listener. With a usable TLS certificate, the fallback uses the loopback HTTP mirror and honors `PORTOS_HTTP_PORT` (exported value, then `.env`, then the shared default). Explicit URLs are never retried against a different listener.
- Credential order: `PORTOS_API_TOKEN` (set inside PortOS-spawned agents), then `~/.portos/agent-key.json` (the agent API key).
- `401 AUTH_REQUIRED` means authentication was rejected: check whether the selected credential is missing, expired, revoked, or invalid without printing it. A set `PORTOS_API_TOKEN` takes precedence over the agent-key file, so a stale injected token can shadow a valid key; obtain a fresh credential through the supported flow. `whoami` answering `"authenticated": false` alone does not prove a missing key, since local requests may be allowed when authentication is disabled. If an external agent needs authentication and no credential is available, ask the user to enable **Settings > Security > Agent API key**. Never ask for, store, or type the instance password.
- Never print the token or paste it into a commit, PR, issue, or chat.
diff --git a/scripts/portos-api.js b/scripts/portos-api.js
index 2292104fa5..27d50b9282 100644
--- a/scripts/portos-api.js
+++ b/scripts/portos-api.js
@@ -16,7 +16,8 @@
* Agent API key is on (`~/.portos/agent-key.json`, or
* `$PORTOS_AGENT_KEY_FILE`; see lib/agentKeyFile.js)
* The base URL is `$PORTOS_URL`, else the key file's `url`, else
- * http://127.0.0.1:5555. A path without a leading `/api/` or `/data/` gets
+ * the configured local HTTP listener (the loopback mirror when TLS is usable).
+ * A path without a leading `/api/` or `/data/` gets
* `/api` prepended. The response body goes to stdout (JSON pretty-printed);
* a non-2xx status exits 1 with the body on stderr.
*
@@ -24,12 +25,28 @@
*/
import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { PORTS } from '../server/lib/ports.js';
+import { resolveInstallRoot } from '../server/lib/dataRoot.js';
+import { certPaths } from '../lib/certPaths.js';
+import { hasTailscaleCert } from '../lib/tailscale-https.js';
+import { parseEnvFile, resolveHttpMirrorPort } from './lib/envFile.js';
import { request as httpRequest } from 'node:http';
import { request as httpsRequest } from 'node:https';
import { resolveAgentKeyFile } from '../lib/agentKeyFile.js';
import { isDirectlyInvoked } from './lib/directInvocation.js';
-const DEFAULT_URL = 'http://127.0.0.1:5555';
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+const localConnection = (env) => {
+ const root = resolveInstallRoot(ROOT);
+ const { PORTOS_HTTP_PORT } = parseEnvFile(join(root, '.env'));
+ const apiPort = PORTS.API;
+ const mirrorPort = resolveHttpMirrorPort({ env, dotenv: { PORTOS_HTTP_PORT } });
+ const tls = hasTailscaleCert(certPaths(join(root, 'data')).dir);
+ return { apiPort, mirrorPort, tls, url: `http://127.0.0.1:${tls ? mirrorPort : apiPort}` };
+};
export const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
const METHODS = new Set(['get', 'post', 'put', 'patch', 'delete']);
const PRIORITIES = new Set(['LOW', 'MEDIUM', 'HIGH', 'CRITICAL']);
@@ -109,7 +126,7 @@ export const resolveCredentials = async (env = process.env) => {
const keyFile = await readFile(resolveAgentKeyFile(env), 'utf8')
.then((raw) => JSON.parse(raw))
.catch(() => null);
- const url = (env.PORTOS_URL || keyFile?.url || DEFAULT_URL).replace(/\/+$/, '');
+ const url = (env.PORTOS_URL || keyFile?.url || localConnection(env).url).replace(/\/+$/, '');
const token = env.PORTOS_API_TOKEN || (typeof keyFile?.token === 'string' ? keyFile.token : null);
return { url, token };
};
@@ -159,7 +176,18 @@ export const main = async (argv = process.argv.slice(2), env = process.env) => {
const headers = { Accept: 'application/json' };
if (token) headers.Authorization = `Bearer ${token}`;
if (body !== null) headers['Content-Type'] = 'application/json';
- const { status, text } = await requestApi(`${url}${parsed.path}`, { method: parsed.method, headers, body, timeoutMs: parsed.timeoutMs ?? DEFAULT_TIMEOUT_MS });
+ const { status, text } = await requestApi(`${url}${parsed.path}`, { method: parsed.method, headers, body, timeoutMs: parsed.timeoutMs ?? DEFAULT_TIMEOUT_MS })
+ .catch((error) => {
+ const target = new URL(url);
+ if (error.code === 'ECONNRESET' && target.protocol === 'http:'
+ && ['127.0.0.1', 'localhost', '[::1]'].includes(target.hostname)) {
+ const local = localConnection(env);
+ if (local.tls && Number(target.port || 80) === local.apiPort) {
+ throw new Error(`Connection reset: this local API port is configured for HTTPS. Use PORTOS_URL=http://127.0.0.1:${local.mirrorPort} for its HTTP mirror.`, { cause: error });
+ }
+ }
+ throw error;
+ });
let out = text;
try { out = JSON.stringify(JSON.parse(text), null, 2); } catch { /* not JSON: print as-is */ }
if (status >= 200 && status < 300) {
diff --git a/scripts/portos-api.test.js b/scripts/portos-api.test.js
index adff96d35d..aa18881017 100644
--- a/scripts/portos-api.test.js
+++ b/scripts/portos-api.test.js
@@ -4,12 +4,26 @@
* credential wins when both the spawn env and the key file are present.
*/
import { describe, it, expect, afterEach, vi } from 'vitest';
-import { createServer } from 'node:http';
-import { mkdtemp, rm, writeFile } from 'fs/promises';
-import { tmpdir } from 'os';
-import { join } from 'path';
+import { createServer, request as httpRequest } from 'node:http';
+import { EventEmitter } from 'node:events';
+
+vi.mock('node:http', async (importOriginal) => {
+ const original = await importOriginal();
+ return { ...original, request: vi.fn(original.request) };
+});
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createServer as createTlsServer } from 'node:https';
+import { PORTS } from '../server/lib/ports.js';
+import { DISPOSABLE_ROOT_MARKER } from '../server/lib/dataRoot.js';
import { main, parseArgs, resolveCredentials } from './portos-api.js';
+
+// Synthetic TLS material; used only by isolated loopback fixtures.
+const TLS_KEY = '-----BEGIN PRIVATE KEY-----\nMIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgsmTM3L/sbDmQbdMy\nhB0Cr2yvl2GrcWmbQM+zu8RjsFyhRANCAASSt8pu/qVh51sOU9YpdzAkKufDGjbq\n4HHPRUwKYqQlDM2fVIKOqO+NqjyOlCiBX21gzbnYU057iXRVJZgEH8jH\n-----END PRIVATE KEY-----\n';
+const TLS_CERT = '-----BEGIN CERTIFICATE-----\nMIIBfTCCASKgAwIBAgIURm+4Ws6hBxzNDDslU4mibL+EV3QwCgYIKoZIzj0EAwIw\nJDEiMCAGA1UEAwwZc3ludGhldGljLXBvcnRvcy1hcGkudGVzdDAeFw0yNjEwMTcw\nMTU3NDlaFw0zNjEwMTQwMTU3NDlaMCQxIjAgBgNVBAMMGXN5bnRoZXRpYy1wb3J0\nb3MtYXBpLnRlc3QwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASSt8pu/qVh51sO\nU9YpdzAkKufDGjbq4HHPRUwKYqQlDM2fVIKOqO+NqjyOlCiBX21gzbnYU057iXRV\nJZgEH8jHozIwMDAdBgNVHQ4EFgQUk3SePqT2M4mcfL9y9Y8MhK226oswDwYDVR0T\nAQH/BAUwAwEB/zAKBggqhkjOPQQDAgNJADBGAiEAsh5/nlEF2WXrJGDsdm2NrD81\nj5omkDkpxyJHHgjH8+wCIQD2U6RF+9aXsztQ/o27GH+/DZluuBgdNiQOVwK8nM0F\nfA==\n-----END CERTIFICATE-----\n';
+
describe('parseArgs', () => {
it('builds a CoS task from the task shorthand', () => {
const parsed = parseArgs(['task', 'Fix', 'the', 'upload', 'test', '--app', 'portos', '--priority', 'high']);
@@ -118,7 +132,10 @@ describe('API request lifecycle', () => {
describe('resolveCredentials', () => {
let dir;
- afterEach(async () => { if (dir) await rm(dir, { recursive: true, force: true }); });
+ afterEach(async () => {
+ vi.unstubAllEnvs();
+ if (dir) await rm(dir, { recursive: true, force: true });
+ });
it('reads the key file, with PORTOS_API_TOKEN and PORTOS_URL taking precedence', async () => {
dir = await mkdtemp(join(tmpdir(), 'portos-api-cli-'));
@@ -132,7 +149,93 @@ describe('resolveCredentials', () => {
});
it('falls back to the default URL and no token without a key file', async () => {
- await expect(resolveCredentials({ PORTOS_AGENT_KEY_FILE: join(tmpdir(), 'portos-missing-key.json') }))
- .resolves.toEqual({ url: 'http://127.0.0.1:5555', token: null });
+ dir = await mkdtemp(join(tmpdir(), 'portos-api-no-cert-'));
+ await writeFile(join(dir, DISPOSABLE_ROOT_MARKER), 'test fixture');
+ vi.stubEnv('PORTOS_DATA_ROOT', dir);
+ await expect(resolveCredentials({ PORTOS_AGENT_KEY_FILE: join(dir, 'missing-key.json') }))
+ .resolves.toEqual({ url: `http://127.0.0.1:${PORTS.API}`, token: null });
+ });
+});
+
+
+describe('local install URL selection', () => {
+ let root;
+ const servers = [];
+ const listen = async (server) => {
+ servers.push(server);
+ await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+ return server.address().port;
+ };
+ const setup = async (tls = false) => {
+ root = await mkdtemp(join(tmpdir(), 'portos-api-config-'));
+ await writeFile(join(root, DISPOSABLE_ROOT_MARKER), 'test fixture');
+ vi.stubEnv('PORTOS_DATA_ROOT', root);
+ await mkdir(join(root, 'data/certs'), { recursive: true });
+ if (tls) {
+ await writeFile(join(root, 'data/certs/cert.pem'), TLS_CERT);
+ await writeFile(join(root, 'data/certs/key.pem'), TLS_KEY);
+ }
+ return { PORTOS_AGENT_KEY_FILE: join(root, 'missing-key.json'), PORTOS_API_TOKEN: 'synthetic-token' };
+ };
+ afterEach(async () => {
+ for (const server of servers.splice(0)) {
+ server.closeAllConnections();
+ if (server.listening) await new Promise(resolve => server.close(resolve));
+ }
+ vi.unstubAllEnvs();
+ vi.restoreAllMocks();
+ if (root) await rm(root, { recursive: true, force: true });
+ });
+
+ it('reaches the configured TLS mirror and preserves credentials', async () => {
+ const env = await setup(true);
+ const seen = [];
+ const port = await listen(createServer((req, res) => {
+ seen.push({ path: req.url, auth: req.headers.authorization });
+ res.end('{"authenticated":true}');
+ }));
+ await writeFile(join(root, '.env'), `PORTOS_HTTP_PORT=${port}\n`);
+ vi.spyOn(console, 'log').mockImplementation(() => {});
+ await expect(main(['whoami'], env)).resolves.toBe(0);
+ expect(seen).toEqual([{ path: '/api/auth/whoami', auth: 'Bearer synthetic-token' }]);
+ await expect(resolveCredentials({ ...env, PORTOS_HTTP_PORT: '12345' }))
+ .resolves.toMatchObject({ url: 'http://127.0.0.1:12345' });
+ await expect(resolveCredentials({ ...env, PORTOS_HTTP_PORT: 'invalid' }))
+ .resolves.toMatchObject({ url: `http://127.0.0.1:${port}` });
+ });
+
+ it('uses the shared defaults and treats unusable certificate files like the server', async () => {
+ const env = await setup(true);
+ await expect(resolveCredentials(env)).resolves.toMatchObject({ url: `http://127.0.0.1:${PORTS.API_LOCAL}` });
+ await writeFile(join(root, 'data/certs/key.pem'), 'incomplete key');
+ await expect(resolveCredentials({ ...env, PORT: String(PORTS.COS) })).resolves.toMatchObject({ url: `http://127.0.0.1:${PORTS.API}` });
+ });
+
+ it('keeps explicit and key-file URLs ahead of TLS-derived defaults without rewriting their audience', async () => {
+ const env = await setup(true);
+ await writeFile(env.PORTOS_AGENT_KEY_FILE, JSON.stringify({ url: 'https://peer.example.test:9443/', token: 'from-file' }));
+ await expect(resolveCredentials(env)).resolves.toEqual({ url: 'https://peer.example.test:9443', token: 'synthetic-token' });
+ await expect(resolveCredentials({ ...env, PORTOS_URL: 'https://explicit.example.test/' }))
+ .resolves.toEqual({ url: 'https://explicit.example.test', token: 'synthetic-token' });
+ });
+
+ it('explains a local TLS-port reset without retrying or sending credentials to the mirror', async () => {
+ const env = await setup(true);
+ const tlsPort = await listen(createTlsServer({ key: TLS_KEY, cert: TLS_CERT }));
+ const mirrorRequests = vi.fn();
+ const mirrorPort = await listen(createServer((_req, res) => { mirrorRequests(); res.end('{}'); }));
+ const config = { ...env, PORTOS_HTTP_PORT: String(mirrorPort), PORTOS_URL: `http://127.0.0.1:${PORTS.API}` };
+ const resetRequest = () => {
+ const request = new EventEmitter();
+ request.end = () => queueMicrotask(() => request.emit('error', Object.assign(new Error('socket hang up'), { code: 'ECONNRESET' })));
+ return request;
+ };
+ vi.mocked(httpRequest).mockImplementationOnce(resetRequest);
+ await expect(main(['whoami'], config)).rejects.toThrow(`PORTOS_URL=http://127.0.0.1:${mirrorPort}`);
+ vi.mocked(httpRequest).mockImplementationOnce(resetRequest);
+ await expect(main(['whoami'], { ...config, PORTOS_URL: `http://external.example.test:${PORTS.API}` }))
+ .rejects.toMatchObject({ code: 'ECONNRESET', message: 'socket hang up' });
+ expect(mirrorRequests).not.toHaveBeenCalled();
+ await expect(main(['whoami'], { ...config, PORTOS_URL: `http://127.0.0.1:${tlsPort}` })).rejects.toMatchObject({ code: 'ECONNRESET', message: 'socket hang up' });
});
});