@qidcloud/sdk 1.2.1 → 1.2.3

package/README.md

@@ -1,68 +1,257 @@
 # @qidcloud/sdk
 
-The official JavaScript/TypeScript SDK for QidCloud. Build PQC-secured, enclave-backed applications in minutes.
+The official JavaScript/TypeScript SDK for QidCloud. Build PQC-secured, enclave-backed applications with ease.
 
-## 🚀 30-Minute Quick Start
+## 🚀 Installation
 
-### 1. Install
 ```bash
 npm install @qidcloud/sdk
 ```
 
-### 2. Initialize
+## 🛠️ Initialization
+
 ```typescript
 import { QidCloud } from '@qidcloud/sdk';
 
 const qid = new QidCloud({
   apiKey: 'your_api_key',   // Found in QidCloud Console -> Settings
-  tenantId: 'your_project_id'
+  tenantId: 'your_project_id' // Optional, for project-scoped operations
 });
 ```
 
 ---
 
-## 🔑 Identity (`qid.auth`)
-
-Enforce Pure Post-Quantum Identity with zero passwords.
+## ⚠️ Prerequisite: CORS Configuration
 
-### `createSession()`
-Initiates a new QR handshake session.
-- **Returns**: `Promise<QidAuthSession>` 
+Before using the SDK, you **must whitelist your application's domain** in the QidCloud Console.
+1. Go to **Settings > Security**.
+2. Add your app's URL (e.g., `http://localhost:5173` or `https://myapp.com`) to the **Allowed Origins** list.
+3. Without this, browser requests will be blocked by CORS policy.
 
 ---
 
-## 🏗️ React Integration
+## 🛡️ Authentication Guide
 
-The SDK provides powerful React tools for seamless integration.
+QidCloud uses a **Post-Quantum Cryptography (PQC)** handshake for authentication. Users strictly log in by scanning a QR code with their QidCloud Mobile App. **Password entry is NOT supported** in the SDK to ensure credentials never touch the client device.
 
-### `useQidAuth(sdk)`
-The recommended way to manage auth state in React.
+### 1. Recommended: Using `QidCloudLogin` Component
+The easiest way to implement secure login.
+```tsx
+import { QidCloud, QidCloudLogin } from '@qidcloud/sdk';
 
+const sdk = new QidCloud({
+  apiKey: 'your_api_key',
+  tenantId: 'your_project_id'
+});
+
+function App() {
+  return (
+    <QidCloudLogin 
+      sdk={sdk} 
+      onSuccess={(user, token) => {
+        console.log('Logged in:', user);
+        // Token is also automatically cached in localStorage by the component
+      }}
+      onError={(err) => console.error(err)}
+    />
+  );
+}
+```
+
+### 2. Custom UI: Using `useQidAuth` Hook
+For building your own UI while keeping the SDK's state management.
 ```tsx
 import { useQidAuth } from '@qidcloud/sdk';
 
-function MyComponent({ qid }) {
-  const { user, token, session, login, initializing } = useQidAuth(qid);
+function CustomLogin() {
+  const { 
+    login,    // Generates QR and starts polling
+    session,  // Contains { qrData } to display
+    user,     // Populated on success
+    logout 
+  } = useQidAuth(sdk);
 
-  if (user) return <p>Welcome, {user.username}</p>;
+  if (user) return <button onClick={logout}>Logout {user.username}</button>;
 
   return (
-    <button onClick={login}>
-      {initializing ? 'Connecting...' : 'Login'}
-    </button>
+    <div>
+      <button onClick={login}>Generate QR</button>
+      {session && <QRCode value={session.qrData} />}
+    </div>
   );
 }
 ```
 
