MiniApp Packaging

W3C Working Draft

More details about this document
This version:
https://www.w3.org/TR/2023/WD-miniapp-packaging-20230530/
Latest published version:
https://www.w3.org/TR/miniapp-packaging/
Latest editor's draft:
https://w3c.github.io/miniapp-packaging/
History:
https://www.w3.org/standards/history/miniapp-packaging
Commit history
Editors:
Martin Alvarez-Espinar (Huawei)
Qing An (Alibaba)
Tengyuan Zhang (Baidu, Inc)
Yongjing Zhang (Huawei)
Dan Zhou (Baidu, Inc)
Former editors:
Shouren Lan (Huawei)
Zhiqiang Yu (Huawei)
Qian Liu (Baidu, Inc)
Shuo Wang (Baidu, Inc)
Feedback:
GitHub w3c/miniapp-packaging (pull requests, new issue, open issues)

Abstract

This specification defines semantics and conformance requirements for a MiniApp package, and the structure of the single file container that holds the resources of a MiniApp, including a manifest file, static page templates, stylesheets, JavaScript documents, media files and other resources. Instances of the MiniApp package are used for MiniApp distribution and execution on runtime environments (MiniApp user agent).

Status of This Document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was published by the MiniApps Working Group as a Working Draft using the Recommendation track.

Publication as a Working Draft does not imply endorsement by W3C and its Members.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 2 November 2021 W3C Process Document.

1. Introduction

1.1 Overview

MiniApp is a concept of light software application, that can be distributed through any digital means, and accessed through the Web. MiniApps are defined by a concrete file structure and all their resources are packed within a single file that represents the whole MiniApp package that can be processed and executed by MiniApp user agents.

A MiniApp package contains a directory structure that holds the specific resources of the MiniApp that defines the rendering, operation, and interaction with the end-users — including static page templates, stylesheets, JavaScript documents, media files, and other resources — and the manifest. The MiniApp manifest, located in the central directory of the package, describes the MiniApp, including information about page routing, styles, and other operational and rendering details of the MiniApp, as well as descriptive information for humans.

As defined in Security Considerations, MiniApps MAY support digital signature verification to guarantee the integrity of the package and contents during the delivery of the package.

The MiniApp runtime environment (MiniApp user agent) identifies MiniApp package files through the standard MiniApp package format and the specific MIME media type, defined in this document. After retrieving the MiniApp ZIP container, the MiniApp user agent loads the static page templates, stylesheets, JavaScript files, and other resources into the cache, following a dereference and processing algorithm. These MiniApp resources will remain available in the cache until the next update, avoiding unnecessary network fetches.

In terms of launch mode, a MiniApp can be launched normally when offline. The MiniApp user agent locates the specified start page from the package cache path and launches the MiniApp according to the description set out in the MiniApp manifest file.

1.2 Terminology

The following terms are specific to MiniApps.

Digital signature
A cryptographic mechanism and hashing techniques to prove the authenticity of resources. Digital signatures can demonstrate the origin, time, identity, and status of resources and of the MiniApp package.
File name
The name of any file within a MiniApp package, either a directory or a file within a directory.
MiniApp
A light software application, that can be distributed through any digital means, and accessed through the Web. MiniApps are defined by a concrete file structure, distributed within a single file MiniApp ZIP container that represents the whole MiniApp package that can be processed and executed by MiniApp user agents.
MiniApp package
A logical document entity composed of a set of resources packaged in a MiniApp ZIP container.
MiniApp resource
A logical document that is part of the view or the logic of a MiniApp. Resources are included physically in MiniApp packages.
MiniApp page
A collection of information that is displayed in a MiniApp user agent, under the scope of a specific MiniApp.
MiniApp user agent
A software application that gets, process and renders MiniApp packages, enabling execution and end-user interaction with MiniApps.
MiniApp ZIP container
The ZIP-based packaging and distribution format for MiniApps, as defined in MiniApp ZIP container section.
MiniApp widget
A special type of MiniApp page that is displayed standalone in host environments such as assistants and device search pages to connect MiniApp services in specific scenarios.
MiniApp start page
The entry point of a MiniApp. The resource that is loaded and rendered by the MiniApp user agent at the launch of the application.

1.3 Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, SHALL, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

The MiniApp Packaging specification depends on the Infra Standard [INFRA] to describe algorithms.

2. Package Conformance

A conformant MiniApp package MUST meet the following criteria:

2.1 Directory and File System Structure

The MiniApp package has a file structure with some restrictions and reserved files and subdirectories.

The following example shows a typical file system structure:

Example 1: File system structure
/
|___manifest.json
|___app.js
|___app.css
|___pages/
|       |___page1.js
|       |___page1.html
|       |___page1.css
|___common/
|       |___componentA.js
|       |___componentA.html
|       |___componentA.css
|       |___example.png
|___i18n/
        |___zh-Hans.json
        |___en-US.json

2.1.1 Root Directory

The MiniApp root directory is the base directory of the MiniApp package file system.

The root directory of a MiniApp package holds several reserved files that include global data and information about the lifecycle management of the MiniApp, including:

manifest.json
The MiniApp manifest is a JSON document responsible for the global configuration of the MiniApp. A manifest file contains a collection of mandatory and optional attributes that indicate the setup of the MiniApp, including routes and paths of the pages and the window configuration of the MiniApp (e.g., styles of the navigation bar, background image, background color, page title, among others), according to the MiniApp Manifest specification [MINIAPP-MANIFEST].
app.css
This file is the main stylesheet of the application, where developers define common styles and look and feel aspects of the pages within the MiniApp. It MAY be empty.
app.js
This script document has the basic service logic of the MiniApp and includes the essential configuration and control of the MiniApp lifecycle [MINIAPP-LIFECYCLE], including the management of events for launching, showing, and hiding the MiniApp.

2.1.2 pages Directory

The pages directory contains a set of files for the display and user interaction of the MiniApp pages.

