Podejście naukowe

Co to jednak znaczy, że traktuję webdev naukowo? Tak naprawdę wyróżniłbym tutaj trzy główne elementy:

1. formę treści,
2. obecność źródeł,
3. empiryczność.

Forma treści

Artykuły naukowe mają ściśle określoną strukturę. Bardzo często opisuje się ją akronimem IMRaD:

1. Introduction (wprowadzenie) – wyjaśnienie celu badania, postawienie hipotezy,
2. Methods (metody badawcze) – w jaki sposób badanie zostało wykonane, kto w nim uczestniczył,
3. Results (wyniki) – omówienie wyników badania, sprawdzenie, czy wyniki zgadzają się z postawioną hipotezą,
4. Discussion (polemika) – próba interpretacji wyników, porównanie ich z innymi badaniami z tego zakresu, zaproponowanie możliwych przyszłych kierunków badań.

Tak tworzone artykuły powinny zachowywać jak największą obiektywność, skupiając się przede wszystkim na opisie faktów, z pominięciem opinii osób autorskich.

Ja nie jestem naukowcem i siłą mojego bloga jest jednak to, że umieszczam na nim materiały o webdevie okraszone moją opinią. Więc bardziej nazwałbym swoją radosną twórczość esejami hipertekstowymi. To nic innego jak eseje, które są opublikowane w formie hipertekstu. Czyli: mogą linkować do innych esejów lub bezpośrednio do źródeł, Równocześnie jednak – raz luźniej, raz ściślej – trzymam się struktury IMRaD. Weźmy taki artykuł o Cookie Store API. Na samym początku jest wprowadzenie, w którym zaznaczam problem (relacja Sieci z ciasteczkami od zawsze była skomplikowana). Następnie następuje omówienie wyników badania (w tym wypadku: organoleptycznego sprawdzenia, jak się obsługuje ciasteczka w przeglądarkach). W przypadku artykułów z eksperymentów (jak np. jednoplikowych komponentów czy ASCSS-a) pojawiają się też sekcje z metodami (opis inspiracji i narzędzi użytych do stworzenia danego projektu) oraz polemika (w jaki sposób go dalej rozwijać, czy moje pierwotne założenia udało się spełnić, itd.).

Źródła

Niemniej to nie forma jest głównym wyznacznikiem “naukowości”. Według mnie o wiele ważniejszym jest odwoływanie się do źródeł. W końcu szansa, że opisałem coś jako pierwszy w Internecie, jest niemalże zerowa. Nawet jeśli w swoim zakątku Sieci jestem faktycznie pierwszy, to przecież o jakimś standardzie sieciowym napisała przede mną choćby… osoba pisząca jego specyfikację. Nawet jeśli już wymyślę coś absolutnie swojego (jak Headings First Principle (HFP)), to przecież to nie istnieje w próżni. Żeby mogło powstać HFP, musiał powstać HTML, a w nim nagłówki. Niezbędnymi elementami były też wszelkie dobre praktyki wokół dzielenia treści stron WWW na sekcje oraz sposób nawigowania przy pomocy nagłówków przez osoby korzystające z czytników ekranowych. Słowem: musiał istnieć cały skomplikowany ekosystem Sieci, żebym ja mógł do niego dodać swoją małą cegiełkę.

Chyba najdobitniej widać to w przypadku mojego, jak dotąd najambitniejszego, projektu, GWD. W każdym “rozdziale” na końcu znajdują się listy źródeł oraz dodatkowych materiałów. Nazbierało się ich około tysiąca. A i tak była to mocno okrojona lista. Zwłaszcza, że sporo tematów ostatecznie wypadło z tego eseju.

Niemniej samo odesłanie do źródeł to za mało. Prawdziwa praca polega na odpowiednim ich dobraniu. Bo można opisać np. element HTML bdo i odesłać do jakiejś strony-krzak czy popularnej, acz słabej jakości witryny. Zamiast tego wypada jednak dokładnie zapoznać się, do czego linkujemy, czy nie ma tam błędów merytorycznych, czy poruszone są wszystkie kwestie ważne poruszenia, itd. I tak jak w świecie nauki, w którym mamy tytuły godne zaufania (Science, Nature), tak i w webdevie jedne źródła są bezpieczniejsze od innych. Najbezpieczniejsze są, rzecz jasna, specyfikacje i standardy. Nie ma pewniejszych źródeł od nich. Jeśli chcę opisać element bdo, to specyfikacja HTML jest Kanonicznym Źródłem Prawdy™. Ale standardy często są pisane w sposób całkowicie hermetyczny i niezrozumiały dla dowolnej osoby, która nie czyta sobie RFC do poduszki. Wtedy warto sięgnąć po drugie najlepsze źródło – dokumentację MDN. Jeśli coś można by nazwać oficjalną dokumentacją platformy sieciowej, to byłoby to właśnie MDN.

Dobrej jakości źródeł jest oczywiście więcej – jak choćby Smashing Magazine, A List Apart czy blogi znanych osób ze światka webdevu. I często na tych stronach, oderwanych od “oficjalnego obiegu”, dzieją się rzeczy ciekawsze. To w końcu na łamach A List Apart powstał termin Responsive Web Design! Często też wyłuskać można na jakiejś stronie jakąś perełkę wśród całej reszty meh artykułów (hej, to zupełnie jak na moim blogu!). Tylko no właśnie – wyłuskać…

Sprawne posługiwanie się źródłami wymaga mimo wszystko wprawy i pewnego doświadczenia. Ja w swoim życiu przerobiłem już tysiące artykułów o webdevie i jestem w stanie oddzielić te faktycznie ciekawe od tych, które takie nie są. I właśnie tę umiejętność selekcji uważam za kluczową w bardziej naukowym podejściu do webdevu. Żeby ją zdobyć, to nie ma innej rady – trzeba spędzić swoje na czytaniu. Na początku będzie się czytać wszystko, jak leci, by z czasem odrzucać te najgorsze z najgorszych, aż w końcu nadejdzie moment, w którym się Po Prostu Wie™, co jest warte poświęcenia czasu, a co nie.

Niemniej z selekcją źródeł jest jeszcze jeden mały haczyk: ryzyko wpadnięcia w bańkę. Każda osoba ma jakieś poglądy i przekonania. Choćby tak błahe, jak nielubienie Reacta czy skłonność do wybierania mniej popularnych rozwiązań. I takie przekonania będą – bardziej lub mniej świadomie – wpływać na to, które źródła się dobiera. Nie sądzę, by dało się od tego całkowicie uciec, ale im bardziej się jest tego świadomym, tym mniejszy ma to wpływ na proces selekcji. Bo czasami warto wręcz sięgać po źródła, z którymi się nie zgadzamy – choćby po to, by wejść z nimi w polemikę.

Empiryczność

Wreszcie ostatni element, który widać w większości moich artykułów – zarówno tutaj, jak i na WebKrytyku. Empiryczność, czyli mówiąc inaczej: eksperymentowanie. Kiedy opisuję nowe API, fajnie byłoby, gdybym przygotował choćby krótkie demko, w którym bym zademonstrował jego podstawowe ficzery. Tym prostym sposobem można być jak Longinus Podbipięta i ściąć trzy gł odhaczyć trzy rzeczy:

1. pokazujemy osobom czytającym, że opisywane przez nas rzeczy faktycznie istnieją i działają,
2. tworzymy dla siebie samych z przyszłości źródło do linkowania, jeśli kiedyś wspomnimy znowu o tym API,
3. zapamiętujemy całą rzecz lepiej, niż gdybyśmy naskrobali jedynie teoretyczny opis.

Poza tym – ostatecznie piszę ten blog dla przyjemności. A gdzie byłby cały fun z tego, gdybym się nie bawił kodem?

Tylko po co?

Odpowiedziałem już na pytanie, jak traktować webdev bardziej naukowo. Pora zatem pochylić się nad drugim, równie ważnym – jeśli nawet nie ważniejszym – pytaniem: po co?

Bo uważam, że tego wymaga uczciwość intelektualna. Webdev nie jest jakąś bliżej niezdefiniowaną sztuką okultystyczną (mimo że czasami tak się jawi!). Wbrew pozorom zdecydowana większość platformy sieciowej jest oparta na konkretnych standardach i specyfikacjach. Bo gdyby nie była, strony WWW działałyby w jednych przeglądarkach i nie działały w innych. Te czasy już przerabialiśmy i to właśnie dzięki nim dzisiaj mamy otwarte standardy sieciowe. Jasne, nie jest idealnie, ale inicjatywy takie jak Web Platform Tests czy Interop dają nadzieję, ze będzie lepiej. A skoro Sieć oparta jest na fundamentach, które są skodyfikowane (spisane “na papierze”, z przybitą pieczątką) i możliwe do empirycznej weryfikacji (w każdej chwili mogę odpalić przeglądarkę i sprawdzić, jak ten HTML czy CSS działają), to nie widzę powodu, by moje artykuły się do tego nie odwoływały.

