IF Commons GitHub

Native-pinned pin tool

0005Active

0005-native-pinned-pin · owner if · domain commons

Requirements

FR-001checkpassing

A request MUST be refused unless it names a program in lower case words, a version, a program file and at least one platform, and every address in it (an artifact or a checksum file) MUST be https with no credentials; a refusal MUST say which part is wrong.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/pin.test.ts

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

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

Tests: passed: suite/pin.test.ts a request is refused unless it is well formed and every address is https with no credentia

FR-002checkpassing

For each platform the tool MUST fetch the artifact and take its SHA-256 itself; a hash it was not asked to check MUST never be copied from the request or from a publisher's file as if it were its own.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/pin.test.ts

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

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

Tests: passed: suite/pin.test.ts the hash is taken by the tool, and the line of the artifact in a checksum file of many is

FR-003checkpassing

Where the request names the publisher's checksum, the tool MUST compare it with the hash it took and say verified, mismatch (with both hashes), absent (none named) or unreadable (the file or the line could not be read); a checksum file lists many artifacts and the line of the one named MUST be the one taken.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/pin.test.ts

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

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

Tests: passed: suite/pin.test.ts the hash is taken by the tool, and the line of the artifact in a checksum file of many is ; passed: suite/pin.test.ts a mismatch, a file with no line for the artifact and no checksum named each make the propo

FR-004checkpassing

For each platform the tool MUST prove the artifact unpacks by the rules of an install (0002-native-pinned-install) with the program at the folder named, and report why not where it does not; a platform that could not be fetched MUST say so and MUST NOT stop the other platforms.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/pin.test.ts

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

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

Tests: passed: suite/pin.test.ts an artifact without its program says why, and a platform that cannot be fetched leaves the

FR-005checkpassing

The proposal MUST be ready only where every platform is verified by the publisher and has its program; it MUST list for each platform every concern a reviewer should know (no checksum named, a mismatch, a program missing); it MUST say it is a proposal and MUST hold no secret; and its text MUST be the same for the same request whatever the order the platforms were written in.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/pin.test.ts

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

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

Tests: passed: suite/pin.test.ts a mismatch, a file with no line for the artifact and no checksum named each make the propo; passed: suite/pin.test.ts the proposal says it is a proposal, holds no pin, and has the same text whatever the order

FR-006checkpassing

The program pin REQUEST [--out FILE] MUST write the proposal to the file or print it, MUST change no pin and no store, and MUST end with status 0 where the proposal is ready, 2 where it is not, 1 where the request could not be read and 64 on a wrong use.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/pin.test.ts

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

Tests: passed: suite/pin.test.ts the program writes only the proposal: status 0 where ready, 2 where not, 1 for an unreadab

Acceptance scenarios

  1. Given a request with an http address, When it is read, Then it is refused naming the platform, per FR-001.
  2. Given an artifact and a checksum file that lists it among others, When a pin is proposed, Then the hash is the one the tool took, the publisher's line is the one of the artifact and the platform is verified, per FR-002 and FR-003.
  3. Given a publisher's checksum that differs, When a pin is proposed, Then the platform is mismatch with both hashes and the proposal is not ready, per FR-003 and FR-005.
  4. Given no checksum named, When a pin is proposed, Then the platform is absent with the concern that this hash is the first seen, per FR-003 and FR-005.
  5. Given an artifact that has no program where it is said to be, When a pin is proposed, Then the platform says why and the proposal is not ready, per FR-004.
  6. Given one platform that cannot be fetched, When a pin is proposed, Then the other platforms are still proposed, per FR-004.
  7. Given a request, When pin runs, Then the status is 0 where ready and 2 where not, and nothing but the proposal file is written, per FR-006.

Out of scope

  • Writing a pin into the ontology and reviewing it: the ontology and its owner.
  • Verifying a signature of a publisher (cosign, minisign, GPG): a later version; the proposal says publisher is by checksum.

Edge cases

  • A checksum file of one hash and no name: that hash is taken, per FR-003.
  • A name that appears with a path in the checksum file (dist/bun.zip): its last word is compared, per FR-003.

Assumptions

  • A publisher's checksum file is served from the same account as the artifact, so verified shows the download was not damaged, not that the publisher is honest; the reviewer decides that.

Open questions

  • None.

Key entities

  • Request - what a publisher gives for a version of a program.
  • Proposal - what the tool found, for a person to review.

Success criteria

SC-001success criterion

A pin that is proposed was fetched, hashed and unpacked by the tool, never copied.

SC-002success criterion

The tool cannot change a pin or a store.

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

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