feat(canvas): share a canvas at a link, and download it as a PDF (ent#554)

[dolho]

Fixes abilityai/trinity-enterprise#554

Implements abilityai/trinity-enterprise#554 — a canvas can now leave the Workspace: a share link, and a PDF.

Stacked on #2619 (ent#553). Base is feature/553-canvas-lifecycle, so this diff is only the share/export work. Review #2619 first, or read this one's three commits and ignore the first two.

The share link

Two scopes, and the default is the narrow one.

scope	reach	enforcement
authorized (default)	the people who could already see the canvas	a DEEP link — the view requires a signed-in principal and re-checks can_user_access_agent. The link points at a canvas; it never grants access to one.
public	anyone holding the URL	explicit, separate, audited; protected only by 256 bits of token entropy

Failing narrow is enforced in five independent places — the column default, the Pydantic default, normalize_scope's fallback for an unrecognised value, the order of SHARE_SCOPES, and the radio the dialog preselects — because a link that reaches further than the sharer understood is the one failure this feature must not have. Creating a public link audits under its own action so "who made this readable by anyone with the URL" is answerable without reading payloads; the token never enters the audit row (it is the capability — the G-04 rule).

Why a separate table, and not agent_public_links

That table has a type column that looks purpose-built for this. Reusing it would have been a real vulnerability: nothing in its read path filters on type — get_public_link_by_token, is_link_valid and routers/public.py::_validate_public_link all resolve a token whatever it is — so a canvas row there would also be a working public-chat token, and anyone sent a canvas could talk to the agent.

type='site' is the same trap already laid, unexploited only because nothing creates those rows today (db_models.py: "currently only 'chat' is supported"). A separate table makes the isolation structural rather than dependent on every consumer remembering to check. Pinned by a test that fails if that read path ever starts filtering on type, at which point the decision is worth revisiting.

Live, and it says so

Operator ruling: the link renders the canvas as it is now, with its updated_at and stale mark, and the page states it is not a copy taken at share time. That follows ent#438's model — a canvas is a surface an agent keeps current — and means a share stores nothing. The cost is drift after sharing; the mitigation is revocation, not freezing.

Revocation keeps the row (revoked_at stamped, never deleted), because a revoked link has to be able to say it was revoked — which it cannot once the row is gone. The status vocabulary splits along disclosure: revoked and expired are returned only for a token that matched a row, since whoever holds such a link was already told the canvas exists; an unknown token and a canvas deleted out from under a link both collapse into one not_found, so a stranger guessing tokens learns nothing from the difference. An unparseable expires_at reads as expired — a lifetime we cannot read is one we cannot promise is live.

The PDF: print-first

The path the issue recommended, and it held up. A print stylesheet plus the browser's own PDF: no headless service to run and — the deciding reason — no second renderer to keep in step with CanvasBlock. A server-side renderer was the stated fallback and was not needed; pagination (break-inside: avoid per block) and fidelity both fall out of the same markup the screen uses.

CanvasDocument.vue is the one printable form, rendered by both the shared page and every authenticated surface, so AC #7's "works identically from every canvas surface" is true by construction rather than by three surfaces agreeing. It carries title, agent and generation date, forces the light rendering under @media print whatever theme the viewer is in, and when window.print is unavailable the control says why and the share link still works.

Boundary with ent#425

ent#425 (hosted deliverable pages) is still open, so by this issue's own rule the narrower share link ships here and #425 adopts it later. Decided by fact, not preference.

Verification

Exercised against a real database, not stubs — the full resolution matrix:

scope + viewer	result
public + anonymous	ok
authorized + anonymous	sign_in_required
authorized + owner	ok
authorized + stranger	not_authorized
unknown token	not_found
revoked / expired	revoked / expired
unparseable expiry	expired (fails closed)
canvas deleted after sharing	not_found

Plus: views counted only on a successful render, cross-agent revoke refused, a second revoke preserving the first revocation time, and 256-bit unique tokens.

23 backend tests and 20 vitest cases for the pure rules (canvasShare.js — vitest runs environment: 'node' with no mount harness, so a rule inside an SFC is one no test can reach).

Docs: flow doc gains sharing + export; user doc gains a section; set_canvas's MCP description now tells agents a canvas may be shared, so titles are written for someone to read.

Related to abilityai/trinity-enterprise#554

🤖 Generated with Claude Code

https://claude.ai/code/session_01CdxGmvuKuqaWJZ6pKUgaUJ

[dolho]

Re-review. The share design is careful — the separate table over agent_public_links is the right call and the argument for it (nothing in that read path filters on type, so a canvas row there is a working public-chat token) is the strongest thing in this PR. parse_iso_timestamp returns tz-aware UTC on both arms, so _is_expired has no naive/aware trap, and print-first for the PDF holds up.

One blocker, and it is not visible from this branch.

The Alembic graph forks the moment #2619 lands. This PR is stacked on feature/553-canvas-lifecycle, but its base is behind that branch by 4 commits — including the one that renumbered the pinned migration 0058_agent_canvases_pinned → 0059_agent_canvases_pinned (down 0058_portal_file_dismissals). This branch still carries the old 0058_ file and chains off it:

0059_agent_canvas_shares.down_revision = "0058_agent_canvases_pinned"   # gone after #2619

Merging the current #2619 in reproduces it — git merge resolves the rename by dropping the 0058_ file, so this PR's parent becomes dangling and the repo's own required guard fails:

$ python3 scripts/ci/check_alembic_heads.py src/backend/migrations/versions
alembic-heads: FAIL — resolves to 2 heads across 61 revision(s); exactly 1 is required.
  • 0059_agent_canvas_shares
  • 0059_agent_canvases_pinned
The heads share no common ancestor in this directory.

alembic upgrade head is singular and resolves its target before applying anything, so that graph applies zero revisions — every revision since the fork stops arriving, not just this one. On PostgreSQL that is a boot failure, and agent_canvas_shares never gets created.

CI here is green only because it is measured against the stale base. That is the part worth taking away: a stacked PR's migration graph is valid only against its base's current head, and neither branch's own checks can see the fork — #2619's tree has one head, this tree has one head, and the union has two. It is also the same class the #2619 review already caught once ("the Alembic fork is gone"); it moved one PR up the stack rather than being resolved.

Fix is small: merge #2619, drop the duplicated 0058_agent_canvases_pinned.py, and repoint 0059_agent_canvas_shares.down_revision at 0059_agent_canvases_pinned. Renumber it to 0060_ while you are there — two files sharing the 0059 prefix is legal (ids are strings) but the numeric prefix is the graph's only human ordering cue.

#2628 is stacked above this and inherits the same fork (0060_execution_open_canvas → 0059_agent_canvas_shares), plus a merge conflict against the current #2619. Whatever order you fix these in, the three have to be re-based as a stack.

Two smaller things, neither blocking:

• resolve() calls db.record_canvas_share_view() on the OK path, so an unauthenticated GET on a public link is a DB write. check_public_link_rate_limit bounds it at 60/min/IP, which is the same budget the other token routes share, so this is noted rather than objected to — but it is worth stating in the docstring that the view counter is a write on a read-shaped path, since that is exactly the shape ent#545 was filed about.
• SIGN_IN_REQUIRED (401) is returned to an anonymous caller for a live authorized-scope token, while an unknown token gets 404. That is a token-validity oracle for someone with no credential at all — narrower than it sounds, since it needs the 256-bit token in hand, and consistent with the docstring's own rule ("whoever holds such a link was already told the canvas exists"). Recording it because that rule is stated for revoked/expired, where the holder has used the link, and this arm extends it to a holder who never has.

[dolho]

Re-based on the current #2619 (def38cf7d: the 2026-09-11 fix plus dev merged through it). One conflict, in raw-color-baseline.json's named_increases block — both sides' notes kept (_ent553_note for 25 → 46, ent554 for 46 → 62), CanvasPanel.vue stays at 62. check_alembic_heads.py on this tree: 61 revisions, 1 head (0060_agent_canvas_shares ← 0059_agent_canvases_pinned). vitest 2803 passed (128 files); canvas backend suites 135 passed; ratchet unchanged.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RS8FBA7oEtAAv6GamZKong

[dolho]

Review: /review + /validate-pr

Reviewed against the merge-base with feature/553-canvas-lifecycle (46f4928e1), so this is only the share/export work. Recommendation: REQUEST CHANGES — one critical finding, confirmed by running the code rather than reading it.

❌ [C1] An agent-scoped key can mint a public share link for its own canvas (Confidence: 9/10)

src/backend/routers/canvas.py — create_canvas_share:

"""Mint a share link for one canvas (ent#554).

Owner-or-admin and human-only via `_gate_human_removal`: a share is a
GRANT, not a use, and the agent that writes a canvas does not decide who
outside the platform may read it.
"""
_gate_human_removal(current_user, name)

_gate_human_removal is not human-only. Its own docstring (added by #2619, one screen above) says so:

* an **agent-scoped key** may only touch its OWN canvas — unchanged, the
  #918 self-gate. `clear_canvas` is an agent tidying up after itself.
...
if current_user.agent_name:
    _require_self(current_user, name)
    return

So the gate admits an agent key acting on its own agent, and CanvasShareCreate accepts scope="public". An agent that is prompt-injected can POST /api/agents/<self>/canvas/<id>/share {"scope":"public"} with the TRINITY_MCP_API_KEY already in its container, and publish whatever it chooses to write into that canvas at an unauthenticated URL.

Verified, not inferred — four probes against the real gate, all passing:

probe	result
create_canvas_share source contains _gate_human_removal(, not _gate_pin(	✅
its docstring contains the string human-only	✅
_gate_human_removal(User(agent_name="agent-a"), "agent-a") raises nothing	✅
_gate_pin(User(agent_name="agent-a"), "agent-a") raises HTTPException(403)	✅
CanvasShareCreate(scope="public") is accepted	✅

This repo's own test already documents the behaviour — test_ent553_canvas_lifecycle.py::test_an_agent_key_may_not_pin_its_own_canvas ends with the line canvas_router._gate_human_removal(_user(agent_name="agent-a"), "agent-a"), asserting exactly this pass-through as correct for delete.

Why this is the more consequential instance of a class #2619 already fixed. _gate_pin's docstring makes the argument verbatim: "'no tool exposes it' is a property of the client, and this route is reachable with the agent's own key." That reasoning was applied to pin, which reorders a list. It was not applied to share, which publishes content to the open internet. Three things compound it:

1. The share is LIVE, not a snapshot (the service docstring says so, and test_a_shared_canvas_shows_current_content_not_a_copy pins it). So one minted link is a persistent, self-updating exfiltration channel, not a one-time disclosure.
2. The agent controls the content completely — it is the only writer of canvas blocks, so anything it can read it can copy into a canvas and publish.
3. audience is never consulted on the share path. ent#438 makes audience fail-closed so "a canvas reaches a Workspace client only because the agent said so"; a public share serves an operator-audience canvas to anyone with the URL. For a human owner that is a defensible override. For the agent itself it removes the last gate.

list_canvas_shares uses the same gate and returns the token in its payload (its own docstring: "this read hands over the capability itself and cannot be wider than the write"), so an agent key can also enumerate live share URLs for its own agent.

Fix: point create_canvas_share, list_canvas_shares and revoke_canvas_share at _gate_pin — it is already exactly the right predicate — or factor it out under a name that reads for both uses (_gate_human_only). Worth a test mirroring test_an_agent_key_may_not_pin_its_own_canvas, since the current suite has 23 tests and none covers the agent-key case.

/review — everything else

Checked and clean, with the line that proves it:

• Token entropy — secrets.token_urlsafe(32), 256 bits, matching the agent_shared_files.download_token shape. A public link's only protection, and it is the right one.
• Failing narrow — normalize_scope is an allowlist defaulting to authorized (bug: subscription reports "rate-limited" for the provider's own warning tier — allowed_warning fails the _headroom_indicates_limited catch-all #2396's rule), and the PR body's claim of five independent narrow defaults holds up.
• The agent_public_links analysis in the PR body is correct and is the best thing in this diff. Reusing that table would have made a canvas token a working public-chat token, because get_public_link_by_token / is_link_valid / _validate_public_link all resolve a token without filtering on type. A separate table makes the isolation structural. Good call, and good that it is pinned by a test.
• Enumeration — revoked / expired are returned only for a token that matched a row; everything else collapses to one not_found. The reasoning in the service docstring is right: a holder of a dead link has already been told the canvas exists.
• get_optional_user — delegates to get_current_user instead of re-implementing it, and the docstring warns against reuse on a route that would otherwise require auth. Correct construction for the one caller.
• XSS on an unauthenticated same-origin page — agent-authored html blocks go through sanitizeCanvasHtml (DOMPurify) at CanvasBlock.vue:132, and diagrams through sanitizeSvg. Pre-existing from ent#438/fix(migrations): swallow duplicate-column race on cold start (#456) #537, not introduced here — but note that ent#554 is what first puts that output on a page a stranger can load, so the sanitizer is now load-bearing for more than it was.
• Expiry fails closed — an unparseable expires_at reads as expired.
• Rename/purge — agent_canvas_shares registered in AGENT_REFS, pinned by test_share_rows_follow_their_agent_through_rename_and_purge.

Informational

[I1] audience is not consulted when minting a share. (Confidence: 7/10) Independent of C1, an owner can publicly share an operator-audience canvas. Probably intended — the owner can read it anyway, and a share is a human override of the agent's declaration — but ent#438 documents audience as the fail-closed gate, and nothing in this diff records that a public share deliberately outranks it. One sentence in agent-canvas.md would settle it.

[I2] A view is a DB write on an unauthenticated route. (Confidence: 6/10) record_canvas_share_view fires per successful resolve. Bounded by check_public_link_rate_limit per IP, so this is a note rather than a finding — but it is the first write-on-read the public token surface has.

/validate-pr — Lane C+schema

Lane C on routers/public.py + dependencies.py — genuinely, unlike #2619 where it was only the compose files.

Category	Status	Notes
Base branch	✅	feature/553-canvas-lifecycle — correct for a stacked PR; retargets to dev when #2619 lands
Closing keyword	⚠️	body says "Implements abilityai/trinity-enterprise#554" — not a closing keyword. It is cross-tracker, so the automation would not promote it anyway, but rephrasing to Fixes abilityai/trinity-enterprise#554 keeps the convention and makes the manual status-in-dev bump obvious
Dual-track migration	✅	SQLite agent_canvas_shares + Alembic 0060_agent_canvas_shares
Alembic single head	✅	61 revisions, 1 head (0060), chained off 0059 — no fork
Security greps	✅	clean
Docs	✅	feature-flows/agent-canvas.md (+68), user-docs/agents/agent-canvas.md (+23)
Merge gate	✅	all checks green
Test adequacy	⚠️	23 tests, strong on scope/expiry/revocation/enumeration — but no agent-principal test on any of the three share routes, which is how C1 got through
ui label	⚠️	adds SharedCanvas.vue, CanvasDocument.vue and +146 lines of CanvasPanel.vue; no label, so frontend-e2e did not exercise the new public page

_{🤖 Generated with Claude Code · https://claude.ai/code/session_01Q19uRCksdn4DiRAJ55rfpZ}

[dolho]

Re-review — [C1] fixed

Pushed to this branch: 1005bd2d9 (the fix), f5a39e1a4 (the # mcp: header), 6d77d988f (learnings). Recommendation moves REQUEST CHANGES → APPROVE.

What changed

The predicate was never wrong — _gate_pin has had the right rule since ent#553. What shipped wrong was three routes reaching for the neighbouring gate, whose name describes a verb (_gate_human_removal) rather than a rule. So the fix renames the rule instead of patching call sites:

_gate_human_only(user, name, *, agent_detail)     # owner-or-admin, no agent principal at all
├── _gate_pin    → "A pin is a human's ordering; an agent may not pin a canvas"
└── _gate_share  → "A share link decides who outside the platform may read this canvas…"

agent_detail is per-caller because an agent reads the refusal to decide what to do next, and "may not pin" is unhelpful on a share.

Final gate map — the three share routes moved, the delete routes deliberately did not:

route	gate	agent key
create_canvas_share	_gate_share	❌
list_canvas_shares	_gate_share	❌ — it returns the token, which is the capability
revoke_canvas_share	_gate_share	❌ — no legitimate way to create a link means none to turn off a person's
pin_canvas	_gate_pin	❌ unchanged
clear_canvas	_gate_human_removal	✅ unchanged
bulk_delete_canvases	_gate_human_removal	✅ unchanged
write_canvas / patch_canvas	_gate_write	✅ unchanged

Verification — the original probes, inverted

The four probes that confirmed the finding now assert the opposite, and pass:

probe	before	after
create_canvas_share source contains _gate_human_removal(	✅ present	❌ absent, _gate_share( instead
_gate_share(User(agent_name="agent-a"), "agent-a")	(gate did not exist)	raises HTTPException(403)
the docstring's human-only claim matches the code	contradicted	matches
scope="public" reachable by an agent	yes	refused at the gate

Six regression tests added, and four of them fail against the parent commit — verified by reverting routers/canvas.py, running, and restoring:

FAILED test_an_agent_key_may_not_mint_a_share_link
FAILED test_all_three_share_routes_use_the_human_only_gate
FAILED test_listing_shares_is_gated_because_it_returns_the_token
FAILED test_the_human_only_gate_names_its_rule_not_a_verb

The other two pass both ways by design — they are the over-correction guards, and they earned themselves immediately. My first attempt used one str.replace on a body shape that occurs twice in this file, and silently swept clear_canvas into the human-only gate. That would have broken a real MCP tool for every agent — a security fix breeding the next bug, the /review §4.14 class — so test_deleting_a_canvas_is_deliberately_still_agent_callable now asserts the boundary in the other direction. (test_ent438_agent_canvas.py:294 would have caught it too.)

Re-review of the fix itself

Checked for the adjacent-sibling class, since that is how the original defect arrived:

• Every remaining _gate_human_removal call site is a delete verb (bulk_delete_canvases, clear_canvas) — nothing grant-shaped is left on the permissive gate.
• No share route exists on the portal prefix, so the Workspace side needs no equivalent change; _require_canvas_manager there is already platform-only + owner.
• No frontend change needed — the share control is gated on canManage, which derives from can_manage_canvases (a human owner/admin check). The fix narrows only the REST surface, which is the point: agents have no UI, so nothing that could previously reach the control has lost it.

Tests

suite	result
-k canvas across tests/unit	291 passed, 2 skipped
test_1310_auth_wiring + test_1310_auth_consolidation + test_293_admin_gate_rejects_agent_keys + test_186_enumeration_uniformity + test_models_centralized	116 passed
CI on this branch	11/11 pass, 0 fail

Docs

• user doc — "Only the agent's owner (or an admin) can delete, pin or share", plus a bullet stating that an agent can mark a canvas for its roster but cannot create, list or revoke a share link.
• flow doc — records the decision, the blast radius, why list_canvas_shares is gated identically, and why the delete routes stay permissive.
• # mcp: header — the three share routes are now listed as deliberately not exposed. Worth more than a comment here: the ent#553 entry already stated the rule the share routes then failed to follow, so a reader consulting this header for a fourth route's gate would have found the reasoning but not the precedent.
• docs/memory/learnings.md — the class is now confirmed twice in two PRs, so it is written down: a gate named after a verb gets reached for by a route that shares the verb but not the rule. It also captures the coverage half — all 23 existing tests would have passed against the vulnerable code, because none constructed a User(agent_name=…).

Still open from the first pass (unchanged, non-blocking)

• [I1] audience is not consulted when minting a share. Now recorded in the flow doc as part of the blast-radius paragraph, but the human-sharer case is still undecided-in-writing. One sentence would settle it.
• [I2] a view is a DB write on an unauthenticated route — bounded by the per-IP limit; still a note.
• ⚠️ no closing keyword — Implements abilityai/trinity-enterprise#554. Rephrase to Fixes … for the convention; cross-tracker, so status-in-dev needs a manual bump either way.
• ⚠️ no ui label — frontend-e2e still has not exercised the new public share page.

_{🤖 Generated with Claude Code · https://claude.ai/code/session_01Q19uRCksdn4DiRAJ55rfpZ}

[vybe]

Validated (/validate-pr, Lane C+schema): auth boundary reviewed (get_optional_user delegates to get_current_user; share routes human-only via _gate_share), dual-track migration present, single Alembic head, no secrets/emails/IPs. Merged dev in (parent-squash echo resolved; tree vs dev is exactly the ent#554 delta), retargeted to dev; full pytest matrix, CodeQL, e2e green.