axauth 2.0.0 → 3.0.0

package/dist/auth/agents/opencode.d.ts

@@ -11,4 +11,4 @@ import type { AuthAdapter } from "../adapter.js";
 /** OpenCode authentication adapter */
 declare const opencodeAdapter: AuthAdapter;
 export { opencodeAdapter };
-export { extractProviderCredentials, removeProviderCredentials, splitToPerProviderCredentials, } from "./opencode-credentials.js";
+export { getAllStoredCredentials, getStoredCredentialsForProvider, removeProviderCredentials, } from "./opencode-credentials.js";

package/dist/auth/agents/opencode.js

@@ -8,9 +8,8 @@
  * - Data (auth): ~/.local/share/opencode (XDG_DATA_HOME/opencode)
  */
 import path from "node:path";
-import { extractCredsFromDirectory } from "../extract-creds-from-directory.js";
 import { extractTokenFromEntry, OpenCodeAuth } from "./opencode-schema.js";
-import { AGENT_ID, CREDS_FILE_NAME, getDefaultAuthFilePath, readAuthFile, } from "./opencode-credentials.js";
+import { AGENT_ID, CREDS_FILE_NAME, getDefaultAuthFilePath, mapToCredentialType, readAuthFile, } from "./opencode-credentials.js";
 import { installCredentials, removeCredentials } from "./opencode-storage.js";
 /** OpenCode authentication adapter */
 const opencodeAdapter = {
@@ -54,59 +53,78 @@ const opencodeAdapter = {
             details: { providers: validProviders.map((p) => p.name) },
         };
     },
