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.

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

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.

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:

                /
                |___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
                

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

                    /
                    |___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"
                        }
                    }
                

ZIP File Requirements

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 .

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

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

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.

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:URL|, perform the following steps. They return a [=MiniApp ZIP container=].

1. Let |resource:MiniApp ZIP container| be a [=MiniApp ZIP container=] as a result of fetching a URL [[FETCH]], passing |miniapp_uri|.
2. Let |supplied_mime_type:string| 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|.

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:MiniApp ZIP container|, 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|.

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: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:ordered map| 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:ordered map| be an [=ordered map=].
5. Process a MiniApp manifest, passing |manifest_json| and |manifest|.
6. Return |manifest|.

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:URL| and [=ordered map=] |manifest:ordered map|, 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:URL| be the result of [=determining the start page=], passing |miniapp_package|, |miniapp_uri| and |manifest|.
5. Return |miniapp_uri|.

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.

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:

• 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 SHALL be followed.

Some technologies and encryption methods are introduced in the .