From a9586e97c7f42a9a221bb20adad1580e5e6c727b Mon Sep 17 00:00:00 2001
From: Andrei Hasna <andrei@hasna.com>
Date: Sat, 8 Aug 2026 09:51:53 +0300
Subject: [PATCH] feat: add password-protected friendly attachment links

Add read-only friendly slug availability checks across local and cloud stores, allow validated password-protected aliases on link regeneration, preserve opaque-token behavior, and document/regenerate the public API SDK.

Agent: aemilia
---
 CHANGELOG.md                         |  10 +++
 docs/cli.md                          |  13 ++-
 sdk/src/generated.ts                 |  15 +++-
 src/cli/commands/link.test.ts        |  41 +++++++++
 src/cli/commands/link.ts             |  22 ++++-
 src/cli/commands/slug.test.ts        |  58 ++++++++++++
 src/cli/commands/slug.ts             |  37 ++++++++
 src/cli/index.ts                     |   2 +
 src/core/cloud-v1.test.ts            |  38 ++++++++
 src/core/cloud-v1.ts                 |  19 +++-
 src/core/db.ts                       |   3 +-
 src/core/friendly-slug.test.ts       |  64 +++++++++++++
 src/core/friendly-slug.ts            |  35 ++++++++
 src/core/links.test.ts               |   1 +
 src/core/links.ts                    |   3 +-
 src/core/store.ts                    |  22 ++++-
 src/db/pg-store.ts                   |   3 +-
 src/index.ts                         |   1 +
 src/serve/app.test.ts                |   1 +
 src/serve/app.ts                     |  78 ++++++++++++++--
 src/serve/friendly-slugs.test.ts     | 130 +++++++++++++++++++++++++++
 src/serve/openapi.ts                 |  42 +++++++++
 src/serve/serve.test-harness.test.ts |   6 +-
 23 files changed, 625 insertions(+), 19 deletions(-)
 create mode 100644 src/cli/commands/slug.test.ts
 create mode 100644 src/cli/commands/slug.ts
 create mode 100644 src/core/friendly-slug.test.ts
 create mode 100644 src/core/friendly-slug.ts
 create mode 100644 src/serve/friendly-slugs.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 791f87f..6410e7f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- Friendly, password-protected share aliases are now supported end to end. Use
+  `attachments slug <slug>` for a read-only availability check, then
+  `attachments link <id> --regenerate --slug <slug> --password <password>` to
+  create `https://<public-host>/a/<slug>`. Slugs are stored only as hashes in
+  the existing share-link table, so no schema migration is required.
+
 ## [1.1.5] - 2026-07-25
 
 ### Fixed
