W3C First Public Working Draft
Copyright © 2021 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
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).
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 First Public Working Draft using the Recommendation track.
Publication as a First Public 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.
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 and Privacy 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.
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, 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 Packaging specification depends on the Infra Standard [INFRA] to describe algorithms.A conformant MiniApp package MUST meet the following criteria:
pages
subdirectory.common
to store resources available at application level.i18n
to store localization resources for internationalization purposes.manifest.json
, to describe and configure the runtime environment as defined in the MiniApp manifest specification [MINIAPP-MANIFEST].app.js
, with the basic control logic of the MiniApp. app.css
, following a syntax, structure and format as defined in the CSS Resources section.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
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
app.css
app.js
pages
DirectoryThe 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.
/
|___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
.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..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..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
DirectoryThe 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
DirectoryThe 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.
Any file name within a MiniApp package MUST comply with the following restrictions to accommodate the potential limitations of the operating systems and facilitate compatibility with the majority of the platforms:
SOLIDUS: /
(U+002F
)
QUOTATION MARK: "
(U+0022
)
ASTERISK: *
(U+002A
)
FULL STOP as the last character: .
(U+002E
)
COLON: :
(U+003A
)
LESS-THAN SIGN: <
(U+003C
)
GREATER-THAN SIGN: >
(U+003E
)
QUESTION MARK: ?
(U+003F
)
REVERSE SOLIDUS: \
(U+005C
)
VERTICAL LINE: \
(U+007C
)
DEL (U+007F
)
C0 range (U+0000 … U+001F
)
C1 range (U+0080 … U+009F
)
Private Use Area (U+E000 … U+F8FF
)
Non characters in Arabic Presentation Forms-A (U+FDD0 … U+FDEF
)
Specials (U+FFF0 … U+FFFF
)
Tags and Variation Selectors Supplement (U+E0000 … U+E0FFF
)
Supplementary Private Use Area-A (U+F0000 … U+FFFFF
)
Supplementary Private Use Area-B (U+100000 … U+10FFFF
)
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.)
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
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:
.html
.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:
app.css
and stored in the root directory..css
.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:
app.js
and stored in the root directory..js
.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:
.json
.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.
A MiniApp ZIP container uses the ZIP format as defined in [ZIP], including some particularities:
0
, file stored) and Deflate-compressed (method 0
, lossless data compression) contents within the ZIP archive, according to the [ZIP] specification.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.
MiniApp files MAY be identified by the .ma file extension although the use of a file extension is not required.
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:
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.
/
|___i18n/
| |___en-US.json
| |___fr-FR.json
| |___fr.json
| |___ja-JP.json
| |___zh-Hans.json
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:
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.
application/miniapp-pkg+zip
, then return failure.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:
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:
0x06054b50
(read as little-endian) in miniapp_zip_file that marks the End of the Central Directory [ZIP].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.
manifest.json
file does not exist in the package's root directory, then return failure.manifest.json
.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.
app.js
does not exist in the root directory, then return failure.app.css
does not exist in the root directory, then return failure.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:
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.
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.
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.
To extract the locale, given ordered map manifest, perform the following steps. They return a string.
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. the 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 not limited to:
No specific digital signature mechanism, cryptographic technology, or algorithm is recommended in this specification. MiniApp vendors MAY or MAY NOT implement digital signature mechanisms, according to their use cases. When implemented, the § 3.3 Digital Signature Requirements shall be followed.
Some examples of technologies and encryption methods are introduced in the § B. Signature Schemes.
This specification does not recommend any encryption mechanism for the MiniApp package to protect its confidentiality. However, it doesn't preclude an implementation from deploying some encryption mechanism for special purposes.
This section is non-normative.
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.
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:
The format of the RPK signing block is as follows:
RPK Sig Block 42
” (16 bytes)ID-value pairs with unknown IDs should be ignored when interpreting the block.
The "block size" value enables locating the start of the signing block in the whole ZIP file.
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.
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:
0x01000101
(uint32)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:
0x02000201
(uint32)0x0101
RSASSA-PSS with SHA2-256 digest, SHA2-256 MGF1, 32 bytes of salt, trailer: 0xbc0x0102
RSASSA-PSS with SHA2-512 digest, SHA2-512 MGF1, 64 bytes of salt, trailer: 0xbc0x0103
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 digest0x0202
ECDSA with SHA2-512 digest0x0301
DSA with SHA2-256 digest0x01
Certificate Digest
0x02
Certificate
0x03
Usage:
0x01
0x02
0x03
0x04
Manifest
0x05
Device IDs
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:
The format of the PKCS#7 signing block is as follows:
MIX Sig Block 42
” (16 bytes)SignedData
:
MIX Sig Block 42
” (16 bytes)The type of the Block Head is identified by its attribute type
. This attribute MUST take two different values:
0
for File Signature blocks1
for Provisioning Profile blocksIf 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
: Default1
: 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)This section is non-normative.
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.
application
miniapp-pkg+zip
.ma
.
A temporary solution could be application/x-w3c-miniapp-pkg+zip
for the sake of any early implementation.
Should processors check the integrity of the package (Security considerations section)?
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: