@qnsp/tenant-sdk 0.3.0 → 0.3.2

package/dist/index.js

@@ -1,31 +1,168 @@
 import { performance } from "node:perf_hooks";
+import { activateSdk } from "@qnsp/sdk-activation";
 import { createTenantClientTelemetry, isTenantClientTelemetry } from "./observability.js";
+import { SDK_PACKAGE_VERSION } from "./sdk-package-version.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.
+ */
+/** Default QNSP cloud API base URL. Get a free API key at https://cloud.qnsp.cuilabs.io/signup */
+export const DEFAULT_BASE_URL = "https://api.qnsp.cuilabs.io";
 /**
  * Default algorithms per crypto policy tier.
+ * These match the definitions in packages/security/src/crypto-policy.ts
+ * and determine which algorithms appear in the portal's Generate Key dropdown.
+ *
+ * default: All supported PQC algorithms (NIST-finalized + candidates via liboqs)
+ * strict: NIST-finalized/selected at higher security levels
+ * maximum: Highest-security NIST-finalized only
+ * government: FIPS-finalized only (no draft standards)
  */
 export const CRYPTO_POLICY_ALGORITHMS = {
     default: {
-        kemAlgorithms: ["kyber-512", "kyber-768", "kyber-1024"],
-        signatureAlgorithms: ["dilithium-2", "dilithium-3", "dilithium-5"],
+        kemAlgorithms: [
+            // FIPS 203 — ML-KEM (NIST finalized)
+            "kyber-512",
+            "kyber-768",
+            "kyber-1024",
+            // HQC (NIST selected March 2025)
+            "hqc-128",
+            "hqc-192",
+            "hqc-256",
+            // BIKE (NIST Round 4 candidate)
+            "bike-l1",
+            "bike-l3",
+            "bike-l5",
+            // Classic McEliece (ISO standard)
+            "mceliece-348864",
+            "mceliece-460896",
+            "mceliece-6688128",
+            "mceliece-6960119",
+            "mceliece-8192128",
+            // FrodoKEM (ISO standard)
+            "frodokem-640-aes",
+            "frodokem-640-shake",
+            "frodokem-976-aes",
+            "frodokem-976-shake",
+            "frodokem-1344-aes",
+            "frodokem-1344-shake",
+            // NTRU (lattice-based)
+            "ntru-hps-2048-509",
+            "ntru-hps-2048-677",
+            "ntru-hps-4096-821",
+            "ntru-hps-4096-1229",
+            "ntru-hrss-701",
+            "ntru-hrss-1373",
+            // NTRU-Prime
+            "sntrup761",
+        ],
+        signatureAlgorithms: [
+            // FIPS 204 — ML-DSA (NIST finalized)
+            "dilithium-2",
+            "dilithium-3",
+            "dilithium-5",
+            // FIPS 205 — SLH-DSA (NIST finalized, SHA-2 variants)
+            "sphincs-sha2-128f-simple",
+            "sphincs-sha2-128s-simple",
+            "sphincs-sha2-192f-simple",
+            "sphincs-sha2-192s-simple",
+            "sphincs-sha2-256f-simple",
+            "sphincs-sha2-256s-simple",
+            // FIPS 205 — SLH-DSA (NIST finalized, SHAKE variants)
+            "sphincs-shake-128f-simple",
+            "sphincs-shake-128s-simple",
+            "sphincs-shake-192f-simple",
+            "sphincs-shake-192s-simple",
+            "sphincs-shake-256f-simple",
+            "sphincs-shake-256s-simple",
+            // FN-DSA / Falcon (FIPS 206 draft)
+            "falcon-512",
+            "falcon-1024",
+            // MAYO (NIST Additional Signatures Round 2)
+            "mayo-1",
+            "mayo-2",
+            "mayo-3",
+            "mayo-5",
+            // CROSS (NIST Additional Signatures Round 2)
+            "cross-rsdp-128-balanced",
+            "cross-rsdp-128-fast",
+            "cross-rsdp-128-small",
+            "cross-rsdp-192-balanced",
+            "cross-rsdp-192-fast",
+            "cross-rsdp-192-small",
+            "cross-rsdp-256-balanced",
+            "cross-rsdp-256-fast",
+            "cross-rsdp-256-small",
+            "cross-rsdpg-128-balanced",
+            "cross-rsdpg-128-fast",
+            "cross-rsdpg-128-small",
+            "cross-rsdpg-192-balanced",
+            "cross-rsdpg-192-fast",
+            "cross-rsdpg-192-small",
+            "cross-rsdpg-256-balanced",
+            "cross-rsdpg-256-fast",
+            "cross-rsdpg-256-small",
+            // UOV (NIST Additional Signatures Round 2)
+            "ov-Is",
+            "ov-Ip",
+            "ov-III",
+            "ov-V",
+            "ov-Is-pkc",
+            "ov-Ip-pkc",
+            "ov-III-pkc",
+            "ov-V-pkc",
+            "ov-Is-pkc-skc",
+            "ov-Ip-pkc-skc",
+            "ov-III-pkc-skc",
+            "ov-V-pkc-skc",
+            // SNOVA (NIST Additional Signatures Round 2)
+            "snova-24-5-4",
+            "snova-24-5-4-shake",
+            "snova-24-5-4-esk",
+            "snova-24-5-4-shake-esk",
+            "snova-25-8-3",
+            "snova-37-17-2",
+            "snova-37-8-4",
+            "snova-24-5-5",
+            "snova-56-25-2",
+            "snova-49-11-3",
+            "snova-60-10-4",
+            "snova-29-6-5",
+        ],
         defaultKemAlgorithm: "kyber-768",
         defaultSignatureAlgorithm: "dilithium-3",
     },
     strict: {
-        kemAlgorithms: ["kyber-768", "kyber-1024"],
-        signatureAlgorithms: ["dilithium-3", "dilithium-5", "falcon-1024"],
+        kemAlgorithms: ["kyber-768", "kyber-1024", "hqc-192", "hqc-256"],
+        signatureAlgorithms: [
+            "dilithium-3",
+            "dilithium-5",
+            "falcon-1024",
+            "sphincs-sha2-256f-simple",
+            "sphincs-sha2-256s-simple",
+            "sphincs-shake-256f-simple",
+            "sphincs-shake-256s-simple",
+        ],
         defaultKemAlgorithm: "kyber-768",
         defaultSignatureAlgorithm: "dilithium-3",
     },
     maximum: {
-        kemAlgorithms: ["kyber-1024"],
-        signatureAlgorithms: ["dilithium-5", "falcon-1024", "sphincs-shake-256f-simple"],
+        kemAlgorithms: ["kyber-1024", "hqc-256"],
+        signatureAlgorithms: [
+            "dilithium-5",
+            "falcon-1024",
+            "sphincs-sha2-256f-simple",
+            "sphincs-shake-256f-simple",
+        ],
         defaultKemAlgorithm: "kyber-1024",
         defaultSignatureAlgorithm: "dilithium-5",
     },
     government: {
         kemAlgorithms: ["kyber-1024"],
-        signatureAlgorithms: ["dilithium-5", "sphincs-shake-256f-simple"],
+        signatureAlgorithms: ["dilithium-5", "sphincs-sha2-256f-simple", "sphincs-shake-256f-simple"],
         defaultKemAlgorithm: "kyber-1024",
         defaultSignatureAlgorithm: "dilithium-5",
     },
@@ -158,19 +295,41 @@ export class TenantClient {
     config;
     telemetry;
     targetService;
+    activationPromise = null;
+    activationConfig;
+    async ensureActivated() {
+        if (!this.activationPromise) {
+            this.activationPromise = activateSdk(this.activationConfig).then(() => undefined);
+        }
+        await this.activationPromise;
+    }
     constructor(config) {
         if (!config.apiKey || config.apiKey.trim().length === 0) {
             throw new Error("QNSP Tenant 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). " +
+                "no credit card required (FREE tier: 10 GB storage, 50,000 API calls/month). " +
                 "Docs: https://docs.qnsp.cuilabs.io/sdk/tenant-sdk");
         }
-        const baseUrl = config.baseUrl.replace(/\/$/, "");
-        // Enforce HTTPS in production (allow HTTP only for localhost in development)
+        const baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).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) {
+            if ((!isLocalhost || !isDevelopment) && !isInternalService) {
                 throw new Error("baseUrl must use HTTPS in production. HTTP is only allowed for localhost in development.");
             }
         }
@@ -192,6 +351,12 @@ export class TenantClient {
         catch {
             this.targetService = "tenant-service";
         }
+        this.activationConfig = {
+            apiKey: config.apiKey,
+            sdkId: "tenant-sdk",
+            sdkVersion: SDK_PACKAGE_VERSION,
+            platformUrl: baseUrl,
+        };
     }
     async request(method, path, options) {
         return this.requestWithRetry(method, path, options, 0);
@@ -296,6 +461,7 @@ export class TenantClient {
      * Requires PQC-signed security envelope and optional signature.
      */
     async createTenant(request) {
+        await this.ensureActivated();
         // Validation is handled by the service, but we validate format here for early feedback
         return this.request("POST", "/tenant/v1/tenants", {
             body: {
@@ -319,6 +485,7 @@ export class TenantClient {
      */
     async updateTenant(id, request) {
         validateUUID(id, "id");
+        await this.ensureActivated();
         return this.request("PATCH", `/tenant/v1/tenants/${id}`, {
             body: {
                 ...(request.plan !== undefined ? { plan: request.plan } : {}),
@@ -338,6 +505,7 @@ export class TenantClient {
      */
     async getTenant(id) {
         validateUUID(id, "id");
+        await this.ensureActivated();
         return this.request("GET", `/tenant/v1/tenants/${id}`, {
             operation: "getTenant",
         });
@@ -347,6 +515,7 @@ export class TenantClient {
      * Returns a list of tenants and an optional next cursor for pagination.
      */
     async listTenants(options) {
+        await this.ensureActivated();
         const params = new URLSearchParams();
         if (options?.limit !== undefined) {
             params.set("limit", String(options.limit));
@@ -367,6 +536,7 @@ export class TenantClient {
      */
     async getTenantCryptoPolicy(tenantId) {
         validateUUID(tenantId, "tenantId");
+        await this.ensureActivated();
         return this.request("GET", `/tenant/v1/tenants/${tenantId}/crypto-policy`, {
             operation: "getTenantCryptoPolicy",
         });
@@ -377,6 +547,7 @@ export class TenantClient {
      */
     async getTenantCryptoPolicyV1(tenantId) {
         validateUUID(tenantId, "tenantId");
+        await this.ensureActivated();
         return this.request("GET", `/tenant/v1/tenants/${tenantId}/crypto-policy-v1`, {
             operation: "getTenantCryptoPolicyV1",
         });
@@ -386,6 +557,7 @@ export class TenantClient {
      */
     async listTenantCryptoPolicyV1History(tenantId, options) {
         validateUUID(tenantId, "tenantId");
+        await this.ensureActivated();
         const params = new URLSearchParams();
         if (options?.limit !== undefined) {
             params.set("limit", String(options.limit));
@@ -404,6 +576,7 @@ export class TenantClient {
      */
     async upsertTenantCryptoPolicy(tenantId, policy) {
         validateUUID(tenantId, "tenantId");
+        await this.ensureActivated();
         return this.request("PUT", `/tenant/v1/tenants/${tenantId}/crypto-policy`, {
             body: {
                 policyTier: policy.policyTier,
@@ -426,6 +599,7 @@ export class TenantClient {
      */
     async updateTenantCryptoPolicyV1(tenantId, policy, etag) {
         validateUUID(tenantId, "tenantId");
+        await this.ensureActivated();
         if (!etag) {
             throw new Error("etag is required for updateTenantCryptoPolicyV1");
         }
@@ -442,6 +616,7 @@ export class TenantClient {
      */
     async enableTier0Legacy(tenantId, input, etag) {
         validateUUID(tenantId, "tenantId");
+        await this.ensureActivated();
         if (!etag) {
             throw new Error("etag is required for enableTier0Legacy");
         }
@@ -458,6 +633,7 @@ export class TenantClient {
      */
     async disableTier0Legacy(tenantId, etag) {
         validateUUID(tenantId, "tenantId");
+        await this.ensureActivated();
         if (!etag) {
             throw new Error("etag is required for disableTier0Legacy");
         }
@@ -474,6 +650,7 @@ export class TenantClient {
      */
     async enableTier4Experimental(tenantId, input, etag) {
         validateUUID(tenantId, "tenantId");
+        await this.ensureActivated();
         if (!etag) {
             throw new Error("etag is required for enableTier4Experimental");
         }
@@ -490,6 +667,7 @@ export class TenantClient {
      */
     async rollbackTenantCryptoPolicyV1(tenantId, input, etag) {
         validateUUID(tenantId, "tenantId");
+        await this.ensureActivated();
         if (!etag) {
             throw new Error("etag is required for rollbackTenantCryptoPolicyV1");
         }
@@ -512,6 +690,8 @@ export class TenantClient {
      * Convenience method that fetches the policy and returns the allowed algorithms.
      */
     async getAllowedKemAlgorithms(tenantId) {
+        validateUUID(tenantId, "tenantId");
+        await this.ensureActivated();
         const policy = await this.getTenantCryptoPolicy(tenantId);
         if (policy.customAllowedKemAlgorithms && policy.customAllowedKemAlgorithms.length > 0) {
             return policy.customAllowedKemAlgorithms;
@@ -523,6 +703,8 @@ export class TenantClient {
      * Convenience method that fetches the policy and returns the allowed algorithms.
      */
     async getAllowedSignatureAlgorithms(tenantId) {
+        validateUUID(tenantId, "tenantId");
+        await this.ensureActivated();
         const policy = await this.getTenantCryptoPolicy(tenantId);
         if (policy.customAllowedSignatureAlgorithms &&
             policy.customAllowedSignatureAlgorithms.length > 0) {
@@ -534,6 +716,8 @@ export class TenantClient {
      * Get the default KEM algorithm for a tenant based on their crypto policy tier.
      */
     async getDefaultKemAlgorithm(tenantId) {
+        validateUUID(tenantId, "tenantId");
+        await this.ensureActivated();
         const policy = await this.getTenantCryptoPolicy(tenantId);
         return CRYPTO_POLICY_ALGORITHMS[policy.policyTier].defaultKemAlgorithm;
     }
@@ -541,9 +725,250 @@ export class TenantClient {
      * Get the default signature algorithm for a tenant based on their crypto policy tier.
      */
     async getDefaultSignatureAlgorithm(tenantId) {
+        validateUUID(tenantId, "tenantId");
+        await this.ensureActivated();
         const policy = await this.getTenantCryptoPolicy(tenantId);
         return CRYPTO_POLICY_ALGORITHMS[policy.policyTier].defaultSignatureAlgorithm;
     }
+    /**
+     * Record a health snapshot for a tenant.
+     */
+    async recordHealthSnapshot(request) {
+        validateUUID(request.tenantId, "tenantId");
+        await this.ensureActivated();
+        return this.request("POST", `/tenant/v1/tenants/${request.tenantId}/health/snapshots`, {
+            body: { metrics: request.metrics },
+            operation: "recordHealthSnapshot",
+        });
+    }
+    /**
+     * Get the current health status for a tenant.
+     */
+    async getCurrentHealth(tenantId) {
+        validateUUID(tenantId, "tenantId");
+        await this.ensureActivated();
+        return this.request("GET", `/tenant/v1/tenants/${tenantId}/health`, {
+            operation: "getCurrentHealth",
+        });
+    }
+    /**
+     * Get health trends for a tenant over time.
+     */
+    async getHealthTrends(request) {
+        validateUUID(request.tenantId, "tenantId");
+        await this.ensureActivated();
+        const params = new URLSearchParams();
+        if (request.since !== undefined)
+            params.set("since", request.since);
+        if (request.until !== undefined)
+            params.set("until", request.until);
+        if (request.granularity !== undefined)
+            params.set("granularity", request.granularity);
+        const queryString = params.toString();
+        const path = queryString
+            ? `/tenant/v1/tenants/${request.tenantId}/health/trends?${queryString}`
+            : `/tenant/v1/tenants/${request.tenantId}/health/trends`;
+        return this.request("GET", path, {
+            operation: "getHealthTrends",
+        });
+    }
+    /**
+     * Create a health alert for a tenant.
+     */
+    async createHealthAlert(request) {
+        validateUUID(request.tenantId, "tenantId");
+        await this.ensureActivated();
+        return this.request("POST", `/tenant/v1/tenants/${request.tenantId}/health/alerts`, {
+            body: {
+                severity: request.severity,
+                title: request.title,
+                description: request.description,
+                ...(request.metric !== undefined ? { metric: request.metric } : {}),
+                ...(request.threshold !== undefined ? { threshold: request.threshold } : {}),
+                ...(request.currentValue !== undefined ? { currentValue: request.currentValue } : {}),
+            },
+            operation: "createHealthAlert",
+        });
+    }
+    /**
+     * Acknowledge a health alert.
+     */
+    async acknowledgeAlert(request) {
+        validateUUID(request.alertId, "alertId");
+        await this.ensureActivated();
+        return this.request("POST", `/tenant/v1/health/alerts/${request.alertId}/acknowledge`, {
+            body: {
+                acknowledgedBy: request.acknowledgedBy,
+                ...(request.note !== undefined ? { note: request.note } : {}),
+            },
+            operation: "acknowledgeAlert",
+        });
+    }
+    /**
+     * Record quota usage for a tenant.
+     */
+    async recordQuotaUsage(request) {
+        validateUUID(request.tenantId, "tenantId");
+        await this.ensureActivated();
+        return this.request("POST", `/tenant/v1/tenants/${request.tenantId}/quotas/usage`, {
+            body: {
+                quotaName: request.quotaName,
+                usage: request.usage,
+                ...(request.timestamp !== undefined ? { timestamp: request.timestamp } : {}),
+            },
+            operation: "recordQuotaUsage",
+        });
+    }
+    /**
+     * Get current quota usage for a tenant.
+     */
+    async getCurrentQuotas(tenantId) {
+        validateUUID(tenantId, "tenantId");
+        await this.ensureActivated();
+        return this.request("GET", `/tenant/v1/tenants/${tenantId}/quotas`, {
+            operation: "getCurrentQuotas",
+        });
+    }
+    /**
+     * Get quota forecast for a tenant.
+     */
+    async getForecast(request) {
+        validateUUID(request.tenantId, "tenantId");
+        await this.ensureActivated();
+        const params = new URLSearchParams();
+        if (request.quotaName !== undefined)
+            params.set("quotaName", request.quotaName);
+        if (request.horizonDays !== undefined)
+            params.set("horizonDays", String(request.horizonDays));
+        const queryString = params.toString();
+        const path = queryString
+            ? `/tenant/v1/tenants/${request.tenantId}/quotas/forecast?${queryString}`
+            : `/tenant/v1/tenants/${request.tenantId}/quotas/forecast`;
+        return this.request("GET", path, {
+            operation: "getForecast",
+        });
+    }
+    /**
+     * Get quota suggestions based on usage patterns.
+     */
+    async getQuotaSuggestions(tenantId) {
+        validateUUID(tenantId, "tenantId");
+        await this.ensureActivated();
+        return this.request("GET", `/tenant/v1/tenants/${tenantId}/quotas/suggestions`, {
+            operation: "getQuotaSuggestions",
+        });
+    }
+    /**
+     * Create an onboarding workflow template.
+     */
+    async createWorkflowTemplate(request) {
+        await this.ensureActivated();
+        return this.request("POST", "/tenant/v1/onboarding/templates", {
+            body: request,
+            operation: "createWorkflowTemplate",
+        });
+    }
+    /**
+     * Start onboarding for a tenant.
+     */
+    async startOnboarding(request) {
+        validateUUID(request.tenantId, "tenantId");
+        await this.ensureActivated();
+        return this.request("POST", `/tenant/v1/tenants/${request.tenantId}/onboarding/start`, {
+            body: {
+                ...(request.templateId !== undefined ? { templateId: request.templateId } : {}),
+                ...(request.metadata !== undefined ? { metadata: request.metadata } : {}),
+            },
+            operation: "startOnboarding",
+        });
+    }
+    /**
+     * Get onboarding status for a tenant.
+     */
+    async getOnboardingStatus(tenantId) {
+        validateUUID(tenantId, "tenantId");
+        await this.ensureActivated();
+        return this.request("GET", `/tenant/v1/tenants/${tenantId}/onboarding/status`, {
+            operation: "getOnboardingStatus",
+        });
+    }
+    /**
+     * Get onboarding statistics.
+     */
+    async getOnboardingStats(options) {
+        await this.ensureActivated();
+        const params = new URLSearchParams();
+        if (options?.since !== undefined)
+            params.set("since", options.since);
+        if (options?.until !== undefined)
+            params.set("until", options.until);
+        const queryString = params.toString();
+        const path = queryString
+            ? `/tenant/v1/onboarding/stats?${queryString}`
+            : "/tenant/v1/onboarding/stats";
+        return this.request("GET", path, {
+            operation: "getOnboardingStats",
+        });
+    }
+    /**
+     * Create an isolation policy for a tenant.
+     */
+    async createIsolationPolicy(request) {
+        validateUUID(request.tenantId, "tenantId");
+        await this.ensureActivated();
+        return this.request("POST", `/tenant/v1/tenants/${request.tenantId}/isolation/policies`, {
+            body: {
+                name: request.name,
+                ...(request.description !== undefined ? { description: request.description } : {}),
+                level: request.level,
+                ...(request.rules !== undefined ? { rules: request.rules } : {}),
+                ...(request.enforcementMode !== undefined
+                    ? { enforcementMode: request.enforcementMode }
+                    : {}),
+            },
+            operation: "createIsolationPolicy",
+        });
+    }
+    /**
+     * Run an isolation audit for a tenant.
+     */
+    async runIsolationAudit(request) {
+        validateUUID(request.tenantId, "tenantId");
+        await this.ensureActivated();
+        return this.request("POST", `/tenant/v1/tenants/${request.tenantId}/isolation/audit`, {
+            body: {
+                ...(request.policyIds !== undefined ? { policyIds: request.policyIds } : {}),
+                ...(request.categories !== undefined ? { categories: request.categories } : {}),
+                ...(request.depth !== undefined ? { depth: request.depth } : {}),
+            },
+            operation: "runIsolationAudit",
+        });
+    }
+    /**
+     * Get isolation findings for a tenant.
+     */
+    async getIsolationFindings(request) {
+        validateUUID(request.tenantId, "tenantId");
+        await this.ensureActivated();
+        const params = new URLSearchParams();
+        if (request.runId !== undefined)
+            params.set("runId", request.runId);
+        if (request.severity !== undefined)
+            params.set("severity", request.severity);
+        if (request.category !== undefined)
+            params.set("category", request.category);
+        if (request.limit !== undefined)
+            params.set("limit", String(request.limit));
+        if (request.cursor !== undefined)
+            params.set("cursor", request.cursor);
+        const queryString = params.toString();
+        const path = queryString
+            ? `/tenant/v1/tenants/${request.tenantId}/isolation/findings?${queryString}`
+            : `/tenant/v1/tenants/${request.tenantId}/isolation/findings`;
+        return this.request("GET", path, {
+            operation: "getIsolationFindings",
+        });
+    }
 }
 export * from "./observability.js";
 export * from "./validation.js";