Creatidy/scarcity-router
5
0
Fork 0
Code Issues 13 Pull requests Projects Releases Packages Wiki Activity Actions

G. TLS + certificate lifecycle (public-CA direction, private-CA fallback) #139

New issue
Open
opened 2026-09-26 21:44:36 +00:00 by kilo · 3 comments
kilo commented 2026-09-26 21:44:36 +00:00
Member
Copy link

Child G of #132. Stop making private-CA handling part of the normal end-user path; establish the recommended self-hosted production TLS direction and keep a supported private-CA fallback.

Recommended production direction (design + implement product support, not a vendor control plane)

https://scarcity-router.creatidy.com:8787
srws://scarcity-router.creatidy.com:8790
  • Real FQDN, public-trusted certificate via ACME/Let's Encrypt with DNS-01; no application ports exposed publicly (split/internal DNS resolves the FQDN to the private host over LAN/VPN); one certificate usable by HTTPS 8787 and worker TLS 8790; automatic renewal with a safe deploy/reload hook; external clients use normal OS trust — no per-client CA configuration in the normal case.
  • Before implementing acquisition: inspect existing Creatidy ACME/Certbot/DNS mechanisms and REUSE proven infrastructure; do not assume the DNS provider; never expose DNS credentials; no large ACME implementation inside the routing core. Certificate lifecycle belongs in installer/service/deployment tooling; the core keeps accepting certificate/key paths.

Private-CA fallback (must not regress)

  • Explicit trust configuration: --ca-cert <path> for worker pair/run/service operations, persisted in worker-local configuration so all subsequent operations reuse it — no hand-written SSL_CERT_FILE environment hacks, and service units (child F) consume the persisted configuration.
  • Never: verify=false, insecure mode, trust-on-first-use, certificate-error suppression. CA export/trust guidance for external clients is documentation, never an automatic system-trust-store mutation.

Worker origin migration

Support moving srws://192.168.2.13:8790 → srws://scarcity-router.creatidy.com:8790 without destructive re-pairing when the existing worker identity remains valid. Before persisting a migrated origin: verify TLS to the new origin AND verify the existing device identity/authentication; only then commit the origin change.

Out of scope

No vendor control-plane/domain dependency; no ZCode-side changes (a concise reproducible report on the observed Custom-certificate propagation failure is prepared as an owner-review artifact only — not published without owner approval; Scarcity Router must not depend on any ZCode fix).

Tests

CA persistence across pair/run/service; origin migration verification order (verify-then-commit; refusal paths); unit/UX integration with child F; negative tests (no bypass modes reachable, credentials never persisted/logged); documentation of the recommended deployment path.

Security classification

Security-critical (TLS, credentials, identity migration): GLM-5.3-Flash review mandatory; Daybreak security review when available, else SECURITY_REVIEW_UNAVAILABLE with the gate open at the human decision point. UX assessment mandatory.

Complexity boundary

Worker config/store + worker_client.py flags + deployment tooling/docs; server CLI unchanged except doc guidance; ~3 test files. Budget: 120 min wall clock.

Child G of #132. Stop making private-CA handling part of the normal end-user path; establish the recommended self-hosted production TLS direction and keep a supported private-CA fallback. ## Recommended production direction (design + implement product support, not a vendor control plane) ``` https://scarcity-router.creatidy.com:8787 srws://scarcity-router.creatidy.com:8790 ``` - Real FQDN, public-trusted certificate via ACME/Let's Encrypt with DNS-01; no application ports exposed publicly (split/internal DNS resolves the FQDN to the private host over LAN/VPN); one certificate usable by HTTPS 8787 and worker TLS 8790; automatic renewal with a safe deploy/reload hook; external clients use normal OS trust — no per-client CA configuration in the normal case. - Before implementing acquisition: inspect existing Creatidy ACME/Certbot/DNS mechanisms and REUSE proven infrastructure; do not assume the DNS provider; never expose DNS credentials; no large ACME implementation inside the routing core. Certificate lifecycle belongs in installer/service/deployment tooling; the core keeps accepting certificate/key paths. ## Private-CA fallback (must not regress) - Explicit trust configuration: `--ca-cert <path>` for worker pair/run/service operations, persisted in worker-local configuration so all subsequent operations reuse it — no hand-written `SSL_CERT_FILE` environment hacks, and service units (child F) consume the persisted configuration. - Never: `verify=false`, insecure mode, trust-on-first-use, certificate-error suppression. CA export/trust guidance for external clients is documentation, never an automatic system-trust-store mutation. ## Worker origin migration Support moving `srws://192.168.2.13:8790` → `srws://scarcity-router.creatidy.com:8790` without destructive re-pairing when the existing worker identity remains valid. Before persisting a migrated origin: verify TLS to the new origin AND verify the existing device identity/authentication; only then commit the origin change. ## Out of scope No vendor control-plane/domain dependency; no ZCode-side changes (a concise reproducible report on the observed Custom-certificate propagation failure is prepared as an owner-review artifact only — not published without owner approval; Scarcity Router must not depend on any ZCode fix). ## Tests CA persistence across pair/run/service; origin migration verification order (verify-then-commit; refusal paths); unit/UX integration with child F; negative tests (no bypass modes reachable, credentials never persisted/logged); documentation of the recommended deployment path. ## Security classification Security-critical (TLS, credentials, identity migration): GLM-5.3-Flash review mandatory; **Daybreak security review** when available, else `SECURITY_REVIEW_UNAVAILABLE` with the gate open at the human decision point. UX assessment mandatory. ## Complexity boundary Worker config/store + `worker_client.py` flags + deployment tooling/docs; server CLI unchanged except doc guidance; ~3 test files. Budget: 120 min wall clock.
kilo commented 2026-09-27 17:42:58 +00:00
Author
Member
Copy link

