clinkx 1.2.0 → 1.4.0
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/CHANGELOG.md +60 -0
- package/README.md +17 -8
- package/clinkx-workflows/dist/architecture-arena/admission.d.ts +16 -0
- package/clinkx-workflows/dist/architecture-arena/admission.js +107 -0
- package/clinkx-workflows/dist/architecture-arena/admission.js.map +1 -0
- package/clinkx-workflows/dist/architecture-arena/contract.d.ts +1368 -0
- package/clinkx-workflows/dist/architecture-arena/contract.js +254 -0
- package/clinkx-workflows/dist/architecture-arena/contract.js.map +1 -0
- package/clinkx-workflows/dist/architecture-arena/runtime.d.ts +53 -0
- package/clinkx-workflows/dist/architecture-arena/runtime.js +511 -0
- package/clinkx-workflows/dist/architecture-arena/runtime.js.map +1 -0
- package/clinkx-workflows/dist/architecture-comparison/admission.d.ts +17 -1
- package/clinkx-workflows/dist/architecture-comparison/admission.js +27 -4
- package/clinkx-workflows/dist/architecture-comparison/admission.js.map +1 -1
- package/clinkx-workflows/dist/architecture-comparison/contract.d.ts +59 -62
- package/clinkx-workflows/dist/architecture-comparison/contract.js +4 -21
- package/clinkx-workflows/dist/architecture-comparison/contract.js.map +1 -1
- package/clinkx-workflows/dist/architecture-comparison/runtime.d.ts +4 -3
- package/clinkx-workflows/dist/architecture-comparison/runtime.js +22 -67
- package/clinkx-workflows/dist/architecture-comparison/runtime.js.map +1 -1
- package/clinkx-workflows/dist/artifacts.d.ts +19 -4
- package/clinkx-workflows/dist/artifacts.js +16 -7
- package/clinkx-workflows/dist/artifacts.js.map +1 -1
- package/clinkx-workflows/dist/backend.d.ts +30 -0
- package/clinkx-workflows/dist/child-env.d.ts +3 -0
- package/clinkx-workflows/dist/child-env.js +11 -0
- package/clinkx-workflows/dist/child-env.js.map +1 -1
- package/clinkx-workflows/dist/clink-client.d.ts +8 -2
- package/clinkx-workflows/dist/clink-client.js +4 -2
- package/clinkx-workflows/dist/clink-client.js.map +1 -1
- package/clinkx-workflows/dist/context-preflight.d.ts +6 -0
- package/clinkx-workflows/dist/context-preflight.js.map +1 -1
- package/clinkx-workflows/dist/council-execution-policy.d.ts +3 -1
- package/clinkx-workflows/dist/council-execution-policy.js +4 -0
- package/clinkx-workflows/dist/council-execution-policy.js.map +1 -1
- package/clinkx-workflows/dist/dashboard/api-routes.d.ts +21 -0
- package/clinkx-workflows/dist/dashboard/api-routes.js +27 -0
- package/clinkx-workflows/dist/dashboard/api-routes.js.map +1 -1
- package/clinkx-workflows/dist/dashboard/auth/challenge-store.d.ts +13 -0
- package/clinkx-workflows/dist/dashboard/auth/challenge-store.js.map +1 -1
- package/clinkx-workflows/dist/dashboard/auth/controller.d.ts +27 -0
- package/clinkx-workflows/dist/dashboard/auth/controller.js +262 -23
- package/clinkx-workflows/dist/dashboard/auth/controller.js.map +1 -1
- package/clinkx-workflows/dist/dashboard/auth/settings-step-up.d.ts +62 -0
- package/clinkx-workflows/dist/dashboard/auth/settings-step-up.js +70 -0
- package/clinkx-workflows/dist/dashboard/auth/settings-step-up.js.map +1 -0
- package/clinkx-workflows/dist/dashboard/contracts.d.ts +586 -586
- package/clinkx-workflows/dist/dashboard/progress-report-contract.d.ts +28 -28
- package/clinkx-workflows/dist/dashboard/request-admission.d.ts +6 -0
- package/clinkx-workflows/dist/dashboard/request-admission.js +9 -0
- package/clinkx-workflows/dist/dashboard/request-admission.js.map +1 -1
- package/clinkx-workflows/dist/dashboard/server-factory.js +15 -1
- package/clinkx-workflows/dist/dashboard/server-factory.js.map +1 -1
- package/clinkx-workflows/dist/dashboard/session-log-contract.d.ts +32 -32
- package/clinkx-workflows/dist/dashboard/settings-contract.d.ts +1806 -0
- package/clinkx-workflows/dist/dashboard/settings-contract.js +630 -0
- package/clinkx-workflows/dist/dashboard/settings-contract.js.map +1 -0
- package/clinkx-workflows/dist/dashboard/settings-process-reader.d.ts +48 -0
- package/clinkx-workflows/dist/dashboard/settings-process-reader.js +195 -0
- package/clinkx-workflows/dist/dashboard/settings-process-reader.js.map +1 -0
- package/clinkx-workflows/dist/dashboard/settings-routes.d.ts +87 -0
- package/clinkx-workflows/dist/dashboard/settings-routes.js +690 -0
- package/clinkx-workflows/dist/dashboard/settings-routes.js.map +1 -0
- package/clinkx-workflows/dist/dashboard-ui/assets/index-DSOtuS0p.js +122 -0
- package/clinkx-workflows/dist/dashboard-ui/assets/style-C5guUjwN.css +1 -0
- package/clinkx-workflows/dist/dashboard-ui/index.html +2 -2
- package/clinkx-workflows/dist/delegate-signature.d.ts +4 -3
- package/clinkx-workflows/dist/delegate-signature.js +4 -3
- package/clinkx-workflows/dist/delegate-signature.js.map +1 -1
- package/clinkx-workflows/dist/durable-file-core.d.ts +76 -0
- package/clinkx-workflows/dist/durable-file-core.js +146 -0
- package/clinkx-workflows/dist/durable-file-core.js.map +1 -0
- package/clinkx-workflows/dist/durable-file.d.ts +13 -0
- package/clinkx-workflows/dist/durable-file.js +22 -0
- package/clinkx-workflows/dist/durable-file.js.map +1 -0
- package/clinkx-workflows/dist/engine.d.ts +42 -7
- package/clinkx-workflows/dist/engine.js +196 -24
- package/clinkx-workflows/dist/engine.js.map +1 -1
- package/clinkx-workflows/dist/index.js +68 -2
- package/clinkx-workflows/dist/index.js.map +1 -1
- package/clinkx-workflows/dist/ping-pong/admission.d.ts +127 -0
- package/clinkx-workflows/dist/ping-pong/admission.js +522 -0
- package/clinkx-workflows/dist/ping-pong/admission.js.map +1 -0
- package/clinkx-workflows/dist/ping-pong/contract.d.ts +2539 -0
- package/clinkx-workflows/dist/ping-pong/contract.js +819 -0
- package/clinkx-workflows/dist/ping-pong/contract.js.map +1 -0
- package/clinkx-workflows/dist/ping-pong/control.d.ts +67 -0
- package/clinkx-workflows/dist/ping-pong/control.js +12 -0
- package/clinkx-workflows/dist/ping-pong/control.js.map +1 -0
- package/clinkx-workflows/dist/ping-pong/runtime-handle.d.ts +24 -0
- package/clinkx-workflows/dist/ping-pong/runtime-handle.js +55 -0
- package/clinkx-workflows/dist/ping-pong/runtime-handle.js.map +1 -0
- package/clinkx-workflows/dist/ping-pong/runtime.d.ts +235 -0
- package/clinkx-workflows/dist/ping-pong/runtime.js +1183 -0
- package/clinkx-workflows/dist/ping-pong/runtime.js.map +1 -0
- package/clinkx-workflows/dist/ping-pong/settle.d.ts +57 -0
- package/clinkx-workflows/dist/ping-pong/settle.js +58 -0
- package/clinkx-workflows/dist/ping-pong/settle.js.map +1 -0
- package/clinkx-workflows/dist/ping-pong/sidecar.d.ts +65 -0
- package/clinkx-workflows/dist/ping-pong/sidecar.js +138 -0
- package/clinkx-workflows/dist/ping-pong/sidecar.js.map +1 -0
- package/clinkx-workflows/dist/plan-review/publication.d.ts +2 -1
- package/clinkx-workflows/dist/plan-review/publication.js +5 -6
- package/clinkx-workflows/dist/plan-review/publication.js.map +1 -1
- package/clinkx-workflows/dist/plan-review/snapshot.d.ts +3 -2
- package/clinkx-workflows/dist/plan-review/snapshot.js +8 -8
- package/clinkx-workflows/dist/plan-review/snapshot.js.map +1 -1
- package/clinkx-workflows/dist/recipe-host.d.ts +315 -0
- package/clinkx-workflows/dist/recipe-host.js +183 -0
- package/clinkx-workflows/dist/recipe-host.js.map +1 -0
- package/clinkx-workflows/dist/recipe-seats.d.ts +96 -0
- package/clinkx-workflows/dist/recipe-seats.js +163 -0
- package/clinkx-workflows/dist/recipe-seats.js.map +1 -0
- package/clinkx-workflows/dist/recipe-shared/evidence.d.ts +67 -0
- package/clinkx-workflows/dist/recipe-shared/evidence.js +111 -0
- package/clinkx-workflows/dist/recipe-shared/evidence.js.map +1 -0
- package/clinkx-workflows/dist/reducers/index.d.ts +9 -1
- package/clinkx-workflows/dist/reducers/index.js +30 -0
- package/clinkx-workflows/dist/reducers/index.js.map +1 -1
- package/clinkx-workflows/dist/run-lock-reclaim.d.ts +44 -0
- package/clinkx-workflows/dist/run-lock-reclaim.js +86 -0
- package/clinkx-workflows/dist/run-lock-reclaim.js.map +1 -0
- package/clinkx-workflows/dist/settings/audit.d.ts +101 -0
- package/clinkx-workflows/dist/settings/audit.js +318 -0
- package/clinkx-workflows/dist/settings/audit.js.map +1 -0
- package/clinkx-workflows/dist/settings/bootstrap.d.ts +35 -0
- package/clinkx-workflows/dist/settings/bootstrap.js +52 -0
- package/clinkx-workflows/dist/settings/bootstrap.js.map +1 -0
- package/clinkx-workflows/dist/settings/codec.d.ts +51 -0
- package/clinkx-workflows/dist/settings/codec.js +410 -0
- package/clinkx-workflows/dist/settings/codec.js.map +1 -0
- package/clinkx-workflows/dist/settings/durable-write.d.ts +48 -0
- package/clinkx-workflows/dist/settings/durable-write.js +31 -0
- package/clinkx-workflows/dist/settings/durable-write.js.map +1 -0
- package/clinkx-workflows/dist/settings/index.d.ts +20 -0
- package/clinkx-workflows/dist/settings/index.js +23 -0
- package/clinkx-workflows/dist/settings/index.js.map +1 -0
- package/clinkx-workflows/dist/settings/loader.d.ts +80 -0
- package/clinkx-workflows/dist/settings/loader.js +577 -0
- package/clinkx-workflows/dist/settings/loader.js.map +1 -0
- package/clinkx-workflows/dist/settings/lock.d.ts +108 -0
- package/clinkx-workflows/dist/settings/lock.js +344 -0
- package/clinkx-workflows/dist/settings/lock.js.map +1 -0
- package/clinkx-workflows/dist/settings/paths.d.ts +65 -0
- package/clinkx-workflows/dist/settings/paths.js +173 -0
- package/clinkx-workflows/dist/settings/paths.js.map +1 -0
- package/clinkx-workflows/dist/settings/process-heartbeat.d.ts +47 -0
- package/clinkx-workflows/dist/settings/process-heartbeat.js +305 -0
- package/clinkx-workflows/dist/settings/process-heartbeat.js.map +1 -0
- package/clinkx-workflows/dist/settings/registry.d.ts +178 -0
- package/clinkx-workflows/dist/settings/registry.js +1285 -0
- package/clinkx-workflows/dist/settings/registry.js.map +1 -0
- package/clinkx-workflows/dist/settings/schema.d.ts +404 -0
- package/clinkx-workflows/dist/settings/schema.js +415 -0
- package/clinkx-workflows/dist/settings/schema.js.map +1 -0
- package/clinkx-workflows/dist/settings/store.d.ts +157 -0
- package/clinkx-workflows/dist/settings/store.js +842 -0
- package/clinkx-workflows/dist/settings/store.js.map +1 -0
- package/clinkx-workflows/dist/state-schema.d.ts +11 -0
- package/clinkx-workflows/dist/state-schema.js +4 -1
- package/clinkx-workflows/dist/state-schema.js.map +1 -1
- package/clinkx-workflows/dist/state.d.ts +178 -3
- package/clinkx-workflows/dist/state.js +618 -83
- package/clinkx-workflows/dist/state.js.map +1 -1
- package/clinkx-workflows/dist/stdio-entry.d.ts +2 -0
- package/clinkx-workflows/dist/stdio-entry.js +52 -0
- package/clinkx-workflows/dist/stdio-entry.js.map +1 -0
- package/clinkx-workflows/dist/transport.d.ts +2 -1
- package/clinkx-workflows/dist/transport.js +5 -0
- package/clinkx-workflows/dist/transport.js.map +1 -1
- package/clinkx-workflows/dist/validators/architecture-arena.d.ts +6 -0
- package/clinkx-workflows/dist/validators/architecture-arena.js +16 -0
- package/clinkx-workflows/dist/validators/architecture-arena.js.map +1 -0
- package/clinkx-workflows/dist/validators/index.js +4 -0
- package/clinkx-workflows/dist/validators/index.js.map +1 -1
- package/clinkx-workflows/dist/validators/ping-pong.d.ts +6 -0
- package/clinkx-workflows/dist/validators/ping-pong.js +10 -0
- package/clinkx-workflows/dist/validators/ping-pong.js.map +1 -0
- package/clinkx-workflows/dist/workflow-tools.d.ts +51 -5
- package/clinkx-workflows/dist/workflow-tools.js +785 -34
- package/clinkx-workflows/dist/workflow-tools.js.map +1 -1
- package/clinkx-workflows/dist/workflow-verification-contract.d.ts +4 -4
- package/clinkx-workflows/templates/architecture-arena/candidate.txt +39 -0
- package/clinkx-workflows/templates/architecture-arena/judge.txt +34 -0
- package/clinkx-workflows/templates/ping-pong/implement.txt +14 -0
- package/clinkx-workflows/templates/ping-pong/remediate.txt +14 -0
- package/clinkx-workflows/templates/ping-pong/review.txt +27 -0
- package/clinkx-workflows/workflows/architecture-arena.yaml +127 -0
- package/clinkx-workflows/workflows/ping-pong.yaml +158 -0
- package/dist/context-builder/bundle.js +4 -3
- package/dist/context-builder/bundle.js.map +1 -1
- package/dist/context-builder/delegate-packet.d.ts +1 -0
- package/dist/context-builder/delegate-packet.js +66 -7
- package/dist/context-builder/delegate-packet.js.map +1 -1
- package/dist/context-builder/delegate-validation.d.ts +12 -3
- package/dist/context-builder/delegate-validation.js +23 -13
- package/dist/context-builder/delegate-validation.js.map +1 -1
- package/dist/context-builder/external-gaps.d.ts +14 -3
- package/dist/context-builder/external-gaps.js +124 -18
- package/dist/context-builder/external-gaps.js.map +1 -1
- package/dist/context-builder/handler.js +108 -191
- package/dist/context-builder/handler.js.map +1 -1
- package/dist/context-builder/review-coverage.js +27 -1
- package/dist/context-builder/review-coverage.js.map +1 -1
- package/dist/context-builder/secrets.js +1 -1
- package/dist/context-builder/secrets.js.map +1 -1
- package/dist/context-builder/versions.d.ts +10 -4
- package/dist/context-builder/versions.js +10 -4
- package/dist/context-builder/versions.js.map +1 -1
- package/dist/context-builder/workflow-runner.js +33 -24
- package/dist/context-builder/workflow-runner.js.map +1 -1
- package/dist/dashboard-cli.d.ts +2 -0
- package/dist/dashboard-cli.js +197 -58
- package/dist/dashboard-cli.js.map +1 -1
- package/dist/dashboard-companion/client.d.ts +10 -0
- package/dist/dashboard-companion/client.js +43 -1
- package/dist/dashboard-companion/client.js.map +1 -1
- package/dist/dashboard-companion/config.d.ts +19 -1
- package/dist/dashboard-companion/config.js +104 -3
- package/dist/dashboard-companion/config.js.map +1 -1
- package/dist/dashboard-companion/protocol.d.ts +16 -0
- package/dist/dashboard-companion/protocol.js +55 -1
- package/dist/dashboard-companion/protocol.js.map +1 -1
- package/dist/dashboard-companion/workstation-binding.d.ts +69 -0
- package/dist/dashboard-companion/workstation-binding.js +192 -0
- package/dist/dashboard-companion/workstation-binding.js.map +1 -0
- package/dist/dashboard-gateway/admin-cli.d.ts +10 -0
- package/dist/dashboard-gateway/admin-cli.js +266 -0
- package/dist/dashboard-gateway/admin-cli.js.map +1 -0
- package/dist/dashboard-gateway/config.d.ts +50 -0
- package/dist/dashboard-gateway/config.js +235 -1
- package/dist/dashboard-gateway/config.js.map +1 -1
- package/dist/dashboard-gateway/connection-registry.d.ts +100 -0
- package/dist/dashboard-gateway/connection-registry.js +228 -0
- package/dist/dashboard-gateway/connection-registry.js.map +1 -0
- package/dist/dashboard-gateway/control-plane/account-auth.d.ts +78 -0
- package/dist/dashboard-gateway/control-plane/account-auth.js +198 -0
- package/dist/dashboard-gateway/control-plane/account-auth.js.map +1 -0
- package/dist/dashboard-gateway/control-plane/billing.d.ts +264 -0
- package/dist/dashboard-gateway/control-plane/billing.js +787 -0
- package/dist/dashboard-gateway/control-plane/billing.js.map +1 -0
- package/dist/dashboard-gateway/control-plane/contracts.d.ts +1293 -0
- package/dist/dashboard-gateway/control-plane/contracts.js +280 -0
- package/dist/dashboard-gateway/control-plane/contracts.js.map +1 -0
- package/dist/dashboard-gateway/control-plane/cookies.d.ts +13 -0
- package/dist/dashboard-gateway/control-plane/cookies.js +46 -0
- package/dist/dashboard-gateway/control-plane/cookies.js.map +1 -0
- package/dist/dashboard-gateway/control-plane/credentials.d.ts +63 -0
- package/dist/dashboard-gateway/control-plane/credentials.js +66 -0
- package/dist/dashboard-gateway/control-plane/credentials.js.map +1 -0
- package/dist/dashboard-gateway/control-plane/entitlements.d.ts +118 -0
- package/dist/dashboard-gateway/control-plane/entitlements.js +329 -0
- package/dist/dashboard-gateway/control-plane/entitlements.js.map +1 -0
- package/dist/dashboard-gateway/control-plane/errors.d.ts +17 -0
- package/dist/dashboard-gateway/control-plane/errors.js +23 -0
- package/dist/dashboard-gateway/control-plane/errors.js.map +1 -0
- package/dist/dashboard-gateway/control-plane/hosts.d.ts +6 -0
- package/dist/dashboard-gateway/control-plane/hosts.js +16 -0
- package/dist/dashboard-gateway/control-plane/hosts.js.map +1 -0
- package/dist/dashboard-gateway/control-plane/http.d.ts +34 -0
- package/dist/dashboard-gateway/control-plane/http.js +331 -0
- package/dist/dashboard-gateway/control-plane/http.js.map +1 -0
- package/dist/dashboard-gateway/control-plane/schema.d.ts +9 -0
- package/dist/dashboard-gateway/control-plane/schema.js +247 -0
- package/dist/dashboard-gateway/control-plane/schema.js.map +1 -0
- package/dist/dashboard-gateway/control-plane/secrets.d.ts +20 -0
- package/dist/dashboard-gateway/control-plane/secrets.js +39 -0
- package/dist/dashboard-gateway/control-plane/secrets.js.map +1 -0
- package/dist/dashboard-gateway/control-plane/store.d.ts +579 -0
- package/dist/dashboard-gateway/control-plane/store.js +1115 -0
- package/dist/dashboard-gateway/control-plane/store.js.map +1 -0
- package/dist/dashboard-gateway/cookie-boundary.d.ts +60 -0
- package/dist/dashboard-gateway/cookie-boundary.js +205 -0
- package/dist/dashboard-gateway/cookie-boundary.js.map +1 -0
- package/dist/dashboard-gateway/index.js +271 -494
- package/dist/dashboard-gateway/index.js.map +1 -1
- package/dist/dashboard-gateway/main.js +7 -2
- package/dist/dashboard-gateway/main.js.map +1 -1
- package/dist/dashboard-gateway/routing.d.ts +43 -0
- package/dist/dashboard-gateway/routing.js +65 -0
- package/dist/dashboard-gateway/routing.js.map +1 -0
- package/dist/dashboard-gateway/tenant-gateway.d.ts +56 -0
- package/dist/dashboard-gateway/tenant-gateway.js +989 -0
- package/dist/dashboard-gateway/tenant-gateway.js.map +1 -0
- package/dist/dashboard-gateway/tenant-main.d.ts +41 -0
- package/dist/dashboard-gateway/tenant-main.js +303 -0
- package/dist/dashboard-gateway/tenant-main.js.map +1 -0
- package/dist/dashboard-gateway/tunnel-errors.d.ts +16 -0
- package/dist/dashboard-gateway/tunnel-errors.js +22 -0
- package/dist/dashboard-gateway/tunnel-errors.js.map +1 -0
- package/dist/dashboard-gateway/tunnel-http.d.ts +21 -0
- package/dist/dashboard-gateway/tunnel-http.js +195 -0
- package/dist/dashboard-gateway/tunnel-http.js.map +1 -0
- package/dist/elaris/config.d.ts +10 -0
- package/dist/elaris/config.js +27 -1
- package/dist/elaris/config.js.map +1 -1
- package/dist/elaris/tools.js +4 -1
- package/dist/elaris/tools.js.map +1 -1
- package/dist/handler.d.ts +6 -0
- package/dist/handler.js +17 -1
- package/dist/handler.js.map +1 -1
- package/dist/index.d.ts +0 -31
- package/dist/index.js +41 -404
- package/dist/index.js.map +1 -1
- package/dist/lib.d.ts +17 -0
- package/dist/lib.js +17 -0
- package/dist/lib.js.map +1 -0
- package/dist/local-clink-backend.d.ts +2 -1
- package/dist/local-clink-backend.js +28 -4
- package/dist/local-clink-backend.js.map +1 -1
- package/dist/parsers/extract.d.ts +19 -1
- package/dist/parsers/extract.js +68 -3
- package/dist/parsers/extract.js.map +1 -1
- package/dist/pipeline.d.ts +17 -1
- package/dist/pipeline.js +34 -6
- package/dist/pipeline.js.map +1 -1
- package/dist/process-group.d.ts +65 -0
- package/dist/process-group.js +153 -0
- package/dist/process-group.js.map +1 -0
- package/dist/progress-report/lock.d.ts +17 -59
- package/dist/progress-report/lock.js +25 -329
- package/dist/progress-report/lock.js.map +1 -1
- package/dist/progress-report/schema.d.ts +23 -23
- package/dist/project-verification/files.js +1 -1
- package/dist/project-verification/files.js.map +1 -1
- package/dist/project-verification/process.js +23 -44
- package/dist/project-verification/process.js.map +1 -1
- package/dist/project-verification/service.js +9 -1
- package/dist/project-verification/service.js.map +1 -1
- package/dist/prompt.d.ts +7 -0
- package/dist/prompt.js +18 -1
- package/dist/prompt.js.map +1 -1
- package/dist/recipe-host/git-trust.d.ts +43 -0
- package/dist/recipe-host/git-trust.js +360 -0
- package/dist/recipe-host/git-trust.js.map +1 -0
- package/dist/recipe-host/git.d.ts +42 -0
- package/dist/recipe-host/git.js +207 -0
- package/dist/recipe-host/git.js.map +1 -0
- package/dist/recipe-host/native-recipe-host.d.ts +127 -0
- package/dist/recipe-host/native-recipe-host.js +880 -0
- package/dist/recipe-host/native-recipe-host.js.map +1 -0
- package/dist/recipe-host/seat-cwd.d.ts +16 -0
- package/dist/recipe-host/seat-cwd.js +170 -0
- package/dist/recipe-host/seat-cwd.js.map +1 -0
- package/dist/runner.d.ts +43 -1
- package/dist/runner.js +234 -35
- package/dist/runner.js.map +1 -1
- package/dist/server.js +84 -5
- package/dist/server.js.map +1 -1
- package/dist/settings-cli/clients.d.ts +137 -0
- package/dist/settings-cli/clients.js +1124 -0
- package/dist/settings-cli/clients.js.map +1 -0
- package/dist/settings-cli/commands.d.ts +67 -0
- package/dist/settings-cli/commands.js +726 -0
- package/dist/settings-cli/commands.js.map +1 -0
- package/dist/settings-cli/format.d.ts +34 -0
- package/dist/settings-cli/format.js +40 -0
- package/dist/settings-cli/format.js.map +1 -0
- package/dist/settings-cli/main.d.ts +18 -0
- package/dist/settings-cli/main.js +256 -0
- package/dist/settings-cli/main.js.map +1 -0
- package/dist/stdio-main.d.ts +73 -0
- package/dist/stdio-main.js +455 -0
- package/dist/stdio-main.js.map +1 -0
- package/docs/configuration.md +362 -40
- package/docs/engineering-recipes.md +291 -0
- package/docs/security.md +234 -6
- package/docs/verification/project-checks.md +24 -2
- package/package.json +6 -2
- package/clinkx-workflows/dist/dashboard-ui/assets/index-BdpmbPps.js +0 -115
- package/clinkx-workflows/dist/dashboard-ui/assets/style-Im5i1iAs.css +0 -1
|
@@ -0,0 +1,842 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Settings store — B1-2. The single writer for the on-disk dashboard settings
|
|
3
|
+
* documents in one settings directory:
|
|
4
|
+
*
|
|
5
|
+
* settings.json (0644, durable-replace) values for non-secret registry keys
|
|
6
|
+
* secrets.json (0600, durable-replace) secret values, its own revision
|
|
7
|
+
* audit.jsonl (0600, O_APPEND) audit.ts
|
|
8
|
+
*
|
|
9
|
+
* Every mutation runs under the cross-process settings lock (B1-1), re-reads
|
|
10
|
+
* the document inside the critical section, and compare-and-swaps on the
|
|
11
|
+
* document revision. `expectedRevision` 0 means "the document is absent".
|
|
12
|
+
*
|
|
13
|
+
* Reads and saves share one classifier and one byte cap with the startup
|
|
14
|
+
* loader (R4): reads go through the loader's hardened file reader
|
|
15
|
+
* (`createNodeSettingsFileReader` — no-follow, regular-file-only, fstat on the
|
|
16
|
+
* opened descriptor, 256 KiB cap) and `classifySettingsDocument`, so a
|
|
17
|
+
* well-formed document with invalid values is still readable AND saveable
|
|
18
|
+
* (per-key tolerance), while saves serialize no more than
|
|
19
|
+
* `MAX_SETTINGS_FILE_BYTES` — a document the loader would refuse to read is
|
|
20
|
+
* never written. Persistence is lossless: the save base is the document's
|
|
21
|
+
* verbatim `raw` entries, so invalid and unknown keys a save does not touch
|
|
22
|
+
* are copied byte-for-byte; secret-class keys inside settings.json are the
|
|
23
|
+
* one exception — they are dropped, never returned, never re-serialized (S2).
|
|
24
|
+
*
|
|
25
|
+
* Publication order is pending-audit → publish → outcome-audit (P3): the
|
|
26
|
+
* `pending` line is durable BEFORE anything is published, so a crash between
|
|
27
|
+
* the two leaves an honest marker instead of a live change with no audit
|
|
28
|
+
* entry. A failed pending append is a clean 503 with nothing published; a
|
|
29
|
+
* failed outcome append reports `published_uncertain` because the bytes are
|
|
30
|
+
* already live.
|
|
31
|
+
*
|
|
32
|
+
* Error surface: `SettingsStoreError` carries a `code` that lines up 1:1 with
|
|
33
|
+
* the dashboard wire error contract (settings-contract.ts) — 409
|
|
34
|
+
* `settings_conflict` on a CAS mismatch, 409 `settings_locked` when the writer
|
|
35
|
+
* lock could not be acquired or held (nothing was published; the message names
|
|
36
|
+
* the `.lock` path and the manual recovery step), 409 `settings_unreadable`
|
|
37
|
+
* for a corrupt
|
|
38
|
+
* document (routine saves refuse; an explicit `recover` save with a matching
|
|
39
|
+
* `expectedDigest` COPIES the corrupt bytes to
|
|
40
|
+
* `settings.json.corrupt-<ts>-<rand>` through the durable writer — the active
|
|
41
|
+
* path is never renamed away, so a failed publication leaves it in place —
|
|
42
|
+
* and then atomically replaces it; when the unreadable state produced no
|
|
43
|
+
* readable bytes at all (over-cap, EACCES, non-regular, symlink) recover
|
|
44
|
+
* REFUSES with manual-move guidance, because no backup can be made), 422
|
|
45
|
+
* with per-key field errors for invalid
|
|
46
|
+
* ops (validated through the registry/codec BEFORE any file is touched), and
|
|
47
|
+
* 503 `settings_unavailable` for EACCES/EROFS/ENOSPC class failures. A
|
|
48
|
+
* `DurablePublishError` after the rename is NOT a rejection: the bytes are
|
|
49
|
+
* live, so the save reports `outcome:"published_uncertain"` and the audit
|
|
50
|
+
* line records it.
|
|
51
|
+
*
|
|
52
|
+
* Secrets rules (TASKS amendment 3): secret values never enter
|
|
53
|
+
* `settings.json`, are never returned, never logged, never hashed and never
|
|
54
|
+
* audited — a secrets save records key names and revisions only, and the
|
|
55
|
+
* secrets document has no digest anywhere in this API (hashing it would hash
|
|
56
|
+
* secret material). A secrets file whose mode allows group/other access is
|
|
57
|
+
* refused: reads treat it as unset (with a warning) and the next save
|
|
58
|
+
* replaces it with a 0600 file.
|
|
59
|
+
*
|
|
60
|
+
* Erasable-syntax TypeScript only: forked test fixtures import this module
|
|
61
|
+
* through Node native type stripping.
|
|
62
|
+
*/
|
|
63
|
+
import { createHash, randomBytes } from "node:crypto";
|
|
64
|
+
import { chmod as nodeChmod } from "node:fs/promises";
|
|
65
|
+
import { join } from "node:path";
|
|
66
|
+
import { getSettingDescriptor, } from "./registry.js";
|
|
67
|
+
import { SECRETS_DOCUMENT_SCHEMA_VERSION, SETTINGS_DOCUMENT_SCHEMA_VERSION, classifySettingsDocument, parseSecretsDocument, } from "./schema.js";
|
|
68
|
+
import { validateSettingValue } from "./codec.js";
|
|
69
|
+
import { createNodeSettingsFileReader, MAX_SETTINGS_FILE_BYTES, } from "./loader.js";
|
|
70
|
+
import { DurablePublishError, DurableSymlinkTargetError, durableWriter, } from "./durable-write.js";
|
|
71
|
+
import { mkdirDurable } from "../durable-file-core.js";
|
|
72
|
+
import { SettingsLockError, withSettingsLock, } from "./lock.js";
|
|
73
|
+
import { SettingsAuditLog, } from "./audit.js";
|
|
74
|
+
// ---------------------------------------------------------------------------
|
|
75
|
+
// Constants
|
|
76
|
+
// ---------------------------------------------------------------------------
|
|
77
|
+
export const SETTINGS_DOCUMENT_FILENAME = "settings.json";
|
|
78
|
+
export const SECRETS_DOCUMENT_FILENAME = "secrets.json";
|
|
79
|
+
/** Settings documents are world-readable (the dashboard container reads them as another user); secrets never are. */
|
|
80
|
+
export const SETTINGS_DIR_MODE = 0o700;
|
|
81
|
+
export const SETTINGS_DOCUMENT_MODE = 0o644;
|
|
82
|
+
export const SECRETS_DOCUMENT_MODE = 0o600;
|
|
83
|
+
/** Parity with the wire contract's MAX_SETTINGS_OPS_PER_SAVE / MAX_SETTINGS_SECRET_CHARS. */
|
|
84
|
+
export const MAX_OPS_PER_SAVE = 64;
|
|
85
|
+
export const MAX_SECRET_VALUE_CHARS = 4096;
|
|
86
|
+
const FS_UNAVAILABLE_CODES = new Set(["EACCES", "EPERM", "EROFS", "ENOSPC", "EDQUOT", "EIO"]);
|
|
87
|
+
const REASON_MAX_CHARS = 256;
|
|
88
|
+
const FIELD_MESSAGE_MAX_CHARS = 512;
|
|
89
|
+
/**
|
|
90
|
+
* Mirrors SETTINGS_ERROR_HTTP_STATUS in the dashboard wire contract, including
|
|
91
|
+
* the `settings_unreadable` 409 being added to it in this wave.
|
|
92
|
+
*/
|
|
93
|
+
const STATUS_BY_CODE = Object.freeze({
|
|
94
|
+
settings_conflict: 409,
|
|
95
|
+
// Q1: lock acquisition failed — nothing was published, but this is NOT a CAS
|
|
96
|
+
// conflict; its own code so the dashboard can show the lock guidance
|
|
97
|
+
// instead of the "another writer saved" dialog.
|
|
98
|
+
settings_locked: 409,
|
|
99
|
+
settings_unreadable: 409,
|
|
100
|
+
settings_invalid: 422,
|
|
101
|
+
settings_unavailable: 503,
|
|
102
|
+
});
|
|
103
|
+
export class SettingsStoreError extends Error {
|
|
104
|
+
code;
|
|
105
|
+
status;
|
|
106
|
+
fieldErrors;
|
|
107
|
+
/** Current document revision, on a CAS conflict, so the caller can retry. */
|
|
108
|
+
expectedRevision;
|
|
109
|
+
/**
|
|
110
|
+
* Digest of the current (unreadable) settings bytes. Secret documents never
|
|
111
|
+
* expose a digest, so this is only ever set for the settings document.
|
|
112
|
+
*/
|
|
113
|
+
digest;
|
|
114
|
+
constructor(code, message, details = {}) {
|
|
115
|
+
super(message);
|
|
116
|
+
this.name = "SettingsStoreError";
|
|
117
|
+
this.code = code;
|
|
118
|
+
this.status = STATUS_BY_CODE[code];
|
|
119
|
+
this.fieldErrors = details.fieldErrors == null || details.fieldErrors.length === 0
|
|
120
|
+
? undefined
|
|
121
|
+
: details.fieldErrors;
|
|
122
|
+
this.expectedRevision = details.expectedRevision;
|
|
123
|
+
this.digest = details.digest;
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
const nodeFs = {
|
|
127
|
+
chmod: async (path, mode) => await nodeChmod(path, mode),
|
|
128
|
+
};
|
|
129
|
+
// ---------------------------------------------------------------------------
|
|
130
|
+
// Helpers
|
|
131
|
+
// ---------------------------------------------------------------------------
|
|
132
|
+
function sha256Hex(bytes) {
|
|
133
|
+
return createHash("sha256").update(bytes).digest("hex");
|
|
134
|
+
}
|
|
135
|
+
function errnoCode(error) {
|
|
136
|
+
return typeof error === "object" && error !== null && "code" in error
|
|
137
|
+
? String(error.code)
|
|
138
|
+
: undefined;
|
|
139
|
+
}
|
|
140
|
+
function capReason(reason) {
|
|
141
|
+
return reason.length <= REASON_MAX_CHARS
|
|
142
|
+
? reason
|
|
143
|
+
: `${reason.slice(0, REASON_MAX_CHARS - 15)}…[truncated]`;
|
|
144
|
+
}
|
|
145
|
+
function capMessage(message) {
|
|
146
|
+
return message.length <= FIELD_MESSAGE_MAX_CHARS
|
|
147
|
+
? message
|
|
148
|
+
: `${message.slice(0, FIELD_MESSAGE_MAX_CHARS - 15)}…[truncated]`;
|
|
149
|
+
}
|
|
150
|
+
function stripKeyPrefix(key, message) {
|
|
151
|
+
const prefix = `${key}: `;
|
|
152
|
+
return message.startsWith(prefix) ? message.slice(prefix.length) : message;
|
|
153
|
+
}
|
|
154
|
+
function readerFailureReason(filename, code) {
|
|
155
|
+
switch (code) {
|
|
156
|
+
case "SYMLINK":
|
|
157
|
+
return `${filename} is a symbolic link`;
|
|
158
|
+
case "NOT_REGULAR":
|
|
159
|
+
return `${filename} is not a regular file`;
|
|
160
|
+
case "TOO_LARGE":
|
|
161
|
+
return `${filename} is larger than ${String(MAX_SETTINGS_FILE_BYTES)} bytes`;
|
|
162
|
+
case "UNREADABLE":
|
|
163
|
+
return `${filename} could not be read`;
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
function schemaVersionOf(parsed) {
|
|
167
|
+
if (typeof parsed !== "object" || parsed === null)
|
|
168
|
+
return "";
|
|
169
|
+
const found = parsed.schema_version;
|
|
170
|
+
return typeof found === "string" ? found : "";
|
|
171
|
+
}
|
|
172
|
+
/** Ops are validated through the registry + codec BEFORE any file is touched. */
|
|
173
|
+
function validateOps(ops, opts) {
|
|
174
|
+
const errors = [];
|
|
175
|
+
if (ops.length < 1) {
|
|
176
|
+
errors.push({ key: "(ops)", message: "at least one op is required" });
|
|
177
|
+
}
|
|
178
|
+
if (ops.length > MAX_OPS_PER_SAVE) {
|
|
179
|
+
errors.push({ key: "(ops)", message: `at most ${String(MAX_OPS_PER_SAVE)} ops are allowed per save` });
|
|
180
|
+
}
|
|
181
|
+
for (const op of ops) {
|
|
182
|
+
if (op.action !== "set" && op.action !== "unset") {
|
|
183
|
+
errors.push({ key: op.key, message: capMessage(`action must be "set" or "unset" (got ${JSON.stringify(op.action)})`) });
|
|
184
|
+
continue;
|
|
185
|
+
}
|
|
186
|
+
// Own-property lookup only: "__proto__"/"constructor"/"toString" resolve
|
|
187
|
+
// no descriptor and are rejected as unknown keys (S1).
|
|
188
|
+
const descriptor = getSettingDescriptor(op.key);
|
|
189
|
+
if (opts.secrets) {
|
|
190
|
+
if (descriptor == null || descriptor.class !== "secret") {
|
|
191
|
+
errors.push({ key: op.key, message: capMessage(`${op.key} is not a secret-class settings key`) });
|
|
192
|
+
continue;
|
|
193
|
+
}
|
|
194
|
+
if (op.action === "set") {
|
|
195
|
+
if (op.value == null) {
|
|
196
|
+
errors.push({ key: op.key, message: "set ops require a value" });
|
|
197
|
+
}
|
|
198
|
+
else if (typeof op.value !== "string") {
|
|
199
|
+
errors.push({ key: op.key, message: "secret values must be strings" });
|
|
200
|
+
}
|
|
201
|
+
else if (op.value.trim() === "") {
|
|
202
|
+
errors.push({ key: op.key, message: "secret value must be non-empty" });
|
|
203
|
+
}
|
|
204
|
+
else if (op.value.length > MAX_SECRET_VALUE_CHARS) {
|
|
205
|
+
errors.push({
|
|
206
|
+
key: op.key,
|
|
207
|
+
message: `secret value must be at most ${String(MAX_SECRET_VALUE_CHARS)} characters`,
|
|
208
|
+
});
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
else if (op.value != null) {
|
|
212
|
+
errors.push({ key: op.key, message: "unset ops must not carry a value" });
|
|
213
|
+
}
|
|
214
|
+
continue;
|
|
215
|
+
}
|
|
216
|
+
if (descriptor == null) {
|
|
217
|
+
errors.push({ key: op.key, message: capMessage(`unknown settings key ${op.key}`) });
|
|
218
|
+
continue;
|
|
219
|
+
}
|
|
220
|
+
if (descriptor.class === "secret") {
|
|
221
|
+
errors.push({ key: op.key, message: capMessage(`secret key ${op.key} must be saved through saveSecrets`) });
|
|
222
|
+
continue;
|
|
223
|
+
}
|
|
224
|
+
if (op.action === "set") {
|
|
225
|
+
if (op.value == null) {
|
|
226
|
+
errors.push({ key: op.key, message: "set ops require a value" });
|
|
227
|
+
}
|
|
228
|
+
else {
|
|
229
|
+
const error = validateSettingValue(descriptor, op.value);
|
|
230
|
+
if (error != null) {
|
|
231
|
+
errors.push({ key: op.key, message: capMessage(stripKeyPrefix(op.key, error)) });
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
else if (op.value != null) {
|
|
236
|
+
errors.push({ key: op.key, message: "unset ops must not carry a value" });
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
return errors;
|
|
240
|
+
}
|
|
241
|
+
/**
|
|
242
|
+
* The lossless save base (R4): the document's verbatim `raw` entries minus the
|
|
243
|
+
* secret-class keys (never re-serialized, S2) minus the op keys (the ops
|
|
244
|
+
* re-write them). Null-prototype, so a raw `"__proto__"` own entry stays an
|
|
245
|
+
* own data entry copied by name (S1).
|
|
246
|
+
*/
|
|
247
|
+
function buildSaveBase(raw, ops) {
|
|
248
|
+
const opKeys = new Set(ops.map((op) => op.key));
|
|
249
|
+
const base = Object.create(null);
|
|
250
|
+
for (const [key, value] of Object.entries(raw)) {
|
|
251
|
+
if (opKeys.has(key))
|
|
252
|
+
continue;
|
|
253
|
+
const descriptor = getSettingDescriptor(key);
|
|
254
|
+
if (descriptor != null && descriptor.class === "secret")
|
|
255
|
+
continue;
|
|
256
|
+
base[key] = value;
|
|
257
|
+
}
|
|
258
|
+
return base;
|
|
259
|
+
}
|
|
260
|
+
function applyOps(base, ops) {
|
|
261
|
+
// Null-prototype copy: assignment below can only ever create own properties,
|
|
262
|
+
// even for prototype-shaped keys (none can reach here — validateOps rejects
|
|
263
|
+
// them first, but the invariant must not depend on that ordering).
|
|
264
|
+
const values = Object.create(null);
|
|
265
|
+
for (const [key, value] of Object.entries(base)) {
|
|
266
|
+
values[key] = value;
|
|
267
|
+
}
|
|
268
|
+
const applied = [];
|
|
269
|
+
const keys = [];
|
|
270
|
+
const classSet = new Set();
|
|
271
|
+
for (const op of ops) {
|
|
272
|
+
if (op.action === "set") {
|
|
273
|
+
const value = op.value;
|
|
274
|
+
if (value === undefined)
|
|
275
|
+
throw new Error(`internal: set op for ${op.key} validated without a value`);
|
|
276
|
+
values[op.key] = value;
|
|
277
|
+
}
|
|
278
|
+
else {
|
|
279
|
+
delete values[op.key];
|
|
280
|
+
}
|
|
281
|
+
applied.push({ key: op.key, action: op.action });
|
|
282
|
+
if (!keys.includes(op.key))
|
|
283
|
+
keys.push(op.key);
|
|
284
|
+
// Own-property lookup: a class is recorded only from a real descriptor, so
|
|
285
|
+
// the audit `classes` array is always built from a defined class (S1).
|
|
286
|
+
const descriptor = getSettingDescriptor(op.key);
|
|
287
|
+
if (descriptor != null)
|
|
288
|
+
classSet.add(descriptor.class);
|
|
289
|
+
}
|
|
290
|
+
return { values, applied, keys, classes: [...classSet].sort() };
|
|
291
|
+
}
|
|
292
|
+
// ---------------------------------------------------------------------------
|
|
293
|
+
// The store
|
|
294
|
+
// ---------------------------------------------------------------------------
|
|
295
|
+
export class SettingsStore {
|
|
296
|
+
#dir;
|
|
297
|
+
#fs;
|
|
298
|
+
#writer;
|
|
299
|
+
#audit;
|
|
300
|
+
#lock;
|
|
301
|
+
#reader;
|
|
302
|
+
#now;
|
|
303
|
+
#warn;
|
|
304
|
+
constructor(dir, deps = {}) {
|
|
305
|
+
this.#dir = dir;
|
|
306
|
+
this.#fs = deps.fs ?? nodeFs;
|
|
307
|
+
this.#writer = deps.writer ?? durableWriter;
|
|
308
|
+
this.#lock = deps.lock;
|
|
309
|
+
this.#reader = createNodeSettingsFileReader();
|
|
310
|
+
this.#now = deps.now ?? Date.now;
|
|
311
|
+
this.#warn = deps.warn ?? (() => undefined);
|
|
312
|
+
this.#audit = deps.audit ?? new SettingsAuditLog(dir, { warn: this.#warn });
|
|
313
|
+
}
|
|
314
|
+
get #settingsPath() {
|
|
315
|
+
return join(this.#dir, SETTINGS_DOCUMENT_FILENAME);
|
|
316
|
+
}
|
|
317
|
+
get #secretsPath() {
|
|
318
|
+
return join(this.#dir, SECRETS_DOCUMENT_FILENAME);
|
|
319
|
+
}
|
|
320
|
+
// -------------------------------------------------------------------------
|
|
321
|
+
// Reads
|
|
322
|
+
// -------------------------------------------------------------------------
|
|
323
|
+
/**
|
|
324
|
+
* Read the settings document. A well-formed document with invalid values is
|
|
325
|
+
* PER-KEY TOLERANT (R4): it reads as `present`, its `values` carry the valid
|
|
326
|
+
* non-secret entries, and `invalidKeys`/`unknownKeys` report the rest, which
|
|
327
|
+
* stay on disk verbatim. An unparseable or shape-invalid document is
|
|
328
|
+
* REPORTED as unreadable (with its raw-bytes digest so a recover save can
|
|
329
|
+
* bind to it), never silently as an empty document.
|
|
330
|
+
*/
|
|
331
|
+
async read() {
|
|
332
|
+
const current = await this.#readSettingsDocument();
|
|
333
|
+
const baselines = await this.#audit.lastSettingsDigestBaselines().catch(() => undefined);
|
|
334
|
+
const externalEdit = this.#isExternalEdit(current, baselines);
|
|
335
|
+
if (current.state === "present" && current.secretClassKeys.length > 0) {
|
|
336
|
+
// Value-free by construction: names only, never the stored material.
|
|
337
|
+
this.#warn({ keys: [...current.secretClassKeys] }, "settings store: settings.json contains secret-class keys; they are ignored and dropped by the next save (secrets belong in secrets.json)");
|
|
338
|
+
}
|
|
339
|
+
switch (current.state) {
|
|
340
|
+
case "absent":
|
|
341
|
+
return { state: "absent", revision: 0, values: {}, digest: current.digest, externalEdit };
|
|
342
|
+
case "present":
|
|
343
|
+
return {
|
|
344
|
+
state: "present",
|
|
345
|
+
revision: current.revision,
|
|
346
|
+
values: current.values,
|
|
347
|
+
digest: current.digest,
|
|
348
|
+
externalEdit,
|
|
349
|
+
invalidKeys: current.invalidKeys,
|
|
350
|
+
unknownKeys: current.unknownKeys,
|
|
351
|
+
updatedAt: current.updatedAt,
|
|
352
|
+
updatedBy: current.updatedBy,
|
|
353
|
+
};
|
|
354
|
+
case "unreadable":
|
|
355
|
+
return {
|
|
356
|
+
state: "unreadable",
|
|
357
|
+
reason: current.reason,
|
|
358
|
+
revision: 0,
|
|
359
|
+
values: {},
|
|
360
|
+
digest: current.digest,
|
|
361
|
+
externalEdit,
|
|
362
|
+
};
|
|
363
|
+
}
|
|
364
|
+
}
|
|
365
|
+
/**
|
|
366
|
+
* Secret presence, never values. A secrets file whose mode allows
|
|
367
|
+
* group/other access is treated as unset with a warning (it is not read);
|
|
368
|
+
* the next save replaces it with a 0600 file.
|
|
369
|
+
*/
|
|
370
|
+
async secretStatus() {
|
|
371
|
+
const current = await this.#readSecretsDocument();
|
|
372
|
+
switch (current.state) {
|
|
373
|
+
case "absent":
|
|
374
|
+
return {
|
|
375
|
+
state: "absent",
|
|
376
|
+
revision: 0,
|
|
377
|
+
entries: {},
|
|
378
|
+
warnings: current.modeWarning == null ? [] : [current.modeWarning],
|
|
379
|
+
};
|
|
380
|
+
case "present": {
|
|
381
|
+
const entries = {};
|
|
382
|
+
for (const [key, entry] of Object.entries(current.entries)) {
|
|
383
|
+
entries[key] = { set: true, updatedAt: entry.updated_at };
|
|
384
|
+
}
|
|
385
|
+
return { state: "present", revision: current.revision, entries, warnings: [] };
|
|
386
|
+
}
|
|
387
|
+
case "unreadable":
|
|
388
|
+
return {
|
|
389
|
+
state: "unreadable",
|
|
390
|
+
reason: current.reason,
|
|
391
|
+
revision: 0,
|
|
392
|
+
entries: {},
|
|
393
|
+
warnings: [],
|
|
394
|
+
};
|
|
395
|
+
}
|
|
396
|
+
}
|
|
397
|
+
// -------------------------------------------------------------------------
|
|
398
|
+
// Saves
|
|
399
|
+
// -------------------------------------------------------------------------
|
|
400
|
+
async save(input) {
|
|
401
|
+
const fieldErrors = [...validateOps(input.ops, { secrets: false })];
|
|
402
|
+
if (!Number.isSafeInteger(input.expectedRevision) || input.expectedRevision < 0) {
|
|
403
|
+
fieldErrors.push({ key: "(expectedRevision)", message: "expectedRevision must be a non-negative integer" });
|
|
404
|
+
}
|
|
405
|
+
if (input.recover === true && typeof input.expectedDigest !== "string") {
|
|
406
|
+
fieldErrors.push({ key: "(recover)", message: "recover requires expectedDigest (the digest reported by read())" });
|
|
407
|
+
}
|
|
408
|
+
if (fieldErrors.length > 0) {
|
|
409
|
+
throw new SettingsStoreError("settings_invalid", `settings save rejected: ${fieldErrors.map((error) => `${error.key}: ${error.message}`).join("; ")}`, { fieldErrors });
|
|
410
|
+
}
|
|
411
|
+
await this.#ensureDir();
|
|
412
|
+
try {
|
|
413
|
+
return await withSettingsLock(this.#dir, async (guard) => {
|
|
414
|
+
const current = await this.#readSettingsDocument();
|
|
415
|
+
const updatedAt = new Date(this.#now()).toISOString();
|
|
416
|
+
let base = {};
|
|
417
|
+
let revisionBefore = 0;
|
|
418
|
+
let recovered = false;
|
|
419
|
+
let recoverBytes;
|
|
420
|
+
if (current.state === "unreadable") {
|
|
421
|
+
if (input.recover !== true) {
|
|
422
|
+
throw new SettingsStoreError("settings_unreadable", `the settings document is unreadable (${current.reason}); a routine save refuses to overwrite it — recover explicitly with expectedDigest`, { digest: current.digest });
|
|
423
|
+
}
|
|
424
|
+
if (current.rawBytes === undefined) {
|
|
425
|
+
// B1/F3 (L1): the reader produced no bytes (over-cap, EACCES,
|
|
426
|
+
// non-regular, symlink), so recover has nothing to preserve —
|
|
427
|
+
// sha256("") binds nothing and the replacement would destroy the
|
|
428
|
+
// only copy with no `.corrupt-*` backup. Refuse BEFORE the
|
|
429
|
+
// pending audit append (which would otherwise dangle) and leave
|
|
430
|
+
// the file byte-identical.
|
|
431
|
+
throw new SettingsStoreError("settings_unreadable", `${this.#settingsPath} could not be read (${current.reason}); no backup can be made — move it aside manually, then save`, { digest: current.digest });
|
|
432
|
+
}
|
|
433
|
+
if (input.expectedDigest !== current.digest) {
|
|
434
|
+
throw new SettingsStoreError("settings_unreadable", "recover refused: expectedDigest does not match the current bytes; re-read the document and retry", { digest: current.digest });
|
|
435
|
+
}
|
|
436
|
+
recovered = true;
|
|
437
|
+
recoverBytes = current.rawBytes;
|
|
438
|
+
}
|
|
439
|
+
else if (current.state === "absent") {
|
|
440
|
+
if (input.expectedRevision !== 0) {
|
|
441
|
+
throw this.#conflict(0, input.expectedRevision);
|
|
442
|
+
}
|
|
443
|
+
}
|
|
444
|
+
else {
|
|
445
|
+
if (input.expectedRevision !== current.revision) {
|
|
446
|
+
throw this.#conflict(current.revision, input.expectedRevision);
|
|
447
|
+
}
|
|
448
|
+
base = buildSaveBase(current.raw, input.ops);
|
|
449
|
+
revisionBefore = current.revision;
|
|
450
|
+
}
|
|
451
|
+
const appliedOps = applyOps(base, input.ops);
|
|
452
|
+
const revisionAfter = revisionBefore + 1;
|
|
453
|
+
const document = {
|
|
454
|
+
schema_version: SETTINGS_DOCUMENT_SCHEMA_VERSION,
|
|
455
|
+
revision: revisionAfter,
|
|
456
|
+
updated_at: updatedAt,
|
|
457
|
+
updated_by: { actor: input.actor, auth: input.auth },
|
|
458
|
+
values: appliedOps.values,
|
|
459
|
+
};
|
|
460
|
+
const bytes = `${JSON.stringify(document)}\n`;
|
|
461
|
+
this.#assertSerializedSize(bytes, SETTINGS_DOCUMENT_FILENAME);
|
|
462
|
+
const digestAfter = sha256Hex(bytes);
|
|
463
|
+
const action = recovered ? "recover" : "save";
|
|
464
|
+
const auditBase = {
|
|
465
|
+
at: updatedAt,
|
|
466
|
+
actor: input.actor,
|
|
467
|
+
auth: input.auth,
|
|
468
|
+
keys: appliedOps.keys,
|
|
469
|
+
classes: appliedOps.classes,
|
|
470
|
+
action,
|
|
471
|
+
revisionBefore,
|
|
472
|
+
revisionAfter,
|
|
473
|
+
};
|
|
474
|
+
// P3 order: the pending line is durable before anything is published.
|
|
475
|
+
await this.#appendAudit({ ...auditBase, digestAfter, outcome: "pending" }, "pending");
|
|
476
|
+
if (recovered) {
|
|
477
|
+
await this.#preserveCorruptBytes(SETTINGS_DOCUMENT_FILENAME, recoverBytes, SETTINGS_DOCUMENT_MODE);
|
|
478
|
+
}
|
|
479
|
+
const publishOutcome = await this.#publishDocument(guard, this.#settingsPath, bytes, SETTINGS_DOCUMENT_MODE, current.digest);
|
|
480
|
+
const appended = await this.#appendAudit({ ...auditBase, digestAfter, outcome: publishOutcome }, "outcome");
|
|
481
|
+
return {
|
|
482
|
+
revision: revisionAfter,
|
|
483
|
+
updatedAt,
|
|
484
|
+
applied: appliedOps.applied,
|
|
485
|
+
digest: digestAfter,
|
|
486
|
+
outcome: appended ? publishOutcome : "published_uncertain",
|
|
487
|
+
};
|
|
488
|
+
}, this.#lockOptions());
|
|
489
|
+
}
|
|
490
|
+
catch (error) {
|
|
491
|
+
throw this.#mapLockError(error);
|
|
492
|
+
}
|
|
493
|
+
}
|
|
494
|
+
async saveSecrets(input) {
|
|
495
|
+
const fieldErrors = [...validateOps(input.ops, { secrets: true })];
|
|
496
|
+
if (!Number.isSafeInteger(input.expectedRevision) || input.expectedRevision < 0) {
|
|
497
|
+
fieldErrors.push({ key: "(expectedRevision)", message: "expectedRevision must be a non-negative integer" });
|
|
498
|
+
}
|
|
499
|
+
if (fieldErrors.length > 0) {
|
|
500
|
+
throw new SettingsStoreError("settings_invalid", `secrets save rejected: ${fieldErrors.map((error) => `${error.key}: ${error.message}`).join("; ")}`, { fieldErrors });
|
|
501
|
+
}
|
|
502
|
+
await this.#ensureDir();
|
|
503
|
+
try {
|
|
504
|
+
return await withSettingsLock(this.#dir, async (guard) => {
|
|
505
|
+
const current = await this.#readSecretsDocument();
|
|
506
|
+
const updatedAt = new Date(this.#now()).toISOString();
|
|
507
|
+
const entries = {};
|
|
508
|
+
let revisionBefore = 0;
|
|
509
|
+
let recovered = false;
|
|
510
|
+
let recoverBytes;
|
|
511
|
+
if (current.state === "unreadable") {
|
|
512
|
+
if (input.recover !== true) {
|
|
513
|
+
throw new SettingsStoreError("settings_unreadable", `the secrets document is unreadable (${current.reason}); a routine save refuses to overwrite it — recover explicitly`);
|
|
514
|
+
}
|
|
515
|
+
if (current.rawBytes === undefined) {
|
|
516
|
+
// B1/F3 (L1), mirroring save(): without readable bytes there is no
|
|
517
|
+
// backup to make, so recover refuses and the file stays
|
|
518
|
+
// byte-identical. No digest anywhere on the secrets path.
|
|
519
|
+
throw new SettingsStoreError("settings_unreadable", `${this.#secretsPath} could not be read (${current.reason}); no backup can be made — move it aside manually, then save`);
|
|
520
|
+
}
|
|
521
|
+
recovered = true;
|
|
522
|
+
recoverBytes = current.rawBytes;
|
|
523
|
+
}
|
|
524
|
+
else if (current.state === "present") {
|
|
525
|
+
if (input.expectedRevision !== current.revision) {
|
|
526
|
+
throw new SettingsStoreError("settings_conflict", `secrets revision mismatch: document is at revision ${String(current.revision)}; expected ${String(input.expectedRevision)}`, { expectedRevision: current.revision });
|
|
527
|
+
}
|
|
528
|
+
revisionBefore = current.revision;
|
|
529
|
+
for (const [key, entry] of Object.entries(current.entries)) {
|
|
530
|
+
entries[key] = { value: entry.value, updated_at: entry.updated_at };
|
|
531
|
+
}
|
|
532
|
+
}
|
|
533
|
+
else if (input.expectedRevision !== 0) {
|
|
534
|
+
throw new SettingsStoreError("settings_conflict", `secrets revision mismatch: document is absent (revision 0); expected ${String(input.expectedRevision)}`, { expectedRevision: 0 });
|
|
535
|
+
}
|
|
536
|
+
const { applied, keys } = applyOps({}, input.ops);
|
|
537
|
+
for (const op of input.ops) {
|
|
538
|
+
if (op.action === "set") {
|
|
539
|
+
const value = op.value;
|
|
540
|
+
if (typeof value !== "string") {
|
|
541
|
+
throw new Error(`internal: secret set op for ${op.key} validated without a string value`);
|
|
542
|
+
}
|
|
543
|
+
entries[op.key] = { value, updated_at: updatedAt };
|
|
544
|
+
}
|
|
545
|
+
else {
|
|
546
|
+
delete entries[op.key];
|
|
547
|
+
}
|
|
548
|
+
}
|
|
549
|
+
const revisionAfter = revisionBefore + 1;
|
|
550
|
+
const document = {
|
|
551
|
+
schema_version: SECRETS_DOCUMENT_SCHEMA_VERSION,
|
|
552
|
+
revision: revisionAfter,
|
|
553
|
+
updated_at: updatedAt,
|
|
554
|
+
entries,
|
|
555
|
+
};
|
|
556
|
+
const bytes = `${JSON.stringify(document)}\n`;
|
|
557
|
+
this.#assertSerializedSize(bytes, SECRETS_DOCUMENT_FILENAME);
|
|
558
|
+
const auditBase = {
|
|
559
|
+
at: updatedAt,
|
|
560
|
+
actor: input.actor,
|
|
561
|
+
auth: input.auth,
|
|
562
|
+
keys,
|
|
563
|
+
classes: ["secret"],
|
|
564
|
+
action: "save_secrets",
|
|
565
|
+
revisionBefore,
|
|
566
|
+
revisionAfter,
|
|
567
|
+
};
|
|
568
|
+
// No digestAfter anywhere on the secrets path: secret material is
|
|
569
|
+
// never hashed, so no pending or outcome line may carry its digest.
|
|
570
|
+
await this.#appendAudit({ ...auditBase, outcome: "pending" }, "pending");
|
|
571
|
+
if (recovered) {
|
|
572
|
+
await this.#preserveCorruptBytes(SECRETS_DOCUMENT_FILENAME, recoverBytes, SECRETS_DOCUMENT_MODE);
|
|
573
|
+
}
|
|
574
|
+
// No digest is passed for the secrets document: secret material is
|
|
575
|
+
// never hashed, so no error surface may carry its digest either.
|
|
576
|
+
const publishOutcome = await this.#publishDocument(guard, this.#secretsPath, bytes, SECRETS_DOCUMENT_MODE, undefined);
|
|
577
|
+
const appended = await this.#appendAudit({ ...auditBase, outcome: publishOutcome }, "outcome");
|
|
578
|
+
return { revision: revisionAfter, updatedAt, applied, outcome: appended ? publishOutcome : "published_uncertain" };
|
|
579
|
+
}, this.#lockOptions());
|
|
580
|
+
}
|
|
581
|
+
catch (error) {
|
|
582
|
+
throw this.#mapLockError(error);
|
|
583
|
+
}
|
|
584
|
+
}
|
|
585
|
+
// -------------------------------------------------------------------------
|
|
586
|
+
// Internals
|
|
587
|
+
// -------------------------------------------------------------------------
|
|
588
|
+
#lockOptions() {
|
|
589
|
+
return { ...(this.#lock ?? {}), warn: this.#lock?.warn ?? this.#warn };
|
|
590
|
+
}
|
|
591
|
+
/**
|
|
592
|
+
* F2: a dangling `pending` audit line carries the `digestAfter` of bytes a
|
|
593
|
+
* failed publish never wrote, so it must not be the ONLY baseline — the
|
|
594
|
+
* unchanged on-disk bytes still match the last outcome line. The on-disk
|
|
595
|
+
* digest is an external edit only when it matches NEITHER baseline; with no
|
|
596
|
+
* baseline at all (no audited write ever, or the audit is unreadable),
|
|
597
|
+
* anything but an absent document is external, as before.
|
|
598
|
+
*/
|
|
599
|
+
#isExternalEdit(current, baselines) {
|
|
600
|
+
if (baselines == null || (baselines.pending === undefined && baselines.outcome === undefined)) {
|
|
601
|
+
return current.state !== "absent";
|
|
602
|
+
}
|
|
603
|
+
return current.digest !== baselines.pending && current.digest !== baselines.outcome;
|
|
604
|
+
}
|
|
605
|
+
async #ensureDir() {
|
|
606
|
+
try {
|
|
607
|
+
// Durable mkdir (P7): each created directory is fsynced into its parent
|
|
608
|
+
// through the writer, so a document published beneath it cannot outlive
|
|
609
|
+
// its own path after a crash.
|
|
610
|
+
await mkdirDurable(this.#writer, this.#dir, SETTINGS_DIR_MODE);
|
|
611
|
+
}
|
|
612
|
+
catch (error) {
|
|
613
|
+
this.#mapFsError(error, "create the settings directory");
|
|
614
|
+
}
|
|
615
|
+
await this.#fs.chmod(this.#dir, SETTINGS_DIR_MODE).catch((error) => {
|
|
616
|
+
this.#warn({ dir: this.#dir, err: error instanceof Error ? error.message : String(error) }, "settings store: could not tighten the settings directory mode to 0700");
|
|
617
|
+
});
|
|
618
|
+
}
|
|
619
|
+
/**
|
|
620
|
+
* A document the startup loader would refuse to read is never written (P4):
|
|
621
|
+
* the store and the loader share `MAX_SETTINGS_FILE_BYTES`, so a save that
|
|
622
|
+
* would exceed it is rejected before anything is published.
|
|
623
|
+
*/
|
|
624
|
+
#assertSerializedSize(bytes, filename) {
|
|
625
|
+
const size = Buffer.byteLength(bytes, "utf8");
|
|
626
|
+
if (size <= MAX_SETTINGS_FILE_BYTES)
|
|
627
|
+
return;
|
|
628
|
+
const message = `the serialized ${filename} would be ${String(size)} bytes, above the ${String(MAX_SETTINGS_FILE_BYTES)}-byte cap the startup loader also enforces; split or shorten the values (large list settings are the usual cause)`;
|
|
629
|
+
throw new SettingsStoreError("settings_invalid", message, {
|
|
630
|
+
fieldErrors: [{ key: "(ops)", message: capMessage(message) }],
|
|
631
|
+
});
|
|
632
|
+
}
|
|
633
|
+
async #readSettingsDocument() {
|
|
634
|
+
const path = this.#settingsPath;
|
|
635
|
+
const read = this.#reader(path);
|
|
636
|
+
if (!read.ok) {
|
|
637
|
+
if (read.code === "MISSING") {
|
|
638
|
+
return { state: "absent", digest: sha256Hex("") };
|
|
639
|
+
}
|
|
640
|
+
return { state: "unreadable", digest: sha256Hex(""), reason: readerFailureReason(SETTINGS_DOCUMENT_FILENAME, read.code) };
|
|
641
|
+
}
|
|
642
|
+
const bytes = Buffer.from(read.bytes);
|
|
643
|
+
const digest = sha256Hex(bytes);
|
|
644
|
+
let parsed;
|
|
645
|
+
try {
|
|
646
|
+
parsed = JSON.parse(bytes.toString("utf8"));
|
|
647
|
+
}
|
|
648
|
+
catch {
|
|
649
|
+
return { state: "unreadable", digest, reason: "settings.json is not valid JSON", rawBytes: bytes };
|
|
650
|
+
}
|
|
651
|
+
const classified = classifySettingsDocument(parsed);
|
|
652
|
+
if (classified.status === "shape_invalid") {
|
|
653
|
+
return { state: "unreadable", digest, reason: "settings.json has an invalid document shape", rawBytes: bytes };
|
|
654
|
+
}
|
|
655
|
+
if (classified.status === "unsupported") {
|
|
656
|
+
return {
|
|
657
|
+
state: "unreadable",
|
|
658
|
+
digest,
|
|
659
|
+
reason: capReason(`settings.json schema_version ${JSON.stringify(schemaVersionOf(parsed))} is not supported (supported: "${SETTINGS_DOCUMENT_SCHEMA_VERSION}")`),
|
|
660
|
+
rawBytes: bytes,
|
|
661
|
+
};
|
|
662
|
+
}
|
|
663
|
+
if (classified.updated_by == null) {
|
|
664
|
+
// Unreachable: the envelope schema requires updated_by; guarded so the
|
|
665
|
+
// present branch never fabricates provenance.
|
|
666
|
+
return { state: "unreadable", digest, reason: "settings.json has an invalid document shape", rawBytes: bytes };
|
|
667
|
+
}
|
|
668
|
+
return {
|
|
669
|
+
state: "present",
|
|
670
|
+
digest,
|
|
671
|
+
revision: classified.revision,
|
|
672
|
+
// `valid` holds only known non-secret keys whose values passed codec
|
|
673
|
+
// validation, so the unknown here is a validated SettingValue.
|
|
674
|
+
values: classified.valid,
|
|
675
|
+
invalidKeys: classified.invalid,
|
|
676
|
+
unknownKeys: Object.keys(classified.unknownRaw),
|
|
677
|
+
secretClassKeys: classified.secretClassKeys,
|
|
678
|
+
raw: classified.raw,
|
|
679
|
+
updatedAt: classified.updated_at,
|
|
680
|
+
updatedBy: classified.updated_by,
|
|
681
|
+
};
|
|
682
|
+
}
|
|
683
|
+
async #readSecretsDocument() {
|
|
684
|
+
const path = this.#secretsPath;
|
|
685
|
+
const read = this.#reader(path);
|
|
686
|
+
if (!read.ok) {
|
|
687
|
+
if (read.code === "MISSING") {
|
|
688
|
+
return { state: "absent", digest: sha256Hex("") };
|
|
689
|
+
}
|
|
690
|
+
return { state: "unreadable", digest: sha256Hex(""), reason: readerFailureReason(SECRETS_DOCUMENT_FILENAME, read.code) };
|
|
691
|
+
}
|
|
692
|
+
// The mode comes from the fstat of the SAME opened descriptor the bytes
|
|
693
|
+
// were read through, so the check cannot be raced onto another file.
|
|
694
|
+
if ((read.mode & 0o077) !== 0) {
|
|
695
|
+
// Refuse to read a secrets file that group/other can touch. Treated as
|
|
696
|
+
// unset; the next save replaces it with a 0600 file.
|
|
697
|
+
return {
|
|
698
|
+
state: "absent",
|
|
699
|
+
digest: sha256Hex(""),
|
|
700
|
+
modeWarning: "secrets.json mode allows group/other access; refusing to read it (treated as unset) — the next secrets save rewrites it with mode 0600",
|
|
701
|
+
};
|
|
702
|
+
}
|
|
703
|
+
const bytes = Buffer.from(read.bytes);
|
|
704
|
+
const digest = sha256Hex(bytes);
|
|
705
|
+
let parsed;
|
|
706
|
+
try {
|
|
707
|
+
parsed = JSON.parse(bytes.toString("utf8"));
|
|
708
|
+
}
|
|
709
|
+
catch {
|
|
710
|
+
return { state: "unreadable", digest, reason: "secrets.json is not valid JSON", rawBytes: bytes };
|
|
711
|
+
}
|
|
712
|
+
const result = parseSecretsDocument(parsed);
|
|
713
|
+
if (result.status === "ok") {
|
|
714
|
+
return { state: "present", digest, revision: result.document.revision, entries: result.document.entries };
|
|
715
|
+
}
|
|
716
|
+
if (result.status === "unsupported") {
|
|
717
|
+
return {
|
|
718
|
+
state: "unreadable",
|
|
719
|
+
digest,
|
|
720
|
+
reason: capReason(`secrets.json schema_version ${JSON.stringify(schemaVersionOf(parsed))} is not supported (supported: "${SECRETS_DOCUMENT_SCHEMA_VERSION}")`),
|
|
721
|
+
rawBytes: bytes,
|
|
722
|
+
};
|
|
723
|
+
}
|
|
724
|
+
const issues = result.issues
|
|
725
|
+
.slice(0, 3)
|
|
726
|
+
.map((issue) => `${issue.key}: ${issue.error}`)
|
|
727
|
+
.join("; ");
|
|
728
|
+
return {
|
|
729
|
+
state: "unreadable",
|
|
730
|
+
digest,
|
|
731
|
+
reason: capReason(`secrets.json failed validation (${result.reason}): ${issues}${result.issues.length > 3 ? ` (+${String(result.issues.length - 3)} more)` : ""}`),
|
|
732
|
+
rawBytes: bytes,
|
|
733
|
+
};
|
|
734
|
+
}
|
|
735
|
+
/**
|
|
736
|
+
* Copy corrupt bytes aside through the durable writer before the active
|
|
737
|
+
* file is replaced. The active path is NEVER renamed away, so a publication
|
|
738
|
+
* that later fails leaves it exactly where it was (a rename-first recover
|
|
739
|
+
* destroyed the active file on the first failure). Both callers refuse
|
|
740
|
+
* recover up front when no bytes were read (L1), so `bytes` is always
|
|
741
|
+
* defined here; the undefined guard remains as a structural backstop.
|
|
742
|
+
* A zero-byte document is preserved as a 0-byte copy (L14): the CLI and UI
|
|
743
|
+
* announce a backup on every successful recover, and an empty unreadable
|
|
744
|
+
* file is exactly the case where that announcement must not be a lie.
|
|
745
|
+
*/
|
|
746
|
+
async #preserveCorruptBytes(filename, bytes, mode) {
|
|
747
|
+
if (bytes === undefined)
|
|
748
|
+
return;
|
|
749
|
+
const to = join(this.#dir, `${filename}.corrupt-${String(this.#now())}-${randomBytes(4).toString("hex")}`);
|
|
750
|
+
try {
|
|
751
|
+
await this.#writer.writeFile(to, bytes, { mode });
|
|
752
|
+
}
|
|
753
|
+
catch (error) {
|
|
754
|
+
if (error instanceof DurablePublishError) {
|
|
755
|
+
// The copy is already visible; the preserved bytes are the point, so a
|
|
756
|
+
// failed directory fsync on them is a warning, not a lost recovery.
|
|
757
|
+
this.#warn({ path: to, err: error.message }, "settings store: preserved the corrupt bytes but could not fsync the settings directory");
|
|
758
|
+
return;
|
|
759
|
+
}
|
|
760
|
+
this.#mapFsError(error, `preserve the corrupt ${filename}`);
|
|
761
|
+
}
|
|
762
|
+
}
|
|
763
|
+
/**
|
|
764
|
+
* Write a published document through the durable writer. A post-rename
|
|
765
|
+
* `DurablePublishError` is reported as `published_uncertain`, never as a
|
|
766
|
+
* clean rejection — the new bytes are already visible.
|
|
767
|
+
*/
|
|
768
|
+
async #publishDocument(guard, path, bytes, mode, digestBefore) {
|
|
769
|
+
try {
|
|
770
|
+
await guard.assertHeld();
|
|
771
|
+
}
|
|
772
|
+
catch (error) {
|
|
773
|
+
throw this.#mapLockError(error);
|
|
774
|
+
}
|
|
775
|
+
try {
|
|
776
|
+
await this.#writer.writeFile(path, bytes, { mode });
|
|
777
|
+
}
|
|
778
|
+
catch (error) {
|
|
779
|
+
if (error instanceof DurablePublishError) {
|
|
780
|
+
this.#warn({ path, err: error.message }, "settings store: document was published but its directory could not be fsynced (published_uncertain)");
|
|
781
|
+
return "published_uncertain";
|
|
782
|
+
}
|
|
783
|
+
if (error instanceof DurableSymlinkTargetError) {
|
|
784
|
+
throw new SettingsStoreError("settings_unreadable", `the document at ${path} is a symbolic link; nothing was written — recover explicitly`, {
|
|
785
|
+
...(digestBefore == null
|
|
786
|
+
? {}
|
|
787
|
+
: { digest: digestBefore }),
|
|
788
|
+
});
|
|
789
|
+
}
|
|
790
|
+
this.#mapFsError(error, `write ${path}`);
|
|
791
|
+
}
|
|
792
|
+
return "ok";
|
|
793
|
+
}
|
|
794
|
+
/**
|
|
795
|
+
* Append one audit line in the pending-first order. A failed PENDING append
|
|
796
|
+
* means nothing has been published yet, so it is a clean 503 refusal. A
|
|
797
|
+
* failed OUTCOME append means the document write may already be live, so it
|
|
798
|
+
* is reported (never swallowed) and the caller answers
|
|
799
|
+
* `published_uncertain` (P3).
|
|
800
|
+
*/
|
|
801
|
+
async #appendAudit(record, phase) {
|
|
802
|
+
try {
|
|
803
|
+
await this.#audit.append(record);
|
|
804
|
+
return true;
|
|
805
|
+
}
|
|
806
|
+
catch (error) {
|
|
807
|
+
const detail = error instanceof Error ? error.message : String(error);
|
|
808
|
+
if (phase === "pending") {
|
|
809
|
+
throw new SettingsStoreError("settings_unavailable", `could not append the pending settings audit entry; nothing was published: ${capMessage(detail)}`);
|
|
810
|
+
}
|
|
811
|
+
this.#warn({ err: capMessage(detail) }, "settings store: could not append the settings audit outcome (the document write may already be published); reporting published_uncertain");
|
|
812
|
+
return false;
|
|
813
|
+
}
|
|
814
|
+
}
|
|
815
|
+
#conflict(currentRevision, expectedRevision) {
|
|
816
|
+
return new SettingsStoreError("settings_conflict", `settings revision mismatch: document is at revision ${String(currentRevision)}; expected ${String(expectedRevision)}`, { expectedRevision: currentRevision });
|
|
817
|
+
}
|
|
818
|
+
#mapLockError(error) {
|
|
819
|
+
if (error instanceof SettingsLockError) {
|
|
820
|
+
return new SettingsStoreError("settings_locked", `settings save could not run: ${error.message}`);
|
|
821
|
+
}
|
|
822
|
+
// The lock re-throws raw fs errors from its own open/write (EACCES on a
|
|
823
|
+
// read-only settings directory, ENOSPC, ...) — map those like every other
|
|
824
|
+
// filesystem failure rather than leaking an errno error to callers.
|
|
825
|
+
const code = errnoCode(error);
|
|
826
|
+
if (code != null && FS_UNAVAILABLE_CODES.has(code)) {
|
|
827
|
+
return new SettingsStoreError("settings_unavailable", `could not acquire or hold the settings lock: ${code}`);
|
|
828
|
+
}
|
|
829
|
+
return error;
|
|
830
|
+
}
|
|
831
|
+
#mapFsError(error, what) {
|
|
832
|
+
const code = errnoCode(error);
|
|
833
|
+
if (code != null && FS_UNAVAILABLE_CODES.has(code)) {
|
|
834
|
+
throw new SettingsStoreError("settings_unavailable", `could not ${what}: ${code}`);
|
|
835
|
+
}
|
|
836
|
+
throw error;
|
|
837
|
+
}
|
|
838
|
+
}
|
|
839
|
+
export function createSettingsStore(dir, deps = {}) {
|
|
840
|
+
return new SettingsStore(dir, deps);
|
|
841
|
+
}
|
|
842
|
+
//# sourceMappingURL=store.js.map
|