@sovaria/sdk 0.0.0-stage → 0.4.0

package/dist/complete-api.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Complete API namespace factories for SovariaSDK parity with console endpoints.
+ */
+import type { JsonObject, JsonValue, RequestOptions } from './index.js';
+type RequestFn = <T = JsonValue>(method: string, path: string, options?: RequestOptions) => Promise<T>;
+export declare function createKeysApi(request: RequestFn): {
+    list: () => Promise<JsonValue>;
+    create: (payload: JsonObject) => Promise<JsonObject>;
+    ensureDefaults: () => Promise<JsonObject>;
+    revoke: (keyId: string) => Promise<JsonObject>;
+};
+export declare function createGovernanceApi(request: RequestFn): {
+    listRegions: () => Promise<JsonValue>;
+    listAvailableRegions: (query?: {
+        size?: string;
+        plan?: string;
+    }) => Promise<JsonValue>;
+    patchRegion: (regionId: string, body: JsonObject) => Promise<JsonObject>;
+    listTenants: () => Promise<JsonValue>;
+    getTenant: (orgId: string) => Promise<JsonObject>;
+    setTenantStatus: (orgId: string, body: JsonObject) => Promise<JsonObject>;
+    listTenantDatabases: (orgId: string) => Promise<JsonValue>;
+    provisionDatabase: (orgId: string, body: JsonObject) => Promise<JsonObject>;
+    getDatabaseConnection: (orgId: string, projectId: string) => Promise<JsonObject>;
+    /** Staff only: the connection string, with the active access grant that allows revealing it. */
+    revealDatabaseConnection: (orgId: string, projectId: string, grantId: string) => Promise<JsonObject>;
+    pauseDatabase: (orgId: string, projectId: string) => Promise<JsonObject>;
+    resumeDatabase: (orgId: string, projectId: string) => Promise<JsonObject>;
+    resizeDatabase: (orgId: string, projectId: string, body: JsonObject) => Promise<JsonObject>;
+    deleteDatabase: (orgId: string, projectId: string, snapshot?: boolean) => Promise<JsonObject>;
+    listDatabaseBackups: (orgId: string, projectId: string, limit?: number) => Promise<JsonValue>;
+    triggerDatabaseBackup: (orgId: string, projectId: string) => Promise<JsonObject>;
+    adminListDatabases: () => Promise<JsonValue>;
+    listHosts: (regionId?: string) => Promise<JsonValue>;
+    patchHost: (hostId: string, body: JsonObject) => Promise<JsonObject>;
+    metricsOverview: () => Promise<JsonObject>;
+    projectMetrics: (projectId: string, since?: string, limit?: number) => Promise<JsonObject>;
+};
+export declare function createAdminApi(request: RequestFn): {
+    listErrorTraces: (query?: Record<string, string | number | boolean | null | undefined>) => Promise<JsonValue>;
+    getErrorTrace: (traceId: string) => Promise<JsonObject>;
+    resolveErrorTrace: (traceId: string, body?: JsonObject) => Promise<JsonObject>;
+    usageOverview: (period?: string, limit?: number) => Promise<JsonObject>;
+    listAccessTransparency: (query: Record<string, string | number | boolean | null | undefined>) => Promise<JsonValue>;
+    gatewayHealth: () => Promise<JsonValue>;
+};
+export {};

package/dist/complete-api.js

