Reveal URLs

Safari is a supported active target with its own entry points. Built-in providers use static scripts and Safari requests no all-sites access. User-added sites receive a runtime optional permission, then the background injects content.js after navigation only for granted, enabled, non-builtin rules, with allFrames per rule. Safari settings are device-local and do not roam between devices. macOS packaging uses Xcode and the Apple Developer Program/App Store route.

Reveal URLs — Arkitektura

Ky dokument përshkruan si është strukturuar zgjerimi Reveal URLs dhe si punon logjika e tij bazë, për kontribues dhe lexues teknikë. Ai i referohet vazhdimisht skedarëve dhe simboleve reale, në formën path symbol, që çdo pretendim të mund të verifikohet te burimi. Për përshkrimin e orientuar nga përdoruesi shihni manual. Për hapat e verifikimit manual shihni manual test plan.

Përmbledhje

Reveal URLs është një MV3 WebExtension i vetëm, i ndërtuar për Chrome, Edge, Opera, Firefox, Safari dhe Thunderbird nga një bërthamë e vetme dhe e pastër kodesh. Safari përdor skripte statike vetëm për ofruesit e integruar dhe është publikuar në App Store. Zgjerimi zbulon URL-në përfundimtare të çdo lidhjeje pranë vetë lidhjes në një email të renderuar dhe shënon një lidhje kur teksti i dukshëm përmend një domen registrable tjetër nga ai i href-it të saj.

Repozitori është një monorepo për pnpm dhe TypeScript, i përshkruar nga pnpm-workspace.yaml dhe package.json, ndërsa "private": true e mban jashtë publikimit si paketë. Bundling drejtohet nga tooling/build.mjs, i cili përpilon paketat e përbashkëta dhe entry points e holla për secilin engine në një direktori të ngarkueshme dist/<target>/. webextension-polyfill përfshihet në çdo script bundle, në vend që të lihet si global i runtime-it, në mënyrë që i njëjti kod të funksionojë si në Chromium ashtu edhe në Gecko.

Dy shtesa vendase emaili e shtrijnë të njëjtën logjikë zbulimi në sipërfaqe ku WebExtension nuk arrin dot: një Outlook Add-in mbi Office.js dhe një Gmail Add-on mbi Apps Script CardService. Të dyja ripërdorin vetëm analizën PURE nga packages/core/src/findings.ts, me analyseAnchors, analyseHtml, modelin neutral Finding[], logjikën hostMismatch dhe nxjerrjen e domenit registrable nga tldts. Ndryshojnë vetëm adapter-i i host-it, pra mënyra si lexohet dhe pars-ohet trupi i mesazhit, dhe mënyra e paraqitjes. Outlook bën parsing me DOMParser dhe punon client-side. Gmail përdor node-html-parser dhe punon server-side në infrastrukturën Apps Script V8 të Google-it. Asnjëra nga këto platforma nuk lejon të ndryshohet DOM-i i mesazhit të lexuar, prandaj të dyja tregojnë panel ose card me gjetje, jo inline annotation. Rruga ekzistuese e DOM mutation në linkProcessor.ts dhe REVEAL_URLS_CSS nuk përdoren atje. Një href relativ zgjidhet vetëm kundrejt një <base href> të besueshëm brenda emailit dhe ndryshe anashkalohet. Kjo rrugë vendase e gjetjeve mbetet qëllimisht vetëm për http:/https:.

Kodi ndahet qartë sipas përgjegjësive:

Skema e depozitës

packages/core — bërthama e pastër

Asnjë modul këtu nuk importon extension API, si browser.*, chrome.* ose messenger.*, dhe asnjë nuk përdor string-to-markup DOM sinks si innerHTML ose insertAdjacentHTML. Ky kontratë zbatohet mekanikisht nga packages/core/test/purity.test.ts, i cili mbledh src/**/*.ts, heq trupat e komenteve me stripComments dhe verifikon që as EXTENSION_API_PATTERN dhe as UNSAFE_DOM_PATTERN të mos përputhen me asnjë modul. Sipërfaqja publike rieksportohet nga packages/core/src/index.ts, ndërsa varësia e vetme runtime është tldts.

Modulet kryesore janë:

packages/webext — mbështjellësit e browser API-së

Këto module MUND të përdorin browser.* dhe janë i vetmi vend ku preken WebExtension APIs. Sipërfaqja publike rieksportohet nga packages/webext/src/index.ts. Këtu gjenden content.ts, contentRegistration.ts, storage.ts, background.ts, toolbarAction.ts, messageDisplay.ts, messageDisplayBackground.ts dhe options/options.ts.

