@nexalink/carecompass-sdk 0.1.0-beta.8 → 0.2.0-beta.11

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to `@nexalink/carecompass-sdk` are documented in this file.
+
+This project uses [release-please](https://github.com/googleapis/release-please) and conventional commits to prepare changelog and version updates.
+
+## [0.2.0-beta.11](https://github.com/nexalink-care/carecompass-sdk/compare/v0.1.0-beta.11...v0.2.0-beta.11) (2026-06-07)
+
+
+### Features
+
+* baa self-serve ([3ff6d66](https://github.com/nexalink-care/carecompass-sdk/commit/3ff6d662dc83215b85615515eec01c54600fb9ea))
+* baa self-serve (CARE-155) ([92c11df](https://github.com/nexalink-care/carecompass-sdk/commit/92c11df5dfc85df195788f5b5aea03112c4c2420))
+* cli update ([99ef0e5](https://github.com/nexalink-care/carecompass-sdk/commit/99ef0e52166b519d8982bd67997fae4a0f1a4bb1))
+* implement telemetry (CARE-158) ([6337fd7](https://github.com/nexalink-care/carecompass-sdk/commit/6337fd791dc8bbf2192f2b683dbd2d0ef3bbf03a))
+* initial commit ([5369c40](https://github.com/nexalink-care/carecompass-sdk/commit/5369c409361be39caaa84db8d3ab1f98f5aec134))
+* initial commit ([26ec799](https://github.com/nexalink-care/carecompass-sdk/commit/26ec79928226e98235cd8c42a348a9e070b948c9))
+* necessary comments ([127c834](https://github.com/nexalink-care/carecompass-sdk/commit/127c8346bc865c5054b02490c890a53bd03db97a))
+* necessary comments ([d7f0d6b](https://github.com/nexalink-care/carecompass-sdk/commit/d7f0d6b7525b9e6282961b8172415e514305bed0))
+* security audit ([8115fe2](https://github.com/nexalink-care/carecompass-sdk/commit/8115fe2a75d522f2560ec1ec0f5d9ea1eb1feba4))
+* security audit ([0505ae1](https://github.com/nexalink-care/carecompass-sdk/commit/0505ae11937ab15d51b633c782494fe6af468217))
+* telemetry ([8f4dff3](https://github.com/nexalink-care/carecompass-sdk/commit/8f4dff3efc80e6e08ad6f0d19b12b7f85688b406))
+* telemetry update ([cd15546](https://github.com/nexalink-care/carecompass-sdk/commit/cd15546a756abfa30bf18705d204e9a21d12822f))
+* update cli flow ([69c55d5](https://github.com/nexalink-care/carecompass-sdk/commit/69c55d58d55ad64281384254852da468e20214f4))
+* updated init flow ([4bd0acf](https://github.com/nexalink-care/carecompass-sdk/commit/4bd0acfd08255b4614fb04b1d5c92b163fb8bcee))
+
+
+### Bug Fixes
+
+* whitespace issue ([764c7fc](https://github.com/nexalink-care/carecompass-sdk/commit/764c7fc23de945f4e358c944312c06c3567b0e5e))
+
+## [0.1.0-beta.11] - 2026-05-30
+
+### Added
+
+- Initial beta SDK package with React embed, vanilla mount helper, CLI setup flow, config validation, snippet generation, and local diagnostics.
+- Supply-chain and runtime security audit documentation for payer deployments.

package/LICENSE

@@ -9,7 +9,8 @@ written agreement with Nexalink Health, Inc.
 
 Authorized Nexalink customers and implementation partners may install and use
 this package solely to evaluate, integrate, test, and operate CareCompass embed
-experiences for payer-approved deployments using Nexalink-issued credentials.
+experiences for customer-approved healthcare deployments using Nexalink-issued
+credentials.
 
 You may not copy, modify, publish, distribute, sell, sublicense, reverse
 engineer, or use this software to provide a competing service except where

package/README.md

@@ -1,29 +1,29 @@
-# CareCompass Payer Embed SDK
+# CareCompass Healthcare Embed SDK
 
-`@nexalink/carecompass-sdk` helps payer teams embed a branded CareCompass chat experience in their own websites and applications. It includes a React component, a vanilla JavaScript mount helper, shared configuration validation, and a CLI for setup, validation, snippet generation, and local diagnostics.
+`@nexalink/carecompass-sdk` helps healthcare organizations embed a branded CareCompass chat experience in their own websites and applications. It includes a React component, a vanilla JavaScript mount helper, shared configuration validation, and a CLI for setup, validation, snippet generation, and local diagnostics.
 
-CareCompass lets a payer offer member-facing navigation support while keeping LLM inference behind Nexalink-hosted APIs. The payer controls the placement, branding, theme, labels, support links, allowed origins, and approved prompt configuration. Nexalink controls account validation, API-key enforcement, embed-key authorization, usage tracking, and the hosted model path.
+CareCompass lets healthcare teams offer member-facing navigation support while keeping LLM inference behind Nexalink-hosted APIs. The integrating organization controls the placement, branding, theme, labels, support links, allowed origins, and approved prompt configuration. Nexalink controls account validation, API-key enforcement, embed-key authorization, usage tracking, and the hosted model path.
 
-This package is publicly installable for developer convenience, but meaningful use requires a Nexalink payer account and a Nexalink-issued API key.
+This package is publicly installable for developer convenience, but live regulated use requires Nexalink onboarding, BAA coverage where PHI may be involved, and Nexalink-issued API credentials.
 
 ## Who This Is For
 
-This SDK is for enterprise healthcare teams that want to add CareCompass to a payer-owned frontend without building their own model gateway, prompt validation layer, key-management flow, or token-metering pipeline.
+This SDK is for enterprise healthcare teams that want to add CareCompass to their own frontend without building a model gateway, prompt validation layer, key-management flow, or token-metering pipeline.
 
 Typical users include:
 
-- payer portal developers embedding CareCompass in a member site
+- payer, provider, employer-benefits, care-navigation, and digital-health teams embedding CareCompass in a member or patient site
 - implementation engineers configuring staging and production deployments
 - technical operators validating origins, branding, and prompt policy
-- non-technical payer admins issuing SDK keys from the payer portal
+- non-technical customer admins issuing SDK keys from the Nexalink portal
 
 ## Account Required
 
-You need a Nexalink payer account before using the SDK beyond package installation.
+You need a Nexalink account with SDK access before using the SDK beyond package installation. For deployments that may involve PHI, a signed BAA and approved credentials are required before live use.
 
 The account is required because Nexalink validates:
 
-- the payer ID
+- the customer or payer ID
 - the secret SDK API key
 - the public browser embed key
 - the deployment environment
@@ -31,15 +31,35 @@ The account is required because Nexalink validates:
 - the approved prompt configuration
 - API usage and token counts for future metered billing
 
-API keys are issued in the Nexalink payer portal under the CareCompass SDK section. The secret API key is shown once and should be stored locally by the developer. It should never be committed to source control or placed in browser code.
+API keys are issued in the Nexalink portal under the CareCompass SDK section.
+For first-time onboarding, a tenant owner or admin executes the canonical BAA
+from the portal BAA page before generating the first key. The secret API key is
+shown once and should be stored locally by the developer. It should never be
+committed to source control or placed in browser code.
 
-If you do not have an API key, run:
+### API Key Vs Embed Key
+
+CareCompass uses two different keys with different security expectations:
+
+- **API key**: a secret credential for trusted setup and server-side/CLI
+  workflows. Use it to authenticate actions such as signing in during `init` and
+  creating or managing SDK access. Never include it in browser code, generated
+  embed HTML, frontend config, or source control.
+- **Embed key**: a public browser-facing identifier for the CareCompass embed.
+  It is safe to include in `carecompass.config.json` and generated snippets. It
+  identifies the payer, environment, and embed client for runtime requests, but
+  it is not a secret and should not be treated as proof of identity on its own.
+
+Start onboarding with:
 
 ```bash
-npx @nexalink/carecompass-sdk login
+npx @nexalink/carecompass-sdk init
 ```
 
-The CLI will direct you to the payer signup path.
+The CLI routes developers without accounts to the configured signup path,
+validates the API key with Nexalink, stores it locally only after successful
+sign-in, and generates the SDK config. BAA execution happens in the Nexalink web
+app before API key creation.
 
 ## Install And Run
 
@@ -47,15 +67,14 @@ Use any common JavaScript package manager. For first-time testing, the simplest
 path is to run each command with `npx`.
 
 ```bash
-npx @nexalink/carecompass-sdk login --api-key <nexalink-api-key>
-npx @nexalink/carecompass-sdk init --payer-id acme-health --origin https://members.acme-health.com
+npx @nexalink/carecompass-sdk init --account-type developer --api-key <nexalink-api-key> --payer-id acme-health --origin https://members.acme-health.com
 npx @nexalink/carecompass-sdk validate --config carecompass/carecompass.config.json
 npx @nexalink/carecompass-sdk doctor --config carecompass/carecompass.config.json
 ```
 
-`npx` does not permanently install a `carecompass` shell command. If you use
-`npx` for login, keep using `npx @nexalink/carecompass-sdk <command>` for init,
-validate, snippet, and doctor.
+`npx` does not permanently install a `carecompass` shell command. Keep using
+`npx @nexalink/carecompass-sdk <command>` for init, validate, snippet, and
+doctor.
 
 Package-manager equivalents:
 
@@ -83,17 +102,15 @@ carecompass init --payer-id acme-health --origin https://members.acme-health.com
 
 ## CLI Commands
 
-### `login`
-
-Stores your secret Nexalink API key locally so the other SDK commands can validate your payer configuration.
-
-```bash
-npx @nexalink/carecompass-sdk login --api-key <nexalink-api-key>
-```
+### `init`
 
-Credentials are stored at `~/.nexalink/carecompass/credentials.json` by default. You can also set `CARECOMPASS_API_KEY` in your shell or CI environment.
+Runs the complete first-time onboarding flow:
 
-### `init`
+- routes users without accounts to the configured signup path
+- validates the API key with Nexalink before continuing
+- stores the secret Nexalink API key locally
+- generates the SDK config, prompt starter, embed page, iframe, and setup guide
+  with only public embed configuration
 
 Creates a `carecompass` folder with all generated SDK files in one place:
 
@@ -103,7 +120,17 @@ Creates a `carecompass` folder with all generated SDK files in one place:
 - `carecompass/carecompass-iframe.html`
 - `carecompass/README.md`
 
-The CLI prints the setup steps in order: review config, edit the system prompt, serve the generated embed page, place the iframe, then validate. The config file contains payer-facing configuration only. It does not contain the secret API key. The embed HTML and iframe are generated automatically during `init`; you do not need to run a separate snippet command for the first setup.
+Credentials are stored at `~/.nexalink/carecompass/credentials.json` by
+default. You can also set `CARECOMPASS_API_KEY` in your shell or CI environment.
+The generated config contains payer-facing configuration only. It does not
+contain the secret API key. The embed HTML and iframe are generated
+automatically during `init`; you do not need to run a separate snippet command
+for the first setup.
+
+For scripted setup, pass `--account-type developer`. The developer signup route
+can be configured with `--developer-signup-url` or
+`CARECOMPASS_DEVELOPER_SIGNUP_URL`. By default, that route is
+`https://www.nexalink.care/developer/signup`.
 
 By default, generated HTML is bundler-friendly and imports the package as
 `@nexalink/carecompass-sdk`, which works with Parcel, Vite, Next.js, and similar
@@ -112,16 +139,18 @@ demo that is not processed by Parcel or another bundler, add
 `--snippet-mode cdn`.
 
 ```bash
-npx @nexalink/carecompass-sdk init --payer-id acme-health --origin https://members.acme-health.com
-npx @nexalink/carecompass-sdk init --snippet-mode cdn --payer-id acme-health --origin https://members.acme-health.com
+npx @nexalink/carecompass-sdk init --account-type developer --api-key <nexalink-api-key> --payer-id acme-health --origin https://members.acme-health.com
+npx @nexalink/carecompass-sdk init --account-type developer --snippet-mode cdn --payer-id acme-health --origin https://members.acme-health.com
 ```
 
 ### `validate`
 
 Checks that the config shape is valid and that credentials are available.
 By default this also calls the hosted Nexalink config-validation endpoint, which
-confirms the API base URL, API key, embed key, environment, and first allowed
-origin are accepted by the server. Use `--local-only` for schema-only checks.
+confirms the API base URL, public embed key, payer ID, environment, and allowed
+origins are accepted by the server. The browser-side validation request uses
+public embed headers; it does not send the secret API key. Use `--local-only`
+for schema-only checks.
 
 ```bash
 npx @nexalink/carecompass-sdk validate --config carecompass/carecompass.config.json
@@ -149,6 +178,11 @@ npx @nexalink/carecompass-sdk doctor --config carecompass/carecompass.config.jso
 
 `carecompass/carecompass.config.json` is safe to commit when it only contains public embed configuration. Do not add the secret API key to this file.
 
+The config is client-facing by design. It should contain the public `embedKey`,
+the payer ID, environment, allowed origins, branding, labels, theme, and prompt
+settings. Store the secret API key only in the local CLI credentials file or an
+approved server-side secret store.
+
 ```json
 {
   "payerId": "acme-health",
@@ -187,6 +221,24 @@ npx @nexalink/carecompass-sdk doctor --config carecompass/carecompass.config.jso
 }
 ```
 
+## Privacy-Safe Telemetry
+
+Telemetry is enabled automatically with Nexalink-managed defaults. Integrators
+do not need to run an additional CLI command, add a runtime config block, or
+manage a PostHog token. The CLI also sends anonymous onboarding funnel events
+using an ephemeral per-process session ID that is never persisted.
+
+The SDK sends only allowlisted anonymous deployment-health events directly to
+PostHog's public ingestion API. It does not bundle `posthog-js`, enable session
+replay or autocapture, identify users, set cookies, or persist analytics state.
+Prompts, model responses, chat history, user context, PHI/PII, credentials, raw
+errors, and stack traces are never included. CLI arguments, terminal input, and
+file paths are also excluded.
+
+The SDK uses a Nexalink-owned public PostHog ingestion token. See
+[`TELEMETRY.md`](./TELEMETRY.md) for the shared web, React Native, and Flutter
+event contract.
+
 ## System Prompt File
 
 `carecompass/system-prompt.md` lets the payer define approved context before a member message reaches the LLM. Use it to steer CareCompass toward plan-specific terminology, support boundaries, escalation rules, and benefit-navigation context.
@@ -195,7 +247,7 @@ The prompt file is resolved by the CLI when it generates `carecompass/carecompas
 
 ## Iframe Placement
 
-`carecompass/carecompass-iframe.html` contains the iframe to place on the payer page where the CareCompass LLM should appear.
+`carecompass/carecompass-iframe.html` contains the iframe to place on the integrating page where the CareCompass LLM should appear.
 
 ```html
 <iframe
@@ -206,7 +258,7 @@ The prompt file is resolved by the CLI when it generates `carecompass/carecompas
 ></iframe>
 ```
 
-Serve `carecompass/carecompass-embed.html` from the payer site at the iframe `src`. For many apps, that means copying the generated `carecompass` folder into the app's public/static assets folder before deployment.
+Serve `carecompass/carecompass-embed.html` from the integrating site at the iframe `src`. For many apps, that means copying the generated `carecompass` folder into the app's public/static assets folder before deployment.
 
 ## React Usage
 
@@ -265,16 +317,31 @@ Peer dependency range:
 
 The CLI requires Node.js 18 or newer.
 
+## Development
+
+This repository uses Bun for local development.
+
+```bash
+bun install
+bun run build
+bun run test
+bun run pack:dry-run
+```
+
+Do not publish a new package version unless the SDK version is intentionally
+changed and release approval is complete.
+
 ## What Runs In The Browser
 
 The browser receives only public embed configuration:
 
-- payer ID
+- customer or payer ID
 - environment
 - public `embedKey`
 - branding and theme values
 - labels and support links
 - approved prompt settings
+- Nexalink-managed telemetry defaults compiled into the SDK
 
 The browser does not receive:
 
@@ -286,9 +353,46 @@ The browser does not receive:
 
 Chat requests are sent to Nexalink-hosted CareCompass API routes. The component does not call the model endpoint directly.
 
+## Hosted LLM Warm-Up
+
+Nexalink hosts the proprietary CareCompass LLM runtime behind Nexalink-managed
+API routes. To control infrastructure costs for early deployments, Nexalink may
+run some hosted model endpoints with scale-to-zero capacity. When an endpoint
+has scaled to zero, the first chat request after an idle period can take several
+minutes while cloud GPU capacity is allocated and the model endpoint warms up.
+
+This warm-up delay is expected for some MVP and development environments. It
+does not mean the browser embed needs a secret API key, and it does not mean the
+SDK is calling SageMaker directly. The request is queued through Nexalink-hosted
+APIs while the model endpoint starts. Nexalink is actively working on
+improvements to reduce or avoid first-request warm-up delays.
+
+## Runtime Security Model
+
+The SDK component uses the public browser `embedKey`, payer ID, environment, and
+allowed origin metadata to call Nexalink-hosted embed API routes. The secret SDK
+API key is used only by trusted setup and server-side/CLI workflows and must
+never be placed in browser config or generated snippets.
+
+For staging and production, `apiBaseUrl` must be a Nexalink-hosted HTTPS URL.
+`localhost` API and origin values are accepted only for `development`
+configurations. Hosted validation still remains authoritative: Nexalink API
+routes must enforce payer ID, embed key, environment, allowed origin, prompt
+guardrails, rate limiting, request attribution, and tenant isolation for config,
+analytics, logs, prompts, and model requests.
+
+Generated snippets escape serialized config before embedding it in a module
+script. React renders chat messages and labels as text rather than raw HTML.
+Do not add `dangerouslySetInnerHTML`, raw HTML snippets, unreviewed third-party
+scripts, or payer-provided secret values to an embed page.
+
 ## API Keys And Usage Tracking
 
-SDK API keys are issued in the payer portal and stored server-side as hashes. Each key is associated with a payer, environment, public embed key, and allowed origins.
+SDK API keys are issued in the Nexalink portal and stored server-side as hashes.
+Each secret API key is associated with a customer or payer ID, environment,
+public embed key, and allowed origins. The API key authenticates trusted setup
+and management flows; the public embed key is what the browser uses for
+client-facing runtime requests.
 
 CareCompass usage under a key is tracked so Nexalink can support future Stripe metered billing. The backend records prompt tokens, completion tokens, total tokens, and last-used timestamps per payer/API key. Hosted routes use MedGemma token counts when they are available and fall back to estimates only when needed.
 
@@ -306,15 +410,22 @@ Before production, confirm:
 
 - production origin is allowlisted exactly
 - production `embedKey` is separate from staging
+- production `apiBaseUrl` points at the approved Nexalink-hosted environment
 - support links route to the payer's approved support surface
 - prompt instructions are approved by Nexalink and the payer
 - no secret API key appears in generated source code
+- diagnostics, logs, and analytics are configured to avoid raw PHI/PII, raw
+  prompts, raw model responses, credentials, or privileged backend tokens unless
+  Nexalink has approved a secure diagnostic path
 
 ## Troubleshooting
 
 `Missing Nexalink API key`
 
-Run `npx @nexalink/carecompass-sdk login --api-key <key>` or set `CARECOMPASS_API_KEY`.
+Run `npx @nexalink/carecompass-sdk init`, choose Developer, and sign in with an
+API key. For non-interactive setup, pass `--account-type developer` with
+`--api-key <key>`, or set `CARECOMPASS_API_KEY` with
+`CARECOMPASS_ACCOUNT_TYPE=developer`.
 
 `zsh: command not found: carecompass`
 
@@ -340,7 +451,7 @@ typing into the embed.
 
 `Origin is not authorized`
 
-Add the exact website origin to the payer portal SDK configuration.
+Add the exact website origin to the Nexalink portal SDK configuration.
 
 `Prompt configuration violates CareCompass guardrails`
 
@@ -348,7 +459,7 @@ Remove unsafe or unsupported instructions and re-run validation.
 
 `CareCompass embed client is not authorized`
 
-Confirm `payerId`, `embedKey`, `environment`, and allowed origins match the key issued in the payer portal.
+Confirm `payerId`, `embedKey`, `environment`, and allowed origins match the key issued in the Nexalink portal.
 
 `CareCompass AppSync inference service is not configured`
 

package/RELEASE.md

@@ -0,0 +1,65 @@
+# CareCompass SDK Release Process
+
+This package is public, but production use requires Nexalink onboarding, BAA coverage where PHI may be involved, and Nexalink-issued credentials. Treat each package release as a supply-chain event.
+
+## Release Authority
+
+- Only approved Nexalink maintainers may publish `@nexalink/carecompass-sdk`.
+- Publish from the canonical GitHub repository: `https://github.com/nexalink-care/carecompass-sdk`.
+- Use the pinned package manager in `package.json` and keep `bun.lock` committed.
+- Do not publish from a dirty working tree or from a local branch that has not passed review.
+
+## Versioning
+
+- Version and changelog updates are managed by release-please on `main`.
+- Use beta versions for pre-production SDKs and avoid reusing a published version.
+- Record security-relevant dependency or packaging changes in the release notes.
+- Use conventional commit messages so release-please can classify release notes.
+
+## Required Validation
+
+Run the full local release check before publishing:
+
+```bash
+bun install --frozen-lockfile
+bun run release:check
+```
+
+`release:check` runs lint, tests, build, dependency audit, and a dry-run package assembly. The package dry run uses `bun pm pack --dry-run --ignore-scripts` so package assembly does not execute install lifecycle scripts.
+
+Before approval, review the dry-run file list and confirm it contains only:
+
+- `dist/**/*.js`
+- `dist/**/*.d.ts`
+- `CHANGELOG.md`
+- `README.md`
+- `TELEMETRY.md`
+- `LICENSE`
+- `RELEASE.md`
+- `SECURITY_AUDIT.md`
+- `RUNTIME_SECURITY_AUDIT.md`
+- `package.json`
+
+Do not publish source maps, local credentials, generated payer configs, test fixtures with secret-like values, `.env` files, package-manager caches, or build logs.
+
+## Dependency And Lockfile Controls
+
+- Use `bun install --frozen-lockfile` in CI to verify reproducible installs.
+- Run `bun audit` before every release.
+- Review `bun outdated` output during routine maintenance and update dev tooling deliberately.
+- Do not add install lifecycle scripts unless the security impact is documented and reviewed.
+- Do not trust transitive package lifecycle scripts in Bun unless there is a specific approved need.
+
+## Provenance, SBOM, And Publishing
+
+Preferred production publishing should use npm trusted publishing or `npm publish --provenance --access public` from CI after the release check passes. Local publishing is allowed only for emergency releases approved by the package owners.
+
+Generate an SBOM during CI when the release pipeline supports it, and retain the SBOM, audit output, package dry-run output, and final tarball integrity in release artifacts.
+
+Release PRs are opened by `.github/workflows/release-please.yml` using the manifest files under `.github/`. Merging the release PR updates `package.json`, `CHANGELOG.md`, and the release manifest, then creates the GitHub release.
+
+## Secret Handling
+
+- Never place Nexalink SDK API keys, payer credentials, SageMaker credentials, AppSync signing roles, or private endpoint URLs in source, docs, tests, generated snippets, package metadata, or release artifacts.
+- CLI credentials must stay in the local credentials file or environment variables described in `README.md`.
+- Generated browser embed files may include public payer configuration and prompt text. Review generated files before committing them to an integrating application.

package/RUNTIME_SECURITY_AUDIT.md

@@ -0,0 +1,180 @@
+# CARE-153 Runtime, API, And Tenant-Isolation Audit
+
+Audit date: 2026-05-30
+
+Scope: SDK-side runtime, embed, CLI validation, generated snippets, browser configuration, prompt configuration, sensitive-data handling, and documentation for payer deployments. Hosted Nexalink API route implementations, backend rate limiting, backend CORS enforcement, backend logs, analytics stores, and SageMaker/AppSync infrastructure are outside this repository and must be validated in the hosted API codebase.
+
+## Summary
+
+The SDK does not ship private SageMaker credentials, AppSync signing roles, privileged backend tokens, or secret Nexalink SDK API keys to the browser. Browser requests use public payer configuration and public embed headers; backend hosted routes remain the authoritative enforcement point for payer identity, embed-key authorization, allowed origins, rate limits, prompt guardrails, logs, analytics, and tenant isolation.
+
+This audit found and remediated two SDK-side runtime issues:
+
+- Staging and production configs could previously point `apiBaseUrl` at any HTTPS origin. The schema now requires a Nexalink-hosted HTTPS API URL for staging and production, with localhost allowed only for development.
+- Generated embed snippets previously serialized config with plain `JSON.stringify` inside a module script. Config values containing `</script>` could break the script context when served as raw HTML. Snippet generation now escapes script-sensitive JSON characters and iframe attributes.
+
+## Auth And API Access Model
+
+- CLI commands use the secret Nexalink SDK API key from `--api-key`, `CARECOMPASS_API_KEY`, or the local credentials file.
+- `init` uses that API key to check BAA status and submit execution metadata to Nexalink-hosted routes. The CLI never receives AWS credentials.
+- Browser/runtime code never receives the secret SDK API key.
+- Browser requests include:
+  - `x-carecompass-payer-id`
+  - `x-carecompass-embed-key`
+  - `x-carecompass-environment`
+- Browser requests target only these SDK paths under the configured Nexalink-hosted API base URL:
+  - `POST /api/carecompass/embed/config/validate`
+  - `POST /api/carecompass/embed/ask`
+  - `GET /api/carecompass/embed/status/:jobId`
+
+Backend requirements that must remain enforced outside this SDK:
+
+- payer ID and embed key binding
+- environment binding
+- exact allowed-origin checks
+- tenant isolation for configuration, prompts, requests, responses, logs, analytics, and usage records
+- rate limiting and request attribution by payer/deployment
+
+## Tenant Isolation Review
+
+SDK-side controls:
+
+- The config schema validates payer ID format, embed key format, deployment environment, allowed origins, API base URL, prompt structure, theme values, and public branding fields.
+- Staging and production cannot use localhost API base URLs or localhost allowed origins.
+- The client sends payer ID, embed key, and environment on every config-validation and inference request.
+- The SDK does not expose APIs for reading another payer's configuration, analytics, logs, prompt history, or user data.
+
+Backend-owned validation:
+
+- The SDK cannot prove cross-payer isolation by itself because tenant state lives in hosted Nexalink services.
+- Hosted routes must reject mismatched payer ID, embed key, environment, and origin tuples.
+- Hosted routes must scope job status lookups by payer/deployment, not only by `jobId`.
+
+## Allowed Origin And API Base URL Controls
+
+Resolved in this branch:
+
+- `apiBaseUrl` must be a Nexalink-hosted HTTPS URL, except localhost for development.
+- Staging and production configs reject localhost `apiBaseUrl`.
+- Staging and production configs reject localhost allowed origins.
+- Browser-hosted pages still fail fast if a non-local page tries to call a localhost API base URL.
+
+Follow-up for hosted API:
+
+- Test unauthorized origins against deployed staging and production routes.
+- Confirm CORS and origin checks happen server-side and are not based only on SDK validation.
+
+## Client-Side Token And Secret Handling
+
+No client-side secret exposure was found.
+
+- Secret SDK API keys are read by the CLI only.
+- The browser receives public `embedKey`, payer ID, environment, branding, labels, allowed origins, and prompt configuration.
+- Credential storage writes local keys with file mode `0600`.
+- CLI output prints the credentials path and source, not the API key value.
+- Executed BAA copies contain agreement metadata and terms, not the SDK API key
+  or private cloud credentials. The CLI writes local executed copies with
+  owner-only (`0600`) permissions.
+
+## Prompt Controls And Sensitive Data Handling
+
+SDK-side controls:
+
+- Prompt instructions are length-limited and checked for explicit guardrail-bypass patterns.
+- Generated setup guidance warns against secrets, raw PHI, diagnosis instructions, treatment instructions, and guardrail bypass attempts in prompt files.
+- `allowUserContext` defaults to `false`.
+
+Backend-owned validation:
+
+- Hosted routes must re-validate prompt configuration against Nexalink policy because browser config is attacker-controlled.
+- Hosted routes must treat user messages, prompt content, model responses, and optional user context as sensitive data.
+
+## Embed, XSS, And CSP Review
+
+Resolved in this branch:
+
+- Generated config JSON is escaped before insertion into `<script type="module">`.
+- Generated iframe `title` and `src` attributes are HTML-attribute escaped.
+
+Existing controls:
+
+- React renders labels and messages as text, not raw HTML.
+- The component does not use `dangerouslySetInnerHTML`, `innerHTML`, `eval`, or `new Function`.
+
+Integration guidance:
+
+- Prefer bundler mode over CDN mode for production.
+- If CDN mode is used for a raw browser demo, the integrating page should set CSP `script-src` for the approved CDN and Nexalink assets only.
+- Do not place unreviewed payer-provided HTML or third-party scripts in generated embed pages.
+
+## Logging, Diagnostics, Telemetry, And Errors
+
+CARE-158 adds an always-on privacy-safe telemetry transport documented in
+`TELEMETRY.md`. The SDK sends only allowlisted anonymous lifecycle metadata to
+PostHog's public ingestion API using a Nexalink-owned public ingestion token.
+Integrators do not configure telemetry or receive a disable switch. The SDK
+does not bundle `posthog-js`, enable session replay or autocapture, identify
+users, set cookies, or persist analytics state.
+
+The CLI sends fixed onboarding funnel events through the same transport. Each
+CLI process uses an ephemeral random session ID that is not persisted. CLI
+payloads exclude arguments, terminal input, file paths, API keys, and BAA signer
+details.
+
+Telemetry payloads exclude prompts, model responses, chat history, optional
+user context, PHI/PII, credentials, raw errors, stack traces, request payloads,
+and response bodies. Error telemetry uses fixed codes and categories. Telemetry
+delivery failures are swallowed so analytics cannot interrupt SDK workflows.
+Runtime errors shown in the component remain derived from local network
+failures or backend error responses.
+
+Backend-owned controls:
+
+- Hosted routes must avoid logging raw PHI/PII, credentials, raw prompts, raw model responses, or privileged backend tokens unless an explicitly approved secure diagnostic path exists.
+- Backend error responses should be sanitized because the component may display the error message.
+
+## Rate Limiting And Abuse Prevention
+
+The SDK can attribute requests by payer ID, embed key, and environment headers, but cannot enforce real rate limits or abuse controls because browser clients are untrusted.
+
+Hosted routes must enforce:
+
+- per-payer and per-origin rate limits
+- per-embed-key request attribution
+- abuse detection for prompt flooding and job-status polling
+- safe status lookup scoping by payer/deployment
+
+## Verification
+
+Commands run:
+
+| Command                 | Result                                                                                      |
+| ----------------------- | ------------------------------------------------------------------------------------------- |
+| `bun run test`          | Validates schema hardening, snippet escaping, CLI behavior, and component runtime requests. |
+| `bun run lint`          | Ensures code quality after remediation.                                                     |
+| `bun run build`         | Regenerates distributable JavaScript and declarations.                                      |
+| `bun run release:check` | Runs frozen install, lint, tests, build, audit, and package dry run.                        |
+
+New regression coverage:
+
+- Reject non-Nexalink `apiBaseUrl` values.
+- Allow localhost API/origin/support URLs only for development.
+- Reject unsafe branding URL schemes.
+- Escape `</script>`-style values in generated embed config JSON.
+- Escape iframe attributes.
+
+## Findings And Follow-Up
+
+Resolved:
+
+- Medium: staging/production `apiBaseUrl` allowed arbitrary HTTPS endpoints. Owner: SDK. Remediation: require Nexalink-hosted HTTPS API URLs outside development.
+- Medium: generated script snippets did not escape script-sensitive JSON characters. Owner: SDK. Remediation: escape `<`, `>`, `&`, U+2028, and U+2029 in serialized config JSON.
+
+No high or critical SDK-side runtime findings remain in this repository.
+
+Follow-up required outside this SDK repository:
+
+- Validate deployed hosted API CORS/origin enforcement with unauthorized origins.
+- Validate cross-payer tenant isolation for config, prompt, analytics, logs, job status, and model request data in the hosted API codebase.
+- Validate backend log/telemetry redaction for raw prompts, model responses, credentials, PHI/PII, and privileged tokens.
+- Validate backend rate limiting and request attribution by payer, environment, origin, and embed key.