@qidcloud/sdk 1.1.0

package/README.md

@@ -0,0 +1,310 @@
+# @pqcloud/sdk
+
+Official JavaScript/TypeScript SDK for Q-Gate Authentication - Quantum-resistant, passwordless authentication for modern applications.
+
+## Installation
+
+```bash
+npm install @pqcloud/sdk
+```
+
+## Quick Start
+
+```typescript
+import { QGateClient } from '@pqcloud/sdk';
+
+// Initialize with your API key
+const qgate = new QGateClient({
+  apiKey: 'your-api-key-here'
+  // baseUrl is optional, defaults to https://qgate.onrender.com
+});
+
+// Register a new user
+const user = await qgate.register('alice');
+
+// Login
+const token = await qgate.login();
+
+// Get user profile
+const profile = await qgate.getProfile();
+
+// Logout
+await qgate.logout();
+```
+
+## Features
+
+✅ **Quantum-Resistant** - Uses CRYSTALS-Dilithium and Kyber  
+✅ **Passwordless** - No passwords to remember or manage  
+✅ **Zero-Knowledge** - Keys never leave the device  
+✅ **TypeScript Support** - Full type definitions included  
+✅ **Browser & Node.js** - Works everywhere
+
+## API Reference
+
+### `new QGateClient(config)`
+
+Initialize the Q-Gate client.
+
+**Parameters:**
+- `config.apiKey` (required): Your Q-Gate API key
+- `config.baseUrl` (optional): Custom backend URL, defaults to `https://qgate.onrender.com`
+- `config.storage` (optional): Custom storage implementation (defaults to localStorage in browser, memory in Node.js)
+
+**Example:**
+```typescript
+const qgate = new QGateClient({
+  apiKey: 'qg-abc123...',
+  baseUrl: 'https://custom-backend.com' // optional
+});
+```
+
+---
+
+### `qgate.register(username, tenantId?)`
+
+Register a new user identity.
+
+**Parameters:**
+- `username` (required): Unique username
+- `tenantId` (optional): Custom tenant ID, defaults to 'default'
+
+**Returns:** `Promise<UserProfile>`
+
+**Example:**
+```typescript
+const user = await qgate.register('alice');
+console.log(user);
+// { userId: "uuid", username: "alice", role: "user" }
+```
+
+**Note:** This generates and stores cryptographic keys locally. **Backup the seed!**
+
+---
+
+### `qgate.login()`
+
+Authenticate using stored identity.
+
+**Returns:** `Promise<string>` - Session token
+
+**Example:**
+```typescript
+const token = await qgate.login();
+// Use token for API requests
+```
+
+**Throws:**
+- `NO_IDENTITY` - User must register first
+- `MISSING_USER_ID` - Re-registration required
+
+---
+
+### `qgate.getProfile()`
+
+Get current user's profile.
+
+**Returns:** `Promise<UserProfile>`
+
+**Example:**
+```typescript
+const profile = await qgate.getProfile();
+console.log(profile);
+// { userId: "uuid", username: "alice", role: "user", status: "active" }
+```
+
+**Requires:** Active session (must be logged in)
+
+---
+
+### `qgate.logout()`
+
+End the current session.
+
+**Returns:** `Promise<void>`
+
+**Example:**
+```typescript
+await qgate.logout();
+```
+
+**Note:** Local keys are preserved for future login.
+
+---
+
+### `qgate.hasIdentity()`
+
+Check if user has registered identity.
+
+**Returns:** `Promise<boolean>`
+
+**Example:**
+```typescript
+if (await qgate.hasIdentity()) {
+  await qgate.login();
+} else {
+  await qgate.register('alice');
+}
+```
+
+---
+
+## Advanced Usage
+
+### Custom Storage
+
+Provide your own storage implementation:
+
+```typescript
+import { QGateClient, IStorage } from '@pqcloud/sdk';
+
+class CustomStorage implements IStorage {
+  async getItem(key: string): Promise<string | null> {
+    // Your implementation
+  }
+  
+  async setItem(key: string, value: string): Promise<void> {
+    // Your implementation
+  }
+  
+  async removeItem(key: string): Promise<void> {
+    // Your implementation
+  }
+}
+
+const qgate = new QGateClient({
+  apiKey: 'your-key',
+  storage: new CustomStorage()
+});
+```
+
+### Error Handling
+
+```typescript
+try {
+  await qgate.login();
+} catch (error) {
+  if (error.message === 'NO_IDENTITY') {
+    console.log('User not registered');
+  } else if (error.response?.status === 401) {
+    console.log('Authentication failed');
+  }
+}
+```
+
+### Session Management
+
+```typescript
+// Check if user is logged in
+const hasIdentity = await qgate.hasIdentity();
+
+// Auto-login on app start
+if (hasIdentity) {
+  try {
+    await qgate.login();
+  } catch {
+    // Handle expired/invalid session
+  }
+}
+```
+
+## TypeScript
+
+Full TypeScript support included:
+
+```typescript
+import { QGateClient, QGateConfig, UserProfile } from '@pqcloud/sdk';
+
+const config: QGateConfig = {
+  apiKey: 'your-key'
+};
+
+const qgate = new QGateClient(config);
+
+const profile: UserProfile = await qgate.getProfile();
+```
+
+## Security Notes
+
+🔒 **Private keys never leave the device**  
+🔒 **All communication is encrypted**  
+🔒 **Quantum-resistant cryptography**  
+🔒 **Store API keys securely (environment variables)**
+
+## Examples
+
+### React Integration
+
+```typescript
+import { useState, useEffect } from 'react';
+import { QGateClient } from '@pqcloud/sdk';
+
+const qgate = new QGateClient({ apiKey: process.env.REACT_APP_QGATE_KEY });
+
+function App() {
+  const [user, setUser] = useState(null);
+  
+  useEffect(() => {
+    async function init() {
+      if (await qgate.hasIdentity()) {
+        await qgate.login();
+        const profile = await qgate.getProfile();
+        setUser(profile);
+      }
+    }
+    init();
+  }, []);
+  
+  const register = async (username) => {
+    const user = await qgate.register(username);
+    setUser(user);
+  };
+  
+  const logout = async () => {
+    await qgate.logout();
+    setUser(null);
+  };
+  
+  return user ? (
+    <div>
+      <h1>Welcome, {user.username}!</h1>
+      <button onClick={logout}>Logout</button>
+    </div>
+  ) : (
+    <button onClick={() => register('alice')}>Register</button>
+  );
+}
+```
+
+### Node.js Backend
+
+```javascript
+const { QGateClient } = require('@pqcloud/sdk');
+
+const qgate = new QGateClient({
+  apiKey: process.env.QGATE_API_KEY
+});
+
+async function authenticateUser(username) {
+  if (!await qgate.hasIdentity()) {
+    await qgate.register(username);
+  }
+  
+  const token = await qgate.login();
+  return token;
+}
+```
+
+## Support
+
+**Documentation:** [Provider Guide](../PROVIDER_API_GUIDE.md)  
+**Issues:** [GitHub Issues](https://github.com/qgate/sdk/issues)  
+**Email:** support@qgate.io
+
+## License
+
+ISC
+
+---
+
+**Built with ❤️ by the Q-Gate Team**

package/dist/QidCloud.d.ts

@@ -0,0 +1,31 @@
+import { IStorage } from './storage';
+export interface QidConfig {
+    baseUrl?: string;
+    apiKey: string;
+    storage?: IStorage;
+}
+export interface UserProfile {
+    userId: string;
+    username: string;
+    role?: string;
+    plan?: string;
+    accountLimits?: {
+        maxProjects: number;
+        maxUsersTotal: number;
+    };
+}
+export declare class QidCloud {
+    private api;
+    private storage;
+    private config;
+    constructor(config: QidConfig);
+    hasIdentity(): Promise<boolean>;
+    register(username: string, tenantId?: string): Promise<UserProfile>;
+    /**
+     * Login / Authenticate
+     * Uses stored PQC keys to sign a challenge from the server
+     */
+    login(): Promise<string>;
+    logout(): Promise<void>;
+    getProfile(): Promise<UserProfile>;
+}

package/dist/QidCloud.js

@@ -0,0 +1,142 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import axios from 'axios';
+import * as PQC from './crypto/pqc';
+import UnifiedStorage from './storage';
+import { generateUUID, toBase64, fromBase64 } from './utils';
+const DEFAULT_BACKEND_URL = 'https://qgate.onrender.com';
+export class QidCloud {
+    constructor(config) {
+        this.config = Object.assign(Object.assign({}, config), { baseUrl: config.baseUrl || DEFAULT_BACKEND_URL });
+        this.storage = config.storage || UnifiedStorage;
+        this.api = axios.create({
+            baseURL: this.config.baseUrl,
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-KEY': config.apiKey
+            }
+        });
+        // Attach token interceptor
+        this.api.interceptors.request.use((req) => __awaiter(this, void 0, void 0, function* () {
+            const token = yield this.storage.getItem('qgate_token');
+            if (token) {
+                req.headers.Authorization = `Bearer ${token} `;
+            }
+            return req;
+        }));
+    }
+    hasIdentity() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const seed = yield this.storage.getItem('qgate_pqc_seed');
+            return !!seed;
+        });
+    }
+    register(username_1) {
+        return __awaiter(this, arguments, void 0, function* (username, tenantId = 'default') {
+            // 1. Generate Seed
+            const seedHex = yield PQC.generateDilithiumSeed();
+            // 2. Persist Locally
+            yield this.storage.setItem('qgate_pqc_seed', seedHex);
+            // 3. Derive Keys
+            const keys = yield PQC.getKeysFromSeed(seedHex);
+            const initResp = yield this.api.post('/api/register/initiate', { tenantId });
+            const { regSessionId, regNonce } = initResp.data;
+            // 4. Sign Nonce
+            // Backend sends nonce as Base64
+            const nonceBytes = fromBase64(regNonce);
+            const signature = keys.sign(nonceBytes);
+            const signatureBase64 = toBase64(signature);
+            // 5. Complete Registration
+            const completeResp = yield this.api.post('/api/register/complete', {
+                regSessionId,
+                did: generateUUID(), // Device ID
+                username,
+                attestation: {
+                    format: 'web-sdk',
+                    signature: signatureBase64,
+                    nonce: regNonce, // Echo back
+                    publicKey: toBase64(keys.publicKey)
+                }
+            });
+            const { user, token } = completeResp.data;
+            // 6. Store Session
+            if (token) {
+                yield this.storage.setItem('qgate_token', token);
+            }
+            if (user && user.userId) {
+                yield this.storage.setItem('qgate_user_id', user.userId);
+                return user;
+            }
+            return user || { userId: 'unknown', username };
+        });
+    }
+    /**
+     * Login / Authenticate
+     * Uses stored PQC keys to sign a challenge from the server
+     */
+    login() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!(yield this.hasIdentity())) {
+                throw new Error('NO_IDENTITY: Device not registered. Call register() first.');
+            }
+            const seedHex = yield this.storage.getItem('qgate_pqc_seed');
+            if (!seedHex) {
+                throw new Error('NO_IDENTITY_SEED: Seed not found. Re-register.');
+            }
+            const keys = yield PQC.getKeysFromSeed(seedHex);
+            // 1. Initiate Auth Challenge
+            let userId = yield this.storage.getItem('qgate_user_id');
+            if (!userId) {
+                // Try to find user from profile if logged in? No, we are logging in.
+                throw new Error('MISSING_USER_ID: Cannot look up user. Re-register.');
+            }
+            const initResp = yield this.api.post('/api/initiate', {
+                regUserId: userId,
+                clientHint: 'web-sdk'
+            });
+            const { sessionId, nonce } = initResp.data;
+            // 2. Sign Challenge
+            // Backend sends nonce as Base64
+            const nonceBytes = fromBase64(nonce);
+            const signature = keys.sign(nonceBytes);
+            const signatureBase64 = toBase64(signature);
+            // 3. Verify
+            const verifyResp = yield this.api.post('/api/verify', {
+                sessionId,
+                signature: signatureBase64
+            });
+            const { token } = verifyResp.data;
+            if (token) {
+                yield this.storage.setItem('qgate_token', token);
+                return token;
+            }
+            throw new Error('Authentication failed');
+        });
+    }
+    logout() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                // Attempt to notify server
+                yield this.api.post('/api/logout');
+            }
+            catch (e) {
+                console.warn('Logout API call failed', e);
+            }
+            yield this.storage.removeItem('qgate_token');
+            // Optional: Keep identity keys? Usually yes.
+        });
+    }
+    getProfile() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const resp = yield this.api.get('/api/me');
+            return resp.data;
+        });
+    }
+}

