8 Commits
Author SHA1 Message Date
Unheard0840 6a1fda8133 docs: record the SDK 3.1.0 rebase in the fork notes 2026-10-22 17:55:32 +02:00
Unheard0840 9ce1c1aa17 style: apply prettier formatting to current.ts 2026-10-22 17:53:48 +02:00
Unheard0840 536819e8ef Merge remote-tracking branch 'upstream/main'
# Conflicts:
#	startos/versions/current.ts
2026-10-22 17:49:42 +02:00
Matt Hill 7b3a486fd8 Merge pull request #7 from Start9-Community/fix/node-security
fix: rebuild on Node.js 22.23.4 for its security release, bump SDK to 3.1.0; 0.4.1:1 → 0.4.1:2
2026-10-21 21:20:27 -06:00
helix-a fa32dcb72e chore: bump @start9labs/start-sdk to 3.1.0
Helix-Harness: claude-code
Helix-Model: claude-opus-5-5
Helix-Identity: helix-b
2026-10-22 03:17:42 +00:00
Matt HillandClaude Opus 5.5 c1fcaea8ca fix: rebuild on Node.js 22.23.4 for its security release; 0.4.1:1 → 0.4.1:2
Pick up Node.js 22.23.4, which fixes the October 2026 Node security
release (Brotli decoder RCE, TLS hostname-check bypasses and others).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 20:40:14 -06:00
ai-bot e7c2a6a58a docs: restore the fork notes after the upstream AGENTS.md resync 2026-10-10 11:30:05 +00:00
ai-bot 59594d46bc docs: record the SDK 3.0.3 merge and adopt upstream's logging disclosure 2026-10-10 11:29:56 +00:00
6 changed files with 30 additions and 40 deletions

No files matched your search

