@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.
- package/README.md +65 -19
- package/assets/management.html +169 -0
- package/dist/client/index.d.ts +1 -1
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/resources/config.d.ts +10 -3
- package/dist/client/resources/config.d.ts.map +1 -1
- package/dist/client/resources/config.js.map +1 -1
- package/dist/client/types/config.d.ts +8 -0
- package/dist/client/types/config.d.ts.map +1 -1
- package/dist/server/config.d.ts +8 -0
- package/dist/server/config.d.ts.map +1 -1
- package/dist/server/config.js +11 -1
- package/dist/server/config.js.map +1 -1
- package/dist/server/cpa-version.d.ts +12 -0
- package/dist/server/cpa-version.d.ts.map +1 -1
- package/dist/server/cpa-version.js +12 -0
- package/dist/server/cpa-version.js.map +1 -1
- package/dist/server/index.d.ts +2 -1
- package/dist/server/index.d.ts.map +1 -1
- package/dist/server/index.js +63 -42
- package/dist/server/index.js.map +1 -1
- package/dist/server/internal.d.ts +2 -0
- package/dist/server/internal.d.ts.map +1 -1
- package/dist/server/management.d.ts +10 -2
- package/dist/server/management.d.ts.map +1 -1
- package/dist/server/management.js +14 -6
- package/dist/server/management.js.map +1 -1
- package/dist/server/panel.d.ts +5 -0
- package/dist/server/panel.d.ts.map +1 -0
- package/dist/server/panel.js +9 -0
- package/dist/server/panel.js.map +1 -0
- package/dist/server/types.d.ts +35 -3
- package/dist/server/types.d.ts.map +1 -1
- package/dist/server/warnings.d.ts +32 -0
- package/dist/server/warnings.d.ts.map +1 -0
- package/dist/server/warnings.js +19 -0
- package/dist/server/warnings.js.map +1 -0
- package/package.json +26 -24
- package/src/client/index.ts +1 -1
- package/src/client/resources/config.ts +12 -3
- package/src/client/types/config.ts +18 -0
- package/src/server/config.ts +17 -1
- package/src/server/cpa-version.ts +13 -0
- package/src/server/index.ts +82 -43
- package/src/server/internal.ts +2 -0
- package/src/server/management.ts +18 -8
- package/src/server/panel.ts +10 -0
- package/src/server/types.ts +36 -3
- 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
|
|
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,
|
|
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
|
-
-
|
|
100
|
-
|
|
101
|
-
|
|
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
|
-
|
|
|
115
|
-
| `management:
|
|
116
|
-
| `management: { key
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
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
|
|
130
|
-
remote management cannot be turned off. `allowRemote: true` emits
|
|
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 });
|