kaiwen-core-js 0.1.0

package/dist/sync/network.d.ts

@@ -0,0 +1,8 @@
+import { KWRecord } from "../models/record";
+export declare class KWNetwork {
+    private apiUrl;
+    private apiKey;
+    constructor(apiUrl: string, apiKey: string);
+    push(records: KWRecord[]): Promise<number>;
+    pull(appId: string, since: number): Promise<any[]>;
+}

package/dist/sync/network.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KWNetwork = void 0;
+const exceptions_1 = require("../core/exceptions");
+const logger_1 = require("../utils/logger");
+class KWNetwork {
+    constructor(apiUrl, apiKey) {
+        this.apiUrl = apiUrl;
+        this.apiKey = apiKey;
+    }
+    async push(records) {
+        logger_1.KWLogger.info("Network push initiated.");
+        const res = await fetch(`${this.apiUrl}/sync`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", "x-api-key": this.apiKey },
+            body: JSON.stringify(records)
+        });
+        if (!res.ok)
+            throw new exceptions_1.SyncFailedException("Network push failed");
+        const data = await res.json();
+        return data.synced || 0;
+    }
+    async pull(appId, since) {
+        logger_1.KWLogger.info(`Network pull initiated since ${since}.`);
+        const res = await fetch(`${this.apiUrl}/fetch?app_id=${appId}&since=${since}`, {
+            headers: { "x-api-key": this.apiKey }
+        });
+        if (!res.ok)
+            throw new exceptions_1.SyncFailedException("Network pull failed");
+        return await res.json();
+    }
+}
+exports.KWNetwork = KWNetwork;

package/dist/utils/logger.d.ts

@@ -0,0 +1,4 @@
+export declare class KWLogger {
+    static info(message: string): void;
+    static error(message: string, error?: any): void;
+}

package/dist/utils/logger.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KWLogger = void 0;
+class KWLogger {
+    static info(message) {
+        console.log(`[KWCore] INFO: ${message}`);
+    }
+    static error(message, error) {
+        console.error(`[KWCore] ERROR: ${message}`, error);
+    }
+}
+exports.KWLogger = KWLogger;

package/dist/utils/tracer.d.ts

@@ -0,0 +1,5 @@
+import { KWTracerContext } from "../models/tracer";
+export declare class KWTracer {
+    static traceStart(operation: string): KWTracerContext;
+    static traceEnd(ctx: KWTracerContext, operation: string): void;
+}

package/dist/utils/tracer.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KWTracer = void 0;
+const tracer_1 = require("../models/tracer");
+const logger_1 = require("./logger");
+class KWTracer {
+    static traceStart(operation) {
+        const ctx = new tracer_1.KWTracerContext();
+        logger_1.KWLogger.info(`[Trace ${ctx.traceId}] Started: ${operation}`);
+        return ctx;
+    }
+    static traceEnd(ctx, operation) {
+        logger_1.KWLogger.info(`[Trace ${ctx.traceId}] Ended: ${operation}`);
+    }
+}
+exports.KWTracer = KWTracer;

package/dist/utils/validator.d.ts

@@ -0,0 +1,3 @@
+export declare class KWValidator {
+    static validatePayload(payload: any): void;
+}

package/dist/utils/validator.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KWValidator = void 0;
+class KWValidator {
+    static validatePayload(payload) {
+        if (payload === undefined || payload === null) {
+            throw new Error("Payload cannot be null or undefined");
+        }
+    }
+}
+exports.KWValidator = KWValidator;

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "kaiwen-core-js",
+  "version": "0.1.0",
+  "description": "Kaiwen Cloud Ecosystem SDK for TypeScript & JavaScript environments.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "kaiwen",
+    "e2ee",
+    "crdt",
+    "offline-first"
+  ],
+  "author": "Kerem Keskinoğlu",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/src/app.ts