A MiniApp page is defined by a set of resources, whose files are identified by a unique filename (e.g., intro) and a specific extension that defines the resource type, such as the business logic of the application (e.g., intro.js), the structure and content (e.g., intro.html), and the scoped stylesheet (e.g., intro.css).

Developers MAY include other types of resources according to their needs. Also, the files related to a page (identified with the same filename) MAY be organized either in specific subdirectories for each page or stored under the pages directory directly.

Example 2: Page resources directly in the pages directory
/
|___manifest.json
|___app.js
|___app.css
|___pages/
        |___detail.js
        |___detail.html
        |___detail.css
        |___list.js
        |___list.html
        |___list.css
Example 3: Page resources organized in subdirectories
/
|___manifest.json
|___app.js
|___app.css
|___pages/
        |___detail/
                |___detail.js
                |___detail.html
                |___detail.css
        |___list
                |___list.js
                |___list.html
                |___list.css
  • A .html resource defines the structure and content of a MiniApp page. Based on HTML, the syntax, structure, and other requirements of this type of file are defined in the HTML Resources section.
  • A .css resource defines the stylesheet of a MiniApp page. The syntax, structure, and other requirements of this type of resource are defined in the CSS Resources section.
  • A .js resource contains the business logic of the MiniApp page, including functions, data, and other configuration aspects needed for the operation of the application. This type of resource is responsible for the setup and lifecycle management of MiniApp pages, as defined in the MiniApp Lifecycle specification [MINIAPP-LIFECYCLE]. The syntax and format of these types of files are defined in the Scripting Resources section.

2.1.3 common Directory

The optional common directory contains resources, such as components, multimedia resources, documents and libraries that are accessible from the pages in a MiniApp. The internal structure of this directory is flexible, so these common resources MAY be organized in customized subdirectories and using different name conventions, as needed.

2.1.4 i18n Directory

The optional i18n directory is a subdirectory in the root directory that includes the localization resources of a MiniApp package.

The i18n Directory contains multi-language localization resources to support the internationalization of the MiniApp contents. The filename of each .json document in this directory follows the Language-Tag notation as defined in [BCP47] and represents the specific configuration for that particular language.

The i18n Directory MAY contain as many localization resources as languages or locales a MiniApp supports. The format of these files is defined in the localization resources section.

2.1.5 File and Path Names

Any file name and path name within a MiniApp package MUST comply with the following restrictions to accommodate the potential limitations of the operating systems and facilitate interoperability with the majority of the platforms and file systems, as specified by Internationalization Best Practices for Spec Developers.

  • File names and file paths are case sensitive.
  • File names and file paths MUST be UTF-8 [Unicode] encoded.
  • File names SHOULD NOT exceed 255 bytes in length.
  • Path names SHOULD NOT exceed 65535 bytes in length.
  • File names and path names MUST NOT use the following [Unicode] points:
    • " [U+0022 QUOTATION MARK]
    • * [U+002A ASTERISK]
    • / [U+002F SOLIDUS]
    • : [U+003A COLON]
    • < [U+003C LESS-THAN SIGN]
    • > [U+003E GREATER-THAN SIGN]
    • \ [U+005C REVERSE SOLIDUS]
    • | [U+007C VERTICAL LINE]
    • U+007F DEL
    • U+E0001 LANGUAGE TAG
    • U+E007F CANCEL TAG
    • Codepoints in the following ranges:
      • C0 Controls [U+0000...U+001F]
      • C1 Controls [U+0080...U+009F]
      • Private Use [U+E000...U+F8FF]
      • Specials [U+FFF0...U+FFFF]
      • Supplementary Private Use [U+F0000...U+FFFFF]
      • Supplementary Private Use [U+100000...U+10FFFF]
    • . [U+002E FULL STOP]
    • All Unicode non-character code points, specifically:
      • The 32 contiguous characters in the Basic Multilingual Plane (U+FDD0 … U+FDEF)
      • The last two code points of the Basic Multilingual Plane (U+FFFE and U+FFFF)
      • The last two code points at the end of the Supplementary Planes (U+1FFFE, U+1FFFF … U+EFFFE, U+EFFFF)

All file names within the same directory MUST be unique following Unicode canonical normalization [UAX15] and then full case folding [Unicode]. (Refer to Unicode Canonical Case Fold Normalization Step [CHARMOD-NORM] for more information.)

Note: Limiting the length of file names
If a MiniApp vendor imposes length limits on path and file names, it is important to avoid mid-character truncation due to the difference between bytes and characters in multibyte encodings such as UTF-8. See the text truncation best practice for more information.

2.2 MiniApp Resources

A MiniApp page is composed of, at least, an HTML resource and, optionally, a CSS resource and/or a scripting resource. These related resources MUST have the same path and filename (only changing the file extension) to identify the MiniApp page through a unique page route that needs to be specified in the pages member of the MiniApp manifest [MINIAPP-MANIFEST].

Example 4: Organization of page resources corresponding to the page route 'pages/product/product'
/
|___pages/
        |___product/
                |___product.html
                |___product.css
                |___product.js

2.2.1 HTML Resources

HTML resources are documents that contain markup and information to define MiniApp pages, and their user interfaces, including the structure, visual components, and interaction elements.

HTML resources MUST meet all the following criteria:

Syntax and content
An HTML resource MUST use the HTML syntax defined in [HTML].
File name
An HTML resource SHOULD have a unique filename that identifies a single MiniApp page and matches with the corresponding CSS resource and scripting resource of the page if present.
File extension
An HTML resource SHOULD use the file extension .html.
Editor's note
To define the HTML profile of MiniApp Content Documents.

2.2.2 CSS Resources

CSS resources are stylesheets that describe the rendering and appearance of MiniApp pages. CSS resources can be global, affecting all the pages in a MiniApp (i.e., app.css in the root directory), or with local scope, just affecting a specific page in the MiniApp.

This specification supports the CSS modules as defined in the [CSS-SNAPSHOT].

CSS resources MUST meet all the following criteria:

