@opengeni/vaults-keeper 0.0.0-stage → 3.2.2

package/src/bootstrap.ts

@@ -0,0 +1,182 @@
+import { VaultProviderError } from "./contract";
+import {
+  KEEPER_DEFAULT_ALLOWED_HOSTS,
+  KEEPER_REGION_HOSTS,
+  assertAllowedHost,
+  memoryKeeperStorage,
+  parseKeeperConfiguration,
+  serializeKeeperConfiguration,
+} from "./config";
+import { mapKeeperMutationError } from "./errors";
+import {
+  type KeeperRuntimeOptions,
+  type KeeperVaultProvider,
+  type PersistKeeperConfiguration,
+  createKeeperVaultProvider,
+  runKeeperOperation,
+} from "./provider";
+import { createKeeperSdkLoader } from "./sdk";
+
+export interface KeeperBootstrapOptions extends KeeperRuntimeOptions {
+  /** One-time access token, `REGION:key` (for example `US:…`), or a bare key with `hostname`. */
+  oneTimeToken: string;
+  /** Region host for a token without a region prefix. */
+  hostname?: string;
+  signal?: AbortSignal;
+  /**
+   * Awaited with the bound configuration (`previous: null`, `reason: "bind"`)
+   * as soon as Keeper has accepted the token, before bootstrap returns or
+   * reports a later failure. The token is spent at that point, so this is the
+   * only copy of the credential.
+   */
+  persistConfiguration?: PersistKeeperConfiguration;
+}
+
+export interface KeeperBootstrapResult {
+  /** Bound KSM configuration (JSON). Store it encrypted; it is the connection's credential. */
+  configuration: string;
+  /** The Secrets Manager application's title. */
+  accountName: string | null;
+}
+
+const TOKEN_PART = /^[A-Za-z0-9_-]{16,128}$/;
+
+function invalidToken(): never {
+  throw new VaultProviderError(
+    "provider_auth_invalid",
+    "That is not a Keeper Secrets Manager one-time access token",
+  );
+}
+
+/** The region host a token names, checked against the allowlist before any network call. */
+export function keeperTokenHost(oneTimeToken: string, hostname?: string): string {
+  const parts = oneTimeToken.trim().split(":");
+  if (parts.length === 1) {
+    if (!TOKEN_PART.test(parts[0]!)) invalidToken();
+    if (!hostname) {
+      throw new VaultProviderError(
+        "provider_auth_invalid",
+        "This one-time token has no region prefix; choose the Keeper region",
+      );
+    }
+    return hostname;
+  }
+  if (parts.length !== 2 && !(parts.length === 4 && parts[0]!.toUpperCase() === "IL5"))
+    invalidToken();
+  if (!TOKEN_PART.test(parts[1]!)) invalidToken();
+  const region = parts[0]!.toUpperCase() as keyof typeof KEEPER_REGION_HOSTS;
+  return KEEPER_REGION_HOSTS[region] ?? parts[0]!;
+}
+
+/**
+ * Redeems a one-time access token once: generates the client key pair in
+ * memory, binds it with the first `get_secret` call, and returns the bound
+ * configuration. The token is never retried; an ambiguous failure means the
+ * customer must generate a new token.
+ */
+export async function bootstrapKeeperConfiguration(
+  options: KeeperBootstrapOptions,
+): Promise<KeeperBootstrapResult> {
+  const token = options.oneTimeToken.trim();
+  const allowed = (options.allowedHosts ?? KEEPER_DEFAULT_ALLOWED_HOSTS).map((host) =>
+    host.toLowerCase(),
+  );
+  assertAllowedHost(keeperTokenHost(token, options.hostname), allowed);
+  const loader = options.sdk ?? createKeeperSdkLoader();
+  let tracker: { sent: number; lastStatus: number | null; mutating: boolean } | null = null;
+  let bindStorage: ReturnType<typeof memoryKeeperStorage> | null = null;
+  let accountName: string | null = null;
+  let failure: unknown = null;
+  try {
+    await runKeeperOperation({
+      runtime: options,
+      loader,
+      config: new Map(),
+      hostInConfig: false,
+      ...(options.signal ? { signal: options.signal } : {}),
+      work: async (keeper, storage) => {
+        tracker = keeper.tracker;
+        bindStorage = storage;
+        await keeper.sdk.initializeStorage(storage, token, options.hostname);
+        assertAllowedHost(storage.values.get("hostname"), allowed);
+        keeper.tracker.mutating = true;
+        const secrets = await keeper.sdk.getSecrets2(keeper.options);
+        keeper.tracker.mutating = false;
+        const title = secrets.appData?.title;
+        accountName = typeof title === "string" && title.trim() ? title.trim().slice(0, 200) : null;
+      },
+    });
+  } catch (error) {
+    failure = error;
+  }
+
+  // Keeper binds the key pair when it answers the first request. Once the
+  // SDK has unwrapped the app key the token is spent, so the configuration is
+  // kept (and persisted) even if something after the bind failed.
+  const bound = bindStorage as ReturnType<typeof memoryKeeperStorage> | null;
+  if (bound?.values.get("appKey")) {
+    bound.values.delete("clientKey");
+    const configuration = serializeKeeperConfiguration(bound.values);
+    parseKeeperConfiguration(configuration);
+    if (options.persistConfiguration) {
+      try {
+        await options.persistConfiguration(configuration, { previous: null, reason: "bind" });
+      } catch {
+        throw new VaultProviderError(
+          "provider_unavailable",
+          "Keeper accepted the one-time token but Opengeni could not save the connection; generate a new token and connect again",
+        );
+      }
+    }
+    return { configuration, accountName };
+  }
+
+  try {
+    if (failure === null) {
+      throw new VaultProviderError(
+        "provider_outcome_unknown",
+        "Keeper did not complete binding; generate a new one-time token",
+      );
+    }
+    throw failure;
+  } catch (error) {
+    if (error instanceof VaultProviderError && error.code === "provider_outcome_unknown")
+      throw error;
+    const used = tracker as { sent: number; lastStatus: number | null; mutating: boolean } | null;
+    const mapped = used
+      ? mapKeeperMutationError(error, "redeem the one-time token", used)
+      : error instanceof VaultProviderError
+        ? error
+        : new VaultProviderError(
+            "provider_auth_invalid",
+            "Keeper could not use that one-time token",
+          );
+    if (mapped.code === "provider_outcome_unknown") {
+      throw new VaultProviderError(
+        "provider_outcome_unknown",
+        "Keeper may have redeemed the one-time token; generate a new one and connect again",
+      );
+    }
+    if (mapped.code === "provider_auth_invalid" || mapped.code === "provider_permission_denied") {
+      throw new VaultProviderError(
+        "provider_auth_invalid",
+        "Keeper rejected the one-time token (expired, already used, or IP-locked); generate a new one",
+      );
+    }
+    throw mapped;
+  }
+}
+
+/**
+ * Bootstrap, then a provider over the bound configuration. The configuration
+ * is persisted through `persistConfiguration` (reason `"bind"`) before this
+ * returns and before the provider makes any request.
+ */
+export async function bootstrapKeeperVaultProvider(
+  options: KeeperBootstrapOptions & { persistConfiguration: PersistKeeperConfiguration },
+): Promise<KeeperBootstrapResult & { provider: KeeperVaultProvider }> {
+  const { oneTimeToken: _token, hostname: _hostname, signal: _signal, ...runtime } = options;
+  const result = await bootstrapKeeperConfiguration(options);
+  const provider = createKeeperVaultProvider({ ...runtime, configuration: result.configuration });
+  return { ...result, provider };
+}

