feat: make it possible to pass signed files to launchApp

Allow apps to launch new instances or other apps with specific files.
The files must be passed as file signature objects, ensuring it was a
file the app was granted access to through a user action.

Author: KernelDeimos

src/gui/src/helpers/launch_app.js

@@ -201,6 +201,7 @@ const launch_app = async (options)=>{
 
         // add app_id to URL
         iframe_url.searchParams.append('puter.app.id', app_info.uuid);
+        iframe_url.searchParams.append('puter.app.name', app_info.name);
 
         // add parent_app_instance_id to URL
         if (options.parent_instance_id) {
@@ -223,7 +224,7 @@ const launch_app = async (options)=>{
 
         if(file_signature){
             iframe_url.searchParams.append('puter.item.uid', file_signature.uid);
-            iframe_url.searchParams.append('puter.item.path', privacy_aware_path(options.file_path) || file_signature.path);
+            iframe_url.searchParams.append('puter.item.path', options.file_path ? privacy_aware_path(options.file_path) : file_signature.path);
             iframe_url.searchParams.append('puter.item.name', file_signature.fsentry_name);
             iframe_url.searchParams.append('puter.item.read_url', file_signature.read_url);
             iframe_url.searchParams.append('puter.item.write_url', file_signature.write_url);

src/gui/src/services/ExecService.js

@@ -48,7 +48,7 @@ export class ExecService extends Service {
     }
 
     // This method is exposed to apps via IPCService.
-    async launchApp ({ app_name, args, pseudonym, file_paths }, { ipc_context, msg_id } = {}) {
+    async launchApp ({ app_name, args, pseudonym, file_paths, items }, { ipc_context, msg_id } = {}) {
         const app = ipc_context?.caller?.app;
         const process = ipc_context?.caller?.process;
 
@@ -105,6 +105,13 @@ export class ExecService extends Service {
                 parent_pseudo_id: connection.backward.uuid,
             } : {}),
         };
+        
+        if ( items && items.length ) {
+            if ( items.length > 1 ) {
+                console.warn('launchApp does not support launch with multiple items (yet)');
+            }
+            launch_options.file_signature = items[0];
+        }
 
         // Check if file_paths are provided and caller has godmode permissions
         if (file_paths && Array.isArray(file_paths) && file_paths.length > 0 && process) {

src/puter-js/src/index.js

@@ -215,6 +215,11 @@ export default globalThis.puter = (function() {
             if(URLParams.has('puter.app.id')){
                 this.appID = decodeURIComponent(URLParams.get('puter.app.id'));
             }
+            
+            // Extract app name (added later)
+            if(URLParams.has('puter.app.name')){
+                this.appName = decodeURIComponent(URLParams.get('puter.app.name'));
+            }
 
             // Construct this App's AppData path based on the appID. AppData path is used to store files that are specific to this app.
             // The default AppData path is `~/AppData/<appID>`.

src/puter-js/src/modules/FSItem.js

@@ -15,8 +15,49 @@ class FSItem{
         this.modified       = options.modified ?? options.fsentry_modified;
         this.created        = options.created ?? options.fsentry_created;
         this.isDirectory    = (options.isDirectory || options.is_dir || options.fsentry_is_dir) ? true : false;
+        
+        // We add some properties to '_internalProperties' to make it clear
+        // that they are not meant to be accessed outside of puter.js;
+        // this permits us to change or remove these properties in the future.
+        const internalProperties = {};
+        Object.defineProperty(this, '_internalProperties', {
+            enumerable: false,
+            value: internalProperties,
+        });
+        
+        // Currently 'signature' and 'expires' are not provided in 'options',
+        // but they can be inferred by writeURL or readURL.
+        internalProperties.signature = options.signature ?? (() => {
+            const url = new URL(this.writeURL ?? this.readURL);
+            return url.searchParams.get('signature');
+        })();
+        internalProperties.expires = options.expires ?? (() => {
+            const url = new URL(this.writeURL ?? this.readURL);
+            return url.searchParams.get('expires');
+        })();
+        
+        // This computed property gives us an object in the format output by
+        // the `/sign` endpoint, which can be passed to `launch_app` to
+        // allow apps to open a file in another app or another instance.
+        Object.defineProperty(internalProperties, 'file_signature', {
+            get: () => ({
+                read_url: this.readURL,
+                write_url: this.writeURL,
+                metadata_url: this.metadataURL,
+                fsentry_accessed: this.accessed,
+                fsentry_modified: this.modified,
+                fsentry_created: this.created,
+                fsentry_is_dir: this.isDirectory,
+                fsentry_size: this.size,
+                fsentry_name: this.name,
+                path: this.path,
+                uid: this.uid,
+                // /sign outputs another property called "type", but we don't
+                // have that information here, so it's omitted.
+            })
+        });
     }
-
+    
     write = async function(data){
         return puter.fs.write( 
             this.path,

src/puter-js/src/modules/FileSystem/index.js

@@ -15,6 +15,7 @@ import symlink from './operations/symlink.js';
 // a reserved keyword in javascript
 import deleteFSEntry from "./operations/deleteFSEntry.js";
 import { AdvancedBase } from '../../../../putility/index.js';
+import FSItem from '../FSItem.js';
 
 export class PuterJSFileSystemModule extends AdvancedBase {
 
@@ -31,6 +32,8 @@ export class PuterJSFileSystemModule extends AdvancedBase {
     write = write;
     sign = sign;
     symlink = symlink;
+    
+    FSItem = FSItem
 
     static NARI_METHODS = {
         stat: {

src/puter-js/src/modules/UI.js

@@ -1072,9 +1072,18 @@ class UI extends EventListener {
     }
 
     // Returns a Promise<AppConnection>
-    launchApp = async function launchApp(app_name, args, callback) {
+    /**
+     * launchApp opens the specified app in Puter with the specified argumets.
+     * @param {*} nameOrOptions - name of the app as a string, or an options object
+     * @param {*} args - named parameters that will be passed to the app as arguments
+     * @param {*} callback - in case you don't want to use `await` or `.then()`
+     * @returns 
+     */
+    launchApp = async function launchApp(nameOrOptions, args, callback) {
         let pseudonym = undefined;
         let file_paths = undefined;
+        let items = undefined;
+        let app_name = nameOrOptions; // becomes string after branch below
 
         // Handle case where app_name is an options object
         if (typeof app_name === 'object' && app_name !== null) {
@@ -1084,17 +1093,31 @@ class UI extends EventListener {
             args = args || options.args;
             callback = callback || options.callback;
             pseudonym = options.pseudonym;
+            items = options.items;
+        }
+        
+        if ( items ) {
+            if ( ! Array.isArray(items) ) items = [];
+            for ( let i=0 ; i < items.length ; i++ ) {
+                if ( items[i] instanceof FSItem ) {
+                    items[i] = items[i]._internalProperties.file_signature;
+                }
+            }
         }
 
         if ( app_name && app_name.includes('#(as)') ) {
             [app_name, pseudonym] = app_name.split('#(as)');
         }
+        
+        if ( ! app_name ) app_name = puter.appName;
+        
         const app_info = await this.#ipc_stub({
             method: 'launchApp',
             callback,
             parameters: {
                 app_name,
                 file_paths,
+                items,
                 pseudonym,
                 args,
             },