+6
View File
@@ -34,7 +34,13 @@ verified, tried, and decided belongs in the commit message and the PR body.
## This repo ## This repo
- **This is a fork, and upstream is a moving target.** `packageRepo` points at `sondreolav/ppq-private-mode-startos`; upstream is `Start9-Community/ppq-private-mode-startos`. Take upstream changes with `git merge upstream/main` — never by hand-copying files. A hand-copy leaves upstream's commits outside our history, so GitHub keeps reporting the fork as *N commits behind*, and the gap grows with every upstream release.
- **The package version tracks the vendored proxy, not upstream's wrapper version.** `version` in `startos/versions/current.ts` follows `ppq-private-mode-proxy/package.json` (currently `0.6.0`), while upstream's wrapper sits on its own `0.4.x` line. That makes `current.ts` a conflict on every upstream merge: keep our version, bump the revision (`0.6.0:5`), and write our own release notes.
- **Don't merge `upstream/next`.** `main` is the released line — upstream's `v0.4.1_1` tag sits on it. Our own tags use the same shape: `v0.6.0_5`, with an underscore because git refs cannot contain `:`.
- **`PPQ_ALLOWED_HOSTS` is derived from the binding's own addresses.** Never hardcode hostnames; `main.ts` resolves them reactively, so an address added later is picked up on the next restart.
- **Put package-owned settings in `store.json`, never in `config.json`** — the proxy rewrites `config.json` whole when a key is saved on the Status Page. - **Put package-owned settings in `store.json`, never in `config.json`** — the proxy rewrites `config.json` whole when a key is saved on the Status Page.
- **Don't set `PPQ_API_KEY`** — the proxy's own key store must stay the key's only owner, so the action and the Status Page write the same key. - **Don't set `PPQ_API_KEY`** — the proxy's own key store must stay the key's only owner, so the action and the Status Page write the same key.
- **A blank key field keeps the saved key; don't "fix" it to clear on empty** — it is how the action toggles logging without re-entering the key. - **A blank key field keeps the saved key; don't "fix" it to clear on empty** — it is how the action toggles logging without re-entering the key.
- **The key pattern is validated in the action** because upstream only validates on the Status Page — a malformed key written straight to `config.json` surfaces later as a 401 on the first request.
- **The task is `important`, not `critical`, on purpose.** A `critical` task suspends the ordinary controls, which would stop the user starting the service — and the Status Page is the other place a key can be saved.
- **Default branch is `main`, not `master`.** Keep `main` in every workflow when resyncing them from the template. - **Default branch is `main`, not `master`.** Keep `main` in every workflow when resyncing them from the template.
+6 -4
View File
@@ -24,12 +24,12 @@ Forked from [Start9-Community/ppq-private-mode-startos](https://github.com/Start
- **DNS-rebinding hardening (default on).** StartOS now sets `PPQ_ALLOWED_HOSTS` automatically to the exact hostnames the API interface is served on (LAN IP, `.local`, private/public domains, the bridge address and loopback). A hostile web page can no longer reach the proxy as "same-origin" or overwrite the stored API key via `/setup/api-key`. The list is resolved reactively, so adding a domain later is picked up on the next restart. - **DNS-rebinding hardening (default on).** StartOS now sets `PPQ_ALLOWED_HOSTS` automatically to the exact hostnames the API interface is served on (LAN IP, `.local`, private/public domains, the bridge address and loopback). A hostile web page can no longer reach the proxy as "same-origin" or overwrite the stored API key via `/setup/api-key`. The list is resolved reactively, so adding a domain later is picked up on the next restart.
- **New action — Service-to-Service URL.** Resolves the internal LXC-bridge address and prints the `http://<bridge-ip>:<port>/v1` base URL that Open WebUI (or any service container on this same StartOS server) should dial — plain HTTP, no TLS or cert handling. This is what an on-box client must use instead of the LAN `https://` address, which fails certificate validation inside another container's runtime. - **New action — Service-to-Service URL.** Resolves the internal LXC-bridge address and prints the `http://<bridge-ip>:<port>/v1` base URL that Open WebUI (or any service container on this same StartOS server) should dial — plain HTTP, no TLS or cert handling. This is what an on-box client must use instead of the LAN `https://` address, which fails certificate validation inside another container's runtime.
- **Key validation matches upstream.** `configureApiKey` uses the exact same API-key shape check as upstream v0.6.0 (`^sk-[A-Za-z0-9]{16,64}$`), so a key accepted in StartOS is never rejected later by the proxy itself. - **Key validation matches upstream.** `configureApiKey` uses the exact same API-key shape check as upstream v0.6.0 (`^sk-[A-Za-z0-9]{16,64}$`), so a key accepted in StartOS is never rejected later by the proxy itself.
- **No glוןouble restart on configure.** The action only writes settings that actually changed (both `debug` and the API key are compared against the stored value first), so toggling logging or replacing the key restarts the service once — and only when something really changed. - **No double restart on configure.** The action only writes settings that actually changed (both `debug` and the API key are compared against the stored value first), so toggling logging or replacing the key restarts the service once — and only when something really changed.
- **Stable consumer contract.** `startos/utils.ts` exports `apiHostId` (`'main'`) and `apiPort` (`8787`) for dependents to import, mirroring the pattern Open WebUI already uses for its other AI backends. - **Stable consumer contract.** `startos/utils.ts` exports `apiHostId` (`'main'`) and `apiPort` (`8787`) for dependents to import, mirroring the pattern Open WebUI already uses for its other AI backends.
- **Docs.** `README.md` and `instructions.md` document the same-server / Open WebUI connection flow and updated models. - **Docs.** `README.md` and `instructions.md` document the same-server / Open WebUI connection flow and updated models.
- **Toolchain rebased onto upstream's SDK migration.** This fork builds with start-sdk 3.1.0: file models use `z.looseObject`, the manifest and init take an `sdk.Dependencies.of()` builder, and the toolchain scripts and devDependencies come from the SDK rather than `package.json`. The container is rebuilt on Node.js 22.23.4 for its October 2026 security release.
Version: `0.6.0:4`, built with SDK 2.0.9. Version: `0.6.0:6`, built with SDK 3.1.0.
--- ---
## Table of Contents ## Table of Contents
@@ -141,6 +141,7 @@ Sets the API key and the verbose-logging switch.
- **Cost:** the service restarts, since the proxy reads its config at start. - **Cost:** the service restarts, since the proxy reads its config at start.
- **Repeat safety:** idempotent. **Leaving the key blank keeps the existing one** rather than clearing it, so the action can be used to toggle logging without re-entering the key. - **Repeat safety:** idempotent. **Leaving the key blank keeps the existing one** rather than clearing it, so the action can be used to toggle logging without re-entering the key.
- **The key is never echoed back into the form.** The logging toggle is pre-filled; the key is not. - **The key is never echoed back into the form.** The logging toggle is pre-filled; the key is not.
- **Verbose logging** adds model information for accepted chat requests and logs OpenAI stream errors. Error messages may include sensitive content, even when verbose logging is off.
- **The key's shape is checked before it is written**, with the exact same pattern upstream v0.6.0 uses (`^sk-[A-Za-z0-9]{16,64}$`) — so a key accepted here is never rejected later by the proxy's own status-page endpoint. - **The key's shape is checked before it is written**, with the exact same pattern upstream v0.6.0 uses (`^sk-[A-Za-z0-9]{16,64}$`) — so a key accepted here is never rejected later by the proxy's own status-page endpoint.
- **Only changed settings are written.** Each value (`debug`, `apiKey`) is compared against the stored value first; nothing is written when it did not change, so no spurious restarts. - **Only changed settings are written.** Each value (`debug`, `apiKey`) is compared against the stored value first; nothing is written when it did not change, so no spurious restarts.
@@ -197,6 +198,7 @@ A restored instance comes back with the same key and works immediately, since no
8. **Same-server clients must use the bridge address, not the LAN `https://` URL** — see [Network Access and Interfaces](#network-access-and-interfaces). 8. **Same-server clients must use the bridge address, not the LAN `https://` URL** — see [Network Access and Interfaces](#network-access-and-interfaces).
9. **Known SDK listener warning (accepted).** `main` reads the files reactively with `.const()` — necessary so a key saved on the Status Page clears the setup task. That hits the known Start9 SDK pattern around `FileHelper.produce` that can emit a cosmetic `MaxListenersExceededWarning` (start9labs/start-technologies#3182). It is library-side and cosmetic; the reactive reads are required, so we deliberately do not "fix" it. 9. **Known SDK listener warning (accepted).** `main` reads the files reactively with `.const()` — necessary so a key saved on the Status Page clears the setup task. That hits the known Start9 SDK pattern around `FileHelper.produce` that can emit a cosmetic `MaxListenersExceededWarning` (start9labs/start-technologies#3182). It is library-side and cosmetic; the reactive reads are required, so we deliberately do not "fix" it.
10. **Upstream request bodies are unbounded (accepted, documented).** Upstream v0.6.0 does not cap HTTP request-body size, so a client that can reach the API could spend memory with very large POSTs (a potential DoS). This is upstream code — this wrapper cannot fix it without forking the proxy — so the mitigation is to keep the API interface private (LAN/VPN/Tor) and never expose it on the public internet. The interface is unauthenticated anyway (see #3), so it should never be publicly reachable. 10. **Upstream request bodies are unbounded (accepted, documented).** Upstream v0.6.0 does not cap HTTP request-body size, so a client that can reach the API could spend memory with very large POSTs (a potential DoS). This is upstream code — this wrapper cannot fix it without forking the proxy — so the mitigation is to keep the API interface private (LAN/VPN/Tor) and never expose it on the public internet. The interface is unauthenticated anyway (see #3), so it should never be publicly reachable.
11. **Upstream logs error messages unsanitized.** A `JSON.parse` failure quotes an excerpt of the request body, and caught errors are logged regardless of the Verbose Logging switch — so logs can contain prompt content. Review logs before sharing them.
--- ---
@@ -236,4 +238,4 @@ health_checks:
- proxy # the port opens only after enclave attestation succeeds - proxy # the port opens only after enclave attestation succeeds
``` ```
**Stable contract for dependents:** `startos/utils.ts` exports `apiHostId` (`'main'`) and `apiPort` (`8787`) — the values a package like Open WebUI imports rather than hardcoding (`sdk.host.getBridgeAddress(effects, { packageId: 'ppq-private-mode', hostId: apiHostId, internalPort: apiPort, ssl: false })`). **Stable contract for dependents:** `startos/utils.ts` exports `apiHostId` (`'main'`) and `apiPort` (`8787`) — the values a package like Open WebUI imports rather than hardcoding (`sdk.host.getBridgeAddress(effects, { packageId: 'ppq-private-mode', hostId: apiHostId, internalPort: apiPort, ssl: false })`).
+10 -29
View File
@@ -6,7 +6,7 @@
"": { "": {
"name": "ppq-private-mode-startos", "name": "ppq-private-mode-startos",
"dependencies": { "dependencies": {
"@start9labs/start-sdk": "3.0.3" "@start9labs/start-sdk": "3.1.0"
} }
}, },
"node_modules/@eslint-community/eslint-utils": { "node_modules/@eslint-community/eslint-utils": {
@@ -250,9 +250,9 @@
"license": "MIT" "license": "MIT"
}, },
"node_modules/@start9labs/start-sdk": { "node_modules/@start9labs/start-sdk": {
"version": "3.0.3", "version": "3.1.0",
"resolved": "https://registry.npmjs.org/@start9labs/start-sdk/-/start-sdk-3.0.3.tgz", "resolved": "https://registry.npmjs.org/@start9labs/start-sdk/-/start-sdk-3.1.0.tgz",
"integrity": "sha512-vnysNRhlEeUIlPyYq+505CSDbCIpODtydK07YXNVAdNiMC8sLclKpqNVVdwQ/a3fhy+yCsgYmKhHzPGAkBdeJA==", "integrity": "sha512-JyTlm5S+eYg+hyh78N9buq9I091Wcp0Thg7Tm0CCfKJhCCz8KGVTa9OyS57YY/bsBNeEME4zTCQ5bybEpwyV6A==",
"bundleDependencies": [ "bundleDependencies": [
"@start9labs/start-core" "@start9labs/start-core"
], ],
@@ -275,8 +275,7 @@
"typescript": "^6.0.3", "typescript": "^6.0.3",
"typescript-eslint": "^8.61.0", "typescript-eslint": "^8.61.0",
"yaml": "^2.8.3", "yaml": "^2.8.3",
"zod": "4.4.3", "zod": "4.6.7"
"zod-deep-partial": "^1.2.0"
} }
}, },
"node_modules/@start9labs/start-sdk/node_modules/@start9labs/start-core": { "node_modules/@start9labs/start-sdk/node_modules/@start9labs/start-core": {
@@ -290,8 +289,7 @@
"isomorphic-fetch": "^3.0.0", "isomorphic-fetch": "^3.0.0",
"mime": "^4.1.0", "mime": "^4.1.0",
"yaml": "^2.8.3", "yaml": "^2.8.3",
"zod": "4.4.3", "zod": "4.6.7"
"zod-deep-partial": "^1.4.4"
} }
}, },
"node_modules/@start9labs/start-sdk/node_modules/@start9labs/start-core/node_modules/@iarna/toml": { "node_modules/@start9labs/start-sdk/node_modules/@start9labs/start-core/node_modules/@iarna/toml": {
@@ -421,21 +419,13 @@
} }
}, },
"node_modules/@start9labs/start-sdk/node_modules/@start9labs/start-core/node_modules/zod": { "node_modules/@start9labs/start-sdk/node_modules/@start9labs/start-core/node_modules/zod": {
"version": "4.4.3", "version": "4.6.7",
"inBundle": true, "inBundle": true,
"license": "MIT", "license": "MIT",
"funding": { "funding": {
"url": "https://github.com/sponsors/colinhacks" "url": "https://github.com/sponsors/colinhacks"
} }
}, },
"node_modules/@start9labs/start-sdk/node_modules/@start9labs/start-core/node_modules/zod-deep-partial": {
"version": "1.4.4",
"inBundle": true,
"license": "MIT",
"peerDependencies": {
"zod": "^4.1.13"
}
},
"node_modules/@types/estree": { "node_modules/@types/estree": {
"version": "1.0.9", "version": "1.0.9",
"resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz", "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
@@ -1866,22 +1856,13 @@
} }
}, },
"node_modules/zod": { "node_modules/zod": {
"version": "4.4.3", "version": "4.6.7",
"resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz", "resolved": "https://registry.npmjs.org/zod/-/zod-4.6.7.tgz",
"integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==", "integrity": "sha512-g8W2D2kU6a8untc053fX1uVBKzM7yqAxW/3zwk83+6RyF2+SKOuV+c0wBDhUwzV1PaGapmZH+rmcUzPf+3CGwg==",
"license": "MIT", "license": "MIT",
"funding": { "funding": {
"url": "https://github.com/sponsors/colinhacks" "url": "https://github.com/sponsors/colinhacks"
} }
},
"node_modules/zod-deep-partial": {
"version": "1.4.4",
"resolved": "https://registry.npmjs.org/zod-deep-partial/-/zod-deep-partial-1.4.4.tgz",
"integrity": "sha512-aWkPl7hVStgE01WzbbSxCgX4O+sSpgt8JOjvFUtMTF75VgL6MhWQbiZi+AWGN85SfSTtI9gsOtL1vInoqfDVaA==",
"license": "MIT",
"peerDependencies": {
"zod": "^4.1.13"
}
} }
} }
} }
+1 -1
View File
@@ -1,7 +1,7 @@
{ {
"name": "ppq-private-mode-startos", "name": "ppq-private-mode-startos",
"dependencies": { "dependencies": {
"@start9labs/start-sdk": "3.0.3" "@start9labs/start-sdk": "3.1.0"
}, },
"overrides": { "overrides": {
"@start9labs/start-sdk": "$@start9labs/start-sdk" "@start9labs/start-sdk": "$@start9labs/start-sdk"
+1
View File
@@ -59,6 +59,7 @@ export const showServiceUrl = sdk.Action.withoutInput(
copyable: true, copyable: true,
qr: false, qr: false,
masked: false, masked: false,
launchable: false,
}, },
} }
}, },
+6 -6
View File
@@ -2,18 +2,18 @@ import { IMPOSSIBLE, VersionInfo } from '@start9labs/start-sdk'
export const current = VersionInfo.of({ export const current = VersionInfo.of({
// Tracks upstream ppq-private-mode-proxy (package.json version). // Tracks upstream ppq-private-mode-proxy (package.json version).
version: '0.6.0:5', version: '0.6.0:6',
releaseNotes: { releaseNotes: {
en_US: en_US:
'Rebased onto upstream start-sdk 3.0.3. The Verbose Logging description now states that error messages may include sensitive content, even when verbose logging is off.', 'Updates Node.js to 22.23.4 with security fixes and moves to start-sdk 3.1.0.',
es_ES: es_ES:
'Actualizado a start-sdk 3.0.3. La descripción de Registro detallado ahora indica que los mensajes de error pueden incluir contenido sensible, incluso con el registro desactivado.', 'Actualiza Node.js a 22.23.4 con correcciones de seguridad y pasa a start-sdk 3.1.0.',
de_DE: de_DE:
'Auf start-sdk 3.0.3 umgestellt. Die Beschreibung von „Ausführliche Protokollierung“ weist nun darauf hin, dass Fehlermeldungen sensiblen Inhalt enthalten können, auch wenn die Protokollierung aus ist.', 'Aktualisiert Node.js auf 22.23.4 mit Sicherheitskorrekturen und wechselt zu start-sdk 3.1.0.',
pl_PL: pl_PL:
'Przejście na start-sdk 3.0.3. Opis opcji Szczegółowe logowanie informuje teraz, że komunikaty błędów mogą zawierać poufne treści, nawet gdy logowanie jest wyłączone.', 'Aktualizuje Node.js do wersji 22.23.4 z poprawkami bezpieczeństwa i przechodzi na start-sdk 3.1.0.',
fr_FR: fr_FR:
"Passage à start-sdk 3.0.3. La description de la Journalisation détaillée indique désormais que les messages d'erreur peuvent contenir du contenu sensible, même lorsque la journalisation est désactivée.", 'Met à jour Node.js vers 22.23.4 avec des correctifs de sécurité et passe à start-sdk 3.1.0.',
}, },
migrations: { migrations: {
up: async ({ effects }) => {}, up: async ({ effects }) => {},