package/src/config.ts

@@ -0,0 +1,161 @@
+import { VaultProviderError } from "./contract";
+import type { KeyValueStorage } from "./sdk";
+
+/** Region prefixes of a one-time token (`US:…`), as mapped by SDK 17.6.0 `initializeStorage`. */
+export const KEEPER_REGION_HOSTS = {
+  US: "keepersecurity.com",
+  EU: "keepersecurity.eu",
+  AU: "keepersecurity.com.au",
+  GOV: "govcloud.keepersecurity.us",
+  JP: "keepersecurity.jp",
+  CA: "keepersecurity.ca",
+  IL5: "il5.keepersecurity.us",
+} as const;
+
+/**
+ * Hosts a configuration may talk to. The SDK treats an unknown token prefix
+ * as a host name, so without this list a crafted token or configuration could
+ * point Opengeni's server at an arbitrary host.
+ */
+export const KEEPER_DEFAULT_ALLOWED_HOSTS: readonly string[] = Object.values(KEEPER_REGION_HOSTS);
+
+/** Keys of the standard KSM JSON configuration. Bytes are standard base64. */
+export const KEEPER_CONFIG_KEYS = [
+  "hostname",
+  "clientId",
+  "clientKey",
+  "privateKey",
+  "appKey",
+  "appOwnerPublicKey",
+  "serverPublicKeyId",
+  "serverPublicKey",
+] as const;
+export type KeeperConfigKey = (typeof KEEPER_CONFIG_KEYS)[number];
+const KNOWN = new Set<string>(KEEPER_CONFIG_KEYS);
+
+export type KeeperConfigValues = Map<KeeperConfigKey, string>;
+
+function invalid(message: string): never {
+  throw new VaultProviderError("provider_auth_invalid", message);
+}
+
+/**
+ * Parses a bound KSM configuration (JSON, or base64 of JSON as Keeper tools
+ * export it, or the already parsed string record). Unknown keys are dropped;
+ * the client must already be bound (appKey present).
+ */
+export function parseKeeperConfiguration(
+  input: string | Readonly<Record<string, string>>,
+): KeeperConfigValues {
+  if (typeof input !== "string") {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+      return invalid("The Keeper configuration is not KSM JSON");
+    }
+    return valuesOf(input);
+  }
+  let text = input.trim();
+  if (!text.startsWith("{")) {
+    try {
+      text = Buffer.from(text, "base64").toString("utf8").trim();
+    } catch {
+      invalid("The Keeper configuration is not KSM JSON");
+    }
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return invalid("The Keeper configuration is not KSM JSON");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return invalid("The Keeper configuration is not KSM JSON");
+  }
+  return valuesOf(parsed as Record<string, unknown>);
+}
+
+function valuesOf(parsed: Readonly<Record<string, unknown>>): KeeperConfigValues {
+  const values: KeeperConfigValues = new Map();
+  for (const [key, value] of Object.entries(parsed)) {
+    if (!KNOWN.has(key)) continue;
+    if (typeof value !== "string" || value.length === 0 || value.length > 4096) {
+      invalid(`The Keeper configuration has an invalid ${key}`);
+    }
+    values.set(key as KeeperConfigKey, value);
+  }
+  for (const key of ["hostname", "clientId", "privateKey", "appKey"] as const) {
+    if (!values.get(key)) {
+      invalid(
+        key === "appKey"
+          ? "The Keeper configuration is not bound yet; connect with a one-time token"
+          : `The Keeper configuration has no ${key}`,
+      );
+    }
+  }
+  return values;
+}
+
+/** The canonical JSON form (sorted known keys) handed to the persistence callback. */
+export function serializeKeeperConfiguration(values: KeeperConfigValues): string {
+  const out: Record<string, string> = {};
+  for (const key of KEEPER_CONFIG_KEYS) {
+    const value = values.get(key);
+    if (value !== undefined) out[key] = value;
+  }
+  return JSON.stringify(out);
+}
+
+/** The canonical string record of a bound configuration, for structured storage. */
+export function keeperConfigurationRecord(
+  configuration: string | Readonly<Record<string, string>>,
+): Record<string, string> {
+  return JSON.parse(
+    serializeKeeperConfiguration(parseKeeperConfiguration(configuration)),
+  ) as Record<string, string>;
+}
+
+export function assertAllowedHost(
+  hostname: string | undefined,
+  allowed: readonly string[],
+): string {
+  const host = (hostname ?? "").trim().toLowerCase();
+  if (!host || !allowed.includes(host)) {
+    throw new VaultProviderError(
+      "provider_auth_invalid",
+      "The Keeper region host is not one Opengeni connects to",
+    );
+  }
+  return host;
+}
+
+/**
+ * In-memory KSM storage over a copy of the configuration. Nothing reaches
+ * disk; `changed` reports whether the SDK rewrote any persisted key (binding,
+ * server key rotation) so the caller can persist the new configuration.
+ */
+export function memoryKeeperStorage(initial: KeeperConfigValues = new Map()): KeyValueStorage & {
+  readonly values: KeeperConfigValues;
+  changed(): boolean;
+} {
+  const values: KeeperConfigValues = new Map(initial);
+  const before = serializeKeeperConfiguration(initial);
+  const set = (key: string, value: string) => {
+    // Session keys (folder, record and file keys) are never persisted by the
+    // SDK; only configuration keys arrive here.
+    if (!KNOWN.has(key)) throw new Error(`unexpected Keeper storage key ${key}`);
+    values.set(key as KeeperConfigKey, value);
+  };
+  return {
+    values,
+    changed: () => serializeKeeperConfiguration(values) !== before,
+    getString: async (key) => values.get(key as KeeperConfigKey),
+    saveString: async (key, value) => set(key, value),
+    getBytes: async (key) => {
+      const value = values.get(key as KeeperConfigKey);
+      return value === undefined ? undefined : new Uint8Array(Buffer.from(value, "base64"));
+    },
+    saveBytes: async (key, value) => set(key, Buffer.from(value).toString("base64")),
+    delete: async (key) => {
+      values.delete(key as KeeperConfigKey);
+    },
+  };
+}