extensions/<engine> — pikat e holla të hyrjes dhe manifestet

Çdo engine ka manifest.json-in dhe icons/ e vet. Chrome, Firefox dhe Thunderbird mbajnë edhe një src/ me entry points. Edge, Opera dhe Safari mbajnë vetëm manifest dhe ikona dhe ripërdorin src/ e Chrome-it. Për shembull extensions/chrome/src/content.ts përmban vetëm void createContentController().bootstrap();, ndërsa extensions/chrome/src/background.ts thërret registerBackground, registerContentReconciliation dhe registerToolbarToggle. extensions/thunderbird/src/background.ts thërret registerBackground dhe registerMessageDisplay. extensions/_template është scaffold, jo build target.

tooling, features dhe smoke tests

tooling përfshin build.mjs, version.mjs dhe icons.mjs. features përfshin skenarët Gherkin, step definitions dhe doubles-et besnike në features/support/webext.ts dhe features/support/world.ts. Çdo engine ka gjithashtu extensions/<engine>/test/manifest.smoke.test.mjs, ndërsa _template përdor template.smoke.test.mjs.

Rrjedha e zbulimit

Rruga e content-it fillon te një entry point engine, si extensions/chrome/src/content.ts, i cili thërret createContentController().bootstrap() nga packages/webext/src/content.ts.

Bootstrap

createContentController bootstrap ekzekutohet një herë për çdo frame. Ai e pretendon frame-in para çdo await me claimBootstrap, ngarkon config-un me loadConfigWithRetry, injekton stylesheet-in me injectStyles vetëm pasi leximi të ketë sukses, dhe rikthen marker-in me releaseBootstrap nëse ngarkimi dështon plotësisht. Kur config.enabled është aktiv thërret start, ndërsa në çdo rast regjistron një listener onConfigChanged.

Zgjidhja e rregullit të site-it aktiv

start dhe applyConfig përdorin resolveSiteRule për të vendosur nëse dhe ku do të bëhet annotation. Fillimisht provohet vetë lokacioni i dokumentit me resolveForHref, i cili filtron config.sites në rregullat e aktivizuara dhe ia lë zgjedhjen selectMostSpecific. Nëse dokumenti nuk përputhet dhe origjina e tij është opaque ose inherited, siç e kontrollon hasOpaqueOrigin, përdoret fallback përmes readTopHref, readOpenerHref dhe readReferrer, duke u mbrojtur nga leximet cross-origin.

Kufizimi te rrënja e përmbajtjes dhe vrojtimi i ndryshimeve

start ruan contentRoot, krijon annotator me createAnnotator(config) dhe proceson çdo rrënjë të përputhur nga selectRoots(doc, contentRoot), i cili e mbështjell querySelectorAll me try/catch që një selector i pavlefshëm të dështojë në mënyrë të sigurt te []. Pastaj vëzhgon doc.body me OBSERVER_OPTIONS. processMutations filtron çdo mutacion sipas root-it, riproceson target-in vetëm kur është Element brenda root-it përmes isWithinRoot dhe closest, ndërsa zbulimin e vonshëm të root-eve ia lë kalimit të kufizuar discoverMatchedRoots() për çdo batch me një querySelectorAll(contentRoot) dhe deduplikim me WeakSet. pendingShadowHosts rishikon host-et plain të mëparshme derisa të shfaqet open shadow root, që të mbulojë edhe shadow upgrade-et. applyConfig bën teardown kur s'ka rregull aktiv, restart kur ndryshon contentRoot, dhe ndryshe vetëm reflow.

Shënimi i një lidhjeje të vetme

