@qnsp/storage-sdk 0.1.0 → 0.3.0

package/src/index.ts

@@ -1,24 +1,156 @@
-import { performance } from "node:perf_hooks";
-
 import type {
 	StorageClientTelemetry,
 	StorageClientTelemetryConfig,
 	StorageClientTelemetryEvent,
 } from "./observability.js";
 import { createStorageClientTelemetry, isStorageClientTelemetry } from "./observability.js";
+import { validateUUID } from "./validation.js";
 
 /**
  * @qnsp/storage-sdk
  *
  * TypeScript SDK client for the QNSP storage-service API.
  * Provides a high-level interface for document upload, download, and management operations.
+ * All cryptographic operations use tenant-specific PQC algorithms based on crypto policy.
+ */
+
+/**
+ * PQC metadata for cryptographic operations.
+ */
+export interface PqcMetadata {
+	readonly provider: string;
+	readonly algorithm: string;
+	readonly algorithmNist?: string;
+	readonly keyId: string;
+}
+
+/**
+ * Mapping from internal algorithm names to NIST/standards display names.
+ * Covers all 90 PQC algorithms supported by QNSP.
+ * Canonical source: @qnsp/cryptography pqc-standards.ts ALGORITHM_NIST_NAMES
+ */
+export const ALGORITHM_TO_NIST: Record<string, string> = {
+	// FIPS 203 — ML-KEM
+	"kyber-512": "ML-KEM-512",
+	"kyber-768": "ML-KEM-768",
+	"kyber-1024": "ML-KEM-1024",
+	// FIPS 204 — ML-DSA
+	"dilithium-2": "ML-DSA-44",
+	"dilithium-3": "ML-DSA-65",
+	"dilithium-5": "ML-DSA-87",
+	// FIPS 205 — SLH-DSA (SHA-2 variants)
+	"sphincs-sha2-128f-simple": "SLH-DSA-SHA2-128f",
+	"sphincs-sha2-128s-simple": "SLH-DSA-SHA2-128s",
+	"sphincs-sha2-192f-simple": "SLH-DSA-SHA2-192f",
+	"sphincs-sha2-192s-simple": "SLH-DSA-SHA2-192s",
+	"sphincs-sha2-256f-simple": "SLH-DSA-SHA2-256f",
+	"sphincs-sha2-256s-simple": "SLH-DSA-SHA2-256s",
+	// FIPS 205 — SLH-DSA (SHAKE variants)
+	"sphincs-shake-128f-simple": "SLH-DSA-SHAKE-128f",
+	"sphincs-shake-128s-simple": "SLH-DSA-SHAKE-128s",
+	"sphincs-shake-192f-simple": "SLH-DSA-SHAKE-192f",
+	"sphincs-shake-192s-simple": "SLH-DSA-SHAKE-192s",
+	"sphincs-shake-256f-simple": "SLH-DSA-SHAKE-256f",
+	"sphincs-shake-256s-simple": "SLH-DSA-SHAKE-256s",
+	// FN-DSA (FIPS 206 draft)
+	"falcon-512": "FN-DSA-512",
+	"falcon-1024": "FN-DSA-1024",
+	// HQC (NIST selected March 2025)
+	"hqc-128": "HQC-128",
+	"hqc-192": "HQC-192",
+	"hqc-256": "HQC-256",
+	// BIKE (NIST Round 4)
+	"bike-l1": "BIKE-L1",
+	"bike-l3": "BIKE-L3",
+	"bike-l5": "BIKE-L5",
+	// Classic McEliece (ISO standard)
+	"mceliece-348864": "Classic-McEliece-348864",
+	"mceliece-460896": "Classic-McEliece-460896",
+	"mceliece-6688128": "Classic-McEliece-6688128",
+	"mceliece-6960119": "Classic-McEliece-6960119",
+	"mceliece-8192128": "Classic-McEliece-8192128",
+	// FrodoKEM (ISO standard)
+	"frodokem-640-aes": "FrodoKEM-640-AES",
+	"frodokem-640-shake": "FrodoKEM-640-SHAKE",
+	"frodokem-976-aes": "FrodoKEM-976-AES",
+	"frodokem-976-shake": "FrodoKEM-976-SHAKE",
+	"frodokem-1344-aes": "FrodoKEM-1344-AES",
+	"frodokem-1344-shake": "FrodoKEM-1344-SHAKE",
+	// NTRU (lattice-based, re-added in liboqs 0.15)
+	"ntru-hps-2048-509": "NTRU-HPS-2048-509",
+	"ntru-hps-2048-677": "NTRU-HPS-2048-677",
+	"ntru-hps-4096-821": "NTRU-HPS-4096-821",
+	"ntru-hps-4096-1229": "NTRU-HPS-4096-1229",
+	"ntru-hrss-701": "NTRU-HRSS-701",
+	"ntru-hrss-1373": "NTRU-HRSS-1373",
+	// NTRU-Prime
+	sntrup761: "sntrup761",
+	// MAYO (NIST Additional Signatures Round 2)
+	"mayo-1": "MAYO-1",
+	"mayo-2": "MAYO-2",
+	"mayo-3": "MAYO-3",
+	"mayo-5": "MAYO-5",
+	// CROSS (NIST Additional Signatures Round 2)
+	"cross-rsdp-128-balanced": "CROSS-RSDP-128-balanced",
+	"cross-rsdp-128-fast": "CROSS-RSDP-128-fast",
+	"cross-rsdp-128-small": "CROSS-RSDP-128-small",
+	"cross-rsdp-192-balanced": "CROSS-RSDP-192-balanced",
+	"cross-rsdp-192-fast": "CROSS-RSDP-192-fast",
+	"cross-rsdp-192-small": "CROSS-RSDP-192-small",
+	"cross-rsdp-256-balanced": "CROSS-RSDP-256-balanced",
+	"cross-rsdp-256-fast": "CROSS-RSDP-256-fast",
+	"cross-rsdp-256-small": "CROSS-RSDP-256-small",
+	"cross-rsdpg-128-balanced": "CROSS-RSDPG-128-balanced",
+	"cross-rsdpg-128-fast": "CROSS-RSDPG-128-fast",
+	"cross-rsdpg-128-small": "CROSS-RSDPG-128-small",
+	"cross-rsdpg-192-balanced": "CROSS-RSDPG-192-balanced",
+	"cross-rsdpg-192-fast": "CROSS-RSDPG-192-fast",
+	"cross-rsdpg-192-small": "CROSS-RSDPG-192-small",
+	"cross-rsdpg-256-balanced": "CROSS-RSDPG-256-balanced",
+	"cross-rsdpg-256-fast": "CROSS-RSDPG-256-fast",
+	"cross-rsdpg-256-small": "CROSS-RSDPG-256-small",
+	// UOV (NIST Additional Signatures Round 2)
+	"ov-Is": "UOV-Is",
+	"ov-Ip": "UOV-Ip",
+	"ov-III": "UOV-III",
+	"ov-V": "UOV-V",
+	"ov-Is-pkc": "UOV-Is-pkc",
+	"ov-Ip-pkc": "UOV-Ip-pkc",
+	"ov-III-pkc": "UOV-III-pkc",
+	"ov-V-pkc": "UOV-V-pkc",
+	"ov-Is-pkc-skc": "UOV-Is-pkc-skc",
+	"ov-Ip-pkc-skc": "UOV-Ip-pkc-skc",
+	"ov-III-pkc-skc": "UOV-III-pkc-skc",
+	"ov-V-pkc-skc": "UOV-V-pkc-skc",
+	// SNOVA (NIST Additional Signatures Round 2, liboqs 0.14+)
+	"snova-24-5-4": "SNOVA-24-5-4",
+	"snova-24-5-4-shake": "SNOVA-24-5-4-SHAKE",
+	"snova-24-5-4-esk": "SNOVA-24-5-4-ESK",
+	"snova-24-5-4-shake-esk": "SNOVA-24-5-4-SHAKE-ESK",
+	"snova-25-8-3": "SNOVA-25-8-3",
+	"snova-37-17-2": "SNOVA-37-17-2",
+	"snova-37-8-4": "SNOVA-37-8-4",
+	"snova-24-5-5": "SNOVA-24-5-5",
+	"snova-56-25-2": "SNOVA-56-25-2",
+	"snova-49-11-3": "SNOVA-49-11-3",
+	"snova-60-10-4": "SNOVA-60-10-4",
+	"snova-29-6-5": "SNOVA-29-6-5",
+};
+
+/**
+ * Convert internal algorithm name to NIST standardized name.
  */
