MiniApp Packaging

MiniApp Packaging

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 Editor Draft is a working document and it does not necessarily imply consensus of the Working Group.

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 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, CSS, 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 [=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=]. 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 Manifest A JSON-based file that provides [=User Agents=] with metadata related to a MiniApp as specified in [[MINIAPP-MANIFEST]]. 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=]. 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. 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 common [=Root Directory=], and two specific subdirectories: i18n, and pages.
• The [=Root Directory=] MAY include a subdirectory common to store resources available at application level.
• The [=Root Directory=] MUST contain one configuration file, named manifest.json, to describe and configure the runtime environment as defined in [=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 the CSS Syntax Module Level 3 [[CSS-SYNTAX-3]].
• 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.

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.xml
                |       |___page1.json
                |       |___page1.css
                |___common/
                |       |___componentA.js
                |       |___componentA.xml
                |       |___componentA.css
                |       |___componentA.json
                |       |___example.png
                |___i18n/
                |       |___zh-Hans.json
                |       |___en-US.json
            

Root Directory

The 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 and color, page title, among other), according to the MiniApp Manifest specification [[MINIAPP-MANIFEST]]. app.css This file is the default CSS stylesheet, responsible for the global appearance of the [=MiniApp pages=]. It MAY be empty. app.js This script document has the basic service logic of the MiniApp and includes the basic control of the MiniApp lifecycle, including the management of events for launch, 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 the file name (e.g., intro) and a specific extension that defines the type [=resource=], such as the service logic (e.g., intro.js), the configuration (e.g., intro.json), the structure (e.g., intro.xml) and the scoped stylesheet (e.g., intro.css).

Developers MAY choose to store all the files related to a page either under the pages directory or organized in specific sub-directories for each page.

