Sub Apps

1. Introduction

The Sub Apps API allows a parent application to programmatically install, list, and remove auxiliary applications (Sub Apps) that:

1. Appear to the operating system and user as fully distinct applications (separate launcher icons, distinct taskbar/shelf windows, and individual OS integrations).

2. Share the underlying resources, origin, storage, permissions, and update lifecycle of the parent application.

This API is restricted to isolated contexts to ensure security and data integrity.

2. Concepts

An installed web application has an associated parent app, which is either null or an installed web application.

An installed web application has an associated sub-apps set, which is a set of installed web applications.

A Document has an associated installed web application, which is the installed web application that the Document is presented as part of. The exact mechanism for this association is implementation-defined.

A Document is a sub-app document if it has an associated installed web application and its associated installed web application’s parent app is not null.

3. Extensions to the Window interface

[Exposed=Window, SecureContext, IsolatedContext]
partial interface Window {
  [SameObject] readonly attribute SubApps subApps;
};

3.1. subApps attribute

Each Window object has an associated subApps, which is a SubApps instance created alongside the Window.

4. SubApps interface

// Represents the https://w3c.github.io/manifest/#id-member
typedef USVString ManifestId;

dictionary SubAppsAddResponse {
  record<USVString, ManifestId> installedApps;
  record<USVString, DOMException> failedApps;
};

dictionary SubAppsRemoveResponse {
  sequence<ManifestId> removedApps;
  record<USVString, DOMException> failedApps;
};

dictionary SubAppsListResult {
  required DOMString appName;
};

[
  Exposed=Window,
  SecureContext,
  IsolatedContext
] interface SubApps {
  Promise<SubAppsAddResponse> add(sequence<USVString> install_paths);
  Promise<SubAppsRemoveResponse> remove(sequence<ManifestId> manifest_ids);
  Promise<record<USVString, SubAppsListResult>> list();
};

A string path is a valid relative path for a Document document if all of the following conditions are met:

1. path is not a valid absolute URL.

2. path starts with "/".

3. path is not empty.

4. path does not start with "//".

5. The result of parsing path with document’s document base URL as the base URL is not failure.

4.1. add() method

The add(install_paths) method steps are:

The install_paths argument is a list of relative paths pointing to the sub-apps' start HTML pages.

1. Let promise be a new promise.

2. Let document be the relevant global object’s associated Document.

3. If document is not allowed to use the policy-controlled feature named "sub-apps", reject promise with a "SecurityError" DOMException and return promise.

4. If document is a sub-app document, reject promise with a "NotSupportedError" DOMException and return promise.

5. Let parsedUrls be an empty list.

6. For each installPath in install_paths:

   1. If installPath is not a valid relative path for document, reject promise with a "TypeError" DOMException and return promise.

   2. Let absoluteUrl be the result of parsing installPath with document’s document base URL as the base URL.

   3. If absoluteUrl is failure, reject promise with a "TypeError" DOMException and return promise.

   4. Append absoluteUrl to parsedUrls.

7. Let parentApp be document’s associated installed web application.

8. Let currentSubAppsCount be the size of parentApp’s sub-apps set.

9. If currentSubAppsCount + install_paths’s size is greater than 20, reject promise with a "QuotaExceededError" DOMException and return promise.

10. Let subApps be this.

11. Run the following steps in parallel:

    1. Let userConsent be the result of requesting user consent for installing the sub-apps in install_paths (e.g. by presenting a unified installation dialog).

    2. If userConsent is denied, queue a global task on the relevant global object of subApps to reject promise with a "NotAllowedError" DOMException, and abort these steps.

    3. Let installedApps be an empty map.

    4. Let failedApps be an empty map.

    5. For each absoluteUrl in parsedUrls:

       1. Let installPath be absoluteUrl’s path.

       2. Let manifest be the result of fetch and process the manifest given absoluteUrl.

       3. If manifest is failure, perform the following steps:

          1. Set failedApps[installPath] to a new "DataError" DOMException.

          2. Continue.

       4. Let manifestId be manifest’s id. If it is not defined, fall back to manifest’s start_url (without reference/hash fragment).

       5. If parentApp already has a sub-app with manifestId installed, perform the following steps:

          1. Set failedApps[installPath] to a new "InvalidStateError" DOMException.

          2. Continue.

       6. If the scope of parentApp’s manifest is a prefix of the manifest’s scope, or the manifest’s scope is a prefix of the scope of any currently installed sub-app in parentApp’s sub-apps set, or the scope of any currently installed sub-app in parentApp’s sub-apps set is a prefix of the manifest’s scope, or the absoluteUrl points to parentApp’s manifest itself, perform the following steps:

          1. Set failedApps[installPath] to a new "ConstraintError" DOMException.

          2. Continue.

       7. Try to install the sub-app on the platform’s application launcher.

       8. If the installation fails due to a system or database error:

          1. Set failedApps[installPath] to a new "OperationError" DOMException.

          2. Continue.

       9. Set installedApps[installPath] to manifestId.

    6. Let response be a new SubAppsAddResponse dictionary with:

       • installedApps set to installedApps.

       • failedApps set to failedApps.

    7. Queue a global task on the relevant global object of subApps to resolve promise with response.

