feat(sdc): implement SDC playground with Questionnaire form handling and OAuth client integration

Author: Ardenexal

.gitignore

@@ -41,3 +41,5 @@ phpstan.neon
 ###< phpunit/phpunit ###
 
 node_modules/
+/.playwright-mcp/
+

demo/CLAUDE.md

@@ -15,6 +15,12 @@ This file documents conventions for the demo Symfony 7.4 application.
 
 Located in `src/Controller/`. Use `#[Route]` attribute for routing. Extend `AbstractController`.
 
+- `SdcController` (`/sdc`) — the SDC Populate/Extract playground: pick or paste a Questionnaire, fill in
+  its form (repeats, `enableWhen`, quantity, `answerValueSet` code-checking all supported), Populate it
+  from launch-context JSON, and Extract into a transaction Bundle. A curated example gallery and a
+  "View QuestionnaireResponse JSON" toggle are on the page itself. See "External FHIR/Terminology
+  Servers" below for its optional live-server env vars.
+
 ## FHIR Services (via FHIRBundle)
 
 Inject by type hint — all autowired:
@@ -30,6 +36,78 @@ Inject by type hint — all autowired:
 
 `config/packages/fhir.yaml` — configures default version, output/cache directories, validation, and FHIRPath cache.
 
+## External FHIR/Terminology Servers (SDC Playground)
+
+The `/sdc` page is offline-first by default. Two env vars opt it into live server connectivity:
+
+- `FHIR_SERVER_URL` — when set, `application/x-fhir-query` `itemPopulationContext`/`variable` directives
+  in `$populate` resolve against this server instead of being skipped with an informational issue.
+- `FHIR_TERMINOLOGY_SERVER_URL` — when set, an `answerValueSet`-bound choice item's "Check code" action
+  validates against this server instead of showing a "no terminology server configured" note.
+
+Both default to empty string (offline). Set them via a real environment variable or `.env.local`
+(gitignored) — **not** `demo/.env`, which is off-limits to agent edits in this repo; the empty defaults
+are declared instead as committed `parameters:` in `config/services.yaml` using Symfony's
+`env(NAME): 'default'` convention, so no `.env` edit is ever required to keep the demo offline by default.
+
+Server base URLs are **operator-configured only** — there is deliberately no "enter a FHIR server URL"
+field anywhere in the UI. A public URL-entry field would turn the demo host into an open SSRF proxy
+against whatever network it runs on. See `src/Sdc/ExternalClientFactory.php` and the
+`FHIRHttpClientInterface`/`FHIRTerminologyClientInterface` factory wiring in `config/services.yaml`.
+
+Overriding these interfaces is app-wide, not scoped to `/sdc`: setting `FHIR_SERVER_URL` also makes
+`/fhirpath`'s `resolve()`/`memberOf()` go live, and `FHIR_TERMINOLOGY_SERVER_URL` also makes `/validate`'s
+terminology binding checks go live — matching `FHIRBundle`'s own documented override pattern.
+
+### FHIR server authentication (M06)
+
+Two independent, composable authentication mechanisms for the `FHIR_SERVER_URL` connection. The
+*destination* is always operator-configured only (env var/`.env.local`, never a request-time input); the
+*credential values* can additionally come from a visitor's own session — see "Session-scoped credential
+entry (M07)" below.
+
+- **OAuth 2.0 client credentials grant** — `FHIR_SERVER_OAUTH_TOKEN_URL`, `FHIR_SERVER_OAUTH_CLIENT_ID`,
+  `FHIR_SERVER_OAUTH_CLIENT_SECRET`. The token URL is required to enable OAuth at all; the client id and
+  secret must either both be present (from env vars, a visitor's session, or one of each) or both absent
+  — a mismatched pair fails loudly at container-resolution time. Token-URL-alone (no id/secret anywhere
+  yet) is a valid state: OAuth is enabled but not yet authenticated for this request. The library fetches
+  and caches the bearer token itself (`Ardenexal\FHIRTools\Component\HttpClient\OAuth\
+  OAuthClientCredentialsTokenProvider` / `OAuthHttpClient`).
+- **A manual header** — `FHIR_SERVER_AUTH_HEADER_NAME` / `FHIR_SERVER_AUTH_HEADER_VALUE`, attached
+  verbatim to every request (`StaticHeaderHttpClient`). Covers a hand-obtained `Authorization: Bearer
+  <token>` or an `X-Api-Key`-style header. Same shape as OAuth: the name enables the mechanism, the value
+  can arrive later (env or session).
+
+Both mechanisms can be configured together as long as they don't both target the `Authorization` header
+(that combination fails loudly too — see `ExternalClientFactory::assertAuthConfigurationIsConsistent()`).
+The client secret and header value are never logged, never displayed, and never appear in any error
+panel — verified end-to-end in `demo/tests/Controller/SdcOAuthSecretLeakageTest.php`. The `/sdc` status
+badge shows *which* mechanism is active (e.g. "configured (OAuth)") but never the credential itself.
+
+### Session-scoped credential entry (M07)
+
+`/sdc` has a small form (shown only when the operator has enabled OAuth or a manual header — i.e. when
+`FHIR_SERVER_OAUTH_TOKEN_URL` or `FHIR_SERVER_AUTH_HEADER_NAME` is set) letting a visitor enter their own
+OAuth client id/secret, or their own header value, for **their session only** — never persisted to disk,
+never logged, never echoed back into the form. This lets someone test the demo as different users
+without editing env vars and restarting the server. `ExternalClientFactory` checks the current visitor's
+session first (`sdc_oauth_client_id`/`sdc_oauth_client_secret`/`sdc_auth_header_value`) and falls back to
+the env-var value when no session override is present — see `App\Controller\SdcController::
+setCredentials()`/`clearCredentials()` and `ExternalClientFactory`'s class docblock.
+
+**Accepted risk, deliberately chosen — not a hardening recommendation.** The destination FHIR server and
+OAuth token URL/IdP stay operator-configured; only the credential *values* are visitor-enterable. This
+still means **any visitor who can reach `/sdc` can authenticate as whoever they claim, against whatever
+server the operator has configured** — there is no verification that a submitted client id/secret
+"belongs" to the person submitting it. This tradeoff was raised explicitly (against a safer
+"operator-pre-configured named profiles" alternative) and the free-text session-entry approach was
+chosen anyway, on the basis that this is suited to a local/trusted-access demo. **Do not expose `/sdc`
+on a network you don't trust without adding real access control first** (see `backlog.md`).
+
+Session isolation between visitors, and that a submitted secret never leaks into any rendered page or
+error, are both covered by `demo/tests/Controller/SdcSessionCredentialIsolationTest.php` and
+`SdcSessionCredentialLeakageTest.php`.
+
 ## Useful Commands
 
 ```bash

demo/assets/controllers/sdc_enable_when_controller.js

@@ -0,0 +1,104 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Client-side `enableWhen` evaluation, no server round-trip — per M03's Kill Criteria, restricted to
+ * the SDC "fixed grammar" (`linkId` + `operator` + one `answer[x]`), with exactly one condition per
+ * dependent item (`enableBehavior: all`/`any` across multiple conditions is out of scope; the render
+ * model only ever carries the item's FIRST `enableWhen` entry — see `QuestionnaireFormRenderer`).
+ *
+ * Hiding a dependent item uses the `hidden` attribute, never `disabled` — a `disabled` field is dropped
+ * from form submission entirely, which would silently contradict the M03 decision that Extract keeps
+ * answers for disabled items (matching `$populate`'s own "enableWhen is a display-time concern, not
+ * applied" behavior).
+ *
+ * Trigger lookup is scoped to this controller's element (the Extract `<form>`) and assumes the trigger
+ * itself is non-repeating (a repeating trigger has no defined "the" value to compare against — out of
+ * scope here).
+ */
+export default class extends Controller {
+    static targets = ['dependent'];
+
+    connect() {
+        this.dependentTargets.forEach((dependentEl) => this.wireDependent(dependentEl));
+    }
+
+    wireDependent(dependentEl) {
+        let condition;
+        try {
+            condition = JSON.parse(dependentEl.dataset.sdcEnableWhenConditionValue);
+        } catch {
+            return;
+        }
+
+        const trigger = this.element.querySelector(
+            `[data-repeat-field-linkid="${condition.question}"] select, ` +
+            `[data-repeat-field-linkid="${condition.question}"] input, ` +
+            `[data-repeat-field-linkid="${condition.question}"] textarea`,
+        );
+        if (!trigger) {
+            return;
+        }
+
+        const evaluate = () => {
+            dependentEl.hidden = !this.evaluateCondition(condition, trigger.value);
+        };
+
+        trigger.addEventListener('change', evaluate);
+        trigger.addEventListener('input', evaluate);
+        evaluate();
+    }
+
+    evaluateCondition(condition, actual) {
+        if (condition.operator === 'exists') {
+            const hasAnswer = actual !== '';
+
+            return condition.answerBoolean === undefined ? hasAnswer : hasAnswer === condition.answerBoolean;
+        }
+
+        const expected = this.expectedValue(condition);
+        const numericActual = Number(actual);
+        const numericExpected = Number(expected);
+        const bothNumeric = actual !== '' && expected !== '' && !Number.isNaN(numericActual) && !Number.isNaN(numericExpected);
+
+        switch (condition.operator) {
+            case '=':
+                return actual === expected;
+            case '!=':
+                return actual !== expected;
+            case '>':
+                return bothNumeric && numericActual > numericExpected;
+            case '<':
+                return bothNumeric && numericActual < numericExpected;
+            case '>=':
+                return bothNumeric && numericActual >= numericExpected;
+            case '<=':
+                return bothNumeric && numericActual <= numericExpected;
+            default:
+                return true;
+        }
+    }
+
+    /** Reads whichever `answer[x]` key is present and returns it as this codec's form-value string. */
+    expectedValue(condition) {
+        if ('answerBoolean' in condition) {
+            return condition.answerBoolean ? 'true' : 'false';
+        }
+        if ('answerString' in condition) {
+            return condition.answerString;
+        }
+        if ('answerInteger' in condition) {
+            return String(condition.answerInteger);
+        }
+        if ('answerDecimal' in condition) {
+            return String(condition.answerDecimal);
+        }
+        if ('answerDate' in condition) {
+            return condition.answerDate;
+        }
+        if ('answerCoding' in condition && condition.answerCoding) {
+            return condition.answerCoding.code ?? '';
+        }
+
+        return '';
+    }
+}

demo/assets/controllers/sdc_picker_controller.js

@@ -0,0 +1,14 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Toggles the "paste your own Questionnaire JSON" textarea on the SDC sample picker. Previously an
+ * inline onchange= attribute; converted to Stimulus because inline handlers don't survive a Turbo Frame
+ * swap re-rendering this form from scratch, whereas data-controller attributes reconnect automatically.
+ */
+export default class extends Controller {
+    static targets = ['customJson'];
+
+    toggleCustom(event) {
+        this.customJsonTarget.classList.toggle('hidden', event.target.value !== 'custom');
+    }
+}

demo/assets/controllers/sdc_repeat_controller.js

@@ -0,0 +1,81 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * "Add another" / "Remove" for repeating Questionnaire items and groups. No hidden `<template>` element
+ * is used — the last rendered `[data-repeat-instance]` row for the target linkId is cloned directly
+ * (its structure is already correct, including any nested repeat/enableWhen wiring), its form values are
+ * cleared, and its index-bearing `name` attributes are bumped to the next free index.
+ *
+ * Indices are read from the DOM at add-time, not tracked in JS state, and are never re-numbered after a
+ * remove — {@see \App\Sdc\QuestionnaireResponseBuilder} is deliberately sparse-index-tolerant (removing
+ * row 1 of [0,1,2] leaves [0,2] on submit, and the builder iterates values rather than assuming
+ * contiguity), so there is no correctness reason to renumber, and renumbering would risk clobbering a
+ * row a user is mid-edit on.
+ */
+export default class extends Controller {
+    add(event) {
+        const linkId = event.params.linkid;
+        const wrapper = this.element.querySelector(
+            `[data-repeat-field-linkid="${linkId}"], [data-repeat-group-linkid="${linkId}"]`,
+        );
+        if (!wrapper) {
+            return;
+        }
+
+        const rows = Array.from(wrapper.querySelectorAll(':scope > [data-repeat-instance]'));
+        const lastRow = rows[rows.length - 1];
+        if (!lastRow) {
+            return;
+        }
+
+        const nextIndex = this.nextIndex(rows, linkId);
+        const clone = lastRow.cloneNode(true);
+        this.reindex(clone, linkId, nextIndex);
+        this.clearValues(clone);
+
+        lastRow.after(clone);
+    }
+
+    remove(event) {
+        event.target.closest('[data-repeat-instance]')?.remove();
+    }
+
+    /** One past the highest `[<linkId>][<n>]` index currently present, so sparse removes never collide. */
+    nextIndex(rows, linkId) {
+        let max = -1;
+        const pattern = new RegExp(`\\[${this.escapeForRegex(linkId)}\\]\\[(\\d+)\\]`);
+
+        rows.forEach((row) => {
+            row.querySelectorAll('[name]').forEach((field) => {
+                const match = field.getAttribute('name').match(pattern);
+                if (match) {
+                    max = Math.max(max, Number(match[1]));
+                }
+            });
+        });
+
+        return max + 1;
+    }
+
+    /** Bumps every `[<linkId>][<oldIndex>]` occurrence in the clone's field names to `[<linkId>][<newIndex>]`. */
+    reindex(clone, linkId, newIndex) {
+        const pattern = new RegExp(`(\\[${this.escapeForRegex(linkId)}\\])\\[\\d+\\]`);
+
+        clone.querySelectorAll('[name]').forEach((field) => {
+            field.setAttribute('name', field.getAttribute('name').replace(pattern, `$1[${newIndex}]`));
+        });
+    }
+
+    clearValues(clone) {
+        clone.querySelectorAll('input, textarea').forEach((field) => {
+            field.value = '';
+        });
+        clone.querySelectorAll('select').forEach((field) => {
+            field.selectedIndex = 0;
+        });
+    }
+
+    escapeForRegex(value) {
+        return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+}

demo/assets/sdc-samples/extract-spike.questionnaire.json

@@ -0,0 +1,41 @@
+{
+  "resourceType": "Questionnaire",
+  "id": "extract-spike",
+  "url": "http://example.org/Questionnaire/extract-spike",
+  "status": "active",
+  "item": [
+    {
+      "extension": [
+        {
+          "url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-definitionExtract",
+          "extension": [
+            { "url": "definition", "valueCanonical": "http://hl7.org/fhir/StructureDefinition/Patient" }
+          ]
+        }
+      ],
+      "linkId": "patient",
+      "text": "Patient",
+      "type": "group",
+      "item": [
+        {
+          "definition": "http://hl7.org/fhir/StructureDefinition/Patient#Patient.name.given",
+          "linkId": "given",
+          "text": "Given name",
+          "type": "string"
+        },
+        {
+          "definition": "http://hl7.org/fhir/StructureDefinition/Patient#Patient.name.family",
+          "linkId": "family",
+          "text": "Family name",
+          "type": "string"
+        },
+        {
+          "definition": "http://hl7.org/fhir/StructureDefinition/Patient#Patient.birthDate",
+          "linkId": "dob",
+          "text": "Date of birth",
+          "type": "date"
+        }
+      ]
+    }
+  ]
+}

demo/assets/sdc-samples/populate-spike.questionnaire.json

@@ -0,0 +1,51 @@
+{
+  "resourceType": "Questionnaire",
+  "status": "active",
+  "url": "http://example.org/Questionnaire/populate-spike",
+  "name": "PopulateSpike",
+  "extension": [
+    {
+      "url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-launchContext",
+      "extension": [
+        {
+          "url": "name",
+          "valueCoding": {
+            "system": "http://hl7.org/fhir/uv/sdc/CodeSystem/launchContext",
+            "code": "patient"
+          }
+        },
+        { "url": "type", "valueCode": "Patient" }
+      ]
+    }
+  ],
+  "item": [
+    {
+      "linkId": "patient-given",
+      "type": "string",
+      "text": "Given name",
+      "extension": [
+        {
+          "url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-initialExpression",
+          "valueExpression": {
+            "language": "text/fhirpath",
+            "expression": "%patient.name.first().given.first()"
+          }
+        }
+      ]
+    },
+    {
+      "linkId": "patient-family",
+      "type": "string",
+      "text": "Family name",
+      "extension": [
+        {
+          "url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-initialExpression",
+          "valueExpression": {
+            "language": "text/fhirpath",
+            "expression": "%patient.name.first().family"
+          }
+        }
+      ]
+    }
+  ]
+}