TypeScript client for storage-service. All files are encrypted with tenant-specific PQC algorithms based on crypto policy.

Storage SDK (`@qnsp/storage-sdk`)

TypeScript client for storage-service. All files are encrypted with tenant-specific PQC algorithms based on crypto policy.

Install

pnpm install @qnsp/storage-sdk

Create a client

import { StorageClient } from "@qnsp/storage-sdk";

const storage = new StorageClient({
	baseUrl: "http://localhost:8092",
	apiKey: "<access_token>",
	tenantId: "<tenant_uuid>",
});

Upload Flow

// 1. Initiate upload
const upload = await storage.initiateUpload({
	name: "document.pdf",
	mimeType: "application/pdf",
	sizeBytes: 1024000,
	classification: "confidential",
	metadata: { department: "engineering" },
	tags: ["report", "q4"],
});

// PQC metadata shows which algorithm was used
console.log(upload.pqc);
// {
//   provider: "liboqs",
//   algorithm: "kyber-768",
//   algorithmNist: "ML-KEM-768",  // NIST standardized name
//   keyId: "key-uuid"
// }

// 2. Upload parts
for (let i = 0; i < upload.totalParts; i++) {
	const partData = getPartData(i); // Your data source
	await storage.uploadPart(upload.uploadId, i, partData);
}

// 3. Complete upload
const result = await storage.completeUpload(upload.uploadId);
console.log(result.documentId);

Download Flow

// Get download descriptor
const descriptor = await storage.getDownloadDescriptor(documentId, version);

// Stream download
const { stream, totalSize, checksumSha3 } = await storage.downloadStream(
	documentId,
	version,
	{ range: "bytes=0-1023" } // Optional range request
);

// Process stream
const reader = stream.getReader();
while (true) {
	const { value, done } = await reader.read();
	if (done) break;
	// Process chunk
}

Document Policies

// Get document policies
const policies = await storage.getDocumentPolicies(documentId);
console.log(policies.compliance.retentionMode); // "compliance" | "governance"

// Update retention policy
await storage.updateDocumentPolicies(documentId, {
	retentionMode: "compliance",
	retainUntil: "2027-01-01T00:00:00Z",
});

// Apply legal hold
await storage.applyLegalHold(documentId, { holdId: "litigation-2026" });

// Release legal hold
await storage.releaseLegalHold(documentId, "litigation-2026");

// Schedule lifecycle transition
await storage.scheduleLifecycleTransition(documentId, {
	targetTier: "cold",
	transitionAfter: "2026-06-01T00:00:00Z",
});

Data Classification

Classify objects based on sensitivity and detect PII automatically.

// Create a classification policy
const policy = await storage.createClassificationPolicy({
	name: "PII Detection Policy",
	classificationLevel: "confidential",
	piiDetectionEnabled: true,
	autoClassify: true,
	patterns: [
		{ name: "SSN", regex: "\\d{3}-\\d{2}-\\d{4}", piiType: "ssn", weight: 100 },
	],
});

// List classification policies
const { policies } = await storage.listClassificationPolicies({ enabled: true });

// Classify an object manually
const classification = await storage.classifyObject(objectId, {
	classificationLevel: "restricted",
	piiDetected: true,
	piiTypes: ["ssn", "email"],
});

// Get object classification
const objClassification = await storage.getObjectClassification(objectId);

// Start a classification scan
const scan = await storage.startClassificationScan({
	scanType: "full",
	scope: { pathPrefix: "/documents/", fileTypes: ["pdf", "docx"] },
});

// Detect PII in content (without storing)
const detection = await storage.detectPII("Contact: john@example.com, SSN: 123-45-6789");
console.log(detection.piiDetected); // true
console.log(detection.detections); // [{ type: "email", count: 1 }, { type: "ssn", count: 1 }]

// Get classification statistics
const stats = await storage.getClassificationStats();
console.log(stats.piiStatistics.objectsWithPii);

Retention Policies

Define and enforce data retention and deletion policies.

// Create a retention policy
const retentionPolicy = await storage.createRetentionPolicy({
	name: "7-Year Financial Records",
	retentionType: "time_based",
	retentionDays: 2555, // ~7 years
	deletionType: "secure_erase",
	appliesTo: { tags: ["financial"], classificationLevels: ["confidential"] },
	requireApprovalForDeletion: true,
	approvers: ["compliance@company.com"],
});

// List retention policies
const { policies } = await storage.listRetentionPolicies({ enabled: true });

// Place a legal hold
const hold = await storage.placeHold(objectId, {
	holdType: "litigation",
	holdReason: "Active lawsuit - Case #12345",
	legalCaseId: "CASE-12345",
});

// Release a legal hold
await storage.releaseHold(objectId, hold.id, "Case dismissed - no longer needed");

// Schedule object deletion
const deletion = await storage.scheduleDelete(objectId, {
	scheduledAt: "2027-01-01T00:00:00Z",
	deletionType: "secure_erase",
});

