@cpajs/cpa 0.1.0-rc.2 → 0.1.0-rc.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +65 -19
  2. package/assets/management.html +169 -0
  3. package/dist/client/index.d.ts +1 -1
  4. package/dist/client/index.d.ts.map +1 -1
  5. package/dist/client/resources/config.d.ts +10 -3
  6. package/dist/client/resources/config.d.ts.map +1 -1
  7. package/dist/client/resources/config.js.map +1 -1
  8. package/dist/client/types/config.d.ts +8 -0
  9. package/dist/client/types/config.d.ts.map +1 -1
  10. package/dist/server/config.d.ts +8 -0
  11. package/dist/server/config.d.ts.map +1 -1
  12. package/dist/server/config.js +11 -1
  13. package/dist/server/config.js.map +1 -1
  14. package/dist/server/cpa-version.d.ts +12 -0
  15. package/dist/server/cpa-version.d.ts.map +1 -1
  16. package/dist/server/cpa-version.js +12 -0
  17. package/dist/server/cpa-version.js.map +1 -1
  18. package/dist/server/index.d.ts +2 -1
  19. package/dist/server/index.d.ts.map +1 -1
  20. package/dist/server/index.js +63 -42
  21. package/dist/server/index.js.map +1 -1
  22. package/dist/server/internal.d.ts +2 -0
  23. package/dist/server/internal.d.ts.map +1 -1
  24. package/dist/server/management.d.ts +10 -2
  25. package/dist/server/management.d.ts.map +1 -1
  26. package/dist/server/management.js +14 -6
  27. package/dist/server/management.js.map +1 -1
  28. package/dist/server/panel.d.ts +5 -0
  29. package/dist/server/panel.d.ts.map +1 -0
  30. package/dist/server/panel.js +9 -0
  31. package/dist/server/panel.js.map +1 -0
  32. package/dist/server/types.d.ts +35 -3
  33. package/dist/server/types.d.ts.map +1 -1
  34. package/dist/server/warnings.d.ts +32 -0
  35. package/dist/server/warnings.d.ts.map +1 -0
  36. package/dist/server/warnings.js +19 -0
  37. package/dist/server/warnings.js.map +1 -0
  38. package/package.json +26 -24
  39. package/src/client/index.ts +1 -1
  40. package/src/client/resources/config.ts +12 -3
  41. package/src/client/types/config.ts +18 -0
  42. package/src/server/config.ts +17 -1
  43. package/src/server/cpa-version.ts +13 -0
  44. package/src/server/index.ts +82 -43
  45. package/src/server/internal.ts +2 -0
  46. package/src/server/management.ts +18 -8
  47. package/src/server/panel.ts +10 -0
  48. package/src/server/types.ts +36 -3
  49. package/src/server/warnings.ts +43 -0
package/README.md CHANGED
@@ -27,7 +27,6 @@ import { startServer } from '@cpajs/cpa/server';
27
27
 
