tpt-identity

Sovereign identity backbone for the TPT open-source ecosystem. Every person gets one DID that works across email, healthcare, payments, and civic systems — authenticated however makes sense for them.

What it does

DID management — create and resolve did:web, did:key, did:peer identifiers (optional: did:ion via build tag)
Verifiable Credentials — issue and verify W3C VC Data Model 2.0 with DataIntegrityProof (eddsa-jcs-2022) and SD-JWT selective disclosure
Consent receipts — cryptographically signed records of who accessed what, under what legal basis (NZ Privacy Act 2020 compliant)
OIDC Provider — authorization code flow with mandatory PKCE, dynamic client registration (RFC 7591), token introspection (RFC 7662), back-channel logout (OIDC BCL 1.0), client credentials grant (RFC 6749 §4.4), refresh token rotation
Identity bridges — accept Google, GitHub, Azure AD, SAML 2.0, LDAP/AD, magic link, password, and passkey (WebAuthn) auth; each maps to a platform DID
Account linking — one DID, multiple external auth providers
MFA — TOTP (RFC 6238) with AES-256-GCM encrypted secrets; brute-force lockout
Duress code — secondary passphrase that creates a normal session but fires a silent session.duress alert
Guardian recovery — M-of-N Shamir secret sharing so trusted guardians can recover a lost identity key
Verifiable audit log — every event is appended to a SHA-256 hash-chained log; tampering is detectable
Credential marketplace — discoverable registry of which issuers offer which credential schemas
Webhook events — push credential.issued, consent.granted, session.duress etc. to subscribers with HMAC-SHA256 signatures
Presentation Exchange — DIF PE v2 request/submit flow for structured credential requests
Inter-service trust — short-lived Ed25519-signed permits and federated reputation via DNS TXT or VC

Docker quickstart

# 1. Generate signing keys
mkdir -p keys
go run ./cmd/tpt-identity keygen --method web --domain example.com \
  --out-sign keys/ed25519.pem --out-enc keys/x25519.pem --passphrase ""

# 2. Copy and edit config
cp config.yaml.example config.yaml
# Set issuer, db_path, api_key, identity.signing_key, etc.

# 3. Build and start
docker compose up --build

# Server is now at http://localhost:8080

Binary quickstart

# Install
go install github.com/PhillipC05/tpt-identity/cmd/tpt-identity@latest

# 1. Generate keys
tpt-identity keygen --method web --domain example.com \
  --out-sign keys/ed25519.pem --out-enc keys/x25519.pem --passphrase ""

# 2. Edit config
cp config.yaml.example config.yaml

# 3. Run migrations
tpt-identity migrate up

# 4. Start server
tpt-identity serve --config config.yaml

Optional build tags

go build -tags "ion"           # include did:ion (Bitcoin/Sidetree)
go build -tags "saml"          # include SAML 2.0 identity bridge
go build -tags "ldap"          # include LDAP/Active Directory bridge
go build -tags "ion,saml,ldap" # all optional features

Integration guide (OIDC)

# Step 1: Register a client (once)
curl -s -X POST https://identity.example.com/oidc/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My App",
    "redirect_uris": ["https://myapp.example.com/callback"],
    "token_endpoint_auth_method": "none"
  }' | tee client.json

CLIENT_ID=$(jq -r .client_id client.json)

# Step 2: Generate PKCE verifier + challenge
VERIFIER=$(openssl rand -base64 32 | tr -d '=+/' | head -c 43)
CHALLENGE=$(echo -n "$VERIFIER" | sha256sum -b | xxd -r -p | base64 -w 0 | tr '+/' '-_' | tr -d '=')

# Step 3: Redirect user to /authorize
echo "https://identity.example.com/authorize?response_type=code\
&client_id=$CLIENT_ID\
&redirect_uri=https://myapp.example.com/callback\
&scope=openid\
&state=$(openssl rand -hex 16)\
&code_challenge=$CHALLENGE\
&code_challenge_method=S256"

# Step 4: Exchange code for tokens
curl -s -X POST https://identity.example.com/token \
  -d "grant_type=authorization_code" \
  -d "code=<code_from_callback>" \
  -d "redirect_uri=https://myapp.example.com/callback" \
  -d "client_id=$CLIENT_ID" \
  -d "code_verifier=$VERIFIER"

Webhook verification

Every webhook delivery includes an X-TPT-Signature-256 header:

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "net/http"
)

func verifyWebhook(r *http.Request, signingSecret string) bool {
    sig := r.Header.Get("X-TPT-Signature-256")
    body, _ := io.ReadAll(r.Body)
    mac := hmac.New(sha256.New, []byte(signingSecret))
    mac.Write(body)
    expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(sig), []byte(expected))
}

