@kojinx/collab-crypto 0.0.2

package/lib/models/crypto.models.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Encrypted message payload format transmitted over HTTP/SSE and stored in database.
+ */
+export interface EncryptedMessagePayload {
+    /** Base64-encoded AES-256-GCM ciphertext */
+    ciphertext: string;
+    /** Base64-encoded 12-byte (96-bit) Initialization Vector (Nonce) */
+    nonce: string;
+    /** UUID of the Session Key used to encrypt this message */
+    sessionKeyId: string;
+    /** Generation number of the Session Key (incremented during key rotation) */
+    generation: number;
+}
+/**
+ * In-memory active Session Key holding standard W3C CryptoKey.
+ */
+export interface ConversationSessionKey {
+    /** Unique UUID identifier for this session key */
+    id: string;
+    /** Conversation scope */
+    type: 'dm' | 'channel' | 'group';
+    /** Target conversation ID (recipientId for 1:1 DM, channelId for channels, groupId for groups) */
+    conversationId: string;
+    /** W3C SubtleCrypto AES-GCM 256-bit Key */
+    rawKey: CryptoKey;
+    /** Generation index (starts at 1, incremented upon rotation) */
+    generation: number;
+    /** Creation epoch timestamp in milliseconds */
+    createdAt: number;
+}
+/**
+ * Wire-format for storing and synchronizing encrypted session keys across members.
+ */
+export interface SessionKeyExchangePayload {
+    sessionKeyId: string;
+    conversationType: 'dm' | 'channel' | 'group';
+    conversationId: string;
+    generation: number;
+    /** Map of UserId -> RSA-OAEP Base64 Encrypted AES Raw Key */
+    memberPayloads: Record<string, string>;
+    createdAt?: string;
+    createdBy?: string;
+}
+/**
+ * Member public key entry returned by public key directory.
+ */
+export interface MemberPublicKey {
+    userId: string;
+    publicKey: string;
+}
+/**
+ * Safety Number verification model (Signal-style).
+ */
+export interface SafetyNumber {
+    /** Raw 60-character hexadecimal digest */
+    raw: string;
+    /** Standardized formatted display in 6 blocks of 5 decimal digits */
+    formatted: string;
+    /** Fingerprint component for the local user */
+    localFingerprint: string;
+    /** Fingerprint component for the remote user */
+    remoteFingerprint: string;
+}
+/**
+ * Cryptography provider abstraction interface (RSA-2048 OAEP).
+ */
+export interface KojinxCryptoProvider {
+    /** Returns the base64-encoded RSA public key */
+    getPublicKey(): Promise<string>;
+    /** Asymmetrically encrypts plaintext using target base64 RSA public key */
+    encrypt(publicKeyBase64: string, plaintext: string): Promise<string>;
+    /** Asymmetrically decrypts ciphertext using local private key */
+    decrypt(ciphertextBase64: string): Promise<string>;
+}
+/**
+ * Client-agnostic fetch options.
+ */
+export interface KojinxFetchOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+/**
+ * Client-agnostic fetch response.
+ */
+export interface KojinxFetchResponse<T = any> {
+    status: number;
+    data: T;
+    headers?: Record<string, string>;
+}
+export type KojinxFetchFunction = <T = any>(url: string, options?: KojinxFetchOptions) => Promise<KojinxFetchResponse<T>>;
+/**
+ * Local storage interface for session key caching.
+ */
+export interface KojinxStorageProvider {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}

package/lib/services/e2e-chat-crypto.service.d.ts

