feat: establish the core API framework and scaffold the Web client (WIP)

- feat: implement the WIP API foundation for file management, administration, logging, error handling, and local storage.
- feat: scaffold the WIP React Web client with routing, data-query, styling, and build foundations.
- docs: reorganize server and Web documentation and add repository review guidance.

.agents/skills/mygo-api-repo-review/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: mygo-api-repo-review
+description: Review the MyGO backend repository for material, evidence-backed architecture, security, resilience, data-consistency, performance, and implementation flaws. Use only when explicitly asked to run a MyGO repository audit in diff, main, or full mode, optionally limited to a target path, package, or component; do not use for ordinary implementation or debugging tasks.
+---
+
+# MyGO API Repository Review
+
+Perform a read-only, evidence-first review of the MyGO backend. Find material defects and systemic risks without turning unfinished product scope, stylistic preferences, or unsupported hypotheticals into findings.
+
+## Resolve the review scope
+
+Resolve two independent inputs: `mode` and `target`.
+
+- Default `mode` to `diff` when the user does not provide one.
+- Default `target` to `all`.
+- Treat `partly` as a request for a limited `target`, not as a fourth mode. Require or safely infer the path, Go package, or logical component to inspect.
+
+Use these mode semantics:
+
+- `diff`: compare the current workspace with `HEAD`. Include staged changes, unstaged changes, and relevant untracked files.
+- `main`: compare the current workspace with the merge base of `HEAD` and the local `main` branch. Record the local `main` and merge-base commit IDs. Do not fetch or silently substitute a remote ref. If local `main` is unavailable, report the limitation.
+- `full`: inspect the current repository as a whole, including tracked code, tests, configuration, and documentation plus relevant untracked source files. Exclude repository metadata, caches, runtime data, build outputs, and generated artifacts unless they are directly relevant.
+
+For a limited target, inspect not only the named files but also the directly affected callers, dependencies, interfaces, tests, configuration, and documentation needed to judge the target correctly.
+
+## Preserve the workspace
+
+Keep the review read-only unless the user separately asks for fixes.
+
+1. Capture the initial branch, `HEAD`, and complete Git status, including untracked files.
+2. Do not run commands intended to rewrite source or dependency files, including `go fmt ./...` and `go mod tidy`.
+3. Do not fetch, pull, commit, stage, or discard changes.
+4. Capture Git status again before reporting. If the workspace changed, identify the change and do not erase it.
+
+## Review the implementation
+
+Read `AGENTS.md`, `docs/roadmap.md`, `docs/architecture.md`, `docs/decisions.md`, and `docs/development.md` before judging the implementation. Treat documented decisions as intent, not as proof that their implementation is correct.
+
+Apply production-grade correctness, security, resilience, and architecture standards to behavior and components that already exist, including implemented paths within WIP features. Do not interpret that standard as requiring every capability of the finished product to exist now.
+
+1. Map the reviewed packages, dependency direction, entry points, state owners, external resources, and lifecycle operations. Use `rg` and targeted reads; do not read `go.sum` in full.
+2. Reconstruct behavior, boundaries, invariants, state transitions, and trust assumptions from code, tests, configuration, and documentation.
+3. Trace important control, data, ownership, resource, concurrency, and failure flows without starting from a predetermined bug list.
+4. Use the lenses below for minimum coverage, then challenge every candidate before reporting it.
+
+Treat the lenses as perspectives, not an exhaustive checklist, taxonomy, or finding quota:
+
+- **Architecture and evolution:** Evaluate whether responsibilities, dependencies, boundaries, data flows, or resource use materially obstruct supported behavior, scaling, committed evolution, extensibility, decoupling, customization, or maintenance.
+- **Security:** Evaluate whether trust, identity, authorization, ownership, confidentiality, integrity, availability, or exposure assumptions can be violated through a reachable execution path or component interaction.
+- **Resilience:** Evaluate whether plausible partial failures, dependency failures, cancellation, concurrency, malformed inputs, or interrupted lifecycle operations can cause disproportionate impact, cascading failure, loss of service, or an unrecoverable state.
+- **Data consistency:** Evaluate whether persistent state, external resources, ownership, and lifecycle transitions preserve required invariants across normal, concurrent, retried, interrupted, and partially failed execution paths.
+
+Continue searching for material problems outside these lenses. Do not manufacture a finding for every lens.
+
+## Use parallel review selectively
+
+Keep small `diff` and narrowly targeted reviews in the main agent by default. For a broad `main` or `full` review, use read-only subagents when they are available and parallel review materially improves coverage.
+
+Give every reviewer the complete, non-exhaustive review objective and one primary emphasis such as architecture and performance, security, or resilience and data consistency. Make the emphasis a starting perspective rather than an exclusive boundary. Wait for all reviewers, then independently verify, deduplicate, and rank their candidates in the main agent.
+
+## Verify and report
+
+Run the repository-wide checks below unless the user explicitly limits command execution or the environment prevents them:
+
+- `go build ./...`
+- `go vet ./...`
+- `go test ./...`
+- a non-mutating `gofmt -l` check over tracked Go files
+
+Record each check and its result. When a test fails, inspect the test first and follow the debugging principles in `AGENTS.md`. Do not convert a command failure into an architecture finding without validating its cause.
+
+After open-ended discovery, read [review-calibration.md](references/review-calibration.md) and apply its admission and falsification rules. Then read [report-template.md](references/report-template.md) and follow it exactly. If no candidate qualifies, state `Findings: None` rather than lowering the threshold.

.agents/skills/mygo-api-repo-review/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "MyGO API Repository Review"
+  short_description: "Evidence-based MyGO backend repository review"
+  default_prompt: "Use $mygo-api-repo-review to review the current working tree against HEAD."
+policy:
+  allow_implicit_invocation: false

.agents/skills/mygo-api-repo-review/references/report-template.md

@@ -0,0 +1,57 @@
+# Review Report Template
+
+Write the report in the language requested by the user; otherwise match the language of the review request. Preserve source identifiers, commands, file paths, and code symbols exactly.
+
+Use category-based finding IDs:
+
+- `ARCH`: architecture and evolution
+- `SEC`: security
+- `REL`: resilience
+- `DATA`: data consistency
+- `PERF`: performance and scaling
+- `IMPL`: implementation correctness
+
+Number IDs within the report, for example `SEC-001`. Assign one primary category to each root cause.
+
+Use these severity levels independently of category:
+
+- `Critical`: a reachable issue with catastrophic impact, such as broad authorization compromise, widespread sensitive-data exposure, irreversible systemic data loss, or reliable total-service failure.
+- `High`: a realistic issue causing material authorization or ownership bypass, user-data exposure or corruption, service-wide outage, or a fundamental design failure that blocks supported behavior.
+- `Medium`: a material but contained correctness, consistency, resilience, scalability, or maintainability failure with a plausible trigger.
+- `Low`: a verified, bounded defect with limited impact. Do not use `Low` for style preferences or optional improvements.
+
+Sort findings by severity, then by impact within the same severity. Security is a category, not a severity; a security finding can have any severity.
+
+Make each `Analysis` identify the existing behavior, boundary, or invariant under review, the evidence and reachable violation path, and the material impact. Do not use any report section as a backlog for absent WIP, planned, or future capabilities.
+
+Use this structure:
+
+```markdown
+- Summary
+  - Mode: diff | main | full
+  - Target: all | <path/package/component>
+  - Baseline: <commit or none>
+  - Reviewed snapshot: <HEAD and workspace state>
+  - Verification: <build, vet, test, and format-check results>
+
+- Findings
+  - ID: <CATEGORY-NNN>
+    - Severity: Critical | High | Medium | Low
+    - Location: <filename:line>
+    - Analysis: <existing behavior or invariant, evidence and reachable violation path, and material impact>
+    - Recommendation: <root-cause repair direction>
+
+  - ID: <CATEGORY-NNN>
+    - <same as above>
+
+- Architecture drift
+  - <material current differences between documented and implemented architecture, referencing finding IDs instead of duplicating analysis>
+
+- Documentation drift
+  - <documentation inaccuracies that can materially mislead implementation, operation, or review>
+
+- Unverified areas
+  - <near-qualifying current defect, missing fact, and the specific validation needed>
+```
+
+If there are no qualifying findings, write `Findings: None`. Write `None` for any other empty section. Do not omit verification failures or review limitations.

.agents/skills/mygo-api-repo-review/references/review-calibration.md

@@ -0,0 +1,27 @@
+# Review Calibration
+
+Use this reference only after open-ended discovery. Apply it to decide which candidates deserve a place in the report.
+
+## Admit a finding
+
+Accept a candidate only when all of these are present:
+
+- An existing implemented behavior, boundary, or intrinsic invariant, including code already exposed within a WIP feature. An absent part of a WIP, planned, or future capability is not itself a basis.
+- Concrete evidence that current code violates that behavior or invariant through a reachable, plausible path.
+- A material consequence under production-grade operation of the existing capability, without requiring the finished product's full feature set.
+- A precise source location and a recommendation that primarily corrects existing behavior or structure rather than delivers a missing product capability.
+
+Ask: **Does the repair mainly correct existing behavior, or design and deliver a capability that does not yet exist?** The amount of code required is not decisive; the repair's purpose is.
+
+Seek the strongest disconfirming evidence. Check other layers, tests, supported scope, containment, and intentional tradeoffs before accepting a candidate.
+
+## Apply the boundary
+
+- A missing safeguard qualifies only when it is intrinsic to an existing interface or mechanism and its absence creates a demonstrated failure. Do not turn expected product policies or lifecycle subsystems into defects merely because a mature product will need them.
+- For configuration, distinguish enforceable technical validity from operator judgment. Report values that violate an implemented mechanism's objective preconditions or are silently misapplied; do not claim the program can prove secret entropy or prevent every poor but technically valid policy choice.
+- Report architecture or evolution risk only when current design causes concrete coupling, boundary leakage, unsafe change propagation, or material rework for a committed direction. A missing future subsystem is not an architecture flaw.
+- Require a reachable hot path, resource-growth mechanism, and material impact for performance findings. Do not report style, naming, speculative scale, or optional preference as a defect.
+- Keep one primary violated invariant and root cause per finding. Do not combine independent missing defenses to raise severity; assign one category and describe only supported secondary impacts.
+- Preserve valid tests and intended behavior. Never weaken a test to dismiss an implementation failure.
+
+Use `Unverified areas` only for a near-qualifying current defect that a specific factual check can resolve. Omit undecided product policy, future capability, and general hardening ideas rather than using this section as a backlog.

AGENTS.md

@@ -1,22 +1,36 @@
-# AGENTS.md — MyGO Backend
+# AGENTS.md — MyGO
 
-## Project Essentials
+## Project Layout
 
-- Module: `github.com/dhao2001/mygo`, Go 1.26.2
+- Server: Go backend in the repository root, with documentation in `docs/server/`
-- WebDisk (cloud drive) backend; roadmap in `docs/roadmap.md`
+- Web: React client in `web/`, with documentation in `docs/web/`
-- CLI framework: `github.com/spf13/cobra`
+- Documentation index: `docs/README.md`
-- Go version pinned in `mise.toml`
 
 ## Agent Workflow
 
-1. Read the task
+1. Read the task and identify the affected project
-2. Read relevant `docs/` files for context
+2. Read `docs/README.md` and the relevant project documentation for context
 3. Explore existing code before writing new code
-4. Implement following the conventions below
+4. Implement following the relevant project conventions below
-5. Verify: `go vet ./... && go test ./...`
+5. Run the verification commands for every affected project
-6. Update `docs/roadmap.md`, `docs/decisions.md`, or `docs/architecture.md` if anything changed
+6. Update the relevant project roadmap, decisions, architecture, or development documentation if anything changed
 
-## Go Conventions
+## Server — Go Backend
+
+### Project Essentials
+
+- Module: `github.com/dhao2001/mygo`, Go 1.26.2
+- WebDisk (cloud drive) backend; roadmap in `docs/server/roadmap.md`
+- CLI framework: `github.com/spf13/cobra`
+- Go version pinned in `mise.toml`
+
+### Repository Review
+
+- Explicitly invoke `$mygo-api-repo-review` for repository-wide or scoped architecture, design, security, resilience, data-consistency, performance, and implementation audits.
+- Repository reviews are read-only unless the user separately requests fixes.
+- Use `diff`, `main`, or `full` review mode and optionally limit any mode with a target path, Go package, or logical component.
+
+### Go Conventions
 
 - **Format**: `go fmt ./...` before every commit
 - **Imports**: stdlib / third-party / internal, blank-line separated
@@ -26,19 +40,64 @@
 - **`init()`**: only in cobra cmd files for flag registration
 - **`cmd/`** is thin; business logic goes in `internal/`
 
-## Documentation
+### Documentation
 
 | File | Read Before | Update After |
 |------|-------------|--------------|
-| `docs/architecture.md` | Adding new packages | Adding new packages |
+| `docs/server/architecture.md` | Adding new packages | Adding new packages |
-| `docs/decisions.md` | Making technical decisions | Making technical decisions |
+| `docs/server/decisions.md` | Making technical decisions | Making technical decisions |
-| `docs/roadmap.md` | Every task | Completing a feature |
+| `docs/server/roadmap.md` | Every server task | Completing a server feature |
-| `docs/development.md` | Build/test/debug setup | Changing workflow |
+| `docs/server/development.md` | Build/test/debug setup | Changing server workflow |
+
+### Commands
+
+```bash
+go build ./...          # build all packages
+go test ./...           # all tests
+go vet ./...            # static analysis
+go fmt ./...            # format
+go mod tidy             # clean deps after add/remove
+```
+
+### Server DO / DON'T
+
+- DO put business logic in `internal/`, keep `cmd/` thin
+- DO add all Go module dependencies **before** writing code that uses them
+- DON'T read `go.sum` entirely into context — use `grep` or other tools to search specific patterns if needed
+- DON'T skip `go vet ./...` before finishing server work
+- DON'T add, remove, or change Go module dependencies after debugging has started — ask for explicit permission first
+
+## Web — React Client
+
+### Project Essentials
+
+- Source: `web/`
+- Pure client-side rendered application; roadmap in `docs/web/roadmap.md`
+- Stack: Node.js 24, Vite, React, TypeScript, React Router, TanStack Query, Tailwind CSS 4, and Ant Design
+- Node.js version pinned in `mise.toml`
+
+### Documentation
+
+| File | Read Before | Update After |
+|------|-------------|--------------|
+| `docs/web/decisions.md` | Making Web technical decisions | Making Web technical decisions |
+| `docs/web/roadmap.md` | Every Web task | Completing a Web feature or changing the Web plan |
+
+### Commands
+
+Run from `web/`:
+
+```bash
+npm ci                  # install locked dependencies
+npm run dev             # start the development server
+npm run check           # lint, type-check, and build
+```
 
 ## Git Version Control
 
+- When using a worktree, create a new branch and place its worktree in `.worktree/`, naming safely (for example, `git worktree add -b feat/partly-upload .worktree/feat-partly-upload`).
 - DON'T create a commit unless the user explicitly asks for one.
-- Before any commit, verify the work with the required project checks. For code changes, run `go vet ./... && go test ./...`; for docs-only changes, run the most relevant non-mutating checks if available.
+- Before any commit, verify the work with the required project checks. For code changes, run the checks for every affected project; for docs-only changes, run the most relevant non-mutating checks if available.
 - Create a commit only when all required checks pass and the current implementation area has no unresolved issues.
 - If a known failing check or unresolved issue belongs to another module and is outside the current task, report it clearly before asking for commit approval.
 - Before running `git commit`, write the complete commit message first, show it to the user, and ask for explicit approval. DON'T commit until the user approves that exact message.
