rcf-lite 0.13.0 → 0.14.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 +29 -1
- package/bin/rcf.js +3 -1
- package/blueprints/application-api-rest/docs/topics.md +1 -1
- package/blueprints/application-spa/README.md +3 -3
- package/blueprints/application-spa/contributions/adrs/adr-202-application-spa-theming.json +1 -1
- package/blueprints/application-spa/contributions/adrs/adr-206-application-spa-iconography.json +1 -1
- package/blueprints/application-spa/contributions/tacs/tac-207-application-spa-token-adherence-probe.json +7 -7
- package/blueprints/application-spa/contributions/tacs/tac-208-application-spa-icon-adherence-probe.json +7 -7
- package/blueprints/application-spa/contributions/tacs/tac-209-application-spa-csp-styled-adherence-probe.json +8 -8
- package/blueprints/application-spa/contributions/tacs/tac-210-application-spa-external-dependency-provisioning-probe.json +8 -8
- package/blueprints/application-spa/contributions/tacs/tac-211-application-spa-core-flow-e2e-probe.json +8 -8
- package/blueprints/application-spa/contributions/user-stories/application-spa-us-1129.json +2 -2
- package/blueprints/application-spa/contributions/user-stories/application-spa-us-1130.json +2 -2
- package/blueprints/application-spa/contributions/user-stories/application-spa-us-1131.json +2 -2
- package/blueprints/application-spa/contributions/user-stories/application-spa-us-1132.json +2 -2
- package/blueprints/application-spa/contributions/user-stories/application-spa-us-1133.json +3 -3
- package/blueprints/application-spa/docs/topics.md +1 -1
- package/blueprints/delivery-ci-workflows/CHANGELOG.md +39 -0
- package/blueprints/delivery-ci-workflows/README.md +57 -0
- package/blueprints/delivery-ci-workflows/assets/ci-provider-examples/github-actions/default-branch-checks.yml +55 -0
- package/blueprints/delivery-ci-workflows/assets/ci-provider-examples/github-actions/pull-request-checks.yml +65 -0
- package/blueprints/delivery-ci-workflows/assets/ci-provider-examples/github-actions/release.yml +71 -0
- package/blueprints/delivery-ci-workflows/assets/ci-provider-examples/github-actions/scheduled-audit.yml +61 -0
- package/blueprints/delivery-ci-workflows/assets/ci-provider-examples/notes.md +61 -0
- package/blueprints/{ci-pipeline → delivery-ci-workflows}/assets/report-samples/per-gate.json +2 -1
- package/blueprints/delivery-ci-workflows/blueprint.json +87 -0
- package/blueprints/delivery-ci-workflows/contributions/adrs/adr-701-delivery-ci-workflows-ci-gates.json +30 -0
- package/blueprints/{ci-pipeline/contributions/adrs/adr-702-ci-pipeline-strict-coverage-gate.json → delivery-ci-workflows/contributions/adrs/adr-702-delivery-ci-workflows-strict-coverage-gate.json} +2 -2
- package/blueprints/{ci-pipeline/contributions/adrs/adr-703-ci-pipeline-node-only-runner.json → delivery-ci-workflows/contributions/adrs/adr-703-delivery-ci-workflows-node-only-runner.json} +1 -1
- package/blueprints/{ci-pipeline/contributions/adrs/adr-704-ci-pipeline-report-shape.json → delivery-ci-workflows/contributions/adrs/adr-704-delivery-ci-workflows-report-shape.json} +3 -3
- package/blueprints/delivery-ci-workflows/contributions/adrs/adr-705-delivery-ci-workflows-elicitation-surface.json +25 -0
- package/blueprints/delivery-ci-workflows/contributions/adrs/adr-706-delivery-ci-workflows-branch-model-defaults.json +25 -0
- package/blueprints/delivery-ci-workflows/contributions/adrs/adr-707-delivery-ci-workflows-release-workflow-shape.json +25 -0
- package/blueprints/delivery-ci-workflows/contributions/adrs/adr-708-delivery-ci-workflows-provider-hint-shape.json +25 -0
- package/blueprints/delivery-ci-workflows/contributions/adrs/adr-709-delivery-ci-workflows-release-artefacts.json +25 -0
- package/blueprints/delivery-ci-workflows/contributions/adrs/adr-710-delivery-ci-workflows-scheduled-audit.json +25 -0
- package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-001.json +18 -0
- package/blueprints/{ci-pipeline/contributions/requirements/ci-pipeline-req-002.json → delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-002.json} +2 -2
- package/blueprints/{ci-pipeline/contributions/requirements/ci-pipeline-req-003.json → delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-003.json} +2 -2
- package/blueprints/{ci-pipeline/contributions/requirements/ci-pipeline-req-004.json → delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-004.json} +2 -2
- package/blueprints/{ci-pipeline/contributions/requirements/ci-pipeline-req-005.json → delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-005.json} +4 -4
- package/blueprints/{ci-pipeline/contributions/requirements/ci-pipeline-req-006.json → delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-006.json} +2 -2
- package/blueprints/{ci-pipeline/contributions/requirements/ci-pipeline-req-007.json → delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-007.json} +2 -2
- package/blueprints/{ci-pipeline/contributions/requirements/ci-pipeline-req-008.json → delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-008.json} +2 -2
- package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-009.json +18 -0
- package/blueprints/{ci-pipeline/contributions/requirements/ci-pipeline-req-010.json → delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-010.json} +2 -2
- package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-011.json +18 -0
- package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-012.json +18 -0
- package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-013.json +18 -0
- package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-014.json +18 -0
- package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-015.json +18 -0
- package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-016.json +18 -0
- package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-017.json +18 -0
- package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-018.json +18 -0
- package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-019.json +18 -0
- package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-020.json +18 -0
- package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-021.json +18 -0
- package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-022.json +18 -0
- package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-023.json +18 -0
- package/blueprints/{ci-pipeline/contributions/tacs/tac-701-ci-pipeline-gate-runner.json → delivery-ci-workflows/contributions/tacs/tac-701-delivery-ci-workflows-gate-runner.json} +3 -3
- package/blueprints/{ci-pipeline/contributions/tacs/tac-702-ci-pipeline-gate-report.json → delivery-ci-workflows/contributions/tacs/tac-702-delivery-ci-workflows-gate-report.json} +1 -1
- package/blueprints/{ci-pipeline/contributions/tacs/tac-703-ci-pipeline-aggregate-report.json → delivery-ci-workflows/contributions/tacs/tac-703-delivery-ci-workflows-aggregate-report.json} +2 -2
- package/blueprints/delivery-ci-workflows/contributions/tacs/tac-704-delivery-ci-workflows-workflow-materialiser.json +64 -0
- package/blueprints/delivery-ci-workflows/contributions/tacs/tac-705-delivery-ci-workflows-release-workflow.json +51 -0
- package/blueprints/delivery-ci-workflows/contributions/tacs/tac-706-delivery-ci-workflows-scheduled-audit.json +38 -0
- package/blueprints/delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6101.json +37 -0
- package/blueprints/{ci-pipeline/contributions/user-stories/ci-pipeline-us-6102.json → delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6102.json} +3 -3
- package/blueprints/{ci-pipeline/contributions/user-stories/ci-pipeline-us-6103.json → delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6103.json} +4 -4
- package/blueprints/{ci-pipeline/contributions/user-stories/ci-pipeline-us-6104.json → delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6104.json} +4 -4
- package/blueprints/{ci-pipeline/contributions/user-stories/ci-pipeline-us-6105.json → delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6105.json} +6 -6
- package/blueprints/{ci-pipeline/contributions/user-stories/ci-pipeline-us-6106.json → delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6106.json} +3 -3
- package/blueprints/{ci-pipeline/contributions/user-stories/ci-pipeline-us-6107.json → delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6107.json} +5 -5
- package/blueprints/{ci-pipeline/contributions/user-stories/ci-pipeline-us-6108.json → delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6108.json} +4 -4
- package/blueprints/delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6109.json +36 -0
- package/blueprints/{ci-pipeline/contributions/user-stories/ci-pipeline-us-6110.json → delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6110.json} +3 -3
- package/blueprints/delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6111.json +36 -0
- package/blueprints/delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6112.json +36 -0
- package/blueprints/delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6113.json +36 -0
- package/blueprints/delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6114.json +46 -0
- package/blueprints/delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6115.json +37 -0
- package/blueprints/delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6116.json +28 -0
- package/blueprints/delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6117.json +28 -0
- package/blueprints/delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6118.json +37 -0
- package/blueprints/delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6119.json +28 -0
- package/blueprints/delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6120.json +28 -0
- package/blueprints/delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6121.json +46 -0
- package/blueprints/delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6122.json +46 -0
- package/blueprints/delivery-ci-workflows/contributions/user-stories/delivery-ci-workflows-us-6123.json +37 -0
- package/blueprints/delivery-ci-workflows/docs/topics.md +61 -0
- package/blueprints/delivery-ci-workflows/guide/delivery-ci-workflows.md +136 -0
- package/blueprints/deploy-cloudflare-workers/docs/topics.md +3 -3
- package/blueprints/email-smtp-resend/docs/topics.md +1 -1
- package/blueprints/observability-essentials/README.md +2 -2
- package/blueprints/observability-essentials/docs/topics.md +5 -5
- package/blueprints/observability-probe-endpoints/docs/topics.md +2 -2
- package/blueprints/persistence-data-d1/README.md +2 -2
- package/blueprints/persistence-data-d1/assets/facade-shape/facade-module-shape.md +1 -1
- package/blueprints/persistence-data-d1/contributions/tacs/tac-1403-persistence-data-d1-deploy-gate.json +1 -1
- package/blueprints/persistence-data-d1/docs/topics.md +2 -2
- package/blueprints/persistence-data-d1/guide/persistence-data-d1.md +1 -1
- package/blueprints/persistence-data-sqlite/README.md +1 -1
- package/blueprints/persistence-data-sqlite/docs/topics.md +1 -1
- package/blueprints/security-auth-clerk/README.md +5 -3
- package/blueprints/security-auth-clerk/assets/middleware/workers-fetch-shape.md +123 -0
- package/blueprints/security-auth-clerk/assets/wiring/workers-wrangler-toml-shape.md +51 -0
- package/blueprints/security-auth-clerk/blueprint.json +1 -1
- package/blueprints/security-auth-clerk/docs/topics.md +2 -2
- package/blueprints/security-auth-clerk/guide/security-auth-clerk.md +9 -0
- package/blueprints/security-auth-keycloak/docs/topics.md +2 -2
- package/blueprints/security-auth-magic-link/README.md +1 -1
- package/blueprints/security-auth-magic-link/docs/topics.md +1 -1
- package/blueprints/security-auth-oauth2/README.md +1 -1
- package/blueprints/security-auth-oauth2/docs/topics.md +2 -2
- package/blueprints/security-secrets-management/README.md +1 -1
- package/blueprints/security-secrets-management/docs/topics.md +3 -3
- package/guidance/build-cycle-playbook.md +2 -2
- package/guidance/document-model.md +1 -1
- package/guidance/harness-template.md +13 -0
- package/guidance/managed/agent-instructions-block.hash +1 -1
- package/guidance/managed/agent-instructions-block.md +13 -0
- package/package.json +5 -2
- package/rcf/adrs/adr-001.json +1 -1
- package/rcf/adrs/adr-009.json +1 -1
- package/rcf/build-sequence.json +1 -1
- package/rcf/manifest.json +2 -2
- package/rcf/prd.json +2 -2
- package/releases/releases.yaml +116 -0
- package/src/blueprint/apply.js +51 -13
- package/src/blueprint/index.js +12 -0
- package/src/blueprint/library-loader.js +271 -0
- package/src/blueprint/library-registry.js +341 -0
- package/src/blueprint/list.js +38 -4
- package/src/blueprint/shelf-resolver.js +144 -31
- package/src/cli/blueprint-library.js +419 -0
- package/src/cli/blueprint.js +46 -9
- package/src/cli/guidance.js +1 -1
- package/src/cli/help.js +27 -1
- package/src/cli/version.js +673 -0
- package/src/cli/view.js +282 -1
- package/src/server/index.js +3 -0
- package/src/server/routes.js +15 -1
- package/src/server/scope-endpoint.js +105 -0
- package/src/view/live-client.js +253 -6
- package/src/view/scope.js +231 -0
- package/src/view/style.css +42 -0
- package/blueprints/ci-pipeline/README.md +0 -49
- package/blueprints/ci-pipeline/assets/ci-provider-examples/github-actions.yml +0 -61
- package/blueprints/ci-pipeline/assets/ci-provider-examples/notes.md +0 -50
- package/blueprints/ci-pipeline/blueprint.json +0 -46
- package/blueprints/ci-pipeline/contributions/adrs/adr-701-ci-pipeline-ci-gates.json +0 -25
- package/blueprints/ci-pipeline/contributions/requirements/ci-pipeline-req-001.json +0 -18
- package/blueprints/ci-pipeline/contributions/requirements/ci-pipeline-req-009.json +0 -18
- package/blueprints/ci-pipeline/contributions/user-stories/ci-pipeline-us-6101.json +0 -37
- package/blueprints/ci-pipeline/contributions/user-stories/ci-pipeline-us-6109.json +0 -36
- package/blueprints/ci-pipeline/docs/topics.md +0 -49
- package/blueprints/ci-pipeline/guide/ci-pipeline.md +0 -79
- package/rcf/.identity/profile.md +0 -37
- package/rcf/knowledge/INDEX.md +0 -12
- package/rcf/knowledge/README.md +0 -41
- package/rcf/knowledge/docs/.gitkeep +0 -0
- package/rcf/knowledge/notes/.gitkeep +0 -0
- /package/blueprints/{ci-pipeline → delivery-ci-workflows}/assets/report-samples/pipeline.json +0 -0
|
@@ -22,7 +22,7 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
|
|
|
22
22
|
| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
|
|
23
23
|
| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
|
|
24
24
|
| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
|
|
25
|
-
| ci-
|
|
25
|
+
| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
|
|
26
26
|
| observability-essentials | 7101-7899 | 8xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics`, `statusPageContract` |
|
|
27
27
|
| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
|
|
28
28
|
| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
|
|
@@ -21,7 +21,7 @@ Phase 1 resolves local path sources only; registry and git-ref resolution is a m
|
|
|
21
21
|
| Status page sample | `assets/status-page-samples/status-page-with-notice.html` | Illustrative rendered HTML with two components and one active incident notice, showing the machine-readable data attributes |
|
|
22
22
|
| Status page empty sample | `assets/status-page-samples/status-page-clean.html` | Illustrative rendered HTML with no active notice, showing the emptyState marker |
|
|
23
23
|
| Guide | `guide/observability-essentials.md` | Operator-facing: when to use it, when not, what stays your call, and the promotion signal for the future metrics and tracing variants |
|
|
24
|
-
| Coordination vocabulary | `docs/topics.md` | The three global-topic strings this blueprint contributes, the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, hello-panel, persistence-data-sqlite, ci-
|
|
24
|
+
| Coordination vocabulary | `docs/topics.md` | The three global-topic strings this blueprint contributes, the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, hello-panel, persistence-data-sqlite, delivery-ci-workflows, observability-essentials) |
|
|
25
25
|
|
|
26
26
|
The doc set is contributions (copied into the project tree by `rcf define blueprint add`); the guide, assets, and docs are package-resident references. Guide rendering into `rcf/knowledge/docs/blueprint-guides/` and asset ingestion are mechanism follow-ups; until they land, the working agent reads them from the applied blueprint's source path recorded in `manifest.blueprints[].source`.
|
|
27
27
|
|
|
@@ -50,4 +50,4 @@ Two HTTP health probes on the request-traffic listener with stable paths and a s
|
|
|
50
50
|
## Known mechanism-reach gaps
|
|
51
51
|
|
|
52
52
|
- **Historical uptime chart on the status page.** Not shipped at v1.0.0. The status page contract (ADR-803) commits to declared components with current state plus incident notices; a rolling window of per-component uptime numbers would require a metrics store the blueprint does not own and a retention window the blueprint should not decide unilaterally. Turning it into a runtime-observable AC ('the chart renders the last 30 days at 1-day granularity') either becomes document-observable ('a chart element is present') or depends on an unowned subsystem. Recorded here rather than smuggled in as a v1 requirement. Promotion signal: a shipped `metrics-store` blueprint (or the persistence-data-sqlite blueprint's event log fed forward) that a metrics-backed `statusPageContract` v1.1 can build on. Project-side workaround until then: a project that wants a history chart authors it on top of the declared component vocabulary using a project-owned metrics substrate.
|
|
53
|
-
- **Notification outcome grep gate.** ADR-805 requires every notification-attempting code path to invoke `recordOutcome` exactly once before returning. The blueprint states the invariant as an AC (AC-7106-1); the mechanism does not compel a project's source tree to only call the transport through the sink. The practical enforcement is a project-side grep gate ('every call to the notification transport is preceded by recordOutcome for that notificationId'), which the blueprint does not ship. A project that skips the gate produces the silent-notification defect the blueprint exists to prevent, and no build-cycle gate refuses the FBS. Promotion signal: a lint-rule or CI-gate contribution in a future rcf-lite blueprint or in the ci-
|
|
53
|
+
- **Notification outcome grep gate.** ADR-805 requires every notification-attempting code path to invoke `recordOutcome` exactly once before returning. The blueprint states the invariant as an AC (AC-7106-1); the mechanism does not compel a project's source tree to only call the transport through the sink. The practical enforcement is a project-side grep gate ('every call to the notification transport is preceded by recordOutcome for that notificationId'), which the blueprint does not ship. A project that skips the gate produces the silent-notification defect the blueprint exists to prevent, and no build-cycle gate refuses the FBS. Promotion signal: a lint-rule or CI-gate contribution in a future rcf-lite blueprint or in the delivery-ci-workflows blueprint's shipped ruleset. Project-side workaround: author the grep gate as a project-authored TC bound to AC-7106-1.
|
|
@@ -6,9 +6,9 @@ This file is the observability-essentials half of the cross-blueprint contract.
|
|
|
6
6
|
|
|
7
7
|
| Topic string | observability-essentials contribution | Origin | Composition note |
|
|
8
8
|
|---|---|---|---|
|
|
9
|
-
| `healthProbes` | ADR-801-observability-essentials-health-probes | Minted here; pre-cleared as unclaimed against application-spa (`clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel`), application-api-rest (`errorEnvelope`, `authModel`, `apiVersioning`, `logging`), security-auth-magic-link (`authModel`), persistence-data-sqlite (`persistenceStore`, `migrationDiscipline`), ci-
|
|
10
|
-
| `readinessSemantics` | ADR-802-observability-essentials-readiness-semantics | Minted here; pre-cleared as unclaimed against application-spa, application-api-rest, security-auth-magic-link, persistence-data-sqlite, ci-
|
|
11
|
-
| `statusPageContract` | ADR-803-observability-essentials-status-page-contract | Minted here; pre-cleared as unclaimed against application-spa, application-api-rest, security-auth-magic-link, persistence-data-sqlite, ci-
|
|
9
|
+
| `healthProbes` | ADR-801-observability-essentials-health-probes | Minted here; pre-cleared as unclaimed against application-spa (`clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel`), application-api-rest (`errorEnvelope`, `authModel`, `apiVersioning`, `logging`), security-auth-magic-link (`authModel`), persistence-data-sqlite (`persistenceStore`, `migrationDiscipline`), delivery-ci-workflows (`ciGates`, `strictCoverageGate`), and the hello-panel walkthrough exemplar (`operatorPanel`) | The one HTTP health probe contract for the project: two endpoints (liveness /healthz, readiness /readyz), shared JSON body shape, served on the request-traffic listener. A composing blueprint that holds a different endpoint contract (a single /health endpoint, gRPC health protocol, probes on a separate admin port) contributes its own scope:global ADR on this exact string and lets composition surface the pairing. Expected resolution: one project-level ADR that fixes the endpoint contract |
|
|
10
|
+
| `readinessSemantics` | ADR-802-observability-essentials-readiness-semantics | Minted here; pre-cleared as unclaimed against application-spa, application-api-rest, security-auth-magic-link, persistence-data-sqlite, delivery-ci-workflows, and hello-panel | The one readiness aggregation and declaration scope for the project: strict-any-fail over an explicit boot-time-declared dependency set, evaluated against per-dep cached state. A composing blueprint that holds a different opinion (quorum aggregation, write-path-only readiness, graceful-degradation model) conflicts here by design. Expected resolution: one project-level ADR fixing the semantics |
|
|
11
|
+
| `statusPageContract` | ADR-803-observability-essentials-status-page-contract | Minted here; pre-cleared as unclaimed against application-spa, application-api-rest, security-auth-magic-link, persistence-data-sqlite, delivery-ci-workflows, and hello-panel | The one public status page contract for the project: declared component list plus fixed state enum plus stable-fielded incident notices. A composing blueprint that wants a different public contract (JSON endpoint at /status.json, historical uptime cells as v1 requirement, webhook-posted notices) conflicts here by design. Expected resolution: one project-level ADR fixing the public contract |
|
|
12
12
|
|
|
13
13
|
The observability-essentials blueprint claims three global topics. Every other contribution is scope-local (ADR-804 probe secrecy and ADR-805 notification outcome model do not contribute global topics; a composing blueprint that holds an opinion on probe auth policy or notification outcome shape authors its own project-level ADR if it wants to override).
|
|
14
14
|
|
|
@@ -34,7 +34,7 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
|
|
|
34
34
|
| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
|
|
35
35
|
| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
|
|
36
36
|
| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
|
|
37
|
-
| ci-
|
|
37
|
+
| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
|
|
38
38
|
| observability-essentials | 7101-7899 | 8xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics`, `statusPageContract` |
|
|
39
39
|
| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
|
|
40
40
|
| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
|
|
@@ -46,7 +46,7 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
|
|
|
46
46
|
|
|
47
47
|
US 7101-7110 sit at the LOW end of the 7101-7899 band on purpose. A project-side story that mechanically derives from an observability-essentials REQs id into the number `7110` would collide against observability-essentials-US-7110 in this package; the band leaves headroom at the HIGH end (US 7181-7899) so a project's own stories anchored to observability-essentials REQs can allocate without conflict. The watchpost run4 lesson applies here too.
|
|
48
48
|
|
|
49
|
-
Row-status caveat: the ci-
|
|
49
|
+
Row-status caveat: the delivery-ci-workflows seat shipped first (PR #95 merged at 595cab9c on main). This branch was rebased onto that main; the delivery-ci-workflows row reflects the shipped state, and the observability row flips to `shipped v1.0.0` at this branch's merge (Dave coordinates that final flip in the merge commit or an immediate follow-up).
|
|
50
50
|
|
|
51
51
|
## Shared expectations for future composing blueprints
|
|
52
52
|
|
|
@@ -15,7 +15,7 @@ Note on the deliberate conflict with observability-essentials: this blueprint is
|
|
|
15
15
|
|
|
16
16
|
Note on the delineation from observability-essentials's `statusPageContract` topic: this blueprint does not contribute an opinion on the public status page. A project that wants the probe surface from this blueprint AND the public status page and notification outcome sink from observability-essentials resolves the two `healthProbes` and `readinessSemantics` conflicts with project-level ADRs and keeps `statusPageContract` on the essentials-supplied side; the blueprints then compose without further conflict.
|
|
17
17
|
|
|
18
|
-
Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, persistence-data-sqlite, ci-
|
|
18
|
+
Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, persistence-data-sqlite, delivery-ci-workflows, observability-essentials, security-secrets-management, security-auth-clerk, email-smtp-resend, and deploy-cloudflare-workers vocabularies, restated as law): lower camel case, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer. Do not mint variants of existing strings (`probeInterface`, `probeSurface`, `probes`, `livenessReadiness`, `probeTransport` are all wrong when `healthProbes` already exists; `readinessAggregation`, `readyPolicy`, `readinessRule` are all wrong when `readinessSemantics` already exists).
|
|
19
19
|
|
|
20
20
|
## Id number bands (registry bootstrap)
|
|
21
21
|
|
|
@@ -31,7 +31,7 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
|
|
|
31
31
|
| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
|
|
32
32
|
| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
|
|
33
33
|
| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
|
|
34
|
-
| ci-
|
|
34
|
+
| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
|
|
35
35
|
| observability-essentials | 7101-7899 | 8xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics`, `statusPageContract` |
|
|
36
36
|
| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
|
|
37
37
|
| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
|
|
@@ -21,7 +21,7 @@ Phase 1 resolves local path sources only; registry and git-ref resolution is a m
|
|
|
21
21
|
| Facade module shape sample | `assets/facade-shape/facade-module-shape.md` | The exact shape of the D1 store facade module (`createStore({ env, bindingName, onEvent })` factory, named verbs, prepared-statement discipline, batch atomicity) with a worked domain example |
|
|
22
22
|
| Batch usage sample | `assets/batch-usage/batch-atomicity-example.md` | The exact shape of a multi-statement atomic write through `db.batch([...])`, with the mid-batch-failure rollback semantics called out |
|
|
23
23
|
| Guide | `guide/persistence-data-d1.md` | Operator-facing: when to use it, when not, what stays your call, and the promotion signals for the sibling single-file SQLite blueprint and future Postgres or replication blueprints |
|
|
24
|
-
| Coordination vocabulary | `docs/topics.md` | The two global-topic strings this blueprint contributes and the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, email-smtp-resend, persistence-data-sqlite, ci-
|
|
24
|
+
| Coordination vocabulary | `docs/topics.md` | The two global-topic strings this blueprint contributes and the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, email-smtp-resend, persistence-data-sqlite, delivery-ci-workflows, observability-essentials, security-secrets-management, security-auth-clerk, persistence-data-d1) |
|
|
25
25
|
|
|
26
26
|
The doc set is contributions (copied into the project tree by `rcf define blueprint add`); the guide, assets, and docs are package-resident references. Guide rendering into `rcf/knowledge/docs/blueprint-guides/` and asset ingestion are mechanism follow-ups; until they land, the working agent reads them from the applied blueprint's source path recorded in `manifest.blueprints[].source`.
|
|
27
27
|
|
|
@@ -31,7 +31,7 @@ Contributed kinds: REQ, US (with inline ACs), TAC, ADR. Adherence is expressed a
|
|
|
31
31
|
|
|
32
32
|
No FBS contributions, as a matter of principle (ratified policy 2026-08-19): FBSs are the work of the implementing agent, not the blueprint; project constraints have to be applied at the time of creation. The blueprint contributes the WHAT (the store facade contract, the wrangler-owned migration discipline, the deploy-pipeline gate contract, the prepared-statement and batch atomicity boundaries, the two-path recovery model, the metadata-only event log discipline); the implementing agent derives the HOW-tasks (FBS) in the host project, where the ACs contributed here get picked up by the project's own build sequencing.
|
|
33
33
|
|
|
34
|
-
Deliberately not contributed: the domain schema (the tables the project's own entities live in are project-authored, on top of the migration directory the project maintains; the blueprint governs the facade contract and the migration discipline, not the domain shape); an ORM or query builder above the D1 prepared-statement surface (the facade is a project-authored surface; how it internally implements its verbs above the vendor binding is not blueprint-owned, but the boundary discipline refuses raw-SQL passthrough on the public surface); a Worker deploy blueprint (a companion `deploy-cloudflare-workers` blueprint is the natural pair for the Worker deploy step the deploy-gate TAC assumes; until it ships, projects wire their own deploy step); a secrets management surface for the CI credential that runs `wrangler d1 migrations apply` and `wrangler deploy` (the credential storage and rotation posture are the concern of the `security-secrets-management` blueprint, not this one); a CI pipeline template (CI shape is the concern of the `ci-
|
|
34
|
+
Deliberately not contributed: the domain schema (the tables the project's own entities live in are project-authored, on top of the migration directory the project maintains; the blueprint governs the facade contract and the migration discipline, not the domain shape); an ORM or query builder above the D1 prepared-statement surface (the facade is a project-authored surface; how it internally implements its verbs above the vendor binding is not blueprint-owned, but the boundary discipline refuses raw-SQL passthrough on the public surface); a Worker deploy blueprint (a companion `deploy-cloudflare-workers` blueprint is the natural pair for the Worker deploy step the deploy-gate TAC assumes; until it ships, projects wire their own deploy step); a secrets management surface for the CI credential that runs `wrangler d1 migrations apply` and `wrangler deploy` (the credential storage and rotation posture are the concern of the `security-secrets-management` blueprint, not this one); a CI pipeline template (CI shape is the concern of the `delivery-ci-workflows` blueprint, not this one; this blueprint contributes the requirement that the migrations-apply step orders strictly before the deploy step, not the file that implements it); a replication or failover surface (D1's read-replica surface is a read-scaling primitive, not a failover primitive; a project needing failover supersedes ADR-1401 with an alternate engine); a logical schema-agnostic dump beyond the vendor's `wrangler d1 export` (out of scope; see ADR-1405's alternatives).
|
|
35
35
|
|
|
36
36
|
## The two global decisions
|
|
37
37
|
|
|
@@ -112,4 +112,4 @@ Not a runnable facade. The snippets above are the SHAPE; a project's own domain
|
|
|
112
112
|
|
|
113
113
|
Not an ORM. Projects that reach for Drizzle or Kysely wire it inside the verb bodies and preserve the outward verb surface. The prepared-statement discipline (static SQL literals inside the verb, values only through `bind`) survives an ORM: most ORMs emit static SQL from typed queries at build time, and the AC-13104-1 grep still lands on static literals.
|
|
114
114
|
|
|
115
|
-
Not the ci-
|
|
115
|
+
Not the delivery-ci-workflows gate. TAC-1403's deploy-gate is a CI file, not a facade responsibility; the two surfaces meet only through the shared event-record shape.
|
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
"description": "The directory the apply step reads; the file set at HEAD determines what the apply attempts."
|
|
33
33
|
}
|
|
34
34
|
],
|
|
35
|
-
"tradeoffs": "Ordering the apply strictly before the deploy costs a small amount of CI latency per environment (one wrangler invocation, one round trip to the D1 API) in exchange for making the schema-behind-the-code state impossible in production. Projects that need faster CI can parallelise across environments, but never inside one environment's apply-then-deploy sequence. The gate is a project-authored CI file; the blueprint does not ship a CI template, because CI shape is a `ci-
|
|
35
|
+
"tradeoffs": "Ordering the apply strictly before the deploy costs a small amount of CI latency per environment (one wrangler invocation, one round trip to the D1 API) in exchange for making the schema-behind-the-code state impossible in production. Projects that need faster CI can parallelise across environments, but never inside one environment's apply-then-deploy sequence. The gate is a project-authored CI file; the blueprint does not ship a CI template, because CI shape is a `delivery-ci-workflows`-adjacent concern the project owns.",
|
|
36
36
|
"createdAt": "2026-08-30T00:00:00Z",
|
|
37
37
|
"updatedAt": "2026-08-30T00:00:00Z"
|
|
38
38
|
}
|
|
@@ -13,7 +13,7 @@ The persistence-data-d1 blueprint claims two global topics. Every other contribu
|
|
|
13
13
|
|
|
14
14
|
Note on the delineation from the application-api-rest blueprint's `logging` topic: `logging` (owned by application-api-rest ADR-304) governs the wire-log shape of the HTTP tier. This blueprint's ADR-1403 governs the STORE-EVENT log shape (facadeReady, migrationsApplied, backupExported, timeTravelRestored, queryFailed). The two log surfaces may share a shipper but do not share a topic. A blueprint that contributes a unified log discipline across all tiers would author its own scope:global ADR on `logging` and expect to conflict with the REST blueprint there, not here.
|
|
15
15
|
|
|
16
|
-
Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, persistence-data-sqlite, ci-
|
|
16
|
+
Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, persistence-data-sqlite, delivery-ci-workflows, observability-essentials, security-secrets-management, security-auth-clerk, and email-smtp-resend vocabularies, restated as law): lower camel case, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer. Do not mint variants of existing strings (`store`, `dataStore`, `db`, `dbEngine`, `d1Store`, `edgeStore` are all wrong when `persistenceStore` already exists; `schemaMigrations`, `dbMigrations`, `wranglerMigrations`, `migrations` are all wrong when `migrationDiscipline` already exists).
|
|
17
17
|
|
|
18
18
|
## Id number bands (registry bootstrap)
|
|
19
19
|
|
|
@@ -29,7 +29,7 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
|
|
|
29
29
|
| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
|
|
30
30
|
| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
|
|
31
31
|
| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
|
|
32
|
-
| ci-
|
|
32
|
+
| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
|
|
33
33
|
| observability-essentials | 7101-7899 | 8xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics`, `statusPageContract` |
|
|
34
34
|
| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
|
|
35
35
|
| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
|
|
@@ -16,7 +16,7 @@ Not a Worker deploy blueprint. The deploy-gate TAC assumes a `wrangler deploy` s
|
|
|
16
16
|
|
|
17
17
|
Not a secrets-management blueprint. The CI credential that runs `wrangler d1 migrations apply` and `wrangler deploy` (the `CLOUDFLARE_API_TOKEN`, or the OAuth-scoped credential the vendor issues) is a secret whose storage and rotation posture the `security-secrets-management` blueprint governs. This blueprint references the credential by role, not by name or storage path.
|
|
18
18
|
|
|
19
|
-
Not a CI-pipeline blueprint. The deploy-gate TAC contributes the requirement that `wrangler d1 migrations apply` orders strictly before `wrangler deploy` and the deploy job refuses on apply failure; the CI file that implements that ordering is the concern of the `ci-
|
|
19
|
+
Not a CI-pipeline blueprint. The deploy-gate TAC contributes the requirement that `wrangler d1 migrations apply` orders strictly before `wrangler deploy` and the deploy job refuses on apply failure; the CI file that implements that ordering is the concern of the `delivery-ci-workflows` blueprint or the project's own CI-authoring practice.
|
|
20
20
|
|
|
21
21
|
Not a logical-dump story beyond the vendor's export. Backups are `wrangler d1 export` artifacts; cross-engine migration and portable dumps beyond D1's own `.sql` export are out of scope. Projects that need a schema-agnostic dump layer a project-authored dump runner beside the file-level runner.
|
|
22
22
|
|
|
@@ -21,7 +21,7 @@ Phase 1 resolves local path sources only; registry and git-ref resolution is a m
|
|
|
21
21
|
| SQLite backup procedure | `assets/backup-procedures/sqlite-file-copy.md` | The downtime-free file-copy procedure under WAL, with the online-backup and checkpoint-then-copy paths |
|
|
22
22
|
| WAL checkpoint note | `assets/backup-procedures/hot-checkpoint-note.md` | Why a checkpoint before a bare cp works, and when the online-backup API is the safer path |
|
|
23
23
|
| Guide | `guide/persistence-data-sqlite.md` | Operator-facing: when to use it, when not, what stays your call, and the promotion signal for the future Postgres variant |
|
|
24
|
-
| Coordination vocabulary | `docs/topics.md` | The two global-topic strings this blueprint contributes, the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, hello-panel, persistence-data-sqlite, ci-
|
|
24
|
+
| Coordination vocabulary | `docs/topics.md` | The two global-topic strings this blueprint contributes, the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, hello-panel, persistence-data-sqlite, delivery-ci-workflows, observability-essentials) |
|
|
25
25
|
|
|
26
26
|
The doc set is contributions (copied into the project tree by `rcf define blueprint add`); the guide, assets, and docs are package-resident references. Guide rendering into `rcf/knowledge/docs/blueprint-guides/` and asset ingestion are mechanism follow-ups; until they land, the working agent reads them from the applied blueprint's source path recorded in `manifest.blueprints[].source`.
|
|
27
27
|
|
|
@@ -29,7 +29,7 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
|
|
|
29
29
|
| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
|
|
30
30
|
| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
|
|
31
31
|
| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
|
|
32
|
-
| ci-
|
|
32
|
+
| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
|
|
33
33
|
| observability-essentials | 7101-7899 | 8xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics`, `statusPageContract` |
|
|
34
34
|
| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
|
|
35
35
|
| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# Security auth Clerk blueprint (v1.
|
|
1
|
+
# Security auth Clerk blueprint (v1.1.0)
|
|
2
2
|
|
|
3
3
|
The tenth content blueprint on the rcf-build-lite blueprint mechanism, category `security`. A Clerk-committed sibling to `security-auth-magic-link` on the `authModel` global topic: Clerk hosts the identity surface (users, sessions, sign-in UX, credential storage, MFA, account recovery); the project owns a framework-agnostic middleware boundary, a session verifier confined to one module, a Clerk-claim-to-project-verb authorisation adapter, and a reduced principal shape the rest of the codebase reasons against. Targeted at small greenfield rcf-lite projects that want hosted identity without building the user-and-session surface themselves; larger deployments supersede the vendor by superseding ADR-1001 with a project-level ADR and swapping the middleware and verifier adapters.
|
|
4
4
|
|
|
@@ -20,10 +20,12 @@ Composing with `security-auth-magic-link` (or any other blueprint contributing `
|
|
|
20
20
|
| Doc set | `contributions/` | 9 REQs, 11 USs (25 ACs), 4 TACs, 5 ADRs, all schema-valid and namespaced (`security-auth-clerk-REQ-001` prefix family; `ADR-1001-security-auth-clerk-auth-model` suffix family) |
|
|
21
21
|
| React-family sample | `assets/wiring/clerk-provider-react.md` | The shape of a `ClerkProvider` wiring in a React-family client tier: where the provider mounts, what the SPA blueprint's session-and-redirect posture composes with |
|
|
22
22
|
| Vue-family sample | `assets/wiring/clerk-provider-vue.md` | The same shape rendered for a Vue-family client tier so the operator can pattern-match without a framework translation step |
|
|
23
|
-
| Middleware sample | `assets/middleware/node-middleware-shape.md` | The framework-agnostic middleware boundary contract (`verify(request)`), with adapter samples for Express and Fastify |
|
|
23
|
+
| Middleware sample (Node) | `assets/middleware/node-middleware-shape.md` | The framework-agnostic middleware boundary contract (`verify(request)`), with adapter samples for Express and Fastify |
|
|
24
|
+
| Middleware sample (Workers) | `assets/middleware/workers-fetch-shape.md` | The Cloudflare Workers fetch-handler adapter around the same `verify(request)` contract; a project on Workers picks up this file, a project on Node picks up the Node sample |
|
|
25
|
+
| Workers wrangler integration | `assets/wiring/workers-wrangler-toml-shape.md` | The wrangler.toml overlay a Workers deployer applies: `nodejs_compat`, `CLERK_SIGN_IN_URL`, the Clerk secret names, and the `run_worker_first` posture the auth-gate bypass finding required |
|
|
24
26
|
| Role-claim mapping | `assets/authorisation/role-claim-mapping-sample.md` | A worked verb-to-role mapping-table example, with the reduction from Clerk's `org:role` claim shape into the project's `roles` array |
|
|
25
27
|
| Guide | `guide/security-auth-clerk.md` | Operator-facing: when to use it, when not, the promotion signals for the OAuth2 and Keycloak siblings, the operator decisions that remain open, the cost-honesty paragraph |
|
|
26
|
-
| Coordination vocabulary | `docs/topics.md` | The one global-topic string this blueprint contributes and the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, email-smtp-resend, persistence-data-sqlite, ci-
|
|
28
|
+
| Coordination vocabulary | `docs/topics.md` | The one global-topic string this blueprint contributes and the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, email-smtp-resend, persistence-data-sqlite, delivery-ci-workflows, observability-essentials, security-secrets-management, security-auth-clerk) |
|
|
27
29
|
|
|
28
30
|
The doc set is contributions (copied into the project tree by `rcf define blueprint add`); the guide, assets, and docs are package-resident references. Guide rendering into `rcf/knowledge/docs/blueprint-guides/` and asset ingestion are mechanism follow-ups; until they land, the working agent reads them from the applied blueprint's source path recorded in `manifest.blueprints[].source`.
|
|
29
31
|
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Workers fetch-handler shape
|
|
2
|
+
|
|
3
|
+
The Cloudflare Workers adapter for the middleware boundary (TAC-1001). Chooser: a project on Node picks up `node-middleware-shape.md` (Express or Fastify adapter around `verify(request)`); a project on Workers picks up this file. Both adapters wrap the same `verify` contract; the reduced `Principal` shape the project reasons against downstream is identical.
|
|
4
|
+
|
|
5
|
+
## Why Workers gets its own sample
|
|
6
|
+
|
|
7
|
+
The framework-agnostic `verify(request)` contract (TAC-1001 responsibility 1) already carries onto Workers. What differs is mechanical:
|
|
8
|
+
|
|
9
|
+
- **Request object.** The handler receives a Fetch API `Request`; header reads go through `request.headers.get('cookie')`, not `request.headers.cookie`. There is no `req.accepts()`; content-negotiation is a header inspection on `accept`.
|
|
10
|
+
- **Response shape.** Handlers return a Fetch API `Response` synchronously; there is no `res.status().json()` chain. The refusal paths return `new Response(...)` bodies.
|
|
11
|
+
- **Secret transport.** The Clerk secret arrives on `env.CLERK_SECRET_KEY` (and `env.CLERK_PUBLISHABLE_KEY`) at request time, not from `process.env` at module load. The `createVerify` factory therefore runs inside the fetch handler, not at module top-level; a per-request construction is cheap because Clerk's `authenticateRequest` is the network cost, not the client construction.
|
|
12
|
+
- **Session-cookie parse.** Clerk's `@clerk/backend` `authenticateRequest(request, ...)` reads the `__session` cookie off the Fetch `Request` itself; no manual cookie header parsing is needed at the middleware seam. The pre-check below (a substring test for `__session=`) is a fast-path refusal so unauthenticated hits do not incur an SDK round trip.
|
|
13
|
+
|
|
14
|
+
## The Workers fetch adapter
|
|
15
|
+
|
|
16
|
+
```
|
|
17
|
+
// src/auth/adapters/workers.mjs
|
|
18
|
+
import { createSessionVerifier } from '../session-verifier.mjs';
|
|
19
|
+
import { reduceClaims } from '../claims-mapper.mjs';
|
|
20
|
+
|
|
21
|
+
function jsonResponse(body, status) {
|
|
22
|
+
return new Response(JSON.stringify(body), {
|
|
23
|
+
status,
|
|
24
|
+
headers: { 'content-type': 'application/json' }
|
|
25
|
+
});
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export function createVerify({ clerkSecretKey, clerkPublishableKey, auditSink, clock }) {
|
|
29
|
+
const verifier = createSessionVerifier({
|
|
30
|
+
clerkSecretKey,
|
|
31
|
+
clerkPublishableKey,
|
|
32
|
+
auditSink,
|
|
33
|
+
clock
|
|
34
|
+
});
|
|
35
|
+
|
|
36
|
+
return async function verify(request) {
|
|
37
|
+
// Fast-path refusal without an SDK round trip.
|
|
38
|
+
const cookieHeader = request.headers.get('cookie') ?? '';
|
|
39
|
+
if (!/(?:^|;\s*)__session=/.test(cookieHeader)) {
|
|
40
|
+
return { authenticated: false, reason: 'no-session-cookie' };
|
|
41
|
+
}
|
|
42
|
+
// Clerk's authenticateRequest reads the __session cookie off the Request
|
|
43
|
+
// and does the vendor-verified session verification server-side.
|
|
44
|
+
const result = await verifier.verifySessionCookie(null, request);
|
|
45
|
+
if (!result.valid) {
|
|
46
|
+
return { authenticated: false, reason: result.reason ?? 'invalid-session' };
|
|
47
|
+
}
|
|
48
|
+
let principal;
|
|
49
|
+
try {
|
|
50
|
+
principal = reduceClaims(result.claims);
|
|
51
|
+
} catch (err) {
|
|
52
|
+
return { authenticated: false, reason: 'claims-map-failed' };
|
|
53
|
+
}
|
|
54
|
+
return { authenticated: true, principal };
|
|
55
|
+
};
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
// One-file adapter that a route dispatcher inside `fetch()` can call.
|
|
59
|
+
// The blueprint does not mandate any particular router; the shape below is
|
|
60
|
+
// the seam a project's router calls into. Route dispatch stays a project
|
|
61
|
+
// concern.
|
|
62
|
+
export function workersRequireAuth({ verify }) {
|
|
63
|
+
return async function requireAuth(request) {
|
|
64
|
+
const result = await verify(request);
|
|
65
|
+
if (result.authenticated) {
|
|
66
|
+
return { ok: true, principal: result.principal };
|
|
67
|
+
}
|
|
68
|
+
const wantsHtml = (request.headers.get('accept') ?? '').includes('text/html');
|
|
69
|
+
const refusal = wantsHtml
|
|
70
|
+
? Response.redirect(new URL('/sign-in', request.url).toString(), 302)
|
|
71
|
+
: jsonResponse({ error: 'unauthenticated', reason: result.reason }, 401);
|
|
72
|
+
return { ok: false, refusal };
|
|
73
|
+
};
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Wiring it inside a fetch handler
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
// src/worker.mjs
|
|
81
|
+
import { createVerify, workersRequireAuth } from './auth/adapters/workers.mjs';
|
|
82
|
+
|
|
83
|
+
export default {
|
|
84
|
+
async fetch(request, env, ctx) {
|
|
85
|
+
const url = new URL(request.url);
|
|
86
|
+
|
|
87
|
+
// Public probes and the sign-in redirect run before the auth gate.
|
|
88
|
+
if (url.pathname === '/health' && request.method === 'GET') {
|
|
89
|
+
return new Response(null, { status: 200 });
|
|
90
|
+
}
|
|
91
|
+
if (url.pathname === '/sign-in') {
|
|
92
|
+
return Response.redirect(env.CLERK_SIGN_IN_URL, 302);
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
// Auth-gated routes go through the middleware boundary.
|
|
96
|
+
const verify = createVerify({
|
|
97
|
+
clerkSecretKey: env.CLERK_SECRET_KEY,
|
|
98
|
+
clerkPublishableKey: env.CLERK_PUBLISHABLE_KEY,
|
|
99
|
+
auditSink: (evt) => console.log(JSON.stringify({ ...evt, kind: 'audit' })),
|
|
100
|
+
clock: () => new Date()
|
|
101
|
+
});
|
|
102
|
+
const requireAuth = workersRequireAuth({ verify });
|
|
103
|
+
|
|
104
|
+
if (url.pathname.startsWith('/api/')) {
|
|
105
|
+
const authResult = await requireAuth(request);
|
|
106
|
+
if (!authResult.ok) return authResult.refusal;
|
|
107
|
+
// request.auth is a Fetch API surface convention the project owns:
|
|
108
|
+
// attach the principal onto a locals object the route handler reads.
|
|
109
|
+
return dispatchApi(url, request, env, ctx, authResult.principal);
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
return env.ASSETS.fetch(request);
|
|
113
|
+
}
|
|
114
|
+
};
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
## Notes
|
|
118
|
+
|
|
119
|
+
- **Attachment convention.** The Fetch `Request` is immutable, so the middleware cannot literally set `request.auth`. The Workers adapter's shape returns `{ ok, principal, refusal }` and the route handler carries the `principal` forward as a function argument. AC-9101-2's runtime observation binds against the reduced `Principal` shape on the successful path either way; the mechanism of attachment is framework-shaped, not contract-shaped.
|
|
120
|
+
- **SDK boundary discipline.** Only `session-verifier.mjs` and this adapter's `createVerify` factory import from `@clerk/backend`. AC-9102-2's source-tree scan still holds on Workers; the two-module allowance covers the Workers case unchanged.
|
|
121
|
+
- **Refusal shape.** The 401 JSON body for API-shaped routes and the 302 redirect for HTML-shaped routes match the Node adapters. AC-9103-2 and AC-9103-3 read the same shapes.
|
|
122
|
+
- **Static-asset ordering.** The wrangler `[assets]` binding serves files before the fetch handler runs by default, which silently bypasses this middleware on any URL that also resolves to a static file. The `run_worker_first` posture on any auth-gated route is a wrangler-configuration concern; the workers wrangler.toml sample carries the fix.
|
|
123
|
+
- **Runtime.** The verifier calls into `@clerk/backend` which needs Node built-ins; wrangler's `compatibility_flags = ["nodejs_compat"]` is the enabling flag on the wrangler side. This is a runtime-config concern, not a middleware-shape concern.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Workers wrangler.toml integration note
|
|
2
|
+
|
|
3
|
+
The wrangler-side configuration a project needs when the Clerk middleware runs inside a Cloudflare Worker. This is a composition boundary between this blueprint (owns the middleware and session-verifier contracts) and `deploy-cloudflare-workers` (owns the wrangler shape); the notes below are the Clerk-specific overlay a Workers deployer applies on top of that blueprint's wrangler-toml sample.
|
|
4
|
+
|
|
5
|
+
## The Clerk-specific overlay
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
# wrangler.toml - Clerk-specific overlay
|
|
9
|
+
compatibility_flags = ["nodejs_compat"]
|
|
10
|
+
|
|
11
|
+
[vars]
|
|
12
|
+
# Public URL of the Clerk-hosted sign-in surface. Not a secret; safe to
|
|
13
|
+
# commit. The middleware's HTML refusal path redirects here.
|
|
14
|
+
CLERK_SIGN_IN_URL = "https://<clerk-subdomain>.accounts.dev/sign-in"
|
|
15
|
+
|
|
16
|
+
[assets]
|
|
17
|
+
directory = "./public"
|
|
18
|
+
binding = "ASSETS"
|
|
19
|
+
# Every auth-gated route that could collide with a static file must appear
|
|
20
|
+
# here, or the assets binding serves the static file BEFORE the fetch
|
|
21
|
+
# handler runs and the middleware is silently bypassed. See the composition
|
|
22
|
+
# note below.
|
|
23
|
+
run_worker_first = ["/api/*", "/sign-in"]
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Secrets are declared by name only, in the deploy blueprint's discipline: no `[secrets]` block in wrangler.toml (that block is decorative and not honoured by wrangler at 4.x, per the deploy blueprint's F-009 fix), and no value in any committed file. The two names the Clerk middleware reads are:
|
|
27
|
+
|
|
28
|
+
- `CLERK_SECRET_KEY` - server-side Clerk API key, read as `env.CLERK_SECRET_KEY` by `session-verifier.mjs`.
|
|
29
|
+
- `CLERK_PUBLISHABLE_KEY` - Clerk publishable key, read as `env.CLERK_PUBLISHABLE_KEY` by `session-verifier.mjs`.
|
|
30
|
+
|
|
31
|
+
Bootstrap-and-steady-state guidance for setting the values lives on the deploy blueprint's `bootstrap-vs-steady-state.md` asset; the shape is the same for both Clerk secrets.
|
|
32
|
+
|
|
33
|
+
## The auth-gate bypass finding
|
|
34
|
+
|
|
35
|
+
The default `[assets]` binding on a Cloudflare Worker serves any file in the assets directory at its path before the Worker's `fetch` handler runs. If an auth-gated route (`/notes` for a UI page, `/api/notes` for an API surface) collides with a static file at the same path, the static file is served without ever hitting the middleware. This is a silent auth bypass at ship time; a project ships assuming the middleware protects `/notes` and only finds out on the first live probe that `/notes` returned the HTML shell to an unauthenticated request.
|
|
36
|
+
|
|
37
|
+
The `run_worker_first` array is the wrangler-side fix: every path listed there is routed through the fetch handler before the assets binding gets a chance. A project on the middleware boundary shape should list every auth-gated route class on the list.
|
|
38
|
+
|
|
39
|
+
The composition responsibility is shared: `deploy-cloudflare-workers` teaches the mechanism (`run_worker_first` in wrangler-toml-shape.md, its US-12101 AC-12101-4 is the runtime-observable acceptance), and this blueprint teaches which routes need it (every auth-gated one on the project's HTTP surface). Neither blueprint carries the project's route list; that emerges from the project's own routing surface.
|
|
40
|
+
|
|
41
|
+
## What is NOT taught here
|
|
42
|
+
|
|
43
|
+
- **Which routes are gated.** The blueprint fixes the middleware boundary shape and the auth model. The concrete route list is a project decision the wrangler.toml integrates against.
|
|
44
|
+
- **How the assets binding composes with static-first vs worker-first per-path routing.** The rules and mechanism belong to the deploy blueprint.
|
|
45
|
+
- **Custom-domain vs workers.dev-only production URL.** Same: deploy blueprint concern. The Clerk overlay above is identical either way.
|
|
46
|
+
|
|
47
|
+
## Notes
|
|
48
|
+
|
|
49
|
+
- The `CLERK_SIGN_IN_URL` var is not a secret. Committing it in `wrangler.toml [vars]` is the default; a project that wants the value to differ across environments moves it to an environment-specific `[env.<name>.vars]` block per wrangler's standard shape.
|
|
50
|
+
- The `nodejs_compat` flag is required because `@clerk/backend` relies on Node built-ins. Without it, the Worker fails to start with a runtime error naming the missing built-in.
|
|
51
|
+
- Reading the secret at request time from `env` (not at module top-level from `process.env`) is what the workers-fetch-shape sample's `createVerify` factory does; the two files together are the enabling shape.
|
|
@@ -10,7 +10,7 @@ This file is the security-auth-clerk half of the cross-blueprint contract. The P
|
|
|
10
10
|
|
|
11
11
|
The security-auth-clerk blueprint claims one global topic. Every other contribution is scope-local (ADR-1002 through ADR-1005 name the middleware-boundary shape, the authorisation-adapter contract, the claims-mapping discipline, and the session-lifecycle posture without contributing global topics; a composing blueprint that holds a different opinion on any of them authors its own project-level ADR if it wants to override).
|
|
12
12
|
|
|
13
|
-
Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, persistence-data-sqlite, ci-
|
|
13
|
+
Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, persistence-data-sqlite, delivery-ci-workflows, observability-essentials, and security-secrets-management vocabularies, restated as law): lower camel case, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer. Do not mint variants of existing strings (`identity`, `identityProvider`, `authVendor`, `signIn` are all wrong when `authModel` already exists).
|
|
14
14
|
|
|
15
15
|
## Id number bands (registry bootstrap)
|
|
16
16
|
|
|
@@ -26,7 +26,7 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
|
|
|
26
26
|
| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
|
|
27
27
|
| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
|
|
28
28
|
| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
|
|
29
|
-
| ci-
|
|
29
|
+
| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
|
|
30
30
|
| observability-essentials | 7101-7899 | 8xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics`, `statusPageContract` |
|
|
31
31
|
| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
|
|
32
32
|
| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
|
|
@@ -66,6 +66,15 @@ A project applies the blueprint on a fresh tree, provisions a Clerk development
|
|
|
66
66
|
- Provisioning-script directory location (`scripts/provisioning/` by convention on AC-9110-1, or a project-declared equivalent). Blueprint owns that provisioning is not a request handler; project owns where the scripts live.
|
|
67
67
|
- Whether to layer a project-authored Clerk-webhook consumer (for user-created, session-ended, or organisation-membership-changed events). Blueprint's default omits it; a project that adds one authors one TAC and one ADR alongside this blueprint's contributions.
|
|
68
68
|
|
|
69
|
+
## Runtime coverage
|
|
70
|
+
|
|
71
|
+
The middleware boundary contract (TAC-1001's `verify(request) -> { authenticated, principal?, reason? }`) is framework-agnostic and runs unchanged on Node HTTP servers (Express, Fastify) and on the Cloudflare Workers fetch handler. Two sample sets ship in `assets/`:
|
|
72
|
+
|
|
73
|
+
- `assets/middleware/node-middleware-shape.md` for Express and Fastify: adapter wrappers around `verify(request)` that attach the reduced `Principal` to `request.auth`.
|
|
74
|
+
- `assets/middleware/workers-fetch-shape.md` and `assets/wiring/workers-wrangler-toml-shape.md` for Cloudflare Workers: a fetch-handler adapter that carries the same `verify(request)` contract onto the Fetch API `Request` shape, plus the wrangler.toml overlay (`nodejs_compat`, the two Clerk secret names, the `CLERK_SIGN_IN_URL` var, and the `run_worker_first` posture on auth-gated routes that the assets binding would otherwise silently bypass).
|
|
75
|
+
|
|
76
|
+
A project on a single framework picks up one adapter and pays nothing for the others; a project that hosts multiple runtimes (a Node main app plus a Workers edge function against the same Clerk instance) picks up both sample sets and shares one session verifier and one claims mapper across them.
|
|
77
|
+
|
|
69
78
|
## Cost-honesty paragraph
|
|
70
79
|
|
|
71
80
|
Shipping this doc set costs the project the following. Clerk is a paid vendor beyond the development tier; the operator budgets for it. The `accountBound` runtime-verify posture means the CI runner needs Clerk reachability to actually verify the runtime-verify ACs; a CI runner without outbound network for that vendor either skips those ACs (which the ship gate flags) or the operator wires a preview Clerk instance for CI to reach. The middleware boundary discipline (`request.auth` and `can`/`assert` everywhere) is a code-review load on every new handler; a project that lets the discipline slip loses the vendor-swap-safety the blueprint is buying. The `revocationCheckIntervalMs` window is a stated trade between per-request cost and sign-out prompt-ness; the operator picks a number that reflects the project's actual policy, not the blueprint's default forever. The read-only provisioning posture forces the operator to run Clerk mutations outside the request lifecycle; a project that wants a per-request user-create call is on a different pattern and should think again. The blueprint says nothing about MFA policy, about pricing, about SLA, or about vendor-lock exit; a project that needs any of those spends its own build cycles on them and this blueprint does not save it any work there.
|
|
@@ -10,7 +10,7 @@ This file is the security-auth-keycloak half of the cross-blueprint contract. Th
|
|
|
10
10
|
|
|
11
11
|
The security-auth-keycloak blueprint claims one global topic. Every other contribution is scope-local (ADR-1202 through ADR-1206 name the verification-mode choice, the provider-routing seam, the session-vs-token contract, the JWKS rotation-cache lifetime, and the refresh-and-sign-out posture without contributing global topics; a composing blueprint that holds a different opinion on any of them authors its own project-level ADR if it wants to override).
|
|
12
12
|
|
|
13
|
-
Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, security-auth-clerk, security-auth-oauth2, persistence-data-sqlite, ci-
|
|
13
|
+
Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, security-auth-clerk, security-auth-oauth2, persistence-data-sqlite, delivery-ci-workflows, observability-essentials, and security-secrets-management vocabularies, restated as law): lower camelCase, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer. Do not mint variants of existing strings (`auth`, `authentication`, `identityProvider`, `keycloakProvider` are all wrong when `authModel` already exists).
|
|
14
14
|
|
|
15
15
|
## The deliberate authModel conflict, restated
|
|
16
16
|
|
|
@@ -37,7 +37,7 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
|
|
|
37
37
|
| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
|
|
38
38
|
| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
|
|
39
39
|
| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
|
|
40
|
-
| ci-
|
|
40
|
+
| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
|
|
41
41
|
| observability-essentials | 7101-7899 | 8xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics`, `statusPageContract` |
|
|
42
42
|
| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
|
|
43
43
|
| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
|
|
@@ -21,7 +21,7 @@ Phase 1 resolves local path sources only; registry and git-ref resolution is a m
|
|
|
21
21
|
| Principal registry samples | `assets/principal-registry-samples/single-address.md` | The single-address registry implementation for solo-operator deployments |
|
|
22
22
|
| Principal registry samples | `assets/principal-registry-samples/allow-list-file.md` | An allow-list file registry pattern for small teams |
|
|
23
23
|
| Guide | `guide/security-auth-magic-link.md` | Operator-facing: when to use it, when not, what stays your call, and the promotion signal for the future auth-oidc blueprint |
|
|
24
|
-
| Coordination vocabulary | `docs/topics.md` | The one global-topic string this blueprint contributes, the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, hello-panel, persistence-data-sqlite, ci-
|
|
24
|
+
| Coordination vocabulary | `docs/topics.md` | The one global-topic string this blueprint contributes, the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, hello-panel, persistence-data-sqlite, delivery-ci-workflows, observability-essentials) |
|
|
25
25
|
|
|
26
26
|
The doc set is contributions (copied into the project tree by `rcf define blueprint add`); the guide, assets, and docs are package-resident references. Guide rendering into `rcf/knowledge/docs/blueprint-guides/` and asset ingestion are mechanism follow-ups; until they land, the working agent reads them from the applied blueprint's source path recorded in `manifest.blueprints[].source`.
|
|
27
27
|
|
|
@@ -26,7 +26,7 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
|
|
|
26
26
|
| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
|
|
27
27
|
| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
|
|
28
28
|
| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
|
|
29
|
-
| ci-
|
|
29
|
+
| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
|
|
30
30
|
| observability-essentials | 7101-7899 | 8xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics`, `statusPageContract` |
|
|
31
31
|
| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
|
|
32
32
|
| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
|
|
@@ -23,7 +23,7 @@ Composing with `security-auth-magic-link`, `security-auth-clerk`, or any other b
|
|
|
23
23
|
| Mock provider bootstrap | `assets/mock-provider/mock-oidc-shape.md` | The shape of a local mock OIDC provider stood up per REQ-010's acceptance-bar AC; the file names the endpoints, the JWKS shape, and the token minting shape without committing a specific library version |
|
|
24
24
|
| Provider selector sample | `assets/provider-selector/list-shape.md` | The rendering shape the reference selector emits and the query-parameter contract a bespoke replacement honours |
|
|
25
25
|
| Guide | `guide/security-auth-oauth2.md` | Operator-facing: when to use it, when not, the promotion signals for the Clerk and Keycloak siblings, the operator decisions that remain open, the cost-honesty paragraph |
|
|
26
|
-
| Coordination vocabulary | `docs/topics.md` | The one global-topic string this blueprint contributes and the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, email-smtp-resend, persistence-data-sqlite, ci-
|
|
26
|
+
| Coordination vocabulary | `docs/topics.md` | The one global-topic string this blueprint contributes and the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, email-smtp-resend, persistence-data-sqlite, delivery-ci-workflows, observability-essentials, security-secrets-management, security-auth-clerk, security-auth-oauth2) |
|
|
27
27
|
|
|
28
28
|
The doc set is contributions (copied into the project tree by `rcf define blueprint add`); the guide, assets, and docs are package-resident references. Guide rendering into `rcf/knowledge/docs/blueprint-guides/` and asset ingestion are mechanism follow-ups; until they land, the working agent reads them from the applied blueprint's source path recorded in `manifest.blueprints[].source`.
|
|
29
29
|
|
|
@@ -10,7 +10,7 @@ This file is the security-auth-oauth2 half of the cross-blueprint contract. The
|
|
|
10
10
|
|
|
11
11
|
The security-auth-oauth2 blueprint claims one global topic. Every other contribution is scope-local (ADR-1102 through ADR-1106 name the provider-abstraction contract shape, the PKCE discipline, the session-bridge shape, the refresh-token posture, and the multi-provider routing without contributing global topics; a composing blueprint that holds a different opinion on any of them authors its own project-level ADR if it wants to override).
|
|
12
12
|
|
|
13
|
-
Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, security-auth-clerk, persistence-data-sqlite, ci-
|
|
13
|
+
Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, security-auth-clerk, persistence-data-sqlite, delivery-ci-workflows, observability-essentials, and security-secrets-management vocabularies, restated as law): lower camelCase, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer. Do not mint variants of existing strings (`auth`, `authentication`, `identityProvider`, `oauthProvider` are all wrong when `authModel` already exists).
|
|
14
14
|
|
|
15
15
|
## The deliberate authModel conflict, restated
|
|
16
16
|
|
|
@@ -37,7 +37,7 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
|
|
|
37
37
|
| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
|
|
38
38
|
| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
|
|
39
39
|
| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
|
|
40
|
-
| ci-
|
|
40
|
+
| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
|
|
41
41
|
| observability-essentials | 7101-7899 | 8xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics`, `statusPageContract` |
|
|
42
42
|
| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
|
|
43
43
|
| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
|
|
@@ -21,7 +21,7 @@ Phase 1 resolves local path sources only; registry and git-ref resolution is a m
|
|
|
21
21
|
| Agent access pattern | `assets/cli-usage/agent-access-pattern.md` | The piped-stdin pattern for `secrets read` and `secrets put`, including a Node.js spawn wrapper that keeps the value off argv and off any log line |
|
|
22
22
|
| UI three-way choice | `assets/ui-integration/three-way-choice.md` | The elicitation script for the admin-UI choice with the shape of each outcome and the field contract for the `integrate` variant |
|
|
23
23
|
| Guide | `guide/security-secrets-management.md` | Operator-facing: when to use it, when not, what stays your call, and the promotion signals for the hosted-vendor and admin-SPA companion blueprints |
|
|
24
|
-
| Coordination vocabulary | `docs/topics.md` | The one global-topic string this blueprint contributes and the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, hello-panel, persistence-data-sqlite, ci-
|
|
24
|
+
| Coordination vocabulary | `docs/topics.md` | The one global-topic string this blueprint contributes and the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, hello-panel, persistence-data-sqlite, delivery-ci-workflows, observability-essentials, security-secrets-management) |
|
|
25
25
|
|
|
26
26
|
The doc set is contributions (copied into the project tree by `rcf define blueprint add`); the guide, assets, and docs are package-resident references. Guide rendering into `rcf/knowledge/docs/blueprint-guides/` and asset ingestion are mechanism follow-ups; until they land, the working agent reads them from the applied blueprint's source path recorded in `manifest.blueprints[].source`.
|
|
27
27
|
|
|
@@ -6,11 +6,11 @@ This file is the security-secrets-management half of the cross-blueprint contrac
|
|
|
6
6
|
|
|
7
7
|
| Topic string | security-secrets-management contribution | Origin | Composition note |
|
|
8
8
|
|---|---|---|---|
|
|
9
|
-
| `secretsSource` | ADR-901-security-secrets-management-secrets-source | Minted here; pre-cleared as unclaimed against application-spa (`clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel`), application-api-rest (`errorEnvelope`, `authModel`, `apiVersioning`, `logging`), security-auth-magic-link (`authModel`), persistence-data-sqlite (`persistenceStore`, `migrationDiscipline`), ci-
|
|
9
|
+
| `secretsSource` | ADR-901-security-secrets-management-secrets-source | Minted here; pre-cleared as unclaimed against application-spa (`clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel`), application-api-rest (`errorEnvelope`, `authModel`, `apiVersioning`, `logging`), security-auth-magic-link (`authModel`), persistence-data-sqlite (`persistenceStore`, `migrationDiscipline`), delivery-ci-workflows (`ciGates`, `strictCoverageGate`), observability-essentials (`healthProbes`, `readinessSemantics`, `statusPageContract`), and the hello-panel walkthrough exemplar (`operatorPanel`) | The one project-wide source of truth for secret material: a repo-root `secrets.yaml` manifest plus a vendor-agnostic Secrets Manager client. A composing blueprint that holds a different opinion on the secrets source (a vendor-committed opinionated blueprint, a config-server pattern, a plaintext-committed pattern for a public reference project) contributes its own scope:global ADR on this exact string and lets composition surface the pairing. Expected resolution: one project-level ADR that fixes the source shape and the vendor selection |
|
|
10
10
|
|
|
11
11
|
The security-secrets-management blueprint claims one global topic. Every other contribution is scope-local (ADR-902 through ADR-905 name the default vendor, the agent access discipline, the `.env` reflection posture, and the rotation-and-audit posture without contributing global topics; a composing blueprint that holds a different opinion on any of them authors its own project-level ADR if it wants to override).
|
|
12
12
|
|
|
13
|
-
Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, persistence-data-sqlite, ci-
|
|
13
|
+
Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, persistence-data-sqlite, delivery-ci-workflows, and observability vocabularies, restated as law): lower camel case, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer. Do not mint variants of existing strings (`secrets`, `secretsStore`, `vault`, `secretsVendor`, `credentialsSource` are all wrong when `secretsSource` already exists).
|
|
14
14
|
|
|
15
15
|
## Id number bands (registry bootstrap)
|
|
16
16
|
|
|
@@ -26,7 +26,7 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
|
|
|
26
26
|
| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
|
|
27
27
|
| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
|
|
28
28
|
| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
|
|
29
|
-
| ci-
|
|
29
|
+
| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
|
|
30
30
|
| observability-essentials | 7101-7899 | 8xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics`, `statusPageContract` |
|
|
31
31
|
| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
|
|
32
32
|
| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
|
|
@@ -264,7 +264,7 @@ One condensed pass against this repository's own tree, captured at build time. Q
|
|
|
264
264
|
|
|
265
265
|
```
|
|
266
266
|
$ rcf build
|
|
267
|
-
# Build queue: BS-001 - RCF
|
|
267
|
+
# Build queue: BS-001 - RCF Lite initial delivery
|
|
268
268
|
|
|
269
269
|
Generation strategy: dependencyFirst
|
|
270
270
|
|
|
@@ -311,7 +311,7 @@ Two actionable items, and the tier column says how they relate: FBS-013 and FBS-
|
|
|
311
311
|
- Estimated hours: 7
|
|
312
312
|
- Risk level: medium
|
|
313
313
|
- Domain: guidance
|
|
314
|
-
- Parent chain: BS-001 -> PRD-001 (RCF
|
|
314
|
+
- Parent chain: BS-001 -> PRD-001 (RCF Lite)
|
|
315
315
|
```
|
|
316
316
|
|
|
317
317
|
Mark pickup, and the cycle is running:
|