@kiauth/web-sdk 1.0.0 → 1.1.0

package/README.md

@@ -1,17 +1,18 @@
 # @kiauth/web-sdk
 
-Framework-agnostic "Login with Kiauth" button for any website (React, Vue, Angular,
-Svelte, or plain HTML). Renders a button, runs the QR approval flow, and hands your
-frontend a one-time authorization `code`. Your **server** exchanges that code for the
-verified user.
+Three things, for any website (React, Vue, Angular, Svelte, or plain HTML):
 
-> Test backend: `https://api.kiauth.com` — pass it as `baseUrl`.
+1. **Verified Human** — know the person signing up is a real, unique, Aadhaar-verified human. Not a bot, not a duplicate account.
+2. **Signup / Login** — passwordless "Login with Kiauth". The user approves on their phone with a biometric. No password database.
+3. **Session management + cross-app knowledge** — the user sees every app they are signed into and can revoke any of them; your server is told when they do. You can also surface logins that never went through Kiauth at all.
+
+> Backend: `https://api.kiauth.com` — pass it as `baseUrl`.
 
 ## Install
 
 **Option A — script tag (no build tooling):**
 ```html
-<script src="/path/to/kiauth-sdk.min.js"></script>
+<script src="https://unpkg.com/@kiauth/web-sdk@1.1.0/dist/kiauth-sdk.min.js"></script>
 <script>
   const kiauth = new KiauthSDK({
     clientId: 'YOUR_CLIENT_ID',
@@ -19,10 +20,14 @@ verified user.
     environment: 'production',
     baseUrl: 'https://api.kiauth.com'
   });
+
   kiauth.renderButton('#login-container', {
     text: 'Login with Kiauth',
+    // onSuccess receives the VERIFIED USER — the SDK completes the code exchange
+    // for you. It does not hand you a raw `code`.
     onSuccess: (user) => {
-      // user.code -> send to YOUR backend to exchange (see below)
+      if (!KiauthSDK.isProductionTrustworthy(user)) return;   // see §1
+      createSessionFor(user.userToken);
     },
     onError: (err) => console.error(err.message)
   });
@@ -30,12 +35,12 @@ verified user.
 <div id="login-container"></div>
 ```
 
-**Option B — local tarball (import workflow):**
+**Option B — npm:**
 ```bash
-npm install ./kiauth-web-sdk-1.0.0.tgz
+npm install @kiauth/web-sdk
 ```
 ```js
-import { KiauthSDK } from '@kiauth/web-sdk';
+import { KiauthSDK, isProductionTrustworthy } from '@kiauth/web-sdk';
 
 const kiauth = new KiauthSDK({
   clientId: process.env.KIAUTH_CLIENT_ID,
@@ -45,6 +50,135 @@ const kiauth = new KiauthSDK({
 });
 ```
 