-### `QidSignInButton`
-A plug-and-play button that handles the entire handshake UI.
+### 3. Raw Implementation (No SDK)
+If you prefer to hit the endpoints directly:
+1. **Create Session**: `POST /api/auth/session` (Headers: `x-api-key`, `x-tenant-id`) -> Returns `sessionId`, `qrData`.
+2. **Display QR**: Render `qrData` as a QR code.
+3. **Listen (Socket/Poll)**: Connect to `socket.io` specific to `sessionId` OR poll status.
+4. **Exchange**: When mobile app confirms, server sends auth token.
+5. **Get Profile**: `GET /api/me` (Header: `Authorization: Bearer <token>`).
+
+### 📱 Mobile-to-Mobile (App-to-App) Auth
+If you are building a mobile application that needs to authenticate users via the QidCloud Mobile App:
+
+1. **Initiate**: Call `sdk.auth.createSession()` to get a `sessionId`.
+2. **Deep Link**: Construct a deep link to the QidCloud app using the following format:
+   ```
+   qidcloud://authorize?data=<JSON_PAYLOAD>&callback=<YOUR_APP_SCHEME>
+   ```
+   - **data**: URL-encoded JSON containing `{ "sessionId": "..." }`.
+   - **callback**: Your app's deep link scheme (e.g., `myapp://auth-callback`).
+3. **Handle Callback**: The QidCloud app will redirect back to your callback URL with status results:
+   - **Success**: `myapp://auth-callback?status=accepted&userId=<APPROVER_ID>`
+   - **Rejection**: `myapp://auth-callback?status=rejected`
+4. **Finalize**: Your app should listen for the `authenticated` event on the socket (as shown in Step 2) to receive the final session token.
 
+---
+### 🔐 Session Management
+- **Persistence**: The SDK automatically caches the token in `localStorage` under `qid_auth_token`.
+- **Restoration**: On page load, `useQidAuth` checks for this token and verifies it via `/api/me`.
+- **Expiry**: Tokens expire after **1 hour of inactivity**. The backend implements a sliding window, so active sessions automatically extend their validity. Handle 401 errors by calling `logout()`.
+
+### 🚪 Logout Handling
+Always use the SDK's `logout()` method to preventing "ghost sessions".
 ```tsx
-import { QidSignInButton } from '@qidcloud/sdk';
+const { logout } = useQidAuth(sdk);
+// ...
+<button onClick={logout}>Sign Out</button>
+```
+**What `logout()` does:**
+1. Calls `POST /api/logout` to invalidate the session on the server.
+2. Removes the token from `localStorage`.
+3. Clears in-memory state.
+
+---
 
-<QidSignInButton 
-  sdk={qid}
-  onSuccess={(user, token) => console.log(user)}
-  onError={(err) => alert(err)}
-/>
+## 🗄️ Secure Vault (`qid.vault`)
+
+### `upload(file, name, metadata?, userToken?)`
+Encrypt and upload a file to the secure enclave.
+- **Returns**: `Promise<QidUploadResponse>`
+```typescript
+await qid.vault.upload(fileBlob, 'secret.pdf', { tag: 'confidential' }, userToken);
+```
+
+### `list(userToken?)`
+List all encrypted files.
+- **Returns**: `Promise<QidFile[]>`
+```typescript
+const files = await qid.vault.list(userToken);
+```
+
+### `download(fileId, userToken?)`
+Download a file as an ArrayBuffer.
+```typescript
+const buffer = await qid.vault.download('file_123', userToken);
+```
+
+### `delete(fileId, userToken?)`
+Soft delete a file (move to recycle bin).
+```typescript
+await qid.vault.delete('file_123', userToken);
 ```
