@opengeni/vaults 3.1.2 → 3.2.2

package/dist/index.js

@@ -5,7 +5,727 @@ import {
   createProviderCallBudget,
   createVaultProviderRegistry,
   isVaultProviderError
-} from "./chunk-7S23LHTK.js";
+} from "./chunk-BD43JBPC.js";
+
+// src/provider-pages.ts
+import { VAULT_LIMITS } from "@opengeni/contracts";
+var PROVIDER_PAGE_SIZE = 100;
+var PROVIDER_MAX_PAGES = 100;
+function incomplete() {
+  throw new VaultProviderError(
+    "provider_inventory_incomplete",
+    "The provider inventory could not be read completely. The previous inventory was kept."
+  );
+}
+async function traverseProviderPages(input) {
+  if (!Number.isSafeInteger(input.maxItems) || input.maxItems < 1 || input.maxItems > 1e4)
+    incomplete();
+  const items = [];
+  const ids = /* @__PURE__ */ new Set();
+  const cursors = /* @__PURE__ */ new Set();
+  let cursor;
+  let snapshot;
+  for (let count = 0; count < PROVIDER_MAX_PAGES; count++) {
+    input.signal?.throwIfAborted();
+    const limit = Math.min(PROVIDER_PAGE_SIZE, input.maxItems - items.length);
+    if (limit < 1) incomplete();
+    const page = await input.page({
+      limit,
+      ...cursor !== void 0 ? { cursor } : {},
+      ...snapshot != null ? { snapshot } : {}
+    });
+    input.signal?.throwIfAborted();
+    if (!page || !Array.isArray(page.items) || page.items.length > limit || page.snapshot !== null && (typeof page.snapshot !== "string" || page.snapshot.length === 0 || page.snapshot.length > 1024) || page.nextCursor !== null && (typeof page.nextCursor !== "string" || page.nextCursor.length === 0 || page.nextCursor.length > 1024))
+      incomplete();
+    if (snapshot !== void 0 && page.snapshot !== snapshot) incomplete();
+    snapshot = page.snapshot;
+    if (page.freshness && page.freshness.state !== "current") incomplete();
+    for (const item of page.items) {
+      const id = input.identity(item);
+      if (typeof id !== "string" || id.length === 0 || id.length > 300 || ids.has(id)) incomplete();
+      ids.add(id);
+      items.push(item);
+    }
+    if (page.nextCursor === null) return { items, consistent: count === 0 || snapshot !== null };
+    if (items.length >= input.maxItems || cursors.has(page.nextCursor)) incomplete();
+    cursors.add(page.nextCursor);
+    cursor = page.nextCursor;
+  }
+  return incomplete();
+}
+async function collectProviderPages(input) {
+  return (await traverseProviderPages(input)).items;
+}
+function validateLegacyInventory(items, identity, max) {
+  if (!Array.isArray(items) || items.length > max) incomplete();
+  const ids = /* @__PURE__ */ new Set();
+  for (const item of items) {
+    const id = identity(item);
+    if (typeof id !== "string" || !id || id.length > 300 || ids.has(id)) incomplete();
+    ids.add(id);
+  }
+  return items;
+}
+async function readProviderVaultInventory(provider, ctx) {
+  const identity = (vault) => vault.externalVaultId;
+  if (provider.listVaultPage) {
+    return traverseProviderPages({
+      page: async (page) => {
+        const result = await provider.listVaultPage(ctx, page);
+        if (result.freshness) ctx.onFreshness?.(result.freshness);
+        return result;
+      },
+      identity,
+      maxItems: VAULT_LIMITS.vaultsPerOwnerScope,
+      ...ctx.signal ? { signal: ctx.signal } : {}
+    });
+  }
+  ctx.signal?.throwIfAborted();
+  const items = await provider.listVaults(ctx);
+  ctx.signal?.throwIfAborted();
+  return {
+    items: validateLegacyInventory(items, identity, VAULT_LIMITS.vaultsPerOwnerScope),
+    consistent: true
+  };
+}
+async function listProviderVaults(provider, ctx) {
+  return (await readProviderVaultInventory(provider, ctx)).items;
+}
+async function readProviderItemInventory(provider, ctx, externalVaultId) {
+  const identity = (item) => item.externalItemId;
+  if (provider.listItemPage) {
+    return traverseProviderPages({
+      page: async (page) => {
+        const result = await provider.listItemPage(ctx, externalVaultId, page);
+        if (result.freshness) ctx.onFreshness?.(result.freshness);
+        return result;
+      },
+      identity,
+      maxItems: VAULT_LIMITS.itemsPerVault,
+      ...ctx.signal ? { signal: ctx.signal } : {}
+    });
+  }
+  ctx.signal?.throwIfAborted();
+  const items = await provider.listItems(ctx, externalVaultId);
+  ctx.signal?.throwIfAborted();
+  return {
+    items: validateLegacyInventory(items, identity, VAULT_LIMITS.itemsPerVault),
+    consistent: true
+  };
+}
+async function listProviderItems(provider, ctx, externalVaultId) {
+  return (await readProviderItemInventory(provider, ctx, externalVaultId)).items;
+}
+
+// src/provider-capabilities.ts
+function providerOperations(capabilities, vault) {
+  const base = capabilities.operations ?? {
+    createItemTypes: capabilities.write ? ["login", "api_key", "note"] : [],
+    updateItem: capabilities.write,
+    removeField: capabilities.write,
+    archiveItem: capabilities.write,
+    archiveKind: capabilities.write ? "archive" : "none",
+    deleteItem: false,
+    restoreItem: false,
+    readFiles: capabilities.files,
+    writeFiles: false,
+    createTotp: capabilities.write && capabilities.totp,
+    updateTotp: capabilities.write && capabilities.totp,
+    createVault: capabilities.createVault,
+    restoreFieldHistory: false
+  };
+  const override = vault?.operations;
+  const operations = {
+    createItemTypes: base.createItemTypes.filter(
+      (type) => type !== "passkey" && (!override || override.createItemTypes.includes(type))
+    ),
+    updateItem: base.updateItem && (override?.updateItem ?? true),
+    removeField: base.removeField && (override?.removeField ?? true),
+    archiveItem: base.archiveItem && (override?.archiveItem ?? true),
+    archiveKind: base.archiveKind,
+    deleteItem: false,
+    restoreItem: base.restoreItem && (override?.restoreItem ?? true),
+    readFiles: base.readFiles && (override?.readFiles ?? true),
+    writeFiles: base.writeFiles && (override?.writeFiles ?? true),
+    createTotp: base.createTotp && (override?.createTotp ?? true),
+    updateTotp: base.updateTotp && (override?.updateTotp ?? true),
+    createVault: base.createVault && (override?.createVault ?? true),
+    restoreFieldHistory: base.restoreFieldHistory && (override?.restoreFieldHistory ?? true)
+  };
+  if (override && override.archiveKind !== base.archiveKind) operations.archiveItem = false;
+  if (operations.archiveKind === "none") operations.archiveItem = false;
+  if (!operations.archiveItem) operations.archiveKind = "none";
+  operations.removeField &&= operations.updateItem;
+  operations.updateTotp &&= operations.updateItem;
+  operations.createTotp &&= operations.createItemTypes.length > 0;
+  if (vault?.writeAccess !== "read_only" && capabilities.write) return operations;
+  return {
+    ...operations,
+    createItemTypes: [],
+    updateItem: false,
+    removeField: false,
+    archiveItem: false,
+    archiveKind: "none",
+    restoreItem: false,
+    writeFiles: false,
+    createTotp: false,
+    updateTotp: false,
+    createVault: false,
+    restoreFieldHistory: false
+  };
+}
+
+// src/remote-provider.ts
+import {
+  VAULT_LIMITS as VAULT_LIMITS2,
+  VAULT_PROVIDER_WIRE_LIMITS,
+  VAULT_PROVIDER_WIRE_RESPONSE_SIGNATURE_HEADER,
+  VAULT_PROVIDER_WIRE_VERSION,
+  VaultProviderWireRequest,
+  parseTotpInput,
+  parseVaultProviderWireResponse,
+  vaultProviderWireResponseKey,
+  vaultProviderWireUtf8Bytes
+} from "@opengeni/contracts";
+import {
+  OPENGENI_SIGNATURE_HEADER,
+  signOpenGeniPayload,
+  verifyOpenGeniSignature
+} from "@opengeni/contracts/workspace-integration-wire";
+var RemoteVaultTransportError = class extends Error {
+  failure;
+  requestSent;
+  constructor(failure, requestSent) {
+    super(`remote vault transport failed: ${failure}`);
+    this.name = "RemoteVaultTransportError";
+    this.failure = failure;
+    this.requestSent = requestSent;
+  }
+};
+function createFetchRemoteVaultTransport(fetchImpl) {
+  return {
+    async post(request) {
+      const controller = new AbortController();
+      let failure = null;
+      const timer = setTimeout(() => {
+        failure = "timeout";
+        controller.abort();
+      }, request.timeoutMs);
+      const onAbort = () => {
+        failure ??= "aborted";
+        controller.abort();
+      };
+      request.signal?.addEventListener("abort", onAbort, { once: true });
+      if (request.signal?.aborted) onAbort();
+      try {
+        let response;
+        try {
+          response = await fetchImpl(request.url, {
+            method: "POST",
+            headers: { ...request.headers },
+            body: request.body,
+            redirect: "manual",
+            signal: controller.signal
+          });
+        } catch {
+          throw new RemoteVaultTransportError(failure ?? "network", true);
+        }
+        if (response.type === "opaqueredirect" || response.status >= 300 && response.status < 400) {
+          await response.body?.cancel().catch(() => {
+          });
+          throw new RemoteVaultTransportError("redirect", true);
+        }
+        const chunks = [];
+        let total = 0;
+        const reader = response.body?.getReader();
+        if (reader) {
+          try {
+            for (; ; ) {
+              const { done, value } = await reader.read();
+              if (done) break;
+              total += value.byteLength;
+              if (total > request.maxResponseBytes) {
+                await reader.cancel().catch(() => {
+                });
+                throw new RemoteVaultTransportError("too_large", true);
+              }
+              chunks.push(value);
+            }
+          } catch (error) {
+            if (error instanceof RemoteVaultTransportError) throw error;
+            throw new RemoteVaultTransportError(failure ?? "network", true);
+          }
+        }
+        const bytes = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+          bytes.set(chunk, offset);
+          offset += chunk.byteLength;
+        }
+        return {
+          status: response.status,
+          headers: response.headers,
+          body: new TextDecoder("utf-8", { fatal: false }).decode(bytes)
+        };
+      } finally {
+        clearTimeout(timer);
+        request.signal?.removeEventListener("abort", onAbort);
+      }
+    }
+  };
+}
+var REMOTE_VAULT_READ_ONLY_OPERATIONS = Object.freeze({
+  createItemTypes: [],
+  updateItem: false,
+  removeField: false,
+  archiveItem: false,
+  archiveKind: "none",
+  deleteItem: false,
+  restoreItem: false,
+  readFiles: false,
+  writeFiles: false,
+  createTotp: false,
+  updateTotp: false,
+  createVault: false,
+  restoreFieldHistory: false
+});
+function remoteVaultOperations(operations) {
+  const createItemTypes = operations.createItemTypes.filter(
+    (type) => type !== "passkey" && type !== "file"
+  );
+  const archiveItem = operations.archiveItem && operations.archiveKind !== "none";
+  return {
+    createItemTypes,
+    updateItem: operations.updateItem,
+    removeField: operations.removeField && operations.updateItem,
+    archiveItem,
+    archiveKind: archiveItem ? operations.archiveKind : "none",
+    deleteItem: false,
+    restoreItem: false,
+    readFiles: operations.readFiles,
+    writeFiles: false,
+    createTotp: operations.createTotp && createItemTypes.length > 0,
+    updateTotp: operations.updateTotp && operations.updateItem,
+    createVault: false,
+    restoreFieldHistory: false
+  };
+}
+var SAFE_MESSAGES = {
+  provider_auth_invalid: "The remote vault rejected Opengeni's credentials.",
+  provider_auth_expired: "The remote vault needs to be reconnected.",
+  provider_rate_limited: "The remote vault is rate limiting requests. Try again later.",
+  provider_unavailable: "The remote vault is unavailable.",
+  provider_conflict: "The item changed in the remote vault. Reload it and try again.",
+  provider_not_found: "The remote vault item or field was not found.",
+  provider_permission_denied: "The remote vault does not allow this operation.",
+  provider_locked: "The remote vault is locked. Unlock it where it runs, then refresh.",
+  provider_inventory_incomplete: "The remote vault inventory could not be read completely. The previous inventory was kept.",
+  provider_outcome_unknown: "The remote vault did not confirm the change. It may or may not have been saved; check the vault before trying again."
+};
+function fail(code, retryAfterMs) {
+  throw new VaultProviderError(code, SAFE_MESSAGES[code], retryAfterMs);
+}
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
+function validEndpoint(endpoint, allowInsecureHttp) {
+  let url;
+  try {
+    url = new URL(endpoint);
+  } catch {
+    return fail("provider_unavailable");
+  }
+  const schemeOk = url.protocol === "https:" || allowInsecureHttp && url.protocol === "http:";
+  if (!schemeOk || url.username || url.password || url.hash || endpoint.length > 2048) {
+    fail("provider_unavailable");
+  }
+  return url.toString();
+}
+function decodeBase64(base64) {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+  return bytes;
+}
+function retryAfterHeader(headers) {
+  const value = headers.get("retry-after");
+  if (!value || !/^\d{1,6}$/.test(value.trim())) return void 0;
+  return Math.min(Number(value.trim()) * 1e3, 864e5);
+}
+function toProviderItem(item) {
+  return {
+    externalItemId: item.externalItemId,
+    name: item.name,
+    type: item.type,
+    websites: [...item.websites],
+    fields: item.fields.map((field) => ({
+      externalFieldId: field.externalFieldId,
+      name: field.name,
+      kind: field.kind
+    })),
+    version: item.version,
+    updatedAt: item.updatedAt
+  };
+}
+function toProviderVault(vault) {
+  return {
+    externalVaultId: vault.externalVaultId,
+    name: vault.name,
+    contentVersion: vault.contentVersion,
+    itemCount: vault.itemCount,
+    writeAccess: vault.writeAccess,
+    ...vault.operations ? { operations: remoteVaultOperations(vault.operations) } : {}
+  };
+}
+function createRemoteVaultProvider(options) {
+  if (options.provider !== "external" && options.provider !== "bitwarden") {
+    fail("provider_unavailable");
+  }
+  const endpoint = validEndpoint(options.endpoint, options.allowInsecureHttp === true);
+  if (typeof options.signingSecret !== "string" || options.signingSecret.length < 32 || options.signingSecret.length > 4096) {
+    fail("provider_auth_invalid");
+  }
+  if (options.connectionId !== void 0 && !UUID.test(options.connectionId)) {
+    fail("provider_unavailable");
+  }
+  const timeoutMs = Math.min(
+    Math.max(Math.trunc(options.timeoutMs ?? VAULT_PROVIDER_WIRE_LIMITS.defaultTimeoutMs), 1e3),
+    VAULT_PROVIDER_WIRE_LIMITS.maxTimeoutMs
+  );
+  const now = options.now ?? (() => Date.now());
+  const newRequestId = options.newRequestId ?? (() => crypto.randomUUID());
+  const responseKey = vaultProviderWireResponseKey(options.signingSecret);
+  let described = null;
+  function currentOperations() {
+    if (described) return described.operations;
+    if (options.operations) return remoteVaultOperations(options.operations);
+    return REMOTE_VAULT_READ_ONLY_OPERATIONS;
+  }
+  function connectionIdFor(ctx) {
+    const fromCtx = ctx.connectionId;
+    if (fromCtx && options.connectionId && fromCtx !== options.connectionId) {
+      fail("provider_permission_denied");
+    }
+    const id = fromCtx ?? options.connectionId;
+    if (!id || !UUID.test(id)) fail("provider_unavailable");
+    return id.toLowerCase();
+  }
+  function freshnessFrom(wire) {
+    if (!wire) return null;
+    return {
+      state: wire.state,
+      lastCheckedAt: new Date(now()).toISOString(),
+      sourceSyncedAt: wire.sourceSyncedAt,
+      source: wire.source,
+      errorCode: wire.errorCode,
+      retryAt: wire.retryAt
+    };
+  }
+  async function call(ctx, budget, operation) {
+    const mutation = operation.op === "write_item" || operation.op === "archive_item";
+    if (!ctx.authority) fail("provider_permission_denied");
+    const connectionId = connectionIdFor(ctx);
+    ctx.signal?.throwIfAborted();
+    ctx.budget.take(budget);
+    const requestId = newRequestId();
+    const { accountId, workspaceId, subjectId, connectionWorkspaceId } = ctx.authority;
+    const parsed = VaultProviderWireRequest.safeParse({
+      version: VAULT_PROVIDER_WIRE_VERSION,
+      type: "request",
+      requestId,
+      sentAt: new Date(now()).toISOString(),
+      provider: options.provider,
+      connectionId,
+      authority: {
+        accountId,
+        workspaceId,
+        subjectId,
+        connectionWorkspaceId,
+        ...ctx.authority.sessionId ? { sessionId: ctx.authority.sessionId } : {},
+        ...ctx.authority.turnId ? { turnId: ctx.authority.turnId } : {},
+        ...ctx.authority.attemptId ? { attemptId: ctx.authority.attemptId } : {},
+        ...ctx.authority.siteId ? { siteId: ctx.authority.siteId } : {}
+      },
+      operation
+    });
+    if (!parsed.success) fail("provider_unavailable");
+    const body = JSON.stringify(parsed.data);
+    if (vaultProviderWireUtf8Bytes(body) > VAULT_PROVIDER_WIRE_LIMITS.maxRequestBytes) {
+      fail("provider_unavailable");
+    }
+    const signature = await signOpenGeniPayload(
+      options.signingSecret,
+      body,
+      Math.floor(now() / 1e3)
+    );
+    const unverified = (code, retryAfterMs) => mutation ? fail("provider_outcome_unknown") : fail(code, retryAfterMs);
+    let response;
+    try {
+      response = await options.transport.post({
+        url: endpoint,
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          accept: "application/json",
+          [OPENGENI_SIGNATURE_HEADER]: signature
+        },
+        body,
+        timeoutMs,
+        maxResponseBytes: VAULT_PROVIDER_WIRE_LIMITS.maxResponseBytes,
+        ...ctx.signal ? { signal: ctx.signal } : {}
+      });
+    } catch (error) {
+      if (error instanceof RemoteVaultTransportError && !error.requestSent) {
+        fail("provider_unavailable");
+      }
+      if (mutation) fail("provider_outcome_unknown");
+      ctx.signal?.throwIfAborted();
+      return fail("provider_unavailable");
+    }
+    if (typeof response?.body !== "string" || vaultProviderWireUtf8Bytes(response.body) > VAULT_PROVIDER_WIRE_LIMITS.maxResponseBytes) {
+      return unverified("provider_unavailable");
+    }
+    if (response.status !== 200) {
+      if (response.status === 401 || response.status === 403) {
+        return unverified("provider_auth_invalid");
+      }
+      if (response.status === 429) {
+        return unverified("provider_rate_limited", retryAfterHeader(response.headers));
+      }
+      return unverified("provider_unavailable");
+    }
+    const verified = await verifyOpenGeniSignature({
+      secret: responseKey,
+      body: response.body,
+      signature: response.headers.get(VAULT_PROVIDER_WIRE_RESPONSE_SIGNATURE_HEADER),
+      toleranceSeconds: VAULT_PROVIDER_WIRE_LIMITS.signatureToleranceSeconds,
+      nowSeconds: Math.floor(now() / 1e3)
+    });
+    if (!verified) return unverified("provider_unavailable");
+    let json;
+    try {
+      json = JSON.parse(response.body);
+    } catch {
+      return unverified("provider_unavailable");
+    }
+    const envelope = parseVaultProviderWireResponse(json, { requestId, op: operation.op });
+    if (!envelope) return unverified("provider_unavailable");
+    const freshness = freshnessFrom(envelope.freshness);
+    if (!envelope.ok) {
+      if (freshness) ctx.onFreshness?.(freshness);
+      fail(envelope.error.code, envelope.error.retryAfterMs ?? void 0);
+    }
+    return { result: envelope.result, freshness };
+  }
+  function readContext(ctx) {
+    const epoch = ctx.cacheEpoch;
+    const cacheEpoch = typeof epoch === "string" && epoch.length > 0 && epoch.length <= VAULT_PROVIDER_WIRE_LIMITS.cacheEpochMaxChars && !CONTROL.test(epoch) ? epoch : null;
+    return { forceRefresh: ctx.forceRefresh === true, cacheEpoch };
+  }
+  function wirePage(page) {
+    const limit = Math.trunc(page.limit);
+    if (!Number.isSafeInteger(limit) || limit < 1) fail("provider_inventory_incomplete");
+    return {
+      limit: Math.min(limit, VAULT_PROVIDER_WIRE_LIMITS.pageSizeMax),
+      ...page.cursor !== void 0 ? { cursor: page.cursor } : {},
+      ...page.snapshot !== void 0 ? { snapshot: page.snapshot } : {}
+    };
+  }
+  function idempotencyKey(ctx) {
+    const key = ctx.idempotencyKey;
+    if (typeof key === "string" && key.length > 0 && key.length <= VAULT_PROVIDER_WIRE_LIMITS.idempotencyKeyMaxChars && !CONTROL.test(key)) {
+      return key;
+    }
+    return crypto.randomUUID();
+  }
+  const provider = {
+    id: options.provider,
+    capabilities() {
+      const operations = currentOperations();
+      return {
+        write: operations.createItemTypes.length > 0 || operations.updateItem || operations.archiveItem,
+        createVault: false,
+        totp: described?.capabilities.totp ?? (operations.createTotp || operations.updateTotp),
+        files: operations.readFiles,
+        groupGrants: false,
+        passkeys: false,
+        operations
+      };
+    },
+    async validate(ctx) {
+      const { result, freshness } = await call(ctx, "admin", { op: "describe" });
+      if (freshness) ctx.onFreshness?.(freshness);
+      const validation = {
+        accountId: result.accountId,
+        accountName: result.accountName,
+        operations: remoteVaultOperations(result.operations),
+        capabilities: { ...result.capabilities }
+      };
+      validation.operations.readFiles &&= validation.capabilities.files;
+      if (!validation.capabilities.totp) {
+        validation.operations.createTotp = false;
+        validation.operations.updateTotp = false;
+      }
+      described = validation;
+      return {
+        ...validation,
+        operations: { ...validation.operations },
+        capabilities: { ...validation.capabilities }
+      };
+    },
+    async listVaultPage(ctx, page) {
+      const request = wirePage(page);
+      const { result, freshness } = await call(ctx, "list", {
+        op: "list_vaults",
+        page: request,
+        ...readContext(ctx)
+      });
+      if (result.items.length > request.limit) fail("provider_inventory_incomplete");
+      return {
+        items: result.items.map(toProviderVault),
+        nextCursor: result.nextCursor,
+        snapshot: result.snapshot,
+        ...freshness ? { freshness } : {}
+      };
+    },
+    async listItemPage(ctx, externalVaultId, page) {
+      const request = wirePage(page);
+      const { result, freshness } = await call(ctx, "list", {
+        op: "list_items",
+        externalVaultId,
+        page: request,
+        ...readContext(ctx)
+      });
+      if (result.items.length > request.limit) fail("provider_inventory_incomplete");
+      return {
+        items: result.items.map(toProviderItem),
+        nextCursor: result.nextCursor,
+        snapshot: result.snapshot,
+        ...freshness ? { freshness } : {}
+      };
+    },
+    // Compatibility: a complete bounded traversal or a refusal, never a prefix.
+    async listVaults(ctx) {
+      return collectProviderPages({
+        page: async (page) => {
+          const result = await provider.listVaultPage(ctx, page);
+          if (result.freshness) ctx.onFreshness?.(result.freshness);
+          return result;
+        },
+        identity: (vault) => vault.externalVaultId,
+        maxItems: VAULT_LIMITS2.vaultsPerOwnerScope,
+        ...ctx.signal ? { signal: ctx.signal } : {}
+      });
+    },
+    async listItems(ctx, externalVaultId) {
+      return collectProviderPages({
+        page: async (page) => {
+          const result = await provider.listItemPage(ctx, externalVaultId, page);
+          if (result.freshness) ctx.onFreshness?.(result.freshness);
+          return result;
+        },
+        identity: (item) => item.externalItemId,
+        maxItems: VAULT_LIMITS2.itemsPerVault,
+        ...ctx.signal ? { signal: ctx.signal } : {}
+      });
+    },
+    async readFields(ctx, externalVaultId, externalItemId, externalFieldIds) {
+      if (externalFieldIds.length === 0) return [];
+      if (externalFieldIds.length > VAULT_PROVIDER_WIRE_LIMITS.readFieldsMax || new Set(externalFieldIds).size !== externalFieldIds.length) {
+        fail("provider_not_found");
+      }
+      const { result, freshness } = await call(ctx, "read", {
+        op: "read_fields",
+        externalVaultId,
+        externalItemId,
+        externalFieldIds: [...externalFieldIds],
+        ...readContext(ctx)
+      });
+      if (freshness) ctx.onFreshness?.(freshness);
+      const byId = new Map(result.fields.map((field) => [field.externalFieldId, field]));
+      if (result.fields.length !== externalFieldIds.length || externalFieldIds.some((id) => !byId.has(id))) {
+        fail("provider_unavailable");
+      }
+      const values = [];
+      for (const externalFieldId of externalFieldIds) {
+        const wire = byId.get(externalFieldId).value;
+        let material;
+        if (wire.type === "text") {
+          material = { type: "text", value: wire.value };
+        } else if (wire.type === "totp") {
+          try {
+            material = { type: "totp", params: parseTotpInput(wire.value) };
+          } catch {
+            return fail("provider_unavailable");
+          }
+        } else {
+          let bytes;
+          try {
+            bytes = decodeBase64(wire.base64);
+          } catch {
+            return fail("provider_unavailable");
+          }
+          if (bytes.byteLength > VAULT_LIMITS2.fileValueMaxBytes) fail("provider_unavailable");
+          material = { type: "bytes", value: bytes };
+        }
+        values.push({ externalFieldId, material });
+      }
+      return values;
+    },
+    async writeItem(ctx, externalVaultId, item) {
+      const operations = currentOperations();
+      const update = item.externalItemId !== void 0;
+      const type = item.type;
+      if (type === "passkey") return fail("provider_permission_denied");
+      if (update ? !operations.updateItem : !operations.createItemTypes.includes(item.type)) {
+        fail("provider_permission_denied");
+      }
+      if (item.fields.some((field) => field.kind === "file" && field.value !== void 0) || update && !operations.removeField && item.fields.some((field) => field.remove) || item.fields.some((field) => field.kind === "totp" && field.value !== void 0) && !(update ? operations.updateTotp : operations.createTotp)) {
+        fail("provider_permission_denied");
+      }
+      const fields = item.fields.map((field) => ({
+        ...field.externalFieldId !== void 0 ? { externalFieldId: field.externalFieldId } : {},
+        name: field.name,
+        kind: field.kind,
+        ...field.value !== void 0 ? { value: field.value } : {},
+        ...field.remove ? { remove: true } : {}
+      }));
+      const { result, freshness } = await call(ctx, "write", {
+        op: "write_item",
+        externalVaultId,
+        item: {
+          ...update ? { externalItemId: item.externalItemId } : {},
+          ...item.expectedVersion !== void 0 ? { expectedVersion: item.expectedVersion } : {},
+          name: item.name,
+          type,
+          websites: [...item.websites],
+          fields
+        },
+        idempotencyKey: idempotencyKey(ctx)
+      });
+      if (freshness) ctx.onFreshness?.(freshness);
+      if (update && result.item.externalItemId !== item.externalItemId) {
+        fail("provider_outcome_unknown");
+      }
+      return toProviderItem(result.item);
+    },
+    async archiveItem(ctx, externalVaultId, externalItemId) {
+      if (!currentOperations().archiveItem) fail("provider_permission_denied");
+      const { freshness } = await call(ctx, "write", {
+        op: "archive_item",
+        externalVaultId,
+        externalItemId,
+        idempotencyKey: idempotencyKey(ctx)
+      });
+      if (freshness) ctx.onFreshness?.(freshness);
+    },
+    async refresh(ctx) {
+      const { freshness } = await call(ctx, "admin", { op: "refresh" });
+      if (freshness) ctx.onFreshness?.(freshness);
+      return freshness;
+    }
+  };
+  return provider;
+}
 
 // src/splice/index.ts
 import { SecretReferenceError as SecretReferenceError3 } from "@opengeni/contracts";
@@ -890,13 +1610,27 @@ function dialectFromShell(shell, os) {
 }
 export {
   EMPTY_VAULT_PROVIDER_REGISTRY,
+  PROVIDER_MAX_PAGES,
+  PROVIDER_PAGE_SIZE,
+  REMOTE_VAULT_READ_ONLY_OPERATIONS,
+  RemoteVaultTransportError,
   SECRET_EXEC_ENV_PREFIX,
   VAULT_PROVIDER_ERROR_CODES,
   VaultProviderError,
+  collectProviderPages,
+  createFetchRemoteVaultTransport,
   createProviderCallBudget,
+  createRemoteVaultProvider,
   createVaultProviderRegistry,
   dialectFromShell,
   isVaultProviderError,
-  spliceShellCommand
+  listProviderItems,
+  listProviderVaults,
+  providerOperations,
+  readProviderItemInventory,
+  readProviderVaultInventory,
+  remoteVaultOperations,
+  spliceShellCommand,
+  traverseProviderPages
 };
 //# sourceMappingURL=index.js.map