Syntax and content
A CSS resource MUST follow described using the syntax and definitions of CSS as described in the [CSS-SNAPSHOT].
File name
The global CSS resource, affecting all pages in a MiniApp, MUST be named app.css and stored in the root directory.
A local CSS resource associated with a page SHOULD have a unique filename that identifies the MiniApp page and matches with the corresponding HTML resource and scripting resource if present.
File extension
A CSS resource filename SHOULD use the file extension .css.

2.2.3 Scripting Resources

Scripting resources are documents that contain script elements and data to control the business logic and functionality of the application, adding interactivity and managing the lifecycle of the MiniApp. There is a global scripting resource (i.e., app.js in the root directory) that includes data and functions available for all the pages of the MiniApp, and with specific logic to control the application's lifecycle. Each MiniApp page MAY have associated specific scripting resources, with the scope limited to the concrete page.

Scripting resources MUST meet all the following criteria:

Syntax and content
The scripting resources MUST conform with the requirements of the ECMAScript specification [ECMA-262].
The global scripting resource MUST be named app.js and stored in the root directory.
A local scripting resource associated with a page SHOULD have a unique filename that identifies the MiniApp page and matches with the corresponding HTML resource and CSS resource if present.
File extension
A scripting resource filename SHOULD use the file extension .js.

2.2.4 Localization Resources

A MiniApp localization resource is a document of a MiniApp package that included localized content as part of the internationalization mechanism of MiniApps.

A multilingual MiniApp MAY has several localization resources that will be used during the localization process by the user agents to render content according to the system locale or the user's language preferences. These resources contain JSON objects with key-value pairs that contain the unique identifier (the key) of a localizable term or expression and the representation in the concrete language (the value).

Example 5: Localization resource
{
    "title": "Cool MiniApp",
    "about": "About this MiniApp",
    "intro-page": {
        "title" : "Introduction",
        "main" : "This is the body of the page"
    }
}

Localization resources MUST meet all the following criteria:

File extension
A localization resource filename SHOULD use the file extension .json.
Format
A localization resource MUST be a valid JSON document [JSON].
Structure
A localization resource MUST be composed of key-value pairs. Each key represents a unique identifier for each localizable string (the values).

3. MiniApp ZIP Container

3.1 Introduction

This section is non-normative.

A MiniApp ZIP container is a physical single-file representation of a MiniApp that can be used to distribute it in different scenarios, including:

A MiniApp ZIP container contains all the resources that conforms a MiniApp, according to the MiniApp package structure in a single file. This format supports the use of compression mechanisms.

3.2 ZIP File Requirements

A MiniApp ZIP container uses the ZIP format as defined in [ZIP], including some particularities:

The structure of a MiniApp ZIP container is as follows:

[ZIP File Entries]
[MiniApp Signing Block]    
[ZIP Central Directory]
[End of ZIP Central Directory]
Structure of standard ZIP package and the MiniApp package with a signing block in the middle
Figure 1 ZIP package and MiniApp package with an optional signing block

The MiniApp ZIP container is parsed by first finding the start of the ZIP Central Directory (locating the ZIP End of Central Directory record at the end of the file, then reading the start offset of the Central Directory from the record). Every MiniApp signing block MAY include a signing block magic numbers block, as specified in Digital Signature Requirements, to identify the presence of digital signatures. Once the "magic numbers" block is recognized, the user agent would be able to process the digital signatures stored in the signing block, in the immediately preceding section of the Central Directory, as shown in Figure 2.

Structure of standard ZIP package and the MiniApp package with a signing block in the middle and references to the different blocks of the package
Figure 2 ZIP and MiniApp packages with references to the different blocks using relative offset addessing

MiniApps vendors MAY adopt the digital signature schemes depending on their needs.

Editor's note: To add extension

MiniApp files MAY be identified by the .ma file extension although the use of a file extension is not required.

3.3 Digital Signature Requirements

A MiniApp ZIP container MAY include none, one, or more signatures to help to detect any changes to the protected parts of the software, guaranteeing the integrity of the MiniApp.

A MiniApp signing block is a collection of bytes that contains specific information and metadata about the digital signature that affects a MiniApp, partially or as a whole. The signing block of a MiniApp ZIP container MUST be located immediately before the central directory of the ZIP container, in a way that makes it easier to locate the block if exists.

The signing block magic numbers block is A 16-byte sequence with a unique fingerprint that identifies a digital signature mechanism for a MiniApp package, stored in the signing block of MiniApp ZIP container.

Although this document does not recommend any specific digital signature mechanism (i.e., hash algorithms, encryption methods, etc.), the signing block, if present, MUST meet the following criteria:

Signing block magic numbers
A signing block MUST contains signing block magic numbers, as the preceding block of the Central Directory to identify univocally the type of digital signature included.

4. Internationalization

Internationalization, abbreviated to i18n, is the process of designing and developing a product in a way that ensures it can be easily adapted for users from any culture, region, or language.

Localization is the process of content adaptation to meet a target language or cultural requirements.

MiniApps enable localization of contents using a mechanism based on localized documents placed in the reserved i18n Directory. This mechanism allows authors to place localization resources, named according to a language-range [BCP47] and the .json extension. This is, documents with the localization resources will be identified with language tags [BCP47] that represent the locale of the content. MiniApp user agents match the language ranges held by their locales to the appropriate locale filename.

The format of the localization resources is defined in the localization resources section.

Example 6: Filenames based on language tags in the i18n directory
/
|___i18n/
|     |___en-US.json
|     |___fr-FR.json
|     |___fr.json            
|     |___ja-JP.json
|     |___zh-Hans.json

5. MiniApp Package Processing

User agents MUST follow the following algorithm to dereference, parse and execute a MiniApp package.

