Fix: Particle Network Iframe Server Key Part Missing

If your application console returns the [Particle Auth] Error: Server key part missing. Fallback triggered stack trace, your infrastructure has failed to load the necessary cryptographic threshold element.

Diagnostic Error State

TypeError: Cannot read properties of undefined (reading 'server_key_part')
    at MPCProvider.loadRemoteShare (particle-auth-core.js:84:21)
    at async MPCProvider.initialize (particle-auth-core.js:102:5)

Immediate Fix: Navigate to the Particle Network Dashboard and verify that your App ID and Client Key are correctly mapped to your current deployment domain. You must initialize the client strictly within a validated WebAuthn origin; mismatched CORS headers or using localhost without an SSL proxy will halt the remote share retrieval loop.

Architectural Context: MPC Shards and Threshold Schemes

Particle Network utilizes a sophisticated Multi-Party Computation (MPC) architecture to eliminate single points of failure in private key management. Unlike the windows 11 device-bound passkey export to mobile ethereum wallet which relies on a single hardware chip, Particle fragments key authority into a 2-of-3 Threshold Signature Scheme (TSS). This cryptographic approach ensures that the full private key is never reconstructed in a single memory space, mitigating the risk of memory scraping attacks or single-node compromises.

The underlying math often utilizes libraries like @noble/curves for efficient elliptic curve operations, specifically the secp256k1 curve used by Ethereum and Bitcoin. In a 2-of-3 setup, three secret shares are generated:

1. The Device Share: Encrypted and stored in the user’s local secure enclave (via WebAuthn) or indexed storage.
2. The Social/OAuth Share: Linked to the identity provider (Google, Apple, etc.) and managed via an OIDC flow.
3. The Server Share: Residing in Particle’s distributed Hardware Security Modules (HSMs).

The “Server Key Part Missing” error signifies a failure in the Remote Share Retrieval Protocol. When the SDK initializes, it triggers an iframe-based handshake. This iframe serves as a “trusted execution environment” within the browser, isolated by the Same-Origin Policy. It attempts to authenticate the session using the social provider’s JWT and the application’s unique projectId. If the server-side HSM determines that the request origin does not match the dashboard configuration, it refuses to release the encrypted server share.

Furthermore, this architecture integrates with modern account abstraction frameworks. Using viem or ethers.js, developers often wrap the Particle provider to interact with ERC-4337 Smart Accounts. If the server_key_part is missing, the signature generated by the SDK will be mathematically invalid, causing the EntryPoint contract on-chain to revert with an AA24 signature error. This deep dependency chain makes the initial handshake the most critical “zero-knowledge” moment of the user session.

The Role of WebAuthn and FIDO2

When the user opts for passkey-based recovery, the WebAuthn API becomes the primary gatekeeper for the Device Share. The browser invokes navigator.credentials.get(), which prompts the hardware (FaceID, TouchID, or Yubikey) to sign a challenge. This signature is then used as a decryption key for the local share. The “Server Key Part” failure often occurs when the WebAuthn origin (e.g., auth.your-dapp.com) differs from the API request origin, causing a mismatch in the cross-origin resource sharing (CORS) preflight checks.

Production-Grade Prevention: Implementation Manual

To ensure 99.9% uptime for MPC shard retrieval, developers must move beyond basic initialization and implement a robust environment schema and Content Security Policy (CSP).

1. Robust Environment Configuration

Avoid hardcoding sensitive identifiers. Use a structured environment schema to manage different stages of the MPC lifecycle.

// env.schema.ts
import { z } from 'zod';

export const particleConfigSchema = z.object({
  PROJECT_ID: z.string().uuid(),
  CLIENT_KEY: z.string().min(32),
  APP_ID: z.string().uuid(),
  CHAIN_ID: z.number().default(1),
  ENV: z.enum(['development', 'production', 'staging']),
});

// Implementation in your App initialization
const config = particleConfigSchema.parse({
  PROJECT_ID: process.env.NEXT_PUBLIC_PARTICLE_PROJECT_ID,
  CLIENT_KEY: process.env.NEXT_PUBLIC_PARTICLE_CLIENT_KEY,
  APP_ID: process.env.NEXT_PUBLIC_PARTICLE_APP_ID,
});