• A .json file is responsible for the configuration of a MiniApp page. The syntax and structure of these types of files are defined in the JSON Resources section.
• A .xml file is responsible for the structure of a MiniApp page, similar to HTML. The syntax and structure of these types of files are defined in the XML Resources section.
• A .css file is responsible for the CSS style of a MiniApp page. The syntax and structure of these types of files are defined in the CSS Resources section.
• A .js file is responsible for the service logic and lifecycle management (defined in MiniApp Lifecycle [[MINIAPP-LIFECYCLE]]) of a MiniApp page. The syntax and structure 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, and libraries that are accessible from all [=MiniApp 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 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 file name 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 Names

Any [=File Name=] within a [=MiniApp Package=] MUST comply with the following restrictions to accomodate the potential limitations of the operating systems and facilitate the compatibility with the majority of the platforms:

• File Names are case sensitive
• File Names MUST be UTF-8 [[Unicode]] encoded.
• File Names MUST NOT exceed 255 bytes.
• File Names MUST NOT use the following [[Unicode]] characters:
  • LESS-THAN SIGN: < (U+003C)
  • GREATER-THAN SIGN: > (U+003E)
  • COLON: : (U+003A)
  • QUESTION MARK: ? (U+003F)
  • SOLIDUS: / (U+002F)
  • REVERSE SOLIDUS: \ (U+005C)
  • VERTICAL LINE: | (U+007C)
  • ASTERISK: * (U+002A)
  • QUOTATION MARK: " (U+0022)
  • FULL STOP at the end: . (U+002E)
  • DEL (U+007F)
  • C0 range (U+0000 … U+001F)
  • C1 range (U+0080 … U+009F)

MiniApp Resources

JSON Resources

XML Resources

MiniApp user interfaces, including the visual components that defines the structure and the interaction elements of the pages, are described in XML resources.

XML resources MUST meet all the following criteria:

File extension An XML document SHOULD use the file extension .xml.

CSS Resources

The content is rendered and presented to end-users according to CSS Style Sheets. MiniApp User Agents support CSS modules as defined in the [[CSS-SNAPSHOT]].

CSS resources MUST meet all the following criteria:

File extension A MiniApp stylesheet filename SHOULD use the file extension .css.

Scripting Resources

MiniApps contains scripting resources, documents written in JavaScript, that provide the MiniApp with functionality and logic.

Scripting resources MUST meet all the following criteria:

File extension A MiniApp JavaScript filename SHOULD use the file extension .js.

Localization Resources

A 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. Structure A [=Localization Resource=] MUST be composed of key-value pairs. Each key represents a unique identifier for each localizable string (the values).

The detailed format of the .json file is to be further developed.

To define the detailed process of file selection according to the system locale.

Other Resources

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 and MAY use encryption mechanisms to protect files within the file.

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 filenames.
• 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 file name.

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                
        

MiniApp Package Processing

[=User Agents=] MUST follow the following algorithm to dereference, parse and execute a [=MiniApp Package=].

To process a MiniApp Package, given an optional |miniapp_uri|, perform the following steps:

1. Let |miniapp_zip_file| be the result of [=retrieving a MiniApp ZIP Container=] with an optional |miniapp_uri|
2. [=Verify a MiniApp ZIP Container=] file with |miniapp_zip_file|.
3. Let |miniapp_package| be the result of unzipping the |miniapp_zip_file|.
4. If |miniapp_package| is an unzip exception, then return failure.
5. [=Process the MiniApp Manifest=] with |miniapp_package|.
6. Let |start_page| be the result of [=preparing the platform runtime=] with an optional |miniapp_uri|.
7. Execute runtime with |start_page|.

Retrieve a MiniApp ZIP Container

[=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 an optional |miniapp_uri|, perform the following steps. They return a [=MiniApp ZIP Container=].

1. Let |resource| be a [=MiniApp ZIP Container=] as a result of resource retrieval.
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|.

Verify a MiniApp ZIP Container

[=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_file|, perform the following steps:

1. If the [=User Agent=] has the capability to perform verification of the digital signature(s) of the |miniapp_zip_file|, then:
   [=Process the Digital Signatures=] with |miniapp_zip_file|.

Process Digital Signatures

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 inmediately before the Central Directory of the ZIP package.

To Process the Digital Signatures, given |miniapp_zip_file|, perform the following steps:

1. Let |magic_numbers| be a [=byte sequence=].
2. Let |eocd_pointer| be the result of locating the byte sequence 0x06054b50 (read as little-endian) in |miniapp_zip_file| that marks the End of the Central Directory.
3. Set |eocd_pointer| to |eocd_pointer| + 0x00000010.
4. Let |cd_pointer| be the result of reading the 4-byte sequence at |eocd_pointer|.
5. Let |magic_numbers_pointer| be |eocd_pointer| - 0x00000010.
6. Set |magic_numbers| to the 16-byte block at |magic_numbers_pointer|.
7. Process the digital signatures with |magic_numbers| and |miniapp_zip_file|.

Process the MiniApp Manifest 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|, perform the following steps. They return [=MiniApp Manifest=].

1. If manifest.json does not exist in the [=Root Directory=], then return failure.
2. Let |manifest_json| be the result of [=parse JSON from bytes=] manifest.json file.
3. If |manifest_json| is a parsing exception, or the type of |manifest_json| is not object, then return failure.
4. Extract descriptive metadata from |manifest_json|.
5. Return |manifest_json|.

Prepare the platform runtime

[=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 first page as the MiniApp entry point, according to the following algorithm.

To prepare the platform runtime, given optional |miniapp_uri| and |manifest_json|, 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. If i18n/ sub-directory does not exist in the [=Root Directory=], then return failure.
4. [=Check dependencies=] with |manifest_json|.
5. [=Determine the start page=] with optional |miniapp_uri| and |manifest_json|.
6. [=Reload package=] with |miniapp_uri|.

Check Dependencies

To check dependencies, given |manifest_json|, perform the following steps...

Determine Start Page

To determine the start page, given optional |miniapp_uri| and |manifest_json|, perform the following steps. They return a [=string=].

1. Let |start_page_id| be a [=string=].
2. If |miniapp_uri| is set, then
   Set |start_page_id| as a result of [=extracting the start page from the MiniApp URI=].
3. If |start_page_id| is not set or |start_page_id| is equal to null, then:
   Set |start_page_id| as a result of [=extracting the start page from the manifest=].
4. If |start_page_id| does not exist in the |miniapp_package|, then return failure.
5. Return |start_page_id|

Extract Start Page From MiniApp URI

To extract the start page from the MiniApp URI, given |miniapp_uri|, perform the following steps...

Extract Start Page From Manifest

To extract the start page from the manifest, given |manifest_json|, perform the following steps. They return a [=string=].

1. Let |start_page_id| be the empty [=string=].
2. Let |pages_array| be null.
3. Set |pages_array| |manifest_json|["pages"].
4. If IsArray(|pages_array|) is true and |pages_array|.length is greater than 0, then:
   Set |start_page_id| to |pages_array|[0].
5. Return the |start_page_id|.

Reload Package

(The [=User Agent=] SHOULD cache the Max-Age of a specific version of the package archive).

To reload package, given |miniapp_uri|, perform the following steps...

Execute MiniApp Runtime

To execute the MiniApp Runtime, given |start_page|, perform the following steps...

Security and Privacy Considerations

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

• 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 ensures a healthy ecosystem of applications.

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 shall be followed.

Some examples of technologies and encryption methods are introduced in the .

Content Confidentiality

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.

Acknowledgments

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 should be 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)
      • ID (uint32)
      • value (variable length)
    • size of signature, excluding this field (uint32)
    • signature algorithm ID according to the values of Signature Algorithm IDs (uint32)
    • size of signature content, excluding this field (uint32)
    • signature content (variable length)

Signature Algorithm IDs

• 0x0101 RSASSA-PSS with SHA2-256 digest, SHA2-256 MGF1, 32 bytes of salt, trailer: 0xbc
• 0x0102 RSASSA-PSS with SHA2-512 digest, SHA2-512 MGF1, 64 bytes of salt, trailer: 0xbc
• 0x0103 RSASSA-PKCS1-v1_5 with SHA2-256 digest. This is for build systems which require deterministic signatures.
• 0x0104 RSASSA-PKCS1-v1_5 with SHA2-512 digest. This is for build systems which require deterministic signatures.
• 0x0201 ECDSA with SHA2-256 digest
• 0x0202 ECDSA with SHA2-512 digest
• 0x0301 DSA with SHA2-256 digest

Supported keys sizes and EC cryptography:

• RSA: 1024, 2048, 4096, 8192, 16384
• EC: NIST P-256, P-384, P-521
• DSA: 1024, 2048, 3072

Provisioning Profile IDs

• 0x01 Certificate Digest
  • size of certificate digest block, excluding this field (uint32)
  • signature algorithm ID according to the values of Signature Algorithm IDs (uint32)
  • size of certificate digest data, excluding this field (uint32)
  • certificate digest data (variable length)
• 0x02 Certificate
  • size of certificate, excluding this field (uint32)
  • certificate data in ASN.1 DER [[?X690]] form (variable length)
• 0x03 Usage:
  • app store, value: 0x01
  • debug, value: 0x02
  • enterprise, value: 0x03
• 0x04 Manifest
  • size of manifest, excluding this field (uint32)
  • manifest in UTF-8 [[Unicode]] (variable length)
• 0x05 Device IDs
  • size of Device IDs, excluding this field (uint32)
  • Sequence of Device IDs:
    • size of Device ID, excluding this field (uint32)
    • Device ID, represented in MD5 format [[?rfc1321]] (variable length)

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:

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

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

Media Type Registration

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

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

Type name: application Subtype name: miniapp-pkg+zip Required parameters: "N/A" Optional parameters: "N/A" Encoding considerations: MiniApp Packages are binary files encoded in the application/zip media type. See RFC 6839, section 3.6 [[RFC6839]]. Security considerations: Security considerations that apply to application/zip also apply to MiniApp package files. User Agents that process MiniApp package files should rigorously check the size and validity of data retrieved. When digital signatures are available in a MiniApp package file, the User Agent SHOULD implement necessary mechanisms to check the integrity and trustworthiness of the file according to the digital signatures, so as to to protect the end user and the hosting platform from the damage of package tampering or corruption. See more at [[[#sec-security-privacy]]]. Interoperability considerations: The file, after including the signature, is not a standard ZIP but the inclusion does not affect parsing and operation of the file as a ZIP file. Published specification: This media type registration is for the MiniApp Package, as described in the specification located at https://www.w3.org/TR/miniapp-packaging/. Applications that use this media type: This media type is used for the distribution of MiniApps. The list, non exhaustive, of applications and software platforms that (intend to) support this media type are:

The listed applications above are the base technologies to develop this spec. They are not using the proposed media type yet, but will potentially support it when the spec is ready. The list shall 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): Person & email address to contact for further information: The MiniApps Working Group can be contacted at [email protected]. Intended usage: COMMON Restrictions on usage: "N/A" Author: The MiniApp Packaging defines a file format developed by the W3C MiniApp Working Group. Change controller: W3C is the controller for the MiniApp Packaging specification Provisional registration?: "N/A"

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)?