To process a MiniApp package, given URL miniapp_uri, perform the following steps:

  1. Let miniapp_zip_file be the result of retrieving a MiniApp ZIP container with miniapp_uri.
  2. Verify a MiniApp ZIP container with miniapp_zip_file.
  3. Let miniapp_package be the result of unzipping the miniapp_zip_file.
  4. If miniapp_package is an unzip exception, then return failure.
  5. Let ordered map manifest be the result of processing the MiniApp manifest with miniapp_package.
  6. Let start_page be the result of preparing the platform runtime with miniapp_uri and manifest.
  7. Let string locale be the result of extracting the locale, passing manifest.
  8. Launch MiniApp passing miniapp_package, manifest, start_page, and locale.

5.1 MiniApp ZIP Container Retrieval

User agents MAY obtain MiniApp ZIP containers through different channels, retrieving the file over the network (i.e., using HTTPs, WebSocket, FTP, or other specific TCP/UDP based protocols), also from the filesystem or using any other mechanism.

To retrieve a MiniApp ZIP container, given URL miniapp_uri, perform the following steps. They return a MiniApp ZIP container.

  1. Let resource be a MiniApp ZIP container as a result of fetching a URL [FETCH], passing miniapp_uri.
  2. Let supplied_mime_type be the result of applying the supplied MIME type detection algorithm [MIMESNIFF] with resource.
  3. If supplied_mime_type is not equal to application/miniapp-pkg+zip, then return failure.
  4. Return resource.

5.2 MiniApp ZIP Container Verification

User agents MAY guarantee the legitimacy and integrity of the MiniApp ZIP container and its content by verifying digital signatures and applying cryptographic mechanisms.

To verify a MiniApp ZIP container, given MiniApp ZIP container miniapp_zip_file, perform the following steps:

  1. If the user agent has the capability to perform digital signature(s) verification of miniapp_zip_file, then:
    Process the digital signatures with miniapp_zip_file.

5.2.1 Digital Signatures Processing

The MiniApp ZIP container MAY contain a signing block that includes one or more signatures. The signing schemes and cryptographic mechanisms depend on the concrete implementation by user agents.

Signing schemes are identified by the magic numbers section included in the MiniApp ZIP container, a 16-byte sequence located immediately before the Central Directory of the ZIP package.

To process the digital signatures, given MiniApp ZIP container miniapp_zip_file, perform the following steps:

  1. Let magic_numbers be a byte sequence.
  2. Let eocd_pointer be a byte sequence as the result of locating the byte sequence 0x06054b50 (read as little-endian) in miniapp_zip_file that marks the End of the Central Directory [ZIP].
  3. Set eocd_pointer to eocd_pointer + 0x00000010.
  4. Let cd_pointer be the result of reading the 4-byte sequence at eocd_pointer.
  5. Let magic_numbers_pointer be eocd_pointer - 0x00000010.
  6. Set magic_numbers to the 16-byte block at magic_numbers_pointer.
  7. Process the digital signatures with magic_numbers and miniapp_zip_file.
Note: Usage
MiniApp user agents implement specific digital signature processing algorithms based on their needs and requirements.

5.3 MiniApp Manifest Processing

User agents MUST parse the MiniApp manifest, located in the MiniApp package, that contains global metadata about the MiniApp.

To process the MiniApp manifest, given MiniApp Package miniapp_package, perform the following steps. They return ordered map.

  1. If manifest.json file does not exist in the package's root directory, then return failure.
  2. Let manifest_json be the result of parse JSON from bytes, passing manifest.json.
  3. If manifest_json is a parsing exception, or manifest_json is not an ordered map, then return failure.
  4. Let manifest be an ordered map.
  5. Process a MiniApp manifest, passing manifest_json and manifest.
  6. Return manifest.

5.4 Platform Runtime Preparation

User agents SHOULD prepare the runtime environment that contains both the logic and the view layers. The logic layer is responsible for logic and control of the application (i.e., app.js, and page.js files). The view layer is responsible for the visual environment and rendering, including the page resource files, such as component templates and stylesheets. In preparation for running a MiniApp, user agents MUST set up the environment with the configuration specified by the MiniApp manifest metadata.

User agents MUST identify and load the start page as the MiniApp entry point, according to the following algorithm.

To prepare the platform runtime, given URL miniapp_uri and ordered map manifest, perform the following steps. They return a MiniApp start page.

  1. If app.js does not exist in the root directory, then return failure.
  2. If app.css does not exist in the root directory, then return failure.
  3. Verify platform compatibility, passing miniapp_package and manifest.
  4. Let start_page be the result of determining the start page, passing miniapp_package, miniapp_uri and manifest.
  5. Return miniapp_uri.

5.4.1 Platform Compatibility Verification

User agents MUST verify that a MiniApp is compatible with them and can run properly in their platform. This verification is performed using the metadata specified in the MiniApp manifest, including the supported version of the platform and checking the pages and resources needed in the execution.

To verify platform compatibility, given MiniApp Package miniapp_package and ordered map manifest, perform the following steps:

  1. Set platform_required to manifest["platform_version"].
  2. If platform_required is not compatible with the user agent configuration, then return failure.
  3. For each page of list manifest["pages"]:
    1. If page does not exist in the miniapp_package, return failure.
  4. If manifest["widgets"] exists, then:
    For each widget_path of list manifest["widgets"]:
    1. If widget_path does not exist in the miniapp_package, return failure.

5.4.2 Start Page Identification

By default, user agents MUST load the start page indicated in the MiniApp manifest as the entry point when the MiniApp is launched. This start page by default MUST be overridden if a valid page is specified in the MiniApp URI, as specified in the following algorithm.

To determine the start page, given MiniApp Package miniapp_package, URL miniapp_uri, and ordered map manifest, perform the following steps. They return a URL.

  1. Let start_page be the result of extracting the start page from URI, passing miniapp_uri.
  2. If start_page is not set, or if start_page is equal to null, or if start_page does not exist in miniapp_package, then:
    Set start_page to the result of extracting the start page from manifest, passing manifest.
  3. Return start_page
5.4.2.1 Extraction of Start Page From URI

