dsh-connect-workbuddy 4.0.0 → 4.2.0

package/lib/index.d.ts

@@ -116,6 +116,12 @@ interface WorkBuddyStoreOptions {
    * pre-dual-provider location. Injectable for tests.
    */
   legacyOwnPath?: string;
+  /**
+   * The unified credential vault directory for this store. Defaults to the
+   * per-region directory under the Harness home; injectable so the vault's
+   * merge/scan behaviour is testable without touching a real machine.
+   */
+  vaultDir?: string;
   /**
    * Auth directories to scan, overriding the platform defaults. Injectable so
    * the multi-account scan is testable without touching a real machine.
@@ -233,6 +239,9 @@ declare class WorkBuddyCredentialStore {
   private readonly ownPathExplicit;
   private readonly legacyOwnPath;
   private readonly legacyOwnPathExplicit;
+  private readonly vaultDirExplicit;
+  /** The vault directory, resolved ONCE at construction. */
+  private readonly vaultDirResolved;
   private readonly authDirs;
   private readonly resolveAtRestKey;
   private desktopPathOverride;
@@ -268,6 +277,8 @@ declare class WorkBuddyCredentialStore {
    * the real machine's legacy copy.
    */
   private ownCandidates;
+  /** The vault directory this store reads and writes (fixed at construction). */
+  private vaultDir;
   /** Repoint the desktop file or directory; applies on the next read. */
   setDesktopPath(path: string | undefined): void;
   /**
@@ -321,6 +332,16 @@ declare class WorkBuddyCredentialStore {
    * which is what keeps the two regions' providers from cross-billing.
    */
   private readAll;
+  /**
+   * Merge the scan's credentials into the vault and read the vault back.
+   *
+   * Incremental by contract: a scan that finds nothing new writes nothing.
+   * Per account, the vault entry is written only when the scan's read is
+   * fresher by {@link isFresherVaultEntry} — so a steady-state scan is
+   * mtime-stable and every sync is O(accounts) reads with at most one write
+   * per CHANGED account.
+   */
+  private syncVault;
   /**
    * Default when no account is explicitly selected: the live sign-in, else the
    * freshest credential. Following the app's current sign-in is the documented
@@ -396,6 +417,31 @@ declare class WorkBuddyCredentialStore {
   private describeMissingCredential;
   /** Read-only sign-in summary; never refreshes and never throws. */
   status(): Promise<WorkBuddyAuthStatus>;
+  /**
+   * Persist one OAuth sign-in into the unified vault.
+   *
+   * The credential is written with `source: 'dsh'` (it never came from a
+   * desktop file) and joins the readable set on the next scan — the vault is
+   * read by `readAll()` like any other source, so no separate discovery path
+   * exists. The write is idempotent per account id: re-adding an account
+   * replaces its entry, which is exactly what re-issuing a login means.
+   *
+   * Returns the account id so the card can offer to select it right away.
+   */
+  addOAuthAccount(credential: Omit<WorkBuddyCredential, 'source' | 'filePath'>): Promise<string>;
+  /**
+   * Remove ONE account's plugin-stored credential by id.
+   *
+   * Only the VAULT entry is deleted — the desktop app's auth files are read-only
+   * to this plugin and are never touched, so an account that still exists as a
+   * desktop sign-in reappears on the next scan. That is the honest behaviour:
+   * the button means "forget what the plugin stored", not "sign the app out".
+   *
+   * Returns whether a stored entry was actually removed, so the caller can
+   * distinguish "removed" from "this account only ever existed as a desktop
+   * sign-in" without a second scan.
+   */
+  removeAccount(accountId: string): Promise<boolean>;
   /**
    * Remove every plugin-owned copy this store could read (per-region file,
    * legacy single file, and their lock siblings); the desktop files are
@@ -406,7 +452,6 @@ declare class WorkBuddyCredentialStore {
   logout(): Promise<void>;
   private needsRefresh;
   private refreshNow;
-  private saveOwn;
   /**
    * Every readable plugin-owned copy, in candidate order; absent or corrupt
    * files are skipped rather than propagated.
@@ -578,6 +623,30 @@ interface UpstreamErrorDetail {
  * them at the openresty layer with an HTML 401.
  */
 declare function regionOf(domain: string): WorkBuddyRegion;
+/**
+ * The STRICT counterpart of {@link regionOf}: a region's domain only when it is
+ * positively recognised, `undefined` for anything else.
+ *
+ * `regionOf`'s catch-all is deliberate — the CN product is single-homed, so an
+ * unrecognised spelling is treated as CN and a real (if oddly written) CN
+ * credential still resolves. That reasoning holds only for a domain the
+ * UPSTREAM issued. It does not hold for a value read out of a file someone
+ * handed the plugin: there "unrecognised" means "cannot be classified", and
+ * calling it CN would file a foreign or spoofed credential in the CN vault.
+ * Import gates must use this, not {@link regionOf}.
+ *
+ * Both sides are matched on their registrable domain, so a bare host and any
+ * subdomain qualify while a lookalike such as `codebuddy.cn.evil.com` cannot.
+ *
+ * `copilot.tencent.com` is NOT a third product — it is this plugin's OWN CN
+ * chat gateway (`CN_CHAT_BASE`), and the credential's `domain` field carries it
+ * verbatim on real records. Refusing it here made the plugin reject its own
+ * export: the card exported 8 accounts, and re-importing that file skipped the
+ * three whose `domain` was the gateway. It cannot be spoofed into the wrong
+ * region by being recognised here — it names the CN gateway, so admitting it is
+ * the same decision as admitting `workbuddy.cn`.
+ */
+declare function knownRegionOf(domain: string): WorkBuddyRegion | undefined;
 /**
  * Normalize an OpenAI chat-completions body for the WorkBuddy upstream:
  * force `stream: true` (the upstream rejects non-streaming), flatten
@@ -1778,6 +1847,59 @@ declare const WORKBUDDY_CHECKIN_PATH = "/plugins/dsh-connect-workbuddy/checkin";
  * browser half.
  */
 declare const WORKBUDDY_PROBE_PATH = "/plugins/dsh-connect-workbuddy/probe";
+/**
+ * One entry of the transfer PREVIEW: display fields only, never token
+ * material. `hasToken` is the import decision input — the import step skips
+ * records without one — and the indexes are the FILE's positions, so the user
+ * picks by the same numbers the import call sends back.
+ */
+interface WorkBuddyTransferPreviewEntry {
+  index: number;
+  uid: string;
+  nickname: string;
+  email: string;
+  hasToken: boolean;
+}
+/** The preview answer: the desensitized listing plus the file's total count. */
+interface WorkBuddyTransferPreview {
+  accounts: readonly WorkBuddyTransferPreviewEntry[];
+  total: number;
+}
+/**
+ * The import answer. `imported` counts records merged into the vault (new OR
+ * overwritten — both change the stored entry); `skipped` counts what was
+ * left out: missing token, a bad index, or a record whose login domain does
+ * not belong to the addressed region.
+ */
+interface WorkBuddyTransferImportAnswer {
+  imported: number;
+  skipped: number;
+}
+/**
+ * The shared file format's record shape, subset the importer consumes.
+ *
+ * Contract with sibling tools exporting the same format: a JSON array of
+ * objects keyed in snake_case — `access_token` (required), `refresh_token`,
+ * `uid`, `nickname`, `email`, `domain`, `expiresAt` (epoch ms),
+ * `refreshExpiresAt`, `auth_raw`. Extra fields ride along untouched.
+ */
+interface WorkBuddyTransferRecord {
+  access_token: string;
+  refresh_token?: string;
+  uid?: string;
+  nickname?: string;
+  email?: string;
+  domain?: string;
+  /** Access-token expiry in epoch MILLISECONDS, the sibling format's unit. */
+  expiresAt?: number;
+  refreshExpiresAt?: number;
+  /** The sibling tool's original credential document, preserved verbatim. */
+  auth_raw?: unknown;
+}
+/** The export answer: the records themselves, tokens included. */
+interface WorkBuddyTransferExportAnswer {
+  accounts: WorkBuddyTransferRecord[];
+}
 /** Query parameter naming the region a card request addresses. */
 declare const WORKBUDDY_REGION_PARAM = "region";
 /** Every region, in card tab order. */
@@ -2410,7 +2532,79 @@ interface WorkBuddyStatusRouteOptions {
    * that needs a working probe dependency.
    */
   pool?: WorkBuddyPoolDeps;
+  /**
+   * OAuth QR sign-in: start a login and poll it to completion.
+   *
+   * Optional as a whole: a Host built without it simply omits the card's
+   * sign-in affordance (an older bundle keeps rendering, minus the button).
+   */
+  oauth?: WorkBuddyOAuthDeps;
+  /**
+   * Batch credential export / import between machines.
+   *
+   * Optional as a whole: a Host built without it simply omits the card's
+   * transfer section (an older bundle keeps rendering, minus the buttons).
+   */
+  transfer?: WorkBuddyTransferDeps;
 }
+/**
+ * What the transfer route needs from the Host. Everything is region-scoped:
+ * the two regions' vaults are parallel stacks, and an export of one tab must
+ * never leak the other tab's accounts.
+ */
+interface WorkBuddyTransferDeps {
+  /**
+   * Export the named accounts' credentials in the shared transfer format.
+   * Unknown ids are simply absent from the answer; an answer with zero
+   * records means nothing named was exportable (the caller decides whether
+   * that is an error).
+   */
+  exportAccounts(region: WorkBuddyRegion, accountIds: readonly string[]): Promise<WorkBuddyTransferExportAnswer>;
+  /** Parse transfer-file text into the desensitized preview. */
+  previewImport(region: WorkBuddyRegion, text: string): Promise<WorkBuddyTransferPreview>;
+  /**
+   * Merge the selected file entries into the region's vault. Returns the
+   * counters the card reports; `skipped` covers missing tokens, bad indexes,
+   * and records belonging to the other region.
+   */
+  importAccounts(region: WorkBuddyRegion, text: string, indexes: readonly number[]): Promise<WorkBuddyTransferImportAnswer>;
+}
+/**
+ * What the OAuth route needs from the Host: the two session actions, plus the
+ * persistence step the route cannot do itself (only the Host may touch the
+ * credential vault).
+ */
+interface WorkBuddyOAuthDeps {
+  /**
+   * Start one login for the region. Resolves the URL the user opens to scan
+   * and confirm, or an actionable error.
+   */
+  start(region: WorkBuddyRegion): Promise<WorkBuddyOAuthStartResult>;
+  /**
+   * Poll once. The card repeats until `done` — then either the account was
+   * persisted (the Host saved it to the vault) or an error is reported.
+   */
+  poll(region: WorkBuddyRegion, loginId: string): Promise<WorkBuddyOAuthPollView>;
+}
+/** The start answer, token-free (the state never leaves the Host). */
+type WorkBuddyOAuthStartResult = {
+  loginId: string;
+  verificationUri: string;
+  expiresIn: number;
+} | {
+  error: string;
+};
+/** The poll answer the card sees. `account` carries display fields only. */
+type WorkBuddyOAuthPollView = {
+  done: false;
+} | {
+  done: true;
+  accountName: string;
+  accountId: string;
+} | {
+  done: true;
+  error: string;
+};
 /**
  * What the pool route needs from the Host.
  *
@@ -2444,6 +2638,22 @@ interface WorkBuddyPoolDeps {
    * checked) instead of passing the guard and running a batch over nothing.
    */
   effectiveMemberAccountIds?(region: WorkBuddyRegion): Promise<readonly string[]>;
+  /**
+   * Test ONE account against the region's target model.
+   *
+   * The per-row button's Host half. Optional: a Host built without it simply
+   * omits the row button (an older bundle keeps rendering, minus the control).
+   * Returns undefined when the region cannot name a target model — the same
+   * refusal the batch route reports as 409.
+   */
+  testOne?(region: WorkBuddyRegion, accountId: string): Promise<WorkBuddyPoolTestRow | undefined>;
+  /**
+   * Forget ONE account's plugin-stored credential. Only the vault entry is
+   * removed; the desktop app's files are never touched. Returns whether an
+   * entry existed — false means the account exists only as a desktop sign-in
+   * (or was already gone), which the card reports instead of a silent no-op.
+   */
+  removeOne?(region: WorkBuddyRegion, accountId: string): Promise<boolean>;
   /**
    * Today's check-in state per account id.
    *
@@ -2772,4 +2982,4 @@ declare function legacyAttributionRegion(value: Config, accountsFor: (region: Wo
  */
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { CREDENTIAL_REJECTED_CODE, Config, DEFAULT_PROBE_INPUT_TOKENS, ENCRYPTED_CREDENTIAL_CODE, FALLBACK_WORKBUDDY_MODELS, FALLBACK_WORKBUDDY_MODELS_GLOBAL, NATIVE_MODALITY_BY_MODEL_ID, PROBE_INPUT_TOKEN_CHOICES, PROBE_MAX_TOKENS, PROBE_SYSTEM_PROMPT, REFUSES_OFF_MODEL_IDS, type UpstreamErrorKind, WORKBUDDY_ACCOUNTS_REFRESH_PATH, WORKBUDDY_APP_EXECUTABLE_ENV, WORKBUDDY_AUTH_FILENAME, WORKBUDDY_AUTH_FILE_ENV, WORKBUDDY_CHECKIN_PATH, WORKBUDDY_CONNECT_VERSION, WORKBUDDY_GLOBAL_PROVIDER, WORKBUDDY_HOST_HEARTBEAT_FILENAME, WORKBUDDY_MODELS_REFRESH_PATH, WORKBUDDY_PROBE_PATH, WORKBUDDY_PROVIDER, WORKBUDDY_PROVIDERS, WORKBUDDY_PROVIDER_DISPLAY_NAMES, WORKBUDDY_REGIONS, WORKBUDDY_REGION_PARAM, WORKBUDDY_SETTINGS_NS, WORKBUDDY_STREAM_IDLE_TIMEOUT_MS, WORKBUDDY_USAGE_PATH, type WorkBuddyAccountChoice, type WorkBuddyAdapter, type WorkBuddyAuthStatus, type WorkBuddyCandidateFailure, WorkBuddyCatalog, type WorkBuddyChatResult, type WorkBuddyCredential, type WorkBuddyCredentialRecovery, WorkBuddyCredentialRejectedError, WorkBuddyCredentialStore, type WorkBuddyCreditPackage, type WorkBuddyCredits, WorkBuddyEncryptedCredentialError, type WorkBuddyEncryptedField, type WorkBuddyHostHeartbeat, type WorkBuddyModelInfo, type WorkBuddyNativeModality, WorkBuddyPoolPreferences, type WorkBuddyProbeClient, type WorkBuddyProbeOutcome, type WorkBuddyProbeResult, type WorkBuddyProbeStore, type WorkBuddyReasoning, type WorkBuddyRecoveryCandidate, type WorkBuddyRefreshOutcome, WorkBuddyRegionState, type WorkBuddyShim, type WorkBuddyStatusRouteOptions, type WorkBuddyStoreOptions, WorkBuddyUpstreamClient, type WorkBuddyUpstreamModel, type WorkBuddyUsabilityProbeOptions, apply, asVolatile, authFileName, classifyUpstreamError, clearAtRestKeyCache, clearHostHeartbeat, cooldownOf, createAccountUsabilityProbe, createWorkBuddyAdapter, createWorkBuddyShim, creditOfStream, defaultDesktopAuthCandidates, defaultDesktopAuthDirs, defaultDesktopAuthPath, defaultOffModelIds, deriveAtRestKey, deriveAtRestKeyId, deriveCatalog, fallbackModelsFor, fetchAtRestKeyPayload, findWorkbuddyAppExecutable, hasEncryptedCredentialFields, imageDefaultFor, inject, isCredentialRejectedError, isEncryptedCredentialError, isEncryptedFieldWrapper, isHeartbeatProcessAlive, isWorkbuddyBundle, legacyAttributionRegion, legacyWorkbuddyOwnAuthPath, macosBundleExecutable, macosNestedAppBundles, name, nativeModalityOf, nextRegionEnabled, nextRegionSlots, offDefaultFor, openEncryptedField, outcomeOfFailure, parseCreditMultiplier, parseReasoning, parseRetryAfter, parseUpstreamModel, parseWorkBuddyAuth, prepareChatBody, probeModel, probeRequestBody, probeSucceeded, processStartTimeMs, readAtRestKey, readHostHeartbeat, regionCleared, regionEnabled, regionEnabledOf, regionOf, regionOfProvider, regionOfStatusUrl, regionStateOf, registerWorkBuddyStatusRoute, resolveCredentialRecovery, selectAccountFor, settingsNamespaceOf, toPersistedWorkBuddyModel, unwrapVolatileDeep, withEffectiveOff, withWorkBuddyRegion, workBuddyDisplayName, workBuddyModelInput, workBuddyThinkingLevelMap, workBuddyWebStatus, workbuddyAccountId, workbuddyAppExecutableCandidates, workbuddyHostHeartbeatPath, workbuddyOwnAuthPath, writeHostHeartbeat };
+export { CREDENTIAL_REJECTED_CODE, Config, DEFAULT_PROBE_INPUT_TOKENS, ENCRYPTED_CREDENTIAL_CODE, FALLBACK_WORKBUDDY_MODELS, FALLBACK_WORKBUDDY_MODELS_GLOBAL, NATIVE_MODALITY_BY_MODEL_ID, PROBE_INPUT_TOKEN_CHOICES, PROBE_MAX_TOKENS, PROBE_SYSTEM_PROMPT, REFUSES_OFF_MODEL_IDS, type UpstreamErrorKind, WORKBUDDY_ACCOUNTS_REFRESH_PATH, WORKBUDDY_APP_EXECUTABLE_ENV, WORKBUDDY_AUTH_FILENAME, WORKBUDDY_AUTH_FILE_ENV, WORKBUDDY_CHECKIN_PATH, WORKBUDDY_CONNECT_VERSION, WORKBUDDY_GLOBAL_PROVIDER, WORKBUDDY_HOST_HEARTBEAT_FILENAME, WORKBUDDY_MODELS_REFRESH_PATH, WORKBUDDY_PROBE_PATH, WORKBUDDY_PROVIDER, WORKBUDDY_PROVIDERS, WORKBUDDY_PROVIDER_DISPLAY_NAMES, WORKBUDDY_REGIONS, WORKBUDDY_REGION_PARAM, WORKBUDDY_SETTINGS_NS, WORKBUDDY_STREAM_IDLE_TIMEOUT_MS, WORKBUDDY_USAGE_PATH, type WorkBuddyAccountChoice, type WorkBuddyAdapter, type WorkBuddyAuthStatus, type WorkBuddyCandidateFailure, WorkBuddyCatalog, type WorkBuddyChatResult, type WorkBuddyCredential, type WorkBuddyCredentialRecovery, WorkBuddyCredentialRejectedError, WorkBuddyCredentialStore, type WorkBuddyCreditPackage, type WorkBuddyCredits, WorkBuddyEncryptedCredentialError, type WorkBuddyEncryptedField, type WorkBuddyHostHeartbeat, type WorkBuddyModelInfo, type WorkBuddyNativeModality, WorkBuddyPoolPreferences, type WorkBuddyProbeClient, type WorkBuddyProbeOutcome, type WorkBuddyProbeResult, type WorkBuddyProbeStore, type WorkBuddyReasoning, type WorkBuddyRecoveryCandidate, type WorkBuddyRefreshOutcome, WorkBuddyRegionState, type WorkBuddyShim, type WorkBuddyStatusRouteOptions, type WorkBuddyStoreOptions, WorkBuddyUpstreamClient, type WorkBuddyUpstreamModel, type WorkBuddyUsabilityProbeOptions, apply, asVolatile, authFileName, classifyUpstreamError, clearAtRestKeyCache, clearHostHeartbeat, cooldownOf, createAccountUsabilityProbe, createWorkBuddyAdapter, createWorkBuddyShim, creditOfStream, defaultDesktopAuthCandidates, defaultDesktopAuthDirs, defaultDesktopAuthPath, defaultOffModelIds, deriveAtRestKey, deriveAtRestKeyId, deriveCatalog, fallbackModelsFor, fetchAtRestKeyPayload, findWorkbuddyAppExecutable, hasEncryptedCredentialFields, imageDefaultFor, inject, isCredentialRejectedError, isEncryptedCredentialError, isEncryptedFieldWrapper, isHeartbeatProcessAlive, isWorkbuddyBundle, knownRegionOf, legacyAttributionRegion, legacyWorkbuddyOwnAuthPath, macosBundleExecutable, macosNestedAppBundles, name, nativeModalityOf, nextRegionEnabled, nextRegionSlots, offDefaultFor, openEncryptedField, outcomeOfFailure, parseCreditMultiplier, parseReasoning, parseRetryAfter, parseUpstreamModel, parseWorkBuddyAuth, prepareChatBody, probeModel, probeRequestBody, probeSucceeded, processStartTimeMs, readAtRestKey, readHostHeartbeat, regionCleared, regionEnabled, regionEnabledOf, regionOf, regionOfProvider, regionOfStatusUrl, regionStateOf, registerWorkBuddyStatusRoute, resolveCredentialRecovery, selectAccountFor, settingsNamespaceOf, toPersistedWorkBuddyModel, unwrapVolatileDeep, withEffectiveOff, withWorkBuddyRegion, workBuddyDisplayName, workBuddyModelInput, workBuddyThinkingLevelMap, workBuddyWebStatus, workbuddyAccountId, workbuddyAppExecutableCandidates, workbuddyHostHeartbeatPath, workbuddyOwnAuthPath, writeHostHeartbeat };