+---
+
+## 1. Verified Human
+
+`onSuccess(user)` hands you a **graded** identity claim. Never trust the bare boolean.
+
+```js
+kiauth.renderButton('#login-container', {
+  onSuccess: (user) => {
+    // ❌ Not enough — `kiauth_verified` is ALSO true for Kiauth's test identities.
+    // if (user.kiauth_verified) { ... }
+
+    // ✅ The check a production app should make:
+    if (!isProductionTrustworthy(user)) {
+      return showError('We could not verify your identity.');
+    }
+
+    // user.userToken  — stable + pairwise. The SAME human always maps to this token
+    //                   at YOUR app, and to a different one at every other app.
+    //                   Key your account record on it.
+    // user.uniqueness — 'one_account_per_human'. One real human holds at most one
+    //                   account at your app — not even by deleting their Kiauth
+    //                   account and re-registering.
+    createAccount({ kiauthUserToken: user.userToken, name: user.name, email: user.email });
+  },
+  onError: (err) => console.error(err.message)
+});
+```
+
+`isProductionTrustworthy(user)` is exactly
+`user.kiauth_verified && user.assurance_level === 'aadhaar' && !user.is_test_identity`.
+It is also available as `KiauthSDK.isProductionTrustworthy` for script-tag users.
+
+### The `KiauthUser` object
+
+| Field | Type | Meaning |
+|---|---|---|
+| `kiauth_verified` | boolean | Kiauth ran an identity check and it passed. **Also true for test identities.** |
+| `verified` | boolean | Alias of `kiauth_verified`. Both are always present. |
+| `identity_verified` | boolean | The durable fact that this human completed Aadhaar verification. Never decays. |
+| `assurance_level` | `'aadhaar' \| 'human' \| 'test' \| 'none'` | How strong the check was. |
+| `is_test_identity` | boolean | **TRUE for a fabricated identity from Kiauth's test mode. Reject in production.** |
+| `uniqueness` | `'one_account_per_human'` | Kiauth's guarantee. |
+| `userToken` | string | Stable, pairwise per (human, your app). Key your account on it. |
+| `method` | `'aadhaar_okyc' \| 'peer' \| 'test_identity' \| 'none'` | |
+| `verified_at` | string \| null | ISO timestamp of the identity check. |
+| `verification_expires_at` | string \| null | When Kiauth will ask them to renew. |
+| `assurance_age_days` | number \| null | How old the check is, in whole days. |
+| `assurance_fresh` | boolean | Whether it is inside Kiauth's current freshness window. |
+
+**Re-verification is Kiauth's job, not yours.** Kiauth periodically re-checks each
+human; that cadence is a Kiauth↔user relationship. You are never forced to pay for a
+fresh check because our clock ran out. If your own risk rules genuinely need a recent
+check, use the verification API's `maxAssuranceAgeDays`. Otherwise read
+`identity_verified` and let us worry about it.
+
+---
+
+## 2. Signup / Login
+
+`renderButton()` runs the whole flow: shows a QR (desktop) or opens the Kiauth app
+(mobile), waits for the biometric approval, exchanges the one-time code, and calls
+`onSuccess(user)`.
+
+```js
+kiauth.renderButton('#login-container', { onSuccess, onError });
+```
+
+Or drive it yourself, without the button:
+
+```js
+await kiauth.startLogin({ onSuccess, onError, onCancel });
+```
+
+### Where the code exchange happens
+
+- **Without `clientSecret`** (recommended for browsers) — the SDK uses **PKCE** and
+  exchanges the code with no secret.
+- **With `clientSecret` in config** — the SDK exchanges directly. Convenient for
+  server-side or sandbox use. **Never ship a client secret to a browser.**
+
+Verify an access token later, from your server:
+```js
+const { valid, user } = await kiauth.verifyToken(accessToken);
+```
+
+> Prefer a redirect-based integration with your existing auth library (Auth.js, etc.)?
+> Kiauth is also a standard **OpenID Connect** provider — see the dev-portal docs.
+> The embedded button (this SDK) gives full white-label control; OIDC is the
+> lowest-friction drop-in.
+
+---
+
+## 3. Session management + cross-app knowledge
+
+The user sees every app they are signed into, inside the Kiauth app, and can revoke
+any of them. When they do, Kiauth sends your server a **`SESSION_REVOKED`** webhook so
+you can end your own session too — two-way logout.
+
+You can also surface logins that **never went through Kiauth**, so the user's dashboard
+is complete rather than partial.
+
+> These methods require your `clientSecret` and **throw if called from a browser**.
+> Run them on your server.
+
+```js
+// A user signed in with Google / password / OTP — put it on their Kiauth dashboard.
+await kiauth.reportSession({
+  kiauthUserToken: user.userToken,
+  externalSessionId: yourSessionId,
+  authMethod: 'GOOGLE_OAUTH',           // EMAIL_PASSWORD | FACEBOOK | PHONE_OTP | APPLE | PASSKEY | UNKNOWN
+  deviceName: 'Chrome on MacBook',
+  deviceType: 'DESKTOP'
+});
+
+// Don't know their userToken? Report against a verified email instead.
+await kiauth.reportSessionByEmail({ email, externalSessionId, authMethod: 'EMAIL_PASSWORD' });
+
+// Backfill many at once.
+await kiauth.reportBatchSessions(user.userToken, [ /* ... */ ]);
+
+// The user logged out of YOUR app — remove it from their dashboard.
+await kiauth.logout({ externalSessionId: yourSessionId });
+```
+
+Webhooks to handle: `SESSION_CREATED`, `SESSION_REVOKED`, `PERMISSION_REVOKED`.
+
+---
+
 ## Config
 
 | Field | Required | Notes |
