How it works: Bundles

What are bundles?

Securepub bundles are zip files ↗︎ which hold the content reviewed in the engagement. Bundles may contain any kind of data supported by a browser.

How are they used?

When members review a topic associated with a bundle, Securepub downloads the corresponding files into the browser's cache and serves them with a Service Worker ↗︎. Securepub navigates to the URL specified by the topic after the content is loaded and the browser presents it to the user.

Who can access bundles?

The host may access all the bundles in an engagement. As the host they can

• list all bundles
• view and modify bundle settings
• view bundle metadata
• review bundle content

Hosts are not subject to bundle sharing restrictions but other members may only access the bundles the host has shared with them. Members other than the host can

• list all bundles shared with them
• view metadata of all bundles shared with them
• review the content of unrestricted bundles shared with them

Members who have accepted their invitation can also

• review the content of restricted bundles shared with them

What are restricted and unrestricted bundles?

Unrestricted bundles are bundles whose contents are visible to members before they've accepted their invitation. Restricted bundles are bundles whose contents are only visible to members who have accepted their invitations by securing their invitation link and agreeing to the terms of the engagement. The host specifies whether or not a bundle is restricted or unrestricted when they add it to the engagement.

Although members who have not accepted their invitations cannot view the contents of restricted bundles, they may nonetheless examine the metadata of such bundles. This allows members to get a better sense of what's offered to them before agreeing to any terms.

What is bundle metadata?

Bundle metadata consists of the names, approximate sizes and content types of the files within the bundle's zip file. For example the root directory of a bundle could have the following metadata:

How do Securepub URLs work?

Bundle content served by the service worker appears to the user as if it was served by a subdomain of securepub.org. For example with default settings a bundle containing a file such as document.html will be served by gl2401s.securepub.org with the URL https://gl2401s.securepub.org/document.html

By convention review content is served from Securepub domains with names ending in 's' e.g.

https://gl2401s.securepub.org
              ━

Securepub and the service worker reserve URLs with the following prefixes for the Securepub application and documentation:

   /_v1.2401_/
/XX/_v1.2401_/

where XX represents a two character ISO 639-1 ↗︎ language code. Securepub bundles should not use URLs with these prefixes.

Apart from this URL restriction Securepub places no limits on a bundle's contents other than what the browser enforces. Bundle contents may be as simple as a single file or folder or as complex as an entire website or application.

   /_vN.YYVV_/
/XX/_vN.YYVV_/

What are bundle settings?

Bundle settings allow the host to fine-tune the following details about how a bundle's content is served:

• where files are mounted in the engagement site
• the start folder in the bundle holding files to serve
• whether or not files such as "index.html" should be served for directories
• logic to ignore certain files in the zip and not serve them
• logic to override the default mime type of served files

The host specifies these using a javascript object. The default settings are:

{
  mount: "/",             // zip contents mounted here
  start: "/",             // serve url paths below this directory
  dirindex: "index.html", // if not blank, serve this file for directories
 
  ignore(path)            // true if path should be excluded
  {
    return path.endsWith(".DS_Store");
  },

  mimetype(path, dflt)    // serve mimetype for path
  {     
    if (dflt === "") dflt = "text/plain";
    return dflt;
  }
}

When would it make sense to change these settings?

mount

The mount setting is useful when serving content from multiple bundles.

For example when preparing an engagement to serve two bundles containing "Q1" and "Q2" quarterly reports each with an index.html file from gl2401s.securepub.org it could make sense to use mount settings such as

start

Content generation tools often place generated content in a special folder with a name like 'public' or 'site' which is not expected to be part of the published URL. Securepub bundle settings makes it easy to work with such tools. For example changing the start setting to

start: "public",

makes it easy to serve to serve a file in the zip such as

public/document.html

as if it had the path

document.html

dirindex

Content generation tools often generate links to directories assuming a web server will serve a link to a directory like /somefolder the same way it would serve /somefolder/index.html so the default Securepub bundle settings specify

dirindex: "index.html",

Since this "directory indexing" behavior can interfere with some applications, the host can disable it by setting dirindex to an empty string:

dirindex: "",

ignore

The ignore setting specifies a function that decides whether or not a particular path in the bundle should be ignored. It can be used to instruct Securepub not to serve undesired files which accidentally find their way into the bundle.

For example browsing a directory on OSX may create unwanted .DS_Store files which can end up in bundles created by the zip command. To prevent these files from being served the default Securepub bundle settings specify

ignore(path)            // true if path should be excluded
{
  return path.endsWith(".DS_Store");
},

mimetype

Securepub uses the mime ↗︎ package to select the default mime type to use when serving a file. The mimetype setting allows the host to specify a function to override the type that would have been used when serving a particular path. The default Securepub bundle settings provides a function which uses the type text/plain if the mime package fails to identify a type:

mimetype(path, dflt)    // serve mimetype for path
{     
  if (dflt === "") dflt = "text/plain";
  return dflt;
}

What if the host specifies invalid settings?

Securepub provides a javascript playground editor to help the host avoid simple syntactic errors. If there are any javascript syntax errors the editor will ask the host to correct them.

Securepub also provides apply and reset options to help the host check their settings. The apply option reports semantic errors it finds when building bundle metadata with the settings and asks the host to correct them. If the host gets stuck the reset option allows them to revert their changes to the defaults.

More details

export interface Settings
{
  mount:        string;
  start:        string;
  dirindex:     string;

  ignore:       (path: string)                  => boolean;
  mimetype:     (path: string, dflt: string)    => string;
};