@opengeni/vaults 3.1.2 → 3.2.2

package/dist/remote-provider.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Generic remote vault provider over the signed `opengeni.vault.v1` protocol.
+ *
+ * The HTTP transport is injected: the API and worker supply their DNS-pinned,
+ * HTTPS-only, no-redirect egress. This adapter only signs exact request
+ * bytes, enforces the response byte cap again, verifies the response MAC and
+ * strictly parses the operation result. It never retries a mutation: any
+ * response that cannot be verified after a write may have been applied and is
+ * reported as `provider_outcome_unknown`.
+ */
+import { type VaultProviderFreshness, type VaultProviderOperations } from "@opengeni/contracts";
+import { type ProviderItemMeta, type ProviderPage, type ProviderPageRequest, type ProviderVault, type VaultProvider, type VaultProviderContext } from "./provider.js";
+export type RemoteVaultProviderKind = "external" | "bitwarden";
+/** Case-insensitive header lookup, satisfied by `Headers`. */
+export interface RemoteVaultHeaders {
+    get(name: string): string | null;
+}
+export interface RemoteVaultHttpRequest {
+    url: string;
+    method: "POST";
+    headers: Readonly<Record<string, string>>;
+    /** Send exactly these bytes; the signature covers them. */
+    body: string;
+    /** Hard deadline for connect, send and the complete response body. */
+    timeoutMs: number;
+    /** Fail instead of reading more response body bytes than this. */
+    maxResponseBytes: number;
+    signal?: AbortSignal;
+}
+export interface RemoteVaultHttpResponse {
+    status: number;
+    headers: RemoteVaultHeaders;
+    body: string;
+}
+/**
+ * Bounded HTTP egress for remote vault calls. Implementations must refuse
+ * redirects, enforce `timeoutMs` and `maxResponseBytes`, and apply the
+ * deployment's endpoint policy (HTTPS, DNS pinning, private-address refusal).
+ */
+export interface RemoteVaultTransport {
+    post(request: RemoteVaultHttpRequest): Promise<RemoteVaultHttpResponse>;
+}
+export type RemoteVaultTransportFailure = "refused" | "network" | "timeout" | "redirect" | "too_large" | "aborted";
+/**
+ * Transport failure. Set `requestSent: false` only when the transport knows
+ * no request bytes left the process (for example a refused DNS policy);
+ * otherwise a failed mutation is reported as an unknown outcome.
+ */
+export declare class RemoteVaultTransportError extends Error {
+    readonly failure: RemoteVaultTransportFailure;
+    readonly requestSent: boolean;
+    constructor(failure: RemoteVaultTransportFailure, requestSent: boolean);
+}
+export type RemoteVaultFetch = (url: string, init: {
+    method: "POST";
+    headers: Record<string, string>;
+    body: string;
+    redirect: "manual";
+    signal: AbortSignal;
+}) => Promise<{
+    status: number;
+    type?: string;
+    headers: RemoteVaultHeaders;
+    body: ReadableStream<Uint8Array> | null;
+}>;
+/**
+ * Adapts a fetch-compatible function (for example the deployment's pinned
+ * fetch) to the bounded transport: manual redirects are refused, the whole
+ * exchange shares one deadline and the body is read with a byte cap.
+ */
+export declare function createFetchRemoteVaultTransport(fetchImpl: RemoteVaultFetch): RemoteVaultTransport;
+export interface RemoteVaultProviderOptions {
+    provider: RemoteVaultProviderKind;
+    /** Registered endpoint. HTTPS only unless `allowInsecureHttp` (local/test). */
+    endpoint: string;
+    /** Per-connection secret; signs requests and derives the response key. */
+    signingSecret: string;
+    transport: RemoteVaultTransport;
+    /** The Opengeni connection id; must match `ctx.connectionId` when both exist. */
+    connectionId?: string;
+    /**
+     * Operations verified by the last describe (stored with the connection), so
+     * a fresh instance can answer `capabilities()` without a call. Without it,
+     * and before `validate`, the provider is read-only.
+     */
+    operations?: VaultProviderOperations;
+    timeoutMs?: number;
+    allowInsecureHttp?: boolean;
+    now?: () => number;
+    newRequestId?: () => string;
+}
+export interface RemoteVaultValidation {
+    accountName: string | null;
+    accountId: string;
+    operations: VaultProviderOperations;
+    capabilities: {
+        totp: boolean;
+        files: boolean;
+    };
+}
+export interface RemoteVaultProvider extends VaultProvider {
+    readonly id: RemoteVaultProviderKind;
+    validate(ctx: VaultProviderContext): Promise<RemoteVaultValidation>;
+    listVaultPage(ctx: VaultProviderContext, page: ProviderPageRequest): Promise<ProviderPage<ProviderVault>>;
+    listItemPage(ctx: VaultProviderContext, externalVaultId: string, page: ProviderPageRequest): Promise<ProviderPage<ProviderItemMeta>>;
+    /** Deliberate upstream refresh. Returns the receiver's freshness. */
+    refresh(ctx: VaultProviderContext): Promise<VaultProviderFreshness | null>;
+}
+/** Operations a remote connection can never perform through this protocol. */
+export declare const REMOTE_VAULT_READ_ONLY_OPERATIONS: VaultProviderOperations;
+/** Clamp a described operation set to what the v1 wire can express. */
+export declare function remoteVaultOperations(operations: VaultProviderOperations): VaultProviderOperations;
+/**
+ * Create a provider for one registered remote connection. Construction
+ * validates the endpoint and secret; no request is sent until a method runs.
+ */
+export declare function createRemoteVaultProvider(options: RemoteVaultProviderOptions): RemoteVaultProvider;

