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

docs: list every always-public API path and fix the renamed constant (#11850)

Adam Eivya6cb27c88214
diff --git a/AGENTS.md b/AGENTS.md
index 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.md
index 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 same
endpoint Tailscale reachability checks hit. Use it to confirm a tailnet host is a
PortOS instance and to label it on a connection screen **before** the app holds
any credential.
diff --git a/docs/auth-public-paths-doc.test.js b/docs/auth-public-paths-doc.test.js
new file mode 100644
index 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.js
index 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.js
index 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 plain
diff --git a/server/routes/systemHealth.js b/server/routes/systemHealth.js
index 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()
]);