MiniApp URIs MAY contain information about the start page, specified as the URL-path-segment string of the URI.

To extract the start page from URI, given URL miniapp_uri, perform the following steps. They return a URL.

  1. Let start_page be the URL-path-segment string resulting of parse miniapp_uri.
  2. If start_page is failure, return null.
  3. Return start_page.
5.4.2.2 Extraction of Start Page From Manifest

As described in the MiniApp Manifest's pages member [MINIAPP-MANIFEST], the start page of a MiniApp is specified in the first item of the pages list.

To extract the start page from manifest, given ordered map manifest, perform the following steps. They return a string.

  1. Let start_page_id be the empty string.
  2. Let list pages be manifest["pages"].
  3. Return pages[0].

5.4.3 Extraction of Locale

To extract the locale, given ordered map manifest, perform the following steps. They return a string.

  1. Let string locale be the user agent's default locale.
  2. If manifest["lang"] exists, and if manifest["lang"] is supported by the user agent, then:
    Set locale to manifest["lang"].
  3. Return locale.

6. Accessibility Considerations

This section is non-normative.

This specification defines a MiniApp in logical and physical terms, detailing its internal file structure and how the different resources are packed within a single file. Also, the document includes algorithms for the MiniApp user agents to retrieve and process a MiniApp container.

The MiniApp Packaging specification requires user agents to process the MiniApp container and its content to generate a user interface and a concrete behavior based on the internal resources (i.e., HTML, stylesheets, scripting, and others) and the configuration (i.e., manifest, app.ux). After the package fetch and processing, user agents are recommended to provide a perceivable and operable user interface and rendered content in every potential scenario, allowing the appearance adaptation to the user’s requirements using stylesheets and offering the possibility to configure and control the display options and the orientation of windows and viewports, as required by some members of the manifest.json (MiniApp Manifest).

Although not specified in this document, it is recommended that user agents guarantee the accessibility aspects in the user interaction, like offering full keyboard access or supporting alternative input devices (if feasible) and enabling users to store the preference settings to improve the user experience. MiniApp user agents and platforms ought to provide mechanisms for rendering and interacting with the application, facilitating the integration of assistive technologies, and complying with applicable specifications and conventions, particularly the User Agent Accessibility Guidelines (UAAG) 2.0.

7. Security Considerations

This specification defines a mechanism to pack, distribute and load MiniApps through a concrete configuration that specifies the app's entry point and different routes (i.e., the manifest's pages member). User agents SHOULD mitigate the potential vulnerability during the initialization and loading phase by limiting the type of resources to be loaded and implementing a sandboxed environment that blocks access to powerful features by default.

7.1 Resources and Services

MiniApp user agents are vulnerable to XSS attacks, concretely getting and processing external resources like images, data sources, and scripts. Therefore, user agents SHOULD examine and limit the potential attack vectors and mitigate the risks by implementing a Content Security Policy (CSP) to control the resources that a MiniApp can fetch or execute.

A MiniApp package MAY include resources of any type, including malicious scripts. Therefore, MiniApp user agents MUST strictly limit the resources to be processed, minimizing the attack surface by discarding those not declared in the manifest and properly bound from the components. So, user agents MUST check the availability of the resources specified in the manifest (i.e., images and component pages) and the complementary files included within the container (i.e., media files, scripts, stylesheets, among others), discarding the rest of the elements in the container. Also, user agents SHOULD consider the specific risks of implementing APIs that enable using third-party resources.

The document does not require a specific exposition of information publicly. However, a MiniApp package includes features that could describe the target user agent and some characteristics of the necessary running environment, including the version of the operating system and the underlying hardware capabilities (e.g., sensors available, type of device, and kind of display). These platform requirements, specified in the MiniApp manifest, MAY halt the execution of a MiniApp initialization during the manifest processing phase, revealing some inconsistencies with the app requirements. Still, user agents SHOULD avoid the public exposition of this information to reduce the attack surface.

The MiniApp Packaging does not specify any specific mechanism to access and expose information about the underlying platform. However, MiniApp user agents MAY implement services to access this information (e.g., platform version, operating system, and sensors available) and APIs to communicate with the hardware and the operating system. Therefore, user agents SHOULD consider the potential risks when supporting these susceptible services and implement adequate mitigation mechanisms by default to guarantee that the powerful features are not activated without meaningful user consent.

7.2 Package Integrity and Trustworthiness

To ensure the integrity and trustworthiness within the distribution stage of MiniApps, a MiniApp package SHOULD be protected by one or more digital signatures. These signatures, along with certificates issued by trusted authorities, could help third parties to validate the authorship of the MiniApp (e.g., a MiniApp developer) and other entities involved in the development or distribution of the software (e.g., an application store as MiniApp distributor).

The usual scenarios where digital signatures are included in MiniApps are, but are not limited to:

No specific digital signature mechanism, cryptographic technology, or algorithm is recommended in this specification. MiniApp vendors MAY implement digital signature mechanisms, according to their use cases. When implemented, the 3.3 Digital Signature Requirements SHALL be followed.

Some technologies and encryption methods are introduced in the B. Signature Schemes.

8. Privacy Considerations

MiniApps MAY deal with personally-identifiable information that can be persisted and preserved in the user agent's sandboxed environment for subsequent app executions. User agents MUST secure that information, allowing only instances of the same application to access the data and avoiding the public exposition. Thus, MiniApp user agents SHOULD transparently inform end-users about the type of data being collected and the purposes of the collection.

End-users MUST decide whether to remove the information stored by the user agent corresponding to any MiniApp instance. User agents SHOULD treat the stored data as potentially sensitive, ensuring that it is adequately removed from the underlying storage when deleting data. Furthermore, user agents SHOULD implement mechanisms to minimize risks in the leakage of sensitive information and protect the user's privacy, like automatically removing the stored data after long periods of inactivity. In any case, user agents SHOULD inform users transparently about the specific privacy policies implemented.

