@duffcloudservices/site-forms 0.4.2 → 0.7.0

package/src/composables/useSitePhiPosture.ts

@@ -0,0 +1,123 @@
+/**
+ * Site PHI posture — the ONE platform signal that decides whether a managed
+ * form shows PHI guidance to the visitor.
+ *
+ * WHY THIS EXISTS (C-415 / KEPT re-review F1). On a HIPAA-mode tenant the AI
+ * chat widget already opens with "please don't include personal health
+ * details", because `/agent/config` projects `hipaaMode` to it. The managed
+ * form on the same tenant — the higher-volume intake path, with a required
+ * free-text message box — projected nothing, so the platform was doing the
+ * hard half of the problem (redacting PHI it had already received) and
+ * skipping the cheap half (asking the visitor not to send it).
+ *
+ * THE SIGNAL, AND ONLY THIS SIGNAL. `GET {apiBase}/sites/{slug}/forms/compliance`
+ * returns `{ siteHandlesPhi }`, the server's projection of
+ * `portal.Service.SiteHandlesPHI` — whose authoritative input is
+ * `SiteAgentConfigs/{slug}/default.HipaaMode`, the same admin-pinned row the
+ * C-352 redaction gate reads. There is no second signal, no YAML flag, and no
+ * per-site opt-in: a site-local switch could drift from the tenant's real HIPAA
+ * posture, which is the exact class of bug C-352 fixed.
+ *
+ * NOT `/agent/config`, which already carries `hipaaMode`: that endpoint 404s
+ * unless the `aiAgent` feature, the per-site toggle, and the global kill switch
+ * are all on. Reading the flag from there would silently give no guidance to a
+ * HIPAA-mode tenant that does not run the chat widget — a fail-OPEN gate hidden
+ * behind an unrelated feature flag.
+ *
+ * FAIL DIRECTION. The server side fails CLOSED (an unresolvable HipaaMode
+ * reports `true`, so the guidance shows). The client cannot: a transport
+ * failure or an offline build has no verdict at all, and defaulting to "show"
+ * would put a health-privacy line on every non-medical customer's contact form.
+ * So the client defaults to `false` on any failure, and the server-side
+ * redactions (C-352) remain the actual control — this module is guidance, not
+ * enforcement.
+ */
+
+export interface SitePhiPostureOptions {
+  /** API base URL, e.g. `https://api.duffcloudservices.com/api/v1`. */
+  apiBase: string
+  /**
+   * Site slug. When empty the slug-free `/forms/compliance` route is used and
+   * the server infers the site from the request origin/host — the same
+   * fallback `submitFormValues` uses, so a build with no baked slug still gets
+   * a verdict instead of requesting the broken `/sites//forms/...` shape.
+   */
+  siteSlug: string
+  /** Optional fetch implementation override (tests). */
+  fetchImpl?: typeof fetch
+}
+
+/** Shape of `GET /sites/{siteSlug}/forms/compliance`. */
+interface SiteFormComplianceResponse {
+  siteHandlesPhi?: unknown
+}
+
+/**
+ * In-flight/settled verdicts keyed by `${base}|${slug}`. A page can host several
+ * `<DcsForm>`s (a contact form plus an intake questionnaire); they must not each
+ * pay for a round trip, and they must not be able to disagree with each other.
+ */
+const postureCache = new Map<string, Promise<boolean>>()
+
+/** Clears the memoized verdicts. Exported for tests and the portal preview iframe. */
+export function resetSitePhiPostureCache(): void {
+  postureCache.clear()
+}
+
+/**
+ * Resolves whether this site's managed-form submissions are PHI-bearing.
+ *
+ * Returns `false` on any failure (network, non-2xx, non-JSON, or a body whose
+ * `siteHandlesPhi` is not a boolean). A missing/garbled body is treated as "no
+ * verdict", never as an implicit yes — see the fail-direction note above.
+ */
+export async function fetchSiteHandlesPhi(
+  opts: SitePhiPostureOptions,
+): Promise<boolean> {
+  const base = (opts.apiBase ?? '').replace(/\/$/, '')
+  const slug = (opts.siteSlug ?? '').trim()
+  const url = slug
+    ? `${base}/sites/${encodeURIComponent(slug)}/forms/compliance`
+    : `${base}/forms/compliance`
+
+  const cacheKey = `${base}|${slug}`
+  const cached = postureCache.get(cacheKey)
+  if (cached) return cached
+
+  const fetchImpl = opts.fetchImpl ?? (typeof fetch === 'function' ? fetch : undefined)
+  if (!fetchImpl) return false
+
+  const pending = (async (): Promise<boolean> => {
+    try {
+      const res = await fetchImpl(url, { method: 'GET' })
+      if (!res.ok) return false
+      const body = (await res.json()) as SiteFormComplianceResponse
+      return body?.siteHandlesPhi === true
+    } catch {
+      // Deliberately silent: the only console output this package emits is the
+      // missing-definition warning (see the PHI-log grep gate in the site-forms
+      // skill). A failed posture read must never become a visitor-visible error
+      // on an otherwise working form.
+      return false
+    }
+  })()
+
+  postureCache.set(cacheKey, pending)
+  return pending
+}
+
+/**
+ * The standard PHI guidance copy. It lives in the package, not in the API
+ * response and not in any site's YAML, so one platform decision renders the
+ * same sentence on every HIPAA-mode tenant.
+ *
+ * It is guidance, not a legal notice: it tells the visitor what to do instead
+ * of what the law requires, and it deliberately mirrors the sentence the AI
+ * chat already ships on these tenants ("please don't include personal health
+ * details") so the two surfaces read as one product.
+ */
+export const PHI_GUIDANCE_COPY = {
+  lead: "Please don't include personal health details.",
+  detail:
+    "A general description of what you need is enough — we'll go over anything specific with you directly.",
+} as const

