Wallet sign-in SDK

// This example is handled by the browser bundler; never create a billing-key client in the browser.
async function appJson(path, body, request) {
  const response = await request(path, {
    method: 'POST', credentials: 'same-origin',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body)
  });
  const payload = await response.json();
  if (!response.ok || payload.code !== 1) {
    const error = new Error(payload.message || 'sign-in request did not succeed, please try again');
    error.fromApp = true;
    throw error;
  }
  return payload.data;
}

export async function signInWithProvider({ ethereum = window.ethereum, request = fetch } = {}) {
  if (!ethereum) throw new Error('no wallet detected; install a wallet or choose QR sign-in');
  try {
    const accounts = await ethereum.request({ method: 'eth_requestAccounts' });
    const address = accounts[0];
    if (!/^0x[0-9a-fA-F]{40}$/.test(address || '')) throw new Error('invalid wallet account');
    const chain = await ethereum.request({ method: 'eth_chainId' });
    if (Number(chain) !== 1) {
      const error = new Error('switch the wallet to Ethereum mainnet, then connect again');
      error.fromApp = true;
      throw error;
    }
    const challenge = await appJson('/api/connect/session', { address }, request);
    // use the message exactly as issued; never rebuild the domain, nonce or expiry yourself.
    const bytes = new TextEncoder().encode(challenge.message);
    const hex = '0x' + Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
    const signature = await ethereum.request({ method: 'personal_sign', params: [hex, address] });
    return await appJson('/api/connect/verify', {
      sessionId: challenge.sessionId, nonce: challenge.nonce,
      message: challenge.message, address, signature
    }, request);
  } catch (error) {
    if (error.code === 4001) throw new Error('the user cancelled the wallet connection or signature; please start again');
    if (error.fromApp) throw error;
    throw new Error('wallet connection or signature failed; check the wallet prompt and your network, then retry');
  }
}
// call this from your connect button handler: await signInWithProvider().

import express from 'express';
import { randomBytes } from 'node:crypto';
import { createClient } from '@chainshield/nexus-sdk';

