@sparkvault/sdk 1.0.0 → 1.1.6

package/dist/identity/api.d.ts

@@ -63,7 +63,7 @@ export declare class IdentityApi {
      * Complete passkey registration
      */
     completePasskeyRegister(params: {
-        email: string;
+        session: Record<string, unknown>;
         credential: PublicKeyCredential;
     }): Promise<PasskeyVerifyResponse>;
     /**
@@ -74,7 +74,7 @@ export declare class IdentityApi {
      * Complete passkey verification
      */
     completePasskeyVerify(params: {
-        email: string;
+        session: Record<string, unknown>;
         credential: PublicKeyCredential;
     }): Promise<PasskeyVerifyResponse>;
     /**
@@ -86,7 +86,8 @@ export declare class IdentityApi {
      */
     getEnterpriseAuthUrl(provider: string, redirectUri: string, state: string): string;
     /**
-     * Send SparkLink email for identity verification
+     * Send SparkLink email for identity verification.
+     * Includes openerOrigin for postMessage-based completion notification.
      */
     sendSparkLink(email: string): Promise<SparkLinkSendResponse>;
     /**

package/dist/identity/renderer.d.ts

@@ -24,6 +24,7 @@ export declare class IdentityRenderer {
     private currentView;
     private focusTimeoutId;
     private pollingInterval;
+    private messageListener;
     constructor(container: Container, api: IdentityApi, options: VerifyOptions, callbacks: RendererCallbacks);
     private get recipient();
     private get identityType();
@@ -78,11 +79,17 @@ export declare class IdentityRenderer {
      */
     private handlePasskeyPromptSkip;
     /**
-     * Start polling for SparkLink verification status.
+     * Start listening for SparkLink verification completion.
+     * Uses postMessage as primary mechanism (instant notification from ceremony page),
+     * with polling as fallback for edge cases where postMessage might fail.
      */
     private startSparkLinkPolling;
     /**
-     * Stop SparkLink polling.
+     * Handle successful SparkLink verification (from either postMessage or polling).
+     */
+    private handleSparkLinkVerified;
+    /**
+     * Stop SparkLink polling and message listener.
      */
     private stopSparkLinkPolling;
     /**

package/dist/identity/types.d.ts

@@ -127,6 +127,8 @@ export interface PasskeyChallengeResponse {
         type: 'public-key';
     }>;
     timeout: number;
+    /** Session object to pass back in complete request */
+    session: Record<string, unknown>;
 }
 export interface PasskeyVerifyResponse {
     token: string;

package/dist/identity/views/icons.d.ts

@@ -28,6 +28,10 @@ export declare function createPasskeyIcon(): SVGSVGElement;
  * Error icon - clean triangle alert
  */
 export declare function createErrorIcon(): SVGSVGElement;
+/**
+ * Expired icon - grayscale triangle alert for expired states
+ */
+export declare function createExpiredIcon(): SVGSVGElement;
 /**
  * Method icons
  */

package/dist/identity/views/sparklink-waiting.d.ts

@@ -11,12 +11,15 @@ export interface SparkLinkWaitingViewProps {
     onResend: () => void;
     onFallback: () => void;
     onBack: () => void;
+    onExpired: () => void;
 }
 export declare class SparkLinkWaitingView implements View {
     private readonly props;
     private expirationTimer;
     private resendTimer;
     private countdownElement;
+    private countdownSection;
+    private waitingSection;
     private resendButton;
     private backLink;
     private fallbackButton;
@@ -28,6 +31,10 @@ export declare class SparkLinkWaitingView implements View {
     private createBackLink;
     private formatTime;
     private startExpirationTimer;
+    /**
+     * Switch to expired state - static icon, no animation, helpful message
+     */
+    private showExpiredState;
     private handleResend;
     destroy(): void;
 }

package/dist/sparkvault.cjs.js

@@ -730,7 +730,18 @@ class IdentityApi {
      * Start passkey registration
      */
     async startPasskeyRegister(email) {
-        return this.request('POST', '/passkey/register', { email });
+        // Backend returns { options: PublicKeyCredentialCreationOptions, session: {...} }
+        // Extract and flatten to match PasskeyChallengeResponse
+        const response = await this.request('POST', '/passkey/register', { email });
+        return {
+            challenge: response.options.challenge,
+            rpId: response.options.rp.id,
+            rpName: response.options.rp.name,
+            userId: response.options.user.id,
+            userName: response.options.user.name,
+            timeout: response.options.timeout,
+            session: response.session,
+        };
     }
     /**
      * Complete passkey registration
@@ -738,7 +749,7 @@ class IdentityApi {
     async completePasskeyRegister(params) {
         const attestation = params.credential.response;
         return this.request('POST', '/passkey/register/complete', {
-            email: params.email,
+            session: params.session,
             credential: {
                 id: params.credential.id,
                 rawId: arrayBufferToBase64url(params.credential.rawId),
@@ -754,7 +765,17 @@ class IdentityApi {
      * Start passkey verification
      */
     async startPasskeyVerify(email) {
-        return this.request('POST', '/passkey/verify', { email });
+        // Backend returns { options: PublicKeyCredentialRequestOptions, session: {...} }
+        // Extract and flatten to match PasskeyChallengeResponse
+        const response = await this.request('POST', '/passkey/verify', { email });
+        return {
+            challenge: response.options.challenge,
+            rpId: response.options.rpId,
+            rpName: 'SparkVault Identity', // Not returned by verify endpoint
+            timeout: response.options.timeout,
+            allowCredentials: response.options.allowCredentials,
+            session: response.session,
+        };
     }
     /**
      * Complete passkey verification
@@ -762,7 +783,7 @@ class IdentityApi {
     async completePasskeyVerify(params) {
         const assertion = params.credential.response;
         return this.request('POST', '/passkey/verify/complete', {
-            email: params.email,
+            session: params.session,
             credential: {
                 id: params.credential.id,
                 rawId: arrayBufferToBase64url(params.credential.rawId),
@@ -799,12 +820,16 @@ class IdentityApi {
         return `${this.baseUrl}/saml/${provider}?${params}`;
     }
     /**
-     * Send SparkLink email for identity verification
+     * Send SparkLink email for identity verification.
+     * Includes openerOrigin for postMessage-based completion notification.
      */
     async sendSparkLink(email) {
         return this.request('POST', '/sparklink/send', {
             email,
             type: 'verify_identity',
+            // Send opener origin for postMessage on verification completion
+            // This allows the ceremony page to notify the SDK directly instead of polling
+            openerOrigin: typeof window !== 'undefined' ? window.location.origin : undefined,
         });
     }
     /**
@@ -1247,15 +1272,15 @@ class PasskeyHandler {
      */
     async register() {
         try {
-            const challenge = await this.api.startPasskeyRegister(this.state.recipient);
+            const challengeResponse = await this.api.startPasskeyRegister(this.state.recipient);
             const publicKeyOptions = {
-                challenge: base64urlToArrayBuffer(challenge.challenge),
+                challenge: base64urlToArrayBuffer(challengeResponse.challenge),
                 rp: {
-                    id: challenge.rpId,
-                    name: challenge.rpName,
+                    id: challengeResponse.rpId,
+                    name: challengeResponse.rpName,
                 },
                 user: {
-                    id: base64urlToArrayBuffer(challenge.userId ?? this.state.recipient),
+                    id: base64urlToArrayBuffer(challengeResponse.userId ?? this.state.recipient),
                     name: this.state.recipient,
                     displayName: this.state.recipient,
                 },
@@ -1263,7 +1288,7 @@ class PasskeyHandler {
                     { type: 'public-key', alg: -7 }, // ES256
                     { type: 'public-key', alg: -257 }, // RS256
                 ],
-                timeout: challenge.timeout,
+                timeout: challengeResponse.timeout,
                 authenticatorSelection: {
                     residentKey: 'preferred',
                     userVerification: 'preferred',
@@ -1281,7 +1306,7 @@ class PasskeyHandler {
                 };
             }
             const response = await this.api.completePasskeyRegister({
-                email: this.state.recipient,
+                session: challengeResponse.session,
                 credential,
             });
             // Update state - user now has a passkey
@@ -1304,13 +1329,13 @@ class PasskeyHandler {
      */
     async verify() {
         try {
-            const challenge = await this.api.startPasskeyVerify(this.state.recipient);
+            const challengeResponse = await this.api.startPasskeyVerify(this.state.recipient);
             const publicKeyOptions = {
-                challenge: base64urlToArrayBuffer(challenge.challenge),
-                rpId: challenge.rpId,
-                timeout: challenge.timeout,
+                challenge: base64urlToArrayBuffer(challengeResponse.challenge),
+                rpId: challengeResponse.rpId,
+                timeout: challengeResponse.timeout,
                 userVerification: 'preferred',
-                allowCredentials: challenge.allowCredentials?.map((cred) => ({
+                allowCredentials: challengeResponse.allowCredentials?.map((cred) => ({
                     id: base64urlToArrayBuffer(cred.id),
                     type: cred.type,
                     transports: ['internal', 'hybrid', 'usb', 'ble', 'nfc'],
@@ -1327,7 +1352,7 @@ class PasskeyHandler {
                 };
             }
             const response = await this.api.completePasskeyVerify({
-                email: this.state.recipient,
+                session: challengeResponse.session,
                 credential,
             });
             return {
@@ -1735,7 +1760,7 @@ function getStyles(options) {
        ======================================== */
 
     .sv-body {
-      padding: 20px;
+      padding: 24px;
       overflow-y: auto;
       flex: 1;
     }
@@ -2468,6 +2493,36 @@ function getStyles(options) {
       color: ${tokens.textSecondary};
     }
 
+    /* SparkLink Expired State */
+    .sv-sparklink-expired {
+      flex-direction: column;
+      gap: 12px;
+      background: ${tokens.bgSubtle};
+      border: 1px solid ${tokens.border};
+    }
+
+    .sv-sparklink-expired-icon {
+      display: flex;
+      justify-content: center;
+    }
+
+    .sv-sparklink-expired-icon svg {
+      width: 48px;
+      height: 48px;
+    }
+
+    .sv-sparklink-expired-text {
+      font-size: 14px;
+      font-weight: 500;
+      color: ${tokens.textSecondary};
+      text-align: center;
+    }
+
+    .sv-expired-icon {
+      width: 48px;
+      height: 48px;
+    }
+
     /* ========================================
        DIVIDER
        ======================================== */
@@ -2515,6 +2570,7 @@ function getStyles(options) {
     .sv-inline-container {
       display: flex;
       flex-direction: column;
+      height: 100%;
       background: ${tokens.bg};
       color: ${tokens.textPrimary};
       font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
@@ -2530,7 +2586,11 @@ function getStyles(options) {
     }
 
     .sv-inline-body {
+      display: flex;
+      flex-direction: column;
+      justify-content: center;
       min-height: 200px;
+      flex: 1;
     }
 
     /* ========================================
@@ -2549,7 +2609,7 @@ function getStyles(options) {
       }
 
       .sv-body {
-        padding: 20px;
+        padding: 24px;
       }
 
       .sv-totp-digit {
@@ -2693,6 +2753,32 @@ function createErrorIcon() {
     svg.appendChild(group);
     return svg;
 }
+/**
+ * Expired icon - grayscale triangle alert for expired states
+ */
+function createExpiredIcon() {
+    const svg = createSvgElement('0 0 48 48', 48, 48);
+    svg.classList.add('sv-expired-icon');
+    // Circle background - muted gray
+    svg.appendChild(createCircle(24, 24, 22, {
+        fill: '#F5F5F5',
+        stroke: '#E5E5E5',
+        'stroke-width': '1',
+    }));
+    // Alert triangle - gray
+    const group = document.createElementNS('http://www.w3.org/2000/svg', 'g');
+    group.setAttribute('transform', 'translate(10, 12)');
+    group.appendChild(createPath('M14 4L2 24h24L14 4z', { fill: '#737373' }));
+    // Exclamation
+    group.appendChild(createPath('M14 10v5', {
+        stroke: '#FFFFFF',
+        'stroke-width': '2',
+        'stroke-linecap': 'round',
+    }));
+    group.appendChild(createCircle(14, 19, 1, { fill: '#FFFFFF' }));
+    svg.appendChild(group);
+    return svg;
+}
 /**
  * Method icons
  */
@@ -4025,6 +4111,8 @@ class SparkLinkWaitingView {
         this.expirationTimer = null;
         this.resendTimer = null;
         this.countdownElement = null;
+        this.countdownSection = null;
+        this.waitingSection = null;
         this.resendButton = null;
         this.backLink = null;
         this.fallbackButton = null;
@@ -4043,7 +4131,7 @@ class SparkLinkWaitingView {
         subtitle.className = 'sv-subtitle';
         subtitle.innerHTML = `We sent a secure link to<br><strong>${escapeHtml(this.props.email)}</strong>`;
         // Spinner with message
-        const waitingSection = div('sv-sparklink-waiting');
+        this.waitingSection = div('sv-sparklink-waiting');
         const spinner = document.createElement('div');
         spinner.className = 'sv-spinner sv-spinner-small';
         spinner.setAttribute('role', 'status');
@@ -4051,17 +4139,17 @@ class SparkLinkWaitingView {
         const waitingText = document.createElement('span');
         waitingText.className = 'sv-sparklink-waiting-text';
         waitingText.textContent = 'Waiting for you to click the link...';
-        waitingSection.appendChild(spinner);
-        waitingSection.appendChild(waitingText);
+        this.waitingSection.appendChild(spinner);
+        this.waitingSection.appendChild(waitingText);
         // Countdown timer
-        const countdownSection = div('sv-sparklink-countdown');
+        this.countdownSection = div('sv-sparklink-countdown');
         const countdownLabel = document.createElement('span');
         countdownLabel.textContent = 'Link expires in ';
         this.countdownElement = document.createElement('span');
         this.countdownElement.className = 'sv-sparklink-countdown-time';
         this.startExpirationTimer();
-        countdownSection.appendChild(countdownLabel);
-        countdownSection.appendChild(this.countdownElement);
+        this.countdownSection.appendChild(countdownLabel);
+        this.countdownSection.appendChild(this.countdownElement);
         // Resend button
         const resendContainer = div('sv-resend-container');
         this.resendButton = document.createElement('button');
@@ -4079,8 +4167,8 @@ class SparkLinkWaitingView {
         container.appendChild(this.backLink);
         container.appendChild(title);
         container.appendChild(subtitle);
-        container.appendChild(waitingSection);
-        container.appendChild(countdownSection);
+        container.appendChild(this.waitingSection);
+        container.appendChild(this.countdownSection);
         container.appendChild(resendContainer);
         container.appendChild(fallbackContainer);
         return container;
@@ -4122,13 +4210,36 @@ class SparkLinkWaitingView {
                 this.countdownElement.textContent = this.formatTime(secondsRemaining);
             },
             onExpired: () => {
-                if (!this.countdownElement)
-                    return;
-                this.countdownElement.textContent = 'Expired';
+                this.showExpiredState();
             },
         });
         this.expirationTimer.start();
     }
+    /**
+     * Switch to expired state - static icon, no animation, helpful message
+     */
+    showExpiredState() {
+        // Notify renderer to stop polling
+        this.props.onExpired();
+        // Update waiting section: replace spinner with expired icon
+        if (this.waitingSection) {
+            this.waitingSection.innerHTML = '';
+            this.waitingSection.classList.add('sv-sparklink-expired');
+            // Add expired icon
+            const iconContainer = div('sv-sparklink-expired-icon');
+            iconContainer.appendChild(createExpiredIcon());
+            this.waitingSection.appendChild(iconContainer);
+            // Add expired message
+            const expiredText = document.createElement('span');
+            expiredText.className = 'sv-sparklink-expired-text';
+            expiredText.textContent = 'This link has expired';
+            this.waitingSection.appendChild(expiredText);
+        }
+        // Hide countdown section
+        if (this.countdownSection) {
+            this.countdownSection.style.display = 'none';
+        }
+    }
     handleResend() {
         if (this.resendTimer?.isRunning() || !this.resendButton)
             return;
@@ -4255,8 +4366,9 @@ class IdentityRenderer {
         // View management
         this.currentView = null;
         this.focusTimeoutId = null;
-        // SparkLink polling
+        // SparkLink polling and postMessage listener
         this.pollingInterval = null;
+        this.messageListener = null;
         this.container = container;
         this.api = api;
         this.options = options;
@@ -4378,7 +4490,11 @@ class IdentityRenderer {
         this.currentView = view;
         clearChildren(body);
         body.appendChild(view.render());
-        const focusable = body.querySelector('input:not([disabled]), button:not([disabled])');
+        // Auto-focus: prefer inputs first, then primary/method buttons (skip back links)
+        const focusable = body.querySelector('input:not([disabled]), ' +
+            'button.sv-btn-primary:not([disabled]), ' +
+            'button.sv-btn-email-primary:not([disabled]), ' +
+            'button.sv-btn-method:not([disabled])');
         if (focusable) {
             // Clear any previous focus timeout to avoid stacking
             if (this.focusTimeoutId !== null) {
@@ -4451,6 +4567,7 @@ class IdentityRenderer {
                     onResend: () => this.handleSparkLinkResend(),
                     onFallback: () => this.handleSparkLinkFallback(),
                     onBack: () => this.showMethodSelect(),
+                    onExpired: () => this.stopSparkLinkPolling(),
                 });
             case 'oauth-pending':
                 return new LoadingView({ message: `Connecting to ${state.provider}...` });
@@ -4793,41 +4910,73 @@ class IdentityRenderer {
         this.callbacks.onSuccess(pendingResult);
     }
     /**
-     * Start polling for SparkLink verification status.
+     * Start listening for SparkLink verification completion.
+     * Uses postMessage as primary mechanism (instant notification from ceremony page),
+     * with polling as fallback for edge cases where postMessage might fail.
      */
     startSparkLinkPolling(sparkId) {
         this.stopSparkLinkPolling();
+        // Primary: Listen for postMessage from ceremony page
+        // This is faster and more reliable than polling
+        this.messageListener = (event) => {
+            // Validate message structure and type
+            if (!event.data || typeof event.data !== 'object')
+                return;
+            if (event.data.type !== 'sparklink_verified')
+                return;
+            const { token, identity, identityType } = event.data;
+            // Validate required fields
+            if (!token || !identity)
+                return;
+            this.handleSparkLinkVerified({
+                token,
+                identity,
+                identityType: identityType || 'email',
+            });
+        };
+        window.addEventListener('message', this.messageListener);
+        // Fallback: Poll status endpoint every 2 seconds
+        // This catches cases where postMessage might not work (popup blockers, etc)
         this.pollingInterval = setInterval(async () => {
             const status = await this.sparkLinkHandler.checkStatus(sparkId);
             if (status.verified && status.token && status.identity) {
-                this.stopSparkLinkPolling();
-                const result = {
+                this.handleSparkLinkVerified({
                     token: status.token,
                     identity: status.identity,
                     identityType: status.identityType || 'email',
-                };
-                // Check if we should prompt for passkey registration
-                if (await this.shouldShowPasskeyPrompt()) {
-                    this.setState({
-                        view: 'passkey-prompt',
-                        email: this.recipient,
-                        pendingResult: result,
-                    });
-                    return;
-                }
-                this.close();
-                this.callbacks.onSuccess(result);
+                });
             }
         }, 2000);
     }
     /**
-     * Stop SparkLink polling.
+     * Handle successful SparkLink verification (from either postMessage or polling).
+     */
+    async handleSparkLinkVerified(result) {
+        this.stopSparkLinkPolling();
+        // Check if we should prompt for passkey registration
+        if (await this.shouldShowPasskeyPrompt()) {
+            this.setState({
+                view: 'passkey-prompt',
+                email: this.recipient,
+                pendingResult: result,
+            });
+            return;
+        }
+        this.close();
+        this.callbacks.onSuccess(result);
+    }
+    /**
+     * Stop SparkLink polling and message listener.
      */
     stopSparkLinkPolling() {
         if (this.pollingInterval) {
             clearInterval(this.pollingInterval);
             this.pollingInterval = null;
         }
+        if (this.messageListener) {
+            window.removeEventListener('message', this.messageListener);
+            this.messageListener = null;
+        }
     }
     /**
      * Handle resending SparkLink.