@sovaria/sdk 0.0.0-stage → 0.5.0

package/dist/complete-api.js

@@ -0,0 +1,71 @@
+/**
+ * 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: {} }),
+        /**
+         * Download a completed backup (plain SQL, gzip) as a Blob — the whole database, so owners, admins and
+         * developers only (`database.backup.read`). Restore it anywhere with `gunzip -c file | psql`.
+         */
+        downloadDatabaseBackup: (orgId, projectId, backupId) => request('GET', gov(`tenants/${safePathSegment(orgId)}/databases/${safePathSegment(projectId)}/backups/${safePathSegment(String(backupId))}/download`), { responseType: 'blob' }),
+        /** Download a portable export bundle (tar.gz: Postgres dump + migration metadata) as a Blob. */
+        downloadProjectExport: (orgId, projectId, exportId) => request('GET', gov(`tenants/${safePathSegment(orgId)}/databases/${safePathSegment(projectId)}/exports/${safePathSegment(exportId)}/download`), { responseType: 'blob' }),
+        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,111 @@
+/**
+ * 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`.
+ *
+ * Release health: `install()` also starts a session (one per page load / app launch) and marks it crashed on
+ * an uncaught error or errored on the first handled one, so the console shows crash-free sessions and users per
+ * release (`trackSessions: false` turns it off). Minified stacks are turned back into your source with the
+ * source maps you upload for the release: `sov crashes sourcemaps upload ./dist --release 1.4.2`.
+ */
+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;
+    session_id?: string;
+    trace_id?: string;
+}
+export interface SessionPing {
+    id: string;
+    status: 'init' | 'crashed' | 'errored' | 'abnormal' | 'exited';
+    started: string;
+    release?: string;
+    environment?: string;
+    platform: string;
+    distinct_id: 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;
+    /** Session pings for release health (crash-free sessions/users per release). Default true. */
+    trackSessions?: boolean;
+}
+type Sender = (events: CrashEvent[]) => Promise<unknown>;
+type SessionSender = (sessions: SessionPing[]) => Promise<unknown>;
+export declare class CrashReporter {
+    private readonly send;
+    private readonly sendSessions?;
+    private options;
+    private queue;
+    private crumbs;
+    private recent;
+    private sentThisMinute;
+    private minute;
+    private timer?;
+    private uninstallers;
+    private session?;
+    private marked;
+    installed: boolean;
+    constructor(send: Sender, sendSessions?: SessionSender | undefined);
+    /** The current session id (also sent with crash reports and performance measurements). */
+    get sessionId(): string | undefined;
+    /** Start a new release-health session (install() starts one; call this when your app returns to the foreground
+     *  after a long time, if you count that as a new session). */
+    startSession(): void;
+    private markSession;
+    private ping;
+    /** 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[];
+declare function detectPlatform(): string;
+/** A stable anonymous id for this browser / app install (localStorage), used to count users per release. */
+export declare function distinctId(): string;
+export { detectPlatform };

package/dist/crashes.js

@@ -0,0 +1,244 @@
+/**
+ * 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`.
+ *
+ * Release health: `install()` also starts a session (one per page load / app launch) and marks it crashed on
+ * an uncaught error or errored on the first handled one, so the console shows crash-free sessions and users per
+ * release (`trackSessions: false` turns it off). Minified stacks are turned back into your source with the
+ * source maps you upload for the release: `sov crashes sourcemaps upload ./dist --release 1.4.2`.
+ */
+const MAX_BREADCRUMBS = 50;
+const MAX_PER_MINUTE = 30;
+export class CrashReporter {
+    send;
+    sendSessions;
+    options = {};
+    queue = [];
+    crumbs = [];
+    recent = new Map();
+    sentThisMinute = 0;
+    minute = 0;
+    timer;
+    uninstallers = [];
+    session;
+    marked = new Set();
+    installed = false;
+    constructor(send, sendSessions) {
+        this.send = send;
+        this.sendSessions = sendSessions;
+    }
+    /** The current session id (also sent with crash reports and performance measurements). */
+    get sessionId() {
+        return this.session?.id;
+    }
+    /** Start a new release-health session (install() starts one; call this when your app returns to the foreground
+     *  after a long time, if you count that as a new session). */
+    startSession() {
+        this.session = {
+            id: randomId(), status: 'init', started: new Date().toISOString(), release: this.options.release,
+            environment: this.options.environment, platform: detectPlatform(), distinct_id: distinctId(),
+        };
+        this.marked.clear();
+        void this.ping({ ...this.session });
+    }
+    markSession(status) {
+        if (!this.session || this.marked.has('crashed') || this.marked.has(status))
+            return;
+        this.marked.add(status);
+        void this.ping({ ...this.session, status });
+    }
+    async ping(s) {
+        if (!this.sendSessions || this.options.trackSessions === false)
+            return;
+        try {
+            await this.sendSessions([s]);
+        }
+        catch {
+            /* release health is best effort */
+        }
+    }
+    /** 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;
+        if (options.trackSessions !== false)
+            this.startSession();
+        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(),
+            session_id: this.session?.id,
+        };
+        if (this.options.beforeSend)
+            event = this.options.beforeSend(event);
+        if (!event)
+            return false;
+        this.markSession(event.handled ? 'errored' : 'crashed');
+        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;
+}
+function randomId() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    return Array.from({ length: 32 }, () => Math.floor(Math.random() * 16).toString(16)).join('');
+}
+let cachedDistinct;
+/** A stable anonymous id for this browser / app install (localStorage), used to count users per release. */
+export function distinctId() {
+    if (cachedDistinct)
+        return cachedDistinct;
+    const g = globalThis;
+    try {
+        const existing = g.localStorage?.getItem('sovaria.distinct_id');
+        if (existing)
+            return (cachedDistinct = String(existing));
+        const id = randomId();
+        g.localStorage?.setItem('sovaria.distinct_id', id);
+        return (cachedDistinct = id);
+    }
+    catch {
+        return (cachedDistinct = randomId());
+    }
+}
+export { detectPlatform };

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);
+    }
+}