@camstack/develop 0.1.3 → 0.1.5
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/dist/hub/admin-token-store.d.ts +53 -0
- package/dist/hub/admin-token-store.d.ts.map +1 -0
- package/dist/hub/admin-token-store.js +139 -0
- package/dist/hub/credentials.d.ts +53 -0
- package/dist/hub/credentials.d.ts.map +1 -0
- package/dist/hub/credentials.js +151 -0
- package/dist/hub/hub-address.d.ts +24 -0
- package/dist/hub/hub-address.d.ts.map +1 -0
- package/dist/hub/hub-address.js +87 -0
- package/dist/hub/hub-client.d.ts +57 -0
- package/dist/hub/hub-client.d.ts.map +1 -0
- package/dist/hub/hub-client.js +176 -0
- package/dist/hub/hub-tls.d.ts +16 -0
- package/dist/hub/hub-tls.d.ts.map +1 -0
- package/dist/hub/hub-tls.js +67 -0
- package/dist/hub/hub-url.d.ts +17 -0
- package/dist/hub/hub-url.d.ts.map +1 -0
- package/dist/hub/hub-url.js +54 -0
- package/dist/hub/session-store.d.ts +55 -0
- package/dist/hub/session-store.d.ts.map +1 -0
- package/dist/hub/session-store.js +178 -0
- package/dist/hub-discovery/hub-candidates.d.ts +53 -0
- package/dist/hub-discovery/hub-candidates.d.ts.map +1 -0
- package/dist/hub-discovery/hub-candidates.js +103 -0
- package/dist/hub-discovery/index.d.ts +4 -0
- package/dist/hub-discovery/index.d.ts.map +1 -0
- package/dist/hub-discovery/index.js +3 -0
- package/dist/hub-discovery/mdns-browse.d.ts +51 -0
- package/dist/hub-discovery/mdns-browse.d.ts.map +1 -0
- package/dist/hub-discovery/mdns-browse.js +116 -0
- package/dist/index.d.ts +15 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +11 -2
- package/dist/scaffold/addon.d.ts.map +1 -1
- package/dist/scaffold/addon.js +6 -0
- package/dist/types.d.ts +6 -1
- package/dist/types.d.ts.map +1 -1
- package/package.json +10 -1
- package/skills/README.md +3 -0
- package/skills/camstack-addon.md +376 -98
- package/skills/camstack-capability.md +184 -77
- package/skills/camstack-secrets.md +121 -34
|
@@ -1,10 +1,20 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: camstack-capability
|
|
3
|
-
description: Add or change a CamStack capability (
|
|
3
|
+
description: Add or change a CamStack capability (`*.cap.ts`) end to end — decide whether one is needed at all, pick its cardinality (singleton, collection, device-native, wrapper, internal, node-hosted), codegen and the two hand-edits it cannot do, registerProvider and the manifest, provider selection through bindings, CAP_INPUT_DEFAULTS, a capability-driven UI, typed routing errors, and what must be published for it to reach a running hub. Use for "new cap", "add a method", "add a field to a cap", "two addons implement the same cap", "No procedure found on path", "provider not available".
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Adding or changing a capability
|
|
7
7
|
|
|
8
|
+
A capability is a typed contract between addons, defined once in
|
|
9
|
+
`packages/types/src/capabilities/<name>.cap.ts`. The long-form reference is
|
|
10
|
+
`docs/architecture/capabilities.md`; the inventory is the generated
|
|
11
|
+
`docs/reference/capabilities.md` and `docs/reference/api.md`. Read the first
|
|
12
|
+
before you design anything.
|
|
13
|
+
|
|
14
|
+
> Skill names with no file in this pack (`camstack-ui`, `camstack-ui-admin`,
|
|
15
|
+
> `camstack-server-change`, `camstack-diagnose`, `camstack-publish-ci`) are
|
|
16
|
+
> server-repository skills under `.claude/skills/`; this text stands on its own.
|
|
17
|
+
|
|
8
18
|
## Tooling
|
|
9
19
|
|
|
10
20
|
```bash
|
|
@@ -17,95 +27,192 @@ The scaffold writes a stub only. You still hand-edit the index + run codegen.
|
|
|
17
27
|
|
|
18
28
|
## 0. Do you need one?
|
|
19
29
|
|
|
20
|
-
A new capability is a **framework
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
- Enumerating providers
|
|
24
|
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
30
|
+
A new capability is a **framework change**: codegen, a publish of the server
|
|
31
|
+
closure, and an update of every node before anyone can call it. Check first:
|
|
32
|
+
|
|
33
|
+
- **Enumerating providers of an existing collection?**
|
|
34
|
+
`addons.listCapabilityProviders({ capName })` works even for `internal` caps.
|
|
35
|
+
- **An addon's own configuration?** `globalSettingsSchema()` plus the existing
|
|
36
|
+
`addon-settings` cap; the settings panel already renders it.
|
|
37
|
+
- **Enable / disable a provider?** `addons.setCapabilityProviderEnabled` (the
|
|
38
|
+
toggle is the ONE enable — D777).
|
|
39
|
+
- **A field on an existing method?** Additive output fields need only the
|
|
40
|
+
providing addon redeployed (the router passes output through structurally).
|
|
41
|
+
A new INPUT field is different: the hub validates input against ITS copy of
|
|
42
|
+
the schema and strips unknown keys, so it needs the server update too (§6).
|
|
43
|
+
|
|
44
|
+
A new capability is right when there is genuinely new state or behaviour that
|
|
45
|
+
several addons implement or call.
|
|
46
|
+
|
|
47
|
+
## 1. Pick the cardinality — it decides everything downstream
|
|
48
|
+
|
|
49
|
+
| Archetype | Declare | Who answers a call |
|
|
50
|
+
| --- | --- | --- |
|
|
51
|
+
| **singleton** | `mode: 'singleton'` | one active provider (§4 selection) |
|
|
52
|
+
| **collection** | `mode: 'collection'` | every enabled provider; a caller may pin one with `addonId` (global) or `provider` (device collection, required — D554) |
|
|
53
|
+
| **device-native** | `scope: 'device'`, registered from the device class | the provider owning that device (`ctx.registerNativeCap`) |
|
|
54
|
+
| **wrapper** | `kind: 'wrapper'` (+ `defaultActive` **and** `deviceTypes`) | a provider bound per device via `deviceManager.getBindings` / `setBinding` |
|
|
55
|
+
| **internal** | `internal: true` (+ `mount: { kind: 'skip' }` for no route at all) | in-process consumers only; without `skip` it is still a full tRPC router whose un-annotated methods floor to `admin` (D240) |
|
|
56
|
+
| **node-hosted** (one per node, called with `{nodeId}`) | `mode: 'singleton'` — **never `'per-node'`** | the pinned node's provider |
|
|
57
|
+
|
|
58
|
+
`per-node` is a declared enum value that codegen does **not** wire:
|
|
59
|
+
`scripts/generate-capability-router-types.ts` matches only
|
|
60
|
+
`singleton|collection`, so a `per-node` cap is silently missing from
|
|
61
|
+
`ALL_CAPABILITY_DEFINITIONS` and every call answers "provider not available".
|
|
62
|
+
Route a node-hosted cap with a pin instead: codegen injects a `nodeId` selector
|
|
63
|
+
into every method of a remote-capable singleton, and `nodePin(id)`
|
|
64
|
+
(`packages/types/src/cap-call-context.ts`) carries the same pin out of band.
|
|
65
|
+
|
|
66
|
+
The mount is **derived** from scope and mode. Set `mount` only for
|
|
67
|
+
`server-provided` (also needs a factory in `buildServerProviders`), `hub-only`
|
|
68
|
+
or `skip`.
|
|
69
|
+
|
|
70
|
+
## 2. Define it
|
|
33
71
|
|
|
34
72
|
```ts
|
|
35
73
|
export const fooCapability = {
|
|
36
|
-
name: 'foo',
|
|
37
|
-
scope: 'system',
|
|
38
|
-
mode: 'singleton',
|
|
39
|
-
methods: { … },
|
|
74
|
+
name: 'foo', // kebab-case — scripts/check-cap-name-kebab.ts
|
|
75
|
+
scope: 'system', // or 'device'
|
|
76
|
+
mode: 'singleton', // or 'collection'
|
|
77
|
+
methods: { … }, // method(input, output, { auth, access })
|
|
40
78
|
} as const satisfies CapabilityDefinition
|
|
41
|
-
|
|
42
79
|
export type IFooProvider = InferProvider<typeof fooCapability>
|
|
43
80
|
```
|
|
44
81
|
|
|
45
|
-
-
|
|
46
|
-
-
|
|
47
|
-
-
|
|
48
|
-
|
|
49
|
-
- `
|
|
50
|
-
|
|
51
|
-
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
82
|
+
- **Auth tier on every method.** Omitted = `protected` (reachable by every
|
|
83
|
+
signed-in non-admin). Every tier is pinned in
|
|
84
|
+
`scripts/method-tier-baseline.json`; accept a deliberate change with
|
|
85
|
+
`npx tsx scripts/check-method-tiers.ts --update` and read the diff. A method
|
|
86
|
+
naming a device keeps the id in a TOP-LEVEL `deviceId`-style field or the
|
|
87
|
+
scope gate cannot see it (`docs/architecture/capabilities.md` §"A
|
|
88
|
+
system-scope method that names a device").
|
|
89
|
+
- **Export coverage.** A cap either exports to the ecosystems or is a written
|
|
90
|
+
exception: `npx tsx scripts/check-export-coverage.ts`. Both checks run in
|
|
91
|
+
the pre-commit hook when a `*.cap.ts` is staged.
|
|
92
|
+
- Behavioural metadata (`kind`, `defaultActive`, `mode`) lives here and only
|
|
93
|
+
here (D4). The manifest lists the cap by `name` (plus `optional`,
|
|
94
|
+
`dependsOn`), nothing else.
|
|
95
|
+
- Device state: `status: { schema, kind }`, `runtimeState` including
|
|
96
|
+
`lastFetchedAt: z.number()`. A camera-config cap uses the `deviceConfig`
|
|
97
|
+
archetype with an honest, camera-probed `getOptions` — the UI is derived from
|
|
98
|
+
it (D14). `deviceConfig` and `exposesDeviceSettings` are mutually exclusive.
|
|
99
|
+
- A `z.enum` in a cap is a second declaration of a union (it reaches the
|
|
100
|
+
generated client): when removing a member, grep both.
|
|
101
|
+
|
|
102
|
+
## 3. Hand-edits, then codegen
|
|
58
103
|
|
|
59
104
|
In `packages/types/src/capabilities/index.ts`:
|
|
60
105
|
|
|
61
|
-
1.
|
|
62
|
-
2.
|
|
106
|
+
1. a value re-export of the capability and its types;
|
|
107
|
+
2. a member of the **`AnyCapability` union** (it produces `CapabilityName`).
|
|
63
108
|
|
|
64
|
-
|
|
109
|
+
`scripts/check-capability-union-complete.ts` (inside codegen) refuses a miss.
|
|
65
110
|
|
|
66
|
-
|
|
111
|
+
```bash
|
|
112
|
+
npm run codegen # routers, mounts, proxies, hooks, access maps, CAP_INPUT_DEFAULTS, addon-api.ts…
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Skipping it is silent drift; `codegen:check` catches it later, not in time.
|
|
116
|
+
Codegen rebuilds a stale `types`/`system` dist itself; if `addon-api.ts` did not
|
|
117
|
+
change when your method is new, the dist was stale — rebuild and rerun. Its
|
|
118
|
+
guard failures are findings, not noise.
|
|
119
|
+
|
|
120
|
+
**Defaults:** a Zod `.default()` on an INPUT runs only where the router parses
|
|
121
|
+
it. A call from an addon through `ctx.api` never reaches the router, so codegen
|
|
122
|
+
emits `CAP_INPUT_DEFAULTS` (`scripts/generate-cap-input-defaults.ts`) and the
|
|
123
|
+
local link merges them. Only TOP-LEVEL defaults are carried — a nested default
|
|
124
|
+
arrives `undefined` on the addon path. Prefer top-level defaults.
|
|
125
|
+
|
|
126
|
+
## 4. Implement, register, select
|
|
127
|
+
|
|
128
|
+
- System scope: return it from `onInitialize` / `ctx.registerProvider(capName,
|
|
129
|
+
impl)`. Device scope: `ctx.registerNativeCap(cap, impl)` from a `BaseDevice`
|
|
130
|
+
subclass. Providers are flat — no nested sub-objects.
|
|
131
|
+
- **Declare it in the manifest** of the same package
|
|
132
|
+
(`camstack.addons[].capabilities`) —
|
|
133
|
+
`scripts/check-registered-caps-declared.ts` fails a registered-but-undeclared
|
|
134
|
+
cap. A builtin that registers in `onInitialize` is no exception.
|
|
135
|
+
- **Agents:** an agent declares capabilities from a hand-curated array in
|
|
136
|
+
`server/backend/src/agent/main.ts`. A cap that must exist on agents goes
|
|
137
|
+
there too; nothing else teaches it.
|
|
138
|
+
- **Two addons implement the same cap?** Both register unconditionally — never
|
|
139
|
+
gate registration behind a private setting. Choose with the binding:
|
|
140
|
+
singleton → `capabilities.setActiveSingleton({ capability, addonId, nodeId? })`
|
|
141
|
+
(persisted as `capabilities.singleton.<cap>` / `capabilities.singletonNode.<cap>.<node>`;
|
|
142
|
+
System → Capabilities in the UI); collection → the enable toggle or
|
|
143
|
+
`capabilities.setCollectionEnabledProviders`; wrapper → the device binding.
|
|
144
|
+
Resolution order for a singleton: per-node override → cluster default → the
|
|
145
|
+
first provider on that node. Two entries on a singleton in
|
|
146
|
+
`capabilities.listCapabilities` is the tell of a silent duplicate.
|
|
147
|
+
- **Consuming another addon's cap:** only `ctx.api.<cap>.<method>` — never an
|
|
148
|
+
import, never `ctx.capabilities` (local process only). In kernel/builtin
|
|
149
|
+
code that needs one addon's provider: `registry.getProviderByAddon(cap, addonId)`.
|
|
150
|
+
- **Never hand-write an interface over a cap.** Type against the generated
|
|
151
|
+
client and narrow it:
|
|
152
|
+
`type FooClient = Pick<import('../generated/addon-api.js').AddonApi['foo'], 'get' | 'set'>`
|
|
153
|
+
(precedent: `SettingsStoreClient` in `settings-store.cap.ts`). A hand-written
|
|
154
|
+
copy keeps compiling after a method is removed and fails at runtime as
|
|
155
|
+
`No procedure found on path`.
|
|
156
|
+
|
|
157
|
+
## 5. UI and errors that follow from the cap
|
|
158
|
+
|
|
159
|
+
- **The UI is derived from the cap, never hard-coded.** To make something
|
|
160
|
+
appear in an admin list, register the cap that drives the page (a collection
|
|
161
|
+
rendered by the generic page — e.g. `network-access` on Remote Access); never
|
|
162
|
+
add a hand-written card. Device-page UI goes through the device aggregate:
|
|
163
|
+
`deviceConfig` (generic cap) or `exposesDeviceSettings` with the three
|
|
164
|
+
injected methods (owned cap) — never a parallel tab system. Decision rule and
|
|
165
|
+
traps: the `camstack-addon` skill, "A UI surface on a DEVICE page".
|
|
166
|
+
- **"Absent" only from an answered query** (D315): ask
|
|
167
|
+
`capabilities.getCapability` / `useCapabilityPresence`, never infer absence
|
|
168
|
+
from `(data ?? [])`, and never throw the literal "provider not available"
|
|
169
|
+
from an accessor — substring matchers mistake it for absence.
|
|
170
|
+
- **Routing errors say WHY.** A dispatch failure carries cap, method, node and
|
|
171
|
+
device plus a typed reason (`CapRouteError` in
|
|
172
|
+
`packages/system/src/kernel/transport/cap-route.ts`: `no-provider`,
|
|
173
|
+
`node-offline`, …), never an opaque "not available".
|
|
174
|
+
|
|
175
|
+
## 6. Spec it, ship it, verify it
|
|
176
|
+
|
|
177
|
+
Spec in `server/backend/src/__tests__/cap-routers/` — the router builder does
|
|
178
|
+
not re-validate OUTPUT, so the test pins the shape.
|
|
179
|
+
|
|
180
|
+
**What must be published.** The hub reads `ALL_CAPABILITY_DEFINITIONS` from
|
|
181
|
+
**`@camstack/system`**, which bundles the cap definitions — and nx-affected
|
|
182
|
+
does NOT mark `@camstack/system` changed for an edit under `packages/types`.
|
|
183
|
+
So a cap change always force-publishes it with the server:
|
|
67
184
|
|
|
68
185
|
```bash
|
|
69
|
-
|
|
186
|
+
gh workflow run "Publish Packages" --ref main -f bump=patch -f scope=affected \
|
|
187
|
+
-f include_dependents=false -f force_packages=@camstack/system,@camstack/server
|
|
70
188
|
```
|
|
71
189
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
A cap change is a framework change: the hub serves the cap definitions bundled
|
|
103
|
-
in `@camstack/system`, so it ships inside a published `@camstack/server` (force
|
|
104
|
-
`@camstack/system` into the publish — an edit under `packages/types` does not
|
|
105
|
-
mark it changed) and reaches a node through `serverManagement.applyServerUpdate`.
|
|
106
|
-
Then deploy the providing addon. An additive OUTPUT field needs only the
|
|
107
|
-
addon redeployed; a new INPUT field needs the server update (the hub strips
|
|
108
|
-
keys its schema does not know).
|
|
109
|
-
|
|
110
|
-
`No procedure found on path "<cap>.<method>"` = the node runs the old server;
|
|
111
|
-
`method '<m>' not found on provider` = the addon is stale.
|
|
190
|
+
Then the server-side chain — publish → `applyServerUpdate` on the hub AND every
|
|
191
|
+
agent → one more restart for builtins → verify — is the `camstack-server-change`
|
|
192
|
+
skill; CI mechanics are `camstack-publish-ci`. Then `camstack deploy` the
|
|
193
|
+
providing addon (its provider must have the method).
|
|
194
|
+
|
|
195
|
+
Two 404s, two causes:
|
|
196
|
+
- `No procedure found on path "<cap>.<method>"` → the node still runs the old
|
|
197
|
+
closure (server update missing).
|
|
198
|
+
- `method '<m>' not found on provider …` → the providing addon is stale
|
|
199
|
+
(deploy it).
|
|
200
|
+
|
|
201
|
+
Verify on the running node: `capabilities.getCapability({ name })` lists the
|
|
202
|
+
provider, and a real call of the new method answers. A new INPUT field is
|
|
203
|
+
verified by a call that USES it — a save that "succeeds" while the hub strips
|
|
204
|
+
the field is the failure mode.
|
|
205
|
+
|
|
206
|
+
## 7. Done-gate — paste it before "done"
|
|
207
|
+
|
|
208
|
+
```
|
|
209
|
+
CAPABILITY DONE — <cap>.<method>
|
|
210
|
+
archetype: <singleton|collection|device-native|wrapper|internal|node-hosted>
|
|
211
|
+
hand-edits: index.ts re-export + AnyCapability union — yes
|
|
212
|
+
codegen: npm run codegen — clean; method tiers / export coverage — <accepted diff | unchanged>
|
|
213
|
+
manifest: declared in <package>/package.json (+ agent main.ts array: <yes|n/a>)
|
|
214
|
+
spec: <spec file> — <result>
|
|
215
|
+
shipped: <"not shipped" | published system+server X.Y.Z, applied on <nodes>, addon deployed>
|
|
216
|
+
verified: <the call and its answer, or "not deployed">
|
|
217
|
+
docs: camstack-docs gate — <files | none needed: reason>
|
|
218
|
+
```
|
|
@@ -1,49 +1,136 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: camstack-secrets
|
|
3
|
-
description: Handle a credential in
|
|
3
|
+
description: Handle a credential in CamStack — a password, token, API key or private key in an addon's settings, a device config, `secretStatePaths`, a token the addon mints, the hub's own secrets, or a credential a spawned child process (ffmpeg, a tunnel CLI) needs. Covers the keychain and `secret://` markers, declaring a secret by schema type, the read and clear rules, never using environment variables or argv, 0600 temp files for children, log scrubbing, the UI field, and the guards that enforce it. Use for "add a password field", "store a token", "pass a key to a subprocess", "a setting reads as { $secret }", "check-secret-fields-declared failed".
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
# Secrets
|
|
6
|
+
# Secrets and the keychain
|
|
7
7
|
|
|
8
|
-
Every password, token and key lives in the hub's
|
|
9
|
-
|
|
10
|
-
where the value used to be
|
|
11
|
-
in the server repository.
|
|
8
|
+
Every password, token and key CamStack holds lives in ONE place: the hub's
|
|
9
|
+
keychain, encrypted. A settings blob, device config, integration or storage
|
|
10
|
+
location holds a **marker** where the value used to be:
|
|
12
11
|
|
|
13
|
-
|
|
12
|
+
```json
|
|
13
|
+
{ "$secret": "secret://<owner>/<scope>/<fieldPath>", "v": 1 }
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Long form, with what it protects against and what it does not:
|
|
17
|
+
`docs/architecture/secrets-keychain.md`. Records: D783 (declared by type; never
|
|
18
|
+
on argv, env or logs), D787 (marker contract), D788 (master key location is
|
|
19
|
+
configuration), D789 (the admin form round-trips the marker), D797 (the hub's
|
|
20
|
+
own secrets), D798 (an addon reads its own settings resolved).
|
|
21
|
+
|
|
22
|
+
> Skill names with no file in this pack (`camstack-ui`, `camstack-ui-admin`,
|
|
23
|
+
> `camstack-server-change`, `camstack-diagnose`, `camstack-publish-ci`) are
|
|
24
|
+
> server-repository skills under `.claude/skills/`; this text stands on its own.
|
|
25
|
+
|
|
26
|
+
## 1. Workflow
|
|
27
|
+
|
|
28
|
+
1. **Declare** every secret by its schema TYPE (§2). Never rely on a key name.
|
|
29
|
+
2. **Read** it the resolved way and handle "stored but unavailable" (§3).
|
|
30
|
+
3. **Hand it to a child** only through an owner-only file (§4) — never env,
|
|
31
|
+
never argv.
|
|
32
|
+
4. **Keep it out of logs, fixtures and the repository** (§5).
|
|
33
|
+
5. **Render** it with the library secret field (§6).
|
|
34
|
+
6. **Run the guards** (§7) and paste the done-gate (§8).
|
|
35
|
+
|
|
36
|
+
## 2. Declare it — by type, never by name
|
|
14
37
|
|
|
15
38
|
- Config-UI field: `type: 'password'`, or `secret: true` on a `text` /
|
|
16
39
|
`textarea` field. Zod device-config field: `.meta({ secret: true })`.
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
-
|
|
20
|
-
`
|
|
21
|
-
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
40
|
+
`storage: 'inline'` opts a field OUT (a masked non-secret). A JSON textarea
|
|
41
|
+
that holds a secret stays inline — the keychain stores strings.
|
|
42
|
+
- A declared field is keychain-backed by `BaseAddon` with no further code: the
|
|
43
|
+
blob stores the marker, `this.config` holds the value.
|
|
44
|
+
- **Hidden state that is a credential** — a token you mint or receive, never a
|
|
45
|
+
form field — goes in `protected readonly secretStatePaths = [...]`
|
|
46
|
+
(`'ingressToken'`, `'identity.pincode'`, `'tokens[userId].accessToken'`).
|
|
47
|
+
- **An array of rows with a secret** needs an id field (`itemIdKey`, default
|
|
48
|
+
`'id'`): refs are addressed by item id, so a reorder keeps them.
|
|
49
|
+
- A credential-named field that is NOT declared fails
|
|
50
|
+
`scripts/check-secret-fields-declared.ts`.
|
|
51
|
+
|
|
52
|
+
## 3. Read and clear it
|
|
53
|
+
|
|
54
|
+
- **Every read of your own settings answers VALUES** — `this.config`,
|
|
55
|
+
`this.state()`, `this.resolveGlobalStore()`, `this.readStoredGlobalKey()`,
|
|
56
|
+
every `this.ctx.settings.read*` — never a marker (D798). Writing back what you
|
|
57
|
+
read is a no-op (no keychain version, no `onConfigChanged`).
|
|
58
|
+
- **Never touch the `initialize(context)` parameter's settings** — that is the
|
|
59
|
+
kernel's unwrapped view and answers markers. Call `super.initialize(context)`
|
|
60
|
+
and use `this.ctx`. `scripts/check-no-raw-secret-read.ts` fails on it.
|
|
61
|
+
- **Locked is never empty.** A value the keychain cannot serve right now reads
|
|
62
|
+
as its MARKER (`isSecretMarker(v)` is true; it is listed in
|
|
63
|
+
`this.unresolvedSecrets`) — never as `''` or absent. Run degraded; do NOT
|
|
64
|
+
mint a replacement. An addon write over a secret it could not read is refused
|
|
65
|
+
(`SecretOverwriteRefusedError`), so "absent → mint → save" cannot loop.
|
|
66
|
+
- **`''` never clears a secret.** To forget one: `this.clearSecrets(['key'])`.
|
|
67
|
+
|
|
68
|
+
## 4. Never through the environment or argv — files for children
|
|
69
|
+
|
|
70
|
+
- **No secret reaches any process through its environment** — not an addon
|
|
71
|
+
credential, not the session signing key, not the cluster secret, not "an
|
|
72
|
+
optional token for power users" (D797 removed `HF_TOKEN`,
|
|
73
|
+
`CAMSTACK_SECRET_KEY` and the like). A credential is a declared field, read
|
|
74
|
+
from your config.
|
|
75
|
+
- The hub's own secrets live in the keychain under owner `system`; an agent's
|
|
76
|
+
cluster secret lives in its own `agent.json` (0600). The keychain master key
|
|
77
|
+
comes from `keychain.keyFile` in `config.yaml`, the desktop app's OS
|
|
78
|
+
keychain, or the default key file — never an env var (D788).
|
|
79
|
+
- **A child process that needs a credential gets an owner-only FILE**: a fresh
|
|
80
|
+
`0700` temp dir, the value written with `mode: 0o600`, the PATH passed on
|
|
81
|
+
argv (`--auth-key=file:<path>`, `--token-file <path>`), the dir removed when
|
|
82
|
+
the child settles — success or failure. Worked example:
|
|
83
|
+
`packages/addon-tailscale/src/auth-key-file.ts`; also
|
|
84
|
+
`packages/addon-cloudflare/src/tunnel/cloudflared-invocation.ts`.
|
|
85
|
+
- A URL with embedded credentials is a secret on argv too: build it for the
|
|
86
|
+
child from a file or a pipe the child reads, never from a string you log.
|
|
87
|
+
- Client-side developer tooling is different: the `camstack` CLI's
|
|
88
|
+
`$CAMSTACK_TOKEN` / `--token-file` and `scripts/hub/hub.mjs`'s credential chain
|
|
89
|
+
(`--token-file`, the 0600 admin token file, the `camstack login` session) are a developer's own credentials on their own machine,
|
|
90
|
+
not server-side secrets.
|
|
91
|
+
|
|
92
|
+
## 5. Logs, fixtures, the repository
|
|
93
|
+
|
|
94
|
+
- A value your addon resolved from the keychain is scrubbed from its logs
|
|
95
|
+
automatically; a message you BUILD with it (an error string from a child,
|
|
96
|
+
`Command failed: …`) is your job — pass it through a scrubber.
|
|
97
|
+
- Recorded fixtures never carry a live camera credential
|
|
98
|
+
(`scripts/check-no-credential-urls-in-fixtures.ts`).
|
|
99
|
+
- No OAuth client secret in a publishable package
|
|
100
|
+
(`scripts/check-no-client-secrets.ts`) and no private key of any kind
|
|
101
|
+
(`scripts/check-no-service-account-keys.ts`) — every package is public on
|
|
102
|
+
npm. A secret that must exist server-side for a public integration lives
|
|
103
|
+
behind a broker, not in source.
|
|
104
|
+
- A secret that was ever committed or published is rotated, not just deleted.
|
|
105
|
+
|
|
106
|
+
## 6. In the UI
|
|
107
|
+
|
|
108
|
+
The secret field is `SecretFieldControl` (`packages/ui-library/src/composites/config-secret-field.tsx`) plus
|
|
109
|
+
`PasswordInput` from the ui-library; the admin form shows "set", never the
|
|
110
|
+
value (D789), and a reveal happens in a dialog. Details: `camstack-ui-admin`.
|
|
111
|
+
|
|
112
|
+
## 7. Guards — run the ones you touched
|
|
44
113
|
|
|
45
114
|
```bash
|
|
46
115
|
npx tsx scripts/check-secret-fields-declared.ts
|
|
47
116
|
npx tsx scripts/check-no-raw-secret-read.ts
|
|
48
117
|
npx tsx scripts/check-no-client-secrets.ts
|
|
118
|
+
npx tsx scripts/check-no-service-account-keys.ts
|
|
119
|
+
npx tsx scripts/check-no-credential-urls-in-fixtures.ts
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Operators moving an old hub's plaintext into the keychain use the one-off
|
|
123
|
+
`scripts/ops/keychain-migrate-hub.mjs`; the product ships no migration code.
|
|
124
|
+
A lost master key is recovered with the `RESET_KEYCHAIN` trigger file
|
|
125
|
+
(D799, `docs/architecture/secrets-keychain.md` §"A lost master key").
|
|
126
|
+
|
|
127
|
+
## 8. Done-gate — paste it before "done"
|
|
128
|
+
|
|
129
|
+
```
|
|
130
|
+
SECRETS DONE — <addon / field>
|
|
131
|
+
declared: <field → password | secret:true | .meta({secret:true}) | secretStatePaths entry>
|
|
132
|
+
read path: <this.config / resolved reads; marker (unavailable) handled as: …>
|
|
133
|
+
children: <0600 file via <helper> | no child needs it>
|
|
134
|
+
env/argv: none — <grep result for the value's variable on spawn calls>
|
|
135
|
+
guards: <the commands above and their result>
|
|
49
136
|
```
|