@tinycloud/sdk-services 2.0.1 → 2.0.2

package/dist/index.js

@@ -1,61 +1,3139 @@
+// src/types.ts
+var ErrorCodes = {
+  // Common errors
+  NOT_FOUND: "NOT_FOUND",
+  AUTH_EXPIRED: "AUTH_EXPIRED",
+  AUTH_REQUIRED: "AUTH_REQUIRED",
+  AUTH_UNAUTHORIZED: "AUTH_UNAUTHORIZED",
+  NETWORK_ERROR: "NETWORK_ERROR",
+  TIMEOUT: "TIMEOUT",
+  ABORTED: "ABORTED",
+  INVALID_INPUT: "INVALID_INPUT",
+  PERMISSION_DENIED: "PERMISSION_DENIED",
+  // KV-specific errors
+  KV_NOT_FOUND: "KV_NOT_FOUND",
+  KV_WRITE_FAILED: "KV_WRITE_FAILED",
+  // SQL-specific errors
+  SQL_ERROR: "SQL_ERROR",
+  SQL_PERMISSION_DENIED: "SQL_PERMISSION_DENIED",
+  SQL_DATABASE_NOT_FOUND: "SQL_DATABASE_NOT_FOUND",
+  SQL_RESPONSE_TOO_LARGE: "SQL_RESPONSE_TOO_LARGE",
+  SQL_QUOTA_EXCEEDED: "SQL_QUOTA_EXCEEDED",
+  SQL_INVALID_STATEMENT: "SQL_INVALID_STATEMENT",
+  SQL_SCHEMA_ERROR: "SQL_SCHEMA_ERROR",
+  SQL_READONLY_VIOLATION: "SQL_READONLY_VIOLATION",
+  // Storage quota errors
+  STORAGE_QUOTA_EXCEEDED: "STORAGE_QUOTA_EXCEEDED",
+  STORAGE_LIMIT_REACHED: "STORAGE_LIMIT_REACHED",
+  // DuckDB-specific errors
+  DUCKDB_ERROR: "DUCKDB_ERROR",
+  DUCKDB_PERMISSION_DENIED: "DUCKDB_PERMISSION_DENIED",
+  DUCKDB_DATABASE_NOT_FOUND: "DUCKDB_DATABASE_NOT_FOUND",
+  DUCKDB_RESPONSE_TOO_LARGE: "DUCKDB_RESPONSE_TOO_LARGE",
+  DUCKDB_QUOTA_EXCEEDED: "DUCKDB_QUOTA_EXCEEDED",
+  DUCKDB_INVALID_STATEMENT: "DUCKDB_INVALID_STATEMENT",
+  DUCKDB_SCHEMA_ERROR: "DUCKDB_SCHEMA_ERROR",
+  DUCKDB_READONLY_VIOLATION: "DUCKDB_READONLY_VIOLATION"
+};
+var defaultRetryPolicy = {
+  maxAttempts: 3,
+  backoff: "exponential",
+  baseDelayMs: 1e3,
+  maxDelayMs: 1e4,
+  retryableErrors: [ErrorCodes.NETWORK_ERROR, ErrorCodes.TIMEOUT]
+};
+var TelemetryEvents = {
+  SERVICE_REQUEST: "service.request",
+  SERVICE_RESPONSE: "service.response",
+  SERVICE_ERROR: "service.error",
+  SERVICE_RETRY: "service.retry",
+  SESSION_CHANGED: "session.changed",
+  SESSION_EXPIRED: "session.expired"
+};
+function ok(data) {
+  return { ok: true, data };
+}
+function err(error) {
+  return { ok: false, error };
+}
+function serviceError(code, message, service, options) {
+  return {
+    code,
+    message,
+    service,
+    cause: options?.cause,
+    meta: options?.meta
+  };
+}
+
+// src/types.schema.ts
+import { z } from "zod";
+var ServiceErrorSchema = z.object({
+  /** Error code for programmatic handling (e.g., 'KV_NOT_FOUND', 'AUTH_EXPIRED') */
+  code: z.string(),
+  /** Human-readable error message */
+  message: z.string(),
+  /** Service that produced the error (e.g., 'kv', 'sql') */
+  service: z.string(),
+  /** Original error if this wraps another error - not validated since Error is a class */
+  cause: z.unknown().optional(),
+  /** Additional metadata about the error - passthrough allows any object properties */
+  meta: z.object({}).passthrough().optional()
+});
+function createResultSchema(dataSchema, errorSchema = ServiceErrorSchema) {
+  return z.discriminatedUnion("ok", [
+    z.object({
+      ok: z.literal(true),
+      data: dataSchema
+    }),
+    z.object({
+      ok: z.literal(false),
+      error: errorSchema
+    })
+  ]);
+}
+var GenericResultSchema = createResultSchema(z.unknown(), ServiceErrorSchema);
+var KVResponseHeadersSchema = z.object({
+  /** ETag for conditional requests */
+  etag: z.string().optional(),
+  /** Content type of the stored value */
+  contentType: z.string().optional(),
+  /** Last modification timestamp */
+  lastModified: z.string().optional(),
+  /** Content length in bytes */
+  contentLength: z.number().optional()
+});
+function createKVResponseSchema(dataSchema) {
+  return z.object({
+    /** The data payload */
+    data: dataSchema,
+    /** Response headers with metadata */
+    headers: KVResponseHeadersSchema
+  });
+}
+var GenericKVResponseSchema = createKVResponseSchema(z.unknown());
+var KVListResponseSchema = z.object({
+  /** Array of keys matching the list criteria */
+  keys: z.array(z.string())
+});
+var KVListResultSchema = createResultSchema(KVListResponseSchema);
+var ServiceRequestEventSchema = z.object({
+  service: z.string(),
+  action: z.string(),
+  key: z.string().optional(),
+  timestamp: z.number()
+});
+var ServiceResponseEventSchema = z.object({
+  service: z.string(),
+  action: z.string(),
+  ok: z.boolean(),
+  duration: z.number(),
+  status: z.number().optional()
+});
+var ServiceErrorEventSchema = z.object({
+  service: z.string(),
+  error: ServiceErrorSchema
+});
+var ServiceRetryEventSchema = z.object({
+  service: z.string(),
+  attempt: z.number().int().positive(),
+  maxAttempts: z.number().int().positive(),
+  error: ServiceErrorSchema
+});
+var RetryPolicySchema = z.object({
+  /** Maximum number of attempts (including initial) */
+  maxAttempts: z.number().int().positive(),
+  /** Backoff strategy between retries */
+  backoff: z.enum(["none", "linear", "exponential"]),
+  /** Base delay in milliseconds for backoff calculation */
+  baseDelayMs: z.number().nonnegative(),
+  /** Maximum delay in milliseconds between retries */
+  maxDelayMs: z.number().nonnegative(),
+  /** Error codes that should trigger a retry */
+  retryableErrors: z.array(z.string())
+});
+var ServiceSessionSchema = z.object({
+  /** The delegation header containing the UCAN */
+  delegationHeader: z.object({
+    Authorization: z.string()
+  }),
+  /** The delegation CID */
+  delegationCid: z.string(),
+  /** The space ID for this session */
+  spaceId: z.string(),
+  /** The verification method DID */
+  verificationMethod: z.string(),
+  /** The session key JWK (required for invoke) */
+  jwk: z.object({}).passthrough()
+});
+function validateServiceError(data) {
+  const result = ServiceErrorSchema.safeParse(data);
+  if (!result.success) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: result.error.message,
+        service: "validation",
+        meta: { issues: result.error.issues }
+      }
+    };
+  }
+  return { ok: true, data: result.data };
+}
+function validateKVListResponse(data) {
+  const result = KVListResponseSchema.safeParse(data);
+  if (!result.success) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: result.error.message,
+        service: "kv",
+        meta: { issues: result.error.issues }
+      }
+    };
+  }
+  return { ok: true, data: result.data };
+}
+function validateKVResponseHeaders(data) {
+  const result = KVResponseHeadersSchema.safeParse(data);
+  if (!result.success) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: result.error.message,
+        service: "kv",
+        meta: { issues: result.error.issues }
+      }
+    };
+  }
+  return { ok: true, data: result.data };
+}
+function validateServiceSession(data) {
+  const result = ServiceSessionSchema.safeParse(data);
+  if (!result.success) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: result.error.message,
+        service: "session",
+        meta: { issues: result.error.issues }
+      }
+    };
+  }
+  return { ok: true, data: result.data };
+}
+function validateRetryPolicy(data) {
+  const result = RetryPolicySchema.safeParse(data);
+  if (!result.success) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: result.error.message,
+        service: "config",
+        meta: { issues: result.error.issues }
+      }
+    };
+  }
+  return { ok: true, data: result.data };
+}
+function validateServiceRequestEvent(data) {
+  const result = ServiceRequestEventSchema.safeParse(data);
+  if (!result.success) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: result.error.message,
+        service: "telemetry",
+        meta: { issues: result.error.issues }
+      }
+    };
+  }
+  return { ok: true, data: result.data };
+}
+function validateServiceResponseEvent(data) {
+  const result = ServiceResponseEventSchema.safeParse(data);
+  if (!result.success) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: result.error.message,
+        service: "telemetry",
+        meta: { issues: result.error.issues }
+      }
+    };
+  }
+  return { ok: true, data: result.data };
+}
+
+// src/context.ts
+var ServiceContext = class {
+  constructor(config) {
+    this._session = null;
+    this._services = /* @__PURE__ */ new Map();
+    this._eventHandlers = /* @__PURE__ */ new Map();
+    this._abortController = new AbortController();
+    this._invoke = config.invoke;
+    this._fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this._hosts = config.hosts;
+    this._session = config.session ?? null;
+    this._retryPolicy = {
+      ...defaultRetryPolicy,
+      ...config.retryPolicy
+    };
+  }
+  // ============================================================
+  // Session Management
+  // ============================================================
+  /**
+   * Get the current session.
+   */
+  get session() {
+    return this._session;
+  }
+  /**
+   * Check if the context has an authenticated session.
+   */
+  get isAuthenticated() {
+    return this._session !== null;
+  }
+  /**
+   * Update the session and notify all registered services.
+   *
+   * @param session - New session or null to clear
+   */
+  setSession(session) {
+    this._session = session;
+    this.emit("session.changed", { authenticated: session !== null });
+    for (const service of this._services.values()) {
+      service.onSessionChange(session);
+    }
+  }
+  // ============================================================
+  // Platform Dependencies
+  // ============================================================
+  /**
+   * Get the invoke function for WASM operations.
+   */
+  get invoke() {
+    return this._invoke;
+  }
+  /**
+   * Get the fetch function for HTTP requests.
+   */
+  get fetch() {
+    return this._fetch;
+  }
+  /**
+   * Get the list of TinyCloud host URLs.
+   */
+  get hosts() {
+    return this._hosts;
+  }
+  // ============================================================
+  // Service Registry
+  // ============================================================
+  /**
+   * Register a service with the context.
+   *
+   * @param name - Service name (e.g., 'kv')
+   * @param service - Service instance
+   */
+  registerService(name, service) {
+    this._services.set(name, service);
+  }
+  /**
+   * Unregister a service from the context.
+   *
+   * @param name - Service name to remove
+   */
+  unregisterService(name) {
+    this._services.delete(name);
+  }
+  /**
+   * Get a registered service by name.
+   *
+   * @param name - Service name
+   * @returns The service instance or undefined if not registered
+   */
+  getService(name) {
+    return this._services.get(name);
+  }
+  // ============================================================
+  // Event System (Telemetry)
+  // ============================================================
+  /**
+   * Emit a telemetry event.
+   *
+   * @param event - Event name
+   * @param data - Event data
+   */
+  emit(event, data) {
+    const handlers = this._eventHandlers.get(event);
+    if (handlers) {
+      for (const handler of handlers) {
+        try {
+          handler(data);
+        } catch (error) {
+          console.error(`Error in event handler for "${event}":`, error);
+        }
+      }
+    }
+  }
+  /**
+   * Subscribe to telemetry events.
+   *
+   * @param event - Event name to subscribe to
+   * @param handler - Handler function
+   * @returns Unsubscribe function
+   */
+  on(event, handler) {
+    if (!this._eventHandlers.has(event)) {
+      this._eventHandlers.set(event, /* @__PURE__ */ new Set());
+    }
+    this._eventHandlers.get(event).add(handler);
+    return () => {
+      const handlers = this._eventHandlers.get(event);
+      if (handlers) {
+        handlers.delete(handler);
+        if (handlers.size === 0) {
+          this._eventHandlers.delete(event);
+        }
+      }
+    };
+  }
+  /**
+   * Remove all event handlers for an event.
+   *
+   * @param event - Event name (if omitted, clears all events)
+   */
+  clearEventHandlers(event) {
+    if (event) {
+      this._eventHandlers.delete(event);
+    } else {
+      this._eventHandlers.clear();
+    }
+  }
+  // ============================================================
+  // Lifecycle
+  // ============================================================
+  /**
+   * Get the abort signal for cancelling operations.
+   */
+  get abortSignal() {
+    return this._abortController.signal;
+  }
+  /**
+   * Abort all pending operations and notify services.
+   * Creates a new AbortController for future operations.
+   */
+  abort() {
+    this._abortController.abort();
+    this._abortController = new AbortController();
+    for (const service of this._services.values()) {
+      service.onSignOut();
+    }
+  }
+  /**
+   * Sign out - abort operations and clear session.
+   */
+  signOut() {
+    this.abort();
+    this.setSession(null);
+    this.emit("session.expired", {});
+  }
+  // ============================================================
+  // Retry Policy
+  // ============================================================
+  /**
+   * Get the retry policy configuration.
+   */
+  get retryPolicy() {
+    return this._retryPolicy;
+  }
+};
+
+// src/errors.ts
+function authRequiredError(service) {
+  return {
+    code: ErrorCodes.AUTH_REQUIRED,
+    message: "Authentication required. Please sign in first.",
+    service
+  };
+}
+function authExpiredError(service) {
+  return {
+    code: ErrorCodes.AUTH_EXPIRED,
+    message: "Session has expired. Please sign in again.",
+    service
+  };
+}
+function networkError(service, message, cause) {
+  return {
+    code: ErrorCodes.NETWORK_ERROR,
+    message,
+    service,
+    cause
+  };
+}
+function timeoutError(service) {
+  return {
+    code: ErrorCodes.TIMEOUT,
+    message: "Request timed out.",
+    service
+  };
+}
+function abortedError(service) {
+  return {
+    code: ErrorCodes.ABORTED,
+    message: "Request was aborted.",
+    service
+  };
+}
+function notFoundError(service, resource) {
+  return {
+    code: ErrorCodes.NOT_FOUND,
+    message: `Resource not found: ${resource}`,
+    service
+  };
+}
+function permissionDeniedError(service, action) {
+  return {
+    code: ErrorCodes.PERMISSION_DENIED,
+    message: `Permission denied for action: ${action}`,
+    service
+  };
+}
+function parseAuthError(responseText) {
+  const match = responseText.match(/^Unauthorized Action:\s*(.+?)\s*\/\s*(tinycloud\.\S+)$/m);
+  if (match) {
+    return { resource: match[1].trim(), action: match[2].trim() };
+  }
+  return {};
+}
+function authUnauthorizedError(service, message, meta) {
+  return serviceError(ErrorCodes.AUTH_UNAUTHORIZED, message, service, { meta });
+}
+function storageQuotaExceededError(service, message, meta) {
+  return {
+    code: ErrorCodes.STORAGE_QUOTA_EXCEEDED,
+    message,
+    service,
+    meta
+  };
+}
+function storageLimitReachedError(service, message, meta) {
+  return {
+    code: ErrorCodes.STORAGE_LIMIT_REACHED,
+    message,
+    service,
+    meta
+  };
+}
+function wrapError(service, error, defaultCode = ErrorCodes.NETWORK_ERROR) {
+  if (error instanceof Error) {
+    if (error.name === "AbortError") {
+      return abortedError(service);
+    }
+    if (error.name === "TimeoutError" || error.message.toLowerCase().includes("timeout")) {
+      return timeoutError(service);
+    }
+    return {
+      code: defaultCode,
+      message: error.message,
+      service,
+      cause: error
+    };
+  }
+  return {
+    code: defaultCode,
+    message: String(error),
+    service
+  };
+}
+function errorResult(error) {
+  return err(error);
+}
+
+// src/base/BaseService.ts
+var BaseService = class {
+  constructor() {
+    /**
+     * Abort controller for this service's operations.
+     * Reset on sign-out.
+     */
+    this.abortController = new AbortController();
+    /**
+     * Service-specific configuration.
+     */
+    this._config = {};
+  }
+  /**
+   * Get the service configuration.
+   */
+  get config() {
+    return this._config;
+  }
+  /**
+   * Initialize the service with context.
+   * Called by the SDK after instantiation.
+   *
+   * @param context - The service context
+   */
+  initialize(context) {
+    this.context = context;
+  }
+  /**
+   * Called when session changes (sign-in, sign-out, refresh).
+   * Override in subclasses to handle session changes.
+   *
+   * @param session - The new session, or null if signed out
+   */
+  onSessionChange(session) {
+  }
+  /**
+   * Called when SDK signs out.
+   * Aborts all pending operations.
+   */
+  onSignOut() {
+    this.abortController.abort();
+    this.abortController = new AbortController();
+  }
+  /**
+   * Get the abort signal for this service.
+   * Combines the service-level abort with context-level abort.
+   */
+  get abortSignal() {
+    return this.abortController.signal;
+  }
+  /**
+   * Check if the service is authenticated.
+   */
+  get isAuthenticated() {
+    return this.context?.isAuthenticated ?? false;
+  }
+  /**
+   * Get the current session.
+   * Throws if not authenticated.
+   */
+  get session() {
+    if (!this.context?.session) {
+      throw new Error("Not authenticated");
+    }
+    return this.context.session;
+  }
+  /**
+   * Check authentication and return error result if not authenticated.
+   * Use this at the start of methods that require authentication.
+   *
+   * @returns true if authenticated, false otherwise
+   */
+  requireAuth() {
+    return this.isAuthenticated;
+  }
+  /**
+   * Emit a telemetry event.
+   *
+   * @param event - Event name
+   * @param data - Event data
+   */
+  emit(event, data) {
+    this.context?.emit(event, data);
+  }
+  /**
+   * Emit a service request event.
+   *
+   * @param action - The action being performed
+   * @param key - Optional key/path being accessed
+   */
+  emitRequest(action, key) {
+    this.emit(TelemetryEvents.SERVICE_REQUEST, {
+      service: this.getServiceName(),
+      action,
+      key,
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Emit a service response event.
+   *
+   * @param action - The action that was performed
+   * @param ok - Whether the request was successful
+   * @param startTime - Start time for duration calculation
+   * @param status - Optional HTTP status code
+   */
+  emitResponse(action, ok2, startTime, status) {
+    this.emit(TelemetryEvents.SERVICE_RESPONSE, {
+      service: this.getServiceName(),
+      action,
+      ok: ok2,
+      duration: Date.now() - startTime,
+      status
+    });
+  }
+  /**
+   * Emit a service error event.
+   *
+   * @param error - The service error
+   */
+  emitError(error) {
+    this.emit(TelemetryEvents.SERVICE_ERROR, {
+      service: this.getServiceName(),
+      error
+    });
+  }
+  /**
+   * Get the service name from the static property.
+   * Subclasses must define static serviceName.
+   */
+  getServiceName() {
+    return this.constructor.serviceName;
+  }
+  /**
+   * Create a combined abort signal from multiple sources.
+   *
+   * @param signals - Additional abort signals to combine
+   * @returns A combined abort signal
+   */
+  combineSignals(...signals) {
+    const controller = new AbortController();
+    const allSignals = [this.abortSignal, ...signals.filter(Boolean)];
+    for (const signal of allSignals) {
+      if (signal.aborted) {
+        controller.abort(signal.reason);
+        return controller.signal;
+      }
+      signal.addEventListener("abort", () => controller.abort(signal.reason), {
+        once: true
+      });
+    }
+    return controller.signal;
+  }
+  /**
+   * Wrap an operation with error handling and telemetry.
+   *
+   * @param action - The action name for telemetry
+   * @param key - Optional key for telemetry
+   * @param operation - The operation to execute
+   * @returns Result of the operation
+   */
+  async withTelemetry(action, key, operation) {
+    const startTime = Date.now();
+    this.emitRequest(action, key);
+    try {
+      const result = await operation();
+      if (result.ok) {
+        this.emitResponse(action, true, startTime);
+      } else {
+        this.emitResponse(action, false, startTime);
+        this.emitError(result.error);
+      }
+      return result;
+    } catch (error) {
+      const serviceError3 = wrapError(this.getServiceName(), error);
+      this.emitResponse(action, false, startTime);
+      this.emitError(serviceError3);
+      return err(serviceError3);
+    }
+  }
+};
+
+// src/kv/PrefixedKVService.ts
+var PrefixedKVService = class _PrefixedKVService {
+  /**
+   * Create a new PrefixedKVService.
+   *
+   * @param kv - The underlying KV service to delegate to
+   * @param prefix - The prefix to apply to all operations
+   */
+  constructor(kv, prefix) {
+    this._kv = kv;
+    this._prefix = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+  }
+  /**
+   * The current prefix for this scoped view.
+   */
+  get prefix() {
+    return this._prefix;
+  }
+  /**
+   * Compute the full key path by combining prefix and key.
+   *
+   * @param key - The key to prefix
+   * @returns The full path including prefix
+   */
+  getFullKey(key) {
+    const normalizedKey = key.startsWith("/") ? key : `/${key}`;
+    return `${this._prefix}${normalizedKey}`;
+  }
+  /**
+   * Get a value by key.
+   */
+  async get(key, options) {
+    const fullKey = this.getFullKey(key);
+    return this._kv.get(fullKey, { ...options, prefix: "" });
+  }
+  /**
+   * Store a value at a key.
+   */
+  async put(key, value, options) {
+    const fullKey = this.getFullKey(key);
+    return this._kv.put(fullKey, value, { ...options, prefix: "" });
+  }
+  /**
+   * List keys within this prefix.
+   */
+  async list(options) {
+    const removePrefix = options?.removePrefix ?? true;
+    return this._kv.list({
+      ...options,
+      prefix: this._prefix,
+      removePrefix
+    });
+  }
+  /**
+   * Delete a key.
+   */
+  async delete(key, options) {
+    const fullKey = this.getFullKey(key);
+    return this._kv.delete(fullKey, { ...options, prefix: "" });
+  }
+  /**
+   * Get metadata for a key without retrieving the value.
+   */
+  async head(key, options) {
+    const fullKey = this.getFullKey(key);
+    return this._kv.head(fullKey, { ...options, prefix: "" });
+  }
+  /**
+   * Create a nested prefix-scoped view.
+   */
+  withPrefix(subPrefix) {
+    const normalizedSubPrefix = subPrefix.startsWith("/") ? subPrefix : `/${subPrefix}`;
+    const combinedPrefix = `${this._prefix}${normalizedSubPrefix}`;
+    return new _PrefixedKVService(this._kv, combinedPrefix);
+  }
+};
+
+// src/kv/types.ts
+var KVAction = {
+  GET: "tinycloud.kv/get",
+  PUT: "tinycloud.kv/put",
+  LIST: "tinycloud.kv/list",
+  DELETE: "tinycloud.kv/del",
+  HEAD: "tinycloud.kv/metadata"
+};
+
+// src/kv/KVService.ts
+var KVService = class extends BaseService {
+  /**
+   * Create a new KVService instance.
+   *
+   * @param config - Service configuration
+   */
+  constructor(config = {}) {
+    super();
+    this._config = config;
+  }
+  /**
+   * Get the service configuration.
+   */
+  get config() {
+    return this._config;
+  }
+  // Parses "Used: X bytes, Limit: Y bytes" from tinycloud-node error responses
+  parseQuotaInfo(errorText) {
+    const match = errorText.match(
+      /Used:\s*(\d+)\s*bytes,\s*Limit:\s*(\d+)\s*bytes/i
+    );
+    if (match) {
+      return {
+        usedBytes: parseInt(match[1], 10),
+        limitBytes: parseInt(match[2], 10)
+      };
+    }
+    return void 0;
+  }
+  handleQuotaErrorResponse(response, errorText, key) {
+    if (response.status === 402) {
+      const quotaInfo = this.parseQuotaInfo(errorText);
+      return err(
+        storageQuotaExceededError(
+          "kv",
+          `Storage quota exceeded for key "${key}": ${errorText}`,
+          {
+            status: response.status,
+            ...quotaInfo ? { usedBytes: quotaInfo.usedBytes, limitBytes: quotaInfo.limitBytes } : {}
+          }
+        )
+      );
+    }
+    if (response.status === 413) {
+      const quotaInfo = this.parseQuotaInfo(errorText);
+      return err(
+        storageLimitReachedError(
+          "kv",
+          `Storage limit reached for key "${key}": ${errorText}`,
+          {
+            status: response.status,
+            ...quotaInfo ? { usedBytes: quotaInfo.usedBytes, limitBytes: quotaInfo.limitBytes } : {}
+          }
+        )
+      );
+    }
+    return void 0;
+  }
+  /**
+   * Get the full path with optional prefix.
+   *
+   * @param key - The key
+   * @param prefixOverride - Optional prefix override
+   * @returns The full path
+   */
+  getFullPath(key, prefixOverride) {
+    const prefix = prefixOverride ?? this._config.prefix ?? "";
+    return prefix ? `${prefix}/${key}` : key;
+  }
+  /**
+   * Get the host URL.
+   */
+  get host() {
+    return this.context.hosts[0];
+  }
+  /**
+   * Execute an invoke operation.
+   *
+   * @param path - Resource path
+   * @param action - KV action
+   * @param body - Optional request body
+   * @param signal - Optional abort signal
+   * @returns Fetch response
+   */
+  async invokeOperation(path, action, body, signal) {
+    const session = this.context.session;
+    const headers = this.context.invoke(
+      session,
+      "kv",
+      path,
+      action
+    );
+    return this.context.fetch(`${this.host}/invoke`, {
+      method: "POST",
+      headers,
+      body,
+      signal: this.combineSignals(signal)
+    });
+  }
+  /**
+   * Create KVResponseHeaders from fetch response headers.
+   *
+   * @param headers - Fetch response headers
+   * @returns KVResponseHeaders object
+   */
+  createResponseHeaders(headers) {
+    return {
+      etag: headers.get("etag") ?? void 0,
+      contentType: headers.get("content-type") ?? void 0,
+      lastModified: headers.get("last-modified") ?? void 0,
+      contentLength: headers.get("content-length") ? parseInt(headers.get("content-length"), 10) : void 0,
+      get: (name) => headers.get(name)
+    };
+  }
+  /**
+   * Parse response body based on content type.
+   *
+   * @param response - Fetch response
+   * @param raw - Whether to return raw text
+   * @returns Parsed data
+   */
+  async parseResponse(response, raw = false) {
+    if (!response.ok) {
+      return void 0;
+    }
+    if (raw) {
+      return await response.text();
+    }
+    const contentType = response.headers.get("content-type");
+    if (contentType?.includes("application/json")) {
+      return await response.json();
+    } else if (contentType?.startsWith("text/")) {
+      return await response.text();
+    }
+    const text = await response.text();
+    if (!text) {
+      return void 0;
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  /**
+   * Get a value by key.
+   */
+  async get(key, options) {
+    return this.withTelemetry("get", key, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("kv"));
+      }
+      const path = this.getFullPath(key, options?.prefix);
+      try {
+        const response = await this.invokeOperation(
+          path,
+          KVAction.GET,
+          void 0,
+          options?.signal
+        );
+        if (!response.ok) {
+          if (response.status === 401) {
+            const errorText2 = await response.text();
+            const { resource, action } = parseAuthError(errorText2);
+            return err(authUnauthorizedError("kv", errorText2, {
+              status: response.status,
+              ...action && { requiredAction: action },
+              ...resource && { resource }
+            }));
+          }
+          if (response.status === 404) {
+            return err(
+              serviceError(
+                ErrorCodes.KV_NOT_FOUND,
+                `Key not found: ${key}`,
+                "kv"
+              )
+            );
+          }
+          const errorText = await response.text();
+          return err(
+            serviceError(
+              ErrorCodes.NETWORK_ERROR,
+              `Failed to get key "${key}": ${response.status} - ${errorText}`,
+              "kv",
+              { meta: { status: response.status, statusText: response.statusText } }
+            )
+          );
+        }
+        const data = await this.parseResponse(response, options?.raw);
+        return ok({
+          data,
+          headers: this.createResponseHeaders(response.headers)
+        });
+      } catch (error) {
+        return err(wrapError("kv", error));
+      }
+    });
+  }
+  /**
+   * Store a value at a key.
+   */
+  async put(key, value, options) {
+    return this.withTelemetry("put", key, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("kv"));
+      }
+      const path = this.getFullPath(key, options?.prefix);
+      let body;
+      if (typeof value === "string") {
+        body = value;
+      } else {
+        body = JSON.stringify(value);
+      }
+      try {
+        const response = await this.invokeOperation(
+          path,
+          KVAction.PUT,
+          body,
+          options?.signal
+        );
+        if (!response.ok) {
+          if (response.status === 401) {
+            const errorText2 = await response.text();
+            const { resource, action } = parseAuthError(errorText2);
+            return err(authUnauthorizedError("kv", errorText2, {
+              status: response.status,
+              ...action && { requiredAction: action },
+              ...resource && { resource }
+            }));
+          }
+          const errorText = await response.text();
+          const quotaError = this.handleQuotaErrorResponse(
+            response,
+            errorText,
+            key
+          );
+          if (quotaError) {
+            return quotaError;
+          }
+          return err(
+            serviceError(
+              ErrorCodes.KV_WRITE_FAILED,
+              `Failed to put key "${key}": ${response.status} - ${errorText}`,
+              "kv",
+              { meta: { status: response.status, statusText: response.statusText } }
+            )
+          );
+        }
+        return ok({
+          data: void 0,
+          headers: this.createResponseHeaders(response.headers)
+        });
+      } catch (error) {
+        return err(wrapError("kv", error));
+      }
+    });
+  }
+  /**
+   * List keys with optional prefix filtering.
+   */
+  async list(options) {
+    return this.withTelemetry("list", options?.prefix, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("kv"));
+      }
+      let listPath = options?.prefix ?? this._config.prefix ?? "";
+      if (options?.path) {
+        listPath = listPath ? `${listPath}/${options.path}` : options.path;
+      }
+      try {
+        const response = await this.invokeOperation(
+          listPath,
+          KVAction.LIST,
+          void 0,
+          options?.signal
+        );
+        if (!response.ok) {
+          if (response.status === 401) {
+            const errorText2 = await response.text();
+            const { resource, action } = parseAuthError(errorText2);
+            return err(authUnauthorizedError("kv", errorText2, {
+              status: response.status,
+              ...action && { requiredAction: action },
+              ...resource && { resource }
+            }));
+          }
+          const errorText = await response.text();
+          return err(
+            serviceError(
+              ErrorCodes.NETWORK_ERROR,
+              `Failed to list keys: ${response.status} - ${errorText}`,
+              "kv",
+              { meta: { status: response.status, statusText: response.statusText } }
+            )
+          );
+        }
+        let keys = await this.parseResponse(response, options?.raw);
+        keys = keys ?? [];
+        if (options?.removePrefix && listPath) {
+          const prefixWithSlash = listPath.endsWith("/") ? listPath : `${listPath}/`;
+          keys = keys.map(
+            (key) => key.startsWith(prefixWithSlash) ? key.slice(prefixWithSlash.length) : key
+          );
+        }
+        return ok({ keys });
+      } catch (error) {
+        return err(wrapError("kv", error));
+      }
+    });
+  }
+  /**
+   * Delete a key.
+   */
+  async delete(key, options) {
+    return this.withTelemetry("delete", key, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("kv"));
+      }
+      const path = this.getFullPath(key, options?.prefix);
+      try {
+        const response = await this.invokeOperation(
+          path,
+          KVAction.DELETE,
+          void 0,
+          options?.signal
+        );
+        if (!response.ok) {
+          if (response.status === 401) {
+            const errorText2 = await response.text();
+            const { resource, action } = parseAuthError(errorText2);
+            return err(authUnauthorizedError("kv", errorText2, {
+              status: response.status,
+              ...action && { requiredAction: action },
+              ...resource && { resource }
+            }));
+          }
+          if (response.status === 404) {
+            return err(
+              serviceError(
+                ErrorCodes.KV_NOT_FOUND,
+                `Key not found: ${key}`,
+                "kv"
+              )
+            );
+          }
+          const errorText = await response.text();
+          return err(
+            serviceError(
+              ErrorCodes.NETWORK_ERROR,
+              `Failed to delete key "${key}": ${response.status} - ${errorText}`,
+              "kv",
+              { meta: { status: response.status, statusText: response.statusText } }
+            )
+          );
+        }
+        return ok(void 0);
+      } catch (error) {
+        return err(wrapError("kv", error));
+      }
+    });
+  }
+  /**
+   * Get metadata for a key without retrieving the value.
+   */
+  async head(key, options) {
+    return this.withTelemetry("head", key, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("kv"));
+      }
+      const path = this.getFullPath(key, options?.prefix);
+      try {
+        const response = await this.invokeOperation(
+          path,
+          KVAction.HEAD,
+          void 0,
+          options?.signal
+        );
+        if (!response.ok) {
+          if (response.status === 401) {
+            const errorText2 = await response.text();
+            const { resource, action } = parseAuthError(errorText2);
+            return err(authUnauthorizedError("kv", errorText2, {
+              status: response.status,
+              ...action && { requiredAction: action },
+              ...resource && { resource }
+            }));
+          }
+          if (response.status === 404) {
+            return err(
+              serviceError(
+                ErrorCodes.KV_NOT_FOUND,
+                `Key not found: ${key}`,
+                "kv"
+              )
+            );
+          }
+          const errorText = await response.text();
+          return err(
+            serviceError(
+              ErrorCodes.NETWORK_ERROR,
+              `Failed to get metadata for key "${key}": ${response.status} - ${errorText}`,
+              "kv",
+              { meta: { status: response.status, statusText: response.statusText } }
+            )
+          );
+        }
+        return ok({
+          data: void 0,
+          headers: this.createResponseHeaders(response.headers)
+        });
+      } catch (error) {
+        return err(wrapError("kv", error));
+      }
+    });
+  }
+  /**
+   * Create a prefix-scoped view of this KV service.
+   *
+   * Returns a PrefixedKVService that automatically prefixes all
+   * key operations with the specified prefix. This enables apps
+   * to isolate their data within a shared space.
+   *
+   * @param prefix - The prefix to apply to all operations
+   * @returns A PrefixedKVService scoped to the prefix
+   *
+   * ## Prefix Conventions
+   *
+   * | Pattern | Use Case | Example |
+   * | -- | -- | -- |
+   * | `/app.{domain}/` | App-private data | `/app.photos.xyz/settings.json` |
+   * | `/{type}/` | Shared data type | `/photos/vacation.jpg` |
+   * | `/.{name}/` | Hidden/system data | `/.cache/thumbnails/` |
+   * | `/public/` | Explicitly shareable | `/public/profile.json` |
+   *
+   * @example
+   * ```typescript
+   * const space = sdk.space('default');
+   *
+   * // Create prefix-scoped views
+   * const myApp = space.kv.withPrefix('/app.myapp.com');
+   * const sharedPhotos = space.kv.withPrefix('/photos');
+   *
+   * // Operations are automatically prefixed
+   * await myApp.put('settings.json', { theme: 'dark' });
+   * // -> Actually writes to: /app.myapp.com/settings.json
+   *
+   * await myApp.get('settings.json');
+   * // -> Actually reads from: /app.myapp.com/settings.json
+   *
+   * await sharedPhotos.list();
+   * // -> Lists: /photos/*
+   *
+   * // Nested prefixes
+   * const settings = myApp.withPrefix('/settings');
+   * await settings.get('theme.json');  // -> /app.myapp.com/settings/theme.json
+   * ```
+   */
+  withPrefix(prefix) {
+    return new PrefixedKVService(this, prefix);
+  }
+};
 /**
- * TinyCloud SDK Services
- *
- * Platform-agnostic services with plugin architecture for TinyCloud.
- *
- * @packageDocumentation
- * @module @tinycloud/sdk-services
- *
- * @example
- * ```typescript
- * import {
- *   ServiceContext,
- *   BaseService,
- *   Result,
- *   ErrorCodes,
- * } from '@tinycloud/sdk-services';
- *
- * // Create a context
- * const context = new ServiceContext({
- *   invoke: wasmInvoke,
- *   hosts: ['https://node.tinycloud.xyz'],
- * });
- *
- * // Create and register a service
- * const kv = new KVService({ prefix: 'myapp' });
- * context.registerService('kv', kv);
- * kv.initialize(context);
- *
- * // Use the service
- * const result = await kv.get('key');
- * if (result.ok) {
- *   console.log(result.data);
- * }
- * ```
+ * Service identifier for registration.
  */