package/dist/crypto/pqc.d.ts

@@ -0,0 +1,12 @@
+export declare function generateKyberKeyPair(): Promise<{
+    publicKey: any;
+    privateKey: any;
+}>;
+export declare function decapsulateSecret(privateKey: Uint8Array, cipherText: Uint8Array): Promise<any>;
+export declare function generateDilithiumSeed(): Promise<string>;
+export declare function getKeysFromSeed(seedHex: string): Promise<{
+    publicKey: Uint8Array<ArrayBufferLike>;
+    privateKey: Uint8Array<ArrayBufferLike>;
+    sign: (msg: Uint8Array) => Uint8Array<ArrayBufferLike>;
+}>;
+export declare function signMessage(seedHex: string, message: Uint8Array | string): Promise<Uint8Array<ArrayBufferLike>>;

package/dist/crypto/pqc.js

@@ -0,0 +1,91 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+// PQC Crypto Utility for Q-Gate SDK
+import { DilithiumLevel, DilithiumKeyPair } from '@asanrom/dilithium';
+import { Kyber1024 } from 'crystals-kyber-js';
+import { hex2buf } from '../utils';
+export function generateKyberKeyPair() {
+    return __awaiter(this, void 0, void 0, function* () {
+        // Hardcoded sizes for Kyber1024
+        const PK_SIZE = 1568;
+        const SK_SIZE = 3168;
+        // Assume Kyber1024 is a class we can instantiate or it has static methods.
+        // Based on library patterns, if static props were missing, maybe it's an instance.
+        const kyber = new Kyber1024();
+        // Try async generation first
+        try {
+            // @ts-ignore
+            if (kyber.generateKeyPair) {
+                // @ts-ignore
+                const [pk, sk] = yield kyber.generateKeyPair();
+                return { publicKey: pk, privateKey: sk };
+            }
+        }
+        catch (e) { }
+        // Fallback to buffer passing
+        const pk = new Uint8Array(PK_SIZE);
+        const sk = new Uint8Array(SK_SIZE);
+        // @ts-ignore
+        kyber.keyPair(pk, sk);
+        return {
+            publicKey: pk,
+            privateKey: sk
+        };
+    });
+}
+export function decapsulateSecret(privateKey, cipherText) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const kyber = new Kyber1024();
+        // @ts-ignore
+        if (kyber.decap) {
+            // @ts-ignore
+            return yield kyber.decap(cipherText, privateKey);
+        }
+        // Fallback
+        const SS_SIZE = 32;
+        const sharedSecret = new Uint8Array(SS_SIZE);
+        // @ts-ignore
+        kyber.decaps(sharedSecret, cipherText, privateKey);
+        return sharedSecret;
+    });
+}
+export function generateDilithiumSeed() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const seed = new Uint8Array(32);
+        if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+            crypto.getRandomValues(seed);
+        }
+        else {
+            for (let i = 0; i < 32; i++)
+                seed[i] = Math.floor(Math.random() * 256);
+        }
+        return Array.prototype.map.call(seed, (x) => ('00' + x.toString(16)).slice(-2)).join('');
+    });
+}
+export function getKeysFromSeed(seedHex) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const level = DilithiumLevel.get(3);
+        const seed = hex2buf(seedHex);
+        const kp = DilithiumKeyPair.generate(level, seed);
+        return {
+            publicKey: kp.getPublicKey().getBytes(),
+            privateKey: kp.getPrivateKey().getBytes(),
+            // Helper to sign and return Uint8Array
+            sign: (msg) => kp.sign(msg).getBytes()
+        };
+    });
+}
+export function signMessage(seedHex, message) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const keys = yield getKeysFromSeed(seedHex);
+        const msgBytes = typeof message === 'string' ? new TextEncoder().encode(message) : message;
+        return keys.sign(msgBytes);
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { QidCloud, QidConfig, UserProfile } from './QidCloud';
+import UnifiedStorage from './storage';
+import * as PQC from './crypto/pqc';
+export { QidCloud, QidCloud as PQAuth, QidConfig, UserProfile, UnifiedStorage, PQC };
+export default QidCloud;

