Standalone bookmark manager (xBrowserSync-compatible) as an installable,
offline-capable PWA.
No browser.bookmarks — the bookmarks live in the PWA's own IndexedDB store, so it
works on iOS/Safari where no host bookmark API exists.
All crypto, API and sync logic comes from
@marksyncorg/core, installed from
GitHub Packages. This repo is the consumer: IndexedDB/local-store adapters, a
plain TS + DOM UI, the service worker and the manifest.
@marksyncorg/core this repo (adapters)
StorageArea <-- IndexedDbStorageArea (src/adapters/indexeddb-storage.ts)
BookmarkProvider <-- LocalBookmarksProvider (src/adapters/local-bookmarks.ts)
SyncEngine / crypto / api client / bookmark model
src/main.ts wires the adapters into the SyncEngine; src/ui/app.ts is the
framework-free view (login, list + search, add form, bookmarklet setting).
src/adapters/page-metadata.ts reads what a page says about itself, which is what
the add form suggests as a description and tags.
Core sanitises every bookmark tree that crosses a trust boundary — a decrypted
sync payload, a backup file, the tree it is about to upload. Its SECURITY.md
names three things a consuming app has to handle itself; here is where each one
lands:
- Check URLs before rendering. The list renders from the local IndexedDB
store, which core never sees, so
bookmarkTitleinsrc/ui/app.tsrunsisSafeBookmarkUrland renders anything else as inert text instead of an<a href>. Since core 0.7.0 that is a narrower question than what the sync carries, so the row has three states, not two: an ordinary web address is a link; achrome://,about:orfile://bookmark is synced like any other but only a browser can open it, so it renders dimmed and says so; a bookmarklet is inert and excluded from the sync while Sync bookmarklets is off, which is a different fact and reads differently (struck through, "kept on this device but never synced"). The add form and the share hooks reject up front whatever this device will not carry (isSyncableBookmarkUrl, with the same policy): core would silently drop it from the uploaded tree, so a bookmark accepted here would look saved and never reach another device. Filtering is not deletion: since core 0.3.0 an entry already in the store is put back before the destructive write that applies a pulled tree, so it stays on this device indefinitely without ever being uploaded. That is why the row says so rather than just looking broken. - Bookmarklets are opt-in, per device. The card under the add form toggles
syncBookmarklets(core's setting, stored with the rest). Off by default:javascript:anddata:addresses run whatever they contain in whichever context opens them, so a sync anyone else can write would otherwise be a way into every device's bookmark bar. Turning it on widens what is uploaded and accepted, never what is rendered as a link. It has to be on everywhere: a device that has it off sanitises them out of the tree it holds and removes them from the sync the next time it uploads. - The storage area holds the decryption key.
SyncInfo.passwordHashis the AES key, andIndexedDbStorageAreais plain IndexedDB — anything with script access to this origin can decrypt the whole sync. That is inherited xBrowserSync behaviour and cannot change without breaking compatibility, so treat "device or origin compromised" as "sync compromised". - The service is trusted for freshness, not for history. A compromised
service can replay an older, genuinely valid payload and the client will
accept it. Core requires
https(plainhttponly for loopback), which the login form's service URL now goes through.
Two login-time behaviours come from core and surface as ordinary form errors:
the service URL must be https with no query, fragment or embedded credentials,
and the sync ID must be 32 lowercase hex characters (checked before the
250k-iteration key derivation, so a typo fails immediately).
The app reconciles with the service on open, again whenever it comes back to the foreground, and whenever the Sync button is pressed.
The automatic ones run after the list is on screen, never before: the store is on disk, so the bookmarks are drawn from it first and the network is touched afterwards. That ordering is what makes a cold start offline unremarkable, and it is why they fail silently: a device with no connection, or a service that is down, still gets its list and simply does not get an update. A launch that carries a share skips the first one, since saving the shared bookmark already pushes and reconciles.
The foreground one listens on visibilitychange, the event a suspended PWA actually gets
back on, since focus misses a resume that restores the app without focusing a control
and pageshow only fires for a full load or a back/forward restore. On a phone this is
the one that matters: the app is suspended and resumed far more often than it is closed
and reopened. It is also an event that repeats (a tab switch, a share sheet, an unlock),
so an automatic sync keeps a minute away from the previous sync, manual ones included,
and never starts while another is in flight.
No sync rebuilds the view. They refresh the results region and the header line in place, because one can now arrive while the app is sitting in the foreground and it must not take the add form out from under someone filling it in.
The header says when this device last reached the service (2 bookmarks · synced 09:41,
with the full date and time in the title, and the date in the label itself once it is not
today's). That is the half a user cannot guess: a sync that finds nothing to do looks
exactly like one that never ran, so a list that is quietly hours stale would otherwise
read as a fresh one. It is this device's own timestamp, written only by a completed sync
and dropped on logout, not SyncStore.getLastUpdated(), which is the service's revision
stamp and does not move when a sync has nothing to carry.
Browsing shows the container tree as expandable folders (native <details>,
so keyboard and screen readers get the disclosure semantics for free), each
labelled with the number of bookmarks below it. Top-level containers start
open, deeper folders closed; toggles are remembered per folder id — a title
path, not an index — so an add or a sync does not reshuffle what is expanded.
Searching switches the same element to a flat list of matches, each tagged with
its folder path, since a filtered tree hides more than it explains. It matches
titles, URLs, descriptions and tags. Titles and URLs are truncated to one line
(full value in the title attribute) and URLs drop their scheme, which keeps a
long tracking URL from taking three lines.
Both are part of the xBrowserSync bookmark model and neither is browser bookmark
data: no bookmarks API has anywhere to keep them, so they exist only inside the
synced payload. The extension has to hold them in a sidecar beside the browser's
own bookmarks to stop a native round trip from erasing them; the PWA needs no such
thing, because its store is the xBrowserSync tree — LocalBookmarksProvider
reads and writes whole Bookmark nodes, so the metadata is carried by
construction.
A description renders under the URL, clamped to two lines so one verbose entry cannot push the list off the screen, and tags render below it; both feed the search box.
Both are also editable when a bookmark is created, and pre-filled the way the extension pre-fills them, because the moment a bookmark is added is the only moment at which the page can still be asked what it would suggest:
- The add form has a description field (bounded to the model's 300 characters, with
a live count) and a comma-separated tags field. Entering a URL asks the page for its
own
<meta>, with the extension's precedence —og:description, thentwitter:description, thendescription;og:video:tagpluskeywordsfor tags — so both clients suggest the same thing for the same page. Two rules come from the extension too: a suggestion only ever fills a field that is empty, so nothing the user typed is overwritten, and nothing is stored until Add is pressed, which is what the hint under the form says. - The share hooks have no review step to offer, so they take the one piece of
metadata a share sheet can actually carry — its
text, the page's excerpt or the user's selection — and store it as the description. (It used to be used as a fallback title, which is where a whole paragraph occasionally ended up.) A share whose text is just the link again contributes nothing.
Where the two clients genuinely differ is how they see the page, and it is worth being
blunt about it. The extension is on the page: it injects a collector into the active
tab under activeTab and always has the markup. A PWA never is, so the only way to see a
page's <meta> is to fetch it — which CORS usually forbids, since most sites send no
Access-Control-Allow-Origin (no-cors would not help: the response body would be
opaque). So a miss is the common case here, not the exception, and it is treated as an
ordinary outcome: the fields stay empty and nothing claims otherwise. The fetch is
credentials: 'omit' with a 4s timeout, stops reading at </head>, and parses into an
inert DOMParser document, so a third party's HTML is only ever data. The tags the user
does end up with are normalised by core (parseTags), which de-duplicates, sorts and
bounds them — the canonical order both dirty detection and the merge compare by value.
pnpm install # needs a read:packages token (see below)
pnpm dev # vite dev server (SW enabled; no CSP — see above)
pnpm build # typecheck + production build to dist/
pnpm preview # serve the built dist
pnpm test:e2e # Playwright: login -> render -> add -> pull -> offline@marksyncorg/core comes from GitHub Packages, whose npm registry requires
authentication even though the repo is public — unlike ghcr.io, it has no
anonymous read. This is not something the workflow can opt out of: an
unauthenticated GET https://npm.pkg.github.com/@marksyncorg%2Fcore returns 401
regardless of visibility. CI already uses the cheapest thing that satisfies it —
the built-in secrets.GITHUB_TOKEN with permissions: packages: read, not a PAT —
so there is nothing to remove there. The token has to live somewhere pnpm will expand, which is not
this repo's .npmrc (see the note in that file):
pnpm config set '//npm.pkg.github.com/:_authToken' <token with read:packages>Without it pnpm install fails with ERR_PNPM_FETCH_401. You need it to bump the
dependency too: CI installs with --frozen-lockfile, so a version change that did
not regenerate pnpm-lock.yaml fails the build rather than being quietly
re-resolved.
Titles, descriptions and tags are free text, and core deliberately does not strip markup
from them: a bookmark whose title really is <b>x</b> has to keep it, and a client that
rewrote the text would corrupt the sync for every other device. Core bounds and
normalises them — 300 characters for a description, 100 tags of 50 characters — but the
values themselves arrive verbatim, including from another client or a scraped page.
So the guarantee is made where they are rendered, not where they enter. src/ui/app.ts
builds every node with createElement + createTextNode; the repo contains no
innerHTML, insertAdjacentHTML or document.write, so a value is never parsed as
markup. The only attribute that takes a user-controlled value is an <a href>, and it is
gated on isSafeBookmarkUrl (see the list above). Suggested metadata is parsed out of a
third party's HTML in an inert DOMParser document that is never adopted into the page,
so nothing in it runs, requests a subresource or navigates. Two e2e cases pin all of
this with real payloads.
Login inputs go to core: the service URL must be https with no query, fragment or
embedded credentials, and the sync ID must be 32 lowercase hex characters — checked
before it is ever interpolated into a request path.
The second layer, so that a future innerHTML is a console error rather than an exploit.
The policy is served in two forms:
- A real response header in
public/_headers, which is the authoritative one — it can carryframe-ancestors, which a meta tag silently ignores. - A
<meta http-equiv>prepended to the builtindex.htmlbycspMetaTag()invite.config.ts. Not a fallback: this is what makesvite preview, and therefore the e2e suite, actually run under the policy instead of production being the first place it is ever exercised.
Two copies would normally invite drift, so an e2e case reads the built _headers and
asserts its policy equals the meta tag's directive-for-directive, frame-ancestors aside
— a change to one and not the other fails CI. Generating the header file from
vite.config.ts would have removed the second copy, but only by importing node:fs
(this project has no @types/node, and adding one for two calls means a lockfile churn)
or by moving the cache rules out of the file the deploy docs point at. The same case also
asserts that inline and cross-origin <script> are both refused, which is the property
the policy exists for.
script-src 'self' is the directive that does the work: the build emits every script as
a file, so no inline script, no eval and no third-party origin is needed. Two directives
are deliberately looser than they look, and it is better to say so than to imply a
strictness that is not there:
style-src-attr 'unsafe-inline'—index.htmlpaints the brand background on<body>before the stylesheet arrives. Attributes only; no<style>block and no sheet from elsewhere. A browser that does not implement the directive falls back tostyle-srcand drops the attribute, costing a flash of unstyled background and nothing else.connect-srcadmits anyhttps:origin plus loopback. It has to: the sync service is whatever the user enters, and the metadata suggestion fetches arbitrary pages. So the policy guards against script injection, not against exfiltration.
The meta tag is injected on build only. vite dev injects styles as inline <style> and
talks to HMR over a websocket, neither of which this policy allows; a policy relaxed
enough for HMR would not be worth shipping, and a developer's own machine is not the
threat model. (Production is unaffected — it is served the header.)
Alongside the policy, _headers sets X-Frame-Options: DENY,
X-Content-Type-Options: nosniff and Referrer-Policy: no-referrer — the last so that
opening a bookmark never leaks this app's URL to the site being visited.
The e2e suite mocks the xBrowserSync API at the network layer and seeds a sync
blob encrypted with the real core crypto, so it exercises the genuine
decrypt/encrypt path without a live backend. Two cases cover the metadata added when a
bookmark is created: one serves a page whose <meta> tags are readable (the mock
supplies the Access-Control-Allow-Origin a real site would have to) to pin the
precedence, the normalisation and the fill-only-what-is-empty rule; the other pins what
the share hooks do with a shared text. Two more pin the injection boundary: markup in a
title, description and tag rendering as text, and a hostile page failing to inject
through the metadata it suggests. Four further cases pin the URL-scheme
policy: dropped on the way in from the service, rejected by the add form and the
share hook, rendered inert if it is already sitting in the local store, and kept
across a pull that rewrites the whole tree while still being left out of the push
(the consumer-side regression test for
core#3).
public/brand/ holds the MarkSync SVG marks and lockups (on-light and on-dark
variants); public/icons/ holds the rasterized PWA/favicon set exported from
them. Both are committed — nothing generates them at build time. When the brand
assets change upstream, re-export and replace these files; icon-maskable-512.png
is icon-512.png scaled to 80% on the same #0e0e0b field, which is the safe
zone Android's circular mask needs.
The UI follows marksync.org: near-black #0e0e0b field,
#14140f panels on #2a2a22 hairlines, cream #f5f4ec text, lime #c8f542
accent, and square corners throughout (the site uses no border-radius
anywhere). Archivo carries UI text, IBM Plex Mono the labels and metadata — both
declared with system fallbacks rather than fetched from a font CDN, since the
shell must render offline. All of it lives in the custom properties at the top
of src/ui/styles.css, dark first with a light palette (cream #f6f5ee field,
white panels, near-black #17170f text) layered on top for prefers-color-scheme: light and for the header's Auto/Light/Dark toggle, which persists its choice in
localStorage and is the only piece of theme state that isn't plain CSS — see
src/ui/theme.ts. The brand mark swaps its on-dark/on-light variant on the same
selectors, purely in CSS.
- Android:
share_targetin the manifest (works for installed PWAs). - iOS / Shortcuts / Plan B native:
window.marksyncReceiveSharedUrl(url, title?, text?)and the?shareUrl=…&shareTitle=…&shareText=…query params, both handled insrc/main.ts.textbecomes the bookmark's description; with no title at all it still names the bookmark, as it did before there was a description to put it in.
Pushes to main publish to Cloudflare Pages via
.github/workflows/deploy-cloudflare.yml. The workflow runs the Playwright suite
first and the deploy job needs: it, so a red run stops the deploy rather than
shipping past it — that suite is the only automated check this repo has, and it
covers the production bundle, the service worker and the CSP. The build then runs on
Actions and wrangler uploads dist/. Setup:
docs/deploy-cloudflare-pages.md.
public/_redirects (SPA fallback) and public/_headers (security headers plus cache control, chiefly
no-cache on the service worker) ship with the build, so the routing and
caching rules live with the code rather than in the Cloudflare dashboard.
Defaults to https://sync.marksync.org. Login uses an existing Sync ID +
password (creating a new sync is out of scope for this prototype).