@opengeni/core 3.1.2 → 3.2.2

package/dist/dependencies.d.ts

@@ -3,6 +3,7 @@ import type { Document, DocumentAuthorityKind, EntitlementsPort, GitHubAppApiPor
 import type { Database, SessionWorkflowWakeDeliveryResult } from "@opengeni/db";
 import type { VaultConnectionCredentialsPort } from "@opengeni/vaults";
 import type { OnePasswordVaultProviderFactory } from "./domain/vaults/provider-registry.js";
+import type { ExternalVaultProviderFactories } from "./domain/vaults/external-provider-connections.js";
 import type { DocumentServices } from "@opengeni/documents";
 import type { EventBus } from "@opengeni/events";
 import type { Observability } from "@opengeni/observability";
@@ -192,6 +193,8 @@ export type AppDependencies = {
      * 1Password vaults report `provider_unavailable`.
      */
     onePasswordVaultProvider?: OnePasswordVaultProviderFactory | null;
+    /** Lazy native/remote vault adapters; null disables the first-wave integrations. */
+    externalVaultProviders?: ExternalVaultProviderFactories | null;
     /**
      * Optional embedding-host session ACL. Unset preserves standalone workspace
      * authorization; once bound, every session-addressed surface fails closed on

package/dist/domain/vaults/external-provider-connections.d.ts

@@ -0,0 +1,126 @@
+import { type Settings } from "@opengeni/config";
+import { ExternalVaultProviderKind, VaultProviderCredentials, VaultProviderOperations, type ConnectionMetadata } from "@opengeni/contracts";
+import { type Database } from "@opengeni/db";
+import { type VaultProvider, type VaultProviderAuthority } from "@opengeni/vaults";
+import { z } from "zod";
+export declare const EXTERNAL_VAULT_CREDENTIAL_ROLE = "external_vault_provider";
+declare const ExternalVaultConnectionDetails: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        bitwarden: "bitwarden";
+        external: "external";
+        keeper: "keeper";
+        protonpass: "protonpass";
+    }>;
+    ownership: z.ZodEnum<{
+        organization: "organization";
+        user: "user";
+        workspace: "workspace";
+    }>;
+    accountId: z.ZodNullable<z.ZodString>;
+    accountName: z.ZodNullable<z.ZodString>;
+    label: z.ZodNullable<z.ZodString>;
+    verifiedAt: z.ZodString;
+    operations: z.ZodObject<{
+        createItemTypes: z.ZodArray<z.ZodEnum<{
+            api_key: "api_key";
+            file: "file";
+            login: "login";
+            note: "note";
+            passkey: "passkey";
+        }>>;
+        updateItem: z.ZodBoolean;
+        removeField: z.ZodBoolean;
+        archiveItem: z.ZodBoolean;
+        archiveKind: z.ZodEnum<{
+            archive: "archive";
+            none: "none";
+            trash: "trash";
+        }>;
+        deleteItem: z.ZodLiteral<false>;
+        restoreItem: z.ZodBoolean;
+        readFiles: z.ZodBoolean;
+        writeFiles: z.ZodBoolean;
+        createTotp: z.ZodBoolean;
+        updateTotp: z.ZodBoolean;
+        createVault: z.ZodBoolean;
+        restoreFieldHistory: z.ZodBoolean;
+    }, z.core.$strict>;
+    verificationStatus: z.ZodOptional<z.ZodEnum<{
+        pending: "pending";
+        ready: "ready";
+    }>>;
+}, z.core.$strict>;
+export type ExternalVaultConnectionDetails = z.infer<typeof ExternalVaultConnectionDetails>;
+export declare function externalVaultProviderDomain(provider: ExternalVaultProviderKind): string;
+/** Metadata is a projection, never a credential/configuration passthrough. */
+export declare function externalVaultConnectionDetails(metadata: Record<string, unknown> | null | undefined): ExternalVaultConnectionDetails | null;
+export declare function isExternalVaultConnection(connection: ConnectionMetadata): boolean;
+/** Keeper bootstrap tokens are never a stored runtime credential. */
+export declare const StoredVaultProviderCredentials: z.ZodUnion<readonly [z.ZodObject<{
+    provider: z.ZodLiteral<"external">;
+    endpoint: z.ZodString;
+    signingSecret: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    provider: z.ZodLiteral<"bitwarden">;
+    endpoint: z.ZodString;
+    signingSecret: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    provider: z.ZodLiteral<"protonpass">;
+    token: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    provider: z.ZodLiteral<"keeper">;
+    configuration: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strict>]>;
+export type StoredVaultProviderCredentials = z.infer<typeof StoredVaultProviderCredentials>;
+/** Encrypted only: preserve the working credential while a reconnect is checked. */
+export declare function pendingVaultCredentialBundle(current: StoredVaultProviderCredentials | null, pending: StoredVaultProviderCredentials): Record<string, unknown>;
+export type ExternalVaultProviderFactory = (input: {
+    credentials: VaultProviderCredentials | StoredVaultProviderCredentials;
+    /** Stable native connection identity; adapter sessions must not cross it. */
+    connectionId?: string;
+    /** Includes credential binding and setup, before ordinary provider calls. */
+    signal?: AbortSignal;
+    /** Persist any later SDK key rotation before reporting successful readiness. */
+    persistCredentials?: (credentials: StoredVaultProviderCredentials) => Promise<void>;
+    /** Verified setup capabilities; the adapter may narrow, never widen them. */
+    operations?: VaultProviderOperations;
+}) => Promise<{
+    provider: VaultProvider;
+    credentials: StoredVaultProviderCredentials;
+}>;
+export type ExternalVaultProviderFactories = Partial<Record<ExternalVaultProviderKind, ExternalVaultProviderFactory>>;
+export declare function externalVaultConnectionMetadata(details: ExternalVaultConnectionDetails): Record<string, unknown>;
+/** Credentials can only be decrypted after the native reach and connection tuple agree. */
+export declare function loadExternalVaultConnection(db: Database, settings: Settings, input: {
+    workspaceId: string;
+    connectionId: string;
+    subjectId: string | null;
+    provider: ExternalVaultProviderKind;
+    /** Setup-only recovery, after independent connection-management authorization. */
+    allowPendingVerification?: boolean;
+}): Promise<{
+    connection: ConnectionMetadata;
+    details: ExternalVaultConnectionDetails;
+    credentials: StoredVaultProviderCredentials;
+    currentCredentials: StoredVaultProviderCredentials | null;
+    pendingCredentials: StoredVaultProviderCredentials | null;
+}>;
+/** A bound adapter never accepts model-supplied identity, even via a copied context. */
+export declare function bindVaultProviderAuthority(provider: VaultProvider, input: {
+    connectionId: string;
+    authority: VaultProviderAuthority;
+    operations: VaultProviderOperations;
+    revalidate: () => Promise<void>;
+}): VaultProvider;
+export declare function externalVaultProviderForConnection(input: {
+    db: Database;
+    settings: Settings;
+    workspaceId: string;
+    subjectId: string | null;
+    connectionId: string;
+    provider: ExternalVaultProviderKind;
+    factory: ExternalVaultProviderFactory;
+    executionContext?: Pick<VaultProviderAuthority, "sessionId" | "turnId" | "attemptId" | "siteId">;
+}): Promise<VaultProvider>;
+export {};

package/dist/domain/vaults/index.d.ts

@@ -1,7 +1,8 @@
 /** Vaults and secret references: the only import point for the vault domain. */
 export { buildMissingSecretAskCard } from "@opengeni/contracts";
 export { isVaultError, VaultError, vaultErrorFromDatabase } from "@opengeni/db";
-export { toVaultItem, toVaultItemSummary, toVaultSummary, vaultCanManage, vaultCanWrite, vaultItemReferences, type VaultCallerAuthority, } from "./mapping.js";
+export { intersectProviderOperations, providerOperationsForMode, storedProviderOperations, toVaultItem, toVaultItemSummary, toVaultSummary, vaultCanManage, vaultCanWrite, vaultItemReferences, type VaultCallerAuthority, } from "./mapping.js";
+export { effectiveProviderOperations, type ProviderWriteOperation, type ProviderWriteOutcome, } from "./provider-writes.js";
 export { chooseSecretCandidate, createSecretResolver, type SecretResolverOptions, } from "./secret-resolver.js";
 export type { VaultRequestActor, VaultServiceDeps } from "./types.js";
 export { createVaultService, vaultActorIsApiKey, type VaultService } from "./vault-service.js";

package/dist/domain/vaults/mapping.d.ts

@@ -3,7 +3,7 @@
  * contract shapes. Only text-kind field values are decrypted for display;
  * every other kind stays server-side until an audited reveal or a resolve.
  */
-import { type VaultItem, type VaultItemReferences, type VaultItemSummary, type VaultSummary } from "@opengeni/contracts";
+import { VaultProviderOperations, type VaultItem, type VaultItemReferences, type VaultItemSummary, type VaultMode, type VaultSummary } from "@opengeni/contracts";
 import { type VaultItemRow, type VaultRow } from "@opengeni/db";
 /** What the caller may do beyond reading; decided by the route's grant. */
 export type VaultCallerAuthority = {
@@ -12,9 +12,25 @@ export type VaultCallerAuthority = {
     /** `account:admin` on the organization */
     accountAdmin: boolean;
 };
+/** No writes at all: what a read-only link or a read-only provider vault allows. */
+export declare function withoutProviderWrites(operations: VaultProviderOperations): VaultProviderOperations;
+/** Operations both sides allow (an archive needs both to agree on its kind). */
+export declare function intersectProviderOperations(left: VaultProviderOperations, right: VaultProviderOperations): VaultProviderOperations;
+/**
+ * What a linked vault allows: the operations its provider last reported for
+ * it, narrowed by the link mode. Null for hosted vaults and for links not yet
+ * checked since operations were recorded (callers then ask the provider).
+ */
+export declare function storedProviderOperations(row: Pick<VaultRow, "source" | "mode"> & {
+    providerOperations?: VaultProviderOperations | null;
+}): VaultProviderOperations | null;
+export declare function providerOperationsForMode(operations: VaultProviderOperations, mode: VaultMode): VaultProviderOperations;
 export declare function vaultCanWrite(row: VaultRow, authority: VaultCallerAuthority): boolean;
 export declare function vaultCanManage(row: VaultRow, authority: VaultCallerAuthority): boolean;
-export declare function toVaultSummary(row: VaultRow, authority: VaultCallerAuthority): VaultSummary;
+export declare function toVaultSummary(row: VaultRow, authority: VaultCallerAuthority, options?: {
+    now?: Date;
+    refreshing?: boolean;
+}): VaultSummary;
 /**
  * Ready references for an item. Every reference names the vault and the field
  * (`{{secret:Vault/Item/field}}`), so it cannot become ambiguous when another

package/dist/domain/vaults/provider-registry.d.ts

@@ -1,7 +1,8 @@
 import type { Settings } from "@opengeni/config";
 import type { ConnectionMetadata, VaultErrorCode } from "@opengeni/contracts";
 import { type Database } from "@opengeni/db";
-import { type VaultProvider, type VaultProviderErrorCode, type VaultProviderRegistry } from "@opengeni/vaults";
+import { type VaultProvider, type VaultProviderErrorCode, type VaultProviderRegistry, type VaultProviderAuthority } from "@opengeni/vaults";
+import { type ExternalVaultProviderFactories } from "./external-provider-connections.js";
 /**
  * Provider error codes as vault API error codes (§10B.1.1). `provider_not_found`
  * is the vault (or, for reads, the field); `provider_permission_denied` is
@@ -69,4 +70,6 @@ export declare function createWorkspaceVaultProviderRegistry(input: {
     subjectId: string | null;
     hostVaultProvider?: VaultProvider | null;
     onePasswordVaultProvider?: OnePasswordVaultProviderFactory | null;
+    externalVaultProviders?: ExternalVaultProviderFactories | null;
+    executionContext?: Pick<VaultProviderAuthority, "sessionId" | "turnId" | "attemptId" | "siteId">;
 }): VaultProviderRegistry;

package/dist/domain/vaults/provider-sync.d.ts

@@ -1,14 +1,21 @@
-import { type VaultFieldKind, type VaultItemType, type VaultSyncStatus } from "@opengeni/contracts";
-import { type Database, type VaultDbContext } from "@opengeni/db";
+import { type VaultFieldKind, type VaultItemType, type VaultProviderFreshness, type VaultProviderOperations, type VaultSyncStatus } from "@opengeni/contracts";
+import { type Database, type StoredProviderFreshness, type VaultDbContext } from "@opengeni/db";
 import { type ProviderItemMeta, type VaultProvider, type VaultProviderContext, type VaultProviderErrorCode, type VaultProviderRegistry } from "@opengeni/vaults";
 /**
- * Provider vault metadata mirror (design §10.9, OP-1/OP-4). A linked
- * 1Password or host vault keeps a metadata-only mirror (item names, types,
+ * Provider vault metadata mirror (design §10.9, OP-1/OP-4; external vaults
+ * §8–§9). A linked vault keeps a metadata-only mirror (item names, types,
  * websites, field names and kinds); values are always read live. A sync costs
- * one `listVaults` call and skips `listItems` entirely when the provider's
+ * one vault listing and skips the item listing entirely when the provider's
  * `contentVersion` is unchanged, so FAMILY-plan quotas are not burnt on
  * no-op refreshes.
  *
+ * Only a complete, consistent traversal replaces the mirror: interrupted,
+ * malformed or over-limit inventories (more than `VAULT_LIMITS.itemsPerVault`
+ * items, or an item beyond the per-item field and website limits) and
+ * multi-page listings without a snapshot keep the previous mirror and record
+ * `provider_inventory_incomplete`. Nothing is cut down to fit. An active
+ * provider rate limit is never bypassed, not even by a forced refresh.
+ *
  * The engine is storage-agnostic: the vault service binds `ProviderMirrorStore`
  * to its tables (`vault_items`, `vault_item_fields`, `vaults.sync_status`,
  * `vaults.rate_limited_until`).
@@ -36,7 +43,12 @@ export interface ProviderMirrorItem {
 export interface ProviderMirrorPlan {
     contentVersion: string | null;
     items: ProviderMirrorItem[];
-    /** Items beyond `VAULT_LIMITS.itemsPerVault` that were not mirrored. */
+    /**
+     * Always 0. A provider vault with more than `VAULT_LIMITS.itemsPerVault`
+     * items, or an item beyond the field or website limits, is refused whole
+     * (`provider_inventory_incomplete`), never mirrored as its first items or
+     * fields. Kept for compatibility with earlier callers.
+     */
     truncated: number;
 }
 export interface ProviderSyncStatusUpdate {
@@ -46,17 +58,29 @@ export interface ProviderSyncStatusUpdate {
     rateLimitedUntil: Date | null;
     /** Set only when the provider was reached and the mirror is current. */
     lastSyncedAt: Date | null;
+    /**
+     * The provider's effective operations for this vault, recorded on every
+     * successful check (absent: keep the stored operations).
+     */
+    operations?: VaultProviderOperations | null;
+    /**
+     * The provider's own upstream freshness observation from this check; null
+     * when it reported none (absent: keep the stored observation). Never
+     * Opengeni's own check time.
+     */
+    freshness?: StoredProviderFreshness | null;
 }
 export interface ProviderMirrorStore {
-    /** Replace the mirror for this vault in one transaction (upsert by external id, drop missing). */
-    replaceMirror(plan: ProviderMirrorPlan): Promise<void>;
-    setSyncStatus(update: ProviderSyncStatusUpdate): Promise<void>;
+    /** Atomically commit mirror and status if the pre-I/O epoch still matches. */
+    settleRefresh(update: ProviderSyncStatusUpdate, plan?: ProviderMirrorPlan): Promise<boolean>;
 }
 export interface ProviderVaultSyncTarget {
     externalVaultId: string;
     /** `contentVersion` recorded by the last successful mirror, if any. */
     mirroredContentVersion: string | null;
     rateLimitedUntil: Date | null;
+    /** The vault's durable value-cache epoch (0789), passed to the provider as `cacheEpoch`. */
+    cacheEpoch?: string | null;
 }
 export type ProviderVaultSyncResult = {
     status: "synced";
@@ -66,6 +90,10 @@ export type ProviderVaultSyncResult = {
 } | {
     status: "unchanged";
     contentVersion: string | null;
+}
+/** Another refresh settled after this one's read; no state was overwritten. */
+ | {
+    status: "superseded";
 } | {
     status: "skipped_rate_limited";
     rateLimitedUntil: Date;
@@ -91,15 +119,35 @@ export declare function providerPrimaryFieldId(item: Pick<ProviderItemMeta, "typ
  * Deterministic mirror projection. Items are ordered by provider name then
  * external id before de-duplication, so the same provider state always yields
  * the same Opengeni names; field names are de-duplicated within each item.
+ * More than `VAULT_LIMITS.itemsPerVault` items, or any item beyond the field
+ * or website limits, is refused with `provider_inventory_incomplete`: a
+ * partial mirror would present the first items (or fields, or websites) of a
+ * larger vault as its complete contents.
  */
 export declare function planProviderMirror(items: readonly ProviderItemMeta[], contentVersion: string | null): ProviderMirrorPlan;
+/**
+ * One freshness observation for a whole check: `cache` when any page came
+ * from a cache, `live` only when every page was live, otherwise `unknown`.
+ * `sourceSyncedAt` is the oldest upstream synchronization any page reported
+ * (never later than the check itself), and unknown (null) when a non-live
+ * page did not say. Null when the provider reported nothing: Opengeni's own
+ * check time never stands in for the provider's.
+ */
+export declare function aggregateProviderFreshness(observations: readonly VaultProviderFreshness[], checkedAt: Date): StoredProviderFreshness | null;
 /** Sync status for a provider failure; rate limits persist `rateLimitedUntil`. */
 export declare function providerSyncFailure(error: unknown, now: Date): ProviderSyncStatusUpdate & {
     syncErrorCode: VaultProviderErrorCode;
 };
 /**
  * Refresh one linked vault's mirror. While `rateLimitedUntil` is in the future
- * the provider is not called at all unless `force` is set.
+ * the provider is not called at all, even when `force` is set.
+ *
+ * `force` re-lists items even when `contentVersion` is unchanged and asks the
+ * provider to bypass its caches (`forceRefresh`). Every successful check
+ * records the provider's effective operations and its own freshness
+ * observation, whether or not the mirror changed. Mirror and status settle
+ * together against the pre-I/O epoch; an intervening settlement returns
+ * `superseded` without overwriting it or retrying provider calls.
  */
 export declare function syncProviderVault(input: {
     provider: VaultProvider;
@@ -107,14 +155,16 @@ export declare function syncProviderVault(input: {
     target: ProviderVaultSyncTarget;
     store: ProviderMirrorStore;
     now?: () => Date;
-    /** Re-list items even when `contentVersion` is unchanged. */
+    /** Re-list items even when `contentVersion` is unchanged, bypassing provider caches. */
     force?: boolean;
 }): Promise<ProviderVaultSyncResult>;
-/** Binds the mirror store to the 0739 routines for one connected vault. */
-export declare function databaseProviderMirrorStore(db: Database, context: VaultDbContext, vaultId: string): ProviderMirrorStore;
+/** Binds atomic settlement to the epoch read before provider I/O (0789). */
+export declare function databaseProviderMirrorStore(db: Database, context: VaultDbContext, vaultId: string, expectedCacheEpoch: string): ProviderMirrorStore;
 /**
  * Sync one linked vault the caller reaches: load its provider refs and mirror
  * version, resolve its provider, refresh the mirror and record sync status.
+ * The provider context carries the vault's durable cache epoch; the
+ * registry binds the trusted authority, never this caller.
  */
 export declare function syncLinkedProviderVault(input: {
     db: Database;
@@ -122,8 +172,12 @@ export declare function syncLinkedProviderVault(input: {
     vaultId: string;
     providers: VaultProviderRegistry;
     budget?: VaultProviderContext["budget"];
+    /** Re-list items and bypass provider caches; an active rate limit still applies. */
     force?: boolean;
     now?: () => Date;
+    signal?: AbortSignal;
+    /** Runtime-only observation of the provider's freshness reports. */
+    onFreshness?: VaultProviderContext["onFreshness"];
 }): Promise<ProviderVaultSyncResult>;
 /** How stale a linked vault's mirror may be before a search refreshes it. */
 export declare const LINKED_VAULT_SEARCH_MAX_AGE_MS: number;
@@ -137,6 +191,12 @@ export declare const LINKED_VAULT_REFRESH_WAIT_MS = 8000;
  * the background and the next load shows it.
  */
 export declare const LINKED_VAULT_OPEN_WAIT_MS = 3000;
+/**
+ * How long one background refresh may run. Afterwards it is abandoned for
+ * de-duplication, so one unresponsive provider cannot pin a vault as
+ * "refreshing" for every later caller.
+ */
+export declare const LINKED_VAULT_REFRESH_TIMEOUT_MS = 60000;
 /** The vault fields a freshness check needs (a `VaultRow` has them all). */
 export type LinkedVaultFreshness = {
     id: string;
@@ -145,6 +205,8 @@ export type LinkedVaultFreshness = {
     lastSyncedAt: string | null;
     rateLimitedUntil: string | null;
     updatedAt: string;
+    syncErrorCode?: string | null;
+    providerFreshness?: StoredProviderFreshness | null;
 };
 /**
  * Whether a linked vault's mirror is older than `maxAgeMs`. A vault whose last
@@ -154,15 +216,67 @@ export type LinkedVaultFreshness = {
  */
 export declare function linkedVaultNeedsRefresh(vault: LinkedVaultFreshness, maxAgeMs: number, now: Date): boolean;
 /**
- * Bring stale linked vault mirrors up to date, so items added in the provider
- * (for example straight in 1Password) are found without anyone pressing Sync.
- *
- * Each refresh is the ordinary non-forced sync: one `listVaults` call, and an
- * item listing only when the provider says the vault changed. Refreshes of the
- * same vault share one call per process. The caller waits at most `waitMs`;
- * slower refreshes finish in the background and record their own status.
- * Never throws: failures are recorded as the vault's sync status.
+ * The freshness a person or agent sees for a linked vault (design §9);
+ * undefined for hosted vaults. `lastCheckedAt` is Opengeni's last successful
+ * check; `source` and `sourceSyncedAt` are only what the provider itself
+ * reported then. `current` means checked successfully within `maxAgeMs`;
+ * `stale` means not recently checked (or a rate limit just lifted);
+ * `refreshing` means a check is running; `unavailable` means the last check
+ * failed, with its safe error code and, under a rate limit, the retry time.
+ */
+export declare function providerVaultFreshness(vault: LinkedVaultFreshness, now: Date, options?: {
+    maxAgeMs?: number;
+    refreshing?: boolean;
+}): VaultProviderFreshness | undefined;
+/**
+ * Whose refresh this is: concurrent refreshes share one provider call only
+ * within the same tenant, workspace and acting principal, because the
+ * provider registry (and its credential) is bound to that authority.
+ */
+export declare function vaultRefreshScopeKey(context: VaultDbContext): string;
+export type LinkedVaultRefreshOutcome = {
+    vaultId: string;
+    /**
+     * `not_due`: hosted, recently checked, or under an active rate limit (no
+     * provider call); `pending`: still running when the wait ended; `done`:
+     * finished with `result`; `failed`: the refresh itself failed unexpectedly.
+     */
+    state: "not_due" | "pending" | "done" | "failed";
+    result: ProviderVaultSyncResult | null;
+};
+export type LinkedVaultRefreshReport = {
+    outcomes: LinkedVaultRefreshOutcome[];
+    /** Vaults whose mirror changed before the wait ended. */
+    changed: string[];
+    /** Vaults whose refresh was still running when the wait ended. */
+    pending: string[];
+};
+/**
+ * Bring linked vault mirrors up to date, so items added in the provider (for
+ * example straight in 1Password) are found without anyone pressing Sync.
  *
+ * Without `force`, only vaults older than `maxAgeMs` refresh, with the
+ * ordinary sync (one vault listing; an item listing only when the provider
+ * says the vault changed). `force` re-lists every given provider vault and
+ * bypasses provider caches, but never an active rate limit. Refreshes of the
+ * same vault by the same principal share one call per process. The caller
+ * waits at most `waitMs`; slower refreshes finish in the background and
+ * record their own status. Never throws: failures are recorded as the vault's
+ * sync status.
+ */
+export declare function refreshLinkedVaults(input: {
+    db: Database;
+    context: VaultDbContext;
+    vaults: readonly LinkedVaultFreshness[];
+    providers: VaultProviderRegistry;
+    /** Refresh vaults whose last check is at least this old (default: the search age). */
+    maxAgeMs?: number;
+    force?: boolean;
+    waitMs?: number;
+    now?: () => Date;
+}): Promise<LinkedVaultRefreshReport>;
+/**
+ * The ordinary stale refresh (`refreshLinkedVaults` without `force`).
  * Returns the ids of the vaults whose mirror changed before the wait ended.
  */
 export declare function refreshStaleLinkedVaults(input: {

package/dist/domain/vaults/provider-writes.d.ts

@@ -1,11 +1,20 @@
-import { type VaultFieldInput, type VaultFieldKind, type VaultItemType } from "@opengeni/contracts";
-import { type Database, type VaultDbContext, type VaultFieldRow, type VaultRow } from "@opengeni/db";
-import { type ProviderCallBudget, type VaultProviderRegistry } from "@opengeni/vaults";
+import { type VaultFieldInput, type VaultFieldKind, type VaultItemType, type VaultProviderOperations } from "@opengeni/contracts";
+import { VaultError, type Database, type VaultDbContext, type VaultFieldRow, type VaultRow } from "@opengeni/db";
+import { type ProviderCallBudget, type VaultProvider, type VaultProviderRegistry } from "@opengeni/vaults";
+import { type ProviderVaultSyncResult } from "./provider-sync.js";
 /**
- * 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. */
 export interface ProviderFieldChange {
@@ -33,10 +42,38 @@ export interface ProviderWriteDeps {
     resolveReference: (raw: string) => Promise<string>;
     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";
+};
 /** A connected vault the caller may change items in. */
 export declare function assertProviderVaultWritable(vault: VaultRow): void;
-/** Create (existing = null) or update an item in a connected read-write vault; returns its item id. */
-export declare function writeProviderVaultItem(deps: ProviderWriteDeps, input: {
+/**
+ * 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 declare function effectiveProviderOperations(vault: VaultRow, provider: Pick<VaultProvider, "capabilities"> | null): VaultProviderOperations;
+/** Refuses a provider operation Opengeni never performs, with the reason. */
+export declare function refuseProviderOperation(vault: VaultRow, operation: Extract<ProviderWriteOperation, "deleteItem" | "restoreItem" | "restoreFieldHistory">): never;
+/**
+ * Create (existing = null) or update an item in a connected read-write vault
+ * and report whether the refreshed mirror lists it.
+ */
+export declare function writeProviderVaultItemOutcome(deps: ProviderWriteDeps, input: {
     vault: VaultRow;
     existing: {
         itemId: string;
@@ -49,9 +86,62 @@ export declare function writeProviderVaultItem(deps: ProviderWriteDeps, input: {
     change: ProviderItemChange;
     /** Receives the names of fields whose values were generated. */
     generated?: string[];
-}): Promise<string>;
-/** Archive an item in a connected read-write vault (the provider keeps it recoverable). */
+}): Promise<ProviderWriteOutcome>;
+/** Thrown when a confirmed provider write is not listed yet: it must not be saved again. */
+export declare function savedNotListedError(vault: VaultRow, itemName: string, outcome: Extract<ProviderWriteOutcome, {
+    status: "saved_not_listed";
+}>): VaultError;
+/**
+ * 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 declare function writeProviderVaultItem(deps: ProviderWriteDeps, input: Parameters<typeof writeProviderVaultItemOutcome>[1]): Promise<string>;
+/** Whether an item can leave this vault recoverably (moves need it before anything is written). */
+export declare function providerArchiveKind(vault: VaultRow, provider: Pick<VaultProvider, "capabilities"> | null): "archive" | "trash" | 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 declare function assertProviderVaultAccepts(deps: ProviderWriteDeps, vault: VaultRow, item: {
+    type: VaultItemType;
+    fields: ReadonlyArray<{
+        kind: VaultFieldKind;
+    }>;
+}): Promise<void>;
+/**
+ * Refuses a move out of a connected vault that cannot archive the original
+ * recoverably (copy instead); returns where the original will go.
+ */
+export declare function assertProviderVaultReleases(deps: ProviderWriteDeps, vault: VaultRow): Promise<"archive" | "trash">;
+/** 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 declare function observeProviderItemVersion(deps: ProviderWriteDeps, input: {
+    vault: VaultRow;
+    providerItemRef: string;
+}): Promise<ProviderItemObservation>;
+/**
+ * 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 declare function archiveProviderVaultItem(deps: ProviderWriteDeps, input: {
     vault: VaultRow;
     itemId: string;
-}): Promise<void>;
+}): Promise<{
+    archiveKind: "archive" | "trash";
+}>;

package/dist/domain/vaults/remote-provider-runtime.d.ts

@@ -0,0 +1,7 @@
+import type { Settings } from "@opengeni/config";
+import { pinnedFetch, type OutboundNetworkSettings } from "@opengeni/network";
+import { type RemoteVaultTransport } from "@opengeni/vaults";
+import type { ExternalVaultProviderFactories } from "./external-provider-connections.js";
+/** Shared by API and worker. No credential-bearing request uses ambient fetch. */
+export declare function createPinnedRemoteVaultTransport(settings: OutboundNetworkSettings, fetchImpl?: typeof pinnedFetch): RemoteVaultTransport;
+export declare function createRemoteExternalVaultFactories(settings: Pick<Settings, "environment" | "integrationsAllowPrivateNetworkTargets">): ExternalVaultProviderFactories;

package/dist/domain/vaults/secret-resolver.d.ts

@@ -4,9 +4,19 @@
  * chosen here (archived dropped, lowest tier, names over aliases, otherwise
  * ambiguous), provider values are fetched, hosted values decrypted, and the
  * batch is recorded. A call resolves all of its references or none (I2).
+ *
+ * A reference that finds nothing first refreshes the connected vaults that
+ * could change the answer: those that could hold it at the priority tier that
+ * decided the lookup or above, even when a hosted item matched without the
+ * field. When one of those could not be checked (unreachable, rate limited,
+ * needing reconnection or still refreshing), the failure names that source
+ * instead of reporting the secret missing, so no missing-secret ask card is
+ * made for a secret that may exist (external vaults §9). Hosted and
+ * explicitly named healthy vaults are never blocked by unrelated outages, and
+ * lower-priority vaults never block a miss a higher tier decided.
  */
 import { type SecretPrincipal, type SecretReference, type SecretReferenceFailure, type SecretResolver } from "@opengeni/contracts";
-import { type SecretReferenceCandidate, type SecretResolutionMeta } from "@opengeni/db";
+import { type SecretReferenceCandidate, type SecretResolutionMeta, type VaultRow } from "@opengeni/db";
 import { type ProviderCallBudget, type VaultProviderRegistry } from "@opengeni/vaults";
 import type { VaultServiceDeps } from "./types.js";
 export type SecretResolverOptions = {
@@ -31,4 +41,22 @@ export declare function chooseSecretCandidate(reference: SecretReference, candid
 } | {
     failure: SecretReferenceFailure;
 };
+/**
+ * The connected vaults whose mirror decides a reference that found nothing.
+ *
+ * Where the item could be: the vault a three-segment reference names; for two
+ * segments the named vault when the first segment names one (else every
+ * connected vault, since it may be `Item/field`); every connected vault for a
+ * bare item name; none for an ID.
+ *
+ * When some item matched but lacks the field (or the one-time password), the
+ * lookup keeps the highest-priority tier, so only vaults at that tier or above
+ * can change the answer: the connected vaults of matched items there that lack
+ * the field, and the connected vaults that could hold the item there but have
+ * no match yet. A hosted match never hides a higher-priority connected vault
+ * whose provider gained the item or its one-time password, and a vault of a
+ * lower-priority tier that is out of date or unavailable never turns a
+ * definite miss into an unchecked one.
+ */
+export declare function relevantProviderVaults(reference: SecretReference, candidates: readonly SecretReferenceCandidate[], reachable: readonly VaultRow[]): VaultRow[];
 export declare function createSecretResolver(deps: VaultServiceDeps, principal: SecretPrincipal, opts: SecretResolverOptions): SecretResolver;