Add file handling support

Author: orbital17

packages/core/src/lib/TwaManifest.ts

@@ -29,6 +29,7 @@ import {LocationDelegationConfig} from './features/LocationDelegationFeature';
 import {PlayBillingConfig} from './features/PlayBillingFeature';
 import {FirstRunFlagConfig} from './features/FirstRunFlagFeature';
 import {ArCoreConfig} from './features/ArCoreFeature';
+import {FileHandler, processFileHandlers} from './types/FileHandler';
 
 // The minimum size needed for the app icon.
 const MIN_ICON_SIZE = 512;
@@ -171,6 +172,7 @@ export class TwaManifest {
   additionalTrustedOrigins: string[];
   retainedBundles: number[];
   protocolHandlers?: ProtocolHandler[];
+  fileHandlers?: FileHandler[];
 
   private static log = new ConsoleLog('twa-manifest');
 
@@ -222,6 +224,7 @@ export class TwaManifest {
     this.additionalTrustedOrigins = data.additionalTrustedOrigins || [];
     this.retainedBundles = data.retainedBundles || [];
     this.protocolHandlers = data.protocolHandlers;
+    this.fileHandlers = data.fileHandlers;
   }
 
   /**
@@ -321,6 +324,12 @@ export class TwaManifest {
         fullScopeUrl,
     );
 
+    const fileHandlers = processFileHandlers(
+      webManifest.file_handlers ?? [],
+      fullStartUrl,
+      fullScopeUrl,
+    );
+
     const twaManifest = new TwaManifest({
       packageId: generatePackageId(webManifestUrl.host) || '',
       host: webManifestUrl.host,
@@ -353,6 +362,7 @@ export class TwaManifest {
       orientation: asOrientation(webManifest.orientation) || DEFAULT_ORIENTATION,
       fullScopeUrl: fullScopeUrl.toString(),
       protocolHandlers: processedProtocolHandlers,
+      fileHandlers,
     });
     return twaManifest;
   }
@@ -505,6 +515,18 @@ export class TwaManifest {
     const fullStartUrl: URL = new URL(webManifest['start_url'] || '/', webManifestUrl);
     const fullScopeUrl: URL = new URL(webManifest['scope'] || '.', webManifestUrl);
 
+    let fileHandlers = oldTwaManifestJson.fileHandlers;
+    if (!(fieldsToIgnore.includes('file_handlers'))) {
+      fileHandlers = processFileHandlers(
+        webManifest.file_handlers ?? [],
+        fullStartUrl,
+        fullScopeUrl,
+      );
+      if (fileHandlers.length == 0) {
+        fileHandlers = oldTwaManifestJson.fileHandlers;
+      }
+    }
+
     const twaManifest = new TwaManifest({
       ...oldTwaManifestJson,
       name: this.getNewFieldValue('name', fieldsToIgnore, oldTwaManifest.name,
@@ -527,6 +549,7 @@ export class TwaManifest {
       monochromeIconUrl: monochromeIconUrl || oldTwaManifestJson.monochromeIconUrl,
       shortcuts: shortcuts,
       protocolHandlers: protocolHandlers,
+      fileHandlers,
     });
     return twaManifest;
   }
@@ -583,6 +606,7 @@ export interface TwaManifestJson {
   additionalTrustedOrigins?: string[];
   retainedBundles?: number[];
   protocolHandlers?: ProtocolHandler[];
+  fileHandlers?: FileHandler[];
 }
 
 export interface SigningKeyInfo {

packages/core/src/lib/features/FeatureManager.ts

@@ -23,6 +23,7 @@ import {FirstRunFlagFeature} from './FirstRunFlagFeature';
 import {Log, ConsoleLog} from '../Log';
 import {ArCoreFeature} from './ArCoreFeature';
 import {ProtocolHandlersFeature} from './ProtocolHandlersFeature';
+import {FileHandlingFeature} from './FileHandlingFeature';
 
 const ANDROID_BROWSER_HELPER_VERSIONS = {
   stable: 'com.google.androidbrowserhelper:androidbrowserhelper:2.6.0',
@@ -108,6 +109,10 @@ export class FeatureManager {
     if (twaManifest.protocolHandlers) {
       this.addFeature(new ProtocolHandlersFeature(twaManifest.protocolHandlers));
     }
+
+    if (twaManifest.fileHandlers) {
+      this.addFeature(new FileHandlingFeature(twaManifest.fileHandlers));
+    }
   }
 
   private addFeature(feature: Feature): void {

packages/core/src/lib/features/FileHandlingFeature.ts

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2025 Google Inc. All Rights Reserved.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+import {EmptyFeature} from './EmptyFeature';
+import {FileHandler} from '../types/FileHandler';
+
+const activityAliasTemplate = (handler: FileHandler, index: number) => `
+    <activity-alias
+        android:name="FileHandlingActivity${index}"
+        android:targetActivity="LauncherActivity"
+        android:exported="true">
+        <meta-data android:name="android.support.customtabs.trusted.FILE_HANDLING_ACTION_URL"
+            android:value="${handler.actionUrl}" /> 
+        <intent-filter>
+            <action android:name="android.intent.action.VIEW"/>
+            <category android:name="android.intent.category.DEFAULT" />
+            <category android:name="android.intent.category.BROWSABLE"/>
+            <data android:scheme="content" />
+            ${ handler.mimeTypes.map(
+              (mimeType: string) => `<data android:mimeType="${mimeType}" />`
+            ).join('\n') }
+        </intent-filter>
+    </activity-alias>
+`;
+
+export class FileHandlingFeature extends EmptyFeature {
+  constructor(fileHandlers: FileHandler[]) {
+    super('fileHandling');
+    if (fileHandlers.length === 0) return;
+    for (let i = 0; i < fileHandlers.length; i++) {
+      this.androidManifest.components.push(activityAliasTemplate(fileHandlers[i], i));
+    }
+  }
+}

packages/core/src/lib/types/FileHandler.ts

@@ -0,0 +1,79 @@
+/*
+ * Copyright 2025 Google Inc. All Rights Reserved.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+export interface FileHandlerJson {
+  action?: string;
+  accept?: {
+    [mimeType: string]: Array<string>;
+  }
+}
+
+export interface FileHandler {
+  actionUrl: string;
+  mimeTypes: Array<string>;
+}
+
+function normalizeUrl(url: string, startUrl: URL, scopeUrl: URL,): string | undefined {
+  try {
+    const absoluteUrl = new URL(url, startUrl);
+
+    if (absoluteUrl.protocol !== 'https:') {
+      console.warn('Ignoring url with illegal scheme:', absoluteUrl.toString());
+      return;
+    }
+
+    if (absoluteUrl.origin != scopeUrl.origin) {
+      console.warn('Ignoring url with invalid origin:', absoluteUrl.toString());
+      return;
+    }
+
+    if (!absoluteUrl.pathname.startsWith(scopeUrl.pathname)) {
+      console.warn('Ignoring url not within manifest scope: ', absoluteUrl.toString());
+      return;
+    }
+
+    return absoluteUrl.toString();
+  } catch (error) {
+    console.warn('Ignoring invalid url:', url);
+  }
+}
+
+export function processFileHandlers(
+  fileHandlers: FileHandlerJson[],
+  startUrl: URL,
+  scopeUrl: URL,
+): FileHandler[] {
+  const processedFileHandlers: FileHandler[] = [];
+
+  for (const handler of fileHandlers) {
+    if (!handler.action || !handler.accept) continue;
+
+    const actionUrl = normalizeUrl(handler.action, startUrl, scopeUrl);
+    if (!actionUrl) continue;
+
+    const mimeTypes = Object.keys(handler.accept);
+    if (mimeTypes.length == 0) continue;
+
+    const processedHandler: FileHandler = {
+      actionUrl,
+      mimeTypes,
+    };
+
+    processedFileHandlers.push(processedHandler);
+  }
+
+  return processedFileHandlers;
+}

packages/core/src/lib/types/WebManifest.ts

@@ -15,6 +15,7 @@
  *  limitations under the License.
  */
 
+import {FileHandlerJson} from './FileHandler';
 import {ProtocolHandler} from './ProtocolHandler';
 
 export interface WebManifestIcon {
@@ -70,4 +71,5 @@ export interface WebManifestJson {
   share_target?: ShareTarget;
   orientation?: OrientationLock;
   protocol_handlers?: Array<ProtocolHandler>;
+  file_handlers?: Array<FileHandlerJson>;
 }