package/dist/testing/fake-provider.js

@@ -1,7 +1,7 @@
 import {
   createFakeVaultProvider
-} from "../chunk-VKPGG2FW.js";
-import "../chunk-7S23LHTK.js";
+} from "../chunk-BEKN77JO.js";
+import "../chunk-BD43JBPC.js";
 export {
   createFakeVaultProvider
 };

package/dist/testing/index.js

@@ -1,10 +1,10 @@
 import {
   createFakeVaultProvider
-} from "../chunk-VKPGG2FW.js";
+} from "../chunk-BEKN77JO.js";
 import {
   VaultProviderError,
   createProviderCallBudget
-} from "../chunk-7S23LHTK.js";
+} from "../chunk-BD43JBPC.js";
 
 // src/testing/static-resolver.ts
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/vaults",
-  "version": "3.1.2",
+  "version": "3.2.2",
   "description": "Vault provider interface, registry, shell splicers and test doubles for Opengeni secrets.",
   "license": "Apache-2.0",
   "repository": {
@@ -42,7 +42,7 @@
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
-    "@opengeni/contracts": "3.1.2"
+    "@opengeni/contracts": "3.2.2"
   },
   "engines": {
     "node": ">=18"

package/src/index.ts

@@ -1,2 +1,5 @@
 export * from "./provider";
+export * from "./provider-pages";
+export * from "./provider-capabilities";
+export * from "./remote-provider";
 export * from "./splice/index";

package/src/provider-capabilities.ts

@@ -0,0 +1,64 @@
+import type { VaultProviderOperations } from "@opengeni/contracts";
+import type { ProviderVault, VaultProviderCapabilities } from "./provider";
+
+/** Preserve the published legacy port, while new adapters declare exact operations. */
+export function providerOperations(
+  capabilities: VaultProviderCapabilities,
+  vault?: Pick<ProviderVault, "operations" | "writeAccess">,
+): VaultProviderOperations {
+  const base: VaultProviderOperations = 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;
+  // An upstream vault may narrow its adapter's abilities, never widen them.
+  const operations: VaultProviderOperations = {
+    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,
+  };
+}

package/src/provider-pages.ts

@@ -0,0 +1,206 @@
+import { VAULT_LIMITS } from "@opengeni/contracts";
+import {
+  VaultProviderError,
+  type ProviderItemMeta,
+  type ProviderPage,
+  type ProviderPageRequest,
+  type ProviderVault,
+  type VaultProvider,
+  type VaultProviderContext,
+} from "./provider";
+
+export const PROVIDER_PAGE_SIZE = 100;
+export const PROVIDER_MAX_PAGES = 100;
+
+function incomplete(): never {
+  // Do not echo untrusted cursors, item names or response bodies in errors.
+  throw new VaultProviderError(
+    "provider_inventory_incomplete",
+    "The provider inventory could not be read completely. The previous inventory was kept.",
+  );
+}
+
+/**
+ * A bounded provider inventory and what it proves (external vaults §8).
+ */
+export interface ProviderInventory<T> {
+  items: T[];
+  /**
+   * Whether the listing also proves which items are absent. It does when it
+   * was one response (a single page or a legacy array listing), or when
+   * every page carried the same provider snapshot token. Offset or position
+   * cursors without a snapshot can skip an existing item that moved across
+   * a page boundary while the pages were read (an earlier item was deleted
+   * meanwhile), so such a multi-page listing proves only what it contains.
+   * Never remove, or report as missing, anything absent from an inventory
+   * that is not consistent.
+   */
+  consistent: boolean;
+}
+
+export interface ProviderPageTraversal<T> {
+  page: (request: ProviderPageRequest) => Promise<ProviderPage<T>>;
+  identity: (item: T) => string;
+  maxItems: number;
+  signal?: AbortSignal;
+}
+
+/**
+ * A full traversal or a refusal (`provider_inventory_incomplete`), never a
+ * prefix presented as the whole. A caller may remove items absent from it
+ * only when it is `consistent`.
+ */
+export async function traverseProviderPages<T>(
+  input: ProviderPageTraversal<T>,
+): Promise<ProviderInventory<T>> {
+  if (!Number.isSafeInteger(input.maxItems) || input.maxItems < 1 || input.maxItems > 10_000)
+    incomplete();
+  const items: T[] = [];
+  const ids = new Set<string>();
+  const cursors = new Set<string>();
+  let cursor: string | undefined;
+  let snapshot: string | null | undefined;
+  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 !== undefined ? { 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 !== undefined && 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);
+    }
+    // One page is one response; later pages are consistent only under the
+    // same snapshot (a changed snapshot was refused above).
+    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();
+}
+
+/**
+ * Enumeration: everything a complete bounded traversal listed, or a refusal.
+ * It does not say whether absence is proven; use `traverseProviderPages`
+ * before removing anything that is not listed.
+ */
+export async function collectProviderPages<T>(input: ProviderPageTraversal<T>): Promise<T[]> {
+  return (await traverseProviderPages(input)).items;
+}
+
+function validateLegacyInventory<T>(items: T[], identity: (item: T) => string, max: number): T[] {
+  if (!Array.isArray(items) || items.length > max) incomplete();
+  const ids = new Set<string>();
+  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;
+}
+
+/**
+ * The provider's vaults and whether absence is proven. Legacy array
+ * providers remain compatible (one response is consistent); new remote
+ * providers page natively.
+ */
+export async function readProviderVaultInventory(
+  provider: VaultProvider,
+  ctx: VaultProviderContext,
+): Promise<ProviderInventory<ProviderVault>> {
+  const identity = (vault: ProviderVault) => 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,
+  };
+}
+
+/** Enumeration of the provider's vaults (discovery and linking). */
+export async function listProviderVaults(
+  provider: VaultProvider,
+  ctx: VaultProviderContext,
+): Promise<ProviderVault[]> {
+  return (await readProviderVaultInventory(provider, ctx)).items;
+}
+
+/**
+ * A provider vault's item metadata and whether absence is proven: only a
+ * consistent inventory may replace a mirror.
+ */
+export async function readProviderItemInventory(
+  provider: VaultProvider,
+  ctx: VaultProviderContext,
+  externalVaultId: string,
+): Promise<ProviderInventory<ProviderItemMeta>> {
+  const identity = (item: ProviderItemMeta) => 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,
+  };
+}
+
+/**
+ * Enumeration of a provider vault's item metadata. It does not prove which
+ * items are absent; mirror replacement uses `readProviderItemInventory`.
+ */
+export async function listProviderItems(
+  provider: VaultProvider,
+  ctx: VaultProviderContext,
+  externalVaultId: string,
+): Promise<ProviderItemMeta[]> {
+  return (await readProviderItemInventory(provider, ctx, externalVaultId)).items;
+}