28
28
  const server = await startServer({
29
29
  stateDir: './.cpa', // omit for a temporary directory that is removed on stop
30
- management: { key: process.env.CPA_MANAGEMENT_KEY! },
31
30
  config: { // native v8 config, typed as CpaConfig
32
31
  access: { 'api-keys': ['sk-my-model-key'] },
33
32
  routing: { strategy: 'fill-first' },
@@ -38,6 +37,10 @@ const server = await startServer({
38
37
  console.log(server.origin); // http://127.0.0.1:40123 (a free port is picked by default)
39
38
  console.log(server.baseUrl); // http://127.0.0.1:40123/v1 for OpenAI-compatible SDKs
40
39
 
40
+ // Management API client, already bound to this server and a key generated for this start.
41
+ const client = server.client();
42
+ await client.credentials.list();
43
+
41
44
  await server.stop();
42
45
  ```
43
46
 
@@ -45,7 +48,7 @@ await server.stop();
45
48
  - `config` is written as YAML to `<stateDir>/config.yaml` only when that file does not exist yet. On later
46
49
  starts the existing file is reused, so changes made through the management API (or by CPA itself) survive
47
50
  `stop()` and `startServer()`. Pass `overwriteConfig: true` to replace it; when a file is kept, `config`, `host`
48
- and `port` are not applied and a message is emitted through `onLog`. Credentials go to `<stateDir>/auths`
51
+ and `port` are not applied and a `configReused` warning is emitted. Credentials go to `<stateDir>/auths`
49
52
  unless `oauth.auth-dir` is set. The server binds `127.0.0.1` unless you pass `host` or set `server.host`.
50
53
  - `configPath` hands an existing file to CPA unchanged. CPA may rewrite it on startup: it hashes a plaintext
51
54
  `management.secret-key`, removes legacy keys that conflict with their v8 equivalents, and normalizes the
@@ -81,7 +84,7 @@ await server.stop();
81
84
  - Windows: no launcher is needed, because Node already kills child processes with their parent.
82
85
 
83
86
  Pass `launcher: false` to start CPA directly. With a custom `binaryPath`, the launcher is looked up next to
84
- that binary and then in the installed platform package; if none is found, a notice is logged. A graceful stop
87
+ that binary and then in the installed platform package; if none is found, CPA starts directly. A graceful stop
85
88
  is still nicer than a kill, and `stopAllServers()` stops every server this process started:
86
89
 
87
90
  ```ts
@@ -96,9 +99,32 @@ await server.stop();
96
99
  ```
97
100
 
98
101
  Lines longer than 64 KiB in CPA's output are truncated, with a marker saying how much was dropped.
99
- - `management: { key }` manages the management API key. The default mode writes a bcrypt hash into
100
- `management.secret-key` of the managed config and sets `management.allow-remote` from `allowRemote`
101
- (default `false`), so the plaintext never reaches disk and remote management stays off.
102
+ - Management key: you usually don't need one. Without `management`, cpajs generates a random key for each start,
103
+ writes only its bcrypt hash into the managed config (remote management off), keeps the plaintext in memory,
104
+ and gives you `server.client()`: a management client bound to this server. The key is never exposed, and
105
+ because nobody types it, it can never be wrong and trigger CPA's 30-minute IP ban. `restart()` keeps the key,
106
+ so existing clients keep working; a new `startServer()` generates a new one. Since no one could log in to the
107
+ web control panel with that key, the panel defaults to off (`disable-control-panel: true`). `management: false`
108
+ turns the management API off.
109
+
110
+ Pass a key yourself when a person or something else needs it, for example the web control panel, a remote
111
+ admin tool or another process: `management: { key }`. The default mode writes a bcrypt hash into
112
+ `management.secret-key` of the managed config and sets `management.allow-remote` from `allowRemote` (default
113
+ `false`), so the plaintext never reaches disk and remote management stays off. `server.client()` works there
114
+ too.
115
+
116
+ The three steps build on each other: no key (only this process), `management: { key }` (people on this
117
+ machine, with the control panel), `allowRemote: true` (people elsewhere too). The rest of the table below is
118
+ for setups that need more control.
119
+
120
+ Control panel: `@cpajs/cpa` ships a pinned copy of the web control panel (`management.html`, see
121
+ [compatibility](docs/compatibility.md)), checked against its sha256 when the package is built. In a config
122
+ cpajs manages, CPA serves that copy at `/management.html` and never downloads one: cpajs copies it to
123
+ `<stateDir>/static/`, points `MANAGEMENT_STATIC_PATH` at it and defaults `disable-auto-update-panel` to `true`.
124
+ Upstream would otherwise fetch the latest panel from GitHub on start and every 3 hours, falling back to an
125
+ unverified mirror. To get that behaviour back, set `disable-auto-update-panel: false` or
126
+ `panel-github-repository` in `config.management`, or set `MANAGEMENT_STATIC_PATH` in `env`. With `configPath`,
127
+ cpajs leaves the panel to your file.
102
128
 
103
129
  Redaction: the key, secrets found in the config when the server starts, and `redact` values are replaced with
104
130
  `[REDACTED]` in `onLog`, `recentLogs` and startup errors. This is best-effort, with known limits:
@@ -109,14 +135,16 @@ await server.stop();
109
135
 
110
136
  Do not treat CPA's output as safe to publish.
111
137
 
112
- | Mode | How CPA compares the key | Remote access |
113
- | --- | --- | --- |
114
- | `management: { key }` (default) | bcrypt hash in `management.secret-key` | Written from `allowRemote`, default `false` |
115
- | `management: { key, allowRemote: true }` | bcrypt hash in `management.secret-key` | Non-loopback clients allowed |
116
- | `management: { key, viaEnvironment: true }` | Plaintext `MANAGEMENT_PASSWORD` | Always allowed: upstream treats the variable as `allow-remote: true` |
117
- | `config.management['secret-key']` | What you write; CPA hashes plaintext on startup | `config.management['allow-remote']` |
118
- | `configPath` | `secret-key` in the file | `allow-remote` in the file |
119
- | `managementKey` (deprecated) | bcrypt hash, same as the default | Same as the default; it no longer opens remote access |
138
+ | Mode | How CPA compares the key | Remote access | `server.client()` | Control panel |
139
+ | --- | --- | --- | --- | --- |
140
+ | omitted (default) | bcrypt hash of a key generated per start | Off | Yes | Off (nobody knows the key) |
141
+ | `management: false` | — (management API disabled) | — | No | — |
142
+ | `management: { key }` | bcrypt hash in `management.secret-key` | Written from `allowRemote`, default `false` | Yes | Pinned copy |
143
+ | `management: { key, allowRemote: true }` | bcrypt hash in `management.secret-key` | Non-loopback clients allowed | Yes | Pinned copy |
144
+ | `management: { key, viaEnvironment: true }` | Plaintext `MANAGEMENT_PASSWORD` | Always allowed: upstream treats the variable as `allow-remote: true` | Yes | Pinned copy |
145
+ | `config.management['secret-key']` | What you write; CPA hashes plaintext on startup | `config.management['allow-remote']` | No: the key is yours | Pinned copy |
146
+ | `configPath` | `secret-key` in the file | `allow-remote` in the file | Only with `management: { key, viaEnvironment: true }` | Your file decides |
147
+ | `managementKey` (deprecated) | bcrypt hash, same as `management: { key }` | Off unless the file allows it | Yes | Pinned copy |
120
148
 
121
149
  `management.key` is rejected together with `config.management['secret-key']`, or with a `secret-key`
122
150
  already present in `configPath`. In `configPath` mode it also requires `viaEnvironment: true`, because
@@ -126,11 +154,29 @@ await server.stop();
126
154
  environment is always removed, and setting it in `env` is rejected. Otherwise it would quietly add a
127
155
  plaintext key and turn remote management on.
128
156
 
129
- `viaEnvironment: true` always emits a warning through `onLog`, because the key is compared in plaintext and
130
- remote management cannot be turned off. `allowRemote: true` emits one when the bind host is not loopback.
131
- These are warnings, not errors, because both are explicit choices.
157
+ `viaEnvironment: true` always emits the `managementViaEnvironment` warning, because the key is compared in
158
+ plaintext and remote management cannot be turned off. `allowRemote: true` emits `remoteManagementExposed` when
159
+ the bind host is not loopback. These are warnings, not errors, because both are explicit choices.
160
+
161
+ The server handle never exposes the key; `server.client()` exposes the capability instead. To connect from
162
+ elsewhere, pass your own key to `createClient`.
163
+ - Warnings: cpajs reports things worth knowing as coded warnings, separate from CPA's output (`onLog`). By
164
+ default they go through `process.emitWarning` as `CpaWarning`, so they appear on stderr and work with Node's
165
+ usual handling (`--no-warnings`, `process.on('warning')`). Pass `onWarning` to route them yourself. Pass
166
+ `suppressWarnings` to silence individual ones; every message names the field that silences it.
167
+
168
+ ```ts
169
+ await startServer({ config, suppressWarnings: { noManagementKey: true } });
170
+ ```
171
+
172
+ | Code | Emitted when |
173
+ | --- | --- |
174
+ | `noManagementKey` | No `management` was given, so a key was generated for this start (use `server.client()`) |
175
+ | `managementViaEnvironment` | `management.viaEnvironment` is used: plaintext comparison, remote management forced on |
176
+ | `remoteManagementExposed` | `allowRemote` is on and the server binds a non-loopback host |
177
+ | `configReused` | An existing managed config was kept; this start's `config`, `host` and `port` were not applied |
178
+ | `managementKeyUpdated` | A reused config's management key was replaced for a new `management.key` |
132
179
 
133
- The server handle does not expose the key. Keep it in your own code and pass it to `createClient`.
134
180
  - CLI flags are typed options:
135
181
  - `localModel: true` → `-local-model`, which uses the embedded model catalogs.
136
182
  - `home: { jwt, disableClusterDiscovery }` → Home mode. The JWT is passed through `HOME_JWT`, so it never appears in argv.
@@ -151,7 +197,7 @@ const client = createClient({
151
197
 
152
198
  const { data: config, etag } = await client.config.get();
153
199
  await client.config.patch({ routing: { strategy: 'round-robin' } }, { ifMatch: etag });
154
- await client.config.set('routing/retry/request-retry', 2);
200
+ await client.config.set('routing/retry/request-retry', 2); // value typed by path: number
155
201
 
156
202
  const { files } = await client.credentials.list();
157
203
  await client.credentials.upload({ name: 'codex-me.json', content: credentialJson });