+
+---
+
+## ⚡ Edge Computing (`qid.edge`)
+
+### `invoke(name, params?, userToken?)`
+Invoke a serverless edge function.
+- **Returns**: `Promise<QidEdgeResponse>`
+```typescript
+const result = await qid.edge.invoke('secure-calc', { input: 42 }, userToken);
+```
+
+### `list()`
+List all provisioned functions.
+```typescript
+const functions = await qid.edge.list();
+```
+
+### `getLogs(name, userToken?)`
+Get logs for a specific function.
+```typescript
+const logs = await qid.edge.getLogs('my-function', userToken);
+```
+
+### `deploy(data, userToken?)`
+Deploy or update a function.
+```typescript
+await qid.edge.deploy({ 
+  name: 'new-func', 
+  code: '...', 
+  runtime: 'node18' 
+}, userToken);
+```
+
+---
+
+## 📊 Observability (`qid.logs`)
+
+### `write(message, source?, level?, meta?)`
+Ingest custom telemetry into the enclave.
+```typescript
+await qid.logs.write('User action detected', 'frontend', 'info', { userId: '123' });
+```
+
+### `fetch(query?)`
+Retrieve project logs.
+```typescript
+const logs = await qid.logs.fetch({ limit: 50, level: 'error' });
+```
+
+---
+
+
+---
+
+## ✅ Production Readiness Checklist
+
+To ensure a secure and robust integration, verify the following before going live:
+
+- [ ] **HTTPS Only**: Ensure your application is served over HTTPS. The SDK's cryptographic features (and many browser security APIs) require a secure context.
+- [ ] **Environment Variables**: Store your `apiKey` and `tenantId` in environment variables (e.g., `VITE_QID_API_KEY`) ensuring they are not hardcoded in version control.
+- [ ] **Error Boundaries**: Wrap the `QidCloudLogin` component in a React Error Boundary to gracefully handle any unexpected runtime failures.
+- [ ] **Strict Mode**: If using React Strict Mode, ensure your `useEffect` logic handles double-invocation (The SDK's hooks are already optimized for this).
+- [ ] **CORS**: Double-check that all your production domains (including `www` and non-`www`) are whitelisted in the QidCloud Console.
+
+## ⚛️ React Helpers
+
+### `useQidAuth(sdk)`
+Hook for managing authentication state.
+```tsx
+const { user, login, logout } = useQidAuth(qid);
+```
+
+### `QidSignInButton`
+Pre-built component for PQC login.
+```tsx
+<QidSignInButton sdk={qid} onSuccess={(user) => console.log(user)} />
+```
+
+---
+
+## ❓ Troubleshooting
+
+### "Invalid hook call" after linking the SDK locally
+If you are developing the SDK locally and linking it to your project (via `npm link` or `npm install ../sdk-path`), you might encounter an "Invalid hook call" error. This is usually caused by **Duplicate React** (the app and the SDK are using different React instances).
+
+**Solution for Vite projects:**
+Add `resolve.dedupe` to your `vite.config.ts` to force both your app and the SDK to share the same React instance.
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  // ... rest of config
+  resolve: {
+    dedupe: ['react', 'react-dom']
+  }
+})
+```
+
+**Manual Check:**
+Ensure that the `@qidcloud/sdk` folder does NOT have a `node_modules/react` directory. If it does, delete it manually so it defers to your project's React.

package/dist/components/QidCloudLogin.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import { QidCloud } from '../index';
+import { QidUser } from '../types';
+interface QidCloudLoginProps {
+    sdk: QidCloud;
+    onSuccess: (user: QidUser, token: string) => void;
+    onError?: (error: string) => void;
+    className?: string;
+}
+/**
+ * A comprehensive login component for QidCloud.
+ * STRICT SECURITY: ONLY supports QR Scanning (Mobile App) for Post-Quantum security.
+ * Conventional login is not available in the SDK to prevent password transmission in third-party apps.
+ */
+export declare const QidCloudLogin: React.FC<QidCloudLoginProps>;
+export {};

package/dist/hooks/useQidAuth.d.ts

@@ -7,9 +7,12 @@ export interface UseQidAuthReturn {
     error: string | null;
     session: QidAuthSession | null;
     initializing: boolean;
+    isExpired: boolean;
+    timeLeft: number;
     login: () => Promise<void>;
     logout: () => void;
     cancel: () => void;
+    setAuthenticated: (user: QidUser, token: string) => void;
 }
 /**
  * A React hook for managing QidCloud authentication lifecycle.

package/dist/index.d.ts

@@ -22,4 +22,5 @@ export declare class QidCloud {
 export default QidCloud;
 export * from './types';
 export { QidSignInButton } from './components/QidSignInButton';
+export { QidCloudLogin } from './components/QidCloudLogin';
 export { useQidAuth } from './hooks/useQidAuth';