@betterreviews/react-native 1.0.0

package/LICENSE

@@ -0,0 +1,145 @@
+BetterReviews Proprietary License (BRPL) v1
+Copyright (c) 2026 BetterReviews ("Licensor")
+
+1. DEFINITIONS
+
+   "Software" means the `@betterreviews/react-native` npm package, including
+   its source code, generated artifacts, type definitions, and accompanying
+   documentation.
+
+   "Authorized Partner" means an entity that has executed a written
+   integration agreement with Licensor that explicitly names this Software
+   and grants right of use. As of the date of this LICENSE, the sole
+   Authorized Partner is Reactiv ("Reactiv Technologies Ltd." or its
+   successor entity).
+
+   "Production Use" means embedding or executing the Software in any
+   application distributed to end users, whether commercial or non-
+   commercial, paid or free.
+
+   "Evaluation Use" means executing the Software (a) against the BetterReviews
+   public mock endpoint with synthetic data only, or (b) against a
+   Licensor-issued sandbox credential, in either case strictly for the
+   purpose of evaluating the Software for a future integration agreement.
+
+2. GRANT OF LICENSE
+
+   2.1. To Authorized Partners. Subject to the terms of this LICENSE and
+   the partner's written integration agreement, Licensor grants each
+   Authorized Partner a non-exclusive, non-transferable, non-sublicensable,
+   revocable license to install, execute, and embed the Software for
+   Production Use solely within the scope defined in that agreement.
+
+   2.2. To Evaluators. Licensor grants any entity a non-exclusive,
+   non-transferable, non-sublicensable, revocable license to install and
+   execute the Software for Evaluation Use only. Evaluation Use does not
+   authorize Production Use, redistribution, modification, or any use
+   beyond pre-integration evaluation.
+
+3. RESTRICTIONS
+
+   You may not, and shall not permit any third party to:
+
+   (a) redistribute, sublicense, sell, lend, rent, or otherwise transfer
+       the Software, in source or compiled form, to any party other than
+       end users of an Authorized Partner's application;
+
+   (b) modify, adapt, translate, or create derivative works of the
+       Software, except for the minimum integration code required to wire
+       the Software into the Authorized Partner's application, and except
+       for bug fixes contributed back to Licensor under section 5;
+
+   (c) reverse engineer, decompile, or disassemble the Software, except
+       to the extent that applicable law expressly permits such activity
+       notwithstanding this restriction;
+
+   (d) remove, alter, or obscure any copyright, trademark, license, or
+       attribution notices contained in the Software;
+
+   (e) use the Software to build, train, or evaluate a product that
+       competes with the BetterReviews review-collection or review-display
+       platform;
+
+   (f) use the Software in any manner that would cause the Software to
+       become subject to an open-source license that requires disclosure
+       of any derivative work;
+
+   (g) extend Production Use beyond the scope granted in the partner's
+       written integration agreement.
+
+4. OWNERSHIP
+
+   The Software is licensed, not sold. Licensor retains all right, title,
+   and interest in and to the Software, including all intellectual
+   property rights. No rights are granted to any trademark, service mark,
+   or trade name of Licensor except as expressly stated in a separate
+   written agreement.
+
+5. CONTRIBUTIONS
+
+   If you submit a bug report, feature request, patch, or other
+   contribution to the Software, you grant Licensor a worldwide,
+   perpetual, irrevocable, royalty-free, sublicensable license to use,
+   modify, distribute, and incorporate that contribution into the
+   Software under any terms Licensor chooses, including under this
+   LICENSE.
+
+6. TERMINATION
+
+   6.1. This LICENSE terminates automatically upon (a) any material
+   breach by you of these terms, or (b) termination or expiration of
+   the underlying written integration agreement, whichever occurs first.
+
+   6.2. Licensor may terminate this LICENSE for any reason with thirty
+   (30) days' written notice. On termination, you must cease all use
+   of the Software and remove the Software from any application under
+   your control within thirty (30) days.
+
+   6.3. Sections 3, 4, 5, 7, 8, and 9 survive termination.
+
+7. CONFIDENTIALITY
+
+   The Software and any non-public information about its internal
+   structure, behavior, or roadmap is confidential to Licensor. You
+   shall protect such information with at least the same degree of care
+   you use for your own confidential information of similar
+   sensitivity, and in no event with less than reasonable care. This
+   obligation does not apply to information that is or becomes
+   publicly available through no fault of yours.
+
+8. WARRANTY DISCLAIMER
+
+   THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE," WITHOUT WARRANTY
+   OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+   WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+   NON-INFRINGEMENT, AND ACCURACY OF DATA. LICENSOR DOES NOT WARRANT
+   THAT THE SOFTWARE WILL OPERATE UNINTERRUPTED OR ERROR-FREE.
+
+9. LIMITATION OF LIABILITY
+
+   TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL
+   LICENSOR BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL,
+   CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR ANY LOSS OF PROFITS, REVENUE,
+   DATA, USE, OR GOODWILL, ARISING OUT OF OR IN CONNECTION WITH THIS
+   LICENSE OR THE SOFTWARE, WHETHER BASED IN CONTRACT, TORT (INCLUDING
+   NEGLIGENCE), STRICT LIABILITY, OR ANY OTHER THEORY, EVEN IF
+   ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. LICENSOR'S TOTAL
+   AGGREGATE LIABILITY UNDER THIS LICENSE SHALL NOT EXCEED ONE
+   HUNDRED U.S. DOLLARS ($100).
+
+10. GOVERNING LAW
+
+    This LICENSE is governed by the laws of England and Wales, without
+    regard to its conflict-of-laws principles. The courts located in
+    London, England shall have exclusive jurisdiction over any dispute
+    arising out of or relating to this LICENSE.
+
+11. ENTIRE AGREEMENT
+
+    This LICENSE, together with any executed written integration
+    agreement between you and Licensor, constitutes the entire
+    agreement between the parties with respect to the Software and
+    supersedes all prior or contemporaneous oral or written
+    communications, proposals, and representations.
+
+For licensing inquiries, contact: legal@betterreviews.app