-export { ErrorCodes, defaultRetryPolicy, TelemetryEvents, ok, err, serviceError, } from "./types";
-// Zod schemas and validation
-export { 
-// Schemas
-ServiceErrorSchema, KVResponseHeadersSchema, KVListResponseSchema, ServiceRequestEventSchema, ServiceResponseEventSchema, ServiceErrorEventSchema, ServiceRetryEventSchema, RetryPolicySchema, ServiceSessionSchema, GenericResultSchema, GenericKVResponseSchema, KVListResultSchema, 
-// Schema factories
-createResultSchema, createKVResponseSchema, 
-// Validation functions
-validateServiceError, validateKVListResponse, validateKVResponseHeaders, validateServiceSession, validateRetryPolicy, validateServiceRequestEvent, validateServiceResponseEvent, } from "./types.schema";
-// Context
-export { ServiceContext } from "./context";
-// Errors
-export { authRequiredError, authExpiredError, networkError, timeoutError, abortedError, notFoundError, permissionDeniedError, wrapError, errorResult, storageQuotaExceededError, storageLimitReachedError, parseAuthError, authUnauthorizedError, } from "./errors";
-// Base service
-export { BaseService } from "./base/index";
-// KV service
-export { KVService, PrefixedKVService, KVAction } from "./kv";
-// SQL service
-export { SQLService, DatabaseHandle, SQLAction } from "./sql";
-// DuckDB service
-export { DuckDbService, DuckDbDatabaseHandle, DuckDbAction } from "./duckdb";
-// Quota
-export { TinyCloudQuota } from "./quota";
-// Vault service
-export { DataVaultService, VaultHeaders, VaultPublicSpaceKVActions, createVaultCrypto } from "./vault";
+KVService.serviceName = "kv";
+
+// src/sql/DatabaseHandle.ts
+var DatabaseHandle = class {
+  constructor(service, name) {
+    this.service = service;
+    this.name = name;
+  }
+  async query(sql, params, options) {
+    return this.service.queryOnDb(this.name, sql, params, options);
+  }
+  async execute(sql, params, options) {
+    return this.service.executeOnDb(this.name, sql, params, options);
+  }
+  async batch(statements, options) {
+    return this.service.batchOnDb(this.name, statements, options);
+  }
+  async executeStatement(name, params, options) {
+    return this.service.executeStatementOnDb(this.name, name, params, options);
+  }
+  async export(options) {
+    return this.service.exportDb(this.name, options);
+  }
+};
+
+// src/sql/types.ts
+var SQLAction = {
+  READ: "tinycloud.sql/read",
+  WRITE: "tinycloud.sql/write",
+  ADMIN: "tinycloud.sql/admin",
+  SELECT: "tinycloud.sql/select",
+  INSERT: "tinycloud.sql/insert",
+  UPDATE: "tinycloud.sql/update",
+  DELETE: "tinycloud.sql/delete",
+  EXECUTE: "tinycloud.sql/execute",
+  EXPORT: "tinycloud.sql/export",
+  ALL: "tinycloud.sql/*"
+};
+
+// src/sql/SQLService.ts
+var SQLService = class extends BaseService {
+  constructor(config = {}) {
+    super();
+    this._config = config;
+  }
+  get config() {
+    return this._config;
+  }
+  get defaultDbName() {
+    return this._config.defaultDatabase ?? "default";
+  }
+  get host() {
+    return this.context.hosts[0];
+  }
+  /**
+   * Get a handle to a named database.
+   */
+  db(name) {
+    return new DatabaseHandle(this, name ?? this.defaultDbName);
+  }
+  /**
+   * Shortcut: query the default database.
+   */
+  async query(sql, params, options) {
+    return this.queryOnDb(this.defaultDbName, sql, params, options);
+  }
+  /**
+   * Shortcut: execute on the default database.
+   */
+  async execute(sql, params, options) {
+    return this.executeOnDb(this.defaultDbName, sql, params, options);
+  }
+  /**
+   * Shortcut: batch on the default database.
+   */
+  async batch(statements, options) {
+    return this.batchOnDb(this.defaultDbName, statements, options);
+  }
+  // === Internal methods called by DatabaseHandle ===
+  async queryOnDb(dbName, sql, params, options) {
+    return this.withTelemetry("query", dbName, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("sql"));
+      }
+      try {
+        const response = await this.invokeSQL(
+          dbName,
+          SQLAction.READ,
+          { action: "query", sql, params: params ?? [] },
+          options?.signal
+        );
+        if (!response.ok) {
+          return this.handleErrorResponse(response, "query");
+        }
+        const data = await response.json();
+        return ok(data);
+      } catch (error) {
+        return err(wrapError("sql", error));
+      }
+    });
+  }
+  async executeOnDb(dbName, sql, params, options) {
+    return this.withTelemetry("execute", dbName, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("sql"));
+      }
+      try {
+        const body = {
+          action: "execute",
+          sql,
+          params: params ?? []
+        };
+        if (options?.schema) {
+          body.schema = options.schema;
+        }
+        const response = await this.invokeSQL(
+          dbName,
+          SQLAction.WRITE,
+          body,
+          options?.signal
+        );
+        if (!response.ok) {
+          return this.handleErrorResponse(response, "execute");
+        }
+        const data = await response.json();
+        return ok(data);
+      } catch (error) {
+        return err(wrapError("sql", error));
+      }
+    });
+  }
+  async batchOnDb(dbName, statements, options) {
+    return this.withTelemetry("batch", dbName, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("sql"));
+      }
+      try {
+        const response = await this.invokeSQL(
+          dbName,
+          SQLAction.WRITE,
+          { action: "batch", statements },
+          options?.signal
+        );
+        if (!response.ok) {
+          return this.handleErrorResponse(response, "batch");
+        }
+        const data = await response.json();
+        return ok(data);
+      } catch (error) {
+        return err(wrapError("sql", error));
+      }
+    });
+  }
+  async executeStatementOnDb(dbName, name, params, options) {
+    return this.withTelemetry("executeStatement", dbName, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("sql"));
+      }
+      try {
+        const response = await this.invokeSQL(
+          dbName,
+          SQLAction.EXECUTE,
+          { action: "execute_statement", name, params: params ?? [] },
+          options?.signal
+        );
+        if (!response.ok) {
+          return this.handleErrorResponse(response, "executeStatement");
+        }
+        const data = await response.json();
+        return ok(data);
+      } catch (error) {
+        return err(wrapError("sql", error));
+      }
+    });
+  }
+  async exportDb(dbName, options) {
+    return this.withTelemetry("export", dbName, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("sql"));
+      }
+      try {
+        const response = await this.invokeSQL(
+          dbName,
+          SQLAction.EXPORT,
+          { action: "export" },
+          options?.signal
+        );
+        if (!response.ok) {
+          return this.handleErrorResponse(response, "export");
+        }
+        const resp = response;
+        if (typeof resp.blob === "function") {
+          const blob = await resp.blob();
+          return ok(blob);
+        }
+        const text = await response.text();
+        return ok(text);
+      } catch (error) {
+        return err(wrapError("sql", error));
+      }
+    });
+  }
+  // === Private helpers ===
+  async invokeSQL(dbName, action, body, signal) {
+    const session = this.context.session;
+    const headers = this.context.invoke(session, "sql", dbName, action);
+    return this.context.fetch(`${this.host}/invoke`, {
+      method: "POST",
+      headers: {
+        ...headers,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body),
+      signal: this.combineSignals(signal)
+    });
+  }
+  async handleErrorResponse(response, operation) {
+    const errorText = await response.text();
+    let errorBody = {};
+    try {
+      errorBody = JSON.parse(errorText);
+    } catch {
+    }
+    const errorCode = this.mapHttpStatusToErrorCode(
+      response.status,
+      errorBody.error
+    );
+    const message = errorBody.message || `SQL ${operation} failed: ${response.status} - ${errorText}`;
+    const meta = { status: response.status, statusText: response.statusText };
+    if (response.status === 401) {
+      const { resource, action } = parseAuthError(errorText);
+      if (action) meta.requiredAction = action;
+      if (resource) meta.resource = resource;
+    }
+    return err(
+      serviceError(errorCode, message, "sql", { meta })
+    );
+  }
+  mapHttpStatusToErrorCode(status, serverError) {
+    switch (status) {
+      case 400:
+        return ErrorCodes.SQL_ERROR;
+      case 401:
+        return ErrorCodes.AUTH_UNAUTHORIZED;
+      case 403:
+        if (serverError === "sql_readonly_violation") {
+          return ErrorCodes.SQL_READONLY_VIOLATION;
+        }
+        return ErrorCodes.SQL_PERMISSION_DENIED;
+      case 404:
+        return ErrorCodes.SQL_DATABASE_NOT_FOUND;
+      case 413:
+        return ErrorCodes.SQL_RESPONSE_TOO_LARGE;
+      case 429:
+        return ErrorCodes.SQL_QUOTA_EXCEEDED;
+      default:
+        return ErrorCodes.NETWORK_ERROR;
+    }
+  }
+};
+SQLService.serviceName = "sql";
+
+// src/duckdb/DuckDbDatabaseHandle.ts
+var DuckDbDatabaseHandle = class {
+  constructor(service, name) {
+    this.service = service;
+    this.name = name;
+  }
+  async query(sql, params, options) {
+    return this.service.queryOnDb(this.name, sql, params, options);
+  }
+  async queryArrow(sql, params, options) {
+    return this.service.queryArrowOnDb(this.name, sql, params, options);
+  }
+  async execute(sql, params, options) {
+    return this.service.executeOnDb(this.name, sql, params, options);
+  }
+  async batch(statements, options) {
+    return this.service.batchOnDb(this.name, statements, options);
+  }
+  async executeStatement(name, params, options) {
+    return this.service.executeStatementOnDb(this.name, name, params, options);
+  }
+  async describe(options) {
+    return this.service.describeDb(this.name, options);
+  }
+  async export(options) {
+    return this.service.exportOnDb(this.name, options);
+  }
+  async import(data, options) {
+    return this.service.importOnDb(this.name, data, options);
+  }
+};
+
+// src/duckdb/types.ts
+var DuckDbAction = {
+  READ: "tinycloud.duckdb/read",
+  WRITE: "tinycloud.duckdb/write",
+  ADMIN: "tinycloud.duckdb/admin",
+  DESCRIBE: "tinycloud.duckdb/describe",
+  EXPORT: "tinycloud.duckdb/export",
+  IMPORT: "tinycloud.duckdb/import",
+  EXECUTE: "tinycloud.duckdb/execute",
+  ALL: "tinycloud.duckdb/*"
+};
+
+// src/duckdb/DuckDbService.ts
+var DuckDbService = class extends BaseService {
+  constructor(config = {}) {
+    super();
+    this._config = config;
+  }
+  get config() {
+    return this._config;
+  }
+  get defaultDbName() {
+    return this._config.defaultDatabase ?? "default";
+  }
+  get host() {
+    return this.context.hosts[0];
+  }
+  /**
+   * Get a handle to a named database.
+   */
+  db(name) {
+    return new DuckDbDatabaseHandle(this, name ?? this.defaultDbName);
+  }
+  /**
+   * Shortcut: query the default database (JSON format).
+   */
+  async query(sql, params, options) {
+    return this.queryOnDb(this.defaultDbName, sql, params, options);
+  }
+  /**
+   * Shortcut: query the default database (Arrow IPC format).
+   */
+  async queryArrow(sql, params, options) {
+    return this.queryArrowOnDb(this.defaultDbName, sql, params, options);
+  }
+  /**
+   * Shortcut: execute on the default database.
+   */
+  async execute(sql, params, options) {
+    return this.executeOnDb(this.defaultDbName, sql, params, options);
+  }
+  /**
+   * Shortcut: batch on the default database.
+   */
+  async batch(statements, options) {
+    return this.batchOnDb(this.defaultDbName, statements, options);
+  }
+  // === Internal methods called by DuckDbDatabaseHandle ===
+  async queryOnDb(dbName, sql, params, options) {
+    return this.withTelemetry("query", dbName, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("duckdb"));
+      }
+      try {
+        const response = await this.invokeDuckDb(
+          dbName,
+          DuckDbAction.READ,
+          { action: "query", sql, params: params ?? [] },
+          options?.signal
+        );
+        if (!response.ok) {
+          return this.handleErrorResponse(response, "query");
+        }
+        const data = await response.json();
+        return ok(data);
+      } catch (error) {
+        return err(wrapError("duckdb", error));
+      }
+    });
+  }
+  async queryArrowOnDb(dbName, sql, params, options) {
+    return this.withTelemetry("queryArrow", dbName, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("duckdb"));
+      }
+      try {
+        const response = await this.invokeDuckDb(
+          dbName,
+          DuckDbAction.READ,
+          { action: "query", sql, params: params ?? [] },
+          options?.signal,
+          { Accept: "application/vnd.apache.arrow.stream" }
+        );
+        if (!response.ok) {
+          return this.handleErrorResponse(response, "queryArrow");
+        }
+        const buffer = await response.arrayBuffer();
+        return ok(buffer);
+      } catch (error) {
+        return err(wrapError("duckdb", error));
+      }
+    });
+  }
+  async executeOnDb(dbName, sql, params, options) {
+    return this.withTelemetry("execute", dbName, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("duckdb"));
+      }
+      try {
+        const body = {
+          action: "execute",
+          sql,
+          params: params ?? []
+        };
+        if (options?.schema) {
+          body.schema = options.schema;
+        }
+        const response = await this.invokeDuckDb(
+          dbName,
+          DuckDbAction.WRITE,
+          body,
+          options?.signal
+        );
+        if (!response.ok) {
+          return this.handleErrorResponse(response, "execute");
+        }
+        const data = await response.json();
+        return ok(data);
+      } catch (error) {
+        return err(wrapError("duckdb", error));
+      }
+    });
+  }
+  async batchOnDb(dbName, statements, options) {
+    return this.withTelemetry("batch", dbName, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("duckdb"));
+      }
+      try {
+        const body = {
+          action: "batch",
+          statements
+        };
+        if (options?.transactional !== void 0) {
+          body.transactional = options.transactional;
+        }
+        const response = await this.invokeDuckDb(
+          dbName,
+          DuckDbAction.WRITE,
+          body,
+          options?.signal
+        );
+        if (!response.ok) {
+          return this.handleErrorResponse(response, "batch");
+        }
+        const data = await response.json();
+        return ok(data);
+      } catch (error) {
+        return err(wrapError("duckdb", error));
+      }
+    });
+  }
+  async executeStatementOnDb(dbName, name, params, options) {
+    return this.withTelemetry("executeStatement", dbName, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("duckdb"));
+      }
+      try {
+        const response = await this.invokeDuckDb(
+          dbName,
+          DuckDbAction.EXECUTE,
+          { action: "executeStatement", name, params: params ?? [] },
+          options?.signal
+        );
+        if (!response.ok) {
+          return this.handleErrorResponse(response, "executeStatement");
+        }
+        const data = await response.json();
+        return ok(data);
+      } catch (error) {
+        return err(wrapError("duckdb", error));
+      }
+    });
+  }
+  async describeDb(dbName, options) {
+    return this.withTelemetry("describe", dbName, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("duckdb"));
+      }
+      try {
+        const response = await this.invokeDuckDb(
+          dbName,
+          DuckDbAction.DESCRIBE,
+          { action: "describe" },
+          options?.signal
+        );
+        if (!response.ok) {
+          return this.handleErrorResponse(response, "describe");
+        }
+        const data = await response.json();
+        return ok(data);
+      } catch (error) {
+        return err(wrapError("duckdb", error));
+      }
+    });
+  }
+  async exportOnDb(dbName, options) {
+    return this.withTelemetry("export", dbName, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("duckdb"));
+      }
+      try {
+        const response = await this.invokeDuckDb(
+          dbName,
+          DuckDbAction.EXPORT,
+          { action: "export" },
+          options?.signal
+        );
+        if (!response.ok) {
+          return this.handleErrorResponse(response, "export");
+        }
+        const blob = await response.blob();
+        return ok(blob);
+      } catch (error) {
+        return err(wrapError("duckdb", error));
+      }
+    });
+  }
+  async importOnDb(dbName, data, options) {
+    return this.withTelemetry("import", dbName, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("duckdb"));
+      }
+      try {
+        const session = this.context.session;
+        const headers = this.context.invoke(
+          session,
+          "duckdb",
+          dbName,
+          DuckDbAction.IMPORT
+        );
+        const response = await this.context.fetch(`${this.host}/invoke`, {
+          method: "POST",
+          headers: {
+            ...headers,
+            "Content-Type": "application/x-duckdb"
+          },
+          body: new Blob([data]),
+          signal: this.combineSignals(options?.signal)
+        });
+        if (!response.ok) {
+          return this.handleErrorResponse(response, "import");
+        }
+        return ok(void 0);
+      } catch (error) {
+        return err(wrapError("duckdb", error));
+      }
+    });
+  }
+  // === Private helpers ===
+  async invokeDuckDb(dbName, action, body, signal, extraHeaders) {
+    const session = this.context.session;
+    const headers = this.context.invoke(session, "duckdb", dbName, action);
+    return this.context.fetch(`${this.host}/invoke`, {
+      method: "POST",
+      headers: {
+        ...headers,
+        "Content-Type": "application/json",
+        ...extraHeaders
+      },
+      body: JSON.stringify(body),
+      signal: this.combineSignals(signal)
+    });
+  }
+  async handleErrorResponse(response, operation) {
+    const errorText = await response.text();
+    let errorBody = {};
+    try {
+      errorBody = JSON.parse(errorText);
+    } catch {
+    }
+    const errorCode = this.mapHttpStatusToErrorCode(
+      response.status,
+      errorBody.error
+    );
+    const message = errorBody.message || `DuckDB ${operation} failed: ${response.status} - ${errorText}`;
+    const meta = { status: response.status, statusText: response.statusText };
+    if (response.status === 401) {
+      const { resource, action } = parseAuthError(errorText);
+      if (action) meta.requiredAction = action;
+      if (resource) meta.resource = resource;
+    }
+    return err(
+      serviceError(errorCode, message, "duckdb", { meta })
+    );
+  }
+  mapHttpStatusToErrorCode(status, serverError) {
+    switch (status) {
+      case 400:
+        return ErrorCodes.DUCKDB_ERROR;
+      case 401:
+        return ErrorCodes.AUTH_UNAUTHORIZED;
+      case 403:
+        if (serverError === "duckdb_readonly_violation") {
+          return ErrorCodes.DUCKDB_READONLY_VIOLATION;
+        }
+        return ErrorCodes.DUCKDB_PERMISSION_DENIED;
+      case 404:
+        return ErrorCodes.DUCKDB_DATABASE_NOT_FOUND;
+      case 413:
+        return ErrorCodes.DUCKDB_RESPONSE_TOO_LARGE;
+      case 429:
+        return ErrorCodes.DUCKDB_QUOTA_EXCEEDED;
+      default:
+        return ErrorCodes.NETWORK_ERROR;
+    }
+  }
+};
+DuckDbService.serviceName = "duckdb";
+
+// src/quota/TinyCloudQuota.ts
+var TinyCloudQuota = class {
+  constructor(config = {}) {
+    this.quotaUrl = null;
+    this.config = config;
+  }
+  /** Set the quota URL discovered from the /info endpoint */
+  setQuotaUrl(url) {
+    this.quotaUrl = url;
+  }
+  /** Whether a quota service is available */
+  get available() {
+    return this.quotaUrl !== null;
+  }
+  /** Query quota status for a space from the quota URL */
+  async getQuota(spaceId) {
+    if (!this.quotaUrl) return null;
+    const resp = await fetch(
+      `${this.quotaUrl}/api/quota/${encodeURIComponent(spaceId)}`
+    );
+    if (!resp.ok) return null;
+    const data = await resp.json();
+    return {
+      limitBytes: data.storage_limit_bytes ?? 0
+    };
+  }
+  /** Trigger the upgrade callback when a quota error is encountered */
+  handleQuotaError(info) {
+    this.config.onUpgradeRequired?.(info);
+  }
+};
+
+// src/vault/types.ts
+var VaultPublicSpaceKVActions = [
+  "tinycloud.kv/get",
+  "tinycloud.kv/put",
+  "tinycloud.kv/metadata"
+];
+var VaultVersionConfig = {
+  "1": {
+    masterMessage: (spaceId) => `tinycloud-vault-master-v1:${spaceId}`,
+    identityMessage: "tinycloud-encryption-identity-v1"
+  }
+};
+var CURRENT_VAULT_VERSION = "1";
+var VaultHeaders = {
+  VERSION: "x-vault-version",
+  CIPHER: "x-vault-cipher",
+  KEY_ID: "x-vault-key-id",
+  CONTENT_TYPE: "x-vault-content-type",
+  KDF: "x-vault-kdf",
+  KEY_ROTATION: "x-vault-key-rotation",
+  GRANT_VERSION: "x-vault-grant-version",
+  GRANTOR: "x-vault-grantor"
+};
+
+// src/vault/SignatureCache.ts
+var DB_NAME = "tinycloud-vault-cache";
+var DB_VERSION = 1;
+var STORE_NAME = "signatures";
+var WRAP_KEY_ID = "__wrap_key__";
+function isBrowser() {
+  try {
+    return typeof indexedDB !== "undefined" && typeof crypto !== "undefined" && typeof crypto.subtle !== "undefined";
+  } catch {
+    return false;
+  }
+}
+function openDB() {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(DB_NAME, DB_VERSION);
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(STORE_NAME)) {
+        db.createObjectStore(STORE_NAME);
+      }
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
+function idbGet(db, key) {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_NAME, "readonly");
+    const store = tx.objectStore(STORE_NAME);
+    const req = store.get(key);
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+function idbPut(db, key, value) {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_NAME, "readwrite");
+    const store = tx.objectStore(STORE_NAME);
+    const req = store.put(value, key);
+    req.onsuccess = () => resolve();
+    req.onerror = () => reject(req.error);
+  });
+}
+function idbDelete(db, key) {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_NAME, "readwrite");
+    const store = tx.objectStore(STORE_NAME);
+    const req = store.delete(key);
+    req.onsuccess = () => resolve();
+    req.onerror = () => reject(req.error);
+  });
+}
+function idbKeys(db) {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_NAME, "readonly");
+    const store = tx.objectStore(STORE_NAME);
+    const req = store.getAllKeys();
+    req.onsuccess = () => resolve(req.result.filter((k) => typeof k === "string"));
+    req.onerror = () => reject(req.error);
+  });
+}
+async function getWrapKey(db) {
+  const existing = await idbGet(db, WRAP_KEY_ID);
+  if (existing) return existing;
+  const key = await crypto.subtle.generateKey(
+    { name: "AES-GCM", length: 256 },
+    false,
+    // non-extractable
+    ["encrypt", "decrypt"]
+  );
+  await idbPut(db, WRAP_KEY_ID, key);
+  return key;
+}
+async function encryptSig(wrapKey, sigBytes) {
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ciphertext = new Uint8Array(
+    await crypto.subtle.encrypt({ name: "AES-GCM", iv }, wrapKey, sigBytes)
+  );
+  return { iv, ciphertext };
+}
+async function decryptSig(wrapKey, entry) {
+  const plaintext = await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv: entry.iv },
+    wrapKey,
+    entry.ciphertext
+  );
+  return new Uint8Array(plaintext);
+}
+function cacheKey(spaceId) {
+  return `sig:${spaceId}`;
+}
+async function loadCachedSignature(spaceId) {
+  if (!isBrowser()) return null;
+  try {
+    const db = await openDB();
+    const entry = await idbGet(db, cacheKey(spaceId));
+    if (!entry) return null;
+    const wrapKey = await getWrapKey(db);
+    return await decryptSig(wrapKey, entry);
+  } catch {
+    return null;
+  }
+}
+async function cacheSignature(spaceId, sigBytes) {
+  if (!isBrowser()) return;
+  try {
+    const db = await openDB();
+    const wrapKey = await getWrapKey(db);
+    const encrypted = await encryptSig(wrapKey, sigBytes);
+    await idbPut(db, cacheKey(spaceId), encrypted);
+  } catch {
+  }
+}
+async function clearSignatureCache(spaceId) {
+  if (!isBrowser()) return;
+  try {
+    const db = await openDB();
+    if (spaceId) {
+      await idbDelete(db, cacheKey(spaceId));
+    } else {
+      const keys = await idbKeys(db);
+      for (const k of keys) {
+        if (k.startsWith("sig:")) {
+          await idbDelete(db, k);
+        }
+      }
+    }
+  } catch {
+  }
+}
+
+// src/vault/DataVaultService.ts
+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 };
+}
+var DataVaultService = class 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", void 0, 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 {
+        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);
+        }
+        this.masterKey = this.crypto.deriveKey(
+          masterSigBytes,
+          this.crypto.sha256(toBytes(spaceId)),
+          toBytes("vault-master")
+        );
+        const publicSpaceId = this.tc.makePublicSpaceId(this.tc.address, this.tc.chainId);
+        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 {
+        }
+        if (existingPubKey) {
+          this.encryptionIdentity = {
+            publicKey: base64Decode(existingPubKey),
+            privateKey: new Uint8Array(0)
+            // private key not available without signing
+          };
+        } else {
+          let identitySigBytes = await loadCachedSignature(identityCacheKey);
+          if (!identitySigBytes) {
+            if (!signer) {
+              this.encryptionIdentity = null;
+              this._isUnlocked = true;
+              return ok(void 0);
+            }
+            const s = signer;
+            const sig = await s.signMessage(versionConfig.identityMessage);
+            identitySigBytes = toBytes(sig);
+            await cacheSignature(identityCacheKey, identitySigBytes);
+          }
+          const seed = this.crypto.deriveKey(
+            identitySigBytes,
+            toBytes("tinycloud-x25519"),
+            toBytes("encryption-identity")
+          );
+          this.encryptionIdentity = this.crypto.x25519FromSeed(seed);
+          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 {
+          }
+        }
+        this._isUnlocked = true;
+        return ok(void 0);
+      } catch (error) {
+        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 {
+        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");
+        const entryKey = this.crypto.randomBytes(32);
+        const keyId = hexEncode(this.crypto.sha256(entryKey)).slice(0, 16);
+        const encrypted = this.crypto.encrypt(entryKey, plaintext);
+        const keyBlob = this.crypto.encrypt(this.masterKey, entryKey);
+        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 ?? {}
+        };
+        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}`
+            )
+          });
+        }
+        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(void 0);
+      } 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 {
+        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);
+        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);
+        const metadata = valueEnvelope.metadata ?? {};
+        const contentType = metadata[VaultHeaders.CONTENT_TYPE] ?? "application/json";
+        const keyId = metadata[VaultHeaders.KEY_ID] ?? "";
+        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 {
+        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(void 0);
+      } 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}`
+            )
+          });
+        }
+        let keys = listResult.data.keys;
+        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 {
+        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 {
+        const pubKeyResult = await this.resolvePublicKey(recipientDID);
+        if (!pubKeyResult.ok) {
+          return pubKeyResult;
+        }
+        const bobPubKey = pubKeyResult.data;
+        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);
+        const ephemeralSeed = this.crypto.randomBytes(32);
+        const ephemeralKeyPair = this.crypto.x25519FromSeed(ephemeralSeed);
+        const sharedSecret = this.crypto.x25519Dh(
+          ephemeralKeyPair.privateKey,
+          bobPubKey
+        );
+        const encryptionKey = this.crypto.deriveKey(
+          sharedSecret,
+          toBytes("tinycloud-x25519"),
+          toBytes("vault-grant")
+        );
+        const encryptedGrant = this.crypto.encrypt(encryptionKey, entryKey);
+        const grantBlob = concatBytes(
+          ephemeralKeyPair.publicKey,
+          encryptedGrant
+        );
+        const grantPayload = JSON.stringify({
+          grant: base64Encode(grantBlob),
+          spaceId: this.vaultConfig.spaceId,
+          metadata: {
+            [VaultHeaders.GRANT_VERSION]: "1",
+            [VaultHeaders.GRANTOR]: this.tc.did,
+            ...options?.metadata ?? {}
+          }
+        });
+        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(void 0);
+      } 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 }."
+            )
+          });
+        }
+        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);
+        const ephemeralPubKey = grantBlobBytes.slice(0, 32);
+        const encryptedGrant = grantBlobBytes.slice(32);
+        const sharedSecret = this.crypto.x25519Dh(
+          this.encryptionIdentity.privateKey,
+          ephemeralPubKey
+        );
+        const encryptionKey = this.crypto.deriveKey(
+          sharedSecret,
+          toBytes("tinycloud-x25519"),
+          toBytes("vault-grant")
+        );
+        const entryKey = this.crypto.decrypt(encryptionKey, encryptedGrant);
+        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);
+        const metadata = valueEnvelope.metadata ?? {};
+        const contentType = metadata[VaultHeaders.CONTENT_TYPE] ?? "application/json";
+        const keyId = metadata[VaultHeaders.KEY_ID] ?? "";
+        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}`
+            )
+          });
+        }
+        const dids = [];
+        for (const grantPath of listResult.data.keys) {
+          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 {
+        const granteesResult = await this.listGrants(key);
+        if (!granteesResult.ok) {
+          return granteesResult;
+        }
+        const remainingGrantees = granteesResult.data.filter(
+          (did) => did !== recipientDID
+        );
+        const deleteGrantResult = await this.tc.kv.delete(
+          `grants/${recipientDID}/${key}`
+        );
+        const getResult = await this.get(key);
+        if (!getResult.ok) {
+          return getResult;
+        }
+        const currentEntry = getResult.data;
+        const newEntryKey = this.crypto.randomBytes(32);
+        const newKeyId = hexEncode(this.crypto.sha256(newEntryKey)).slice(
+          0,
+          16
+        );
+        let plaintext;
+        if (currentEntry.value instanceof Uint8Array) {
+          plaintext = currentEntry.value;
+        } else {
+          plaintext = toBytes(JSON.stringify(currentEntry.value));
+        }
+        const encrypted = this.crypto.encrypt(newEntryKey, plaintext);
+        const newKeyBlob = this.crypto.encrypt(this.masterKey, newEntryKey);
+        const metadata = {
+          ...currentEntry.metadata,
+          [VaultHeaders.KEY_ID]: newKeyId
+        };
+        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}`
+            )
+          });
+        }
+        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}`
+            )
+          });
+        }
+        for (const did of remainingGrantees) {
+          const grantResult = await this.reencrypt(key, did);
+          if (!grantResult.ok) {
+          }
+        }
+        return ok(void 0);
+      } 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) {
+    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";
+
+// src/vault/createVaultCrypto.ts
+function createVaultCrypto(wasm) {
+  return {
+    encrypt: (key, plaintext) => wasm.vault_encrypt(key, plaintext),
+    decrypt: (key, blob) => wasm.vault_decrypt(key, blob),
+    deriveKey: (signature, salt, info) => wasm.vault_derive_key(salt, signature, info),
+    x25519FromSeed: (seed) => wasm.vault_x25519_from_seed(seed),
+    x25519Dh: (privateKey, publicKey) => wasm.vault_x25519_dh(privateKey, publicKey),
+    randomBytes: (length) => wasm.vault_random_bytes(length),
+    sha256: (data) => wasm.vault_sha256(data)
+  };
+}
+export {
+  BaseService,
+  DataVaultService,
+  DatabaseHandle,
+  DuckDbAction,
+  DuckDbDatabaseHandle,
+  DuckDbService,
+  ErrorCodes,
+  GenericKVResponseSchema,
+  GenericResultSchema,
+  KVAction,
+  KVListResponseSchema,
+  KVListResultSchema,
+  KVResponseHeadersSchema,
+  KVService,
+  PrefixedKVService,
+  RetryPolicySchema,
+  SQLAction,
+  SQLService,
+  ServiceContext,
+  ServiceErrorEventSchema,
+  ServiceErrorSchema,
+  ServiceRequestEventSchema,
+  ServiceResponseEventSchema,
+  ServiceRetryEventSchema,
+  ServiceSessionSchema,
+  TelemetryEvents,
+  TinyCloudQuota,
+  VaultHeaders,
+  VaultPublicSpaceKVActions,
+  abortedError,
+  authExpiredError,
+  authRequiredError,
+  authUnauthorizedError,
+  createKVResponseSchema,
+  createResultSchema,
+  createVaultCrypto,
+  defaultRetryPolicy,
+  err,
+  errorResult,
+  networkError,
+  notFoundError,
+  ok,
+  parseAuthError,
+  permissionDeniedError,
+  serviceError,
+  storageLimitReachedError,
+  storageQuotaExceededError,
+  timeoutError,
+  validateKVListResponse,
+  validateKVResponseHeaders,
+  validateRetryPolicy,
+  validateServiceError,
+  validateServiceRequestEvent,
+  validateServiceResponseEvent,
+  validateServiceSession,
+  wrapError
+};
 //# sourceMappingURL=index.js.map