auth-aware-delivery

Status, 2026-08-04: not built, and not currently planned. This is a design exploration from May 2025. Nothing in it shipped.

What did ship is simpler and mostly orthogonal: OAuth login, plus comments and reactions gated on it. Markdown is still served as static files built by Docusaurus and pushed to S3 — there is no server-side markdown gateway, no per-file UUID, and no auth-level filtering of content.

Keep the page for the thinking. Don't read it as a roadmap.

---

Once you bring authorization-aware delivery into the mix, you’re essentially building a smart content gateway. Every Markdown file becomes a secured asset, with variable visibility based on the requester.

Below: what this architecture means, where it shines, and how to implement it without slowing yourself down.

---

🧠 The Model: Markdown-as-Restricted-Content

Concept:

Every markdown file is:

• Identified by a UUID
• Parsed server-side
• Filtered by auth level
• Then sent to the frontend for rendering

GET /markdowns/:uuid
Authorization: Bearer <JWT or session>

Returns:

{
  "front_matter": { ... },
  "body": "<filtered markdown string>"
}

---

🔐 Why This Is Necessary

If you want:

• {auth=adminOnly} style in-markdown gates
• Sections that vary per user (like a comment box that only shows if logged in)
• Logging which parts of content get read
• Gamified or progressive unlocks

...then you must control delivery from the server.

---

🔧 How It Works (At a High Level)

1. Parse the Markdown server-side

• Use any parser that gives you access to AST or just plain text blocks
• Extract {auth=...} directives

2. Authenticate the request

• Session, JWT, API key, whatever

3. Transform the document

• Strip unauthorized blocks
• Optionally insert “locked” placeholders or progress hints

4. Return to the frontend

• Can still be hydrated via MDX if needed, or rendered raw

---

🏗 Suggested Folder Structure (Server-side)

markdowns/
  65cc66.md      → actual content
  65cc66.meta    → front matter or cached AST
  _category_.json

---

⚙️ Backend Endpoint

GET /api/markdowns/:uuid

Header: Authorization: Bearer xyz

Backend does:

• Load markdown file
• Parse front matter and {auth=} blocks
• Look up user’s access level
• Filter → return body + front matter

---

✨ Bonus Ideas

• 🔐 Serve as static if no {auth=} blocks are present
• 🧠 Precompile filtered versions per access tier (if content is stable)
• 🎯 Add headers like X-Content-Access-Level: full/partial/locked
• 📜 Include hidden blocks with <!-- locked --> comments (if you want client-side hinting too)

---

🧩 Why This Rocks

You now have:

• Variable markdown delivery
• A backend that understands semantics, not just blobs
• The groundwork for unlockable content, gamified auth, and dynamic personalization

---

If you'd like:

• A Go or Python example of how to parse {auth=} tags
• A file-backed storage model with basic auth
• A pipeline that pre-renders markdown for different roles

I’d be happy to sketch it out. This is definitely next-level content architecture — but you’re already halfway there.