Start here

Quickstart

Create one challenge on the host, open the VeilPass login surface, verify once, then establish an opaque cookie session.

Know what you are integrating

This is a Testnet MVP. The client package opens the hosted login UI, but your app must provide same-origin POST /api/challenges and POST /api/verify routes. Those are required by the current 0.2.x SDK and are not configurable. Your server is responsible for trusted origin/gate selection, durable atomic replay protection, the pinned cryptographic verifier and current gate policy, abuse controls, and your application's session.

Prerequisites

Use a modern browser with popup and Web Crypto support; open login from a user gesture. Deploy host and login pages on exact HTTPS origins (loopback HTTP is for local development only). For real Testnet enrollment, the user also needs Freighter on Stellar Testnet and a wallet eligible under the configured gate. The default public demo checks minimum native XLM and does not need a custom asset trustline. Run env:validate in the VeilPass operator repository before deploying that service; it prints issue codes only.

Install

Install the browser client and shared contracts. Pin versions in your lockfile and verify package contents before production rollout.

bash

npm install @veilpass/sdk @veilpass/shared

Client

Instantiate the SDK with your exact VeilPass login origin and call login from a button or other user gesture. A resolved result means the SDK received a successful response from your host's /api/verify route. Configure that host route to create your own server-side app session only after verification succeeds.

import { VeilPass } from "@veilpass/sdk";

const veilpass = new VeilPass({
  loginOrigin: "https://login.veilpass.dev",
});

const result = await veilpass.login({ gateId: "premium-holder" });
// result never contains the wallet address

Host server

The server package validates proof policy but intentionally leaves database, chain policy, cryptographic key loading, challenge issuance, HTTP routes, request limits, and app sessions to the integrator. Do not paste an in-memory store or always-true verifier into production. Review the mandatory consume contract, route requirements, and negative tests before shipping.

import { verifyVeilPassProof } from "@veilpass/server";

const verified = await verifyVeilPassProof({
  proofResult,
  expectedOrigin: "https://app.example",
  expectedGateId: "premium-holder",
  policy,
  store: durableChallengeStore,
  verifyProof: verifyNoirMembershipProof,
  requestId,
});

Before production

Run valid proof, wrong-origin, wrong-gate, expired proof, stale-root/epoch, revoked credential, spent challenge, concurrent replay, body-size, rate-limit, and session-cookie tests against your own deployed host origin. Confirm your logging/tracing provider does not capture POST /api/verify bodies. A passing SDK unit test is not proof that your host's adapters are production-ready.