View the site as a user
Status: pending approval. Nothing here is built.
- Who builds: a separate agent, after the owner has read and approved this
plan. Who reviews: a third. - Read from source:
trip2g/trip2gmainate0e339c9. Everyfile:line
below is from that commit. - Not measured live: nothing. No code was run for this plan. Section 9
lists what is unknown and the experiment that settles each point. - Decided by the owner on 2026-11-18: a separate PR from
main, read-only,
an ordinary user as the target, a second cookie beside the admin's own
session, a banner "you are viewing as X" with a button that returns the
admin's rights. The banner is drawn by the default template only; a custom
layout shows it by calling a method. The plan's author had recommended
splicing it into every page instead, as the only exit a person can see.
1. Why
An admin cannot see what a reader sees. The padlock on a note link means "this
note is not free"; it says nothing about who can open it. A note with no
subgraph looks as locked as a note in a private subgraph, and it is readable by
every reader with any active subscription
(internal/case/canreadnote/resolve.go:80-88). The only way to check today is to
create a test user, grant it the same access and sign in as it.
The feature answers one question: what does this particular reader get on
this site right now, through the same code that serves the reader.
2. What exists and why it is not enough
The admin user page has a "Sign-in link" action (admin.createHatLink,
internal/case/admin/createhatlink/resolve.go). It mints a link that signs its
holder in as that email for 1 to 60 minutes. An admin can open it themselves.
It is a way to let a person in, and it makes a poor inspection tool:
- It is a full session. Purchases, form posts and personal tokens all work
under it. - Views are recorded under the user, so the inspection changes the reader's
history and the analytics. - It replaces the admin's session in that browser. Coming back means
signing in again or keeping a second browser profile. - Nothing on the page says whose session it is.
- The audit log has the minting only. What was done under the session
cannot be told apart from the user's own actions.
3. Behaviour
- On the admin page of a user, the admin presses View as this user.
- The browser opens the site's front page. A bar across the top reads
"You are viewing this site as maria@example.com. Read-only." with a
Back to admin button. - Every page, search, attachment and note query answers as that user would
get it. Nothing can be changed: every GraphQL mutation and every
state-changing HTTP request is refused. - No page view is recorded and the reader does not appear to move on the
admin graph. - Back to admin removes the second cookie and returns to the user's admin
page. The admin's own session was never touched. - After an hour the second cookie expires and the admin is themselves again
on the next request.
4. Design
4.1 The override cookie
- Name: the session cookie name plus
_as(trip2g_token_asby default;
the session name comes from--user-token-cookie-name). - Attributes: the same as the session cookie (
internal/usertoken/token.go:172-209):
HttpOnly,Path=/,SameSite=Lax,Secureunless--user-token-insecure. - Value: a JWT signed with the same secret as sessions, HS256, carrying
as(target user id),by(admin user id),use: "view-as"andexp
(one hour). Nothing secret is in the payload: two ids and a purpose. usekeeps the two token kinds apart: the session parser refuses a token
with ause, the override parser refuses one without it. Without this an
override JWT pasted into the session cookie would be a session for useri
with an empty role.
4.2 Where the override is applied
appreq.Request.UserToken() (internal/appreq/request.go:203-272) is where a
request gets its identity, and it caches the result for the request. The
override is applied there, on the cookie branch only (:216), before the
result is cached. It is not applied to Authorization: Bearer, personal
tokens or ?token=: those are machine credentials and nobody presses a
button under them.
The override is honoured only when all of these hold:
- the session cookie resolved to an admin after the validators ran, so an
admin whose role was removed loses the override at once
(cmd/server/auth.go:26-52re-reads the admin row on every request); byequals that admin's id;- the token is unexpired and carries
use: "view-as"; - the target user exists, is not an admin and is not banned.
Anything else: the override cookie is deleted and the request is served as the
admin. A stolen override cookie is worthless alone, and with the admin's
session cookie the thief already is the admin.
appreq has no database. It gets a small resolver the way it already gets
PersonalTokenResolver (cmd/server/server.go:68-75): an interface on the
request, implemented by the app, that turns the two cookies into the effective
usertoken.Data.
The effective identity is a new usertoken.Data{ID: target, Role: "user"}
with one unexported-from-JSON field, ViewAsBy int, and a method IsViewAs().
It is never the admin's parsed struct with a field changed: the validator
mutates that struct in place (cmd/server/auth.go:42).
4.3 Read-only
One predicate, appreq.DenyViewAs(ctx), asked in two places:
- GraphQL. In
makeAroundOperations(internal/graph/handler.go:173-247),
before the transaction gate at:203, so it also covers@skipTx
mutations. A mutation is refused with "view-as is read-only". One exception:
a mutation that is onlysignOutends the view (it deletes the override
cookie and leaves the admin's session), because the user-space widget shows
a sign-out button and it has to do something sensible. - Everything else. Non-GraphQL requests have no single dispatch point: they
pass through a middleware list (cmd/server/routing.go:191-244), then
?hat=handling, then the router. The check therefore sits in the request
handler before the middlewares (cmd/server/server.go:78): a method other
than GET, HEAD or OPTIONS from a view-as request answers 403, except the
GraphQL prefixes (their own check above) and the stop endpoint.
Sign-in paths that work over GET stay open on purpose: ?hat=, the HAT GET
link, OAuth and OIDC callbacks, the Telegram link, the purchase-token cookie.
Each replaces the session cookie with a real account. The next request then
fails the by check and the override is dropped. SetupUserToken
(cmd/server/auth.go:162-192) and TokenManager.Delete also delete the
override cookie, so a real sign-in or sign-out never leaves one behind.
4.4 No trace in the reader's history
handleUserToken (internal/case/rendernotepage/resolve.go:361-421) does two
things for a signed-in reader on every page: it records the view on a
background context (:389-393) and publishes the reader's move to the admin
graph (:398-404). Both are skipped for a view-as identity. The reads in the
same function (active subgraphs, last view) stay, because the page needs them
to render what the reader would see.
4.5 The page cache
Nothing to do. The cache stores and serves pages only for a nil token
(internal/case/rendernotepage/pagecache.go:67-69, :126-128); a view-as
identity is not nil.
4.6 The banner
Rendered by the server, with no JavaScript, as a form that posts to the stop
endpoint. The default template has one <body> for every mode
(internal/defaulttemplate/views.html:84), so a block right after it shows on
note pages, the paywall, the sign-in wall and 404.
Custom Jet layouts render their own HTML and do not get the banner by
themselves. A layout shows it by calling one method on the defaultTemplate
variable it already receives (internal/case/rendernotepage/userspace.go:197-204),
next to Header and Footer. The method returns the finished HTML, and an
empty string when no view is active, so a layout calls it without a condition.
The server does not splice anything into a layout's HTML. The federation guest
plan (PR #522) uses the same method for its guest bar.
An admin inside a layout that does not call the method has no reminder that
they are someone else. Nothing they do there can change anything, and the view
ends by itself after an hour.
The banner names the target by email, or by "user #id" when the user has none.
That costs one user lookup per request, only while a view is active.
4.7 Start, stop, audit
- Start:
admin.startViewAs(input: { userId }), a use case under
internal/case/admin/startviewas/shaped likecreatehatlink: admin gate,
target checks, set the cookie, one audit line (actorUserID,
targetUserID). No new table, so no migration. - Stop:
POST /_system/view-as/stop, a use case with an endpoint. It
deletes the cookie, writes an audit line and redirects to the user's admin
page in the admin. It is a plain HTTP endpoint so the banner works without
JavaScript and in any layout. - Admin UI: one more tool on the user page
(assets/ui/admin/user/show/show.view.tree:5-30), wired like the
"Sign-in link" button; on success the page navigates to/.
4.8 What the admin loses while viewing
While the override is present the session is the user's everywhere, not only
on reader pages:
/adminand everyadmin { ... }GraphQL field refuse, as they do for that
user.- An admin session no longer stands in for an API key
(internal/case/checkapikey/resolve.go:40-47), so a sync from the same
browser fails instead of running as the admin. - Fleet and codellm decide "is this an admin" by asking the monolith for
viewer { role }with the browser's cookies
(internal/delegatedadmin/delegatedadmin.go:1-20). They will see the user.
This is the simple rule, "you are X until you press Back to admin", and it is
the price of having one identity per request.
5. Files
| Area | Files |
|---|---|
| Token | internal/usertoken/token.go (override mint/parse/delete, ViewAsBy, use check) |
| Request | internal/appreq/request.go (resolver hook, DenyViewAs) |
| App | cmd/server/auth.go (resolver impl, cookie cleanup on sign-in and sign-out), cmd/server/server.go (non-GraphQL guard) |
| GraphQL | internal/graph/schema.graphqls, internal/graph/handler.go, generated files (make gqlgen) |
| Cases | internal/case/admin/startviewas/, internal/case/stopviewas/ (+ go generate ./internal/router/...) |
| Reader page | internal/case/rendernotepage/resolve.go (skip view and move), banner |
| Template | internal/defaulttemplate/views.html, langs/en.toml, langs/ru.toml, assets/defaulttemplate/src/index.scss |
| Admin UI | assets/ui/admin/user/show/, a new assets/ui/admin/user/viewas/ |
| Docs | docs/en/user/ and docs/ru/user/ page pair, a row in the docs map |
6. Options that lost
-
Open the existing sign-in link in a second browser profile. Zero code.
Loses on every point of section 2, and has no answer at all for a reader
without an email. -
Swap the admin's session for the user's and keep a "return ticket". One
identity cookie instead of two. Loses because the return ticket has to be
able to restore an admin session, so it is an admin credential under another
name, and coming back becomes a mint instead of a delete. -
A
?view_as=<id>parameter honoured for admins. No cookie at all. Loses
because links on the page and the$molwidgets' GraphQL calls do not carry
the parameter: the page would be the user's and everything it loads would be
the admin's. -
An access report in the admin ("this user can read these 214 notes, and
here is why"). No impersonation, no session risk. It answers "what is open"
better than clicking through pages does, and it loses only on "what does it
look like". This plan's verdict is measured on the ground that favours it:
the request was to look with the reader's eyes. For the padlock question
alone the report may be the better tool, and it can be built later without
touching this. -
Full impersonation, writes included. Lets an admin test a purchase or a
form as the user. Refused by the owner for this PR: the admin's actions
would be indistinguishable from the user's unless every write path learned
to mark them. -
Splicing the bar into every HTML page, custom layouts included. One bar
everywhere, and it was the plan author's recommendation, because the bar is
the only way out a person can see. It lost on the owner's decision: the
server would be editing HTML that a layout author wrote, and a layout with
unusual markup could show it in an odd place. A method the layout calls
leaves the author in charge of their page.
7. Decisions left to the owner
- Who may be a target. The plan refuses admins (pointless, and it avoids
an admin acting under another admin's name in the audit log) and banned
users (a banned session answers 503 today,internal/router/router.go:129-132).
Allowing a banned target would show exactly that broken page. - Lifetime. One hour, fixed. Shorter is safer against a forgotten tab;
longer suits a long review. signOutwhile viewing. The plan makes it end the view and keep the
admin signed in. The alternative is to refuse it like every other mutation
and leave the widget's button dead.- Viewing as an anonymous visitor. Not in this PR. It needs its own gate
on the page cache, which treats every nil token as shareable
(pagecache.go:67,:126).
8. Tests the build must bring
Written first, red before green.
- In-process HTTP matrix in
cmd/server, on the helpers of
free_note_matrix_test.go:142-369: an admin with an override gets the
target's answer on page render, GraphQLnote, site search, attachments,
note queries andviewer; the same requests without the override answer as
the admin. - Refusals: an override alone (no session); an override with another
admin's session; with a non-admin session; expired; with a target that is an
admin, banned or missing; an override JWT in the session cookie and a session
JWT in the override cookie. Each ends with the override cookie deleted. - Read-only: every mutation refused,
signOutends the view, every
non-GET endpoint ininternal/router/endpoints_gen.gorefused except stop. - No trace: after a page render no row appears in
user_note_viewsfor
the target and no reader move is published. - Losing the role: remove the admin row mid-view; the next request is an
ordinary user and the override is gone. - Use cases: table tests with moq for
startviewasandstopviewas. - Layouts: a Jet layout that calls the method shows the banner during a
view and nothing otherwise; one that does not call it shows none. - E2E: one Playwright spec. The admin opens a user's page, presses the
button, sees the banner, gets the closed page on a note the user cannot
read, has a mutation refused, presses Back to admin and is an admin again.
Done is the scenario of section 3 walked by hand on a dev instance, with a
transcript and screenshots checked by an agent that has not seen the code.
9. What is not covered, and the experiment for each
- The non-GraphQL guard may miss a write path. The middleware list has
paths with their own auth (git API, Telegram and payment webhooks, replica
intake); they do not read the session, so they are not the reader's actions,
but the list was read, not exercised. Experiment: a test that walks every
registered endpoint and every middleware with a view-as request and a
non-GET method, and fails when a new POST endpoint appears unclassified. - Order of the first
UserToken()call. The asset middleware resolves the
identity before the router (internal/case/serveasset/resolve.go:169), and
the result is cached per request. The override must already be applied by
then. Experiment: an attachment of a note the target cannot read answers
as it does for the target. - SSE subscriptions copy the request with
Snapshot()
(cmd/server/graphql.go:130). Experiment: a note-changes subscription
under view-as delivers the target's scope, not the admin's. - A sign-in in the middle of a view (
?hat=, purchase-token cookie,
Telegram link) overwrites the session during the request
(cmd/server/server.go:90-108,routing.go:229-234). The plan says the
override is dropped on the next request; what the current request renders
was not traced. Experiment: a test per path. - Fleet and codellm under a view. Read from one file comment.
Experiment: on a stand with fleet, open its UI during a view and note
what it shows. - The MCP endpoint builds an admin identity from an API key
(internal/case/mcp/endpoint.go:373-394) and is POST, so the guard refuses
it for a browser under view-as. Whether any browser-side feature relies on
that POST was not checked. Experiment: grep the$molsources for
/_system/mcpbefore building. - A layout that does not call the method leaves the admin with no visible
way back. Experiment: during the hand-walked scenario, open a page with a
custom layout under a view and note how a person gets out (the admin user
page in another tab, or waiting an hour). - Expiry returns the admin's rights silently. A tab left open for an hour
shows a banner-less page on the next click with full admin rights. No fix is
proposed; it is the direction of least surprise for the cookie, and the
most surprising one for the person.