package/dist/index.js

@@ -0,0 +1,5 @@
+import { QidCloud } from './QidCloud';
+import UnifiedStorage from './storage';
+import * as PQC from './crypto/pqc';
+export { QidCloud, QidCloud as PQAuth, UnifiedStorage, PQC };
+export default QidCloud;

package/dist/storage/index.d.ts

@@ -0,0 +1,18 @@
+export interface IStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+export declare class MemoryStorage implements IStorage {
+    private storage;
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+export declare class LocalStorageAdapter implements IStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+declare const storage: MemoryStorage | LocalStorageAdapter;
+export default storage;

package/dist/storage/index.js

@@ -0,0 +1,58 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+export class MemoryStorage {
+    constructor() {
+        this.storage = new Map();
+    }
+    getItem(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.storage.get(key) || null;
+        });
+    }
+    setItem(key, value) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.storage.set(key, value);
+        });
+    }
+    removeItem(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.storage.delete(key);
+        });
+    }
+}
+export class LocalStorageAdapter {
+    getItem(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (typeof window !== 'undefined' && window.localStorage) {
+                return window.localStorage.getItem(key);
+            }
+            return null;
+        });
+    }
+    setItem(key, value) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (typeof window !== 'undefined' && window.localStorage) {
+                window.localStorage.setItem(key, value);
+            }
+        });
+    }
+    removeItem(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (typeof window !== 'undefined' && window.localStorage) {
+                window.localStorage.removeItem(key);
+            }
+        });
+    }
+}
+// Default export: Auto-detect
+const storage = typeof window !== 'undefined' && window.localStorage
+    ? new LocalStorageAdapter()
+    : new MemoryStorage();
+export default storage;

