@sigilo/verify

Privacy-preserving age verification. Relying-party SDK.

sigilo (n., Sp./Pt.) — secrecy; discretion; the practice of keeping a matter unspoken. From Latin sigillum, "a small seal."

Sigilo is a privacy-preserving age verification network. It lets your users prove they meet an age threshold (over 13, 16, 18, 21, 25) without revealing their identity, date of birth, document, or any correlatable identifier — to you, to Sigilo, or to anyone else.

This package is the relying-party SDK. Drop it into your website to age-gate a flow. A second module, @sigilo/verify/server, performs the server-side verification that must back every client-side check.

Release status

⚠️ This is the v0.0.1 namespace-reservation release. The API surface below is stable and reflects the intended production shape, but the network and cryptographic operations are stubbed: every call to verify() throws SigiloError("server_error") with a pointer to our status page.

Real cryptography (BBS+ proofs over W3C Verifiable Credentials, via audited libraries) ships in v0.2. The first production-ready release will be versioned >=1.0 and will follow an independent security audit by Trail of Bits, NCC Group, or Cure53.

Do not use this package in production until v1.0. Track release progress at sigilo.id/status.

Install

npm install @sigilo/verify

Browser usage

import { Sigilo, SigiloError } from "@sigilo/verify";

const sigilo = new Sigilo({
  publishableKey: "pk_live_...",  // from your Sigilo dashboard
  predicate: "over_18",
  assurance: "high",              // "estimation" | "standard" | "high"
});

try {
  const result = await sigilo.verify();
  if (result.verified) {
    // POST result.presentation to your server for verification.
    // Do not trust this client-side result as authoritative.
    await fetch("/api/age-check", {
      method: "POST",
      body: JSON.stringify({ presentation: result.presentation }),
    });
  }
} catch (e) {
  if (e instanceof SigiloError) {
    switch (e.code) {
      case "user_denied":
        // show a friendly "couldn't verify your age" message
        break;
      case "no_wallet":
        // walk the user through wallet setup
        break;
      default:
        // log e.code; never expose it to the user
    }
  }
}

Server usage

import { verifyPresentation, SigiloError } from "@sigilo/verify/server";

app.post("/api/age-check", async (req, res) => {
  try {
    const verified = await verifyPresentation(process.env.SIGILO_SECRET!, {
      presentation: req.body.presentation,
      expectedPredicate: "over_18",
      minAssurance: "high",
      expectedNonce: req.session.verificationNonce,
    });
    // Trust ONLY this server-side result.
    // verified.predicate is "over_18"; verified.assurance >= "high".
    req.session.ageVerified = true;
    res.json({ ok: true });
  } catch (e) {
    res.status(403).json({ ok: false });
  }
});

What you receive — and what you don't

When verify() succeeds, you receive:

| Field | Example | What it tells you | |---|---|---| | verified | true | The proof was valid | | predicate | "over_18" | What was proven (echoes your request) | | assurance | "high" | The actual tier delivered (≥ requested) | | proofId | "proof_4kZ..." | Opaque audit identifier | | nonce | "n_..." | Replay-protection nonce (verify server-side) | | presentation | "eyJ..." | The cryptographic proof for server-side verification |

You do not receive: the user's name, date of birth, document number, biometric, issuer identity, or any cross-site identifier. Two verifications by the same user — at your site or at any other site in the network — produce presentations that are cryptographically unlinkable.

API reference

class Sigilo

new Sigilo(config: SigiloConfig)

Methods

• verify(): Promise<VerificationResult> — initiate a verification. Throws SigiloError on any failure.
• cancel(): void — cancel any in-flight verification. Idempotent.
• get state(): VerificationState — the current lifecycle state.

verifyPresentation(secretKey, options)

import { verifyPresentation } from "@sigilo/verify/server";

verifyPresentation(secretKey: string, options: VerifyPresentationOptions): Promise<VerifiedPresentation>

Required server-side. Never trust the client SDK's verified: true alone.

class SigiloError extends Error

All thrown errors are instances. Inspect .code for stable machine-readable error identification.

| Code | Meaning | |---|---| | user_denied | User explicitly denied the request | | user_canceled | User closed their wallet without responding | | timeout | Wallet did not respond within the protocol window | | no_wallet | User has no Sigilo-compatible wallet | | assurance_unmet | User's credential cannot meet the requested tier | | invalid_config | Publishable/secret key, predicate, or tier invalid | | network_error | Transport failure | | rate_limited | Too many requests from this RP | | server_error | Network-side fault |

Security

Found a security issue? Please do not open a public GitHub issue. Email [email protected]. PGP key fingerprint and disclosure policy at sigilo.id/security.

See SECURITY.md for our disclosure policy and THREAT_MODEL.md for the network's threat model.

Standards

Sigilo builds on:

• W3C Verifiable Credentials Data Model
• OpenID for Verifiable Presentations (OpenID4VP)
• BBS+ Signatures
• ISO/IEC 18013-5 (mobile driving licence)
• eIDAS 2.0 / EUDI Wallet ARF

We do not invent cryptography. We integrate audited implementations and provide the network layer, issuer trust framework, and developer experience above them.

License

Apache 2.0

Built with sigilo — proof, in confidence.