{"id":50453948,"url":"https://github.com/mizcausevic-dev/kinetic-gain-embedded","last_synced_at":"2026-06-01T01:05:29.143Z","repository":{"id":361330867,"uuid":"1254039328","full_name":"mizcausevic-dev/kinetic-gain-embedded","owner":"mizcausevic-dev","description":"Drop-in audit-stream + Decision Card vault contract SDK for B2B SaaS. Emit hash-chained Suite-compliant audit events, enforce vault contracts before AI tools touch sensitive data, validate Decision Cards. TypeScript-first, dual ESM/CJS, zero runtime deps. Apache-2.0.","archived":false,"fork":false,"pushed_at":"2026-05-30T05:38:26.000Z","size":46,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-30T07:13:54.669Z","etag":null,"topics":["ai-disclosure","ai-governance","apache-2","audit-stream","decision-card","ed25519","embedded-analytics","hash-chained-audit","kinetic-gain","kinetic-gain-protocol-suite","saas-embedding","tokenization","typescript","vault-contract"],"latest_commit_sha":null,"homepage":"https://kineticgain.com/embedded/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mizcausevic-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-30T04:28:58.000Z","updated_at":"2026-05-30T05:38:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mizcausevic-dev/kinetic-gain-embedded","commit_stats":null,"previous_names":["mizcausevic-dev/kinetic-gain-embedded"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/mizcausevic-dev/kinetic-gain-embedded","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizcausevic-dev%2Fkinetic-gain-embedded","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizcausevic-dev%2Fkinetic-gain-embedded/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizcausevic-dev%2Fkinetic-gain-embedded/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizcausevic-dev%2Fkinetic-gain-embedded/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mizcausevic-dev","download_url":"https://codeload.github.com/mizcausevic-dev/kinetic-gain-embedded/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizcausevic-dev%2Fkinetic-gain-embedded/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33755377,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-disclosure","ai-governance","apache-2","audit-stream","decision-card","ed25519","embedded-analytics","hash-chained-audit","kinetic-gain","kinetic-gain-protocol-suite","saas-embedding","tokenization","typescript","vault-contract"],"created_at":"2026-06-01T01:05:28.611Z","updated_at":"2026-06-01T01:05:29.138Z","avatar_url":"https://github.com/mizcausevic-dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kinetic-gain-embedded\n\n[![ci](https://github.com/mizcausevic-dev/kinetic-gain-embedded/actions/workflows/ci.yml/badge.svg)](https://github.com/mizcausevic-dev/kinetic-gain-embedded/actions/workflows/ci.yml)\n[![npm-publish](https://github.com/mizcausevic-dev/kinetic-gain-embedded/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/mizcausevic-dev/kinetic-gain-embedded/actions/workflows/npm-publish.yml)\n[![npm version](https://img.shields.io/npm/v/kinetic-gain-embedded.svg)](https://www.npmjs.com/package/kinetic-gain-embedded)\n[![license: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n[![node: ≥20](https://img.shields.io/badge/node-%E2%89%A520-brightgreen.svg)](package.json)\n\n**Drop-in audit-stream + Decision Card vault contract SDK for B2B SaaS.**\n\nBuilt for SaaS embedders whose customers expect:\n\n- in-product analytics + AI features, but\n- compliance teams that won't approve incumbent BI procurement, and\n- regulators that want evidence of *which AI tool read what customer data, when, under what consent*.\n\nThis SDK gives you the runtime primitives. Three lines of code = a hash-chained, vault-contracted, ed25519-signable audit stream that an external auditor can replay.\n\nTypeScript-first. Dual ESM/CJS. Zero runtime dependencies. Node 20+.\n\n---\n\n## Install\n\n```bash\nnpm install kinetic-gain-embedded\n```\n\n[![npm](https://img.shields.io/npm/v/kinetic-gain-embedded.svg)](https://www.npmjs.com/package/kinetic-gain-embedded) · Apache-2.0 · TypeScript dual ESM/CJS · zero runtime deps · Node 20+\n\n## Five-minute integration\n\n```ts\nimport {\n  AuditStream,\n  applyVaultContract,\n  NdjsonFileSink,\n  parseDecisionCard\n} from \"kinetic-gain-embedded\";\n\n// 1. Load the buyer's Decision Card (their signed data-handling rules)\nconst card = parseDecisionCard(JSON.parse(decisionCardJson));\n\n// 2. Set up the audit stream\nconst audit = new AuditStream({\n  source: \"my-saas-prod\",\n  decisionCardRef: card.canonical_url,\n  sink: new NdjsonFileSink(\"/var/log/audit.ndjson\")\n});\n\n// 3. On every customer-data touch:\nconst { payload, redactionApplied } = applyVaultContract(customerRecord, card);\n//   payload is tokenized — hand IT to the AI tool, not the raw record\n//   redactionApplied is the list of redactions you record on the audit event\n\nawait audit.emit({\n  kind: \"ai.chat.completion\",\n  redaction_applied: redactionApplied,\n  session_id: req.sessionId\n});\n```\n\nThat's it. Every emit:\n\n- assigns a UUID v7 `event_id` (time-ordered)\n- chains the new event to the previous via `prev_hash` (genesis = 64 zeros)\n- computes `hash = sha256(canonical_json(event - {hash, signature}))`\n- optionally ed25519-signs the same canonical body\n- writes through the configured sink (NDJSON, HTTP, in-memory, or your own)\n\n## What's in the box\n\n| Module | Purpose |\n| --- | --- |\n| `AuditStream` | Hash-chained event emitter |\n| `applyVaultContract` | Tokenize / mask / hash / drop fields per the Decision Card |\n| `applyVaultContractWith` | Same, with an injectable tokenizer (Skyflow / Privacera / self-hosted KMS) |\n| `parseDecisionCard` / `fetchDecisionCard` | Load + validate a Decision Card |\n| `createEd25519Signer` / `verifyEd25519Signature` | Sign + verify events with ed25519 (no external deps) |\n| `verifyChain` | Walk a stream + return the first hash-chain break, or `ok` |\n| `InMemorySink` / `NdjsonFileSink` / `HttpSink` / `TeeSink` | Reference sinks |\n| `canonicalize` / `canonicalHash` / `sha256Hex` | The exact canonical-JSON hashing every other Suite tool uses |\n| `uuidv7` | Time-ordered UUID v7 generator (used for `event_id` by default) |\n\n## Why this exists\n\nA SaaS embedder wiring in AI features (chat, summarization, RAG retrieval) faces three independent problems:\n\n1. **Show your customers which AI tool read what, when, under what consent** — without a hash-chained ledger, every claim is unverifiable.\n2. **Don't let the AI tool see raw customer PII/PHI/SPI** — without a runtime vault contract layer, the engineering team is one prompt-injection away from a CloudWatch log full of regulated data.\n3. **Make the audit trail re-playable by an auditor** — without canonical hashing + ed25519 signing, a clever insider can rewrite history.\n\nThis SDK is the embedder's runtime side of the [Kinetic Gain Protocol Suite](https://suite.kineticgain.com). It implements the open Suite specs (audit-stream, Decision Card, vault contract) as a production npm package.\n\nThe Decision Card is *issued by the buyer*. The SDK *enforces it on the embedder's side*. The audit stream is *replayable by the auditor*. That triangle is the whole product.\n\n## Vault contract field paths\n\nField paths are dot-separated, index-free:\n\n```ts\n{ field: \"customer.email\",          action: \"mask\"     }   // customer.email\n{ field: \"customer.ssn\",            action: \"hash\"     }   // customer.ssn\n{ field: \"order.lineItems.sku\",     action: \"tokenize\" }   // every lineItem's sku\n{ field: \"patient.identifier\",      action: \"tokenize\" }   // FHIR Patient.identifier\n{ field: \"candidate.demographics\",  action: \"drop\"     }   // remove entirely\n```\n\nFour actions:\n\n| Action | What it does | When to use |\n| --- | --- | --- |\n| `tokenize` | Replace with a deterministic opaque token (`tok_\u003chex\u003e`) | Names, identifiers, free-text fields the AI tool needs *correlation on* but not the value |\n| `mask` | Reveal only the first 2 + last 2 chars (`ja***om`) | Emails, phone numbers — when the AI tool needs *shape* but not the value |\n| `hash` | Replace with `hash_\u003chex\u003e` digest | SSNs, account numbers — when even the shape leaks |\n| `drop` | Remove the field entirely | High-sensitivity fields the AI tool should never see |\n\nThe default tokenizer is deterministic SHA-256-based, which works for test/dev and vault-less integrations. For production with unlinkability guarantees, inject your own tokenizer via `applyVaultContractWith` (Skyflow, Privacera, or your own KMS).\n\n## Hash chain invariants\n\nEvery event satisfies:\n\n```\nprev_hash := previous event's hash (or 64 zeros for the genesis)\nhash      := sha256(canonical_json(event minus hash + signature))\nsignature := optional ed25519 over the same canonical body\n```\n\n`canonical_json`: object keys sorted lexicographically, no whitespace, UTF-8. This canonicalization is byte-for-byte identical across every tool in the Suite — that's how a stream emitted by this SDK can be replayed by an auditor running a Python or Go verifier from a different vertical.\n\nUse `verifyChain(events)` to walk a stream and return the first break:\n\n```ts\nimport { verifyChain } from \"kinetic-gain-embedded\";\n\nconst verdict = verifyChain(events);\nif (!verdict.ok) {\n  console.error(`Chain break at event ${verdict.firstBreakAt}: ${verdict.reason}`);\n}\n```\n\n## Examples\n\n- [`examples/standalone/demo.mjs`](examples/standalone/demo.mjs) — End-to-end demo: vault → 3 audit events → chain verify\n- [`examples/express-middleware/middleware.mjs`](examples/express-middleware/middleware.mjs) — Drop-in Express middleware\n\n## Sinks: bring your own, or use ours\n\nThe shipped sinks (`InMemorySink`, `NdjsonFileSink`, `HttpSink`, `TeeSink`) are reference implementations. Production embedders typically write their own sink that pushes into their existing observability pipeline (Kafka, Kinesis, Loki, OpenTelemetry, a managed log service).\n\nA sink is one method:\n\n```ts\ninterface AuditSink {\n  write(event: AuditEvent): void | Promise\u003cvoid\u003e;\n  flush?(): void | Promise\u003cvoid\u003e;\n}\n```\n\nThat's the whole contract.\n\n## Composes with\n\n- [Kinetic Gain Protocol Suite](https://suite.kineticgain.com) — the umbrella\n- [`ai-procurement-decision-spec`](https://github.com/mizcausevic-dev/ai-procurement-decision-spec) — the Decision Card v0.3 spec this SDK enforces\n- [`fhir-resource-access-audit-reference`](https://github.com/mizcausevic-dev/fhir-resource-access-audit-reference) — HealthTech-specific end-to-end reference using a sibling vault contract\n- The Suite's 8 vertical 6-packs (HealthTech, EdTech, PropTech, InsurTech, HR Tech, FinTech, GovTech, LegalTech) — every audit-stream spec consumed by this SDK\n\n## Sales-enablement — Procurement Packet Starter\n\nWhen your enterprise customer's security team asks for a \"procurement packet\" or \"security review packet\" before they'll go to PoC, [`docs/sales/PROCUREMENT-PACKET.md`](./docs/sales/PROCUREMENT-PACKET.md) is a fill-in template you adapt and send.\n\nIt is **KGE-enabled**: §8 of the packet contains four verifiable claims you can make about your trust boundary precisely *because* KGE backs them (hash-chained audit, vault contract tokenization, ed25519-signable events, customer-defined Decision Card). Your customer can verify each claim independently from the npm package — no proprietary tooling, no SaaS dependency.\n\nThe packet maps to SIG-Lite, CAIQ, VSA Core, and custom AI security questionnaires (cross-reference table in §15). It is **scaffolding for human use, not a SOC 2 substitute, not legal advice** — fill in honestly, have counsel review, send. Honest framing for pre-SOC-2 vendors included verbatim in the template intro.\n\nCompanion buyer-side templates (the inverse — your customer uses these to evaluate vendors like you): the [Kinetic Gain Trust Pack](https://kineticgain.com/trust/) — 8 browser-only tools including AI System Card Builder, AI Vendor Intake Form, and Vendor AI Disclosure Review. Pointing customers at those tools builds trust by handing them the evaluation framework.\n\n## Compliance posture\n\nThis SDK is **audit-stream scaffolding**. Producing a verified hash-chained stream + applying a vault contract gives you *evidence artifacts* an auditor can replay — it does not establish HIPAA / FERPA / SOC 2 / GDPR / ISO 27001 / NIST AI RMF / EU AI Act / ISO 42001 compliance. Compliance posture depends on the embedder's full control environment, executed business associate / data processing agreements, and the appropriate external attestation for each regime.\n\nPer the Kinetic Gain standing public-language guardrail: *readiness · evidence · posture · controls · scaffolding* — never \"compliant\" / \"certified\" without an external attestation specific to each regime.\n\n## Publishing\n\nThis package is **npm-publish-ready**. The `.github/workflows/npm-publish.yml` workflow auto-publishes to npm on every `v*` tag push, with npm provenance attestation enabled (links the published artifact to the exact commit + workflow run).\n\nTo publish:\n\n1. **One-time setup:** add an npm \"Automation\" type access token as `NPM_TOKEN` in the repo's GitHub Actions secrets (Settings → Secrets and variables → Actions → New repository secret). Automation tokens bypass 2FA at publish time, which is what `--provenance` requires.\n2. **Bump version** in `package.json` (e.g. `0.1.0` → `0.1.1` for a patch release).\n3. **Tag + push:** `git tag v0.1.1 \u0026\u0026 git push origin v0.1.1`.\n4. The workflow runs: typecheck → tests → build → ESM/CJS smoke → `npm pack --dry-run` preview → `npm publish --access public --provenance`.\n\nBefore publishing, the local `prepublishOnly` script (in `package.json`) re-runs clean + build + test as a final pre-flight gate — both locally (if you ever `npm publish` from your machine) and in the workflow.\n\n## License\n\n[Apache-2.0](LICENSE). Pick it up, embed it, ship it.\n\n## Status\n\n- v0.1 (Phase 1) — production SDK for TypeScript + Node. 42 tests across 4 suites. Dual ESM/CJS output. Zero runtime deps. **npm-publish-ready** (workflow shipped; awaiting NPM_TOKEN secret).\n- v0.2+ (Phase 2 candidates) — Python SDK · OpenTelemetry sink · Decision Card CRDT for multi-party signing\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmizcausevic-dev%2Fkinetic-gain-embedded","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmizcausevic-dev%2Fkinetic-gain-embedded","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmizcausevic-dev%2Fkinetic-gain-embedded/lists"}