@@ -0,0 +1,60 @@
+import { KWVault } from "./storage/vault";
+import { KWCryptoEngine } from "./crypto/engine";
+import { KWMigrationEngine } from "./models/migration";
+import { KWAssetEngine } from "./storage/assets";
+import { KWPipeline } from "./core/pipeline";
+import { IKWStorage, MemoryStorage } from "./storage/db";
+import { KWRecord } from "./models/record";
+import { KWValidator } from "./utils/validator";
+
+export class KaiwenApp {
+  public vault: KWVault;
+  public assetEngine: KWAssetEngine;
+  public pipeline: KWPipeline;
+  public migration: KWMigrationEngine;
+
+  constructor(
+    private appId: string, 
+    apiUrl: string, 
+    apiKey: string, 
+    private storage: IKWStorage = new MemoryStorage()
+  ) {
+    this.vault = new KWVault();
+    this.assetEngine = new KWAssetEngine(this.vault);
+    this.pipeline = new KWPipeline(this.vault, storage, apiUrl, apiKey);
+    this.migration = new KWMigrationEngine(storage, 1);
+  }
+
+  async login(mnemonic: string): Promise<void> {
+    await this.vault.login(mnemonic, this.appId);
+    await this.migration.migrateAll();
+  }
+
+  async saveRecord(userId: string, payload: any): Promise<KWRecord> {
+    KWValidator.validatePayload(payload);
+    
+    const encrypted = await KWCryptoEngine.encryptPayload(payload, this.vault.getKey());
+    const generateId = () => typeof crypto !== 'undefined' && crypto.randomUUID ? crypto.randomUUID() : Math.random().toString(36).substring(2);
+    
+    const record = new KWRecord(
+      generateId(), this.appId, userId, encrypted, Date.now() / 1000, 0, 1, 1
+    );
+
+    await this.storage.saveRecord(record.id, record);
+    return record;
+  }
+
+  async getDecryptedRecord(id: string): Promise<any> {
+    const record = await this.storage.getRecord(id);
+    if (!record) return null;
+    return await KWCryptoEngine.decryptPayload(record.payload, this.vault.getKey());
+  }
+
+  async pushSync(): Promise<number> { 
+    return await this.pipeline.pushSync(this.appId); 
+  }
+  
+  async pullSync(): Promise<number> { 
+    return await this.pipeline.pullSync(this.appId); 
+  }
+}

package/src/core/exceptions.ts

@@ -0,0 +1,20 @@
+export class KWException extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "KWException";
+  }
+}
+
+export class VaultLockedException extends KWException {
+  constructor() {
+    super("Vault is locked. User not authenticated.");
+    this.name = "VaultLockedException";
+  }
+}
+
+export class SyncFailedException extends KWException {
+  constructor(message: string) {
+    super(`Sync failed: ${message}`);
+    this.name = "SyncFailedException";
+  }
+}

package/src/core/pipeline.ts

@@ -0,0 +1,57 @@
+import { KWVault } from "../storage/vault";
+import { KWNetwork } from "../sync/network";
+import { IKWStorage } from "../storage/db";
+import { KWRecord } from "../models/record";
+import { KWLogger } from "../utils/logger";
+
+export class KWPipeline {
+  private network: KWNetwork;
+
+  constructor(
+    private vault: KWVault,
+    private storage: IKWStorage,
+    apiUrl: string,
+    apiKey: string
+  ) {
+    this.network = new KWNetwork(apiUrl, apiKey);
+  }
+
+  async pushSync(appId: string): Promise<number> {
+    KWLogger.info("Starting pushSync...");
+    const allRecords = await this.storage.getAllRecords();
+    const pending = allRecords.filter(r => r.is_synced === 0);
+    if (pending.length === 0) return 0;
+
+    const syncedCount = await this.network.push(pending);
+    
+    for (const r of pending) {
+      r.is_synced = 1;
+      await this.storage.saveRecord(r.id, r);
+    }
+    return syncedCount;
+  }
+
+  async pullSync(appId: string): Promise<number> {
+    KWLogger.info("Starting pullSync...");
+    const allRecords = await this.storage.getAllRecords();
+    let latestUpdate = 0;
+    allRecords.forEach(r => {
+      if (r.updated_at > latestUpdate) latestUpdate = r.updated_at;
+    });
+
+    const incomingRecords = await this.network.pull(appId, latestUpdate);
+
+    let mergedCount = 0;
+    for (const remoteObj of incomingRecords) {
+      const remote = KWRecord.fromObject(remoteObj);
+      const local = await this.storage.getRecord(remote.id);
+      
+      if (!local || remote.logical_clock > local.logical_clock) {
+        remote.is_synced = 1;
+        await this.storage.saveRecord(remote.id, remote);
+        mergedCount++;
+      }
+    }
+    return mergedCount;
+  }
+}

package/src/crypto/engine.ts