Uczciwość intelektualna wymaga też, by istniała pewna ciągłość między tym, co tworzymy, a tym, co zostało stworzone. Tak jak artykuł naukowy nie może istnieć bez źródeł, tak trudno stworzyć artykuł o hipertekście bez… hipertekstu. W webdevie nie ma self-made men, wszyscy budujemy na fundamentach postawionych przez innych. Nawet jeśli nasze budowanie polega na niezgadzaniu się z już istniejącymi dobrymi praktykami i proponowaniu czegoś nowego. Bo ostatecznie nie byłoby tej propozycji, gdyby nie ta praktyka! Żeby się z czymś nie zgadzać, trzeba najpierw zauważyć istnienie tego czegoś. Inaczej nasza krytyka będzie całkowicie jałowa.

Wreszcie: webdev najzwyczajniej w świecie zasługuje na bardziej naukowe – czy też po prostu merytoryczne – traktowanie. Choćby dlatego, że Sieć stanowi coraz większą część naszego codziennego życia. To wszechobecna technologia, do której dostęp ma ok. 6 miliardów ludzi. W innych dziedzinach nauki i technologii, które często dotykają mniejszej liczby osób (jak np. projekt nowego skafandra astronautycznego), zachowujemy niezwykłą precyzję i naukową rygorystyczność. Natomiast w dziedzinie, która w taki czy inny sposób zahacza o jakieś ¾ światowej populacji, mam wrażenie, że często wychodzimy z założenia, że to tylko technologia. A to przecież nieprawda. Ludzie mają różne powody, by korzystać z Internetu. Jeśli – jako osoby tworzące strony WWW – nie traktujemy Sieci wystarczająco poważnie, ostatecznie szkodzimy osobom, które z tych stron WWW następnie korzystają. I myślę, że przestawienie myślenia z to tylko technologia w kierunku webdev to nauka jest mało bolesnym sposobem na stworzenie lepszej Sieci.

I tym optymistycznym akcentem życzę Wszystkim wesołych świąt 🎄🎄🎄!

Technologia asystująca

Czym jednak jest technologia asystująca? Za definicją proponowaną przez WHO:

Assistive products help maintain or improve an individual’s functioning related to cognition, communication, hearing, mobility, self-care and vision, thus enabling their health, well-being, inclusion and participation.

[Produkty asystujące pomagają w utrzymaniu lub poprawie funkcjonowania osoby w zakresie funkcji poznawczych, komunikacji, słuchu, mobilności, samoopieki oraz wzroku, pozwalając tej osobie być zdrową fizycznie i psychicznie, włączoną w życie społeczne oraz uczestniczącą w nim.]

Ta definicja jest niezwykle szeroka i obejmuje tak naprawdę wszystkie sprzęty oraz oprogramowanie, które pomagają w codziennym funkcjonowaniu. Stąd można do niej zaliczyć np. wózek inwalidzki, czytniki ekranu, ale też choćby lupę. Swego czasu opisałem trochę przykładów takich technologii.

Systemowa technologia asystująca

Systemy operacyjne dostarczają osobom z nich korzystających wbudowanych technologii asystujących. Lista takich technologii będzie się różnić w zależności od systemu. Weźmy jako przykład macOS-a. Chyba najbardziej znaną technologią asystującą dostępną wraz z tym systemem jest czytnik ekranowy VoiceOver. Nie jest bynajmniej jedyną. Ustawienia systemu posiadają mocno rozbudowaną sekcję poświęconą dostępności:

Jak widać, macOS dzieli te ustawienia na poszczególne zmysły, które dane opcje mają wspierać. Stąd w kategorii wzroku mamy m.in. czytnik ekranu (VoiceOver), ale też ustawienia wyświetlacza czy animacji ruchowych, w słuchu – ustawienia dźwięku itd. Każda z tych opcji w menu posiada konkretne ustawienia, np. odnośnie animacji ruchowych:

System od Apple pozwala na dostosowanie większości aspektów systemu, np. wyłączając autoodtwarzanie ruchomych obrazków (GIF-ów). I choć na początku ogrom opcji może przytłaczać, to sam fakt ich istnienia jest jak najbardziej pozytywny. W końcu jedne z najbardziej dostępnych rozwiązań to te, które można najbardziej dostosować pod siebie!

Windows również posiada dość rozbudowane opcje dostępności. Podobnie jak macOS udostępnia czytnik ekranowy, Narratora. W przypadku jednak tego systemu nie zdobył on nigdy większej popularności. Od lat na tej platformie królują JAWS (płatny) oraz NVDA (darmowy). Oprócz czytnika Windows oferuje choćby lupę ekranową (do powiększania fragmentów ekranu) czy tryb wysokiego kontrastu.

Systemy mobilne także dostarczają technologii asystujących. Zarówno Android, jak i iOS, mają wbudowane czytniki ekranowe – odpowiednio TalkBack i VoiceOver. Mają także choćby opcję ograniczania animacji ruchowych. Także sporo linuksowych dystrybucji ma ustawienia dostępności, np. LInux Mint pozwala włączyć tryb wysokiego kontrastu i ma wbudowany czytnik ekranu (Orcę).

Innymi słowy: systemy operacyjne próbują dostarczyć niezbędnych narzędzi do tego, by mogło z nich korzystać jak najwięcej osób, w tym osoby z niepełnosprawnościami.

System a przeglądarka

Jak zatem taka systemowa technologia asystująca przekłada się na przeglądarkę? To zależy. Wraz z rozwojem technologii sieciowych, osoby tworzące strony WWW dostały możliwość dowiedzenia się nieco więcej o systemie operacyjnym, na którym uruchomiona jest przeglądarka. Najczęściej dzięki nowym media queries w CSS-ie. Wśród nich wymienić można:

• prefers-reduced-motion – informujące o ustawieniach dotyczących ograniczenia animacji ruchowych,
• forced-colors – informujące o trybie wymuszonych kolorów, czyli ograniczeniu palety dostępnych kolorów, jak w przypadku Windowsowego trybu wysokiego kontrastu,
• prefers-color-scheme – informujące o preferencjach osoby użytkowniczej co do doboru schematu kolorystycznego; inaczej mówiąc: czy woli jasny, czy ciemny motyw.

Część z systemowych ułatwień dostępu może być jednak “zakamuflowana”. Dobrym przykładem są tu różnego rodzaju powiększenia. Działają one trochę jak zmniejszenie rozdzielczości: poszczególne elementy robią się większe, przez co są bardziej czytelne. Równocześnie jednak ogranicza to liczbę elementów widocznych w danej chwili na ekranie. Przeglądarka często interpretuje to jako mniejszy viewport. Co też dobrze pokazuje, jak zawodne jest opieranie responsywności na założeniu mały ekran = urządzenie mobilne.

Jeszcze inne technologie asystujące są całkowicie przezroczyste dla przeglądarki, jak np. czytniki ekranu. Nie ma żadnego sposobu, aby dowiedzieć się, że osoba odwiedzająca stronę używa czytnika ekranu. I to akurat dobrze. Zwłaszcza, że stworzenie strony z zachowaniem standardów sieciowych i dobrych praktyk dostępności jest w większości przypadków wystarczające, by strona ta działała poprawnie we wszystkich popularnych czytnikach ekranu. Innymi słowy: wystarczy dobrze wykonywać swoją pracę – jakkolwiek brutalnie by to nie brzmiało.

Podsumowując: przeglądarka i system to para zaufanych przyjaciół, która niektóre sekrety zostawia wyłącznie dla siebie. Ale to, czym się jednak z nami dzielą, powinno wystarczyć do stworzenia dostępnej, przyjaznej strony WWW.

Kanały Atom

Dawno, dawno temu ktoś wpadł na szalony pomysł: a co jeśliby pozwolić ludziom czytać treść ze stron internetowych jak i kiedy chcą? Zamiast musieć wchodzić na konkretną stronę WWW, ktoś mógłby po prostu dostać informację o nowym wpisie na blogu czy zdjęciu w galerii podobnie, jak dostaje maila. Ot, taki newsletter, tylko że nie przez maila. Tak powstały tzw. feeds (kanały). W największym skrócie: kanał to plik w formacie innym niż HTML, w którym znajduje się treść strony i który jest przystosowany do czytania przez tzw. feed readers (czytniki kanałów). Te czytniki pobierają kanały ze stron co pewien czas, by sprawdzić, czy na stronie pojawiło się coś nowego. Osobiście używam ich jako głównego sposobu na dowiadywanie się o nowościach ze światka webdevu.

Obecnie mamy trzy standardy kanałów: Really Simple Syndication (RSS), Atom oraz JSON Feed. Te dwa pierwsze to formaty oparte o XML, podczas gdy ostatni, jak sama nazwa sugeruje, o JSON. Na tym blogu stosuję format Atom.

Problemy z kanałem

Przy okazji odświeżenia bloga dodałem też do nagłówków w postach linki odsyłające do konkretnych sekcji:

<h2 id="odświeżone-bloczki"> <!-- 2 -->
	<a class="header-anchor" href="#odświeżone-bloczki">Odświeżone bloczki</a> <!-- 1 -->
