@tinycloud/sdk-services 1.2.0 → 1.5.0

package/dist/vault/DataVaultService.js

@@ -0,0 +1,975 @@
+/**
+ * DataVaultService - Encrypted key-value storage service implementation.
+ *
+ * Platform-agnostic encrypted KV service that wraps KVService internally.
+ * Uses dependency injection via VaultCrypto for WASM crypto operations
+ * and DataVaultServiceConfig for platform dependencies.
+ *
+ * Architecture:
+ * - Extends BaseService (not KVService)
+ * - Wraps two KV instances: dataKV (prefix "vault/") and keyKV (prefix "keys/")
+ * - Master key and encryption identity live in memory only (cleared on lock)
+ */
+import { BaseService } from "../base/BaseService";
+import { ok, } from "../types";
+import { VaultHeaders, } from "./types";
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/** Convert a caught value to an Error. WASM throws plain objects, not Error instances. */
+function toError(error) {
+    if (error instanceof Error)
+        return error;
+    if (typeof error === "object" && error !== null) {
+        return new Error(JSON.stringify(error));
+    }
+    return new Error(String(error));
+}
+function toBytes(str) {
+    return new TextEncoder().encode(str);
+}
+function fromBytes(bytes) {
+    return new TextDecoder().decode(bytes);
+}
+function hexEncode(bytes) {
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+function concatBytes(...arrays) {
+    const total = arrays.reduce((acc, arr) => acc + arr.length, 0);
+    const result = new Uint8Array(total);
+    let offset = 0;
+    for (const arr of arrays) {
+        result.set(arr, offset);
+        offset += arr.length;
+    }
+    return result;
+}
+function base64Encode(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+function base64Decode(str) {
+    const binary = atob(str);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+function defaultVaultMessage(input) {
+    switch (input.code) {
+        case "DECRYPTION_FAILED": return input.message ?? "Decryption failed";
+        case "KEY_NOT_FOUND": return input.message ?? `Key not found: ${input.key}`;
+        case "INTEGRITY_ERROR": return input.message ?? "Integrity check failed";
+        case "GRANT_NOT_FOUND": return input.message ?? `Grant not found: ${input.grantor} / ${input.key}`;
+        case "VAULT_LOCKED": return input.message ?? "Vault is locked";
+        case "PUBLIC_KEY_NOT_FOUND": return input.message ?? `Public key not found for ${input.did}`;
+        case "STORAGE_ERROR": return input.message ?? input.cause.message;
+    }
+}
+function vaultError(input) {
+    const error = {
+        ...input,
+        service: "vault",
+        message: defaultVaultMessage(input),
+    };
+    return { ok: false, error };
+}
+// =============================================================================
+// DataVaultService
+// =============================================================================
+/**
+ * Data Vault service implementation.
+ *
+ * Provides encrypted key-value storage with client-side encryption,
+ * key management, and sharing via X25519 grants.
+ *
+ * @example
+ * ```typescript
+ * // Unlock the vault
+ * await vault.unlock(signer);
+ *
+ * // Store encrypted data
+ * await vault.put('secret/notes', { content: 'Hello' });
+ *
+ * // Retrieve and decrypt
+ * const entry = await vault.get<{ content: string }>('secret/notes');
+ * if (entry.ok) {
+ *   console.log(entry.data.value.content); // 'Hello'
+ * }
+ *
+ * // Share with another user
+ * await vault.grant('secret/notes', recipientDID);
+ * ```
+ */
+export class DataVaultService extends BaseService {
+    /**
+     * Create a new DataVaultService instance.
+     *
+     * @param config - Service configuration including crypto and tc references
+     */
+    constructor(config) {
+        super();
+        this.masterKey = null;
+        this.encryptionIdentity = null;
+        this._isUnlocked = false;
+        this.vaultConfig = config;
+        this._config = config;
+    }
+    /**
+     * Get the service configuration.
+     */
+    get config() {
+        return this._config;
+    }
+    /**
+     * Whether the vault is currently unlocked.
+     */
+    get isUnlocked() {
+        return this._isUnlocked;
+    }
+    /**
+     * The vault's public encryption key (X25519).
+     * Throws if vault is locked.
+     */
+    get publicKey() {
+        if (!this.encryptionIdentity) {
+            throw new Error("Vault is locked");
+        }
+        return this.encryptionIdentity.publicKey;
+    }
+    /**
+     * Convenience accessor for crypto operations.
+     */
+    get crypto() {
+        return this.vaultConfig.crypto;
+    }
+    /**
+     * Convenience accessor for TinyCloud instance.
+     */
+    get tc() {
+        return this.vaultConfig.tc;
+    }
+    /**
+     * Get the host URL.
+     */
+    get host() {
+        return this.tc.hosts[0];
+    }
+    // =========================================================================
+    // Phase 1: Core Operations
+    // =========================================================================
+    /**
+     * Unlock the vault. Triggers wallet signatures to derive keys.
+     *
+     * 1. Signs a deterministic message to derive the master key
+     * 2. Signs a second message to derive the X25519 encryption identity
+     * 3. Ensures public space exists and publishes the public key
+     *
+     * @param signer - Object with signMessage method (wallet/key signer)
+     */
+    async unlock(signer) {
+        return this.withTelemetry("unlock", undefined, async () => {
+            const s = signer;
+            const spaceId = this.vaultConfig.spaceId;
+            try {
+                // Step 1: Derive master key from deterministic signature
+                const masterSig = await s.signMessage(`tinycloud-vault-master-v1:${spaceId}`);
+                const masterSigBytes = toBytes(masterSig);
+                this.masterKey = this.crypto.deriveKey(masterSigBytes, this.crypto.sha256(toBytes(spaceId)), toBytes("vault-master"));
+                // Step 2: Derive encryption identity from second signature
+                const identitySig = await s.signMessage("tinycloud-encryption-identity-v1");
+                const identitySigBytes = toBytes(identitySig);
+                const seed = this.crypto.deriveKey(identitySigBytes, toBytes("tinycloud-x25519"), toBytes("encryption-identity"));
+                this.encryptionIdentity = this.crypto.x25519FromSeed(seed);
+                // Step 3: Publish vault metadata to public space (best-effort)
+                // This enables other users to discover our public key and vault location.
+                // Non-fatal: key derivation succeeded, publishing is optional.
+                try {
+                    // Try to ensure public space exists (may fail if delegation lacks space/info action)
+                    await this.tc.ensurePublicSpace();
+                    // Publish regardless — the space may already exist even if ensurePublicSpace failed
+                    const pubKeyB64 = base64Encode(this.encryptionIdentity.publicKey);
+                    await this.tc.publicKV.put(".well-known/vault-pubkey", pubKeyB64);
+                    await this.tc.publicKV.put(".well-known/vault-version", "1");
+                    // Publish vault space ID so getShared() can find grants and data
+                    await this.tc.publicKV.put(".well-known/vault-space", this.vaultConfig.spaceId);
+                }
+                catch {
+                    // Public key publishing failed — vault still usable
+                }
+                this._isUnlocked = true;
+                return ok(undefined);
+            }
+            catch (error) {
+                // Clear key material on failure
+                this.masterKey = null;
+                this.encryptionIdentity = null;
+                return vaultError({
+                    code: "STORAGE_ERROR",
+                    cause: toError(error),
+                });
+            }
+        });
+    }
+    /**
+     * Lock the vault, clearing all key material from memory.
+     */
+    lock() {
+        this.masterKey = null;
+        this.encryptionIdentity = null;
+        this._isUnlocked = false;
+    }
+    /**
+     * Called when SDK signs out. Locks the vault and aborts operations.
+     */
+    onSignOut() {
+        this.lock();
+        super.onSignOut();
+    }
+    /**
+     * Encrypt and store a value at the given key.
+     *
+     * @param key - The key to store under
+     * @param value - The value to encrypt and store
+     * @param options - Optional put configuration
+     */
+    async put(key, value, options) {
+        return this.withTelemetry("put", key, async () => {
+            if (!this._isUnlocked || !this.masterKey) {
+                return vaultError({
+                    code: "VAULT_LOCKED",
+                    message: "Vault must be unlocked before storing data",
+                });
+            }
+            if (!this.requireAuth()) {
+                return vaultError({
+                    code: "VAULT_LOCKED",
+                    message: "Authentication required",
+                });
+            }
+            try {
+                // Serialize value
+                let plaintext;
+                if (value instanceof Uint8Array) {
+                    plaintext = value;
+                }
+                else if (options?.serialize) {
+                    plaintext = options.serialize(value);
+                }
+                else if (typeof value === "string") {
+                    plaintext = toBytes(value);
+                }
+                else {
+                    plaintext = toBytes(JSON.stringify(value));
+                }
+                const contentType = options?.contentType ??
+                    (value instanceof Uint8Array
+                        ? "application/octet-stream"
+                        : "application/json");
+                // Generate per-entry key
+                const entryKey = this.crypto.randomBytes(32);
+                const keyId = hexEncode(this.crypto.sha256(entryKey)).slice(0, 16);
+                // Encrypt value with entry key
+                const encrypted = this.crypto.encrypt(entryKey, plaintext);
+                // Encrypt entry key with master key
+                const keyBlob = this.crypto.encrypt(this.masterKey, entryKey);
+                // Build metadata
+                const metadata = {
+                    [VaultHeaders.VERSION]: "1",
+                    [VaultHeaders.CIPHER]: "aes-256-gcm",
+                    [VaultHeaders.KEY_ID]: keyId,
+                    [VaultHeaders.CONTENT_TYPE]: contentType,
+                    [VaultHeaders.KDF]: "hkdf-sha256",
+                    [VaultHeaders.KEY_ROTATION]: this.vaultConfig.keyRotation ?? "per-write",
+                    ...(options?.metadata ?? {}),
+                };
+                // Store encrypted entry key in key space
+                const keyMetadata = JSON.stringify({
+                    keyId,
+                    contentType,
+                    ...metadata,
+                });
+                const keyPayload = JSON.stringify({
+                    key: base64Encode(keyBlob),
+                    metadata: keyMetadata,
+                });
+                const keyPutResult = await this.tc.kv.put(`keys/${key}`, keyPayload);
+                if (!keyPutResult.ok) {
+                    return vaultError({
+                        code: "STORAGE_ERROR",
+                        cause: new Error(`Failed to store key blob: ${keyPutResult.error.message}`),
+                    });
+                }
+                // Store encrypted value in data space
+                const valuePayload = JSON.stringify({
+                    data: base64Encode(encrypted),
+                    metadata,
+                });
+                const valuePutResult = await this.tc.kv.put(`vault/${key}`, valuePayload);
+                if (!valuePutResult.ok) {
+                    return vaultError({
+                        code: "STORAGE_ERROR",
+                        cause: new Error(`Failed to store encrypted value: ${valuePutResult.error.message}`),
+                    });
+                }
+                return ok(undefined);
+            }
+            catch (error) {
+                return vaultError({
+                    code: "STORAGE_ERROR",
+                    cause: toError(error),
+                });
+            }
+        });
+    }
+    /**
+     * Retrieve and decrypt a value by key.
+     *
+     * @param key - The key to retrieve
+     * @param options - Optional get configuration
+     * @returns Result with the decrypted entry
+     */
+    async get(key, options) {
+        return this.withTelemetry("get", key, async () => {
+            if (!this._isUnlocked || !this.masterKey) {
+                return vaultError({
+                    code: "VAULT_LOCKED",
+                    message: "Vault must be unlocked before reading data",
+                });
+            }
+            if (!this.requireAuth()) {
+                return vaultError({
+                    code: "VAULT_LOCKED",
+                    message: "Authentication required",
+                });
+            }
+            try {
+                // Fetch encrypted entry key from key space
+                const keyResult = await this.tc.kv.get(`keys/${key}`, {
+                    raw: true,
+                });
+                if (!keyResult.ok) {
+                    return vaultError({ code: "KEY_NOT_FOUND", key });
+                }
+                const keyEnvelope = JSON.parse(keyResult.data.data);
+                const keyBlobBytes = base64Decode(keyEnvelope.key);
+                const entryKey = this.crypto.decrypt(this.masterKey, keyBlobBytes);
+                // Fetch encrypted value from data space
+                const valueResult = await this.tc.kv.get(`vault/${key}`, {
+                    raw: true,
+                });
+                if (!valueResult.ok) {
+                    return vaultError({ code: "KEY_NOT_FOUND", key });
+                }
+                const valueEnvelope = JSON.parse(valueResult.data.data);
+                const encryptedBytes = base64Decode(valueEnvelope.data);
+                const plaintext = this.crypto.decrypt(entryKey, encryptedBytes);
+                // Read metadata
+                const metadata = valueEnvelope.metadata ?? {};
+                const contentType = metadata[VaultHeaders.CONTENT_TYPE] ?? "application/json";
+                const keyId = metadata[VaultHeaders.KEY_ID] ?? "";
+                // Deserialize
+                let value;
+                if (options?.raw) {
+                    value = plaintext;
+                }
+                else if (options?.deserialize) {
+                    value = options.deserialize(plaintext);
+                }
+                else if (contentType === "application/json") {
+                    value = JSON.parse(fromBytes(plaintext));
+                }
+                else {
+                    value = plaintext;
+                }
+                return ok({ value, metadata, keyId });
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    error.message.includes("decryption")) {
+                    return vaultError({
+                        code: "DECRYPTION_FAILED",
+                        message: error.message,
+                    });
+                }
+                return vaultError({
+                    code: "STORAGE_ERROR",
+                    cause: toError(error),
+                });
+            }
+        });
+    }
+    /**
+     * Delete an encrypted key.
+     * Removes both the encrypted value and the key blob.
+     *
+     * @param key - The key to delete
+     */
+    async delete(key) {
+        return this.withTelemetry("delete", key, async () => {
+            if (!this._isUnlocked) {
+                return vaultError({
+                    code: "VAULT_LOCKED",
+                    message: "Vault must be unlocked before deleting data",
+                });
+            }
+            if (!this.requireAuth()) {
+                return vaultError({
+                    code: "VAULT_LOCKED",
+                    message: "Authentication required",
+                });
+            }
+            try {
+                // Delete from both key space and data space
+                const [keyDelResult, valueDelResult] = await Promise.all([
+                    this.tc.kv.delete(`keys/${key}`),
+                    this.tc.kv.delete(`vault/${key}`),
+                ]);
+                if (!keyDelResult.ok && !valueDelResult.ok) {
+                    return vaultError({ code: "KEY_NOT_FOUND", key });
+                }
+                return ok(undefined);
+            }
+            catch (error) {
+                return vaultError({
+                    code: "STORAGE_ERROR",
+                    cause: toError(error),
+                });
+            }
+        });
+    }
+    /**
+     * List vault keys with optional prefix filtering.
+     *
+     * @param options - Optional list configuration
+     * @returns Result with array of key names (vault/ prefix stripped)
+     */
+    async list(options) {
+        return this.withTelemetry("list", options?.prefix, async () => {
+            if (!this._isUnlocked) {
+                return vaultError({
+                    code: "VAULT_LOCKED",
+                    message: "Vault must be unlocked before listing data",
+                });
+            }
+            if (!this.requireAuth()) {
+                return vaultError({
+                    code: "VAULT_LOCKED",
+                    message: "Authentication required",
+                });
+            }
+            try {
+                const listPrefix = options?.prefix
+                    ? `vault/${options.prefix}`
+                    : "vault/";
+                const listResult = await this.tc.kv.list({
+                    prefix: listPrefix,
+                    removePrefix: true,
+                });
+                if (!listResult.ok) {
+                    return vaultError({
+                        code: "STORAGE_ERROR",
+                        cause: new Error(`Failed to list vault keys: ${listResult.error.message}`),
+                    });
+                }
+                // Keys are already stripped of the "vault/" prefix by removePrefix
+                let keys = listResult.data.keys;
+                // If a user prefix was provided, strip it too if requested
+                if (options?.removePrefix && options.prefix) {
+                    const userPrefix = options.prefix.endsWith("/")
+                        ? options.prefix
+                        : `${options.prefix}/`;
+                    keys = keys.map((k) => k.startsWith(userPrefix) ? k.slice(userPrefix.length) : k);
+                }
+                return ok(keys);
+            }
+            catch (error) {
+                return vaultError({
+                    code: "STORAGE_ERROR",
+                    cause: toError(error),
+                });
+            }
+        });
+    }
+    /**
+     * Get envelope metadata for a key without decrypting the value.
+     *
+     * @param key - The key to inspect
+     * @returns Result with metadata headers
+     */
+    async head(key) {
+        return this.withTelemetry("head", key, async () => {
+            if (!this._isUnlocked) {
+                return vaultError({
+                    code: "VAULT_LOCKED",
+                    message: "Vault must be unlocked before reading metadata",
+                });
+            }
+            if (!this.requireAuth()) {
+                return vaultError({
+                    code: "VAULT_LOCKED",
+                    message: "Authentication required",
+                });
+            }
+            try {
+                // Fetch envelope without decrypting
+                const valueResult = await this.tc.kv.get(`vault/${key}`, {
+                    raw: true,
+                });
+                if (!valueResult.ok) {
+                    return vaultError({ code: "KEY_NOT_FOUND", key });
+                }
+                const valueEnvelope = JSON.parse(valueResult.data.data);
+                const metadata = valueEnvelope.metadata ?? {};
+                return ok(metadata);
+            }
+            catch (error) {
+                return vaultError({
+                    code: "STORAGE_ERROR",
+                    cause: toError(error),
+                });
+            }
+        });
+    }
+    // =========================================================================
+    // Batch Operations
+    // =========================================================================
+    /**
+     * Encrypt and store multiple entries.
+     *
+     * @param entries - Array of key/value pairs with optional per-entry options
+     * @returns Array of results, one per entry
+     */
+    async putMany(entries) {
+        return Promise.all(entries.map((entry) => this.put(entry.key, entry.value, entry.options)));
+    }
+    /**
+     * Retrieve and decrypt multiple keys.
+     *
+     * @param keys - Array of keys to retrieve
+     * @param options - Optional get configuration applied to all entries
+     * @returns Array of results, one per key
+     */
+    async getMany(keys, options) {
+        return Promise.all(keys.map((key) => this.get(key, options)));
+    }
+    // =========================================================================
+    // Phase 2: Sharing
+    // =========================================================================
+    /**
+     * Re-encrypt a vault key for another user (renamed from grant).
+     * Re-encrypts the data key to the recipient's public key via X25519 DH.
+     *
+     * @param key - The key to share
+     * @param recipientDID - The recipient's primary DID (did:pkh:...)
+     * @param options - Optional grant configuration
+     */
+    async reencrypt(key, recipientDID, options) {
+        return this.withTelemetry("reencrypt", key, async () => {
+            if (!this._isUnlocked || !this.masterKey) {
+                return vaultError({
+                    code: "VAULT_LOCKED",
+                    message: "Vault must be unlocked before granting access",
+                });
+            }
+            if (!this.requireAuth()) {
+                return vaultError({
+                    code: "VAULT_LOCKED",
+                    message: "Authentication required",
+                });
+            }
+            try {
+                // Step 1: Resolve recipient's public key
+                const pubKeyResult = await this.resolvePublicKey(recipientDID);
+                if (!pubKeyResult.ok) {
+                    return pubKeyResult;
+                }
+                const bobPubKey = pubKeyResult.data;
+                // Step 2: Fetch and decrypt entry key from key space
+                const keyResult = await this.tc.kv.get(`keys/${key}`, {
+                    raw: true,
+                });
+                if (!keyResult.ok) {
+                    return vaultError({ code: "KEY_NOT_FOUND", key });
+                }
+                const keyEnvelope = JSON.parse(keyResult.data.data);
+                const keyBlobBytes = base64Decode(keyEnvelope.key);
+                const entryKey = this.crypto.decrypt(this.masterKey, keyBlobBytes);
+                // Step 3: Create ephemeral X25519 key pair
+                const ephemeralSeed = this.crypto.randomBytes(32);
+                const ephemeralKeyPair = this.crypto.x25519FromSeed(ephemeralSeed);
+                // Step 4: Compute shared secret via DH
+                const sharedSecret = this.crypto.x25519Dh(ephemeralKeyPair.privateKey, bobPubKey);
+                // Step 5: Derive encryption key from shared secret
+                const encryptionKey = this.crypto.deriveKey(sharedSecret, toBytes("tinycloud-x25519"), toBytes("vault-grant"));
+                // Step 6: Encrypt entry key with derived key
+                const encryptedGrant = this.crypto.encrypt(encryptionKey, entryKey);
+                // Step 7: Concatenate ephemeral public key + encrypted grant
+                const grantBlob = concatBytes(ephemeralKeyPair.publicKey, encryptedGrant);
+                // Step 8: Store grant in key space
+                const grantPayload = JSON.stringify({
+                    grant: base64Encode(grantBlob),
+                    spaceId: this.vaultConfig.spaceId,
+                    metadata: {
+                        [VaultHeaders.GRANT_VERSION]: "1",
+                        [VaultHeaders.GRANTOR]: this.tc.did,
+                        ...(options?.metadata ?? {}),
+                    },
+                });
+                // Store grant in the vault's space (main space)
+                const grantPutResult = await this.tc.kv.put(`grants/${recipientDID}/${key}`, grantPayload);
+                if (!grantPutResult.ok) {
+                    return vaultError({
+                        code: "STORAGE_ERROR",
+                        cause: new Error(`Failed to store grant: ${grantPutResult.error.message}`),
+                    });
+                }
+                return ok(undefined);
+            }
+            catch (error) {
+                return vaultError({
+                    code: "STORAGE_ERROR",
+                    cause: toError(error),
+                });
+            }
+        });
+    }
+    /**
+     * @deprecated Use reencrypt() instead.
+     */
+    async grant(key, recipientDID, options) {
+        return this.reencrypt(key, recipientDID, options);
+    }
+    /**
+     * Retrieve and decrypt a value shared by another user.
+     *
+     * @param grantorDID - The DID of the user who shared the data
+     * @param key - The key that was shared
+     * @param options - Optional get configuration
+     * @returns Result with the decrypted entry
+     */
+    async getShared(grantorDID, key, options) {
+        return this.withTelemetry("getShared", key, async () => {
+            if (!this._isUnlocked ||
+                !this.masterKey ||
+                !this.encryptionIdentity) {
+                return vaultError({
+                    code: "VAULT_LOCKED",
+                    message: "Vault must be unlocked before reading shared data",
+                });
+            }
+            if (!this.requireAuth()) {
+                return vaultError({
+                    code: "VAULT_LOCKED",
+                    message: "Authentication required",
+                });
+            }
+            try {
+                const myDID = this.tc.did;
+                const grantorKV = options?.kv;
+                if (!grantorKV) {
+                    return vaultError({
+                        code: "STORAGE_ERROR",
+                        cause: new Error("getShared requires a delegated KV service via options.kv. " +
+                            "Use useDelegation() to get delegated access, then pass { kv: access.kv }."),
+                    });
+                }
+                // Step 1: Fetch grant from grantor's space via delegated KV
+                const grantResult = await grantorKV.get(`grants/${myDID}/${key}`, {
+                    raw: true,
+                });
+                if (!grantResult.ok) {
+                    return vaultError({
+                        code: "GRANT_NOT_FOUND",
+                        grantor: grantorDID,
+                        key,
+                    });
+                }
+                const grantEnvelope = typeof grantResult.data?.data === "string"
+                    ? JSON.parse(grantResult.data.data)
+                    : grantResult.data?.data;
+                const grantBlobBytes = base64Decode(grantEnvelope.grant);
+                // Step 2: Extract ephemeral public key and encrypted grant
+                const ephemeralPubKey = grantBlobBytes.slice(0, 32);
+                const encryptedGrant = grantBlobBytes.slice(32);
+                // Step 3: Compute shared secret using our private key
+                const sharedSecret = this.crypto.x25519Dh(this.encryptionIdentity.privateKey, ephemeralPubKey);
+                // Step 4: Derive decryption key
+                const encryptionKey = this.crypto.deriveKey(sharedSecret, toBytes("tinycloud-x25519"), toBytes("vault-grant"));
+                // Step 5: Decrypt entry key
+                const entryKey = this.crypto.decrypt(encryptionKey, encryptedGrant);
+                // Step 6: Fetch encrypted value from grantor's space via delegated KV
+                const valueResult = await grantorKV.get(`vault/${key}`, {
+                    raw: true,
+                });
+                if (!valueResult.ok) {
+                    return vaultError({
+                        code: "KEY_NOT_FOUND",
+                        key,
+                    });
+                }
+                const valueEnvelope = typeof valueResult.data?.data === "string"
+                    ? JSON.parse(valueResult.data.data)
+                    : valueResult.data?.data;
+                const encryptedBytes = base64Decode(valueEnvelope.data);
+                const plaintext = this.crypto.decrypt(entryKey, encryptedBytes);
+                // Read metadata
+                const metadata = valueEnvelope.metadata ?? {};
+                const contentType = metadata[VaultHeaders.CONTENT_TYPE] ?? "application/json";
+                const keyId = metadata[VaultHeaders.KEY_ID] ?? "";
+                // Deserialize
+                let value;
+                if (options?.raw) {
+                    value = plaintext;
+                }
+                else if (options?.deserialize) {
+                    value = options.deserialize(plaintext);
+                }
+                else if (contentType === "application/json") {
+                    value = JSON.parse(fromBytes(plaintext));
+                }
+                else {
+                    value = plaintext;
+                }
+                return ok({ value, metadata, keyId });
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    error.message.includes("decryption")) {
+                    return vaultError({
+                        code: "DECRYPTION_FAILED",
+                        message: error.message,
+                    });
+                }
+                return vaultError({
+                    code: "STORAGE_ERROR",
+                    cause: toError(error),
+                });
+            }
+        });
+    }
+    /**
+     * Resolve another user's public encryption key from their DID.
+     *
+     * @param did - The DID to resolve (did:pkh:eip155:{chainId}:{address})
+     * @returns Result with the public key bytes
+     */
+    async resolvePublicKey(did) {
+        try {
+            const parts = this.parseDID(did);
+            if (!parts) {
+                return vaultError({ code: "PUBLIC_KEY_NOT_FOUND", did });
+            }
+            const spaceId = this.tc.makePublicSpaceId(parts.address, parts.chainId);
+            const result = await this.tc.readPublicSpace(this.host, spaceId, ".well-known/vault-pubkey");
+            if (!result.ok) {
+                return vaultError({ code: "PUBLIC_KEY_NOT_FOUND", did });
+            }
+            const pubKeyBytes = base64Decode(result.data);
+            return { ok: true, data: pubKeyBytes };
+        }
+        catch (error) {
+            return vaultError({ code: "PUBLIC_KEY_NOT_FOUND", did });
+        }
+    }
+    /**
+     * List DIDs that have been granted access to a key.
+     *
+     * @param key - The key to list grants for
+     * @returns Result with array of recipient DIDs
+     */
+    async listGrants(key) {
+        return this.withTelemetry("listGrants", key, async () => {
+            if (!this._isUnlocked) {
+                return vaultError({
+                    code: "VAULT_LOCKED",
+                    message: "Vault must be unlocked before listing grants",
+                });
+            }
+            if (!this.requireAuth()) {
+                return vaultError({
+                    code: "VAULT_LOCKED",
+                    message: "Authentication required",
+                });
+            }
+            try {
+                const listResult = await this.tc.kv.list({
+                    prefix: "grants/",
+                    removePrefix: true,
+                });
+                if (!listResult.ok) {
+                    return vaultError({
+                        code: "STORAGE_ERROR",
+                        cause: new Error(`Failed to list grants: ${listResult.error.message}`),
+                    });
+                }
+                // Grant paths are: {recipientDID}/{key}
+                // Filter for the specific key and extract DIDs
+                const dids = [];
+                for (const grantPath of listResult.data.keys) {
+                    // Path format: {recipientDID}/{key}
+                    // The key may contain slashes, so we need to match the suffix
+                    if (grantPath.endsWith(`/${key}`)) {
+                        const did = grantPath.slice(0, grantPath.length - key.length - 1);
+                        if (did) {
+                            dids.push(did);
+                        }
+                    }
+                }
+                return ok(dids);
+            }
+            catch (error) {
+                return vaultError({
+                    code: "STORAGE_ERROR",
+                    cause: toError(error),
+                });
+            }
+        });
+    }
+    // =========================================================================
+    // Phase 3: Key Rotation / Revocation
+    // =========================================================================
+    /**
+     * Revoke a previously issued grant.
+     *
+     * This performs a full key rotation:
+     * 1. Lists current grantees
+     * 2. Removes the revoked recipient
+     * 3. Re-encrypts the value with a new entry key
+     * 4. Re-issues grants to remaining recipients
+     *
+     * @param key - The key to revoke access to
+     * @param recipientDID - The recipient whose access to revoke
+     */
+    async revoke(key, recipientDID) {
+        return this.withTelemetry("revoke", key, async () => {
+            if (!this._isUnlocked || !this.masterKey) {
+                return vaultError({
+                    code: "VAULT_LOCKED",
+                    message: "Vault must be unlocked before revoking access",
+                });
+            }
+            if (!this.requireAuth()) {
+                return vaultError({
+                    code: "VAULT_LOCKED",
+                    message: "Authentication required",
+                });
+            }
+            try {
+                // Step 1: List all current grantees
+                const granteesResult = await this.listGrants(key);
+                if (!granteesResult.ok) {
+                    return granteesResult;
+                }
+                const remainingGrantees = granteesResult.data.filter((did) => did !== recipientDID);
+                // Step 2: Delete the grant for the revoked recipient
+                const deleteGrantResult = await this.tc.kv.delete(`grants/${recipientDID}/${key}`);
+                // Grant may already be deleted, that's fine
+                // Step 3: Fetch and decrypt current value
+                const getResult = await this.get(key);
+                if (!getResult.ok) {
+                    return getResult;
+                }
+                const currentEntry = getResult.data;
+                // Step 4: Generate new entry key
+                const newEntryKey = this.crypto.randomBytes(32);
+                const newKeyId = hexEncode(this.crypto.sha256(newEntryKey)).slice(0, 16);
+                // Step 5: Re-serialize and re-encrypt value with new key
+                let plaintext;
+                if (currentEntry.value instanceof Uint8Array) {
+                    plaintext = currentEntry.value;
+                }
+                else {
+                    plaintext = toBytes(JSON.stringify(currentEntry.value));
+                }
+                const encrypted = this.crypto.encrypt(newEntryKey, plaintext);
+                // Step 6: Encrypt new entry key with master key
+                const newKeyBlob = this.crypto.encrypt(this.masterKey, newEntryKey);
+                // Step 7: Update metadata with new key ID
+                const metadata = {
+                    ...currentEntry.metadata,
+                    [VaultHeaders.KEY_ID]: newKeyId,
+                };
+                // Step 8: Store updated key blob
+                const keyPayload = JSON.stringify({
+                    key: base64Encode(newKeyBlob),
+                    metadata: JSON.stringify({
+                        keyId: newKeyId,
+                        ...metadata,
+                    }),
+                });
+                const keyPutResult = await this.tc.kv.put(`keys/${key}`, keyPayload);
+                if (!keyPutResult.ok) {
+                    return vaultError({
+                        code: "STORAGE_ERROR",
+                        cause: new Error(`Failed to store rotated key blob: ${keyPutResult.error.message}`),
+                    });
+                }
+                // Step 9: Store re-encrypted value
+                const valuePayload = JSON.stringify({
+                    data: base64Encode(encrypted),
+                    metadata,
+                });
+                const valuePutResult = await this.tc.kv.put(`vault/${key}`, valuePayload);
+                if (!valuePutResult.ok) {
+                    return vaultError({
+                        code: "STORAGE_ERROR",
+                        cause: new Error(`Failed to store re-encrypted value: ${valuePutResult.error.message}`),
+                    });
+                }
+                // Step 10: Re-issue grants to remaining recipients
+                for (const did of remainingGrantees) {
+                    const grantResult = await this.reencrypt(key, did);
+                    if (!grantResult.ok) {
+                        // Continue re-issuing to other recipients even if one fails
+                        // The failed grant can be re-issued manually
+                    }
+                }
+                return ok(undefined);
+            }
+            catch (error) {
+                return vaultError({
+                    code: "STORAGE_ERROR",
+                    cause: toError(error),
+                });
+            }
+        });
+    }
+    // =========================================================================
+    // Internal Helpers
+    // =========================================================================
+    /**
+     * Parse a DID string to extract address and chainId.
+     * Expected format: did:pkh:eip155:{chainId}:{address}
+     *
+     * @param did - The DID to parse
+     * @returns Parsed address and chainId, or null if invalid
+     */
+    parseDID(did) {
+        // did:pkh:eip155:{chainId}:{address}
+        const parts = did.split(":");
+        if (parts.length !== 5 ||
+            parts[0] !== "did" ||
+            parts[1] !== "pkh" ||
+            parts[2] !== "eip155") {
+            return null;
+        }
+        const chainId = parseInt(parts[3], 10);
+        const address = parts[4];
+        if (isNaN(chainId) || !address) {
+            return null;
+        }
+        return { address, chainId };
+    }
+}
+/**
+ * Service identifier for registration.
+ */
+DataVaultService.serviceName = "vault";
+//# sourceMappingURL=DataVaultService.js.map