Annotator-i jeton te packages/core/src/linkProcessor.ts. createAnnotator kthen një Annotator me një Map, një token data-ru nga generateToken dhe config-un aktual. process(root) pastron entries jo më të lidhura, mbledh a[href] me collectAnchors, zgjidh URL-të me resolveAnnotatableUrl, përdor fast path-in isAnnotationIntact kur render-i është i paprekur dhe llogarit mospërputhjen përpara se të thërrasë annotateAnchor. Më hollësisht, metoda:

  1. Heq shënimet e regjistrit, lidhja e të cilave nuk është më e lidhur.
  2. Mbledh lidhjet kandidate me collectAnchors (pasardhësit a[href] dhe vetë rrënjën kur ajo është a[href], pa dublikatë).
  3. Zgjidh destinacionin e çdo lidhjeje me resolveAnnotatableUrl, që delegon te resolveAnnotatableHref. Ai kthen null (anashkalo) vetëm për href bosh, në faqe ose të paparsueshëm, zgjidh href-at relativë kundrejt baseURI dhe pranon çdo skemë të parsueshme, duke përfshirë mailto:, tel:, sms: dhe URL-të opake javascript:, data: e blob:. ignoreHosts zbatohet vetëm për lidhjet http:/https: që kanë host.
  4. Merr rrugën e shpejtë idempotente kur isAnnotationIntact konfirmon se gjurma e renderimit nuk ka ndryshuar dhe çdo nyje e krijuar është ende e lidhur dhe në pozicion; përndryshe kthen mbrapsht shënimin e vjetruar dhe e renderon sërish.
  5. Llogarit mospërputhjen e varur nga skema me destinationMismatch mbi tekstin e pastër të lidhjes: classifyScheme dërgon lidhjet e uebit te hostMismatch, postën te mailMismatch, telefonin te phoneMismatch dhe të tjerat te opaqueMismatch. Pastaj thërret annotateAnchor; showOnlyOnMismatch fsheh vetëm zbulimin e dukshëm brenda rreshtit për një lidhje pa dallime, duke ruajtur title e destinacionit të saj.

annotateAnchor renderon vetëm SAFE-DOM. Ai ruan gjithmonë title origjinal (TitleSave) dhe shkruan title e destinacionit — i vetmi shkrim te lidhja. Nuk ka mënyrë të veçantë titulli ose distinktiv paralajmërues. Përveç kur showOnlyOnMismatch fsheh një lidhje pa dallime, ai vendos përpara një <span class="reveal-urls-url"> dhe një <br> pasues, duke i lënë fëmijët e lidhjes të paprekur. needsLeadingInlineRevealBreak shton një <br> kryesore kur përmbajtja e dukshme brenda rreshtit i paraprin lidhjes në të njëjtin rresht. Span-i shfaq një href absolut të shkruar nga autori pa ndryshim ose një href relativ të zgjidhur kundrejt baseURI, përmes textContent inert (me shigjetë dhe hapësirë jo-ndarëse U+00A0 në fillim, pastaj të shkurtuar nga truncateUrl); sapo lidhet, merr një sfond kontrasti përmes applyContrastBackdrop. Për një mospërputhje të theksuar, REVEAL_URLS_MISMATCH_CLASS i shtohet REVEAL_URLS_URL_CLASS, duke zbatuar ngjyrën e konfiguruar të mospërputhjes përmes applyColour dhe tekst të trashë si parazgjedhje në REVEAL_URLS_CSS; një mbishkrim i shprehur i peshës së shkronjave përmes applyFontOverrides ka përparësi. Çdo nyje e krijuar shënohet me data-ru="<token>" (kurrë lidhja), dhe çdo shënim regjistron configFingerprint, që një ndryshim i konfigurimit të renderimit të detyrojë rrjedhjen e re. revertOwned heq nyjet e krijuara sipas referencës dhe rikthen title e ruajtur; revertAll e bën këtë për çdo lidhje në pronësi dhe pastron regjistrin. truncateUrl punon mbi [...displayHref] dhe përdor URL_ELLIPSIS.

Mospërputhja e host-it

packages/core/src/hostMismatch.ts hostMismatch është dega e uebit e destinationMismatch: ai krahason tekstin e dukshëm të lidhjes me href-in e saj sipas domenit të regjistrueshëm, jo emrit të papërpunuar të hostit, prandaj një nën-domen pa dallime nuk shënohet, kurse një imitim po. extractHostCandidates ndan tekstin dhe redukton çdo token nëpërmjet hostCandidate (që kërkon një pikë dhe një prapashtesë publike ICANN të njohur nga tldts, duke refuzuar tekst të zakonshëm me pika si e.g). Si hosti i href-it, ashtu edhe çdo kandidat reduktohen në domenin e tyre të regjistrueshëm me tldts.getDomain, dhe ÇDO kandidat me domen të ndryshëm nga ai i href-it jep mospërputhje — kështu që emërtimi i hostit të vërtetë keqdashës pranë një hosti karrem nuk mund ta shtypë paralajmërimin. Ai nuk hedh kurrë gabim.

