@cpajs/cpa 0.1.0-rc.3 → 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 (39) hide show
  1. package/README.md +33 -18
  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 +1 -1
  19. package/dist/server/index.d.ts.map +1 -1
  20. package/dist/server/index.js +27 -5
  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/panel.d.ts +5 -0
  25. package/dist/server/panel.d.ts.map +1 -0
  26. package/dist/server/panel.js +9 -0
  27. package/dist/server/panel.js.map +1 -0
  28. package/dist/server/types.d.ts +4 -1
  29. package/dist/server/types.d.ts.map +1 -1
  30. package/package.json +26 -24
  31. package/src/client/index.ts +1 -1
  32. package/src/client/resources/config.ts +12 -3
  33. package/src/client/types/config.ts +18 -0
  34. package/src/server/config.ts +17 -1
  35. package/src/server/cpa-version.ts +13 -0
  36. package/src/server/index.ts +29 -5
  37. package/src/server/internal.ts +2 -0
  38. package/src/server/panel.ts +10 -0
  39. package/src/server/types.ts +4 -1
package/README.md CHANGED
@@ -103,13 +103,28 @@ await server.stop();
103
103
  writes only its bcrypt hash into the managed config (remote management off), keeps the plaintext in memory,
104
104
  and gives you `server.client()`: a management client bound to this server. The key is never exposed, and
105
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. `management: false` turns the
107
- management API off.
108
-
109
- Pass a key yourself only when something else needs it, for example a remote admin tool or another process:
110
- `management: { key }`. The default mode writes a bcrypt hash into `management.secret-key` of the managed config
111
- and sets `management.allow-remote` from `allowRemote` (default `false`), so the plaintext never reaches disk
112
- and remote management stays off. `server.client()` works there too.
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.
113
128
 
114
129
  Redaction: the key, secrets found in the config when the server starts, and `redact` values are replaced with
115
130
  `[REDACTED]` in `onLog`, `recentLogs` and startup errors. This is best-effort, with known limits:
@@ -120,16 +135,16 @@ await server.stop();
120
135
 
121
136
  Do not treat CPA's output as safe to publish.
122
137
 
123
- | Mode | How CPA compares the key | Remote access | `server.client()` |
124
- | --- | --- | --- | --- |
125
- | omitted (default) | bcrypt hash of a key generated per start | Off | Yes |
126
- | `management: false` | — (management API disabled) | — | No |
127
- | `management: { key }` | bcrypt hash in `management.secret-key` | Written from `allowRemote`, default `false` | Yes |
128
- | `management: { key, allowRemote: true }` | bcrypt hash in `management.secret-key` | Non-loopback clients allowed | Yes |
129
- | `management: { key, viaEnvironment: true }` | Plaintext `MANAGEMENT_PASSWORD` | Always allowed: upstream treats the variable as `allow-remote: true` | Yes |
130
- | `config.management['secret-key']` | What you write; CPA hashes plaintext on startup | `config.management['allow-remote']` | No: the key is yours |
131
- | `configPath` | `secret-key` in the file | `allow-remote` in the file | Only with `management: { key, viaEnvironment: true }` |
132
- | `managementKey` (deprecated) | bcrypt hash, same as `management: { key }` | Off unless the file allows it | Yes |
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 |
133
148
 
134
149
  `management.key` is rejected together with `config.management['secret-key']`, or with a `secret-key`
135
150
  already present in `configPath`. In `configPath` mode it also requires `viaEnvironment: true`, because
@@ -182,7 +197,7 @@ const client = createClient({
182
197
 
183
198
  const { data: config, etag } = await client.config.get();
184
199
  await client.config.patch({ routing: { strategy: 'round-robin' } }, { ifMatch: etag });
185
- await client.config.set('routing/retry/request-retry', 2);
200
+ await client.config.set('routing/retry/request-retry', 2); // value typed by path: number
186
201
 
187
202
  const { files } = await client.credentials.list();
188
203
  await client.credentials.upload({ name: 'codex-me.json', content: credentialJson });