@kiauth/web-sdk 1.0.0 → 1.1.0

package/dist/types/KiauthSDK.d.ts

@@ -1,4 +1,5 @@
 import { KiauthConfig, KiauthUser, LoginOptions, ProgrammaticLoginOptions } from './types';
+import { isProductionTrustworthy } from './normalizeUser';
 export declare class KiauthSDK {
     private config;
     private api;
@@ -9,6 +10,14 @@ export declare class KiauthSDK {
     private healthCheckIntervalId;
     private pollIntervalId;
     private completed;
+    /**
+     * 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;
+     */
+    static isProductionTrustworthy: typeof isProductionTrustworthy;
     constructor(config: KiauthConfig);
     private startHealthCheck;
     renderButton(selector: string, options: LoginOptions): void;

package/dist/types/index.d.ts

@@ -1,2 +1,3 @@
 export { KiauthSDK } from './KiauthSDK';
+export { normalizeUser, isProductionTrustworthy } from './normalizeUser';
 export * from './types';

package/dist/types/normalizeUser.d.ts

@@ -0,0 +1,24 @@
+import { KiauthUser } from './types';
+/**
+ * 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.
+ */
+export declare function normalizeUser(raw: any): KiauthUser;
+/**
+ * The check a production app should make. True only for a real, Aadhaar-verified,
+ * non-fabricated human.
+ *
+ *   if (!isProductionTrustworthy(user)) return reject();
+ */
+export declare function isProductionTrustworthy(user: KiauthUser): boolean;

package/dist/types/types.d.ts

@@ -6,12 +6,61 @@ export interface KiauthConfig {
     redirectUri?: string;
     baseUrl?: string;
 }
+/** How the human was verified. Ordered weakest → strongest. */
+export type KiauthMethod = 'none' | 'test_identity' | 'peer' | 'aadhaar_okyc';
+/**
+ * Assurance ladder.
+ *  - `none`    — not verified. Never trust.
+ *  - `test`    — a fabricated identity from Kiauth's test mode. NEVER trust in production.
+ *  - `human`   — a real human, proven by a peer attestation. No government ID behind it.
+ *  - `aadhaar` — Aadhaar-verified. The strongest tier.
+ */
+export type KiauthAssuranceLevel = 'none' | 'test' | 'human' | 'aadhaar';
 export interface KiauthUser {
-    name: string;
+    name: string | null;
     email: string | null;
+    /**
+     * True when Kiauth ran an identity check and it passed.
+     *
+     * ⚠️ Do NOT gate production trust on this alone — it is also true for Kiauth's
+     * test identities. Check `assurance_level === 'aadhaar'` and `!is_test_identity`.
+     */
     kiauth_verified: boolean;
+    /** Alias of `kiauth_verified`. Both are always present. */
+    verified: boolean;
+    /**
+     * The durable fact that this human completed Aadhaar verification. Unlike
+     * `kiauth_verified` it never decays: Kiauth's own re-verification cadence is a
+     * Kiauth↔user matter, not the relying party's.
+     */
+    identity_verified: boolean;
+    assurance_level: KiauthAssuranceLevel;
+    method: KiauthMethod;
+    /** ISO timestamp of the identity check, or null. */
+    verified_at: string | null;
+    /** ISO timestamp after which the assurance must be renewed, or null. */
+    verification_expires_at: string | null;
+    /** @deprecated Alias of `verification_expires_at`. */
+    verificationExpiry: string | null;
+    /** Whole days since the identity check. Null when never verified. */
+    assurance_age_days: number | null;
+    /** Whether the check is within Kiauth's current freshness window. */
+    assurance_fresh: boolean;
+    /**
+     * TRUE for an identity fabricated by Kiauth's test mode. A production app MUST
+     * reject these — a test identity can never satisfy `assurance_level: 'aadhaar'`.
+     */
+    is_test_identity: boolean;
+    /**
+     * Kiauth's guarantee: one real human holds at most one account at your app — not
+     * even by deleting their Kiauth account and re-registering.
+     */
+    uniqueness: 'one_account_per_human';
+    /**
+     * Stable and 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.
+     */
     userToken: string;
-    verificationExpiry: string;
 }
 export interface ButtonStyleOptions {
     text?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kiauth/web-sdk",
-  "version": "1.0.0",
-  "description": "Kiauth Business Web SDK",
+  "version": "1.1.0",
+  "description": "Kiauth Web SDK — verified-human signup, passwordless login, and cross-app session management",
   "publishConfig": {
     "access": "public"
   },