Eve library

@oshun/identity — Cross-domain auth flows

Other

Revision 1

On this page

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)#

text
┌──────────┐  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:

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 jti deny-list honoured by the sessionValidator hook.
  • rate_tier, allowed_ips, and scopes claims are enforced at the gateway (rate tier) and inside authenticate() (scopes → permissions).

Create a key:

ts
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:

ts
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)#

ts
// 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:

ts
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:

ts
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:

ts
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, or publicKey from user-controlled config. Load from the secret store at boot.