heartofgold 0.1.0__tar.gz

heartofgold-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Takacs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

heartofgold-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: heartofgold
+Version: 0.1.0
+Summary: A small self-hosted kanban board shared by humans and AI agents, with REST and MCP access.
+Author: Daniel Takacs
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pydantic-settings>=2.4
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: typer>=0.12
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: markdown-it-py>=3
+Requires-Dist: mdit-py-plugins>=0.4
+Requires-Dist: linkify-it-py>=2
+Requires-Dist: nh3>=0.2.17
+Requires-Dist: pillow>=10
+Requires-Dist: argon2-cffi>=23
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: mcp>=2.3,<3
+Requires-Dist: jinja2>=3.1
+Requires-Dist: itsdangerous>=2.2
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# HeartOfGold
+
+A small, self-hosted kanban board shared by you and your AI agents. You use the web UI; agents
+(local Claude Code, Claude Code cloud sessions, claude.ai chat, Desktop, mobile and Cowork) use a
+REST API and a remote MCP server. They hand work to each other, ask you questions, and you approve
+and sign off. One Python package, one SQLite file, no other services.
+
+- Projects with a Markdown plan and ordered columns; Draft → Ready → In Progress → Review → Done by
+  default, where Ready and Done are human-gated and Review/Done need a written resolution.
+- Tasks with Markdown descriptions, comments with @mentions, dependencies, attachments (images,
+  PDFs, HTML reports, text), Mermaid diagrams and full revision history with one-click restore.
+- Every agent has its own identity and inbox; parallel sessions claim tasks so they never collide.
+- Reachable from anywhere at zero cost through Tailscale Funnel on the free plan.
+
+Docs: [deployment](https://github.com/takacsd/HeartOfGold/blob/main/docs/deployment.md) ·
+[client setup](https://github.com/takacsd/HeartOfGold/blob/main/docs/client-setup.md) ·
+[agent conventions](https://github.com/takacsd/HeartOfGold/blob/main/docs/agent-conventions.md) ·
+[spec](https://github.com/takacsd/HeartOfGold/blob/main/docs/spec.md)
+
+## Quick start (about 10 minutes)
+
+You need a machine that stays on (Linux, macOS or a Raspberry Pi with a 64-bit OS) and a free
+[Tailscale](https://tailscale.com) account.
+
+**1. Install uv and HeartOfGold.** uv also fetches Python 3.12 if your system has none.
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh     # see https://docs.astral.sh/uv/ for other ways
+uv tool install heartofgold                          # or, before the first PyPI release:
+                                                     # uv tool install git+https://github.com/takacsd/HeartOfGold
+uv tool update-shell                                 # puts ~/.local/bin on PATH; open a new shell
+```
+
+(`pipx install heartofgold` works too if you prefer pipx; it needs Python 3.12 or newer.)
+
+**2. Create your account and an agent token.**
+
+```bash
+heartofgold init                                     # data dir, secret, your owner account
+heartofgold create-agent laptop
+heartofgold issue-token laptop --name "laptop claude code"   # prints hog_… once: keep it
+```
+
+**3. Put it on the internet with Tailscale Funnel.** Install Tailscale 1.52 or newer from
+[tailscale.com/download](https://tailscale.com/download) (distribution packages are often older;
+on macOS use the open-source `tailscaled` variant; keep MagicDNS on), log in, then:
+
+```bash
+sudo tailscale funnel --bg 8000      # approve the prompt that enables HTTPS and Funnel
+tailscale funnel status              # shows your URL, e.g. https://heartofgold.tail1234.ts.net
+```
+
+The public DNS name can take up to 10 minutes to appear the first time.
+
+**4. Tell HeartOfGold its public URL and run it as a service.** The board only accepts MCP requests
+for the host in `HEARTOFGOLD_BASE_URL`, so this step is required.
+
+```bash
+mkdir -p ~/.config/heartofgold
+echo "HEARTOFGOLD_BASE_URL=https://heartofgold.tail1234.ts.net" > ~/.config/heartofgold/env
+
+# Linux (systemd user service)
+curl -fsSLo ~/.config/systemd/user/heartofgold.service --create-dirs \
+  https://raw.githubusercontent.com/takacsd/HeartOfGold/main/examples/heartofgold.service
+systemctl --user daemon-reload && systemctl --user enable --now heartofgold
+loginctl enable-linger "$USER"       # keep it running when you are logged out
+```
+
+On macOS use [`examples/com.heartofgold.plist`](https://github.com/takacsd/HeartOfGold/blob/main/examples/com.heartofgold.plist)
+with `launchctl`. On Windows, run `heartofgold serve` in a terminal or from Task Scheduler (not
+tested). To just try it: `uvx heartofgold serve` (with the same environment variable exported).
+
+**5. Log in** at your `https://…ts.net` URL (not `http://127.0.0.1`: with an https base URL the
+session cookie is HTTPS-only). Then connect your agents: see
+[client setup](https://github.com/takacsd/HeartOfGold/blob/main/docs/client-setup.md). For Claude Code
+on this machine:
+
+```bash
+export HEARTOFGOLD_TOKEN=hog_…        # also add this line to your shell profile
+claude mcp add --transport http --scope user heartofgold https://heartofgold.tail1234.ts.net/mcp \
+  --header "Authorization: Bearer ${HEARTOFGOLD_TOKEN}"
+claude mcp get heartofgold            # check the header is not just "Bearer "
+```
+
+Paste [`docs/agent-conventions.md`](https://github.com/takacsd/HeartOfGold/blob/main/docs/agent-conventions.md)
+into your `CLAUDE.md`, open Claude Code and ask "what's in my HeartOfGold inbox?".
+
+## Everyday operations
+
+- **CLI** (runs on the server, acts as admin): `init`, `serve`, `create-agent <handle> [--admin]`,
+  `issue-token <handle> --name <name>`, `revoke-token <prefix>`, `set-role <handle> admin|member`,
+  `reset-password <handle>`, `backup [--to PATH]`. If your env file sets anything besides the base
+  URL (such as `HEARTOFGOLD_DATA_DIR`), load it first: `set -a; . ~/.config/heartofgold/env; set +a`.
+- **Undoing mistakes**: every text change has a History with diff and Restore; deleted comments and
+  attachments come back from Admin. Backups are for disasters.
+- **Backups**: `heartofgold backup` writes a consistent snapshot, new attachment files and the
+  secret key to `<data dir>/backups` (or `--to` another disk) and keeps 14 snapshots. Schedule it
+  with [the backup timer](https://github.com/takacsd/HeartOfGold/blob/main/examples/heartofgold-backup.timer)
+  or cron. Restoring is described in
+  [deployment](https://github.com/takacsd/HeartOfGold/blob/main/docs/deployment.md#restore).
+- **Upgrades**: `uv tool upgrade heartofgold` (or `pipx upgrade heartofgold`), then
+  `systemctl --user restart heartofgold`. Database migrations run at startup.
+
+## Configuration
+
+All settings are environment variables; all have defaults. Invalid values stop startup with a
+message naming the variable.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `HEARTOFGOLD_BASE_URL` | `http://127.0.0.1:<port>` | Public URL without a path, e.g. `https://heartofgold.tail1234.ts.net` (may include `:8443`) |
+| `HEARTOFGOLD_PORT` | `8000` | Listen port (the server binds to 127.0.0.1; `serve --host` changes that) |
+| `HEARTOFGOLD_DATA_DIR` | platform user data dir (`~/.local/share/heartofgold` on Linux) | Database, `files/`, `backups/`, generated secret |
+| `HEARTOFGOLD_SECRET_KEY` | generated on first run (stored with mode 0600) | Signs session cookies and CSRF tokens |
+| `HEARTOFGOLD_RATE_LIMIT` | `120/minute` | Per credential; `0` disables |
+| `HEARTOFGOLD_MAX_UPLOAD_MB` | `10` | Per-file REST upload limit (MCP uploads: 256 KB) |
+| `HEARTOFGOLD_MAX_STORAGE_MB` | `2048` | Total attachment storage |
+| `HEARTOFGOLD_LOG_LEVEL` | `info` | JSON log lines on stdout |
+
+## API
+
+- REST: `/api/v1` with `Authorization: Bearer hog_…`; interactive docs at `/api/v1/docs`; writes
+  accept an `X-Session-Label` header.
+- MCP: `/mcp` (Streamable HTTP, stateless). Tools: whoami, projects, tasks, comments, questions,
+  claims, inbox, waiting, history, search, attachments.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+uv run heartofgold serve
+```
+
+Decisions taken while building: [`docs/DECISIONS.md`](https://github.com/takacsd/HeartOfGold/blob/main/docs/DECISIONS.md).
+
+## License
+
+MIT

heartofgold-0.1.0/README.md

@@ -0,0 +1,140 @@
+# HeartOfGold
+
+A small, self-hosted kanban board shared by you and your AI agents. You use the web UI; agents
+(local Claude Code, Claude Code cloud sessions, claude.ai chat, Desktop, mobile and Cowork) use a
+REST API and a remote MCP server. They hand work to each other, ask you questions, and you approve
+and sign off. One Python package, one SQLite file, no other services.
+
+- Projects with a Markdown plan and ordered columns; Draft → Ready → In Progress → Review → Done by
+  default, where Ready and Done are human-gated and Review/Done need a written resolution.
+- Tasks with Markdown descriptions, comments with @mentions, dependencies, attachments (images,
+  PDFs, HTML reports, text), Mermaid diagrams and full revision history with one-click restore.
+- Every agent has its own identity and inbox; parallel sessions claim tasks so they never collide.
+- Reachable from anywhere at zero cost through Tailscale Funnel on the free plan.
+
+Docs: [deployment](https://github.com/takacsd/HeartOfGold/blob/main/docs/deployment.md) ·
+[client setup](https://github.com/takacsd/HeartOfGold/blob/main/docs/client-setup.md) ·
+[agent conventions](https://github.com/takacsd/HeartOfGold/blob/main/docs/agent-conventions.md) ·
+[spec](https://github.com/takacsd/HeartOfGold/blob/main/docs/spec.md)
+
+## Quick start (about 10 minutes)
+
+You need a machine that stays on (Linux, macOS or a Raspberry Pi with a 64-bit OS) and a free
+[Tailscale](https://tailscale.com) account.
+
+**1. Install uv and HeartOfGold.** uv also fetches Python 3.12 if your system has none.
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh     # see https://docs.astral.sh/uv/ for other ways
+uv tool install heartofgold                          # or, before the first PyPI release:
+                                                     # uv tool install git+https://github.com/takacsd/HeartOfGold
+uv tool update-shell                                 # puts ~/.local/bin on PATH; open a new shell
+```
+
+(`pipx install heartofgold` works too if you prefer pipx; it needs Python 3.12 or newer.)
+
+**2. Create your account and an agent token.**
+
+```bash
+heartofgold init                                     # data dir, secret, your owner account
+heartofgold create-agent laptop
+heartofgold issue-token laptop --name "laptop claude code"   # prints hog_… once: keep it
+```
+
+**3. Put it on the internet with Tailscale Funnel.** Install Tailscale 1.52 or newer from
+[tailscale.com/download](https://tailscale.com/download) (distribution packages are often older;
+on macOS use the open-source `tailscaled` variant; keep MagicDNS on), log in, then:
+
+```bash
+sudo tailscale funnel --bg 8000      # approve the prompt that enables HTTPS and Funnel
+tailscale funnel status              # shows your URL, e.g. https://heartofgold.tail1234.ts.net
+```
+
+The public DNS name can take up to 10 minutes to appear the first time.
+
+**4. Tell HeartOfGold its public URL and run it as a service.** The board only accepts MCP requests
+for the host in `HEARTOFGOLD_BASE_URL`, so this step is required.
+
+```bash
+mkdir -p ~/.config/heartofgold
+echo "HEARTOFGOLD_BASE_URL=https://heartofgold.tail1234.ts.net" > ~/.config/heartofgold/env
+
+# Linux (systemd user service)
+curl -fsSLo ~/.config/systemd/user/heartofgold.service --create-dirs \
+  https://raw.githubusercontent.com/takacsd/HeartOfGold/main/examples/heartofgold.service
+systemctl --user daemon-reload && systemctl --user enable --now heartofgold
+loginctl enable-linger "$USER"       # keep it running when you are logged out
+```
+
+On macOS use [`examples/com.heartofgold.plist`](https://github.com/takacsd/HeartOfGold/blob/main/examples/com.heartofgold.plist)
+with `launchctl`. On Windows, run `heartofgold serve` in a terminal or from Task Scheduler (not
+tested). To just try it: `uvx heartofgold serve` (with the same environment variable exported).
+
+**5. Log in** at your `https://…ts.net` URL (not `http://127.0.0.1`: with an https base URL the
+session cookie is HTTPS-only). Then connect your agents: see
+[client setup](https://github.com/takacsd/HeartOfGold/blob/main/docs/client-setup.md). For Claude Code
+on this machine:
+
+```bash
+export HEARTOFGOLD_TOKEN=hog_…        # also add this line to your shell profile
+claude mcp add --transport http --scope user heartofgold https://heartofgold.tail1234.ts.net/mcp \
+  --header "Authorization: Bearer ${HEARTOFGOLD_TOKEN}"
+claude mcp get heartofgold            # check the header is not just "Bearer "
+```
+
+Paste [`docs/agent-conventions.md`](https://github.com/takacsd/HeartOfGold/blob/main/docs/agent-conventions.md)
+into your `CLAUDE.md`, open Claude Code and ask "what's in my HeartOfGold inbox?".
+
+## Everyday operations
+
+- **CLI** (runs on the server, acts as admin): `init`, `serve`, `create-agent <handle> [--admin]`,
+  `issue-token <handle> --name <name>`, `revoke-token <prefix>`, `set-role <handle> admin|member`,
+  `reset-password <handle>`, `backup [--to PATH]`. If your env file sets anything besides the base
+  URL (such as `HEARTOFGOLD_DATA_DIR`), load it first: `set -a; . ~/.config/heartofgold/env; set +a`.
+- **Undoing mistakes**: every text change has a History with diff and Restore; deleted comments and
+  attachments come back from Admin. Backups are for disasters.
+- **Backups**: `heartofgold backup` writes a consistent snapshot, new attachment files and the
+  secret key to `<data dir>/backups` (or `--to` another disk) and keeps 14 snapshots. Schedule it
+  with [the backup timer](https://github.com/takacsd/HeartOfGold/blob/main/examples/heartofgold-backup.timer)
+  or cron. Restoring is described in
+  [deployment](https://github.com/takacsd/HeartOfGold/blob/main/docs/deployment.md#restore).
+- **Upgrades**: `uv tool upgrade heartofgold` (or `pipx upgrade heartofgold`), then
+  `systemctl --user restart heartofgold`. Database migrations run at startup.
+
+## Configuration
+
+All settings are environment variables; all have defaults. Invalid values stop startup with a
+message naming the variable.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `HEARTOFGOLD_BASE_URL` | `http://127.0.0.1:<port>` | Public URL without a path, e.g. `https://heartofgold.tail1234.ts.net` (may include `:8443`) |
+| `HEARTOFGOLD_PORT` | `8000` | Listen port (the server binds to 127.0.0.1; `serve --host` changes that) |
+| `HEARTOFGOLD_DATA_DIR` | platform user data dir (`~/.local/share/heartofgold` on Linux) | Database, `files/`, `backups/`, generated secret |
+| `HEARTOFGOLD_SECRET_KEY` | generated on first run (stored with mode 0600) | Signs session cookies and CSRF tokens |
+| `HEARTOFGOLD_RATE_LIMIT` | `120/minute` | Per credential; `0` disables |
+| `HEARTOFGOLD_MAX_UPLOAD_MB` | `10` | Per-file REST upload limit (MCP uploads: 256 KB) |
+| `HEARTOFGOLD_MAX_STORAGE_MB` | `2048` | Total attachment storage |
+| `HEARTOFGOLD_LOG_LEVEL` | `info` | JSON log lines on stdout |
+
+## API
+
+- REST: `/api/v1` with `Authorization: Bearer hog_…`; interactive docs at `/api/v1/docs`; writes
+  accept an `X-Session-Label` header.
+- MCP: `/mcp` (Streamable HTTP, stateless). Tools: whoami, projects, tasks, comments, questions,
+  claims, inbox, waiting, history, search, attachments.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+uv run heartofgold serve
+```
+
+Decisions taken while building: [`docs/DECISIONS.md`](https://github.com/takacsd/HeartOfGold/blob/main/docs/DECISIONS.md).
+
+## License
+
+MIT

heartofgold-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+name = "heartofgold"
+version = "0.1.0"
+description = "A small self-hosted kanban board shared by humans and AI agents, with REST and MCP access."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn>=0.30",
+    "pydantic>=2.7",
+    "pydantic-settings>=2.4",
+    "platformdirs>=4.2",
+    "typer>=0.12",
+    "sqlalchemy>=2.0",
+    "markdown-it-py>=3",
+    "mdit-py-plugins>=0.4",
+    "linkify-it-py>=2",
+    "nh3>=0.2.17",
+    "pillow>=10",
+    "argon2-cffi>=23",
+    "python-multipart>=0.0.9",
+    "mcp>=2.3,<3",
+    "jinja2>=3.1",
+    "itsdangerous>=2.2",
+]
+
+[[project.authors]]
+name = "Daniel Takacs"
+
+[project.scripts]
+heartofgold = "heartofgold.cli:app"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "httpx>=0.27",
+    "ruff>=0.6",
+    "mypy>=1.11",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.1,<0.14"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "RUF",
+    "A",
+]
+
+[tool.mypy]
+strict = true
+files = ["src/heartofgold"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+filterwarnings = ["ignore:Using `httpx` with `starlette.testclient` is deprecated"]

heartofgold-0.1.0/pyproject.toml.orig

@@ -0,0 +1,60 @@
+[project]
+name = "heartofgold"
+version = "0.1.0"
+description = "A small self-hosted kanban board shared by humans and AI agents, with REST and MCP access."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Daniel Takacs" }]
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn>=0.30",
+    "pydantic>=2.7",
+    "pydantic-settings>=2.4",
+    "platformdirs>=4.2",
+    "typer>=0.12",
+    "sqlalchemy>=2.0",
+    "markdown-it-py>=3",
+    "mdit-py-plugins>=0.4",
+    "linkify-it-py>=2",
+    "nh3>=0.2.17",
+    "pillow>=10",
+    "argon2-cffi>=23",
+    "python-multipart>=0.0.9",
+    "mcp>=2.3,<3",
+    "jinja2>=3.1",
+    "itsdangerous>=2.2",
+]
+
+[project.scripts]
+heartofgold = "heartofgold.cli:app"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "httpx>=0.27",
+    "ruff>=0.6",
+    "mypy>=1.11",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.1,<0.14"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF", "A"]
+
+[tool.mypy]
+strict = true
+files = ["src/heartofgold"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+filterwarnings = ["ignore:Using `httpx` with `starlette.testclient` is deprecated"]

heartofgold-0.1.0/src/heartofgold/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("heartofgold")

heartofgold-0.1.0/src/heartofgold/__main__.py

@@ -0,0 +1,3 @@
+from heartofgold.cli import app
+
+app(prog_name="heartofgold")

heartofgold-0.1.0/src/heartofgold/api/errors.py

@@ -0,0 +1,92 @@
+"""RFC 9457 problem+json responses for every error (section 6)."""
+
+from collections.abc import Mapping
+from http import HTTPStatus
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse, Response
+from starlette.exceptions import HTTPException
+
+from heartofgold.services.common import ServiceError
+
+_CODES = {
+    400: "invalid_request",
+    401: "unauthenticated",
+    403: "forbidden",
+    404: "not_found",
+    405: "invalid_request",
+    413: "too_large",
+    422: "validation_error",
+    429: "rate_limited",
+}
+
+
+_API_PREFIXES = ("/api/", "/files/", "/mcp", "/.well-known/", "/healthz")
+
+
+def _respond(request: Request, status: int, code: str, detail: str, **kw: object) -> Response:
+    """problem+json for API clients; a small HTML page for the browser UI."""
+    if not request.url.path.startswith(_API_PREFIXES):
+        from heartofgold.web.routes import error_page
+
+        return error_page(request, status, detail)
+    return problem(status, code, detail, **kw)  # type: ignore[arg-type]
+
+
+def problem(
+    status: int,
+    code: str,
+    detail: str,
+    headers: Mapping[str, str] | None = None,
+    extra: Mapping[str, object] | None = None,
+) -> JSONResponse:
+    body = {
+        "type": "about:blank",
+        "title": HTTPStatus(status).phrase,
+        "status": status,
+        "detail": detail,
+        "code": code,
+        **(extra or {}),
+    }
+    return JSONResponse(body, status, headers=headers, media_type="application/problem+json")
+
+
+def _service_error(request: Request, exc: Exception) -> Response:
+    assert isinstance(exc, ServiceError)
+    return _respond(request, exc.status, exc.code, exc.detail, extra=exc.extra)
+
+
+def _http_error(request: Request, exc: Exception) -> Response:
+    assert isinstance(exc, HTTPException)
+    code = _CODES.get(exc.status_code, "invalid_request")
+    detail = exc.detail if isinstance(exc.detail, str) else HTTPStatus(exc.status_code).phrase
+    return _respond(request, exc.status_code, code, detail, headers=exc.headers)
+
+
+def _validation_error(request: Request, exc: Exception) -> JSONResponse:
+    assert isinstance(exc, RequestValidationError)
+    errors = exc.errors()
+    if any(e.get("type") == "json_invalid" for e in errors):
+        return problem(400, "invalid_request", "The request body is not valid JSON.")
+    parts = []
+    for error in errors:
+        loc = ".".join(str(p) for p in error["loc"] if p not in ("body", "query", "path"))
+        parts.append(f"{loc or 'body'}: {error['msg']}")
+    return problem(422, "validation_error", "; ".join(parts))
+
+
+def _unexpected(request: Request, exc: Exception) -> JSONResponse:
+    return problem(500, "internal_error", "Unexpected server error; see the server log.")
+
+
+def _overflow(request: Request, exc: Exception) -> JSONResponse:
+    return problem(422, "validation_error", "A number in the request is out of range.")
+
+
+def install(app: FastAPI) -> None:
+    app.add_exception_handler(Exception, _unexpected)
+    app.add_exception_handler(OverflowError, _overflow)
+    app.add_exception_handler(ServiceError, _service_error)
+    app.add_exception_handler(HTTPException, _http_error)
+    app.add_exception_handler(RequestValidationError, _validation_error)

heartofgold-0.1.0/src/heartofgold/api/files.py

@@ -0,0 +1,85 @@
+"""Attachment upload, listing, delete/restore and download (FR-17..FR-23, section 8)."""
+
+import os
+from typing import Annotated
+
+from fastapi import APIRouter, File, Form, UploadFile
+from fastapi.responses import FileResponse
+
+from heartofgold.auth.deps import CallerDep, DbDep, StorageDep
+from heartofgold.schemas import AttachmentOut
+from heartofgold.services import attachments
+from heartofgold.services.common import not_found
+
+router = APIRouter()
+
+
+class BlobResponse(FileResponse):
+    """A file response carrying only the headers section 8 lists (no etag or last-modified)."""
+
+    def set_stat_headers(self, stat_result: os.stat_result) -> None:
+        self.headers.setdefault("content-length", str(stat_result.st_size))
+        del self.headers["accept-ranges"]
+
+    def _should_use_range(self, http_if_range: str) -> bool:
+        return False
+
+
+CACHE = "private, max-age=31536000, immutable"
+SVG_CSP = "sandbox; default-src 'none'; style-src 'unsafe-inline'; img-src data:"
+INLINE = {"image/png", "image/jpeg", "image/gif", "image/webp", "application/pdf"}
+
+
+@router.post("/api/v1/tasks/{ref}/attachments", status_code=201)
+def upload(
+    ref: str,
+    file: Annotated[UploadFile, File()],
+    caller: CallerDep,
+    db: DbDep,
+    storage: StorageDep,
+    alt_text: Annotated[str | None, Form()] = None,
+) -> AttachmentOut:
+    data = file.file.read(storage.max_upload_bytes + 1)
+    return attachments.upload(db, caller, storage, ref, file.filename or "file", data, alt_text)
+
+
+@router.get("/api/v1/tasks/{ref}/attachments")
+def list_attachments(ref: str, caller: CallerDep, db: DbDep) -> list[AttachmentOut]:
+    return attachments.list_attachments(db, caller, ref)
+
+
+@router.delete("/api/v1/attachments/{attachment_id}")
+def delete_attachment(attachment_id: str, caller: CallerDep, db: DbDep) -> AttachmentOut:
+    return attachments.set_deleted(db, caller, attachment_id, True)
+
+
+@router.post("/api/v1/attachments/{attachment_id}/restore")
+def restore_attachment(attachment_id: str, caller: CallerDep, db: DbDep) -> AttachmentOut:
+    return attachments.set_deleted(db, caller, attachment_id, False)
+
+
+@router.get("/files/{attachment_id}/{filename}")
+def download(
+    attachment_id: str, filename: str, caller: CallerDep, db: DbDep, storage: StorageDep
+) -> FileResponse:
+    meta, path = attachments.open_blob(db, caller, storage, attachment_id)
+    if filename != meta.filename:
+        raise not_found(f"Attachment {attachment_id} is named {meta.filename}.")
+    kind = meta.content_type.split(";")[0]
+    headers = {"Cache-Control": CACHE, "X-Content-Type-Options": "nosniff"}
+    disposition = "inline"
+    if kind == "image/svg+xml":
+        headers["Content-Security-Policy"] = SVG_CSP
+    elif kind == "text/html":
+        headers["Content-Security-Policy"] = "sandbox allow-scripts"
+    elif kind not in INLINE:
+        headers["Content-Security-Policy"] = "sandbox"
+        disposition = "attachment"
+    response = BlobResponse(
+        path,
+        media_type=meta.content_type,
+        filename=meta.filename,
+        content_disposition_type=disposition,
+        headers=headers,
+    )
+    return response