@opengeni/core 3.1.2 → 3.2.2

package/src/domain/vaults/provider-writes.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import {
   generatePassword,
   isValidTotpInput,
@@ -5,6 +6,7 @@ import {
   type VaultFieldInput,
   type VaultFieldKind,
   type VaultItemType,
+  type VaultProviderOperations,
 } from "@opengeni/contracts";
 import {
   getProviderVaultItemRef,
@@ -16,19 +18,36 @@ import {
 } from "@opengeni/db";
 import {
   isVaultProviderError,
+  providerOperations,
+  readProviderItemInventory,
   type ProviderCallBudget,
   type ProviderWriteField,
   type VaultProvider,
+  type VaultProviderContext,
   type VaultProviderRegistry,
 } from "@opengeni/vaults";
+import {
+  intersectProviderOperations,
+  providerOperationsForMode,
+  storedProviderOperations,
+  withoutProviderWrites,
+} from "./mapping";
 import { vaultErrorCodeForProvider } from "./provider-registry";
-import { syncLinkedProviderVault } from "./provider-sync";
+import { syncLinkedProviderVault, type ProviderVaultSyncResult } from "./provider-sync";
 
 /**
- * Edits of items in a read-write connected vault (OP-3): the change is written
- * to the provider (1Password `items.get` → patch → `items.put`, with the
- * mirrored version as the expected version), then the metadata mirror is
- * refreshed. Values never touch Opengeni storage.
+ * Edits of items in a read-write connected vault (OP-3, external vaults §10):
+ * the change is written to the provider (with the mirrored version as the
+ * expected version), then the metadata mirror is refreshed. Values never
+ * touch Opengeni storage.
+ *
+ * Every write is checked against the vault's effective operations first (the
+ * provider's current capabilities, narrowed by what it last reported for the
+ * vault and by the link mode), before any reference is resolved or value
+ * generated. A provider mutation is never retried: when its outcome is
+ * unknown the caller is told to check the vault, and a write that succeeded
+ * but could not be listed yet is reported as saved, never as a failure that
+ * invites saving it again.
  */
 
 /** One field change; the REST `VaultFieldInput` and the agent `secret_save` field both fit. */
@@ -60,6 +79,33 @@ export interface ProviderWriteDeps {
   budget?: ProviderCallBudget;
 }
 
+/** An operation a connected vault may not allow; reported in `vault_read_only` details. */
+export type ProviderWriteOperation =
+  | "createItem"
+  | "updateItem"
+  | "removeField"
+  | "createTotp"
+  | "updateTotp"
+  | "archiveItem"
+  | "deleteItem"
+  | "restoreItem"
+  | "writeFiles"
+  | "restoreFieldHistory";
+
+/** The result of a provider write once the mirror was refreshed. */
+export type ProviderWriteOutcome =
+  | { status: "listed"; itemId: string }
+  | {
+      /**
+       * The provider confirmed the write, but the refreshed mirror does not
+       * show it yet (for example the refresh was rate limited). It must not be
+       * saved again; it appears after the next successful sync.
+       */
+      status: "saved_not_listed";
+      vaultId: string;
+      sync: ProviderVaultSyncResult["status"] | "error";
+    };
+
 const TEXT_FIELD_NAMES = ["username", "user", "email", "login", "account"];
 
 function defaultKind(name: string): VaultFieldKind {
@@ -79,14 +125,76 @@ export function assertProviderVaultWritable(vault: VaultRow): void {
   }
 }
 
-async function providerFieldWrites(
+const NO_PROVIDER_OPERATIONS: VaultProviderOperations = withoutProviderWrites({
+  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,
+});
+
+/**
+ * What a connected vault allows now: the provider's current capabilities,
+ * narrowed by the operations it last reported for this vault (a read-only
+ * share, for example) and by the link mode. Permanent deletion is never
+ * allowed.
+ */
+export function effectiveProviderOperations(
+  vault: VaultRow,
+  provider: Pick<VaultProvider, "capabilities"> | null,
+): VaultProviderOperations {
+  if (vault.source === "opengeni") return NO_PROVIDER_OPERATIONS;
+  const stored = storedProviderOperations(vault);
+  const live = provider ? providerOperations(provider.capabilities()) : null;
+  const operations = live && stored ? intersectProviderOperations(live, stored) : (stored ?? live);
+  return operations ? providerOperationsForMode(operations, vault.mode) : NO_PROVIDER_OPERATIONS;
+}
+
+function refuse(
+  vault: VaultRow,
+  operation: ProviderWriteOperation,
+  message: string,
+  details: Record<string, unknown> = {},
+): never {
+  throw new VaultError("vault_read_only", message, { vaultId: vault.id, operation, ...details });
+}
+
+/** Refuses a provider operation Opengeni never performs, with the reason. */
+export function refuseProviderOperation(
+  vault: VaultRow,
+  operation: Extract<ProviderWriteOperation, "deleteItem" | "restoreItem" | "restoreFieldHistory">,
+): never {
+  const messages = {
+    deleteItem: `Opengeni never permanently deletes items in ${vault.name}. Archive the item, or delete it in the provider itself.`,
+    restoreItem: `Items archived in ${vault.name} are restored in the provider itself; the restored item appears after the next sync.`,
+    restoreFieldHistory: `${vault.name} keeps field history in the provider; restore an earlier value there.`,
+  } as const;
+  return refuse(vault, operation, messages[operation]);
+}
+
+type PlannedField = {
+  input: ProviderFieldChange;
+  base: ProviderWriteField;
+  kind: VaultFieldKind;
+};
+
+/** Checks every field change against the vault's operations, before any value exists. */
+function planFieldWrites(
+  vault: VaultRow,
+  operations: VaultProviderOperations,
+  creating: boolean,
   fields: readonly ProviderFieldChange[],
   existing: readonly VaultFieldRow[],
-  resolveReference: (raw: string) => Promise<string>,
-  generated: string[],
-): Promise<ProviderWriteField[]> {
-  const writes: ProviderWriteField[] = [];
-  for (const input of fields) {
+): PlannedField[] {
+  return fields.map((input) => {
     const current = existing.find(
       (field) =>
         (input.fieldId !== undefined && field.id === input.fieldId) ||
@@ -98,24 +206,56 @@ async function providerFieldWrites(
       name: input.name,
       kind,
     };
-    if (input.remove) {
-      writes.push({ ...base, remove: true });
-      continue;
-    }
     if (input.restoreVersion !== undefined) {
-      throw new VaultError(
-        "provider_unavailable",
-        "connected vaults keep their history in the provider; restore it there",
-        { field: input.name },
-      );
+      return refuseProviderOperation(vault, "restoreFieldHistory");
     }
-    if (input.fileBase64 !== undefined || kind === "file") {
+    if (input.fileBase64 !== undefined || kind === "file" || current?.kind === "file") {
       throw new VaultError(
         "provider_unavailable",
         "files in connected vaults are read-only in Opengeni",
-        { field: input.name },
+        { field: input.name, vaultId: vault.id, operation: "writeFiles" },
       );
     }
+    const totp = kind === "totp" || current?.kind === "totp";
+    if (input.remove) {
+      if (!operations.removeField) {
+        refuse(vault, "removeField", `${vault.name} does not allow removing fields here`, {
+          field: input.name,
+        });
+      }
+      if (totp && !operations.updateTotp) {
+        refuse(vault, "updateTotp", `${vault.name} does not allow changing one-time passwords`, {
+          field: input.name,
+        });
+      }
+      return { input, base, kind };
+    }
+    if (totp) {
+      const allowed = creating ? operations.createTotp : operations.updateTotp;
+      if (!allowed) {
+        refuse(
+          vault,
+          creating ? "createTotp" : "updateTotp",
+          `${vault.name} does not allow ${creating ? "saving" : "changing"} one-time passwords`,
+          { field: input.name },
+        );
+      }
+    }
+    return { input, base, kind };
+  });
+}
+
+async function providerFieldValues(
+  planned: readonly PlannedField[],
+  resolveReference: (raw: string) => Promise<string>,
+  generated: string[],
+): Promise<ProviderWriteField[]> {
+  const writes: ProviderWriteField[] = [];
+  for (const { input, base, kind } of planned) {
+    if (input.remove) {
+      writes.push({ ...base, remove: true });
+      continue;
+    }
     let value: string;
     if (input.generate !== undefined) {
       value = generatePassword(input.generate);
@@ -147,6 +287,23 @@ function providerFailure(error: unknown): never {
   throw error;
 }
 
+/**
+ * A provider mutation that failed. Only a provider's own definitive answer is
+ * a failure; anything else (a timeout, a dropped connection, an adapter
+ * defect, or a provider that says so) leaves the outcome unknown, and the
+ * mutation is not retried.
+ */
+function mutationFailure(vault: VaultRow, error: unknown, what: string): never {
+  if (isVaultProviderError(error) && error.code !== "provider_outcome_unknown") {
+    return providerFailure(error);
+  }
+  throw new VaultError(
+    "provider_outcome_unknown",
+    `${vault.name} did not confirm ${what}. It may have been applied: check the vault before trying again.`,
+    { vaultId: vault.id },
+  );
+}
+
 async function providerFor(deps: ProviderWriteDeps, vault: VaultRow): Promise<VaultProvider> {
   try {
     return await deps.providers.forVault({
@@ -158,39 +315,62 @@ async function providerFor(deps: ProviderWriteDeps, vault: VaultRow): Promise<Va
   }
 }
 
+function mutationContext(deps: ProviderWriteDeps, vault: VaultRow): VaultProviderContext {
+  return {
+    connectionId: vault.providerConnectionId,
+    budget: deps.budget ?? { take() {} },
+    cacheEpoch: vault.providerCacheEpoch ?? null,
+    // Read-before-write must see the provider's current item, never a cached copy.
+    forceRefresh: true,
+    idempotencyKey: randomUUID(),
+  };
+}
+
+/** Refresh after a confirmed write; never turns the confirmed write into a failure. */
+async function refreshAfterWrite(
+  deps: ProviderWriteDeps,
+  vault: VaultRow,
+): Promise<ProviderVaultSyncResult["status"] | "error"> {
+  try {
+    const result = await syncLinkedProviderVault({
+      db: deps.db,
+      context: deps.context,
+      vaultId: vault.id,
+      providers: deps.providers,
+      force: true,
+      ...(deps.budget ? { budget: deps.budget } : {}),
+    });
+    return result.status;
+  } catch {
+    return "error";
+  }
+}
+
 async function refreshAndFind(
   deps: ProviderWriteDeps,
   vault: VaultRow,
   providerItemRef: string,
-): Promise<string> {
-  await syncLinkedProviderVault({
-    db: deps.db,
-    context: deps.context,
-    vaultId: vault.id,
-    providers: deps.providers,
-    force: true,
-    ...(deps.budget ? { budget: deps.budget } : {}),
-  });
+): Promise<ProviderWriteOutcome> {
+  const sync = await refreshAfterWrite(deps, vault);
   try {
     const ref = await getProviderVaultItemRef(deps.db, deps.context, {
       vaultId: vault.id,
       providerItemRef,
     });
-    return ref.itemId;
+    return { status: "listed", itemId: ref.itemId };
   } catch (error) {
     if (error instanceof VaultError && error.code === "vault_item_not_found") {
-      throw new VaultError(
-        "provider_unavailable",
-        "saved in the provider; Opengeni will show it after the next sync",
-        { vaultId: vault.id },
-      );
+      return { status: "saved_not_listed", vaultId: vault.id, sync };
     }
     throw error;
   }
 }
 
-/** Create (existing = null) or update an item in a connected read-write vault; returns its item id. */
-export async function writeProviderVaultItem(
+/**
+ * Create (existing = null) or update an item in a connected read-write vault
+ * and report whether the refreshed mirror lists it.
+ */
+export async function writeProviderVaultItemOutcome(
   deps: ProviderWriteDeps,
   input: {
     vault: VaultRow;
@@ -206,12 +386,29 @@ export async function writeProviderVaultItem(
     /** Receives the names of fields whose values were generated. */
     generated?: string[];
   },
-): Promise<string> {
+): Promise<ProviderWriteOutcome> {
   const { vault, existing, change } = input;
   assertProviderVaultWritable(vault);
-  if ((change.type ?? existing?.type) === "passkey") {
+  const type = change.type ?? existing?.type ?? "login";
+  if (type === "passkey") {
     throw new VaultError("vault_permission_denied", "passkeys live only in Opengeni vaults");
   }
+  const provider = await providerFor(deps, vault);
+  const operations = effectiveProviderOperations(vault, provider);
+  if (existing) {
+    if (!operations.updateItem) {
+      refuse(vault, "updateItem", `${vault.name} does not allow changing items here`);
+    }
+  } else if (!operations.createItemTypes.includes(type)) {
+    refuse(
+      vault,
+      "createItem",
+      operations.createItemTypes.length === 0
+        ? `${vault.name} does not allow creating items here`
+        : `${vault.name} cannot hold ${type} items; it accepts ${operations.createItemTypes.join(", ")}`,
+      { itemType: type, allowedItemTypes: operations.createItemTypes },
+    );
+  }
   let externalItemId: string | undefined;
   let expectedVersion: string | null | undefined;
   if (existing) {
@@ -231,58 +428,205 @@ export async function writeProviderVaultItem(
     externalItemId = ref.providerItemRef;
     expectedVersion = ref.providerVersion;
   }
-  const fields = await providerFieldWrites(
+  const planned = planFieldWrites(
+    vault,
+    operations,
+    existing === null,
     change.fields ?? [],
     existing?.fields ?? [],
-    deps.resolveReference,
-    input.generated ?? [],
   );
-  const provider = await providerFor(deps, vault);
+  const fields = await providerFieldValues(planned, deps.resolveReference, input.generated ?? []);
+  const name = change.name ?? existing?.name ?? "";
   let written;
   try {
-    written = await provider.writeItem(
-      { connectionId: vault.providerConnectionId, budget: deps.budget ?? { take() {} } },
-      vault.providerVaultRef ?? "",
+    written = await provider.writeItem(mutationContext(deps, vault), vault.providerVaultRef ?? "", {
+      ...(externalItemId ? { externalItemId, expectedVersion: expectedVersion ?? null } : {}),
+      name,
+      type,
+      websites: change.websites ?? existing?.websites ?? [],
+      fields,
+    });
+  } catch (error) {
+    return mutationFailure(vault, error, existing ? `the change to ${name}` : `saving ${name}`);
+  }
+  return await refreshAndFind(deps, vault, written.externalItemId);
+}
+
+/** Thrown when a confirmed provider write is not listed yet: it must not be saved again. */
+export function savedNotListedError(
+  vault: VaultRow,
+  itemName: string,
+  outcome: Extract<ProviderWriteOutcome, { status: "saved_not_listed" }>,
+): VaultError {
+  return new VaultError(
+    "provider_inventory_incomplete",
+    `Saved ${itemName} in ${vault.name}, but Opengeni could not list it yet. Do not save it again: it appears after the next successful sync.`,
+    { saved: true, vaultId: outcome.vaultId, itemName, sync: outcome.sync },
+  );
+}
+
+/**
+ * Create (existing = null) or update an item in a connected read-write vault;
+ * returns its item id. A confirmed write that is not listed yet throws
+ * `provider_inventory_incomplete` with `details.saved = true`.
+ */
+export async function writeProviderVaultItem(
+  deps: ProviderWriteDeps,
+  input: Parameters<typeof writeProviderVaultItemOutcome>[1],
+): Promise<string> {
+  const outcome = await writeProviderVaultItemOutcome(deps, input);
+  if (outcome.status === "listed") return outcome.itemId;
+  throw savedNotListedError(
+    input.vault,
+    input.change.name ?? input.existing?.name ?? "the item",
+    outcome,
+  );
+}
+
+/** Whether an item can leave this vault recoverably (moves need it before anything is written). */
+export function providerArchiveKind(
+  vault: VaultRow,
+  provider: Pick<VaultProvider, "capabilities"> | null,
+): "archive" | "trash" | null {
+  const operations = effectiveProviderOperations(vault, provider);
+  if (!operations.archiveItem) return null;
+  return operations.archiveKind === "archive" || operations.archiveKind === "trash"
+    ? operations.archiveKind
+    : null;
+}
+
+/**
+ * Refuses, before any value is read or written, an item a connected vault
+ * cannot receive as a new item (its type, a one-time password, or a file).
+ */
+export async function assertProviderVaultAccepts(
+  deps: ProviderWriteDeps,
+  vault: VaultRow,
+  item: { type: VaultItemType; fields: ReadonlyArray<{ kind: VaultFieldKind }> },
+): Promise<void> {
+  assertProviderVaultWritable(vault);
+  if (item.type === "passkey") {
+    throw new VaultError("vault_permission_denied", "passkeys live only in Opengeni vaults");
+  }
+  if (item.fields.some((field) => field.kind === "file")) {
+    throw new VaultError(
+      "provider_unavailable",
+      "files in connected vaults are read-only in Opengeni; copy the item into an Opengeni vault instead",
+      { vaultId: vault.id, operation: "writeFiles" },
+    );
+  }
+  const operations = effectiveProviderOperations(vault, await providerFor(deps, vault));
+  if (!operations.createItemTypes.includes(item.type)) {
+    refuse(
+      vault,
+      "createItem",
+      operations.createItemTypes.length === 0
+        ? `${vault.name} does not allow creating items here`
+        : `${vault.name} cannot hold ${item.type} items; it accepts ${operations.createItemTypes.join(", ")}`,
+      { itemType: item.type, allowedItemTypes: operations.createItemTypes },
+    );
+  }
+  if (item.fields.some((field) => field.kind === "totp") && !operations.createTotp) {
+    refuse(vault, "createTotp", `${vault.name} does not allow saving one-time passwords`);
+  }
+}
+
+/**
+ * Refuses a move out of a connected vault that cannot archive the original
+ * recoverably (copy instead); returns where the original will go.
+ */
+export async function assertProviderVaultReleases(
+  deps: ProviderWriteDeps,
+  vault: VaultRow,
+): Promise<"archive" | "trash"> {
+  assertProviderVaultWritable(vault);
+  const archiveKind = providerArchiveKind(vault, await providerFor(deps, vault));
+  if (archiveKind === null) {
+    refuse(
+      vault,
+      "archiveItem",
+      `${vault.name} cannot archive the original recoverably, so the item cannot be moved out of it; copy it instead`,
+    );
+  }
+  return archiveKind;
+}
+
+/** What a fresh provider listing says about one mirrored item. */
+export type ProviderItemObservation =
+  | { listed: true; version: string | null }
+  | { listed: false; consistent: boolean };
+
+/**
+ * The provider's current version of one item, from a fresh listing of its
+ * vault (provider caches bypassed). `version` is null when the provider does
+ * not version items. A provider failure is thrown as a `VaultError`.
+ *
+ * The provider contract has no conditional (compare-and-archive) operation,
+ * so this only narrows the window between reading an item and archiving it;
+ * it cannot close it.
+ */
+export async function observeProviderItemVersion(
+  deps: ProviderWriteDeps,
+  input: { vault: VaultRow; providerItemRef: string },
+): Promise<ProviderItemObservation> {
+  const { vault } = input;
+  const provider = await providerFor(deps, vault);
+  try {
+    const inventory = await readProviderItemInventory(
+      provider,
       {
-        ...(externalItemId ? { externalItemId, expectedVersion: expectedVersion ?? null } : {}),
-        name: change.name ?? existing?.name ?? "",
-        type: change.type ?? existing?.type ?? "login",
-        websites: change.websites ?? existing?.websites ?? [],
-        fields,
+        connectionId: vault.providerConnectionId,
+        budget: deps.budget ?? { take() {} },
+        cacheEpoch: vault.providerCacheEpoch ?? null,
+        forceRefresh: true,
       },
+      vault.providerVaultRef ?? "",
     );
+    const item = inventory.items.find((meta) => meta.externalItemId === input.providerItemRef);
+    if (!item) return { listed: false, consistent: inventory.consistent };
+    return {
+      listed: true,
+      version: typeof item.version === "string" && item.version.length > 0 ? item.version : null,
+    };
   } catch (error) {
-    return providerFailure(error);
+    if (isVaultProviderError(error)) {
+      throw new VaultError(vaultErrorCodeForProvider(error.code, "vault"), error.message, {
+        vaultId: vault.id,
+        ...(error.retryAfterMs ? { retryAfterMs: error.retryAfterMs } : {}),
+      });
+    }
+    throw error;
   }
-  return await refreshAndFind(deps, vault, written.externalItemId);
 }
 
-/** Archive an item in a connected read-write vault (the provider keeps it recoverable). */
+/**
+ * Archive an item in a connected read-write vault. Only a recoverable archive
+ * (the provider's archive or trash) is ever used; permanent deletion is not.
+ */
 export async function archiveProviderVaultItem(
   deps: ProviderWriteDeps,
   input: { vault: VaultRow; itemId: string },
-): Promise<void> {
-  assertProviderVaultWritable(input.vault);
+): Promise<{ archiveKind: "archive" | "trash" }> {
+  const { vault } = input;
+  assertProviderVaultWritable(vault);
   const ref = await getProviderVaultItemRef(deps.db, deps.context, {
-    vaultId: input.vault.id,
+    vaultId: vault.id,
     itemId: input.itemId,
   });
-  const provider = await providerFor(deps, input.vault);
+  const provider = await providerFor(deps, vault);
+  const archiveKind = providerArchiveKind(vault, provider);
+  if (archiveKind === null) {
+    refuse(vault, "archiveItem", `${vault.name} does not allow archiving items here`);
+  }
   try {
     await provider.archiveItem(
-      { connectionId: input.vault.providerConnectionId, budget: deps.budget ?? { take() {} } },
-      input.vault.providerVaultRef ?? "",
+      mutationContext(deps, vault),
+      vault.providerVaultRef ?? "",
       ref.providerItemRef,
     );
   } catch (error) {
-    providerFailure(error);
+    mutationFailure(vault, error, "archiving the item");
   }
-  await syncLinkedProviderVault({
-    db: deps.db,
-    context: deps.context,
-    vaultId: input.vault.id,
-    providers: deps.providers,
-    force: true,
-    ...(deps.budget ? { budget: deps.budget } : {}),
-  });
+  await refreshAfterWrite(deps, vault);
+  return { archiveKind };
 }