dsh-git-branch-manage 1.1.0 → 1.2.0

package/lib/credentials.d.ts

@@ -1,25 +1,36 @@
 /**
- * Global git credential store (host half). Credentials belong to a remote
- * HOST, not to a project: the same `github.com` token serves every repository
- * the panel touches, so the record lives in one file under `$DSH_HOME`
- * (`~/.dsh`) instead of the per-repository settings document. The secret
- * never travels to the browser — the list route answers masked tails only —
- * and the store is read/written by the host alone.
+ * Global git credential store (host half), backed by the machine's own
+ * credential file (decision 0037).
  *
- * Authentication rides `git -c http.https://<host>/.extraHeader=…` on the
- * panel's own network commands and on the `git_network` tool: the user's git
- * configuration FILES are never written. Plain `git` commands in a spawned
- * shell are covered separately by the environment bridge in `shell-bridge.ts`,
- * which installs this store's per-host tokens as URL-scoped credential helpers
- * through `GIT_CONFIG_*` (process environment only, never a config file).
- * Only `https://` remotes receive the header; ssh and plain-http remotes are
- * never sent a secret.
+ * A credential belongs to a remote HOST, not to a project: the same
+ * `github.com` token serves every repository. Up to 1.1.x the plugin kept its
+ * own `~/.dsh/git-credentials.json`, which meant the panel's token was
+ * invisible to a plain `git` run in a shell and the machine's helpers
+ * answered instead (often with a different account). 0037 makes the panel
+ * manage the SAME file git's built-in `credential-store` helper uses —
+ * `~/.git-credentials` — so one save is visible to every git process:
+ *
+ *  - the secret lines are the store format (`https://user:pass@host`),
+ *    percent-encoded exactly as `git credential approve` writes them;
+ *  - method/updatedAt cannot live in that format, so a sibling
+ *    `<dsh-home>/git-credentials.meta.json` keeps the UI-only metadata
+ *    (no secret ever goes in there);
+ *  - a generated `<dsh-home>/git-credentials.include.gitconfig` scopes
+ *    `helper = store` to each managed host, and `~/.gitconfig` gains one
+ *    `[include] path = <that file>` line (idempotent, decision 0037
+ *    overturns 0021's "never write the user's git config" for exactly this
+ *    one scoped include).
+ *
+ * The secret never travels to the browser — the list route answers masked
+ * tails only — and only `https://` remotes are ever covered.
  */
 import type { CredentialMethod } from './wire.js';
 /**
  * The Basic-auth name git sends when a token was stored without a username.
  * GitHub, GitLab and Gitee all accept any non-empty name for a personal access
- * token, and `oauth2` is the conventional placeholder.
+ * token, and `oauth2` is the conventional placeholder. The store format has no
+ * "blank username", so this value is what a blank one becomes on disk and is
+ * read back as blank again.
  */
 export declare const TOKEN_USERNAME = "oauth2";
 /** One stored credential: exactly one per remote host. */
@@ -27,19 +38,19 @@ export interface GitCredential {
     /** Normalized remote host (`github.com`, `git.example.com:8443`). */
     host: string;
     /** Basic-auth username (a real account name, or a vendor-form placeholder
-     * such as `x-access-token` / `oauth2`). */
+     * such as `x-access-token` / `oauth2`). Blank for a bare token. */
     username: string;
     /** Token or password, verbatim (never returned to the client). */
     secret: string;
     /** How the secret is meant to be used — informational for the UI; git
      * itself only sees the Basic header. */
     method: CredentialMethod;