</h2>

Zawartość nagłówka jest otoczona linkiem (1), który odsyła do tego nagłówka przy pomocy kotwicy (2). Problem polega na tym, że atrybut [href] zawiera samą nazwę kotwicy, nie cały URL. A to sprawia, że gdy taki link zostanie wyciągnięty poza oryginalny kontekst (np. do czytnika kanałów), linki w nagłówkach przestają działać. I od dłuższego czasu odkładałem poprawienie tego na później, aż w końcu…

…aż w końcu zmieniłem też bloczki kodu i do problemu z nagłówkami doszedł kolejny:

Z racji tego, że czytnik kanałów wycina potencjalnie niebezpieczne elementy, przycisk do kopiowania zawartości bloczków kodu zamienił się w zwykły tekst. Co więcej, nawet gdyby mój czytnik zostawił w tym miejscu przycisk, to i tak by on nie zadziałał, bo nie ma sposobu na dodanie JS-a do kanału Atom. Innymi słowy: kanał mojego bloga miał już dwa niedziałające elementy. Przyszła pora, by coś z tym zrobić!

Naprawa HTML-a

Postanowiłem dodać filtr w Eleventy, który brałby treść posta i wycinał z niego wszystkie elementy, które nie działają w kanale. Problem polega jednak na tym, że w momencie stosowania filtru zawartość posta jest już sparsowana z Markdowna do HTML-a. A to oznacza, że muszę parsować HTML. W tym celu postanowiłem użyć biblioteki cheerio, która dostarcza API podobnego do jQuery. Ostatecznie powstał następujący filtr:

import { load } from 'cheerio'; // 2

const MORE_COMMENT_REGEX = /<!--\s*more\s*-->/; // 10

eleventyConfig.addFilter( 'rss_content', ( post ) => { // 1
	const postURL = cfUrl( new URL( post.data.permalink, post.data.site.url ).href ); // 7
	const $ = load( post.content ); // 3

	$( ':where(h1, h2, h3, h4, h5, h6) a' ).each( ( _, link ) => { // 4
		const $link = $( link );
		const originalHref = $link.attr( 'href' ); // 5

		$link.attr( 'href', postURL + originalHref ); // 6
	} );
	$( '.code__copy' ).remove();

	return $( 'body' ).html().replace( MORE_COMMENT_REGEX, '' ); // 9
} );

Dodajemy nowy filtr o nazwie rss_content (1). Przekazujemy mu obiekt wpisu. Następnie importujemy funkcję load() z biblioteki cheerio (2). Pozwala ona sparsować kod HTML do DOM-u. Używamy jej do sparsowania zawartości postu (3). Na tak stworzonym drzewku wyszukujemy wszystkie linki w naglówkach (4) i dla każdego z nich pobieramy wartość atrybutu [href] (5) oraz zamieniamy go na absolutny URL (6) – a więc #odświeżone-bloczki zamienią się na https://blog.comandeer.pl/inkunabuly-madrosci#odświeżone-bloczki. Absolutny URL uzyskujemy, sklejając link do posta z linkiem do strony przy pomocy konstruktora URL (7). Link do posta jest dostarczony przez Eleventy, natomiast link do strony – przeze mnie przy pomocy mechanizmu globalnych plików z danymi. Po naprawieniu linków, wyszukujemy i usuwamy wszystkie przyciski do kopiowania kodu (8). Na koniec wyciągamy kod HTML z DOM-u i usuwamy z niego komentarz <!--more--> (9) przy pomocy wyrażenia regularnego (10). Mimo usilnych starań nie udało mi się usunąć go w bardziej przyzwoity sposób, używając API biblioteki cheerio. Warto tutaj zwrócić uwagę, że kod HTML wyciągamy z elementu body. Biblioteka cheerio parsuje bowiem HTML zgodnie z regułami opisanymi w specyfikacji, a więc – jako pełny dokument, co sprawia, że dodaje brakujące elementy html i body. Można też wymusić na cheerio parsowanie w trybie fragmentu, podając false jako trzeci argument do funkcji load().

Tajemnicza funkcja cfUrl() z poprzedniego fragmentu kodu wycina z przekazanego linku rozszerzenie .html lub fragment index.html:

function cfUrl( url ) {
	return url.replace( /index\.html$/, '' ).replace( /\.html$/, '' );
}

Dzięki temu linki typu /blog-2.0.html lub /kategorie/javascript/index.html zmienią się odpowiednio w /blog-2.0 oraz /kategorie/javascript.

Tak stworzony filtr dodajemy następnie do szablonu kanałów, w miejscu, w którym wyświetlana jest treść posta:

<content type="html"><![CDATA[{{ post | rss_content }}]]></content>

I to w sumie tyle! W końcu kanały bloga powinny działać poprawnie.

Stare bloczki

Stare bloczki… były:

Co prawda spełniały swoje zadanie, miały nawet dobre kolorowanie składni (dzięki Shiki), ale brakowało w nich choćby informacji o języku programowania. Dlatego też postanowiłem je nieco odświeżyc.

Odświeżone bloczki

Nowe bloczki wyglądają następująco:

Tak naprawdę zmiany nie są szczególnie wielkie – pojawiła się jedynie nazwa języka oraz przycisk do skopiowania kodu do schowka.

Nowy HTML

Od strony HTML-a cały bloczek kodu trafił do elementu figure:

<figure class="code" typeof="SoftwareSourceCode">
	<figcaption class="code__caption"> <!-- 3 -->
		<span class="code__title" property="programmingLanguage">CSS</span> <!-- 1 -->
		<button class="code__copy">Kopiuj</button> <!-- 2 -->
	</figcaption>
	<div class="code__code" translate="no" property="text"> <!-- 4 -->
		<pre><code>[…]</code></pre> <!-- 5 -->
	</div>
</figure>

Podpis z nazwą języka (1) i przyciskiem (2) został umieszczony w figcaption (3), natomiast sam kod w dodatkowym divie z atrybutem [translate=no] (4). Dzięki temu Google Translate i podobne usługi nie będą próbowały tłumaczyć kodu na inne języki. Dodatkowo zastosowałem też RDFa, żeby oznaczyć całość jako kod w języku programowania. Sam kod (5) pozostał bez zmian – dalej jest kolorowany przez Shiki.

Nowy JS

Przycisk do kopiowania kodu potrzebuje obsługi w JS-ie. Dodałem więc taką do swojego pliku JS:

document.addEventListener( 'click', async ( evt ) => { // 1
	const isCopyButton = evt.target.closest( '.code__copy' ); // 2

	if ( !isCopyButton ) {
		return;
	}

	const closestCode = evt.target.closest( '.code' ).querySelector( '.code__code' ); // 3

	await navigator.clipboard.writeText( closestCode.innerText ); // 4
} );

Stosuje tutaj technikę event delegation (delegacji zdarzeń) (1). Dzięki temu mogę przypiąć tylko jeden nasłuchiwacz i obsłużyć wszystkie przyciski “Kopiuj”, zamiast musieć się przypiąć do każdego z nich osobno. Niemniej ta technika sprawia, ze muszę sprawdzić, czy na pewno został kliknięty przycisk “Kopiuj”. Robię to przy pomocy wyszukania go przez metodę #closest() (2). Metoda ta zwróci najbliższy element o klasie .code__copy. W przypadku, gdy ktoś kliknie przycisk, będzie to on sam. Metoda #closest() zabezpiecza nas przed przypadkiem, gdybyśmy dodali kiedyś ikonkę do przycisku i ktoś kliknął w nią – wówczas zamiast przycisku mielibyśmy w evt.target np. element svg. Jak już ustalimy, że został naciśnięty odpowiedni przycisk, wyszukujemy najbliższy bloczek kodu (3). Następnie wywołujemy metodę Clipboard#writeText(), do której przekazujemy tekstową zawartość bloczka (4). Jeśli osoba naciskająca przycisk wyrazi zgodę na zapisanie danych do schowka, kod zostanie skopiowany.

Nowy backend

Nowe bloczki kodu renderowane są przy pomocy autorskiego pluginu do MarkdownIt (biblioteki renderującej Markdowna w Eleventy). Jego kod prezentuje się następująco:

function markdownItCodeBlock( markdownIt ) {
	const originalFenceRule = markdownIt.renderer.rules.fence; // 1

	markdownIt.renderer.rules.fence = ( tokens, idx, options, env, slf ) => {
		const token = tokens[ idx ];
		const lang = token.info ? token.info.trim() : ''; // 3
		const renderedCodeBlock = originalFenceRule( tokens, idx, options, env, slf ); // 4

		/ * 5 */ return `<figure class="code" typeof="SoftwareSourceCode">
			<figcaption class="code__caption">
				<span class="code__title" property="programmingLanguage">${ langs[ lang ] ?? '' }</span>
				<button class="code__copy">Kopiuj</button>
			</figcaption>
			<div class="code__code" translate="no" property="text">
				${ renderedCodeBlock }
			</div>
		</figure>`;
	};
}

