2 |
3 | # Local Font Access Explained
4 |
5 | [](https://github.com/WICG/local-font-access/actions/workflows/auto-publish.yml)
6 |
7 | > August 14th, 20182 | Title: Local Font Access API 3 | Shortname: LocalFonts 4 | Level: 1 5 | Status: CG-DRAFT 6 | Group: WICG 7 | ED: https://wicg.github.io/local-font-access/ 8 | Repository: WICG/local-font-access 9 | Abstract: This specification documents web browser support for allowing users to grant web sites access to the full set of available system fonts for enumeration, and access to the raw data of fonts, allowing for more detailed custom text rendering. 10 | Editor: Joshua Bell, Google Inc. https://google.com, jsbell@google.com, w3cid 61302 11 | Former Editor: Emil A. Eklund 12 | Former Editor: Alex Russell 13 | Former Editor: Olivier Yiptong 14 | Assume Explicit For: yes 15 | Markup Shorthands: markdown yes, css yes 16 | Complain About: accidental-2119 yes, missing-example-ids yes 17 | Favicon: logo-font-enumeration.svg 18 | Test Suite: https://github.com/web-platform-tests/wpt/tree/master/font-access 19 |20 | 21 |
22 | spec: html; urlPrefix: https://html.spec.whatwg.org/multipage/ 23 | urlPrefix: system-state.html 24 | type: dfn 25 | text: a plausible language; url: a-plausible-language 26 |27 | 28 | 46 | 47 | 48 |
49 |
54 |
60 |
61 |
62 | # Introduction # {#introduction}
63 |
64 |
65 | This specification describes a font enumeration API for web browsers which may, optionally, allow users to grant access to the full set of available system fonts. For each font, low-level (byte-oriented) access to an SFNT [[!SFNT]] container or the equivalent provides full font data.
66 |
67 | Web developers historically lack anything more than heuristic information about which local fonts are available for use in styling page content. Web developers often include complex lists of `font-family` values in their CSS to control font fallback in a heuristic way. Generating good fallbacks is such a complex task for designers that tools have been built to help "eyeball" likely-available local matches.
68 |
69 | Font enumeration helps:
70 |
71 | * Improving styling options for user-generated content.
72 | * Matching fonts declared by existing content.
73 |
74 | While the web has its origins as a text-focused medium and user agents provide very high quality typography support, they have limitations that impact some classes of web-based applications:
75 |
76 | * System font engines (and browser stacks) may display certain glyphs differently. These differences are necessary, in general, to create fidelity with the underlying OS (so web content doesn't "look wrong"). These differences reduce consistency for applications that span across multiple platforms, e.g. when pixel-accurate layout and rendering is required.
77 | * Design tools need access to font data to do their own layout in a platform-independent way, and for actions such as performing vector filters or transforms on the glyph shapes.
78 | * Developers may provide font selection UI based on metrics or themes, or automatic font matching based on metrics and other data, which require direct access to font data.
79 | * Some fonts may not be licensed for delivery over the web. For example, Linotype has a license for some fonts that only includes desktop use.
80 |
81 | Professional-quality design and graphics tools have historically been difficult to deliver on the web. These tools provide extensive typographic features and controls as core capabilities.
82 |
83 | This API provides these tools access to the same underlying font data that browser layout and rasterization engines use for drawing text. Examples include the [[OPENTYPE|OpenType]] glyf table for glyph vector data, the GPOS table for glyph placement, and the GSUB table for ligatures and other glyph substitution. This information is necessary for these tools in order to guarantee both platform-independence of the resulting output (by embedding vector descriptions rather than codepoints) and to enable font-based art (treating fonts as the basis for manipulated shapes).
84 |
85 |
86 |
87 | # Goals # {#goals}
88 |
89 |
90 | The API should:
91 |
92 | * Provide efficient enumeration of all local fonts without blocking the main thread
93 | * Ensure UAs are free to return anything they like. If a browser implementation prefers, they may choose to only provide a set of default fonts built into the browser.
94 | * Be available from Workers
95 | * Allow multiple levels of privacy preservation; e.g., full access for "trusted" sites and degraded access for untrusted scenarios
96 | * Reflect local font access state in the Permissions API
97 | * Provide unique identification of families and instances (variants like "bold" and "italic"), including PostScript names
98 | * Enable a memory efficient implementation, avoiding leaks and copies by design
99 | * Restrict access to local font data to Secure Contexts and to only the top-most frame by default via the Permissions Policy spec
100 | * Sort any result list by font name to reduce possible fingerprinting entropy bits; e.g. .queryLocalFonts() returns an iterable which will be sorted by given font names
101 | * Provide access to the raw bytes of the font data. Most uses of this API will be to provide the full font data to existing libraries that only expect to consume entire font files. Providing only access to pre-parsed font table data would require developers to reassemble a blob containing all of the data in order to use such libraries.
102 |
103 | Issue: Although Worker support is called as a goal out above, the API as specified is currently only exposed to Window contexts.
104 |
105 |
108 |
109 |
110 |
111 |
112 | # Examples # {#examples}
113 |
114 |
115 | *This section is non-normative.*
116 |
117 |
118 | ## Enumerating local fonts ## {#example-enumerate-local-fonts}
119 |
120 |
121 | The API allows script to enumerate local fonts, including properties about each font.
122 |
123 |
124 | The following code queries the available local fonts, and logs the names and metrics of each to the console.
125 |
126 | ```js
127 | showLocalFontsButton.onclick = async function() {
128 | try {
129 | const array = await self.queryLocalFonts();
130 |
131 | array.forEach(font => {
132 | console.log(font.postscriptName);
133 | console.log(` full name: ${font.fullName}`);
134 | console.log(` family: ${font.family}`);
135 | console.log(` style: ${font.style}`);
136 | });
137 | } catch(e) {
138 | // Handle error, e.g. user cancelled the operation.
139 | console.warn(`Local font access not available: ${e.message}`);
140 | }
141 | };
142 | ```
143 |
144 |
145 |
146 | ## Styling with local fonts ## {#example-style-with-local-fonts}
147 |
148 |
149 | Advanced creative tools can offer the ability to style text using all available local fonts. In this case, getting access to the local font name allows the user to select from a richer set of choices:
150 |
151 |
152 |
153 | The following code populates a drop-down selection form element with the available local fonts, and could be used as part of the user interface for an editing application.
154 |
155 | ```js
156 | useLocalFontsButton.onclick = async function() {
157 | try {
158 | // Query for allowed local fonts.
159 | const array = await self.queryLocalFonts();
160 |
161 | // Create an element to style.
162 | const exampleText = document.createElement("p");
163 | exampleText.id = "exampleText";
164 | exampleText.innerText = "The quick brown fox jumps over the lazy dog";
165 | exampleText.style.fontFamily = "dynamic-font";
166 |
167 | // Create a list of fonts to select from, and a selection handler.
168 | const textStyle = document.createElement("style");
169 | const fontSelect = document.createElement("select");
170 | fontSelect.onchange = e => {
171 | const postscriptName = fontSelect.value;
172 | console.log("selected:", postscriptName);
173 | // An example of styling using @font-face src: local matching.
174 | textStyle.textContent = `
175 | @font-face {
176 | font-family: "dynamic-font";
177 | src: local("${postscriptName}");
178 | }`;
179 | };
180 |
181 | // Populate the list with the available fonts.
182 | array.forEach(font => {
183 | const option = document.createElement("option");
184 | option.text = font.fullName;
185 | // postscriptName can be used with @font-face src: local to style elements.
186 | option.value = font.postscriptName;
187 | fontSelect.append(option);
188 | });
189 |
190 | // Add all of the elements to the page.
191 | document.body.appendChild(textStyle);
192 | document.body.appendChild(exampleText);
193 | document.body.appendChild(fontSelect);
194 | } catch(e) {
195 | // Handle error, e.g. user cancelled the operation.
196 | console.warn(`Local font access not available: ${e.message}`);
197 | }
198 | };
199 | ```
200 |
201 |
202 |
203 |
204 | ## Accessing font data ## {#example-accessing-font-data}
205 |
206 |
207 | The API allows script to request font data.
208 |
209 |
210 | The following code queries the available local fonts, and logs details about each to the console.
211 |
212 | Here we use enumeration to access specific local font data; we can use this to parse out specific tables or feed it into, e.g., WASM version of [HarfBuzz](https://www.freedesktop.org/wiki/Software/HarfBuzz/) or [Freetype](https://www.freetype.org/):
213 |
214 | ```js
215 | useLocalFontsButton.onclick = async function() {
216 | try {
217 | const array = await self.queryLocalFonts();
218 |
219 | array.forEach(font => {
220 | // blob() returns a Blob containing the bytes of the font.
221 | const bytes = await font.blob();
222 |
223 | // Inspect the first four bytes, which for SFNT define the format.
224 | // Spec: https://docs.microsoft.com/en-us/typography/opentype/spec/otff#organization-of-an-opentype-font
225 | const sfntVersion = await bytes.slice(0, 4).text();
226 |
227 | let outlineFormat = "UNKNOWN";
228 | switch (sfntVersion) {
229 | case '\x00\x01\x00\x00':
230 | case 'true':
231 | case 'typ1':
232 | outlineFormat = "truetype";
233 | break;
234 | case 'OTTO':
235 | outlineFormat = "cff";
236 | break;
237 | }
238 | console.log(`${font.fullName} outline format: ${outlineFormat}`);
239 | }
240 | } catch(e) {
241 | // Handle error. It could be a permission error.
242 | console.warn(`Local font access not available: ${e.message}`);
243 | }
244 | };
245 | ```
246 |
247 | Parsing font files in more detail, for example enumerating the contained tables, is beyond the scope of this specification.
248 |
249 |
250 |
251 |
252 | ## Requesting specific fonts ## {#example-requesting-specific-fonts}
253 |
254 |
255 | In some cases, a web application may wish to request access to specific fonts. For example, it may be presenting previously authored content that embeds font names. The `queryLocalFonts()` call takes a `postscriptNames` option that scopes the request to fonts identified by PostScript names. Only fonts exactly matching the names in the list will be returned.
256 |
257 | User agents may provide a different user interface to support this. For example, if the fingerprinting risk is deemed minimal, the request may be satisfied without prompting the user for permission. Alternately, a picker could be shown with only the requested fonts included.
258 |
259 |
260 |
261 | ```js
262 | // User activation is needed.
263 | requestFontsButton.onclick = async function() {
264 | try {
265 | const array = await self.queryLocalFonts({postscriptNames: ['Verdana', 'Verdana-Bold', 'Verdana-Italic']});
266 |
267 | array.forEach(font => {
268 | console.log(`Access granted for ${font.postscriptName}`);
269 | });
270 |
271 | } catch(e) {
272 | // Handle error. It could be a permission error.
273 | console.warn(`Local font access not available: ${e.message}`);
274 | }
275 | };
276 | ```
277 |
278 |
279 |
280 |
281 | # Concepts # {#concepts}
282 |
283 |
284 | The user language is a valid BCP 47 language tag representing either [=/a plausible language=] or the user's most preferred language. [[!BCP47]]
285 |
286 |
287 | ## Font Representation ## {#concept-font-representation}
288 |
289 |
290 | A font representation is some concrete representation of a font. Examples include [[OPENTYPE|OpenType]], [[TRUETYPE|TrueType]], bitmap fonts, Type1 fonts, SVG fonts, and future font formats. This specification defines the properties of a [=/font representation=] as:
291 |
292 |
293 |
294 | * The data bytes, which is a [=/byte sequence=] containing a serialization of the font.
295 |
296 | note: The [=/font representation=]'s [=font representation/data bytes=] are generally expected to be the exact byte-by-byte representation of font files on the user's filesystem. UAs aren't expected to normalize the font data, so font representations would not vary across user agents for a given user on a particular OS. The lack of normalization supports the goal of enabling web applications that perform text rendering for content creation with the full fidelity of the font.
297 |
298 |
299 | * The PostScript name, which is a {{DOMString}}. This is commonly used as a unique identifier for the font during font loading, e.g. "Optima-Bold".
300 | * The full name, which is a {{DOMString}}. This is usually a human-readable name used to identify the font, e.g. "Optima Bold".
301 | * The family name, which is a {{DOMString}}. This defines a set of fonts that vary among attributes such as weight and slope, e.g. "Optima"
302 | * The style name, which is a {{DOMString}}. This defines the variation of the font within a family, e.g. "Bold".
303 |
304 |
305 |
306 |
307 | note:
308 | This specification doesn't precisely define the values of the above fields for any particular font format, so that differences between operating systems don't make UAs non-compliant. However, for an OpenType [[!OPENTYPE]] font the following values would be sensible:
309 | * The [=font representation/data bytes=] are the SFNT [[!SFNT]] serialization of the font.
310 | * The [=font representation/PostScript name=] is found in the font's name table, in the name record with nameID = 6; if multiple localizations are available, the US English version is used if provided, or the first localization otherwise.
311 | * The [=font representation/full name=] is found in the font's name table, in the name record with nameID = 4; if multiple localizations are available, the [=/user language=] version is used if provided, or the first localization otherwise.
312 | * The [=font representation/family name=] is found in the font's name table, in the name record with nameID = 1; if multiple localizations are available, the [=/user language=] version is used if provided, or the first localization otherwise.
313 | * The [=font representation/style name=] is found in the font's name table, in the name record with nameID = 2; if multiple localizations are available, the [=/user language=] version is used if provided, or the first localization otherwise.
314 |
315 | These name properties are exposed to align with property usage in [[CSS-FONTS-4]], e.g. ''@font-face'', 'font-family', and so on. The [=font representation/PostScript name=] can be used as a unique key, for example when specifying a font when creating content or matching fonts against existing content. The [=font representation/full name=] or [=font representation/family name=] can be used for user-visible font selection UI, and the [=font representation/style name=] can be used to provide more specific selections.
316 |
317 |
318 | A valid PostScript name is a [=/scalar value string=] with [=string/length=] less than 64 and consisting only of characters in the range U+0021 (!) to U+007E (~) except for the 10 code units
319 | U+005B ([),
320 | U+005D (]),
321 | U+0028 LEFT PARENTHESIS,
322 | U+0029 RIGHT PARENTHESIS,
323 | U+007B ({),
324 | U+007D (}),
325 | U+003C (<),
326 | U+003E (>),
327 | U+002F (/), and
328 | U+0025 (%).
329 |
330 | note: This is intended to match the requirements for nameID = 6 in [[!OPENTYPE]].
331 |
332 |
333 |
334 | ## System Fonts ## {#concept-system-fonts}
335 |
336 |
337 | A system font is a font that is available system-wide provided by the operating system.
338 |
339 | To read a system font as a font representation is to provide a [=/font representation=] equivalent to the font. This means providing all properties of a [=/font representation=]:
340 | * [=font representation/Data bytes=].
341 | * [=font representation/PostScript name=], which must be valid.
342 | * [=font representation/Full name=].
343 | * [=font representation/Family name=].
344 | * [=font representation/Style name=].
345 |
346 | This operation can fail if providing a [=/font representation=] is not possible.
347 |
348 | A user agent may use any algorithm to provide a [=/font representation=] for a [=/system font=]. In practice, contemporary operating systems and system APIs support fonts that are persisted in SFNT [[!SFNT]] font file formats, such as [[OPENTYPE|OpenType]], [[TRUETYPE|TrueType]], [[WOFF|Web Open Font Format]], etc. which satisfy these requirements, as well as the means to efficiently enumerate font collections with these common name properties provided for each font.
349 |
350 |
351 | To get all system font representations, run these steps:
352 | 1. Let |fonts| be a [=/list=] of all [=/system fonts=].
353 | 1. Let |result| be a new [=/list=].
354 | 1. [=list/For each=] |font| in |fonts|.
355 | 1. Let |representation| be |font| [=/read as a font representation=]. On failure, [=iteration/continue=].
356 | 1. If the user agent determines that the user should never expose the font to the web, then it may [=iteration/continue=].
357 | 1. Append |representation| to |result|.
358 | 1. Return |result|.
359 |
360 |
361 |
362 |
363 | # Permissions Integration # {#permissions-integration}
364 |
365 |
366 | Enumeration of local fonts requires a permission to be granted.
367 |
368 |
369 | ## Permissions ## {#permissions}
370 |
371 |
372 | The Local Font Access API is a [=/default powerful feature=] that is identified by the [=powerful feature/name=] "local-fonts".
373 |
374 | When the {{Window/queryLocalFonts()}} API is invoked, the user agent may present a list of font choices, a yes/no choice, or other interface options. The user agent should present the results of the choice in the permission in an appropriate way. For example, if the user has selected a set of fonts to expose to the site and further API calls will return the same set of fonts, the permission state could be "granted". If the user will be prompted again, the permission state could be "prompt".
375 |
376 |
377 | Permission to enumerate local fonts can be queried using the `navigator.permissions` API:
378 |
379 | ```js
380 | // This just queries the existing state of the permission, it does not change it.
381 | const status = await navigator.permissions.query({ name: "local-fonts" });
382 | if (status.state === "granted")
383 | console.log("permission was granted 👍");
384 | else if (status.state === "prompt")
385 | console.log("permission will be requested");
386 | else
387 | console.log("permission was denied 👎");
388 | ```
389 |
390 |
391 |
392 | ## Permissions policy ## {#permissions-policy}
393 |
394 |
395 | This specification defines a [=/policy-controlled feature=] identified by the string "local-fonts". Its [=policy-controlled feature/default allowlist=] is `'self'`.
396 |
397 |
398 | note:
399 | The [=policy-controlled feature/default allowlist=] of `'self'` allows usage of this feature on same-origin nested frames by default but prevents access by third-party content.
400 |
401 | Third-party usage can be selectively enabled by adding the `allow="local-fonts"` attribute to an <{iframe}> element:
402 |
403 |
419 |
420 |
421 |
422 | # API # {#api}
423 |
424 |
425 |
426 | ## Font task source ## {#font-task-source-dfn}
427 |
428 |
429 | The font task source is a new generic [=/task source=] which is used for all [=/queue a task|tasks that are queued=] in this specification.
430 |
431 |
432 |
433 | ## Font manager ## {#font-manager-api}
434 |
435 |
436 |
404 | ```html
405 |
406 | ```
407 |
408 |
409 | Alternatively, this feature can be disabled completely in first-party contexts by specifying the permissions policy in an HTTP response header:
410 |
411 |
412 | ```http
413 | Permissions-Policy: local-fonts 'none'
414 | ```
415 |
416 |
417 | See [[PERMISSIONS-POLICY]] for more details.
418 |
437 |
438 | : await self . {{Window/queryLocalFonts()}}
439 | : await self . {{Window/queryLocalFonts()|queryLocalFonts}}({ {{QueryOptions/postscriptNames}}: [ ... ] })
440 | :: Asynchronously query for available/allowed fonts. If successful, the returned promise resolves to an array of {{FontData}} objects.
441 |
442 | If the method is not called while the document has [=/transient activation=] (e.g. in response to a click event), the returned promise will be rejected.
443 |
444 | The user will be prompted for permission for access local fonts or to select fonts to provide to the site. If the permission is not granted, the returned promise will rejected.
445 |
446 | If the {{QueryOptions/postscriptNames}} option is given, then only fonts with matching PostScript names will be included in the results.
447 |
448 |
449 |
450 |
451 |
463 | The queryLocalFonts(|options|) method steps are:
464 |
465 | 1. Let |promise| be [=/a new promise=].
466 | 1. Let |descriptor| be a {{PermissionDescriptor}} with its {{PermissionDescriptor/name}} set to {{"local-fonts"}}.
467 | 1. If [=/this=]’s [=relevant settings object=]'s [=origin=] is an [=/opaque origin=], then [=/reject=] |promise| with a "{{SecurityError}}" {{DOMException}}, and return |promise|.
468 | 1. If [=/this=]’s [=relevant global object=]'s [=/associated Document=] is not [=/allowed to use=] the [=/policy-controlled feature=] named {{PermissionPolicy/"local-fonts"}}, then [=/reject=] |promise| with a "{{SecurityError}}" {{DOMException}}, and return |promise|.
469 | 1. If [=/this=]’s [=relevant global object=] does not have [=/transient activation=], then [=/reject=] |promise| with a "{{SecurityError}}" {{DOMException}}, and return |promise|.
470 | 1. Otherwise, run these steps [=in parallel=]:
471 | 1. Let |system fonts| be the result of [=/getting all system font representations=].
472 | 1. Let |selectable fonts| be a new [=/list=].
473 | 1. [=list/For each=] font |representation| in |system fonts|, run these steps:
474 | 1. Let |postscriptName| be |representation|'s [=font representation/PostScript name=].
475 | 1. Assert: |postscriptName| is a [=/valid PostScript name=].
476 | 1. If |options|[{{QueryOptions/"postscriptNames"}}] [=map/exists=] and |options|[{{QueryOptions/"postscriptNames"}}] does not [=list/contain=] |postscriptName|, then [=iteration/continue=].
477 | 1. [=list/Append=] a new {{FontData}} instance associated with |representation| to |selectable fonts|.
478 | 1. [=/Prompt the user to choose=] one or more items from |selectable fonts|, with |descriptor| and allowMultiple set to true, and let |result| be the result.
479 | User agents may present a yes/no choice instead of a list of choices, and in that case they should set |result| to |selectable fonts|.
480 | 1. If |result| is {{PermissionState/"denied"}}, then [=/reject=] |promise| with a "{{NotAllowedError}}" {{DOMException}}, and abort these steps.
481 | 1. Sort |result| in [=list/sort in ascending order|ascending order=] by using {{FontData/postscriptName}} as the sort key and store the result as |result|.
482 | 1. [=/Queue a task=] on the [=/font task source=] to [=/resolve=] |promise| with |result|.
483 | 1. Return |promise|.
484 |
485 |
486 |
487 | Issue: Move to {{WindowOrWorkerGlobalScope}} and sort out permission issues.
488 |
489 |
490 | ## The {{FontData}} interface ## {#fontdata-interface}
491 |
492 |
493 | A {{FontData}} provides details about a font face. Each {{FontData}} has an associated [=/font representation=].
494 |
495 |
496 |
497 | : |fontdata| . {{FontData/postscriptName}}
498 | :: The PostScript name for the font. Example: "`Arial-Bold`".
499 |
500 | : |fontdata| . {{FontData/fullName}}
501 | :: The full font name, including family subfamily names. Example: "`Arial Bold`"
502 |
503 | : |fontdata| . {{FontData/family}}
504 | :: The font family name. This corresponds with the CSS 'font-family' property. Example: "`Arial`"
505 |
506 | : |fontdata| . {{FontData/style}}
507 | :: The font style (or subfamily) name. Example: "`Regular`", "`Bold Italic`"
508 |
509 |
510 |
511 |
512 |
526 |
527 |
543 |
544 | Issue: Consider making {{FontData}} [=/serializable objects=] so that the results of {{Window/queryLocalFonts()}} can be passed to Workers.
545 |
546 |
528 | The postscriptName getter steps are:
529 |
530 | 1. Let |postscriptName| be [=/this=]'s [=font representation/PostScript name=].
531 | 1. Assert: |postscriptName| is a [=/valid PostScript name=].
532 | 1. Return |postscriptName|.
533 |
534 |
535 |
536 | The fullName getter steps are to return [=/this=]'s associated [=/font representation=]'s [=font representation/full name=].
537 |
538 | The family getter steps are to return [=/this=]'s associated [=/font representation=]'s [=font representation/family name=].
539 |
540 | The style getter steps are to return [=/this=]'s associated [=/font representation=]'s [=font representation/style name=].
541 |
542 |
547 |
548 | : await |blob| = |fontdata| . {{FontData/blob()}}
549 | :: Request the underlying bytes of a font. The result |blob| contains [=font representation/data bytes=].
550 |
551 |
552 |
553 |
554 |
555 | The blob() method steps are:
556 |
557 | 1. Let |realm| be [=/this=]'s [=/relevant Realm=].
558 | 1. Let |promise| be [=/a new promise=] in |realm|.
559 | 1. Run these steps [=in parallel=]:
560 | 1. Let |bytes| be [=this=]'s associated [=/font representation=]'s [=font representation/data bytes=].
561 | 1. Let |type| be \``application/octet-stream`\`.
562 | 1. [=/Queue a task=] on the [=/font task source=] to:
563 | 1. Let |blob| be a new {{Blob}} in |realm| whose contents are |bytes| and {{Blob/type}} attribute is |type|.
564 | 1. [=/Resolve=] |promise| with |blob|.
565 | 1. Return |promise|.
566 |
567 |
568 |
569 |
570 | # Internationalization considerations # {#i18n}
571 |
572 |
573 | Issue: Document internationalization considerations other than string localization, e.g. https://github.com/WICG/local-font-access/issues/72, https://github.com/WICG/local-font-access/issues/59, etc.
574 |
575 |
576 | ## Font Names ## {#i18n-names}
577 |
578 |
579 | The \``name`\` table in [[OPENTYPE|OpenType]] fonts allows names (family, subfamily, etc) to have multilingual strings, using either platform-specific numeric language identifiers or language-tag strings conforming to [[BCP47]]. For example, a font could have family name strings defined for both \``en-US`\` and \``zh-Hant-HK`\`.
580 |
581 | The {{FontData}} properties {{FontData/postscriptName}}, {{FontData/fullName}}, {{FontData/family}}, and {{FontData/style}} are provided by this API simply as strings, using either the US English localization or the [=/user language=] localization depending on the name, or the first localization as a fallback.
582 |
583 | Web applications that need to provide names in other languages can request and parse the \``name`\` table directly.
584 |
585 | Issue(69): Should we define an option to the {{Window/queryLocalFonts()}} method to specify the desired language for strings (e.g. `{lang: 'zh'}`), falling back to \``en-US`\` if not present? Or provide access to all the names, e.g. as a map from [[BCP47]] language tag to name?
586 |
587 |
588 |
589 | # Accessibility considerations # {#a11y}
590 |
591 |
592 | There are no known accessibility impacts of this feature.
593 |
594 |
595 | # Security considerations # {#security}
596 |
597 |
598 | There are no known security impacts of this feature.
599 |
600 |
601 | # Privacy considerations # {#privacy}
602 |
603 |
604 |
605 | ## Fingerprinting ## {#privacy-fingerprinting}
606 |
607 |
608 | The font data includes:
609 |
610 | * Fonts included in the operating system distribution.
611 | * Fonts installed by particular applications installed on the system, for example office suites.
612 | * Fonts directly installed by the system administrator and/or end user.
613 | * The version of the font installed on the system, obtained via the font data.
614 |
615 | This provides several "bits of entropy" to distinguish users.
616 |
617 | User agents could mitigate this in certain cases (e.g. when the permission is denied, or in Private Browsing / "incognito" mode) by providing an enumeration of a fixed set of fonts provided with the user agent.
618 |
619 | User agents may also allow the user to select a set of fonts to make available via the API.
620 |
621 | When multiple localizations of font names are provided by a font, the user's locale is potentially exposed through the font name. User agents should ensure that if a locale is exposed in this way, it's the same locale that's exposed by navigator.{{NavigatorLanguage/language}}.
622 |
623 |
624 | ## Identification ## {#privacy-identification}
625 |
626 |
627 | Users from a particular organization could have specific fonts installed. Employees of "Example Co." could all have an "Example Corporate Typeface" installed by their system administrator, which would allow distinguishing users of a site as employees.
628 |
629 | There are services which create fonts based on handwriting samples. If these fonts are given names including personally identifiable information (e.g. "Alice's Handwriting Font"), then personally identifiable information would be made available. This may not be apparent to users if the information is included as properties within the font, not just the font name.
630 |
631 |
632 |
633 | # Acknowledgements # {#acknowledgements}
634 |
635 |
636 | We'd like to acknowledge the contributions of:
637 |
638 | * Daniel Nishi, Owen Campbell-Moore, and Mike Tsao who helped pioneer the previous local font access proposal.
639 | * Evan Wallace, Biru, Leah Cassidy, Katie Gregorio, Morgan Kennedy, and Noah Levin of Figma who have patiently enumerated the needs of their ambitious web product.
640 | * Alex Russell, who drafted the initial version of this proposal.
641 | * Olivier Yiptong, who provided an initial implementation and iteration on the API shape.
642 | * Tab Atkins, Jr. and the CSS Working Group who have provided usable base-classes which only need slight extension to enable these cases.
643 | * Dominik Röttsches and Igor Kopylov for their thoughtful feedback.
644 | * We would like to express our gratitude to former editor Emil A. Eklund, who passed away in 2020. Emil was instrumental in getting this proposal underway, providing technical guidance, and championing the needs of users and developers.
645 |
646 | Special thanks (again!) to Tab Atkins, Jr. for creating and maintaining [Bikeshed](https://github.com/tabatkins/bikeshed), the specification authoring tool used to create this document.
647 |
648 | And thanks to
649 | Anne van Kesteren,
650 | Chase Phillips,
651 | Domenic Denicola,
652 | Dominik Röttsches,
653 | Igor Kopylov,
654 | Jake Archibald, and
655 | Jeffrey Yasskin
656 | for suggestions, reviews, and other feedback.
657 |
--------------------------------------------------------------------------------
/logo-font-enumeration.svg:
--------------------------------------------------------------------------------
1 |
7 |
--------------------------------------------------------------------------------
/logo-font-table-access.svg:
--------------------------------------------------------------------------------
1 |
23 |
--------------------------------------------------------------------------------
/security-privacy.md:
--------------------------------------------------------------------------------
1 | Questions from https://www.w3.org/TR/security-privacy-questionnaire/
2 |
3 | # 2. Questions to Consider
4 |
5 | ## 2.1. What information might this feature expose to Web sites or other parties, and for what purposes is that exposure necessary?
6 |
7 | This feature intentionally reveals a list of local fonts to the Web site, and optionally tables within each font. This can include common fonts, fonts purchased from type foundries, or even custom fonts such as personal handwriting fonts.
8 |
9 | In addition, the data returned in the tables can include metadata about the font, as well as the actual font contents. Providing access to this information is necessary in order to correctly render text using the font.
10 |
11 | Browsers currently provide for the use of local fonts, but not enumeration. For example, the CSS `font-family` property can be used to request the use of a local font by name. If the font is not available, the browser will provide a fallback. Through the use of measurement APIs, it is usually possible to determine if the requested font or a fallback was used. Given a dictionary of font names, this can be used to determine which are available on a user's system.
12 |
13 | The feature will require the user to grant permission before providing the data to a site.
14 |
15 | ## 2.2. Is this specification exposing the minimum amount of information necessary to power the feature?
16 |
17 | The feature exposes the names and a handful of additional properties of each font. For example, the name, "PostScript" name, metrics, color and variability information. These are needed by Web applications that will present a list of fonts to users - e.g. illustration tools - to group and classify options. Some of these properties would also be available indirectly e.g. through measurement APIs.
18 |
19 | System APIs may in some cases expose more than the minimum amount of information necessary. For example, a list of fonts given by system APIs may be returned in the order in which the fonts were installed. This API intends to remove this additional information by sorting the returned result by Unicode code point given font names.
20 |
21 | ## 2.3. How does this specification deal with personal information or personally-identifiable information or information derived thereof?
22 |
23 | There are services which create fonts based on handwriting samples. If these fonts are given names including personally identifiable information (e.g. "Alice's Handwriting Font"), then personally identifiable information would be made available. This may not be apparent to users if the information is included as properties within the font, not just the font name.
24 |
25 | User agents should make the risks of granting the permission clear to users.
26 |
27 | ## 2.4. How does this specification deal with sensitive information?
28 |
29 | Fonts installed on particular operating system versions could reveal information about the user's location.
30 |
31 | Fonts may be installed by particular applications installed on the system, for example office suites. This could allow identifying the other applications on the system.
32 |
33 | Users from a particular organization could have specific fonts installed. Employees of "Example Co." could all have an "Example Corporate Typeface" installed by their system administrator, which would allow distinguishing users of a site as employees.
34 |
35 | User agents should make the risks of granting the permission clear to users.
36 |
37 | ## 2.5. Does this specification introduce new state for an origin that persists across browsing sessions?
38 |
39 | Yes, user agents could persist the `local-fonts` permission grant, but at least in the Chrome implementation, this permission grant will only be persistent for installed PWAs. The drive-by web will only have enough state to allow it to re-prompt for access, but the access itself won't be persistent.
40 |
41 | Furthermore, the user will be able to revoke permission to clear the state that was persisted, similarly to how other permissions work.
42 |
43 | ## 2.6. What information from the underlying platform, e.g. configuration data, is exposed by this specification to an origin?
44 |
45 | The font list includes:
46 |
47 | * Fonts included in the operating system distribution.
48 | * Fonts installed by particular applications installed on the system, for example office suites.
49 | * Fonts directly installed by the system administrator and/or end user.
50 |
51 | This will identify the operating system and version and potentially some installed applications.
52 |
53 | Font table access provides overall access to the raw data stored in a font's tables. This information includes all of the information about a specific font, including:
54 |
55 | * Metadata contained in a font's tables, including its various names, color and variability data, and copyright information
56 | * The raw table data used in OpenType fonts (e.g. the cmap table, etc)
57 | * The raw table data used in TrueType or CFF fonts (e.g. 'CFF2' or 'glyf' tables, etc)
58 | * Any other valid tables contained in the font beyond what may be required for traditional font rendering
59 |
60 | From this information, it may be possible to identify the operating system and version and potentially some installed applications.
61 |
62 | ## 2.7. Does this specification allow an origin access to sensors on a user’s device
63 |
64 | No.
65 |
66 | ## 2.8. What data does this specification expose to an origin? Please also document what data is identical to data exposed by other features, in the same or different contexts.
67 |
68 | The data described above is exposed to script, which can then transmit it to the origin.
69 |
70 | ## 2.9. Does this specification enable new script execution/loading mechanisms?
71 |
72 | No.
73 |
74 | ## 2.10. Does this specification allow an origin to access other devices?
75 |
76 | No.
77 |
78 | ## 2.11. Does this specification allow an origin some measure of control over a user agent’s native UI?
79 |
80 | No. (Other than potentially triggering the display of a permission prompt.)
81 |
82 | ## 2.12. What temporary identifiers might this this specification create or expose to the web?
83 |
84 | None.
85 |
86 | ## 2.13. How does this specification distinguish between behavior in first-party and third-party contexts?
87 |
88 | A user agent may decline to grant permissions requested by third-party contexts. Cooperating origins could work around this limitation via `postMessage()`.
89 |
90 | ## 2.14. How does this specification work in the context of a user agent’s Private Browsing or "incognito" mode?
91 |
92 | Some possibilities for incognito-specific behaviors have been considered:
93 |
94 | * The user agent could automatically deny the permission request.
95 | * The user agent could grant the permission request, but provide "anonymous" data, e.g. a fixed set of fonts, rather than providing access to the actual local fonts.
96 |
97 | While eliminating the ability for accessing local fonts, these choices can unintentionally expose that the user is in incognito mode. For example,
98 | automatically rejecting may indicate to a web page that, while a given UA normally supports the API, the rejection may hint that the UA has turned
99 | off the API due to being in incognito mode.
100 |
101 | Many permission-based web capabilities are exposed in incognito mode, so there's precedent that capabilities themselves are not problematic in incognito mode. Other capabilities
102 | can identify the user (e.g. file upload) which also aren't limited by incognito mode. Finally, eliminating capabilities from incognito mode reduces incognito mode's usefulness,
103 | which itself could impact the value of that feature. Based on this, an incognito mode session is most likely best served by continuing to offer these local font access APIs.
104 |
105 | ## 2.15. Does this specification have a "Security Considerations" and "Privacy Considerations" section?
106 |
107 | TBD.
108 |
109 | ## 2.16. Does this specification allow downgrading default security characteristics?
110 |
111 | No.
112 |
113 | ## 2.17. What should this questionnaire have asked?
114 |
115 |
116 |
117 | # 3. Threat Models
118 |
119 | ## 3.1 Passive Network Attackers
120 |
121 | ## 3.2 Active Network Attackers
122 |
123 | ## 3.3 Same-Origin Policy Violations
124 |
125 | ## 3.4 Third-Party Tracking
126 |
127 | ## 3.5 Legitimate Misuse
128 |
--------------------------------------------------------------------------------
/w3c.json:
--------------------------------------------------------------------------------
1 | {
2 | "group": [80485]
3 | , "contacts": ["cwilso"]
4 | , "repo-type": "cg-report"
5 | }
6 |
--------------------------------------------------------------------------------