Identity v1

<script src="https://cdn.sparkvault.com/sdk/v1/sparkvault.js"></script>

const sv = SparkVault.init({ accountId: 'acc_your_account_id' });

document.querySelector('#login-btn').onclick = async () => {
  const { identity, token } = await sv.products.identity.signIn();
  console.log(identity, token);  // "user@example.com", "eyJhbG..."
};

// Frontend: Trigger verification
async function login() {
  const result = await sparkvault.products.identity.signIn();

  // Send token to YOUR backend for verification
  const response = await fetch('/api/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ token: result.token })
  });

  // Backend verifies the signed proof and maps the person by SVID.
  // For production session replacement, use the OIDC/BFF flow below.
}

// Backend: Verify token and map your app data by SVID
app.post('/api/auth/login', async (req, res) => {
  const { token } = req.body;

  // Verify SparkVault token (see JWKS verification examples below)
  const claims = await verifySparkVaultToken(token);
  const svid = claims.svid || claims.sub;

  // Use SVID as the stable foreign key. Keep profile, roles, uploads,
  // preferences, and moderation state in your own database.
  const user = await findOrCreateUserBySvid(svid, {
    identity: claims.identity,
    identityType: claims.identity_type
  });

  res.cookie('app_session', createAppSessionToken(user.id), {
    httpOnly: true,
    secure: true
  });

  res.json({ success: true, user });
});

https://x.sv/{link_code}

Example:
https://x.sv/aB3xK9mQpR7sT2uVwY4zC1

// The popup offers every method you have enabled, including
// SparkLink, and the person picks one. Pre-fill the email to
// skip the first step.
const result = await sparkvault.products.identity.signIn({
  email: 'user@example.com'
});

curl -X POST 'https://auth.sparkvault.com/{account_id}/sparklink/send' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "connection_id": "conn_abc123..."
  }'

{
  "data": {
    "link_code": "aB3xK9mQpR7sT2uVwY4zC1",
    "expiresAt": 1704067800000,
    "kindling": "kdl_abc123..."
  }
}

{ "data": { "pending": true } }

{
  "data": {
    "type": "sparklink_verified",
    "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
    "identity": "user@example.com",
    "identityType": "email",
    "svid": "ing_019e66a4e27875f2822ede0e4f5d8792",
    "session_id": "sess_abc123",
    "refresh_token": "rt_..."
  }
}

curl -X POST 'https://auth.sparkvault.com/{account_id}/otp/send' \
  -H 'Content-Type: application/json' \
  -d '{
    "recipient": "user@example.com",
    "method": "sparklink",
    "connection_id": "conn_abc123..."
  }'

{
  "success": true,
  "method": "sparklink",
  "message": "Magic link sent"
}

<!-- Add to your HTML -->
<script src="https://cdn.sparkvault.com/sdk/v1/sparkvault.js"></script>

// Initialize with your account ID
const sparkvault = SparkVault.init({
  accountId: 'acc_YOUR_ACCOUNT_ID'  // From your dashboard
});

// Trigger verification - SparkVault handles everything
async function login() {
  const result = await sparkvault.products.identity.signIn();

  // User verified! result.token is a signed JWT proving verification
  console.log('Verified:', result.identity);       // "user@example.com" or "+14155551234"
  console.log('Type:', result.identityType);       // "email", "phone", or "social"

  // Send the signed token to your backend for verification and SVID mapping
  await fetch('/api/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ token: result.token })
  });
}

// CRITICAL: Always verify tokens on your backend using JWKS
import * as jose from 'jose';

const ACCOUNT_ID = 'acc_your_account_id';