Na początku zapisujemy sobie do zmiennej aktualną funkcję do renderowania bloczków kodu (1). W przypadku MarkdownIt funkcja ta znajduje się w regułach renderera. Następnie nadpisujemy tę regułę własną (2). Wyciągamy z kodu Markdown nazwę języka programowania (3), a następnie wywołujemy oryginalną regułę renderującą bloczki kodu (4). Dzięki temu dostajemy kod ładnie pokolorowany przez Shiki. Na koniec tworzymy nasz własny kod HTML bloczka (5), do którego wsadzamy pokolorowany kod i zwracamy całość z funkcji.

Teraz zostaje tylko dodać ten plugin do naszej zmodyfikowanej wersji MarkdownIt. Można to zrobić przy pomocy metody #use().

I to tyle! Bloczki kodu na blogu są od teraz nieco lepsze.

Kompatybilność?

Obecnie na rynku mamy trzy duże silniki przeglądarek: Blink (używany w Chrome), WebKit (Safari) oraz Gecko (Firefox). Do tego dochodzą różne przeglądarki oparte na różnych wersjach tych trzech silników, ale też np. rozwiązania pokroju Electrona, który pozwala tworzyć aplikacje desktopowe na Chromium. Powstają też dwa nowe, duże silniki: Servo oraz Ladybird.

W teorii wszystkie te silniki wspierają te same standardy sieciowe. Ale w praktyce różnice mogą być znaczące. Po pierwsze, istnieje bardzo dużo standardów sieciowych, które nieustannie się zmieniają (np. specyfikacja HTML w momencie pisania tego artykułu była zmieniana ostatnio 17 grudnia 2025). Niektóre przeglądarki nie mają na tyle zasobów, by implementować wszystkie najnowsze standardy i robią to z opóźnieniem. Dodatkowo, nawet jeśli przeglądarka X zaimplementuje jakiś standard z wersji z listopada, to wersja z grudnia może być już zupełnie inna. Tym samym dwie przeglądarki implementujące ten sam standard mogą nie być kompatybilne między sobą.

Kolejnym czynnikiem są różne priorytety przeglądarek. Niektóre przeglądarki skupiają się na dostarczaniu coraz to nowych ficzerów, podczas gdy inne stawiają na innowacje w innych obszarach, jak np. UI samej przeglądarki. Dobrym przykładem może być tutaj Projekt Fugu. Google zgłosiło szereg propozycji standardów sieciowych, które miały zminimalizować różnice między możliwościami aplikacji natywnych oraz webowych. Wśród propozycji były m.in. WebUSB czy Web NFC. Zarówno Firefox, jak i Safari, odmówiły implementacji tych propozycji, wskazując na potencjalne problemy z bezpieczeństwem i prywatnością.

Wreszcie: zarówno przeglądarki, jak i same specyfikacje, mają bugi. Dodatkowo specyfikacje można interpretować na różne sposoby, nawet jeśli włożono spory wysiłek w to, by ich tekst był jak najbardziej jednoznaczny. Tutaj na pomoc przychodzą Web Platform Tests – testy sprawdzające zgodność implementacji ze standardami sieciowymi. I choć dostarczają one dokładnych wyników, to są przeznaczone raczej dla osób, które zawodowo zajmują się tworzeniem przeglądarek lub standardów. Dla całej reszty mogą być mało czytelne.

Baseline

Dlatego też powstał Baseline. To wskaźnik pierwotnie zaproponowany przez Chrome’a w trakcie Google I/O 2023. Obecnie jest rozwijany przez Web Developer Experience Community Group. Jego zadaniem jest wskazywanie, czy dany ficzer jest już dostępny we wszystkich najpopularniejszych przeglądarkach, czyli w Chrome (na desktopie i Androdzie), Firefoksie (na desktopie i Androidzie), Edge’u (na desktopie) oraz Safari (na desktopie i iOS-ie).

Każdy ficzer może mieć trzy poziomy wsparcia:

• Limited availability (ograniczona dostępność) – dany ficzer wciąż nie jest dostępny we wszystkich przeglądarkach,
• Newly available (świeżo dostępny) – dany ficzer jest dostępny w najnowszych wersjach przeglądarek, może nie działać w starszych,
• Widely available (szeroko dostępny) – dany ficzer jest dostępny we wszystkich przeglądarkach od co najmniej 30 miesięcy (2.5 roku).

Baseline ma dostarczać prostej odpowiedzi na pytanie, czy ficzer X można już używać w projektach. Niemniej nie mówi nic ponad to, w jakich przeglądarkach dany ficzer jest dostępny. Jeśli potrzebujemy większej liczby szczegółów, wciąż trzeba sięgnąć po dokładniejsze źródła, takie jak choćby wspomniane już Web Platform Tests. Co więcej, wskaźnik ten nie uwzględnia różnic w implementacji danego standardu w przeglądarkach. Jedynie wskazuje, czy jest on obsługiwany w jakikolwiek sposób. A to może też prowadzić do przekłamań, np. niektóre API są oznaczone jako mające ograniczoną dostępność, bo nie są dostępne w desktopowych przeglądarkach – mimo że niekoniecznie mają w nich sens (np. wspomniane już Web NFC).

Mimo swoich wad, Baseline już jest stałym elementem choćby dokumentacji MDN czy Web.dev. Osobiście mam co do niego mieszane uczucia, ale nie można mu odmówić jednego: robi dokładnie to, do czego go stworzono. A przez to już jest lepszy od wielu technologii sieciowych…

Problem z istniejącymi aplikacjami

Żeby zabezpieczyć aplikację przy pomocy HTML Sanitizer API, trzeba zadbać o to, żeby wszystkie miejsca, w których dodajemy HTML, korzystały z nowej metody #setHTML(). Innymi słowy: wszystkie wystąpienia własności #innerHTML trzeba podmienić. I choć na pierwszy rzut oka nie wydaje się to specjalnie skomplikowane, to z powodu złożoności aplikacji może to nastręczyć sporo problemów.

Pierwszym z nich jest zmiana zachowania aplikacji. Dotąd HTML był ustawiany bez dodatkowego czyszczenia. Teraz jest filtrowany. W zależności od aplikacji, może to być problemem. Weźmy takiego CKEditora. Jeśli nagle przestanie działać dodawanie obrazków w edytorze (bo HTML Sanitizer APi je wytnie), to on sam stanie się średnio użyteczny. Stąd proste podmienienie własności #innerHTML na metodę #setHTML() w takim wypadku nie zadziała.

Drugi z problemów związany jest z samym refactorem. Bo to prawie nigdy nie jest po prostu podmiana czegoś w kodzie. Często trzeba też zmienić choćby testy, które mogą zacząć padać po zmianie zachowania aplikacji. Często też trzeba sprawdzić, czemu testy nie zaczęły padać – by się upewnić, że na pewno wszystko dobrze testują.

Trzeci problem to zależności aplikacji. Nasz kod możemy w ten czy inny sposób zrefactoryzować. Ale z zależnościami nie jest już tak łatwo i najczęściej kończy się na czekaniu, aż dany projekt doda wsparcie dla nowego API. A na to se można poczekać – o ile dany projekt w ogóle będzie chciał taką zmianę wprowadzić.

I wreszcie: kompatybilność. Dopóki HTML Sanitizer API nie będzie miało sensownego wsparcia we wszystkich najważniejszych przeglądarkach, trzeba będzie zadbać o alternatywę. Najprawdopodobniej w postaci polyfilla. A to dodatkowo niepotrzebnie skomplikuje kod i dołoży kolejną zależność do projektu.

Innymi słowy: wdrożenie HTML Sanitizer API może być sporym wyzwaniem w istniejących projektach.

Trusted Types API

Na szczęście istnieje inne API, które ma zdecydowanie lepsze wsparcie i które można wpiąć w już istniejące aplikacje przy minimalnej ingerencji. To API to Trusted Types API (API Zaufanych Typów). Pozwala ono zabezpieczyć tzw. injection sinks (miejsca wstrzykiwania) przy pomocy polityk.

Miejsca wstrzykiwania

Miejsca wstrzykiwania to wszystkie te fragmenty kodu, w których do strony WWW jest dodawana treść lub może być wykonany skrypt JS. Najprostszym przykładem jest własność #innerHTML, przy pomocy której można wsadzić HTML do wybranego elementu. Są też jednak mniej oczywiste przykłady:

• własność HTMLScriptElement#text – służąca do zmiany zawartości elementu script,
• własność HTMLScriptElement#src – służąca do zmiany źródła elementu script,
• funkcja eval() – wykonująca przekazany jej kod JS,
• metoda DOMParser#parseFromString() – parsująca przekazany kod HTML,
• metoda setHTMLUnsafe() – służąca do zmiany zawartości elementu z pominięciem czyszczenia przekazanego kodu.

Takie przykłady można by mnożyć. MDN zawiera sporą listę potencjalnych miejsc wstrzykiwania.

Polityki