@@ -0,0 +1,58 @@
+import { ConversationSessionKey, EncryptedMessagePayload } from '../models/crypto.models';
+import * as i0 from "@angular/core";
+/**
+ * Pure End-to-End Encryption cryptographic service.
+ * Handles AES-256-GCM message encryption/decryption and RSA key wrapping/unwrapping.
+ */
+export declare class E2EChatCryptoService {
+    private cryptoProvider;
+    /**
+     * Generates a new cryptographically secure 256-bit AES-GCM session key.
+     */
+    generateAesKey(): Promise<CryptoKey>;
+    /**
+     * Encrypts plaintext string using AES-256-GCM with a fresh 12-byte (96-bit) nonce.
+     *
+     * @param sessionKey In-memory active session key
+     * @param plaintext Plaintext message content
+     */
+    encryptMessage(sessionKey: ConversationSessionKey, plaintext: string): Promise<EncryptedMessagePayload>;
+    /**
+     * Decrypts an EncryptedMessagePayload using AES-256-GCM.
+     *
+     * @param sessionKey In-memory session key corresponding to payload.sessionKeyId
+     * @param payload Encrypted payload containing ciphertext and nonce
+     */
+    decryptMessage(sessionKey: ConversationSessionKey, payload: EncryptedMessagePayload): Promise<string>;
+    /**
+     * Exports an AES-GCM key and wraps (encrypts) it with a recipient's RSA public key.
+     *
+     * @param aesKey AES CryptoKey to wrap
+     * @param recipientPublicKey Base64-encoded recipient RSA public key
+     */
+    wrapSessionKey(aesKey: CryptoKey, recipientPublicKey: string): Promise<string>;
+    /**
+     * Unwraps (decrypts) an RSA-encrypted AES raw key and imports it back into a W3C CryptoKey.
+     *
+     * @param encryptedAesKeyBase64 RSA-encrypted AES raw key in base64 format
+     */
+    unwrapSessionKey(encryptedAesKeyBase64: string): Promise<CryptoKey>;
+    /**
+     * Exports a CryptoKey to base64 raw bytes.
+     */
+    exportRawKeyBase64(key: CryptoKey): Promise<string>;
+    /**
+     * Imports a base64 raw key string into a CryptoKey.
+     */
+    importRawKeyBase64(base64: string): Promise<CryptoKey>;
+    /**
+     * Encodes ArrayBuffer to Base64 string.
+     */
+    arrayBufferToBase64(buffer: ArrayBuffer | Uint8Array): string;
+    /**
+     * Decodes Base64 string to ArrayBuffer.
+     */
+    base64ToArrayBuffer(base64: string): ArrayBuffer;
+    static ɵfac: i0.ɵɵFactoryDeclaration<E2EChatCryptoService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<E2EChatCryptoService>;
+}

package/lib/services/session-key-manager.service.d.ts

@@ -0,0 +1,71 @@
+import { ConversationSessionKey, MemberPublicKey } from '../models/crypto.models';
+import * as i0 from "@angular/core";
+/**
+ * Manages the lifecycle, caching, negotiation, and rotation of conversation session keys.
+ */
+export declare class SessionKeyManagerService {
+    private cryptoService;
+    private httpFetch;
+    private getApiUrl;
+    private getAuthToken;
+    private storage;
+    /** Fast in-memory cache mapped by conversationId */
+    private activeKeysByConversation;
+    /** Fast in-memory cache mapped by sessionKeyId (for historic messages) */
+    private keysById;
+    /**
+     * Retrieves or creates an active session key for a 1:1 Direct Message conversation.
+     *
+     * @param localUserId Current user's ID
+     * @param remoteUserId Remote contact's ID
+     * @param remotePublicKey Base64 RSA public key of remote contact
+     * @param localPublicKey Base64 RSA public key of local user
+     */
+    getOrCreateDmSessionKey(localUserId: string, remoteUserId: string, remotePublicKey: string, localPublicKey: string): Promise<ConversationSessionKey>;
+    /**
+     * Retrieves or creates an active session key for a Native Channel or Group.
+     *
+     * @param channelId Unique channel ID
+     * @param members List of all workspace/channel members with their public keys
+     */
+    getOrCreateChannelSessionKey(channelId: string, members: MemberPublicKey[]): Promise<ConversationSessionKey>;
+    /**
+     * Retrieves a session key by its specific sessionKeyId (used for decrypting historic messages).
+     */
+    getSessionKeyById(sessionKeyId: string): Promise<ConversationSessionKey | null>;
+    /**
+     * Generates a new AES session key, wraps it for all members, and uploads to the server.
+     */
+    createAndDistributeSessionKey(params: {
+        type: 'dm' | 'channel' | 'group';
+        conversationId: string;
+        generation: number;
+        members: MemberPublicKey[];
+    }): Promise<ConversationSessionKey>;
+    /**
+     * Helper to check if a key has exceeded the 30-day rotation threshold.
+     */
+    isKeyExpired(key: ConversationSessionKey): boolean;
+    /**
+     * Builds a deterministic conversation identifier for 1:1 DMs (lexicographical sort).
+     */
+    buildDmConversationId(userIdA: string, userIdB: string): string;
+    /**
+     * Caches a session key in memory.
+     */
+    private cacheKey;
+    /**
+     * Persists an unwrapped session key to local storage for fast startup.
+     */
+    private persistKeyLocally;
+    /**
+     * Fetches latest session key from server and unwraps it locally.
+     */
+    private fetchSessionKeyFromServer;
+    /**
+     * Generates a random UUID (W3C standard or fallback).
+     */
+    private generateUuid;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SessionKeyManagerService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SessionKeyManagerService>;
+}