app.post('/api/auth/verify', async (req, res) => {
  const { token } = req.body;

  try {
    // Fetch JWKS and verify Ed25519 signature
    const jwksUrl = `https://auth.sparkvault.com/${ACCOUNT_ID}/.well-known/jwks.json`;
    const JWKS = jose.createRemoteJWKSet(new URL(jwksUrl));

    const { payload } = await jose.jwtVerify(token, JWKS, {
      issuer: `https://auth.sparkvault.com/${ACCOUNT_ID}`,
      audience: ACCOUNT_ID,
      algorithms: ['EdDSA']
    });

    // Token is valid. SVID is the stable identity key for your app.
    const svid = payload.svid || payload.sub;
    const user = await findOrCreateUserBySvid(svid, {
      identity: payload.identity,           // email or phone
      identityType: payload.identity_type,  // 'email' or 'phone'
      method: payload.method                // 'otp', 'passkey', 'sparklink', 'social:google', ...
    });

    res.json({ success: true, user });
  } catch (error) {
    res.status(401).json({ error: 'Invalid token' });
  }
});

// Runs on every page load; redeems a returned code or self-heals a lost result.
sv.products.identity.handleRedirectResult({
  onSuccess: (result) => createSession(result.token),  // same handler as signIn()
}).catch((error) => showError(error));

{
  "iss": "https://auth.sparkvault.com/acc_example",
  "sub": "ing_019e66a4e27875f2822ede0e4f5d8792",
  "aud": "acc_example",
  "jti": "6f1b2a34-8c9d-4e5f-a012-3456789abcde",
  "svid": "ing_019e66a4e27875f2822ede0e4f5d8792",
  "session_id": "sess_abc123",
  "identity": "user@example.com",
  "identity_type": "email",
  "method": "otp",
  "amr": ["otp"],
  "acr": "urn:sparkvault:identity:1",
  "verified_at": 1703977200,
  "iat": 1703977200,
  "exp": 1703977500
}

try {
  await sparkvault.products.identity.signIn();
} catch (error) {
  switch (error.code) {
    case 'user_cancelled':      // User closed the popup
      break;
    case 'network_error':       // Connection failed
      break;
    case 'invalid_config':      // Bad accountId or malformed configuration
      break;
    case 'ORIGIN_NOT_ALLOWED':  // This page's domain is not a verified
      break;                    // company domain for the account (HTTP 400).
                                // Add the domain in the dashboard; retrying
                                // never clears an origin block.
  }
}

import { useCallback, useState } from 'react';
import SparkVault from '@sparkvault/sdk-js';

// Initialize once, outside the component
const sparkvault = SparkVault.init({
  accountId: 'acc_YOUR_ACCOUNT_ID'
});

function LoginButton() {
  const [isVerifying, setIsVerifying] = useState(false);

  const handleLogin = useCallback(async () => {
    setIsVerifying(true);
    try {
      // Open the sign-in popup
      const result = await sparkvault.products.identity.signIn();

      // Send token to backend
      await fetch('/api/auth/login', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ token: result.token })
      });
    } catch (err) {
      if (err.code !== 'user_cancelled') throw err;
    } finally {
      setIsVerifying(false);
    }
  }, []);

  return (
    <button onClick={handleLogin} disabled={isVerifying}>
      {isVerifying ? 'Verifying...' : 'Log In'}
    </button>
  );
}

// Generate cryptographically secure PKCE parameters
function generateCodeVerifier() {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  return base64urlEncode(array);
}

async function generateCodeChallenge(verifier) {
  const encoder = new TextEncoder();
  const data = encoder.encode(verifier);
  const hash = await crypto.subtle.digest('SHA-256', data);
  return base64urlEncode(new Uint8Array(hash));
}

function base64urlEncode(buffer) {
  return btoa(String.fromCharCode(...buffer))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '');
}

// Generate and store for later verification
const codeVerifier = generateCodeVerifier();
const codeChallenge = await generateCodeChallenge(codeVerifier);
const state = crypto.randomUUID();
const nonce = crypto.randomUUID();

sessionStorage.setItem('pkce_verifier', codeVerifier);
sessionStorage.setItem('auth_state', state);
sessionStorage.setItem('auth_nonce', nonce);

const authUrl = new URL('https://auth.sparkvault.com/{account_id}/authorize');
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('client_id', 'your-client-id');
authUrl.searchParams.set('redirect_uri', 'https://your-app.com/auth/callback');
authUrl.searchParams.set('scope', 'openid email');
authUrl.searchParams.set('state', state);
authUrl.searchParams.set('nonce', nonce);
authUrl.searchParams.set('code_challenge', codeChallenge);
authUrl.searchParams.set('code_challenge_method', 'S256');