A session starts when the app is launched and terminates when it is unloaded from the system, as defined in [MINIAPP-LIFECYCLE]. Although this specification does not describe any mechanism for data persistence across sessions, MiniApps MAY store data on a user's device that could be retrieved in subsequent sessions. This scenario introduces the risk of user tracking without their knowledge or control. Thus, MiniApp user agents MUST implement protections to ensure that client-side storage mechanisms cannot be misused to track users without their control, like isolating the MiniApps running environments. This isolation will allow exclusive storage space for each MiniApp, univocally identified by the manifest's app_id member, restricting access to the data from other MiniApps.

User agents MAY offer the possibility of installing an app on the system (e.g., through home-screen shortcuts, icons on the desktop, and similar). This process SHOULD be transparent and reversible. If an end-user wants to uninstall the app, the user agent MUST ensure that all the related data is adequately removed from the underlying storage.

This specification does not recommend any encryption mechanism for the MiniApp package to protect its confidentiality. However, it doesn't preclude implementing some encryption mechanism for particular purposes.

A. Acknowledgments

This section is non-normative.

Editor's note
List all the contributors and W3C Team contacts

B. Signature Schemes

This section is non-normative.

Every user agent MAY support its own digital signature schemes depending on their needs. This section includes some examples of digital signature implementations as illustrated in Figure 4. They can be used in specific scenarios, such as developer verification and integrity of a MiniApp during its distribution.

Example of signing blocks with different signature scheme in the MiniApp package
Figure 4 Example of different signature methods included in the MiniApp package

B.1 RPK Signature Scheme

As one implementation of MiniApp, Quick Apps use a so-called RPK (Runnable Package) Signature Scheme, which is similar to the APK Signature Scheme v2 [APK-SIGNATURE-V2], to verify the authorship of the MiniApp package. This signature scheme takes every byte in a MiniApp package into the signature generation. The resulting signing block is created and inserted into the package file, according to the Digital Signature Requirements.

The signing block contains ID-value pairs with information about the signature and the signer identity.

Note

All data values in the RPK signing block are represented in little-endian format, and all length-prefixed fields use uint32 for length.

The description uses the following basic data types:

uint64
64-bit (8-byte) unsigned integer in little-endian format
uint32
32-bit (4-byte) unsigned integer in little-endian format

B.1.1 Signing Block Format

The format of the RPK signing block is as follows:

  • block size in bytes, excluding this field (uint64)
  • Sequence of ID-value pairs (where the Signatures are defined):
    • size of ID-value pair (uint64)
    • ID (uint32)
    • value (size of ID-value pair - 4 bytes)
  • block size in bytes (the same as first field) (uint64)
  • magic numbersRPK Sig Block 42” (16 bytes)

ID-value pairs with unknown IDs are ignored when interpreting the block.

The "block size" value enables locating the start of the signing block in the whole ZIP file.

B.1.1.1 Signatures

The signatures are stored as ID-value pairs with specific identifiers that represent the types of the signature. The supported signatures, and associated IDs, for RPK packages are described in the following sub-clauses.

Editor's note: package-splitting

There are cases where a MiniApp package is split into multiple sub-packages (by a distribution platform e.g. an app-store) for the user agent to download and execute it in a progressive fashion to improve the user experience. In such a case, additional signature types (thus IDs) would be needed to ensure the integrity of each sub-package as well as the whole. Details are for further study.

B.1.1.1.1 Developer Signature

The ID-value pair in the signing block under ID 0x01000101 represents the data of the signature of the whole-file MiniApp package.

The value of the ID-pair contains all the signature blocks and it has a variable length and its structure is as follows:

  • ID: 0x01000101 (uint32)
  • value:
    • size of signer blocks, excluding this field (uint32)
    • Sequence of signer blocks:
      • size of signer block, excluding this field (uint32)
      • signed data:
        • size of digests, excluding this field (uint32)
        • Sequence of digests:
          • size of digest block, excluding this field (uint32)
          • signature algorithm ID (uint32)
          • size of digest content, excluding this field (uint32)
          • digest content (variable length)
        • size of certificates, excluding this field (uint32)
        • Sequence of certificates:
          • size of certificate, excluding this field (uint32)
          • X.509 certificate [rfc2528] in ASN.1 DER form [X690] (variable length)
        • size of additional attributes, excluding this field (uint32)
        • additional attributes
      • size of signatures, excluding this field (uint32)
      • Sequence of signatures:
        • size of signature, excluding this field (uint32)
        • signature algorithm ID (uint32)
        • size of signature content, excluding this field (uint32)
        • signature content (variable length)
      • size of public key, excluding this field (uint32)
      • public key in ASN.1 DER [X690] form (variable length)
B.1.1.1.2 Distributor Signature

The signature of the distributor preserves the integrity of the application during the distribution process, guaranteeing that the package is verified by the trusted distributor and the permission control policy (in the form of a provisioning profile) from the distributor is enforced upon the package.

During the process of distributor signing, either the distributor or the developer adds a Provisioning Profile and uses the private key of the distributor to sign the signature.

The Provisioning Profile is stored in the ID-value pair of the signing block under ID 0x02000201.

The value of the ID-pair contains all its signature blocks and it has a variable length and its structure is as follows:

  • ID: 0x02000201 (uint32)
  • value:
    • size of signer block, excluding this field (uint32)
    • signer block:
      • size of the Provisioning Profile, excluding this field (uint32)
      • provisioning profile. Sequence of the provisioning profile ID-value pairs, according to the provisioning profile IDs:
        • size of ID-value pair, excluding this field (uint32)
        • ID (uint32)
        • value (variable length)
      • size of signature, excluding this field (uint32)
      • signature algorithm ID according to the values of Signature Algorithm IDs (uint32)
      • size of signature content, excluding this field (uint32)
      • signature content (variable length)
