@scalemule/ledvery

TypeScript SDK for Ledvery — the organization ledger / OIDC identity service. Use this in any app that wants to let users sign in via Ledvery, regardless of whether it's a ScaleMule platform app or a third-party integration.

Install

npm install @scalemule/ledvery

Quick start

import { LedveryClient } from "@scalemule/ledvery";

const ledvery = new LedveryClient({
  issuer: "https://api.ledvery.com",          // or api-dev.ledvery.com
  clientId: "your-rp-client-id",
  clientSecret: process.env.LEDVERY_CLIENT_SECRET!,
  redirectUri: "https://your-app.com/auth/ledvery/callback",
});

// 1. Start the flow — in your sign-in route, redirect the browser here.
const { url, state, codeVerifier } = await ledvery.createAuthorizationUrl({
  scope: "openid email profile",
  nonce: crypto.randomUUID(),
});
// Stash `state` + `codeVerifier` in a signed cookie so the callback can
// recover them. (The SDK doesn't impose a storage mechanism.)
res.redirect(url);

// 2. In your callback route:
const session = await ledvery.exchangeCode({
  code: req.query.code as string,
  codeVerifier,             // from the cookie
  expectedState: state,     // from the cookie
  receivedState: req.query.state as string,
});
// session = { accessToken, idToken, claims: {sub, email, ...} }

// 3. Any time you need userinfo for a live access token:
const user = await ledvery.getUserInfo(session.accessToken);

What's in the box

• createAuthorizationUrl() — generates a PKCE verifier + challenge, signs nothing (caller handles cookie storage), returns the full Ledvery /authorize URL.
• exchangeCode() — validates state, POSTs to /token with client_secret_basic, verifies the returned ID token's RS256 signature against Ledvery's JWKS, parses claims.
• verifyIdToken() — standalone helper if you already have an ID token (e.g. from a webhook).
• getUserInfo() — calls /userinfo with a bearer access token.
• discover() — fetches and caches /.well-known/openid-configuration. All other calls use this internally.

Design notes

• Session storage is your problem. The SDK does not ship cookie code because different frameworks have incompatible opinions. Look at examples/next-app/ for a Next.js pattern.
• JWKS is cached in-process for 10 minutes by default. That matches Ledvery's key-rotation grace period per the ADR.
• PKCE is always on. Even confidential clients run PKCE — it costs nothing and closes code-interception attacks if redirect_uri is ever misconfigured.
• No refresh tokens yet. Ledvery MVP issues 1-hour access + ID tokens; refresh is a tracked follow-up. This SDK will gain refresh() when the server does.

References

• Ledvery ADR: scalemule-repos/docs/ADR-2026-04-23-ledvery-standalone-product.md
• OIDC discovery spec: https://openid.net/specs/openid-connect-discovery-1_0.html
• PKCE RFC 7636: https://www.rfc-editor.org/rfc/rfc7636