@@ -0,0 +1,64 @@
+/**
+ * Complete API namespace factories for SovariaSDK parity with console endpoints.
+ */
+function safePathSegment(value) {
+    return encodeURIComponent(value);
+}
+export function createKeysApi(request) {
+    return {
+        list: () => request('GET', '/api/v1/apikeys', { requiresScope: true }),
+        create: (payload) => request('POST', '/api/v1/apikeys', { body: payload, requiresScope: true }),
+        ensureDefaults: () => request('POST', '/api/v1/apikeys/ensure-defaults', {
+            body: {},
+            requiresScope: true,
+        }),
+        revoke: (keyId) => request('DELETE', `/api/v1/apikeys/${safePathSegment(keyId)}`, {
+            requiresScope: true,
+        }),
+    };
+}
+export function createGovernanceApi(request) {
+    const gov = (suffix) => `/api/v1/governance/${suffix.replace(/^\//, '')}`;
+    return {
+        listRegions: () => request('GET', gov('regions')),
+        listAvailableRegions: (query) => request('GET', gov('regions/available'), { query }),
+        patchRegion: (regionId, body) => request('PATCH', gov(`regions/${safePathSegment(regionId)}`), { body }),
+        listTenants: () => request('GET', gov('tenants')),
+        getTenant: (orgId) => request('GET', gov(`tenants/${safePathSegment(orgId)}`)),
+        setTenantStatus: (orgId, body) => request('PATCH', gov(`tenants/${safePathSegment(orgId)}/status`), { body }),
+        listTenantDatabases: (orgId) => request('GET', gov(`tenants/${safePathSegment(orgId)}/databases`)),
+        provisionDatabase: (orgId, body) => request('POST', gov(`tenants/${safePathSegment(orgId)}/databases/provision`), {
+            body,
+        }),
+        getDatabaseConnection: (orgId, projectId) => request('GET', gov(`tenants/${safePathSegment(orgId)}/databases/${safePathSegment(projectId)}/connection`)),
+        /** Staff only: the connection string, with the active access grant that allows revealing it. */
+        revealDatabaseConnection: (orgId, projectId, grantId) => request('POST', gov(`tenants/${safePathSegment(orgId)}/databases/${safePathSegment(projectId)}/connection/reveal`), { body: { grant_id: grantId } }),
+        pauseDatabase: (orgId, projectId) => request('POST', gov(`tenants/${safePathSegment(orgId)}/databases/${safePathSegment(projectId)}/pause`), { body: {} }),
+        resumeDatabase: (orgId, projectId) => request('POST', gov(`tenants/${safePathSegment(orgId)}/databases/${safePathSegment(projectId)}/resume`), { body: {} }),
+        resizeDatabase: (orgId, projectId, body) => request('POST', gov(`tenants/${safePathSegment(orgId)}/databases/${safePathSegment(projectId)}/resize`), { body }),
+        deleteDatabase: (orgId, projectId, snapshot = true) => request('DELETE', gov(`tenants/${safePathSegment(orgId)}/databases/${safePathSegment(projectId)}`), { query: { snapshot } }),
+        listDatabaseBackups: (orgId, projectId, limit = 5) => request('GET', gov(`tenants/${safePathSegment(orgId)}/databases/${safePathSegment(projectId)}/backups`), { query: { limit } }),
+        triggerDatabaseBackup: (orgId, projectId) => request('POST', gov(`tenants/${safePathSegment(orgId)}/databases/${safePathSegment(projectId)}/backups`), { body: {} }),
+        adminListDatabases: () => request('GET', gov('admin/databases')),
+        listHosts: (regionId) => request('GET', gov('hosts'), { query: regionId ? { region_id: regionId } : undefined }),
+        patchHost: (hostId, body) => request('PATCH', gov(`hosts/${safePathSegment(hostId)}`), { body }),
+        metricsOverview: () => request('GET', gov('metrics/overview')),
+        projectMetrics: (projectId, since = '24', limit = 500) => request('GET', gov(`metrics/projects/${safePathSegment(projectId)}`), {
+            query: { since, limit },
+        }),
+    };
+}
+export function createAdminApi(request) {
+    return {
+        listErrorTraces: (query) => request('GET', '/api/v1/error-traces', { query }),
+        getErrorTrace: (traceId) => request('GET', `/api/v1/error-traces/${safePathSegment(traceId)}`),
+        resolveErrorTrace: (traceId, body = {}) => request('PATCH', `/api/v1/error-traces/${safePathSegment(traceId)}/resolved`, {
+            body,
+        }),
+        usageOverview: (period, limit = 100) => request('GET', '/api/v1/admin/usage/overview', {
+            query: { period, limit },
+        }),
+        listAccessTransparency: (query) => request('GET', '/api/v1/access-transparency', { query }),
+        gatewayHealth: () => request('GET', '/healthz', { requiresAuth: false }),
+    };
+}