Trzonem Trusted Types API są tzw. polityki. To obiekty zawierające konfigurację opisują, w jaki sposób mają być zabezpieczone poszczególne miejsca wstrzykiwania. Każda polityka może składać się z trzech metod-fabryk:

• #createHTML() – służąca do tworzenia obiektów TrustedHTML, które mogą być później używane wszędzie tam, gdzie trzeba przekazać kod HTML, np. własność #innerHTML lub metoda #setHTMLUnsafe(),
• #createScript() – służąca do tworzenia obiektów TrustedScript, które mogą być później używane tam, gdzie jest potrzebny kod JS, np. wewnątrz funkcji eval(),
• #createScriptURL() – służąca do tworzenia obiektów TrustedScriptURL, które mogą być później używane tam, gdzie potrzebny jest adres skryptu JS, np. we własności HTMLScriptElement#src.

Żeby dodać nową politykę, trzeba skorzystać z metody trustedTypes#createPolicy():

const policy = trustedTypes.createPolicy( 'my-policy', { // 1
	createHTML( html ) { // 2
		return sanitizeHTML( html );
	},

	createScript( js ) { // 3
		return sanitizeJS( js );
	},

	createScriptURL( url ) { // 4
		return sanitizeURL( url );
	}
} );

Tworzymy nową politykę o nazwie my-policy i zapisujemy ją do zmiennej policy (1). Ma ona wszystkie trzy metody – #createHTML() (2), #createScript() (3) oraz #createScriptURL() (4). Zwracają one przekazany im kod przepuszczony przez odpowiednie funkcje filtrujące (5, 6, 7 ). To, co te funkcje robią, zależy w zupełności od nas. W końcu każda aplikacja jest inna i może mieć inne wymagania odnośnie czyszczenia HTML-a czy JS-a. Na potrzeby przykładu stwórzmy zaślepki, które po prostu zwrócą przekazany im argument:

function sanitizeHTML( html ) {
	return html;
}

function sanitizeJS( js ) {
	return js;
}

function sanitizeURL( url ) {
	return url;
}

Żeby wykorzystać w praktyce naszą politykę, trzeba wywołać jej metody:

const div = document.createElement( 'div' ); // 1

div.innerHTML = policy.createHTML( '<p>Jestem zaufanym HTML-em</p>' ); // 2

eval( policy.createScript( 'alert(1)' ) ); // 3

const script = document.createElement( 'script' ); // 4

script.src = policy.createScriptURL( 'data:text/javascript;charset=utf-8;base64,YWxlcnQoMSk=' ); // 5

Tworzymy element div (1), a następnie wsadzamy do niego “zaufany” HTML, stworzony przy pomocy metody policy#createHTML() (2). Z kolei do funkcji eval() przekazujemy “zaufany” skrypt, stworzony przy pomocy metody policy#createScript() (3). Na koniec tworzymy element script (4) i ustawiamy jego własność #src na “zaufany” URL skryptu stworzony przy pomocy metody policy#createScriptURL() (5).

Wymuszanie polityki

Samo jednak dodanie polityki nie zabezpieczy aplikacji. Przeglądarka nie będzie miała żadnego problemu z tym, żeby ją ominąć i ustawić własność #innerHTML na dowolny tekst. Dlatego API dostarcza też mechanizm, który wymusza stosowanie polityki. Służy do tego dyrektywa require-trusted-types-for w nagłówku HTTP Content-Security-Policy:

Content-Security-Policy: require-trusted-types-for 'script';

Jak na razie jedyną wartością dla tej dyrektywy jest 'script', która pokrywa wszystkie trzy przypadki (kod HTML, kod JS i URL-e skryptów).

Jeśli wyślemy taki nagłówek HTTP, a następnie spróbujemy wstawić niezabezpieczony tekst do własności #innerHTML, powinniśmy otrzymać następujący błąd:

This document requires 'TrustedHTML' assignment. The action has been blocked.

Istnieje też dyrektywa trusted-types, która kontroluje tworzenie polityk:

Content-Security-Policy: require-trusted-types-for 'script';trusted-types my-policy;

Taki nagłówek wymusi używanie polityki, a równocześnie pozwoli stworzyć jedynie taką o nazwie my-policy.

Domyślna polityka

Ale zaraz, zaraz – czy to API nie miało być tym “mniej inwazyjnym”, które nie wymaga sporego refactoru istniejących aplikacji? Takie tworzenie polityk wydaje się wręcz jeszcze bardziej upierdliwe, niż prosta zamiana #innerHTML na #setHTML(). Na całe szczęście Trusted Types API ma asa w rękawie: domyślną politykę. Jeśli wymusimy stosowanie polityk przy pomocy dyrektywy require-trusted-types-for, a następnie stworzymy politykę o nazwie default, będzie ona automatycznie wykorzystywana w każdym miejscu wstrzykiwania:

trustedTypes.createPolicy( 'default', { // 1
	createHTML( html ) {
		console.log( 'HTML' ); // 5

		return html; // 2
	},

	createScript( js ) {
		console.log( 'JS' ); // 6

		return js; // 3
	},

	createScriptURL( url ) {
		console.log( 'URL' ); // 7

		return url; // 4
	}
} );

Tworzymy nową politykę o nazwie 'default' (1). Ponownie tworzymy metody-fabryki, w których zwracamy przekazany im kod (2, 3, 4). Wcześniej jednak logujemy w konsoli, jaki typ danych filtrujemy (5, 6, 7)

Wykorzystanie tej polityki jest całkowicie przezroczyste:

const div = document.createElement( 'div' );

div.innerHTML = '<p>Jestem zaufanym HTML-em</p>'; // 1

eval( 'alert(1)' ); // 2

const script = document.createElement( 'script' );

script.src = 'data:text/javascript;charset=utf-8;base64,YWxlcnQoMSk='; // 3

Nie trzeba się już odwoływać do polityki ani przy przypisywaniu wartości do własności #innerHTML (1), ani przy wywoływaniu funkcji eval() (2), ani przy ustawianiu źródła skryptu (3).

Jeśli odpalimy ten kod w przeglądarce, wówczas powinniśmy zobaczyć w konsoli logi potwierdzające, że polityka została zaaplikowana do każdego z trzech miejsc wstrzykiwania.

Kompatybilność

Specyfikacja Trusted Types API jest już na dość zaawansowanym etapie standaryzacji. Choć wciąż może się zmieniać, nie oczekiwałbym jakichś wielkich, wywrotowych zmian. Jak już jakieś nastąpią, to raczej kosmetyczne. Natomiast wsparcie jest już od dłuższego czasu zarówno w Chrome, jak i w Safari. W Firefoksie wciąż jest eksperymentalne za flagą.

Myślę, że dopóki wsparcie nie będzie we wszystkich najważniejszych przeglądarkach, najlepiej się ograniczyć do tworzenia domyślnej polityki i wymuszać ją przy pomocy dyrektywy require-trusted-types-for. Dzięki temu całość będzie jak najbardziej transparentna dla przeglądarek, które wciąż nie wspierają tego API. Natomiast cała reszta dostanie lepsze zabezpieczenie przed atakami XSS.

I w końcu będzie można zacząć ufać własności #innerHTML!

Definicja

TAG proponuje następującą definicję agenta osoby użytkowniczej:

A web user agent is any software entity that interacts with websites outside the entity itself, on behalf of its user, including simply rendering the content of websites. […] The most common type of web user agent is the web browser, including in-app browsers that can follow cross-site links. However, user agents also include other tools like search engines, voice-driven assistants, and generative AI systems that present snippets or summaries of website content, or help people navigate and interact with websites.

[Sieciowy agent osoby użytkowniczej to każde oprogramowanie, wchodzące w interakcje ze stronami WWW, pozostającymi poza tym oprogramowaniem, na polecenie swojej osoby użytkowniczej; interakcje obejmują m.in. samo renderowanie zawartości stron. […] Najpopularniejszym typem sieciowego agenta osoby użytkowniczej jest przeglądarka, włączając w to przeglądarki wbudowane w aplikacje, mogące korzystać z linków między stronami. Niemniej termin “agenty osoby użytkowniczej” zawiera także inne narzędzia, takie jak wyszukiwarki, asystenci do sterowania głosem oraz systemy generatywnego AI, które prezentują wycinki lub podsumowania zawartości stron lub pomagają osobom nawigować i wchodzić w interakcje ze stronami.]

Brzmi to strasznie zawile, więc spróbujmy to uprościć. W największym skrócie: sieciowy agent osoby użytkowniczej to dowolny progam, dzięki któremu można coś zrobić ze stroną WWW. Przeglądarka spełnia tę definicję, ponieważ pozwala wyświetlać stronę WWW. Wyszukiwarka spełnia tę definicję, bo umożliwia znalezienie konkretnej strony lub przeszukanie jej treści. ChatGPT też spełnia tę definicję, ponieważ może podsumować treść strony.

Warto też zwrócić uwagę, że w definicji pada sformułowanie sieciowy agent. Jak bowiem TAG zauważa, istnieć mogą też inne agenty, np. mailowy agent – a więc taki, przez którego wyślemy i odbierzemy maila.

