adopt 0.4's persistent key store and browser setup form

The earlier bump took 0.4.1 for its model catalog and status page but
left PPQ_DATA_DIR unset, which disabled the key form the release exists
to add. Enable it, and let the proxy own the key outright.

PPQ_API_KEY is no longer passed. The volume's `proxy/` subpath mounts at
/data as PPQ_DATA_DIR, so upstream's key store is the single source of
truth: the Status Page and the Configure PPQ API Key action write the
same config.json, and there is no StartOS-side copy to revert what the
browser saved. A chown oneshot hands /data to the image's `node` user so
the page can write there.

Verbose Logging moves to store.json outside the mount, because upstream
rewrites config.json wholesale when a key is saved and would drop it.

main.ts watches config.json — upstream loads it once at startup, so the
watch is what makes the action take effect: the write restarts the
daemon, which reloads the file. A key saved on the page applies
immediately and converges through the same restart.

The task drops from critical to important. A critical task suspends
every other control, so it would have left the user unable to start the
service and reach the page's own form — and with PPQ_DATA_DIR set the
proxy no longer exits keyless; it attests, serves the page, and answers
401 until a key exists. main.ts clears the task when a key appears,
since saving on the page never touches the action that would clear it.

The action's key field is now validated against upstream's own
^sk-[A-Za-z0-9]{16,64}$ shape and no longer refuses a blank submission,
a key having become optional.
This commit is contained in:
helix-nine committed 2026-08-12 09:58:35 -06:00
1 parent 42b2841945
commit 8397c7b1eb
10 files changed
+213 -140

No files matched your search