B.1.1.1.2.1 Signature Algorithm IDs
  • 0x0101 RSASSA-PSS with SHA2-256 digest, SHA2-256 MGF1, 32 bytes of salt, trailer: 0xbc
  • 0x0102 RSASSA-PSS with SHA2-512 digest, SHA2-512 MGF1, 64 bytes of salt, trailer: 0xbc
  • 0x0103 RSASSA-PKCS1-v1_5 with SHA2-256 digest. This is for build systems which require deterministic signatures.
  • 0x0104 RSASSA-PKCS1-v1_5 with SHA2-512 digest. This is for build systems which require deterministic signatures.
  • 0x0201 ECDSA with SHA2-256 digest
  • 0x0202 ECDSA with SHA2-512 digest
  • 0x0301 DSA with SHA2-256 digest
B.1.1.1.2.2 Supported keys sizes and EC cryptography:
  • RSA: 1024, 2048, 4096, 8192, 16384
  • EC: NIST P-256, P-384, P-521
  • DSA: 1024, 2048, 3072
B.1.1.1.2.3 Provisioning Profile IDs
  • 0x01 Certificate Digest
    • size of certificate digest block, excluding this field (uint32)
    • signature algorithm ID according to the values of Signature Algorithm IDs (uint32)
    • size of certificate digest data, excluding this field (uint32)
    • certificate digest data (variable length)
  • 0x02 Certificate
    • size of certificate, excluding this field (uint32)
    • certificate data in ASN.1 DER [X690] form (variable length)
  • 0x03 Usage:
    • app store, value: 0x01
    • debug, value: 0x02
    • enterprise, value: 0x03
  • 0x04 Manifest
    • size of manifest, excluding this field (uint32)
    • manifest in UTF-8 [UNICODE] (variable length)
  • 0x05 Device IDs
    • size of Device IDs, excluding this field (uint32)
    • Sequence of Device IDs:
      • size of Device ID, excluding this field (uint32)
      • Device ID, represented in MD5 format [rfc1321] (variable length)

B.2 PKCS#7 Signature Scheme

This signature scheme is based on the PKCS #7 Cryptographic Message Syntax [rfc2315]. It MAY cover different stages of packaging signature described in RPK Signature Scheme, including the developer signature and distributor signature.

This signature scheme includes the Provisioning Profile of the MiniApp and the developer's signature at the first stage (developer signing stage). At the second stage (distributor signing stage), a distributor MAY replace the developer's signature with the its own signature. Like the RPK Signature Scheme, this approach generates a signing block to be included into the package file, according to the Digital Signature Requirements.

The PKCS#7 signing block is defined as a data container that includes the block with the digital signature, data encrypted using the PKCS #7 syntax that contains the signatures and the signer identity.

The description uses the following basic data types:

uint64
64-bit (8-byte) unsigned integer
uint32
32-bit (4-byte) unsigned integer
uint16
16-bit (2-byte) unsigned integer

B.2.1 Signing Block Format

The format of the PKCS#7 signing block is as follows:

  • Signing block head
  • Signature Block head:
    • reserved (4 bytes)
    • number of blocks (uint32)
    • size (uint32)
    • version (4 bytes)
    • magic numbersMIX Sig Block 42” (16 bytes)
  • Data
  • Signature Block data in PKCS #7:
    • PKCS #7 Content Type set to SignedData:
      • version: syntax version number
      • digest algorithms: a collection of message-digest algorithm identifiers
      • The content that is signed:
        • version (uint32)
        • size (uint16)
        • number of blocks (uint16)
        • Content Hash:
          • type (uint8)
          • tag (uint8)
          • algorithm ID (uint8)
          • length (uint32)
          • hash (variable length)
      • certificates: a set of PKCS #6 extended certificates and X.509 certificates
      • crls: a set of certificate-revocation lists
      • signerInfos: a collection of per-signer information
    • Signer
  • Hw sign head:
    • number of blocks (uint32)
    • size (uint32)
    • version (4 bytes)
    • magic numbersMIX Sig Block 42” (16 bytes)
B.2.1.1 Types of Signing Blocks

The type of the Block Head is identified by its attribute type. This attribute MUST take two different values:

If the value of type is set to 0 (File Signature block), the header MUST specify a narrower subtype, using the attribute tag in its Block Head. The values for this subtype are:

  • 0: Default
  • 1: HASH (Whole file hash)
  • 0x80: 1M_HASH_ROOT (1M block hash tree, root hash)
  • 0x81: 512K_HASH_ROOT (512K block hash tree, root hash)
  • 0x82: 256K_HASH_ROOT (256K block hash tree, root hash)
  • 0x83: 128K_HASH_ROOT (128K block hash tree, root hash)
  • 0x84: 64K_HASH_ROOT (64K block hash tree, root hash)
  • 0x85: 32K_HASH_ROOT (32K block hash tree, root hash)
  • 0x86: 16K_HASH_ROOT (16K block hash tree, root hash)
  • 0x87: 8K_HASH_ROOT (8K block hash tree, root hash)
  • 0x88: 4K_HASH_ROOT (4K block hash tree, root hash)
  • 0x90: 1M_HASH_BLOCK (1M block hash tree)
  • 0x91: 512K_HASH_BLOCK (512K block hash tree)
  • 0x92: 256K_HASH_BLOCK (256K block hash tree)
  • 0x93: 128K_HASH_BLOCK (128K block hash tree)
  • 0x94: 64K_HASH_BLOCK (64K block hash tree)
  • 0x95: 32K_HASH_BLOCK (32K block hash tree)
  • 0x96: 16K_HASH_BLOCK (16K block hash tree)
  • 0x97: 8K_HASH_BLOCK (8K block hash tree)
  • 0x98: 4K_HASH_BLOCK (4K block hash tree)

C. Media Type Registration

This appendix registers the application/miniapp-pkg+zip media type for MiniApp packages, in conformance with BCP 13 [RFC4289] and Register an Internet Media Type for a W3C Spec.

A MiniApp package file is a container technology based on the [ZIP] archive format, including some modifications.