package/dist/utils.d.ts

@@ -0,0 +1,5 @@
+export declare function generateUUID(): string;
+export declare function buf2hex(buffer: Uint8Array): string;
+export declare function hex2buf(hex: string): Uint8Array;
+export declare function toBase64(bytes: Uint8Array): string;
+export declare function fromBase64(base64: string): Uint8Array;

package/dist/utils.js

@@ -0,0 +1,46 @@
+export function generateUUID() {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    // Fallback for environments without randomUUID
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+        var r = Math.random() * 16 | 0, v = c === 'x' ? r : (r & 0x3 | 0x8);
+        return v.toString(16);
+    });
+}
+export function buf2hex(buffer) {
+    return Array.prototype.map.call(new Uint8Array(buffer), (x) => ('00' + x.toString(16)).slice(-2)).join('');
+}
+export function hex2buf(hex) {
+    if (!hex)
+        return new Uint8Array(0);
+    const bytes = new Uint8Array(Math.ceil(hex.length / 2));
+    for (let i = 0; i < bytes.length; i++)
+        bytes[i] = parseInt(hex.substr(i * 2, 2), 16);
+    return bytes;
+}
+export function toBase64(bytes) {
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(bytes).toString('base64');
+    }
+    // Browser fallback
+    let binary = '';
+    const len = bytes.byteLength;
+    for (let i = 0; i < len; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return window.btoa(binary);
+}
+export function fromBase64(base64) {
+    if (typeof Buffer !== 'undefined') {
+        return new Uint8Array(Buffer.from(base64, 'base64'));
+    }
+    // Browser fallback
+    const binary_string = window.atob(base64);
+    const len = binary_string.length;
+    const bytes = new Uint8Array(len);
+    for (let i = 0; i < len; i++) {
+        bytes[i] = binary_string.charCodeAt(i);
+    }
+    return bytes;
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@qidcloud/sdk",
+  "version": "1.1.0",
+  "description": "Information-Theoretic Security SDK for Web",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "quantum",
+    "pqc",
+    "security",
+    "kyber",
+    "dilithium"
+  ],
+  "author": "Q-Gate",
+  "license": "ISC",
+  "dependencies": {
+    "@asanrom/dilithium": "^1.0.1",
+    "axios": "^1.6.0",
+    "crystals-kyber-js": "^1.1.1",
+    "eventemitter3": "^5.0.1",
+    "socket.io-client": "^4.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.27",
+    "typescript": "^5.0.0"
+  }
+}

