@venturineai/identity 0.1.0

package/index.d.ts

@@ -0,0 +1,91 @@
+import { type JWK } from 'jose';
+export interface ServiceJwtConfig {
+    audience: string;
+    privateJwk: JWK;
+    serviceId: string;
+    kid: string;
+    expiry?: string;
+}
+export interface VerifyConfig {
+    token: string;
+    expectedIssuer: string;
+    serviceId: string;
+    jwksUrl: string;
+}
+export interface JwtClaims {
+    iss: string;
+    jti: string;
+    sub: string;
+}
+export declare function signServiceJwt(config: ServiceJwtConfig): Promise<string>;
+export declare function verifyServiceJwt(config: VerifyConfig): Promise<JwtClaims>;
+export declare function buildJwks(privateJwk: JWK, kid: string): {
+    keys: JWK[];
+};
+export declare function signSubmitterToken(submitterId: string, secret: string, expiry?: string): Promise<string>;
+export declare function verifySubmitterToken(token: string, secret: string): Promise<string>;
+/**
+ * Required configuration was missing or unusable. Distinct from an auth failure
+ * because it is the *operator's* fault, not the caller's: map it to 500, never
+ * 401, or a misconfigured deployment reads as a stream of rejected callers.
+ */
+export declare class EventConfigError extends Error {
+    constructor(message: string);
+}
+/** The token itself failed verification (bad signature, wrong pin, stale, replayed) → 401. */
+export declare class EventAuthError extends Error {
+    constructor(message: string);
+}
+export interface VerifiedEventToken {
+    iss: string;
+    aud: string | string[] | undefined;
+    sub: string;
+    jti: string;
+}
+/**
+ * Returns true if this jti has already been consumed. Implementations must be
+ * atomic check-and-set (Redis `SET NX EX`) so two concurrent deliveries of the
+ * same token cannot both see false.
+ */
+export type ReplayGuard = (jti: string) => Promise<boolean>;
+export interface EventTokenConfig {
+    token: string;
+    /** URL of the platform's JWKS document. */
+    jwksUrl: string;
+    /** Expected `aud` — this app's registered jwt_audience. */
+    expectedAudience: string;
+    /** Expected `iss`. Defaults to 'platform'. */
+    expectedIssuer?: string;
+    /**
+     * Max age of the token measured from its `iat`, e.g. '5m' (the default).
+     * Bounds staleness independently of the token's own `exp`: a captured token
+     * stops verifying once it is older than this, even if it has not expired.
+     */
+    maxTokenAge?: string;
+    /**
+     * The jti replay guard, or the literal 'none' to run without one.
+     *
+     * Required rather than optional on purpose. A forgotten optional guard fails
+     * silently — the call keeps succeeding and the replay window quietly reopens —
+     * so opting out has to be written down at the call site where a reviewer and
+     * a grep can both find it.
+     */
+    replayGuard: ReplayGuard | 'none';
+}
+/**
+ * Verify an inbound platform event JWT. Fails CLOSED on any misconfig or
+ * mismatch, and throws `EventConfigError` vs `EventAuthError` so the caller can
+ * tell a broken deployment from a rejected caller.
+ *
+ * Pins issuer, audience, `algorithms: ['EdDSA']` and `maxTokenAge`; requires
+ * `jti` and `sub`; and consumes the jti through the replay guard.
+ *
+ * The caller must still pin the subscription — see `assertSubscription`.
+ */
+export declare function verifyEventToken(config: EventTokenConfig): Promise<VerifiedEventToken>;
+/**
+ * Assert the verified token belongs to this app's subscription (the `sub` pin).
+ * Separate from `verifyEventToken` because a valid platform token for a
+ * *different* subscription is authentic but not authorised here.
+ */
+export declare function assertSubscription(token: VerifiedEventToken, expectedSubscriptionId: string | undefined): void;

package/index.js