-    /** Epoch millis of the last save. */
+    /** Epoch millis of the last save (0 when unknown). */
     updatedAt: number;
 }
 /** Load/save seam for the credential file (tests substitute an in-memory one). */
 export interface CredentialStore {
-    /** Absolute file the store persists to (for diagnostics/UI hints). */
+    /** Absolute file the store persists secrets to (for diagnostics/UI hints). */
     readonly path: string;
     /** Every stored credential, one per host, sorted by host. A missing file
      * is the empty list; an unreadable/malformed one throws
@@ -54,11 +65,32 @@ export declare class CredentialStoreError extends Error {
     constructor(path: string, message: string);
 }
 /**
- * Resolve the credential file location: `<dsh-home>/git-credentials.json`.
+ * The retired 0021/0029 plugin-private file `<dsh-home>/git-credentials.json`.
+ * Read once by {@link migrateLegacyCredentialFile} and deleted afterwards.
  * @param home - user home directory seam.
  * @param envHome - `$DSH_HOME` environment value seam (blank = unset).
  */
 export declare function credentialFilePath(home: string, envHome: string | undefined): string;
+/**
+ * `~/.git-credentials` — the file git's `credential-store` helper reads and
+ * writes (`$HOME/.git-credentials` on every platform).
+ * @param home - user home directory seam.
+ */
+export declare function gitCredentialsFile(home: string): string;
+/**
+ * The UI-only metadata sidecar: method and `updatedAt` per host. Never holds a
+ * secret; a missing or damaged file only costs the "how/when" columns.
+ * @param home - user home directory seam.
+ * @param envHome - `$DSH_HOME` environment value seam.
+ */
+export declare function credentialMetaFile(home: string, envHome: string | undefined): string;
+/**
+ * The generated gitconfig included from `~/.gitconfig`: one URL-scoped
+ * `helper = store` section per managed host.
+ * @param home - user home directory seam.
+ * @param envHome - `$DSH_HOME` environment value seam.
+ */
+export declare function credentialIncludeFile(home: string, envHome: string | undefined): string;
 /** Why a user-typed host is not usable yet (undefined = fine). */
 export type CredentialHostIssue = 'empty' | 'invalid';
 /**
@@ -99,16 +131,6 @@ export declare function credentialSecretIssue(value: string): 'empty' | 'illegal
  * @param secret - the stored secret.
  */
 export declare function maskSecret(secret: string): string;
-/**
- * The git config argv that authenticates network commands against the stored
- * hosts: one `http.<https-url>.extraHeader` per host. Git applies a
- * `http.<url>.*` section only to a matching remote URL, so injecting every
- * stored host at once cannot leak one host's header to another; only
- * `https://` URLs match (ssh/http never receive it).
- * @param entries - stored credentials (duplicates collapsed by host).
- * @returns the `-c <key>=<value>` pairs, ready to prepend to a subcommand.
- */
-export declare function authConfigArgs(entries: readonly GitCredential[]): readonly string[];
 /**
  * Insert or update one credential; the pair `(host, updatedAt)` changes,
  * everything else is replaced. An existing host keeps its position.
@@ -127,22 +149,105 @@ export declare function removeCredential(entries: readonly GitCredential[], host
 /** Stable host order for the file and the UI. */
 export declare function sortCredentials(entries: readonly GitCredential[]): GitCredential[];
 /**
- * Parse the credential file. Unknown extra fields are tolerated (a
- * hand-edited file), but a malformed entry is an error rather than a silent
- * drop — losing a credential behind the user's back is worse than an
- * explicit message. Hosts are re-normalized and de-duplicated.
+ * Percent-encode one userinfo component the way git's store helper does:
+ * everything outside the RFC 3986 unreserved set becomes `%xx` (lowercase
+ * hex, matching `git credential approve`). `encodeURIComponent` would leave
+ * `!'()*` alone and git would then mis-split the line at a literal `@`.
+ * @param value - raw username or secret.
+ */
+export declare function encodeCredentialPart(value: string): string;
+/**
+ * One `<scheme>://user:pass@host` line, ready for `~/.git-credentials`.
+ * @param entry - the credential to write.
+ */
+export declare function formatCredentialLine(entry: GitCredential): string;
+/** A `~/.git-credentials` file split into credentials and untouched lines. */
+export interface ParsedCredentials {
+    /** One credential per https host; a duplicated host keeps the LAST line,
+     * which is the line git's store helper would resolve to after a rewrite. */
+    readonly entries: GitCredential[];
+    /** Lines this store does not own (comments, ssh/http rows, malformed
+     * text). Written back verbatim so a hand-edited file survives a save. */
+    readonly others: string[];
+}
+/**
+ * Parse a `~/.git-credentials` document.
+ * @param text - raw file contents (BOM tolerated).
+ */
+export declare function parseGitCredentials(text: string): ParsedCredentials;
+/**
+ * Parse the retired `<dsh-home>/git-credentials.json`. Unknown extra fields
+ * are tolerated (a hand-edited file), but a malformed entry is an error rather
+ * than a silent drop — losing a credential during the one-time migration is
+ * worse than an explicit message.
  * @param text - raw file contents.
  * @param path - file path (for the error message).
  */
 export declare function parseCredentialFile(text: string, path?: string): GitCredential[];
+/** Write-then-rename so a crashed save never truncates the real file. */
+export declare function writeFileAtomic(path: string, text: string, mode?: number): Promise<void>;
+/**
+ * The real store over `~/.git-credentials`. The secret lines are the git
+ * store format; the sibling metadata file carries method/updatedAt only.
+ * A missing file reads as "no credentials yet".
+ * @param home - user home directory seam.
+ * @param envHome - `$DSH_HOME` environment value seam.
+ */
+export declare function createLocalCredentialStore(home: string, envHome: string | undefined): CredentialStore;
+/**
+ * One-time 0037 migration: import the retired plugin-private JSON into the
+ * local store (plugin values win for a host they share), then delete the old
+ * file so there is exactly one place a secret lives.
+ *
+ * Idempotent: a missing legacy file is a no-op, and the file is removed only
+ * after the store write succeeded — a failed migration keeps the old file.
+ * @param home - user home directory seam.
+ * @param envHome - `$DSH_HOME` environment value seam.
+ * @param store - destination store.
+ * @returns true when a legacy file was imported and removed.
+ */
+export declare function migrateLegacyCredentialFile(home: string, envHome: string | undefined, store: CredentialStore): Promise<boolean>;
+/**
+ * The generated include file's contents: one URL-scoped section per host that
+ * resets any inherited helper for that exact URL and then installs the
+ * built-in `store` helper. The empty `helper =` line is what beats a
+ * user-level helper (`gh`, GCM) configured for the same host.
+ * @param hosts - managed remote hosts (already normalized).
+ */
+export declare function credentialIncludeBody(hosts: readonly string[]): string;
+/**
+ * Whether `~/.gitconfig` already includes the generated file. Matched loosely
+ * (any `path = <X>` line pointing at it) so a hand-reformatted include — or
+ * one with forward slashes on Windows — is not added a second time.
+ * @param text - current `~/.gitconfig` contents.
+ * @param includePath - the generated file.
+ */
+export declare function gitconfigHasInclude(text: string, includePath: string): boolean;
+/**
+ * Append the `[include] path = …` section, leaving every existing byte alone.
+ * @param text - current `~/.gitconfig` contents.
+ * @param includePath - the generated file.
+ */
+export declare function appendGitconfigInclude(text: string, includePath: string): string;
+/**
+ * Idempotently ensure `~/.gitconfig` includes the generated file. Rewrites
+ * atomically, preserving the file's existing mode; a missing file is created.
+ * @param gitconfigPath - user global config (`<home>/.gitconfig`).
+ * @param includePath - the generated file.
+ * @returns true when the file had to be changed.
+ */
+export declare function ensureGitconfigInclude(gitconfigPath: string, includePath: string): Promise<boolean>;
 /**
- * Serialize the credential set for the file.
- * @param entries - stored credentials.
+ * Remove the include section pointing at the generated file (plugin teardown).
+ * Every other line is preserved verbatim.
+ * @param text - current `~/.gitconfig` contents.
+ * @param includePath - the generated file.
  */
-export declare function serializeCredentialFile(entries: readonly GitCredential[]): string;
+export declare function stripGitconfigInclude(text: string, includePath: string): string;
 /**
- * The real file-backed store: atomic replace, `0600` where the platform
- * honours it. A missing file reads as "no credentials yet".
- * @param path - absolute credential file path.
+ * Remove the generated include from `~/.gitconfig`. Best effort: a teardown
+ * must not throw, and an already-clean file is left untouched.
+ * @param gitconfigPath - user global config (`<home>/.gitconfig`).
+ * @param includePath - the generated file.
  */
-export declare function createCredentialStore(path: string): CredentialStore;
+export declare function removeGitconfigInclude(gitconfigPath: string, includePath: string): Promise<void>;