Additive scope note (D-056, PR #147 remediation — the frozen scope text above is unchanged; this assigns newly accepted architecture into the existing deployment tooling/docs scope rather than creating a new issue):

This child now also implements the accepted same-host container plaintext transport tier from D-056 (docs/decisions.md):

  • Plain HTTP between containers on ONE physical host, only under deployment isolation that makes the transport host-local and non-routable from external networks (dedicated or internal: true Docker network, no externally published plaintext application port). This includes the currently unsupported Docker bridge + loopback-publish case (-p 127.0.0.1:8787:8787), which today fails because published traffic reaches the container on a non-loopback interface where plaintext binds are refused.
  • The tier is a property of the ENTIRE composed HTTP listener (execution, machine-interface, control and administration surfaces ride one listener, D-041) — never a per-surface plaintext/TLS mix, and never a global non-loopback 0.0.0.0 plaintext listener. An explicit deployment/local-transport mode is expected; it must be difficult to accidentally turn a LAN-facing endpoint into plaintext. Worker-protocol transport is unchanged.
  • Until this lands, non-loopback binds require TLS exactly as today; cross-host/LAN/VPN/remote stays TLS-required (VPN is not automatically local), and the TLS certificate lifecycle work above remains this child's primary direction.

Details: D-056 in docs/decisions.md, "Client-transport tiers (D-056)" in docs/security.md, PR #147.

Additive scope note (D-056, PR #147 remediation — the frozen scope text above is unchanged; this assigns newly accepted architecture into the existing deployment tooling/docs scope rather than creating a new issue): This child now also implements the accepted **same-host container plaintext transport tier** from D-056 (`docs/decisions.md`): - Plain HTTP between containers on ONE physical host, only under deployment isolation that makes the transport host-local and non-routable from external networks (dedicated or `internal: true` Docker network, no externally published plaintext application port). This includes the currently unsupported Docker bridge + loopback-publish case (`-p 127.0.0.1:8787:8787`), which today fails because published traffic reaches the container on a non-loopback interface where plaintext binds are refused. - The tier is a property of the ENTIRE composed HTTP listener (execution, machine-interface, control and administration surfaces ride one listener, D-041) — never a per-surface plaintext/TLS mix, and never a global non-loopback `0.0.0.0` plaintext listener. An explicit deployment/local-transport mode is expected; it must be difficult to accidentally turn a LAN-facing endpoint into plaintext. Worker-protocol transport is unchanged. - Until this lands, non-loopback binds require TLS exactly as today; cross-host/LAN/VPN/remote stays TLS-required (VPN is not automatically local), and the TLS certificate lifecycle work above remains this child's primary direction. Details: D-056 in `docs/decisions.md`, "Client-transport tiers (D-056)" in `docs/security.md`, PR #147.
kilo commented 2026-09-27 21:01:49 +00:00
Author
Member
Copy link

Additive scope note #2 (D-056, PR #147 — complementing the same-host container-tier note above; frozen scope text unchanged):

D-056 also fixes the local-first normal path that this child's documentation and UX must present: plain-HTTP loopback (http://localhost:8787/v1) is a SUPPORTED local transport and a normal certificate-free configuration (D-056 pt 8A / pt 9). Local operation must not be documented or UX-framed as requiring certificate setup, and a private CA is never required for ordinary localhost operation. The remote normal UX stays public FQDN + publicly trusted certificate + automated renewal, with private CA as the advanced fallback (pt 8D — already this child's primary direction). These are documentation/UX consequences of D-056 only; no listener-behavior change beyond what the container-tier note above assigns.

Additive scope note #2 (D-056, PR #147 — complementing the same-host container-tier note above; frozen scope text unchanged): D-056 also fixes the local-first normal path that this child's documentation and UX must present: plain-HTTP loopback (`http://localhost:8787/v1`) is a SUPPORTED local transport and a normal certificate-free configuration (D-056 pt 8A / pt 9). Local operation must not be documented or UX-framed as requiring certificate setup, and a private CA is never required for ordinary localhost operation. The remote normal UX stays public FQDN + publicly trusted certificate + automated renewal, with private CA as the advanced fallback (pt 8D — already this child's primary direction). These are documentation/UX consequences of D-056 only; no listener-behavior change beyond what the container-tier note above assigns.
kilo commented 2026-10-27 21:24:31 +00:00
Author
Member
Copy link

2026-10-27 owner backlog disposition (D-083, governance issue #228). This issue remains open with its wontfix label unchanged; history preserved. Its still-required obligations are re-homed to active successor #224 (same-host container tier B, persisted/validated CA trust, certificate lifecycle, origin migration — security-critical), which carries every retained invariant: no plaintext LAN/WAN exposure, whole-composed-listener property with proven deployment-boundary enforcement, no verify=false/TOFU/bypass, no TLS/CSRF/credential weakening. The former #186 → #139 native dependency was removed as stale. See D-083 in docs/decisions.md.

**2026-10-27 owner backlog disposition (D-083, governance issue #228).** This issue remains open with its `wontfix` label unchanged; history preserved. Its still-required obligations are re-homed to active successor **#224** (same-host container tier B, persisted/validated CA trust, certificate lifecycle, origin migration — security-critical), which carries every retained invariant: no plaintext LAN/WAN exposure, whole-composed-listener property with proven deployment-boundary enforcement, no `verify=false`/TOFU/bypass, no TLS/CSRF/credential weakening. The former #186 → #139 native dependency was removed as stale. See D-083 in `docs/decisions.md`.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
develop
issue-246-authorized-receipt
issue-245-mi-startup
issue-226-administrator-ux
issue-183-observer-access
issue-183-event-acceptance
issue-183-internal-events
issue-183-resource-state
issue-242-secure-bootstrap
issue-238-mi-server
issue-239-architecture-reconciliation
issue-224-certificate-lifecycle
issue-224-origin-bound-worker
issue-224-worker-ca-trust
issue-234-evidenced-resources
issue-186-installed-lifecycle
issue-186-ghcr-distribution
issue-225-cancel-paths
issue-228-backlog-disposition
issue-222-active-mi
issue-176-mi-consumer
issue-185-contract-conformance
issue-219-project-security-audit
issue-181-responses-subset
issue-214-claude-subscription
issue-205-review-result-recovery
issue-174-executable-contract
issue-215-conversational-review
issue-210-d069-review-governance
issue-212-d069a-bootstrap
issue-202-dependency-eligibility
issue-184-strict-no-payg
issue-175-kernel-requirements
issue-180-native-authority-boundary
issue-182-readable-status
issue-195-post-selection-gates
issue-179-catalog-effort
issue-178-exact-target-pin
issue-190-workflow-self-remediation
task/168-capacity-controlled-home
fix/143-scenario11-cancel-race
policy/zai-model-governance-campaign
main
No results found.
Labels
Clear labels   
accessibility
Barrier affecting people with disabilities

  
bug
Something isn't working

  
documentation
Improvements or additions to documentation

  
duplicate
This issue or pull request already exists

  
enhancement
New feature or request

  
good first issue
Good for newcomers

  
help wanted
Extra attention is needed

  
invalid
This doesn't seem right

  
P1
Owner-declared highest explicit implementation priority (loop ordering rank)

  
P2
Required product and integration work

  
P3
Deferred or producer-dependent work

  
question
Further information is requested

  
wontfix
This will not be worked on

No labels
accessibility
bug
documentation
duplicate
enhancement
good first issue
help wanted
invalid
P1
P2
P3
question
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
Creatidy/scarcity-router#139
No description provided.