@@ -0,0 +1,180 @@
+// Service-to-service JWT helpers using EdDSA (OKP/Ed25519).
+//
+// Each service (portal, platform, future services) owns a keypair.
+// Private key in SERVICE_SIGNING_KEY env var (JWK JSON string).
+// Public key published at /.well-known/jwks.json.
+//
+// Usage:
+//   const jwt = await signServiceJwt({ audience: 'platform', privateJwk, serviceId: 'portal', kid });
+//   const claims = await verifyServiceJwt({ token, expectedIssuer: 'portal', serviceId: 'platform', jwksUrl });
+import { SignJWT, jwtVerify, importJWK, createRemoteJWKSet, } from 'jose';
+import { randomUUID } from 'crypto';
+// Per-process JWKS cache — jose manages the 5-min cache internally
+const _jwksSets = new Map();
+function getRemoteJwks(url) {
+    if (!_jwksSets.has(url)) {
+        _jwksSets.set(url, createRemoteJWKSet(new URL(url)));
+    }
+    return _jwksSets.get(url);
+}
+export async function signServiceJwt(config) {
+    const { audience, privateJwk, serviceId, kid, expiry = '60s' } = config;
+    const privateKey = await importJWK(privateJwk, 'EdDSA');
+    return new SignJWT({ sub: `service:${serviceId}` })
+        .setProtectedHeader({ alg: 'EdDSA', kid })
+        .setIssuer(serviceId)
+        .setAudience(audience)
+        .setIssuedAt()
+        .setExpirationTime(expiry)
+        .setJti(randomUUID())
+        .sign(privateKey);
+}
+export async function verifyServiceJwt(config) {
+    const { token, expectedIssuer, serviceId, jwksUrl } = config;
+    const JWKS = getRemoteJwks(jwksUrl);
+    const { payload } = await jwtVerify(token, JWKS, {
+        issuer: expectedIssuer,
+        audience: serviceId,
+        // Pin the algorithm. Without this, jose accepts whatever the matched JWK
+        // declares, so a single unexpected key in the peer's JWKS (an RSA key added
+        // for some other purpose, or one injected by whoever can write that
+        // document) widens the accepted algorithm set from the outside.
+        algorithms: ['EdDSA'],
+    });
+    if (!payload.jti)
+        throw new Error('JWT missing jti claim');
+    return {
+        iss: payload.iss,
+        jti: payload.jti,
+        sub: payload.sub ?? '',
+    };
+}
+// Returns the public JWKS document for the service's signing key.
+// Publish this at GET /.well-known/jwks.json.
+export function buildJwks(privateJwk, kid) {
+    const { d, p, q, dp, dq, qi, ...pub } = privateJwk;
+    void d;
+    void p;
+    void q;
+    void dp;
+    void dq;
+    void qi;
+    return { keys: [{ ...pub, kid, use: 'sig', alg: 'EdDSA' }] };
+}
+// ── Submitter auth cookie (HS256, symmetric) ───────────────────────────────
+// Used by portals to sign/verify the venturine_submitter httpOnly cookie.
+export async function signSubmitterToken(submitterId, secret, expiry = '30d') {
+    const key = new TextEncoder().encode(secret);
+    return new SignJWT({ sub: submitterId })
+        .setProtectedHeader({ alg: 'HS256' })
+        .setIssuedAt()
+        .setExpirationTime(expiry)
+        .sign(key);
+}
+export async function verifySubmitterToken(token, secret) {
+    const key = new TextEncoder().encode(secret);
+    const { payload } = await jwtVerify(token, key, { algorithms: ['HS256'] });
+    if (!payload.sub)
+        throw new Error('JWT missing sub');
+    return payload.sub;
+}
+// ── Inbound platform → app event tokens ────────────────────────────────────
+//
+// The canonical verifier for the platform's signed-event deliveries. Every
+// spoke had hand-rolled its own copy of this, and the hardenings had drifted so
+// that no single copy had them all (ops#293 / F-24): the EdDSA pin existed only
+// in myestate-plan, maxTokenAge only in gih-vision, the jti replay guard only in
+// lihnid, typed config errors only in icm2-sentinel. This unions all four, so
+// adopting the package is strictly a security upgrade for every spoke.
+//
+// Config is passed explicitly rather than read from process.env: each spoke
+// names its own vars (GIH_JWT_AUDIENCE vs LIHNID_JWT_AUDIENCE vs …), and a
+// shared library that reached for one repo's names is precisely why this could
+// not be shared before.
+/**
+ * Required configuration was missing or unusable. Distinct from an auth failure
+ * because it is the *operator's* fault, not the caller's: map it to 500, never
+ * 401, or a misconfigured deployment reads as a stream of rejected callers.
+ */
+export class EventConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EventConfigError';
+    }
+}
+/** The token itself failed verification (bad signature, wrong pin, stale, replayed) → 401. */
+export class EventAuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EventAuthError';
+    }
+}
+/**
+ * Verify an inbound platform event JWT. Fails CLOSED on any misconfig or
+ * mismatch, and throws `EventConfigError` vs `EventAuthError` so the caller can
+ * tell a broken deployment from a rejected caller.
+ *
+ * Pins issuer, audience, `algorithms: ['EdDSA']` and `maxTokenAge`; requires
+ * `jti` and `sub`; and consumes the jti through the replay guard.
+ *
+ * The caller must still pin the subscription — see `assertSubscription`.
+ */
+export async function verifyEventToken(config) {
+    const { token, jwksUrl, expectedAudience, expectedIssuer = 'platform', maxTokenAge = '5m', replayGuard, } = config;
+    if (!token)
+        throw new EventAuthError('event token missing');
+    if (!jwksUrl)
+        throw new EventConfigError('jwksUrl is not set');
+    if (!expectedAudience)
+        throw new EventConfigError('expectedAudience is not set');
+    if (!replayGuard)
+        throw new EventConfigError('replayGuard is not set (pass a guard or the literal "none")');
+    let JWKS;
+    try {
+        JWKS = getRemoteJwks(jwksUrl);
+    }
+    catch (err) {
+        // A malformed jwksUrl is a deployment fault, not a bad caller.
+        throw new EventConfigError(`jwksUrl is not a valid URL: ${err.message}`);
+    }
+    let payload;
+    try {
+        ({ payload } = await jwtVerify(token, JWKS, {
+            issuer: expectedIssuer,
+            audience: expectedAudience,
+            algorithms: ['EdDSA'],
+            maxTokenAge,
+        }));
+    }
+    catch (err) {
+        throw new EventAuthError(`event token verification failed: ${err.message}`);
+    }
+    if (!payload.jti)
+        throw new EventAuthError('event token missing jti');
+    if (!payload.sub)
+        throw new EventAuthError('event token missing sub');
+    const verified = {
+        iss: String(payload.iss),
+        aud: payload.aud,
+        sub: String(payload.sub),
+        jti: String(payload.jti),
+    };
+    // Replay guard last: only consume the jti once the token has actually proven
+    // itself, so an attacker cannot burn jtis with unverifiable tokens.
+    if (replayGuard !== 'none' && (await replayGuard(verified.jti))) {
+        throw new EventAuthError(`event token replayed: jti ${verified.jti} already consumed`);
+    }
+    return verified;
+}
+/**
+ * Assert the verified token belongs to this app's subscription (the `sub` pin).
+ * Separate from `verifyEventToken` because a valid platform token for a
+ * *different* subscription is authentic but not authorised here.
+ */
+export function assertSubscription(token, expectedSubscriptionId) {
+    if (!expectedSubscriptionId)
+        throw new EventConfigError('expectedSubscriptionId is not set');
+    if (token.sub !== expectedSubscriptionId) {
+        throw new EventAuthError(`event token sub mismatch: ${token.sub} !== expected subscription`);
+    }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@venturineai/identity",
+  "version": "0.1.0",
+  "description": "EdDSA service-to-service JWT, JWKS and signed-event verification helpers for the Venturine service mesh",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "types": "./index.d.ts"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "dependencies": {
+    "jose": "^6.0.0"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/VenturineAI/venturine-contracts.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}