package/dist/crashes.d.ts

@@ -0,0 +1,79 @@
+/**
+ * App crash reporting (plan C5): uncaught errors from your app, grouped into issues in the console
+ * (Observability › Crashes).
+ *
+ * ```ts
+ * sov.crashes.install({ release: '1.4.2' })                 // browser + React Native: uncaught errors and rejections
+ * try { await checkout() } catch (e) { sov.crashes.capture(e, { tags: { step: 'pay' } }) }
+ * ```
+ *
+ * Each report carries the error type, message and stack, the release, the platform and device, the
+ * last 50 breadcrumbs (Sovaria requests the SDK made, plus your own `addBreadcrumb`) and the signed-in
+ * user (the server takes the user from the request's token, not from the report). Reports are batched,
+ * duplicates within a second are dropped and at most 30 a minute are sent, so a crash loop can't flood
+ * your plan's `obs.crash_events_month`.
+ */
+export interface CrashEvent {
+    type: string;
+    message: string;
+    stack: string[];
+    platform: string;
+    release?: string;
+    environment?: string;
+    handled: boolean;
+    url?: string;
+    device?: Record<string, unknown>;
+    breadcrumbs: Breadcrumb[];
+    tags?: Record<string, string>;
+    extra?: Record<string, unknown>;
+    fingerprint?: string;
+    timestamp: string;
+}
+export interface Breadcrumb {
+    category: string;
+    message: string;
+    data?: Record<string, unknown>;
+    timestamp: string;
+}
+export interface CrashOptions {
+    release?: string;
+    environment?: string;
+    /** 0..1: the share of crashes to send (default 1). */
+    sampleRate?: number;
+    /** Change or drop (return null) a report before it is sent. */
+    beforeSend?: (event: CrashEvent) => CrashEvent | null;
+}
+type Sender = (events: CrashEvent[]) => Promise<unknown>;
+export declare class CrashReporter {
+    private readonly send;
+    private options;
+    private queue;
+    private crumbs;
+    private recent;
+    private sentThisMinute;
+    private minute;
+    private timer?;
+    private uninstallers;
+    installed: boolean;
+    constructor(send: Sender);
+    /** Report uncaught errors and unhandled promise rejections (browser and React Native). Call once. */
+    install(options?: CrashOptions): () => void;
+    uninstall(): void;
+    addBreadcrumb(crumb: {
+        category?: string;
+        message: string;
+        data?: Record<string, unknown>;
+    }): void;
+    /** Report an error you caught (handled) or one the app didn't. Returns false when it was dropped. */
+    capture(error: unknown, context?: {
+        handled?: boolean;
+        tags?: Record<string, string>;
+        extra?: Record<string, unknown>;
+        fingerprint?: string;
+    }): boolean;
+    private schedule;
+    /** Send queued reports now. */
+    flush(): Promise<void>;
+}
+export declare function parseStack(error: Error): string[];
+export {};

package/dist/crashes.js