package/src/index.ts

@@ -24,6 +24,35 @@ export {
 } from './composables/useFormValidation'
 export { submitFormValues } from './composables/useFormSubmission'
 export type { SubmitOptions } from './composables/useFormSubmission'
+// C-415 — the site PHI posture read that decides whether <DcsForm> shows PHI
+// guidance. Exported so a site can read the same verdict for its own copy;
+// there is deliberately NO prop or YAML flag that forces it either way.
+export {
+  fetchSiteHandlesPhi,
+  resetSitePhiPostureCache,
+  PHI_GUIDANCE_COPY,
+} from './composables/useSitePhiPosture'
+export type { SitePhiPostureOptions } from './composables/useSitePhiPosture'
+// C-310 — the CANONICAL receipt primitive. Site-local backports (lamphere,
+// iron-oak, web/, portal/) track this module; see its header for the contract.
+export {
+  readOkBody,
+  readExpectedJson,
+  isManagedFormReceipt,
+  isSiteContactReceipt,
+  isEstimateReceipt,
+  isPasswordlessVerifyReceipt,
+  isBookingCancellationReceipt,
+} from './composables/readExpectedJson'
+export type {
+  ReceiptValidator,
+  UnconfirmedSubmissionError,
+  ManagedFormReceipt,
+  SiteContactReceipt,
+  EstimateReceipt,
+  PasswordlessVerifyReceipt,
+  BookingCancellationReceipt,
+} from './composables/readExpectedJson'
 
 export { loadFormDefinitions, parseFormYaml } from './loaders/yaml'
 export {

package/src/style.css

@@ -31,6 +31,30 @@
   gap: 1rem;
 }
 
+/*
+ * PHI guidance (C-415). Rendered only when the platform reports the tenant as
+ * PHI-handling; sits directly above the first free-text field. Styled as a calm
+ * aside, not an alert: it is asking the visitor to phrase something differently,
+ * not warning them that something went wrong. Colours follow the rest of this
+ * file (translucent slate over the host page's own surface) so it inherits every
+ * customer brand without knowing any of them.
+ */
+.dcs-form__phi-guidance {
+  margin: 0;
+  padding: 0.7rem 0.9rem;
+  font-size: 0.9rem;
+  line-height: 1.55;
+  color: inherit;
+  background: rgba(15, 23, 42, 0.045);
+  border: 1px solid rgba(15, 23, 42, 0.1);
+  border-left: 3px solid rgba(37, 99, 235, 0.6);
+  border-radius: 0.625rem;
+}
+
+.dcs-form__phi-guidance strong {
+  font-weight: 650;
+}
+
 .dcs-form-field {
   display: grid;
   gap: 0.5rem;
@@ -338,6 +362,7 @@
     grid-column: span 1;
   }
 
+  .dcs-form__phi-guidance,
   .dcs-form-field--width-full,
   .dcs-form-field--width-auto,
   .dcs-form-field--textarea,

package/src/types.ts

@@ -161,4 +161,20 @@ export interface DcsFormSubmitError {
   payload: DcsFormSubmitPayload
   error: Error
   status?: number
+  /**
+   * True when the server answered 2xx but the body was NOT JSON — i.e. the POST
+   * was answered by something that is not the DCS API (SPA shell, proxy
+   * interstitial, gateway page) and the submission was NOT stored. Additive and
+   * optional: the pre-existing error contract is unchanged (C-301).
+   */
+  nonJsonResponse?: boolean
+  /**
+   * True when the server answered 2xx with valid JSON that is NOT the endpoint's
+   * receipt (C-310). Distinct from `nonJsonResponse` because the remedies differ:
+   * that one means "the POST was answered by something else — check routing",
+   * this one means "the API answered, but with nothing that proves a row exists
+   * — check the endpoint contract against the receipt predicate". Additive and
+   * optional; the pre-existing error contract is unchanged.
+   */
+  unconfirmedReceipt?: boolean
 }