+export function toNistAlgorithmName(algorithm: string): string {
+	return ALGORITHM_TO_NIST[algorithm] ?? algorithm;
+}
 
 export interface StorageClientConfig {
 	readonly baseUrl: string;
-	readonly apiKey?: string;
+	readonly apiKey: string;
 	readonly tenantId: string;
 	readonly timeoutMs?: number;
+	readonly maxRetries?: number;
+	readonly retryDelayMs?: number;
 	readonly telemetry?: StorageClientTelemetry | StorageClientTelemetryConfig;
 }
 
@@ -27,6 +159,8 @@ type InternalStorageClientConfig = {
 	readonly apiKey: string;
 	readonly tenantId: string;
 	readonly timeoutMs: number;
+	readonly maxRetries: number;
+	readonly retryDelayMs: number;
 };
 
 export interface InitiateUploadOptions {
@@ -154,11 +288,37 @@ export class StorageClient {
 	private readonly targetService: string;
 
 	constructor(config: StorageClientConfig) {
+		if (!config.apiKey || config.apiKey.trim().length === 0) {
+			throw new Error(
+				"QNSP Storage SDK: apiKey is required. " +
+					"Get your free API key at https://cloud.qnsp.cuilabs.io/signup — " +
+					"no credit card required (FREE tier: 5 GB storage, 2,000 API calls/month). " +
+					"Docs: https://docs.qnsp.cuilabs.io/sdk/storage-sdk",
+			);
+		}
+
+		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: config.baseUrl.replace(/\/$/, ""),
-			apiKey: config.apiKey ?? "",
+			baseUrl,
+			apiKey: config.apiKey,
 			tenantId: config.tenantId,
 			timeoutMs: config.timeoutMs ?? 30_000,
+			maxRetries: config.maxRetries ?? 3,
+			retryDelayMs: config.retryDelayMs ?? 1_000,
 		};
 
 		this.telemetry = config.telemetry
@@ -175,15 +335,22 @@ export class StorageClient {
 	}
 
 	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}`;
-		}
+		headers["Authorization"] = `Bearer ${this.config.apiKey}`;
 
 		const controller = new AbortController();
 		const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs);
@@ -211,15 +378,39 @@ export class StorageClient {
 			clearTimeout(timeoutId);
 			httpStatus = response.status;
 
-			if (!response.ok) {
+			// 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";
-				const errorText = await response.text().catch(() => "Unknown error");
-				errorMessage = errorText;
+				errorMessage = `HTTP ${response.status}`;
 				throw new Error(
-					`Storage API error: ${response.status} ${response.statusText} - ${errorText}`,
+					`Storage API error: Rate limit exceeded after ${this.config.maxRetries} retries`,
 				);
 			}
 
+			if (!response.ok) {
+				status = "error";
+				errorMessage = `HTTP ${response.status}`;
+				throw new Error(`Storage API error: ${response.status} ${response.statusText}`);
+			}
+
 			if (response.status === 204) {
 				return undefined as T;
 			}
@@ -261,13 +452,23 @@ export class StorageClient {
 		readonly totalParts: number;
 		readonly expiresAt: string;
 		readonly resumeToken: string | null;
-		readonly pqc: {
-			readonly provider: string;
-			readonly algorithm: string;
-			readonly keyId: string;
-		};
+		readonly pqc: PqcMetadata;
 	}> {
-		return this.request("POST", "/storage/v1/documents", {
+		const result = await this.request<{
+			uploadId: string;
+			documentId: string;
+			tenantId: string;
+			chunkSizeBytes: number;
+			totalSizeBytes: number;
+			totalParts: number;
+			expiresAt: string;
+			resumeToken: string | null;
+			pqc: {
+				provider: string;
+				algorithm: string;
+				keyId: string;
+			};
+		}>("POST", "/storage/v1/documents", {
 			body: {
 				name: options.name,
 				mimeType: options.mimeType,
@@ -279,6 +480,15 @@ export class StorageClient {
 			},
 			operation: "initiateUpload",
 		});
+
+		// Enrich PQC metadata with NIST algorithm name
+		return {
+			...result,
+			pqc: {
+				...result.pqc,
+				algorithmNist: toNistAlgorithmName(result.pqc.algorithm),
+			},
+		};
 	}
 
 	async uploadPart(
@@ -291,9 +501,7 @@ export class StorageClient {
 			"Content-Type": "application/octet-stream",
 		};
 
-		if (this.config.apiKey) {
-			headers["Authorization"] = `Bearer ${this.config.apiKey}`;
-		}
+		headers["Authorization"] = `Bearer ${this.config.apiKey}`;
 
 		const bytesSent =
 			data instanceof Buffer || data instanceof Uint8Array ? data.byteLength : undefined;
@@ -336,11 +544,8 @@ export class StorageClient {
 
 			if (!response.ok) {
 				status = "error";
-				const errorText = await response.text().catch(() => "Unknown error");
-				errorMessage = errorText;
-				throw new Error(
-					`Upload part error: ${response.status} ${response.statusText} - ${errorText}`,
-				);
+				errorMessage = `HTTP ${response.status}`;
+				throw new Error(`Upload part error: ${response.status} ${response.statusText}`);
 			}
 
 			return (await response.json()) as UploadPartResult;
@@ -373,6 +578,7 @@ export class StorageClient {
 	}
 
 	async getUploadStatus(uploadId: string): Promise<UploadStatus> {
+		validateUUID(uploadId, "uploadId");
 		// Use GET since we need the full status object
 		return this.request<UploadStatus>("GET", `/storage/v1/uploads/${uploadId}`, {
 			operation: "getUploadStatus",
@@ -381,6 +587,7 @@ export class StorageClient {
 	}
 
 	async completeUpload(uploadId: string): Promise<CompleteUploadResult> {
+		validateUUID(uploadId, "uploadId");
 		return this.request("POST", `/storage/v1/uploads/${uploadId}/complete`, {
 			operation: "completeUpload",
 			telemetryRoute: "/storage/v1/uploads/:uploadId/complete",
@@ -461,9 +668,7 @@ export class StorageClient {
 			headers["Range"] = options.range;
 		}
 
-		if (this.config.apiKey) {
-			headers["Authorization"] = `Bearer ${this.config.apiKey}`;
-		}
+		headers["Authorization"] = `Bearer ${this.config.apiKey}`;
 
 		const controller = new AbortController();
 		const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs);
@@ -486,9 +691,8 @@ export class StorageClient {
 
 			if (!response.ok) {
 				status = "error";
-				const errorText = await response.text().catch(() => "Unknown error");
-				errorMessage = errorText;
-				throw new Error(`Download error: ${response.status} ${response.statusText} - ${errorText}`);
+				errorMessage = `HTTP ${response.status}`;
+				throw new Error(`Download error: ${response.status} ${response.statusText}`);
 			}
 
 			const contentRange = response.headers.get("Content-Range");
@@ -563,6 +767,7 @@ export class StorageClient {
 	 * Requires x-tenant-id header.
 	 */
 	async getDocumentPolicies(documentId: string): Promise<DocumentPolicies> {
+		validateUUID(documentId, "documentId");
 		return this.request("GET", `/storage/v1/documents/${documentId}/policies`, {
 			operation: "getDocumentPolicies",
 			telemetryRoute: "/storage/v1/documents/:documentId/policies",
@@ -580,6 +785,7 @@ export class StorageClient {
 		documentId: string,
 		input: UpdatePoliciesRequest,
 	): Promise<DocumentPolicies> {
+		validateUUID(documentId, "documentId");
 		return this.request("PATCH", `/storage/v1/documents/${documentId}/policies`, {
 			body: input,
 			operation: "updateDocumentPolicies",
@@ -602,6 +808,7 @@ export class StorageClient {
 		readonly tenantId: string;
 		readonly legalHolds: readonly string[];
 	}> {
+		validateUUID(documentId, "documentId");
 		return this.request("POST", `/storage/v1/documents/${documentId}/legal-holds`, {
 			body: request,
 			operation: "applyLegalHold",
@@ -617,6 +824,7 @@ export class StorageClient {
 	 * Requires x-tenant-id header.
 	 */
 	async releaseLegalHold(documentId: string, holdId: string): Promise<void> {
+		validateUUID(documentId, "documentId");
 		return this.request("DELETE", `/storage/v1/documents/${documentId}/legal-holds/${holdId}`, {
 			operation: "releaseLegalHold",
 			telemetryRoute: "/storage/v1/documents/:documentId/legal-holds/:holdId",
@@ -642,6 +850,7 @@ export class StorageClient {
 			readonly transitionAfter?: string | null;
 		};
 	}> {
+		validateUUID(documentId, "documentId");
 		return this.request("POST", `/storage/v1/documents/${documentId}/lifecycle/transitions`, {
 			body: request,
 			operation: "scheduleLifecycleTransition",
@@ -662,3 +871,4 @@ export class StorageClient {
 
 export * from "./events.js";
 export * from "./observability.js";
+export * from "./validation.js";

package/src/validation.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+/**
+ * Validation schemas for storage-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;
+	}
+}