@@ -0,0 +1,176 @@
+/**
+ * App crash reporting (plan C5): uncaught errors from your app, grouped into issues in the console
+ * (Observability › Crashes).
+ *
+ * ```ts
+ * sov.crashes.install({ release: '1.4.2' })                 // browser + React Native: uncaught errors and rejections
+ * try { await checkout() } catch (e) { sov.crashes.capture(e, { tags: { step: 'pay' } }) }
+ * ```
+ *
+ * Each report carries the error type, message and stack, the release, the platform and device, the
+ * last 50 breadcrumbs (Sovaria requests the SDK made, plus your own `addBreadcrumb`) and the signed-in
+ * user (the server takes the user from the request's token, not from the report). Reports are batched,
+ * duplicates within a second are dropped and at most 30 a minute are sent, so a crash loop can't flood
+ * your plan's `obs.crash_events_month`.
+ */
+const MAX_BREADCRUMBS = 50;
+const MAX_PER_MINUTE = 30;
+export class CrashReporter {
+    send;
+    options = {};
+    queue = [];
+    crumbs = [];
+    recent = new Map();
+    sentThisMinute = 0;
+    minute = 0;
+    timer;
+    uninstallers = [];
+    installed = false;
+    constructor(send) {
+        this.send = send;
+    }
+    /** Report uncaught errors and unhandled promise rejections (browser and React Native). Call once. */
+    install(options = {}) {
+        this.options = options;
+        if (this.installed)
+            return () => this.uninstall();
+        this.installed = true;
+        const g = globalThis;
+        if (typeof g.addEventListener === 'function') {
+            const onError = (e) => this.capture(e.error ?? new Error(String(e.message ?? 'Script error')), { handled: false });
+            const onRejection = (e) => this.capture(e.reason ?? new Error('Unhandled promise rejection'), { handled: false });
+            g.addEventListener('error', onError);
+            g.addEventListener('unhandledrejection', onRejection);
+            const onHide = () => void this.flush();
+            g.addEventListener('pagehide', onHide);
+            this.uninstallers.push(() => {
+                g.removeEventListener?.('error', onError);
+                g.removeEventListener?.('unhandledrejection', onRejection);
+                g.removeEventListener?.('pagehide', onHide);
+            });
+        }
+        // React Native: wrap the global handler, then call the previous one (keeps the red box / crash).
+        const errorUtils = g.ErrorUtils;
+        if (errorUtils?.setGlobalHandler && errorUtils.getGlobalHandler) {
+            const previous = errorUtils.getGlobalHandler();
+            errorUtils.setGlobalHandler((error, fatal) => {
+                this.capture(error, { handled: false, tags: { fatal: String(Boolean(fatal)) } });
+                void this.flush();
+                previous?.(error, fatal);
+            });
+            this.uninstallers.push(() => errorUtils.setGlobalHandler?.(previous));
+        }
+        return () => this.uninstall();
+    }
+    uninstall() {
+        for (const off of this.uninstallers.splice(0))
+            off();
+        this.installed = false;
+    }
+    addBreadcrumb(crumb) {
+        this.crumbs.push({ category: crumb.category ?? 'app', message: String(crumb.message).slice(0, 300), data: crumb.data,
+            timestamp: new Date().toISOString() });
+        if (this.crumbs.length > MAX_BREADCRUMBS)
+            this.crumbs.splice(0, this.crumbs.length - MAX_BREADCRUMBS);
+    }
+    /** Report an error you caught (handled) or one the app didn't. Returns false when it was dropped. */
+    capture(error, context = {}) {
+        const err = error instanceof Error ? error : new Error(typeof error === 'string' ? error : JSON.stringify(error ?? 'Unknown error'));
+        if ((this.options.sampleRate ?? 1) < 1 && Math.random() >= (this.options.sampleRate ?? 1))
+            return false;
+        const stack = parseStack(err);
+        const key = `${err.name}|${err.message}|${stack[0] ?? ''}`;
+        const now = Date.now();
+        if ((this.recent.get(key) ?? 0) > now - 1000)
+            return false;
+        this.recent.set(key, now);
+        if (this.recent.size > 200)
+            this.recent.clear();
+        const minute = Math.floor(now / 60_000);
+        if (minute !== this.minute) {
+            this.minute = minute;
+            this.sentThisMinute = 0;
+        }
+        if (this.sentThisMinute >= MAX_PER_MINUTE)
+            return false;
+        let event = {
+            type: err.name || 'Error',
+            message: err.message,
+            stack,
+            platform: detectPlatform(),
+            release: this.options.release,
+            environment: this.options.environment,
+            handled: context.handled ?? true,
+            url: currentUrl(),
+            device: deviceInfo(),
+            breadcrumbs: [...this.crumbs],
+            tags: context.tags,
+            extra: context.extra,
+            fingerprint: context.fingerprint,
+            timestamp: new Date().toISOString(),
+        };
+        if (this.options.beforeSend)
+            event = this.options.beforeSend(event);
+        if (!event)
+            return false;
+        this.sentThisMinute++;
+        this.queue.push(event);
+        this.schedule();
+        return true;
+    }
+    schedule() {
+        if (this.timer)
+            return;
+        this.timer = setTimeout(() => void this.flush(), 1000);
+    }
+    /** Send queued reports now. */
+    async flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        while (this.queue.length) {
+            const batch = this.queue.splice(0, 20);
+            try {
+                await this.send(batch);
+            }
+            catch {
+                return; // never let crash reporting itself crash the app; the batch is dropped
+            }
+        }
+    }
+}
+export function parseStack(error) {
+    return String(error.stack ?? '')
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l && !l.startsWith(`${error.name}:`) && l !== error.name)
+        .slice(0, 50);
+}
+function detectPlatform() {
+    const g = globalThis;
+    if (g.navigator?.product === 'ReactNative')
+        return 'react-native';
+    if (typeof g.window !== 'undefined' && typeof g.document !== 'undefined')
+        return 'web';
+    if (g.process?.versions?.node)
+        return 'node';
+    return 'javascript';
+}
+function currentUrl() {
+    const g = globalThis;
+    return typeof g.location?.href === 'string' ? g.location.href : undefined;
+}
+function deviceInfo() {
+    const g = globalThis;
+    const out = {};
+    if (g.navigator?.userAgent)
+        out.user_agent = String(g.navigator.userAgent).slice(0, 300);
+    if (g.navigator?.language)
+        out.language = g.navigator.language;
+    if (g.screen?.width)
+        out.screen = `${g.screen.width}x${g.screen.height}`;
+    if (g.process?.versions?.node)
+        out.node = g.process.versions.node;
+    return out;
+}