@@ -72,25 +131,10 @@ feat(middleware): add AdminRequired authorization middleware
 - test: admin passes, non-admin forbidden, soft-deleted admin rejected, missing user ID.
 ```
 
-## Commands
+## Shared DO / DON'T
 
-```bash
-go build ./...          # build all packages
-go test ./...           # all tests
-go vet ./...            # static analysis
-go fmt ./...            # format
-go mod tidy             # clean deps after add/remove
-```
-
-## DO / DON'T
-
-- DO put business logic in `internal/`, keep `cmd/` thin
 - DO write all code, comments, and documentation in English
-- DO add all Go module dependencies **before** writing code that uses them
-- DON'T read `go.sum` entirely into context — use `grep` or other tools to search specific patterns if needed
-- DON'T skip `go vet ./...` before finishing work
 - DON'T commit without following the Git Version Control rules above
-- DON'T add, remove, or change Go module dependencies after debugging has started — ask for explicit permission first
 
 ## Debugging Principles
 

README.md

@@ -39,10 +39,10 @@ MyGO is a WebDisk (cloud drive) server, written in Go.
 
 ## Frontend
 
-The frontend uses React + TypeScript and communicates with the backend via HTTP API. Frontend source is maintained in a separate repository.
+The frontend uses React + TypeScript and communicates with the backend via HTTP API. Frontend source is maintained in `web/`.
 
 ---
 
 ## Development
 
-See `docs/development.md` for build and test workflows. See `AGENTS.md` for behavioral conventions.
+See `docs/README.md` for the server and Web documentation index. See `AGENTS.md` for behavioral conventions.

cmd/serve.go

@@ -12,7 +12,7 @@ import (
 
 	"github.com/dhao2001/mygo/internal/app"
 	"github.com/dhao2001/mygo/internal/config"
-	mygolog "github.com/dhao2001/mygo/internal/log"
+	"github.com/dhao2001/mygo/internal/logging"
 	"github.com/dhao2001/mygo/internal/server"
 )
 
@@ -29,7 +29,7 @@ var serveCmd = &cobra.Command{
 		}
 
 		// Set up structured logging before anything else.
-		appLogger := mygolog.NewLogger(cfg.Log)
+		appLogger := logging.NewLogger(cfg.Log)
 		slog.SetDefault(appLogger)
 		slog.Info("mygo server starting")
 		if loadInfo.EphemeralJWTSecret {

docs/README.md

@@ -1,8 +1,19 @@
 # Docs
 
+Documentation is organized by project. Use `server/` for the Go backend and `web/` for the browser client.
+
+## Server
+
 | File | Content |
 |------|---------|
-| `architecture.md` | Module layout, package boundaries |
+| `server/architecture.md` | Module layout, package boundaries |
-| `decisions.md` | Technical decisions (ADR) |
+| `server/decisions.md` | Technical decisions (ADR) |
-| `roadmap.md` | Feature progress and status |
+| `server/roadmap.md` | Feature progress and status |
-| `development.md` | Build, test, debug workflow |
+| `server/development.md` | Build, test, debug workflow |
+
+## Web
+
+| File | Content |
+|------|---------|
+| `web/decisions.md` | Technical decisions (ADR) |
+| `web/roadmap.md` | Product boundary, foundation, planned structure, and deferred dependencies |

docs/server/architecture.md

@@ -14,7 +14,12 @@ Repository (GORM data access)   Storage (file I/O)
 
 Rules:
 - Handler has no business logic — parse request, call service, write response.
+- Handler and middleware never access repositories directly; they depend on services.
 - Service has no HTTP awareness — operates on domain models and interfaces.
+- `internal/model` and `internal/service` do not import `net/http`, Gin, or `internal/api`.
+- JSON response DTOs live in HTTP packages. Domain and service result structs are not the public REST schema.
+- Domain models may use `json:"-"` for defensive redaction of sensitive fields; this is not a REST response contract.
+- Domain errors carry a protocol-neutral kind, a safe message, and an optional cause. HTTP status mapping happens only at the API boundary.
 - Repository abstracts the database; Storage abstracts where bytes live, including staged upload promotion.
 - `internal/server` is the composition root — wires all dependencies together.
 
@@ -31,12 +36,12 @@ Rules:
 | **HTTP** | `internal/server` | Gin router init, route registration (public/protected split), graceful shutdown | ✅ |
 | | `internal/handler` | HTTP handlers (auth, file, admin, webdav...) | 🛠 WIP |
 | | `internal/middleware` | Gin middleware (logger, jwt, cors, auth) | 🛠 WIP |
-| **Business** | `internal/service` | Business logic: `AuthService` (register, login, refresh, logout, passkey CRUD) | ✅ |
+| **Business** | `internal/service` | Business logic: `AuthService`, `FileService`, `AdminService`; protocol-neutral results and errors | ✅ |
-| | `internal/model` | Domain types (User, File, Credential, Session), error codes | ✅ |
+| | `internal/model` | Domain types (User, File, Credential, Session), protocol-neutral error kinds | ✅ |
 | **Data** | `internal/repository` | Repository interfaces + GORM implementations (User, Session, File, Credential) | ✅ |
 | | `internal/storage` | Storage backend interface + local disk impl, with staging and promotion | 🛠 WIP |
 | **Util** | `internal/auth` | JWT sign/verify (HS256), token type discrimination (access/refresh), password hashing (bcrypt), app passkey tokens | ✅ |
-| | `internal/api` | Unified JSON error response helpers | ✅ |
+| | `internal/api` | Unified JSON error response helpers and REST error-kind mapping | ✅ |
 
 ## API Routes (v0)
 
@@ -72,7 +77,9 @@ Applied globally by `gin.Default()`: logger → recovery
 
 Planned globally: cors
 
-Applied to protected groups: auth (JWT validation, inject user into gin.Context)
+Applied to protected groups: auth (extract bearer token, delegate access-token authentication to `AuthService`, inject principal into gin.Context)
+
+Applied to admin groups: admin (check authenticated principal from context)
 
 ## Server Responsibilities
 

docs/server/decisions.md

@@ -81,8 +81,28 @@
 | Staging before promotion | Storage backends write upload bytes to a staging path first, then promote the object to the long-term data path only after validation succeeds. |
 | Promote before DB create | The service promotes the object before creating the active file record, preventing visible DB rows from pointing at missing objects. If DB creation fails after promotion, the service best-effort deletes the promoted object. |
 | Upload parent location | Multipart upload `parent_id` is passed as a query parameter, keeping the multipart body focused on the file stream. |
+| Service-layer upload errors | HTTP transport errors are converted at the handler boundary; the file service only handles domain errors such as oversized uploads. |
 
 **Consequences**:
 - Interrupted, malformed, and oversized uploads leave only staging objects, which are safe to clean by path prefix and age.
-- Local storage can promote with `os.Rename`; future S3 storage can implement promotion with copy/delete while keeping business visibility controlled by the DB row.
+- Local storage promotes with `os.Rename` and falls back to copy/delete on cross-device `EXDEV`; future S3 storage can implement promotion with copy/delete while keeping business visibility controlled by the DB row.
 - A DB failure after promotion can still leave a long-term orphan object, but it is not visible through the file API and can be cleaned independently.
+
+## 2026-07-05: Protocol-Neutral Service Boundary
+
+**Context**: The service and model layers carried HTTP status codes and JSON response tags, and some middleware and handlers accessed repositories directly. That made the business layer harder to reuse for future WebDAV and Nextcloud-compatible APIs.
+
+**Decisions**:
+
+| Decision | Guidance |
+|----------|----------|
+| Protocol-neutral errors | `model.AppError` uses an error `Kind`, safe message, and optional cause. REST status codes are mapped in `internal/api` only. |
+| API log references | REST error responses may include `error.log_id` for server-recorded errors: all 5xx responses and 4xx responses with internal causes. |
+| Service boundaries | Handlers and middleware depend on services, not repositories. `AuthService` authenticates access tokens into a principal; `AdminService` owns admin user operations. |
+| DTO ownership | Service and model structs are internal/domain data. HTTP handlers assemble response DTOs with JSON tags. |
+| Architecture enforcement | Package-level tests reject HTTP imports in model/service and repository imports in handlers/middleware. Targeted model tests verify defensive JSON redaction for sensitive fields. |
+
+**Consequences**:
+- REST remains a handler/API concern, and future protocols can reuse services without HTTP leakage.
+- Error responses keep the same top-level shape, with optional `log_id` instead of embedding log references in the message.
+- Admin and auth middleware behavior is testable through service contracts rather than database access.

docs/server/development.md

@@ -26,6 +26,22 @@ go vet ./...
 go fmt ./...
 ```
 
