@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/auth/file.js

@@ -1,210 +1,410 @@
-import { readFile, writeFile, mkdir } from "node:fs/promises";
-import { dirname } from "node:path";
 import { InMemoryAccountInfo } from "./in-memory.js";
-class FileAccountInfo {
-  /**
-   * Constructs a `FileAccountInfo` bound to a JSON file on disk. The file is
-   * created on the first `setAuth` write; reading it back happens via
-   * {@link load}.
-   *
-   * @param path - Absolute path to the JSON file that backs this account info.
-   */
-  constructor(path) {
-    this.path = path;
-  }
-  inner = new InMemoryAccountInfo();
-  writeQueue = Promise.resolve();
-  /**
-   * Reads the JSON file at the configured path and populates in-memory state.
-   * If the file is missing or contains invalid JSON, leaves state empty and
-   * returns silently (a re-auth is expected next).
-   *
-   * @returns A promise that resolves when load is complete.
-   */
-  async load() {
-    try {
-      const text = await readFile(this.path, "utf8");
-      const parsed = JSON.parse(text);
-      this.inner.setAuth(parsed);
-    } catch {
-    }
-  }
-  /**
-   * Persists the current auth response to the file. Atomically queues writes
-   * so concurrent updates serialize.
-   *
-   * @returns A promise that resolves when the write completes.
-   */
-  flush() {
-    const auth = this.inner.getAuth();
-    const next = this.writeQueue.then(async () => {
-      if (auth === null) {
-        try {
-          await writeFile(this.path, "", "utf8");
-        } catch {
-        }
-        return;
-      }
-      await mkdir(dirname(this.path), { recursive: true });
-      await writeFile(this.path, JSON.stringify(auth), "utf8");
-    });
-    this.writeQueue = next.catch(() => {
-    });
-    return next;
-  }
-  /**
-   * Stores the given authorization response and triggers an async write to disk.
-   *
-   * @param auth - The authorize-account response to persist.
-   */
-  setAuth(auth) {
-    this.inner.setAuth(auth);
-    void this.flush();
-  }
-  /**
-   * Returns the currently cached authorization response, or `null` if none.
-   *
-   * @returns The cached authorization response, or `null` if not authorized.
-   */
-  getAuth() {
-    return this.inner.getAuth();
-  }
-  /** Discards in-memory state and clears the on-disk file. */
-  clear() {
-    this.inner.clear();
-    void this.flush();
-  }
-  /**
-   * Returns the cached B2 API URL.
-   *
-   * @returns The base URL for B2 API calls.
-   */
-  getApiUrl() {
-    return this.inner.getApiUrl();
-  }
-  /**
-   * Returns the cached file-download URL.
-   *
-   * @returns The base URL for file downloads.
-   */
-  getDownloadUrl() {
-    return this.inner.getDownloadUrl();
-  }
-  /**
-   * Returns the cached session authorization token.
-   *
-   * @returns The current authorization token.
-   */
-  getAuthToken() {
-    return this.inner.getAuthToken();
-  }
-  /**
-   * Returns the cached account identifier.
-   *
-   * @returns The authorized account ID.
-   */
-  getAccountId() {
-    return this.inner.getAccountId();
-  }
-  /**
-   * Returns the server-recommended part size for multipart uploads.
-   *
-   * @returns The recommended part size in bytes.
-   */
-  getRecommendedPartSize() {
-    return this.inner.getRecommendedPartSize();
-  }
-  /**
-   * Returns the server-enforced minimum part size for multipart uploads.
-   *
-   * @returns The absolute minimum part size in bytes.
-   */
-  getAbsoluteMinimumPartSize() {
-    return this.inner.getAbsoluteMinimumPartSize();
-  }
-  /**
-   * Returns the cached S3-compatible API URL.
-   *
-   * @returns The base URL for the S3-compatible API.
-   */
-  getS3ApiUrl() {
-    return this.inner.getS3ApiUrl();
-  }
-  /**
-   * Returns the bucket the key is restricted to, if any.
-   *
-   * @returns The restricted bucket ID, or `null` if the key is unrestricted.
-   */
-  getAllowedBucketId() {
-    return this.inner.getAllowedBucketId();
-  }
-  /**
-   * Takes an upload URL from the in-memory pool for the given bucket.
-   *
-   * @param bucketId - Bucket to check out an upload URL for.
-   *
-   * @returns A reusable upload URL entry, or `null` if none are pooled.
-   */
-  checkoutUploadUrl(bucketId) {
-    return this.inner.checkoutUploadUrl(bucketId);
-  }
-  /**
-   * Returns a still-valid upload URL to the pool for reuse.
-   *
-   * @param bucketId - Bucket the upload URL belongs to.
-   * @param entry - Upload URL entry to return.
-   */
-  returnUploadUrl(bucketId, entry) {
-    this.inner.returnUploadUrl(bucketId, entry);
-  }
-  /**
-   * Removes an upload URL from the pool after an upload error.
-   *
-   * @param bucketId - Bucket the failed upload URL belongs to.
-   * @param entry - Upload URL entry to evict.
-   */
-  evictUploadUrl(bucketId, entry) {
-    this.inner.evictUploadUrl(bucketId, entry);
-  }
-  /**
-   * Takes a large-file part upload URL from the in-memory pool.
-   *
-   * @param fileId - Large file to check out a part upload URL for.
-   *
-   * @returns A reusable part upload URL entry, or `null` if none are pooled.
-   */
-  checkoutPartUploadUrl(fileId) {
-    return this.inner.checkoutPartUploadUrl(fileId);
-  }
-  /**
-   * Returns a still-valid part upload URL to the pool for reuse.
-   *
-   * @param fileId - Large file the part upload URL belongs to.
-   * @param entry - Part upload URL entry to return.
-   */
-  returnPartUploadUrl(fileId, entry) {
-    this.inner.returnPartUploadUrl(fileId, entry);
-  }
-  /**
-   * Removes a part upload URL from the pool after an error.
-   *
-   * @param fileId - Large file the failed part upload URL belongs to.
-   * @param entry - Part upload URL entry to evict.
-   */
-  evictPartUploadUrl(fileId, entry) {
-    this.inner.evictPartUploadUrl(fileId, entry);
-  }
-  /**
-   * Awaits any pending disk writes. Call before process exit to ensure the
-   * latest state is persisted.
-   *
-   * @returns A promise that resolves once all queued writes are flushed.
-   */
-  async flushed() {
-    await this.writeQueue;
-  }
+import { getRealmUrl } from "./realms.js";
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+//#region src/auth/file.ts
+var PRIVATE_FILE_MODE = 384;
+var PERSISTED_AUTH_VERSION = 1;
+var BUILT_IN_PRODUCTION_REALM_URL = getRealmUrl("production");
+var BUILT_IN_STAGING_REALM_URL = getRealmUrl("staging");
+var PRODUCTION_HOST_SUFFIX = "backblazeb2.com";
+var STAGING_HOST_SUFFIX = "backblaze.net";
+function readPersistedAuthState(value) {
+	if (value === null || typeof value !== "object") return null;
+	const maybeState = value;
+	if (maybeState._b2sdk?.version !== void 0 && maybeState._b2sdk.version !== PERSISTED_AUTH_VERSION) return null;
+	return {
+		auth: value,
+		realmUrl: maybeState._b2sdk !== void 0 && typeof maybeState._b2sdk.realmUrl === "string" ? maybeState._b2sdk.realmUrl : null,
+		applicationKeyId: maybeState._b2sdk !== void 0 && typeof maybeState._b2sdk.applicationKeyId === "string" ? maybeState._b2sdk.applicationKeyId : null
+	};
 }
-export {
-  FileAccountInfo
+function isProductionBackblazeEndpoint(url) {
+	try {
+		const parsed = new URL(url);
+		return parsed.protocol === "https:" && hasHostSuffix(parsed.hostname, PRODUCTION_HOST_SUFFIX);
+	} catch {
+		return false;
+	}
+}
+function isProductionAuthResponse(auth) {
+	try {
+		const storageApi = auth.apiInfo.storageApi;
+		return [
+			storageApi.apiUrl,
+			storageApi.downloadUrl,
+			storageApi.s3ApiUrl
+		].every(isProductionBackblazeEndpoint);
+	} catch {
+		return false;
+	}
+}
+function verifiedRealmEndpointSuffix(realmUrl) {
+	try {
+		const realm = new URL(realmUrl);
+		if (realm.origin === new URL(BUILT_IN_PRODUCTION_REALM_URL).origin) return PRODUCTION_HOST_SUFFIX;
+		if (realm.origin === new URL(BUILT_IN_STAGING_REALM_URL).origin) return STAGING_HOST_SUFFIX;
+	} catch {}
+	return null;
+}
+function hasHostSuffix(hostname, suffix) {
+	const host = hostname.toLowerCase();
+	const lowered = suffix.toLowerCase();
+	return host === lowered || host.endsWith(`.${lowered}`);
+}
+function isEndpointInRealm(url, realmUrl) {
+	try {
+		const realm = new URL(realmUrl);
+		const endpoint = new URL(url);
+		const endpointHost = endpoint.hostname.toLowerCase();
+		const realmHost = realm.hostname.toLowerCase();
+		if (isLoopbackEndpointHost(endpointHost) || isLoopbackEndpointHost(realmHost)) return endpoint.origin === realm.origin;
+		const verifiedSuffix = verifiedRealmEndpointSuffix(realmUrl);
+		if (verifiedSuffix !== null) return endpoint.protocol === "https:" && hasHostSuffix(endpointHost, verifiedSuffix);
+		return endpoint.protocol === realm.protocol && hasHostSuffix(endpointHost, realmHost);
+	} catch {
+		return false;
+	}
+}
+function isLoopbackEndpointHost(host) {
+	if (host === "localhost" || host === "::1" || host === "[::1]") return true;
+	const parts = host.split(".");
+	return parts.length === 4 && parts[0] === "127" && parts.every((part) => /^\d+$/.test(part) && Number(part) <= 255);
+}
+function authEndpointsMatchRealm(auth, realmUrl) {
+	try {
+		const storageApi = auth.apiInfo.storageApi;
+		return [
+			storageApi.apiUrl,
+			storageApi.downloadUrl,
+			storageApi.s3ApiUrl
+		].every((url) => isEndpointInRealm(url, realmUrl));
+	} catch {
+		return false;
+	}
+}
+/**
+* Node-only {@link AccountInfo} backend that persists the authorization
+* response to a JSON file. Upload URL pools remain in memory because URLs are
+* short-lived and shouldn't be shared across processes.
+* The JSON file contains a live B2 authorization token, so treat it as
+* sensitive and keep it out of shared or world-readable locations.
+* `FileAccountInfo` serializes writes within one process but does not provide
+* inter-process locking. If multiple processes share one path, use
+* {@link FileAccountInfoOptions.onDiscard} and {@link FileAccountInfoOptions.onWriteError}
+* to observe cache churn, or prefer one cache path per resolved realm and key.
+*
+* On instantiation, call {@link FileAccountInfo.load} to populate state from
+* disk (or start fresh if the file is missing or corrupt). The authorization
+* response is written back to disk on every {@link setAuth} or {@link clear}
+* call so a process restart can resume without re-authorizing.
+* Cache files without an SDK metadata application-key binding are ignored once
+* bound to a `B2Client`, because the SDK cannot verify which key wrote them.
+*
+* This module imports `node:fs/promises`; do not load it in browser bundles.
+*/
+var FileAccountInfo = class {
+	path;
+	options;
+	inner = new InMemoryAccountInfo();
+	writeQueue = Promise.resolve();
+	realmUrl;
+	loadedAuthRealmUrl;
+	applicationKeyId;
+	loadedAuthApplicationKeyId;
+	/**
+	* Constructs a `FileAccountInfo` bound to a JSON file on disk. The file is
+	* created on the first `setAuth` write; reading it back happens via
+	* {@link load}.
+	*
+	* @param path - Absolute path to the JSON file that backs this account info.
+	* @param options - Optional discard and write-error observers.
+	*/
+	constructor(path, options = {}) {
+		this.path = path;
+		this.options = options;
+	}
+	/**
+	* Reads the JSON file at the configured path and populates in-memory state.
+	* If the file is missing or contains invalid JSON, leaves state empty and
+	* returns silently (a re-auth is expected next).
+	*
+	* @returns A promise that resolves when load is complete.
+	*/
+	async load() {
+		try {
+			const text = await readFile(this.path, "utf8");
+			const parsed = readPersistedAuthState(JSON.parse(text));
+			if (parsed === null) return;
+			this.inner.setAuth(parsed.auth);
+			this.loadedAuthRealmUrl = parsed.realmUrl;
+			this.loadedAuthApplicationKeyId = parsed.applicationKeyId;
+			this.discardMismatchedAuth();
+		} catch {}
+	}
+	/**
+	* Binds this cache to the configured realm URL. `B2Client` calls this when a
+	* FileAccountInfo instance is supplied, so stale auth produced by another
+	* realm is discarded before it can be used.
+	*
+	* @param realmUrl - Resolved authorize-account realm URL for the client.
+	*/
+	setRealmUrl(realmUrl) {
+		this.realmUrl = realmUrl;
+		this.discardMismatchedAuth();
+	}
+	/**
+	* Binds this cache to the configured application key ID. `B2Client` calls
+	* this when a FileAccountInfo instance is supplied, so stale auth produced by
+	* another key is discarded before it can be used.
+	*
+	* @param applicationKeyId - Application key ID configured on the client.
+	*/
+	setApplicationKeyId(applicationKeyId) {
+		this.applicationKeyId = applicationKeyId;
+		this.discardMismatchedAuth();
+	}
+	discardMismatchedAuth() {
+		const auth = this.inner.getAuth();
+		if (auth === null) return;
+		const reason = this.mismatchReason(auth);
+		if (reason === null) return;
+		this.inner.clear();
+		this.options.onDiscard?.({
+			path: this.path,
+			reason,
+			cachedRealmUrl: this.loadedAuthRealmUrl,
+			expectedRealmUrl: this.realmUrl,
+			cachedApplicationKeyId: this.loadedAuthApplicationKeyId,
+			expectedApplicationKeyId: this.applicationKeyId
+		});
+		this.loadedAuthRealmUrl = void 0;
+		this.loadedAuthApplicationKeyId = void 0;
+	}
+	mismatchReason(auth) {
+		const realmMatches = this.realmUrl === void 0 || this.loadedAuthRealmUrl === this.realmUrl || this.loadedAuthRealmUrl === null && this.realmUrl === BUILT_IN_PRODUCTION_REALM_URL && isProductionAuthResponse(auth);
+		const applicationKeyMatches = this.applicationKeyId === void 0 || this.loadedAuthApplicationKeyId === this.applicationKeyId;
+		if (!realmMatches) return "realm_mismatch";
+		if (!applicationKeyMatches) return "application_key_mismatch";
+		if (this.realmUrl !== void 0 && !authEndpointsMatchRealm(auth, this.realmUrl)) return "endpoint_mismatch";
+		return null;
+	}
+	/**
+	* Persists the current auth response to the file. Atomically queues writes
+	* so concurrent updates serialize.
+	*
+	* @returns A promise that resolves when the write completes.
+	*/
+	flush() {
+		const auth = this.inner.getAuth();
+		const next = this.writeQueue.then(async () => {
+			if (auth === null) {
+				try {
+					await this.writePrivateFileAtomically("");
+				} catch {}
+				return;
+			}
+			const contents = this.realmUrl !== void 0 ? JSON.stringify({
+				...auth,
+				_b2sdk: {
+					version: PERSISTED_AUTH_VERSION,
+					realmUrl: this.realmUrl,
+					...this.applicationKeyId !== void 0 ? { applicationKeyId: this.applicationKeyId } : {}
+				}
+			}) : JSON.stringify(auth);
+			await this.writePrivateFileAtomically(contents);
+		});
+		this.writeQueue = next.catch((error) => {
+			this.options.onWriteError?.({
+				path: this.path,
+				error
+			});
+		});
+		return next;
+	}
+	async writePrivateFileAtomically(contents) {
+		const dir = dirname(this.path);
+		const tempPath = join(dir, `.${basename(this.path)}.${process.pid}.${randomUUID()}.tmp`);
+		await mkdir(dir, { recursive: true });
+		try {
+			await writeFile(tempPath, contents, {
+				encoding: "utf8",
+				mode: PRIVATE_FILE_MODE
+			});
+			await chmod(tempPath, PRIVATE_FILE_MODE);
+			await rename(tempPath, this.path);
+			await chmod(this.path, PRIVATE_FILE_MODE);
+		} catch (error) {
+			await rm(tempPath, { force: true }).catch(() => {});
+			throw error;
+		}
+	}
+	/**
+	* Stores the given authorization response and triggers an async write to disk.
+	*
+	* @param auth - The authorize-account response to persist.
+	*/
+	setAuth(auth) {
+		this.inner.setAuth(auth);
+		this.loadedAuthRealmUrl = this.realmUrl ?? null;
+		this.loadedAuthApplicationKeyId = this.applicationKeyId ?? null;
+		this.flush();
+	}
+	/**
+	* Returns the currently cached authorization response, or `null` if none.
+	*
+	* @returns The cached authorization response, or `null` if not authorized.
+	*/
+	getAuth() {
+		return this.inner.getAuth();
+	}
+	/** Discards in-memory state and clears the on-disk file. */
+	clear() {
+		this.inner.clear();
+		this.loadedAuthRealmUrl = void 0;
+		this.loadedAuthApplicationKeyId = void 0;
+		this.flush();
+	}
+	/**
+	* Returns the cached B2 API URL.
+	*
+	* @returns The base URL for B2 API calls.
+	*/
+	getApiUrl() {
+		return this.inner.getApiUrl();
+	}
+	/**
+	* Returns the cached file-download URL.
+	*
+	* @returns The base URL for file downloads.
+	*/
+	getDownloadUrl() {
+		return this.inner.getDownloadUrl();
+	}
+	/**
+	* Returns the cached session authorization token.
+	*
+	* @returns The current authorization token.
+	*/
+	getAuthToken() {
+		return this.inner.getAuthToken();
+	}
+	/**
+	* Returns the cached account identifier.
+	*
+	* @returns The authorized account ID.
+	*/
+	getAccountId() {
+		return this.inner.getAccountId();
+	}
+	/**
+	* Returns the server-recommended part size for multipart uploads.
+	*
+	* @returns The recommended part size in bytes.
+	*/
+	getRecommendedPartSize() {
+		return this.inner.getRecommendedPartSize();
+	}
+	/**
+	* Returns the server-enforced minimum part size for multipart uploads.
+	*
+	* @returns The absolute minimum part size in bytes.
+	*/
+	getAbsoluteMinimumPartSize() {
+		return this.inner.getAbsoluteMinimumPartSize();
+	}
+	/**
+	* Returns the cached S3-compatible API URL.
+	*
+	* @returns The base URL for the S3-compatible API.
+	*/
+	getS3ApiUrl() {
+		return this.inner.getS3ApiUrl();
+	}
+	/**
+	* Returns the bucket the key is restricted to, if any.
+	*
+	* @returns The restricted bucket ID, or `null` if the key is unrestricted.
+	*/
+	getAllowedBucketId() {
+		return this.inner.getAllowedBucketId();
+	}
+	/**
+	* Returns the buckets the key is restricted to, if any.
+	*
+	* @returns The restricted bucket IDs, or `null` if the key is unrestricted.
+	*/
+	getAllowedBucketIds() {
+		return this.inner.getAllowedBucketIds();
+	}
+	/**
+	* Takes an upload URL from the in-memory pool for the given bucket.
+	*
+	* @param bucketId - Bucket to check out an upload URL for.
+	*
+	* @returns A reusable upload URL entry, or `null` if none are pooled.
+	*/
+	checkoutUploadUrl(bucketId) {
+		return this.inner.checkoutUploadUrl(bucketId);
+	}
+	/**
+	* Returns a still-valid upload URL to the pool for reuse.
+	*
+	* @param bucketId - Bucket the upload URL belongs to.
+	* @param entry - Upload URL entry to return.
+	*/
+	returnUploadUrl(bucketId, entry) {
+		this.inner.returnUploadUrl(bucketId, entry);
+	}
+	/**
+	* Removes an upload URL from the pool after an upload error.
+	*
+	* @param bucketId - Bucket the failed upload URL belongs to.
+	* @param entry - Upload URL entry to evict.
+	*/
+	evictUploadUrl(bucketId, entry) {
+		this.inner.evictUploadUrl(bucketId, entry);
+	}
+	/**
+	* Takes a large-file part upload URL from the in-memory pool.
+	*
+	* @param fileId - Large file to check out a part upload URL for.
+	*
+	* @returns A reusable part upload URL entry, or `null` if none are pooled.
+	*/
+	checkoutPartUploadUrl(fileId) {
+		return this.inner.checkoutPartUploadUrl(fileId);
+	}
+	/**
+	* Returns a still-valid part upload URL to the pool for reuse.
+	*
+	* @param fileId - Large file the part upload URL belongs to.
+	* @param entry - Part upload URL entry to return.
+	*/
+	returnPartUploadUrl(fileId, entry) {
+		this.inner.returnPartUploadUrl(fileId, entry);
+	}
+	/**
+	* Removes a part upload URL from the pool after an error.
+	*
+	* @param fileId - Large file the failed part upload URL belongs to.
+	* @param entry - Part upload URL entry to evict.
+	*/
+	evictPartUploadUrl(fileId, entry) {
+		this.inner.evictPartUploadUrl(fileId, entry);
+	}
+	/**
+	* Awaits any pending disk writes. Call before process exit to ensure the
+	* latest state is persisted.
+	*
+	* @returns A promise that resolves once all queued writes are flushed.
+	*/
+	async flushed() {
+		await this.writeQueue;
+	}
 };
-//# sourceMappingURL=file.js.map
+//#endregion
+export { FileAccountInfo };
+
+//# sourceMappingURL=file.js.map