mizcausevic-dev/kinetic-gain-embedded

Purpose and principal workflow

kinetic-gain-embedded is a TypeScript SDK for SaaS applications that need to enforce buyer-defined data-handling rules and emit verifiable audit events around customer-data use. The main workflow is initiated by an embedding SaaS application when its code is about to pass customer data to an AI tool: it loads the buyer’s Decision Card, applies its vault rules to the payload, and emits an event recording the applicable redactions. The SDK provides primitives for producing, storing, and verifying the audit trail; the embedder supplies the application workflow and chooses the event sink.

Components

SDK entry and policy loading

• Public SDK surface — src/index.ts: Exports the supported runtime functions, types, and sink implementations to package consumers.

• Decision Card loader and validator — src/decision-card.ts: Parses and structurally checks buyer-provided cards, or fetches a card from a URL using fetch.

Data protection and audit events

• Vault contract enforcement — src/vault.ts: Deep-clones payloads and applies the card’s field rules—tokenize, mask, hash, or drop—returning both transformed data and a redaction list; also supports an injected tokenizer.

• Audit stream and chain verification — src/audit-stream.ts: Builds events with timestamps, IDs, card reference, and prior-event hash; computes each event hash, optionally signs it, writes it to the configured sink, and exposes chain verification.

Cryptographic and event primitives

• Canonical serialization and hashing — src/canonical.ts: Implements sorted-key canonical JSON, SHA-256 hashing, and the genesis prior-hash constant used by event creation and verification.

• Ed25519 signing and verification — src/sign.ts: Creates signers from PEM private keys and verifies event signatures against PEM public keys.

• Time-ordered event IDs — src/uuid.ts: Generates UUID v7 values, used by default for audit event IDs.

Event destinations

• Reference audit sinks — src/sinks.ts: Implements in-memory, NDJSON-file, HTTP POST, and tee sinks; production consumers can provide their own sink through the same write/optional-flush contract.

External participants

• Embedding SaaS application — null: The consumer application initiates policy loading, data protection, and event emission around its customer-data workflow.

• Buyer / Decision Card issuer — null: Supplies the card that states the authorization and vault rules the SDK applies.

• Auditor or downstream verifier — null: Replays exported events and can check the hash chain and, when it has the public key, event signatures.

Relationships

• Embedding SaaS application -> Public SDK surface: Imports the SDK’s exported runtime API; the package entry point re-exports the implementation.

• Buyer / Decision Card issuer -> Embedding SaaS application: Supplies the buyer-issued Decision Card used by the embedding application.

• Embedding SaaS application -> Decision Card loader and validator: Calls parse on supplied card data or fetches a card from its URL.

• Decision Card loader and validator -> Embedding SaaS application: Returns a structurally checked card; the loader does not enforce the card’s full JSON Schema.

• Embedding SaaS application -> Vault contract enforcement: Passes a payload and card or contract for field-level transformation before the AI tool receives the payload.

• Vault contract enforcement -> Embedding SaaS application: Returns the transformed payload and redaction list for the caller to use and record.

• Embedding SaaS application -> Audit stream and chain verification: Calls emit with event details, including redactions when applicable.

• Audit stream and chain verification -> Time-ordered event IDs: Uses UUID v7 as the default event-ID generator.

• Audit stream and chain verification -> Canonical serialization and hashing: Hashes canonical event bodies and invokes the same chain logic when verifying events.

• Audit stream and chain verification -> Ed25519 signing and verification: Calls the configured signer to sign the canonical event body when signing is enabled.

• Audit stream and chain verification -> Reference audit sinks: Writes each completed event to the configured sink; the sink may instead be consumer-provided.

• Reference audit sinks -> Auditor or downstream verifier: Can deliver events via HTTP or persist them in a file for later replay; actual downstream delivery depends on the selected sink and consumer setup.

• Auditor or downstream verifier -> Public SDK surface: A consumer can call the exported chain verifier and signature verifier when replaying events.

Coverage limits

Source excerpts establish the core SDK calls and data flow, but do not show the embedder’s application code, its chosen sink configuration, or how a buyer distributes cards and signing keys. The README documents additional use cases and production sink options; those deployment-specific integrations are not established as repository implementations.