IF Commons GitHub

Native-pinned install

0002Active

0002-native-pinned-install · owner if · domain commons

Requirements

FR-001checkpassing

The bytes of an artifact MUST be checked against the SHA-256 of its pin before anything is unpacked, and a download whose SHA-256 differs MUST be refused with both hashes named and no file returned.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/install.test.ts: the hash is checked before anything is unpacked

Proved by: archon-dialect-native-pinned/suite/install.test.ts

Written in: archon-dialect-native-pinned/src/install.ts

Tests: passed: suite/install.test.ts the bytes are checked against the pinned SHA-256 before anything is unpacked, and a mismat

FR-002checkpassing

An artifact MUST be unpacked in memory by its format: zip, tar (plain, or compressed with gzip or xz, found by its first bytes) or file (the bytes are the program, named by the program's name, with .exe added for Windows); every path in it MUST be a path inside the folder (never absolute, never with ..), and an archive with a path that is not MUST be refused whole.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/install.test.ts: zip, tar and gzipped tar give the same files and an unsafe path, a path twice and a link refuse the archive

Proved by: archon-dialect-native-pinned/suite/install.test.ts

Written in: archon-dialect-native-pinned/src/install.ts

Tests: passed: suite/install.test.ts a zip, a tar and a gzipped tar give the same files, a file is the program, and an unsafe p

FR-003checkpassing

The program MUST be in the unpacked files, at the folder of the pin (binPath) with the program's name (and .exe on Windows), and an artifact that does not hold it MUST be refused naming the path.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/install.test.ts: the program must be in the unpacked files

Proved by: archon-dialect-native-pinned/suite/install.test.ts

Written in: archon-dialect-native-pinned/src/install.ts

Tests: passed: suite/install.test.ts the program must be in the unpacked files, at its folder and with its name

FR-004checkpassing

The install record MUST name the tool, the version, the platform, the address, the SHA-256 of the artifact, the path of the program, the SHA-256 of each file by its path and the target of each symbolic link by its path, MUST be written as JSON with its keys in order, two spaces, and a final line break, and MUST be read back, a text that is not a record being refused with the reason.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/install.test.ts: the install record is written and read back

Proved by: archon-dialect-native-pinned/suite/install.test.ts

Written in: archon-dialect-native-pinned/src/install.ts

Tests: passed: suite/install.test.ts the install record names the tool and the pin, holds the hash of each file, is written in

FR-005checkpassing

installDrift MUST find, by comparing the files found in a tool's folder with its record, every file or symbolic link changed, missing or extra, in the order of the paths, and MUST say where the record's artifact is not the one the pin now names.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/install.test.ts: drift finds every change

Proved by: archon-dialect-native-pinned/suite/install.test.ts

Written in: archon-dialect-native-pinned/src/install.ts

Tests: passed: suite/install.test.ts drift finds every file changed, missing or extra, in the order of the paths, and a pin tha

FR-006checkpassing

A shim MUST be a POSIX sh script that runs the installed program with its arguments, or on Windows a .cmd file; a command name that is not letters, digits, dots, underscores and hyphens, a path with a line break, and on Windows a path with ", %, ^, &, |, < or > MUST be refused.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/install.test.ts: shims and what is refused

Proved by: archon-dialect-native-pinned/suite/install.test.ts

Written in: archon-dialect-native-pinned/src/install.ts

Tests: passed: suite/install.test.ts a shim is a POSIX script or a .cmd file, and an unsafe command or path is refused

FR-007checkpassing

A symbolic link in an archive MUST be kept only where its target is a relative path that stays inside the folder the archive is unpacked into (never absolute, never with a backslash or a drive letter, never above the root of the folder), is a file or a folder the archive holds, or another link whose own target is such (a chain of any depth that does not come back to a link it has passed), is not the folder the link is in or one above it, and passes through no link on the way (no folder of the target's path is a link); no file, folder or link MUST be written below a link, and a link MUST NOT have the path of a file, a folder or another link; an archive with a link that fails any of these MUST be refused whole, with the path of the link and one reason from a closed list, and nothing written.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/links.test.ts: a Node release and a Temurin JRE unpack with their links, and each way a link cannot be trusted is refused with its reason

Proved by: archon-dialect-native-pinned/suite/links.test.ts

Written in: archon-dialect-native-pinned/src/install.ts, archon-dialect-native-pinned/src/links.ts

Tests: passed: suite/links.test.ts a Node release, xz-compressed, and a Temurin JRE, gzipped, unpack with their links: files,; passed: suite/links.test.ts a link may name a folder, a file below another folder, or reach up and down inside the fol; passed: suite/links.test.ts a link may name another link, to any depth, where the chain ends at something the archive ; passed: suite/links.test.ts each way a link cannot be trusted refuses the whole archive with the path of the link and ; passed: suite/links.test.ts every refusal is a sentence that names the path of the link, says why and says that nothin

Cited by: Archon dialect: native-pinned, links

FR-008checkpassing

A hard link in an archive MUST be a copy of the file it names, which the archive holds before it; the unpacking MUST give the paths of the files the archive marks as executable (any execute bit of their mode), and where the system cannot make symbolic links (Windows) a link to a file MUST be a copy of the file and a link to a folder MUST be refused.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/links.test.ts: hard links are copies, execute bits are given, links are copies where the system has none

Proved by: archon-dialect-native-pinned/suite/links.test.ts

Written in: archon-dialect-native-pinned/src/install.ts, archon-dialect-native-pinned/src/links.ts

Tests: passed: suite/links.test.ts a hard link is a copy of the file it names, executable where either is, and a file below n; passed: suite/links.test.ts where the system cannot make links a link to a file is a copy of the file and a link to a

Cited by: Archon dialect: native-pinned, links

Acceptance scenarios

  1. Given bytes that are not the pinned bytes, When they are unpacked, Then nothing is returned and the error names both hashes, per FR-001.
  2. Given a tar with an entry ../evil, When it is unpacked, Then the whole archive is refused, per FR-002.
  3. Given a zip, a tar and a gzipped tar of the same files, When each is unpacked, Then the files are the same, per FR-002.
  4. Given a Node release as a .tar.xz and a Temurin JRE as a .tar.gz, each with relative links inside its folder, When each is unpacked, Then the files and the links come back, and a link to an absolute path, above the folder, to nothing or through another link refuses the archive whole, per FR-007.
  5. Given an artifact without the program, When it is unpacked, Then it is refused naming the path it should have, per FR-003.
  6. Given an installed folder with one file changed, one removed and one added, When it is compared with its record, Then each is found, per FR-005.
  7. Given the command bun and the path /home/a/b, When the shim is made for Linux and for Windows, Then each is the right text, per FR-006.

Out of scope

Edge cases

  • An artifact that is a single file for the root folder: the program is the file, per FR-002.
  • A zip with a directory entry: ignored, never a file, per FR-002.
  • Two entries with one path in an archive: refused, per FR-002.

Assumptions

  • The SHA-256 of an artifact is the one a person put in the packaging ontology from the publisher's own checksum.

Open questions

  • None.

Key entities

  • Download - what a pin gives for a platform (commons toolchain).
  • InstallRecord - what an install leaves beside the files.

Success criteria

SC-001success criterion

No byte of an artifact is unpacked before its hash is checked.

SC-002success criterion

A change to an installed file is always found.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

Archon dialect: native-pinned, links, Native-pinned store, Native-pinned pin tool

Titles, headings, exports, tables, columns and requirements. Esc closes.