+## Repository Review
+
+Use the repository-scoped `$mygo-api-repo-review` skill for evidence-based architecture, design, security, resilience, data-consistency, performance, and implementation audits. Reviews are read-only unless fixes are requested separately.
+
+Select one review mode:
+
+- `diff` compares the current workspace, including relevant untracked files, with `HEAD`.
+- `main` compares the current workspace with the merge base of `HEAD` and the local `main` branch without fetching remote refs.
+- `full` reviews the current repository as a whole.
+
+Optionally limit any mode to a target path, Go package, or logical component. For example:
+
+```text
+Use $mygo-api-repo-review in main mode with target internal/storage.
+```
+
 ## Dependencies
 
 ```bash

docs/server/roadmap.md

@@ -8,7 +8,7 @@
 | JWT authentication | ✅ | access + refresh tokens, refresh token in DB, app passkey support |
 | Web API foundation | ✅ | WebApp composition, Gin router, graceful shutdown, `GET /api/v1/version` |
 | File upload/download/manage APIs | 🛠 WIP | REST API via Gin |
-| Admin endpoints | 🛠 WIP | user CRUD for superusers |
+| Admin endpoints | 🛠 WIP | user service boundary in place for superusers |
 | WebDAV | 🛠 WIP | future v0 or v1 |
 
 ## Implementation Tasks
@@ -18,16 +18,17 @@ Package-level implementation order (each task includes unit tests):
 1. `internal/config` — Viper loader, config struct ✅
 2. `internal/app` — runtime dependency container ✅
 3. `internal/model` — domain types, error codes ✅
-4. `internal/api` — error response helpers ✅
+4. `internal/api` — protocol-neutral error kind to REST response mapping ✅
 5. `internal/auth` — JWT utils ✅
 6. `internal/storage` — backend interface + local fs with staged upload promotion
 7. `internal/repository` — interfaces + GORM/SQLite impl ✅
-8. `internal/service` — auth, file, admin services ✅ (auth done)
+8. `internal/service` — auth, file, admin services ✅
-9. `internal/middleware` — logger, cors, auth ✅ (auth done)
+9. `internal/middleware` — logger, cors, auth ✅ (auth done; principal boundary enforced)
-10. `internal/handler` — auth, account, file, admin handlers 🛠 (auth + account done)
+10. `internal/handler` — auth, account, file, admin handlers 🛠 (HTTP DTO mapping in place)
 11. `internal/server` — Gin router, route registration, graceful shutdown ✅
 12. `cmd/serve.go`, `cmd/config.go`, `cmd/status.go` ✅ (serve done)
 13. Integration tests
+14. Architecture boundary tests ✅
 
 ## Future
 

docs/web/decisions.md

@@ -0,0 +1,19 @@
+# Technical Decisions
+
+## 2026-07-14: Client-rendered Web Foundation
+
+**Context**: MyGO needs a browser client now and native clients later. The Web application must share the versioned REST API instead of introducing browser-only server logic.
+
+**Decisions**:
+
+| Area | Choice | Guidance |
+|------|--------|----------|
+| Rendering | Pure client-side rendered SPA | Vite emits static assets; do not introduce SSR, React Server Components, or a Node API server. |
+| Application stack | React, strict TypeScript, React Router, and TanStack Query | Keep routing and remote-data state explicit and client-side. |
+| UI system | Ant Design plus Tailwind CSS 4 | Ant Design owns reusable controls and theme tokens; Tailwind initially owns layout, spacing, and responsive utilities. |
+| Dependency policy | Install capabilities when their feature starts | Keep API generation, transfer, virtualization, drag-and-drop, test, and preview libraries deferred in `docs/web/roadmap.md`. |
+
+**Consequences**:
+- The Web and future native clients consume the same client-neutral API contracts.
+- MyGO or a reverse proxy may host `web/dist` with an SPA fallback without changing the rendering model.
+- MyGO domain components own file-browser behavior and must not depend on Ant Design request behavior for business logic.

docs/web/roadmap.md

@@ -0,0 +1,49 @@
+# Web Roadmap
+
+## Product Boundary
+
+- The Web client is a pure client-side rendered single-page application.
+- Vite produces static assets only. The project does not use SSR, React Server Components, a Node API server, or a browser-specific business backend.
+- The Web client consumes the same versioned REST API as future Android and other native clients.
+- Production may serve `web/dist` from MyGO or a reverse proxy.
+- Shared API contracts should remain client-neutral and eventually be described by OpenAPI.
+
+## Foundation
+
+The initial project contains only the framework and styling foundation:
+
+- Node.js 24 and npm
+- Vite
+- React
+- TypeScript in strict mode
+- TanStack Query provider
+- Tailwind CSS 4 through its Vite plugin
+- Ant Design provider and components
+- Oxlint from the Vite template
+
+Ant Design owns reusable UI components and theme tokens. Tailwind CSS is initially limited to application layout, spacing, and responsive utilities.
+
+## Planned Structure
+
+```text
+web/src/
+├── app/          # Router, providers, and application composition
+├── api/          # API client and generated contracts
+├── components/   # Shared presentation components
+├── features/     # Auth, files, account, and admin features
+├── pages/        # Route entry points
+├── lib/          # Framework-independent utilities
+└── test/         # Shared test setup and fixtures
+```
+
+## Deferred Dependencies
+
+Some dependencies are suggested for future implementation. Refer these only when the corresponding feature is implemented and propose better choices if any:
+
+- `@ant-design/icons`: Add Ant Design-consistent application and action icons when real screens require them.
+- `openapi-typescript`: Generate TypeScript API types from the shared OpenAPI document.
+- `openapi-fetch`: Provide a small type-safe Fetch client based on generated OpenAPI types.
+- `openapi-react-query`: Connect generated OpenAPI operations to TanStack Query if handwritten query adapters become repetitive.
+- `zustand`: Manage a cross-route upload queue, bulk selection, or other complex client-only state if React state is insufficient.
+- `vitest`: Run unit and integration tests using the Vite toolchain.
+- `pdfjs-dist`: Preview PDF files in the browser when document preview is implemented.

internal/api/response.go

@@ -21,48 +21,102 @@ type ErrorResponse struct {
 // ErrorBody contains human-readable error details.
 type ErrorBody struct {
 	Message string `json:"message"`
+	LogID   string `json:"log_id,omitempty"`
 }
 
 // Error writes a JSON error response.
 func Error(c *gin.Context, status int, message string) {
+	writeError(c, status, message, "")
+}
+
+func writeError(c *gin.Context, status int, message, logID string) {
 	c.JSON(status, ErrorResponse{
 		Error: ErrorBody{
 			Message: message,
+			LogID:   logID,
 		},
 	})
 }
 
 // RespondError unpacks an error from the service layer and writes a JSON
-// error response. It expects *model.AppError; unexpected non-AppError
+// error response. It maps protocol-neutral domain error kinds to HTTP status
-// values are treated as 500 with a safe message. For 500+ errors, a
+// codes at the API boundary. Unexpected non-AppError values are treated as 500
-// random reference hash is included in the response so operators can
+// with a safe message. Recorded errors return a log_id for correlation.
-// correlate it with server logs.
 func RespondError(c *gin.Context, err error) {
 	var ae *model.AppError
 	if !errors.As(err, &ae) {
-		ref := randomHex(8)
+		logID := randomHex(8)
 		slog.ErrorContext(c.Request.Context(), "non-AppError escaped to handler",
-			"ref", ref, "error", err, "type", fmt.Sprintf("%T", err))
+			"log_id", logID, "error", err, "type", fmt.Sprintf("%T", err))
-		Error(c, http.StatusInternalServerError, "internal server error (ref: "+ref+")")
+		writeError(c, http.StatusInternalServerError, "internal server error", logID)
 		return
 	}
 
-	// 500+ errors: log full detail with a reference hash, return sanitized message.
+	status := StatusForErrorKind(ae.Kind)
-	if ae.Status >= 500 {
+	message := ae.Message
-		ref := randomHex(8)
+	if status >= http.StatusInternalServerError {
+		message = "internal server error"
+	}
+
+	if status >= http.StatusInternalServerError {
+		logID := randomHex(8)
 		slog.ErrorContext(c.Request.Context(), "internal server error",
-			"ref", ref, slog.Any("error", ae.Err), "message", ae.Message)
+			"log_id", logID, slog.Any("error", ae.Err), "message", ae.Message)
-		Error(c, ae.Status, "internal server error (ref: "+ref+")")
+		writeError(c, status, message, logID)
 		return
 	}
 
-	// 4xx errors with internal cause: log at WARN for diagnostics.
+	// 4xx errors with unexpected causes are recorded for diagnostics and return log_id.
-	if ae.Err != nil {
+	if isLoggableCause(ae.Err) {
+		logID := randomHex(8)
 		slog.WarnContext(c.Request.Context(), ae.Message,
-			"status", ae.Status, slog.Any("error", ae.Err))
+			"log_id", logID, "status", status, slog.Any("error", ae.Err))
+		writeError(c, status, message, logID)
+		return
 	}
 
-	Error(c, ae.Status, ae.Message)
+	writeError(c, status, message, "")
+}
+
+func isLoggableCause(err error) bool {
+	if err == nil {
+		return false
+	}
+
+	for _, expected := range []error{
+		model.ErrNotFound,
+		model.ErrDuplicate,
+		model.ErrUnauthorized,
+		model.ErrForbidden,
+		model.ErrUploadTooLarge,
+	} {
+		if errors.Is(err, expected) {
+			return false
+		}
+	}
+	return true
+}
+
+// StatusForErrorKind maps a protocol-neutral error kind to a REST status code.
+func StatusForErrorKind(kind model.ErrorKind) int {
+	switch kind {
+	case model.KindInvalidArgument:
+		return http.StatusBadRequest
+	case model.KindUnauthenticated:
+		return http.StatusUnauthorized
+	case model.KindPermissionDenied:
+		return http.StatusForbidden
+	case model.KindNotFound:
+		return http.StatusNotFound
+	case model.KindConflict:
+		return http.StatusConflict
+	case model.KindPayloadTooLarge:
+		return http.StatusRequestEntityTooLarge
+	case model.KindInternal:
+		return http.StatusInternalServerError
+	default:
+		return http.StatusInternalServerError
+	}
 }
 
 func randomHex(n int) string {

internal/api/response_test.go

@@ -2,11 +2,14 @@ package api
 
 import (
 	"encoding/json"
+	"errors"
 	"net/http"
 	"net/http/httptest"
 	"testing"
 
 	"github.com/gin-gonic/gin"
+
+	"github.com/dhao2001/mygo/internal/model"
 )
 
 func TestError(t *testing.T) {
@@ -33,4 +36,66 @@ func TestError(t *testing.T) {
 	if body.Error.Message != "invalid request" {
 		t.Errorf("message = %q, want %q", body.Error.Message, "invalid request")
 	}
+	if body.Error.LogID != "" {
+		t.Errorf("log_id = %q, want empty", body.Error.LogID)
+	}
+}
+
+func TestRespondErrorMapsDomainKinds(t *testing.T) {
+	tests := []struct {
+		name       string
+		err        error
+		wantStatus int
+		wantLogID  bool
+	}{
+		{"invalid argument", model.NewInvalidArgumentError("bad input"), http.StatusBadRequest, false},
+		{"unauthenticated", model.NewUnauthenticatedError("invalid token"), http.StatusUnauthorized, false},
+		{"permission denied", model.NewPermissionDeniedError("access denied", nil), http.StatusForbidden, false},
+		{"not found", model.NewNotFoundError("missing", nil), http.StatusNotFound, false},
+		{"conflict", model.NewConflictError("duplicate"), http.StatusConflict, false},
+		{"payload too large", model.NewPayloadTooLargeError("too large", nil), http.StatusRequestEntityTooLarge, false},
+		{"internal", model.NewInternalError("lookup", errors.New("database offline")), http.StatusInternalServerError, true},
+		{"unknown", errors.New("escaped error"), http.StatusInternalServerError, true},
+		{"permission denied sentinel cause", model.NewPermissionDeniedError("access denied", model.ErrForbidden), http.StatusForbidden, false},
+		{"not found sentinel cause", model.NewNotFoundError("missing", model.ErrNotFound), http.StatusNotFound, false},
+		{"payload too large sentinel cause", model.NewPayloadTooLargeError("too large", model.ErrUploadTooLarge), http.StatusRequestEntityTooLarge, false},
+		{"client with diagnostic cause", model.NewPermissionDeniedError("access denied", errors.New("policy backend failed")), http.StatusForbidden, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			rec := exerciseRespondError(tt.err)
+			if rec.Code != tt.wantStatus {
+				t.Fatalf("status = %d, want %d; body = %s", rec.Code, tt.wantStatus, rec.Body.String())
+			}
+
+			var body ErrorResponse
+			if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+				t.Fatalf("unmarshal response: %v", err)
+			}
+
+			if tt.wantLogID && body.Error.LogID == "" {
+				t.Fatalf("log_id is empty, want populated; body = %s", rec.Body.String())
+			}
+			if !tt.wantLogID && body.Error.LogID != "" {
+				t.Fatalf("log_id = %q, want empty", body.Error.LogID)
+			}
+			if rec.Code >= http.StatusInternalServerError && body.Error.Message != "internal server error" {
+				t.Fatalf("message = %q, want sanitized internal message", body.Error.Message)
+			}
+		})
+	}
+}
+
+func exerciseRespondError(err error) *httptest.ResponseRecorder {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	router.GET("/error", func(c *gin.Context) {
+		RespondError(c, err)
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/error", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+	return rec
 }

internal/app/webapp.go

@@ -23,6 +23,7 @@ type WebApp struct {
 	FileRepo       repository.FileRepository
 	CredentialRepo repository.CredentialRepository
 	AuthService    *service.AuthService
+	AdminService   *service.AdminService
 	FileService    *service.FileService
 	Storage        storage.StorageBackend
 }
@@ -58,6 +59,7 @@ func Bootstrap(cfg *config.Config) (*WebApp, error) {
 	}
 
 	fileService := service.NewFileService(fileRepo, store, cfg.Storage.MaxUploadSize, slog.Default())
+	adminService := service.NewAdminService(userRepo)
 
 	return &WebApp{
 		Config:         cfg,
@@ -68,6 +70,7 @@ func Bootstrap(cfg *config.Config) (*WebApp, error) {
 		FileRepo:       fileRepo,
 		CredentialRepo: credentialRepo,
 		AuthService:    authService,
+		AdminService:   adminService,
 		FileService:    fileService,
 		Storage:        store,
 	}, nil
@@ -80,6 +83,7 @@ func NewWebApp(cfg *config.Config, db *gorm.DB,
 	fileRepo repository.FileRepository,
 	credentialRepo repository.CredentialRepository,
 	authService *service.AuthService,
+	adminService *service.AdminService,
 	fileService *service.FileService,
 	store storage.StorageBackend,
 ) *WebApp {
@@ -92,6 +96,7 @@ func NewWebApp(cfg *config.Config, db *gorm.DB,
 		FileRepo:       fileRepo,
 		CredentialRepo: credentialRepo,
 		AuthService:    authService,
+		AdminService:   adminService,
 		FileService:    fileService,
 		Storage:        store,
 	}

internal/app/webapp_test.go

@@ -9,7 +9,7 @@ import (
 func TestNewWebApp(t *testing.T) {
 	cfg := &config.Config{}
 
-	webApp := NewWebApp(cfg, nil, nil, nil, nil, nil, nil, nil, nil)
+	webApp := NewWebApp(cfg, nil, nil, nil, nil, nil, nil, nil, nil, nil)
 
 	if webApp.Config != cfg {
 		t.Fatal("Config was not assigned")
@@ -20,7 +20,7 @@ func TestNewWebApp(t *testing.T) {
 }
 
 func TestCloseNilDB(t *testing.T) {
-	webApp := NewWebApp(&config.Config{}, nil, nil, nil, nil, nil, nil, nil, nil)
+	webApp := NewWebApp(&config.Config{}, nil, nil, nil, nil, nil, nil, nil, nil, nil)
 	if err := webApp.Close(); err != nil {
 		t.Errorf("Close with nil DB should not error: %v", err)
 	}

internal/architecture_test.go

@@ -0,0 +1,68 @@
+package internal_test
+
+import (
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"os"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+func TestArchitecture_ModelAndServiceAreProtocolNeutral(t *testing.T) {
+	for _, dir := range []string{"model", "service"} {
+		imports := packageImports(t, dir)
+		for _, forbidden := range []string{
+			"net/http",
+			"github.com/gin-gonic/gin",
+			"github.com/dhao2001/mygo/internal/api",
+		} {
+			if imports[forbidden] {
+				t.Fatalf("internal/%s imports forbidden package %q", dir, forbidden)
+			}
+		}
+	}
+}
+
+func TestArchitecture_HTTPDoesNotImportRepositories(t *testing.T) {
+	for _, dir := range []string{"handler", "middleware"} {
+		imports := packageImports(t, dir)
+		if imports["github.com/dhao2001/mygo/internal/repository"] {
+			t.Fatalf("internal/%s imports internal/repository; use service boundaries instead", dir)
+		}
+	}
+}
+
+func packageImports(t *testing.T, dir string) map[string]bool {
+	t.Helper()
+
+	imports := map[string]bool{}
+	pkgs := parsePackage(t, dir)
+	for _, pkg := range pkgs {
+		for _, file := range pkg.Files {
+			for _, spec := range file.Imports {
+				path, err := strconv.Unquote(spec.Path.Value)
+				if err != nil {
+					t.Fatalf("unquote import path %s: %v", spec.Path.Value, err)
+				}
+				imports[path] = true
+			}
+		}
+	}
+	return imports
+}
+
+func parsePackage(t *testing.T, dir string) map[string]*ast.Package {
+	t.Helper()
+
+	fset := token.NewFileSet()
+	pkgs, err := parser.ParseDir(fset, dir, func(info os.FileInfo) bool {
+		name := info.Name()
+		return !strings.HasSuffix(name, "_test.go")
+	}, parser.ParseComments)
+	if err != nil {
+		t.Fatalf("parse internal/%s: %v", dir, err)
+	}
+	return pkgs
+}

internal/handler/account.go

@@ -3,6 +3,7 @@ package handler
 import (
 	"log/slog"
 	"net/http"
+	"time"
 
 	"github.com/gin-gonic/gin"
 
@@ -26,10 +27,29 @@ type createPasskeyRequest struct {
 	Label string `json:"label" binding:"required"`
 }
 
+type accountResponse struct {
+	UserID string `json:"user_id"`
+}
+
+type passkeyResponse struct {
+	ID         string     `json:"id"`
+	UserID     string     `json:"user_id"`
+	Type       string     `json:"type"`
+	Label      string     `json:"label"`
+	LastUsedAt *time.Time `json:"last_used_at"`
+	CreatedAt  time.Time  `json:"created_at"`
+}
+
+type createdPasskeyResponse struct {
+	ID    string `json:"id"`
+	Raw   string `json:"raw"`
+	Label string `json:"label"`
+}
+
 // GetAccount handles GET /api/v1/account.
 func (h *AccountHandler) GetAccount(c *gin.Context) {
 	userID := middleware.MustGetUserID(c)
-	c.JSON(http.StatusOK, gin.H{"user_id": userID})
+	c.JSON(http.StatusOK, accountResponse{UserID: userID})
 }
 
 // ListPasskeys handles GET /api/v1/account/passkeys.
@@ -46,7 +66,7 @@ func (h *AccountHandler) ListPasskeys(c *gin.Context) {
 		creds = []model.Credential{}
 	}
 
-	c.JSON(http.StatusOK, creds)
+	c.JSON(http.StatusOK, toPasskeyResponses(creds))
 }
 
 // CreatePasskey handles POST /api/v1/account/passkeys.
@@ -66,7 +86,11 @@ func (h *AccountHandler) CreatePasskey(c *gin.Context) {
 		return
 	}
 
-	c.JSON(http.StatusCreated, pk)
+	c.JSON(http.StatusCreated, createdPasskeyResponse{
+		ID:    pk.ID,
+		Raw:   pk.Raw,
+		Label: pk.Label,
+	})
 }
 
 // RevokePasskey handles DELETE /api/v1/account/passkeys/:id.
@@ -86,3 +110,18 @@ func (h *AccountHandler) RevokePasskey(c *gin.Context) {
 
 	c.Status(http.StatusOK)
 }
+
+func toPasskeyResponses(creds []model.Credential) []passkeyResponse {
+	items := make([]passkeyResponse, 0, len(creds))
+	for i := range creds {
+		items = append(items, passkeyResponse{
+			ID:         creds[i].ID,
+			UserID:     creds[i].UserID,
+			Type:       creds[i].Type,
+			Label:      creds[i].Label,
+			LastUsedAt: creds[i].LastUsedAt,
+			CreatedAt:  creds[i].CreatedAt,
+		})
+	}
+	return items
+}

internal/handler/account_test.go

@@ -10,8 +10,6 @@ import (
 	"github.com/gin-gonic/gin"
 
 	"github.com/dhao2001/mygo/internal/middleware"
-	"github.com/dhao2001/mygo/internal/model"
-	"github.com/dhao2001/mygo/internal/service"
 )
 
 func setupAccountRouter(t *testing.T) (*gin.Engine, []byte) {
@@ -31,7 +29,7 @@ func setupAccountRouter(t *testing.T) (*gin.Engine, []byte) {
 	}
 
 	protected := r.Group("/api/v1")
-	protected.Use(middleware.AuthRequired(secret))
+	protected.Use(middleware.AuthRequired(svc))
 	{
 		account := protected.Group("/account")
 		{
@@ -65,7 +63,7 @@ func TestAccountEndpoint(t *testing.T) {
 	rec = httptest.NewRecorder()
 	r.ServeHTTP(rec, req)
 
-	var pair service.TokenPair
+	var pair testTokenPairResponse
 	json.Unmarshal(rec.Body.Bytes(), &pair)
 
 	// Get /account
@@ -107,7 +105,7 @@ func TestPasskeyCRUD(t *testing.T) {
 	rec = httptest.NewRecorder()
 	r.ServeHTTP(rec, req)
 
-	var pair service.TokenPair
+	var pair testTokenPairResponse
 	json.Unmarshal(rec.Body.Bytes(), &pair)
 	authHeader := "Bearer " + pair.AccessToken
 
@@ -134,7 +132,7 @@ func TestPasskeyCRUD(t *testing.T) {
 	}
 
 	// Revoke passkey
-	var creds []model.Credential
+	var creds []passkeyResponse
 	json.Unmarshal(rec.Body.Bytes(), &creds)
 	if len(creds) != 1 {
 		t.Fatalf("expected 1 passkey, got %d", len(creds))

internal/handler/admin.go

@@ -9,17 +9,17 @@ import (
 
 	"github.com/dhao2001/mygo/internal/api"
 	"github.com/dhao2001/mygo/internal/model"
-	"github.com/dhao2001/mygo/internal/repository"
+	"github.com/dhao2001/mygo/internal/service"
 )
 
 // AdminHandler handles admin-only endpoints for user management.
 type AdminHandler struct {
-	userRepo repository.UserRepository
+	adminService *service.AdminService
 }
 
 // NewAdminHandler creates an AdminHandler.
-func NewAdminHandler(userRepo repository.UserRepository) *AdminHandler {
+func NewAdminHandler(adminService *service.AdminService) *AdminHandler {
-	return &AdminHandler{userRepo: userRepo}
+	return &AdminHandler{adminService: adminService}
 }
 
 // adminUserResponse exposes all user fields, including status, for admin views.
@@ -55,7 +55,7 @@ func toAdminResponse(u *model.User) adminUserResponse {
 func (h *AdminHandler) DeleteUser(c *gin.Context) {
 	id := c.Param("id")
 
-	if err := h.userRepo.Delete(c.Request.Context(), id); err != nil {
+	if err := h.adminService.DeleteUser(c.Request.Context(), id); err != nil {
 		api.RespondError(c, err)
 		return
 	}
@@ -67,7 +67,7 @@ func (h *AdminHandler) DeleteUser(c *gin.Context) {
 func (h *AdminHandler) GetUser(c *gin.Context) {
 	id := c.Param("id")
 
-	user, err := h.userRepo.FindByIDIncludeDeleted(c.Request.Context(), id)
+	user, err := h.adminService.GetUser(c.Request.Context(), id)
 	if err != nil {
 		api.RespondError(c, err)
 		return
@@ -93,7 +93,7 @@ func (h *AdminHandler) ListUsers(c *gin.Context) {
 		limit = 200
 	}
 
-	users, total, err := h.userRepo.ListIncludeDeleted(c.Request.Context(), offset, limit)
+	users, total, err := h.adminService.ListUsers(c.Request.Context(), offset, limit)
 	if err != nil {
 		api.RespondError(c, err)
 		return

internal/handler/admin_test.go

@@ -42,7 +42,8 @@ func setupAdminRouter(t *testing.T) (*gin.Engine, repository.UserRepository) {
 	)
 
 	authHandler := NewAuthHandler(authService)
-	adminHandler := NewAdminHandler(userRepo)
+	adminService := service.NewAdminService(userRepo)
+	adminHandler := NewAdminHandler(adminService)
 
 	gin.SetMode(gin.TestMode)
 	r := gin.New()
@@ -54,8 +55,8 @@ func setupAdminRouter(t *testing.T) (*gin.Engine, repository.UserRepository) {
 	}
 
 	admin := r.Group("/api/v1/admin")
-	admin.Use(middleware.AuthRequired(secret))
+	admin.Use(middleware.AuthRequired(authService))
-	admin.Use(middleware.AdminRequired(userRepo))
+	admin.Use(middleware.AdminRequired())
 	{
 		admin.GET("/users", adminHandler.ListUsers)
 		admin.GET("/users/:id", adminHandler.GetUser)
@@ -104,7 +105,7 @@ func loginHelper(t *testing.T, r *gin.Engine, email, password string) string {
 		t.Fatalf("login %s: status = %d, body = %s", email, rec.Code, rec.Body.String())
 	}
 
-	var pair service.TokenPair
+	var pair testTokenPairResponse
 	if err := json.Unmarshal(rec.Body.Bytes(), &pair); err != nil {
 		t.Fatalf("unmarshal login response: %v", err)
 	}

internal/handler/auth.go

@@ -3,10 +3,12 @@ package handler
 import (
 	"log/slog"
 	"net/http"
+	"time"
 
 	"github.com/gin-gonic/gin"
 
 	"github.com/dhao2001/mygo/internal/api"
+	"github.com/dhao2001/mygo/internal/model"
 	"github.com/dhao2001/mygo/internal/service"
 )
 
@@ -35,6 +37,20 @@ type tokenRequest struct {
 	RefreshToken string `json:"refresh_token" binding:"required"`
 }
 
+type userResponse struct {
+	ID        string    `json:"id"`
+	Username  string    `json:"username"`
+	Email     string    `json:"email"`
+	IsAdmin   bool      `json:"is_admin"`
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `json:"updated_at"`
+}
+
+type tokenPairResponse struct {
+	AccessToken  string `json:"access_token"`
+	RefreshToken string `json:"refresh_token"`
+}
+
 // Register handles POST /api/v1/auth/register.
 func (h *AuthHandler) Register(c *gin.Context) {
 	var req registerRequest
@@ -50,7 +66,7 @@ func (h *AuthHandler) Register(c *gin.Context) {
 		return
 	}
 
-	c.JSON(http.StatusCreated, user)
+	c.JSON(http.StatusCreated, toUserResponse(user))
 }
 
 // Login handles POST /api/v1/auth/login.
@@ -68,7 +84,7 @@ func (h *AuthHandler) Login(c *gin.Context) {
 		return
 	}
 
-	c.JSON(http.StatusOK, pair)
+	c.JSON(http.StatusOK, toTokenPairResponse(pair))
 }
 
 // Refresh handles POST /api/v1/auth/refresh.
@@ -86,7 +102,7 @@ func (h *AuthHandler) Refresh(c *gin.Context) {
 		return
 	}
 
-	c.JSON(http.StatusOK, pair)
+	c.JSON(http.StatusOK, toTokenPairResponse(pair))
 }
 
 // Logout handles POST /api/v1/auth/logout.
@@ -105,3 +121,21 @@ func (h *AuthHandler) Logout(c *gin.Context) {
 
 	c.Status(http.StatusOK)
 }
+
+func toUserResponse(user *model.User) userResponse {
+	return userResponse{
+		ID:        user.ID,
+		Username:  user.Username,
+		Email:     user.Email,
+		IsAdmin:   user.IsAdmin,
+		CreatedAt: user.CreatedAt,
+		UpdatedAt: user.UpdatedAt,
+	}
+}
+
+func toTokenPairResponse(pair *service.TokenPair) tokenPairResponse {
+	return tokenPairResponse{
+		AccessToken:  pair.AccessToken,
+		RefreshToken: pair.RefreshToken,
+	}
+}

internal/handler/auth_test.go

@@ -17,6 +17,11 @@ import (
 	"github.com/dhao2001/mygo/internal/service"
 )
 
+type testTokenPairResponse struct {
+	AccessToken  string `json:"access_token"`
+	RefreshToken string `json:"refresh_token"`
+}
+
 func setupTestAuthService(t *testing.T) (*service.AuthService, []byte) {
 	t.Helper()
 
@@ -140,7 +145,7 @@ func TestLoginHandler(t *testing.T) {
 		t.Errorf("status = %d, want %d; body = %s", rec.Code, http.StatusOK, rec.Body.String())
 	}
 
-	var pair service.TokenPair
+	var pair testTokenPairResponse
 	if err := json.Unmarshal(rec.Body.Bytes(), &pair); err != nil {
 		t.Fatalf("unmarshal response: %v", err)
 	}
@@ -196,7 +201,7 @@ func TestRefreshHandler(t *testing.T) {
 	rec = httptest.NewRecorder()
 	r.ServeHTTP(rec, req)
 
-	var pair service.TokenPair
+	var pair testTokenPairResponse
 	json.Unmarshal(rec.Body.Bytes(), &pair)
 
 	// Refresh

internal/handler/file.go

@@ -10,11 +10,13 @@ import (
 	"net/http"
 	"net/url"
 	"strconv"
+	"time"
 
 	"github.com/gin-gonic/gin"
 
 	"github.com/dhao2001/mygo/internal/api"
 	"github.com/dhao2001/mygo/internal/middleware"
+	"github.com/dhao2001/mygo/internal/model"
 	"github.com/dhao2001/mygo/internal/service"
 )
 
@@ -24,6 +26,13 @@ const (
 	multipartFileField      = "file"
 )
 
+var (
+	errMissingFileField         = errors.New("missing file field")
+	errMissingFileName          = errors.New("missing file name")
+	errUnexpectedMultipartField = errors.New("unexpected multipart field")
+	errInvalidMultipartForm     = errors.New("invalid multipart form")
+)
+
 // FileHandler handles file management endpoints.
 type FileHandler struct {
 	fileService *service.FileService
@@ -44,6 +53,23 @@ type updateFileRequest struct {
 	ParentID *string `json:"parent_id"`
 }
 
+type fileInfoResponse struct {
+	ID        string    `json:"id"`
+	UserID    string    `json:"user_id"`
+	ParentID  *string   `json:"parent_id"`
+	Name      string    `json:"name"`
+	Size      int64     `json:"size"`
+	MimeType  string    `json:"mime_type"`
+	IsDir     bool      `json:"is_dir"`
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `json:"updated_at"`
+}
+
+type fileListResponse struct {
+	Files []fileInfoResponse `json:"files"`
+	Total int64              `json:"total"`
+}
+
 // Upload handles POST /api/v1/files.
 // If the content type is multipart/form-data, it uploads a file.
 // If the content type is application/json, it creates a directory.
@@ -73,7 +99,7 @@ func (h *FileHandler) Upload(c *gin.Context) {
 			return
 		}
 
-		c.JSON(http.StatusCreated, dir)
+		c.JSON(http.StatusCreated, toFileInfoResponse(dir))
 		return
 	}
 
@@ -111,48 +137,73 @@ func (h *FileHandler) Upload(c *gin.Context) {
 			api.Error(c, http.StatusRequestEntityTooLarge, "request body is too large")
 			return
 		}
-		api.Error(c, http.StatusBadRequest, err.Error())
+		api.Error(c, http.StatusBadRequest, uploadPartErrorMessage(err))
 		return
 	}
 	defer part.Close()
 
-	info, err := h.fileService.Upload(c.Request.Context(), userID, parentID, fileName, part)
+	info, err := h.fileService.Upload(c.Request.Context(), userID, parentID, fileName, uploadBodyReader{reader: part})
 	if err != nil {
 		api.RespondError(c, err)
 		return
 	}
 
-	c.JSON(http.StatusCreated, info)
+	c.JSON(http.StatusCreated, toFileInfoResponse(info))
 }
 
 func nextUploadFilePart(reader *multipart.Reader) (*multipart.Part, string, error) {
 	part, err := reader.NextPart()
 	if err != nil {
 		if err == io.EOF {
-			return nil, "", errors.New("missing file field")
+			return nil, "", errMissingFileField
 		}
-		return nil, "", err
+		return nil, "", fmt.Errorf("%w: %v", errInvalidMultipartForm, err)
 	}
 
 	if part.FormName() != multipartFileField {
 		part.Close()
-		return nil, "", fmt.Errorf("unexpected multipart field %q", part.FormName())
+		return nil, "", fmt.Errorf("%w: %q", errUnexpectedMultipartField, part.FormName())
 	}
 
 	fileName := part.FileName()
 	if fileName == "" {
 		part.Close()
-		return nil, "", errors.New("missing file name")
+		return nil, "", errMissingFileName
 	}
 
 	return part, fileName, nil
 }
 
+func uploadPartErrorMessage(err error) string {
+	switch {
+	case errors.Is(err, errMissingFileField):
+		return "missing file field"
+	case errors.Is(err, errMissingFileName):
+		return "missing file name"
+	case errors.Is(err, errUnexpectedMultipartField):
+		return "unexpected multipart field"
+	default:
+		return "invalid multipart form"
+	}
+}
+
 func isRequestBodyTooLarge(err error) bool {
 	var maxBytesErr *http.MaxBytesError
 	return errors.As(err, &maxBytesErr)
 }
 
+type uploadBodyReader struct {
+	reader io.Reader
+}
+
+func (r uploadBodyReader) Read(p []byte) (int, error) {
+	n, err := r.reader.Read(p)
+	if isRequestBodyTooLarge(err) {
+		return n, model.ErrUploadTooLarge
+	}
+	return n, err
+}
+
 // List handles GET /api/v1/files.
 func (h *FileHandler) List(c *gin.Context) {
 	userID := middleware.MustGetUserID(c)
@@ -184,7 +235,7 @@ func (h *FileHandler) List(c *gin.Context) {
 		return
 	}
 
-	c.JSON(http.StatusOK, list)
+	c.JSON(http.StatusOK, toFileListResponse(list))
 }
 
 // Get handles GET /api/v1/files/:id.
@@ -198,7 +249,7 @@ func (h *FileHandler) Get(c *gin.Context) {
 		return
 	}
 
-	c.JSON(http.StatusOK, info)
+	c.JSON(http.StatusOK, toFileInfoResponse(info))
 }
 
 // Download handles GET /api/v1/files/:id/content.
@@ -223,7 +274,23 @@ func (h *FileHandler) Download(c *gin.Context) {
 	c.Header("Content-Length", strconv.FormatInt(info.Size, 10))
 
 	c.Status(http.StatusOK)
-	io.Copy(c.Writer, reader)
+	written, err := io.Copy(c.Writer, reader)
+	if err != nil {
+		slog.WarnContext(c.Request.Context(), "download copy failed",
+			"user_id", userID,
+			"file_id", fileID,
+			"written", written,
+			"expected_size", info.Size,
+			"error", err)
+		return
+	}
+	if written != info.Size {
+		slog.WarnContext(c.Request.Context(), "download size mismatch",
+			"user_id", userID,
+			"file_id", fileID,
+			"written", written,
+			"expected_size", info.Size)
+	}
 }
 
 // Update handles PUT /api/v1/files/:id.
@@ -250,7 +317,7 @@ func (h *FileHandler) Update(c *gin.Context) {
 		return
 	}
 
-	c.JSON(http.StatusOK, info)
+	c.JSON(http.StatusOK, toFileInfoResponse(info))
 }
 
 // Delete handles DELETE /api/v1/files/:id.
@@ -265,3 +332,28 @@ func (h *FileHandler) Delete(c *gin.Context) {
 
 	c.Status(http.StatusNoContent)
 }
+
+func toFileInfoResponse(info *service.FileInfo) fileInfoResponse {
+	return fileInfoResponse{
+		ID:        info.ID,
+		UserID:    info.UserID,
+		ParentID:  info.ParentID,
+		Name:      info.Name,
+		Size:      info.Size,
+		MimeType:  info.MimeType,
+		IsDir:     info.IsDir,
+		CreatedAt: info.CreatedAt,
+		UpdatedAt: info.UpdatedAt,
+	}
+}
+
+func toFileListResponse(list *service.FileList) fileListResponse {
+	items := make([]fileInfoResponse, 0, len(list.Files))
+	for i := range list.Files {
+		items = append(items, toFileInfoResponse(&list.Files[i]))
+	}
+	return fileListResponse{
+		Files: items,
+		Total: list.Total,
+	}
+}

internal/handler/file_test.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"io"
 	"mime/multipart"
 	"net/http"
@@ -24,6 +25,7 @@ import (
 // inMemStore implements storage.StorageBackend with an in-memory map.
 type inMemStore struct {
 	files     map[string][]byte
+	failReads bool
 }
 
 func newInMemStore() *inMemStore {
@@ -54,6 +56,9 @@ func (s *inMemStore) Open(_ context.Context, path string) (io.ReadCloser, error)
 	if !ok {
 		return nil, &fsNotFoundError{path}
 	}
+	if s.failReads {
+		return io.NopCloser(&errorAfterReader{data: data, err: errors.New("download read failed")}), nil
+	}
 	return io.NopCloser(bytes.NewReader(data)), nil
 }
 
@@ -70,13 +75,27 @@ type fsNotFoundError struct{ path string }
 
 func (e *fsNotFoundError) Error() string { return "file not found on disk: " + e.path }
 
+type errorAfterReader struct {
+	data []byte
+	err  error
+}
+
+func (r *errorAfterReader) Read(p []byte) (int, error) {
+	if len(r.data) == 0 {
+		return 0, r.err
+	}
+	n := copy(p, r.data)
+	r.data = r.data[n:]
+	return n, nil
+}
+
 var _ storage.StorageBackend = (*inMemStore)(nil)
 
-func setupFileHandler(t *testing.T) *FileHandler {
+func setupFileHandler(t *testing.T) (*FileHandler, *inMemStore) {
 	return setupFileHandlerWithMaxUploadSize(t, 0)
 }
 
-func setupFileHandlerWithMaxUploadSize(t *testing.T, maxUploadSize int64) *FileHandler {
+func setupFileHandlerWithMaxUploadSize(t *testing.T, maxUploadSize int64) (*FileHandler, *inMemStore) {
 	t.Helper()
 
 	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
@@ -91,7 +110,7 @@ func setupFileHandlerWithMaxUploadSize(t *testing.T, maxUploadSize int64) *FileH
 	store := newInMemStore()
 	fileService := service.NewFileService(fileRepo, store, maxUploadSize, nil)
 
-	return NewFileHandler(fileService)
+	return NewFileHandler(fileService), store
 }
 
 func setupFileRouter(t *testing.T) *gin.Engine {
@@ -99,9 +118,14 @@ func setupFileRouter(t *testing.T) *gin.Engine {
 }
 
 func setupFileRouterWithMaxUploadSize(t *testing.T, maxUploadSize int64) *gin.Engine {
+	r, _ := setupFileRouterWithMaxUploadSizeAndStore(t, maxUploadSize)
+	return r
+}
+
+func setupFileRouterWithMaxUploadSizeAndStore(t *testing.T, maxUploadSize int64) (*gin.Engine, *inMemStore) {
 	t.Helper()
 
-	handler := setupFileHandlerWithMaxUploadSize(t, maxUploadSize)
+	handler, store := setupFileHandlerWithMaxUploadSize(t, maxUploadSize)
 
 	gin.SetMode(gin.TestMode)
 	r := gin.New()
@@ -125,7 +149,7 @@ func setupFileRouterWithMaxUploadSize(t *testing.T, maxUploadSize int64) *gin.En
 		files.DELETE("/:id", handler.Delete)
 	}
 
-	return r
+	return r, store
 }
 
 func TestFileHandler_Upload(t *testing.T) {
@@ -147,7 +171,7 @@ func TestFileHandler_Upload(t *testing.T) {
 		t.Errorf("status = %d, want %d; body = %s", rec.Code, http.StatusCreated, rec.Body.String())
 	}
 
-	var info service.FileInfo
+	var info fileInfoResponse
 	if err := json.Unmarshal(rec.Body.Bytes(), &info); err != nil {
 		t.Fatalf("unmarshal: %v", err)
 	}
@@ -234,6 +258,52 @@ func TestFileHandler_UploadNoFile(t *testing.T) {
 	}
 }
 
+func TestFileHandler_UploadUnexpectedFieldDoesNotEchoFieldName(t *testing.T) {
+	r := setupFileRouter(t)
+
+	body := &bytes.Buffer{}
+	writer := multipart.NewWriter(body)
+	part, _ := writer.CreateFormField("secret_token")
+	part.Write([]byte("secret"))
+	writer.Close()
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/files", body)
+	req.Header.Set("Content-Type", writer.FormDataContentType())
+	req.Header.Set("X-User-ID", "user1")
+	rec := httptest.NewRecorder()
+	r.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d; body = %s", rec.Code, http.StatusBadRequest, rec.Body.String())
+	}
+	if !strings.Contains(rec.Body.String(), "unexpected multipart field") {
+		t.Errorf("body = %s, want safe unexpected field message", rec.Body.String())
+	}
+	if strings.Contains(rec.Body.String(), "secret_token") {
+		t.Errorf("body leaks multipart field name: %s", rec.Body.String())
+	}
+}
+
+func TestFileHandler_UploadMalformedMultipartDoesNotLeakParserError(t *testing.T) {
+	r := setupFileRouter(t)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/files", strings.NewReader("not a valid multipart body"))
+	req.Header.Set("Content-Type", "multipart/form-data; boundary=mygo-boundary")
+	req.Header.Set("X-User-ID", "user1")
+	rec := httptest.NewRecorder()
+	r.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d; body = %s", rec.Code, http.StatusBadRequest, rec.Body.String())
+	}
+	if !strings.Contains(rec.Body.String(), "invalid multipart form") {
+		t.Errorf("body = %s, want safe invalid multipart message", rec.Body.String())
+	}
+	if strings.Contains(rec.Body.String(), "NextPart") || strings.Contains(rec.Body.String(), "EOF") {
+		t.Errorf("body leaks parser internals: %s", rec.Body.String())
+	}
+}
+
 func TestFileHandler_CreateDir(t *testing.T) {
 	r := setupFileRouter(t)
 
@@ -248,7 +318,7 @@ func TestFileHandler_CreateDir(t *testing.T) {
 		t.Errorf("status = %d, want %d; body = %s", rec.Code, http.StatusCreated, rec.Body.String())
 	}
 
-	var info service.FileInfo
+	var info fileInfoResponse
 	if err := json.Unmarshal(rec.Body.Bytes(), &info); err != nil {
 		t.Fatalf("unmarshal: %v", err)
 	}
@@ -283,7 +353,7 @@ func TestFileHandler_List(t *testing.T) {
 		t.Errorf("status = %d, want %d; body = %s", rec.Code, http.StatusOK, rec.Body.String())
 	}
 
-	var list service.FileList
+	var list fileListResponse
 	if err := json.Unmarshal(rec.Body.Bytes(), &list); err != nil {
 		t.Fatalf("unmarshal: %v", err)
 	}
@@ -308,7 +378,7 @@ func TestFileHandler_Get(t *testing.T) {
 	rec := httptest.NewRecorder()
 	r.ServeHTTP(rec, req)
 
-	var uploaded service.FileInfo
+	var uploaded fileInfoResponse
 	json.Unmarshal(rec.Body.Bytes(), &uploaded)
 
 	// Get metadata.
@@ -321,7 +391,7 @@ func TestFileHandler_Get(t *testing.T) {
 		t.Errorf("status = %d, want %d", rec.Code, http.StatusOK)
 	}
 
-	var info service.FileInfo
+	var info fileInfoResponse
 	if err := json.Unmarshal(rec.Body.Bytes(), &info); err != nil {
 		t.Fatalf("unmarshal: %v", err)
 	}
@@ -360,7 +430,7 @@ func TestFileHandler_Download(t *testing.T) {
 	rec := httptest.NewRecorder()
 	r.ServeHTTP(rec, req)
 
-	var uploaded service.FileInfo
+	var uploaded fileInfoResponse
 	json.Unmarshal(rec.Body.Bytes(), &uploaded)
 
 	// Download.
@@ -380,6 +450,42 @@ func TestFileHandler_Download(t *testing.T) {
 	}
 }
 
+func TestFileHandler_DownloadReadErrorAfterResponseStarted(t *testing.T) {
+	r, store := setupFileRouterWithMaxUploadSizeAndStore(t, 0)
+
+	body := &bytes.Buffer{}
+	writer := multipart.NewWriter(body)
+	part, _ := writer.CreateFormFile("file", "download-error.txt")
+	content := []byte("partial response")
+	part.Write(content)
+	writer.Close()
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/files", body)
+	req.Header.Set("Content-Type", writer.FormDataContentType())
+	req.Header.Set("X-User-ID", "user1")
+	rec := httptest.NewRecorder()
+	r.ServeHTTP(rec, req)
+
+	var uploaded fileInfoResponse
+	if err := json.Unmarshal(rec.Body.Bytes(), &uploaded); err != nil {
+		t.Fatalf("unmarshal upload: %v", err)
+	}
+
+	store.failReads = true
+
+	req = httptest.NewRequest(http.MethodGet, "/api/v1/files/"+uploaded.ID+"/content", nil)
+	req.Header.Set("X-User-ID", "user1")
+	rec = httptest.NewRecorder()
+	r.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Errorf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+	if !bytes.Equal(rec.Body.Bytes(), content) {
+		t.Errorf("content = %q, want %q", rec.Body.String(), content)
+	}
+}
+
 func TestFileHandler_Update(t *testing.T) {
 	r := setupFileRouter(t)
 
@@ -396,7 +502,7 @@ func TestFileHandler_Update(t *testing.T) {
 	rec := httptest.NewRecorder()
 	r.ServeHTTP(rec, req)
 
-	var uploaded service.FileInfo
+	var uploaded fileInfoResponse
 	json.Unmarshal(rec.Body.Bytes(), &uploaded)
 
 	// Rename.
@@ -411,7 +517,7 @@ func TestFileHandler_Update(t *testing.T) {
 		t.Errorf("status = %d, want %d; body = %s", rec.Code, http.StatusOK, rec.Body.String())
 	}
 
-	var updated service.FileInfo
+	var updated fileInfoResponse
 	if err := json.Unmarshal(rec.Body.Bytes(), &updated); err != nil {
 		t.Fatalf("unmarshal: %v", err)
 	}
@@ -436,7 +542,7 @@ func TestFileHandler_UpdateNoFields(t *testing.T) {
 	rec := httptest.NewRecorder()
 	r.ServeHTTP(rec, req)
 
-	var uploaded service.FileInfo
+	var uploaded fileInfoResponse
 	json.Unmarshal(rec.Body.Bytes(), &uploaded)
 
 	updateBody, _ := json.Marshal(gin.H{})
@@ -467,7 +573,7 @@ func TestFileHandler_Delete(t *testing.T) {
 	rec := httptest.NewRecorder()
 	r.ServeHTTP(rec, req)
 
-	var uploaded service.FileInfo
+	var uploaded fileInfoResponse
 	json.Unmarshal(rec.Body.Bytes(), &uploaded)
 
 	// Delete.
@@ -507,7 +613,7 @@ func TestFileHandler_ForbiddenAccess(t *testing.T) {
 	rec := httptest.NewRecorder()
 	r.ServeHTTP(rec, req)
 
-	var uploaded service.FileInfo
+	var uploaded fileInfoResponse
 	json.Unmarshal(rec.Body.Bytes(), &uploaded)
 
 	// Try to access as user2.

internal/logging/context.go

@@ -1,4 +1,4 @@
-package log
+package logging
 
 import (
 	"context"

internal/logging/logger.go

@@ -1,4 +1,4 @@
-package log
+package logging
 
 import (
 	"context"

internal/middleware/auth.go

@@ -1,21 +1,28 @@
 package middleware
 
 import (
+	"context"
 	"net/http"
 	"strings"
 
 	"github.com/gin-gonic/gin"
 
 	"github.com/dhao2001/mygo/internal/api"
-	"github.com/dhao2001/mygo/internal/auth"
+	"github.com/dhao2001/mygo/internal/service"
-	"github.com/dhao2001/mygo/internal/repository"
 )
 
-const userIDKey = "user_id"
+const (
+	userIDKey    = "user_id"
+	principalKey = "principal"
+)
+
+type accessAuthenticator interface {
+	AuthenticateAccessToken(ctx context.Context, token string) (*service.Principal, error)
+}
 
 // AuthRequired returns a Gin middleware that validates JWT access tokens.
-// On success, it injects the user ID into the context via c.Get("user_id").
+// On success, it injects the principal and user ID into the context.
-func AuthRequired(jwtSecret []byte) gin.HandlerFunc {
+func AuthRequired(authenticator accessAuthenticator) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		header := c.GetHeader("Authorization")
 		if header == "" {
@@ -31,20 +38,15 @@ func AuthRequired(jwtSecret []byte) gin.HandlerFunc {
 			return
 		}
 
-		claims, err := auth.ParseToken(parts[1], jwtSecret)
+		principal, err := authenticator.AuthenticateAccessToken(c.Request.Context(), parts[1])
 		if err != nil {
-			api.Error(c, http.StatusUnauthorized, "invalid or expired token")
+			api.RespondError(c, err)
 			c.Abort()
 			return
 		}
 
-		if claims.Type != auth.TokenAccess {
+		c.Set(principalKey, *principal)
-			api.Error(c, http.StatusUnauthorized, "invalid token type")
+		c.Set(userIDKey, principal.UserID)
-			c.Abort()
-			return
-		}
-
-		c.Set(userIDKey, claims.UserID)
 		c.Next()
 	}
 }
@@ -65,32 +67,42 @@ func GetUserID(c *gin.Context) string {
 func MustGetUserID(c *gin.Context) string {
 	userID := GetUserID(c)
 	if userID == "" {
-		panic("user_id not found in context — is AuthRequired middleware applied?")
+		panic("user_id not found in context - is AuthRequired middleware applied?")
 	}
 	return userID
 }
 
-// AdminRequired returns a Gin middleware that gates access to admin-only
+// GetPrincipal extracts the authenticated principal injected by AuthRequired.
-// endpoints. It must be applied AFTER AuthRequired. It fetches the user from
+func GetPrincipal(c *gin.Context) (service.Principal, bool) {
-// the repository, and returns 403 if the user is not an admin. Soft-deleted
+	v, ok := c.Get(principalKey)
-// users are not found by FindByID and will receive a 401 response.
+	if !ok || v == nil {
-func AdminRequired(userRepo repository.UserRepository) gin.HandlerFunc {
+		return service.Principal{}, false
+	}
+	principal, ok := v.(service.Principal)
+	return principal, ok
+}
+
+// MustGetPrincipal extracts the authenticated principal injected by AuthRequired.
+func MustGetPrincipal(c *gin.Context) service.Principal {
+	principal, ok := GetPrincipal(c)
+	if !ok {
+		panic("principal not found in context - is AuthRequired middleware applied?")
+	}
+	return principal
+}
+
+// AdminRequired returns a Gin middleware that gates access to admin-only endpoints.
+// It must be applied after AuthRequired.
+func AdminRequired() gin.HandlerFunc {
 	return func(c *gin.Context) {
-		userID := GetUserID(c)
+		principal, ok := GetPrincipal(c)
-		if userID == "" {
+		if !ok {
 			api.Error(c, http.StatusUnauthorized, "missing user context")
 			c.Abort()
 			return
 		}
 
-		user, err := userRepo.FindByID(c.Request.Context(), userID)
+		if !principal.IsAdmin {
-		if err != nil {
-			api.Error(c, http.StatusUnauthorized, "user not found")
-			c.Abort()
-			return
-		}
-
-		if !user.IsAdmin {
 			api.Error(c, http.StatusForbidden, "admin access required")
 			c.Abort()
 			return

internal/middleware/auth_test.go

@@ -7,29 +7,47 @@ import (
 	"net/http/httptest"
 	"strings"
 	"testing"
-	"time"
 
 	"github.com/gin-gonic/gin"
-	"gorm.io/driver/sqlite"
-	"gorm.io/gorm"
 
-	"github.com/dhao2001/mygo/internal/auth"
 	"github.com/dhao2001/mygo/internal/model"
-	"github.com/dhao2001/mygo/internal/repository"
+	"github.com/dhao2001/mygo/internal/service"
 )
 
-func setupTestRouter(secret []byte) *gin.Engine {
+type stubAccessAuthenticator struct {
+	wantToken string
+	principal service.Principal
+	err       error
+	called    bool
+}
+
+func (s *stubAccessAuthenticator) AuthenticateAccessToken(_ context.Context, token string) (*service.Principal, error) {
+	s.called = true
+	if s.wantToken != "" && token != s.wantToken {
+		return nil, model.NewUnauthenticatedError("invalid token")
+	}
+	if s.err != nil {
+		return nil, s.err
+	}
+	return &s.principal, nil
+}
+
+func setupTestRouter(authenticator accessAuthenticator) *gin.Engine {
 	gin.SetMode(gin.TestMode)
 	r := gin.New()
-	r.Use(AuthRequired(secret))
+	r.Use(AuthRequired(authenticator))
 	r.GET("/protected", func(c *gin.Context) {
-		c.JSON(http.StatusOK, gin.H{"user_id": MustGetUserID(c)})
+		c.JSON(http.StatusOK, gin.H{
+			"user_id":  MustGetUserID(c),
+			"is_admin": MustGetPrincipal(c).IsAdmin,
+		})
 	})
 	return r
 }
 
 func TestAuthRequiredNoHeader(t *testing.T) {
-	r := setupTestRouter([]byte("test-secret"))
+	authenticator := &stubAccessAuthenticator{}
+	r := setupTestRouter(authenticator)
 
 	req := httptest.NewRequest(http.MethodGet, "/protected", nil)
 	rec := httptest.NewRecorder()
@@ -38,10 +56,14 @@ func TestAuthRequiredNoHeader(t *testing.T) {
 	if rec.Code != http.StatusUnauthorized {
 		t.Errorf("status = %d, want %d", rec.Code, http.StatusUnauthorized)
 	}
+	if authenticator.called {
+		t.Fatal("authenticator should not be called without a bearer token")
+	}
 }
 
 func TestAuthRequiredInvalidFormat(t *testing.T) {
-	r := setupTestRouter([]byte("test-secret"))
+	authenticator := &stubAccessAuthenticator{}
+	r := setupTestRouter(authenticator)
 
 	req := httptest.NewRequest(http.MethodGet, "/protected", nil)
 	req.Header.Set("Authorization", "invalid")
@@ -51,10 +73,14 @@ func TestAuthRequiredInvalidFormat(t *testing.T) {
 	if rec.Code != http.StatusUnauthorized {
 		t.Errorf("status = %d, want %d", rec.Code, http.StatusUnauthorized)
 	}
+	if authenticator.called {
+		t.Fatal("authenticator should not be called for malformed authorization header")
+	}
 }
 
 func TestAuthRequiredNotBearer(t *testing.T) {
-	r := setupTestRouter([]byte("test-secret"))
+	authenticator := &stubAccessAuthenticator{}
+	r := setupTestRouter(authenticator)
 
 	req := httptest.NewRequest(http.MethodGet, "/protected", nil)
 	req.Header.Set("Authorization", "Basic dXNlcjpwYXNz")
@@ -64,105 +90,51 @@ func TestAuthRequiredNotBearer(t *testing.T) {
 	if rec.Code != http.StatusUnauthorized {
 		t.Errorf("status = %d, want %d", rec.Code, http.StatusUnauthorized)
 	}
+	if authenticator.called {
+		t.Fatal("authenticator should not be called for non-bearer authorization")
+	}
 }
 
-func TestAuthRequiredExpiredToken(t *testing.T) {
+func TestAuthRequiredServiceRejectsToken(t *testing.T) {
-	secret := []byte("test-secret")
+	authenticator := &stubAccessAuthenticator{err: model.NewUnauthenticatedError("invalid or expired token")}
-	token, err := auth.GenerateAccessToken("user-1", secret, -1*time.Minute)
+	r := setupTestRouter(authenticator)
-	if err != nil {
-		t.Fatalf("GenerateAccessToken = %v", err)
-	}
 
-	r := setupTestRouter(secret)
 	req := httptest.NewRequest(http.MethodGet, "/protected", nil)
-	req.Header.Set("Authorization", "Bearer "+token)
+	req.Header.Set("Authorization", "Bearer expired")
 	rec := httptest.NewRecorder()
 	r.ServeHTTP(rec, req)
 
 	if rec.Code != http.StatusUnauthorized {
 		t.Errorf("status = %d, want %d", rec.Code, http.StatusUnauthorized)
 	}
+	if !authenticator.called {
+		t.Fatal("authenticator was not called")
+	}
 }
 
 func TestAuthRequiredValidToken(t *testing.T) {
-	secret := []byte("test-secret")
+	authenticator := &stubAccessAuthenticator{
-	token, err := auth.GenerateAccessToken("user-1", secret, 15*time.Minute)
+		wantToken: "valid",
-	if err != nil {
+		principal: service.Principal{
-		t.Fatalf("GenerateAccessToken = %v", err)
+			UserID:  "user-1",
+			IsAdmin: true,
+		},
 	}
+	r := setupTestRouter(authenticator)
 
-	r := setupTestRouter(secret)
 	req := httptest.NewRequest(http.MethodGet, "/protected", nil)
-	req.Header.Set("Authorization", "Bearer "+token)
+	req.Header.Set("Authorization", "Bearer valid")
 	rec := httptest.NewRecorder()
 	r.ServeHTTP(rec, req)
 
 	if rec.Code != http.StatusOK {
 		t.Errorf("status = %d, want %d", rec.Code, http.StatusOK)
 	}
+	if !strings.Contains(rec.Body.String(), "user-1") {
+		t.Errorf("response body %q does not contain user id", rec.Body.String())
 	}
-
+	if !strings.Contains(rec.Body.String(), "true") {
-func TestAuthRequiredRefreshTokenRejected(t *testing.T) {
+		t.Errorf("response body %q does not contain admin flag", rec.Body.String())
-	secret := []byte("test-secret")
-	token, err := auth.GenerateRefreshToken("user-1", secret, 7*24*time.Hour)
-	if err != nil {
-		t.Fatalf("GenerateRefreshToken = %v", err)
-	}
-
-	r := setupTestRouter(secret)
-	req := httptest.NewRequest(http.MethodGet, "/protected", nil)
-	req.Header.Set("Authorization", "Bearer "+token)
-	rec := httptest.NewRecorder()
-	r.ServeHTTP(rec, req)
-
-	if rec.Code != http.StatusUnauthorized {
-		t.Errorf("status = %d, want %d (refresh token should be rejected)", rec.Code, http.StatusUnauthorized)
-	}
-}
-
-func TestGetUserID(t *testing.T) {
-	secret := []byte("test-secret")
-	token, err := auth.GenerateAccessToken("alice-42", secret, 15*time.Minute)
-	if err != nil {
-		t.Fatalf("GenerateAccessToken = %v", err)
-	}
-
-	r := setupTestRouter(secret)
-	req := httptest.NewRequest(http.MethodGet, "/protected", nil)
-	req.Header.Set("Authorization", "Bearer "+token)
-	rec := httptest.NewRecorder()
-	r.ServeHTTP(rec, req)
-
-	if rec.Code != http.StatusOK {
-		t.Fatalf("status = %d", rec.Code)
-	}
-
-	body := rec.Body.String()
-	if !strings.Contains(body, "alice-42") {
-		t.Errorf("response body %q does not contain user id", body)
-	}
-}
-
-func TestMustGetUserID(t *testing.T) {
-	secret := []byte("test-secret")
-	token, err := auth.GenerateAccessToken("bob-99", secret, 15*time.Minute)
-	if err != nil {
-		t.Fatalf("GenerateAccessToken = %v", err)
-	}
-
-	r := setupTestRouter(secret)
-	req := httptest.NewRequest(http.MethodGet, "/protected", nil)
-	req.Header.Set("Authorization", "Bearer "+token)
-	rec := httptest.NewRecorder()
-	r.ServeHTTP(rec, req)
-
-	if rec.Code != http.StatusOK {
-		t.Fatalf("status = %d", rec.Code)
-	}
-
-	body := rec.Body.String()
-	if !strings.Contains(body, "bob-99") {
-		t.Errorf("response body %q does not contain user id", body)
 	}
 }
 
@@ -170,7 +142,7 @@ func TestMustGetUserIDPanics(t *testing.T) {
 	gin.SetMode(gin.TestMode)
 	r := gin.New()
 	r.GET("/naked", func(c *gin.Context) {
-		MustGetUserID(c) // should panic — no AuthRequired middleware applied
+		MustGetUserID(c)
 	})
 
 	req := httptest.NewRequest(http.MethodGet, "/naked", nil)
@@ -184,75 +156,27 @@ func TestMustGetUserIDPanics(t *testing.T) {
 	r.ServeHTTP(rec, req)
 }
 
-func TestAuthRequiredWrongSecret(t *testing.T) {
-	secret := []byte("test-secret")
-	token, err := auth.GenerateAccessToken("user-1", secret, 15*time.Minute)
-	if err != nil {
-		t.Fatalf("GenerateAccessToken = %v", err)
-	}
-
-	// Use a different secret for the middleware
-	r := setupTestRouter([]byte("different-secret"))
-	req := httptest.NewRequest(http.MethodGet, "/protected", nil)
-	req.Header.Set("Authorization", "Bearer "+token)
-	rec := httptest.NewRecorder()
-	r.ServeHTTP(rec, req)
-
-	if rec.Code != http.StatusUnauthorized {
-		t.Errorf("status = %d, want %d", rec.Code, http.StatusUnauthorized)
-	}
-}
-
-// --- AdminRequired tests ---
-
-// errorBody extracts the error.message field from a JSON response body.
 type errorBody struct {
 	Error struct {
 		Message string `json:"message"`
 	} `json:"error"`
 }
 
-func setupAdminTestDB(t *testing.T) repository.UserRepository {
+func injectPrincipalMiddleware(principal *service.Principal) gin.HandlerFunc {
-	t.Helper()
-
-	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
-	if err != nil {
-		t.Fatalf("open db: %v", err)
-	}
-	if err := db.AutoMigrate(&model.User{}); err != nil {
-		t.Fatalf("migrate: %v", err)
-	}
-
-	return repository.NewUserRepository(db)
-}
-
-// injectUserIDMiddleware simulates AuthRequired by injecting a user_id into the context.
-func injectUserIDMiddleware(userID string) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		c.Set(userIDKey, userID)
+		if principal != nil {
+			c.Set(principalKey, *principal)
+			c.Set(userIDKey, principal.UserID)
+		}
 		c.Next()
 	}
 }
 
 func TestAdminRequired_AdminPasses(t *testing.T) {
-	repo := setupAdminTestDB(t)
-	ctx := context.Background()
-
-	user := &model.User{
-		ID:       "admin-1",
-		Username: "admin",
-		Email:    "admin@example.com",
-		IsAdmin:  true,
-		Status:   model.StatusActive,
-	}
-	if err := repo.Create(ctx, user); err != nil {
-		t.Fatalf("Create = %v", err)
-	}
-
 	gin.SetMode(gin.TestMode)
 	r := gin.New()
-	r.Use(injectUserIDMiddleware("admin-1"))
+	r.Use(injectPrincipalMiddleware(&service.Principal{UserID: "admin-1", IsAdmin: true}))
-	r.Use(AdminRequired(repo))
+	r.Use(AdminRequired())
 	r.GET("/admin", func(c *gin.Context) {
 		c.JSON(http.StatusOK, gin.H{"status": "ok"})
 	})
@@ -267,24 +191,10 @@ func TestAdminRequired_AdminPasses(t *testing.T) {
 }
 
 func TestAdminRequired_NonAdminForbidden(t *testing.T) {
-	repo := setupAdminTestDB(t)
-	ctx := context.Background()
-
-	user := &model.User{
-		ID:       "user-1",
-		Username: "regular",
-		Email:    "regular@example.com",
-		IsAdmin:  false,
-		Status:   model.StatusActive,
-	}
-	if err := repo.Create(ctx, user); err != nil {
-		t.Fatalf("Create = %v", err)
-	}
-
 	gin.SetMode(gin.TestMode)
 	r := gin.New()
-	r.Use(injectUserIDMiddleware("user-1"))
+	r.Use(injectPrincipalMiddleware(&service.Principal{UserID: "user-1", IsAdmin: false}))
-	r.Use(AdminRequired(repo))
+	r.Use(AdminRequired())
 	r.GET("/admin", func(c *gin.Context) {
 		c.JSON(http.StatusOK, gin.H{"status": "ok"})
 	})
@@ -306,49 +216,10 @@ func TestAdminRequired_NonAdminForbidden(t *testing.T) {
 	}
 }
 
-func TestAdminRequired_SoftDeletedAdmin(t *testing.T) {
+func TestAdminRequired_NoPrincipal(t *testing.T) {
-	repo := setupAdminTestDB(t)
-	ctx := context.Background()
-
-	user := &model.User{
-		ID:       "admin-2",
-		Username: "deleted_admin",
-		Email:    "deleted_admin@example.com",
-		IsAdmin:  true,
-		Status:   model.StatusActive,
-	}
-	if err := repo.Create(ctx, user); err != nil {
-		t.Fatalf("Create = %v", err)
-	}
-
-	// Soft-delete the admin user
-	if err := repo.Delete(ctx, "admin-2"); err != nil {
-		t.Fatalf("Delete = %v", err)
-	}
-
 	gin.SetMode(gin.TestMode)
 	r := gin.New()
-	r.Use(injectUserIDMiddleware("admin-2"))
+	r.Use(AdminRequired())
-	r.Use(AdminRequired(repo))
-	r.GET("/admin", func(c *gin.Context) {
-		c.JSON(http.StatusOK, gin.H{"status": "ok"})
-	})
-
-	req := httptest.NewRequest(http.MethodGet, "/admin", nil)
-	rec := httptest.NewRecorder()
-	r.ServeHTTP(rec, req)
-
-	if rec.Code != http.StatusUnauthorized {
-		t.Errorf("status = %d, want %d", rec.Code, http.StatusUnauthorized)
-	}
-}
-
-func TestAdminRequired_NoUserID(t *testing.T) {
-	repo := setupAdminTestDB(t)
-
-	gin.SetMode(gin.TestMode)
-	r := gin.New()
-	r.Use(AdminRequired(repo))
 	r.GET("/admin", func(c *gin.Context) {
 		c.JSON(http.StatusOK, gin.H{"status": "ok"})
 	})

internal/middleware/requestid.go

@@ -4,7 +4,7 @@ import (
 	"github.com/gin-gonic/gin"
 	"github.com/google/uuid"
 
-	mygolog "github.com/dhao2001/mygo/internal/log"
+	"github.com/dhao2001/mygo/internal/logging"
 )
 
 // RequestID returns a Gin middleware that ensures every request has a
@@ -19,7 +19,7 @@ func RequestID() gin.HandlerFunc {
 		}
 
 		// Inject into Go context for slog.*Context calls.
-		c.Request = c.Request.WithContext(mygolog.WithRequestID(c.Request.Context(), reqID))
+		c.Request = c.Request.WithContext(logging.WithRequestID(c.Request.Context(), reqID))
 
 		// Also set in Gin context for direct access.
 		c.Set("req_id", reqID)

internal/model/credential.go

@@ -8,11 +8,11 @@ import (
 // The primary password is stored on the User model; additional credentials
 // (app passkeys, WebAuthn, OAuth) are stored here with a type discriminator.
 type Credential struct {
-	ID         string     `gorm:"primaryKey;type:varchar(36)" json:"id"`
+	ID         string `gorm:"primaryKey;type:varchar(36)"`
-	UserID     string     `gorm:"index;type:varchar(36);not null" json:"user_id"`
+	UserID     string `gorm:"index;type:varchar(36);not null"`
-	Type       string     `gorm:"index;type:varchar(32);not null" json:"type"`
+	Type       string `gorm:"index;type:varchar(32);not null"`
-	Label      string     `gorm:"type:varchar(128)" json:"label"`
+	Label      string `gorm:"type:varchar(128)"`
 	SecretHash string `gorm:"uniqueIndex;type:varchar(255);not null" json:"-"`
-	LastUsedAt *time.Time `json:"last_used_at"`
+	LastUsedAt *time.Time
-	CreatedAt  time.Time  `json:"created_at"`
+	CreatedAt  time.Time
 }

internal/model/errors.go

@@ -3,7 +3,6 @@ package model
 import (
 	"errors"
 	"fmt"
-	"net/http"
 )
 
 var (
@@ -11,25 +10,79 @@ var (
 	ErrDuplicate      = errors.New("resource already exists")
 	ErrUnauthorized   = errors.New("unauthorized")
 	ErrForbidden      = errors.New("forbidden")
+	ErrUploadTooLarge = errors.New("upload exceeds maximum size")
 )
 
-// AppError is a service-layer error that carries an HTTP status, a user-safe
+// ErrorKind classifies domain errors without tying them to a transport.
-// message, and an optional internal cause for logging. Handlers unpack it
+type ErrorKind string
-// transparently via api.RespondError.
+
+// Protocol-neutral error kinds.
+const (
+	KindInvalidArgument  ErrorKind = "invalid_argument"
+	KindUnauthenticated  ErrorKind = "unauthenticated"
+	KindPermissionDenied ErrorKind = "permission_denied"
+	KindNotFound         ErrorKind = "not_found"
+	KindConflict         ErrorKind = "conflict"
+	KindPayloadTooLarge  ErrorKind = "payload_too_large"
+	KindInternal         ErrorKind = "internal"
+)
+
+// AppError is a service-layer error that carries a protocol-neutral kind, a
+// user-safe message, and an optional internal cause for logging.
 type AppError struct {
-	Status  int    // HTTP status code
+	Kind    ErrorKind
-	Message string // safe for API response
+	Message string
-	Err     error  // internal cause (nil = user-caused, skip logging)
+	Err     error
 }
 
 func (e *AppError) Error() string { return e.Message }
 func (e *AppError) Unwrap() error { return e.Err }
 
-// NewInternalError creates a 500 AppError with a wrapped internal cause.
+// NewInvalidArgumentError creates an invalid-argument AppError.
+func NewInvalidArgumentError(message string) *AppError {
+	return &AppError{Kind: KindInvalidArgument, Message: message}
+}
+
+// NewBadRequestError creates an invalid-argument AppError.
+func NewBadRequestError(message string) *AppError {
+	return NewInvalidArgumentError(message)
+}
+
+// NewUnauthenticatedError creates an unauthenticated AppError.
+func NewUnauthenticatedError(message string) *AppError {
+	return &AppError{Kind: KindUnauthenticated, Message: message}
+}
+
+// NewConflictError creates a conflict AppError.
+func NewConflictError(message string) *AppError {
+	return &AppError{Kind: KindConflict, Message: message}
+}
+
+// NewNotFoundError creates a not-found AppError.
+func NewNotFoundError(message string, cause error) *AppError {
+	return &AppError{Kind: KindNotFound, Message: message, Err: cause}
+}
+
+// NewPermissionDeniedError creates a permission-denied AppError.
+func NewPermissionDeniedError(message string, cause error) *AppError {
+	return &AppError{Kind: KindPermissionDenied, Message: message, Err: cause}
+}
+
+// NewForbiddenError creates a permission-denied AppError.
+func NewForbiddenError(message string, cause error) *AppError {
+	return NewPermissionDeniedError(message, cause)
+}
+
+// NewPayloadTooLargeError creates a payload-too-large AppError.
+func NewPayloadTooLargeError(message string, cause error) *AppError {
+	return &AppError{Kind: KindPayloadTooLarge, Message: message, Err: cause}
+}
+
+// NewInternalError creates an internal AppError with a wrapped internal cause.
 // msg describes the operation that failed; cause is the underlying error.
 func NewInternalError(msg string, cause error) *AppError {
 	return &AppError{
-		Status:  http.StatusInternalServerError,
+		Kind:    KindInternal,
 		Message: "internal server error",
 		Err:     fmt.Errorf("%s: %w", msg, cause),
 	}

internal/model/errors_test.go

@@ -0,0 +1,79 @@
+package model
+
+import (
+	"errors"
+	"testing"
+)
+
+func TestAppErrorConstructors(t *testing.T) {
+	cause := errors.New("database offline")
+
+	tests := []struct {
+		name    string
+		err     *AppError
+		kind    ErrorKind
+		message string
+		cause   error
+	}{
+		{
+			name:    "invalid argument",
+			err:     NewInvalidArgumentError("bad input"),
+			kind:    KindInvalidArgument,
+			message: "bad input",
+		},
+		{
+			name:    "unauthenticated",
+			err:     NewUnauthenticatedError("invalid token"),
+			kind:    KindUnauthenticated,
+			message: "invalid token",
+		},
+		{
+			name:    "permission denied",
+			err:     NewPermissionDeniedError("access denied", ErrForbidden),
+			kind:    KindPermissionDenied,
+			message: "access denied",
+			cause:   ErrForbidden,
+		},
+		{
+			name:    "not found",
+			err:     NewNotFoundError("missing", ErrNotFound),
+			kind:    KindNotFound,
+			message: "missing",
+			cause:   ErrNotFound,
+		},
+		{
+			name:    "conflict",
+			err:     NewConflictError("duplicate"),
+			kind:    KindConflict,
+			message: "duplicate",
+		},
+		{
+			name:    "payload too large",
+			err:     NewPayloadTooLargeError("too large", ErrUploadTooLarge),
+			kind:    KindPayloadTooLarge,
+			message: "too large",
+			cause:   ErrUploadTooLarge,
+		},
+		{
+			name:    "internal",
+			err:     NewInternalError("load record", cause),
+			kind:    KindInternal,
+			message: "internal server error",
+			cause:   cause,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.err.Kind != tt.kind {
+				t.Fatalf("Kind = %q, want %q", tt.err.Kind, tt.kind)
+			}
+			if tt.err.Message != tt.message {
+				t.Fatalf("Message = %q, want %q", tt.err.Message, tt.message)
+			}
+			if tt.cause != nil && !errors.Is(tt.err, tt.cause) {
+				t.Fatalf("errors.Is(%v, %v) = false", tt.err, tt.cause)
+			}
+		})
+	}
+}

internal/model/file.go

@@ -9,16 +9,16 @@ const StatusUserDeleted = "user_deleted"
 
 // File represents a file or directory entry in the virtual filesystem.
 type File struct {
-	ID          string    `gorm:"primaryKey;type:varchar(36)" json:"id"`
+	ID          string  `gorm:"primaryKey;type:varchar(36)"`
-	UserID      string    `gorm:"index;uniqueIndex:idx_user_parent_name,priority:1;type:varchar(36);not null" json:"user_id"`
+	UserID      string  `gorm:"index;uniqueIndex:idx_user_parent_name,priority:1;type:varchar(36);not null"`
-	ParentID    *string   `gorm:"index;uniqueIndex:idx_user_parent_name,priority:2;type:varchar(36)" json:"parent_id"`
+	ParentID    *string `gorm:"index;uniqueIndex:idx_user_parent_name,priority:2;type:varchar(36)"`
-	Name        string    `gorm:"type:varchar(255);not null;uniqueIndex:idx_user_parent_name,priority:3" json:"name"`
+	Name        string  `gorm:"type:varchar(255);not null;uniqueIndex:idx_user_parent_name,priority:3"`
-	Size        int64     `gorm:"default:0" json:"size"`
+	Size        int64   `gorm:"default:0"`
-	MimeType    string    `gorm:"type:varchar(127)" json:"mime_type"`
+	MimeType    string  `gorm:"type:varchar(127)"`
-	StoragePath string    `gorm:"type:varchar(512)" json:"storage_path"`
+	StoragePath string  `gorm:"type:varchar(512)" json:"-"`
 	Hash        string  `gorm:"type:varchar(64)" json:"-"`
 	Status      string  `gorm:"type:varchar(32);not null;default:active;index" json:"-"`
-	IsDir       bool      `gorm:"default:false" json:"is_dir"`
+	IsDir       bool    `gorm:"default:false"`
-	CreatedAt   time.Time `json:"created_at"`
+	CreatedAt   time.Time
-	UpdatedAt   time.Time `json:"updated_at"`
+	UpdatedAt   time.Time
 }

internal/model/file_test.go

@@ -6,7 +6,7 @@ import (
 	"time"
 )
 
-func TestFile_StatusExcludedFromJSON(t *testing.T) {
+func TestFileJSONOmitsInternalFields(t *testing.T) {
 	f := &File{
 		ID:          "1",
 		UserID:      "u1",
@@ -14,6 +14,8 @@ func TestFile_StatusExcludedFromJSON(t *testing.T) {
 		Name:        "test.txt",
 		Size:        100,
 		MimeType:    "text/plain",
+		StoragePath: "users/u1/files/1",
+		Hash:        "abc123",
 		Status:      StatusActive,
 		IsDir:       false,
 		CreatedAt:   time.Now(),
@@ -30,13 +32,11 @@ func TestFile_StatusExcludedFromJSON(t *testing.T) {
 		t.Fatalf("json.Unmarshal: %v", err)
 	}
 
-	if _, ok := result["status"]; ok {
+	assertJSONKeysAbsent(t, result,
-		t.Errorf("Status field should be excluded from JSON (json:\"-\"), but it appeared in output")
+		"StoragePath", "storage_path",
-	}
+		"Hash", "hash",
-
+		"Status", "status",
-	if _, ok := result["hash"]; ok {
+	)
-		t.Errorf("Hash field should be excluded from JSON (json:\"-\"), but it appeared in output")
-	}
 }
 
 func TestStatusConstants(t *testing.T) {

internal/model/session.go

@@ -6,9 +6,9 @@ import (
 
 // Session stores a refresh token for a user session.
 type Session struct {
-	ID        string    `gorm:"primaryKey;type:varchar(36)" json:"id"`
+	ID        string    `gorm:"primaryKey;type:varchar(36)"`
-	UserID    string    `gorm:"index;type:varchar(36);not null" json:"user_id"`
+	UserID    string    `gorm:"index;type:varchar(36);not null"`
 	TokenHash string    `gorm:"uniqueIndex;type:varchar(255);not null" json:"-"`
-	ExpiresAt time.Time `gorm:"not null" json:"expires_at"`
+	ExpiresAt time.Time `gorm:"not null"`
-	CreatedAt time.Time `json:"created_at"`
+	CreatedAt time.Time
 }

internal/model/user.go

@@ -6,14 +6,14 @@ import (
 
 // User represents a registered account.
 type User struct {
-	ID           string    `gorm:"primaryKey;type:varchar(36)" json:"id"`
+	ID           string `gorm:"primaryKey;type:varchar(36)"`
-	Username     string    `gorm:"uniqueIndex;type:varchar(64);not null" json:"username"`
+	Username     string `gorm:"uniqueIndex;type:varchar(64);not null"`
-	Email        string    `gorm:"uniqueIndex;type:varchar(255);not null" json:"email"`
+	Email        string `gorm:"uniqueIndex;type:varchar(255);not null"`
 	PasswordHash string `gorm:"type:varchar(255);not null" json:"-"`
-	IsAdmin      bool      `gorm:"default:false" json:"is_admin"`
+	IsAdmin      bool   `gorm:"default:false"`
-	Status       string    `gorm:"type:varchar(32);not null;default:active;index" json:"-"`
+	Status       string `gorm:"type:varchar(32);not null;default:active;index"`
-	CreatedAt    time.Time `json:"created_at"`
+	CreatedAt    time.Time
-	UpdatedAt    time.Time `json:"updated_at"`
+	UpdatedAt    time.Time
 }
 
 // User status constants.

internal/model/user_test.go

@@ -5,11 +5,12 @@ import (
 	"testing"
 )
 
-func TestUserJSONOmitsStatusField(t *testing.T) {
+func TestUserJSONOmitsPasswordHash(t *testing.T) {
 	u := User{
 		ID:           "user-1",
 		Username:     "alice",
 		Email:        "alice@example.com",
+		PasswordHash: "hash-secret",
 		Status:       StatusActive,
 	}
 
@@ -23,7 +24,57 @@ func TestUserJSONOmitsStatusField(t *testing.T) {
 		t.Fatalf("json.Unmarshal: %v", err)
 	}
 
-	if _, ok := m["status"]; ok {
+	assertJSONKeysAbsent(t, m, "PasswordHash", "password_hash")
-		t.Error("Status field should not appear in JSON output")
+}
+
+func TestSessionJSONOmitsTokenHash(t *testing.T) {
+	s := Session{
+		ID:        "session-1",
+		UserID:    "user-1",
+		TokenHash: "token-hash-secret",
+	}
+
+	raw, err := json.Marshal(s)
+	if err != nil {
+		t.Fatalf("json.Marshal: %v", err)
+	}
+
+	var m map[string]interface{}
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatalf("json.Unmarshal: %v", err)
+	}
+
+	assertJSONKeysAbsent(t, m, "TokenHash", "token_hash")
+}
+
+func TestCredentialJSONOmitsSecretHash(t *testing.T) {
+	c := Credential{
+		ID:         "credential-1",
+		UserID:     "user-1",
+		Type:       "app_passkey",
+		Label:      "Phone",
+		SecretHash: "credential-secret",
+	}
+
+	raw, err := json.Marshal(c)
+	if err != nil {
+		t.Fatalf("json.Marshal: %v", err)
+	}
+
+	var m map[string]interface{}
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatalf("json.Unmarshal: %v", err)
+	}
+
+	assertJSONKeysAbsent(t, m, "SecretHash", "secret_hash")
+}
+
+func assertJSONKeysAbsent(t *testing.T, m map[string]interface{}, keys ...string) {
+	t.Helper()
+
+	for _, key := range keys {
+		if _, ok := m[key]; ok {
+			t.Errorf("%s field should not appear in JSON output", key)
+		}
 	}
 }

internal/server/routes_protected.go

@@ -9,12 +9,11 @@ import (
 )
 
 func setupProtectedRoutes(rg *gin.RouterGroup, webApp *app.WebApp) {
-	jwtSecret := []byte(webApp.Config.JWT.Secret)
 	accountHandler := handler.NewAccountHandler(webApp.AuthService)
 	fileHandler := handler.NewFileHandler(webApp.FileService)
-	adminHandler := handler.NewAdminHandler(webApp.UserRepo)
+	adminHandler := handler.NewAdminHandler(webApp.AdminService)
 
-	rg.Use(middleware.AuthRequired(jwtSecret))
+	rg.Use(middleware.AuthRequired(webApp.AuthService))
 
 	account := rg.Group("/account")
 	{
@@ -39,7 +38,7 @@ func setupProtectedRoutes(rg *gin.RouterGroup, webApp *app.WebApp) {
 	}
 
 	admin := rg.Group("/admin")
-	admin.Use(middleware.AdminRequired(webApp.UserRepo))
+	admin.Use(middleware.AdminRequired())
 	{
 		admin.GET("/users", adminHandler.ListUsers)
 		admin.GET("/users/:id", adminHandler.GetUser)

internal/server/server_test.go

@@ -25,7 +25,7 @@ func TestVersionRoute(t *testing.T) {
 		},
 	}
 	authService := service.NewAuthService(nil, nil, nil, nil, 15*time.Minute, 7*24*time.Hour)
-	webApp := app.NewWebApp(cfg, nil, nil, nil, nil, nil, authService, nil, nil)
+	webApp := app.NewWebApp(cfg, nil, nil, nil, nil, nil, authService, nil, nil, nil)
 	router := NewRouter(webApp)
 
 	req := httptest.NewRequest(http.MethodGet, "/api/v1/version", nil)
@@ -84,6 +84,7 @@ func TestAdminRoutes(t *testing.T) {
 	refreshTTL := 168 * time.Hour
 
 	authService := service.NewAuthService(userRepo, sessionRepo, credentialRepo, jwtSecret, accessTTL, refreshTTL)
+	adminService := service.NewAdminService(userRepo)
 
 	cfg := &config.Config{
 		JWT: config.JWTConfig{
@@ -93,7 +94,7 @@ func TestAdminRoutes(t *testing.T) {
 		},
 	}
 
-	webApp := app.NewWebApp(cfg, db, userRepo, sessionRepo, nil, credentialRepo, authService, nil, nil)
+	webApp := app.NewWebApp(cfg, db, userRepo, sessionRepo, nil, credentialRepo, authService, adminService, nil, nil)
 	router := NewRouter(webApp)
 
 	// Helper: register a user via POST /api/v1/auth/register and return the user ID.

internal/service/admin.go

@@ -0,0 +1,51 @@
+package service
+
+import (
+	"context"
+	"errors"
+
+	"github.com/dhao2001/mygo/internal/model"
+	"github.com/dhao2001/mygo/internal/repository"
+)
+
+// AdminService handles administrator user-management operations.
+type AdminService struct {
+	userRepo repository.UserRepository
+}
+
+// NewAdminService creates an AdminService.
+func NewAdminService(userRepo repository.UserRepository) *AdminService {
+	return &AdminService{userRepo: userRepo}
+}
+
+// GetUser returns a user by ID, including deleted users.
+func (s *AdminService) GetUser(ctx context.Context, id string) (*model.User, error) {
+	user, err := s.userRepo.FindByIDIncludeDeleted(ctx, id)
+	if err != nil {
+		if errors.Is(err, model.ErrNotFound) {
+			return nil, model.NewNotFoundError("user not found", model.ErrNotFound)
+		}
+		return nil, model.NewInternalError("find admin user", err)
+	}
+	return user, nil
+}
+
+// ListUsers returns all users, including deleted users, with pagination.
+func (s *AdminService) ListUsers(ctx context.Context, offset, limit int) ([]model.User, int64, error) {
+	users, total, err := s.userRepo.ListIncludeDeleted(ctx, offset, limit)
+	if err != nil {
+		return nil, 0, model.NewInternalError("list admin users", err)
+	}
+	return users, total, nil
+}
+
+// DeleteUser soft-deletes a user.
+func (s *AdminService) DeleteUser(ctx context.Context, id string) error {
+	if _, err := s.GetUser(ctx, id); err != nil {
+		return err
+	}
+	if err := s.userRepo.Delete(ctx, id); err != nil {
+		return model.NewInternalError("delete admin user", err)
+	}
+	return nil
+}

internal/service/admin_test.go

@@ -0,0 +1,69 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	"github.com/dhao2001/mygo/internal/model"
+	"github.com/dhao2001/mygo/internal/repository"
+)
+
+func setupAdminService(t *testing.T) (*AdminService, repository.UserRepository) {
+	t.Helper()
+
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	if err := db.AutoMigrate(&model.User{}); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+
+	userRepo := repository.NewUserRepository(db)
+	return NewAdminService(userRepo), userRepo
+}
+
+func TestAdminServiceGetUserMissingReturnsNotFound(t *testing.T) {
+	svc, _ := setupAdminService(t)
+
+	_, err := svc.GetUser(context.Background(), "missing")
+	var ae *model.AppError
+	if !errors.As(err, &ae) {
+		t.Fatalf("expected AppError, got %T: %v", err, err)
+	}
+	if ae.Kind != model.KindNotFound {
+		t.Fatalf("kind = %q, want %q", ae.Kind, model.KindNotFound)
+	}
+}
+
+func TestAdminServiceListIncludesDeletedUsers(t *testing.T) {
+	svc, repo := setupAdminService(t)
+	ctx := context.Background()
+
+	active := &model.User{ID: "active-1", Username: "active", Email: "active@example.com", Status: model.StatusActive}
+	deleted := &model.User{ID: "deleted-1", Username: "deleted", Email: "deleted@example.com", Status: model.StatusActive}
+	if err := repo.Create(ctx, active); err != nil {
+		t.Fatalf("create active: %v", err)
+	}
+	if err := repo.Create(ctx, deleted); err != nil {
+		t.Fatalf("create deleted: %v", err)
+	}
+	if err := repo.Delete(ctx, deleted.ID); err != nil {
+		t.Fatalf("delete user: %v", err)
+	}
+
+	users, total, err := svc.ListUsers(ctx, 0, 10)
+	if err != nil {
+		t.Fatalf("ListUsers = %v", err)
+	}
+	if total != 2 {
+		t.Fatalf("total = %d, want 2", total)
+	}
+	if len(users) != 2 {
+		t.Fatalf("len(users) = %d, want 2", len(users))
+	}
+}

internal/service/auth.go

@@ -3,7 +3,6 @@ package service
 import (
 	"context"
 	"errors"
-	"net/http"
 	"strings"
 	"time"
 
@@ -16,15 +15,21 @@ import (
 
 // TokenPair contains the access and refresh tokens returned after authentication.
 type TokenPair struct {
-	AccessToken  string `json:"access_token"`
+	AccessToken  string
-	RefreshToken string `json:"refresh_token"`
+	RefreshToken string
 }
 
 // CreatedPasskey contains the raw token for a newly created app passkey.
 type CreatedPasskey struct {
-	ID    string `json:"id"`
+	ID    string
-	Raw   string `json:"raw"`
+	Raw   string
-	Label string `json:"label"`
+	Label string
+}
+
+// Principal is the authenticated user identity used by transport layers.
+type Principal struct {
+	UserID  string
+	IsAdmin bool
 }
 
 // AuthService handles user authentication and session management.
@@ -59,7 +64,7 @@ func NewAuthService(
 // Register creates a new user account.
 func (s *AuthService) Register(ctx context.Context, username, email, password string) (*model.User, error) {
 	if username == "" || email == "" || password == "" {
-		return nil, &model.AppError{Status: http.StatusBadRequest, Message: "username, email, and password are required"}
+		return nil, model.NewInvalidArgumentError("username, email, and password are required")
 	}
 
 	passwordHash, err := auth.HashPassword(password)
@@ -77,7 +82,7 @@ func (s *AuthService) Register(ctx context.Context, username, email, password st
 
 	if err := s.userRepo.Create(ctx, user); err != nil {
 		if errors.Is(err, model.ErrDuplicate) {
-			return nil, &model.AppError{Status: http.StatusConflict, Message: "username or email already exists"}
+			return nil, model.NewConflictError("username or email already exists")
 		}
 		return nil, model.NewInternalError("create user", err)
 	}
@@ -90,17 +95,17 @@ func (s *AuthService) Login(ctx context.Context, email, password string) (*Token
 	user, err := s.userRepo.FindByEmail(ctx, email)
 	if err != nil {
 		if errors.Is(err, model.ErrNotFound) {
-			return nil, &model.AppError{Status: http.StatusUnauthorized, Message: "invalid email or password"}
+			return nil, model.NewUnauthenticatedError("invalid email or password")
 		}
 		return nil, model.NewInternalError("find user", err)
 	}
 
 	if user.Status != model.StatusActive {
-		return nil, &model.AppError{Status: http.StatusUnauthorized, Message: "invalid email or password"}
+		return nil, model.NewUnauthenticatedError("invalid email or password")
 	}
 
 	if err := auth.VerifyPassword(user.PasswordHash, password); err != nil {
-		return nil, &model.AppError{Status: http.StatusUnauthorized, Message: "invalid email or password"}
+		return nil, model.NewUnauthenticatedError("invalid email or password")
 	}
 
 	return s.issueTokens(ctx, user.ID)
@@ -111,32 +116,32 @@ func (s *AuthService) Login(ctx context.Context, email, password string) (*Token
 func (s *AuthService) Refresh(ctx context.Context, refreshTokenStr string) (*TokenPair, error) {
 	claims, err := auth.ParseToken(refreshTokenStr, s.jwtSecret)
 	if err != nil {
-		return nil, &model.AppError{Status: http.StatusUnauthorized, Message: "invalid token"}
+		return nil, model.NewUnauthenticatedError("invalid token")
 	}
 
 	if claims.Type != auth.TokenRefresh {
-		return nil, &model.AppError{Status: http.StatusUnauthorized, Message: "invalid token"}
+		return nil, model.NewUnauthenticatedError("invalid token")
 	}
 
 	tokenHash := auth.HashToken(refreshTokenStr)
 	session, err := s.sessionRepo.FindByTokenHash(ctx, tokenHash)
 	if err != nil {
 		if errors.Is(err, model.ErrNotFound) {
-			return nil, &model.AppError{Status: http.StatusUnauthorized, Message: "invalid token"}
+			return nil, model.NewUnauthenticatedError("invalid token")
 		}
 		return nil, model.NewInternalError("find session", err)
 	}
 
 	if session.UserID != claims.UserID {
-		return nil, &model.AppError{Status: http.StatusUnauthorized, Message: "invalid token"}
+		return nil, model.NewUnauthenticatedError("invalid token")
 	}
 
 	user, err := s.userRepo.FindByID(ctx, claims.UserID)
 	if err != nil {
-		return nil, &model.AppError{Status: http.StatusUnauthorized, Message: "invalid token"}
+		return nil, model.NewUnauthenticatedError("invalid token")
 	}
 	if user.Status != model.StatusActive {
-		return nil, &model.AppError{Status: http.StatusUnauthorized, Message: "invalid token"}
+		return nil, model.NewUnauthenticatedError("invalid token")
 	}
 
 	if err := s.sessionRepo.Delete(ctx, session.ID); err != nil {
@@ -157,7 +162,10 @@ func (s *AuthService) Logout(ctx context.Context, refreshTokenStr string) error
 		return model.NewInternalError("find session", err)
 	}
 
-	return s.sessionRepo.Delete(ctx, session.ID)
+	if err := s.sessionRepo.Delete(ctx, session.ID); err != nil {
+		return model.NewInternalError("delete session", err)
+	}
+	return nil
 }
 
 // CreatePasskey creates a new app passkey for the authenticated user.
@@ -189,14 +197,14 @@ func (s *AuthService) CreatePasskey(ctx context.Context, userID, label string) (
 // LoginWithPasskey authenticates a user using an app passkey token.
 func (s *AuthService) LoginWithPasskey(ctx context.Context, tokenStr string) (*TokenPair, error) {
 	if !strings.HasPrefix(tokenStr, "mygo_") {
-		return nil, &model.AppError{Status: http.StatusUnauthorized, Message: "invalid passkey format"}
+		return nil, model.NewUnauthenticatedError("invalid passkey format")
 	}
 
 	tokenHash := auth.HashToken(tokenStr)
 	cred, err := s.credentialRepo.FindByHash(ctx, tokenHash)
 	if err != nil {
 		if errors.Is(err, model.ErrNotFound) {
-			return nil, &model.AppError{Status: http.StatusUnauthorized, Message: "invalid passkey"}
+			return nil, model.NewUnauthenticatedError("invalid passkey")
 		}
 		return nil, model.NewInternalError("find credential", err)
 	}
@@ -206,11 +214,11 @@ func (s *AuthService) LoginWithPasskey(ctx context.Context, tokenStr string) (*T
 		return nil, model.NewInternalError("find user", err)
 	}
 	if user.Status != model.StatusActive {
-		return nil, &model.AppError{Status: http.StatusUnauthorized, Message: "invalid passkey"}
+		return nil, model.NewUnauthenticatedError("invalid passkey")
 	}
 
 	if cred.Type != "app_passkey" {
-		return nil, &model.AppError{Status: http.StatusUnauthorized, Message: "invalid credential type"}
+		return nil, model.NewUnauthenticatedError("invalid credential type")
 	}
 
 	if err := s.credentialRepo.UpdateLastUsed(ctx, cred.ID); err != nil {
@@ -222,7 +230,11 @@ func (s *AuthService) LoginWithPasskey(ctx context.Context, tokenStr string) (*T
 
 // ListPasskeys returns all app passkeys for a user.
 func (s *AuthService) ListPasskeys(ctx context.Context, userID string) ([]model.Credential, error) {
-	return s.credentialRepo.FindByUserIDAndType(ctx, userID, "app_passkey")
+	creds, err := s.credentialRepo.FindByUserIDAndType(ctx, userID, "app_passkey")
+	if err != nil {
+		return nil, model.NewInternalError("list passkeys", err)
+	}
+	return creds, nil
 }
 
 // RevokePasskey deletes an app passkey owned by the user.
@@ -230,16 +242,47 @@ func (s *AuthService) RevokePasskey(ctx context.Context, userID, credID string)
 	cred, err := s.credentialRepo.FindByID(ctx, credID)
 	if err != nil {
 		if errors.Is(err, model.ErrNotFound) {
-			return &model.AppError{Status: http.StatusNotFound, Message: "passkey not found", Err: model.ErrNotFound}
+			return model.NewNotFoundError("passkey not found", model.ErrNotFound)
 		}
 		return model.NewInternalError("find credential", err)
 	}
 
 	if cred.UserID != userID {
-		return &model.AppError{Status: http.StatusForbidden, Message: "access denied", Err: model.ErrForbidden}
+		return model.NewPermissionDeniedError("access denied", model.ErrForbidden)
 	}
 
-	return s.credentialRepo.Delete(ctx, credID)
+	if err := s.credentialRepo.Delete(ctx, credID); err != nil {
+		return model.NewInternalError("delete credential", err)
+	}
+	return nil
+}
+
+// AuthenticateAccessToken validates an access token and returns the active user principal.
+func (s *AuthService) AuthenticateAccessToken(ctx context.Context, accessTokenStr string) (*Principal, error) {
+	claims, err := auth.ParseToken(accessTokenStr, s.jwtSecret)
+	if err != nil {
+		return nil, model.NewUnauthenticatedError("invalid or expired token")
+	}
+
+	if claims.Type != auth.TokenAccess {
+		return nil, model.NewUnauthenticatedError("invalid token type")
+	}
+
+	user, err := s.userRepo.FindByID(ctx, claims.UserID)
+	if err != nil {
+		if errors.Is(err, model.ErrNotFound) {
+			return nil, model.NewUnauthenticatedError("user not found")
+		}
+		return nil, model.NewInternalError("find access token user", err)
+	}
+	if user.Status != model.StatusActive {
+		return nil, model.NewUnauthenticatedError("user not found")
+	}
+
+	return &Principal{
+		UserID:  user.ID,
+		IsAdmin: user.IsAdmin,
+	}, nil
 }
 
 func (s *AuthService) issueTokens(ctx context.Context, userID string) (*TokenPair, error) {

internal/service/auth_test.go

@@ -3,7 +3,6 @@ package service
 import (
 	"context"
 	"errors"
-	"net/http"
 	"testing"
 	"time"
 
@@ -347,8 +346,8 @@ func TestAuthService_RevokePasskeyNotOwner(t *testing.T) {
 
 	err = svc.RevokePasskey(ctx, claimsBob.UserID, pk.ID)
 	var ae *model.AppError
-	if !errors.As(err, &ae) || ae.Status != http.StatusForbidden {
+	if !errors.As(err, &ae) || ae.Kind != model.KindPermissionDenied {
-		t.Fatalf("expected AppError 403 Forbidden, got %v", err)
+		t.Fatalf("expected permission denied AppError, got %v", err)
 	}
 }
 
@@ -434,8 +433,8 @@ func TestAuthService_LoginDisabledUser(t *testing.T) {
 	if !errors.As(err, &ae) {
 		t.Fatalf("expected AppError, got %T: %v", err, err)
 	}
-	if ae.Status != http.StatusUnauthorized {
+	if ae.Kind != model.KindUnauthenticated {
-		t.Errorf("status = %d, want %d", ae.Status, http.StatusUnauthorized)
+		t.Errorf("kind = %q, want %q", ae.Kind, model.KindUnauthenticated)
 	}
 	if ae.Message != "invalid email or password" {
 		t.Errorf("message = %q, want %q", ae.Message, "invalid email or password")
@@ -519,8 +518,8 @@ func TestAuthService_LoginWithPasskeyDisabledUser(t *testing.T) {
 	if !errors.As(err, &ae) {
 		t.Fatalf("expected AppError, got %T: %v", err, err)
 	}
-	if ae.Status != http.StatusUnauthorized {
+	if ae.Kind != model.KindUnauthenticated {
-		t.Errorf("status = %d, want %d", ae.Status, http.StatusUnauthorized)
+		t.Errorf("kind = %q, want %q", ae.Kind, model.KindUnauthenticated)
 	}
 	if ae.Message != "invalid passkey" {
 		t.Errorf("message = %q, want %q", ae.Message, "invalid passkey")
@@ -554,10 +553,68 @@ func TestAuthService_RefreshDisabledUser(t *testing.T) {
 	if !errors.As(err, &ae) {
 		t.Fatalf("expected AppError, got %T: %v", err, err)
 	}
-	if ae.Status != http.StatusUnauthorized {
+	if ae.Kind != model.KindUnauthenticated {
-		t.Errorf("status = %d, want %d", ae.Status, http.StatusUnauthorized)
+		t.Errorf("kind = %q, want %q", ae.Kind, model.KindUnauthenticated)
 	}
 	if ae.Message != "invalid token" {
 		t.Errorf("message = %q, want %q", ae.Message, "invalid token")
 	}
 }
+
+func TestAuthService_AuthenticateAccessToken(t *testing.T) {
+	svc, userRepo := setupAuthServiceWithRepos(t)
+	ctx := context.Background()
+
+	user, err := svc.Register(ctx, "alice", "alice@example.com", "password123")
+	if err != nil {
+		t.Fatalf("Register = %v", err)
+	}
+	user.IsAdmin = true
+	if err := userRepo.Update(ctx, user); err != nil {
+		t.Fatalf("promote user: %v", err)
+	}
+
+	pair, err := svc.Login(ctx, "alice@example.com", "password123")
+	if err != nil {
+		t.Fatalf("Login = %v", err)
+	}
+
+	principal, err := svc.AuthenticateAccessToken(ctx, pair.AccessToken)
+	if err != nil {
+		t.Fatalf("AuthenticateAccessToken = %v", err)
+	}
+	if principal.UserID != user.ID {
+		t.Fatalf("UserID = %q, want %q", principal.UserID, user.ID)
+	}
+	if !principal.IsAdmin {
+		t.Fatal("IsAdmin = false, want true")
+	}
+}
+
+func TestAuthService_AuthenticateAccessTokenRejectsDeletedUser(t *testing.T) {
+	svc, userRepo := setupAuthServiceWithRepos(t)
+	ctx := context.Background()
+
+	user, err := svc.Register(ctx, "alice", "alice@example.com", "password123")
+	if err != nil {
+		t.Fatalf("Register = %v", err)
+	}
+
+	pair, err := svc.Login(ctx, "alice@example.com", "password123")
+	if err != nil {
+		t.Fatalf("Login = %v", err)
+	}
+
+	if err := userRepo.Delete(ctx, user.ID); err != nil {
+		t.Fatalf("Delete = %v", err)
+	}
+
+	_, err = svc.AuthenticateAccessToken(ctx, pair.AccessToken)
+	var ae *model.AppError
+	if !errors.As(err, &ae) {
+		t.Fatalf("expected AppError, got %T: %v", err, err)
+	}
+	if ae.Kind != model.KindUnauthenticated {
+		t.Fatalf("kind = %q, want %q", ae.Kind, model.KindUnauthenticated)
+	}
+}

internal/service/file.go

@@ -9,7 +9,6 @@ import (
 	"fmt"
 	"io"
 	"log/slog"
-	"net/http"
 	"strings"
 	"time"
 
@@ -23,26 +22,24 @@ import (
 
 // FileInfo is the public representation of a file or directory.
 type FileInfo struct {
-	ID        string    `json:"id"`
+	ID        string
-	UserID    string    `json:"user_id"`
+	UserID    string
-	ParentID  *string   `json:"parent_id"`
+	ParentID  *string
-	Name      string    `json:"name"`
+	Name      string
-	Size      int64     `json:"size"`
+	Size      int64
-	MimeType  string    `json:"mime_type"`
+	MimeType  string
-	IsDir     bool      `json:"is_dir"`
+	IsDir     bool
-	Hash      string    `json:"hash,omitempty"`
+	Hash      string
-	CreatedAt time.Time `json:"created_at"`
+	CreatedAt time.Time
-	UpdatedAt time.Time `json:"updated_at"`
+	UpdatedAt time.Time
 }
 
 // FileList is a paginated list of files.
 type FileList struct {
-	Files []FileInfo `json:"files"`
+	Files []FileInfo
-	Total int64      `json:"total"`
+	Total int64
 }
 
-var errUploadTooLarge = errors.New("upload exceeds maximum size")
-
 // FileService handles file management business logic.
 type FileService struct {
 	fileRepo      repository.FileRepository
@@ -90,7 +87,7 @@ func (s *FileService) Upload(ctx context.Context, userID string, parentID *strin
 
 	// Check for name conflicts in the target directory.
 	if _, err := s.fileRepo.FindByNameAndParent(ctx, userID, parentID, fileName); err == nil {
-		return nil, &model.AppError{Status: http.StatusConflict, Message: "a file with this name already exists in this directory"}
+		return nil, model.NewConflictError("a file with this name already exists in this directory")
 	} else if !errors.Is(err, model.ErrNotFound) {
 		return nil, model.NewInternalError("check name conflict", err)
 	}
@@ -156,7 +153,7 @@ func (s *FileService) Upload(ctx context.Context, userID string, parentID *strin
 		// Compensate: remove the promoted file.
 		_ = s.storage.Delete(ctx, storagePath)
 		if errors.Is(err, model.ErrDuplicate) {
-			return nil, &model.AppError{Status: http.StatusConflict, Message: "a file with this name already exists in this directory"}
+			return nil, model.NewConflictError("a file with this name already exists in this directory")
 		}
 		return nil, model.NewInternalError("create file record", err)
 	}
@@ -179,7 +176,7 @@ func (r *uploadLimitReader) Read(p []byte) (int, error) {
 		n, err := r.reader.Read(one[:])
 		if n > 0 {
 			p[0] = one[0]
-			return 1, errUploadTooLarge
+			return 1, model.ErrUploadTooLarge
 		}
 		return 0, err
 	}
@@ -197,18 +194,14 @@ func isUploadTooLargeError(err error) bool {
 	if err == nil {
 		return false
 	}
-	if errors.Is(err, errUploadTooLarge) {
+	return errors.Is(err, model.ErrUploadTooLarge)
-		return true
-	}
-	var maxBytesErr *http.MaxBytesError
-	return errors.As(err, &maxBytesErr)
 }
 
 func uploadTooLargeError(maxUploadSize int64) *model.AppError {
 	if maxUploadSize > 0 {
-		return &model.AppError{Status: http.StatusRequestEntityTooLarge, Message: fmt.Sprintf("file size exceeds the maximum allowed size of %d bytes", maxUploadSize)}
+		return model.NewPayloadTooLargeError(fmt.Sprintf("file size exceeds the maximum allowed size of %d bytes", maxUploadSize), model.ErrUploadTooLarge)
 	}
-	return &model.AppError{Status: http.StatusRequestEntityTooLarge, Message: "request body is too large"}
+	return model.NewPayloadTooLargeError("request body is too large", model.ErrUploadTooLarge)
 }
 
 // Download returns a reader for the file's content and its metadata.
@@ -220,7 +213,7 @@ func (s *FileService) Download(ctx context.Context, userID, fileID string) (io.R
 	}
 
 	if file.IsDir {
-		return nil, nil, &model.AppError{Status: http.StatusBadRequest, Message: "cannot download a directory"}
+		return nil, nil, model.NewBadRequestError("cannot download a directory")
 	}
 
 	reader, err := s.storage.Open(ctx, file.StoragePath)
@@ -279,7 +272,7 @@ func (s *FileService) Update(ctx context.Context, userID, fileID string, newName
 	// If parent is changing, verify the new parent.
 	if newParentID != nil {
 		if *newParentID == fileID {
-			return nil, &model.AppError{Status: http.StatusBadRequest, Message: "cannot move a directory into itself"}
+			return nil, model.NewBadRequestError("cannot move a directory into itself")
 		}
 		if err := s.verifyParent(ctx, userID, *newParentID); err != nil {
 			return nil, err
@@ -291,7 +284,7 @@ func (s *FileService) Update(ctx context.Context, userID, fileID string, newName
 	if newName != "" || newParentID != nil {
 		conflict, err := s.fileRepo.FindByNameAndParent(ctx, userID, file.ParentID, file.Name)
 		if err == nil && conflict.ID != fileID {
-			return nil, &model.AppError{Status: http.StatusConflict, Message: "a file with this name already exists in the target directory"}
+			return nil, model.NewConflictError("a file with this name already exists in the target directory")
 		} else if err != nil && !errors.Is(err, model.ErrNotFound) {
 			return nil, model.NewInternalError("check name conflict", err)
 		}
@@ -299,7 +292,7 @@ func (s *FileService) Update(ctx context.Context, userID, fileID string, newName
 
 	if err := s.fileRepo.Update(ctx, file); err != nil {
 		if errors.Is(err, model.ErrDuplicate) {
-			return nil, &model.AppError{Status: http.StatusConflict, Message: "a file with this name already exists in the target directory"}
+			return nil, model.NewConflictError("a file with this name already exists in the target directory")
 		}
 		return nil, model.NewInternalError("update file", err)
 	}
@@ -325,7 +318,7 @@ func (s *FileService) Delete(ctx context.Context, userID, fileID string) error {
 			return model.NewInternalError("check directory contents", err)
 		}
 		if total > 0 {
-			return &model.AppError{Status: http.StatusConflict, Message: "directory is not empty"}
+			return model.NewConflictError("directory is not empty")
 		}
 	}
 
@@ -350,7 +343,7 @@ func (s *FileService) CreateDir(ctx context.Context, userID string, parentID *st
 
 	// Check for name conflicts in the target directory.
 	if _, err := s.fileRepo.FindByNameAndParent(ctx, userID, parentID, dirName); err == nil {
-		return nil, &model.AppError{Status: http.StatusConflict, Message: "a file with this name already exists in this directory"}
+		return nil, model.NewConflictError("a file with this name already exists in this directory")
 	} else if !errors.Is(err, model.ErrNotFound) {
 		return nil, model.NewInternalError("check name conflict", err)
 	}
@@ -366,7 +359,7 @@ func (s *FileService) CreateDir(ctx context.Context, userID string, parentID *st
 
 	if err := s.fileRepo.Create(ctx, dir); err != nil {
 		if errors.Is(err, model.ErrDuplicate) {
-			return nil, &model.AppError{Status: http.StatusConflict, Message: "a file with this name already exists in this directory"}
+			return nil, model.NewConflictError("a file with this name already exists in this directory")
 		}
 		return nil, model.NewInternalError("create directory record", err)
 	}
@@ -379,13 +372,13 @@ func (s *FileService) getOwnedFile(ctx context.Context, userID, fileID string) (
 	file, err := s.fileRepo.FindByID(ctx, fileID)
 	if err != nil {
 		if errors.Is(err, model.ErrNotFound) {
-			return nil, &model.AppError{Status: http.StatusNotFound, Message: "file not found", Err: model.ErrNotFound}
+			return nil, model.NewNotFoundError("file not found", model.ErrNotFound)
 		}
 		return nil, model.NewInternalError("find file", err)
 	}
 
 	if file.UserID != userID {
-		return nil, &model.AppError{Status: http.StatusForbidden, Message: "access denied", Err: model.ErrForbidden}
+		return nil, model.NewForbiddenError("access denied", model.ErrForbidden)
 	}
 
 	return file, nil
@@ -396,17 +389,17 @@ func (s *FileService) verifyParent(ctx context.Context, userID, parentID string)
 	parent, err := s.fileRepo.FindByID(ctx, parentID)
 	if err != nil {
 		if errors.Is(err, model.ErrNotFound) {
-			return &model.AppError{Status: http.StatusNotFound, Message: "parent directory not found"}
+			return model.NewNotFoundError("parent directory not found", model.ErrNotFound)
 		}
 		return model.NewInternalError("find parent", err)
 	}
 
 	if parent.UserID != userID {
-		return &model.AppError{Status: http.StatusForbidden, Message: "access denied", Err: model.ErrForbidden}
+		return model.NewForbiddenError("access denied", model.ErrForbidden)
 	}
 
 	if !parent.IsDir {
-		return &model.AppError{Status: http.StatusBadRequest, Message: "parent is not a directory"}
+		return model.NewBadRequestError("parent is not a directory")
 	}
 
 	return nil
@@ -416,13 +409,13 @@ func (s *FileService) verifyParent(ctx context.Context, userID, parentID string)
 // null bytes, or are reserved names "." and "..".
 func validateFileName(name string) error {
 	if name == "" {
-		return &model.AppError{Status: http.StatusBadRequest, Message: "file name must not be empty"}
+		return model.NewBadRequestError("file name must not be empty")
 	}
 	if strings.ContainsAny(name, "/\\\x00") {
-		return &model.AppError{Status: http.StatusBadRequest, Message: "file name contains invalid characters"}
+		return model.NewBadRequestError("file name contains invalid characters")
 	}
 	if name == "." || name == ".." {
-		return &model.AppError{Status: http.StatusBadRequest, Message: fmt.Sprintf("file name is reserved: %s", name)}
+		return model.NewBadRequestError(fmt.Sprintf("file name is reserved: %s", name))
 	}
 	return nil
 }

internal/service/file_test.go

@@ -5,7 +5,6 @@ import (
 	"context"
 	"errors"
 	"io"
-	"net/http"
 	"strings"
 	"sync"
 	"testing"
@@ -18,16 +17,16 @@ import (
 	"github.com/dhao2001/mygo/internal/storage"
 )
 
-// assertAppError checks that err is an *model.AppError with the expected status.
+// assertAppError checks that err is an *model.AppError with the expected kind.
-func assertAppError(t *testing.T, err error, wantStatus int) bool {
+func assertAppError(t *testing.T, err error, wantKind model.ErrorKind) bool {
 	t.Helper()
 	var ae *model.AppError
 	if !errors.As(err, &ae) {
 		t.Errorf("expected *model.AppError, got %T: %v", err, err)
 		return false
 	}
-	if ae.Status != wantStatus {
+	if ae.Kind != wantKind {
-		t.Errorf("status = %d, want %d; message = %q", ae.Status, wantStatus, ae.Message)
+		t.Errorf("kind = %q, want %q; message = %q", ae.Kind, wantKind, ae.Message)
 		return false
 	}
 	return true
@@ -151,7 +150,7 @@ func TestFileService_UploadRejectsOversizedFileAndCleansStaging(t *testing.T) {
 	ctx := context.Background()
 
 	_, err := svc.Upload(ctx, "user1", nil, "too-large.txt", strings.NewReader("123456"))
-	assertAppError(t, err, http.StatusRequestEntityTooLarge)
+	assertAppError(t, err, model.KindPayloadTooLarge)
 
 	store.mu.RLock()
 	defer store.mu.RUnlock()
@@ -285,7 +284,7 @@ func TestFileService_DownloadForbidden(t *testing.T) {
 	}
 
 	_, _, err = svc.Download(ctx, "user2", info.ID)
-	assertAppError(t, err, http.StatusForbidden)
+	assertAppError(t, err, model.KindPermissionDenied)
 }
 
 func TestFileService_DownloadDirectory(t *testing.T) {
@@ -326,7 +325,7 @@ func TestFileService_GetNotFound(t *testing.T) {
 	ctx := context.Background()
 
 	_, err := svc.Get(ctx, "user1", "nonexistent")
-	assertAppError(t, err, http.StatusNotFound)
+	assertAppError(t, err, model.KindNotFound)
 }
 
 func TestFileService_GetForbidden(t *testing.T) {
@@ -339,7 +338,7 @@ func TestFileService_GetForbidden(t *testing.T) {
 	}
 
 	_, err = svc.Get(ctx, "user2", info.ID)
-	assertAppError(t, err, http.StatusForbidden)
+	assertAppError(t, err, model.KindPermissionDenied)
 }
 
 func TestFileService_List(t *testing.T) {
@@ -437,7 +436,7 @@ func TestFileService_Delete(t *testing.T) {
 	}
 
 	_, err = svc.Get(ctx, "user1", info.ID)
-	assertAppError(t, err, http.StatusNotFound)
+	assertAppError(t, err, model.KindNotFound)
 }
 
 func TestFileService_DeleteNonEmptyDirectory(t *testing.T) {
@@ -469,7 +468,7 @@ func TestFileService_DeleteForbidden(t *testing.T) {
 	}
 
 	err = svc.Delete(ctx, "user2", info.ID)
-	assertAppError(t, err, http.StatusForbidden)
+	assertAppError(t, err, model.KindPermissionDenied)
 }
 
 func TestFileService_CreateDir(t *testing.T) {
@@ -513,7 +512,7 @@ func TestFileService_VerifyParentForbidden(t *testing.T) {
 	}
 
 	_, err = svc.Upload(ctx, "user2", &dir.ID, "stolen.txt", strings.NewReader("data"))
-	assertAppError(t, err, http.StatusForbidden)
+	assertAppError(t, err, model.KindPermissionDenied)
 }
 
 func TestFileService_SoftDelete(t *testing.T) {
@@ -530,7 +529,7 @@ func TestFileService_SoftDelete(t *testing.T) {
 	}
 
 	_, err = svc.Get(ctx, "user1", info.ID)
-	assertAppError(t, err, http.StatusNotFound)
+	assertAppError(t, err, model.KindNotFound)
 }
 
 func TestFileService_SoftDeleteKeepsStorage(t *testing.T) {
@@ -590,5 +589,5 @@ func TestFileService_SoftDeleteForbidden(t *testing.T) {
 	}
 
 	err = svc.Delete(ctx, "user2", info.ID)
-	assertAppError(t, err, http.StatusForbidden)
+	assertAppError(t, err, model.KindPermissionDenied)
 }

internal/storage/local.go

@@ -2,11 +2,13 @@ package storage
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"io"
 	"os"
 	"path/filepath"
 	"strings"
+	"syscall"
 )
 
 const (
@@ -14,6 +16,8 @@ const (
 	stagingPathPrefix = "staging"
 )
 
+var renameLocalFile = os.Rename
+
 // LocalStorage implements StorageBackend using the local filesystem.
 type LocalStorage struct {
 	basePath string
@@ -87,13 +91,47 @@ func (s *LocalStorage) PromoteStaged(_ context.Context, stagedPath, finalPath st
 		return fmt.Errorf("create parent directory: %w", err)
 	}
 
-	if err := os.Rename(fullStagedPath, fullFinalPath); err != nil {
+	if err := renameLocalFile(fullStagedPath, fullFinalPath); err != nil {
+		if errors.Is(err, syscall.EXDEV) {
+			return promoteByCopy(fullStagedPath, fullFinalPath)
+		}
 		return fmt.Errorf("promote staged file: %w", err)
 	}
 
 	return nil
 }
 
+func promoteByCopy(stagedPath, finalPath string) error {
+	source, err := os.Open(stagedPath)
+	if err != nil {
+		return fmt.Errorf("open staged file: %w", err)
+	}
+	defer source.Close()
+
+	destination, err := os.OpenFile(finalPath, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0666)
+	if err != nil {
+		return fmt.Errorf("create final file: %w", err)
+	}
+
+	if _, err := io.Copy(destination, source); err != nil {
+		destination.Close()
+		os.Remove(finalPath)
+		return fmt.Errorf("copy staged file: %w", err)
+	}
+
+	if err := destination.Close(); err != nil {
+		os.Remove(finalPath)
+		return fmt.Errorf("close final file: %w", err)
+	}
+
+	if err := os.Remove(stagedPath); err != nil {
+		os.Remove(finalPath)
+		return fmt.Errorf("delete staged file after copy: %w", err)
+	}
+
+	return nil
+}
+
 // Open returns a reader for the file at path under the storage root.
 func (s *LocalStorage) Open(_ context.Context, path string) (io.ReadCloser, error) {
 	fullPath := filepath.Join(s.basePath, path)

internal/storage/local_test.go

@@ -5,6 +5,7 @@ import (
 	"io"
 	"os"
 	"strings"
+	"syscall"
 	"testing"
 )
 
@@ -179,6 +180,50 @@ func TestPromoteRequiresDataFinalPrefix(t *testing.T) {
 	}
 }
 
+func TestPromoteStagedFallsBackToCopyOnEXDEV(t *testing.T) {
+	dir := t.TempDir()
+	store, err := NewLocalStorage(dir)
+	if err != nil {
+		t.Fatalf("NewLocalStorage: %v", err)
+	}
+	ctx := context.Background()
+
+	content := "copy across filesystems"
+	_, err = store.SaveStaged(ctx, "staging/cross-device.txt", strings.NewReader(content))
+	if err != nil {
+		t.Fatalf("SaveStaged: %v", err)
+	}
+
+	originalRename := renameLocalFile
+	renameLocalFile = func(_, _ string) error {
+		return &os.LinkError{Op: "rename", Err: syscall.EXDEV}
+	}
+	t.Cleanup(func() {
+		renameLocalFile = originalRename
+	})
+
+	if err := store.PromoteStaged(ctx, "staging/cross-device.txt", "data/cross-device.txt"); err != nil {
+		t.Fatalf("PromoteStaged: %v", err)
+	}
+
+	reader, err := store.Open(ctx, "data/cross-device.txt")
+	if err != nil {
+		t.Fatalf("Open promoted file: %v", err)
+	}
+	got, err := io.ReadAll(reader)
+	reader.Close()
+	if err != nil {
+		t.Fatalf("ReadAll: %v", err)
+	}
+	if string(got) != content {
+		t.Errorf("content = %q, want %q", string(got), content)
+	}
+
+	if _, err := os.Stat(dir + "/staging/cross-device.txt"); !os.IsNotExist(err) {
+		t.Errorf("staged file should be removed after fallback promote, stat err = %v", err)
+	}
+}
+
 func TestOpenMissingFile(t *testing.T) {
 	dir := t.TempDir()
 	store, err := NewLocalStorage(dir)

mise.toml

@@ -1,2 +1,3 @@
 [tools]
 go = "1.26.2"
+node = "24"

web/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

web/.oxlintrc.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["react", "typescript", "oxc"],
+  "rules": {
+    "react/rules-of-hooks": "error",
+    "react/only-export-components": ["warn", { "allowConstantExport": true }]
+  }
+}

web/README.md

@@ -0,0 +1,18 @@
+# MyGO Web
+
+MyGO's browser client is a pure client-side rendered application built with React, TypeScript, and Vite.
+
+## Development
+
+```bash
+npm install
+npm run dev
+```
+
+## Checks
+
+```bash
+npm run check
+```
+
+The production build is emitted to `dist/` as static assets. See `docs/web/roadmap.md` at the repository root for architecture boundaries and planned dependencies.

web/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="MyGO web client" />
+    <title>MyGO</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

web/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "mygo-web",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "engines": {
+    "node": ">=24 <25"
+  },
+  "packageManager": "npm@11.9.0",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "oxlint",
+    "typecheck": "tsc -b",
+    "check": "npm run lint && npm run build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.101.2",
+    "antd": "^6.5.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "react-router": "^8.2.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.2",
+    "@types/node": "^24.13.2",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.3",
+    "oxlint": "^1.71.0",
+    "tailwindcss": "^4.3.2",
+    "typescript": "~6.0.2",
+    "vite": "^8.1.1"
+  }
+}

web/src/App.tsx

@@ -0,0 +1,9 @@
+import { RouterProvider } from 'react-router'
+
+import { router } from './app/router.tsx'
+
+function App() {
+  return <RouterProvider router={router} />
+}
+
+export default App

web/src/app/providers.tsx

@@ -0,0 +1,15 @@
+import type { PropsWithChildren } from 'react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { App as AntDesignApp, ConfigProvider } from 'antd'
+
+const queryClient = new QueryClient()
+
+export function AppProviders({ children }: PropsWithChildren) {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <ConfigProvider>
+        <AntDesignApp>{children}</AntDesignApp>
+      </ConfigProvider>
+    </QueryClientProvider>
+  )
+}

web/src/app/router.tsx

@@ -0,0 +1,15 @@
+import { createBrowserRouter } from 'react-router'
+
+import { HomePage } from '../pages/HomePage.tsx'
+import { NotFoundPage } from '../pages/NotFoundPage.tsx'
+
+export const router = createBrowserRouter([
+  {
+    path: '/',
+    element: <HomePage />,
+  },
+  {
+    path: '*',
+    element: <NotFoundPage />,
+  },
+])

web/src/index.css

@@ -0,0 +1,13 @@
+@layer theme, base, antd, components, utilities;
+@import 'tailwindcss';
+
+html,
+body,
+#root {
+  min-width: 320px;
+  min-height: 100%;
+}
+
+body {
+  margin: 0;
+}

web/src/main.tsx

@@ -0,0 +1,13 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import './index.css'
+import App from './App.tsx'
+import { AppProviders } from './app/providers.tsx'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <AppProviders>
+      <App />
+    </AppProviders>
+  </StrictMode>,
+)

web/src/pages/HomePage.tsx

@@ -0,0 +1,19 @@
+import { Card, Space, Tag, Typography } from 'antd'
+
+const { Paragraph, Title } = Typography
+
+export function HomePage() {
+  return (
+    <main className="grid min-h-screen place-items-center bg-slate-50 p-6">
+      <Card className="w-full max-w-xl">
+        <Space orientation="vertical" size="middle">
+          <Tag color="blue">MyGO Web</Tag>
+          <Title level={1}>MyGO</Title>
+          <Paragraph>
+            The client-side web application foundation is ready.
+          </Paragraph>
+        </Space>
+      </Card>
+    </main>
+  )
+}

web/src/pages/NotFoundPage.tsx

@@ -0,0 +1,16 @@
+import { Button, Result } from 'antd'
+import { Link } from 'react-router'
+
+export function NotFoundPage() {
+  return (
+    <Result
+      status="404"
+      title="Page not found"
+      extra={
+        <Button type="primary">
+          <Link to="/">Back home</Link>
+        </Button>
+      }
+    />
+  )
+}

web/tsconfig.app.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023", "DOM"],
+    "module": "esnext",
+    "types": ["vite/client"],
+    "allowArbitraryExtensions": true,
+    "skipLibCheck": true,
+    "strict": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}

web/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}

web/tsconfig.node.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023"],
+    "types": ["node"],
+    "skipLibCheck": true,
+    "strict": true,
+
+    /* Bundler mode */
+    "module": "nodenext",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["vite.config.ts"]
+}

web/vite.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+})