Embed contract

SP/1 capture runs inside pages the hub doesn’t control. The embed contract keeps that safe for the host.

Declarative configuration

Embeds are configured with data-* attributes on a single script tag — no host JavaScript required:

<script
  src="https://cdn.pryvc.com/v1/pryvc.js"
  data-client-id="pc_your_client_id"
  data-mode="consent"
  data-purpose="Discuss insurance options"
  data-entities="Your Agency|Your FMO LLC"
  data-form-selector="#lead-form"
  data-checkbox-selector="#agree"
  data-disclosure-selector="#disclosure"
></script>

Two modes:

• Share mode — renders the grant button; runs the authorization flow (data-flow selects auto | popup | redirect).
• Consent mode — renders nothing; intercepts the host form’s submit, captures the certificate, then lets the submit proceed.

Normative behavior

• Fail-open, always. If capture fails — network, misconfiguration, rate limit — the host form MUST still submit. The embed MUST NOT retry in a way that blocks or loops the host page (the reference implementation attempts capture at most once per submission attempt).
• On success in consent mode, the embed injects the certificate id as a hidden input (pryvc_cert_id) so the host backend receives it with the lead.
• The embed MUST emit DOM events the host can observe: pryvc:consent (detail: cert_id, fingerprint, verify_url) and pryvc:consent-error (detail: code), bubbling from the form element.
• If a consent checkbox is designated, capture MUST NOT proceed while it is unchecked — and the disclosure text captured MUST be the text actually rendered at submission time.
• Field mapping: explicit data-field-map (CSS selector → registry key) takes precedence; data-pryvc-field attributes and name/autocomplete heuristics are fallbacks.

Distribution requirements

• Embed script channels (/v1/..., /latest/...) are mutable and MUST be served with short cache lifetimes (reference: max-age=300) — a consent bug frozen into a year-long immutable cache is an evidence bug.
• The embed MUST stay small enough not to burden host pages (reference budget: < 15 KB gzipped; currently ~5 KB).