Oprócz definicji TAG wymienia też trzy obowiązki agenta:

• ochrona – interakcje ze stronami WWW muszą być bezpieczne, czyli np. strona nie może bez pozwolenia zmieniać ustawień komputera, a przeglądarka nie może sama z siebie wysłać stronie numeru karty kredytowej swojej osoby użytkowniczej;
• szczerość – agent powinien zawsze informować osobę użytkowniczą, co się dzieje, i to w sposób dla niej zrozumiały, np. pasek adresu w przeglądarce powinien pokazywać poprawny adres obecnie przeglądanej strony;
• lojalność – agent powinien przedkładać interes swojej osoby użytkowniczej ponad interes kogokolwiek innego, np. przeglądarka wbudowana w aplikację nie może utrudniać próby otwarcia strony w innej przeglądarce tylko po to, by zatrzymać kogoś wewnątrz siebie.

TAG?

No dobrze, ale czym jest ten cały TAG? TAG, a dokładniej W3C Technical Architecture Group (Grupa Architektury Technicznej W3C), to trochę taka starszyzna standardów sieciowych. W jej skład wchodzą osoby wybierane na dwuletnie kadencje przez członków W3C (czyli firmy zgromadzone w W3C) lub wskazywane przez zespół W3C oraz Tim Berners-Lee, jedyny dożywotni członek. Zadanie TAG jest ściśle określone i sprowadza się przede wszystkim do doradzania innym grupom, w jaki sposób rozwiązywać techniczne zagwozdki, oraz do dokumentowania zasad, jakie powinny przyświecać standardom sieciowym. Przykładem tej drugiej części działalności grupy jest definicja agenta osoby użytkowniczej, ale też Ethical Web Principles (Zasady Etycznej Sieci). Z kolei przykładem pierwszej są publiczne dyskusje nad propozycjami nowych standardów.

Co prawda TAG nie bierze bezpośredniego udziału w tworzeniu standardów, a ma jedynie doradzać, jednak uwagi zgłaszane przez tę grupę najczęściej są brane pod uwagę. W TAG-u siedzą ludzie, którzy zjedli zęby na standardach sieciowych i są w stanie zauważyć niedoskonałości w większości pokazywanych im API. Czy to na poziomie czysto technicznym, czy też na poziomie np. potencjalnych zagrożeń prywatności. Mając osoby z takim doświadczeniem na wyciągnięcie ręki, głupio byłoby z ich wsparcia nie skorzystać.

Więc korzystajmy!

XSS – czyli co zagraża aplikacji WWW?

Zacznijmy od tego, czym w ogóle jest atak Cross-Site Scripting (XSS). W największym skrócie: to atak polegający na wstrzyknięciu złośliwego kodu na stronę WWW. Ten kod następnie zostanie wykonany przez przeglądarkę osoby odwiedzającej stronę. Taki kod może zrobić tak naprawdę wszystko, co potrafi JS w przeglądarce, np. pobranie ciasteczek i wysłanie ich do zewnętrznego serwera.

Wstrzyknięcia można dokonać na wiele różnych sposobów. Jednym z najczęstszych jest wykorzystanie formularzy na stronie, np. edytora postów na blogu czy księgi gości. Jeśli dostęp do takiego formularza mają też niezaufane osoby, wówczas jest spora szansa, że jedna z nich spróbuje zaatakować stronę. Choćby zostawiając poniższy wpis:

<img src="x" onerror="alert( 'Słaba ta strona!' )">

Jeśli w żaden sposób nie filtrujemy danych przychodzących, tego typu kod może trafić do bazy danych, a ostatecznie – do przeglądarek innych osób odwiedzających stronę. Każdej z tych osób pokaże się wówczas wyskakujące okienko z tekstem Słaba ta strona!. Dzieje się tak, ponieważ atrybut [onerror] dodaje do obrazka nasłuchiwacz dla zdarzenia error. A to odpala się m.in wówczas, gdy wczytywany obrazek nie istnieje. Jeśli nie mamy na stronie obrazka pod ścieżką /x (a mało kto ma), to zdarzenie się odpali i kod wykona się u niczego niepodejrzewających osób odwiedzających naszą stronę.

Istniejące sposoby ochrony

Mimo że XSS to jeden z podstawowych typów ataków, niemal tak stary jak sam Internet, to wciąż jest niezwykle popularny. Wciąż mocno się trzyma na liście Top 10 OWASP – raporcie opisującym dziesięć najpopularniejszych typów ataków w Internecie. Dlatego też wciąż potrzeba sensownych i sprawdzonych metod obrony przed nim. Dotąd trzeba było wykorzystywać w tym celu różne biblioteki. Jedną z najpopularniejszych jest DOMPurify, które działa nie tylko w przeglądarce, ale także w Node.js. Działanie tej biblioteki można zobaczyć w oficjalnym demie. Polega na usuwaniu z przekazanego ciągu tekstowego wszystkich niebezpiecznych fragmentów HTML-a. Jako przykład posłuży nam następujący kod:

<script>alert( 'script' );</script> <!-- 1 -->
<img src="x" alt="" onerror="alert('obrazek')"> <!-- 2 -->
<span onmouseover="alert('hover')">Najedź mnie</span> <!-- 3 -->

Powyższy kod HTML po odpaleniu w przeglądarce wyświetli trzy wyskakujące okienka:

1. po wykonaniu skryptu z elementu script,
2. po błędzie wczytywania obrazka,
3. po najechaniu na tekst Najedź mnie.

Po przepuszczeniu tego kodu przez DOMPurify dostaniemy:

<img src="x" alt=""> 
<span>Najedź mnie</span> 

Wszystkie JS-owe elementy kodu zostały usunięte, tym samym zostawiając wyłącznie bezpieczny HTML.

HTML Sanitizer API – nowy obrońca Sieci

W końcu doczekaliśmy się API chroniącego przed XSS-em, które jest wbudowane w przeglądarkę – HTML Sanitizer API (API Dezynfekujące HTML-a). Składają się na niego dwa główne elementy:

1. metoda #setHTML(), dołączona do elementów HTML i korzeni Shadow DOM,
2. statyczna metoda Document.parseHTML().

Bezpieczny zaułek

Metoda #setHTML() jest odpowiednikiem własności #innerHTML. Główna różnica między nimi polega na tym, że nowa metoda wyrzuca z przekazanego jej kodu HTML wszystkie niebezpieczne elementy:

document.body.setHTML( `<script>alert( 'script' );</script>
<img src="x" alt="" onerror="alert('obrazek')">
<span onmouseover="alert('hover')">Najedź mnie</span>` );

Wykonanie tego kodu sprawi, że zawartość strony zostanie podmieniona na następującą:

<span>Najedź mnie</span>

Jak widać, natywne API jest nawet dokładniejsze niż domyślne ustawienia biblioteki DOMPurify. Zniknął bowiem cały element img. Gdy przyjrzymy się algorytmowi dezynfekcji HTML-a w specyfikacji, zauważymy, że jednym z kroków jest usuwanie elementów, które nie występują w konfiguracji dezynfekcji. Jeśli nie podamy własnego obiektu z opcjami, wówczas zostanie użyty domyślny – a ten nie zawiera elementu img. Stąd nie ma go też w wynikowym HTML-u. Teoretycznie, żeby zachować obrazek, jako drugi argument metody #setHTML() trzeba podać obiekt konfiguracyjny – ale na ten moment nie działa to w żadnej przeglądarce.

Z kolei metoda statyczna Document.parseHTML() jest odpowiednikiem wbudowanego parsera HTML. Metoda parsuje kod HTML, czyści go ze wszystkich niebezpiecznych fragmentów, a następnie tworzy nowy obiekt Document na jego podstawie:

console.log( Document.parseHTML( `<!DOCTYPE html>
    <html lang="pl">
        <head>
            <title>Testowy dokument</title>
        </head>
        <body>
            <script>alert( 'script' );</script>
            <h1>Hello, world!</h1>
        </body>
    </html>`) );

Ten kod wyświetli w konsoli następujący dokument:

<!DOCTYPE html>
<html lang="pl">
	<head>
		<title>Testowy dokument</title>
	</head>
	<body>
		<h1>Hello, world!</h1>
	</body>
</html>

Jak widać, dokument jest praktycznie identyczny jak ten, który przekazaliśmy metodzie Document.parseHTML(). Jedyną różnicą jest brak elementu script.

Niebezpieczna manipulacja

Warto wspomnieć, że zarówno #setHTML(), jak i Document.parseHTML(), mają swoje “niebezpieczne” odpowiedniki – #setHTMLUnsafe() oraz Document.parseHTMLUnsafe(). Działają tak samo, ale nie usuwają niczego.

Tym samym, jeśli użyjemy #setHTMLUnsafe() na naszym testowym kodzie HTML:

document.body.setHTMLUnsafe( `<script>alert( 'script' );</script>
<img src="x" alt="" onerror="alert('obrazek')">
<span onmouseover="alert('hover')">Najedź mnie</span>` );