+15 -13
View File
@@ -1,5 +1,6 @@
import { sdk } from '../sdk'
import { configJson } from '../fileModels/config.json'
import { storeJson } from '../fileModels/store.json'
import { i18n } from '../i18n'
const { InputSpec, Value } = sdk
@@ -8,12 +9,21 @@ const inputSpec = InputSpec.of({
apiKey: Value.text({
name: i18n('PPQ.AI API Key'),
description: i18n(
'Your API key from ppq.ai (Settings → API Keys). Leave blank to keep the key already saved.',
'Your API key from ppq.ai (Settings → API Keys). Leave blank to keep the key already saved, or to set one later from the Status Page.',
),
required: false,
default: null,
masked: true,
placeholder: 'sk-...',
// Upstream's own shape check, applied here too — the Status Page rejects a
// malformed key outright, but a key written straight to config.json would
// only surface as a 401 on the first request.
patterns: [
{
regex: '^sk-[A-Za-z0-9]{16,64}$',
description: i18n('A PPQ.AI key starts with "sk-".'),
},
],
}),
debug: Value.toggle({
name: i18n('Verbose Logging'),
@@ -42,21 +52,13 @@ export const configureApiKey = sdk.Action.withInput(
// Prefill: the API key is never echoed back into the form.
async ({ effects }) => ({
debug: (await configJson.read((c) => c.debug).once()) ?? false,
debug: (await storeJson.read((s) => s.debug).once()) ?? false,
}),
async ({ effects, input }) => {
const apiKey =
(input.apiKey ?? '').trim() ||
(await configJson.read((c) => c.apiKey).once())
if (!apiKey) {
throw new Error(
i18n(
'An API key is required. Create one at ppq.ai under Settings → API Keys.',
),
)
}
await storeJson.merge(effects, { debug: input.debug })
await configJson.merge(effects, { apiKey, debug: input.debug })
const apiKey = (input.apiKey ?? '').trim()
if (apiKey) await configJson.merge(effects, { apiKey })
},
)
+5 -5
View File
@@ -1,15 +1,15 @@
import { FileHelper, z } from '@start9labs/start-sdk'
import { sdk } from '../sdk'
// Package-owned settings file on the main volume. The upstream proxy is
// configured purely through environment variables; main.ts bridges these
// values into the daemon's env.
// Upstream's own persistent config, at <PPQ_DATA_DIR>/config.json. The proxy
// loads the key from here at startup and rewrites the whole file when one is
// saved from the status page, so this shape must stay exactly upstream's and
// nothing else may live in it — see fileModels/store.json.ts.
const shape = z.object({
apiKey: z.string().optional().catch(undefined),
debug: z.boolean().catch(false),
})
export const configJson = FileHelper.json(
{ base: sdk.volumes.main, subpath: 'config.json' },
{ base: sdk.volumes.main, subpath: 'proxy/config.json' },
shape,
)
+13
View File
@@ -0,0 +1,13 @@
import { FileHelper, z } from '@start9labs/start-sdk'
import { sdk } from '../sdk'
// Package-owned settings, kept outside the mounted PPQ_DATA_DIR subtree so the
// proxy neither sees them nor overwrites them.
const shape = z.object({
debug: z.boolean().catch(false),
})
export const storeJson = FileHelper.json(
{ base: sdk.volumes.main, subpath: 'store.json' },
shape,
)
+7 -7
View File
@@ -13,14 +13,14 @@ const dict = {
'Point any OpenAI or Anthropic SDK client at this URL to use PPQ private (TEE) models with end-to-end encryption': 7,
// actions/configureApiKey.ts
'PPQ.AI API Key': 8,
'Your API key from ppq.ai (Settings → API Keys). Leave blank to keep the key already saved.': 9,
'Verbose Logging': 10,
'Log every request the proxy handles. Useful for troubleshooting.': 11,
'Configure PPQ API Key': 12,
'Set the PPQ.AI API key the proxy uses to authenticate. Requests are billed to this key.': 13,
'An API key is required. Create one at ppq.ai under Settings → API Keys.': 14,
'Your API key from ppq.ai (Settings → API Keys). Leave blank to keep the key already saved, or to set one later from the Status Page.': 9,
'A PPQ.AI key starts with "sk-".': 10,
'Verbose Logging': 11,
'Log every request the proxy handles. Useful for troubleshooting.': 12,
'Configure PPQ API Key': 13,
'Set the PPQ.AI API key the proxy uses to authenticate. Requests are billed to this key.': 14,
// init/taskConfigureApiKey.ts
'Add your PPQ.AI API key to start the proxy': 15,
'Add your PPQ.AI API key here, or start the service and save one on the Status Page': 15,
} as const
/**
+28 -28
View File
@@ -11,13 +11,13 @@ export default {
6: 'API compatible con OpenAI',
7: 'Apunta cualquier cliente SDK de OpenAI o Anthropic a esta URL para usar los modelos privados (TEE) de PPQ con cifrado de extremo a extremo',
8: 'Clave API de PPQ.AI',
9: 'Tu clave API de ppq.ai (Ajustes → Claves API). Déjalo en blanco para conservar la clave ya guardada.',
10: 'Registro detallado',
11: 'Registra cada solicitud que maneja el proxy. Útil para diagnosticar problemas.',
12: 'Configurar clave API de PPQ',
13: 'Establece la clave API de PPQ.AI que el proxy usa para autenticarse. Las solicitudes se facturan a esta clave.',
14: 'Se requiere una clave API. Crea una en ppq.ai en Ajustes → Claves API.',
15: 'Añade tu clave API de PPQ.AI para iniciar el proxy',
9: 'Tu clave API de ppq.ai (Ajustes → Claves API). Déjalo en blanco para conservar la clave ya guardada, o para configurar una más tarde desde la Página de estado.',
10: 'Una clave de PPQ.AI empieza por «sk-».',
11: 'Registro detallado',
12: 'Registra cada solicitud que maneja el proxy. Útil para diagnosticar problemas.',
13: 'Configurar clave API de PPQ',
14: 'Establece la clave API de PPQ.AI que el proxy usa para autenticarse. Las solicitudes se facturan a esta clave.',
15: 'Añade aquí tu clave API de PPQ.AI, o inicia el servicio y guárdala en la Página de estado',
},
de_DE: {
0: 'Starte PPQ Private Mode!',
@@ -29,13 +29,13 @@ export default {
6: 'OpenAI-kompatible API',
7: 'Verbinde jeden OpenAI- oder Anthropic-SDK-Client mit dieser URL, um die privaten (TEE) Modelle von PPQ mit Ende-zu-Ende-Verschlüsselung zu nutzen',
8: 'PPQ.AI-API-Schlüssel',
9: 'Dein API-Schlüssel von ppq.ai (Einstellungen → API-Schlüssel). Leer lassen, um den bereits gespeicherten Schlüssel zu behalten.',
10: 'Ausführliche Protokollierung',
11: 'Protokolliert jede Anfrage, die der Proxy verarbeitet. Nützlich zur Fehlersuche.',
12: 'PPQ-API-Schlüssel konfigurieren',
13: 'Lege den PPQ.AI-API-Schlüssel fest, mit dem sich der Proxy authentifiziert. Anfragen werden diesem Schlüssel in Rechnung gestellt.',
14: 'Ein API-Schlüssel ist erforderlich. Erstelle einen auf ppq.ai unter Einstellungen → API-Schlüssel.',
15: 'Füge deinen PPQ.AI-API-Schlüssel hinzu, um den Proxy zu starten',
9: 'Dein API-Schlüssel von ppq.ai (Einstellungen → API-Schlüssel). Leer lassen, um den bereits gespeicherten Schlüssel zu behalten oder später auf der Statusseite einen festzulegen.',
10: 'Ein PPQ.AI-Schlüssel beginnt mit „sk-“.',
11: 'Ausführliche Protokollierung',
12: 'Protokolliert jede Anfrage, die der Proxy verarbeitet. Nützlich zur Fehlersuche.',
13: 'PPQ-API-Schlüssel konfigurieren',
14: 'Lege den PPQ.AI-API-Schlüssel fest, mit dem sich der Proxy authentifiziert. Anfragen werden diesem Schlüssel in Rechnung gestellt.',
15: 'Füge deinen PPQ.AI-API-Schlüssel hier hinzu, oder starte den Dienst und speichere ihn auf der Statusseite',
},
pl_PL: {
0: 'Uruchamianie PPQ Private Mode!',
@@ -47,13 +47,13 @@ export default {
6: 'API zgodne z OpenAI',
7: 'Skieruj dowolnego klienta SDK OpenAI lub Anthropic na ten URL, aby korzystać z prywatnych modeli (TEE) PPQ z szyfrowaniem end-to-end',
8: 'Klucz API PPQ.AI',
9: 'Twój klucz API z ppq.ai (Ustawienia → Klucze API). Pozostaw puste, aby zachować już zapisany klucz.',
10: 'Szczegółowe logowanie',
11: 'Rejestruje każde żądanie obsługiwane przez proxy. Przydatne przy rozwiązywaniu problemów.',
12: 'Skonfiguruj klucz API PPQ',
13: 'Ustaw klucz API PPQ.AI, którym proxy się uwierzytelnia. Żądania są rozliczane na ten klucz.',
14: 'Wymagany jest klucz API. Utwórz go na ppq.ai w Ustawienia → Klucze API.',
15: 'Dodaj swój klucz API PPQ.AI, aby uruchomić proxy',
9: 'Twój klucz API z ppq.ai (Ustawienia → Klucze API). Pozostaw puste, aby zachować już zapisany klucz lub ustawić go później na Stronie stanu.',
10: 'Klucz PPQ.AI zaczyna się od „sk-”.',
11: 'Szczegółowe logowanie',
12: 'Rejestruje każde żądanie obsługiwane przez proxy. Przydatne przy rozwiązywaniu problemów.',
13: 'Skonfiguruj klucz API PPQ',
14: 'Ustaw klucz API PPQ.AI, którym proxy się uwierzytelnia. Żądania są rozliczane na ten klucz.',
15: 'Dodaj tutaj swój klucz API PPQ.AI albo uruchom usługę i zapisz go na Stronie stanu',
},
fr_FR: {
0: 'Démarrage de PPQ Private Mode !',
@@ -65,12 +65,12 @@ export default {
6: 'API compatible OpenAI',
7: "Pointez n'importe quel client SDK OpenAI ou Anthropic vers cette URL pour utiliser les modèles privés (TEE) de PPQ avec un chiffrement de bout en bout",
8: 'Clé API PPQ.AI',
9: 'Votre clé API de ppq.ai (Paramètres → Clés API). Laissez vide pour conserver la clé déjà enregistrée.',
10: 'Journalisation détaillée',
11: 'Journalise chaque requête traitée par le proxy. Utile pour le dépannage.',
12: 'Configurer la clé API PPQ',
13: "Définissez la clé API PPQ.AI avec laquelle le proxy s'authentifie. Les requêtes sont facturées sur cette clé.",
14: 'Une clé API est requise. Créez-en une sur ppq.ai dans Paramètres → Clés API.',
15: 'Ajoutez votre clé API PPQ.AI pour démarrer le proxy',
9: "Votre clé API de ppq.ai (Paramètres → Clés API). Laissez vide pour conserver la clé déjà enregistrée, ou pour en définir une plus tard depuis la Page d'état.",
10: 'Une clé PPQ.AI commence par « sk- ».',
11: 'Journalisation détaillée',
12: 'Journalise chaque requête traitée par le proxy. Utile pour le dépannage.',
13: 'Configurer la clé API PPQ',
14: "Définissez la clé API PPQ.AI avec laquelle le proxy s'authentifie. Les requêtes sont facturées sur cette clé.",
15: "Ajoutez ici votre clé API PPQ.AI, ou démarrez le service et enregistrez-la sur la Page d'état",
},
} satisfies Record<string, LangDict>
+8 -4
View File
@@ -3,14 +3,18 @@ import { configJson } from '../fileModels/config.json'
import { configureApiKey } from '../actions/configureApiKey'
import { i18n } from '../i18n'
// The proxy cannot start without a PPQ.AI API key, so a critical task blocks
// startup until the user provides one.
// The proxy starts and serves its Status Page without a key, answering 401 to
// inference requests until one is set. So this prompt is important rather than
// critical: a critical task suspends every other control, which would leave the
// user unable to start the service and reach the Status Page's own key form.
export const taskConfigureApiKey = sdk.setupOnInit(async (effects) => {
const apiKey = await configJson.read((c) => c.apiKey).once()
if (!apiKey) {
await sdk.action.createOwnTask(effects, configureApiKey, 'critical', {
reason: i18n('Add your PPQ.AI API key to start the proxy'),
await sdk.action.createOwnTask(effects, configureApiKey, 'important', {
reason: i18n(
'Add your PPQ.AI API key here, or start the service and save one on the Status Page',
),
})
}
})
+64 -38
View File
@@ -1,49 +1,75 @@
import { i18n } from './i18n'
import { sdk } from './sdk'
import { apiPort } from './utils'
import { manifest } from './manifest'
import { apiPort, dataDir } from './utils'
import { configureApiKey } from './actions/configureApiKey'
import { configJson } from './fileModels/config.json'
import { storeJson } from './fileModels/store.json'
export const main = sdk.setupMain(async ({ effects }) => {
console.info(i18n('Starting PPQ Private Mode!'))
// Read reactively so the daemon restarts when the user changes settings.
// The proxy reads config.json once at startup, so watching it is what makes a
// key saved by the Configure PPQ API Key action take effect: the write
// restarts the daemon, which reloads the file. PPQ_API_KEY is left unset so
// the proxy's own key store is the only thing that owns the key.
const apiKey = await configJson.read((c) => c.apiKey).const(effects)
const debug = await configJson.read((c) => c.debug).const(effects)
const debug = await storeJson.read((s) => s.debug).const(effects)
return sdk.Daemons.of(effects).addDaemon('proxy', {
// The proxy is stateless and fully configured via env — the 'main' volume
// (config.json, read host-side by the SDK) is never mounted into the
// container.
subcontainer: sdk.SubContainer.of(
effects,
{ imageId: 'proxy' },
null,
'proxy-sub',
),
exec: {
command: ['node', '/app/dist/bin/server.js'],
env: {
PPQ_API_KEY: apiKey ?? '',
HOST: '0.0.0.0',
PORT: apiPort.toString(),
DEBUG: debug ? 'true' : 'false',
// Running the action clears its own task, but a key saved on the Status Page
// never touches the action — so clear it here, on the restart that same save
// triggers. Otherwise StartOS keeps asking for a key the user already set.
if (apiKey) {
await sdk.action.clearTask(effects, `${manifest.id}:${configureApiKey.id}`)
}
const subcontainer = sdk.SubContainer.of(
effects,
{ imageId: 'proxy' },
sdk.Mounts.of().mountVolume({
volumeId: 'main',
subpath: 'proxy',
mountpoint: dataDir,
readonly: false,
}),
'proxy-sub',
)
return sdk.Daemons.of(effects)
.addOneshot('chown', {
subcontainer,
exec: {
command: ['chown', '-R', 'node:node', dataDir],
user: 'root',
},
},
// The proxy only binds its port after remote attestation of the enclave
// succeeds, so a listening port means the encrypted channel is verified
// and ready.
ready: {
display: i18n('Encrypted Proxy'),
fn: () =>
sdk.healthCheck.checkPortListening(effects, apiPort, {
successMessage: i18n(
'The proxy is ready — enclave attestation verified',
),
errorMessage: i18n(
'The proxy is not ready (enclave attestation pending)',
),
}),
},
requires: [],
})
requires: [],
})
.addDaemon('proxy', {
subcontainer,
exec: {
command: ['node', '/app/dist/bin/server.js'],
env: {
PPQ_DATA_DIR: dataDir,
HOST: '0.0.0.0',
PORT: apiPort.toString(),
DEBUG: debug ? 'true' : 'false',
},
},
// The proxy only binds its port after remote attestation of the enclave
// succeeds, so a listening port means the encrypted channel is verified
// and ready.
ready: {
display: i18n('Encrypted Proxy'),
fn: () =>
sdk.healthCheck.checkPortListening(effects, apiPort, {
successMessage: i18n(
'The proxy is ready — enclave attestation verified',
),
errorMessage: i18n(
'The proxy is not ready (enclave attestation pending)',
),
}),
},
requires: ['chown'],
})
})
+4
View File
@@ -2,3 +2,7 @@
// Port the proxy listens on inside the container (upstream default).
export const apiPort = 8787
// Upstream's PPQ_DATA_DIR inside the container: where it persists the API key
// saved from the status page.
export const dataDir = '/data'