Configuration

Copy config.yaml.example to config.yaml. All keys can be overridden via environment variables prefixed TPT_IDENTITY_ (e.g. TPT_IDENTITY_API_KEY).

| Key | Description | |-----|-------------| | issuer | Canonical HTTPS URL — used as OIDC issuer and did:web base (required) | | listen_addr | HTTP bind address (default :8080) | | db_path | SQLite database file path | | api_key | Bearer token for admin/service endpoints | | identity.signing_key | Path to Ed25519 private key PEM | | identity.passphrase | Argon2id passphrase for key decryption | | totp_passphrase | Passphrase for TOTP secret encryption (defaults to identity.passphrase) | | rate_limit | Requests per second per IP (default 50) | | server.trusted_proxies | CIDR list of trusted reverse proxies for X-Forwarded-For | | cors.allowed_origins | Allowed CORS origins (empty = CORS disabled) | | bridges.oidc[] | OIDC relying-party bridges — name, issuer, client_id, client_secret, scopes | | bridges.password.enabled | Enable legacy password bridge (default false) | | consent.expiry_warning_days | Fire consent.expiring_soon events N days before expiry (default 7) | | marketplace.advertise | Enable the credential marketplace registry (default false) | | log.level | debug, info, warn, error (default info) | | log.format | json or text (default json) |

Deployment notes

HTTPS (required)

Run behind Caddy or nginx. Caddy example:

identity.example.com {
    reverse_proxy localhost:8080
}

SQLite WAL mode

The server enables WAL mode automatically. For best performance, mount the database on a local filesystem (not NFS). The store uses a single writer connection intentionally — do not set SetMaxOpenConns higher than 1.

Key file permissions

chmod 600 keys/ed25519.pem keys/x25519.pem

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                           tpt-identity                               │
│                                                                      │
│  ┌──────────────────── Identity Bridge ───────────────────────────┐  │
│  │ OIDC RP (Google/GitHub/Azure) │ Magic Link │ SAML† │ LDAP/AD† │  │
│  │ Password (opt-in) │ WebAuthn/Passkeys │ TOTP MFA                │  │
│  └────────────────────────────┬───────────────────────────────────┘  │
│                               │ ExternalIdentity → platform DID      │
│  ┌─────────┐  ┌────────────┐  ┌───────────┐  ┌──────────────────┐   │
│  │   DID   │  │  VC + SD-  │  │  Consent  │  │  OIDC Provider   │   │
│  │  layer  │  │    JWT     │  │ grants +  │  │ PKCE · RFC 7591  │   │
│  │ w/k/p/i │  │ issue/vrfy │  │ receipts  │  │ introspect · BCL │   │
│  └────┬────┘  └─────┬──────┘  └─────┬─────┘  └────────┬─────────┘   │
│       │              │               │                  │             │
│  ┌────┴──────────────┴───────────────┴──────────────────┴──────────┐  │
│  │              SQLite store (PostgreSQL-compatible schema)         │  │
│  └─────────────────────────────────────────────────────────────────┘  │
│                                                                      │
│  ┌───────────────────────────────────────────────────────────────┐   │
│  │  REST API · rate limit · audit log · webhook events · metrics  │   │
│  └───────────────────────────────────────────────────────────────┘   │
│  ┌──────────────────┐  ┌─────────────────┐  ┌─────────────────────┐  │
│  │  Duress alerts   │  │ Guardian recovery│  │  Credential market  │  │
│  └──────────────────┘  └─────────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘
 † requires build tag

API endpoints

Public — no auth required

| Method | Path | Description | |--------|------|-------------| | GET | /.well-known/openid-configuration | OIDC discovery document | | GET | /.well-known/jwks.json | JSON Web Key Set | | GET | /.well-known/did.json | Platform DID document | | GET | /authorize | OIDC authorization (PKCE + state required) | | POST | /token | Token exchange, refresh, client credentials | | POST | /oauth/introspect | RFC 7662 token introspection | | GET | /userinfo | Subject DID + AMR claims | | POST | /oidc/register | RFC 7591 dynamic client registration | | POST | /oidc/revoke | RFC 7009 token revocation | | GET | /healthz | Liveness probe | | GET | /readyz | Readiness probe (DB check) | | GET | /api/v1/status/{listId} | BitstringStatusList credential | | GET | /api/v1/marketplace | Credential marketplace (issuers + schemas) |

Identity bridge — public

