@qnsp/tenant-sdk 0.0.1

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@qnsp/tenant-sdk",
+  "version": "0.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "description": "TypeScript SDK client for the QNSP tenant-service API. Provides tenant lifecycle and subscription management.",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.208.0",
+    "@opentelemetry/sdk-metrics": "^2.2.0",
+    "@qnsp/observability": "^0.0.1",
+    "undici": "^7.16.0",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.14",
+    "tsx": "^4.20.6",
+    "vitest": "^4.0.10"
+  },
+  "engines": {
+    "node": "24.12.0"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "dev": "tsx watch src/index.ts",
+    "lint": "biome check .",
+    "test": "vitest run",
+    "typecheck": "tsc --project tsconfig.json --noEmit"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,165 @@
+import { describe, expect, it, vi } from "vitest";
+import { TenantClient } from "./index.js";
+
+describe("TenantClient Security Tests", () => {
+	const mockFetch = vi.fn();
+	global.fetch = mockFetch;
+
+	describe("HTTPS Enforcement", () => {
+		it("should reject HTTP URLs in production", () => {
+			const originalEnv = process.env["NODE_ENV"];
+			process.env["NODE_ENV"] = "production";
+
+			expect(() => {
+				new TenantClient({
+					baseUrl: "http://example.com",
+				});
+			}).toThrow("baseUrl must use HTTPS in production");
+
+			process.env["NODE_ENV"] = originalEnv;
+		});
+
+		it("should allow HTTP localhost in development", () => {
+			const originalEnv = process.env["NODE_ENV"];
+			process.env["NODE_ENV"] = "development";
+
+			expect(() => {
+				new TenantClient({
+					baseUrl: "http://localhost:3000",
+				});
+			}).not.toThrow();
+
+			process.env["NODE_ENV"] = originalEnv;
+		});
+	});
+
+	describe("Input Validation", () => {
+		const client = new TenantClient({
+			baseUrl: "https://api.example.com",
+		});
+
+		it("should reject invalid UUIDs", async () => {
+			await expect(client.getTenant("not-a-uuid")).rejects.toThrow("Invalid id");
+		});
+
+		it("should reject SQL injection in tenantId", async () => {
+			await expect(client.getTenant("'; DROP TABLE tenants; --")).rejects.toThrow("Invalid id");
+		});
+
+		it("should reject path traversal in tenantId", async () => {
+			await expect(client.getTenant("../../etc/passwd")).rejects.toThrow("Invalid id");
+		});
+
+		it("should reject XSS attempts in tenantId", async () => {
+			await expect(client.getTenant("<script>alert('xss')</script>")).rejects.toThrow("Invalid id");
+		});
+	});
+
+	describe("Error Message Sanitization", () => {
+		const client = new TenantClient({
+			baseUrl: "https://api.example.com",
+		});
+
+		it("should not expose sensitive data in error messages", async () => {
+			mockFetch.mockResolvedValueOnce({
+				ok: false,
+				status: 500,
+				statusText: "Internal Server Error",
+				headers: new Headers(),
+				text: async () =>
+					JSON.stringify({
+						error: "Database connection failed",
+						stack: "at TenantService.getTenant()",
+						apiKey: "sk_live_1234567890",
+						password: "secret123",
+					}),
+			});
+
+			await expect(client.getTenant("123e4567-e89b-12d3-a456-426614174000")).rejects.toThrow(
+				"Tenant API error: 500 Internal Server Error",
+			);
+
+			const errorMessage = await (async () => {
+				try {
+					await client.getTenant("123e4567-e89b-12d3-a456-426614174000");
+					return "";
+				} catch (error) {
+					return error instanceof Error ? error.message : String(error);
+				}
+			})();
+
+			expect(errorMessage).not.toContain("sk_live_1234567890");
+			expect(errorMessage).not.toContain("secret123");
+			expect(errorMessage).not.toContain("Database connection failed");
+			expect(errorMessage).not.toContain("stack");
+		});
+	});
+
+	describe("Rate Limiting", () => {
+		const client = new TenantClient({
+			baseUrl: "https://api.example.com",
+			maxRetries: 2,
+			retryDelayMs: 10,
+		});
+
+		it("should retry on 429 with Retry-After header", async () => {
+			let attemptCount = 0;
+			mockFetch.mockImplementation(async () => {
+				attemptCount++;
+				if (attemptCount === 1) {
+					return {
+						ok: false,
+						status: 429,
+						statusText: "Too Many Requests",
+						headers: new Headers({ "Retry-After": "1" }),
+						text: async () => "",
+					};
+				}
+				return {
+					ok: true,
+					status: 200,
+					headers: new Headers(),
+					json: async () => ({
+						id: "123e4567-e89b-12d3-a456-426614174000",
+						name: "test-tenant",
+						slug: "test-tenant",
+						status: "active",
+						plan: "basic",
+						region: "us-east-1",
+						complianceTags: [],
+						metadata: {},
+						security: {
+							controlPlaneTokenSha256: null,
+							pqcSignatures: [],
+							hardwareProvider: null,
+							attestationStatus: null,
+							attestationProof: null,
+						},
+						domains: [],
+						createdAt: "2024-01-01T00:00:00Z",
+						updatedAt: "2024-01-01T00:00:00Z",
+					}),
+				};
+			});
+
+			const result = await client.getTenant("123e4567-e89b-12d3-a456-426614174000");
+
+			expect(result.id).toBe("123e4567-e89b-12d3-a456-426614174000");
+			expect(attemptCount).toBe(2);
+		});
+
+		it("should fail after max retries", async () => {
+			mockFetch.mockResolvedValue({
+				ok: false,
+				status: 429,
+				statusText: "Too Many Requests",
+				headers: new Headers(),
+				text: async () => "",
+			});
+
+			await expect(client.getTenant("123e4567-e89b-12d3-a456-426614174000")).rejects.toThrow(
+				"Rate limit exceeded after 2 retries",
+			);
+		});
+	});
+});

package/src/index.ts

@@ -0,0 +1,359 @@
+import { performance } from "node:perf_hooks";
+
+import type {
+	TenantClientTelemetry,
+	TenantClientTelemetryConfig,
+	TenantClientTelemetryEvent,
+} from "./observability.js";
+import { createTenantClientTelemetry, isTenantClientTelemetry } from "./observability.js";
+import { validateUUID } from "./validation.js";
+
+/**
+ * @qnsp/tenant-sdk
+ *
+ * TypeScript SDK client for the QNSP tenant-service API.
+ * Provides a high-level interface for tenant lifecycle and subscription management.
+ */
+
+export interface TenantClientConfig {
+	readonly baseUrl: string;
+	readonly apiKey?: string;
+	readonly timeoutMs?: number;
+	readonly telemetry?: TenantClientTelemetry | TenantClientTelemetryConfig;
+	readonly maxRetries?: number;
+	readonly retryDelayMs?: number;
+}
+
+type InternalTenantClientConfig = {
+	readonly baseUrl: string;
+	readonly apiKey: string;
+	readonly timeoutMs: number;
+	readonly maxRetries: number;
+	readonly retryDelayMs: number;
+};
+
+export type TenantStatus = "active" | "suspended" | "pending" | "deleted";
+
+export interface TenantSecurityEnvelope {
+	readonly controlPlaneTokenSha256: string | null;
+	readonly pqcSignatures: readonly {
+		readonly provider: string;
+		readonly algorithm: string;
+		readonly value: string;
+		readonly publicKey: string;
+	}[];
+	readonly hardwareProvider: string | null;
+	readonly attestationStatus: string | null;
+	readonly attestationProof: string | null;
+}
+
+export interface TenantSignature {
+	readonly provider: string;
+	readonly algorithm: string;
+	readonly value: string;
+	readonly publicKey: string;
+}
+
+export interface TenantDomain {
+	readonly id: string;
+	readonly domain: string;
+	readonly verified: boolean;
+	readonly createdAt: string;
+	readonly updatedAt: string;
+}
+
+export interface Tenant {
+	readonly id: string;
+	readonly name: string;
+	readonly slug: string;
+	readonly status: TenantStatus;
+	readonly plan: string;
+	readonly region: string;
+	readonly complianceTags: readonly string[];
+	readonly metadata: Record<string, unknown>;
+	readonly security: TenantSecurityEnvelope;
+	readonly domains: readonly TenantDomain[];
+	readonly createdAt: string;
+	readonly updatedAt: string;
+}
+
+export interface CreateTenantRequest {
+	readonly name: string;
+	readonly slug: string;
+	readonly plan?: string;
+	readonly region?: string;
+	readonly complianceTags?: readonly string[];
+	readonly metadata?: Record<string, unknown>;
+	readonly domains?: readonly {
+		readonly domain: string;
+		readonly verified?: boolean;
+	}[];
+	readonly security: TenantSecurityEnvelope;
+	readonly signature?: TenantSignature;
+}
+
+export interface UpdateTenantRequest {
+	readonly plan?: string;
+	readonly status?: TenantStatus;
+	readonly complianceTags?: readonly string[];
+	readonly metadata?: Record<string, unknown>;
+	readonly security: TenantSecurityEnvelope;
+	readonly signature?: TenantSignature;
+}
+
+export interface ListTenantsResponse {
+	readonly items: readonly Tenant[];
+	readonly nextCursor: string | null;
+}
+
+interface RequestOptions {
+	readonly body?: unknown;
+	readonly headers?: Record<string, string>;
+	readonly signal?: AbortSignal;
+	readonly operation?: string;
+	readonly telemetryRoute?: string;
+	readonly telemetryTarget?: string;
+}
+
+export class TenantClient {
+	private readonly config: InternalTenantClientConfig;
+	private readonly telemetry: TenantClientTelemetry | null;
+	private readonly targetService: string;
+
+	constructor(config: TenantClientConfig) {
+		const baseUrl = config.baseUrl.replace(/\/$/, "");
+
+		// Enforce HTTPS in production (allow HTTP only for localhost in development)
+		if (!baseUrl.startsWith("https://")) {
+			const isLocalhost =
+				baseUrl.startsWith("http://localhost") || baseUrl.startsWith("http://127.0.0.1");
+			const isDevelopment =
+				process.env["NODE_ENV"] === "development" || process.env["NODE_ENV"] === "test";
+			if (!isLocalhost || !isDevelopment) {
+				throw new Error(
+					"baseUrl must use HTTPS in production. HTTP is only allowed for localhost in development.",
+				);
+			}
+		}
+
+		this.config = {
+			baseUrl,
+			apiKey: config.apiKey ?? "",
+			timeoutMs: config.timeoutMs ?? 30_000,
+			maxRetries: config.maxRetries ?? 3,
+			retryDelayMs: config.retryDelayMs ?? 1_000,
+		};
+
+		this.telemetry = config.telemetry
+			? isTenantClientTelemetry(config.telemetry)
+				? config.telemetry
+				: createTenantClientTelemetry(config.telemetry)
+			: null;
+
+		try {
+			this.targetService = new URL(this.config.baseUrl).host;
+		} catch {
+			this.targetService = "tenant-service";
+		}
+	}
+
+	private async request<T>(method: string, path: string, options?: RequestOptions): Promise<T> {
+		return this.requestWithRetry<T>(method, path, options, 0);
+	}
+
+	private async requestWithRetry<T>(
+		method: string,
+		path: string,
+		options: RequestOptions | undefined,
+		attempt: number,
+	): Promise<T> {
+		const url = `${this.config.baseUrl}${path}`;
+		const headers: Record<string, string> = {
+			"Content-Type": "application/json",
+			...options?.headers,
+		};
+
+		if (this.config.apiKey) {
+			headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+		}
+
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs);
+		const signal = options?.signal ?? controller.signal;
+		const route = options?.telemetryRoute ?? new URL(path, this.config.baseUrl).pathname;
+		const target = options?.telemetryTarget ?? this.targetService;
+		const start = performance.now();
+		let status: "ok" | "error" = "ok";
+		let httpStatus: number | undefined;
+		let errorMessage: string | undefined;
+
+		try {
+			const init: RequestInit = {
+				method,
+				headers,
+				signal,
+			};
+
+			if (options?.body !== undefined) {
+				init.body = JSON.stringify(options.body);
+			}
+
+			const response = await fetch(url, init);
+
+			clearTimeout(timeoutId);
+			httpStatus = response.status;
+
+			// Handle rate limiting (429) with retry logic
+			if (response.status === 429) {
+				if (attempt < this.config.maxRetries) {
+					const retryAfterHeader = response.headers.get("Retry-After");
+					let delayMs = this.config.retryDelayMs;
+
+					if (retryAfterHeader) {
+						const retryAfterSeconds = Number.parseInt(retryAfterHeader, 10);
+						if (!Number.isNaN(retryAfterSeconds) && retryAfterSeconds > 0) {
+							delayMs = retryAfterSeconds * 1_000;
+						}
+					} else {
+						// Exponential backoff: 2^attempt * baseDelay, capped at 30 seconds
+						delayMs = Math.min(2 ** attempt * this.config.retryDelayMs, 30_000);
+					}
+
+					await new Promise((resolve) => setTimeout(resolve, delayMs));
+					return this.requestWithRetry<T>(method, path, options, attempt + 1);
+				}
+
+				status = "error";
+				errorMessage = `HTTP ${response.status}`;
+				throw new Error(
+					`Tenant API error: Rate limit exceeded after ${this.config.maxRetries} retries`,
+				);
+			}
+
+			if (!response.ok) {
+				status = "error";
+				// Sanitize error message to prevent information disclosure
+				// Don't include full response text in error to avoid leaking sensitive data
+				errorMessage = `HTTP ${response.status}`;
+				throw new Error(`Tenant API error: ${response.status} ${response.statusText}`);
+			}
+
+			if (response.status === 204) {
+				return undefined as T;
+			}
+
+			return (await response.json()) as T;
+		} catch (error) {
+			clearTimeout(timeoutId);
+			status = "error";
+			if (!errorMessage && error instanceof Error) {
+				errorMessage = error.message;
+			}
+			if (error instanceof Error && error.name === "AbortError") {
+				errorMessage = `timeout after ${this.config.timeoutMs}ms`;
+				throw new Error(`Request timeout after ${this.config.timeoutMs}ms`);
+			}
+			throw error;
+		} finally {
+			const durationMs = performance.now() - start;
+			const event: TenantClientTelemetryEvent = {
+				operation: options?.operation ?? `${method} ${route}`,
+				method,
+				route,
+				target,
+				status,
+				durationMs,
+				...(typeof httpStatus === "number" ? { httpStatus } : {}),
+				...(status === "error" && errorMessage ? { error: errorMessage } : {}),
+			};
+			this.recordTelemetryEvent(event);
+		}
+	}
+
+	private recordTelemetryEvent(event: TenantClientTelemetryEvent): void {
+		if (!this.telemetry) {
+			return;
+		}
+		this.telemetry.record(event);
+	}
+
+	/**
+	 * Create a new tenant.
+	 * Requires PQC-signed security envelope and optional signature.
+	 */
+	async createTenant(request: CreateTenantRequest): Promise<Tenant> {
+		// Validation is handled by the service, but we validate format here for early feedback
+		return this.request<Tenant>("POST", "/tenant/v1/tenants", {
+			body: {
+				name: request.name,
+				slug: request.slug,
+				...(request.plan !== undefined ? { plan: request.plan } : {}),
+				...(request.region !== undefined ? { region: request.region } : {}),
+				...(request.complianceTags !== undefined ? { complianceTags: request.complianceTags } : {}),
+				...(request.metadata !== undefined ? { metadata: request.metadata } : {}),
+				...(request.domains !== undefined ? { domains: request.domains } : {}),
+				security: request.security,
+				...(request.signature !== undefined ? { signature: request.signature } : {}),
+			},
+			operation: "createTenant",
+		});
+	}
+
+	/**
+	 * Update a tenant's plan, status, compliance tags, or metadata.
+	 * Requires PQC-signed security envelope and optional signature.
+	 */
+	async updateTenant(id: string, request: UpdateTenantRequest): Promise<Tenant> {
+		validateUUID(id, "id");
+
+		return this.request<Tenant>("PATCH", `/tenant/v1/tenants/${id}`, {
+			body: {
+				...(request.plan !== undefined ? { plan: request.plan } : {}),
+				...(request.status !== undefined ? { status: request.status } : {}),
+				...(request.complianceTags !== undefined ? { complianceTags: request.complianceTags } : {}),
+				...(request.metadata !== undefined ? { metadata: request.metadata } : {}),
+				security: request.security,
+				...(request.signature !== undefined ? { signature: request.signature } : {}),
+			},
+			operation: "updateTenant",
+		});
+	}
+
+	/**
+	 * Get a tenant by ID.
+	 * Returns the tenant with domains and security envelope.
+	 */
+	async getTenant(id: string): Promise<Tenant> {
+		validateUUID(id, "id");
+
+		return this.request<Tenant>("GET", `/tenant/v1/tenants/${id}`, {
+			operation: "getTenant",
+		});
+	}
+
+	/**
+	 * List tenants with cursor-based pagination.
+	 * Returns a list of tenants and an optional next cursor for pagination.
+	 */
+	async listTenants(options?: {
+		readonly limit?: number;
+		readonly cursor?: string;
+	}): Promise<ListTenantsResponse> {
+		const params = new URLSearchParams();
+		if (options?.limit !== undefined) {
+			params.set("limit", String(options.limit));
+		}
+		if (options?.cursor !== undefined) {
+			params.set("cursor", options.cursor);
+		}
+		const queryString = params.toString();
+		const path = queryString ? `/tenant/v1/tenants?${queryString}` : "/tenant/v1/tenants";
+
+		return this.request<ListTenantsResponse>("GET", path, {
+			operation: "listTenants",
+		});
+	}
+}
+
+export * from "./observability.js";
+export * from "./validation.js";