// Redirect user to Identity hosted login
window.location.href = authUrl.toString();

// In your /auth/callback route handler
const params = new URLSearchParams(window.location.search);
const code = params.get('code');
const returnedState = params.get('state');

// Validate state to prevent CSRF
if (returnedState !== sessionStorage.getItem('auth_state')) {
  throw new Error('Invalid state parameter');
}

// Exchange code for tokens (do this server-side!)
const response = await fetch('https://auth.sparkvault.com/{account_id}/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + btoa('client_id:client_secret')
  },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    code: code,
    redirect_uri: 'https://your-app.com/auth/callback',
    client_id: 'your-client-id',
    code_verifier: sessionStorage.getItem('pkce_verifier')
  })
});

const { id_token } = await response.json();

// Clean up
sessionStorage.removeItem('pkce_verifier');
sessionStorage.removeItem('auth_state');
sessionStorage.removeItem('auth_nonce');

import { ed25519 } from '@noble/curves/ed25519';

async function verifyIdToken(idToken, accountId, clientId, nonce) {
  const [headerB64, payloadB64, signatureB64] = idToken.split('.');

  // Fetch public key from JWKS
  const jwksResponse = await fetch(
    `https://auth.sparkvault.com/${accountId}/.well-known/jwks.json`
  );
  const jwks = await jwksResponse.json();
  const publicKey = base64urlDecode(jwks.keys[0].x);

  // Verify Ed25519 signature
  const signedData = `${headerB64}.${payloadB64}`;
  const signature = base64urlDecode(signatureB64);
  const isValid = ed25519.verify(
    signature,
    new TextEncoder().encode(signedData),
    publicKey
  );

  if (!isValid) throw new Error('Invalid signature');

  // Decode and validate claims
  const payload = JSON.parse(atob(payloadB64.replace(/-/g,'+').replace(/_/g,'/')));

  if (payload.iss !== `https://auth.sparkvault.com/${accountId}`) {
    throw new Error('Invalid issuer');
  }
  if (payload.aud !== clientId) {
    throw new Error('Invalid audience');
  }
  if (payload.nonce !== nonce) {
    throw new Error('Invalid nonce');
  }
  if (payload.exp < Math.floor(Date.now() / 1000)) {
    throw new Error('Token expired');
  }

  return payload; // { sub: svid, identity, identity_type, email?, phone_number?, amr, ... }
}

{
  "issuer": "https://auth.sparkvault.com/acc_example",
  "authorization_endpoint": "https://auth.sparkvault.com/acc_example/authorize",
  "token_endpoint": "https://auth.sparkvault.com/acc_example/token",
  "introspection_endpoint": "https://auth.sparkvault.com/acc_example/introspect",
  "revocation_endpoint": "https://auth.sparkvault.com/acc_example/revoke",
  "jwks_uri": "https://auth.sparkvault.com/acc_example/.well-known/jwks.json",
  "response_types_supported": ["code"],
  "response_modes_supported": ["query", "json"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["EdDSA"],
  "token_endpoint_auth_methods_supported": ["client_secret_post", "client_secret_basic", "none"],
  "revocation_endpoint_auth_methods_supported": ["client_secret_post", "client_secret_basic", "none"],
  "claims_supported": ["iss", "sub", "aud", "exp", "iat", "auth_time", "nonce",
                       "email", "email_verified", "phone_number", "phone_number_verified",
                       "identity", "identity_type", "svid", "session_id", "amr", "acr"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["openid", "email", "phone"]
}

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "base64url-encoded-public-key",
      "kid": "key-id-for-rotation",
      "use": "sig",
      "alg": "EdDSA"
    }
  ]
}

{
  "iss": "https://auth.sparkvault.com/acc_example",
  "sub": "ing_019e66a4e27875f2822ede0e4f5d8792",
  "aud": "your-client-id",
  "exp": 1703980800,
  "iat": 1703977200,
  "auth_time": 1703977195,
  "nonce": "abc123",
  "svid": "ing_019e66a4e27875f2822ede0e4f5d8792",
  "identity": "user@example.com",
  "identity_type": "email",
  "email": "user@example.com",
  "email_verified": true,
  "amr": ["passkey"],
  "acr": "urn:sparkvault:identity:1"
}

