x511

TypeScript SDK for gating HTTP requests behind privacy-preserving identity verification.

It supports two providers:

• self
• zkpassport

When a request is not yet verified, x511 returns a verification state that can be rendered as an HTML challenge page. After successful verification, the SDK issues a short-lived claim cookie and lets the original request continue.

What It Does

x511 helps you protect a route or group of routes with checks such as:

• minimum age
• allowed nationalities
• allowed or restricted issuing countries

The package provides:

• a core x511(config) factory
• framework adapters for Hono and Elysia
• an in-memory session adapter
• country-code helpers and common country groups

Install

pnpm add x511

You will also need one of the supported framework peer dependencies if you use the adapters:

pnpm add hono

or:

pnpm add elysia

Quick Start

import { x511 } from 'x511'

const gateway = x511({
  domain: 'https://example.com',
  providers: ['self', 'zkpassport'],
  disclosures: {
    minAge: 18,
  },
})

The returned object contains:

• verified(request) for checking whether an incoming request is already verified
• verify(request) for handling verification-related endpoints
• config with the resolved configuration

How The Flow Works

1. A protected request calls verified(request).
2. If the request is already verified, the result is { type: 'verified' }.
3. If not, the result is { type: 'pending' } with a generated session and provider payload.
4. Your app renders the built-in verification page or uses an adapter.
5. The client completes verification with Self or ZKPassport.
6. The provider callback reaches verify(request).
7. The SDK creates a short-lived claim cookie.
8. The browser reloads the original page.
9. A second call to verified(request) returns { type: 'verified' } and optionally exposes a hashed unique ID in the X-Verification-Id header.

Framework Adapters

The package includes adapters for:

• Hono via x511/adapter
• Elysia via x511/adapter

Both adapters:

• return the built-in verification page with HTTP status 511 when verification is pending
• continue the original request when verification succeeds
• set Set-Cookie and X-Verification-Id headers when available

Configuration

interface X511Config {
  domain: string
  basePath?: string
  dev?: boolean
  providers: ('self' | 'zkpassport')[]
  disclosures: {
    minAge: number
    nationality?: CountryFilter
    issuingState?: CountryFilter
  }
  sessionAdapter?: SessionAdapter
}

Required

• domain: public origin used in verification links, for example https://example.com
• providers: one or more providers; empty arrays are rejected
• disclosures.minAge: minimum age required for verification

Optional

• basePath: defaults to /
• dev: defaults to false
• disclosures.nationality
• disclosures.issuingState
• sessionAdapter

Country Filters

Country filters accept exactly one mode:

{ included: ['SVK', 'CZE'] }

or:

{ excluded: ['RUS', 'BLR'] }

Setting both included and excluded throws an error. Setting neither also throws an error.

Country Helpers

The package exposes country utilities from src/countries.ts:

• ALL_COUNTRIES
• EU_COUNTRIES
• EEA_COUNTRIES
• SCHENGEN_COUNTRIES
• ASEAN_COUNTRIES
• MERCOSUR_COUNTRIES
• AMERICAS_COUNTRIES
• X511Country

Example:

import { EU_COUNTRIES, x511 } from 'x511/core'

const gateway = x511({
  domain: 'https://example.com',
  providers: ['self'],
  disclosures: {
    minAge: 18,
    nationality: { included: EU_COUNTRIES },
  },
})

Session Storage

By default, x511 uses MemorySessionAdapter, which stores verification state in memory. That is fine for local development, but usually not enough for production because sessions disappear on process restart and are not shared across instances.

You can provide your own adapter by implementing:

interface SessionAdapter {
  has(sessionId: string): Promise<boolean>
  get(sessionId: string): Promise<string | undefined>
  set(sessionId: string, accessToken?: string): Promise<void>
  consume(sessionId: string): Promise<string | undefined>
}

consume() should return the stored value and delete it in one logical step.

Headers And Cookies

During successful completion, the SDK may use:

• Set-Cookie: x511=...
• X-Verification-Id: <sha256-hash>

Cookie behavior:

• cookie name is x511
• HttpOnly
• SameSite=Strict
• Path=/
• Secure is enabled unless dev === true

The verification ID is the SHA-256 hash of the provider’s unique identifier. The raw identifier is not returned directly.

Routes Handled By verify()

The core verifier handles these internal endpoints:

• GET /sse
• POST /verify/self
• POST /verify/zk
• POST /claim

If none matches, it returns 404.

Important: the built-in page uses basePath when calling these endpoints, but the current verify() implementation matches the raw path names listed above. If you mount the gateway under a non-root base path, your router may need to strip that prefix before forwarding the request to verify().

Exports

Current package exports from package.json:

• x511
• x511/core
• x511/adapter
• x511/countries
• x511/session

Development

pnpm install
pnpm build

Available scripts:

• pnpm build
• pnpm dev

Notes

• The package is ESM-only.
• @selfxyz/common and @zkpassport/sdk are loaded through createRequire() because of ESM compatibility issues noted in the source.
• There is currently no test suite in this repository.

License

MIT. See LICENSE.