package/src/observability.ts

@@ -0,0 +1,115 @@
+import type { Attributes } from "@opentelemetry/api";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import type { MetricReader } from "@opentelemetry/sdk-metrics";
+import {
+	ConsoleMetricExporter,
+	createCounter,
+	createHistogram,
+	createMeterProvider,
+	PeriodicExportingMetricReader,
+} from "@qnsp/observability";
+
+export interface TenantClientTelemetryConfig {
+	readonly serviceName: string;
+	readonly serviceVersion?: string;
+	readonly environment?: string;
+	readonly otlpEndpoint?: string;
+	readonly metricsIntervalMs?: number;
+	readonly metricsTimeoutMs?: number;
+	readonly exporterFactory?: () => MetricReader;
+}
+
+export interface TenantClientTelemetryEvent {
+	readonly operation: string;
+	readonly method: string;
+	readonly route: string;
+	readonly status: "ok" | "error";
+	readonly durationMs: number;
+	readonly httpStatus?: number;
+	readonly target?: string;
+	readonly error?: string;
+}
+
+export interface TenantClientTelemetry {
+	record(event: TenantClientTelemetryEvent): void;
+}
+
+export function createTenantClientTelemetry(
+	config: TenantClientTelemetryConfig,
+): TenantClientTelemetry {
+	const interval = config.metricsIntervalMs ?? 60_000;
+	const timeout = config.metricsTimeoutMs ?? 15_000;
+	const readers: MetricReader[] = [];
+
+	if (typeof config.exporterFactory === "function") {
+		readers.push(config.exporterFactory());
+	} else if (config.otlpEndpoint) {
+		readers.push(
+			new PeriodicExportingMetricReader({
+				exporter: new OTLPMetricExporter({
+					url: config.otlpEndpoint,
+				}),
+				exportIntervalMillis: interval,
+				exportTimeoutMillis: timeout,
+			}),
+		);
+	} else if (process.env["NODE_ENV"] !== "test") {
+		readers.push(
+			new PeriodicExportingMetricReader({
+				exporter: new ConsoleMetricExporter(),
+				exportIntervalMillis: interval,
+				exportTimeoutMillis: timeout,
+			}),
+		);
+	}
+
+	const provider = createMeterProvider(
+		{
+			serviceName: config.serviceName,
+			serviceVersion: config.serviceVersion ?? "0.0.0",
+			environment: config.environment ?? process.env["NODE_ENV"] ?? "development",
+		},
+		readers,
+	);
+
+	const requestCounter = createCounter(provider, "tenant_sdk_requests_total", {
+		description: "Count of Tenant SDK HTTP requests",
+	});
+	const failureCounter = createCounter(provider, "tenant_sdk_request_failures_total", {
+		description: "Count of failed Tenant SDK HTTP requests",
+	});
+	const durationHistogram = createHistogram(provider, "tenant_sdk_request_duration_ms", {
+		description: "Latency of Tenant SDK HTTP requests",
+		unit: "ms",
+	});
+
+	return {
+		record(event) {
+			const baseAttributes: Attributes = {
+				service: config.serviceName,
+				operation: event.operation,
+				method: event.method,
+				route: event.route,
+				target: event.target ?? event.route,
+				status: event.status,
+				...(event.httpStatus ? { http_status: event.httpStatus } : {}),
+			};
+
+			requestCounter.add(1, baseAttributes);
+			durationHistogram.record(event.durationMs, baseAttributes);
+
+			if (event.status === "error") {
+				failureCounter.add(1, {
+					...baseAttributes,
+					error: event.error ?? "unknown",
+				});
+			}
+		},
+	};
+}
+
+export function isTenantClientTelemetry(
+	value: TenantClientTelemetry | TenantClientTelemetryConfig,
+): value is TenantClientTelemetry {
+	return typeof (value as TenantClientTelemetry)?.record === "function";
+}

package/src/validation.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+/**
+ * Validation schemas for tenant-sdk inputs
+ */
+
+export const uuidSchema = z.string().uuid("Invalid UUID format");
+
+/**
+ * Validates a UUID string
+ */
+export function validateUUID(value: string, fieldName: string): void {
+	try {
+		uuidSchema.parse(value);
+	} catch (error) {
+		if (error instanceof z.ZodError) {
+			throw new Error(`Invalid ${fieldName}: ${error.issues[0]?.message ?? "Invalid format"}`);
+		}
+		throw error;
+	}
+}

package/tsconfig.build.json

@@ -0,0 +1,10 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"outDir": "dist",
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true
+	},
+	"exclude": ["src/**/*.test.ts", "src/**/*.spec.ts", "dist", "build"]
+}