package/dist/crypto.d.ts

@@ -0,0 +1,37 @@
+/** Argon2id parameters (OWASP recommended minimums, matching Python SDK). */
+export declare const ARGON2_TIME_COST = 3;
+export declare const ARGON2_MEMORY_COST = 65536;
+export declare const ARGON2_PARALLELISM = 1;
+export declare const ARGON2_HASH_LEN = 32;
+export declare const ARGON2_SALT_LEN = 16;
+export declare const DEK_SIZE_BYTES = 32;
+export declare const NONCE_SIZE_BYTES = 12;
+export interface EncryptedEnvelope {
+    ciphertext: string;
+    nonce: string;
+    auth_tag: string;
+    encrypted_dek: string;
+    dek_nonce: string;
+    payload_hash: string;
+    salt?: string;
+}
+/** Derive a 256-bit KEK from password + salt using Argon2id. */
+export declare function deriveKek(password: string, salt: Uint8Array): Promise<Uint8Array>;
+/** Generate a 128-bit cryptographically random salt. */
+export declare function generateSalt(): Uint8Array;
+/** Parse a hex-encoded salt string into bytes. */
+export declare function hexToBytes(hex: string): Uint8Array;
+/** Encode bytes as a lowercase hex string. */
+export declare function bytesToHex(bytes: Uint8Array): string;
+/** Best-effort RAM wipe for sensitive byte buffers. */
+export declare function zeroBytes(data: Uint8Array | ArrayBuffer): void;
+/** SHA-256(ciphertext_b64 || nonce_b64 || auth_tag_b64) for Gateway L11 verification. */
+export declare function computePayloadHash(envelope: Pick<EncryptedEnvelope, 'ciphertext' | 'nonce' | 'auth_tag'>): Promise<string>;
+/** Full Zero-Knowledge envelope encryption (derives KEK from password). */
+export declare function encryptDocument(plaintext: Uint8Array, password: string, salt: Uint8Array): Promise<EncryptedEnvelope>;
+/** Encrypt using a pre-derived KEK (skips Argon2id). */
+export declare function encryptDocumentWithKek(plaintext: Uint8Array, kek: Uint8Array): Promise<EncryptedEnvelope>;
+/** Reverse envelope encryption using password-derived KEK. */
+export declare function decryptDocument(envelope: EncryptedEnvelope, password: string, salt: Uint8Array): Promise<Uint8Array>;
+/** Decrypt using a pre-derived KEK (skips Argon2id). */
+export declare function decryptDocumentWithKek(envelope: EncryptedEnvelope, kek: Uint8Array): Promise<Uint8Array>;

