@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.
Files changed (42) hide show
  1. package/dist/hub/admin-token-store.d.ts +53 -0
  2. package/dist/hub/admin-token-store.d.ts.map +1 -0
  3. package/dist/hub/admin-token-store.js +139 -0
  4. package/dist/hub/credentials.d.ts +53 -0
  5. package/dist/hub/credentials.d.ts.map +1 -0
  6. package/dist/hub/credentials.js +151 -0
  7. package/dist/hub/hub-address.d.ts +24 -0
  8. package/dist/hub/hub-address.d.ts.map +1 -0
  9. package/dist/hub/hub-address.js +87 -0
  10. package/dist/hub/hub-client.d.ts +57 -0
  11. package/dist/hub/hub-client.d.ts.map +1 -0
  12. package/dist/hub/hub-client.js +176 -0
  13. package/dist/hub/hub-tls.d.ts +16 -0
  14. package/dist/hub/hub-tls.d.ts.map +1 -0
  15. package/dist/hub/hub-tls.js +67 -0
  16. package/dist/hub/hub-url.d.ts +17 -0
  17. package/dist/hub/hub-url.d.ts.map +1 -0
  18. package/dist/hub/hub-url.js +54 -0
  19. package/dist/hub/session-store.d.ts +55 -0
  20. package/dist/hub/session-store.d.ts.map +1 -0
  21. package/dist/hub/session-store.js +178 -0
  22. package/dist/hub-discovery/hub-candidates.d.ts +53 -0
  23. package/dist/hub-discovery/hub-candidates.d.ts.map +1 -0
  24. package/dist/hub-discovery/hub-candidates.js +103 -0
  25. package/dist/hub-discovery/index.d.ts +4 -0
  26. package/dist/hub-discovery/index.d.ts.map +1 -0
  27. package/dist/hub-discovery/index.js +3 -0
  28. package/dist/hub-discovery/mdns-browse.d.ts +51 -0
  29. package/dist/hub-discovery/mdns-browse.d.ts.map +1 -0
  30. package/dist/hub-discovery/mdns-browse.js +116 -0
  31. package/dist/index.d.ts +15 -2
  32. package/dist/index.d.ts.map +1 -1
  33. package/dist/index.js +11 -2
  34. package/dist/scaffold/addon.d.ts.map +1 -1
  35. package/dist/scaffold/addon.js +6 -0
  36. package/dist/types.d.ts +6 -1
  37. package/dist/types.d.ts.map +1 -1
  38. package/package.json +10 -1
  39. package/skills/README.md +3 -0
  40. package/skills/camstack-addon.md +376 -98
  41. package/skills/camstack-capability.md +184 -77
  42. 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 (*.cap.ts) — necessity, cardinality, codegen and the hand-edits it cannot do, providers and bindings, CAP_INPUT_DEFAULTS, and what must be published for it to reach a hub.
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** change: codegen, and in production it reaches
21
- nodes only through a published `@camstack/server`. Prefer:
22
-
23
- - Enumerating providers → `addons.listCapabilityProviders({ capName })`
24
- - Addon config → `globalSettingsSchema()` + `addon-settings`
25
- - Enable/disable a provider → `addons.setCapabilityProviderEnabled`
26
- - Additive field on an existing method → redeploy the providing addon only
27
-
28
- Mint a cap when several addons must implement or call genuinely new behaviour.
29
-
30
- ## 1. Define it
31
-
32
- `packages/types/src/capabilities/<name>.cap.ts`:
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', // or 'device'
38
- mode: 'singleton', // or 'collection'
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
- - Mount is derived from mode unless `server-provided` / `hub-only` / `skip`.
46
- - `internal: true` + `mount: { kind: 'skip' }` = in-process only, no tRPC route.
47
- - `internal: true` without skip still gets a router; unannotated methods floor
48
- to `auth: 'admin'`.
49
- - `runtimeState` must include `lastFetchedAt: z.number()`.
50
- - Behavioural metadata lives **only** here.
51
- - A cap hosted on every node and called with `{nodeId}` is `mode: 'singleton'`
52
- — never `'per-node'`, which codegen does not wire (every call then answers
53
- "provider not available").
54
- - Give every method an explicit `auth` tier; the tier baseline is checked
55
- (`npx tsx scripts/check-method-tiers.ts --update` to accept a deliberate change).
56
-
57
- ## 2. Two hand-edits codegen cannot do
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. Value re-export of the capability + types.
62
- 2. Member of the `AnyCapability` union.
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
- Miss either → compiles but invisible to consumers.
109
+ `scripts/check-capability-union-complete.ts` (inside codegen) refuses a miss.
65
110
 
