fix: support UTF-8 attachment filenames

Author: none23

DESIGN.md

@@ -131,12 +131,13 @@ Required headers:
 
 - `Authorization: Bearer <token>`
 - `Content-Length: <bytes>`
-- `X-Filename: <display filename>`
+- `X-Filename: <display filename or percent-encoded UTF-8 filename>`
 
 Optional headers:
 
 - `Content-Type`; defaults to `application/octet-stream`
 - `X-Alt-Text`; used when generating image Markdown
+- `X-Filename-Encoding: percent`; set when `X-Filename` is percent-encoded UTF-8
 
 `Content-Length` is mandatory so the service can reject an upload before reading its body if insufficient quota remains.
 

README.md

@@ -172,6 +172,9 @@ curl --fail-with-body \
   "$GITHUB_ATTACHMENTS_URL/v1/attachments"
 ```
 
+For non-ASCII filenames, percent-encode the UTF-8 filename in `X-Filename` and add
+`X-Filename-Encoding: percent`. The included CLI and agent skill do this automatically.
+
 See [openapi.yaml](openapi.yaml) for the complete contract.
 
 ## Technical overview

bin/github-attach.mjs

@@ -34,7 +34,8 @@ async function main() {
     "content-length": String(bytes.byteLength),
     "content-type":
       CONTENT_TYPES.get(extname(filename).toLowerCase()) ?? "application/octet-stream",
-    "x-filename": filename,
+    "x-filename": encodeURIComponent(filename),
+    "x-filename-encoding": "percent",
   };
   if (options.alt !== undefined) {
     headers["x-alt-text"] = options.alt;

openapi.yaml

@@ -40,7 +40,13 @@ paths:
         - name: X-Filename
           in: header
           required: true
-          schema: { type: string, maxLength: 200 }
+          description: Raw filename, or percent-encoded UTF-8 when X-Filename-Encoding is percent. Decoded filenames are limited to 200 Unicode characters.
+          schema: { type: string, maxLength: 2400 }
+        - name: X-Filename-Encoding
+          in: header
+          required: false
+          description: Set when X-Filename contains percent-encoded UTF-8.
+          schema: { type: string, enum: [percent] }
         - name: X-Alt-Text
           in: header
           required: false

skills/attach-github-pr-files/scripts/upload.sh

@@ -57,12 +57,15 @@ fi
 
 output=$(mktemp)
 trap 'rm -f "$output"' EXIT HUP INT TERM
+filename=$(basename "$file")
+encoded_filename=$(node -e 'process.stdout.write(encodeURIComponent(process.argv[1]))' "$filename")
 
 set -- \
   --fail-with-body --silent --show-error \
   --request POST \
   --header "Authorization: Bearer $token" \
-  --header "X-Filename: $(basename "$file")" \
+  --header "X-Filename: $encoded_filename" \
+  --header "X-Filename-Encoding: percent" \
   --header "Content-Type: $(file --brief --mime-type -- "$file")" \
   --data-binary "@$file" \
   --output "$output"

src/upload.ts

@@ -25,7 +25,7 @@ export async function handleUpload(request: Request, env: Env): Promise<Response
   }
 
   const limits = readLimits(env);
-  const filename = sanitizeFilename(request.headers.get("x-filename"));
+  const filename = sanitizeFilename(decodeFilenameHeader(request.headers));
   if (filename === null) {
     return errorResponse(400, "invalid_filename", "X-Filename must contain a valid filename.");
   }
@@ -164,6 +164,23 @@ function sanitizeFilename(raw: string | null): string | null {
   return sanitized.length > 0 && sanitized !== "." && sanitized !== ".." ? sanitized : null;
 }
 
+function decodeFilenameHeader(headers: Headers): string | null {
+  const raw = headers.get("x-filename");
+  const encoding = headers.get("x-filename-encoding");
+  if (encoding === null) {
+    return raw;
+  }
+  if (encoding !== "percent" || raw === null) {
+    return null;
+  }
+
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return null;
+  }
+}
+
 function sanitizeAltText(raw: string | null, filename: string): string {
   const fallback = filename.replace(/\.[^.]+$/, "") || filename;
   if (raw === null) {

test-node/cli.test.mjs

@@ -10,6 +10,8 @@ const CLI = resolve("bin/github-attach.mjs");
 const FIXTURE = resolve("test/fixtures/cli-fixture.txt");
 const SKILL_UPLOADER = resolve("skills/attach-github-pr-files/scripts/upload.sh");
 const EXPECTED_MARKDOWN = "[cli-fixture.txt](https://example.test/a/id/cli-fixture.txt)\n";
+const UNICODE_FILENAME = "日本語.txt";
+const UNICODE_MARKDOWN = `[${UNICODE_FILENAME}](https://example.test/a/id/${encodeURIComponent(UNICODE_FILENAME)})\n`;
 
 test("CLI uploads raw bytes and prints only Markdown", async (context) => {
   const serviceUrl = await startServer(context, { alt: "CLI fixture", token: "test-token" });
@@ -70,6 +72,29 @@ test("CLI reads the user-level service profile", async (context) => {
   assert.equal(result.stdout, EXPECTED_MARKDOWN);
 });
 
+test("CLI percent-encodes UTF-8 filenames", async (context) => {
+  const repository = await temporaryRepository(context);
+  const file = join(repository, UNICODE_FILENAME);
+  await writeFile(file, "unicode attachment\n");
+  const serviceUrl = await startServer(context, {
+    alt: "Unicode CLI",
+    body: "unicode attachment\n",
+    filename: UNICODE_FILENAME,
+    markdown: UNICODE_MARKDOWN.trim(),
+    token: "unicode-cli-token",
+  });
+
+  const result = await run(process.execPath, [CLI, file, "--alt", "Unicode CLI"], {
+    ...process.env,
+    GITHUB_ATTACHMENTS_TOKEN: "unicode-cli-token",
+    GITHUB_ATTACHMENTS_URL: serviceUrl,
+  });
+
+  assert.equal(result.stderr, "");
+  assert.equal(result.exitCode, 0);
+  assert.equal(result.stdout, UNICODE_MARKDOWN);
+});
+
 test("skill uploader uses the repository override", async (context) => {
   const serviceUrl = await startServer(context, { alt: "Skill", token: "skill-repo-token" });
   const repository = await temporaryRepository(context);
@@ -94,6 +119,34 @@ test("skill uploader uses the repository override", async (context) => {
   assert.equal(result.stdout, EXPECTED_MARKDOWN);
 });
 
+test("skill uploader percent-encodes UTF-8 filenames", async (context) => {
+  const repository = await temporaryRepository(context);
+  const file = join(repository, UNICODE_FILENAME);
+  await writeFile(file, "unicode attachment\n");
+  const serviceUrl = await startServer(context, {
+    alt: "Unicode skill",
+    body: "unicode attachment\n",
+    filename: UNICODE_FILENAME,
+    markdown: UNICODE_MARKDOWN.trim(),
+    token: "unicode-skill-token",
+  });
+
+  const result = await run(
+    SKILL_UPLOADER,
+    [file, "Unicode skill"],
+    {
+      ...process.env,
+      GITHUB_ATTACHMENTS_TOKEN: "unicode-skill-token",
+      GITHUB_ATTACHMENTS_URL: serviceUrl,
+    },
+    repository,
+  );
+
+  assert.equal(result.stderr, "");
+  assert.equal(result.exitCode, 0);
+  assert.equal(result.stdout, UNICODE_MARKDOWN);
+});
+
 test("skill uploader reads the user-level service profile", async (context) => {
   const serviceUrl = await startServer(context, { alt: "Skill user", token: "skill-user-token" });
   const repository = await temporaryRepository(context);
@@ -142,18 +195,23 @@ async function startServer(context, expected) {
     assert.equal(request.method, "POST");
     assert.equal(request.url, "/v1/attachments");
     assert.equal(request.headers.authorization, `Bearer ${expected.token}`);
-    assert.equal(request.headers["x-filename"], "cli-fixture.txt");
+    const filename = expected.filename ?? "cli-fixture.txt";
+    assert.equal(request.headers["x-filename"], encodeURIComponent(filename));
+    assert.equal(request.headers["x-filename-encoding"], "percent");
     assert.equal(request.headers["x-alt-text"], expected.alt);
     assert.equal(request.headers["content-type"], "text/plain");
 
     const chunks = [];
     for await (const chunk of request) {
       chunks.push(chunk);
     }
-    assert.equal(Buffer.concat(chunks).toString("utf8"), "attachment CLI fixture\n");
+    assert.equal(
+      Buffer.concat(chunks).toString("utf8"),
+      expected.body ?? "attachment CLI fixture\n",
+    );
 
     response.writeHead(201, { "content-type": "application/json" });
-    response.end(JSON.stringify({ markdown: EXPECTED_MARKDOWN.trim() }));
+    response.end(JSON.stringify({ markdown: expected.markdown ?? EXPECTED_MARKDOWN.trim() }));
   });
   server.listen(0, "127.0.0.1");
   await once(server, "listening");

test/upload.test.ts

@@ -109,10 +109,38 @@ describe("attachment upload API", () => {
     expect(new Uint8Array(await served.arrayBuffer())).toEqual(PNG);
   });
 
+  it("decodes percent-encoded UTF-8 filenames", async () => {
+    const filename = "日本語.png";
+    const response = await upload(PNG, {
+      filename: encodeURIComponent(filename),
+      filenameEncoding: "percent",
+    });
+    const body = await response.json<UploadBody>();
+
+    expect(response.status).toBe(201);
+    expect(body.filename).toBe(filename);
+    expect(body.url).toContain(`/${encodeURIComponent(filename)}`);
+
+    const served = await exports.default.fetch(new Request(body.url));
+    expect(served.status).toBe(200);
+  });
+
   it("validates filenames, body length, and image size", async () => {
     const badFilename = await upload(PNG, { filename: ".." });
     expect(badFilename.status).toBe(400);
 
+    const unknownFilenameEncoding = await upload(PNG, {
+      filename: "test.png",
+      filenameEncoding: "base64",
+    });
+    expect(unknownFilenameEncoding.status).toBe(400);
+
+    const malformedEncodedFilename = await upload(PNG, {
+      filename: "bad%encoding.png",
+      filenameEncoding: "percent",
+    });
+    expect(malformedEncodedFilename.status).toBe(400);
+
     const missingLength = await authenticatedFetch("/v1/attachments", {
       method: "POST",
       headers: {
@@ -142,6 +170,7 @@ async function upload(
     authorization?: string | null;
     contentType?: string;
     filename?: string;
+    filenameEncoding?: string;
   } = {},
 ): Promise<Response> {
   const headers: Record<string, string> = {
@@ -152,6 +181,9 @@ async function upload(
   if (options.authorization !== null) {
     headers.authorization = options.authorization ?? `Bearer ${TOKEN}`;
   }
+  if (options.filenameEncoding !== undefined) {
+    headers["x-filename-encoding"] = options.filenameEncoding;
+  }
   if (options.altText !== undefined) {
     headers["x-alt-text"] = options.altText;
   }