@ulexid/node 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# @ulexid/node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Version `0.1.1` — [Ulexid Documentation](https://docs.ulexid.com)
+
+Node.js server SDK for [Ulexid](https://www.ulexid.com) — JWT/JWKS verification, session middleware, and webhooks.
+
+```bash
+npm install @ulexid/node
+```
+
+## License
+
+Proprietary (`UNLICENSED`). Copyright (c) Ulexid. All rights reserved.

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+/**
+ * `@ulexid/node` — Official server-side Node.js & Edge SDK for ulex.
+ *
+ * Capabilities:
+ * - Local JWKS caching and JWT access/ID token verification (`verifyAccessToken`)
+ * - M2M `client_credentials` token acquisition with automatic expiry caching
+ * - RFC 8693 server-side token exchange for scoped agent credentials
+ * - Raw-body Svix-style webhook verification (`ulex-signature`, `ulex-timestamp`, `ulex-id`)
+ *   with strict 5-minute replay tolerance (Invariant #9)
+ * - Typed Management REST helpers (`getUsage`, `listUsers`, `listOrganizations`)
+ */
+import { type JWTPayload } from 'jose';
+import { UlexClient, type FetchLike, type TokenExchangeOptions, type TokenSet } from '@ulexid/js';
+export { UlexOAuthError, type FetchLike, type TokenSet } from '@ulexid/js';
+export declare const WEBHOOK_SIGNATURE_HEADER = "ulex-signature";
+export declare const WEBHOOK_TIMESTAMP_HEADER = "ulex-timestamp";
+export declare const WEBHOOK_ID_HEADER = "ulex-id";
+export interface UlexServerClientConfig {
+    readonly issuer: string;
+    readonly clientId?: string;
+    readonly clientSecret?: string;
+    /** Management API key (`ulex_live_...` or `ulex_test_...`) for `/api/v1/*` endpoints. */
+    readonly apiKey?: string;
+    /** Expected JWT `aud` claim when verifying access tokens. */
+    readonly audience?: string | readonly string[];
+    /** JWKS cache TTL in milliseconds (default: 5 minutes). */
+    readonly jwksTtlMs?: number;
+    readonly fetch?: FetchLike;
+}
+export interface VerifyAccessTokenOptions {
+    readonly audience?: string | readonly string[];
+    readonly requiredScopes?: readonly string[];
+    readonly clockToleranceSeconds?: number;
+}
+export interface VerifiedAccessToken {
+    readonly sub: string;
+    readonly iss: string;
+    readonly aud?: string | readonly string[];
+    readonly exp?: number;
+    readonly iat?: number;
+    readonly scopes: readonly string[];
+    readonly orgId?: string;
+    readonly clientId?: string;
+    readonly claims: JWTPayload;
+}
+export interface WebhookVerifyOptions {
+    /** Maximum age of webhook timestamp in seconds (default: 300 = 5 minutes). */
+    readonly toleranceSeconds?: number;
+    /** Maximum future skew in seconds (default: 60). */
+    readonly futureToleranceSeconds?: number;
+    /** Override current epoch milliseconds for deterministic testing. */
+    readonly nowMs?: number;
+}
+export type WebhookFailureReason = 'missing_signature' | 'missing_timestamp' | 'missing_id' | 'malformed_timestamp' | 'timestamp_out_of_tolerance' | 'signature_mismatch';
+export declare class UlexWebhookVerificationError extends Error {
+    readonly reason: WebhookFailureReason;
+    constructor(reason: WebhookFailureReason, message: string);
+}
+export declare class UlexTokenVerificationError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Verifies a ulex webhook against the **raw unparsed UTF-8 body** (Invariant #9)
+ * and rejects timestamps older than 5 minutes by default.
+ */
+export declare function verifyWebhookSignature<T = Record<string, unknown>>(rawBody: string | Buffer, headers: Headers | Record<string, string | readonly string[] | undefined>, secret: string | Buffer, options?: WebhookVerifyOptions): T;
+export interface TenantUsageResponse {
+    readonly usage: Record<string, unknown>;
+    readonly requests: Record<string, number>;
+    readonly billing: Record<string, unknown>;
+    readonly plan_limits_enforced: boolean;
+}
+export declare class UlexServerClient {
+    readonly issuer: string;
+    readonly oauth: UlexClient;
+    private readonly clientId?;
+    private readonly clientSecret?;
+    private readonly apiKey?;
+    private readonly defaultAudience?;
+    private readonly jwksTtlMs;
+    private readonly fetchImpl;
+    private cachedJwks;
+    private cachedM2M;
+    constructor(config: UlexServerClientConfig);
+    /**
+     * Verifies a JWT access or ID token against the tenant's JWKS (`/oauth2/keys`),
+     * checking cryptographic signature, `iss`, `exp`, optional `aud`, and `requiredScopes`.
+     */
+    verifyAccessToken(token: string, options?: VerifyAccessTokenOptions): Promise<VerifiedAccessToken>;
+    /**
+     * Acquires and caches an M2M `client_credentials` token, refreshing 30 seconds
+     * prior to expiration.
+     */
+    getM2MToken(scopes?: readonly string[]): Promise<TokenSet>;
+    /**
+     * Server-authenticated RFC 8693 token exchange (`urn:ietf:params:oauth:grant-type:token-exchange`).
+     */
+    exchangeToken(options: Omit<TokenExchangeOptions, 'clientSecret'>): Promise<TokenSet>;
+    getUsage(): Promise<TenantUsageResponse>;
+    listUsers(limit?: number, cursor?: string): Promise<{
+        data: unknown[];
+        next_cursor: string | null;
+    }>;
+    listOrganizations(limit?: number, cursor?: string): Promise<{
+        data: unknown[];
+        next_cursor: string | null;
+    }>;
+    private apiGet;
+    private getJwks;
+}

package/dist/index.js

@@ -0,0 +1,282 @@
+/**
+ * `@ulexid/node` — Official server-side Node.js & Edge SDK for ulex.
+ *
+ * Capabilities:
+ * - Local JWKS caching and JWT access/ID token verification (`verifyAccessToken`)
+ * - M2M `client_credentials` token acquisition with automatic expiry caching
+ * - RFC 8693 server-side token exchange for scoped agent credentials
+ * - Raw-body Svix-style webhook verification (`ulex-signature`, `ulex-timestamp`, `ulex-id`)
+ *   with strict 5-minute replay tolerance (Invariant #9)
+ * - Typed Management REST helpers (`getUsage`, `listUsers`, `listOrganizations`)
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { createLocalJWKSet, jwtVerify } from 'jose';
+import { UlexClient, UlexOAuthError, } from '@ulexid/js';
+export { UlexOAuthError } from '@ulexid/js';
+export const WEBHOOK_SIGNATURE_HEADER = 'ulex-signature';
+export const WEBHOOK_TIMESTAMP_HEADER = 'ulex-timestamp';
+export const WEBHOOK_ID_HEADER = 'ulex-id';
+export class UlexWebhookVerificationError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'UlexWebhookVerificationError';
+        this.reason = reason;
+    }
+}
+export class UlexTokenVerificationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'UlexTokenVerificationError';
+        this.code = code;
+    }
+}
+function getHeaderCaseInsensitive(headers, name) {
+    if (headers instanceof Headers) {
+        return headers.get(name) ?? undefined;
+    }
+    const lower = name.toLowerCase();
+    for (const [k, v] of Object.entries(headers)) {
+        if (k.toLowerCase() === lower) {
+            if (typeof v === 'string')
+                return v;
+            if (Array.isArray(v))
+                return v[0];
+        }
+    }
+    return undefined;
+}
+/**
+ * Verifies a ulex webhook against the **raw unparsed UTF-8 body** (Invariant #9)
+ * and rejects timestamps older than 5 minutes by default.
+ */
+export function verifyWebhookSignature(rawBody, headers, secret, options = {}) {
+    const bodyStr = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf8');
+    const sigHeader = getHeaderCaseInsensitive(headers, WEBHOOK_SIGNATURE_HEADER);
+    const tsHeader = getHeaderCaseInsensitive(headers, WEBHOOK_TIMESTAMP_HEADER);
+    const idHeader = getHeaderCaseInsensitive(headers, WEBHOOK_ID_HEADER);
+    if (!sigHeader) {
+        throw new UlexWebhookVerificationError('missing_signature', 'Missing `ulex-signature` header.');
+    }
+    if (!tsHeader) {
+        throw new UlexWebhookVerificationError('missing_timestamp', 'Missing `ulex-timestamp` header.');
+    }
+    if (!idHeader) {
+        throw new UlexWebhookVerificationError('missing_id', 'Missing `ulex-id` header.');
+    }
+    const timestampSec = Number(tsHeader);
+    if (!Number.isFinite(timestampSec)) {
+        throw new UlexWebhookVerificationError('malformed_timestamp', 'Invalid numeric `ulex-timestamp`.');
+    }
+    const nowSec = Math.floor((options.nowMs ?? Date.now()) / 1000);
+    const tolerance = options.toleranceSeconds ?? 300;
+    const futureTolerance = options.futureToleranceSeconds ?? 60;
+    const age = nowSec - timestampSec;
+    if (age > tolerance || age < -futureTolerance) {
+        throw new UlexWebhookVerificationError('timestamp_out_of_tolerance', `Webhook timestamp ${timestampSec} is outside the ${tolerance}s replay window.`);
+    }
+    const signedPayload = `${idHeader}.${timestampSec}.${bodyStr}`;
+    const expectedMac = createHmac('sha256', secret).update(signedPayload, 'utf8').digest();
+    const candidates = sigHeader.split(/\s+/).filter(Boolean);
+    let matched = false;
+    for (const token of candidates) {
+        const commaIdx = token.indexOf(',');
+        if (commaIdx <= 0)
+            continue;
+        const version = token.slice(0, commaIdx);
+        const b64 = token.slice(commaIdx + 1);
+        if (version !== 'v1' || !b64)
+            continue;
+        const candidateBytes = Buffer.from(b64, 'base64');
+        if (candidateBytes.length === expectedMac.length && timingSafeEqual(candidateBytes, expectedMac)) {
+            matched = true;
+        }
+    }
+    if (!matched) {
+        throw new UlexWebhookVerificationError('signature_mismatch', 'Webhook HMAC-SHA256 signature verification failed.');
+    }
+    return JSON.parse(bodyStr);
+}
+export class UlexServerClient {
+    issuer;
+    oauth;
+    clientId;
+    clientSecret;
+    apiKey;
+    defaultAudience;
+    jwksTtlMs;
+    fetchImpl;
+    cachedJwks = null;
+    cachedM2M = new Map();
+    constructor(config) {
+        this.issuer = config.issuer.trim().replace(/\/+$/, '');
+        this.clientId = config.clientId;
+        this.clientSecret = config.clientSecret;
+        this.apiKey = config.apiKey;
+        this.defaultAudience = config.audience;
+        this.jwksTtlMs = config.jwksTtlMs ?? 300_000;
+        this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+        this.oauth = new UlexClient({
+            issuer: this.issuer,
+            clientId: config.clientId,
+            fetch: this.fetchImpl,
+        });
+    }
+    /**
+     * Verifies a JWT access or ID token against the tenant's JWKS (`/oauth2/keys`),
+     * checking cryptographic signature, `iss`, `exp`, optional `aud`, and `requiredScopes`.
+     */
+    async verifyAccessToken(token, options = {}) {
+        const jwks = await this.getJwks(false);
+        const audience = options.audience ?? this.defaultAudience;
+        const verifyOpts = {
+            issuer: this.issuer,
+            clockTolerance: options.clockToleranceSeconds ?? 5,
+            ...(audience ? { audience: Array.isArray(audience) ? [...audience] : audience } : {}),
+        };
+        let payload;
+        try {
+            const verified = await jwtVerify(token, jwks, verifyOpts);
+            payload = verified.payload;
+        }
+        catch {
+            // Refresh JWKS once in case the tenant just rotated signing keys.
+            const refreshedJwks = await this.getJwks(true);
+            try {
+                const verified = await jwtVerify(token, refreshedJwks, verifyOpts);
+                payload = verified.payload;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : 'JWT verification failed';
+                throw new UlexTokenVerificationError('invalid_token', msg);
+            }
+        }
+        if (!payload.sub) {
+            throw new UlexTokenVerificationError('missing_sub', 'Verified token is missing `sub` claim.');
+        }
+        const rawScope = typeof payload['scope'] === 'string' ? payload['scope'] : '';
+        const scopes = rawScope ? rawScope.split(/\s+/).filter(Boolean) : [];
+        if (options.requiredScopes?.length) {
+            const scopeSet = new Set(scopes);
+            const missing = options.requiredScopes.filter((s) => !scopeSet.has(s));
+            if (missing.length > 0) {
+                throw new UlexTokenVerificationError('insufficient_scope', `Token is missing required scope(s): ${missing.join(', ')}`);
+            }
+        }
+        return {
+            sub: payload.sub,
+            iss: payload.iss ?? this.issuer,
+            aud: payload.aud,
+            exp: payload.exp,
+            iat: payload.iat,
+            scopes,
+            orgId: typeof payload['org_id'] === 'string' ? payload['org_id'] : undefined,
+            clientId: typeof payload['client_id'] === 'string' ? payload['client_id'] : undefined,
+            claims: payload,
+        };
+    }
+    /**
+     * Acquires and caches an M2M `client_credentials` token, refreshing 30 seconds
+     * prior to expiration.
+     */
+    async getM2MToken(scopes = []) {
+        if (!this.clientId || !this.clientSecret) {
+            throw new UlexOAuthError('missing_client_credentials', 400, '`clientId` and `clientSecret` are required for `client_credentials` grant.');
+        }
+        const cacheKey = [...scopes].sort().join(' ');
+        const cached = this.cachedM2M.get(cacheKey);
+        if (cached && cached.expiresAt > Date.now()) {
+            return cached.token;
+        }
+        const body = new URLSearchParams({
+            grant_type: 'client_credentials',
+            client_id: this.clientId,
+            client_secret: this.clientSecret,
+        });
+        if (scopes.length > 0) {
+            body.set('scope', scopes.join(' '));
+        }
+        const res = await this.fetchImpl(`${this.issuer}/oauth2/token`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/x-www-form-urlencoded',
+                accept: 'application/json',
+            },
+            body: body.toString(),
+        });
+        if (!res.ok) {
+            const payload = (await res.json().catch(() => ({})));
+            const code = typeof payload['error'] === 'string' ? payload['error'] : `http_${res.status}`;
+            const desc = typeof payload['error_description'] === 'string' ? payload['error_description'] : undefined;
+            throw new UlexOAuthError(code, res.status, desc);
+        }
+        const token = (await res.json());
+        const ttlMs = Math.max(0, (token.expires_in - 30) * 1000);
+        this.cachedM2M.set(cacheKey, { token, expiresAt: Date.now() + ttlMs });
+        return token;
+    }
+    /**
+     * Server-authenticated RFC 8693 token exchange (`urn:ietf:params:oauth:grant-type:token-exchange`).
+     */
+    async exchangeToken(options) {
+        return this.oauth.exchangeToken({
+            ...options,
+            clientSecret: this.clientSecret,
+        });
+    }
+    async getUsage() {
+        return this.apiGet('/api/v1/usage');
+    }
+    async listUsers(limit = 50, cursor) {
+        const qs = new URLSearchParams({ limit: String(limit) });
+        if (cursor)
+            qs.set('cursor', cursor);
+        return this.apiGet(`/api/v1/users?${qs.toString()}`);
+    }
+    async listOrganizations(limit = 50, cursor) {
+        const qs = new URLSearchParams({ limit: String(limit) });
+        if (cursor)
+            qs.set('cursor', cursor);
+        return this.apiGet(`/api/v1/organizations?${qs.toString()}`);
+    }
+    async apiGet(path) {
+        if (!this.apiKey) {
+            throw new UlexOAuthError('missing_api_key', 401, 'Management API calls require `apiKey`.');
+        }
+        const baseOrigin = new URL(this.issuer).origin;
+        const res = await this.fetchImpl(`${baseOrigin}${path}`, {
+            method: 'GET',
+            headers: {
+                authorization: `Bearer ${this.apiKey}`,
+                accept: 'application/json',
+            },
+        });
+        if (!res.ok) {
+            const payload = (await res.json().catch(() => ({})));
+            const nested = typeof payload['error'] === 'object' && payload['error'] !== null
+                ? payload['error']
+                : null;
+            const code = typeof nested?.['code'] === 'string' ? nested['code'] : `http_${res.status}`;
+            const msg = typeof nested?.['message'] === 'string' ? nested['message'] : undefined;
+            throw new UlexOAuthError(code, res.status, msg);
+        }
+        return (await res.json());
+    }
+    async getJwks(forceRefresh) {
+        if (!forceRefresh && this.cachedJwks && this.cachedJwks.expiresAt > Date.now()) {
+            return this.cachedJwks.set;
+        }
+        const res = await this.fetchImpl(`${this.issuer}/oauth2/keys`, {
+            method: 'GET',
+            headers: { accept: 'application/json' },
+        });
+        if (!res.ok) {
+            throw new UlexTokenVerificationError('jwks_fetch_failed', `Failed to fetch JWKS from ${this.issuer}/oauth2/keys (HTTP ${res.status}).`);
+        }
+        const jwksJson = (await res.json());
+        const set = createLocalJWKSet(jwksJson);
+        this.cachedJwks = { set, expiresAt: Date.now() + this.jwksTtlMs };
+        return set;
+    }
+}

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@ulexid/node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "license": "UNLICENSED",
+  "type": "module",
+  "description": "Official server-side Node.js and Edge SDK for Ulexid: JWKS JWT verification, M2M client credentials, RFC 8693 agent token exchange, Svix-compatible webhook verification, and management API client.",
+  "homepage": "https://www.ulexid.com",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@ulexid/js": "0.1.1",
+    "jose": "^5.9.6"
+  }
+}