{
  "session_id": "nZk4tW8xQ2mVbC7dEfGh1A",
  "verify_url": "https://auth.sparkvault.com/{account_id}/verify?session=nZk4tW8xQ2mVbC7dEfGh1A",
  "expires_in_seconds": 900
}

import { ed25519 } from '@noble/curves/ed25519';

async function verifyCallback(params, accountId) {
  // Fetch public key from JWKS
  const jwksResponse = await fetch(
    `https://auth.sparkvault.com/${accountId}/.well-known/jwks.json`
  );
  const jwks = await jwksResponse.json();
  const publicKeyBytes = base64urlDecode(jwks.keys[0].x);

  // Check timestamp is recent (5 minute window)
  const timestamp = parseInt(params.timestamp, 10);
  const now = Math.floor(Date.now() / 1000);
  if (timestamp < now - 300 || timestamp > now + 60) {
    throw new Error('Timestamp out of range');
  }

  // Rebuild the exact string the server signed (field order matters).
  const dataToVerify = [
    'verified=true',
    `session_id=${params.session_id}`,
    `timestamp=${params.timestamp}`,
    `nonce=${params.nonce}`,
    `account_id=${params.account_id}`
  ].join('&');

  // Decode and verify signature
  const signatureBytes = base64urlDecode(params.signature);
  const isValid = ed25519.verify(
    signatureBytes,
    new TextEncoder().encode(dataToVerify),
    publicKeyBytes
  );

  if (!isValid) throw new Error('Invalid signature');

  // The callback carries no PII. A valid signature confirms verification for
  // the session you initiated; SparkVault resolves the verified identity
  // server-side, so you never receive the raw email here.
  return {
    verified: true,
    sessionId: params.session_id,
    method: 'simple_redirect'
  };
}

curl -X POST 'https://auth.sparkvault.com/{account_id}/otp/send' \
  -H 'Content-Type: application/json' \
  -d '{
    "recipient": "user@example.com",
    "method": "email"
  }'

{
  "success": true,
  "kindling": "kdl_abc123...",
  "expires_at": 1704067800,
  "method": "email"
}

curl -X POST 'https://auth.sparkvault.com/{account_id}/otp/verify' \
  -H 'Content-Type: application/json' \
  -d '{
    "recipient": "user@example.com",
    "pin": "123456",
    "kindling": "kdl_abc123..."
  }'

{
  "verified": true,
  "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "identity": "user@example.com",
  "identity_type": "email",
  "method": "otp",
  "svid": "ing_019e66a4e27875f2822ede0e4f5d8792",
  "session_id": "sess_abc123",
  "refresh_token": "rt_...",
  "recommendations": [
    { "type": "passkey" }
  ]
}

const IDENTITY_URL = 'https://auth.sparkvault.com';
const ACCOUNT_ID = 'acc_youraccountid';

// Step 1: Send verification code
async function sendVerificationCode(email) {
  const response = await fetch(`${IDENTITY_URL}/${ACCOUNT_ID}/otp/send`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      recipient: email,
      method: 'email'
    })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Failed to send code');
  }

  return response.json();
  // { success: true, kindling: "kdl_...", expires_at: 1234567890, method: "email" }
}

// Step 2: Verify code entered by user (include kindling from step 1)
async function verifyCode(email, pin, kindling) {
  const response = await fetch(`${IDENTITY_URL}/${ACCOUNT_ID}/otp/verify`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      recipient: email,
      pin,
      kindling  // Required - from send response
    })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Verification failed');
  }

  return response.json();
  // { verified, token, identity, identity_type, method,
  //   svid, session_id, refresh_token, recommendations }
}

// Step 3: Verify the returned JWT using JWKS
import * as jose from 'jose';

