@qnsp/storage-sdk 0.2.1 → 0.3.0

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;AAEjE;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,SAAiB;IAC5D,IAAI,CAAC;QACJ,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,KAAK,YAAY,CAAC,CAAC,QAAQ,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CAAC,WAAW,SAAS,KAAK,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,gBAAgB,EAAE,CAAC,CAAC;QAC1F,CAAC;QACD,MAAM,KAAK,CAAC;IACb,CAAC;AACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@qnsp/storage-sdk",
-	"version": "0.2.1",
+	"version": "0.3.0",
 	"publishConfig": {
 		"access": "public"
 	},
@@ -23,16 +23,16 @@
 	},
 	"dependencies": {
 		"@opentelemetry/api": "^1.9.0",
-		"@opentelemetry/exporter-metrics-otlp-http": "^0.208.0",
-		"@opentelemetry/resources": "^2.0.0",
-		"@opentelemetry/sdk-metrics": "^2.2.0",
-		"undici": "^7.16.0",
-		"zod": "^4.1.12"
+		"@opentelemetry/exporter-metrics-otlp-http": "^0.210.0",
+		"@opentelemetry/resources": "^2.4.0",
+		"@opentelemetry/sdk-metrics": "^2.4.0",
+		"undici": "^7.18.2",
+		"zod": "^4.3.5"
 	},
 	"devDependencies": {
-		"@types/node": "^24.10.4",
+		"@types/node": "^25.0.9",
 		"tsx": "^4.21.0",
-		"vitest": "4.0.16"
+		"vitest": "4.0.17"
 	},
 	"engines": {
 		"node": "24.12.0"

package/src/event-envelope.ts

@@ -1,4 +1,3 @@
-import { randomUUID } from "node:crypto";
 import { z } from "zod";
 
 export const eventMetadataSchema = z.object({
@@ -20,7 +19,7 @@ export const eventEnvelopeSchema = z.object({
 	id: z
 		.string()
 		.uuid()
-		.default(() => randomUUID()),
+		.default(() => crypto.randomUUID()),
 	topic: z.string().min(1),
 	version: z.string().min(1).default("1"),
 	occuredAt: z

package/src/events.ts

@@ -1,5 +1,3 @@
-import { performance } from "node:perf_hooks";
-
 import type { EventEnvelope } from "./event-envelope.js";
 import { createEventEnvelope } from "./event-envelope.js";
 import type {

package/src/index.test.ts

@@ -1,9 +1,15 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { StorageClient, StorageEventsClient } from "./index.js";
 
-const mockTenantId = "tenant-123";
+const mockTenantId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
 const baseUrl = "https://storage.qnsp.example/";
 
+// Valid UUID test constants
+const mockUploadId = "11111111-1111-4111-a111-111111111111";
+const mockUploadId2 = "22222222-2222-4222-a222-222222222222";
+const mockUploadIdErr = "33333333-3333-4333-a333-333333333333";
+const mockDocumentId = "44444444-4444-4444-a444-444444444444";
+
 function jsonResponse(payload: unknown, init?: ResponseInit): Response {
 	return new Response(JSON.stringify(payload), {
 		status: 200,
@@ -60,8 +66,8 @@ describe("StorageClient", () => {
 		});
 
 		const expectedResponse = {
-			uploadId: "upload-1",
-			documentId: "document-1",
+			uploadId: mockUploadId,
+			documentId: mockDocumentId,
 			tenantId: mockTenantId,
 			chunkSizeBytes: 16_777_216,
 			totalSizeBytes: 42_000_000,
@@ -118,7 +124,7 @@ describe("StorageClient", () => {
 		});
 
 		const expectedPayload = {
-			uploadId: "upload-1",
+			uploadId: mockUploadId,
 			partId: 1,
 			status: "uploaded",
 			sizeBytes: 3,
@@ -137,7 +143,7 @@ describe("StorageClient", () => {
 
 		const source = Buffer.from([0xde, 0xad, 0xbe]);
 
-		const result = await client.uploadPart("upload-1", 1, source);
+		const result = await client.uploadPart(mockUploadId, 1, source);
 		expect(result).toEqual(expectedPayload);
 		expect(globalThis.fetch).toHaveBeenCalledTimes(1);
 		const uploadCall = (globalThis.fetch as unknown as ReturnType<typeof vi.fn>).mock.calls.at(0);
@@ -158,6 +164,7 @@ describe("StorageClient", () => {
 	it("parses ranged download responses and surfaces stream metadata", async () => {
 		const client = new StorageClient({
 			baseUrl,
+			apiKey: "test-api-key",
 			tenantId: mockTenantId,
 		});
 
@@ -179,12 +186,12 @@ describe("StorageClient", () => {
 
 		(globalThis.fetch as unknown as ReturnType<typeof vi.fn>).mockResolvedValue(response);
 
-		const result = await client.downloadStream("document-1", 2, {
+		const result = await client.downloadStream(mockDocumentId, 2, {
 			range: "bytes=0-2",
 		});
 
 		expect(globalThis.fetch).toHaveBeenCalledWith(
-			"https://storage.qnsp.example/storage/v1/documents/document-1/versions/2/content?tenantId=tenant-123&range=bytes%3D0-2",
+			`https://storage.qnsp.example/storage/v1/documents/${mockDocumentId}/versions/2/content?tenantId=${mockTenantId}&range=bytes%3D0-2`,
 			expect.objectContaining({
 				method: "GET",
 				headers: expect.objectContaining({
@@ -207,13 +214,14 @@ describe("StorageClient", () => {
 		const telemetry = { record: vi.fn() };
 		const client = new StorageClient({
 			baseUrl,
+			apiKey: "test-api-key",
 			tenantId: mockTenantId,
 			telemetry,
 		});
 
 		const statusResponse = {
-			uploadId: "upload-123",
-			documentId: "doc-1",
+			uploadId: mockUploadId2,
+			documentId: mockDocumentId,
 			tenantId: mockTenantId,
 			status: "pending",
 			chunkSizeBytes: 4,
@@ -232,7 +240,7 @@ describe("StorageClient", () => {
 			jsonResponse(statusResponse),
 		);
 
-		await client.getUploadStatus("upload-123");
+		await client.getUploadStatus(mockUploadId2);
 
 		expect(telemetry.record).toHaveBeenCalled();
 		const event = (telemetry.record as ReturnType<typeof vi.fn>).mock.calls.at(-1)?.[0];
@@ -248,6 +256,7 @@ describe("StorageClient", () => {
 		const telemetry = { record: vi.fn() };
 		const client = new StorageClient({
 			baseUrl,
+			apiKey: "test-api-key",
 			tenantId: mockTenantId,
 			telemetry,
 		});
@@ -256,7 +265,7 @@ describe("StorageClient", () => {
 			new Response("boom", { status: 500, statusText: "error" }),
 		);
 
-		await expect(client.completeUpload("upload-err")).rejects.toThrow(/Storage API error/);
+		await expect(client.completeUpload(mockUploadIdErr)).rejects.toThrow(/Storage API error/);
 
 		const event = (telemetry.record as ReturnType<typeof vi.fn>).mock.calls.at(-1)?.[0];
 		expect(event).toBeDefined();
@@ -271,12 +280,13 @@ describe("StorageClient", () => {
 		const telemetry = { record: vi.fn() };
 		const client = new StorageClient({
 			baseUrl,
+			apiKey: "test-api-key",
 			tenantId: mockTenantId,
 			telemetry,
 		});
 
 		const expectedPayload = {
-			uploadId: "upload-1",
+			uploadId: mockUploadId,
 			partId: 1,
 			status: "uploaded",
 			sizeBytes: 3,
@@ -293,7 +303,7 @@ describe("StorageClient", () => {
 			jsonResponse(expectedPayload),
 		);
 
-		await client.uploadPart("upload-1", 1, Buffer.from([1, 2, 3]));
+		await client.uploadPart(mockUploadId, 1, Buffer.from([1, 2, 3]));
 
 		const event = (telemetry.record as ReturnType<typeof vi.fn>).mock.calls.at(-1)?.[0];
 		expect(event).toBeDefined();
@@ -315,7 +325,7 @@ describe("StorageClient", () => {
 			// PATCH response
 			.mockResolvedValueOnce(
 				jsonResponse({
-					documentId: "doc-1",
+					documentId: mockDocumentId,
 					tenantId: mockTenantId,
 					compliance: {
 						retentionMode: "compliance",
@@ -328,7 +338,7 @@ describe("StorageClient", () => {
 			// GET response
 			.mockResolvedValueOnce(
 				jsonResponse({
-					documentId: "doc-1",
+					documentId: mockDocumentId,
 					tenantId: mockTenantId,
 					compliance: {
 						retentionMode: "compliance",
@@ -344,26 +354,30 @@ describe("StorageClient", () => {
 				}),
 			);
 
-		const updated = await client.updateDocumentPolicies("doc-1", {
+		const updated = await client.updateDocumentPolicies(mockDocumentId, {
 			retentionMode: "compliance",
 			retainUntil: "2026-01-01T00:00:00Z",
 			legalHolds: ["hold-1"],
 		});
-		expect(updated.documentId).toBe("doc-1");
+		expect(updated.documentId).toBe(mockDocumentId);
 		const patchCall = (globalThis.fetch as unknown as ReturnType<typeof vi.fn>).mock
 			.calls[0] as unknown as [string, RequestInit];
-		expect(patchCall[0]).toBe("https://storage.qnsp.example/storage/v1/documents/doc-1/policies");
+		expect(patchCall[0]).toBe(
+			`https://storage.qnsp.example/storage/v1/documents/${mockDocumentId}/policies`,
+		);
 		expect(patchCall[1]?.headers).toMatchObject({
 			"Content-Type": "application/json",
 			Authorization: "Bearer key",
 			"x-tenant-id": mockTenantId,
 		});
 
-		const policies = await client.getDocumentPolicies("doc-1");
+		const policies = await client.getDocumentPolicies(mockDocumentId);
 		expect(policies.tenantId).toBe(mockTenantId);
 		const getCall = (globalThis.fetch as unknown as ReturnType<typeof vi.fn>).mock
 			.calls[1] as unknown as [string, RequestInit];
-		expect(getCall[0]).toBe("https://storage.qnsp.example/storage/v1/documents/doc-1/policies");
+		expect(getCall[0]).toBe(
+			`https://storage.qnsp.example/storage/v1/documents/${mockDocumentId}/policies`,
+		);
 		expect(getCall[1]?.headers).toMatchObject({
 			"Content-Type": "application/json",
 			Authorization: "Bearer key",
@@ -382,7 +396,7 @@ describe("StorageClient", () => {
 			// apply
 			.mockResolvedValueOnce(
 				jsonResponse({
-					documentId: "doc-1",
+					documentId: mockDocumentId,
 					tenantId: mockTenantId,
 					legalHolds: ["hold-9"],
 				}),
@@ -390,21 +404,23 @@ describe("StorageClient", () => {
 			// release (204)
 			.mockResolvedValueOnce(new Response(null, { status: 204 }));
 
-		const applied = await client.applyLegalHold("doc-1", { holdId: "hold-9" });
+		const applied = await client.applyLegalHold(mockDocumentId, { holdId: "hold-9" });
 		expect(applied.legalHolds).toContain("hold-9");
 		const postCall = (globalThis.fetch as unknown as ReturnType<typeof vi.fn>).mock
 			.calls[0] as unknown as [string, RequestInit];
-		expect(postCall[0]).toBe("https://storage.qnsp.example/storage/v1/documents/doc-1/legal-holds");
+		expect(postCall[0]).toBe(
+			`https://storage.qnsp.example/storage/v1/documents/${mockDocumentId}/legal-holds`,
+		);
 		expect(postCall[1]?.method).toBe("POST");
 		expect(postCall[1]?.headers).toMatchObject({
 			"x-tenant-id": mockTenantId,
 		});
 
-		await client.releaseLegalHold("doc-1", "hold-9");
+		await client.releaseLegalHold(mockDocumentId, "hold-9");
 		const delCall = (globalThis.fetch as unknown as ReturnType<typeof vi.fn>).mock
 			.calls[1] as unknown as [string, RequestInit];
 		expect(delCall[0]).toBe(
-			"https://storage.qnsp.example/storage/v1/documents/doc-1/legal-holds/hold-9",
+			`https://storage.qnsp.example/storage/v1/documents/${mockDocumentId}/legal-holds/hold-9`,
 		);
 		expect(delCall[1]?.method).toBe("DELETE");
 		expect(delCall[1]?.headers).toMatchObject({
@@ -427,6 +443,7 @@ describe("StorageEventsClient", () => {
 		const telemetry = { record: vi.fn() };
 		const client = new StorageEventsClient({
 			baseUrl,
+			apiKey: "test-api-key",
 			telemetry,
 		});
 

package/src/index.ts

@@ -1,11 +1,10 @@
-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
@@ -26,15 +25,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 +146,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 +159,8 @@ type InternalStorageClientConfig = {
 	readonly apiKey: string;
 	readonly tenantId: string;
 	readonly timeoutMs: number;
+	readonly maxRetries: number;
+	readonly retryDelayMs: number;
 };
 
 export interface InitiateUploadOptions {
@@ -184,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
@@ -205,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);
@@ -241,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;
 			}
@@ -340,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;
@@ -385,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;
@@ -422,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",
@@ -430,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",
@@ -510,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);
@@ -535,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");
@@ -612,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",
@@ -629,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",
@@ -651,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",
@@ -666,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",
@@ -691,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",
@@ -711,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;
+	}
+}