# Universal Embed Contract

> **Documentation contract only.** No embed SDK, iframe host, or token issuer implementation.  
> Architecture: [published-resource-architecture.md](../architecture/published-resource-architecture.md) · [ADR-022](../architecture/adr/ADR-022.md)  
> Contract version: `universal-embed.v1` (additive; open embed-type registry)

---

## 1. Purpose

Published Resources may be **embedded** into external websites or applications. Experience owns **embed metadata** (presentation, theming hooks, allowed origins refs). Business logic for actions inside the embed remains with owning services. All embed contexts identify the surface by **`publish_id`**.

---

## 2. Reserved embed types (open)

| Embed type key | Meaning |
| --- | --- |
| `iframe` | Hosted iframe pointing at public/embed URL |
| `javascript_sdk` | Script loader + mount API |
| `widget` | Prebuilt widget shell |
| `popup` | Popup window |
| `inline` | Inline DOM mount |
| `modal` | Modal overlay |
| `floating_button` | Floating launcher |
| *future.*\* | Unlimited future types |

---

## 3. Embed metadata (conceptual)

```
EmbedDescriptor {
  publish_id
  tenant_id
  embed_types_allowed[]
  responsive_sizing { mode, min_height?, aspect_ratio? }
  theme_inheritance { inherit_host, token_ref? }
  security {
    sandbox_flags[]
    allowed_origins[]
    origin_validation
  }
  permission_delegation { scopes[], permission_prefix? }
  token_passing { mode }           # e.g. postMessage, query, header — owned by Identity patterns
  analytics_propagation { publish_id, embed_session_ref? }
}
```

---

## 4. Contract requirements

### Responsive sizing

- Descriptors MUST support fluid width and documented height strategies (`auto`, `fixed`, `aspect`).
- Host pages MUST NOT be required to hardcode Experience internal layout ids.

### Security & sandbox

- Iframe embeds SHOULD declare sandbox flags and CSP expectations (edge/frontend responsibility when implemented).
- **Origin validation** is mandatory for SDK/postMessage flows.
- Secrets MUST NOT be embedded in public HTML; use short-lived tokens via Identity/platform patterns.

### Permission delegation

- Embeds may request limited scopes; evaluation remains Identity/Core.
- Experience stores which scopes an embed *advertises*, not the auth decision.

### Token passing

- Modes are reserved: `postMessage`, `signed_query`, `authorization_header`.
- Experience does not become token issuer of record.

### Theming inheritance

- Optional inherit-host tokens; Experience theme packs remain Experience-owned when applied to the resource itself.

### Analytics propagation

- All embed events record **`publish_id`** (and optional `embed_session_ref`).
- Analytics ownership rules unchanged ([ADR-022](../architecture/adr/ADR-022.md)).

---

## 5. Ownership

| Concern | Owner |
| --- | --- |
| Embed metadata / rendering presentation | Experience |
| Business action execution inside embed | Owning service of the action |
| Auth tokens | Identity / Core |
| Paid unlock inside embed | Payment |
| Host page integration UI | Frontend / external developers |

---

## 6. Related

- [Published Action Registry](published-action-registry.md)
- [Public Access Contract](public-access-contract.md)
- [Published Resource Contracts](published-resource-contracts.md)