66
- ## 3. Codegen
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
- npm run codegen
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
- Skipping is silent drift. CI `codegen:check` catches it later.
73
-
74
- Input `.default()`s run only where the router parses them. A call from an addon
75
- through `ctx.api` gets codegen's `CAP_INPUT_DEFAULTS` instead, which carries
76
- TOP-LEVEL defaults only — a nested default arrives `undefined` on that path.
77
-
78
- ## 4. Implement and declare
79
-
80
- - System: `context.registerProvider(cap, impl)` / return from `onInitialize`.
81
- - Device: `ctx.registerNativeCap(cap, impl)` from a `BaseDevice` subclass.
82
- - Declare the capability **by name** in the addon manifest.
83
- - Flat providers — no nested sub-objects.
84
- - If agents must expose the cap, also add it to the agent-side curated list in
85
- `server/backend` (hand-maintained).
86
- - Two addons implementing one cap both register unconditionally; the operator
87
- picks by binding (`capabilities.setActiveSingleton`, the collection enable
88
- toggle, or a device binding) — never a private setting.
89
- - Never hand-write an interface over a cap; narrow the generated client
90
- (`Pick<AddonApi['foo'], …>`). A hand copy keeps compiling after a method is
91
- removed and fails at runtime.
92
-
93
- ## 5. Spec + docs
94
-
95
- Router tests under `server/backend/src/__tests__/cap-routers/`. Generated
96
- `docs/reference/capabilities.md` updates on commit. Append
97
- `docs/history/sessions.md`; write a decision when you rejected a real
98
- alternative.
99
-
100
- ## 6. Ship
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 a CamStack addon — a password, token or key field, hidden credential state, or a secret a spawned child process needs. Declared by schema type, stored in the keychain, never in the environment or on argv.
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 in an addon
6
+ # Secrets and the keychain
7
7
 
8
- Every password, token and key lives in the hub's keychain. A settings blob
9
- holds a marker (`{ "$secret": "secret://<owner>/<scope>/<field>", "v": 1 }`)
10
- where the value used to be. Long form: `docs/architecture/secrets-keychain.md`
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
- ## 1. Declare it by type, never by name
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
- - A declared field is keychain-backed by `BaseAddon`: `this.config` holds the
18
- value, the stored blob holds the marker.
19
- - Hidden credential state (a token you mint or receive) goes in
20
- `protected readonly secretStatePaths = [...]`.
21
- - An array of rows with a secret needs an id field (`itemIdKey`, default `'id'`).
22
-
23
- ## 2. Read and clear it
24
-
25
- - Your own reads (`this.config`, `this.ctx.settings.read*`, …) answer VALUES.
26
- Never read the `initialize(context)` parameter's settings — that view holds
27
- markers; call `super.initialize(context)` and use `this.ctx`.
28
- - A value the keychain cannot serve right now reads as its marker
29
- (`isSecretMarker(v)`) — "stored, unavailable". Run degraded; never mint a
30
- replacement.
31
- - `''` never clears a secret: `this.clearSecrets(['key'])`.
32
-
33
- ## 3. Never the environment, never argv
34
-
35
- - No credential is read from an env var, not even an optional "power user"
36
- token.
37
- - A child process gets a FILE: a fresh 0700 temp dir, the value written with
38
- mode 0600, the path on argv (`--token-file <path>`), the dir removed when the
39
- child exits. Build error messages from a child's output through a scrubber.
40
- - No client secret or private key in a publishable package — every package is
41
- public on npm.
42
-
43
- ## 4. Check
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
  ```