package/README.md

@@ -0,0 +1,189 @@
+# @betterreviews/react-native
+
+Native React Native renderer for BetterReviews mobile PDP content. Consumes the `betterreviews_reactiv.*` Shopify metafield namespace and renders product content blocks themed to the merchant.
+
+## Authorized Partner
+
+This package is licensed for use by **Reactiv** under a written integration agreement with BetterReviews. See [LICENSE](./LICENSE).
+
+## Installation
+
+```bash
+yarn add @betterreviews/react-native \
+  react-native-webview react-native-svg react-native-gesture-handler
+```
+
+Peer dependencies your host app must provide: `react ≥18`, `react-native ≥0.74`, `react-native-webview ≥13`, `react-native-svg ≥15`, and `react-native-gesture-handler ≥2.16`. `valibot` is bundled as a direct dependency — you don't install it.
+
+**`react-native-gesture-handler` setup (required by `ReviewWidget`'s media viewer):** import it as the **very first line** of your app entry (`index.js`/`index.ts`) and wrap your app root in `GestureHandlerRootView`:
+
+```tsx
+import 'react-native-gesture-handler'; // must be first
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+
+export default function Root() {
+  return <GestureHandlerRootView style={{ flex: 1 }}>{/* app */}</GestureHandlerRootView>;
+}
+```
+
+> **npm users:** React Native 0.74 ships a mismatched `@types/react` peer range, so a plain `npm install` may fail with `ERESOLVE`. This is an upstream React Native quirk, not specific to this package — install with `npm install --legacy-peer-deps`, or use Yarn (which is more lenient). Yarn is recommended for React Native projects.
+
+## Quick start
+
+```tsx
+import {
+  BetterReviewsProvider,
+  ProductContentBlock,
+  type Theme,
+  type Config,
+  type ProductContentBlockSchema,
+} from '@betterreviews/react-native';
+
+function App() {
+  // Partner host app fetches the three metafield bodies from Shopify
+  // (storefront API or partner-backend proxy) for the active product.
+  const theme: Theme | null = useFetchedTheme(productId);
+  const config: Config | null = useFetchedConfig(productId);
+  const block: ProductContentBlockSchema | null = useFetchedBlock(productId);
+
+  return (
+    <BetterReviewsProvider
+      theme={theme}
+      config={config}
+      onTelemetryEvent={(event) => {
+        // Forward to partner's own observability stack.
+        partnerAnalytics.log(event);
+      }}
+    >
+      <ProductContentBlock block={block} />
+    </BetterReviewsProvider>
+  );
+}
+```
+
+## Render gates
+
+`<ProductContentBlock>` renders nothing (returns `null`) when any of these are true:
+
+- `config.product_content_block_enabled === false` — merchant explicitly disabled this product
+- `config.min_sdk_version` declared and current SDK below floor — emits `betterreviews.fetch.failure` telemetry
+- `block` is `null` / `undefined`
+- The block envelope fails top-level schema validation — emits `betterreviews.schema.violation` telemetry
+
+Per-section validation uses tolerant-reader semantics: an individual malformed section is dropped (with telemetry) while the rest render.
+
+## Telemetry events
+
+| Event | When |
+|---|---|
+| `betterreviews.fetch.failure` | Mount blocked by `min_sdk_version` floor (`error_code: "sdk_below_floor"`) |
+| `betterreviews.schema.violation` | Envelope or per-section validation failed |
+
+Future versions will emit `betterreviews.fetch.success`, `betterreviews.signature.invalid`, and `betterreviews.webview.error` (the last lands with the WebView host in Card C.12b).
+
+## Theming
+
+The widgets are **neutral by default** — a black CTA on zinc grayscale. No brand color appears unless the host opts in by passing a `theme` to `<BetterReviewsProvider>` (`background_color`, `text_color`, `accent_color`, `corner_style`, `font_family`). The only non-grayscale defaults are the **gold stars/bars** and the green **"Verified Buyer"** badge (universal review conventions, fixed in v1).
+
+## StarRating (aggregate badge)
+
+`<StarRating>` is the compact rating badge (stars + score + review count) for near the product title — the RN equivalent of the storefront `br-star-rating` block. The host supplies the aggregate (`average` + `total`, typically from the `betterreviews.summary` metafield it already fetches); the badge does **not** call the API.
+
+```tsx
+import { StarRating } from '@betterreviews/react-native';
+
+<StarRating average={4.5} total={128} onPress={scrollToReviews} />
+```
+
+Star color comes from `<BetterReviewsProvider>` theme (gold fallback outside a provider); `onPress` makes it a button (e.g. scroll to the `ReviewWidget`); it renders nothing when `total` is 0 (`hideWhenEmpty`, default on).
+
+## ReviewWidget (review browsing + voting)
+
+`<ReviewWidget>` renders the full review-browsing surface — paginated list, rating/photo/search filters, sort, read-more, a full-screen media viewer, and helpful/unhelpful voting.
+
+The package owns the UI + pagination/sort/filter state. **Your host app owns transport and auth** via an injected `Fetcher`: it prepends the API base URL, injects the widget `token`, and returns parsed JSON (throwing on a non-2xx status). No token ever lives inside this package or your app binary's SDK code — keep it in your host's secure config / backend proxy.
+
+```tsx
+import {
+  ReviewWidget,
+  createBetterReviewsClient,
+  type Fetcher,
+} from '@betterreviews/react-native';
+
+const fetcher: Fetcher = async ({ path, query, method = 'GET', body, signal }) => {
+  const params = new URLSearchParams();
+  for (const [k, v] of Object.entries(query ?? {})) if (v !== undefined) params.set(k, String(v));
+  params.set('token', getWidgetTokenFromSecureConfig()); // host-injected; never hardcode
+  const res = await fetch(`${API_BASE}${path}?${params}`, {
+    method, signal,
+    headers: body ? { 'Content-Type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) throw new Error(`widget request failed: HTTP ${res.status}`); // never log the URL — the token is in it
+  return res.json();
+};
+
+const client = createBetterReviewsClient({ fetcher, storeId, productId });
+
+// Theme + telemetry come from <BetterReviewsProvider> context (NOT props).
+<BetterReviewsProvider theme={theme} onTelemetryEvent={partnerAnalytics.log}>
+  <ReviewWidget client={client} onWriteReview={openReviewChat} />
+</BetterReviewsProvider>
+```
+
+Notes:
+- **`ReviewWidget` renders inline** — it owns no scroll container, so drop it into your product-page `ScrollView` as one section (e.g. below the product info and `ProductContentBlock`) and it scrolls with the page. Paging is a "Load more" button (no virtualization). The sort drawer and full-screen media viewer are `Modal` overlays, so they work regardless.
+- `onWriteReview` is host-owned (open your chat WebView / nav). The CTA hides if omitted. Never pass server-controlled strings to `Linking.openURL`.
+- Voting persists in-memory by default; pass `voteStateStore` (e.g. AsyncStorage-backed) to persist "already voted" across launches. Store only review id → direction; never review content or the token.
+- The widget requires the `GestureHandlerRootView` root wrap above.
+
+## Security obligations on the host
+
+See [SECURITY.md § "What you must do (the host)"](./SECURITY.md) for the contract every embedding host app must honor — credential storage, GDPR cascade, Shopify Level 2 data scope, cache TTL ceiling, Info.plist permissions, logging discipline.
+
+## Versioning
+
+This package follows semver. The `betterreviews_reactiv.*` metafield schema (generated JSON Schemas at `elixir/priv/reactiv_schemas/v1/`) follows additive-only compatibility with a 90-day deprecation window — see `schemas/betterreviews-reactiv/COMPATIBILITY.md` at the BetterReviews repo root.
+
+## WebView surface
+
+For the customer-facing chat flow (`/review/chat`), use `WebViewHost`:
+
+```tsx
+import { WebViewHost } from '@betterreviews/react-native';
+
+<WebViewHost
+  url={`https://api.betterreviews.app/review/chat?store_id=${storeId}&product_id=${productId}&token=${token}`}
+  onMessage={(event) => console.log('message from chat', event.nativeEvent.data)}
+  onError={(event) => console.warn('webview error', event.nativeEvent)}
+  onClose={() => dismissChat()} // fires when the page posts {type:'close'} (e.g. "Back to store")
+/>
+```
+
+The component intentionally exposes only `{ url, onMessage, onError }`. All underlying `WebView` props (cookie scope, content-inset behavior, keyboard handling, media playback) are locked to the baseline validated by the Tier 2 WebView test (`docs/proposals/reactiv-webview-tier2-test-2026-05-18.md`). Future recovery patches stay surgical.
+
+`react-native-webview ≥13.0.0` is a peer dep. Add it to your host app:
+
+```bash
+yarn add react-native-webview
+```
+
+## Bridge config
+
+`config.bridge` declares the merchant's preference for native bridge surfaces:
+
+- `"off"` (default): everything renders in-WebView.
+- `"auto"`: native if available, fall back to in-WebView.
+- `"required"`: native; if not available, render nothing.
+
+v1 of this package supports `"off"` only. `"auto"` and `"required"` resolve to `"off"` behavior and emit a `betterreviews.fetch.failure` telemetry event with `error_code: "bridge_not_implemented"` so partner observability can surface the unhonored intent. Native bridge implementations land post-soft-launch (Card C.14).
+
+## Not yet shipped
+
+- Native (non-WebView) bridge surfaces for the chat flow (Card C.14 — post-soft-launch)
+- Per-surface theming of the widget's fixed neutrals (star/verified/muted/border/scrim) — a later additive `theme` schema bump
+- HMAC signature verification (forward-compat — added when a bidirectional channel emerges)
+
+## License
+
+Proprietary. See [LICENSE](./LICENSE). For licensing inquiries: `legal@betterreviews.app`.

package/SECURITY.md

@@ -0,0 +1,238 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Email `security@betterreviews.app` with a description of the issue, steps
+to reproduce, and any proof-of-concept code. Encrypt sensitive details
+with our PGP key if you prefer (fingerprint: PENDING — published at
+https://betterreviews.app/.well-known/security.txt).
+
+**Do not file a public GitHub issue or open a PR for security issues.**
+
+We commit to:
+
+- Acknowledge receipt within 24 hours.
+- Provide an initial assessment within 72 hours.
+- Coordinate disclosure timing with you. We aim to patch within 14 days
+  for critical issues, 30 days for high, 90 days for medium and low.
+- Credit you in our advisory if you wish, after the fix ships.
+
+We will not pursue legal action against good-faith security research
+that follows this policy. Specifically, we permit:
+
+- Testing against the BetterReviews public mock endpoint
+  (`https://api.betterreviews.app/api/v1/reactiv/mock/*`) with synthetic
+  data only.
+- Testing against your own sandbox credential.
+- Decompiling or reverse-engineering this package for the sole purpose
+  of identifying a vulnerability you intend to report under this policy.
+
+We do not permit testing that:
+
+- Uses real production credentials issued to a different partner.
+- Accesses, modifies, or attempts to access another merchant's data.
+- Causes service disruption (DoS, fuzzing at scale, etc.).
+- Persists data exfiltrated from BetterReviews beyond what is needed
+  to demonstrate the issue.
+
+## Supported versions
+
+| Version | Supported     |
+|---------|---------------|
+| 1.x     | Yes           |
+| < 1.0   | Pre-release — no security commitments. Upgrade. |
+
+When a v2 ships, v1 remains supported with security patches for 12
+months from the v2 release date.
+
+## What BetterReviews commits to (the wire)
+
+The wire between this package and `api.betterreviews.app` is designed
+fail-closed. Specifically:
+
+- **HMAC signatures.** Every outbound state-change webhook from
+  BetterReviews to a partner endpoint is signed HMAC-SHA256. The
+  package verifies signatures using `Plug.Crypto.secure_compare`-
+  equivalent constant-time comparison; a missing or invalid signature
+  rejects the message.
+- **Per-merchant credentials.** The `reactiv_app_id` issued to a
+  partner is scoped per merchant. A leaked credential exposes one
+  merchant's content stream, not all merchants.
+- **No PII at rest in the package.** The package does not persist
+  customer email, name, IP, or any conversation transcript locally.
+  Review content fetched from BetterReviews is rendered and discarded
+  on view-change. If your host app caches review content, that is your
+  responsibility under the BR data-handling addendum.
+- **Tolerant-reader pattern.** Unknown JSON fields are ignored, never
+  echoed back to BR or forwarded to logs. Unknown section types in
+  product content blocks are skipped, logged locally, and reported via
+  the telemetry hook (see "Observability" below).
+- **WKWebView origin pinning.** The package's WebView host for
+  `/review/chat` pins the origin to `*.betterreviews.app` and
+  `*.betterreviews.ngrok-free.dev` (development only). Cross-origin
+  navigations are blocked.
+- **Schema validation.** Content blocks are validated against the
+  generated JSON Schema at `elixir/priv/reactiv_schemas/v1/` before
+  render. Schema mismatches are dropped, not partially rendered.
+- **Storage of partner credentials.** BetterReviews stores partner
+  credentials encrypted at rest via `PiiVault` (AES-GCM with per-tenant
+  key derivation). Plaintext credentials never appear in logs, audit
+  rows, or error messages.
+
+## What you must do (the host)
+
+Integrating this package into your host app shifts certain obligations
+to you. The integration is not safe unless you do these:
+
+### 1. Store credentials in iOS Keychain / Android Keystore
+
+The `reactiv_app_id` and any merchant-specific tokens must be stored
+in the platform-native secure enclave, never in `AsyncStorage`,
+`UserDefaults`, or shared preferences. Example: use
+`react-native-keychain` with `ACCESSIBLE_WHEN_UNLOCKED_THIS_DEVICE_ONLY`.
+
+### 2. Honor the GDPR cascade
+
+When a customer requests deletion under GDPR Article 17, you MUST:
+
+- Stop calling `/api/v1/reactiv/*` endpoints with that customer's
+  identifiers within 30 days of the request.
+- Purge any locally cached review content tied to that customer within
+  the same window.
+- Forward the request to BetterReviews via
+  `POST /api/v1/reactiv/customer-data-erasure` with the customer's
+  email hash (SHA-256 of lowercased email).
+
+A separate Data Processing Addendum covers BetterReviews' obligations
+on the upstream side.
+
+### 3. Honor the Shopify Level 2 protected data scope
+
+BetterReviews holds Shopify Level 2 protected customer data approval.
+Any review content you render through this package may include data
+classified as protected customer data under Shopify's policies. You
+must ensure your host app's Shopify data-handling commitments cover
+the data your app receives via this package, or terminate display when
+the merchant's Shopify access is revoked.
+
+### 4. Honor the cache TTL ceiling
+
+Review content fetched from BetterReviews may not be cached longer
+than 1 hour without re-fetch. This is enforced upstream by the
+`Cache-Control: max-age=3600` header on every `/api/v1/reactiv/content`
+response. The package respects this header on its own internal cache;
+if your host app adds its own cache layer, it must respect the same
+ceiling. (This bound is set by the BetterReviews GDPR remediation lag
+requirement — see the schema doc § 11 gap 8.)
+
+### 5. Configure Info.plist permissions
+
+The chat surface uses the iOS native photo picker. Your host app's
+`Info.plist` must declare:
+
+- `NSCameraUsageDescription`
+- `NSPhotoLibraryUsageDescription`
+- `NSMicrophoneUsageDescription` (only if you enable the
+  voice-input experiment)
+
+Without these, the photo step in the chat surface silently fails on
+iOS.
+
+### 6. Do not log review content, customer emails, or partner
+   credentials
+
+The package emits structured telemetry events via the configured
+telemetry hook (see "Observability"). Those events are pre-redacted.
+If you add your own logs around the package, do not log raw event
+payloads — they may contain review content (untrusted user input) or
+customer identifiers.
+
+### 7. Use mock-mode for development
+
+Do not use a production partner credential during development. The
+package supports a mock-mode flag that routes all calls to
+`https://api.betterreviews.app/api/v1/reactiv/mock/*`, which returns
+synthetic data and accepts any well-formed signature. Configure it
+via the `BR_REACTIV_MOCK_MODE=true` environment variable, or
+programmatically via the `mockMode: true` package option.
+
+### 8. Widget read/vote fetcher surface (`ReviewWidget`)
+
+`ReviewWidget` reads and votes via the public widget API (`/api/widget/...`),
+authenticated by a widget `token` query param that **your injected `Fetcher`
+supplies** — the token never lives in this package or your binary's SDK code.
+Obligations:
+
+- **Inject the token host-side, from secure config — never a `const TOKEN =
+  '...'` literal, never committed.** The widget read token is the public,
+  store-scoped HMAC token; it is rotated only by a global secret rotation that
+  affects every surface, so treat a leak as high-impact and keep it out of the
+  app binary (inject from your backend / secure store).
+- **Never log the resolved request URL or the raw fetcher error.** The token
+  rides in the query string — a logged URL or an `Error` whose message includes
+  the URL leaks it. Throw a coarse message (`HTTP <status>`), not the URL.
+- **Render review content (`body`/`title`/`author`/`tags`/`merchant_reply`) in
+  `<Text>` only — never a WebView, `react-native-render-html`, or any HTML
+  renderer.** Review text is untrusted, user-authored input; RN `<Text>` renders
+  it inert, an HTML renderer does not.
+- **Do not pass server-controlled strings to `Linking.openURL`.** Your
+  `onWriteReview` handler is host-owned; keep it to your own URLs.
+- The SDK already drops any media URL that is not `https://` and never sends
+  `product_id`-less detail/vote calls (the server scopes detail/vote to the
+  product). Don't bypass the client by reading the raw response shape yourself.
+
+## Observability
+
+The package emits the following telemetry event types via the
+configured `onTelemetryEvent` hook. All events are pre-redacted; no
+customer PII appears in any payload.
+
+| Event | When | Payload (redacted) |
+|---|---|---|
+| `betterreviews.fetch.success` | Successful content fetch | `{block_id, latency_ms, cache_hit}` |
+| `betterreviews.fetch.failure` | Failed content fetch | `{block_id, error_code, retry_attempt}` |
+| `betterreviews.signature.invalid` | HMAC verification failed | `{endpoint, source_ip_hash}` |
+| `betterreviews.schema.violation` | Content/response failed schema validation (one event per response — bad list rows are dropped, the rest render) | `{schema_version, violation_path, dropped_count}` |
+| `betterreviews.webview.error` | WebView navigation error | `{error_code, url_origin}` |
+
+Forward these events to your own observability stack. BetterReviews
+also receives an aggregate signal via the heartbeat endpoint (no
+per-event forwarding from your side).
+
+## Cryptographic primitives
+
+| Use | Primitive |
+|---|---|
+| Outbound webhook signing | HMAC-SHA256 |
+| Constant-time signature compare | `Plug.Crypto.secure_compare` (Elixir side); `crypto.timingSafeEqual` (Node side); the package uses the platform-native equivalent on RN |
+| TLS | TLS 1.3 required for all `*.betterreviews.app` endpoints |
+| PII at rest | AES-256-GCM via PiiVault (server side); package does not persist PII |
+| Email hash | SHA-256 of `lowercase(email)` |
+
+## Out-of-scope assets
+
+The following are intentionally not covered by this policy and should
+not be the target of security research:
+
+- Third-party services BetterReviews uses (Anthropic, OpenAI, AWS,
+  Cloudflare, Shopify). Report vulnerabilities in those to the vendor
+  directly.
+- Sample apps, demo stores, or fixtures distributed alongside this
+  package. They exist to demonstrate integration patterns and may
+  contain intentionally simplified code.
+- The mock endpoint's synthetic data. By design, it accepts any
+  well-formed signature so partner-side dev does not require real
+  credentials.
+
+## Contact
+
+- Vulnerability reports: `security@betterreviews.app`
+- General partner security questions:
+  `partner-security@betterreviews.app`
+- BetterReviews security lead: PENDING (publish name + LinkedIn once
+  team grows).
+
+## Acknowledgements
+
+We thank the following researchers for responsible disclosure
+(populated post-launch).