package/lib/tokens.d.ts

@@ -0,0 +1,24 @@
+import { InjectionToken } from '@angular/core';
+import { KojinxCryptoProvider, KojinxFetchFunction, KojinxStorageProvider } from './models/crypto.models';
+/**
+ * Injected Asymmetric Cryptography Provider (RSA-2048 OAEP).
+ * On desktop: Implemented via Tauri Rust Keyring IPC.
+ * On mobile: Implemented via SubtleCrypto + Capacitor SecureStorage.
+ */
+export declare const KOJINX_CRYPTO_PROVIDER: InjectionToken<KojinxCryptoProvider>;
+/**
+ * Injected Client-Agnostic HTTP Fetcher (bypass CORS on native).
+ */
+export declare const KOJINX_HTTP_FETCH: InjectionToken<KojinxFetchFunction>;
+/**
+ * Injected Storage Provider for local session key caching.
+ */
+export declare const KOJINX_CRYPTO_STORAGE: InjectionToken<KojinxStorageProvider>;
+/**
+ * Injected API Base URL accessor function.
+ */
+export declare const KOJINX_API_BASE_URL: InjectionToken<() => string>;
+/**
+ * Injected Auth Bearer Token accessor function.
+ */
+export declare const KOJINX_AUTH_TOKEN: InjectionToken<() => Promise<string | null>>;

package/lib/utils/safety-number.utils.d.ts

@@ -0,0 +1,30 @@
+import { SafetyNumber } from '../models/crypto.models';
+/**
+ * Computes deterministic SHA-256 safety verification numbers (Signal-style).
+ * Users can compare these 30-digit numbers out-of-band to verify end-to-end identity.
+ */
+export declare class SafetyNumberUtils {
+    /**
+     * Generates a Safety Number between two identity public keys.
+     *
+     * @param localPublicKey Base64-encoded local RSA public key
+     * @param remotePublicKey Base64-encoded remote RSA public key
+     */
+    static generate(localPublicKey: string, remotePublicKey: string): Promise<SafetyNumber>;
+    /**
+     * Hashes a single public key using SHA-256.
+     */
+    static hashPublicKey(publicKeyBase64: string): Promise<string>;
+    /**
+     * Computes SHA-256 hex string using W3C Web Crypto API.
+     */
+    private static sha256;
+    /**
+     * Converts a hexadecimal string into a deterministic 30-digit decimal string.
+     */
+    private static hexTo30Digits;
+    /**
+     * Formats a 30-digit string into 6 blocks of 5 digits separated by spaces.
+     */
+    private static formatBlocks;
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@kojinx/collab-crypto",
+  "version": "0.0.2",
+  "description": "Kojinx End-to-End Encryption Trust Module for Collaboration Hub",
+  "peerDependencies": {
+    "@angular/common": "^17.3.0",
+    "@angular/core": "^17.3.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "sideEffects": false,
+  "module": "fesm2022/kojinx-collab-crypto.mjs",
+  "typings": "index.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./index.d.ts",
+      "esm2022": "./esm2022/kojinx-collab-crypto.mjs",
+      "esm": "./esm2022/kojinx-collab-crypto.mjs",
+      "default": "./fesm2022/kojinx-collab-crypto.mjs"
+    }
+  }
+}

package/public-api.d.ts

@@ -0,0 +1,5 @@
+export * from './lib/tokens';
+export * from './lib/models/crypto.models';
+export * from './lib/utils/safety-number.utils';
+export * from './lib/services/e2e-chat-crypto.service';
+export * from './lib/services/session-key-manager.service';