package/src/provider.ts

@@ -4,6 +4,8 @@ import type {
   VaultFieldKind,
   VaultItemType,
   VaultSource,
+  VaultProviderOperations,
+  VaultProviderFreshness,
 } from "@opengeni/contracts";
 
 export interface VaultProviderCapabilities {
@@ -14,12 +16,16 @@ export interface VaultProviderCapabilities {
   groupGrants: boolean;
   /** Passkeys live only in Opengeni-hosted vaults (D20). */
   passkeys: false;
+  /** Additive: older in-process providers retain the legacy capability flags. */
+  operations?: VaultProviderOperations;
 }
 export interface ProviderVault {
   externalVaultId: string;
   name: string;
   contentVersion: string | null;
   itemCount: number | null;
+  writeAccess?: "read_only" | "read_write" | "unknown";
+  operations?: VaultProviderOperations;
 }
 export interface ProviderFieldMeta {
   externalFieldId: string;
@@ -63,13 +69,74 @@ export interface VaultProviderContext {
   connectionId: string | null;
   budget: ProviderCallBudget;
   signal?: AbortSignal;
+  /** Trusted native scope, supplied by the authorized registry, never model arguments. */
+  authority?: VaultProviderAuthority;
+  /** Last successful mirror-check identity; changes invalidate attempt value caches. */
+  cacheEpoch?: string | null;
+  /** Recheck upstream, without retrying a mutation or bypassing provider throttling. */
+  forceRefresh?: boolean;
+  /** Stable caller operation identity when available. No automatic replay is implied. */
+  idempotencyKey?: string;
+  /** Runtime-only observation; never supplied by an agent or persisted with values. */
+  onFreshness?: (freshness: VaultProviderFreshness) => void;
 }
+
+export interface VaultProviderAuthority {
+  accountId: string;
+  workspaceId: string;
+  subjectId: string | null;
+  /** Where the encrypted connection is owned, not a replacement for the calling workspace. */
+  connectionWorkspaceId: string;
+  sessionId?: string;
+  turnId?: string;
+  attemptId?: string;
+  siteId?: string;
+}
+
+export interface ProviderPageRequest {
+  cursor?: string;
+  limit: number;
+  snapshot?: string;
+}
+
+export interface ProviderPage<T> {
+  items: T[];
+  nextCursor: string | null;
+  /**
+   * Null only when upstream cannot supply snapshot consistency. A single page
+   * needs none, but a multi-page listing without a snapshot proves only what
+   * it contains: Opengeni lists it for discovery, yet never replaces a mirror
+   * from it (that would drop items skipped while the pages were read). Every
+   * page of one listing carries the same snapshot.
+   */
+  snapshot: string | null;
+  freshness?: VaultProviderFreshness;
+}
+
 export interface VaultProvider {
-  readonly id: "onepassword" | "host" | "fake";
+  readonly id: Exclude<VaultSource, "opengeni"> | "fake";
   capabilities(): VaultProviderCapabilities;
-  validate(ctx: VaultProviderContext): Promise<{ accountName: string | null }>;
+  validate(ctx: VaultProviderContext): Promise<{
+    accountName: string | null;
+    /** Stable identity, when supplied by the upstream account or bridge. */
+    accountId?: string;
+  }>;
+  /**
+   * One complete response, trusted as a consistent inventory. An adapter
+   * that pages upstream should implement `listVaultPage`/`listItemPage`, so
+   * page consistency is checked, rather than join pages here.
+   */
   listVaults(ctx: VaultProviderContext): Promise<ProviderVault[]>;
   listItems(ctx: VaultProviderContext, externalVaultId: string): Promise<ProviderItemMeta[]>;
+  listVaultPage?(
+    ctx: VaultProviderContext,
+    page: ProviderPageRequest,
+  ): Promise<ProviderPage<ProviderVault>>;
+  listItemPage?(
+    ctx: VaultProviderContext,
+    externalVaultId: string,
+    page: ProviderPageRequest,
+  ): Promise<ProviderPage<ProviderItemMeta>>;
   readFields(
     ctx: VaultProviderContext,
     externalVaultId: string,
@@ -105,6 +172,9 @@ export const VAULT_PROVIDER_ERROR_CODES = [
    * service reports `vault_read_only` for writes, `vault_permission_denied` otherwise.
    */
   "provider_permission_denied",
+  "provider_locked",
+  "provider_inventory_incomplete",
+  "provider_outcome_unknown",
 ] as const;
 export type VaultProviderErrorCode = (typeof VAULT_PROVIDER_ERROR_CODES)[number];
 
@@ -149,6 +219,10 @@ export interface VaultProviderRegistry {
 export function createVaultProviderRegistry(factories: {
   onepassword?: (connectionId: string | null) => Promise<VaultProvider>;
   host?: () => Promise<VaultProvider>;
+  external?: (connectionId: string | null) => Promise<VaultProvider>;
+  protonpass?: (connectionId: string | null) => Promise<VaultProvider>;
+  keeper?: (connectionId: string | null) => Promise<VaultProvider>;
+  bitwarden?: (connectionId: string | null) => Promise<VaultProvider>;
 }): VaultProviderRegistry {
   return {
     async forVault(vault) {
@@ -156,6 +230,14 @@ export function createVaultProviderRegistry(factories: {
         return factories.onepassword(vault.providerConnectionId);
       }
       if (vault.source === "host" && factories.host) return factories.host();
+      if (
+        vault.source !== "opengeni" &&
+        vault.source !== "host" &&
+        vault.source !== "onepassword"
+      ) {
+        const factory = factories[vault.source];
+        if (factory) return factory(vault.providerConnectionId);
+      }
       throw new VaultProviderError(
         "provider_unavailable",
         vault.source === "opengeni"