Marius van Niekerk
b85eae5a79
Moves AgentsView to Go 1.27 and adopts native `encoding/json/v2` behavior throughout. This is a clean migration with no JSON v1 compatibility or checkpoint fallback paths. Typed Huma routes now share JSON v2 request and response semantics with the rest of the application. OpenAPI continues to describe token usage as arbitrary JSON. JSONL rewrite paths retain untouched values as raw JSON, so large integers stay exact, while stored map output is deterministic where bytes define artifact identity. The Go 1.27 audit also adopts generic methods, assignment-context inference, promoted fields in struct literals, `errors.AsType`, and related standard-library simplifications. Build images, local tooling, documentation, and reviewer guidance now require Go 1.27. golangci-lint is pinned to v2.13.0, which can analyze the new language level.
139 lines
6.8 KiB
TOML
139 lines
6.8 KiB
TOML
review_guidelines = """
|
|
agentsview is a single-user developer tool. Default mode binds to
|
|
127.0.0.1. Optional managed Caddy proxy mode allows LAN access while
|
|
keeping the backend on loopback. Optional remote access mode binds to
|
|
0.0.0.0 with bearer-token auth for use over secure tunnels (Tailscale,
|
|
SSH, reverse proxy with TLS). Not designed for multi-user or
|
|
internet-facing deployment.
|
|
|
|
Key assumptions reviewers MUST account for:
|
|
|
|
1. AUTH MODEL: In local-only mode, loopback bind is the access
|
|
boundary — no auth tokens needed. In proxy mode, validateServeConfig
|
|
forces the backend to loopback; Caddy enforces CIDR subnet
|
|
allowlisting. When auth is required (`require_auth: true`), a
|
|
bearer token is required for all API requests (including localhost,
|
|
to prevent bypass via reverse proxy). An auth token is
|
|
auto-generated at startup if missing. Do not flag missing auth on
|
|
local-only code paths. DO flag any path that lets the backend bind
|
|
non-loopback in proxy mode, or missing subnet checks for
|
|
non-loopback Caddy binds.
|
|
|
|
2. MANAGED CADDY INVARIANTS: Backend loopback-only (enforced).
|
|
Non-loopback Caddy binds require allowed_subnets. auto_https off;
|
|
TLS needs user-supplied cert/key. Caddyfile is generated, validated
|
|
via `caddy validate`, then run as a supervised child process.
|
|
DO flag Caddyfile injection via unsanitized config values.
|
|
|
|
3. REMOTE ACCESS THREAT MODEL: Remote access is opt-in, intended for
|
|
encrypted tunnels. Accepted design decisions:
|
|
- No TLS termination — user's responsibility via tunnel/proxy.
|
|
- Token in URL for SSE — EventSource cannot set headers; accepted.
|
|
- Server restart required to rebind listener on toggle.
|
|
- Terminal config RCE prevention: generic PUT /api/v1/settings
|
|
rejects terminal updates; they must go through the validated
|
|
POST /api/v1/config/terminal endpoint.
|
|
|
|
4. XSS: {@html renderMarkdown(...)} is safe — renderMarkdown()
|
|
sanitizes via DOMPurify before returning HTML.
|
|
|
|
5. RATE LIMITING: Single-user tool. Do not flag missing rate limits
|
|
or concurrency caps.
|
|
|
|
6. CORS: corsMiddleware requires matching Origin for mutating
|
|
requests. Allowed origins = loopback variants + public_url +
|
|
public_origins. In remote mode, authenticated requests (bearer
|
|
token) allow the request origin. Do not flag as overly permissive
|
|
unless origins outside the configured set are accepted.
|
|
|
|
7. INPUT VALIDATION: Body size limits not required — backend is
|
|
loopback-only; in proxy mode Caddy subnet filtering limits
|
|
clients to trusted hosts. In remote mode, bearer token gates
|
|
all API access.
|
|
|
|
8. SESSION DATA: Displaying session contents (tool args, commands,
|
|
paths) is the tool's purpose. The user owns these files. Do not
|
|
flag as sensitive data exposure.
|
|
|
|
9. SUBPROCESS ENV: Agent CLI subprocesses intentionally inherit the
|
|
parent environment. Do not flag env var inheritance.
|
|
|
|
10. SESSION PARSING: Input files are from local agent CLIs, not
|
|
adversarial. Do not flag missing cycle detection, recursion
|
|
limits, or unreachable-node checks in DAG traversals.
|
|
|
|
11. WRITE ATOMICITY: Per-session transactions only. Full resync
|
|
recovers partial state. Do not flag non-atomic multi-session
|
|
writes.
|
|
|
|
12. TOCTOU ON LOCAL FILES: Files in ~/.agentsview/ are user-owned.
|
|
An attacker with home-directory access already has equivalent
|
|
privileges. Do not flag TOCTOU on local-only paths.
|
|
|
|
13. SCHEMA: Verify actual schema before flagging. tool_calls has
|
|
`id INTEGER PRIMARY KEY`. sessions has `relationship_type TEXT
|
|
NOT NULL DEFAULT ''` — NULLs cannot exist, so NOT IN is correct.
|
|
|
|
14. CONTROL FLOW: Trace actual flow (early returns, continues,
|
|
conditionals) before claiming logic errors.
|
|
|
|
15. DESKTOP (TAURI): Local wrapper around localhost backend. Focus
|
|
on: preventing remote navigation, tight CSP, no internal error
|
|
leakage, safe concurrency on response writers. Flag CSP
|
|
regressions (`csp: null`). Sidecar stdout may arrive in partial
|
|
chunks — flag code that assumes complete lines when readiness
|
|
depends on it.
|
|
|
|
16. INSIGHT AGENT SANDBOXING: Not all agent CLIs offer equal
|
|
sandboxing. Claude (--tools "") and Codex (--sandbox read-only)
|
|
have verified no-tools/read-only modes. Gemini currently does not.
|
|
Copilot only supports --disable-builtin-mcps (blocks MCP tools
|
|
but not all tool use). Kiro CLI uses --trust-tools= and
|
|
--no-interactive (disables tool trust prompts but does not
|
|
prevent tool execution); cwd is set to os.TempDir() to limit
|
|
exposure. This is an accepted design decision: agentsview
|
|
operates on the user's own session data, and users should only
|
|
run insight generation with agents they trust — the same trust
|
|
model as running agents on codebases. Do not flag Copilot's or
|
|
Kiro's sandboxing as insufficient.
|
|
|
|
17. POSTGRES PARITY: agentsview supports both SQLite (default) and
|
|
PostgreSQL (via `pg push` / `pg serve`) as the session store.
|
|
Any schema or read/write change to the SQLite session model
|
|
must be mirrored on the PG side. Reviewers should check that
|
|
new sessions columns are added to:
|
|
- internal/postgres/schema.go (CREATE TABLE + idempotent
|
|
ALTER TABLE migration in EnsureSchema)
|
|
- internal/postgres/sessions.go (pgSessionCols, scanPGSession)
|
|
- internal/postgres/push.go (INSERT column list + placeholders,
|
|
ON CONFLICT DO UPDATE SET, the IS DISTINCT FROM predicate,
|
|
the args slice, AND sessionPushFingerprint — a column missing
|
|
from the fingerprint will silently skip pushes when only that
|
|
column changed)
|
|
- CheckSchemaCompat probe (any column required for reads)
|
|
Filter logic that runs against both backends (e.g. activity-
|
|
window predicates) must use the same constants/semantics in
|
|
both internal/db/ and internal/postgres/. DO flag SQLite-only
|
|
changes to the session model that don't have a matching PG
|
|
update, and DO flag new session columns missing from
|
|
sessionPushFingerprint.
|
|
|
|
18. GO VERSION: This project pins Go 1.27+ in go.mod. Go 1.26
|
|
added value-form `new(v)` which returns `*T` pointing to v —
|
|
e.g. `new("clean")` is valid and yields a `*string`
|
|
initialized to "clean". DO NOT flag value-form `new` calls as
|
|
"new requires a type" compile errors; that was true through
|
|
1.25 only. Go 1.27 permits methods to declare type parameters,
|
|
promoted field selectors as struct-literal keys, and generic
|
|
function inference in every assignment context. Accept forms
|
|
such as `func (s *Server) get[I, O any](...)`,
|
|
`Outer{Promoted: value}`, and generic function values whose
|
|
target function type supplies the type arguments. Verify the
|
|
go.mod toolchain version before flagging unfamiliar language
|
|
features.
|
|
|
|
Do NOT flag issues that only apply to public-facing, multi-tenant,
|
|
or internet-exposed services. Focus on bugs, logic errors, data
|
|
corruption risks, and code quality issues.
|
|
"""
|