package/src/QidCloud.ts

@@ -0,0 +1,171 @@
+import axios, { AxiosInstance } from 'axios';
+import * as PQC from './crypto/pqc';
+import UnifiedStorage, { IStorage } from './storage';
+import { generateUUID, toBase64, hex2buf, fromBase64 } from './utils';
+
+export interface QidConfig {
+    baseUrl?: string; // Optional, defaults to production backend
+    apiKey: string;
+    storage?: IStorage;
+}
+
+const DEFAULT_BACKEND_URL = 'https://qgate.onrender.com';
+
+export interface UserProfile {
+    userId: string;
+    username: string;
+    role?: string;
+    plan?: string;
+    accountLimits?: {
+        maxProjects: number;
+        maxUsersTotal: number;
+    };
+}
+
+export class QidCloud {
+    private api: AxiosInstance;
+    private storage: IStorage;
+    private config: QidConfig;
+
+    constructor(config: QidConfig) {
+        this.config = {
+            ...config,
+            baseUrl: config.baseUrl || DEFAULT_BACKEND_URL
+        };
+        this.storage = config.storage || UnifiedStorage;
+        this.api = axios.create({
+            baseURL: this.config.baseUrl,
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-KEY': config.apiKey
+            }
+        });
+
+        // Attach token interceptor
+        this.api.interceptors.request.use(async (req) => {
+            const token = await this.storage.getItem('qgate_token');
+            if (token) {
+                req.headers.Authorization = `Bearer ${token} `;
+            }
+            return req;
+        });
+    }
+
+    async hasIdentity(): Promise<boolean> {
+        const seed = await this.storage.getItem('qgate_pqc_seed');
+        return !!seed;
+    }
+
+    async register(username: string, tenantId: string = 'default'): Promise<UserProfile> {
+        // 1. Generate Seed
+        const seedHex = await PQC.generateDilithiumSeed();
+
+        // 2. Persist Locally
+        await this.storage.setItem('qgate_pqc_seed', seedHex);
+
+        // 3. Derive Keys
+        const keys = await PQC.getKeysFromSeed(seedHex);
+
+        const initResp = await this.api.post('/api/register/initiate', { tenantId });
+        const { regSessionId, regNonce } = initResp.data;
+
+        // 4. Sign Nonce
+        // Backend sends nonce as Base64
+        const nonceBytes = fromBase64(regNonce);
+        const signature = keys.sign(nonceBytes);
+        const signatureBase64 = toBase64(signature);
+
+        // 5. Complete Registration
+        const completeResp = await this.api.post('/api/register/complete', {
+            regSessionId,
+            did: generateUUID(), // Device ID
+            username,
+            attestation: {
+                format: 'web-sdk',
+                signature: signatureBase64,
+                nonce: regNonce, // Echo back
+                publicKey: toBase64(keys.publicKey)
+            }
+        });
+
+        const { user, token } = completeResp.data;
+
+        // 6. Store Session
+        if (token) {
+            await this.storage.setItem('qgate_token', token);
+        }
+        if (user && user.userId) {
+            await this.storage.setItem('qgate_user_id', user.userId);
+            return user;
+        }
+
+        return user || { userId: 'unknown', username };
+    }
+
+    /**
+     * Login / Authenticate
+     * Uses stored PQC keys to sign a challenge from the server
+     */
+    async login(): Promise<string> {
+        if (!(await this.hasIdentity())) {
+            throw new Error('NO_IDENTITY: Device not registered. Call register() first.');
+        }
+
+        const seedHex = await this.storage.getItem('qgate_pqc_seed');
+        if (!seedHex) {
+            throw new Error('NO_IDENTITY_SEED: Seed not found. Re-register.');
+        }
+        const keys = await PQC.getKeysFromSeed(seedHex);
+
+        // 1. Initiate Auth Challenge
+        let userId = await this.storage.getItem('qgate_user_id');
+
+        if (!userId) {
+            // Try to find user from profile if logged in? No, we are logging in.
+            throw new Error('MISSING_USER_ID: Cannot look up user. Re-register.');
+        }
+
+        const initResp = await this.api.post('/api/initiate', {
+            regUserId: userId,
+            clientHint: 'web-sdk'
+        });
+
+        const { sessionId, nonce } = initResp.data;
+
+        // 2. Sign Challenge
+        // Backend sends nonce as Base64
+        const nonceBytes = fromBase64(nonce);
+        const signature = keys.sign(nonceBytes);
+        const signatureBase64 = toBase64(signature);
+
+        // 3. Verify
+        const verifyResp = await this.api.post('/api/verify', {
+            sessionId,
+            signature: signatureBase64
+        });
+
+        const { token } = verifyResp.data;
+        if (token) {
+            await this.storage.setItem('qgate_token', token);
+            return token;
+        }
+
+        throw new Error('Authentication failed');
+    }
+
+    async logout(): Promise<void> {
+        try {
+            // Attempt to notify server
+            await this.api.post('/api/logout');
+        } catch (e) {
+            console.warn('Logout API call failed', e);
+        }
+        await this.storage.removeItem('qgate_token');
+        // Optional: Keep identity keys? Usually yes.
+    }
+
+    async getProfile(): Promise<UserProfile> {
+        const resp = await this.api.get('/api/me');
+        return resp.data;
+    }
+}