async function verifyToken(token) {
  const jwksUrl = `${IDENTITY_URL}/${ACCOUNT_ID}/.well-known/jwks.json`;
  const JWKS = jose.createRemoteJWKSet(new URL(jwksUrl));

  const { payload } = await jose.jwtVerify(token, JWKS, {
    issuer: `${IDENTITY_URL}/${ACCOUNT_ID}`,
    audience: ACCOUNT_ID,
    algorithms: ['EdDSA']
  });

  return payload;  // { identity, identity_type, method, verified_at, ... }
}

import requests

IDENTITY_URL = 'https://auth.sparkvault.com'
ACCOUNT_ID = 'acc_youraccountid'

def send_verification_code(email: str) -> dict:
    """Send a verification code to the email address."""
    response = requests.post(
        f'{IDENTITY_URL}/{ACCOUNT_ID}/otp/send',
        json={
            'recipient': email,
            'method': 'email'
        }
    )
    response.raise_for_status()
    return response.json()
    # Returns: {'success': True, 'kindling': 'kdl_...', 'expires_at': ..., 'method': 'email'}

def verify_code(email: str, pin: str, kindling: str) -> dict:
    """Verify the code and get a signed JWT."""
    response = requests.post(
        f'{IDENTITY_URL}/{ACCOUNT_ID}/otp/verify',
        json={
            'recipient': email,
            'pin': pin,
            'kindling': kindling  # Required - from send response
        }
    )
    response.raise_for_status()
    return response.json()
    # Returns: {'verified': True, 'token': '...', 'identity': '...', 'identity_type': '...',
    #           'method': '...', 'svid': '...', 'session_id': '...', 'refresh_token': '...',
    #           'recommendations': [...]}

{
  "verified": false,
  "kindling": "kdl_abc123...",
  "expires_at": 1704067800,
  "retry_after": 1704067830
}

curl -X POST 'https://auth.sparkvault.com/{account_id}/passkey/check' \
  -H 'Content-Type: application/json' \
  -d '{ "email": "user@example.com" }'

{
  "identity_valid": true,
  "has_passkey": true
}

{
  "options": {
    "challenge": "base64url-encoded-challenge",
    "rp": { "name": "SparkVault Identity", "id": "sparkvault.com" },
    "user": { "id": "base64url-user-id", "name": "user@example.com", "displayName": "User" },
    "pubKeyCredParams": [
      { "type": "public-key", "alg": -7 },
      { "type": "public-key", "alg": -257 }
    ],
    "timeout": 60000,
    "attestation": "none",
    "excludeCredentials": [
      { "type": "public-key", "id": "base64url-existing-credential-id" }
    ],
    "authenticatorSelection": {
      "residentKey": "required",
      "requireResidentKey": true,
      "userVerification": "required"
    }
  },
  "session": {
    "sessionId": "9f2c4e8a1b3d5f7a9c0e2468acefdb13579bdf02468ace13579bdf024680acef",
    "challenge": "base64url-encoded-challenge",
    "identity": "user@example.com",
    "identityType": "email",
    "deviceName": null,
    "rpId": "sparkvault.com"
  }
}

{
  "verified": true,
  "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "identity": "user@example.com",
  "identity_type": "email",
  "method": "passkey",
  "svid": "ing_019e66a4e27875f2822ede0e4f5d8792",
  "session_id": "sess_abc123",
  "refresh_token": "rt_...",
  "recommendations": []
}

{
  "options": {
    "challenge": "base64url-encoded-challenge",
    "timeout": 60000,
    "rpId": "sparkvault.com",
    "userVerification": "required",
    "allowCredentials": [
      { "type": "public-key", "id": "base64url-credential-id" }
    ]
  },
  "session": {
    "sessionId": "9f2c4e8a1b3d5f7a9c0e2468acefdb13579bdf02468ace13579bdf024680acef",
    "challenge": "base64url-encoded-challenge",
    "rpId": "sparkvault.com"
  }
}

{
  "verified": true,
  "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "identity": "user@example.com",
  "identity_type": "email",
  "method": "passkey",
  "svid": "ing_019e66a4e27875f2822ede0e4f5d8792",
  "session_id": "sess_abc123",
  "refresh_token": "rt_...",
  "recommendations": []
}