12. Return promise.

4.2. remove() method

The manifest_ids argument is a list of ids of the sub-apps to remove.

The remove(manifest_ids) method steps are:

1. Let promise be a new promise.

2. Let document be the relevant global object’s associated Document.

3. If document is not allowed to use the policy-controlled feature named "sub-apps", reject promise with a "SecurityError" DOMException and return promise.

4. If document is a sub-app document, reject promise with a "NotSupportedError" DOMException and return promise.

5. Let parentApp be document’s associated installed web application.

6. Let parsedManifestIds be an empty list.

7. For each manifestId in manifest_ids:

   1. If manifestId is not a valid relative path for document, reject promise with a "TypeError" DOMException and return promise.

   2. Let parsedUrl be the result of parsing manifestId with document’s document base URL as the base URL.

   3. If parsedUrl is failure, reject promise with a "TypeError" DOMException and return promise.

   4. Append parsedUrl to parsedManifestIds.

8. Let subApps be this.

9. Run the following steps in parallel:

   1. Let removedApps be an empty sequence.

   2. Let failedApps be an empty map.

   3. For each parsedUrl in parsedManifestIds:

      1. Let manifestId be parsedUrl’s path.

      2. If there is no installed web application in parentApp’s sub-apps set whose id is manifestId, perform the following steps:

         1. Set failedApps[manifestId] to a new "NotFoundError" DOMException.

         2. Continue.

      3. Attempt to uninstall the sub-app with ID manifestId from the system launcher and registry.

      4. If uninstallation fails due to a system error, perform the following steps:

         1. Set failedApps[manifestId] to a new "OperationError" DOMException.

         2. Continue.

      5. Append manifestId to removedApps.

   4. Let response be a new SubAppsRemoveResponse dictionary with:

      • removedApps set to removedApps.

      • failedApps set to failedApps.

   5. Queue a global task on the relevant global object of subApps to resolve promise with response.

10. Return promise.

4.3. list() method

The list() method steps are:

1. Let promise be a new promise.

2. Let document be the relevant global object’s associated Document.

3. If document is not allowed to use the policy-controlled feature named "sub-apps", reject promise with a "SecurityError" DOMException and return promise.

4. If document is a sub-app document, reject promise with a "NotSupportedError" DOMException and return promise.

5. Let parentApp be document’s associated installed web application.

6. Let subApps be this.

7. Run the following steps in parallel:

   1. Let listResult be an empty map.

   2. Retrieve the list of all currently installed sub-apps for parentApp from the platform registry.

   3. If retrieving the list fails due to a platform error, Queue a global task on the relevant global object of subApps to reject promise with an "OperationError" DOMException, and abort these steps.

   4. For each installed sub-app subApp:

      1. Let manifestId be subApp’s id.

      2. Let appName be the name of the sub-app as extracted from its web manifest.

      3. Let resultEntry be a new SubAppsListResult dictionary with appName set to appName.

      4. Set listResult[manifestId] to resultEntry.

   5. Queue a global task on the relevant global object of subApps to resolve promise with listResult.

8. Return promise.

4.4. Fetch and process the manifest

write the "fetch and process the manifest" algorithm. [Issue #2]

To fetch and process the manifest given a url (a URL), run the following steps:

1. Return failure.

5. Security and Privacy Considerations

Installing and managing auxiliary applications is a powerful feature. A user agent MUST NOT allow a web application to install or manage sub-apps without express permission.

This section outlines the threats considered and the normative requirements for user agents to mitigate them.

5.1. Shared Origin Identity

5.2. Permission Inheritance

To access the Sub Apps API, the parent app’s document must explicitly declare the permission policy sub-apps. Permission policies declared for a sub-app have no effect.

5.3. Explicit User Consent

The user agent MUST display a permission prompt that clearly indicates which origin is requesting access and provides the user with enough information to make an informed decision (for example, by displaying the names and icons of the sub-apps being installed).

5.4. Identity Spoofing Risks

5.5. OS Integration Extension Risk

5.6. Quota and Limits

6. Integrations

6.1. Permissions Policy

This specification defines a feature that controls whether the methods exposed by the subApps attribute on the Window object may be used.

The feature name for this feature is "sub-apps".

The default allowlist for this feature is 'none'. User agents MAY override this to 'self' for particular origins (for example based on user decision).