do zawartości strony trafi dokładnie ten kod HTML, bez żadnego czyszczenia:

<script>alert( 'script' );</script>
<img src="x" alt="" onerror="alert('obrazek')">
<span onmouseover="alert('hover')">Najedź mnie</span>

Podobnie stanie się, jeśli podmienimy Document.parseHTML() na Document.parseHTMLUnsafe():

console.log( Document.parseHTMLUnsafe( `<!DOCTYPE html>
    <html lang="pl">
        <head>
            <title>Testowy dokument</title>
        </head>
        <body>
            <script>alert( 'script' );</script>
            <h1>Hello, world!</h1>
        </body>
    </html>`) );

Ten kod stworzy dokładnie taki dokument HTML:

<!DOCTYPE html>
<html lang="pl">
	<head>
		<title>Testowy dokument</title>
	</head>
	<body>
		<script>alert( 'script' );</script>
		<h1>Hello, world!</h1>
	</body>
</html>

Kompatybilność

Gdzie zatem można użyć nowego API? Otóż… nigdzie. Pojawić się powinno w Firefoksie 147, którego wydanie planowane jest na 13 stycznia 2026 roku. W Chrome dostępne jest jako eksperymentalny ficzer, ukryty za flagą. Na ten moment nie wiadomo, kiedy trafi do Chrome’a jako stabilny ficzer. Na pewno nie pomaga temu fakt, że specyfikacja wciąż się zmienia i nie wyszła jeszcze z grupy inkubującej nowe standardy.

Zatem wygląda na to, że w najbliższej przyszłości rozwiązania pokroju DOMPurify wciąż będą jedynymi rozwiązaniami pozwalającymi dezynfekować kod HTML. Jednak przeglądarki mają w rękawie jeszcze jednego asa… Ale to już opowieść na inną okazję!

Zainteresowanie?

Wypada zacząć od wyjaśnienia, czym jest zainteresowanie w tym kontekście. W oficjalnej propozycji nowego API jest to wyjaśnione mocno enigmatycznie:

[…] rather than being activated via a click on the element, this API uses a lighter-touch way for the user to “show interest” in an element without fully activating it.

[[…] zamiast aktywowania poprzez klik na elemencie, to API używa lżejszego sposobu okazania przez osobę użytkowniczą “zainteresowania” elementem bez jego pełnej aktywacji.]

Taka definicja nie wyjaśnia za dużo, ale na szczęście jest cała sekcja poświęcona różnym sposobom interakcji z urządzeniem i jak się to przekłada na zainteresowanie:

Innymi słowy: “okazywanie zainteresowania” to ulepszony hover. Działa bowiem nie tylko z myszką, dostosowuje się także do innych urządzeń wejściowych i sposobów interakcji z urządzeniem.

Nowe API

Tooltipy

Nowe API jest podobne do istniejącego Invoker Commands API. Jego głównym elementem jest atrybut [interestfor]. Można go dodać do elementów a, area, button oraz a w SVG. Wskazuje on na element, z którym coś ma się stać, gdy elementowi z tym atrybutem okaże się zainteresowanie. Sztandarowym przykładem jest pokazanie tooltipa:

<button interestfor="tooltip">Jakiś przycisk</button> <!-- 1 -->
<span popover="hint" id="tooltip">Jakiś tooltip</span> <!-- 2 -->

Przycisk ma atrybut [interestfor], wskazujący na element #tooltip (1). Z kolei element #tooltip ma atrybut [popover=hint] (2). Dzięki temu po najechaniu myszą na przycisk, po chwili powinien pod nim pojawić się tooltip:

Natomiast sama wartość hint dla atrybutu [popover] informuje przeglądarkę, że ma traktować ten popover jako pomocniczy. Dzięki temu jego pojawienie się będzie zamykać jedynie inne pomocnicze popovery. Pozostałe będą go ignorować.

Położenie tooltipa można kontrolować przy pomocy własności CSS position-area:

[popover=hint] {
	position-area: bottom; /* 1 */
}

W naszym przykładzie użyliśmy wartości bottom (1), dzięki czemu tooltip pojawia się pod przyciskiem.

CSS pozwala także zmienić opóźnienie po interakcji z elementem, po którym przeglądarka uzna, że ktoś wyraża zainteresowanie:

[interestfor] { /* 2 */
	interest-delay: 0s; /* 1 */
}

W powyższym przykładzie ustawiliśmy opóźnienie na 0s (1). Tym samym będzie się to zachowywać praktycznie identycznie do pseudoklas :hover i :focus. Warto też zauważyć, że własność tę należy dodać do elementu z atrybutem [interestfor], nie zaś do popovera (2).

Zaawansowane interakcje

Można jednak tworzyć o wiele bardziej skomplikowane interakcje, niż pokazywanie tooltipa:

W powyższym przykładzie najechanie na przycisk sprawi trzy rzeczy:

1. najechany przycisk dostanie pomarańczowe tło,
2. kółko na środku strony zmieni kształt i kolor obramowania,
3. kółko na środku dostanie kolor tła równy zawartości atrybutu [data-color] najechanego przycisku.

Kod HTML wygląda następująco:

<p>
	<button interestfor="circle" data-color="pink">Różowy</button> <!-- 1 -->
	<button interestfor="circle" data-color="blue">Niebieski</button> <!-- 2 -->
	<button interestfor="circle" data-color="green">Zielony</button> <!-- 3 -->
</p>
<div class="circle" id="circle"></div> <!-- 4 -->

Każdy z przycisków (1, 2, 3) ma atrybut [interestfor] wskazujący na element #circle (4).

Z kolei kod CSS odpowiedzialny za zmianę tła przycisków oraz obramowania koła prezentuje się tak:

:interest-source { /* 1 */
	background: orange; /* 2 */
}
:interest-target { /* 3 */
	border: 2px #f00 dashed; /* 4 */
}

Pseudoklasa :interest-source (1) wskazuje na aktualnie najechany elementy z atrybutem [interestfor]. Dostanie on pomarańczowe tło (2). Z kolei element wskazywany przez atrybut [interestfor] aktualnie najechanego elementu jest wskazywany przez pseudoklasę :interest-target (3). Dostanie on czerwone, przerywane obramowanie (4).

Natomiast do zmiany tła kółka potrzebujemy kodu JS:

const circle = document.querySelector( '#circle' );

circle.addEventListener( 'interest', ( evt ) => { // 1
	evt.target.style.backgroundColor = evt.source.dataset.color; // 2
} );
circle.addEventListener( 'loseinterest', ( evt ) => { // 3
	evt.target.style.backgroundColor = 'transparent'; // 4
} );

Gdy najedziemy na przycisk z atrybutem [interestfor], na elemencie przez niego wskazywanym odpali się zdarzenie interest (1). Gdy zajdzie, do kółka przypisujemy kolor wskazywany przez atrybut [data-color] przycisku (2). Własność evt.target przechowuje element wskazywany przez atrybut [interestfor], podczas gdy evt-source – element z atrybutem [interestfor]. Z kolei, gdy zjedzie się myszą z przycisku, wówczas na kółku zostanie odpalone zdarzenie loseinterest (3). Wtedy też usuwamy mu tło (4).

Przyszłość

Nowe API ma zdecydowanie gorsze wsparcie niż swój klikalny odpowiednik. Na ten moment działa wyłącznie w Chrome i Edge’u. Co nie jest aż takie zaskakujące, jeśli weźmie się pod uwagę, że Interest Invoker API nie ma jeszcze nawet oficjalnej specyfikacji. To oznacza, że jeszcze trochę sobie poczekamy na w pełni natywne, deklaratywne tooltipy. A jest na co czekać, bo zrobienie ich dobrze, z dobrym pozycjonowaniem tooltipów, to jest zaskakująco skomplikowany problem. Istnieją całe biblioteki, takie jak Floating UI, których jedynym zadaniem jest obliczanie, w którym miejscu okienko z pomocną etykietą powinno się pokazać. Do tego trzeba dodać całą JS-ową logikę, która będzie pokazywać tooltipa po odpowiednio długim przytrzymaniu myszy na elemencie. A przecież trzeba jeszcze obsłużyć inne sposoby “okazywania zainteresowania”. To w gruncie rzeczy problem podobny do zamykania elementów UI zgodnie z konwencjami danej platformy.

Dlatego ja z niecierpliwością czekam na czasy, gdy okazywanie zainteresowania w końcu stanie się łatwe.

Podstawy działania ciasteczek, czyli stary przepis babci

Lata 90. to był dziwny czas dla platformy sieciowej. Jej kształt dopiero się wykuwał i sporo obecnie standardowych technologii wtedy nawet nie istniało. Same ciasteczka pojawiły się w 1994, więc na rok przed JavaScriptem! Z tego też względu oryginalna propozycja Netscape’a z oczywistych względów nie wspomina o żadnym JS-owym API. Zamiast tego jedynym sposobem ustawienia ciasteczek był nagłówek HTTP Set-Cookie:

Set-Cookie: NAME=VALUE; expires=DATE; path=PATH; domain=DOMAIN_NAME; secure

