sudapass-service-provider

Node.js SDK for SudaPass eKYC — plug-and-play OIDC + PKCE integration for service providers.

Install

npm install sudapass-service-provider

Usage (2 steps)

const { SudaPassClient } = require('sudapass-service-provider');

const client = new SudaPassClient({
  issuer:      'https://sudapass.online',
  clientId:    'client_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  redirectUri: 'https://yourapp.com/callback',
  scopes:      ['openid', 'profile', 'email', 'verified_claims'],
});

// Step 1 — redirect user to SudaPass
const { url, session } = await client.getAuthorizationUrl();
req.session.sudapass = session;
res.redirect(url);

// Step 2 — handle the callback
const user = await client.handleCallback({
  code:          req.query.code,
  state:         req.query.state,
  storedSession: req.session.sudapass,
});

// user.name, user.email, user.picture, user.nationalNumber,
// user.gender, user.birthdate, user.nationality, user.verifiedClaims ...

Express middleware

const { createMiddleware } = require('sudapass-service-provider/middleware');

const { requireAuth, callbackHandler, protect } = createMiddleware(client, {
  onSuccess(req, res, user) {
    req.session.user = user;
    res.redirect('/dashboard');
  },
});

app.get('/login',     requireAuth);
app.get('/callback',  callbackHandler);
app.get('/dashboard', protect, (req, res) => res.json(req.sudapassUser));

What the SDK handles internally

• PKCE verifier + S256 challenge generation (RFC 7636)
• State + nonce generation for CSRF and replay protection
• OIDC discovery document fetch and cache
• Authorization code exchange (public client, no secret)
• JWKS fetch, cache, and ID token signature verification
• Nonce validation
• Full citizen claim extraction including verified_claims

User object returned

{
  "sub":            "citizen-uuid",
  "name":           "Ahmed Mohamed",
  "email":          "[email protected]",
  "nationalNumber": "123456789",
  "gender":         "M",
  "birthdate":      "1990-01-01",
  "nationality":    "Sudanese",
  "picture":        "/uploads/verification/uuid/citizen.jpg",
  "assuranceLevel": "urn:sudapass:fido2",
  "verifiedClaims": { ... },
  "idTokenClaims":  { ... },
  "tokens": {
    "accessToken":  "...",
    "refreshToken": "...",
    "expiresIn":    3600
  }
}

Requirements

• Node.js >= 18

License

MIT — National Center for Technology Resources (NCTR)