feat: Allow document unfurling with shareId (outline#12007)

* feat: Allow document unfurling with shareId

* fix: Handle collection shares, share-scoped URLs, and unauthenticated unfurls

- Return 204 instead of 404 for collection shares without a document
- Use share-scoped URL in unfurl response so hover previews stay within
  the share context
- Add test coverage for unauthenticated share URL unfurling

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* perf: Only resolve team from context for non-UUID share identifiers

loadPublicShare only requires teamId when the share identifier is a
slug (urlId), not a UUID. Skip the getTeamFromContext DB lookup on the
common UUID path.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: tommoor

app/components/HoverPreview/HoverPreviewDocument.tsx

@@ -26,7 +26,7 @@ const HoverPreviewDocument = React.forwardRef(function HoverPreviewDocument_(
           <ErrorBoundary showTitle={false} reloadOnChunkMissing={false}>
             <Flex column gap={2}>
               <Title>{title}</Title>
-              <Info>{lastActivityByViewer}</Info>
+              {lastActivityByViewer && <Info>{lastActivityByViewer}</Info>}
               <Description as="div">
                 <React.Suspense fallback={<div />}>
                   <Editor

server/presenters/unfurl.ts

@@ -92,14 +92,17 @@ const presentDocument = (
   data: Record<string, any>
 ): UnfurlResponse[UnfurlResourceType.Document] => {
   const document: Document = data.document;
-  const viewer: User = data.viewer;
+  const viewer: User | undefined = data.viewer;
+  const url: string | undefined = data.url;
   return {
-    url: document.url,
+    url: url ?? document.url,
     type: UnfurlResourceType.Document,
     id: document.id,
     title: document.titleWithDefault,
     summary: document.getSummary(),
-    lastActivityByViewer: presentLastActivityInfoFor(document, viewer),
+    lastActivityByViewer: viewer
+      ? presentLastActivityInfoFor(document, viewer)
+      : undefined,
   };
 };
 

server/routes/api/urls/urls.test.ts

@@ -1,7 +1,12 @@
 import { UnfurlResourceType } from "@shared/types";
 import env from "@server/env";
 import type { User } from "@server/models";
-import { buildDocument, buildUser } from "@server/test/factories";
+import {
+  buildCollection,
+  buildDocument,
+  buildShare,
+  buildUser,
+} from "@server/test/factories";
 import { getTestServer } from "@server/test/support";
 import Iframely from "plugins/iframely/server/iframely";
 
@@ -157,6 +162,120 @@ describe("#urls.unfurl", () => {
     expect(body.id).toEqual(document.id);
   });
 
+  it("should succeed with status 200 ok when valid share url is supplied", async () => {
+    const document = await buildDocument({
+      teamId: user.teamId,
+    });
+    const share = await buildShare({
+      teamId: user.teamId,
+      userId: user.id,
+      documentId: document.id,
+      published: true,
+    });
+
+    const res = await server.post("/api/urls.unfurl", {
+      body: {
+        token: user.getJwtToken(),
+        url: `${env.URL}/s/${share.id}/doc/${document.urlId}`,
+      },
+    });
+    const body = await res.json();
+    expect(res.status).toEqual(200);
+    expect(body.type).toEqual(UnfurlResourceType.Document);
+    expect(body.title).toEqual(document.titleWithDefault);
+    expect(body.id).toEqual(document.id);
+  });
+
+  it("should succeed with status 200 ok when share url with urlId is supplied", async () => {
+    const document = await buildDocument({
+      teamId: user.teamId,
+    });
+    const share = await buildShare({
+      teamId: user.teamId,
+      userId: user.id,
+      documentId: document.id,
+      urlId: "test-share",
+      published: true,
+    });
+
+    const res = await server.post("/api/urls.unfurl", {
+      body: {
+        token: user.getJwtToken(),
+        url: `${env.URL}/s/${share.urlId}/doc/${document.urlId}`,
+      },
+    });
+    const body = await res.json();
+    expect(res.status).toEqual(200);
+    expect(body.type).toEqual(UnfurlResourceType.Document);
+    expect(body.title).toEqual(document.titleWithDefault);
+    expect(body.id).toEqual(document.id);
+  });
+
+  it("should succeed with status 200 ok for share url without authentication", async () => {
+    const document = await buildDocument({
+      teamId: user.teamId,
+    });
+    const share = await buildShare({
+      teamId: user.teamId,
+      userId: user.id,
+      documentId: document.id,
+      published: true,
+    });
+
+    const res = await server.post("/api/urls.unfurl", {
+      body: {
+        url: `${env.URL}/s/${share.id}/doc/${document.urlId}`,
+      },
+    });
+    const body = await res.json();
+    expect(res.status).toEqual(200);
+    expect(body.type).toEqual(UnfurlResourceType.Document);
+    expect(body.title).toEqual(document.titleWithDefault);
+    expect(body.id).toEqual(document.id);
+  });
+
+  it("should return share-scoped url in unfurl response", async () => {
+    const document = await buildDocument({
+      teamId: user.teamId,
+    });
+    const share = await buildShare({
+      teamId: user.teamId,
+      userId: user.id,
+      documentId: document.id,
+      published: true,
+    });
+
+    const res = await server.post("/api/urls.unfurl", {
+      body: {
+        token: user.getJwtToken(),
+        url: `${env.URL}/s/${share.id}/doc/${document.urlId}`,
+      },
+    });
+    const body = await res.json();
+    expect(res.status).toEqual(200);
+    expect(body.url).toContain(`/s/${share.id}/doc/`);
+  });
+
+  it("should return 204 for collection share url without document", async () => {
+    const collection = await buildCollection({
+      teamId: user.teamId,
+    });
+    const share = await buildShare({
+      teamId: user.teamId,
+      userId: user.id,
+      collectionId: collection.id,
+      published: true,
+    });
+
+    const res = await server.post("/api/urls.unfurl", {
+      body: {
+        token: user.getJwtToken(),
+        url: `${env.URL}/s/${share.id}`,
+      },
+    });
+    expect(res.status).toEqual(204);
+  });
+
   it("should succeed with status 200 ok for a valid external url", async () => {
     (Iframely.requestResource as jest.Mock).mockResolvedValue(
       Promise.resolve({

server/routes/api/urls/urls.ts

@@ -1,17 +1,23 @@
 import dns from "node:dns";
 import Router from "koa-router";
 import { traceFunction } from "@server/logging/tracing";
+import isUUID from "validator/lib/isUUID";
 import { MentionType, UnfurlResourceType } from "@shared/types";
 import { getBaseDomain, parseDomain } from "@shared/utils/domains";
 import parseDocumentSlug from "@shared/utils/parseDocumentSlug";
 import parseMentionUrl from "@shared/utils/parseMentionUrl";
-import { isInternalUrl } from "@shared/utils/urls";
-import { NotFoundError, ValidationError } from "@server/errors";
+import { isInternalUrl, parseShareIdFromUrl } from "@shared/utils/urls";
+import {
+  AuthenticationError,
+  NotFoundError,
+  ValidationError,
+} from "@server/errors";
 import auth from "@server/middlewares/authentication";
 import { rateLimiter } from "@server/middlewares/rateLimiter";
 import validate from "@server/middlewares/validate";
 import { Document, Share, Team, User, Group, GroupUser } from "@server/models";
 import { authorize, can } from "@server/policies";
+import { loadPublicShare } from "@server/commands/shareLoader";
 import presentUnfurl from "@server/presenters/unfurl";
 import type { APIContext, Unfurl } from "@server/types";
 import { CacheHelper, type CacheResult } from "@server/utils/CacheHelper";
@@ -22,6 +28,7 @@ import {
   checkEmbeddability,
   type EmbedCheckResult,
 } from "@server/utils/embeds";
+import { getTeamFromContext } from "@server/utils/passport";
 import * as T from "./schema";
 import { MAX_AVATAR_DISPLAY } from "@shared/constants";
 import { Day } from "@shared/utils/time";
@@ -32,13 +39,54 @@ const plugins = PluginManager.getHooks(Hook.UnfurlProvider);
 router.post(
   "urls.unfurl",
   rateLimiter(RateLimiterStrategy.OneThousandPerHour),
-  auth(),
+  auth({ optional: true }),
   validate(T.UrlsUnfurlSchema),
   async (ctx: APIContext<T.UrlsUnfurlReq>) => {
     const { url, documentId } = ctx.input.body;
-    const { user: actor } = ctx.state.auth;
     const urlObj = new URL(url);
 
+    // Public share URLs – does not require authentication
+    if (isInternalUrl(url)) {
+      const shareId = parseShareIdFromUrl(url);
+
+      if (shareId) {
+        const actor = ctx.state.auth.user;
+        // teamId is only needed when the share identifier is a slug, not a UUID
+        let teamId: string | undefined = actor?.teamId;
+        if (!teamId && !isUUID(shareId)) {
+          const teamFromCtx = await getTeamFromContext(ctx, {
+            includeStateCookie: false,
+          });
+          teamId = teamFromCtx?.id;
+        }
+        const previewDocumentId = parseDocumentSlug(url);
+        const { share, document } = await loadPublicShare({
+          id: shareId,
+          documentId: previewDocumentId,
+          teamId,
+        });
+
+        if (!document) {
+          ctx.response.status = 204;
+          return;
+        }
+
+        ctx.body = await presentUnfurl({
+          type: UnfurlResourceType.Document,
+          document,
+          viewer: actor,
+          url: `${share.canonicalUrl}/doc/${document.url.replace("/doc/", "")}`,
+        });
+        return;
+      }
+    }
+
+    // Everything below requires authentication
+    const { user: actor } = ctx.state.auth;
+    if (!actor) {
+      throw AuthenticationError();
+    }
+
     // Mentions
     if (urlObj.protocol === "mention:") {
       if (!documentId) {
@@ -113,9 +161,9 @@ router.post(
     if (isInternalUrl(url) || parseDomain(url).host === actor.team.domain) {
       const previewDocumentId = parseDocumentSlug(url);
       if (previewDocumentId) {
-        const document = previewDocumentId
-          ? await Document.findByPk(previewDocumentId, { userId: actor.id })
-          : undefined;
+        const document = await Document.findByPk(previewDocumentId, {
+          userId: actor.id,
+        });
         if (!document) {
           throw NotFoundError("Document does not exist");
         }
@@ -128,6 +176,7 @@ router.post(
         });
         return;
       }
+
       ctx.response.status = 204;
       return;
     }

shared/types.ts

@@ -591,7 +591,7 @@ export type UnfurlResponse = {
     /** Document summary */
     summary: string;
     /** Viewer's last activity on this document */
-    lastActivityByViewer: string;
+    lastActivityByViewer?: string;
   };
   [UnfurlResourceType.Issue]: {
     /** The resource type */

shared/utils/urls.test.ts

@@ -190,6 +190,40 @@ describe("sanitizeUrl", () => {
   });
 });
 
+describe("parseShareIdFromUrl", () => {
+  it("should return share id from url with doc path", () => {
+    expect(
+      urlsUtils.parseShareIdFromUrl(
+        "https://app.example.com/s/my-share/doc/test-abc123"
+      )
+    ).toBe("my-share");
+  });
+
+  it("should return share uuid from url", () => {
+    expect(
+      urlsUtils.parseShareIdFromUrl(
+        "https://app.example.com/s/2767ba0e-ac5c-4533-b9cf-4f5fc456600e/doc/test-abc123"
+      )
+    ).toBe("2767ba0e-ac5c-4533-b9cf-4f5fc456600e");
+  });
+
+  it("should return share id when no doc path is present", () => {
+    expect(
+      urlsUtils.parseShareIdFromUrl("https://app.example.com/s/my-share")
+    ).toBe("my-share");
+  });
+
+  it("should return undefined for non-share urls", () => {
+    expect(
+      urlsUtils.parseShareIdFromUrl("https://app.example.com/doc/test-abc123")
+    ).toBeUndefined();
+  });
+
+  it("should return undefined for invalid urls", () => {
+    expect(urlsUtils.parseShareIdFromUrl("not a url")).toBeUndefined();
+  });
+});
+
 describe("#urlRegex", () => {
   it("should return undefined for invalid urls", () => {
     expect(urlRegex(undefined)).toBeUndefined();

shared/utils/urls.ts

@@ -221,6 +221,39 @@ export function urlRegex(url: string | null | undefined): RegExp | undefined {
   return new RegExp(escapeRegExp(`${urlObj.protocol}//${urlObj.host}`));
 }
 
+/**
+ * Parse the share identifier from a given url.
+ *
+ * @param url The url to parse.
+ * @returns A share identifier or undefined if not found.
+ */
+export function parseShareIdFromUrl(url: string): string | undefined {
+  if (url[0] === "/") {
+    url = `${env.URL}${url}`;
+  }
+
+  let pathname;
+  try {
+    pathname = new URL(url).pathname;
+  } catch (_err) {
+    return;
+  }
+
+  const split = pathname.split("/");
+  const indexOfS = split.indexOf("s");
+
+  if (indexOfS >= 0) {
+    const shareId = split[indexOfS + 1];
+    if (shareId) {
+      // Remove trailing format like .md
+      const dotIndex = shareId.indexOf(".");
+      return dotIndex >= 0 ? shareId.substring(0, dotIndex) : shareId;
+    }
+  }
+
+  return undefined;
+}
+
 /**
  * Extracts LIKELY urls from the given text, note this does not validate the urls.
  *