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
docs: list every always-public API path and fix the renamed constant (#11850)
Adam Eivya6cb27c88214
diff --git a/AGENTS.md b/AGENTS.mdindex 669c7d825a..6581e279e6 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -80,7 +80,7 @@ A full-suite plan runs only the always-run guards unless `--full` is supplied. D**Authentication and HTTPS exist, but are OPT-IN and OFF by default.** Do not assume they are absent:-- **Auth** — an optional instance password (`server/services/auth.js`, enforced by `server/services/authGate.js`) gates all of `/api/*` and `/data/*` when set, with a small always-public set (`/api/auth/status`, `/api/system/health`). Paired peers authenticate through scoped pair credentials attached by `peerFetch` (`server/lib/peerHttpClient.js`); legacy Basic compatibility uses the instance password and is not a scoped credential (see `docs/PEER_PUSH_AUTH.md`). **A PortOS-spawned agent authenticates with `PORTOS_API_TOKEN`** — a loopback session token the server mints and injects into the agent's environment (`server/services/agentApiAuth.js`). Any `curl` you write against this install's own API carries `-H "Authorization: Bearer ${PORTOS_API_TOKEN:-}"`; `401 AUTH_REQUIRED` means authentication was rejected; check for a missing, expired, or invalid token before diagnosing availability. The variable is empty when no password is set (the gate ignores it) and is never given to a public-content review stage.+- **Auth** — an optional instance password (`server/services/auth.js`, enforced by `server/services/authGate.js`) gates all of `/api/*` and `/data/*` when set, with a small always-public set (`ALWAYS_PUBLIC_API_PATHS` in `server/lib/apiAccessPolicy.js`: `/api/auth/status`, `/api/auth/whoami`, `/api/auth/login`, `/api/auth/logout`, `/api/system/health`, `/api/eidoverse/travel/guest`). Paired peers authenticate through scoped pair credentials attached by `peerFetch` (`server/lib/peerHttpClient.js`); legacy Basic compatibility uses the instance password and is not a scoped credential (see `docs/PEER_PUSH_AUTH.md`). **A PortOS-spawned agent authenticates with `PORTOS_API_TOKEN`** — a loopback session token the server mints and injects into the agent's environment (`server/services/agentApiAuth.js`). Any `curl` you write against this install's own API carries `-H "Authorization: Bearer ${PORTOS_API_TOKEN:-}"`; `401 AUTH_REQUIRED` means authentication was rejected; check for a missing, expired, or invalid token before diagnosing availability. The variable is empty when no password is set (the gate ignores it) and is never given to a public-content review stage.- **Agent API key** — an agent PortOS did NOT spawn (a terminal Claude Code / Codex session on this machine) calls the API with `node scripts/portos-api.js …`, which spends `PORTOS_API_TOKEN` when set, else the opt-in key the server keeps in `~/.portos/agent-key.json` (Settings > Security). Never ask for or type the instance password. See [docs/AGENT_API_KEY.md](docs/AGENT_API_KEY.md) and the `portos-api` skill.- **HTTPS** — provisioned by `npm run setup:cert`; `:5555` flips to TLS with a loopback-only HTTP mirror on `:5553`. Peer hops set `rejectUnauthorized: false` ("Tailnet is the trust boundary"): between two tailnet nodes WireGuard supplies mutual auth, but a non-tailnet peer (plain LAN IP / non-`.ts.net` host, see `peerRequiresTailscale()`) gets no server authentication.diff --git a/docs/COMPANION_APP_API.md b/docs/COMPANION_APP_API.mdindex d39a6df183..8b3cfd6bce 100644--- a/docs/COMPANION_APP_API.md+++ b/docs/COMPANION_APP_API.md@@ -32,7 +32,7 @@ plus whether it currently holds an operator session for that instance.## 1. Discovery & identity (pre-auth)`GET /api/system/health` — **public**, bypasses the auth gate even when the-password is on (`PUBLIC_API_PATHS` in `server/services/authGate.js`), and is the same+password is on (`ALWAYS_PUBLIC_API_PATHS` in `server/lib/apiAccessPolicy.js`), and is the sameendpoint Tailscale reachability checks hit. Use it to confirm a tailnet host is aPortOS instance and to label it on a connection screen **before** the app holdsany credential.diff --git a/docs/auth-public-paths-doc.test.js b/docs/auth-public-paths-doc.test.jsnew file mode 100644index 0000000000..c728edc0ca--- /dev/null+++ b/docs/auth-public-paths-doc.test.js@@ -0,0 +1,40 @@+/**+ * Parity guard for the auth-boundary documentation.+ *+ * AGENTS.md's Security Model is treated as ground truth by audits, so its Auth+ * bullet must name every path in ALWAYS_PUBLIC_API_PATHS. It also guards against+ * docs citing the retired bare `PUBLIC_API_PATHS` identifier.+ */+import { execFileSync } from 'child_process';+import { readFileSync } from 'fs';+import { dirname, join } from 'path';+import { fileURLToPath } from 'url';+import { describe, expect, it } from 'vitest';+import { ALWAYS_PUBLIC_API_PATHS } from '../server/lib/apiAccessPolicy.js';++const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');++describe('auth-exempt path documentation', () => {+ it('AGENTS.md Auth bullet names every always-public path and its source file', () => {+ const bullet = readFileSync(join(ROOT, 'AGENTS.md'), 'utf8')+ .split('\n')+ .find((line) => line.startsWith('- **Auth**'));+ expect(bullet).toBeDefined();+ expect(bullet).toContain('server/lib/apiAccessPolicy.js');+ for (const path of ALWAYS_PUBLIC_API_PATHS) expect(bullet).toContain(`\`${path}\``);+ });++ it('no tracked file cites the retired bare PUBLIC_API_PATHS identifier', () => {+ let hits = '';+ try {+ hits = execFileSync(+ 'git',+ ['grep', '-nw', 'PUBLIC_API_PATHS', '--', ':!.changelog', ':!docs/plans', ':!docs/auth-public-paths-doc.test.js'],+ { cwd: ROOT, encoding: 'utf8' },+ );+ } catch (err) {+ if (err.status !== 1) throw err; // 1 = no matches+ }+ expect(hits).toBe('');+ });+});diff --git a/scripts/ci-test-plan.js b/scripts/ci-test-plan.jsindex 0d48411f14..7ba56d2abf 100644--- a/scripts/ci-test-plan.js+++ b/scripts/ci-test-plan.js@@ -275,6 +275,7 @@ export const ALWAYS_RUN_TESTS = [// can select it — a docs-only PR that documented a removed endpoint would// otherwise merge green.'docs/api-doc.test.js',+ 'docs/auth-public-paths-doc.test.js','docs/deps-doc.test.js','docs/features/product-surfaces.test.js','scripts/agent-instructions-files.test.js',diff --git a/scripts/verify-server-health.js b/scripts/verify-server-health.jsindex 17846a4d63..a5006a4a78 100644--- a/scripts/verify-server-health.js+++ b/scripts/verify-server-health.js@@ -20,7 +20,7 @@* is reported as unhealthy. The recovery it triggers is one extra `pm2 start`,* which cannot make an already-healthy install worse.*- * `/api/system/health` is in the always-public set (`PUBLIC_API_PATHS`), so+ * `/api/system/health` is in the always-public set (`ALWAYS_PUBLIC_API_PATHS`), so* this works with the optional instance password on. All three candidate URLs* are probed because the listening scheme/port depends on whether a cert is* provisioned: HTTPS on :5555 plus the loopback HTTP mirror on :5553, or plaindiff --git a/server/routes/systemHealth.js b/server/routes/systemHealth.jsindex b6e821f034..a566483cc7 100644--- a/server/routes/systemHealth.js+++ b/server/routes/systemHealth.js@@ -68,7 +68,7 @@ router.get('/health', asyncHandler(async (req, res) => {getCurrentVersion(),// Whether the optional password gate is on, so a companion client knows to// prompt for a password without a second round-trip to /api/auth/status.- // This endpoint stays public (PUBLIC_API_PATHS) so the client can read+ // This endpoint stays public (ALWAYS_PUBLIC_API_PATHS) so the client can read// identity before it holds any credential.isAuthEnabled()]);