export function createConnectApp({
  apiKey = process.env.CS_API_KEY, baseUrl = process.env.CS_BASE_URL,
  origin = process.env.APP_ORIGIN, client
} = {}) {
  if (!apiKey || !baseUrl || !origin) throw new Error('set the server key, platform URL and app origin first');
  const site = new URL(origin);
  if (site.origin !== origin || (site.protocol !== 'https:' && !(site.protocol === 'http:' && ['localhost', '127.0.0.1'].includes(site.hostname)))) {
    throw new Error('the app origin must be HTTPS; local development may use http://localhost or http://127.0.0.1');
  }
  const nexus = client || createClient({ apiKey, baseUrl, retries: 0 });
  const app = express();
  app.use(express.json({ limit: '16kb' }));
  // single-instance example: in production use a shared persistent session store and keep the challenge binding rules below.
  const sessions = new Map();
  const cookieOptions = { httpOnly: true, sameSite: 'strict', secure: site.protocol === 'https:', path: '/', maxAge: 600000 };
  const replyError = (res, status, message) => res.status(status).json({ code: 'APP_CONNECT_ERROR', message });
  app.use((req, res, next) => {
    res.set('Cache-Control', 'no-store');
    if (req.method === 'POST' && (req.get('Origin') !== origin || !req.is('application/json'))) {
      return replyError(res, 403, 'wrong request origin or content type; start again from the app page');
    }
    for (const [key, value] of sessions) if (value.expiresAt <= Date.now()) sessions.delete(key);
    const rawCookie = String(req.headers.cookie || '').split(';').map(x => x.trim()).find(x => x.startsWith('cs_doc_session='));
    let token = rawCookie ? rawCookie.slice('cs_doc_session='.length) : '';
    let state = sessions.get(token);
    if (!state) {
      if (sessions.size >= 1000) return replyError(res, 503, 'too many connection requests; try again shortly');
      token = randomBytes(32).toString('hex');
      state = { expiresAt: Date.now() + 600000, pending: null, authenticated: null };
      sessions.set(token, state);
      res.cookie('cs_doc_session', token, cookieOptions);
    }
    req.connectState = state;
    req.connectToken = token;
    next();
  });
  const route = handler => (req, res, next) => Promise.resolve(handler(req, res)).catch(next);
  app.post('/api/connect/session', route(async (req, res) => {
    const address = req.body.address;
    if (!/^0x[0-9a-fA-F]{40}$/.test(address || '')) return replyError(res, 400, 'provide a real wallet address');
    const challenge = await nexus.connect.createSession({
      domain: site.host, origin, chainId: 1, namespace: 'eip155', connectorKey: 'injected', address,
      statement: 'Sign in to the example app. This signature does not send an on-chain transaction.'
    });
    if (sessions.get(req.connectToken) !== req.connectState || req.connectState.expiresAt <= Date.now()) {
      return replyError(res, 409, 'the app session changed; reconnect the wallet');
    }
    req.connectState.pending = { ...challenge, address };
    res.json({ code: 1, data: challenge });
  }));
  app.post('/api/connect/verify', route(async (req, res) => {
    const pending = req.connectState.pending;
    if (!pending || (pending.nonceExpiresAt && Date.parse(pending.nonceExpiresAt) <= Date.now())) {
      return replyError(res, 400, 'this app session has no valid challenge; reconnect the wallet');
    }
    for (const key of ['sessionId', 'nonce', 'message', 'address']) {
      if (req.body[key] !== undefined && req.body[key] !== pending[key]) return replyError(res, 400, 'the challenge changed; use the original message created in this session');
    }
    const result = await nexus.connect.verifySiwe({
      sessionId: pending.sessionId, nonce: pending.nonce,
      message: pending.message, address: pending.address, signature: req.body.signature
    });
    // logout, a new challenge or session expiry must invalidate any in-flight verification.
    if (sessions.get(req.connectToken) !== req.connectState || req.connectState.pending !== pending ||
        req.connectState.expiresAt <= Date.now() || (pending.nonceExpiresAt && Date.parse(pending.nonceExpiresAt) <= Date.now())) {
      return replyError(res, 409, 'the app session or challenge changed; reconnect the wallet');
    }
    if (!result.ok || result.address.toLowerCase() !== pending.address.toLowerCase()) return replyError(res, 401, 'the signed identity does not match this wallet');
    const authenticated = { address: result.address, sessionId: pending.sessionId };
    // after sign-in, rotate your own app session; the platform verification result is not an app cookie or JWT.
    sessions.delete(req.connectToken);
    const token = randomBytes(32).toString('hex');
    sessions.set(token, { expiresAt: Date.now() + 600000, pending: null, authenticated });
    res.cookie('cs_doc_session', token, cookieOptions);
    res.json({ code: 1, data: { ...authenticated, verified: true } });
  }));
  app.get('/api/connect/state', route(async (req, res) => {
    const current = req.connectState.authenticated;
    if (!current) return replyError(res, 401, 'app sign-in is not complete; connect the wallet first');
    const platformState = await nexus.connect.getSession(current.sessionId);
    if (!platformState.verified || platformState.revoked || !['connected', 'disconnected'].includes(platformState.status)) {
      sessions.delete(req.connectToken);
      res.clearCookie('cs_doc_session', { httpOnly: true, sameSite: 'strict', secure: site.protocol === 'https:', path: '/' });
      return replyError(res, 401, 'the platform session is no longer valid; reconnect the wallet');
    }
    res.json({ code: 1, data: platformState });
  }));
  app.post('/api/connect/logout', route(async (req, res) => {
    const current = req.connectState.authenticated;
    sessions.delete(req.connectToken);
    res.clearCookie('cs_doc_session', { httpOnly: true, sameSite: 'strict', secure: site.protocol === 'https:', path: '/' });
    if (current) await nexus.connect.revokeSession(current.sessionId, 'user signed out of the app');
    res.json({ code: 1, data: { loggedOut: true } });
  }));
  app.use((error, req, res, next) => {
    const status = Number.isInteger(error.httpStatus) && error.httpStatus >= 400 && error.httpStatus <= 599 ? error.httpStatus : 500;
    replyError(res, status, status >= 500 ? 'the connect service is temporarily unavailable; try again shortly' : 'connect verification failed; recheck the wallet and the original challenge');
  });
  return app;
}
// listen only when this file is run directly (node server.mjs).
// no server starts when another module imports it: an exported module must not have import-time side effects,
// otherwise any import would bind port 3000 and the doc example execution check would fail.
if (process.argv && process.argv[1] && process.argv[1].endsWith('server.mjs')) {
  createConnectApp().listen(3000, '127.0.0.1', () => console.log('connect example listening; open it from the configured app origin'));
}

import { createWalletConnectPairing } from '@chainshield/nexus-sdk/browser';

// renderQr receives the real wc: URI and renders it with your own QR component; the SDK does not return qrSvg.
// signIn is the signInWithProvider above; metadata must use your app's real origin.
export async function signInWithWalletConnect({ projectId, metadata, renderQr, signIn, providerFactory, signal }) {
  if (typeof renderQr !== 'function' || typeof signIn !== 'function') throw new Error('provide a QR renderer and a sign-in handler');
  const pairing = await createWalletConnectPairing({
    projectId, metadata, chains: [1], timeoutMs: 120000, providerFactory, signal
  });
  try {
    if (pairing.uri) await renderQr(pairing.uri);
    // showing the QR code does not mean connected; only request a signature after approval resolves.
    const connection = await pairing.approval;
    const result = await signIn({ ethereum: connection.provider });
    return { ...result, disconnect: connection.disconnect };
  } catch (error) {
    await pairing.cancel();
    throw error;
  }
}
// projectId is the public WalletConnect relay project ID; never put a billing API key here.
// cancel scanning through the AbortController signal; call the returned disconnect on sign-out.