package/src/connection.ts

@@ -0,0 +1,75 @@
+import { VaultProviderError, type VaultProviderOperations } from "./contract";
+import { bootstrapKeeperConfiguration } from "./bootstrap";
+import { keeperConfigurationRecord } from "./config";
+import {
+  type KeeperRuntimeOptions,
+  type KeeperVaultProvider,
+  createKeeperVaultProvider,
+} from "./provider";
+
+/** What a server stores for a Keeper connection: setup input, or the bound configuration. */
+export type KeeperConnectionCredentials =
+  | { oneTimeToken: string; hostname?: string }
+  | { configuration: string | Readonly<Record<string, string>> };
+
+/**
+ * Durable, encrypted storage for the bound configuration. Called with
+ * `reason: "bind"` when a one-time token is redeemed (before anything else
+ * runs) and `reason: "rotation"` when Keeper rotates its key.
+ */
+export type PersistKeeperConfigurationRecord = (
+  configuration: Record<string, string>,
+  context: { reason: "bind" | "rotation" },
+) => Promise<void>;
+
+export interface OpenKeeperConnectionOptions extends KeeperRuntimeOptions {
+  credentials: KeeperConnectionCredentials;
+  /** Required: without durable storage a redeemed token or a rotated key would be lost. */
+  persistConfiguration?: PersistKeeperConfigurationRecord;
+  /** Operations verified at setup; the provider narrows to them. */
+  operations?: VaultProviderOperations;
+  valueCacheMs?: number;
+  signal?: AbortSignal;
+}
+
+/**
+ * One Keeper connection for a server: redeems a one-time token or opens a
+ * stored configuration, and returns the provider with the bound configuration
+ * as a string record. The one-time token is never part of the result. Each
+ * call has its own provider; SDK state is per operation, so connections never
+ * share keys.
+ */
+export async function openKeeperConnection(
+  options: OpenKeeperConnectionOptions,
+): Promise<{ provider: KeeperVaultProvider; configuration: Record<string, string> }> {
+  const persist = options.persistConfiguration;
+  if (!persist) {
+    throw new VaultProviderError(
+      "provider_unavailable",
+      "Keeper connections need durable configuration storage on this server",
+    );
+  }
+  const { credentials, persistConfiguration: _persist, operations, signal, ...runtime } = options;
+  let configuration: Record<string, string>;
+  if ("oneTimeToken" in credentials) {
+    const bound = await bootstrapKeeperConfiguration({
+      ...runtime,
+      oneTimeToken: credentials.oneTimeToken,
+      ...(credentials.hostname ? { hostname: credentials.hostname } : {}),
+      ...(signal ? { signal } : {}),
+      persistConfiguration: (next, context) =>
+        persist(keeperConfigurationRecord(next), { reason: context.reason }),
+    });
+    configuration = keeperConfigurationRecord(bound.configuration);
+  } else {
+    configuration = keeperConfigurationRecord(credentials.configuration);
+  }
+  const provider = createKeeperVaultProvider({
+    ...runtime,
+    configuration,
+    ...(operations ? { operations } : {}),
+    persistConfiguration: (next, context) =>
+      persist(keeperConfigurationRecord(next), { reason: context.reason }),
+  });
+  return { provider, configuration };
+}