Jego poszczególne części to:

1. NAME – nazwa ciasteczka,
2. VALUE – wartość ciasteczka
3. expires=DATE – data ważności, po której ciasteczko zostanie usunięte; format daty opisany jest w standardzie RFC 2616,
4. path=PATH – ścieżka, dla której ciasteczko ma być używane,
5. domain=DOMAIN_NAME – nazwa domeny, dla której ciasteczko ma być używane,
6. secure – słowo kluczowe, oznaczające, że ciasteczko ma być wysyłane tylko bezpiecznym połączeniem (HTTPS).

Obowiązkowe było podanie tylko nazwy i wartości, resztę części można było ominąć.

Założenie ciasteczek było proste: serwer wysyła do przeglądarki jakąś informację (np. identyfikator koszyka w sklepie). Gdy dana strona zostanie potem ponownie odwiedzona, przeglądarka odsyła tę informację z powrotem. Robiła to przy pomocy nagłówka Cookie, dodawanego do żądania HTTP:

Cookie: cookie1=wartosc; cookie2=wartosc; cookie3=wartosc

Przeglądarka wysyłała jedynie nazwy i wartości istniejących ciasteczek. Każda para <nazwa, wartość> była oddzielona od siebie średnikiem. Tym sposobem można powiązać konkretną osobę (przeglądarkę) z konkretnymi danymi po stronie serwera.

Co ciekawe, nagłówek HTTP Set-Cookie niemalże w niezmienionej postaci przetrwał do dziś. Oficjalna specyfikacja ciasteczek, RFC 6265, definiuje go następująco:

Set-Cookie: NAME=VALUE; Expires=DATE; Max-Age=MAX_AGE; Domain=DOMAIN_NAME; Path=PATH; Secure; HttpOnly; EXTENSIONS

Tak naprawdę pojawiły się trzy nowe elementy:

1. Max-Age=MAX_AGE – liczba sekund, po której ciasteczko traci ważność,
2. HttpOnly – słowo kluczowe wskazujące, że ciasteczko ma być dostępne wyłącznie w żądaniach i odpowiedziach HTTP, bez dostępu z poziomu JS-a,
3. EXTENSIONS – dodatkowe elementy nagłówka, opisane w innych specyfikacjach.

Na ten moment istnieją tak naprawdę dwa ustandaryzowane dodatkowe elementy nagłówka:

1. Partitioned – słowo kluczowe wskazujące, że ciasteczko ma zostać wrzucone do osobnego słoika, dzięki czemu nie będzie mogło być użyte do śledzenia przeglądarki między różnymi stronami; część tzw. CHIPS (Cookies Having Independent Partitioned State, Ciasteczka Posiadające Niezależny Podzielony Stan),
2. SameSite=None|Lax|Strict – określa, jak ciasteczko ma się zachowywać w żądaniach pomiędzy różnymi stronami.

Nawet jednak biorąc pod uwagę cztery nowe elementy nagłówka Set-Cookie, można spokojnie uznać, że podstawy działania ciasteczek pozostały niezmienne od ponad 30 lat. To wciąż są małe fragmenty informacji, które serwer może zapisać w przeglądarce, a przeglądarka odeśle je z powrotem przy każdym żądaniu HTTP.

Stare API, czyli wyżerając surowe ciasto

Wraz z pojawieniem się JS-a powstała potrzeba odczytywania i ustawiania ciasteczek z jego poziomu. Powstała zatem własność document.cookie, Za jej pomocą można zarówno odczytywać, jak i zapisywać ciasteczka.

Żeby zapisać ciasteczko, ustawiamy wartość własności document.cookie na poprawną zawartość nagłówka HTTP Set-Cookie:

document.cookie = `myCookie=wartosc;Expires=${ ( new Date( '2030-12-31' ) ).toUTCString() }`;

Powyższy kod stworzy nowe ciasteczko o nazwie myCookie i wartości wartosc. Ciasteczko będzie ważne do 31 grudnia 2030 roku. Warto zwrócić uwagę, że wykorzystaliśmy tutaj metodę Date#toUTCString() – tworzy ona datę w formacie zgodnym ze standardem RFC 7231. Ogólnie można uznać, że to ten sam format, który jest akceptowany w nagłówku Set-Cookie.

Żeby odczytać istniejące ciasteczka, można odczytać wartość własności document.cookie:

console.log( document.cookie );

Zwróci to ciąg tekstowy w postaci:

cookie1=wartosc; cookie2=wartosc

Innymi słowy: jest to taki sam format, jaki ma nagłówek HTTP Cookie.

Stare JS-owe API ciasteczkowe jest, cóż, proste. I na tym jego lista zalet się kończy. Ustawianie zmiennej na wartość A, by następnie odczytać z niej wartość B samo w sobie brzmi jak słaby projekt API. Do tego dochodzą zwracanie ciasteczek w formie jednego, długiego ciągu znaków, który trzeba samemu parsować, oraz synchroniczność samego API. A mimo to przez lata nie doczekaliśmy się niczego sensowniejszego.

Nowe API, czyli przechowując ciasteczka w słoiku

Dopiero całkiem niedawno doczekaliśmy się nowego API, Cookie Store. Składa się ono z dwóch zasadniczych części: CookieStore oraz CookieStoreManager.

Przy ustawianiu i odczytywaniu ciasteczek potrzebny będzie nam CookieStore. Każda strona jest już w niego wyposażona, jako własność window.cookieStore:

await cookieStore.set( 'testowe', 'jakaś wartość' ); // 1
await cookieStore.set( { // 2
	name: 'testowe2',
	value: 'ęą',
	sameSite: 'strict'
} );

console.log( await cookieStore.getAll() ); // 3

await cookieStore.delete( 'testowe' ); // 4
console.log( await cookieStore.get( 'testowe' ) ); // 5

Na sam początek dodajemy przy pomocy metody CookieStore#set() nowe ciasteczko o nazwie testowe i wartości jakaś wartość (1). Jeśli chcemy podać więcej opcji przy tworzeniu ciasteczka, można przekazać do metody #set() obiekt z opcjami (2). Akceptowana jest większość opcji z nagłówka HTTP Set-Cookie, oprócz Secure (bo Cookie Store API i tak wymaga HTTPS) i HttpOnly (bo ciasteczka dostępne wyłącznie przez HTTP nie mają sensu w JS-ie). Następnie przy pomocy metody #getAll() wyświetlamy wszystkie zapisane ciasteczka (3). Potem, przy pomocy metody #delete() usuwamy ciasteczko testowe (4) i próbujemy je wyświetlić przy pomocy metody #get() (5). Z racji tego, że ciasteczka już nie ma, w konsoli pojawi się wartość null. Warto zwrócić przy okazji uwagę, że wszystkie metody CookieStore są asynchroniczne.

Na obiekcie CookieStore może też zajść zdarzenie change. Odpala się ono w momencie, gdy zajdzie jakakolwiek zmiana w ciasteczkach:

cookieStore.addEventListener( 'change', ( { changed, deleted } ) => { // 1
	console.group( 'CookieChangeEvent' ); // 4
	console.log( 'Zmienione ciasteczka', changed ); // 2
	console.log( 'Usunięte ciasteczla', deleted ); // 3
	console.groupEnd( 'CookieChangeEvent' ); // 5
} );

Nasłuchujemy na zdarzenie change (1). Gdy zajdzie, wyświetlamy informacje o nim: listę zmienionych ciasteczek (2) oraz listę usuniętych ciasteczek (3). Dzięki grupowaniu w konsoli (4, 5) informacje o konkretnym zdarzeniu są ładnie oddzielone od reszty komunikatów w konsoli:

Z kolei CookieStoreManager pozwala wykrywać zmiany w ciasteczkach z poziomu Service Workera. Nie umożliwia jednak modyfikowania ciasteczek.

Jeśli chodzi o CookieStore, wszystkie najważniejsze przeglądarki go wspierają. Z kolei CookieStoreManager nie jest obsługiwany w Safari.

Testowanie, czyli pora na degustację

Wypada jeszcze słowo poświęcić temu, w jaki sposób można testować ciasteczka. Tutaj na pomoc przychodzą narzędzia deweloperskie przeglądarki (devtools). W przypadku Chrome interesuje nas zakładka Application. W niej z kolei znajduje się sekcja Storage, a w niej – opcja Cookies. Po wejściu w nią, naszym oczom ukaże się lista zapisanych w przeglądarce ciasteczek dla danej strony:

Z poziomu tego widoku można dodawać, modyfikować i usuwać ciasteczka. Co więcej, wszystkie zmiany wprowadzone tutaj zostaną wyłapane przez zdarzenie change obiektu CookieStore. Dzięki temu można przetestować, czy nasza logika obsługi ciasteczek działa poprawnie.

Z kolei w przypadku Firefoksa analogiczny widok jest dostępny w zakładce Storage w devtools:

Tutaj też można dodawać, usuwać i modyfikować ciasteczka.

Zatem nie przedłużając już więcej: miłej degu… znaczy testowania ciasteczek!