package/dist/crypto.js

@@ -0,0 +1,189 @@
+import { argon2id } from 'hash-wasm';
+/** Argon2id parameters (OWASP recommended minimums, matching Python SDK). */
+export const ARGON2_TIME_COST = 3;
+export const ARGON2_MEMORY_COST = 65536; // 64 MB in KiB
+export const ARGON2_PARALLELISM = 1;
+export const ARGON2_HASH_LEN = 32;
+export const ARGON2_SALT_LEN = 16;
+export const DEK_SIZE_BYTES = 32;
+export const NONCE_SIZE_BYTES = 12;
+function getSubtleCrypto() {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new Error('Web Crypto API (crypto.subtle) is not available in this environment');
+    }
+    return subtle;
+}
+function randomBytes(length) {
+    const bytes = new Uint8Array(length);
+    globalThis.crypto.getRandomValues(bytes);
+    return bytes;
+}
+function bytesToBase64(bytes) {
+    let binary = '';
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+    }
+    return btoa(binary);
+}
+function base64ToBytes(value) {
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+function concatBytes(...parts) {
+    const total = parts.reduce((sum, part) => sum + part.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+function toBufferSource(data) {
+    return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+}
+async function sha256Hex(data) {
+    const digest = await getSubtleCrypto().digest('SHA-256', toBufferSource(data));
+    return Array.from(new Uint8Array(digest))
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('');
+}
+async function importAesKey(keyBytes, usages) {
+    return getSubtleCrypto().importKey('raw', toBufferSource(keyBytes), { name: 'AES-GCM' }, false, usages);
+}
+async function aesGcmEncrypt(keyBytes, nonce, plaintext) {
+    const key = await importAesKey(keyBytes, ['encrypt']);
+    const full = new Uint8Array(await getSubtleCrypto().encrypt({ name: 'AES-GCM', iv: toBufferSource(nonce), tagLength: 128 }, key, toBufferSource(plaintext)));
+    return {
+        ciphertext: full.slice(0, full.length - 16),
+        authTag: full.slice(full.length - 16),
+    };
+}
+async function aesGcmDecrypt(keyBytes, nonce, ciphertext, authTag) {
+    const key = await importAesKey(keyBytes, ['decrypt']);
+    const full = concatBytes(ciphertext, authTag);
+    return new Uint8Array(await getSubtleCrypto().decrypt({ name: 'AES-GCM', iv: toBufferSource(nonce), tagLength: 128 }, key, toBufferSource(full)));
+}
+async function aesGcmDecryptCombined(keyBytes, nonce, ciphertextWithTag) {
+    const key = await importAesKey(keyBytes, ['decrypt']);
+    return new Uint8Array(await getSubtleCrypto().decrypt({ name: 'AES-GCM', iv: toBufferSource(nonce), tagLength: 128 }, key, toBufferSource(ciphertextWithTag)));
+}
+async function buildEnvelopeFromParts(docCiphertext, docNonce, authTag, encryptedDek, dekNonce) {
+    const ciphertext = bytesToBase64(docCiphertext);
+    const nonce = bytesToBase64(docNonce);
+    const auth_tag = bytesToBase64(authTag);
+    const payload_hash = await computePayloadHash({ ciphertext, nonce, auth_tag });
+    return {
+        ciphertext,
+        nonce,
+        auth_tag,
+        encrypted_dek: bytesToBase64(encryptedDek),
+        dek_nonce: bytesToBase64(dekNonce),
+        payload_hash,
+    };
+}
+/** Derive a 256-bit KEK from password + salt using Argon2id. */
+export async function deriveKek(password, salt) {
+    const hash = await argon2id({
+        password,
+        salt,
+        iterations: ARGON2_TIME_COST,
+        memorySize: ARGON2_MEMORY_COST,
+        parallelism: ARGON2_PARALLELISM,
+        hashLength: ARGON2_HASH_LEN,
+        outputType: 'binary',
+    });
+    return hash instanceof Uint8Array ? hash : new Uint8Array(hash);
+}
+/** Generate a 128-bit cryptographically random salt. */
+export function generateSalt() {
+    return randomBytes(ARGON2_SALT_LEN);
+}
+/** Parse a hex-encoded salt string into bytes. */
+export function hexToBytes(hex) {
+    const normalized = hex.trim();
+    if (normalized.length % 2 !== 0) {
+        throw new Error('Invalid hex string length');
+    }
+    const bytes = new Uint8Array(normalized.length / 2);
+    for (let i = 0; i < bytes.length; i += 1) {
+        bytes[i] = Number.parseInt(normalized.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}
+/** Encode bytes as a lowercase hex string. */
+export function bytesToHex(bytes) {
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/** Best-effort RAM wipe for sensitive byte buffers. */
+export function zeroBytes(data) {
+    const view = data instanceof Uint8Array ? data : new Uint8Array(data);
+    for (let i = 0; i < view.length; i += 1) {
+        view[i] = 0;
+    }
+}
+/** SHA-256(ciphertext_b64 || nonce_b64 || auth_tag_b64) for Gateway L11 verification. */
+export async function computePayloadHash(envelope) {
+    const payload = new TextEncoder().encode(envelope.ciphertext + envelope.nonce + envelope.auth_tag);
+    return sha256Hex(payload);
+}
+/** Full Zero-Knowledge envelope encryption (derives KEK from password). */
+export async function encryptDocument(plaintext, password, salt) {
+    const kek = await deriveKek(password, salt);
+    const dek = randomBytes(DEK_SIZE_BYTES);
+    try {
+        const docNonce = randomBytes(NONCE_SIZE_BYTES);
+        const { ciphertext: docCiphertext, authTag } = await aesGcmEncrypt(dek, docNonce, plaintext);
+        const dekNonce = randomBytes(NONCE_SIZE_BYTES);
+        const encryptedDek = await aesGcmEncryptCombined(kek, dekNonce, dek);
+        return await buildEnvelopeFromParts(docCiphertext, docNonce, authTag, encryptedDek, dekNonce);
+    }
+    finally {
+        zeroBytes(dek);
+        zeroBytes(kek);
+    }
+}
+async function aesGcmEncryptCombined(keyBytes, nonce, plaintext) {
+    const key = await importAesKey(keyBytes, ['encrypt']);
+    return new Uint8Array(await getSubtleCrypto().encrypt({ name: 'AES-GCM', iv: toBufferSource(nonce), tagLength: 128 }, key, toBufferSource(plaintext)));
+}
+/** Encrypt using a pre-derived KEK (skips Argon2id). */
+export async function encryptDocumentWithKek(plaintext, kek) {
+    const dek = randomBytes(DEK_SIZE_BYTES);
+    try {
+        const docNonce = randomBytes(NONCE_SIZE_BYTES);
+        const { ciphertext: docCiphertext, authTag } = await aesGcmEncrypt(dek, docNonce, plaintext);
+        const dekNonce = randomBytes(NONCE_SIZE_BYTES);
+        const encryptedDek = await aesGcmEncryptCombined(kek, dekNonce, dek);
+        return await buildEnvelopeFromParts(docCiphertext, docNonce, authTag, encryptedDek, dekNonce);
+    }
+    finally {
+        zeroBytes(dek);
+    }
+}
+/** Reverse envelope encryption using password-derived KEK. */
+export async function decryptDocument(envelope, password, salt) {
+    const kek = await deriveKek(password, salt);
+    try {
+        return await decryptDocumentWithKek(envelope, kek);
+    }
+    finally {
+        zeroBytes(kek);
+    }
+}
+/** Decrypt using a pre-derived KEK (skips Argon2id). */
+export async function decryptDocumentWithKek(envelope, kek) {
+    const dek = await aesGcmDecryptCombined(kek, base64ToBytes(envelope.dek_nonce), base64ToBytes(envelope.encrypted_dek));
+    try {
+        return aesGcmDecrypt(dek, base64ToBytes(envelope.nonce), base64ToBytes(envelope.ciphertext), base64ToBytes(envelope.auth_tag));
+    }
+    finally {
+        zeroBytes(dek);
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Errors thrown by the SDK.
+ *
+ * `message` is written for the people using your app ("You don't have permission to do that."),
+ * so `catch (e) { show(e.message) }` never leaks policy names, table names or SQL to end users.
+ * The server's own text stays available for developers in `technicalMessage` / `detail`,
+ * and `code` is a stable value to branch on.
+ */
+export type SovariaErrorCode = 'NETWORK_ERROR' | 'UNAUTHENTICATED' | 'PERMISSION_DENIED' | 'NOT_FOUND' | 'CONFLICT' | 'INVALID_INPUT' | 'PAYLOAD_TOO_LARGE' | 'UNSUPPORTED_TYPE' | 'RATE_LIMITED' | 'PLAN_LIMIT_REACHED' | 'PLAN_FEATURE_REQUIRED' | 'PLAN_QUOTA_EXHAUSTED' | 'SERVICE_UNAVAILABLE' | 'SERVER_ERROR' | 'BAD_REQUEST' | 'CONFIG_ERROR' | 'UNKNOWN';
+export declare class SovariaError extends Error {
+    /** HTTP status (0 when the request never got a response). */
+    readonly statusCode: number;
+    /** The server's response body (or the SDK's own explanation). */
+    readonly detail: unknown;
+    /** Stable category to branch on. */
+    readonly code: SovariaErrorCode;
+    /** The server code when one was sent (e.g. PLAN_LIMIT_REACHED), else `code`. */
+    readonly serverCode: string;
+    /** `HTTP <status>: <server text>` — for logs and developers, not for end users. */
+    technicalMessage: string;
+    /**
+     * The request's trace id (W3C traceparent). In the console, Logs › Request traces (or
+     * `sov.api.observability…` / `sov logs why <id>`) says which check refused the request and why.
+     */
+    traceId?: string;
+    constructor(statusCode: number, detail: unknown, code?: SovariaErrorCode);
+    /** Attach the request's trace id (kept in `technicalMessage` for logs). */
+    withTraceId(traceId: string | null | undefined): this;
+    /** A mistake in how the SDK is set up or called; the message is written for the developer. */
+    static config(message: string, statusCode?: number): SovariaError;
+    /** The message to show your users (same as `message`). */
+    get userMessage(): string;
+    toString(): string;
+}
+/** A friendly message for any thrown value: SovariaError text as-is, anything else generic. */
+export declare function userMessageFor(error: unknown, fallback?: string): string;
+/** A W3C trace id (32 hex) for one logical request; every retry of it shares the id. */
+export declare function newTraceId(): string;
+/** `traceparent` for one attempt: the request's trace id and a fresh span id. */
+export declare function traceparentFor(traceId: string): string;