Shared identity primitives used by every Oshun capability domain (Yemaya, Lilith, Isis, Sophia, Hathor, Bellona, Aphrodite, Aja). Token issuance is owned by the auth service; every other domain consumes this library to validate tokens, read canonical claims, and enforce role/permission decisions.
This document is the library-level companion to ADR-0003 (Unified auth identity strategy) and ADR-0004 (Shared identity and cross-domain session model). Read those for the why; this README is the how.
What this library ships#
| Module | Purpose |
|---|---|
types.ts |
Canonical claim shapes (AccessTokenClaims, RefreshTokenClaims, ApiKeyTokenClaims, ServiceTokenClaims) + role/permission enums |
jwt.ts |
JwtService — signs (HS256/RS256/ES256) and validates tokens via Web Crypto. HMAC comparison is constant-time via crypto.subtle.verify |
middleware.ts |
authenticate() pipeline for HTTP handlers. Extracts bearer/API-key/service tokens, validates, checks role/permission |
mtls.ts |
verifyForwardedClientCert() for service-to-service mTLS; pins on fingerprint / SPIFFE ID / CN / DNS SAN |
v2-account-binding.ts |
V2 account-state contract for 2FA, recovery, region binding, and PSN / Xbox Live / Nintendo / Steam linked credentials |
1. User auth flow (browser → domain API)#
┌──────────┐ 1. POST /login ┌──────────┐
│ Browser │ ───────────────────────▶ │ auth-svc │
│ │ └────┬──────┘
│ │ │ 2. issue access + refresh tokens
│ │ ◀──────────────────────────────┘ (JwtService.createTokenPair)
│ │
│ │ 3. GET /api/… w/ Bearer <access>
│ │ ─────────────────────────────────────▶ ┌──────────────┐
│ │ │ gateway │
│ │ │ (Traefik) │
│ │ └──────┬───────┘
│ │ │ 4. forward-auth → auth-svc/verify
│ │ │ populates X-User-ID / X-User-Role
│ │ ▼
│ │ ┌──────────────┐
│ │ │ domain API │
│ │ │ (lilith-bff, │
│ │ │ sophia-api, │
│ │ │ ...) │
│ │ └──────┬───────┘
│ │ │ 5. authenticate(req, jwt)
│ │ │ → AuthContext { userId, role, permissions }
│ │ ◀──────────────────────────────── 6. response ─┘
└──────────┘
Step 5 uses authenticate() from middleware.ts:
import { JwtService, authenticate } from '@oshun/identity';
const jwt = new JwtService({
algorithm: 'RS256',
issuer: 'oshun-auth',
audience: ['oshun'],
publicKey: process.env.AUTH_PUBLIC_KEY_PEM,
});
app.addHook('preHandler', async (req, reply) => {
const result = await authenticate(
jwt,
{
authorization: req.headers.authorization,
'x-api-key': req.headers['x-api-key'] as string | undefined,
'x-service-token': req.headers['x-service-token'] as string | undefined,
},
{
required: true,
requireVerifiedEmail: route.auth === 'verified-email',
requireMfa: route.auth === 'mfa',
}
);
if (!result.success) {
const status =
result.errorCode === 'INSUFFICIENT_ROLE' ||
result.errorCode === 'INSUFFICIENT_PERMISSIONS'
? 403
: 401;
return reply.status(status).send({ error: result.error });
}
req.auth = result.context;
});
For services that use the Node http module directly, the
@oshun/identity/node-http subpath ships enforceHttpAuth() which wraps the
dance above (header extraction + status mapping + WWW-Authenticate header) for
you.
2. API-key flow (external integrations, partner APIs)#
API keys are JWTs with type: 'api-key', signed by the auth service the same
way access tokens are signed. That means:
- The same
JwtService.validate()path validates them. - Revocation uses a shared
jtideny-list honoured by the sessionValidator hook. rate_tier,allowed_ips, andscopesclaims are enforced at the gateway (rate tier) and insideauthenticate()(scopes → permissions).
Create a key:
const token = await jwt.createApiKeyToken({
keyId: 'key_01HA2Z…',
ownerId: 'u_123',
name: 'Build bot',
scopes: ['assets:read', 'builds:write'],
rateTier: 'enterprise',
allowedIps: ['10.0.1.0/24'],
expiresIn: 60 * 60 * 24 * 90, // 90 days
});
Consume a key in a domain API — exactly the same entry point as bearer tokens,
differentiated by the X-API-Key header:
const result = await authenticate(
jwt,
{ 'x-api-key': req.headers['x-api-key'] as string | undefined },
{
allowApiKey: true,
requiredPermissions: ['builds:write'],
}
);
3. Service-to-service flow (trust boundary between domains)#
Two supported options, picked per-environment:
3a. Short-lived service tokens (default)#
// On the calling side (e.g. Bellona → Isis)
const svcToken = await jwt.createServiceToken({
serviceName: 'bellona-builder',
instanceId: process.env.HOSTNAME,
targets: ['isis-orchestrator'],
expiresIn: 60, // 1-minute TTL; refresh per request
});
await fetch('http://isis-orchestrator/v1/jobs', {
headers: { 'x-service-token': svcToken },
});
// On the receiving side
import { authenticateService } from '@oshun/identity';
const result = await authenticateService(
jwt,
req.headers['x-service-token'] as string,
{
expectedService: 'bellona-builder',
expectedTarget: 'isis-orchestrator',
}
);
if (!result.valid) {
return reply.status(401).send({ error: result.error ?? 'unauthorised' });
}
Tokens are minted using the same symmetric/asymmetric secret as user tokens but
carry type: 'service' so a leaked user access token can't be used as a service
credential (and vice versa).
3b. mTLS (high-trust boundaries, partner networks)#
When Traefik / Envoy terminates TLS with client-cert verification, it forwards
the cert on X-Client-Cert. Use verifyForwardedClientCert to pin the allowed
callers:
import { verifyForwardedClientCert } from '@oshun/identity';
const result = verifyForwardedClientCert(req.headers['x-client-cert'], {
allowedSpiffeIds: ['spiffe://oshun/ns/bellona/sa/builder'],
allowedCommonNames: ['bellona-builder.internal'],
allowedFingerprints256: [process.env.BELLONA_CERT_FP],
});
if (!result.allowed) return reply.status(401).send({ error: result.reason });
The policy can pin on any combination of SPIFFE URI, fingerprint, CN, or DNS SAN. Fingerprint pinning is the strongest and should be preferred in ambient-mesh deployments where identities rotate.
4. Session revocation#
Access tokens are short-lived (default 15 min). If you need immediate revocation, wire a session validator:
await jwt.validateAccessToken(token, {
sessionValidator: async (sessionId, sessionVersion) => {
const current = await redis.get(`session:${sessionId}:version`);
return Number(current) === sessionVersion;
},
});
Incrementing session:${sessionId}:version invalidates every access token that
was issued for that session prior to the bump, without waiting for expiry.
5. Token rotation#
Refresh tokens form a rotation family. Every successful refresh increments gen
and issues a new family member; reuse of an old gen is a leak signal. Detect
and handle at the refresh endpoint:
const result = await jwt.validate<RefreshTokenClaims>(refreshToken);
if (!result.valid) return reply.status(401).send();
const seen = await redis.get(`refresh:${result.claims.fam}:seen`);
if (seen && Number(seen) >= result.claims.gen) {
// reused an older generation → assume leak, revoke the family
await redis.del(`refresh:${result.claims.fam}:active`);
return reply.status(401).send({ error: 'replay detected' });
}
await redis.set(`refresh:${result.claims.fam}:seen`, result.claims.gen);
const pair = await jwt.createTokenPair({
/* … */ family: result.claims.fam,
generation: result.claims.gen + 1,
});
return reply.send(pair);
6. Cross-domain token compatibility#
All domains share the same issuer (iss: 'oshun-auth') and a shared audience
set. Domain APIs accept any aud that includes their own name. The tid
(tenant) claim is forwarded unchanged so multi-tenant requests reach the right
partition without every domain re-implementing tenant resolution.
Security notes#
- HMAC signatures: we verify with
crypto.subtle.verify, which is constant-time. Previous===comparisons were removed in the 11.5.3 fix. - Service tokens: mint with the shortest TTL that lets a single RPC complete (default 60 s). Do not reuse across requests.
- mTLS: always combine fingerprint/SPIFFE pinning with CA-level verification at the proxy; this library only enforces the identity policy, not the trust chain.
- Secrets: never import
secret,privateKey, orpublicKeyfrom user-controlled config. Load from the secret store at boot.