User:Homunq/Activity bundles v2

Signatures

An activity bundle consists of a file whose nominal extension is .xo, but whose real structure corresponds to .zip, OR .tgz (interchangeable). The difference between these two structures is auto-detected.

Zip is for backward compatibility, .tgz is a better format for differential version control because, while it is compressed for sending over a network connection, it is also easily expanded to a form that is friendly to binary diffs.

The internal structure looks something like the following:

Helloworld.activity/
    MANIFEST
    TRANSLATABLES
    HASHES
    helloworld.py
    locale/
        de_DE/
            activity.linfo
        zh_CN/
            activity.linfo
    activity/
        activity.info
    icons/
        helloworld.svg
    SIGNATURES/
        activity.key
        VALIDKEYS/
            key1.key
            key1.key.sig
            fulanoskey
            fulanoskey.sig
        GENSIGS/
            fulano.sig
        TRANSSIGS/
            chinese_hashes
            chinese_hashes.mengano.sig
            zh_de_hashes
            zh_de_hashes..sig
            zh_de_hashes.....sig

All special files are assumed to be in UTF-8. All linefeeds are unix-style.

1. MANIFEST
   1. Mandatory
   2. list of realative paths of all files and directories (with trailing dash) in bundle, except:
      1. non-empty directories (only empty directories should be in MANIFEST)
      2. MANIFEST
      3. TRANSLATABLES
      4. HASHES
      5. any files in SIGNATURES
      6. any files matched by a pattern in TRANSLATABLES (see below)
   3. Ends with a newline
   4. Order is significant, and should be maintained
      1. When renaming a file, the renamed file should appear on the same line
      2. When deleting a file, leaving a blank line is OPTIONAL and ENCOURAGED. Blank lines are DISCOURAGED but ALLOWED in other cases.
   5. Other whitespace not part of file names is NOT ALLOWED

maintaining order makes merges, diffs, and import to source control tools easier

For the example above, MANIFEST would be exactly:

helloworld.py
icons/helloworld.svg

1. TRANSLATABLES
   1. optional file
   2. uses the same format as .gitignore
   3. indicates what files from MANIFEST should *not* be included in HASHES

Obviously, this does introduce a security risk, as an unsigned TRANSLATABLES file could theoretically cause a buffer overflow (or, indeed, be deliberately run by malicious signed code). The first case is considered avoidable with good tools, and the second is considered to be no additional risk (malicious code is malicious code)

L10n should not require bugging the original activity author - imagine having to sign multiple versions of dozens of languages for every activity version, besides the inconvenience it is a security risk because the underlying code could change between "pure-l10n" versions without the author realizing.

1. HASHES
   1. auto-generated file
   2. first line '#HASH-VERSION: 1.0; HASH-FUNCTION:sha256'.
   3. No additional whitespace
   4. The further lines of HASHES alternate
      1. one line with a path as in MANIFEST
      2. the sha1sum hash of the binary contents of the file on the line which follows.
   5. There is no limit to line length.
   6. order:
      1. [The first two lines are TRANSLATABLES and its hash, if it exists]
      2. The rest of HASHES follows MANIFEST, in the same order, excluding blank lines or any lines that match patterns in TRANSLATABLES.

1. SIGNATURES/
   1. optional directory
2. Contents
   1. activity.key
      1. public DSA key, as generated by ssh
   2. VALIDKEYS/
      1. contains pairs of files
         1. a public key, filename does not end in ".sig"
         2. a separate signature, format specified below, of that file. filename is the same with ".sig" appended.
            1. meaningful metadata:
               1. "requiredmetadata":{JSON object}. At least one key:value pair from the requiredmetadata must be in the metadata object of signatures using this key.
            2. all signatures here should be verifiable with activity.key
               1. invalid signatures are deleted on installation
   3. GENSIGS/
      1. Signatures of HASHES
         1. iff any of these are verifiable with a key from VALIDKEYS, the bundle is considered to be "signed"
         2. additional signatures are allowed, and may be respected if recognized by Sugar. (ie, a control panel for "valid global activity signers"
         3. meaningful metadata:
            1. "status":
               1. "favorite" means signor claims that this activity should be favoritted. Equivalent to "latest" unless this signature recognized by sugar.
               2. "latest" means signor claims that this version supercedes previous versions.
               3. "development" means signor claims that this version does NOT supercede previous versions
               4. any other status attribute, or none, is interpreted as "development"
            2. anything from requiredmetadata of signing key.
   4. TRANSSIGS/
      1. signatures of translation files
      2. hashes
         1. same format as HASHES, contain any subset of files which match TRANSLATABLES
         2. may contain files not in (purged for space from) bundle, as long as at least 1 of the files is still present
      3. sigs
         1. signatures on hashes
         2. any signer - this information to be used by sugar.