@qidcloud/sdk 1.2.2 → 1.2.3

package/README.md

@@ -21,30 +21,107 @@ const qid = new QidCloud({
 
 ---
 
-## 🛡️ Identity & Auth (`qid.auth`)
+## ⚠️ Prerequisite: CORS Configuration
 
-### `createSession()`
-Initializes a new PQC handshake session for QR login.
-- **Returns**: `Promise<{ sessionId: string, qrData: string, expiresAt: number }>`
-```typescript
-const { sessionId, qrData } = await qid.auth.createSession();
+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.
+
+---
+
+## 🛡️ Authentication Guide
+
+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.
+
+### 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)}
+    />
+  );
+}
 ```
 
-### `getProfile(token)`
-Verifies a session token and retrieves the user profile.
-- **Returns**: `Promise<QidUser>`
-```typescript
-const user = await qid.auth.getProfile(sessionToken);
+### 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 CustomLogin() {
+  const { 
+    login,    // Generates QR and starts polling
+    session,  // Contains { qrData } to display
+    user,     // Populated on success
+    logout 
+  } = useQidAuth(sdk);
+
+  if (user) return <button onClick={logout}>Logout {user.username}</button>;
+
+  return (
+    <div>
+      <button onClick={login}>Generate QR</button>
+      {session && <QRCode value={session.qrData} />}
+    </div>
+  );
+}
 ```
 
-### `listen(sessionId, onAuthorized, onDenied?)`
-Listen for real-time authorization events via WebSocket.
-```typescript
-qid.auth.listen(sessionId, 
-  (token) => console.log('Authenticated:', token), 
-  (error) => console.error('Denied:', error)
-);
+### 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
+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.
 
 ---
 
@@ -127,6 +204,19 @@ 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)`
@@ -140,3 +230,28 @@ 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';