package/src/crypto/pqc.ts

@@ -0,0 +1,79 @@
+// PQC Crypto Utility for Q-Gate SDK
+import { DilithiumLevel, DilithiumKeyPair } from '@asanrom/dilithium';
+import { Kyber1024 } from 'crystals-kyber-js';
+import { hex2buf } from '../utils';
+
+export async function generateKyberKeyPair() {
+    // Hardcoded sizes for Kyber1024
+    const PK_SIZE = 1568;
+    const SK_SIZE = 3168;
+
+    // Assume Kyber1024 is a class we can instantiate or it has static methods.
+    // Based on library patterns, if static props were missing, maybe it's an instance.
+    const kyber = new Kyber1024();
+    // Try async generation first
+    try {
+        // @ts-ignore
+        if (kyber.generateKeyPair) {
+            // @ts-ignore
+            const [pk, sk] = await kyber.generateKeyPair();
+            return { publicKey: pk, privateKey: sk };
+        }
+    } catch (e) { }
+
+    // Fallback to buffer passing
+    const pk = new Uint8Array(PK_SIZE);
+    const sk = new Uint8Array(SK_SIZE);
+    // @ts-ignore
+    kyber.keyPair(pk, sk);
+
+    return {
+        publicKey: pk,
+        privateKey: sk
+    };
+}
+
+export async function decapsulateSecret(privateKey: Uint8Array, cipherText: Uint8Array) {
+    const kyber = new Kyber1024();
+    // @ts-ignore
+    if (kyber.decap) {
+        // @ts-ignore
+        return await kyber.decap(cipherText, privateKey);
+    }
+
+    // Fallback
+    const SS_SIZE = 32;
+    const sharedSecret = new Uint8Array(SS_SIZE);
+    // @ts-ignore
+    kyber.decaps(sharedSecret, cipherText, privateKey);
+    return sharedSecret;
+}
+
+export async function generateDilithiumSeed(): Promise<string> {
+    const seed = new Uint8Array(32);
+    if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+        crypto.getRandomValues(seed);
+    } else {
+        for (let i = 0; i < 32; i++) seed[i] = Math.floor(Math.random() * 256);
+    }
+    return Array.prototype.map.call(seed, (x: number) => ('00' + x.toString(16)).slice(-2)).join('');
+}
+
+export async function getKeysFromSeed(seedHex: string) {
+    const level = DilithiumLevel.get(3);
+    const seed = hex2buf(seedHex);
+
+    const kp = DilithiumKeyPair.generate(level, seed);
+    return {
+        publicKey: kp.getPublicKey().getBytes(),
+        privateKey: kp.getPrivateKey().getBytes(),
+        // Helper to sign and return Uint8Array
+        sign: (msg: Uint8Array) => kp.sign(msg).getBytes()
+    };
+}
+
+export async function signMessage(seedHex: string, message: Uint8Array | string) {
+    const keys = await getKeysFromSeed(seedHex);
+    const msgBytes = typeof message === 'string' ? new TextEncoder().encode(message) : message;
+    return keys.sign(msgBytes);
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+import { QidCloud, QidConfig, UserProfile } from './QidCloud';
+import UnifiedStorage from './storage';
+import * as PQC from './crypto/pqc';
+
+export { QidCloud, QidCloud as PQAuth, QidConfig, UserProfile, UnifiedStorage, PQC };
+
+export default QidCloud;

package/src/storage/index.ts

@@ -0,0 +1,49 @@
+export interface IStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+
+export class MemoryStorage implements IStorage {
+    private storage: Map<string, string> = new Map();
+
+    async getItem(key: string): Promise<string | null> {
+        return this.storage.get(key) || null;
+    }
+
+    async setItem(key: string, value: string): Promise<void> {
+        this.storage.set(key, value);
+    }
+
+    async removeItem(key: string): Promise<void> {
+        this.storage.delete(key);
+    }
+}
+
+export class LocalStorageAdapter implements IStorage {
+    async getItem(key: string): Promise<string | null> {
+        if (typeof window !== 'undefined' && window.localStorage) {
+            return window.localStorage.getItem(key);
+        }
+        return null;
+    }
+
+    async setItem(key: string, value: string): Promise<void> {
+        if (typeof window !== 'undefined' && window.localStorage) {
+            window.localStorage.setItem(key, value);
+        }
+    }
+
+    async removeItem(key: string): Promise<void> {
+        if (typeof window !== 'undefined' && window.localStorage) {
+            window.localStorage.removeItem(key);
+        }
+    }
+}
+
+// Default export: Auto-detect
+const storage = typeof window !== 'undefined' && window.localStorage
+    ? new LocalStorageAdapter()
+    : new MemoryStorage();
+
+export default storage;

package/src/utils.ts

@@ -0,0 +1,48 @@
+export function generateUUID(): string {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    // Fallback for environments without randomUUID
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+        var r = Math.random() * 16 | 0, v = c === 'x' ? r : (r & 0x3 | 0x8);
+        return v.toString(16);
+    });
+}
+
+export function buf2hex(buffer: Uint8Array): string {
+    return Array.prototype.map.call(new Uint8Array(buffer), (x: number) => ('00' + x.toString(16)).slice(-2)).join('');
+}
+
+export function hex2buf(hex: string): Uint8Array {
+    if (!hex) return new Uint8Array(0);
+    const bytes = new Uint8Array(Math.ceil(hex.length / 2));
+    for (let i = 0; i < bytes.length; i++) bytes[i] = parseInt(hex.substr(i * 2, 2), 16);
+    return bytes;
+}
+
+export function toBase64(bytes: Uint8Array): string {
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(bytes).toString('base64');
+    }
+    // Browser fallback
+    let binary = '';
+    const len = bytes.byteLength;
+    for (let i = 0; i < len; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return window.btoa(binary);
+}
+
+export function fromBase64(base64: string): Uint8Array {
+    if (typeof Buffer !== 'undefined') {
+        return new Uint8Array(Buffer.from(base64, 'base64'));
+    }
+    // Browser fallback
+    const binary_string = window.atob(base64);
+    const len = binary_string.length;
+    const bytes = new Uint8Array(len);
+    for (let i = 0; i < len; i++) {
+        bytes[i] = binary_string.charCodeAt(i);
+    }
+    return bytes;
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES6",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": [
+      "DOM",
+      "ES2017"
+    ],
+    "declaration": true,
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [
+    "src/**/*"
+  ]
+}

