encoding

src/tiers/DiskStorageTier.ts

···
 	TierGetResult,
 	TierStreamResult,
 } from '../types/index.js';
-import { encodeKey } from '../utils/path-encoding.js';
+import { encodeKey, decodeKey } from '../utils/path-encoding.js';
 
 /**
  * Eviction policy for disk tier when size limit is reached.
···
 	 * - 'size': Evict largest files first
 	 */
 	evictionPolicy?: EvictionPolicy;
+
+	/**
+	 * Whether to encode colons in keys as %3A.
+	 *
+	 * @defaultValue true on Windows, false on Unix/macOS
+	 *
+	 * @remarks
+	 * Colons are invalid in Windows filenames but allowed on Unix.
+	 * Set to false to preserve colons for human-readable paths on Unix systems.
+	 * Set to true on Windows or for cross-platform compatibility.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Unix with readable paths
+	 * new DiskStorageTier({ directory: './cache', encodeColons: false })
+	 * // Result: cache/did:plc:abc123/site/index.html
+	 *
+	 * // Windows or cross-platform
+	 * new DiskStorageTier({ directory: './cache', encodeColons: true })
+	 * // Result: cache/did%3Aplc%3Aabc123/site/index.html
+	 * ```
+	 */
+	encodeColons?: boolean;
 }
 
 /**
···
 		{ size: number; createdAt: Date; lastAccessed: Date }
 	>();
 	private currentSize = 0;
+	private readonly encodeColons: boolean;
 
 	constructor(private config: DiskStorageTierConfig) {
 		if (!config.directory) {
···
 		if (config.maxSizeBytes !== undefined && config.maxSizeBytes <= 0) {
 			throw new Error('maxSizeBytes must be positive');
 		}
+
+		// Default: encode colons on Windows, preserve on Unix/macOS
+		const platform = process.platform;
+		this.encodeColons = config.encodeColons ?? platform === 'win32';
 
 		void this.ensureDirectory();
 		void this.rebuildIndex();
···
 	 * Get the filesystem path for a key's data file.
 	 */
 	private getFilePath(key: string): string {
-		const encoded = encodeKey(key);
+		const encoded = encodeKey(key, this.encodeColons);
 		return join(this.config.directory, encoded);
 	}
 

src/utils/path-encoding.ts

···
  * Encode a key to be safe for use as a filesystem path.
  *
  * @param key - The key to encode
+ * @param encodeColons - Whether to encode colons as %3A (default: false)
  * @returns Filesystem-safe encoded key
  *
  * @remarks
  * Preserves forward slashes to create directory structure.
  * Encodes characters that are problematic in filenames:
  * - Backslash (\) → %5C
- * - Colon (:) → %3A (invalid on Windows)
+ * - Colon (:) → %3A (when encodeColons is true, invalid on Windows)
  * - Asterisk (*) → %2A
  * - Question mark (?) → %3F
  * - Quote (") → %22
···
  * @example
  * ```typescript
  * const key = 'did:plc:abc123/site/index.html';
- * const encoded = encodeKey(key);
+ *
+ * // Encode colons (Windows/cross-platform)
+ * const encoded = encodeKey(key, true);
  * // Result: 'did%3Aplc%3Aabc123/site/index.html'
  * // Creates: cache/did%3Aplc%3Aabc123/site/index.html
+ *
+ * // Preserve colons (Unix/macOS with readable paths)
+ * const readable = encodeKey(key, false);
+ * // Result: 'did:plc:abc123/site/index.html'
+ * // Creates: cache/did:plc:abc123/site/index.html
  * ```
  */
-export function encodeKey(key: string): string {
-	return key
+export function encodeKey(key: string, encodeColons = false): string {
+	let result = key
 		.replace(/%/g, '%25') // Must be first!
-		.replace(/\\/g, '%5C')
-		.replace(/:/g, '%3A')
+		.replace(/\\/g, '%5C');
+
+	if (encodeColons) {
+		result = result.replace(/:/g, '%3A');
+	}
+
+	return result
 		.replace(/\*/g, '%2A')
 		.replace(/\?/g, '%3F')
 		.replace(/"/g, '%22')
···
  * Decode a filesystem-safe key back to original form.
  *
  * @param encoded - The encoded key
+ * @param decodeColons - Whether to decode %3A to : (default: false)
  * @returns Original key
  *
  * @example
  * ```typescript
  * const encoded = 'did%3Aplc%3Aabc123/site/index.html';
- * const key = decodeKey(encoded);
+ *
+ * // Decode with colons
+ * const key = decodeKey(encoded, true);
+ * // Result: 'did:plc:abc123/site/index.html'
+ *
+ * // Decode without colons (already readable)
+ * const readable = decodeKey('did:plc:abc123/site/index.html', false);
  * // Result: 'did:plc:abc123/site/index.html'
  * ```
  */
-export function decodeKey(encoded: string): string {
-	return encoded
+export function decodeKey(encoded: string, decodeColons = false): string {
+	let result = encoded
 		.replace(/%5C/g, '\\')
-		.replace(/%3A/g, ':')
 		.replace(/%2A/g, '*')
 		.replace(/%3F/g, '?')
 		.replace(/%22/g, '"')
 		.replace(/%3C/g, '<')
 		.replace(/%3E/g, '>')
 		.replace(/%7C/g, '|')
-		.replace(/%00/g, '\0')
-		.replace(/%25/g, '%'); // Must be last!
+		.replace(/%00/g, '\0');
+
+	if (decodeColons) {
+		result = result.replace(/%3A/g, ':');
+	}
+
+	return result.replace(/%25/g, '%'); // Must be last!
 }