package/src/contract.ts

@@ -0,0 +1,29 @@
+/**
+ * The shared vault contracts this adapter implements, re-exported for the
+ * package's modules so every file names one source.
+ */
+export {
+  VaultProviderError,
+  type ProviderCallBudget,
+  type ProviderCallOperation,
+  type ProviderFieldMeta,
+  type ProviderFieldValue,
+  type ProviderItemMeta,
+  type ProviderVault,
+  type ProviderWriteField,
+  type ProviderWriteItem,
+  type VaultProvider,
+  type VaultProviderAuthority,
+  type VaultProviderCapabilities,
+  type VaultProviderContext,
+  type VaultProviderErrorCode,
+} from "@opengeni/vaults";
+export {
+  VAULT_LIMITS,
+  parseTotpInput,
+  type SecretMaterial,
+  type TotpParams,
+  type VaultFieldKind,
+  type VaultItemType,
+  type VaultProviderOperations,
+} from "@opengeni/contracts";

package/src/errors.ts

@@ -0,0 +1,196 @@
+import { VaultProviderError } from "./contract";
+
+/**
+ * Keeper Secrets Manager errors as SDK 17.6.0 raises them: a non-200 response
+ * becomes `new Error(<first 1000 bytes of the body>)`, where the body is JSON
+ * such as `{"path":"…","result_code":"access_denied","message":"…"}` (older
+ * servers use `error` for the code); an empty error body becomes
+ * `unknown ksm error, code <status>`; exhausted throttle retries raise
+ * `KeeperThrottleError`; request deadlines raise `KeeperError("Request to …
+ * timed out after …ms")`. These shapes come from the SDK source and Keeper's
+ * documentation; Keeper does not publish a complete result-code table, so the
+ * message patterns below are deliberately conservative.
+ */
+const AUTH_HINT =
+  /signature|client ?id|clientid|one[- ]?time|token|expired|ip address|ip lock|locked out|not bound|unbound|device|revoked/i;
+const NOT_FOUND_HINT = /not found|does not exist|no such|unknown (?:record|folder)/i;
+const CONFLICT_HINT = /revision|out of (?:date|sync)|conflict|modified/i;
+
+export interface KeeperErrorBody {
+  code: string | null;
+  message: string;
+  retryAfterSeconds: number | null;
+}
+
+/** Parses the JSON error body the SDK embeds in its Error message. */
+export function keeperErrorBody(error: unknown): KeeperErrorBody | null {
+  if (!(error instanceof Error)) return null;
+  const text = error.message.trim();
+  if (!text.startsWith("{")) return null;
+  try {
+    const body = JSON.parse(text) as Record<string, unknown>;
+    const code = body.result_code ?? body.error;
+    const retry = body.retry_after;
+    return {
+      code: typeof code === "string" ? code.slice(0, 64) : null,
+      message: typeof body.message === "string" ? body.message : "",
+      retryAfterSeconds: typeof retry === "number" && retry >= 0 ? retry : null,
+    };
+  } catch {
+    // A body cut at 1000 bytes may not parse; fall back to the code alone.
+    const code = /"(?:result_code|error)"\s*:\s*"([a-z_]{1,64})"/.exec(text)?.[1] ?? null;
+    return { code, message: "", retryAfterSeconds: null };
+  }
+}
+
+function safeCode(code: string | null): string {
+  return code && /^[a-z0-9_]{1,64}$/i.test(code) ? code : "error";
+}
+
+export function isAbortLike(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  return (
+    error.name === "AbortError" ||
+    error.name === "TimeoutError" ||
+    /timed out after \d+ms/.test(error.message)
+  );
+}
+
+/**
+ * Maps any failure of a read-side operation. stderr-like SDK text never
+ * leaves this function; only a closed result code may appear in messages.
+ */
+export function mapKeeperError(error: unknown, subject: string): VaultProviderError {
+  if (error instanceof VaultProviderError) return error;
+  if (error instanceof Error && error.name === "KeeperThrottleError") {
+    return new VaultProviderError(
+      "provider_rate_limited",
+      "Keeper is rate limiting this application",
+      60_000,
+    );
+  }
+  if (isAbortLike(error)) {
+    return new VaultProviderError(
+      "provider_unavailable",
+      `Keeper did not answer in time (${subject})`,
+    );
+  }
+  const body = keeperErrorBody(error);
+  if (body) {
+    const { code, message } = body;
+    if (code === "throttled") {
+      return new VaultProviderError(
+        "provider_rate_limited",
+        "Keeper is rate limiting this application",
+        (body.retryAfterSeconds ?? 60) * 1000,
+      );
+    }
+    if (
+      code === "access_denied" ||
+      code === "invalid_client" ||
+      code === "invalid_client_version"
+    ) {
+      if (code !== "access_denied" || AUTH_HINT.test(message)) {
+        return new VaultProviderError(
+          "provider_auth_invalid",
+          "Keeper rejected this application's credentials; reconnect with a new one-time token",
+        );
+      }
+      if (NOT_FOUND_HINT.test(message)) {
+        return new VaultProviderError(
+          "provider_not_found",
+          "No such Keeper shared folder or record",
+        );
+      }
+      return new VaultProviderError(
+        "provider_permission_denied",
+        `The Keeper application may not ${subject}`,
+      );
+    }
+    if (
+      NOT_FOUND_HINT.test(message) ||
+      (code && /not_found|invalid_record|record_uid/.test(code))
+    ) {
+      return new VaultProviderError("provider_not_found", "No such Keeper shared folder or record");
+    }
+    if (CONFLICT_HINT.test(message) || (code && /revision|conflict/.test(code))) {
+      return new VaultProviderError(
+        "provider_conflict",
+        "The Keeper record changed since it was read; read it again before writing",
+      );
+    }
+    return new VaultProviderError(
+      "provider_unavailable",
+      `Keeper rejected the request (${safeCode(code)})`,
+    );
+  }
+  const status =
+    error instanceof Error ? /unknown ksm error, code (\d{3})/.exec(error.message)?.[1] : undefined;
+  if (status) {
+    const code = Number(status);
+    if (code === 401) {
+      return new VaultProviderError(
+        "provider_auth_invalid",
+        "Keeper rejected this application's credentials",
+      );
+    }
+    if (code === 403) {
+      return new VaultProviderError(
+        "provider_permission_denied",
+        `The Keeper application may not ${subject}`,
+      );
+    }
+    if (code === 404)
+      return new VaultProviderError("provider_not_found", "No such Keeper shared folder or record");
+    if (code === 429)
+      return new VaultProviderError(
+        "provider_rate_limited",
+        "Keeper is rate limiting this application",
+        60_000,
+      );
+    return new VaultProviderError("provider_unavailable", `Keeper returned HTTP ${code}`);
+  }
+  return new VaultProviderError("provider_unavailable", `Keeper could not ${subject}`);
+}
+
+/** Tracks one mutation's requests so a failure can be classified as definite or unknown. */
+export interface MutationTracker {
+  /** Requests started for the mutation itself. */
+  sent: number;
+  /** Status of the last mutation response, if one arrived. */
+  lastStatus: number | null;
+}
+
+/**
+ * Statuses with which Keeper refuses a request before applying it: a bad or
+ * unauthorised request (400, 401, 403), a missing target (404), a revision
+ * conflict (409) or throttling (429). Any other status after the request was
+ * sent (5xx from Keeper or a proxy, an unexpected 2xx or 3xx) may follow an
+ * applied change.
+ */
+export const KEEPER_DEFINITE_REJECTION_STATUSES: ReadonlySet<number> = new Set([
+  400, 401, 403, 404, 409, 429,
+]);
+
+/**
+ * A mutation failure is definite only when nothing was sent, or Keeper
+ * answered the last request with a known rejection status. A transport
+ * failure, deadline or abort after sending, any other status (502 included),
+ * or any failure after a 200, leaves the outcome unknown.
+ */
+export function mapKeeperMutationError(
+  error: unknown,
+  subject: string,
+  tracker: MutationTracker,
+): VaultProviderError {
+  const definite =
+    tracker.sent === 0 ||
+    (tracker.lastStatus !== null && KEEPER_DEFINITE_REJECTION_STATUSES.has(tracker.lastStatus));
+  if (!definite) {
+    return new VaultProviderError(
+      "provider_outcome_unknown",
+      `Keeper may or may not have completed "${subject}"; check the record before retrying`,
+    );
+  }
+  return mapKeeperError(error, subject);
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+export {
+  KEEPER_OPERATIONS,
+  KEEPER_VALUE_CACHE_MS,
+  createKeeperVaultProvider,
+  type KeeperRuntimeOptions,
+  type KeeperVaultProvider,
+  type KeeperVaultProviderOptions,
+  type PersistKeeperConfiguration,
+} from "./provider";
+export {
+  bootstrapKeeperConfiguration,
+  bootstrapKeeperVaultProvider,
+  keeperTokenHost,
+  type KeeperBootstrapOptions,
+  type KeeperBootstrapResult,
+} from "./bootstrap";
+export {
+  KEEPER_CONFIG_KEYS,
+  KEEPER_DEFAULT_ALLOWED_HOSTS,
+  KEEPER_REGION_HOSTS,
+  keeperConfigurationRecord,
+  parseKeeperConfiguration,
+  serializeKeeperConfiguration,
+} from "./config";
+export {
+  KEEPER_MAX_RESPONSE_BYTES,
+  KEEPER_REQUEST_TIMEOUT_MS,
+  KEEPER_SDK_PACKAGE,
+  KEEPER_SDK_SHA256,
+  KEEPER_SDK_VERSION,
+  createKeeperSdkLoader,
+  type KeeperFetch,
+  type KeeperFileFetcher,
+  type KeeperQueryFunction,
+  type KeeperSdkLoader,
+} from "./sdk";
+export { FILE_FIELD_PREFIX, NOTES_FIELD_ID } from "./mapping";
+export {
+  openKeeperConnection,
+  type KeeperConnectionCredentials,
+  type OpenKeeperConnectionOptions,
+  type PersistKeeperConfigurationRecord,
+} from "./connection";
+export { restrictToOperations } from "./operations";
+export { KEEPER_DEFINITE_REJECTION_STATUSES } from "./errors";