@@ -0,0 +1,105 @@
+export class KWCryptoEngine {
+  private static getSubtleCrypto(): SubtleCrypto {
+    if (typeof crypto !== "undefined" && crypto.subtle) {
+      return crypto.subtle; // Modern Browsers & Deno
+    }
+    // Node.js fallback or RN polyfill
+    if (typeof globalThis !== "undefined" && (globalThis as any).crypto && (globalThis as any).crypto.subtle) {
+      return (globalThis as any).crypto.subtle;
+    }
+    throw new Error("Web Crypto API (crypto.subtle) is not available in this environment.");
+  }
+
+  private static bufferToBase64(buffer: Uint8Array): string {
+    let binary = '';
+    const len = buffer.byteLength;
+    for (let i = 0; i < len; i++) {
+      binary += String.fromCharCode(buffer[i]);
+    }
+    return btoa(binary);
+  }
+
+  private static base64ToBuffer(base64: string): Uint8Array {
+    const binary = atob(base64);
+    const len = binary.length;
+    const bytes = new Uint8Array(len);
+    for (let i = 0; i < len; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+  }
+
+  static async deriveAppKeyFromMnemonic(mnemonic: string, appId: string): Promise<CryptoKey> {
+    const subtle = this.getSubtleCrypto();
+    const encoder = new TextEncoder();
+    
+    // 1. PBKDF2 Master Key Derivation (matches Python)
+    const pbkdf2KeyMaterial = await subtle.importKey(
+      "raw", encoder.encode(mnemonic), { name: "PBKDF2" }, false, ["deriveBits"]
+    );
+    
+    const pbkdf2Salt = encoder.encode("visuality_global_salt");
+    const masterKeyRaw = await subtle.deriveBits(
+      { name: "PBKDF2", salt: pbkdf2Salt, iterations: 200000, hash: "SHA-256" },
+      pbkdf2KeyMaterial,
+      256
+    );
+
+    // 2. HKDF App Key Derivation (matches Python)
+    const hkdfKeyMaterial = await subtle.importKey(
+      "raw", masterKeyRaw, { name: "HKDF" }, false, ["deriveKey"]
+    );
+
+    return await subtle.deriveKey(
+      { name: "HKDF", hash: "SHA-256", salt: new Uint8Array(32), info: encoder.encode(appId) },
+      hkdfKeyMaterial,
+      { name: "AES-GCM", length: 256 },
+      false, 
+      ["encrypt", "decrypt"]
+    );
+  }
+
+  static async encryptPayload(payload: any, appKey: CryptoKey): Promise<string> {
+    const encoder = new TextEncoder();
+    const data = encoder.encode(JSON.stringify(payload));
+    return this.encryptAssetChunk(data, appKey);
+  }
+
+  static async decryptPayload(encryptedPayloadBase64: string, appKey: CryptoKey): Promise<any> {
+    const decoder = new TextDecoder();
+    const decryptedBuffer = await this.decryptAssetChunk(encryptedPayloadBase64, appKey);
+    return JSON.parse(decoder.decode(decryptedBuffer));
+  }
+
+  // Raw Uint8Array Encryption for Asset Engine
+  static async encryptAssetChunk(data: Uint8Array, appKey: CryptoKey): Promise<string> {
+    const subtle = this.getSubtleCrypto();
+    
+    const iv = new Uint8Array(12);
+    if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+      crypto.getRandomValues(iv);
+    } else {
+      for (let i=0; i<12; i++) iv[i] = Math.floor(Math.random() * 256);
+    }
+    
+    const encryptedBuffer = await subtle.encrypt({ name: "AES-GCM", iv: iv }, appKey, data as any);
+    
+    const encryptedArray = new Uint8Array(encryptedBuffer);
+    const combined = new Uint8Array(iv.length + encryptedArray.length);
+    combined.set(iv, 0);
+    combined.set(encryptedArray, iv.length);
+    
+    return this.bufferToBase64(combined);
+  }
+
+  static async decryptAssetChunk(encryptedBase64: string, appKey: CryptoKey): Promise<Uint8Array> {
+    const subtle = this.getSubtleCrypto();
+    const combined = this.base64ToBuffer(encryptedBase64);
+    
+    const iv = combined.slice(0, 12);
+    const ciphertext = combined.slice(12);
+    
+    const decryptedBuffer = await subtle.decrypt({ name: "AES-GCM", iv: iv }, appKey, ciphertext as any);
+    return new Uint8Array(decryptedBuffer);
+  }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { KaiwenApp } from "./app";
+export { IKWStorage, MemoryStorage } from "./storage/db";
+export { KWRecord } from "./models/record";
+export { KWVault } from "./storage/vault";
+export { KWAssetEngine, KWAssetManifest } from "./storage/assets";
+export { KWMigrationEngine } from "./models/migration";
+export { KWCryptoEngine } from "./crypto/engine";
+export { KWPipeline } from "./core/pipeline";
+export { KWSyncStatus, KWRecordType } from "./models/enums";
+export { KWException, VaultLockedException, SyncFailedException } from "./core/exceptions";
+export { KWLogger } from "./utils/logger";
+export { KWTracer } from "./utils/tracer";
+export { KWValidator } from "./utils/validator";
+export { KWNetwork } from "./sync/network";

package/src/models/enums.ts

@@ -0,0 +1,9 @@
+export enum KWSyncStatus {
+  PENDING = 0,
+  SYNCED = 1
+}
+
+export enum KWRecordType {
+  TEXT = "text",
+  ASSET = "asset"
+}

package/src/models/migration.ts

@@ -0,0 +1,18 @@
+import { IKWStorage } from "../storage/db";
+
+export class KWMigrationEngine {
+  constructor(private storage: IKWStorage, private currentSchemaVersion: number) {}
+
+  async migrateAll(): Promise<void> {
+    const records = await this.storage.getAllRecords();
+    for (const record of records) {
+      if (record.schema_version < this.currentSchemaVersion) {
+        record.schema_version = this.currentSchemaVersion;
+        record.updated_at = Date.now() / 1000;
+        record.logical_clock += 1;
+        record.is_synced = 0;
+        await this.storage.saveRecord(record.id, record);
+      }
+    }
+  }
+}

package/src/models/record.ts

@@ -0,0 +1,19 @@
+export class KWRecord {
+  constructor(
+    public id: string,
+    public app_id: string,
+    public user_id: string,
+    public payload: string,
+    public updated_at: number,
+    public is_synced: number = 0,
+    public schema_version: number = 1,
+    public logical_clock: number = 1
+  ) {}
+
+  static fromObject(obj: any): KWRecord {
+    return new KWRecord(
+      obj.id, obj.app_id, obj.user_id, obj.payload, 
+      obj.updated_at, obj.is_synced, obj.schema_version, obj.logical_clock
+    );
+  }
+}

package/src/models/tracer.ts

@@ -0,0 +1,6 @@
+export class KWTracerContext {
+  public traceId: string;
+  constructor() {
+    this.traceId = typeof crypto !== 'undefined' && crypto.randomUUID ? crypto.randomUUID() : Math.random().toString(36).substring(2);
+  }
+}

package/src/storage/assets.ts

@@ -0,0 +1,63 @@
+import { KWCryptoEngine } from "../crypto/engine";
+import { KWVault } from "./vault";
+
+export interface KWAssetManifest {
+  assetId: string;
+  totalChunks: number;
+  mimeType: string;
+  size: number;
+}
+
+export class KWAssetEngine {
+  private readonly CHUNK_SIZE = 1024 * 1024; // 1MB
+
+  constructor(private vault: KWVault) {}
+
+  async encryptAsset(fileBuffer: Uint8Array, mimeType: string): Promise<{ manifest: KWAssetManifest, encryptedChunks: string[] }> {
+    if (!this.vault.isUnlocked()) throw new Error("Vault locked");
+    const key = this.vault.getKey();
+    const chunks: string[] = [];
+    
+    const generateId = () => typeof crypto !== 'undefined' && crypto.randomUUID ? crypto.randomUUID() : Math.random().toString(36).substring(2);
+    const assetId = generateId();
+
+    for (let i = 0; i < fileBuffer.length; i += this.CHUNK_SIZE) {
+      const chunk = fileBuffer.slice(i, i + this.CHUNK_SIZE);
+      const encryptedChunk = await KWCryptoEngine.encryptAssetChunk(chunk, key);
+      chunks.push(encryptedChunk);
+    }
+
+    return {
+      manifest: {
+        assetId,
+        totalChunks: chunks.length,
+        mimeType,
+        size: fileBuffer.length
+      },
+      encryptedChunks: chunks
+    };
+  }
+
+  async decryptAsset(encryptedChunks: string[], mimeType: string): Promise<Uint8Array> {
+    if (!this.vault.isUnlocked()) throw new Error("Vault locked");
+    const key = this.vault.getKey();
+    
+    let totalLength = 0;
+    const decryptedChunks: Uint8Array[] = [];
+
+    for (const chunk64 of encryptedChunks) {
+      const decrypted = await KWCryptoEngine.decryptAssetChunk(chunk64, key);
+      decryptedChunks.push(decrypted);
+      totalLength += decrypted.length;
+    }
+
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of decryptedChunks) {
+      result.set(chunk, offset);
+      offset += chunk.length;
+    }
+
+    return result;
+  }
+}

