@aforoai/storefront-widgets 1.0.1

package/SECURITY.md

@@ -0,0 +1,138 @@
+# Security Policy
+
+This document describes the security model of `@aforoai/storefront-widgets` and
+the procedure for reporting vulnerabilities. For broader platform-wide security
+posture, see [`SECURITY.md`](https://github.com/aforoai/aforo-nextgen-UI/blob/main/SECURITY.md)
+in the root of the Aforo UI repository.
+
+## Supported Versions
+
+The widget SDK follows semver. We provide security fixes for the latest minor
+release within the current major (`v1.x`). Older majors are not patched once a
+new major ships — customers should upgrade to the current major.
+
+| Version | Supported          |
+|---------|--------------------|
+| 0.1.x   | :white_check_mark: |
+| < 0.1   | :x:                |
+
+> **Pre-1.0 caveat.** Until the SDK reaches 1.0 (after the remaining widget
+> bodies ship), each minor release may carry incremental security hardening.
+> Pin to a specific version in production and watch the changelog.
+
+## Reporting a Vulnerability
+
+If you believe you have found a security vulnerability in
+`@aforoai/storefront-widgets`, **do not file a public GitHub issue**. Report it
+privately:
+
+**Email:** `security@aforo.ai`
+
+PGP-encrypted reports are welcome. Request our key by emailing the same address
+with subject `PGP key request`.
+
+### What to include
+
+- A clear description of the issue and its impact
+- Steps to reproduce (proof-of-concept code, request/response examples,
+  screenshots)
+- Affected widget(s), affected version(s), and browser/runtime
+- Your contact info so we can follow up
+- Any disclosure timeline you have in mind (we follow coordinated disclosure)
+
+### What to expect
+
+- **Acknowledgement**: within 2 business days
+- **Initial triage**: within 5 business days, with severity assessment
+  (Critical / High / Medium / Low)
+- **Fix timeline**: Critical → ASAP (typically &lt;72h), High → within 14 days,
+  Medium/Low → next routine release
+- **Disclosure**: we coordinate public disclosure timing with the reporter;
+  default 90-day embargo
+
+We do not currently run a paid bug-bounty program. We will credit reporters
+publicly (with their consent) in the relevant release notes.
+
+## Security Model
+
+The plugin tier sits between Aforo's headless API (T6, full integration
+flexibility) and the managed storefront (T1, zero integration). Customers
+embed Aforo-served scripts on their pages, so the security boundary is
+carefully drawn.
+
+### Identity and trust
+
+- **Embed key.** Each tenant mints embed keys in Embed Studio. The key is a
+  public identifier — its security comes from a server-side **domain
+  allowlist**. A key only works when served from a registered origin. See
+  the [Authentication docs](https://docs.aforo.ai/docs/embed-authentication).
+- **Bridge token.** Customers' own backends mint short-lived bridge tokens
+  (signed with a server-side key) to identify their customer to Aforo. Aforo
+  exchanges the bridge token for an in-memory session JWT. The customer's
+  long-lived signing key never reaches the browser.
+- **Session JWT.** Stored in memory only — never in `localStorage` or
+  `sessionStorage`, never in cookies. Cleared on tab close or explicit
+  `AforoSession.destroy()`.
+- **Magic-link mode** (Prompt 9). For customer portals without their own
+  session, Aforo can mint a session JWT via an email magic link with anti-
+  enumeration rate limits and 15-minute one-time-use tokens. See
+  [`MagicLinkFallback`](https://docs.aforo.ai/docs/embed-authentication#magic-link-mode).
+
+### Browser-side integrity
+
+- **Subresource Integrity (SRI).** Every bundle ships with a SHA-384 hash
+  published at `https://embed.aforo.ai/v1/sri.json` and per-release in the
+  changelog. Customers MUST pin the `integrity=` attribute on their
+  `<script>` tag. See [Security docs](https://docs.aforo.ai/docs/embed-security).
+- **HTTPS only.** The loader refuses to bootstrap on `http://` pages.
+- **CSP.** Customers add `script-src https://embed.aforo.ai` (and
+  `connect-src https://api.aforo.ai`) to their Content-Security-Policy.
+  The widgets do not require `unsafe-inline` or `unsafe-eval`. See the
+  [CSP guidance](https://docs.aforo.ai/docs/embed-security#content-security-policy).
+- **No dynamic code.** No `eval()`, no `Function()` constructor, no dynamic
+  `import()` of untrusted URLs.
+- **Sandboxed iframe (iframe tier).** When customers choose the iframe tier
+  (Phase 1, not yet shipped), the widget runs in an `<iframe sandbox="">`
+  with explicit `allow-scripts` only — never `allow-same-origin`.
+
+### Network and data
+
+- **Per-tenant rate limits.** Magic-link request: 5/hour per email,
+  10/minute per IP. Bridge exchange: 60/minute per key.
+  See the [magic-link auth runbook](https://github.com/aforoai/aforo-nextgen-storefront-service/blob/main/docs/runbooks/2026-05-29-embed-magic-link-smoke.md).
+- **Anti-enumeration.** Magic-link request endpoint always returns the same
+  202 envelope regardless of whether the email exists — attackers cannot
+  use it as a user-registration probe.
+- **postMessage origin validation.** All inbound and outbound events validate
+  the parent-page origin against the embed key's allowed-domains list.
+  postMessage with `targetOrigin: '*'` is **never** used — every emit uses the
+  resolved parent origin.
+- **Webhook authority.** postMessage events fired into the parent page are
+  **advisory only**. Customers MUST validate state changes via Aforo's
+  signed webhooks before mutating their own database. The SDK explicitly
+  surfaces this in the [`events` docs](https://docs.aforo.ai/docs/embed-events#webhook-vs-postmessage).
+- **Idempotency keys.** Every mutation (subscribe, pay invoice, cart action)
+  accepts an idempotency key — flaky-network retry never double-charges.
+
+### Out of scope (customer responsibility)
+
+The following are the **customer's responsibility**, not the widget SDK's:
+
+- Securing the customer's own bridge-token signing key (HSM, KMS, secret
+  manager — never check it into source)
+- Securing the customer's own portal authentication (Aforo only sees the
+  bridge token after the customer has authenticated their user)
+- 3DS / SCA challenge UX beyond the Phase 0 redirect fallback (Phase 1
+  ships an inline 3DS modal)
+- The customer's own Content-Security-Policy configuration on their pages
+- Browser extensions / supply-chain attacks against the customer's own
+  build pipeline
+
+## Past Advisories
+
+None to date.
+
+## Acknowledgements
+
+Thanks to the security researchers and customers who have responsibly
+disclosed issues. Specific credits will be added here as advisories ship.

package/dist/AforoEmbed-BqQOFsl3.d.cts

@@ -0,0 +1,67 @@
+import { aD as WidgetMountConfig, Q as AforoEventType, N as AforoEventPayload, aC as WidgetId } from './types-Dm6cp_Cc.cjs';
+
+/**
+ * AforoEmbed — vanilla-JS + script-tag mount API.
+ *
+ *   AforoEmbed.configure({ tenantSlug, embedKey })   — sets global defaults
+ *   AforoEmbed.mount(element, { widget, config })     — mounts a widget
+ *   AforoEmbed.unmount(element)                       — teardown
+ *   AforoEmbed.on(eventType, handler)                 — typed subscriber
+ *   AforoEmbed.version                                — VERSION constant
+ *
+ * Idempotent: `mount(el, …)` twice on the same element is a no-op
+ * (FR-SDK-9). React Strict Mode's dev-time double-effect is safe.
+ *
+ * Attached to `window.aforoEmbed` when running in browser context. The
+ * loader script (`loader/loader.ts`) imports this module + assigns it
+ * before scanning the DOM for `data-aforo-widget` placeholders.
+ */
+
+type GlobalConfig = {
+    tenantSlug?: string;
+    embedKey?: string;
+    bridgeToken?: string;
+    embedBaseUrl?: string;
+};
+type EventHandler = (event: AforoEventPayload) => void;
+/**
+ * Lazy registry — a widget bundle (Prompts 4-7) calls
+ * `AforoEmbed._registerWidget('pricing-card', mountFn)` at load time. The
+ * registry is internal: the registration function is NOT part of the
+ * locked public surface (asserted by sdk-contract.test.ts).
+ */
+type MountFn = (element: HTMLElement, config: WidgetMountConfig) => () => void;
+/** Internal: widget bundles register here. Not exported publicly. */
+declare function registerWidget(id: WidgetId, mountFn: MountFn): void;
+declare const AforoEmbed: {
+    version: string;
+    /**
+     * Set platform-wide defaults. Calling repeatedly merges (last call wins
+     * per key). Useful when the SPA learns the tenant context after page
+     * load (FR-TIER-10).
+     */
+    configure(cfg: GlobalConfig): void;
+    /** Read-only snapshot of the current global config. */
+    getConfig(): GlobalConfig;
+    /**
+     * Mount a widget into the given element. Idempotent — re-mounting the
+     * same element is a no-op.
+     */
+    mount(element: HTMLElement | null, config: WidgetMountConfig): boolean;
+    /** Unmount a previously-mounted widget. */
+    unmount(element: HTMLElement | null): boolean;
+    /**
+     * Subscribe to widget events. Returns an unsubscribe function.
+     *
+     * Pass `'*'` to receive every aforo.* event.
+     */
+    on(eventType: AforoEventType, handler: EventHandler): () => void;
+    /** Internal: bundle registration hook. Not part of the public surface. */
+    _registerWidget: typeof registerWidget;
+    /** Internal: list registered widget ids. Tests only. */
+    _registeredWidgetsForTesting(): WidgetId[];
+    /** Internal: reset registry. Tests only. */
+    _resetForTesting(): void;
+};
+
+export { AforoEmbed as A };

package/dist/AforoEmbed-CmqjlYlt.d.ts

@@ -0,0 +1,67 @@
+import { aD as WidgetMountConfig, Q as AforoEventType, N as AforoEventPayload, aC as WidgetId } from './types-Dm6cp_Cc.js';
+
+/**
+ * AforoEmbed — vanilla-JS + script-tag mount API.
+ *
+ *   AforoEmbed.configure({ tenantSlug, embedKey })   — sets global defaults
+ *   AforoEmbed.mount(element, { widget, config })     — mounts a widget
+ *   AforoEmbed.unmount(element)                       — teardown
+ *   AforoEmbed.on(eventType, handler)                 — typed subscriber
+ *   AforoEmbed.version                                — VERSION constant
+ *
+ * Idempotent: `mount(el, …)` twice on the same element is a no-op
+ * (FR-SDK-9). React Strict Mode's dev-time double-effect is safe.
+ *
+ * Attached to `window.aforoEmbed` when running in browser context. The
+ * loader script (`loader/loader.ts`) imports this module + assigns it
+ * before scanning the DOM for `data-aforo-widget` placeholders.
+ */
+
+type GlobalConfig = {
+    tenantSlug?: string;
+    embedKey?: string;
+    bridgeToken?: string;
+    embedBaseUrl?: string;
+};
+type EventHandler = (event: AforoEventPayload) => void;
+/**
+ * Lazy registry — a widget bundle (Prompts 4-7) calls
+ * `AforoEmbed._registerWidget('pricing-card', mountFn)` at load time. The
+ * registry is internal: the registration function is NOT part of the
+ * locked public surface (asserted by sdk-contract.test.ts).
+ */
+type MountFn = (element: HTMLElement, config: WidgetMountConfig) => () => void;
+/** Internal: widget bundles register here. Not exported publicly. */
+declare function registerWidget(id: WidgetId, mountFn: MountFn): void;
+declare const AforoEmbed: {
+    version: string;
+    /**
+     * Set platform-wide defaults. Calling repeatedly merges (last call wins
+     * per key). Useful when the SPA learns the tenant context after page
+     * load (FR-TIER-10).
+     */
+    configure(cfg: GlobalConfig): void;
+    /** Read-only snapshot of the current global config. */
+    getConfig(): GlobalConfig;
+    /**
+     * Mount a widget into the given element. Idempotent — re-mounting the
+     * same element is a no-op.
+     */
+    mount(element: HTMLElement | null, config: WidgetMountConfig): boolean;
+    /** Unmount a previously-mounted widget. */
+    unmount(element: HTMLElement | null): boolean;
+    /**
+     * Subscribe to widget events. Returns an unsubscribe function.
+     *
+     * Pass `'*'` to receive every aforo.* event.
+     */
+    on(eventType: AforoEventType, handler: EventHandler): () => void;
+    /** Internal: bundle registration hook. Not part of the public surface. */
+    _registerWidget: typeof registerWidget;
+    /** Internal: list registered widget ids. Tests only. */
+    _registeredWidgetsForTesting(): WidgetId[];
+    /** Internal: reset registry. Tests only. */
+    _resetForTesting(): void;
+};
+
+export { AforoEmbed as A };