diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 6e1a7e4..b8a32f4 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -4,7 +4,7 @@ on: workflow_dispatch: pull_request: paths-ignore: ['*.md'] - branches: ['master'] + branches: ['main'] concurrency: group: ${{ github.workflow }}-${{ github.head_ref || github.ref }} @@ -14,6 +14,4 @@ jobs: build: if: github.event.pull_request.draft == false uses: Start9Labs/start-technologies/.github/workflows/build.yml@master - # with: - # FREE_DISK_SPACE: true # No DEV_KEY — a PR build doesn't publish, so it doesn't need the signing key. diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 9defaba..6dcef4a 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -6,23 +6,9 @@ on: - 'v*.*' jobs: - guard: - runs-on: ubuntu-latest - outputs: - id: ${{ steps.read.outputs.id }} - steps: - - uses: actions/checkout@v4 - - id: read - run: | - id="$(awk -F"'" '/id:/ {print $2; exit}' startos/manifest/index.ts)" - echo "id=$id" >> "$GITHUB_OUTPUT" - release: - needs: guard - if: needs.guard.outputs.id != 'hello-world' uses: Start9Labs/start-technologies/.github/workflows/release.yml@master with: - # FREE_DISK_SPACE: true RELEASE_REGISTRY: ${{ vars.RELEASE_REGISTRY }} S3_S9PKS_BASE_URL: ${{ vars.S3_S9PKS_BASE_URL }} secrets: diff --git a/.github/workflows/tagAndRelease.yml b/.github/workflows/tagAndRelease.yml index 50858c3..c4031d3 100644 --- a/.github/workflows/tagAndRelease.yml +++ b/.github/workflows/tagAndRelease.yml @@ -2,7 +2,7 @@ name: Tag and Release on: push: - branches: ['master'] + branches: ['main'] paths-ignore: ['*.md'] concurrency: @@ -10,24 +10,10 @@ concurrency: cancel-in-progress: true jobs: - guard: - runs-on: ubuntu-latest - outputs: - id: ${{ steps.read.outputs.id }} - steps: - - uses: actions/checkout@v4 - - id: read - run: | - id="$(awk -F"'" '/id:/ {print $2; exit}' startos/manifest/index.ts)" - echo "id=$id" >> "$GITHUB_OUTPUT" - tag: - needs: guard - if: needs.guard.outputs.id != 'hello-world' uses: Start9Labs/start-technologies/.github/workflows/tagAndRelease.yml@master with: REFERENCE_REGISTRY: ${{ vars.REFERENCE_REGISTRY }} - # FREE_DISK_SPACE: true RELEASE_REGISTRY: ${{ vars.RELEASE_REGISTRY }} S3_S9PKS_BASE_URL: ${{ vars.S3_S9PKS_BASE_URL }} secrets: diff --git a/README.md b/README.md index e6d46b3..4c68871 100644 --- a/README.md +++ b/README.md @@ -46,44 +46,84 @@ Architectures: `x86_64`, `aarch64`. ## Volume and Data Layout -One volume, `main`, holding only `config.json` (the StartOS-managed settings -file containing the API key and logging preference), read and written by the -SDK on the host side. The proxy itself is stateless and the volume is **not** -mounted into the container — configuration reaches the daemon via environment -variables only. +One volume, `main`, split so the container sees only what it owns: + +| Host path | Container path | Written by | +| ------------------- | ------------------- | ------------------------------------------------ | +| `proxy/config.json` | `/data/config.json` | the proxy (Status Page) **and** the SDK (action) | +| `store.json` | not mounted | the SDK only | + +`proxy/` is mounted at `/data` as the proxy's `PPQ_DATA_DIR`, and `config.json` +inside it is upstream's own file — the proxy rewrites it wholesale when a key is +saved from the Status Page, so nothing of ours may live there. The Verbose +Logging setting therefore lives in `store.json`, outside the mount. + +A `chown` oneshot hands `/data` to the image's unprivileged `node` user before +the daemon starts, so the Status Page can write to it. ## Installation and First-Run Flow -On install, a critical task prompts for a PPQ.AI API key. The service cannot -start until the key is provided (upstream exits immediately without -`PPQ_API_KEY`). There is no other setup. +On install, an **important** (non-blocking) task prompts for a PPQ.AI API key. +There are two ways to satisfy it, and neither is required before starting: + +1. Run the **Configure PPQ API Key** action. +2. Start the service and save the key on the **Status Page**. + +The proxy runs without a key — it completes attestation, serves the Status Page, +and answers `401` to inference requests until one is set. The task is +deliberately not 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. ## Configuration Management -All upstream configuration is via environment variables; StartOS manages them -from `config.json`: +The API key is the proxy's to own. StartOS does **not** pass `PPQ_API_KEY`; +instead it points `PPQ_DATA_DIR` at the mounted volume so upstream's key store +is the single source of truth, written by either the action or the Status Page +and read from the same file by both. -- `PPQ_API_KEY` — set from the **Configure PPQ API Key** action -- `DEBUG` — set from the same action's Verbose Logging toggle +- `PPQ_DATA_DIR` — `/data`, enabling persistence and the Status Page's key form +- `DEBUG` — set from the action's Verbose Logging toggle, via `store.json` - `HOST` — fixed to `0.0.0.0` (container binding) -- `PORT` — fixed to `8787` +- `PORT` — fixed to 8787 - `PPQ_API_BASE` — not set (upstream default `https://api.ppq.ai`) -Changing settings restarts the daemon (values are read reactively). +The proxy loads `config.json` once at startup, so `main.ts` watches the file: +writing a key restarts the daemon, which reloads it. A key saved on the Status +Page takes effect immediately in the running proxy and then triggers that same +restart — brief, and it converges on the value just saved either way. ## Network Access and Interfaces -One interface, `api` (port 8787, HTTP): the upstream OpenAI-compatible API, -shown as a copyable connection string. Endpoints: `GET /health`, -`GET /v1/models`, `POST /v1/chat/completions` (OpenAI format), -`POST /v1/messages` (Anthropic format). Availability on LAN/Tor is decided by -the user from the interface panel. +Two interfaces on one HTTP host, port 8787, both served by the proxy: + +- **Status Page** (`ui`) — upstream's server-rendered page at `/`: attestation + state (enclave host and code fingerprint), API-key status, the private model + list, and client setup snippets. +- **OpenAI-Compatible API** (`api`) — the same origin, shown as a copyable + connection string for AI clients. Endpoints: `GET /health`, + `GET /v1/models`, `POST /v1/chat/completions` (OpenAI format), + `POST /v1/messages` (Anthropic format). + +Availability on LAN/Tor is decided by the user from the interface panel. + +**No endpoint is authenticated.** Upstream ships no auth on any route, so +whoever can reach the port can spend the user's PPQ.AI balance via +`/v1/chat/completions`, and — because this package sets `PPQ_DATA_DIR` — can +also replace the stored key via `POST /setup/api-key` +([upstream #23](https://github.com/PayPerQ/ppq-private-mode-proxy/issues/23)). +The billing exposure predates that endpoint and is inherent to the proxy; the +key-replacement one is enabled by our `PPQ_DATA_DIR` choice, and closes when +upstream's patch lands and this package bumps to it. `instructions.md` warns +the user to expose the interface accordingly. ## Actions (StartOS UI) -- **Configure PPQ API Key** (`configure-api-key`) — sets the PPQ.AI API key - (masked, never echoed back) and the Verbose Logging toggle. Available at any - service status. Also the target of the critical first-run task. +- **Configure PPQ API Key** (`configure-api-key`) — visible and enabled at any + service status. Inputs: the PPQ.AI API key (masked, validated against + upstream's `^sk-[A-Za-z0-9]{16,64}$` shape; left blank it keeps the key + already saved and is never echoed back into the form) and the Verbose Logging + toggle. No result output. Also the target of the first-run task. ## Backups and Restore @@ -108,16 +148,21 @@ None. 1. This service is a client-side encryption proxy, not a self-hosted model server: inference runs remotely in PPQ.AI's attested TEE enclaves, and a funded [PPQ.AI](https://ppq.ai) API key is required (pay-per-query). -2. The upstream OpenClaw-plugin mode is not packaged; only the standalone +2. Saving a key on the Status Page restarts the daemon a few seconds later. + The proxy applies the key immediately; the restart is StartOS reacting to + the same file write, and is what makes the **Configure PPQ API Key** action + work at all (upstream reads `config.json` only at startup). +3. The upstream OpenClaw-plugin mode is not packaged; only the standalone proxy runs on StartOS. -3. The bind address and port are fixed (`0.0.0.0:8787` inside the container); - upstream's `HOST`/`PORT`/`PPQ_API_BASE` variables are not user-configurable. +4. The bind address and port are fixed inside the container; upstream's + `HOST`/`PORT`/`PPQ_API_BASE` variables are not user-configurable. ## What Is Unchanged from Upstream - All API endpoints, request/response formats, and streaming behavior - The encryption and attestation flow (EHBP transport via the `tinfoil` client) - Model catalog and per-request `Authorization: Bearer` key override +- The status page rendered at `/`, its API-key form included ## Contributing @@ -131,12 +176,15 @@ See [AGENTS.md](AGENTS.md). package_id: ppq-private-mode architectures: [x86_64, aarch64] volumes: - main: /data + main: /data # subpath `proxy/` only; `store.json` stays host-side ports: - api: 8787 + main: 8787 # one host serving both interfaces +interfaces: + - ui + - api dependencies: none startos_managed_env_vars: - - PPQ_API_KEY + - PPQ_DATA_DIR - HOST - PORT - DEBUG diff --git a/TODO.md b/TODO.md deleted file mode 100644 index d287cc6..0000000 --- a/TODO.md +++ /dev/null @@ -1,9 +0,0 @@ -# TODO — remaining work before release - -- [x] Verified on StartOS 0.4.0 (aarch64, QEMU/HVF VM): sideload install, - critical first-run task, Configure PPQ API Key action, attestation-gated - health check, OpenAI chat completion through the exported TLS interface, - logs, stop/start persistence, uninstall, and backup/restore to a disk - target (service restores with its key, no re-prompt). -- [ ] Submit to the Community Registry (email submissions@start9.com with a - link to this repo). diff --git a/UPDATING.md b/UPDATING.md index 9425cd5..ac086d5 100644 --- a/UPDATING.md +++ b/UPDATING.md @@ -2,14 +2,15 @@ Upstream is [PayPerQ/ppq-private-mode-proxy](https://github.com/PayPerQ/ppq-private-mode-proxy), vendored as the `ppq-private-mode-proxy` git submodule and built from its own -`Dockerfile`. The package version tracks upstream's `package.json` version. +`Dockerfile`. The package version tracks upstream's `package.json` version, +which upstream tags as `v`. ## Determining the upstream version ```bash -git -C ppq-private-mode-proxy fetch origin -git -C ppq-private-mode-proxy log --oneline HEAD..origin/main # anything new? -jq -r .version ppq-private-mode-proxy/package.json # current pin +git -C ppq-private-mode-proxy fetch origin --tags +git -C ppq-private-mode-proxy describe --tags HEAD # current pin +git -C ppq-private-mode-proxy tag --sort=-v:refname | head # latest released ``` The packaged version lives in `startos/versions/current.ts` (`version: @@ -17,9 +18,14 @@ The packaged version lives in `startos/versions/current.ts` (`version: ## Applying the bump -1. Advance the submodule: `git -C ppq-private-mode-proxy checkout origin/main` -2. Update `version` in `startos/versions/current.ts` to the new upstream +1. Advance the submodule: `git -C ppq-private-mode-proxy checkout v` +2. Read the upstream diff (`git -C ppq-private-mode-proxy diff ..`) + for anything the package has to follow — new or renamed environment + variables, changed endpoints, a changed bind/attestation order (the health + check depends on the port being bound only after attestation), or a model + catalog change that the docs name. +3. Update `version` in `startos/versions/current.ts` to the new upstream `package.json` version with revision `:0` (bump only the revision for - packaging-only changes), and write release notes. -3. Rebuild and test: `make x86` (or `make arm`), install, verify attestation - completes and a `/v1/models` request succeeds. + packaging-only changes), and write release notes in every locale. +4. Rebuild and test: `make x86` (or `make arm`), install, verify attestation + completes, the Status Page loads, and a `/v1/models` request succeeds. diff --git a/instructions.md b/instructions.md index 36881a7..6afbf8c 100644 --- a/instructions.md +++ b/instructions.md @@ -5,21 +5,46 @@ - [Upstream proxy documentation](https://github.com/PayPerQ/ppq-private-mode-proxy) — endpoints, client examples, and how the encryption works - [PPQ.AI API docs](https://ppq.ai/api-docs) — creating an API key and funding your account +## What you get on StartOS + +A local endpoint your AI clients talk to instead of talking to a model provider +directly. Everything sent through it is encrypted on your server and only +decrypted inside an attested hardware enclave, so neither PPQ.AI nor the model +host can read your queries. + +Two interfaces share one address: + +- **Status Page** — a web page showing whether enclave attestation succeeded, + which private models are available, and how to point a client at the proxy. + It is also where you can save your API key. +- **OpenAI-Compatible API** — the same address, ready to copy into a client. + +The only thing the service stores is your PPQ.AI API key and the logging +setting. + ## Getting set up -1. When the service is installed, you will be prompted to run **Configure PPQ - API Key**. Paste an API key from [ppq.ai](https://ppq.ai) (create one under - **Settings → API Keys** and fund the account — usage is billed per query to - this key). -2. The service starts and performs a cryptographic attestation of the remote - enclave. The health check reports ready once attestation is verified — - usually within a few seconds. -3. Copy the **OpenAI-Compatible API** address from the service's interface - panel. That is the URL you point your AI clients at. +You need a funded API key from [ppq.ai](https://ppq.ai) — create one under +**Settings → API Keys**, since usage is billed per query to that key. You can +save it before or after starting the service; the proxy runs either way and +simply refuses inference requests until it has one. -## Using the proxy +1. Start the service. It performs a cryptographic attestation of the remote + enclave, which the health check reports as ready — usually within a few + seconds. +2. Open the **Status Page**, confirm attestation says _verified_, and paste your + key into the API key form. The proxy picks it up immediately, then restarts + once to persist it. +3. Copy the **OpenAI-Compatible API** address to point a client at it. -Point any OpenAI-compatible client at the interface address: +If you would rather not start the service first, run the **Configure PPQ API +Key** action instead of step 2 — it does the same thing from the Actions tab. + +## Using PPQ Private Mode + +### Connecting a client + +Point any OpenAI-compatible client at the API address: ``` POST /v1/chat/completions @@ -34,16 +59,27 @@ export ANTHROPIC_BASE_URL="" export ANTHROPIC_MODEL="private/glm-5-2" ``` -`GET /v1/models` lists the available private models. Every -request is encrypted on your server before it leaves and is only decrypted -inside the attested enclave — neither PPQ.AI nor the model host can read your -queries. +`GET /v1/models` lists the available private models, and the Status +Page shows the same list. Requests are billed to your saved API key by default. To bill a different PPQ.AI key per request, pass it as an `Authorization: Bearer` header. -If you need to change the key or turn on verbose logging later, run -**Configure PPQ API Key** again from the service's Actions. +### Replacing the key + +Either surface works, and both write the same place: **Replace key** on the +Status Page, or the **Configure PPQ API Key** action. The action is also where +you turn Verbose Logging on and off; leaving its key field blank keeps the key +you already saved. + +## Limitations + +**The proxy has no login of its own, so only expose it to people you trust.** +Anyone who can reach the address can send requests that are billed to your +PPQ.AI key, and can replace the stored key from the Status Page. On a LAN-only +address that means everyone on your network; if you enable a Tor or public +address, it means anyone with the address. Keeping it on the LAN, or on Tor with +the address kept private, is the safe default. Backups of this service include your saved API key, and restoring a backup restores it — keep that in mind when handling backup drives. diff --git a/ppq-private-mode-proxy b/ppq-private-mode-proxy index a6d0f81..3ba4ac9 160000 --- a/ppq-private-mode-proxy +++ b/ppq-private-mode-proxy @@ -1 +1 @@ -Subproject commit a6d0f8116bf58499e64dffa81136940f94db952d +Subproject commit 3ba4ac94316572cb124c6052004b1231c1a0e7c8 diff --git a/startos/actions/configureApiKey.ts b/startos/actions/configureApiKey.ts index 0ef1985..bb24778 100644 --- a/startos/actions/configureApiKey.ts +++ b/startos/actions/configureApiKey.ts @@ -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'), @@ -41,27 +51,14 @@ export const configureApiKey = sdk.Action.withInput( inputSpec, // Prefill: the API key is never echoed back into the form. - async ({ effects }) => { - const debug = await configJson - .read((c) => c.debug) - .once() - .catch(() => false) - return { debug: debug ?? false } - }, + async ({ effects }) => ({ + debug: (await storeJson.read((s) => s.debug).once()) ?? false, + }), async ({ effects, input }) => { - const existingKey = await configJson - .read((c) => c.apiKey) - .once() - .catch(() => undefined) + await storeJson.merge(effects, { debug: input.debug }) - const apiKey = (input.apiKey ?? '').trim() || existingKey - if (!apiKey) { - throw new Error( - i18n('An API key is required. Create one at ppq.ai under Settings → API Keys.'), - ) - } - - await configJson.merge(effects, { apiKey, debug: input.debug }) + const apiKey = (input.apiKey ?? '').trim() + if (apiKey) await configJson.merge(effects, { apiKey }) }, ) diff --git a/startos/fileModels/config.json.ts b/startos/fileModels/config.json.ts index ecd8040..f74024d 100644 --- a/startos/fileModels/config.json.ts +++ b/startos/fileModels/config.json.ts @@ -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 /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, ) diff --git a/startos/fileModels/store.json.ts b/startos/fileModels/store.json.ts new file mode 100644 index 0000000..eae28b0 --- /dev/null +++ b/startos/fileModels/store.json.ts @@ -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, +) diff --git a/startos/i18n/dictionaries/default.ts b/startos/i18n/dictionaries/default.ts index d8191be..caf3bf0 100644 --- a/startos/i18n/dictionaries/default.ts +++ b/startos/i18n/dictionaries/default.ts @@ -7,18 +7,20 @@ const dict = { 'The proxy is ready — enclave attestation verified': 2, 'The proxy is not ready (enclave attestation pending)': 3, // interfaces.ts - 'OpenAI-Compatible API': 4, - 'Point any OpenAI or Anthropic SDK client at this URL to use PPQ private (TEE) models with end-to-end encryption': 5, + 'Status Page': 4, + 'Enclave attestation state, the available private models, and client setup snippets': 5, + 'OpenAI-Compatible API': 6, + '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': 6, - 'Your API key from ppq.ai (Settings → API Keys). Leave blank to keep the key already saved.': 7, - 'Verbose Logging': 8, - 'Log every request the proxy handles. Useful for troubleshooting.': 9, - 'Configure PPQ API Key': 10, - 'Set the PPQ.AI API key the proxy uses to authenticate. Requests are billed to this key.': 11, - 'An API key is required. Create one at ppq.ai under Settings → API Keys.': 12, + 'PPQ.AI API Key': 8, + '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': 13, + 'Add your PPQ.AI API key here, or start the service and save one on the Status Page': 15, } as const /** diff --git a/startos/i18n/dictionaries/translations.ts b/startos/i18n/dictionaries/translations.ts index 39b6cbe..f1f8d66 100644 --- a/startos/i18n/dictionaries/translations.ts +++ b/startos/i18n/dictionaries/translations.ts @@ -6,63 +6,71 @@ export default { 1: 'Proxy cifrado', 2: 'El proxy está listo — atestación del enclave verificada', 3: 'El proxy no está listo (atestación del enclave pendiente)', - 4: 'API compatible con OpenAI', - 5: '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', - 6: 'Clave API de PPQ.AI', - 7: 'Tu clave API de ppq.ai (Ajustes → Claves API). Déjalo en blanco para conservar la clave ya guardada.', - 8: 'Registro detallado', - 9: 'Registra cada solicitud que maneja el proxy. Útil para diagnosticar problemas.', - 10: 'Configurar clave API de PPQ', - 11: 'Establece la clave API de PPQ.AI que el proxy usa para autenticarse. Las solicitudes se facturan a esta clave.', - 12: 'Se requiere una clave API. Crea una en ppq.ai en Ajustes → Claves API.', - 13: 'Añade tu clave API de PPQ.AI para iniciar el proxy', + 4: 'Página de estado', + 5: 'Estado de la atestación del enclave, los modelos privados disponibles y fragmentos de configuración para clientes', + 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, 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!', 1: 'Verschlüsselter Proxy', 2: 'Der Proxy ist bereit — Enklave-Attestierung verifiziert', 3: 'Der Proxy ist nicht bereit (Enklave-Attestierung ausstehend)', - 4: 'OpenAI-kompatible API', - 5: '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', - 6: 'PPQ.AI-API-Schlüssel', - 7: 'Dein API-Schlüssel von ppq.ai (Einstellungen → API-Schlüssel). Leer lassen, um den bereits gespeicherten Schlüssel zu behalten.', - 8: 'Ausführliche Protokollierung', - 9: 'Protokolliert jede Anfrage, die der Proxy verarbeitet. Nützlich zur Fehlersuche.', - 10: 'PPQ-API-Schlüssel konfigurieren', - 11: 'Lege den PPQ.AI-API-Schlüssel fest, mit dem sich der Proxy authentifiziert. Anfragen werden diesem Schlüssel in Rechnung gestellt.', - 12: 'Ein API-Schlüssel ist erforderlich. Erstelle einen auf ppq.ai unter Einstellungen → API-Schlüssel.', - 13: 'Füge deinen PPQ.AI-API-Schlüssel hinzu, um den Proxy zu starten', + 4: 'Statusseite', + 5: 'Status der Enklave-Attestierung, die verfügbaren privaten Modelle und Codeschnipsel zur Client-Einrichtung', + 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 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!', 1: 'Szyfrowany proxy', 2: 'Proxy jest gotowy — atestacja enklawy zweryfikowana', 3: 'Proxy nie jest gotowy (atestacja enklawy w toku)', - 4: 'API zgodne z OpenAI', - 5: 'Skieruj dowolnego klienta SDK OpenAI lub Anthropic na ten URL, aby korzystać z prywatnych modeli (TEE) PPQ z szyfrowaniem end-to-end', - 6: 'Klucz API PPQ.AI', - 7: 'Twój klucz API z ppq.ai (Ustawienia → Klucze API). Pozostaw puste, aby zachować już zapisany klucz.', - 8: 'Szczegółowe logowanie', - 9: 'Rejestruje każde żądanie obsługiwane przez proxy. Przydatne przy rozwiązywaniu problemów.', - 10: 'Skonfiguruj klucz API PPQ', - 11: 'Ustaw klucz API PPQ.AI, którym proxy się uwierzytelnia. Żądania są rozliczane na ten klucz.', - 12: 'Wymagany jest klucz API. Utwórz go na ppq.ai w Ustawienia → Klucze API.', - 13: 'Dodaj swój klucz API PPQ.AI, aby uruchomić proxy', + 4: 'Strona stanu', + 5: 'Stan atestacji enklawy, dostępne modele prywatne oraz fragmenty konfiguracji dla klientów', + 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 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 !', 1: 'Proxy chiffré', 2: "Le proxy est prêt — attestation de l'enclave vérifiée", 3: "Le proxy n'est pas prêt (attestation de l'enclave en attente)", - 4: 'API compatible OpenAI', - 5: "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", - 6: 'Clé API PPQ.AI', - 7: 'Votre clé API de ppq.ai (Paramètres → Clés API). Laissez vide pour conserver la clé déjà enregistrée.', - 8: 'Journalisation détaillée', - 9: 'Journalise chaque requête traitée par le proxy. Utile pour le dépannage.', - 10: 'Configurer la clé API PPQ', - 11: "Définissez la clé API PPQ.AI avec laquelle le proxy s'authentifie. Les requêtes sont facturées sur cette clé.", - 12: 'Une clé API est requise. Créez-en une sur ppq.ai dans Paramètres → Clés API.', - 13: 'Ajoutez votre clé API PPQ.AI pour démarrer le proxy', + 4: "Page d'état", + 5: "État de l'attestation de l'enclave, les modèles privés disponibles et des extraits de configuration client", + 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, 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 diff --git a/startos/init/taskConfigureApiKey.ts b/startos/init/taskConfigureApiKey.ts index 766085a..3c8e725 100644 --- a/startos/init/taskConfigureApiKey.ts +++ b/startos/init/taskConfigureApiKey.ts @@ -3,17 +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. -export const taskConfigureApiKey = sdk.setupOnInit(async (effects, kind) => { - const apiKey = await configJson - .read((c) => c.apiKey) - .once() - .catch(() => undefined) +// 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', + ), }) } }) diff --git a/startos/interfaces.ts b/startos/interfaces.ts index 0da1f8c..783d5d7 100644 --- a/startos/interfaces.ts +++ b/startos/interfaces.ts @@ -2,30 +2,39 @@ import { sdk } from './sdk' import { apiPort } from './utils' import { i18n } from './i18n' -// Host id (the sdk.MultiHost.of group) — distinct from the interface id exported on it. -export const apiHostId = 'api-multi' -export const apiInterfaceId = 'api' - export const setInterfaces = sdk.setupInterfaces(async ({ effects }) => { - const apiMulti = sdk.MultiHost.of(effects, apiHostId) - const apiMultiOrigin = await apiMulti.bindPort(apiPort, { + const multi = sdk.MultiHost.of(effects, 'main') + const origin = await multi.bindPort(apiPort, { protocol: 'http', }) + const ui = sdk.createInterface(effects, { + name: i18n('Status Page'), + id: 'ui', + description: i18n( + 'Enclave attestation state, the available private models, and client setup snippets', + ), + type: 'ui', + masked: false, + schemeOverride: null, + username: null, + path: '', + query: {}, + }) const api = sdk.createInterface(effects, { name: i18n('OpenAI-Compatible API'), - id: apiInterfaceId, + id: 'api', description: i18n( 'Point any OpenAI or Anthropic SDK client at this URL to use PPQ private (TEE) models with end-to-end encryption', ), type: 'api', - masked: true, + masked: false, schemeOverride: null, username: null, path: '', query: {}, }) - const apiReceipt = await apiMultiOrigin.export([api]) + const receipt = await origin.export([ui, api]) - return [apiReceipt] + return [receipt] }) diff --git a/startos/main.ts b/startos/main.ts index 5ed427a..10a1485 100644 --- a/startos/main.ts +++ b/startos/main.ts @@ -1,45 +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' }, - sdk.Mounts.of(), - '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'], + }) }) diff --git a/startos/manifest/i18n.ts b/startos/manifest/i18n.ts index b78a199..818617f 100644 --- a/startos/manifest/i18n.ts +++ b/startos/manifest/i18n.ts @@ -1,9 +1,12 @@ export const short = { en_US: 'End-to-end encrypted proxy for PPQ.AI private (TEE) AI models', - es_ES: 'Proxy cifrado de extremo a extremo para los modelos de IA privados (TEE) de PPQ.AI', - de_DE: 'Ende-zu-Ende-verschlüsselter Proxy für private (TEE) KI-Modelle von PPQ.AI', + es_ES: + 'Proxy cifrado de extremo a extremo para los modelos de IA privados (TEE) de PPQ.AI', + de_DE: + 'Ende-zu-Ende-verschlüsselter Proxy für private (TEE) KI-Modelle von PPQ.AI', pl_PL: 'Szyfrowany end-to-end proxy dla prywatnych modeli AI (TEE) PPQ.AI', - fr_FR: 'Proxy chiffré de bout en bout pour les modèles IA privés (TEE) de PPQ.AI', + fr_FR: + 'Proxy chiffré de bout en bout pour les modèles IA privés (TEE) de PPQ.AI', } export const long = { diff --git a/startos/manifest/index.ts b/startos/manifest/index.ts index 2ad2417..5d3d4f5 100644 --- a/startos/manifest/index.ts +++ b/startos/manifest/index.ts @@ -5,7 +5,7 @@ export const manifest = setupManifest({ id: 'ppq-private-mode', title: 'PPQ Private Mode', license: 'MIT', - packageRepo: 'https://github.com/PayPerQ/ppq-private-mode-startos', + packageRepo: 'https://github.com/Start9-Community/ppq-private-mode-startos', upstreamRepo: 'https://github.com/PayPerQ/ppq-private-mode-proxy', marketingUrl: 'https://ppq.ai', donationUrl: null, diff --git a/startos/utils.ts b/startos/utils.ts index 92220bd..d6ca153 100644 --- a/startos/utils.ts +++ b/startos/utils.ts @@ -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' diff --git a/startos/versions/current.ts b/startos/versions/current.ts index e984012..ee0d6d9 100644 --- a/startos/versions/current.ts +++ b/startos/versions/current.ts @@ -2,7 +2,7 @@ import { IMPOSSIBLE, VersionInfo } from '@start9labs/start-sdk' export const current = VersionInfo.of({ // Tracks upstream ppq-private-mode-proxy (package.json version). - version: '0.3.2:0', + version: '0.4.1:0', releaseNotes: { en_US: 'Initial release for StartOS', es_ES: 'Lanzamiento inicial para StartOS',