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=]).
Introduction
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.
The MiniApp Packaging specification depends on the Infra Standard [[INFRA]] to describe algorithms.
Package Conformance
A conformant [=MiniApp package=] MUST meet the following criteria:
The file system of a package MUST have a file structure based on a [=root directory=] and the pages subdirectory.
The [=root directory=] MAY include a subdirectory common to store resources available at application level.
The [=root directory=] SHOULD include a subdirectory i18n to store [=localization resources=] for internationalization purposes.
The [=root directory=] MUST contain one configuration file, named manifest.json, to describe and configure the runtime environment as defined in the MiniApp manifest specification [[MINIAPP-MANIFEST]].
The [=root directory=] MUST contain one script document, named app.js, with the basic control logic of the MiniApp.
The [=root directory=] MUST contain one stylesheet, named app.css, following a syntax, structure and format as defined in the CSS Resources section.
The whole [=MiniApp package=] MUST be wrapped as a [[ZIP]] file, according to the requirements of [=MiniApp ZIP containers=].
The file system of a package MAY contain other subdirectories and files of different nature as defined in the Directory and File System Structure section.
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:
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.
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.
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.
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.
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.
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 [[[international-specs]]].
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.)
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.
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]].
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.
To define the HTML profile of MiniApp Content Documents.
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.
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.
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).
{
"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).
MiniApp ZIP Container
Introduction
A [=MiniApp ZIP container=] is a physical single-file representation of a MiniApp that can be used to distribute it in different scenarios, including:
An organization that stores and lists catalogs of MiniApps (i.e., marketplace);
A developer that builds a MiniApp and delivers it to a marketplace;
A developer that shares a MiniApp with the QA department for testing.
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.
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]
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 .
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.
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.
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.
[=User agents=] MUST follow the following algorithm to dereference, parse and execute a [=MiniApp package=].
To process a MiniApp package, given [=URL=] |miniapp_uri:URL|, perform the following steps:
Let |miniapp_zip_file:MiniApp ZIP container| be the result of [=retrieving a MiniApp ZIP container=] with |miniapp_uri|.
[=Verify a MiniApp ZIP container=] with |miniapp_zip_file|.
Let |miniapp_package:Miniapp package| be the result of unzipping the |miniapp_zip_file|.
If |miniapp_package| is an unzip exception, then return failure.
Let [=ordered map=] |manifest:ordered map| be the result of [=processing the MiniApp manifest=] with |miniapp_package|.
Let |start_page:MiniApp start page| be the result of [=preparing the platform runtime=] with |miniapp_uri| and |manifest|.
Let [=string=] |locale:string| be the result of [=extracting the locale=], passing |manifest|.
Launch MiniApp passing |miniapp_package|, |manifest|, |start_page|, and |locale|.
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=].
Let |resource:MiniApp ZIP container| be a [=MiniApp ZIP container=] as a result of fetching a URL [[FETCH]], passing |miniapp_uri|.
If |supplied_mime_type| is not equal to application/miniapp-pkg+zip, then return failure.
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:
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|.
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:MiniApp ZIP container|, perform the following steps:
Let |magic_numbers:byte sequence| be a [=byte sequence=].
Let |eocd_pointer:byte sequence| 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]].
Set |eocd_pointer| to |eocd_pointer| + 0x00000010.
Let |cd_pointer:byte sequence| be the result of reading the 4-byte sequence at |eocd_pointer|.
Let |magic_numbers_pointer:byte sequence| be |eocd_pointer| - 0x00000010.
Set |magic_numbers| to the 16-byte block at |magic_numbers_pointer|.
Process the digital signatures with |magic_numbers| and |miniapp_zip_file|.
[=MiniApp user agents=] implement specific digital signature processing algorithms based on their needs and requirements.
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=].
If manifest.json file does not exist in the package's [=root directory=], then return failure.
Let |manifest_json:ordered map| be the result of [=parse JSON from bytes=], passing manifest.json.
If |manifest_json| is a parsing exception, or |manifest_json| is not an [=ordered map=], then return failure.
[=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=].
If app.js does not exist in the [=root directory=], then return failure.
If app.css does not exist in the [=root directory=], then return failure.
[=Verify platform compatibility=], passing |miniapp_package| and |manifest|.
Let |start_page:URL| be the result of [=determining the start page=], passing |miniapp_package|, |miniapp_uri| and |manifest|.
Return |miniapp_uri|.
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:MiniApp Package| and [=ordered map=] |manifest:ordered map|, perform the following steps:
Set |platform_required:ordered map| to |manifest|["platform_version"].
If |platform_required| is not compatible with the [=user agent=] configuration, then return failure.
[=list/For each=] |page:URL| of [=list=] |manifest|["pages"]:
If |page| does not exist in the |miniapp_package|, return failure.
If |manifest|["widgets"] [=map/exists=], then:
[=list/For each=] |widget_path:URL| of [=list=] |manifest|["widgets"]:
If |widget_path| does not exist in the |miniapp_package|, return failure.
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:MiniApp Package|, [=URL=] |miniapp_uri:URL|, and [=ordered map=] |manifest:ordered map|, perform the following steps. They return a [=URL=].
Let |start_page:URL| be the result of [=extracting the start page from URI=], passing |miniapp_uri|.
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|.
Return |start_page|
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:URL|, perform the following steps. They return a [=URL=].
Let |start_page:URL| be the [=URL-path-segment string=] resulting of [=URL Parser|parse=] |miniapp_uri:URL|.
If |start_page| is failure, return null.
Return |start_page|.
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:ordered map|, perform the following steps. They return a [=string=].
Let |start_page_id| be the empty [=string=].
Let [=list=] |pages:list| be |manifest|["pages"].
Return |pages|[0].
Extraction of Locale
To extract the locale, given [=ordered map=] |manifest:ordered map|, perform the following steps. They return a [=string=].
Let [=string=] |locale:string| be the [=user agent=]'s default locale.
If |manifest|["lang"] [=map/exists=], and if |manifest|["lang"] is supported by the [=user agent=], then:
Set |locale| to |manifest|["lang"].
Return |locale|.
Accessibility Considerations
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 [[[UAAG20]]].
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.
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 .
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 [=Document/launched=] and terminates when it is [=Document/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.
Acknowledgments
List all the contributors and W3C Team contacts
Signature Schemes
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 . They can be used in specific scenarios, such as developer verification and integrity of a MiniApp during its distribution.
Example of different signature methods included in the MiniApp package
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.
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
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 numbers “RPK 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.
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.
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.
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)
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)
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)
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
Signing Block Format
The format of the PKCS#7 signing block is as follows:
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 numbers “MIX Sig Block 42” (16 bytes)
Types of Signing Blocks
The type of the Block Head is identified by its attribute type. This attribute MUST take two different values:
0 for File Signature blocks
1 for [=Provisioning Profile=] blocks
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:
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 [[[#sec-security]]].
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.
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:
