Dyphal, the Dynamic Photo Album

Dyphal is a web photo album designed to allow photographers to show off their work without needing to turn to commercial providers that inject advertising and may do ethically dubious things with the photos and information that they host.

An album is displayed as a list of photos; each photo can be opened to show a larger view with metadata. The photo’s size scales to best fit the browser window. An album can be navigated by mouse, touch, or keyboard.

An album can be hosted on any web document server; no server-side scripts or databases are required. All necessary files are generated from original photographs and their metadata up front and stored on the server. The album and its metadata files are designed to require minimal storage space and minimal network traffic.

There is a demo album at https://ciphertext.info/software/dyphal/#/demo.

Design principles

Dyphal was designed to satisfy the following goals:

1. The photo is central. It must be the most prominent element of the page. It must be entirely visible within the browser window; scrolling is not allowed. Do not up-scale the photo beyond its actual size. Do down-scale the photo to fit the browser window if necessary.
2. Metadata is important. Information about what is in a photo, where and when it was taken, and photographic properties such as exposure and aperture must be visible for each photo.
3. The album must not break the web. Browsers’ Forward and Back buttons must work. Bookmarks and saved links to photos and albums must work. The URI in the address bar must represent the current album or photo.
4. The album must work using a document server as the back end.
5. The album must be as small as possible with as many elements as possible shared between pages.
   
6. The album must use modern web standards with a minimum of cruft to support old browsers. It must follow security best practices and support CSP.
7. All features of the album must work properly on recent versions of Chrome and Firefox. There should be no major problems in minor browsers such as Opera or Edge.
   
8. All content must be in HTML or be inserted at run-time. All styling must be in CSS or inserted at run-time.
9. Album styles should be changeable without needing to change scripts.

Generating Dyphal albums

Dyphal albums are created using DyphalGenerator:

1. Use the Add Photos button to import photo files or gThumb 3 catalogs. Photos can be re-ordered by dragging.
2. Choose the caption and property fields to display for each photo. The fields available depend on what metadata tags are stored in the selected photos. By default, only the fields available in all selected photos are listed; check the Show all box to list all fields that are available in any selected photo. Fields can be re-ordered by dragging.
3. Set a title, description and footer for the album. The title and footer will appear on photo pages as well as the album page. No HTML markup is allowed.
4. Choose the size for photos in the album. Larger sizes will show more detail, but require more space and time to load.
5. Use the Generate Album button to save the album and generate the down-scaled photos, thumbnails, and metadata files that it requires.
6. If you haven’t already done so, use the Install Album Template button to install the Dyphal web template into the album directory.

If you generated the album “Vacation” in a directory served as http://example.com/photos and installed the web template to the same directory, you can view the album at http://example.com/photos/#/Vacation.

To edit an album in DyphalGenerator, open the “.dyphal” file for the album.

DyphalGenerator does not currently have a metadata editor. Instead, it pulls metadata fields from embedded photo tags. The following tags are recognized as “properties” (using exiftool’s naming scheme):

• Composite:Aperture
• Composite:DigitalZoom
• Composite:DriveMode
• Composite:FlashType
• Composite:FOV
• Composite:FocalLength35efl
• Composite:HyperfocalDistance
• Composite:ImageSize
• Composite:Lens35efl
• Composite:LensID
• Composite:LightValue
• Composite:ScaleFactor35efl
• Composite:ShootingMode
• Composite:ShutterSpeed
• EXIF:DateTimeOriginal
• EXIF:ExposureCompensation
• EXIF:ExposureMode
• EXIF:Flash
• EXIF:FocalLength
• EXIF:ISO
• EXIF:Make
• EXIF:Model
• EXIF:Orientation
• File:FileSize
• File:FileType
• MakerNotes:MacroMode
• MakerNotes:Rotation

Only three fields are recognized as “captions”: Description, Location, and Date. They are synthesized from various tags that are commonly used to store such information (again, using exiftool’s naming scheme):

• Description
  • XMP:Description
  • IPTC:Caption-Abstract
  • EXIF:UserComment
• Location
  • XMP:Location
  • IPTC:ContentLocationName
• Date:
  • XMP:DateTimeOriginal
  • Composite:DateTimeCreated
  • EXIF:DateTimeOriginal

Recent versions of gThumb use these fields for metadata; there are probably other photo managers that do as well. Older versions of gThumb stored metadata only in external XML files; the tool “gthumb-comment-update” can be used to import metadata from the XML files into embedded tags.

Serving Dyphal albums

Nothing special is required to serve Dyphal albums, just a basic web document server such as Apache or lighttpd. For improved security, server operators are encouraged to serve Dyphal albums over HTTPS with the following headers:

• Content-Security-Policy: default-src 'none'; script-src 'self'; style-src 'self'; img-src 'self'; connect-src 'self';
• X-Frame-Options: DENY
• Strict-Transport-Security: max-age=31536000

Since Dyphal uses asynchronous queries, it won’t work from file:// URIs.

The “.dyphal” files created by DyphalGeneraor should not be served with the web page. These files are intended to allow DyphalGenerator to re-open and edit albums.

Technical details

An album is represented by a single web page, index.html. JavaScript running within that page determines what to display based on hash parameters. The first parameter, which must always be present, identifies the album. This value is the name of the JSON file that describes the album with the “.json” suffix omitted. If your directory structure looks like this:

    album.css
    common.css
    dyphal.js
    index.html
    photo.css
    vacation.json
    photos/photo1.jpeg
    metadata/photo1.jpeg.json
    ...

then the path to load the “vacation” album is

    /#/vacation

This will load album view, which shows the title and description of the album as a whole alongside thumbnails for every photo in the album. Clicking on any one of the thumbnails will open photo view for that photo, containing a larger view of the selected photo and its metadata, along with controls to move to the previous or next photos in the album, or to return to album view. The photo will re-scale to the largest size that fits in your browser window without hiding the header, footer, or metadata or going beyond its physical dimensions. If the photo is not shown at its full size, clicking on it will open overlay view to show the photo at the largest size that can fit in the window, potentially hiding the header, footer, and metadata. There is also a help view that can be opened from either album or photo view using the question mark icon.

When loaded in a window smaller than 750 CSS-pixels wide or tall, the album will use compact layout that omits the metadata and footer from photo view in order to show the photo at the largest size possible. In compact layout, overlay view shows the metadata and footer rather than another view of the photo. The album is also displayed full-screen in browsers that support this feature if the display is less than 750 CSS-pixels wide or tall (though, for technical reasons, the user needs to interact with the page before it can enter full-screen mode).

Each photo view has its own URI, consisting of the URI to the album followed by the index number of the photo (indices start from 1). For example, the path for the third photo in the “Vacation” album might be

    /#/vacation/3

The photo and help overlays do not have independent URIs.

Since only one HTML document is used for all views, its differences in appearance are implemented by switching styles and, to a lesser extent, by adding and removing document elements. Photos, thumbnails, and photo metadata are not stored in the HTML; they are loaded from JSON files and their contents are inserted or removed from the document when appropriate. The album JSON file (vacation.json in the above example) contains a title, footer, and description of the album, plus a list of the photos in the album. Each photo has its own JSON file (the photo’s name from the album JSON with “.json” appended), containing the name of the photo file, its dimensions, and its metadata. JSON files, thumbnails, and photos are loaded on demand; the JSON and photo for the next photo in the album are pre-cached to reduce load time.

Appending “/debug” to any album or photo URI will load it in debug mode, which suppresses some of the styling, outlines various document elements in various colours, and logs some information to the browser console.

Everything is implemented in as standards-conformant a manner as possible.
Browser-specific logic is implemented using feature detection rather than browser detection where possible; browser detection is only used to work around the buggy touch tracking in Android browsers and the broken scrolling in full-screen Internet Explorer because no ways to fix these issues using feature detection could be found.

If my JavaScript has idiosyncrasies, it’s probably because I’m a C++ programmer who learned JavaScript by trial and error.

History

The original version of Dyphal was the BestFit template for gThumb, which I wrote in 2005 and became part of gThumb starting with version 2.9.1 in 2006. That template was designed to take scale the photo to fit in the browser window and show metadata around its edges; superficially, it looked a lot like this album. However, it was limited by the hacks required to support Internet Explorer 6 and albums built from that template consisted of a large number of repetitive generated HTML files.

At some point after 2008, gThumb removed the BestFit template without telling its author (i.e., me) why. Since working with the gThumb maintainer in the past had been a pain, I opted to not try to get it reinstated. Instead, I dropped support for IE6 (simplifying the code considerably) and started work on a version where photos and metadata would be inserted into a single page at run-time using JavaScript. I eventually merged the album and photo pages, accidentally re-invented JSON before learning how to use JSON properly, and ended up with this.

The main disadvantage of the new album over the old gThumb-generated one is that I can no longer rely on gThumb to select the photos to include, create down-sized versions of them, and extract their metadata. Instead, I wrote my own tool, DyphalGenerator. gThumb, despite a couple annoying mis-features, still has the best support for photo metadata of any Linux photo manager that I could find, so DyphalGenerator pulls metadata from the places where gThumb stores it and pulls lists of photos from gThumb collections.

Security Model

DyphalGenerator, which generates the server-side data, fills the role of a server component. It is trusted, as are the shell commands that it invokes. The image files loaded by DyphalGenerator are not trusted and are assumed to contain arbitrary malicious content. The JSON files emitted by DyphalGenerator are partially trusted. The following fields are safe to insert into URIs with no additional encoding:

• metadataDir
• thumbnail
• path
• name
• photo

The following fields are restricted to hard-coded values:

• orientation
• albumVersion
• captionFields
• propertyFields
• photoResolution
• the first element of each properties tuple

All other values should be assumed to be attacker-controlled.

To be secure, DyphalGenerator must never emit photo URIs outside of the album directory and albums must never execute any scripts or interpret any markup found in properties, captions, or other fields. Additionally, albums must never load JSON files or images from outside of the album directory.

See javascript.html for information about Dyphal’s use of JavaScript.

The “.dyphal” files created by DyphalGenerator contain local paths and should not be served with the web page.

Why am I so concerned about TOCTOU in DyphalGenerator when there’s no privilege separation to be attacked? Practice.

Licence

Dyphal is copyright (c) Rennie deGraaf, 2005-2023. It is distributed under the terms of the GNU General Public Licence, either version 2 or (at your option) version 3. See LICENCE or http://www.gnu.org/licenses/ for details.

Contact information

Rennie deGraaf (rennie-dot-degraaf-at-gmail-dot-com)

The latest version of Dyphal, including full source code, can be obtained at https://ciphertext.info/software/dyphal/.

Version 3.0-beta2-22-g3c52816-dirty, 2023-04-16