@qnsp/storage-sdk 0.2.1 → 0.3.1

package/src/index.ts

@@ -1,4 +1,4 @@
-import { performance } from "node:perf_hooks";
+import { activateSdk, type SdkActivationConfig } from "@qnsp/sdk-activation";
 
 import type {
 	StorageClientTelemetry,
@@ -6,6 +6,7 @@ import type {
 	StorageClientTelemetryEvent,
 } from "./observability.js";
 import { createStorageClientTelemetry, isStorageClientTelemetry } from "./observability.js";
+import { validateUUID } from "./validation.js";
 
 /**
  * @qnsp/storage-sdk
@@ -26,15 +27,116 @@ export interface PqcMetadata {
 }
 
 /**
- * Mapping from internal algorithm names to NIST standardized names.
+ * 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",
 };
 
 /**
@@ -46,9 +148,11 @@ export function toNistAlgorithmName(algorithm: string): string {
 
 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;
 }
 
@@ -57,6 +161,8 @@ type InternalStorageClientConfig = {
 	readonly apiKey: string;
 	readonly tenantId: string;
 	readonly timeoutMs: number;
+	readonly maxRetries: number;
+	readonly retryDelayMs: number;
 };
 
 export interface InitiateUploadOptions {
@@ -182,13 +288,61 @@ export class StorageClient {
 	private readonly config: InternalStorageClientConfig;
 	private readonly telemetry: StorageClientTelemetry | null;
 	private readonly targetService: string;
+	private activationPromise: Promise<void> | null = null;
+	private readonly activationConfig: SdkActivationConfig;
+
+	private async ensureActivated(): Promise<void> {
+		if (!this.activationPromise) {
+			this.activationPromise = activateSdk(this.activationConfig).then(() => undefined);
+		}
+		return this.activationPromise;
+	}
 
 	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: 10 GB storage, 50,000 API calls/month). " +
+					"Docs: https://docs.qnsp.cuilabs.io/sdk/storage-sdk",
+			);
+		}
+
+		const baseUrl = config.baseUrl.replace(/\/$/, "");
+
+		// Enforce HTTPS in production (allow HTTP for localhost in development and
+		// for internal service-mesh hostnames — e.g. *.internal — which are on a
+		// private VPC network and do not require TLS termination at the transport layer).
+		if (!baseUrl.startsWith("https://")) {
+			const isLocalhost =
+				baseUrl.startsWith("http://localhost") || baseUrl.startsWith("http://127.0.0.1");
+			let isInternalService = false;
+			try {
+				const parsed = new URL(baseUrl);
+				isInternalService =
+					parsed.protocol === "http:" &&
+					(parsed.hostname.endsWith(".internal") ||
+						parsed.hostname === "localhost" ||
+						parsed.hostname === "127.0.0.1");
+			} catch {
+				// ignore; invalid URL will be caught later by fetch
+			}
+			const isDevelopment =
+				process.env["NODE_ENV"] === "development" || process.env["NODE_ENV"] === "test";
+			if ((!isLocalhost || !isDevelopment) && !isInternalService) {
+				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
@@ -202,18 +356,32 @@ export class StorageClient {
 		} catch {
 			this.targetService = "storage-service";
 		}
+
+		this.activationConfig = {
+			apiKey: config.apiKey,
+			sdkId: "storage-sdk",
+			sdkVersion: "0.3.0",
+			platformUrl: config.baseUrl,
+		};
 	}
 
 	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);
@@ -241,15 +409,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;
 			}
@@ -293,6 +485,7 @@ export class StorageClient {
 		readonly resumeToken: string | null;
 		readonly pqc: PqcMetadata;
 	}> {
+		await this.ensureActivated();
 		const result = await this.request<{
 			uploadId: string;
 			documentId: string;
@@ -335,14 +528,13 @@ export class StorageClient {
 		partId: number,
 		data: ReadableStream<Uint8Array> | Buffer | Uint8Array,
 	): Promise<UploadPartResult> {
+		await this.ensureActivated();
 		const url = `${this.config.baseUrl}/storage/v1/uploads/${uploadId}/parts/${partId}`;
 		const headers: Record<string, string> = {
 			"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;
@@ -385,11 +577,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;
@@ -422,6 +611,8 @@ export class StorageClient {
 	}
 
 	async getUploadStatus(uploadId: string): Promise<UploadStatus> {
+		validateUUID(uploadId, "uploadId");
+		await this.ensureActivated();
 		// Use GET since we need the full status object
 		return this.request<UploadStatus>("GET", `/storage/v1/uploads/${uploadId}`, {
 			operation: "getUploadStatus",
@@ -430,6 +621,8 @@ export class StorageClient {
 	}
 
 	async completeUpload(uploadId: string): Promise<CompleteUploadResult> {
+		validateUUID(uploadId, "uploadId");
+		await this.ensureActivated();
 		return this.request("POST", `/storage/v1/uploads/${uploadId}/complete`, {
 			operation: "completeUpload",
 			telemetryRoute: "/storage/v1/uploads/:uploadId/complete",
@@ -445,6 +638,7 @@ export class StorageClient {
 			readonly signature?: string | null;
 		},
 	): Promise<DownloadDescriptor> {
+		await this.ensureActivated();
 		const params = new URLSearchParams({
 			tenantId: this.config.tenantId,
 		});
@@ -486,6 +680,7 @@ export class StorageClient {
 		readonly range?: { readonly start: number; readonly end: number };
 		readonly checksumSha3: string;
 	}> {
+		await this.ensureActivated();
 		const params = new URLSearchParams({
 			tenantId: this.config.tenantId,
 		});
@@ -510,9 +705,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);
@@ -535,9 +728,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");
@@ -612,6 +804,8 @@ export class StorageClient {
 	 * Requires x-tenant-id header.
 	 */
 	async getDocumentPolicies(documentId: string): Promise<DocumentPolicies> {
+		validateUUID(documentId, "documentId");
+		await this.ensureActivated();
 		return this.request("GET", `/storage/v1/documents/${documentId}/policies`, {
 			operation: "getDocumentPolicies",
 			telemetryRoute: "/storage/v1/documents/:documentId/policies",
@@ -629,6 +823,8 @@ export class StorageClient {
 		documentId: string,
 		input: UpdatePoliciesRequest,
 	): Promise<DocumentPolicies> {
+		validateUUID(documentId, "documentId");
+		await this.ensureActivated();
 		return this.request("PATCH", `/storage/v1/documents/${documentId}/policies`, {
 			body: input,
 			operation: "updateDocumentPolicies",
@@ -651,6 +847,8 @@ export class StorageClient {
 		readonly tenantId: string;
 		readonly legalHolds: readonly string[];
 	}> {
+		validateUUID(documentId, "documentId");
+		await this.ensureActivated();
 		return this.request("POST", `/storage/v1/documents/${documentId}/legal-holds`, {
 			body: request,
 			operation: "applyLegalHold",
@@ -666,6 +864,8 @@ export class StorageClient {
 	 * Requires x-tenant-id header.
 	 */
 	async releaseLegalHold(documentId: string, holdId: string): Promise<void> {
+		validateUUID(documentId, "documentId");
+		await this.ensureActivated();
 		return this.request("DELETE", `/storage/v1/documents/${documentId}/legal-holds/${holdId}`, {
 			operation: "releaseLegalHold",
 			telemetryRoute: "/storage/v1/documents/:documentId/legal-holds/:holdId",
@@ -691,6 +891,8 @@ export class StorageClient {
 			readonly transitionAfter?: string | null;
 		};
 	}> {
+		validateUUID(documentId, "documentId");
+		await this.ensureActivated();
 		return this.request("POST", `/storage/v1/documents/${documentId}/lifecycle/transitions`, {
 			body: request,
 			operation: "scheduleLifecycleTransition",
@@ -711,3 +913,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;
+	}
+}