package/verify_sdk.ts

@@ -0,0 +1,53 @@
+import { QGateClient } from './src';
+import * as PQC from './src/crypto/pqc';
+
+async function verify() {
+    console.log('--- QGate SDK Verification ---');
+
+    // 1. Verify Exports
+    if (!QGateClient) {
+        throw new Error('QGateClient export missing');
+    }
+    console.log('✅ QGateClient exported');
+
+    // 2. Verify PQC Generation (Dilithium)
+    console.log('Testing Dilithium Seed Generation...');
+    const seed = await PQC.generateDilithiumSeed();
+    console.log('Generated Seed:', seed);
+    if (!seed || seed.length !== 64) { // 32 bytes hex
+        throw new Error('Invalid seed generated');
+    }
+    console.log('✅ Dilithium Seed Generated');
+
+    // 3. Verify Key Derivation
+    console.log('Deriving Keys...');
+    const keys = await PQC.getKeysFromSeed(seed);
+    if (!keys.publicKey || !keys.privateKey) {
+        throw new Error('Failed to derive keys');
+    }
+    console.log('✅ Keys Derived');
+
+    // 4. Verify Signing
+    console.log('Testing Signing...');
+    const msg = "Hello QGate";
+    const sig = keys.sign(new TextEncoder().encode(msg));
+    console.log('Signature Length:', sig.length);
+    if (sig.length === 0) {
+        throw new Error('Signature failed');
+    }
+    console.log('✅ Signing Success'); // Verification requires Dilithium library verify which we didn't export in PQC yet but sign works.
+
+    // 5. Verify Client Instantiation
+    const client = new QGateClient({
+        baseUrl: 'http://localhost:3000',
+        apiKey: 'test-key'
+    });
+    console.log('✅ Client Instantiated');
+
+    console.log('--- SDK VERIFIED ---');
+}
+
+verify().catch(err => {
+    console.error('❌ VERIFICATION FAILED:', err);
+    process.exit(1);
+});