| Method | Path | Description | |--------|------|-------------| | GET | /auth/{provider} | Start redirect-based bridge flow | | GET | /auth/{provider}/callback | OAuth2/OIDC callback | | POST | /auth/magiclink/request | Request a magic link | | GET | /auth/magiclink/verify | Verify magic link token | | POST | /auth/password | Password authentication | | POST | /auth/webauthn/register/begin | Start passkey registration | | POST | /auth/webauthn/register/finish | Complete passkey registration | | POST | /auth/webauthn/login/begin | Start passkey login | | POST | /auth/webauthn/login/finish | Complete passkey login |

Self-service — bearer token (user's own access token)

| Method | Path | Description | |--------|------|-------------| | GET | /api/v1/me/sessions | List active sessions | | DELETE | /api/v1/me/sessions/{id} | Revoke a session | | GET | /api/v1/me/links | List linked external providers | | DELETE | /api/v1/me/links/{provider} | Unlink a provider | | POST | /api/v1/me/totp/enrol | Enrol TOTP — returns otpauth:// URI | | POST | /api/v1/me/totp/verify | Verify a TOTP code | | DELETE | /api/v1/me/totp | Remove TOTP enrolment | | POST | /api/v1/me/duress/enrol | Set duress passphrase | | DELETE | /api/v1/me/duress | Remove duress passphrase | | POST | /api/v1/me/recovery/enrol | Configure guardian recovery (M-of-N) | | GET | /api/v1/me/recovery | Get recovery configuration |

Protected — Bearer `api_key`

| Method | Path | Description | |--------|------|-------------| | POST | /api/v1/identities | Register a DID | | GET | /api/v1/identities/{did} | Resolve identity | | POST | /api/v1/credentials | Issue a W3C VC | | POST | /api/v1/credentials/verify | Verify a W3C VC | | GET | /api/v1/credentials | List credentials for a subject | | DELETE | /api/v1/credentials/{id} | Delete a credential | | POST | /api/v1/credentials/sd-jwt | Issue an SD-JWT credential | | POST | /api/v1/credentials/sd-jwt/verify | Verify an SD-JWT presentation | | GET/POST/DELETE | /api/v1/consents/grants | Consent grant management | | GET | /api/v1/consents/receipts | Consent receipt audit trail | | GET | /api/v1/schemas | Full schema taxonomy | | POST/GET/DELETE | /api/v1/webhooks | Webhook subscription management | | POST | /api/v1/presentations/request | DIF PE v2 presentation request | | POST | /api/v1/presentations/submit | Submit a VP | | DELETE | /api/v1/sessions/{id} | Admin session revocation | | GET | /api/v1/audit-log | Paginated verifiable audit log | | GET | /api/v1/audit-log/proof/{seq} | Hash-chain proof from seq to head | | POST | /api/v1/recovery/{id}/approve | Guardian approves a recovery request | | GET | /api/v1/recovery/{id} | Get recovery request status | | POST | /api/v1/recovery/initiate | Initiate M-of-N recovery | | GET | /metrics | Prometheus metrics (api_key gated) |

Security notes

PKCE (S256) and state are mandatory on every authorization code flow
Dynamic client registration is required — unregistered client_id values are rejected
Refresh tokens are single-use, stored by sha256(raw), with stolen-token detection via grace window
did:key is blocked as a VC issuer DID — use did:web or did:peer
did:web resolution enforces RFC-1918 blocking and 5-second timeout (SSRF hardening)
Webhook URLs are validated at registration time; loopback/RFC-1918 targets are rejected
Argon2id (64 MB / 3 iterations / 4 threads) for all passphrase-based key derivation
LDAP bridge requires ldaps:// — plaintext ldap:// is refused at startup
Duress passphrase creates a normal-looking session while triggering a silent session.duress event
Extra-sensitive schemas (mental-health, addiction, criminal-record, etc.) require individual explicit grants
Consent revocations set revokedAt — records are never deleted (NZ Privacy Act 2020 audit trail)
Audit log events are SHA-256 hash-chained; any tampering breaks the chain

Credential schema taxonomy

50+ schemas across 11 categories. See SCHEMA.md for the full reference.

Categories: identity · healthcare · finance · professional · education · legal · property · civic · social · travel · insurance

PWA / Mobile

tpt-identity exposes a pure REST + OIDC API. The recommended mobile integration is a Progressive Web App that communicates directly with the API — no native SDK or app-store distribution required.

License

MIT — see LICENSE.

tpt-identity

Languages

tpt-identity

What it does

Docker quickstart

Binary quickstart

Optional build tags

Integration guide (OIDC)

Webhook verification

Configuration

Deployment notes

HTTPS (required)

SQLite WAL mode

Key file permissions

Architecture

API endpoints

Public — no auth required

Identity bridge — public

Self-service — bearer token (user's own access token)

Protected — Bearer api_key

Security notes

Credential schema taxonomy

PWA / Mobile

License

Protected — Bearer `api_key`