Për lidhjet e postës, mailMismatch krahason të gjithë domenet e regjistrueshme të marrësve, duke përfshirë to, cc dhe bcc; phoneMismatch krahason numrat e formueshëm që mund të zgjidhen. opaqueMismatch shënon gjithmonë SCRIPT_LIKE_SCHEMES — javascript:, data: dhe vbscript: — ndërsa skemat e tjera opake shënohen vetëm kur teksti i dukshëm emërton një destinacion konkret uebi, emaili ose telefoni.

Stilet dhe kontrasti

packages/core/src/styles.ts mban REVEAL_URLS_CSS dhe helper-at applyColour, applyFontOverrides dhe applyContrastBackdrop. applyContrastBackdrop lexon ngjyrën e llogaritur të elementit dhe sfondin e parë opaque duke ecur lart me getComputedStyle, pastaj përdor needsWhiteBackdrop nga packages/core/src/contrast.ts për të vendosur nëse duhet style.backgroundColor = "white". contrast.ts jep parseColour, relativeLuminance dhe contrastRatio.

Hostet e konfigurueshme dhe kufizimi i përmbajtjes

Një SiteRule në packages/core/src/config.ts përcakton KU ekzekutohet annotation me match dhe allFrames, dhe CILI container e kufizon atë me contentRoot, bashkë me enabled dhe shenjën builtin. DEFAULT_SITES mbulojnë Gmail, Proton me allFrames dhe të dy hostet e Outlook-it. Config bashkon toggles globale, colours, font overrides dhe listën sites.

Mekanizmi i match pattern-it

packages/core/src/matchPattern.ts mban gramatikën restrictive MATCH_PATTERN: vetëm http dhe https, wildcard host opsional *., glob path, pa port, pa * scheme dhe pa <all_urls>. matchesPattern provon një URL kundrejt një pattern-i të validuar dhe ia delegon rrugën pathGlobMatches. parsePatternParts e ndan pattern-in në host, path, scheme dhe wildcardHost.

Rregullat që mbivendosen zgjidhen sipas parimit "most specific wins". compareSiteSpecificity rendit hostin ekzakt mbi wildcard-in, pastaj hostin më të gjatë literal, pastaj path-in më literal me literalPathLength, e në fund një ASCII tiebreak. selectMostSpecific kthen rregullin më specifik të aktivizuar që përputhet me URL-në.