diff --git a/docs/cli.md b/docs/cli.md
index f91b0f6..1230dbb 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -47,7 +47,16 @@ Supports `--format compact|json|table`, `--expired`, `--limit <n>` (default
 ### `link <id>`
 
 Shows the current link. `--regenerate` accepts `--expiry`, `--password`, and
-`--max-downloads`. Output supports `--format human|json` and `--brief`.
+`--max-downloads`. Add `--slug <friendly-slug> --password <password>` to mint a
+password-protected `https://<public-host>/a/<friendly-slug>` alias. Friendly
+slugs use lowercase letters, numbers, and single hyphens. Output supports
+`--format human|json` and `--brief`.
+
+### `slug <slug>`
+
+Checks whether a friendly alias is available without creating a share link.
+`--format human|json` controls output, and `--brief` prints only `available` or
+`unavailable`. An unavailable valid slug exits with code `2`.
 
 ## Direct S3 Upload
 
@@ -124,4 +133,6 @@ attachments complete-task TASK-042 \
 attachments snapshot-session session-id --expiry 7d --tag session:session-id
 attachments report --project attachments --format markdown
 attachments health-check --fix --format json
+attachments slug company-closing-packet --format json
+attachments link att_123 --regenerate --slug company-closing-packet --password "$ATTACHMENT_PASSWORD"
 ```
diff --git a/sdk/src/generated.ts b/sdk/src/generated.ts
index 4004f0c..4096459 100644
--- a/sdk/src/generated.ts
+++ b/sdk/src/generated.ts
@@ -14,9 +14,11 @@ export interface VersionInfo { "status": string; "version": string; "mode": stri
 
 export interface CreateAttachmentRequest { "filename": string; "content_base64": string; "expiry"?: string; "tag"?: string; "password"?: string; "max_downloads"?: number; "link_type"?: "presigned" | "server" }
 
-export interface LinkResponse { "link": string | null; "expires_at"?: number | null }
+export interface LinkResponse { "link": string | null; "expires_at"?: number | null; "slug"?: string }
 
-export interface RegenerateLinkRequest { "expiry"?: string; "password"?: string; "max_downloads"?: number; "link_type"?: "presigned" | "server" }
+export interface RegenerateLinkRequest { "expiry"?: string; "password"?: string; "max_downloads"?: number; "link_type"?: "presigned" | "server"; "slug"?: string }
+
+export interface SlugAvailability { "slug": string; "available": boolean }
 
 export interface DeleteResponse { "deleted": boolean; "id": string }
 
@@ -151,6 +153,15 @@ export class AttachmentsApiClient {
       });
     }
 
+    /** Check whether a friendly /a/<slug> alias is available. */
+    async getFriendlySlugAvailability(slug: string, init?: RequestInit): Promise<SlugAvailability> {
+      return this.request("GET", `/v1/slugs/${encodeURIComponent(String(slug))}`, {
+        body: undefined,
+        query: undefined,
+        init,
+      });
+    }
+
     /** Service version and mode. */
     async getVersion(init?: RequestInit): Promise<VersionInfo> {
       return this.request("GET", `/version`, {
diff --git a/src/cli/commands/link.test.ts b/src/cli/commands/link.test.ts
index 6782a5b..0e3975b 100644
--- a/src/cli/commands/link.test.ts
+++ b/src/cli/commands/link.test.ts
@@ -16,12 +16,14 @@ type MockAttachment = {
 const mockFindById = mock((_id: string): MockAttachment | null => null);
 const mockUpdateLink = mock((_id: string, _link: string, _expiresAt?: number | null) => {});
 const mockDbClose = mock(() => {});
+const mockFindShareLinkByToken = mock((_token: string) => null);
 const mockCreateShareLink = mock((_input: unknown) => ({ shareLink: {}, token: "share_linktest" }));
 
 mock.module("../../core/db", () => ({
   AttachmentsDB: class MockAttachmentsDB {
     constructor(_path?: string) {}
     findById = mockFindById;
+    findShareLinkByToken = mockFindShareLinkByToken;
     updateLink = mockUpdateLink;
     createShareLink = mockCreateShareLink;
     close = mockDbClose;
@@ -200,6 +202,8 @@ describe("linkCommand", () => {
     mockFindById.mockReset();
     mockUpdateLink.mockReset();
     mockDbClose.mockReset();
+    mockFindShareLinkByToken.mockReset();
+    mockFindShareLinkByToken.mockImplementation(() => null);
     mockS3Presign.mockReset();
     mockCreateShareLink.mockReset();
     mockCreateShareLink.mockImplementation(() => ({ shareLink: {}, token: "share_linktest" }));
@@ -319,6 +323,43 @@ describe("linkCommand", () => {
     }
   });
 
+  it("creates a password-protected friendly alias when --slug is provided", async () => {
+    const att = makeAttachment({ id: "att_friendly" });
+    mockFindById.mockImplementation(() => att);
+
+    const capture = captureOutput();
+    try {
+      const program = buildLinkCmd();
+      await program.parseAsync(
+        [
+          "link",
+          "att_friendly",
+          "--regenerate",
+          "--slug",
+          "company-closing-packet",
+          "--password",
+          "passphrase",
+          "--format",
+          "json",
+        ],
+        { from: "user" },
+      );
+      expect(mockFindShareLinkByToken).toHaveBeenCalledWith("company-closing-packet");
+      expect(mockCreateShareLink).toHaveBeenCalledWith(
+        expect.objectContaining({
+          attachmentId: "att_friendly",
+          token: "company-closing-packet",
+          password: "passphrase",
+        }),
+      );
+      expect(mockGeneratePresignedLink).not.toHaveBeenCalled();
+      const parsed = JSON.parse(capture.out.join(""));
+      expect(parsed.slug).toBe("company-closing-packet");
+    } finally {
+      capture.restore();
+    }
+  });
+
   it("regenerates with default expiry when --expiry not specified", async () => {
     const att = makeAttachment({ id: "att_default_expiry" });
     mockFindById.mockImplementation(() => att);
diff --git a/src/cli/commands/link.ts b/src/cli/commands/link.ts
index 34a309e..a900ef7 100644
--- a/src/cli/commands/link.ts
+++ b/src/cli/commands/link.ts
@@ -2,6 +2,7 @@ import { Command } from "commander";
 import { getConfig } from "../../core/config";
 import { resolveStore } from "../../core/store";
 import { formatExpiry } from "../utils";
+import { parseFriendlySlug } from "../../core/friendly-slug";
 
 export function linkCommand(): Command {
   const cmd = new Command("link")
@@ -10,6 +11,7 @@ export function linkCommand(): Command {
     .option("--regenerate", "Generate a fresh share link", false)
     .option("--expiry <time>", "Expiry duration for regenerated link (e.g. 7d, 24h, 30m, never)")
     .option("--password <password>", "Require a password for the regenerated link")
+    .option("--slug <slug>", "Create a friendly /a/<slug> alias (requires --regenerate and --password)")
     .option("--max-downloads <count>", "Maximum successful downloads for the regenerated link")
     .option("--format <format>", "Output format: human or json", "human")
     .option("--brief", "Compact one-line output")
@@ -21,6 +23,15 @@ export function linkCommand(): Command {
       }
 
       const config = getConfig();
+      const slug = options.slug ? parseFriendlySlug(options.slug as string) : undefined;
+      if (slug && !options.regenerate) {
+        process.stderr.write("Error: --slug requires --regenerate\n");
+        process.exit(1);
+      }
+      if (slug && !options.password) {
+        process.stderr.write("Error: --slug requires --password because friendly URLs are guessable\n");
+        process.exit(1);
+      }
       const maxDownloads = options.maxDownloads ? parseInt(options.maxDownloads as string, 10) : undefined;
       if (maxDownloads !== undefined && (!Number.isInteger(maxDownloads) || maxDownloads <= 0)) {
         process.stderr.write("Error: --max-downloads must be a positive integer\n");
@@ -35,13 +46,14 @@ export function linkCommand(): Command {
           process.exit(1);
         }
 
-        let result: { link: string | null; expires_at: number | null };
+        let result: { link: string | null; expires_at: number | null; slug?: string };
         if (options.regenerate) {
           result = await store.regenerateLink(id, {
             expiry: options.expiry,
             password: options.password as string | undefined,
             maxDownloads,
             linkType: config.defaults.linkType,
+            slug,
           });
         } else {
           result = await store.getLink(id);
@@ -51,7 +63,13 @@ export function linkCommand(): Command {
           process.stdout.write(`${result.link ?? "no link"}\n`);
         } else if (format === "json") {
           process.stdout.write(
-            JSON.stringify({ id: att.id, filename: att.filename, link: result.link, expiresAt: result.expires_at }, null, 2) +
+            JSON.stringify({
+              id: att.id,
+              filename: att.filename,
+              link: result.link,
+              expiresAt: result.expires_at,
+              ...(result.slug ? { slug: result.slug } : {}),
+            }, null, 2) +
               "\n"
           );
         } else {
diff --git a/src/cli/commands/slug.test.ts b/src/cli/commands/slug.test.ts
new file mode 100644
index 0000000..ff6f69e
--- /dev/null
+++ b/src/cli/commands/slug.test.ts
@@ -0,0 +1,58 @@
+import { beforeEach, describe, expect, mock, spyOn, test } from "bun:test";
+import { Command } from "commander";
+
+const mockIsSlugAvailable = mock(async (_slug: string) => true);
+const mockClose = mock(() => {});
+
+import { slugCommand } from "./slug";
+
+const resolveStore = () => ({
+  isSlugAvailable: mockIsSlugAvailable,
+  close: mockClose,
+});
+
+describe("slug command", () => {
+  beforeEach(() => {
+    mockIsSlugAvailable.mockReset();
+    mockIsSlugAvailable.mockImplementation(async () => true);
+    mockClose.mockReset();
+    process.exitCode = 0;
+  });
+
+  test("prints JSON availability from the store", async () => {
+    const output: string[] = [];
+    const stdout = spyOn(process.stdout, "write").mockImplementation((chunk: unknown) => {
+      output.push(String(chunk));
+      return true;
+    });
+    try {
+      const program = new Command();
+      program.exitOverride();
+      program.addCommand(slugCommand(resolveStore));
+      await program.parseAsync(["slug", "company-closing-packet", "--format", "json"], { from: "user" });
+      expect(mockIsSlugAvailable).toHaveBeenCalledWith("company-closing-packet");
+      expect(JSON.parse(output.join(""))).toEqual({
+        slug: "company-closing-packet",
+        available: true,
+      });
+      expect(mockClose).toHaveBeenCalled();
+    } finally {
+      stdout.mockRestore();
+    }
+  });
+
+  test("uses exit code 2 for an unavailable but valid slug", async () => {
+    mockIsSlugAvailable.mockImplementation(async () => false);
+    const stdout = spyOn(process.stdout, "write").mockImplementation(() => true);
+    try {
+      const program = new Command();
+      program.exitOverride();
+      program.addCommand(slugCommand(resolveStore));
+      await program.parseAsync(["slug", "company-closing-packet", "--brief"], { from: "user" });
+      expect(process.exitCode).toBe(2);
+    } finally {
+      process.exitCode = 0;
+      stdout.mockRestore();
+    }
+  });
+});
diff --git a/src/cli/commands/slug.ts b/src/cli/commands/slug.ts
new file mode 100644
index 0000000..dd5b997
--- /dev/null
+++ b/src/cli/commands/slug.ts
@@ -0,0 +1,37 @@
+import { Command } from "commander";
+import { parseFriendlySlug } from "../../core/friendly-slug";
+import { resolveStore, type Store } from "../../core/store";
+
+export function slugCommand(resolve: () => Pick<Store, "isSlugAvailable" | "close"> = resolveStore): Command {
+  return new Command("slug")
+    .description("Check whether a friendly /a/<slug> link is available")
+    .argument("<slug>", "Lowercase letters, numbers, and single hyphens")
+    .option("--format <format>", "Output format: human or json", "human")
+    .option("--brief", "Print only available or unavailable")
+    .action(async (slugInput: string, options: { format: string; brief?: boolean }) => {
+      if (!["human", "json"].includes(options.format)) {
+        process.stderr.write("Error: --format must be one of: human, json\n");
+        process.exitCode = 1;
+        return;
+      }
+
+      const store = resolve();
+      try {
+        const slug = parseFriendlySlug(slugInput);
+        const available = await store.isSlugAvailable(slug);
+        if (options.brief) {
+          process.stdout.write(`${available ? "available" : "unavailable"}\n`);
+        } else if (options.format === "json") {
+          process.stdout.write(`${JSON.stringify({ slug, available })}\n`);
+        } else {
+          process.stdout.write(`${slug}: ${available ? "available" : "unavailable"}\n`);
+        }
+        if (!available) process.exitCode = 2;
+      } catch (err) {
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = 1;
+      } finally {
+        store.close();
+      }
+    });
+}
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 6437e06..905af82 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -25,6 +25,7 @@ import { linkCommand } from "./commands/link";
 import { configCommand } from "./commands/config";
 import { initCommand, heartbeatCommand, focusCommand } from "./commands/agent";
 import { domainCommand } from "./commands/domain";
+import { slugCommand } from "./commands/slug";
 
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const pkgVersion: string = (() => { try { return (require("../../package.json") as { version: string }).version; } catch { return process.env.npm_package_version ?? "unknown"; } })();
@@ -58,6 +59,7 @@ program.addCommand(removeCommand());
 program.addCommand(linkCommand());
 program.addCommand(configCommand());
 program.addCommand(domainCommand());
+program.addCommand(slugCommand());
 program.addCommand(initCommand());
 program.addCommand(heartbeatCommand());
 program.addCommand(focusCommand());
diff --git a/src/core/cloud-v1.test.ts b/src/core/cloud-v1.test.ts
index 87c48c5..7ede92a 100644
--- a/src/core/cloud-v1.test.ts
+++ b/src/core/cloud-v1.test.ts
@@ -100,6 +100,44 @@ describe("resolveAttachmentsV1", () => {
     expect(calls[0]!.method).toBe("DELETE");
     expect(calls[0]!.url).toBe(`${BASE}/v1/attachments/att_x`);
   });
+
+  test("checks friendly slug availability through the read-only slug route", async () => {
+    const { calls, fetchImpl } = mockFetch(() => ({
+      status: 200,
+      body: { slug: "company-closing-packet", available: true },
+    }));
+    const r = resolveAttachmentsV1(cloudEnv, { fetchImpl });
+    if (r.transport !== "cloud-http") throw new Error("expected cloud");
+    expect(await r.store.isSlugAvailable("company-closing-packet")).toBe(true);
+    expect(calls[0]!.method).toBe("GET");
+    expect(calls[0]!.url).toBe(`${BASE}/v1/slugs/company-closing-packet`);
+  });
+
+  test("passes a friendly slug when regenerating a password-protected link", async () => {
+    const { calls, fetchImpl } = mockFetch(() => ({
+      status: 200,
+      body: {
+        link: "https://has.na/a/company-closing-packet",
+        expires_at: null,
+        slug: "company-closing-packet",
+      },
+    }));
+    const r = resolveAttachmentsV1(cloudEnv, { fetchImpl });
+    if (r.transport !== "cloud-http") throw new Error("expected cloud");
+    const result = await r.store.regenerateLink("att_1", {
+      slug: "company-closing-packet",
+      password: "passphrase",
+      linkType: "server",
+    });
+    expect(result.slug).toBe("company-closing-packet");
+    expect(calls[0]!.method).toBe("POST");
+    expect(calls[0]!.url).toBe(`${BASE}/v1/attachments/att_1/link`);
+    expect(JSON.parse(calls[0]!.body!)).toMatchObject({
+      slug: "company-closing-packet",
+      password: "passphrase",
+      link_type: "server",
+    });
+  });
 });
 
 // ---------------------------------------------------------------------------
diff --git a/src/core/cloud-v1.ts b/src/core/cloud-v1.ts
index 131b02c..1b01d42 100644
--- a/src/core/cloud-v1.ts
+++ b/src/core/cloud-v1.ts
@@ -91,10 +91,17 @@ export interface AttachmentsV1Store {
   uploadUrl(url: string, options?: V1UploadOptions): Promise<Attachment>;
   delete(id: string): Promise<void>;
   getLink(id: string): Promise<{ link: string | null; expires_at: number | null }>;
+  isSlugAvailable(slug: string): Promise<boolean>;
   regenerateLink(
     id: string,
-    options: { expiry?: string; password?: string; maxDownloads?: number; linkType?: "presigned" | "server" },
-  ): Promise<{ link: string | null; expires_at: number | null }>;
+    options: {
+      expiry?: string;
+      password?: string;
+      maxDownloads?: number;
+      linkType?: "presigned" | "server";
+      slug?: string;
+    },
+  ): Promise<{ link: string | null; expires_at: number | null; slug?: string }>;
   download(id: string, output: string | undefined, options?: { password?: string }): Promise<V1DownloadResult>;
   saveFeedback(input: { message: string; email?: string | null; category?: string; version?: string | null }): Promise<void>;
 }
@@ -327,12 +334,20 @@ function makeStore(client: HasnaStorageClient, env: NodeJS.ProcessEnv): Attachme
       return client.transport.get(`/attachments/${encodeURIComponent(id)}/link`);
     },
 
+    async isSlugAvailable(slug: string): Promise<boolean> {
+      const result = await client.transport.get<{ slug: string; available: boolean }>(
+        `/slugs/${encodeURIComponent(slug)}`,
+      );
+      return result.available;
+    },
+
     async regenerateLink(id, options): Promise<{ link: string | null; expires_at: number | null }> {
       return client.transport.post(`/attachments/${encodeURIComponent(id)}/link`, {
         expiry: options.expiry,
         password: options.password,
         max_downloads: options.maxDownloads,
         link_type: options.linkType,
+        slug: options.slug,
       });
     },
 
diff --git a/src/core/db.ts b/src/core/db.ts
index 9ad8895..7d64e0b 100644
--- a/src/core/db.ts
+++ b/src/core/db.ts
@@ -393,12 +393,13 @@ export class AttachmentsDB {
   createShareLink(input: {
     attachmentId: string;
     expiresAt: number | null;
+    token?: string;
     password?: string;
     maxUses?: number | null;
     requireEmail?: boolean;
     allowedEmails?: string[] | null;
   }): { shareLink: ShareLink; token: string } {
-    const token = generateShareToken();
+    const token = input.token ?? generateShareToken();
     const now = Date.now();
     const allowedEmails =
       input.allowedEmails && input.allowedEmails.length > 0 ? input.allowedEmails : null;
diff --git a/src/core/friendly-slug.test.ts b/src/core/friendly-slug.test.ts
new file mode 100644
index 0000000..8c69aca
--- /dev/null
+++ b/src/core/friendly-slug.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import { rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { AttachmentsDB, type Attachment } from "./db";
+import { FriendlySlugError, parseFriendlySlug, requireFriendlySlugPassword } from "./friendly-slug";
+
+describe("friendly slug validation", () => {
+  test("accepts canonical lowercase dashed slugs", () => {
+    expect(parseFriendlySlug("company-closing-packet")).toBe("company-closing-packet");
+  });
+
+  test("rejects malformed and reserved slugs", () => {
+    for (const slug of ["ABCD", "two--hyphens", "-leading", "trailing-", "__attachments_probe__"]) {
+      expect(() => parseFriendlySlug(slug)).toThrow(FriendlySlugError);
+    }
+  });
+
+  test("requires a password only when a friendly slug is requested", () => {
+    expect(() => requireFriendlySlugPassword("company-closing-packet", undefined)).toThrow(
+      "Friendly links require a password",
+    );
+    expect(() => requireFriendlySlugPassword("company-closing-packet", "passphrase")).not.toThrow();
+    expect(() => requireFriendlySlugPassword(undefined, undefined)).not.toThrow();
+  });
+
+  test("stores only the slug hash and lets the unique index reserve it", () => {
+    const path = join(tmpdir(), `attachments-friendly-slug-${process.pid}-${Date.now()}.sqlite`);
+    const db = new AttachmentsDB(path);
+    const attachment: Attachment = {
+      id: "att_friendly_db",
+      filename: "packet.pdf",
+      s3Key: "attachments/packet.pdf",
+      bucket: "local",
+      size: 1,
+      contentType: "application/pdf",
+      link: null,
+      tag: null,
+      expiresAt: null,
+      createdAt: Date.now(),
+    };
+    try {
+      db.insert(attachment);
+      db.createShareLink({
+        attachmentId: attachment.id,
+        expiresAt: null,
+        token: "company-closing-packet",
+        password: "passphrase",
+      });
+      expect(db.findShareLinkByToken("company-closing-packet")).not.toBeNull();
+      expect(() =>
+        db.createShareLink({
+          attachmentId: attachment.id,
+          expiresAt: null,
+          token: "company-closing-packet",
+          password: "different-passphrase",
+        }),
+      ).toThrow();
+    } finally {
+      db.close();
+      rmSync(path, { force: true });
+    }
+  });
+});
diff --git a/src/core/friendly-slug.ts b/src/core/friendly-slug.ts
new file mode 100644
index 0000000..b319296
--- /dev/null
+++ b/src/core/friendly-slug.ts
@@ -0,0 +1,35 @@
+const FRIENDLY_SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const FRIENDLY_SLUG_MIN_LENGTH = 3;
+const FRIENDLY_SLUG_MAX_LENGTH = 64;
+const RESERVED_FRIENDLY_SLUGS = new Set(["__attachments_probe__"]);
+
+export class FriendlySlugError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "FriendlySlugError";
+  }
+}
+
+export function parseFriendlySlug(input: string): string {
+  const slug = input.trim();
+  if (slug.length < FRIENDLY_SLUG_MIN_LENGTH || slug.length > FRIENDLY_SLUG_MAX_LENGTH) {
+    throw new FriendlySlugError(
+      `Friendly slug must be between ${FRIENDLY_SLUG_MIN_LENGTH} and ${FRIENDLY_SLUG_MAX_LENGTH} characters.`,
+    );
+  }
+  if (!FRIENDLY_SLUG_PATTERN.test(slug)) {
+    throw new FriendlySlugError(
+      "Friendly slug must contain only lowercase letters, numbers, and single hyphens.",
+    );
+  }
+  if (RESERVED_FRIENDLY_SLUGS.has(slug)) {
+    throw new FriendlySlugError(`Friendly slug is reserved: ${slug}`);
+  }
+  return slug;
+}
+
+export function requireFriendlySlugPassword(slug: string | undefined, password: string | undefined): void {
+  if (slug && !password) {
+    throw new FriendlySlugError("Friendly links require a password because their URLs are guessable.");
+  }
+}
diff --git a/src/core/links.test.ts b/src/core/links.test.ts
index 25d4a29..e60a322 100644
--- a/src/core/links.test.ts
+++ b/src/core/links.test.ts
@@ -156,6 +156,7 @@ describe("resolveDeliverableLinkType", () => {
     expect(resolveDeliverableLinkType({ ...base, password: "x" })).toBe("server");
     expect(resolveDeliverableLinkType({ ...base, maxDownloads: 1 })).toBe("server");
     expect(resolveDeliverableLinkType({ ...base, requireEmail: true })).toBe("server");
+    expect(resolveDeliverableLinkType({ ...base, slug: "friendly-link" })).toBe("server");
     expect(resolveDeliverableLinkType({ ...base, encrypt: true })).toBe("server");
     expect(resolveDeliverableLinkType({ ...base, backend: "local" })).toBe("server");
     expect(resolveDeliverableLinkType({ ...base, requested: "server" })).toBe("server");
diff --git a/src/core/links.ts b/src/core/links.ts
index e3d93b8..5c51dca 100644
--- a/src/core/links.ts
+++ b/src/core/links.ts
@@ -85,6 +85,7 @@ export interface DeliverableLinkTypeInput {
   encrypt?: boolean;
   maxDownloads?: number | null;
   requireEmail?: boolean;
+  slug?: string;
 }
 
 /**
@@ -99,7 +100,7 @@ export interface DeliverableLinkTypeInput {
 export function resolveDeliverableLinkType(input: DeliverableLinkTypeInput): "presigned" | "server" {
   if (input.requested === "server") return "server";
   if (input.backend !== "s3") return "server";
-  if (input.password || input.encrypt || input.requireEmail) return "server";
+  if (input.password || input.encrypt || input.requireEmail || input.slug) return "server";
   if (input.maxDownloads !== undefined && input.maxDownloads !== null) return "server";
   if (exceedsPresignLimit(input.expiryMs)) return "server";
   return "presigned";
diff --git a/src/core/store.ts b/src/core/store.ts
index d2edb14..63aa1a5 100644
--- a/src/core/store.ts
+++ b/src/core/store.ts
@@ -51,6 +51,7 @@ import {
 } from "./upload";
 import { downloadAttachment, type DownloadResult } from "./download";
 import { resolveAttachmentsV1, type AttachmentsV1Store, type V1UploadOptions } from "./cloud-v1";
+import { parseFriendlySlug, requireFriendlySlugPassword } from "./friendly-slug";
 
 export type { UploadOptions } from "./upload";
 
@@ -58,6 +59,7 @@ export type { UploadOptions } from "./upload";
 export interface LinkResult {
   link: string | null;
   expires_at: number | null;
+  slug?: string;
 }
 
 export interface ListOptions {
@@ -71,6 +73,7 @@ export interface RegenerateLinkOptions {
   password?: string;
   maxDownloads?: number;
   linkType?: "presigned" | "server";
+  slug?: string;
 }
 
 /** A single feedback note about the service. */
@@ -109,6 +112,7 @@ export interface Store {
   deleteExpired(): Promise<number>;
 
   getLink(id: string): Promise<LinkResult>;
+  isSlugAvailable(slug: string): Promise<boolean>;
   regenerateLink(id: string, options: RegenerateLinkOptions): Promise<LinkResult>;
 
   download(idOrUrl: string, output?: string, options?: { password?: string }): Promise<DownloadResult>;
@@ -240,11 +244,21 @@ export class LocalStore implements Store {
     return { link: att.link, expires_at: att.expiresAt };
   }
 
+  async isSlugAvailable(slugInput: string): Promise<boolean> {
+    const slug = parseFriendlySlug(slugInput);
+    return this.db().findShareLinkByToken(slug) === null;
+  }
+
   async regenerateLink(id: string, options: RegenerateLinkOptions): Promise<LinkResult> {
     const db = this.db();
     const att = db.findById(id);
     if (!att) throw new Error(`Attachment not found: ${id}`);
 
+    const slug = options.slug ? parseFriendlySlug(options.slug) : undefined;
+    requireFriendlySlugPassword(slug, options.password);
+    if (slug && !(await this.isSlugAvailable(slug))) {
+      throw new Error(`Friendly slug is already in use: ${slug}`);
+    }
     const { milliseconds: expiryMs } = parseExpiryStrict(options.expiry ?? this.config.defaults.expiry);
     const expiresAt = expiryMs !== null ? Date.now() + expiryMs : null;
     const linkType = resolveDeliverableLinkType({
@@ -253,6 +267,7 @@ export class LocalStore implements Store {
       expiryMs,
       password: options.password,
       maxDownloads: options.maxDownloads,
+      slug,
     });
 
     let link: string;
@@ -262,6 +277,7 @@ export class LocalStore implements Store {
       const { token } = db.createShareLink({
         attachmentId: att.id,
         expiresAt,
+        token: slug,
         password: options.password,
         maxUses: options.maxDownloads ?? null,
       });
@@ -272,7 +288,7 @@ export class LocalStore implements Store {
       );
     }
     db.updateLink(att.id, link, expiresAt);
-    return { link, expires_at: expiresAt };
+    return { link, expires_at: expiresAt, ...(slug ? { slug } : {}) };
   }
 
   async download(idOrUrl: string, output?: string, options: { password?: string } = {}): Promise<DownloadResult> {
@@ -435,6 +451,10 @@ export class ApiStore implements Store {
     return this.v1.getLink(id);
   }
 
+  isSlugAvailable(slug: string): Promise<boolean> {
+    return this.v1.isSlugAvailable(slug);
+  }
+
   regenerateLink(id: string, options: RegenerateLinkOptions): Promise<LinkResult> {
     return this.v1.regenerateLink(id, options);
   }
diff --git a/src/db/pg-store.ts b/src/db/pg-store.ts
index ca0584e..c054b7c 100644
--- a/src/db/pg-store.ts
+++ b/src/db/pg-store.ts
@@ -224,12 +224,13 @@ export class PgAttachmentsStore {
   async createShareLink(input: {
     attachmentId: string;
     expiresAt: number | null;
+    token?: string;
     password?: string;
     maxUses?: number | null;
     requireEmail?: boolean;
     allowedEmails?: string[] | null;
   }): Promise<{ shareLink: ShareLink; token: string }> {
-    const token = generateShareToken();
+    const token = input.token ?? generateShareToken();
     const now = Date.now();
     const allowedEmails =
       input.allowedEmails && input.allowedEmails.length > 0 ? input.allowedEmails : null;
diff --git a/src/index.ts b/src/index.ts
index f67cd0e..40565b0 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -13,6 +13,7 @@ export type { AttachmentsConfig } from "./core/config.js";
 export { S3Client } from "./core/s3.js";
 export type { S3Config } from "./core/s3.js";
 export { generatePresignedLink, generateServerLink, generateShareLink, getLinkType } from "./core/links.js";
+export { FriendlySlugError, parseFriendlySlug, requireFriendlySlugPassword } from "./core/friendly-slug.js";
 export { resolveShareAccess, ShareAccessError } from "./core/share.js";
 export { LocalObjectStore, createObjectStore } from "./core/object-storage.js";
 export { buildDeploymentPlan } from "./core/deployment.js";
diff --git a/src/serve/app.test.ts b/src/serve/app.test.ts
index 84c47d4..addf4a3 100644
--- a/src/serve/app.test.ts
+++ b/src/serve/app.test.ts
@@ -103,6 +103,7 @@ describe("attachments serve app", () => {
       "/v1/attachments",
       "/v1/attachments/{id}",
       "/v1/attachments/{id}/link",
+      "/v1/slugs/{slug}",
       "/version",
     ]);
   });
diff --git a/src/serve/app.ts b/src/serve/app.ts
index 92a4d4e..5636679 100644
--- a/src/serve/app.ts
+++ b/src/serve/app.ts
@@ -35,6 +35,11 @@ import {
   resolveDeliverableLinkType,
 } from "../core/links.js";
 import { createObjectKey, sanitizeFilename, contentDispositionAttachment } from "../core/security.js";
+import {
+  FriendlySlugError,
+  parseFriendlySlug,
+  requireFriendlySlugPassword,
+} from "../core/friendly-slug.js";
 import { buildOpenApiDocument } from "./openapi.js";
 import { registerCloudPublicRoutes } from "./public-routes.js";
 
@@ -66,6 +71,7 @@ function toApiAttachment(a: Attachment) {
 
 /** Thrown for caller mistakes that must surface as HTTP 400, never a bare 500. */
 class BadRequestError extends Error {}
+class ConflictError extends Error {}
 
 /**
  * Turn a handler failure into a response. Caller mistakes become 400 with the
@@ -77,6 +83,9 @@ function badRequestOrRethrow(c: Context, err: unknown): Response {
   if (err instanceof BadRequestError || err instanceof PresignExpiryError) {
     return c.json({ error: err.message }, 400);
   }
+  if (err instanceof ConflictError) {
+    return c.json({ error: err.message }, 409);
+  }
   const message = err instanceof Error ? err.message : String(err);
   console.error("[v1]", c.req.method, c.req.path, message);
   return c.json({ error: "Internal Server Error", detail: message }, 500);
@@ -90,6 +99,23 @@ function parseExpiryOr400(expiry: string): { milliseconds: number | null; never:
   }
 }
 
+function parseFriendlySlugOr400(slug: string): string {
+  try {
+    return parseFriendlySlug(slug);
+  } catch (err) {
+    if (err instanceof FriendlySlugError) throw new BadRequestError(err.message);
+    throw err;
+  }
+}
+
+function isShareTokenConflict(err: unknown): boolean {
+  const message = err instanceof Error ? err.message.toLowerCase() : String(err).toLowerCase();
+  return (
+    (message.includes("unique") || message.includes("duplicate")) &&
+    (message.includes("token_hash") || message.includes("share_links"))
+  );
+}
+
 interface ParsedMultipartUpload {
   filename: string;
   buffer: Buffer;
@@ -225,6 +251,18 @@ export function createServeApp(deps: ServeAppDeps): Hono {
   app.get("/openapi.json", (c) => c.json(buildOpenApiDocument(version)));
 
   // ── /v1 API ──────────────────────────────────────────────────────────────
+  app.get("/v1/slugs/:slug", async (c) => {
+    const denied = await requireScopes(c, [`${APP_SLUG}:read`]);
+    if (denied) return denied;
+    try {
+      const slug = parseFriendlySlugOr400(c.req.param("slug"));
+      const existing = await store.findShareLinkByToken(slug);
+      return c.json({ slug, available: existing === null });
+    } catch (err) {
+      return badRequestOrRethrow(c, err);
+    }
+  });
+
   app.get("/v1/attachments", async (c) => {
     const denied = await requireScopes(c, [`${APP_SLUG}:read`]);
     if (denied) return denied;
@@ -448,8 +486,19 @@ export function createServeApp(deps: ServeAppDeps): Hono {
       password?: string;
       max_downloads?: number;
       link_type?: "presigned" | "server";
+      slug?: string;
     };
     try {
+      const slug = body.slug ? parseFriendlySlugOr400(body.slug) : undefined;
+      try {
+        requireFriendlySlugPassword(slug, body.password);
+      } catch (err) {
+        if (err instanceof FriendlySlugError) throw new BadRequestError(err.message);
+        throw err;
+      }
+      if (slug && (await store.findShareLinkByToken(slug))) {
+        throw new ConflictError(`Friendly slug is already in use: ${slug}`);
+      }
       const { milliseconds: expiryMs } = parseExpiryOr400(body.expiry ?? config.defaults.expiry);
       const newExpiresAt = expiryMs !== null ? Date.now() + expiryMs : null;
       const linkType = resolveDeliverableLinkType({
@@ -458,22 +507,37 @@ export function createServeApp(deps: ServeAppDeps): Hono {
         expiryMs,
         password: body.password,
         maxDownloads: body.max_downloads,
+        slug,
       });
 
       let newLink: string;
       if (linkType === "presigned") {
         newLink = await generatePresignedLink(new S3Client(config.s3), attachment.s3Key, expiryMs);
       } else {
-        const { token } = await store.createShareLink({
-          attachmentId: id,
-          expiresAt: newExpiresAt,
-          password: body.password,
-          maxUses: body.max_downloads ?? null,
-        });
+        let token: string;
+        try {
+          ({ token } = await store.createShareLink({
+            attachmentId: id,
+            expiresAt: newExpiresAt,
+            token: slug,
+            password: body.password,
+            maxUses: body.max_downloads ?? null,
+          }));
+        } catch (err) {
+          if (slug && isShareTokenConflict(err)) {
+            throw new ConflictError(`Friendly slug is already in use: ${slug}`);
+          }
+          throw err;
+        }
         newLink = generateShareLink(token, publicBaseUrl, config.server.publicPath);
       }
       await store.updateLink(id, newLink, newExpiresAt);
-      return c.json({ link: newLink, expires_at: newExpiresAt, link_type: linkType });
+      return c.json({
+        link: newLink,
+        expires_at: newExpiresAt,
+        link_type: linkType,
+        ...(slug ? { slug } : {}),
+      });
     } catch (err) {
       return badRequestOrRethrow(c, err);
     }
diff --git a/src/serve/friendly-slugs.test.ts b/src/serve/friendly-slugs.test.ts
new file mode 100644
index 0000000..fb1d1e6
--- /dev/null
+++ b/src/serve/friendly-slugs.test.ts
@@ -0,0 +1,130 @@
+import { describe, expect, test } from "bun:test";
+import { mintApiKey } from "@hasna/contracts/auth";
+import { normalizeConfig } from "../core/config.js";
+import type { Attachment } from "../core/db.js";
+import { createServeApp } from "./app.js";
+import { InMemoryAttachmentsStore, stubQueryClient } from "./serve.test-harness.test.js";
+
+const SIGNING_SECRET = "friendly-slug-test-signing-secret";
+const FRIENDLY_SLUG = "company-closing-packet";
+
+function attachment(): Attachment {
+  return {
+    id: "att_friendly",
+    filename: "closing-packet.pdf",
+    s3Key: "attachments/att_friendly/closing-packet.pdf",
+    bucket: "local",
+    size: 128,
+    contentType: "application/pdf",
+    link: null,
+    tag: "legal",
+    expiresAt: null,
+    createdAt: Date.now(),
+    storageBackend: "local",
+    status: "ready",
+    downloads: 0,
+  };
+}
+
+function auth(scopes: string[]): Record<string, string> {
+  const { token } = mintApiKey({
+    app: "attachments",
+    scopes,
+    signingSecret: SIGNING_SECRET,
+  });
+  return {
+    "content-type": "application/json",
+    "x-api-key": token,
+  };
+}
+
+function makeApp() {
+  const store = new InMemoryAttachmentsStore();
+  store.attachments.push(attachment());
+  const app = createServeApp({
+    client: stubQueryClient(),
+    store: store as never,
+    config: normalizeConfig({
+      storage: { backend: "local" },
+      server: { baseUrl: "https://has.na", publicPath: "/a" },
+    }),
+    version: "test",
+    mode: "self_hosted",
+    signingSecret: SIGNING_SECRET,
+  });
+  return { app, store };
+}
+
+describe("friendly attachment slugs", () => {
+  test("rejects malformed, passwordless, and duplicate aliases", async () => {
+    const { app } = makeApp();
+
+    const malformed = await app.request("/v1/slugs/Not-Friendly", {
+      headers: auth(["attachments:read"]),
+    });
+    expect(malformed.status).toBe(400);
+
+    const passwordless = await app.request("/v1/attachments/att_friendly/link", {
+      method: "POST",
+      headers: auth(["attachments:write"]),
+      body: JSON.stringify({ slug: FRIENDLY_SLUG }),
+    });
+    expect(passwordless.status).toBe(400);
+
+    const first = await app.request("/v1/attachments/att_friendly/link", {
+      method: "POST",
+      headers: auth(["attachments:write"]),
+      body: JSON.stringify({ slug: FRIENDLY_SLUG, password: "passphrase" }),
+    });
+    expect(first.status).toBe(200);
+
+    const duplicate = await app.request("/v1/attachments/att_friendly/link", {
+      method: "POST",
+      headers: auth(["attachments:write"]),
+      body: JSON.stringify({ slug: FRIENDLY_SLUG, password: "different-passphrase" }),
+    });
+    expect(duplicate.status).toBe(409);
+  });
+
+  test("reports availability, creates a password-protected alias, and reserves it", async () => {
+    const { app } = makeApp();
+
+    const before = await app.request(`/v1/slugs/${FRIENDLY_SLUG}`, {
+      headers: auth(["attachments:read"]),
+    });
+    expect(before.status).toBe(200);
+    expect(await before.json()).toEqual({
+      slug: FRIENDLY_SLUG,
+      available: true,
+    });
+
+    const created = await app.request("/v1/attachments/att_friendly/link", {
+      method: "POST",
+      headers: auth(["attachments:write"]),
+      body: JSON.stringify({
+        slug: FRIENDLY_SLUG,
+        password: "offline-test-password",
+        expiry: "7d",
+      }),
+    });
+    expect(created.status).toBe(200);
+    expect(await created.json()).toMatchObject({
+      link: `https://has.na/a/${FRIENDLY_SLUG}`,
+      link_type: "server",
+      slug: FRIENDLY_SLUG,
+    });
+
+    const after = await app.request(`/v1/slugs/${FRIENDLY_SLUG}`, {
+      headers: auth(["attachments:read"]),
+    });
+    expect(after.status).toBe(200);
+    expect(await after.json()).toEqual({
+      slug: FRIENDLY_SLUG,
+      available: false,
+    });
+
+    const publicPage = await app.request(`/a/${FRIENDLY_SLUG}`);
+    expect(publicPage.status).toBe(200);
+    expect(await publicPage.text()).toContain('name="password"');
+  });
+});
diff --git a/src/serve/openapi.ts b/src/serve/openapi.ts
index 024446b..b6d6312 100644
--- a/src/serve/openapi.ts
+++ b/src/serve/openapi.ts
@@ -82,6 +82,7 @@ export function buildOpenApiDocument(version: string): Record<string, unknown> {
           properties: {
             link: { type: "string", nullable: true },
             expires_at: { type: "integer", nullable: true },
+            slug: { type: "string" },
           },
           required: ["link"],
         },