-    extractRawCredentials() {
+    findStoredCredentials(options) {
+        if (!options?.provider) {
+            throw new Error("OpenCode requires provider parameter. Use checkAuth() to list available providers.");
+        }
+        const normalizedProvider = options.provider.trim();
+        if (normalizedProvider.length === 0) {
+            throw new Error("Provider cannot be empty");
+        }
         const authResult = readAuthFile(getDefaultAuthFilePath());
         // Treat errors same as missing file for extraction (return undefined)
-        if (!authResult.ok ||
-            !authResult.data ||
-            Object.keys(authResult.data).length === 0) {
+        if (!authResult.ok || !authResult.data) {
+            return undefined;
+        }
+        const entry = authResult.data[normalizedProvider];
+        if (!entry) {
+            return undefined;
+        }
+        const parsed = OpenCodeAuth.safeParse(entry);
+        if (!parsed.success) {
             return undefined;
         }
         return {
-            agent: AGENT_ID,
-            type: "oauth-credentials",
-            data: authResult.data,
+            credentials: {
+                agent: AGENT_ID,
+                type: mapToCredentialType(parsed.data),
+                provider: normalizedProvider,
+                data: entry,
+            },
+            source: "file",
         };
     },
-    extractRawCredentialsFromDirectory(options) {
+    loadCredentialsFromDirectory(options) {
         // OpenCode stores credentials in dataDir only - configDir is for settings
-        // If dataDir not provided, return undefined (use extractRawCredentials() for default)
+        // If dataDir not provided, return undefined; if provider not provided, throw
         if (!options.dataDir)
             return undefined;
-        // Only return if there's at least one provider
-        return extractCredsFromDirectory(AGENT_ID, options.dataDir, CREDS_FILE_NAME, (data) => (Object.keys(data).length > 0 ? data : undefined));
-    },
-    installCredentials,
-    removeCredentials,
-    getAccessToken(creds, options) {
-        const data = creds.data;
-        // Per-provider credential: data is the provider's entry directly
-        if (creds.provider) {
-            const parsed = OpenCodeAuth.safeParse(data);
-            if (!parsed.success)
-                return undefined;
-            return extractTokenFromEntry(parsed.data);
+        const authResult = readAuthFile(path.join(options.dataDir, CREDS_FILE_NAME));
+        // Treat errors same as missing file for extraction (return undefined)
+        if (!authResult.ok ||
+            !authResult.data ||
+            Object.keys(authResult.data).length === 0) {
+            return undefined;
         }
-        // Bundled credential: data contains multiple providers
-        // If provider specified in options, get that provider's token
-        if (options?.provider) {
-            const normalizedProvider = options.provider.trim();
-            const entry = data[normalizedProvider];
-            const parsed = OpenCodeAuth.safeParse(entry);
-            if (!parsed.success)
+        // If provider filter is specified, return only that provider's credentials
+        if (options.provider) {
+            const targetProvider = options.provider.trim();
+            if (targetProvider.length === 0)
+                return undefined;
+            const entry = authResult.data[targetProvider];
+            if (!entry)
                 return undefined;
-            return extractTokenFromEntry(parsed.data);
-        }
-        // Otherwise return first available token
-        for (const entry of Object.values(data)) {
             const parsed = OpenCodeAuth.safeParse(entry);
             if (!parsed.success)
-                continue;
-            const token = extractTokenFromEntry(parsed.data);
-            if (token)
-                return token;
+                return undefined;
+            return {
+                agent: AGENT_ID,
+                type: mapToCredentialType(parsed.data),
+                provider: targetProvider,
+                data: entry,
+            };
         }
-        return undefined;
+        // No provider filter: throw to enforce explicit provider requirement
+        throw new Error("OpenCode requires provider parameter for loadCredentialsFromDirectory. Use findStoredCredentials() with provider option.");
+    },
+    installCredentials,
+    removeCredentials,
+    getAccessToken(creds) {
+        // OpenCode credentials are always per-provider: data is the provider's entry
+        const parsed = OpenCodeAuth.safeParse(creds.data);
+        if (!parsed.success)
+            return undefined;
+        return extractTokenFromEntry(parsed.data);
     },
     credentialsToEnvironment() {
         // OpenCode requires auth.json file, no env var support
@@ -117,4 +135,4 @@ const opencodeAdapter = {
     },
 };
 export { opencodeAdapter };
-export { extractProviderCredentials, removeProviderCredentials, splitToPerProviderCredentials, } from "./opencode-credentials.js";
+export { getAllStoredCredentials, getStoredCredentialsForProvider, removeProviderCredentials, } from "./opencode-credentials.js";

package/dist/auth/build-refreshed-credentials.d.ts

@@ -1,12 +1,14 @@
 /**
- * Build refreshed credentials with source and provider context preserved.
+ * Build refreshed credentials with provider context preserved.
  */
 import type { Credentials } from "./types.js";
 /**
- * Build refreshed credentials, preserving _source marker and handling
- * per-provider vs bundled credential formats.
+ * Build refreshed credentials, preserving provider context.
  *
- * @param originalCreds - Original credentials with _source marker
+ * For OpenCode (per-provider), extracts the specific provider's refreshed data.
+ * For other agents, uses the refreshed data directly.
+ *
+ * @param originalCreds - Original credentials
  * @param refreshedCreds - Credentials returned from refresh operation
  * @returns Built credentials or error message
  */

package/dist/auth/build-refreshed-credentials.js

@@ -1,20 +1,32 @@
 /**
- * Build refreshed credentials with source and provider context preserved.
+ * Build refreshed credentials with provider context preserved.
  */
 /**
- * Build refreshed credentials, preserving _source marker and handling
- * per-provider vs bundled credential formats.
+ * Build refreshed credentials, preserving provider context.
  *
- * @param originalCreds - Original credentials with _source marker
+ * For OpenCode (per-provider), extracts the specific provider's refreshed data.
+ * For other agents, uses the refreshed data directly.
+ *
+ * @param originalCreds - Original credentials
  * @param refreshedCreds - Credentials returned from refresh operation
  * @returns Built credentials or error message
  */
 function buildRefreshedCredentials(originalCreds, refreshedCreds) {
-    // Per-provider refresh: extract just the refreshed provider's data
-    if (originalCreds.provider) {
+    // OpenCode per-provider refresh: verify provider matches and use data directly
+    if (originalCreds.agent === "opencode" && originalCreds.provider) {
         const normalizedProvider = originalCreds.provider.trim();
-        const providerData = refreshedCreds.data[normalizedProvider];
-        if (!providerData || typeof providerData !== "object") {
+        // refreshedCreds from loadCredentialsFromDirectory is now per-provider format:
+        // - refreshedCreds.provider = the provider name
+        // - refreshedCreds.data = the provider's auth entry directly
+        if (refreshedCreds.agent !== "opencode") {
+            return {
+                ok: false,
+                error: `Provider '${normalizedProvider}' not found in refreshed credentials`,
+            };
+        }
+        // TypeScript narrows to OpenCodeCredentials which has provider as required
+        // (z.string().trim().min(1) in axshared) - NOT optional despite Credentials union
+        if (refreshedCreds.provider.trim() !== normalizedProvider) {
             return {
                 ok: false,
                 error: `Provider '${normalizedProvider}' not found in refreshed credentials`,
@@ -24,24 +36,27 @@ function buildRefreshedCredentials(originalCreds, refreshedCreds) {
             ok: true,
             credentials: {
                 agent: originalCreds.agent,
-                type: originalCreds.type,
+                type: refreshedCreds.type,
                 provider: normalizedProvider,
-                data: {
-                    ...providerData,
-                    _source: originalCreds.data._source,
-                },
+                data: refreshedCreds.data,
             },
         };
     }
-    // Bundled refresh: use all credentials as-is
+    // Standard agent refresh: use refreshed data
+    // Both originalCreds and refreshedCreds are standard agents here (not OpenCode)
+    if (originalCreds.agent === "opencode") {
+        // TypeScript narrowing: unreachable, but satisfies type checker
+        return {
+            ok: false,
+            error: "Unexpected OpenCode credential without provider",
+        };
+    }
     return {
         ok: true,
         credentials: {
-            ...refreshedCreds,
-            data: {
-                ...refreshedCreds.data,
-                _source: originalCreds.data._source,
-            },
+            agent: originalCreds.agent,
+            type: refreshedCreds.type,
+            data: refreshedCreds.data,
         },
     };
 }

package/dist/auth/extract-creds-from-directory.d.ts

@@ -1,16 +1,20 @@
 /**
  * Common utility for extracting credentials from a directory.
  */
-import type { AgentCli } from "axshared";
 import type { Credentials } from "./types.js";
+/** Standard agents (all except OpenCode) */
+type StandardAgentCli = "claude" | "codex" | "gemini" | "copilot";
 /**
  * Extract credentials from a JSON file in a directory.
  *
- * @param agentId - The agent ID
+ * Only for standard agents (claude, codex, gemini, copilot).
+ * OpenCode has its own extraction logic due to different credential structure.
+ *
+ * @param agentId - The agent ID (standard agents only)
  * @param directory - Directory to read from
  * @param fileName - Name of the credentials file
  * @param transform - Optional transform to apply to file contents
  * @returns Credentials or undefined if not found
  */
-declare function extractCredsFromDirectory(agentId: AgentCli, directory: string, fileName: string, transform?: (data: Record<string, unknown>) => Record<string, unknown> | undefined): Credentials | undefined;
+declare function extractCredsFromDirectory(agentId: StandardAgentCli, directory: string, fileName: string, transform?: (data: Record<string, unknown>) => Record<string, unknown> | undefined): Credentials | undefined;
 export { extractCredsFromDirectory };

package/dist/auth/extract-creds-from-directory.js

@@ -6,7 +6,10 @@ import path from "node:path";
 /**
  * Extract credentials from a JSON file in a directory.
  *
- * @param agentId - The agent ID
+ * Only for standard agents (claude, codex, gemini, copilot).
+ * OpenCode has its own extraction logic due to different credential structure.
+ *
+ * @param agentId - The agent ID (standard agents only)
  * @param directory - Directory to read from
  * @param fileName - Name of the credentials file
  * @param transform - Optional transform to apply to file contents

package/dist/auth/is-token-expired.d.ts

@@ -1,5 +1,11 @@
 /**
- * Token and credential expiry check utilities.
+ * Token and credential expiry/refresh utilities.
+ *
+ * Provides field detection for common OAuth credential formats:
+ * - Google OAuth: expiry_date (ms), refresh_token
+ * - Generic OAuth: expires_at (s or ms), refresh_token
+ * - OpenCode: expires (ms), refresh
+ * - Claude: expiresAt (ms), refreshToken (camelCase)
  */
 /**
  * Check if a JWT token is expired.
@@ -23,4 +29,48 @@ declare function isTokenExpired(token: string, bufferSeconds?: number): boolean
  * @returns true if expired, false if valid, undefined if no expiry field found
  */
 declare function isCredentialExpired(data: Record<string, unknown>, bufferSeconds?: number): boolean | undefined;
-export { isCredentialExpired, isTokenExpired };
+/**
+ * Extract expiry timestamp in milliseconds from credential data.
+ *
+ * Checks common expiry field names in order of preference:
+ * - `expiry_date`: Google OAuth (milliseconds)
+ * - `expires_at`: Generic OAuth (seconds or milliseconds, auto-detected)
+ * - `expiresAt`: Claude (seconds or milliseconds, auto-detected)
+ * - `expires`: OpenCode (seconds or milliseconds, auto-detected)
+ */
+declare function extractExpiryTimestamp(data: Record<string, unknown>): number | undefined;
+/**
+ * Extract expiry date from credential data.
+ *
+ * Convenience wrapper around {@link extractExpiryTimestamp} that returns
+ * a Date object instead of milliseconds.
+ *
+ * @param data - The credential data object
+ * @returns Date if expiry field found, undefined otherwise
+ */
+declare function extractExpiryDate(data: Record<string, unknown>): Date | undefined;
+/**
+ * Credential data containing a refresh token.
+ *
+ * Union of all supported refresh token field naming conventions.
+ */
+type RefreshableCredentials = (Record<string, unknown> & {
+    refresh_token: string;
+}) | (Record<string, unknown> & {
+    refreshToken: string;
+}) | (Record<string, unknown> & {
+    refresh: string;
+});
+/**
+ * Check if credential data contains a refresh token.
+ *
+ * Supports multiple field naming conventions:
+ * - `refresh_token`: Standard OAuth / Google / Generic
+ * - `refreshToken`: Claude (camelCase)
+ * - `refresh`: OpenCode
+ *
+ * @param data - The credential data object (accepts unknown for safety)
+ * @returns true if a refresh token field exists with a string value
+ */
+declare function isRefreshable(data: unknown): data is RefreshableCredentials;
+export { extractExpiryDate, extractExpiryTimestamp, isCredentialExpired, isRefreshable, isTokenExpired, type RefreshableCredentials, };

package/dist/auth/is-token-expired.js

@@ -1,5 +1,11 @@
 /**
- * Token and credential expiry check utilities.
+ * Token and credential expiry/refresh utilities.
+ *
+ * Provides field detection for common OAuth credential formats:
+ * - Google OAuth: expiry_date (ms), refresh_token
+ * - Generic OAuth: expires_at (s or ms), refresh_token
+ * - OpenCode: expires (ms), refresh
+ * - Claude: expiresAt (ms), refreshToken (camelCase)
  */
 /**
  * Timestamp threshold to distinguish seconds from milliseconds.
@@ -65,7 +71,15 @@ function isCredentialExpired(data, bufferSeconds = 60) {
     const bufferMs = bufferSeconds * 1000;
     return nowMs > expiryTimestampMs - bufferMs;
 }
-/** Extract expiry timestamp in milliseconds from credential data. */
+/**
+ * Extract expiry timestamp in milliseconds from credential data.
+ *
+ * Checks common expiry field names in order of preference:
+ * - `expiry_date`: Google OAuth (milliseconds)
+ * - `expires_at`: Generic OAuth (seconds or milliseconds, auto-detected)
+ * - `expiresAt`: Claude (seconds or milliseconds, auto-detected)
+ * - `expires`: OpenCode (seconds or milliseconds, auto-detected)
+ */
 function extractExpiryTimestamp(data) {
     // Google OAuth uses expiry_date (milliseconds)
     if (typeof data.expiry_date === "number") {
@@ -77,10 +91,62 @@ function extractExpiryTimestamp(data) {
             ? data.expires_at * 1000
             : data.expires_at;
     }
-    // OpenCode uses expires (milliseconds)
+    // Claude uses expiresAt (milliseconds, camelCase)
+    if (typeof data.expiresAt === "number") {
+        return data.expiresAt < SECONDS_THRESHOLD
+            ? data.expiresAt * 1000
+            : data.expiresAt;
+    }
+    // OpenCode uses expires (milliseconds, but apply heuristic for safety)
     if (typeof data.expires === "number") {
-        return data.expires;
+        return data.expires < SECONDS_THRESHOLD
+            ? data.expires * 1000
+            : data.expires;
     }
     return undefined;
 }
-export { isCredentialExpired, isTokenExpired };
+/**
+ * Extract expiry date from credential data.
+ *
+ * Convenience wrapper around {@link extractExpiryTimestamp} that returns
+ * a Date object instead of milliseconds.
+ *
+ * @param data - The credential data object
+ * @returns Date if expiry field found, undefined otherwise
+ */
+function extractExpiryDate(data) {
+    const ts = extractExpiryTimestamp(data);
+    if (ts === undefined)
+        return undefined;
+    return new Date(ts);
+}
+/**
+ * Check if credential data contains a refresh token.
+ *
+ * Supports multiple field naming conventions:
+ * - `refresh_token`: Standard OAuth / Google / Generic
+ * - `refreshToken`: Claude (camelCase)
+ * - `refresh`: OpenCode
+ *
+ * @param data - The credential data object (accepts unknown for safety)
+ * @returns true if a refresh token field exists with a string value
+ */
+function isRefreshable(data) {
+    if (typeof data !== "object" || data === null)
+        return false;
+    const record = data;
+    // Standard OAuth field name
+    if ("refresh_token" in record && typeof record.refresh_token === "string") {
+        return true;
+    }
+    // Claude uses camelCase
+    if ("refreshToken" in record && typeof record.refreshToken === "string") {
+        return true;
+    }
+    // OpenCode uses 'refresh'
+    if ("refresh" in record && typeof record.refresh === "string") {
+        return true;
+    }
+    return false;
+}
+export { extractExpiryDate, extractExpiryTimestamp, isCredentialExpired, isRefreshable, isTokenExpired, };

package/dist/auth/refresh-credentials.d.ts

@@ -4,13 +4,15 @@
  * Refreshes credentials by running the agent in an isolated temp config,
  * triggering its internal auth refresh mechanism.
  */
-import type { Credentials } from "./types.js";
+import { type Credentials } from "./types.js";
 /** Options for credential refresh */
 interface RefreshOptions {
     /** Timeout in ms (default: 30000) */
     timeout?: number;
     /** Provider for multi-provider agents (OpenCode) */
     provider?: string;
+    /** Storage type for persisting refreshed credentials (default: "file") */
+    storage?: "keychain" | "file";
 }
 /** Result of a credential refresh attempt */
 type RefreshResult = {
@@ -39,22 +41,46 @@ type RefreshAndPersistResult = {
     ok: false;
     staleCredentials: Credentials;
 };
+/** Install function type for refreshAndPersist */
+type InstallFunction = (creds: Credentials, options?: {
+    storage?: "keychain" | "file";
+}) => {
+    ok: boolean;
+    message: string;
+};
 /**
- * Refresh credentials and persist to original storage.
+ * Refresh credentials and persist to storage.
  *
  * Higher-level function that:
  * 1. Refreshes credentials via agent subprocess
- * 2. Preserves _source marker from original credentials
- * 3. Persists refreshed credentials to original storage location
+ * 2. Persists refreshed credentials to the specified storage location
  *
- * @param creds - Original credentials with _source marker
+ * @param creds - Original credentials
  * @param installFunction - Function to install credentials (avoids circular import)
- * @param options - Refresh options
+ * @param options - Refresh options including storage type
  * @returns Refreshed credentials or original credentials on failure
  */
-declare function refreshAndPersist(creds: Credentials, installFunction: (c: Credentials) => {
-    ok: boolean;
-    message: string;
-}, options?: RefreshOptions): Promise<RefreshAndPersistResult>;
-export { refreshAndPersist, refreshCredentials };
-export type { RefreshAndPersistResult, RefreshOptions, RefreshResult };
+declare function refreshAndPersist(creds: Credentials, installFunction: InstallFunction, options?: RefreshOptions): Promise<RefreshAndPersistResult>;
+/** Result of refreshing an opaque credential blob */
+type RefreshBlobResult = {
+    ok: true;
+    blob: unknown;
+    expiresAt: Date | undefined;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Refresh credentials from an opaque blob.
+ *
+ * This is the vault-friendly interface: accepts an opaque blob, validates it,
+ * refreshes the credentials, and returns the new blob. The caller (axvault)
+ * never needs to understand the blob's internal structure.
+ *
+ * @param blob - Opaque credential blob (expected to be a Credentials object)
+ * @param options - Refresh options (timeout)
+ * @returns RefreshBlobResult with new blob and expiresAt, or error
+ */
+declare function refreshBlob(blob: unknown, options?: RefreshOptions): Promise<RefreshBlobResult>;
+export { refreshAndPersist, refreshBlob, refreshCredentials };
+export type { RefreshAndPersistResult, RefreshBlobResult, RefreshOptions, RefreshResult, };

package/dist/auth/refresh-credentials.js

@@ -7,8 +7,10 @@
 import { cleanupCredentials, runAgent } from "axexec";
 import { buildRefreshedCredentials } from "./build-refreshed-credentials.js";
 import { formatRunError } from "./format-run-error.js";
-import { mergeOpenCodeBundle, resolveRefreshCredentials, } from "./resolve-refresh-credentials.js";
+import { extractExpiryDate } from "./is-token-expired.js";
+import { resolveRefreshCredentials } from "./resolve-refresh-credentials.js";
 import { waitForRefreshedCredentials } from "./wait-for-refreshed-credentials.js";
+import { parseCredentials } from "./types.js";
 /** Default timeout for refresh operations in milliseconds */
 const DEFAULT_REFRESH_TIMEOUT_MS = 30_000;
 async function safeCleanup(directory) {
@@ -33,7 +35,7 @@ async function safeCleanup(directory) {
 async function refreshCredentials(creds, options) {
     const timeoutMs = options?.timeout ?? DEFAULT_REFRESH_TIMEOUT_MS;
     const deadlineMs = Date.now() + timeoutMs;
-    const resolved = resolveRefreshCredentials(creds, options);
+    const resolved = resolveRefreshCredentials(creds);
     if (!resolved.ok) {
         return { ok: false, error: resolved.error };
     }
@@ -88,13 +90,21 @@ async function refreshCredentials(creds, options) {
         if (!directories) {
             return { ok: false, error: "No directories in execution metadata" };
         }
-        const refreshedCredentials = await waitForRefreshedCredentials(resolved.credentials.agent, directories, deadlineMs);
+        // For OpenCode, pass the provider to filter refreshed credentials
+        const provider = resolved.credentials.agent === "opencode"
+            ? resolved.credentials.provider
+            : undefined;
+        const refreshedCredentials = await waitForRefreshedCredentials(resolved.credentials.agent, directories, deadlineMs, { provider });
         if (!refreshedCredentials) {
             return { ok: false, error: "No credentials found after refresh" };
         }
+        const buildResult = buildRefreshedCredentials(creds, refreshedCredentials);
+        if (!buildResult.ok) {
+            return { ok: false, error: buildResult.error };
+        }
         return {
             ok: true,
-            credentials: mergeOpenCodeBundle(creds, refreshedCredentials, resolved.mergeProvider),
+            credentials: buildResult.credentials,
         };
     }
     finally {
@@ -105,16 +115,15 @@ async function refreshCredentials(creds, options) {
     }
 }
 /**
- * Refresh credentials and persist to original storage.
+ * Refresh credentials and persist to storage.
  *
  * Higher-level function that:
  * 1. Refreshes credentials via agent subprocess
- * 2. Preserves _source marker from original credentials
- * 3. Persists refreshed credentials to original storage location
+ * 2. Persists refreshed credentials to the specified storage location
  *
- * @param creds - Original credentials with _source marker
+ * @param creds - Original credentials
  * @param installFunction - Function to install credentials (avoids circular import)
- * @param options - Refresh options
+ * @param options - Refresh options including storage type
  * @returns Refreshed credentials or original credentials on failure
  */
 async function refreshAndPersist(creds, installFunction, options) {
@@ -123,17 +132,39 @@ async function refreshAndPersist(creds, installFunction, options) {
         console.error(`Warning: Token refresh failed: ${result.error}`);
         return { ok: false, staleCredentials: creds };
     }
-    // Build refreshed credentials, preserving _source and provider context
-    const buildResult = buildRefreshedCredentials(creds, result.credentials);
-    if (!buildResult.ok) {
-        console.error(`Warning: ${buildResult.error}`);
-        return { ok: false, staleCredentials: creds };
-    }
     // Persist refreshed credentials back to storage
-    const installResult = installFunction(buildResult.credentials);
+    const storage = options?.storage ?? "file";
+    const installResult = installFunction(result.credentials, { storage });
     if (!installResult.ok) {
         console.error(`Warning: Failed to save refreshed credentials: ${installResult.message}`);
     }
-    return { ok: true, credentials: buildResult.credentials };
+    return { ok: true, credentials: result.credentials };
+}
+/**
+ * Refresh credentials from an opaque blob.
+ *
+ * This is the vault-friendly interface: accepts an opaque blob, validates it,
+ * refreshes the credentials, and returns the new blob. The caller (axvault)
+ * never needs to understand the blob's internal structure.
+ *
+ * @param blob - Opaque credential blob (expected to be a Credentials object)
+ * @param options - Refresh options (timeout)
+ * @returns RefreshBlobResult with new blob and expiresAt, or error
+ */
+async function refreshBlob(blob, options) {
+    // Parse and validate the blob
+    const credentials = parseCredentials(blob);
+    if (!credentials) {
+        return { ok: false, error: "Invalid credential format" };
+    }
+    // Refresh using existing function
+    const result = await refreshCredentials(credentials, options);
+    if (!result.ok) {
+        return { ok: false, error: result.error };
+    }
+    // Extract expiry from the refreshed data
+    const expiresAt = extractExpiryDate(result.credentials.data);
+    // Return the new blob (the Credentials object itself)
+    return { ok: true, blob: result.credentials, expiresAt };
 }
-export { refreshAndPersist, refreshCredentials };
+export { refreshAndPersist, refreshBlob, refreshCredentials };