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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
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.mdindex 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.jsindex 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.jsindex 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' });});});