@@ -92,8 +93,22 @@ export function buildOpenApiDocument(version: string): Record<string, unknown> {
             password: { type: "string" },
             max_downloads: { type: "integer" },
             link_type: { type: "string", enum: ["presigned", "server"] },
+            slug: {
+              type: "string",
+              pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+              minLength: 3,
+              maxLength: 64,
+            },
           },
         },
+        SlugAvailability: {
+          type: "object",
+          properties: {
+            slug: { type: "string" },
+            available: { type: "boolean" },
+          },
+          required: ["slug", "available"],
+        },
         DeleteResponse: {
           type: "object",
           properties: { deleted: { type: "boolean" }, id: { type: "string" } },
@@ -209,6 +224,33 @@ export function buildOpenApiDocument(version: string): Record<string, unknown> {
           },
         },
       },
+      "/v1/slugs/{slug}": {
+        get: {
+          operationId: "getFriendlySlugAvailability",
+          summary: "Check whether a friendly /a/<slug> alias is available.",
+          security: [{ apiKey: [] }],
+          parameters: [
+            {
+              name: "slug",
+              in: "path",
+              required: true,
+              schema: {
+                type: "string",
+                pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+                minLength: 3,
+                maxLength: 64,
+              },
+            },
+          ],
+          responses: {
+            "200": {
+              content: {
+                "application/json": { schema: { $ref: "#/components/schemas/SlugAvailability" } },
+              },
+            },
+          },
+        },
+      },
     },
   };
 }
diff --git a/src/serve/serve.test-harness.test.ts b/src/serve/serve.test-harness.test.ts
index 7c11609..d62a236 100644
--- a/src/serve/serve.test-harness.test.ts
+++ b/src/serve/serve.test-harness.test.ts
@@ -54,12 +54,16 @@ export class InMemoryAttachmentsStore {
   async createShareLink(input: {
     attachmentId: string;
     expiresAt: number | null;
+    token?: string;
     password?: string;
     maxUses?: number | null;
     requireEmail?: boolean;
     allowedEmails?: string[] | null;
   }): Promise<{ shareLink: ShareLink; token: string }> {
-    const token = generateShareToken();
+    const token = input.token ?? generateShareToken();
+    if (this.shareLinks.some((link) => link.tokenHash === hashShareToken(token))) {
+      throw new Error("Friendly slug is already in use.");
+    }
     const shareLink: ShareLink = {
       id: `share_${generateShareToken().slice(0, 16)}`,
       attachmentId: input.attachmentId,