Public: anyone can read this; the crew can change it.
The forge toolbar in an app or preview can be dismissed for a week and comes back by itself #14493
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/14463-the-forge-toolbar-in-an-app-or-preview-c → main 6 commits fork 2 threads · 2 unresolved
8 files
changed +131
−7
docs/APPS.md +1
| @@ -147,6 +147,7 @@ Under the box, four starter sentences are plain links (no script): | ||
| 147 | 147 | the declared type, and keeps the file under `FORGE_APP_DATA/note-pictures`. |
| 148 | 148 | The issue page shows it from `/:owner/:name/issues/:n/picture`, which answers |
| 149 | 149 | exactly those who can read the issue (a sealed report gives the not-found). |
| 150 | - **The pill can be dismissed for a week.** "Hide for 7 days" in the panel sets the first-party cookie `forge-toolbar-hidden=1` (Path=/, SameSite=Lax, 7 days, no personal data) on the app's host; the proxy reads that cookie as it serves the page and the pill comes up as a small tab that restores it in one tap. The host is fixed-position, so hiding or showing shifts no layout; the pill is script-added, so without JavaScript nothing hides. | |
| 150 | 151 | - **The forge pill acts.** The pill the proxy adds to an app's pages |
| 151 | 152 | (`"toolbar": false` in `forge.json` turns it off; to write it in, the proxy asks the app for the page uncompressed, so a page that carries the pill goes out without gzip) links to a forge page, |
| 152 | 153 | `/:owner/:name/toolbar?env=production|pull-N`, opened in a tab of its own: the |
src/apps/proxy.ts +18 −2
| @@ -78,7 +78,7 @@ import { stepsOf } from "../core/review_steps.ts"; | ||
| 78 | 78 | import { TOUR_ASSET_PATH, tourResponse } from "./tour.ts"; |
| 79 | 79 | import { behindDefault } from "./pill_behind.ts"; |
| 80 | 80 | import { repoDir } from "../git/repos.ts"; |
| 81 | import { cspNonce, htmlAnswer, readPage, rewritable, TOOLBAR_ASSET_PATH, TOOLBAR_ASSET_PREFIX, toolbarResponse, withToolbar, type PillWhere } from "./toolbar.ts"; | |
| 81 | import { cspNonce, HIDE_COOKIE, HIDE_PATH, HIDE_SECONDS, htmlAnswer, readPage, rewritable, TOOLBAR_ASSET_PATH, TOOLBAR_ASSET_PREFIX, toolbarResponse, withToolbar, type PillWhere } from "./toolbar.ts"; | |
| 82 | 82 | import { COMMENT_ASSET_PATH, commentResponse } from "./toolbar_comment.ts"; |
| 83 | 83 | |
| 84 | 84 | const proxySecure = (request: Request, url: URL, forgeUrl: string): boolean => |
| @@ -1139,6 +1139,19 @@ export async function proxyApp( | ||
| 1139 | 1139 | }), |
| 1140 | 1140 | ); |
| 1141 | 1141 | } |
| 1142 | // The visitor's dismissal of the toolbar: a same-origin POST sets or clears the forge's flag | |
| 1143 | // cookie. A request with no sec-fetch-site is refused too, so only a browser's own page can ask. | |
| 1144 | if (url.pathname === HIDE_PATH && !target.nested) { | |
| 1145 | const site = request.headers.get("sec-fetch-site"); | |
| 1146 | if (request.method !== "POST" || site !== "same-origin") return notFound(); | |
| 1147 | const on = url.searchParams.get("on") === "1"; | |
| 1148 | const secure = proxySecure(request, url, runtime.options.forgeUrl); | |
| 1149 | const headers = { | |
| 1150 | "set-cookie": setCookie(HIDE_COOKIE, on ? "1" : "", { maxAge: on ? HIDE_SECONDS : 0, secure }), | |
| 1151 | "cache-control": "no-store", | |
| 1152 | }; | |
| 1153 | return withPhases(request, securityFloor(new Response(null, { status: 204, headers }))); | |
| 1154 | } | |
| 1142 | 1155 | // The pill's fourth door: who of the crew is working on this app now, |
| 1143 | 1156 | // for the person the app's own grant names, read once as the pill opens. |
| 1144 | 1157 | if (url.pathname === "/__forge/crew" && !target.nested) { |
| @@ -1518,11 +1531,14 @@ export async function proxyApp( | ||
| 1518 | 1531 | ? mintProof(grantCookie, request.headers.get("host") ?? "") |
| 1519 | 1532 | : undefined; |
| 1520 | 1533 | if (proof !== undefined) out.set("cache-control", "private, no-store"); |
| 1534 | const dismissed = cookieValue(request, HIDE_COOKIE) === "1"; | |
| 1535 | // Dismissed or not, the page differs by the cookie, so every copy says so. | |
| 1536 | out.append("vary", "cookie"); | |
| 1521 | 1537 | const page = timePhase(request, "rewrite", () => |
| 1522 | 1538 | withToolbar( |
| 1523 | 1539 | bytes, |
| 1524 | 1540 | runtime.options.forgeUrl, |
| 1525 | pillWhere(runtime, target, vouched?.who), | |
| 1541 | { ...pillWhere(runtime, target, vouched?.who), ...(dismissed ? { hidden: true } : {}) }, | |
| 1526 | 1542 | proof, |
| 1527 | 1543 | cspNonce(out.get("content-security-policy")), |
| 1528 | 1544 | ), |
src/apps/toolbar.ts +39
| @@ -37,6 +37,14 @@ export const FRESHNESS_WORDS = { | ||
| 37 | 37 | */ |
| 38 | 38 | export const PREVIEW_WAITS = "This preview uses empty data until a writer approves the pull"; |
| 39 | 39 | |
| 40 | /** | |
| 41 | * The cookie a visitor's dismissal is kept in: the forge's own name, one flag, no personal data. | |
| 42 | */ | |
| 43 | export const HIDE_PATH = "/__forge/hide"; | |
| 44 | export const HIDE_COOKIE = "forge-toolbar-hidden"; | |
| 45 | /** How long a dismissal lasts: 7 days, in seconds. */ | |
| 46 | export const HIDE_SECONDS = 7 * 24 * 60 * 60; | |
| 47 | ||
| 40 | 48 | /** |
| 41 | 49 | * The client, as plain source: no `eval`, no inline handlers. Its comments are for readers here. |
| 42 | 50 | */ |
| @@ -582,6 +590,30 @@ const toolbarSource = `(function () { | ||
| 582 | 590 | ring(x); |
| 583 | 591 | x.addEventListener("click", function () { set(false); pill.focus(); }); |
| 584 | 592 | panel.appendChild(x); |
| 593 | // Dismissed for a week: the forge sets its own cookie; the page's are never touched here. | |
| 594 | var gone = document.createElement("button"); | |
| 595 | gone.type = "button"; | |
| 596 | gone.textContent = "Hide for 7 days"; | |
| 597 | gone.style.cssText = "all:unset;box-sizing:border-box;cursor:pointer;min-height:44px;line-height:44px;opacity:.85;text-decoration:underline"; | |
| 598 | ring(gone); | |
| 599 | panel.appendChild(gone); | |
| 600 | var tab = document.createElement("button"); | |
| 601 | tab.type = "button"; | |
| 602 | tab.textContent = "\\u2692"; | |
| 603 | tab.setAttribute("aria-label", "Show the forge toolbar"); | |
| 604 | tab.style.cssText = "all:unset;box-sizing:border-box;cursor:pointer;width:28px;height:44px;border-radius:8px;background:#1f2328;color:#fff;text-align:center;line-height:44px;font-size:14px;opacity:.6;display:none"; | |
| 605 | ring(tab); | |
| 606 | function hide(on) { | |
| 607 | call("/__forge/hide?on=" + (on ? 1 : 0), { method: "POST", credentials: "same-origin" }).catch(function () {}); | |
| 608 | set(false); | |
| 609 | pill.style.display = on ? "none" : ""; | |
| 610 | tab.style.display = on ? "block" : "none"; | |
| 611 | (on ? tab : pill).focus(); | |
| 612 | } | |
| 613 | gone.addEventListener("click", function () { hide(true); }); | |
| 614 | tab.addEventListener("click", function () { hide(false); }); | |
| 615 | // The forge read the cookie as it served the page and said so in data-hidden. | |
| 616 | if (d.hidden === "1") { pill.style.display = "none"; tab.style.display = "block"; } | |
| 585 | 617 | panel.style.display = "none"; |
| 586 | 618 | function set(open) { |
| 587 | 619 | panel.hidden = !open; |
| @@ -637,6 +669,7 @@ const toolbarSource = `(function () { | ||
| 637 | 669 | }); |
| 638 | 670 | box.appendChild(pill); |
| 639 | 671 | box.appendChild(panel); |
| 672 | box.appendChild(tab); | |
| 640 | 673 | root.appendChild(box); |
| 641 | 674 | (document.body || document.documentElement).appendChild(host); |
| 642 | 675 | })(); |
| @@ -737,6 +770,11 @@ export type PillWhere = { | ||
| 737 | 770 | * record. |
| 738 | 771 | */ |
| 739 | 772 | serving?: { oid: string; at: string; change?: string; behind?: string }; |
| 773 | /** | |
| 774 | * The visitor dismissed the toolbar (`HIDE_COOKIE` came with the request): the page shows its tab | |
| 775 | * only. | |
| 776 | */ | |
| 777 | hidden?: boolean; | |
| 740 | 778 | /** The pull carries a review script: its preview adds the guided review (`apps/tour.ts`). */ |
| 741 | 779 | tour?: TourWhere; |
| 742 | 780 | }; |
| @@ -808,6 +846,7 @@ export function toolbarTag( | ||
| 808 | 846 | ["behind", where.behind === true ? "1" : undefined], |
| 809 | 847 | ["deploying", where.deploying === true ? "1" : undefined], |
| 810 | 848 | ["waits", where.waits === true ? PREVIEW_WAITS : undefined], |
| 849 | ["hidden", where.hidden === true ? "1" : undefined], | |
| 811 | 850 | ] |
| 812 | 851 | .filter((pair): pair is [string, string] => pair[1] !== undefined) |
| 813 | 852 | .map(([k, v]) => ` data-${k}="${escapeAttr(v)}"`) |
test/apps-crew-pill.test.ts +15
| @@ -197,6 +197,21 @@ describe("the crew line", () => { | ||
| 197 | 197 | end(run.id); |
| 198 | 198 | }); |
| 199 | 199 | |
| 200 | test("the dismissal door sets and clears the flag cookie, on a same-origin POST only", async () => { | |
| 201 | const at = (method: string, on: string, site?: string) => | |
| 202 | fetch(`${servers.url}/__forge/hide?on=${on}`, { | |
| 203 | method, | |
| 204 | headers: { host: `notes.${DOMAIN}`, ...(site === undefined ? {} : { "sec-fetch-site": site }) }, | |
| 205 | }); | |
| 206 | const set = await at("POST", "1", "same-origin"); | |
| 207 | expect(set.status).toBe(204); | |
| 208 | expect(set.headers.get("set-cookie")).toBe("forge-toolbar-hidden=1; Path=/; HttpOnly; SameSite=Lax; Max-Age=604800"); | |
| 209 | expect(set.headers.get("x-content-type-options")).toBe("nosniff"); | |
| 210 | expect((await at("POST", "0", "same-origin")).headers.get("set-cookie")).toContain("Max-Age=0"); | |
| 211 | expect((await at("POST", "1", "cross-site")).status).toBe(404); | |
| 212 | expect((await at("GET", "1")).status).toBe(404); | |
| 213 | }); | |
| 214 | ||
| 200 | 215 | test("the script asks once, same-origin, and never reads the page or its cookies", () => { |
| 201 | 216 | expect(toolbarJs).toContain("/__forge/crew"); |
| 202 | 217 | // One fetch is the crew line; the other is `call`, the feedback door's |
test/apps-toolbar-nonce.test.ts +14
| @@ -117,3 +117,17 @@ test("a malformed nonce copies nothing", async () => { | ||
| 117 | 117 | test("no nonce in the policy leaves the tag as before", async () => { |
| 118 | 118 | expect(await tagOf("/none")).not.toContain("nonce="); |
| 119 | 119 | }); |
| 120 | ||
| 121 | test("a served page carries data-hidden only with the dismissal cookie, and varies on cookie either way", async () => { | |
| 122 | const at = (cookie?: string) => | |
| 123 | fetch(`${servers.url}/`, { | |
| 124 | headers: { host: `notes.${DOMAIN}`, accept: "text/html", ...(cookie ? { cookie } : {}) }, | |
| 125 | redirect: "manual", | |
| 126 | }); | |
| 127 | const plain = await at(); | |
| 128 | expect(await plain.text()).not.toContain("data-hidden"); | |
| 129 | expect(plain.headers.get("vary")).toContain("cookie"); | |
| 130 | const hidden = await at("forge-toolbar-hidden=1"); | |
| 131 | expect(await hidden.text()).toContain('data-hidden="1"'); | |
| 132 | expect(hidden.headers.get("vary")).toContain("cookie"); | |
| 133 | }); |
test/apps-toolbar-state.test.ts +6 −4
| @@ -26,12 +26,14 @@ test("no landed change leaves the attribute out and the pill says only since whe | ||
| 26 | 26 | expect(boot(null, 400, 800, { ...set, change: "Fix <b>the</b> thing" }).texts()).toContain("Live since 4 min ago \u00b7 Fix <b>the</b> thing"); |
| 27 | 27 | }); |
| 28 | 28 | |
| 29 | // The script's size at the commit this change branched from (bfb7e8dc2), pinned so the delta is | |
| 30 | // real. | |
| 31 | const BASE_SCRIPT_BYTES = 22623; | |
| 29 | // The script's size on main (b74af663e) just before the 7-day dismissal (#14463), pinned so the | |
| 30 | // delta is real: 22918 bytes. The dismissal's own button, restoring tab and request are 1144 of | |
| 31 | // the growth on top, allowed here by name; anything beyond that still has to stay under 300. | |
outdated
Re-pinning the base to 23800 makes the 300-byte guard meaningless for this change and the comment's numbers contradict each other. Keep the real base, and widen the allowance with a stated reason. |
||
| 32 | const BASE_SCRIPT_BYTES = 22918; | |
| 33 | const DISMISSAL_ALLOWANCE = 1150; | |
| 32 | 34 | |
| 33 | 35 | test("the addition stays under 300 bytes", () => { |
| 34 | expect(Buffer.byteLength(toolbarJs) - BASE_SCRIPT_BYTES).toBeLessThan(300); | |
| 36 | expect(Buffer.byteLength(toolbarJs) - BASE_SCRIPT_BYTES).toBeLessThan(300 + DISMISSAL_ALLOWANCE); | |
| 35 | 37 | const tag = toolbarTag("https://forge.test", where("x".repeat(CHANGE_MAX)), "p", "n"); |
| 36 | 38 | const bare = toolbarTag("https://forge.test", where(), "p", "n"); |
| 37 | 39 | expect(Buffer.byteLength(tag) - Buffer.byteLength(bare)).toBeLessThan(300); |
test/cookie-flags.test.ts +2 −1
| @@ -63,6 +63,7 @@ const COOKIES: Record<string, Spelled> = { | ||
| 63 | 63 | path: { path: "/signin/parent", why: "the OpenID state is read only by /signin/parent/callback; no other page should carry it" }, |
| 64 | 64 | }, |
| 65 | 65 | "src/apps/proxy.ts grantCookieName(target)": { name: /^forge_grant_[0-9a-z]{8}$/, lines: 2, door: "app grant" }, |
| 66 | "src/apps/proxy.ts HIDE_COOKIE": { name: "forge-toolbar-hidden", lines: 1, why: "set by a same-origin POST to the toolbar door, tested in test/toolbar-hide.test.ts; HttpOnly, Lax, Secure over https" }, | |
| 66 | 67 | "src/apps/feedback.ts VISITOR_COOKIE": { name: "forge_visitor", lines: 1, door: "app note" }, |
| 67 | 68 | "src/perf/visitor_id.ts COOKIE": { name: "forge_visitor", lines: 1, door: "page-view beacon" }, |
| 68 | 69 | "src/web/gift_cookie.ts NAME": { name: "forge_gift", lines: 2, door: "gift link" }, |
| @@ -103,7 +104,7 @@ const WALKED: Record<string, number> = { | ||
| 103 | 104 | "src/http/server.ts": 1, // the mode switch |
| 104 | 105 | "src/http/session_renewal.ts": 1, // a renewed session re-set on a page read |
| 105 | 106 | "src/http/rp.ts": 6, // parent sign-in and link: state cookie set and cleared |
| 106 | "src/apps/proxy.ts": 2, // app grant, app sign-out | |
| 107 | "src/apps/proxy.ts": 3, // app grant, app sign-out, toolbar dismissal | |
| 107 | 108 | "src/apps/feedback.ts": 2, // a stranger's note on an app host, both answers that may carry the visitor cookie |
| 108 | 109 | "src/web/pages/passkeys.ts": 5, // import, passkey sign-in, passkey add/recovery-link sign-in, access-link sign-in (+1 mention) |
| 109 | 110 | "src/web/pages/site.ts": 4, // sessionCookie() itself and its uses: password sign-in/sign-up, logout; the theme cookie |
test/toolbar-hide.test.ts added +36
| @@ -0,0 +1,36 @@ | ||
| 1 | /** The toolbar can be dismissed for a week and restored in one tap (#14463). */ | |
| 2 | import { expect, test } from "bun:test"; | |
| 3 | import { HIDE_COOKIE, HIDE_PATH, HIDE_SECONDS, toolbarJs, toolbarTag } from "../src/apps/toolbar.ts"; | |
| 4 | ||
| 5 | test("the snippet carries a dismiss control and a restoring tab", () => { | |
| 6 | expect(toolbarJs).toContain("Hide for 7 days"); | |
| 7 | expect(toolbarJs).toContain("Show the forge toolbar"); | |
| 8 | }); | |
| 9 | ||
| 10 | test("the cookie is namespaced and lasts 7 days; the script never touches cookies", () => { | |
| 11 | expect(HIDE_COOKIE).toMatch(/^forge-toolbar-/); | |
| 12 | expect(HIDE_SECONDS).toBe(7 * 24 * 60 * 60); | |
| 13 | expect(toolbarJs).not.toContain("document.cookie"); | |
| 14 | expect(toolbarJs).toContain(HIDE_PATH); | |
| 15 | expect(toolbarJs).toContain("position:fixed"); | |
| 16 | }); | |
| 17 | ||
| 18 | test("a dismissed visitor's tag says so, and others' does not", () => { | |
| 19 | const where = { app: "notes", env: "production" }; | |
| 20 | expect(toolbarTag("https://forge.test", { ...where, hidden: true })).toContain('data-hidden="1"'); | |
| 21 | expect(toolbarTag("https://forge.test", where)).not.toContain("data-hidden"); | |
| 22 | }); | |
| 23 | ||
| 24 | test("the cookie's attributes are pinned: HttpOnly, SameSite=Lax, Path=/, a week, cleared at 0", async () => { | |
| 25 | const { setCookie } = await import("../src/auth/cookies.ts"); | |
| 26 | const on = setCookie(HIDE_COOKIE, "1", { maxAge: HIDE_SECONDS, secure: false }); | |
| 27 | expect(on).toBe(`${HIDE_COOKIE}=1; Path=/; HttpOnly; SameSite=Lax; Max-Age=604800`); | |
| 28 | expect(setCookie(HIDE_COOKIE, "", { maxAge: 0, secure: true })).toContain("Max-Age=0"); | |
| 29 | expect(setCookie(HIDE_COOKIE, "1", { maxAge: HIDE_SECONDS, secure: true })).toContain("Secure"); | |
| 30 | }); | |
| 31 | ||
| 32 | test("the restoring tab is fixed and shown by the server's word, not a cookie read", () => { | |
| 33 | expect(toolbarJs).toContain("position:fixed"); | |
| 34 | expect(toolbarJs).toContain('d.hidden === "1"'); | |
| 35 | expect(toolbarJs).toContain("tab.style.display"); | |
| 36 | }); |
new above
offline
Vary: cookie only when dismissed leaves the other variant uncacheable-safe only by luck. Add it for every page that gets the toolbar.