Type name:
application
Subtype name:
miniapp-pkg+zip
Required parameters:
"N/A"
Optional parameters:
"N/A"
Encoding considerations:
MiniApp packages are binary files encoded in the application/zip media type. See RFC 6839, section 3.6 [RFC6839].
Security considerations:
Security considerations that apply to application/zip also apply to MiniApp package files. User agents that process MiniApp package files should rigorously check the size and validity of data retrieved. When digital signatures are available in a MiniApp package file, the user agent SHOULD implement necessary mechanisms to check the integrity and trustworthiness of the file according to the digital signatures, so as to to protect the end user and the hosting platform from the damage of package tampering or corruption. See more at 7. Security Considerations.
Interoperability considerations:
The file, after including the signature, is not a standard ZIP but the inclusion does not affect parsing and operation of the file as a ZIP file.
Published specification:
This media type registration is for the MiniApp package, as described in the specification located at https://www.w3.org/TR/miniapp-packaging/.
Applications that use this media type:
This media type is used for the distribution of MiniApps. The list, non exhaustive, of applications and software platforms that (intend to) support this media type are: The listed applications above are the base technologies to develop this spec. They are not using the proposed media type yet, but will potentially support it when the spec is ready. The list will be confirmed/updated later.
Fragment identifier considerations:
"N/A"
Additional information:
Deprecated alias names for this type:
"N/A"
Magic number(s):
50 4B 03 04
File extension(s):
MiniApps are usually identified with the extension .ma.
Macintosh file type code(s):
ZIP
Person & email address to contact for further information:
The MiniApps Working Group can be contacted at public-miniapps-wg@w3.org.
Intended usage:
COMMON
Restrictions on usage:
"N/A"
Author:
The MiniApp Packaging defines a file format developed by the W3C MiniApp Working Group.
Change controller:
W3C is the controller for the MiniApp Packaging specification
Provisional registration?:
"N/A"
Issue 4: ZIP container for the package
This section needs to specify the technical details for the MIME type registration (like the extension).
Note

A temporary solution could be application/x-w3c-miniapp-pkg+zip for the sake of any early implementation.

Issue

Should processors check the integrity of the package (Security considerations section)?

D. References

D.1 Normative references

[BCP47]
Tags for Identifying Languages. A. Phillips, Ed.; M. Davis, Ed.. IETF. September 2009. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc5646
[CSS-SNAPSHOT]
CSS Snapshot. URL: https://www.w3.org/TR/CSS/
[ECMA-262]
ECMAScript Language Specification. Ecma International. URL: https://tc39.es/ecma262/multipage/
[FETCH]
Fetch Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://fetch.spec.whatwg.org/
[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[international-specs]
Internationalization Best Practices for Spec Developers. Richard Ishida; Addison Phillips. W3C. 27 April 2023. W3C Working Group Note. URL: https://www.w3.org/TR/international-specs/
[JSON]
The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. December 2017. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc8259
[MIMESNIFF]
MIME Sniffing Standard. Gordon P. Hemsley. WHATWG. Living Standard. URL: https://mimesniff.spec.whatwg.org/
[MINIAPP-LIFECYCLE]
MiniApp Lifecycle. Qing An; Haoyang Xu. W3C. 29 May 2023. W3C Working Draft. URL: https://www.w3.org/TR/miniapp-lifecycle/
[MINIAPP-MANIFEST]
MiniApp Manifest. Martin Alvarez-Espinar; Yongjing ZHANG. W3C. 28 February 2023. W3C Working Draft. URL: https://www.w3.org/TR/miniapp-manifest/
[permissions]
Permissions. Marcos Caceres; Mike Taylor. W3C. 20 December 2022. W3C Working Draft. URL: https://www.w3.org/TR/permissions/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC4289]
Multipurpose Internet Mail Extensions (MIME) Part Four: Registration Procedures. N. Freed; J. Klensin. IETF. December 2005. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc4289
[RFC6839]
Additional Media Type Structured Syntax Suffixes. T. Hansen; A. Melnikov. IETF. January 2013. Informational. URL: https://www.rfc-editor.org/rfc/rfc6839
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[UAX15]
Unicode Normalization Forms. Ken Whistler. Unicode Consortium. 17 August 2022. Unicode Standard Annex #15. URL: https://www.unicode.org/reports/tr15/tr15-53.html
[Unicode]
The Unicode Standard. Unicode Consortium. URL: https://www.unicode.org/versions/latest/
[url]
URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/
[ZIP]
.ZIP File Format Specification. 15 July 2020. Final. URL: https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT

D.2 Informative references

[APK-SIGNATURE-V2]
APK Signature Scheme v2. URL: https://source.android.com/security/apksigning/v2
[CHARMOD-NORM]
Character Model for the World Wide Web: String Matching. Addison Phillips et al. W3C. 11 August 2021. W3C Working Group Note. URL: https://www.w3.org/TR/charmod-norm/
[rfc1321]
The MD5 Message-Digest Algorithm. R. Rivest. IETF. April 1992. Informational. URL: https://www.rfc-editor.org/rfc/rfc1321
[rfc2315]
PKCS #7: Cryptographic Message Syntax Version 1.5. B. Kaliski. IETF. March 1998. Informational. URL: https://www.rfc-editor.org/rfc/rfc2315
[rfc2528]
Internet X.509 Public Key Infrastructure Representation of Key Exchange Algorithm (KEA) Keys in Internet X.509 Public Key Infrastructure Certificates. R. Housley; W. Polk. IETF. March 1999. Informational. URL: https://www.rfc-editor.org/rfc/rfc2528
[UAAG20]
User Agent Accessibility Guidelines (UAAG) 2.0. James Allan; Greg Lowney; Kimberly Patch; Jeanne F Spellman. W3C. 15 December 2015. W3C Working Group Note. URL: https://www.w3.org/TR/UAAG20/
[X690]
Recommendation X.690 — Information Technology — ASN.1 Encoding Rules — Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER), and Distinguished Encoding Rules (DER). ITU. URL: https://www.itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf