@sourcepress/media 0.1.0

package/dist/registry.js

@@ -0,0 +1,88 @@
+/**
+ * MediaRegistryManager reads/writes the media.json file in Git.
+ * This is the source of truth for all media metadata.
+ */
+export class MediaRegistryManager {
+    github;
+    registryPath;
+    cache = null;
+    registrySha = null;
+    constructor(github, registryPath) {
+        this.github = github;
+        this.registryPath = registryPath;
+    }
+    /**
+     * Load the full registry from Git.
+     */
+    async load() {
+        if (this.cache)
+            return this.cache;
+        const file = await this.github.getFile(this.registryPath);
+        if (!file) {
+            this.cache = {};
+            this.registrySha = null;
+            return this.cache;
+        }
+        this.registrySha = file.sha;
+        try {
+            this.cache = JSON.parse(file.content);
+        }
+        catch {
+            console.error("Failed to parse media registry JSON, falling back to empty registry");
+            this.cache = {};
+        }
+        return this.cache;
+    }
+    /**
+     * Save the registry back to Git.
+     */
+    async save(message) {
+        const content = JSON.stringify(this.cache ?? {}, null, 2);
+        const result = await this.github.createOrUpdateFile(this.registryPath, content, message, undefined, this.registrySha ?? undefined);
+        this.registrySha = result.sha;
+    }
+    /**
+     * Add or update an entry in the registry.
+     */
+    async set(path, ref) {
+        await this.load();
+        if (!this.cache)
+            this.cache = {};
+        this.cache[path] = ref;
+    }
+    /**
+     * Get a single entry.
+     */
+    async get(path) {
+        const registry = await this.load();
+        return registry[path] ?? null;
+    }
+    /**
+     * Remove an entry from the registry.
+     */
+    async remove(path) {
+        await this.load();
+        if (this.cache) {
+            delete this.cache[path];
+        }
+    }
+    /**
+     * List entries, optionally filtered by prefix.
+     */
+    async list(prefix) {
+        const registry = await this.load();
+        const entries = Object.entries(registry);
+        if (prefix) {
+            return entries.filter(([key]) => key.startsWith(prefix)).map(([, ref]) => ref);
+        }
+        return entries.map(([, ref]) => ref);
+    }
+    /**
+     * Invalidate the in-memory cache.
+     */
+    invalidate() {
+        this.cache = null;
+        this.registrySha = null;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,2 @@
+export type { MediaRef, MediaRegistry, MediaUploadInput, MediaConfig } from "@sourcepress/core";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/validation.d.ts

@@ -0,0 +1,12 @@
+import type { MediaConfig } from "@sourcepress/core";
+export interface ValidationResult {
+    valid: boolean;
+    error?: string;
+}
+export declare function validateUpload(contentType: string, sizeBytes: number, config?: Partial<MediaConfig>): ValidationResult;
+/**
+ * Sanitize a media path — no traversal, lowercase, forward slashes.
+ * Iterates until stable, then verifies no traversal sequences remain.
+ */
+export declare function sanitizePath(path: string): string;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAarD,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,cAAc,CAC7B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC3B,gBAAgB,CAoBlB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoBjD"}

package/dist/validation.js

@@ -0,0 +1,51 @@
+import { posix } from "node:path";
+const DEFAULT_ALLOWED_TYPES = [
+    "image/jpeg",
+    "image/png",
+    "image/webp",
+    "image/gif",
+    "image/svg+xml",
+    "application/pdf",
+];
+const DEFAULT_MAX_SIZE_MB = 10;
+export function validateUpload(contentType, sizeBytes, config) {
+    const allowedTypes = config?.allowedTypes ?? DEFAULT_ALLOWED_TYPES;
+    const maxSizeMb = config?.maxSizeMb ?? DEFAULT_MAX_SIZE_MB;
+    if (!allowedTypes.includes(contentType)) {
+        return {
+            valid: false,
+            error: `Content type "${contentType}" is not allowed. Allowed: ${allowedTypes.join(", ")}`,
+        };
+    }
+    const maxBytes = maxSizeMb * 1024 * 1024;
+    if (sizeBytes > maxBytes) {
+        return {
+            valid: false,
+            error: `File size ${(sizeBytes / 1024 / 1024).toFixed(1)}MB exceeds maximum ${maxSizeMb}MB`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Sanitize a media path — no traversal, lowercase, forward slashes.
+ * Iterates until stable, then verifies no traversal sequences remain.
+ */
+export function sanitizePath(path) {
+    let current = path.replace(/\\/g, "/").replace(/^\//, "").toLowerCase();
+    // Iteratively remove traversal sequences until stable
+    let prev;
+    do {
+        prev = current;
+        current = current
+            .replace(/\.{2,}/g, "")
+            .replace(/\/+/g, "/")
+            .replace(/^\//, "");
+    } while (current !== prev);
+    // Final check via posix.normalize
+    const normalized = posix.normalize(current);
+    if (normalized.includes("..") || normalized.startsWith("/")) {
+        throw new Error(`Path traversal detected in: ${path}`);
+    }
+    return normalized;
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAGlC,MAAM,qBAAqB,GAAG;IAC7B,YAAY;IACZ,WAAW;IACX,YAAY;IACZ,WAAW;IACX,eAAe;IACf,iBAAiB;CACjB,CAAC;AAEF,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAO/B,MAAM,UAAU,cAAc,CAC7B,WAAmB,EACnB,SAAiB,EACjB,MAA6B;IAE7B,MAAM,YAAY,GAAG,MAAM,EAAE,YAAY,IAAI,qBAAqB,CAAC;IACnE,MAAM,SAAS,GAAG,MAAM,EAAE,SAAS,IAAI,mBAAmB,CAAC;IAE3D,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QACzC,OAAO;YACN,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,iBAAiB,WAAW,8BAA8B,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;SAC1F,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,SAAS,GAAG,IAAI,GAAG,IAAI,CAAC;IACzC,IAAI,SAAS,GAAG,QAAQ,EAAE,CAAC;QAC1B,OAAO;YACN,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,aAAa,CAAC,SAAS,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,sBAAsB,SAAS,IAAI;SAC3F,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACxC,IAAI,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAExE,sDAAsD;IACtD,IAAI,IAAY,CAAC;IACjB,GAAG,CAAC;QACH,IAAI,GAAG,OAAO,CAAC;QACf,OAAO,GAAG,OAAO;aACf,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;aACtB,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;aACpB,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACtB,CAAC,QAAQ,OAAO,KAAK,IAAI,EAAE;IAE3B,kCAAkC;IAClC,MAAM,UAAU,GAAG,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAC5C,IAAI,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,UAAU,CAAC;AACnB,CAAC"}

package/package.json

@@ -0,0 +1,26 @@
+{
+	"name": "@sourcepress/media",
+	"version": "0.1.0",
+	"publishConfig": { "access": "public" },
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "tsc",
+		"test": "vitest run",
+		"typecheck": "tsc --noEmit",
+		"clean": "rm -rf dist"
+	},
+	"dependencies": {
+		"@sourcepress/core": "workspace:*",
+		"@sourcepress/github": "workspace:*"
+	},
+	"devDependencies": {
+		"typescript": "^5.7.0",
+		"vitest": "^3.0.0"
+	}
+}

package/src/__tests__/git-storage.test.ts

@@ -0,0 +1,160 @@
+import type { MediaRef } from "@sourcepress/core";
+import { describe, expect, it, vi } from "vitest";
+import { GitMediaStorage } from "../git-storage.js";
+
+// Mock crypto.subtle for hash computation
+vi.stubGlobal("crypto", {
+	subtle: {
+		digest: vi.fn().mockResolvedValue(new Uint8Array(32).buffer),
+	},
+});
+
+function createMockGitHub() {
+	return {
+		getFile: vi.fn().mockResolvedValue(null),
+		createOrUpdateFile: vi.fn().mockResolvedValue({ sha: "file-sha", commit_sha: "commit-sha" }),
+		owner: "test",
+		repo: "test",
+		branch: "main",
+	};
+}
+
+const defaultConfig = {
+	storage: "git" as const,
+	path: "assets",
+	registry: "media.json",
+};
+
+describe("GitMediaStorage", () => {
+	it("uploads a file and registers it", async () => {
+		// biome-ignore lint/suspicious/noExplicitAny: mock GitHubClient
+		const github = createMockGitHub() as any;
+		const storage = new GitMediaStorage(github, defaultConfig);
+
+		const result = await storage.upload({
+			file: Buffer.from("fake-image-data"),
+			path: "hero.webp",
+			content_type: "image/webp",
+			source: "uploaded",
+			uploaded_by: "test-user",
+			alt: "Hero image",
+		});
+
+		expect(result.path).toBe("assets/hero.webp");
+		expect(result.content_type).toBe("image/webp");
+		expect(result.source).toBe("uploaded");
+		expect(result.uploaded_by).toBe("test-user");
+		expect(result.alt).toBe("Hero image");
+
+		// Should have uploaded the file
+		expect(github.createOrUpdateFile).toHaveBeenCalledTimes(2); // file + registry
+	});
+
+	it("rejects disallowed content type", async () => {
+		// biome-ignore lint/suspicious/noExplicitAny: mock GitHubClient
+		const github = createMockGitHub() as any;
+		const storage = new GitMediaStorage(github, defaultConfig);
+
+		await expect(
+			storage.upload({
+				file: Buffer.from("data"),
+				path: "malware.exe",
+				content_type: "application/x-executable",
+				source: "uploaded",
+				uploaded_by: "test-user",
+			}),
+		).rejects.toThrow("not allowed");
+	});
+
+	it("rejects file exceeding max size", async () => {
+		// biome-ignore lint/suspicious/noExplicitAny: mock GitHubClient
+		const github = createMockGitHub() as any;
+		const storage = new GitMediaStorage(github, {
+			...defaultConfig,
+			maxSizeMb: 1,
+		});
+
+		const largeBuffer = Buffer.alloc(2 * 1024 * 1024); // 2MB
+		await expect(
+			storage.upload({
+				file: largeBuffer,
+				path: "large.png",
+				content_type: "image/png",
+				source: "uploaded",
+				uploaded_by: "test-user",
+			}),
+		).rejects.toThrow("exceeds maximum");
+	});
+
+	it("sanitizes upload paths", async () => {
+		// biome-ignore lint/suspicious/noExplicitAny: mock GitHubClient
+		const github = createMockGitHub() as any;
+		const storage = new GitMediaStorage(github, defaultConfig);
+
+		const result = await storage.upload({
+			file: Buffer.from("data"),
+			path: "../../../HERO.WebP",
+			content_type: "image/webp",
+			source: "uploaded",
+			uploaded_by: "test-user",
+		});
+
+		expect(result.path).toBe("assets/hero.webp");
+	});
+
+	it("lists media entries", async () => {
+		// biome-ignore lint/suspicious/noExplicitAny: mock GitHubClient
+		const github = createMockGitHub() as any;
+		// Pre-populate registry via getFile mock
+		const registry = {
+			"assets/a.webp": {
+				path: "assets/a.webp",
+				content_type: "image/webp",
+				size_bytes: 1000,
+				hash: "aaa",
+				source: "uploaded",
+				uploaded_at: "2026-04-04",
+				uploaded_by: "test",
+			},
+		};
+		github.getFile.mockResolvedValueOnce({
+			path: "media.json",
+			sha: "reg-sha",
+			content: JSON.stringify(registry),
+			encoding: "utf-8",
+		});
+
+		const storage = new GitMediaStorage(github, defaultConfig);
+		const list = await storage.list();
+		expect(list).toHaveLength(1);
+		expect(list[0].path).toBe("assets/a.webp");
+	});
+
+	it("updates metadata for existing file", async () => {
+		// biome-ignore lint/suspicious/noExplicitAny: mock GitHubClient
+		const github = createMockGitHub() as any;
+		const existingRef: MediaRef = {
+			path: "assets/hero.webp",
+			content_type: "image/webp",
+			size_bytes: 5000,
+			hash: "abc",
+			source: "uploaded",
+			uploaded_at: "2026-04-04",
+			uploaded_by: "test",
+		};
+		github.getFile.mockResolvedValueOnce({
+			path: "media.json",
+			sha: "reg-sha",
+			content: JSON.stringify({ "assets/hero.webp": existingRef }),
+			encoding: "utf-8",
+		});
+
+		const storage = new GitMediaStorage(github, defaultConfig);
+		const updated = await storage.updateMeta("assets/hero.webp", {
+			alt: "Updated alt text",
+		});
+
+		expect(updated.alt).toBe("Updated alt text");
+		expect(updated.path).toBe("assets/hero.webp");
+	});
+});

package/src/__tests__/registry.test.ts

@@ -0,0 +1,116 @@
+import type { MediaRef } from "@sourcepress/core";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { MediaRegistryManager } from "../registry.js";
+
+// Mock GitHubClient
+function createMockGitHub(existingRegistry?: Record<string, MediaRef>) {
+	const content = existingRegistry ? JSON.stringify(existingRegistry) : null;
+	return {
+		getFile: vi
+			.fn()
+			.mockResolvedValue(
+				content ? { path: "media.json", sha: "abc123", content, encoding: "utf-8" as const } : null,
+			),
+		createOrUpdateFile: vi.fn().mockResolvedValue({ sha: "new-sha", commit_sha: "commit-sha" }),
+		owner: "test",
+		repo: "test",
+		branch: "main",
+	};
+}
+
+const sampleRef: MediaRef = {
+	path: "assets/hero.webp",
+	content_type: "image/webp",
+	size_bytes: 50000,
+	hash: "abc123def456",
+	source: "uploaded",
+	uploaded_at: "2026-04-04T10:00:00Z",
+	uploaded_by: "test-user",
+};
+
+describe("MediaRegistryManager", () => {
+	it("loads empty registry when file does not exist", async () => {
+		// biome-ignore lint/suspicious/noExplicitAny: mock GitHubClient
+		const github = createMockGitHub() as any;
+		const manager = new MediaRegistryManager(github, "media.json");
+
+		const registry = await manager.load();
+		expect(registry).toEqual({});
+	});
+
+	it("loads existing registry from Git", async () => {
+		const existing = { "assets/hero.webp": sampleRef };
+		// biome-ignore lint/suspicious/noExplicitAny: mock GitHubClient
+		const github = createMockGitHub(existing) as any;
+		const manager = new MediaRegistryManager(github, "media.json");
+
+		const registry = await manager.load();
+		expect(registry["assets/hero.webp"]).toEqual(sampleRef);
+	});
+
+	it("sets and retrieves an entry", async () => {
+		// biome-ignore lint/suspicious/noExplicitAny: mock GitHubClient
+		const github = createMockGitHub() as any;
+		const manager = new MediaRegistryManager(github, "media.json");
+
+		await manager.set("assets/new.png", sampleRef);
+		const result = await manager.get("assets/new.png");
+		expect(result).toEqual(sampleRef);
+	});
+
+	it("removes an entry", async () => {
+		const existing = { "assets/hero.webp": sampleRef };
+		// biome-ignore lint/suspicious/noExplicitAny: mock GitHubClient
+		const github = createMockGitHub(existing) as any;
+		const manager = new MediaRegistryManager(github, "media.json");
+
+		await manager.remove("assets/hero.webp");
+		const result = await manager.get("assets/hero.webp");
+		expect(result).toBeNull();
+	});
+
+	it("lists entries with prefix filter", async () => {
+		const existing = {
+			"assets/cases/hero.webp": { ...sampleRef, path: "assets/cases/hero.webp" },
+			"assets/team/anna.jpg": { ...sampleRef, path: "assets/team/anna.jpg" },
+			"assets/cases/detail.png": { ...sampleRef, path: "assets/cases/detail.png" },
+		};
+		// biome-ignore lint/suspicious/noExplicitAny: mock GitHubClient
+		const github = createMockGitHub(existing) as any;
+		const manager = new MediaRegistryManager(github, "media.json");
+
+		const casesOnly = await manager.list("assets/cases/");
+		expect(casesOnly).toHaveLength(2);
+	});
+
+	it("saves registry to Git", async () => {
+		// biome-ignore lint/suspicious/noExplicitAny: mock GitHubClient
+		const github = createMockGitHub() as any;
+		const manager = new MediaRegistryManager(github, "media.json");
+
+		await manager.set("assets/hero.webp", sampleRef);
+		await manager.save("media: add hero image");
+
+		expect(github.createOrUpdateFile).toHaveBeenCalledWith(
+			"media.json",
+			expect.stringContaining("assets/hero.webp"),
+			"media: add hero image",
+			undefined,
+			undefined,
+		);
+	});
+
+	it("invalidates cache", async () => {
+		const existing = { "assets/hero.webp": sampleRef };
+		// biome-ignore lint/suspicious/noExplicitAny: mock GitHubClient
+		const github = createMockGitHub(existing) as any;
+		const manager = new MediaRegistryManager(github, "media.json");
+
+		await manager.load();
+		manager.invalidate();
+
+		// Should call getFile again after invalidation
+		await manager.load();
+		expect(github.getFile).toHaveBeenCalledTimes(2);
+	});
+});

package/src/__tests__/validation.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { sanitizePath, validateUpload } from "../validation.js";
+
+describe("validateUpload", () => {
+	it("accepts valid image upload", () => {
+		const result = validateUpload("image/webp", 500_000);
+		expect(result.valid).toBe(true);
+		expect(result.error).toBeUndefined();
+	});
+
+	it("rejects disallowed content type", () => {
+		const result = validateUpload("application/zip", 1000);
+		expect(result.valid).toBe(false);
+		expect(result.error).toContain("not allowed");
+	});
+
+	it("rejects file exceeding max size", () => {
+		const result = validateUpload("image/png", 20 * 1024 * 1024);
+		expect(result.valid).toBe(false);
+		expect(result.error).toContain("exceeds maximum");
+	});
+
+	it("uses custom allowed types from config", () => {
+		const result = validateUpload("application/zip", 1000, {
+			allowedTypes: ["application/zip"],
+		});
+		expect(result.valid).toBe(true);
+	});
+
+	it("uses custom max size from config", () => {
+		const result = validateUpload("image/png", 50 * 1024 * 1024, {
+			maxSizeMb: 100,
+		});
+		expect(result.valid).toBe(true);
+	});
+});
+
+describe("sanitizePath", () => {
+	it("normalizes backslashes to forward slashes", () => {
+		expect(sanitizePath("assets\\images\\hero.png")).toBe("assets/images/hero.png");
+	});
+
+	it("removes directory traversal attempts", () => {
+		expect(sanitizePath("../../../etc/passwd")).toBe("etc/passwd");
+	});
+
+	it("collapses multiple slashes", () => {
+		expect(sanitizePath("assets///images//hero.png")).toBe("assets/images/hero.png");
+	});
+
+	it("lowercases the path", () => {
+		expect(sanitizePath("Assets/HERO.PNG")).toBe("assets/hero.png");
+	});
+
+	it("removes leading slash", () => {
+		expect(sanitizePath("/assets/hero.png")).toBe("assets/hero.png");
+	});
+});

package/src/git-storage.ts

@@ -0,0 +1,109 @@
+import type { MediaConfig, MediaRef, MediaUploadInput } from "@sourcepress/core";
+import type { GitHubClient } from "@sourcepress/github";
+import type { MediaStorage } from "./interface.js";
+import { MediaRegistryManager } from "./registry.js";
+import { sanitizePath, validateUpload } from "./validation.js";
+
+/**
+ * Compute a simple hash from a Buffer using Web Crypto API.
+ */
+async function computeHash(data: Buffer): Promise<string> {
+	const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+	const hashArray = Array.from(new Uint8Array(hashBuffer));
+	return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * GitMediaStorage stores media files directly in the Git repository.
+ * Best for small sites with < 50 images.
+ */
+export class GitMediaStorage implements MediaStorage {
+	private github: GitHubClient;
+	private registry: MediaRegistryManager;
+	private config: MediaConfig;
+
+	constructor(github: GitHubClient, config: MediaConfig) {
+		this.github = github;
+		this.config = config;
+		this.registry = new MediaRegistryManager(github, config.registry);
+	}
+
+	async upload(input: MediaUploadInput): Promise<MediaRef> {
+		const sanitized = sanitizePath(input.path);
+		const fullPath = `${this.config.path}/${sanitized}`;
+
+		// Validate
+		const validation = validateUpload(input.content_type, input.file.length, this.config);
+		if (!validation.valid) {
+			throw new Error(validation.error);
+		}
+
+		// Compute hash
+		const hash = await computeHash(input.file);
+
+		// Upload file to Git — pass as latin1 string so createOrUpdateFile's
+		// internal btoa() produces valid base64 (no double-encoding).
+		const content = input.file.toString("latin1");
+		await this.github.createOrUpdateFile(fullPath, content, `media: upload ${sanitized}`);
+
+		// Create MediaRef
+		const ref: MediaRef = {
+			path: fullPath,
+			content_type: input.content_type,
+			size_bytes: input.file.length,
+			hash,
+			alt: input.alt,
+			source: input.source,
+			generated_by: input.generated_by,
+			prompt: input.prompt,
+			uploaded_at: new Date().toISOString(),
+			uploaded_by: input.uploaded_by,
+		};
+
+		// Register in media.json
+		await this.registry.set(fullPath, ref);
+		await this.registry.save(`media: register ${sanitized}`);
+
+		return ref;
+	}
+
+	async get(path: string): Promise<Buffer | null> {
+		const file = await this.github.getFile(path);
+		if (!file) return null;
+		return Buffer.from(file.content, "base64");
+	}
+
+	async delete(path: string): Promise<void> {
+		// Remove from registry
+		await this.registry.remove(path);
+		await this.registry.save(`media: delete ${path}`);
+
+		// Note: Git doesn't truly "delete" — we remove from registry.
+		// The file remains in Git history. For actual file deletion,
+		// a future version could use the GitHub Contents API DELETE.
+	}
+
+	async list(prefix?: string): Promise<MediaRef[]> {
+		return this.registry.list(prefix);
+	}
+
+	async getMeta(path: string): Promise<MediaRef | null> {
+		return this.registry.get(path);
+	}
+
+	async updateMeta(
+		path: string,
+		updates: Partial<Pick<MediaRef, "alt" | "source" | "generated_by" | "prompt">>,
+	): Promise<MediaRef> {
+		const existing = await this.registry.get(path);
+		if (!existing) {
+			throw new Error(`Media not found: ${path}`);
+		}
+
+		const updated: MediaRef = { ...existing, ...updates };
+		await this.registry.set(path, updated);
+		await this.registry.save(`media: update metadata for ${path}`);
+
+		return updated;
+	}
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export type { MediaStorage } from "./interface.js";
+export { GitMediaStorage } from "./git-storage.js";
+export { MediaRegistryManager } from "./registry.js";
+export { validateUpload, sanitizePath } from "./validation.js";