{
  "passkeys": [
    {
      "credential_id": "base64url-credential-id",
      "device_name": "MacBook Pro",
      "created_at": 1703977200,
      "last_used": 1704067800,
      "backup_eligible": true,
      "backup_state": true
    }
  ],
  "count": 1
}

{
  "success": true,
  "credential_id": "base64url-credential-id"
}

{
  "verified": false,
  "second_factor_required": true,
  "ticket": "opaque-64-char-hex-ticket",
  "methods": ["authenticator", "recovery_code"],
  "identity": "user@example.com",
  "identity_type": "email"
}

GET https://auth.sparkvault.com/{account_id}/social/google?redirect_uri=https://yourapp.com/callback&state=abc123

→ Redirects to Google OAuth consent page
→ After consent, redirects to /social/google/callback
→ Finally redirects to your redirect_uri with #token=...&state=abc123

Entity ID: https://auth.sparkvault.com/{account_id}
ACS URL:   https://auth.sparkvault.com/{account_id}/saml/{provider}/acs
Binding:   HTTP-POST
NameID:    Email address (required)

https://auth.sparkvault.com/{account_id}?auth_request=req_abc123        ← from /authorize
https://auth.sparkvault.com/{account_id}?mode=simple&session=nZk4tW8x   ← from /verify

→ Shows the branded login page with all enabled methods
→ User chooses a method and verifies
→ The stored OIDC or simple-verify flow completes (code callback or signed redirect)

{
  "data": {
    "accountId": "acc_example",
    "branding": {
      "companyName": "Your Company",
      "logoLight": "https://yourcompany.com/logo-light.png",
      "logoDark": "https://yourcompany.com/logo-dark.png",
      "themeMode": "light"
    },
    "allowedIdentityTypes": ["email", "phone"],
    "methods": [
      "passkey",
      "otp_email",
      "otp_sms",
      "sparklink",
      "social_google",
      "social_apple"
    ],
    "sso": { "enabled": true, "forced": false },
    "wsDomain": "ws.sparkvault.com"
  }
}

import express from 'express';
import { ed25519 } from '@noble/curves/ed25519';

const app = express();

// Configuration
const IDENTITY_URL = 'https://auth.sparkvault.com/acc_youraccountid';
const CLIENT_ID = 'your-client-id';
const CLIENT_SECRET = process.env.IDENTITY_CLIENT_SECRET;
const REDIRECT_URI = 'https://your-app.com/auth/callback';

// JWKS cache
let jwksCache = null;
let jwksCacheExpiry = 0;

async function getPublicKey() {
  if (jwksCache && Date.now() < jwksCacheExpiry) {
    return jwksCache;
  }
  const res = await fetch(`${IDENTITY_URL}/.well-known/jwks.json`);
  const jwks = await res.json();
  jwksCache = base64urlDecode(jwks.keys[0].x);
  jwksCacheExpiry = Date.now() + 5 * 60 * 1000; // 5 min
  return jwksCache;
}

// Login route - redirect to Identity
app.get('/login', async (req, res) => {
  const codeVerifier = generateCodeVerifier();
  const codeChallenge = await generateCodeChallenge(codeVerifier);
  const state = crypto.randomUUID();
  const nonce = crypto.randomUUID();

  // Store in session
  req.session.pkce = { codeVerifier, state, nonce };

  const authUrl = new URL(`${IDENTITY_URL}/authorize`);
  authUrl.searchParams.set('response_type', 'code');
  authUrl.searchParams.set('client_id', CLIENT_ID);
  authUrl.searchParams.set('redirect_uri', REDIRECT_URI);
  authUrl.searchParams.set('scope', 'openid email');
  authUrl.searchParams.set('state', state);
  authUrl.searchParams.set('nonce', nonce);
  authUrl.searchParams.set('code_challenge', codeChallenge);
  authUrl.searchParams.set('code_challenge_method', 'S256');

  res.redirect(authUrl.toString());
});

