Credential Helpers

Low-level functions for interacting with the system's git credential helper directly. These are the building blocks used by createNodeAuthCallbacks and createAuthenticatedTransport, exposed for cases where you need fine-grained control over credential lifecycle.

Import

import {
  getCredentials,
  storeCredentials,
  rejectCredentials,
} from "@catmint-fs/git-auth-node";

getCredentials

Retrieves stored credentials for a given URL by running git credential fill.

Signature

function getCredentials(
  url: string,
): Promise<{ username: string; password: string } | undefined>;

Parameters

Return Value

Returns a Promise that resolves to:

• { username: string; password: string } -- if credentials were found
• undefined -- if no credentials are stored for the given URL

Example

import { getCredentials } from "@catmint-fs/git-auth-node";

const creds = await getCredentials("https://github.com");
if (creds) {
  console.log(`Authenticated as ${creds.username}`);
} else {
  console.log("No credentials found");
}

storeCredentials

Saves credentials for a URL by running git credential approve. The credential helper will store them according to its configuration (e.g., in the system keychain).

Signature

function storeCredentials(
  url: string,
  credentials: { username: string; password: string },
): Promise<void>;

Parameters

Return Value

Returns a Promise<void> that resolves when the credentials have been stored.

Example

import { storeCredentials } from "@catmint-fs/git-auth-node";

await storeCredentials("https://github.com", {
  username: "my-user",
  password: "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
});

rejectCredentials

Tells the credential helper that the given credentials are invalid by running git credential reject. The helper will remove them from storage so they are not returned by future getCredentials calls.

Signature

function rejectCredentials(
  url: string,
  credentials: { username: string; password: string },
): Promise<void>;

Parameters

Return Value

Returns a Promise<void> that resolves when the credentials have been rejected.

Example

import { getCredentials, rejectCredentials } from "@catmint-fs/git-auth-node";

const creds = await getCredentials("https://github.com");
if (creds) {
  // If authentication fails, reject the bad credentials
  await rejectCredentials("https://github.com", creds);
}

Full Lifecycle Example

import {
  getCredentials,
  storeCredentials,
  rejectCredentials,
} from "@catmint-fs/git-auth-node";

const url = "https://github.com";

// 1. Look up existing credentials
let creds = await getCredentials(url);

if (!creds) {
  // 2. No credentials found -- prompt or provide them
  creds = { username: "my-user", password: "my-token" };
}

// 3. Attempt to use the credentials...
const success = await attemptAuth(url, creds);

if (success) {
  // 4. Store on success so the helper remembers them
  await storeCredentials(url, creds);
} else {
  // 5. Reject on failure so the helper forgets them
  await rejectCredentials(url, creds);
}

How It Works

Each function shells out to the git credential subcommand:

The URL is parsed to extract the protocol and host, which are passed to git via stdin in the expected format:

protocol=https
host=github.com

See Also

• createNodeAuthCallbacks
• createAuthenticatedTransport
• @catmint-fs/git Overview