package/src/storage/db.ts

@@ -0,0 +1,24 @@
+import { KWRecord } from "../models/record";
+
+export interface IKWStorage {
+  saveRecord(id: string, data: KWRecord): Promise<boolean>;
+  getRecord(id: string): Promise<KWRecord | null>;
+  getAllRecords(): Promise<KWRecord[]>;
+}
+
+export class MemoryStorage implements IKWStorage {
+  private store: Map<string, KWRecord> = new Map();
+
+  async saveRecord(id: string, data: KWRecord): Promise<boolean> {
+    this.store.set(id, data);
+    return true;
+  }
+
+  async getRecord(id: string): Promise<KWRecord | null> {
+    return this.store.get(id) || null;
+  }
+
+  async getAllRecords(): Promise<KWRecord[]> {
+    return Array.from(this.store.values());
+  }
+}

package/src/storage/vault.ts

@@ -0,0 +1,23 @@
+import { KWCryptoEngine } from "../crypto/engine";
+import { VaultLockedException } from "../core/exceptions";
+
+export class KWVault {
+  private appKey: CryptoKey | null = null;
+  
+  async login(mnemonic: string, appId: string): Promise<void> {
+    this.appKey = await KWCryptoEngine.deriveAppKeyFromMnemonic(mnemonic, appId);
+  }
+
+  isUnlocked(): boolean {
+    return this.appKey !== null;
+  }
+
+  getKey(): CryptoKey {
+    if (!this.appKey) throw new VaultLockedException();
+    return this.appKey;
+  }
+
+  lock(): void {
+    this.appKey = null;
+  }
+}