// Evaluate if object can be deleted
const evaluation = await storage.evaluateRetention(objectId);
if (evaluation.canDelete) {
	console.log("Object can be deleted");
} else {
	console.log(`Blocked by: ${evaluation.reason}`);
}

Cross-Region Replication

Configure and monitor data replication across regions.

// Create a replication configuration
const replicationConfig = await storage.createReplicationConfig({
	name: "US to EU Replication",
	sourceRegion: "us-east-1",
	targetRegions: ["eu-west-1", "eu-central-1"],
	replicationMode: "async",
	encryptionInTransit: true,
	verifyChecksum: true,
	filterRules: [
		{ type: "include", field: "classification", operator: "equals", value: "critical" },
	],
});

// List replication configurations
const { configurations } = await storage.listReplicationConfigs({ enabled: true });

// Replicate a specific object
const replication = await storage.replicateObject(objectId, ["eu-west-1", "ap-southeast-1"], {
	priority: "high",
	sizeBytes: 1024000,
});

// Get replication status for an object
const status = await storage.getReplicationStatus(objectId);
for (const rep of status.replications) {
	console.log(`${rep.targetRegion}: ${rep.status}`);
}

// Get replication metrics
const metrics = await storage.getReplicationMetrics({ periodDays: 7 });
console.log(metrics.summary);

// Check region health
const health = await storage.getRegionHealth();
console.log(`Overall status: ${health.status}`);

Intelligent Tiering

Auto-migrate data to cheaper storage tiers based on access patterns.

// Create a tiering policy
const tieringPolicy = await storage.createTieringPolicy({
	name: "Auto-Archive Policy",
	enabled: true,
	rules: [
		{
			name: "Move to cold after 30 days",
			condition: { lastAccessedDaysAgo: 30 },
			action: { targetTier: "cold" },
			priority: 100,
		},
		{
			name: "Archive after 90 days",
			condition: { lastAccessedDaysAgo: 90 },
			action: { targetTier: "archive" },
			priority: 200,
		},
	],
});

// List tiering policies
const { policies } = await storage.listTieringPolicies();

// Evaluate a policy (dry run by default)
const evaluation = await storage.evaluateTiering(policyId, true);
console.log(`Objects matched: ${evaluation.objectsMatched}`);
console.log(`Estimated savings: ${evaluation.estimatedSavingsPercent}%`);

// Execute tiering (not dry run)
const execution = await storage.evaluateTiering(policyId, false);
console.log(`Transition ID: ${execution.transitionId}`);

// Get tiering statistics
const stats = await storage.getTieringStats();
console.log(stats.tierDistribution);

// Get tiering recommendations
const { recommendations } = await storage.getTieringRecommendations();
for (const rec of recommendations) {
	console.log(`${rec.title}: ${rec.sizeGb} GB, ~${rec.estimatedSavingsPercent}% savings`);
}

The Storage SDK exports the full 93-algorithm NIST name mapping covering all PQC families supported by QNSP: ML-KEM (FIPS 203), ML-DSA (FIPS 204), SLH-DSA (FIPS 205), FN-DSA (FIPS 206 draft), HQC, BIKE, Classic McEliece, FrodoKEM, NTRU, NTRU-Prime, MAYO, CROSS, UOV, and SNOVA.

import { toNistAlgorithmName, ALGORITHM_TO_NIST } from "@qnsp/storage-sdk";

// Convert internal to NIST name
const nistName = toNistAlgorithmName("kyber-768"); // "ML-KEM-768"

// All uploads include PQC metadata
const upload = await storage.initiateUpload({ /* ... */ });
console.log(`Encrypted with ${upload.pqc.algorithmNist}`);

// Full mapping covers all 90 PQC algorithms. Representative entries:
console.log(ALGORITHM_TO_NIST);
// {
//   "kyber-512": "ML-KEM-512",        // FIPS 203
//   "kyber-768": "ML-KEM-768",
//   "kyber-1024": "ML-KEM-1024",
//   "dilithium-2": "ML-DSA-44",       // FIPS 204
//   "dilithium-3": "ML-DSA-65",
//   "dilithium-5": "ML-DSA-87",
//   "sphincs-sha2-128f-simple": "SLH-DSA-SHA2-128f",  // FIPS 205
//   "falcon-512": "FN-DSA-512",       // FIPS 206 (draft)
//   "hqc-128": "HQC-128",             // NIST selected (March 2025)
//   "bike-l1": "BIKE-L1",             // NIST Round 4
//   "mceliece-348864": "Classic-McEliece-348864",  // ISO standard
//   "frodokem-640-aes": "FrodoKEM-640-AES",        // ISO standard
//   "ntru-hps-2048-509": "NTRU-HPS-2048-509",      // liboqs 0.15
//   "mayo-1": "MAYO-1",               // NIST Additional Signatures
//   "cross-rsdp-128-balanced": "CROSS-RSDP-128-balanced",
//   "ov-Is": "UOV-Is",
//   "snova-24-5-4": "SNOVA-24-5-4",
//   ... // 93 algorithms total
// }