MiniApp Packaging

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.

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.

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, and SHOULD 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 package has a file structure with some restrictions and reserved files and subdirectories.

The following example shows a typical 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

/
|___manifest.json
|___app.js
|___app.css
|___pages/
        |___detail.js
        |___detail.html
        |___detail.css
        |___list.js
        |___list.html
        |___list.css

/
|___manifest.json
|___app.js
|___app.css
|___pages/
        |___detail/
                |___detail.js
                |___detail.html
                |___detail.css
        |___list
                |___list.js
                |___list.html
                |___list.css

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].

/
|___pages/
        |___product/
                |___product.html
                |___product.css
                |___product.js

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

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

• The contents of the MiniApp ZIP container MUST be a conforming MiniApp package.
• MiniApp ZIP containers MUST NOT use the ZIP encryption mechanisms.
• Data integrity MUST be provided for each file using CRC32 as specified in [ZIP].
• MiniApp ZIP containers MUST NOT use the features in the ZIP application note [ZIP] that allow ZIP files to be spanned across multiple storage media, or split into multiple files.
• MiniApp ZIP containers MUST include ZIP uncompressed (method 0, file stored) and Deflate-compressed (method 0, lossless data compression) contents within the ZIP archive, according to the [ZIP] specification.
• MiniApp ZIP containers MUST use UTF-8 [Unicode] for encoding file names.
• MiniApp ZIP containers MUST NOT use patented features.
• MiniApp ZIP containers MAY include a special block, the MiniApp signing block, to allow digital signatures affecting the whole package.
• The minimum version of ZIP to extract a MiniApp ZIP container is 2.0 (supporting folders and Deflate compression), according to the [ZIP] specification.

The structure of a MiniApp ZIP container is as follows:

[ZIP File Entries]
[MiniApp Signing Block]    
[ZIP Central Directory]
[End of ZIP Central Directory]

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.

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

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.

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.

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.

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.

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.

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.

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:

• A digital signature (with a valid certificate) of the author that ensures the origin of the MiniApp, which gives a recipient strong reason to believe that this package was created by a known sender (authentication) and that the message was not altered in transit (integrity). Thus, an end-user or a hosting platform can decide whether to install the MiniApp package depending on the status and quality of the author (e.g., credits, blocklist, certifications, etc.).
• Distributors’ signatures (for example, official marketplace signatures), which are used to ensure the trustworthiness of the delivery channel. This kind of signature protects end-users from tampering activities and provides a healthy ecosystem of applications.

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.