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

package/SECURITY_AUDIT.md

@@ -0,0 +1,78 @@
+# CARE-152 Dependency And Supply-Chain Audit
+
+Audit date: 2026-05-30
+
+Scope: `@nexalink/carecompass-sdk` source, package metadata, Bun lockfile, generated `dist` artifacts, README guidance, local package assembly, and release-process documentation.
+
+## Summary
+
+No high or critical dependency vulnerabilities were found by the available package-manager audit. No hardcoded Nexalink API key, payer credential, SageMaker credential, AppSync signing role, private model endpoint, AWS access key, or private endpoint URL was found in the package source or generated distributable files.
+
+The audit found supply-chain process gaps rather than an active secret exposure: release provenance and SBOM expectations were not previously documented, the package manager was not pinned in `package.json`, and the package dry-run script delegated to `bunx --bun npm pack`. These have been remediated in this branch with pinned package-manager metadata, a safer dry-run pack script, explicit release documentation, and exclusion of source maps from the published package surface.
+
+## Commands Run
+
+| Command                                  | Result                                                                                                                                        |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bun audit`                              | Passed. No vulnerabilities found.                                                                                                             |
+| `npm audit --audit-level=high`           | Not applicable because this repository uses `bun.lock` and has no `package-lock.json`.                                                        |
+| `bun outdated`                           | Runtime dependency `zod` current. Dev-tooling major updates available for `@eslint/js`, `eslint`, `@types/node`, `globals`, and `typescript`. |
+| `bun run build`                          | Passed after refreshing local Bun install links.                                                                                              |
+| `bun run lint`                           | Passed.                                                                                                                                       |
+| `bun run test`                           | Passed: 3 suites, 17 tests.                                                                                                                   |
+| `bun pm pack --dry-run --ignore-scripts` | Passed and confirmed the intended package contents.                                                                                           |
+
+## Dependency Review
+
+Runtime dependency:
+
+- `zod` `^4.4.3`
+
+Peer dependencies:
+
+- `react` `^18.3.0 || ^19.0.0`
+- `react-dom` `^18.3.0 || ^19.0.0`
+
+Development dependencies are limited to the React, Jest, ESLint, Prettier, TypeScript, and type-definition toolchain. The dependencies are mainstream packages, and the runtime package surface is small.
+
+`bun.lock` pins concrete transitive versions and integrity hashes for Bun installs. Non-Bun package managers are supported for consumers, but repository development and release validation are intentionally pinned to Bun with `bun install --frozen-lockfile`.
+
+## Package Script Review
+
+No `preinstall`, `install`, `postinstall`, `prepare`, `prepublish`, `publish`, or `postpublish` lifecycle scripts are declared by the root package.
+
+Package assembly now uses:
+
+```bash
+bun pm pack --dry-run --ignore-scripts
+```
+
+This avoids fetching or executing an external pack command through `bunx` and prevents lifecycle scripts during the dry run.
+
+## Generated Artifact Review
+
+The package publishes only `dist/**/*.js`, `dist/**/*.d.ts`, `README.md`, `LICENSE`, `RELEASE.md`, `SECURITY_AUDIT.md`, `RUNTIME_SECURITY_AUDIT.md`, and `package.json`.
+
+Source maps were removed from the published package surface. They did not contain embedded `sourcesContent`, but excluding them reduces accidental source-path and metadata disclosure in the public npm package.
+
+Searches for secret-like terms found only documented placeholders, public configuration examples, local credential handling code, and expected hosted API URLs. Credential writes use file mode `0600`, and CLI output does not print the secret API key.
+
+## Release-Process Risks And Remediation
+
+Resolved in this branch:
+
+- Added `packageManager` to pin Bun for development and release validation.
+- Added repository and issue metadata to `package.json`.
+- Added npm registry to `publishConfig`.
+- Added `audit` and `release:check` scripts.
+- Replaced `pack:dry-run` with a Bun-native dry run that ignores scripts.
+- Added `RELEASE.md` with versioning, validation, provenance, SBOM, and secret-handling expectations.
+- Excluded source maps from the package surface.
+
+Follow-up recommendations:
+
+- Add CI that runs `bun install --frozen-lockfile`, `bun run release:check`, and stores audit and package dry-run output as artifacts.
+- Publish through npm trusted publishing or `npm publish --provenance --access public`.
+- Generate and retain an SBOM for each production release.
+- Review major dev-tooling updates reported by `bun outdated` on a maintenance cadence.
+- Keep runtime dependency additions rare and require security review for any package with install lifecycle scripts or native binary behavior.

package/TELEMETRY.md

@@ -0,0 +1,129 @@
+# CareCompass SDK Telemetry Contract
+
+Contract version: `1.0.0`
+
+CareCompass SDK telemetry measures deployment health without collecting PHI,
+PII, chat content, or credentials. The web SDK sends allowlisted anonymous
+events directly to PostHog's public ingestion API. The CLI uses the same narrow
+transport for onboarding funnel events. React Native and Flutter SDKs should
+adopt the same event names and property contract.
+
+## Configuration
+
+Telemetry is enabled automatically for every web SDK deployment. Integrators do
+not need to run an additional CLI command, add a runtime config block, or manage
+a PostHog token.
+
+The web SDK sends events to Nexalink's PostHog project through the public US
+ingestion endpoint. It uses a Nexalink-owned public PostHog project token
+compiled into the SDK. The token permits event ingestion only; it is never a
+PostHog personal or admin API key.
+
+The anonymous deployment ID is derived from the public payer ID, environment,
+and web platform. For example, payer `acme-health` in staging is reported as
+`acme-health-staging-web`.
+
+CLI invocations use an ephemeral random `cli_session_id` as their anonymous
+PostHog `distinct_id`. It is created in memory for one process invocation and is
+not persisted. Before the CLI has public payer context, events use
+`anonymous-unknown-cli`; later events use the public payer ID and environment.
+
+## Event Taxonomy
+
+Initialization and configuration:
+
+- `carecompass_sdk_initialized`
+- `carecompass_sdk_initialization_failed`
+- `carecompass_sdk_configuration_validated`
+- `carecompass_sdk_configuration_failed`
+
+Component lifecycle:
+
+- `carecompass_component_rendered`
+- `carecompass_component_opened`
+- `carecompass_component_closed`
+- `carecompass_component_error`
+
+Inference lifecycle:
+
+- `carecompass_prompt_submitted`
+- `carecompass_inference_succeeded`
+- `carecompass_inference_failed`
+- `carecompass_inference_rate_limited`
+
+Customization and deployment health:
+
+- `carecompass_theme_loaded`
+- `carecompass_prompt_configuration_loaded`
+- `carecompass_prompt_configuration_failed`
+
+CLI onboarding:
+
+- `carecompass_cli_started`
+- `carecompass_cli_login_started`
+- `carecompass_cli_login_succeeded`
+- `carecompass_cli_login_failed`
+- `carecompass_cli_init_started`
+- `carecompass_cli_init_failed`
+- `carecompass_cli_setup_kit_generated`
+- `carecompass_cli_validation_succeeded`
+- `carecompass_cli_validation_failed`
+- `carecompass_cli_snippet_generated`
+- `carecompass_cli_doctor_completed`
+- `carecompass_cli_command_failed`
+
+For the always-visible web embed, opened and closed map to mount and unmount.
+Future mobile components should map these events to their equivalent visible
+screen lifecycle.
+
+## Allowed Properties
+
+Events contain only:
+
+- `contract_version`
+- `sdk_version`
+- `component_version`
+- `platform`
+- `environment`
+- `payer_id`
+- `deployment_id`
+- `event_timestamp`
+- `duration_bucket`, when applicable
+- `failure_category`, when applicable
+- `error_code`, when applicable
+- `cli_session_id`, for CLI events only
+- `$process_person_profile: false`
+
+The transport also sends the public PostHog project token, event name, anonymous
+`distinct_id`, and timestamp required by the PostHog ingestion API. Web events
+use the deployment ID as `distinct_id`; CLI events use the ephemeral
+`cli_session_id`. It does not identify individual users or create person
+profiles.
+
+## Prohibited Data
+
+Never send:
+
+- raw user prompts, model responses, chat history, or optional user context
+- PHI, PII, member IDs, policy IDs, names, emails, or phone numbers
+- API keys, access tokens, cookies, credentials, or session secrets
+- CLI arguments, terminal input, or file paths
+- SageMaker credentials, internal infrastructure details, or privileged tokens
+- raw error objects, stack traces, request payloads, or response bodies
+- payer prompt text; use an approved non-sensitive configuration ID in a future
+  contract version if needed
+
+The web SDK intentionally does not bundle `posthog-js`. It does not enable
+session replay, autocapture, DOM capture, form capture, cookies, persistence,
+surveys, feature flags, or user identification.
+
+Package download counts remain registry-owned metrics. CLI telemetry begins when
+the user invokes the installed package.
+
+## Verification
+
+1. Mount a development component, submit a non-PHI prompt, and complete an
+   inference.
+2. Confirm the expected lifecycle events arrive in Nexalink's PostHog project.
+3. Inspect event payloads and verify they contain only the allowlisted
+   properties above.

package/dist/cli.d.ts

@@ -3,6 +3,8 @@ type CliIO = {
     stdout: Pick<NodeJS.WriteStream, "write">;
     stderr: Pick<NodeJS.WriteStream, "write">;
     env: NodeJS.ProcessEnv;
+    stdin?: NodeJS.ReadStream;
+    prompt?: (question: string) => Promise<string>;
 };
 export declare function runCareCompassCli(argv?: string[], io?: CliIO): Promise<1 | 0>;
 export {};