permissions.getAll() mund të raportojë grants në gramatikën e plotë të WebExtension-it (<all_urls>, *://*/*, https://*/*, *://*.host/*, https://host/*) që MATCH_PATTERN do t'i refuzonte. parseGrantedOrigin i kthen ato në GrantedOriginParts, originCovers kontrollon mbulimin mbi match, ndërsa matchAllowsOriginFallback raporton nëse path-i është saktësisht ORIGIN_FALLBACK_PATH, pra /*.

Regjistrimi dinamik

packages/webext/src/contentRegistration.ts regjistron nga një dynamic content script për çdo rregull të shtuar nga përdoruesi. Built-ins shërbehen nga static content_scripts entries dhe nuk regjistrohen kurrë dinamikisht. desiredContentScripts filtron config.sites, përdor isOriginGranted, originCovers dhe contentScriptId, dhe e vendos matchOriginAsFallback: true vetëm kur lejohet nga matchAllowsOriginFallback(rule.match).

reconcileContentScriptsOnce lexon origjinat e miratuara, config-un e ruajtur dhe regjistrimet live dhe i pajton ato me diff të vetëdijshëm për properties. sameRegistration normalizon descriptor-in e dëshiruar dhe read-back-un live. Meqë nuk ka updateContentScripts, një script i ndryshuar hiqet dhe regjistrohet sërish. reconcileContentScripts përdor një promise inFlight për të serializuar trigger-at që mund të ndodhin afër njëri-tjetrit.

Rrjedha e lejes së shprehur

Manifestet statike deklarojnë optional_host_permissions (http://*/*, https://*/*) që përdoruesi të mund të japë në runtime leje për një host shtesë. packages/webext/src/options/options.ts addSite validon të gjithë rregullin kandidat përmes normaliseSiteRule, nxjerr origin-in me matchOrigin dhe thërret browser.permissions.request nga click gesture-i i butonit Add. Vetëm pas miratimit shton një rresht builtin:false.

Config, storage dhe modeli kanonik

Funneli i vetëm i validimit

normaliseConfig në packages/core/src/config.ts është rruga e vetme kanonike e leximit. Ai konverton dhe kufizon çdo fushë, kthehet te vlera e parazgjedhur kur ndesh diçka të pavlefshme dhe nuk hedh kurrë exception. Ai ndërtohet nga validatorë si normaliseBoolean, normaliseMaxLength, normaliseIgnoreHosts, normaliseMatchColour, normaliseMismatchColour, normaliseCssSize, normaliseFontWeight, normaliseContentRoot, normaliseMatchPattern dhe normaliseSites. normaliseSites heq vlera të pavlefshme, i heq dublikatat sipas match, detyrimisht vendos builtin: true kur një rregull përputhet me built-in dhe risjell built-ins që mungojnë.

Ruajtja

packages/webext/src/storage.ts mbështjell WebExtension storage API. configArea përdor browser.storage.sync kur është i disponueshëm dhe bën fallback në browser.storage.local, p.sh. në Thunderbird. getConfig, setConfig dhe onConfigChanged e kalojnë gjithmonë vlerën e tyre nëpërmjet normaliseConfig, prandaj një store i prishur nuk mund të dorëzojë kurrë një Config të pavlefshëm. Dy add-on-et ripërdorin të njëjtin funnel mbi storage-et e tyre pritëse.

Modeli i config-ut kanonik dhe përditësimet e synuara

Tre rrugë shkrimi lexojnë config-un kanonik, ndryshojnë saktësisht një gjë dhe e shkruajnë sërish, pa ruajtur form edits të papërfunduara:

toggleEnabled te packages/webext/src/toolbarAction.ts ndjek të njëjtin model edhe nga ana e background-it.

Build-i sipas engine-it dhe kontrata e manifestit

tooling/build.mjs drejton një build të vetëm esbuild për çdo target të WebExtension-it. Descriptor-i TARGETS përcakton SOURCE TARGET për secilin target. Chrome, Firefox dhe Thunderbird kanë src/ e tyre. Edge, Opera dhe Safari përdorin chrome si source. Outlook add-in ka source-in e vet. ACTIVE_TARGETS, domethënë Chrome, Edge, Firefox, Opera dhe Thunderbird, janë ato që ndërtohen me --all dhe --package. Safari dhe Outlook ndërtohen vetëm kur emërtohen shprehimisht, ndërsa Gmail përdor make build-gmail.

Bundle-i i Gmail-it synon runtime-in Apps Script V8, i cili nuk ka as ES modules dhe as URL natyror. Prandaj ndërtohet si ESM dhe pastaj i hiqet export {…}, në mënyrë që funksionet trigger të mbeten globals në nivel moduli. Një polyfill i vogël për URL përfshihet vetëm kur duhet. buildTarget pastron dist/<target>/, kopjon manifest.json dhe icons/, bën bundle të scripts si IIFE dhe faqes së opsioneve si ESM, dhe kopjon options.html dhe options.css.

tooling/version.mjs stamp-on versionet. Ai merr MAJOR.MINOR nga root package.json, gjen BUILD number më të lartë ekzistues dhe e shton atë në çdo manifest target. Outlook add-in mban si manifest.json ashtu edhe manifest.xml. tooling/icons.mjs, i ekzekutuar me make icons, bën rasterise të assets/icon.svg në icon48.png dhe icon128.png.

Kontrata e manifestit përcaktohet te extensions/<engine>/test/manifest.smoke.test.mjs, ku verifikohet forma e saktë e secilit manifest dhe ekzistenca e çdo skedari të referuar.

Ndërkombëtarizimi (i18n)

Reveal URLs është i lokalizuar në shumë gjuhë përveç anglishtes. Burimi i vetëm i këtij grupi është packages/core/src/locales.json, i cili përmban SUPPORTED_LOCALES, emrat vendorë dhe gjuhën e parazgjedhur. Çdo string jo-anglisht është machine-translated dhe pret rishikim njerëzor. Marker-i i proveniencës ndryshon sipas formatit: _locales e mbajnë në description, site catalogues e regjistrojnë në site/i18n/README.md, ndërsa docs të përkthyera mbajnë komentin HTML në rreshtin e parë.

Janë tri sipërfaqe të pavarura lokalizimi:

Fshehja e “Sajteve aktive” në klientin e postës (AD-3)

Një target mail client, sot Thunderbird, i sheh tashmë të gjitha mesazhet e renderuara, kështu që editor-i “Active sites” sipas host-it është i tepërt. Vendimi bartet nga mailClient: true te tooling/build.mjs.

Qëndrimi për sigurinë dhe privatësinë

Testimi