@tinycloud/sdk-services 2.0.1 → 2.0.2-beta.0

package/dist/vault/DataVaultService.js

@@ -1,1040 +0,0 @@
-/**
- * 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, VaultVersionConfig, CURRENT_VAULT_VERSION, } from "./types";
-import { loadCachedSignature, cacheSignature, clearSignatureCache, } from "./SignatureCache";
-// =============================================================================
-// 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. Derives keys from two wallet signatures:
-     * 1. Master signature (per-space) — used to derive the master encryption key
-     * 2. Identity signature (per-address) — used to derive X25519 encryption identity
-     *
-     * If the identity public key already exists in the public space, the identity
-     * signature is skipped entirely (no wallet popup). The identity private key is
-     * only needed for sharing operations.
-     *
-     * @param signer - Object with signMessage method. Optional when cached
-     *                 signatures exist (browser only).
-     */
-    async unlock(signer) {
-        return this.withTelemetry("unlock", undefined, async () => {
-            const spaceId = this.vaultConfig.spaceId;
-            const versionConfig = VaultVersionConfig[CURRENT_VAULT_VERSION];
-            const masterCacheKey = `vault-master:${spaceId}`;
-            const identityCacheKey = `vault-identity:${this.tc.address}`;
-            try {
-                // -----------------------------------------------------------------
-                // Step 1: Master signature → master key
-                // -----------------------------------------------------------------
-                let masterSigBytes = await loadCachedSignature(masterCacheKey);
-                if (!masterSigBytes) {
-                    if (!signer) {
-                        return vaultError({
-                            code: "VAULT_LOCKED",
-                            message: "Signer is required when no cached master signature exists",
-                        });
-                    }
-                    const s = signer;
-                    const sig = await s.signMessage(versionConfig.masterMessage(spaceId));
-                    masterSigBytes = toBytes(sig);
-                    await cacheSignature(masterCacheKey, masterSigBytes);
-                }
-                // Derive master key: deriveKey(sigBytes, sha256(spaceId), "vault-master")
-                this.masterKey = this.crypto.deriveKey(masterSigBytes, this.crypto.sha256(toBytes(spaceId)), toBytes("vault-master"));
-                // -----------------------------------------------------------------
-                // Step 2: Identity — check public space first, then sign if needed
-                // -----------------------------------------------------------------
-                const publicSpaceId = this.tc.makePublicSpaceId(this.tc.address, this.tc.chainId);
-                // Check public space for existing vault pubkey
-                let existingPubKey = null;
-                try {
-                    const existing = await this.tc.readPublicSpace(this.host, publicSpaceId, ".well-known/vault-pubkey");
-                    if (existing.ok && existing.data) {
-                        existingPubKey = existing.data;
-                    }
-                }
-                catch {
-                    // Read failed — treat as missing
-                }
-                if (existingPubKey) {
-                    // Public key exists — trust it, skip identity signing entirely
-                    this.encryptionIdentity = {
-                        publicKey: base64Decode(existingPubKey),
-                        privateKey: new Uint8Array(0), // private key not available without signing
-                    };
-                }
-                else {
-                    // Public key missing — need identity signature to derive keypair
-                    let identitySigBytes = await loadCachedSignature(identityCacheKey);
-                    if (!identitySigBytes) {
-                        if (!signer) {
-                            // No signer available — skip identity derivation.
-                            // Vault still works for get/put (only needs master key).
-                            this.encryptionIdentity = null;
-                            this._isUnlocked = true;
-                            return ok(undefined);
-                        }
-                        const s = signer;
-                        const sig = await s.signMessage(versionConfig.identityMessage);
-                        identitySigBytes = toBytes(sig);
-                        await cacheSignature(identityCacheKey, identitySigBytes);
-                    }
-                    // Derive X25519 keypair from identity signature
-                    const seed = this.crypto.deriveKey(identitySigBytes, toBytes("tinycloud-x25519"), toBytes("encryption-identity"));
-                    this.encryptionIdentity = this.crypto.x25519FromSeed(seed);
-                    // Publish public key to public space
-                    try {
-                        const pubKeyB64 = base64Encode(this.encryptionIdentity.publicKey);
-                        await this.tc.ensurePublicSpace();
-                        await this.tc.publicKV.put(".well-known/vault-pubkey", pubKeyB64);
-                        await this.tc.publicKV.put(".well-known/vault-version", CURRENT_VAULT_VERSION);
-                        await this.tc.publicKV.put(".well-known/vault-space", this.vaultConfig.spaceId);
-                    }
-                    catch {
-                        // 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),
-                });
-            }
-        });
-    }
-    /**
-     * Clear the cached vault signatures.
-     *
-     * @param spaceId - Clear only this space's master cache. If omitted, clears all.
-     */
-    async clearCache(spaceId) {
-        if (spaceId) {
-            await clearSignatureCache(`vault-master:${spaceId}`);
-        }
-        else {
-            await clearSignatureCache();
-        }
-    }
-    /**
-     * 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