@@ -53,6 +187,7 @@ const kiauth = new KiauthSDK({
 | `scopes` | yes | Subset of `name`, `email`, `dob`, `gender`, `phone` |
 | `environment` | yes | `'production'` or `'sandbox'` |
 | `baseUrl` | recommended | Backend URL. Overrides the env default. `/api/v1` is appended automatically. |
+| `clientSecret` | no | **Server / sandbox only.** Omit in browsers — the SDK uses PKCE. |
 | `redirectUri` | optional | Where to return after approval |
 
 ## Button customization (white-label)
@@ -83,27 +218,23 @@ kiauth.renderButton('#login-container', {
 });
 ```
 
-> Prefer a redirect-based integration with your existing auth library (Auth.js, etc.)?
-> Kiauth is also a standard **OpenID Connect** provider — see the dev-portal docs for the
-> "Login with Kiauth" OIDC option. The embedded button (this SDK) gives full white-label
-> control; OIDC is the lowest-friction drop-in.
-
-## Server-side token exchange (required)
-
-The `code` from `onSuccess` is exchanged on **your backend** — never expose your Client Secret in the browser.
-
-```js
-const res = await fetch('https://api.kiauth.com/api/v1/auth/token', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    grantType: 'authorization_code',
-    code,
-    clientId: process.env.KIAUTH_CLIENT_ID,
-    clientSecret: process.env.KIAUTH_CLIENT_SECRET
-  })
-});
-const { user } = await res.json(); // { name, email, verified, userToken }
-```
-
-Use `user.userToken` (a stable per-user id) to create your own app session.
+---
+
+## Changelog
+
+### 1.1.0
+- **Fixed:** `user.kiauth_verified` was `undefined` after a login. The backend's login
+  exchange emitted `verified` while this SDK's type declared `kiauth_verified`, so an
+  app checking the documented field silently treated every verified human as
+  unverified. Both spellings are now emitted and normalized.
+- **Fixed:** the README claimed `onSuccess` hands you a `code` to exchange on your
+  server. It hands you the verified **user** — the SDK completes the exchange.
+- **Added:** graded identity claims — `assurance_level`, `is_test_identity`,
+  `identity_verified`, `assurance_age_days`, `assurance_fresh`, `uniqueness`.
+- **Added:** `isProductionTrustworthy(user)` (also `KiauthSDK.isProductionTrustworthy`).
+- **Hardened:** every response is normalized and **fails closed**. A missing or
+  unrecognised field grades as unverified rather than reaching your `if` as
+  `undefined`.
+
+### 1.0.0
+- Initial release.

package/dist/kiauth-sdk.js

@@ -1,3 +1,68 @@
+/**
+ * Normalizes whatever the backend returned into a complete `KiauthUser`.
+ *
+ * Why this exists: `/auth/token` and `/auth/verify` historically disagreed on the
+ * key name — the login exchange said `verified`, introspection said
+ * `kiauth_verified`, and this SDK's type declared only the latter. Any app that
+ * wrote `if (user.kiauth_verified)` after a login was reading `undefined` and
+ * treating a verified human as unverified.
+ *
+ * The backend now emits both spellings. This function keeps the SDK correct against
+ * older backends too, and guarantees every field is defined rather than silently
+ * absent — an `undefined` in a trust decision is worse than a `false`.
+ *
+ * FAIL CLOSED: anything missing or unrecognised grades as unverified.
+ */
+function normalizeUser(raw) {
+    const src = raw ?? {};
+    // Accept either spelling; require an explicit `true`, never a truthy accident.
+    const verified = src.kiauth_verified === true || src.verified === true;
+    const assurance = src.assurance_level === 'aadhaar' ||
+        src.assurance_level === 'human' ||
+        src.assurance_level === 'test' ||
+        src.assurance_level === 'none'
+        ? src.assurance_level
+        : // An older backend sent no grading. A bare `verified: true` cannot be
+            // distinguished from a test identity, so do not claim `aadhaar`.
+            verified
+                ? 'human'
+                : 'none';
+    const method = src.method === 'aadhaar_okyc' || src.method === 'test_identity' || src.method === 'peer' || src.method === 'none'
+        ? src.method
+        : 'none';
+    const expiresAt = src.verification_expires_at ?? src.verificationExpiry ?? null;
+    return {
+        name: src.name ?? src.displayName ?? null,
+        email: src.email ?? null,
+        kiauth_verified: verified,
+        verified,
+        // Absent on an older backend: fall back to `verified` rather than inventing a
+        // durable fact we were not told about.
+        identity_verified: src.identity_verified === true || verified,
+        assurance_level: assurance,
+        method,
+        verified_at: src.verified_at ?? null,
+        verification_expires_at: expiresAt,
+        verificationExpiry: expiresAt,
+        assurance_age_days: typeof src.assurance_age_days === 'number' ? src.assurance_age_days : null,
+        assurance_fresh: src.assurance_fresh === true,
+        // Fail closed: if the backend did not say, assume nothing. A missing flag must
+        // not read as "definitely a real human".
+        is_test_identity: src.is_test_identity === true,
+        uniqueness: 'one_account_per_human',
+        userToken: src.userToken ?? ''
+    };
+}
+/**
+ * The check a production app should make. True only for a real, Aadhaar-verified,
+ * non-fabricated human.
+ *
+ *   if (!isProductionTrustworthy(user)) return reject();
+ */
+function isProductionTrustworthy(user) {
+    return user.kiauth_verified && user.assurance_level === 'aadhaar' && !user.is_test_identity;
+}
+
 class KiauthApi {
     constructor(config) {
         this.baseUrl = KiauthApi.resolveBaseUrl(config);
@@ -99,7 +164,10 @@ class KiauthApi {
             const err = await res.json().catch(() => ({}));
             throw { code: err.code || 'TOKEN_EXCHANGE_FAILED', message: err.message || 'Failed to exchange authorization code.' };
         }
-        return res.json();
+        const body = await res.json();
+        // Never hand the caller a raw response: normalizeUser guarantees every field is
+        // defined, so `user.kiauth_verified` can never be a silent `undefined`.
+        return { ...body, user: normalizeUser(body.user) };
     }
     async verifyToken(token) {
         const res = await fetch(`${this.baseUrl}/auth/verify`, {
@@ -113,7 +181,10 @@ class KiauthApi {
         if (!res.ok) {
             return { valid: false };
         }
-        return res.json();
+        const body = await res.json();
+        if (!body.valid)
+            return { valid: false };
+        return { valid: true, user: normalizeUser(body.user) };
     }
     async reportSession(clientId, clientSecret, options) {
         const creds = btoa(`${clientId}:${clientSecret}`);
@@ -3679,6 +3750,14 @@ class KiauthSDK {
         this.modal.close();
     }
 }
+/**
+ * The check a production app should make on every login.
+ *
+ * `user.kiauth_verified` alone is NOT enough — it is also true for Kiauth's test
+ * identities. Exposed as a static so script-tag (UMD) users can reach it too:
+ *   if (!KiauthSDK.isProductionTrustworthy(user)) return;
+ */
+KiauthSDK.isProductionTrustworthy = isProductionTrustworthy;
 
-export { KiauthSDK };
+export { KiauthSDK, isProductionTrustworthy, normalizeUser };
 //# sourceMappingURL=kiauth-sdk.js.map