package/src/sync/network.ts

@@ -0,0 +1,28 @@
+import { KWRecord } from "../models/record";
+import { SyncFailedException } from "../core/exceptions";
+import { KWLogger } from "../utils/logger";
+
+export class KWNetwork {
+  constructor(private apiUrl: string, private apiKey: string) {}
+
+  async push(records: KWRecord[]): Promise<number> {
+    KWLogger.info("Network push initiated.");
+    const res = await fetch(`${this.apiUrl}/sync`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "x-api-key": this.apiKey },
+      body: JSON.stringify(records)
+    });
+    if (!res.ok) throw new SyncFailedException("Network push failed");
+    const data = await res.json();
+    return data.synced || 0;
+  }
+
+  async pull(appId: string, since: number): Promise<any[]> {
+    KWLogger.info(`Network pull initiated since ${since}.`);
+    const res = await fetch(`${this.apiUrl}/fetch?app_id=${appId}&since=${since}`, {
+      headers: { "x-api-key": this.apiKey }
+    });
+    if (!res.ok) throw new SyncFailedException("Network pull failed");
+    return await res.json();
+  }
+}

package/src/utils/logger.ts

@@ -0,0 +1,8 @@
+export class KWLogger {
+  static info(message: string) {
+    console.log(`[KWCore] INFO: ${message}`);
+  }
+  static error(message: string, error?: any) {
+    console.error(`[KWCore] ERROR: ${message}`, error);
+  }
+}

package/src/utils/tracer.ts

@@ -0,0 +1,13 @@
+import { KWTracerContext } from "../models/tracer";
+import { KWLogger } from "./logger";
+
+export class KWTracer {
+  static traceStart(operation: string): KWTracerContext {
+    const ctx = new KWTracerContext();
+    KWLogger.info(`[Trace ${ctx.traceId}] Started: ${operation}`);
+    return ctx;
+  }
+  static traceEnd(ctx: KWTracerContext, operation: string) {
+    KWLogger.info(`[Trace ${ctx.traceId}] Ended: ${operation}`);
+  }
+}

package/src/utils/validator.ts

@@ -0,0 +1,7 @@
+export class KWValidator {
+  static validatePayload(payload: any) {
+    if (payload === undefined || payload === null) {
+      throw new Error("Payload cannot be null or undefined");
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "declaration": true,
+    "outDir": "./dist",
+    "strict": true,
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"]
+}