2. Content Security Policy (CSP) Requirements

The Particle SDK injects an iframe that communicates with static.particle.network and api.particle.network. Without the correct CSP headers, the browser will block the shard retrieval. Ensure your headers include:

Content-Security-Policy: 
  default-src 'self'; 
  script-src 'self' 'unsafe-inline' https://static.particle.network; 
  connect-src 'self' https://api.particle.network wss://*.particle.network; 
  frame-src 'self' https://static.particle.network; 
  img-src 'self' data: https://static.particle.network;

3. Detailed Error Boundary Strategy

Instead of a generic error message, implement a granular recovery flow. If the server share fails, it is often due to a network interruption or an expired session.

import { ParticleNetwork } from '@particle-network/auth';

const particle = new ParticleNetwork({
  projectId: config.PROJECT_ID,
  clientKey: config.CLIENT_KEY,
  appId: config.APP_ID,
  chainName: 'Ethereum',
  chainId: config.CHAIN_ID,
});

async function safeInitialize() {
  try {
    const userInfo = await particle.auth.login();
    console.log('User authenticated, MPC shards active');
  } catch (error: any) {
    if (error.code === 4001) {
       // User rejected the login
       handleUserRejection();
    } else if (error.message.includes('server_key_part')) {
       // CRITICAL: Server share retrieval failed
       console.error('Handshake Failure: Check Dashboard Whitelist and CORS');
       notifySentry(error);
       triggerFallbackAuth();
    }
  }
}

4. Domain Verification Checklist

Before moving to production, verify the following in the Particle Dashboard:

• Exact Origin Match: https://app.example.com is different from https://www.app.example.com.
• Protocol Security: Particle rejects http origins except for localhost.
• Subdomain Wildcards: If using dynamic subdomains, ensure the root domain is verified and contact Particle support for wildcard shard access.

Cryptographic Security Policies and HSM Integration

The server-side component of the MPC share is governed by strict Access Control Lists (ACLs) within Particle’s HSM infrastructure. When your application requests the server_key_part, the HSM performs a multi-stage validation:

1. Origin Validation: Checks the Origin and Referer headers against the registered App ID.
2. Signature Verification: Validates the social provider’s JWT (e.g., Google’s id_token) to ensure the user is who they claim to be.
3. Timestamp Replay Protection: Ensures the request is fresh and hasn’t been intercepted and replayed by a malicious actor.

By understanding this backend flow, developers can better diagnose failures. For instance, if a user’s system clock is significantly out of sync, the HSM may reject the request due to timestamp divergence, resulting in the “Server Key Part Missing” error even if the origin is correct.

Advanced FAQ Layer

Q1: Can I recover a wallet if Particle Network’s server share is permanently unavailable? In a standard 2-of-3 TSS setup, if the server share is gone, you can still reconstruct the key using the Device Share and the Social Share. Particle provides a “Self-Custody Recovery” tool where users can input these two shards to export their full private key (BIP-39 mnemonic or Hex). This ensures that even if Particle’s infrastructure is offline, user funds are not trapped.

Q2: How does the SDK handle the “Split-Brain” scenario where two different device shares exist? Particle uses a versioning system for MPC shards. When a user creates a new passkey or logs in from a new device, a “Share Synchronization” event is triggered. The HSM coordinates with the client to ensure the most recent valid shard (based on the last_updated_at metadata) is used. If synchronization fails, the SDK triggers a ShareCollisionError, requiring the user to re-authenticate via the primary social provider.

Q3: Is the server_key_part sensitive if intercepted during the iframe handshake? The server_key_part is encrypted using a transport key derived from a Diffie-Hellman exchange between the SDK iframe and the HSM. Even if an attacker intercepts the network traffic, the shard is useless without the transport key and the other 1-of-2 required shares (Device or Social). This layered encryption approach is why Particle is considered significantly more secure than traditional “cloud-stored” private keys.