// Callback route - exchange code for token
app.get('/auth/callback', async (req, res) => {
  const { code, state, error } = req.query;
  const { codeVerifier, state: savedState, nonce } = req.session.pkce || {};

  // Handle errors
  if (error) {
    return res.redirect(`/login?error=${error}`);
  }

  // Validate state
  if (state !== savedState) {
    return res.status(400).send('Invalid state');
  }

  // Exchange code for tokens
  const tokenRes = await fetch(`${IDENTITY_URL}/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Basic ' + Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64')
    },
    body: JSON.stringify({
      grant_type: 'authorization_code',
      code,
      redirect_uri: REDIRECT_URI,
      client_id: CLIENT_ID,
      code_verifier: codeVerifier
    })
  });

  const { id_token, access_token, refresh_token } = await tokenRes.json();

  // Verify ID token
  const claims = await verifyIdToken(id_token, nonce);

  // Clear PKCE data
  delete req.session.pkce;

  // BFF boundary: keep token material server-side or in encrypted/signed
  // HttpOnly, Secure, SameSite=Lax cookies. Browser JS should never see it.
  req.session.identity = { accessToken: access_token, refreshToken: refresh_token };
  req.session.user = {
    svid: claims.svid || claims.sub,
    identity: claims.identity || claims.email || claims.phone_number
  };

  res.redirect('/dashboard');
});

app.post('/logout', async (req, res) => {
  const refreshToken = req.session.identity?.refreshToken;
  if (refreshToken) {
    await fetch(`${IDENTITY_URL}/revoke`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Basic ' + Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64')
      },
      body: JSON.stringify({
        client_id: CLIENT_ID,
        token: refreshToken
      })
    });
  }
  req.session.destroy(() => res.sendStatus(204));
});

async function verifyIdToken(idToken, expectedNonce) {
  const [headerB64, payloadB64, signatureB64] = idToken.split('.');
  const publicKey = await getPublicKey();

  // Verify signature
  const signedData = `${headerB64}.${payloadB64}`;
  const signature = base64urlDecode(signatureB64);
  const isValid = ed25519.verify(
    signature,
    new TextEncoder().encode(signedData),
    publicKey
  );

  if (!isValid) throw new Error('Invalid signature');

  const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString());

  // Validate claims
  if (payload.iss !== IDENTITY_URL) throw new Error('Invalid issuer');
  if (payload.nonce !== expectedNonce) throw new Error('Invalid nonce');
  if (payload.exp < Math.floor(Date.now() / 1000)) throw new Error('Token expired');
  if (payload.aud !== CLIENT_ID) throw new Error('Invalid audience');

  return payload;
}

import os
import base64
import hashlib
import secrets
from flask import Flask, redirect, request, session
import requests
from nacl.signing import VerifyKey
from nacl.exceptions import BadSignatureError

app = Flask(__name__)
app.secret_key = os.environ['FLASK_SECRET_KEY']

IDENTITY_URL = 'https://auth.sparkvault.com/acc_youraccountid'
CLIENT_ID = 'your-client-id'
CLIENT_SECRET = os.environ['IDENTITY_CLIENT_SECRET']
REDIRECT_URI = 'https://your-app.com/auth/callback'

# JWKS cache
_jwks_cache = {'key': None, 'expires': 0}

def get_public_key():
    import time
    if _jwks_cache['key'] and time.time() < _jwks_cache['expires']:
        return _jwks_cache['key']

    response = requests.get(f'{IDENTITY_URL}/.well-known/jwks.json')
    jwks = response.json()
    key_b64 = jwks['keys'][0]['x']
    # Add padding if needed
    padding = 4 - (len(key_b64) % 4)
    if padding != 4:
        key_b64 += '=' * padding
    key_bytes = base64.urlsafe_b64decode(key_b64)

    _jwks_cache['key'] = key_bytes
    _jwks_cache['expires'] = time.time() + 300  # 5 min
    return key_bytes

def base64url_encode(data):
    return base64.urlsafe_b64encode(data).rstrip(b'=').decode('ascii')

def generate_pkce():
    code_verifier = secrets.token_urlsafe(32)
    code_challenge = base64url_encode(
        hashlib.sha256(code_verifier.encode()).digest()
    )
    return code_verifier, code_challenge

@app.route('/login')
def login():
    code_verifier, code_challenge = generate_pkce()
    state = secrets.token_urlsafe(16)
    nonce = secrets.token_urlsafe(16)

    session['pkce'] = {
        'code_verifier': code_verifier,
        'state': state,
        'nonce': nonce
    }

    auth_url = (
        f'{IDENTITY_URL}/authorize'
        f'?response_type=code'
        f'&client_id={CLIENT_ID}'
        f'&redirect_uri={REDIRECT_URI}'
        f'&scope=openid%20email'
        f'&state={state}'
        f'&nonce={nonce}'
        f'&code_challenge={code_challenge}'
        f'&code_challenge_method=S256'
    )
    return redirect(auth_url)

@app.route('/auth/callback')
def callback():
    code = request.args.get('code')
    state = request.args.get('state')
    error = request.args.get('error')

    if error:
        return redirect(f'/login?error={error}')

    pkce = session.get('pkce', {})
    if state != pkce.get('state'):
        return 'Invalid state', 400

    # Exchange code
    credentials = base64.b64encode(
        f'{CLIENT_ID}:{CLIENT_SECRET}'.encode()
    ).decode()

    response = requests.post(
        f'{IDENTITY_URL}/token',
        headers={
            'Content-Type': 'application/json',
            'Authorization': f'Basic {credentials}'
        },
        json={
            'grant_type': 'authorization_code',
            'code': code,
            'redirect_uri': REDIRECT_URI,
            'client_id': CLIENT_ID,
            'code_verifier': pkce['code_verifier']
        }
    )

    token_response = response.json()
    id_token = token_response['id_token']
    claims = verify_id_token(id_token, pkce['nonce'])

    session.pop('pkce', None)
    # BFF boundary: keep token material server-side or in encrypted/signed
    # HttpOnly, Secure, SameSite=Lax cookies. Browser JS should never see it.
    session['identity'] = {
        'access_token': token_response['access_token'],
        'refresh_token': token_response['refresh_token']
    }
    session['user'] = {
        'svid': claims.get('svid') or claims['sub'],
        'identity': claims.get('identity') or claims.get('email') or claims.get('phone_number')
    }

    return redirect('/dashboard')

@app.route('/logout', methods=['POST'])
def logout():
    refresh_token = session.get('identity', {}).get('refresh_token')
    if refresh_token:
        credentials = base64.b64encode(
            f'{CLIENT_ID}:{CLIENT_SECRET}'.encode()
        ).decode()
        requests.post(
            f'{IDENTITY_URL}/revoke',
            headers={
                'Content-Type': 'application/json',
                'Authorization': f'Basic {credentials}'
            },
            json={
                'client_id': CLIENT_ID,
                'token': refresh_token
            },
            timeout=5
        )
    session.clear()
    return '', 204

def verify_id_token(id_token, expected_nonce):
    import json
    import time

    parts = id_token.split('.')
    header_b64, payload_b64, signature_b64 = parts

    # Decode payload
    padding = 4 - (len(payload_b64) % 4)
    if padding != 4:
        payload_b64 += '=' * padding
    payload = json.loads(base64.urlsafe_b64decode(payload_b64))

    # Verify signature
    public_key = get_public_key()
    verify_key = VerifyKey(public_key)

    signed_data = f'{parts[0]}.{parts[1]}'.encode()
    padding = 4 - (len(signature_b64) % 4)
    if padding != 4:
        signature_b64 += '=' * padding
    signature = base64.urlsafe_b64decode(signature_b64)

    try:
        verify_key.verify(signed_data, signature)
    except BadSignatureError:
        raise ValueError('Invalid signature')

    # Validate claims
    if payload['iss'] != IDENTITY_URL:
        raise ValueError('Invalid issuer')
    if payload['nonce'] != expected_nonce:
        raise ValueError('Invalid nonce')
    if payload['exp'] < time.time():
        raise ValueError('Token expired')
    if payload['aud'] != CLIENT_ID:
        raise ValueError('Invalid audience')

    return payload

{
  "error": "invalid_grant",
  "error_description": "Authorization code is invalid or expired"
}