penpot/docs/technical-guide/developer/subsystems/link-unfurl.md

title, desc

title	desc
Link unfurl (link previews)	How Penpot serves Open Graph metadata for shared links, so that Slack, Discord, Twitter and other platforms render rich previews with the file name and thumbnail.

Link unfurl (link previews)

When a user pastes a Penpot link in a chat or social platform (Slack, Discord, Twitter/X, WhatsApp, Telegram, LinkedIn, Mastodon, Bluesky...), the platform's crawler fetches the URL and looks for Open Graph metadata to render a rich preview card. This subsystem serves that metadata dynamically:

• For a file link: the file name as title and the latest dashboard thumbnail of the file as preview image.
• For a project or team link: a generic "Project | Penpot" or "Team dashboard | Penpot" title.
• In any other case (or when the feature is disabled): the default Penpot title, description and preview image.

The whole feature is gated behind the link-unfurl flag (enabled with enable-link-unfurl in PENPOT_FLAGS), and is disabled by default. See Security considerations below for why.

How it works, end to end

The main obstacle is that Penpot is a SPA and all the routing state lives in the URL fragment (#/workspace?file-id=...). The fragment is never sent to the server, so with a plain URL the backend has no way to know which file the link points to. The feature is therefore built from three cooperating pieces:

 user shares URL          crawler (Slackbot, ...)            regular browser
       │                          │                                 │
       │  https://host/?file-id=X#/workspace?...                    │
       │                          │                                 │
       ▼                          ▼                                 ▼
   [frontend]                 [nginx]                           [nginx]
 mirrors context      user-agent matches crawler        user-agent is normal
 params before the    rewrite / -> /unfurl              serve SPA index.html
 fragment on every    (query string preserved)
 navigation                       │
                                  ▼
                             [backend]
                        GET /unfurl?file-id=X
                        query DB, render Open
                        Graph HTML template

1. Frontend: mirroring context params on the query string

File: frontend/src/app/main/router.cljs

On every navigation, the navigated event calls match->context-params to extract the identifiers that give sharing context to the current route, and mirrors them on the query string (before the fragment) using history.replaceState. The resulting URLs look like:

https://design.penpot.app/?file-id=<uuid>#/workspace?team-id=...&file-id=...&page-id=...
https://design.penpot.app/?team-id=<uuid>&project-id=<uuid>#/dashboard/recent?...
https://design.penpot.app/?team-id=<uuid>#/dashboard/recent?team-id=...

match->context-params implements a priority: if the route has a file-id only that is mirrored; otherwise project-id (together with its team-id); otherwise team-id. Routes without any of those ids (e.g. auth pages) mirror nothing and replaceState strips any stale query string. Ids are read both from :query-params (current routes) and from [:params :path] (legacy routes that carry them as path params).

This way, when the user copies the URL from the address bar and shares it, the context ids travel in a part of the URL that does reach the server.

2. Nginx: detecting link preview crawlers

Files: docker/devenv/files/nginx.conf (devenv) and docker/images/files/nginx.conf.template (production image).

A map block classifies the request by User-Agent:

map $http_user_agent $penpot_unfurl_agent {
    default 0;
    ~*(slackbot|discordbot|twitterbot|facebookexternalhit|facebookcatalog|whatsapp|telegrambot|linkedinbot|skypeuripreview|pinterestbot|redditbot|embedly|iframely|mastodon|bluesky) 1;
}

Inside the SPA root location, crawler requests for / are internally rewritten to the backend unfurl endpoint (the query string is preserved by rewrite ... last):

if ($penpot_unfurl_agent) {
    rewrite ^/$ /unfurl last;
}

location = /unfurl {
    proxy_pass http://127.0.0.1:6060/unfurl$is_args$args;   # devenv
    # proxy_pass $PENPOT_BACKEND_URI/unfurl$is_args$args;   # production template
}

Regular browsers are not affected: they keep receiving the SPA index.html. If you self-host behind a different reverse proxy, you need to replicate this routing there.

3. Backend: the /unfurl endpoint

File: backend/src/app/http/unfurl.clj (new namespace).

The handler:

1. If the link-unfurl flag is not set, skips any lookup and uses the default context.

2. Otherwise parses file-id / project-id / team-id from the query params (invalid UUIDs are tolerated and treated as absent).

3. For a file-id, runs a single query joining file with its most recent non-deleted file_thumbnail row (the dashboard thumbnail):

   SELECT f.name, ft.media_id
     FROM file AS f
     LEFT JOIN file_thumbnail AS ft
            ON (ft.file_id = f.id AND ft.deleted_at IS NULL)
    WHERE f.id = ?
      AND f.deleted_at IS NULL
    ORDER BY ft.revn DESC NULLS LAST
    LIMIT 1
   

4. Builds the context: :title is "<file name> | Penpot" and :image is <public-uri>/assets/by-id/<media-id> when a thumbnail exists. Missing data falls back to the defaults; the default image is <public-uri>/images/penpot-link-preview.png (a static asset shipped in frontend/resources/public/images/).

5. Renders backend/resources/app/templates/unfurl.tmpl and responds with 200, text/html and cache-control: no-store, no-cache, max-age=0.

The endpoint always returns 200 with at least the generic metadata; a non-existent file id, a malformed id or a disabled flag never produce an error, so crawlers always get a valid preview.

The route is registered in backend/src/app/http.clj and wired in the integrant system map in backend/src/app/main.clj (::http.unfurl/routes, which only needs the ::db/pool dependency).

The HTML template

File: backend/resources/app/templates/unfurl.tmpl.

A minimal HTML page with og:title, og:description, og:image, the equivalent twitter:* card tags and <meta name="robots" content="noindex">. The body contains a single script:

<script>location.replace("/" + location.hash);</script>

so that if a human somehow lands on /unfurl (e.g. some clients let users click through to the fetched URL), the browser bounces back to the SPA root keeping the fragment, and the app loads normally. Crawlers do not execute JavaScript, so they just read the meta tags.

Making file thumbnails publicly accessible

File: backend/src/app/http/assets.clj.

Crawlers fetch og:image anonymously, so the thumbnail asset must be served without authentication. The assets handler decides per storage bucket whether auth is required; with this feature the file-thumbnail bucket is treated as public only while the link-unfurl flag is enabled:

(defn- public-bucket?
  [bucket]
  (or (contains? public-buckets bucket)
      (and (= "file-thumbnail" bucket)
           (contains? cf/flags :link-unfurl))))

With the flag disabled, file-thumbnail objects keep requiring an authenticated profile with access to the file, as before.

The feature flag

Defined in common/src/app/common/flags.cljc as :link-unfurl, listed in the varia set and not included in the default flags. Enable it on the backend with:

export PENPOT_FLAGS="$PENPOT_FLAGS enable-link-unfurl"

It is a backend-only decision point; the frontend URL mirroring is always active (it is harmless on its own), and the nginx crawler routing is also unconditional — with the flag off the endpoint simply serves the generic metadata.

Security considerations

Enabling link-unfurl deliberately trades some privacy for shareability:

• File names become readable by anyone who knows the file id (the /unfurl endpoint does no permission check).
• Dashboard thumbnails become downloadable by anyone who knows the media id (the file-thumbnail bucket becomes public).

Both ids are random UUIDs, so they are not enumerable, but this is knowledge-of-the-id access, not real authorization. This is the standard trade-off that link preview features make; it is the reason the flag is off by default and should be documented to self-hosters before they enable it.

The unfurl page also sets robots: noindex to keep search engines from indexing these preview pages, and responses are marked non-cacheable.

Testing it locally (devenv)

1. Make sure the devenv nginx picked up the config (restart the devenv, or nginx -s reload inside the container, if it predates these changes).

2. Enable the flag before starting the backend REPL:

   export PENPOT_FLAGS="$PENPOT_FLAGS enable-link-unfurl"
   

3. In the browser (http://localhost:3449), open a file in the workspace and go back to the dashboard — leaving the workspace is what generates the dashboard thumbnail. Verify the address bar now shows ?file-id=... before the #.

4. Hit the endpoint directly (bypasses the user-agent detection):

   curl "http://localhost:3449/unfurl?file-id=<FILE_ID>"
   

   Expect HTML with og:title containing the file name and og:image pointing to /assets/by-id/<media-id> (or the default image if the file has no thumbnail yet).

5. Simulate a real crawler against the root, exercising the full nginx → rewrite → backend path:

   curl -A "Slackbot-LinkExpanding 1.0" "http://localhost:3449/?file-id=<FILE_ID>"
   

   The same URL with a normal user-agent must return the SPA index.html.

6. Verify the thumbnail is public:

   curl -I "http://localhost:3449/assets/by-id/<MEDIA_ID>"
   

   Expect 200 without any session cookie while the flag is on, and 401 with the flag off (restart the backend after changing flags).

7. To see the actual preview card rendered by Slack/Discord you need a publicly reachable URL (og:image is built from PENPOT_PUBLIC_URI), so use a tunnel such as ngrok; for local verification the curl checks above are enough.

Automated tests

• backend/test/backend_tests/http_unfurl_test.clj — endpoint behavior: default context, file with/without thumbnail, non-existent and malformed file ids, project and team links, and flag disabled.
• backend/test/backend_tests/http_assets_test.clj (objects-handler-file-thumbnail-bucket-link-unfurl-flag) — the file-thumbnail bucket is public only while the flag is enabled.
• frontend/test/frontend_tests/router_test.cljs — match->context-params priority and legacy path-params support.

Relevant files

File	Role
backend/src/app/http/unfurl.clj	/unfurl handler: flag check, DB lookup, template rendering
backend/resources/app/templates/unfurl.tmpl	Open Graph HTML template + human redirect script
backend/src/app/http/assets.clj	Makes file-thumbnail bucket public under the flag
backend/src/app/http.clj, backend/src/app/main.clj	Route registration and system wiring
common/src/app/common/flags.cljc	:link-unfurl flag definition
frontend/src/app/main/router.cljs	Mirrors context ids on the query string on navigation
docker/devenv/files/nginx.conf	Devenv crawler detection and /unfurl routing
docker/images/files/nginx.conf.template	Same routing for the production image