@push.rocks/smartlinuxrepo 0.0.0-stage → 1.0.0

package/dist_ts/writers/gotar.js

@@ -0,0 +1,218 @@
+import { concatBytes } from '../readers/bytes.js';
+import { LinuxRepoError } from '../shared/errors.js';
+import { goPathJoin } from '../shared/gopath.js';
+const BLOCK = 512;
+const NAME_SIZE = 100;
+const PREFIX_SIZE = 155;
+/** Go `maxSpecialFileSize`: the largest PAX record block Go writes or reads. */
+const MAX_SPECIAL_FILE_SIZE = 1 << 20;
+/** Go `fitsInOctal(8, x)` for the mode field: below 8^7. */
+const MODE_LIMIT = 8 ** 7;
+/** Go `fitsInOctal(12, x)` for the size field: below 8^11 (8 GiB). */
+const SIZE_LIMIT = 8 ** 11;
+const encoder = new TextEncoder();
+/**
+ * The subset of Go 1.27 `archive/tar` `Writer` that Gitea 28.2.0 uses for its
+ * index archives (Arch `services/packages/arch/repository.go:381-399`, Alpine
+ * `services/packages/alpine/repository.go:331-351`): regular files from
+ * `tar.Header{Name, Mode, Size}` with every other field zero, so the zero
+ * `ModTime` is written as 0, uid and gid are 0 and user and group names are
+ * empty.
+ *
+ * Format choice follows Go's `allowedFormats` and `WriteHeader`: USTAR when the
+ * name is ASCII and at most 100 bytes, USTAR with a prefix split when the name
+ * splits, else PAX with one `path` record (refused when the records exceed
+ * Go's 1 MiB `maxSpecialFileSize`, as Go returns `ErrFieldTooLong`).
+ *
+ * Refused with `invalid-input` where Go would not write a regular file in USTAR
+ * or PAX-`path` form:
+ * - a name with NUL (Go fails with an invalid PAX record) or ending with `/`
+ *   (Go refuses it for a regular file; Gitea's untyped header would become a
+ *   directory entry instead);
+ * - a mode outside 7 octal digits (Go falls back to the GNU format);
+ * - a size of 8 GiB or more (Go adds a PAX `size` record; the codec does not);
+ * - a string that is not well-formed UTF-16 (Go strings never carry one).
+ */
+export function writeGoTar(filesArg, optionsArg = { endOfArchive: true }) {
+    const parts = [];
+    for (const file of filesArg) {
+        parts.push(goTarHeader(file.name, file.mode, file.data.length), file.data, new Uint8Array(padding(file.data.length)));
+    }
+    if (optionsArg.endOfArchive) {
+        parts.push(new Uint8Array(BLOCK * 2));
+    }
+    return concatBytes(parts);
+}
+/**
+ * The bytes Go `Writer.WriteHeader` writes for a regular file: the main
+ * header block, preceded by a PAX `x` header and its padded records when the
+ * name needs one.
+ */
+export function goTarHeader(nameArg, modeArg, sizeArg) {
+    if (!nameArg.isWellFormed()) {
+        throw new LinuxRepoError('invalid-input', 'a tar entry name is not well-formed UTF-16', { field: 'name' });
+    }
+    if (nameArg.includes('\0')) {
+        throw new LinuxRepoError('invalid-input', 'a tar entry name contains NUL', { field: 'name' });
+    }
+    if (nameArg.endsWith('/')) {
+        throw new LinuxRepoError('invalid-input', 'a regular tar entry name ends with /', { field: 'name' });
+    }
+    if (!Number.isSafeInteger(modeArg) || modeArg < 0 || modeArg >= MODE_LIMIT) {
+        throw new LinuxRepoError('invalid-input', 'a tar entry mode does not fit the USTAR mode field', {
+            field: 'mode',
+        });
+    }
+    if (!Number.isSafeInteger(sizeArg) || sizeArg < 0 || sizeArg >= SIZE_LIMIT) {
+        throw new LinuxRepoError('invalid-input', 'a tar entry size does not fit the USTAR size field', {
+            field: 'size',
+        });
+    }
+    const nameBytes = encoder.encode(nameArg);
+    if (isAscii(nameBytes) && nameBytes.length <= NAME_SIZE) {
+        return header({ name: nameBytes, prefix: null, size: sizeArg, mode: modeArg, typeflag: '0' });
+    }
+    const split = splitUstarPath(nameBytes);
+    if (split !== null) {
+        return header({ name: split.name, prefix: split.prefix, size: sizeArg, mode: modeArg, typeflag: '0' });
+    }
+    return paxHeader(nameArg, modeArg, sizeArg);
+}
+/** Go `splitUSTARPath` (`archive/tar/writer.go:454`). */
+function splitUstarPath(nameArg) {
+    let length = nameArg.length;
+    if (length <= NAME_SIZE || !isAscii(nameArg)) {
+        return null;
+    }
+    else if (length > PREFIX_SIZE + 1) {
+        length = PREFIX_SIZE + 1;
+    }
+    else if (nameArg[length - 1] === 0x2f) {
+        length--;
+    }
+    const i = nameArg.subarray(0, length).lastIndexOf(0x2f);
+    const nameLength = nameArg.length - i - 1;
+    const prefixLength = i;
+    if (i <= 0 || nameLength > NAME_SIZE || nameLength === 0 || prefixLength > PREFIX_SIZE) {
+        return null;
+    }
+    return { prefix: nameArg.subarray(0, i), name: nameArg.subarray(i + 1) };
+}
+/**
+ * Go `writePAXHeader` (`archive/tar/writer.go:131`) for one `path` record:
+ * the `x` header written by `writeRawFile`, the records, their padding, then
+ * the main header with the ASCII-folded name.
+ */
+function paxHeader(nameArg, modeArg, sizeArg) {
+    const records = paxRecord('path', nameArg);
+    if (records.length > MAX_SPECIAL_FILE_SIZE) {
+        throw new LinuxRepoError('invalid-input', 'a tar entry name is longer than Go archive/tar writes', {
+            field: 'name',
+        });
+    }
+    // path.Split, then path.Join(dir, "PaxHeaders.0", file); writeRawFile folds
+    // it to ASCII, cuts it to 100 bytes and trims trailing slashes
+    const slash = nameArg.lastIndexOf('/');
+    const dir = nameArg.slice(0, slash + 1);
+    const file = nameArg.slice(slash + 1);
+    let paxName = encoder.encode(toAscii(goPathJoin([dir, 'PaxHeaders.0', file])));
+    if (paxName.length > NAME_SIZE) {
+        paxName = paxName.subarray(0, NAME_SIZE);
+    }
+    let end = paxName.length;
+    while (end > 0 && paxName[end - 1] === 0x2f) {
+        end--;
+    }
+    return concatBytes([
+        header({ name: paxName.subarray(0, end), prefix: null, size: records.length, mode: 0, typeflag: 'x', raw: true }),
+        records,
+        new Uint8Array(padding(records.length)),
+        header({ name: encoder.encode(toAscii(nameArg)), prefix: null, size: sizeArg, mode: modeArg, typeflag: '0' }),
+    ]);
+}
+/** Go `formatPAXRecord` (`archive/tar/strconv.go:291`). */
+function paxRecord(keyArg, valueArg) {
+    const payload = encoder.encode(` ${keyArg}=${valueArg}\n`);
+    let size = payload.length;
+    size += String(size).length;
+    let record = concatBytes([encoder.encode(String(size)), payload]);
+    if (record.length !== size) {
+        size = record.length;
+        record = concatBytes([encoder.encode(String(size)), payload]);
+    }
+    return record;
+}
+/** Go `templateV7Plus` plus `setFormat` (`archive/tar/writer.go:323`, `format.go:205`). */
+function header(specArg) {
+    const block = new Uint8Array(BLOCK);
+    formatString(block, 0, NAME_SIZE, specArg.name);
+    formatOctal(block, 100, 8, specArg.mode);
+    formatOctal(block, 108, 8, 0); // uid
+    formatOctal(block, 116, 8, 0); // gid
+    formatOctal(block, 124, 12, specArg.size);
+    formatOctal(block, 136, 12, 0); // mtime: the zero time.Time is written as 0
+    block[156] = specArg.typeflag.charCodeAt(0);
+    // linkname, uname and gname stay empty
+    if (!specArg.raw) {
+        formatOctal(block, 329, 8, 0); // devmajor
+        formatOctal(block, 337, 8, 0); // devminor
+    }
+    if (specArg.prefix !== null) {
+        formatString(block, 345, PREFIX_SIZE, specArg.prefix);
+    }
+    block.set(encoder.encode('ustar\0'), 257);
+    block.set(encoder.encode('00'), 263);
+    let sum = 0;
+    for (let i = 0; i < BLOCK; i++) {
+        sum += i >= 148 && i < 156 ? 0x20 : block[i];
+    }
+    formatOctal(block, 148, 7, sum);
+    block[155] = 0x20;
+    return block;
+}
+/** Go `formatter.formatString` (`archive/tar/strconv.go:63`): copy, NUL-terminate when shorter, cut when longer. */
+function formatString(blockArg, offsetArg, lengthArg, valueArg) {
+    const field = blockArg.subarray(offsetArg, offsetArg + lengthArg);
+    field.set(valueArg.subarray(0, lengthArg));
+    if (valueArg.length < lengthArg) {
+        field[valueArg.length] = 0;
+    }
+    if (valueArg.length > lengthArg && field[lengthArg - 1] === 0x2f) {
+        let n = lengthArg - 1;
+        while (n > 0 && valueArg[n - 1] === 0x2f) {
+            n--;
+        }
+        field[n] = 0;
+    }
+}
+/**
+ * Go `formatter.formatOctal` (`archive/tar/strconv.go:176`): zero-padded octal
+ * leaving room for a NUL. Callers check the range first; Go would write 0.
+ */
+function formatOctal(blockArg, offsetArg, lengthArg, valueArg) {
+    const digits = valueArg.toString(8).padStart(lengthArg - 1, '0');
+    formatString(blockArg, offsetArg, lengthArg, encoder.encode(digits));
+}
+/** Go `toASCII` (`archive/tar/strconv.go:32`): drops every non-ASCII rune (NUL is refused earlier). */
+function toAscii(valueArg) {
+    let result = '';
+    for (const char of valueArg) {
+        if (char.codePointAt(0) < 0x80) {
+            result += char;
+        }
+    }
+    return result;
+}
+/** Go `isASCII` (`archive/tar/strconv.go:21`) for a name without NUL. */
+function isAscii(bytesArg) {
+    for (let i = 0; i < bytesArg.length; i++) {
+        if (bytesArg[i] >= 0x80) {
+            return false;
+        }
+    }
+    return true;
+}
+function padding(sizeArg) {
+    return (BLOCK - (sizeArg % BLOCK)) % BLOCK;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZ290YXIuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy93cml0ZXJzL2dvdGFyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxXQUFXLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUNsRCxPQUFPLEVBQUUsY0FBYyxFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFDckQsT0FBTyxFQUFFLFVBQVUsRUFBRSxNQUFNLHFCQUFxQixDQUFDO0FBa0JqRCxNQUFNLEtBQUssR0FBRyxHQUFHLENBQUM7QUFDbEIsTUFBTSxTQUFTLEdBQUcsR0FBRyxDQUFDO0FBQ3RCLE1BQU0sV0FBVyxHQUFHLEdBQUcsQ0FBQztBQUN4QixnRkFBZ0Y7QUFDaEYsTUFBTSxxQkFBcUIsR0FBRyxDQUFDLElBQUksRUFBRSxDQUFDO0FBQ3RDLDREQUE0RDtBQUM1RCxNQUFNLFVBQVUsR0FBRyxDQUFDLElBQUksQ0FBQyxDQUFDO0FBQzFCLHNFQUFzRTtBQUN0RSxNQUFNLFVBQVUsR0FBRyxDQUFDLElBQUksRUFBRSxDQUFDO0FBQzNCLE1BQU0sT0FBTyxHQUFHLElBQUksV0FBVyxFQUFFLENBQUM7QUFFbEM7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQXFCRztBQUNILE1BQU0sVUFBVSxVQUFVLENBQ3hCLFFBQStCLEVBQy9CLFVBQVUsR0FBdUIsRUFBRSxZQUFZLEVBQUUsSUFBSSxFQUFFO0lBRXZELE1BQU0sS0FBSyxHQUFpQixFQUFFLENBQUM7SUFDL0IsS0FBSyxNQUFNLElBQUksSUFBSSxRQUFRLEVBQUUsQ0FBQztRQUM1QixLQUFLLENBQUMsSUFBSSxDQUFDLFdBQVcsQ0FBQyxJQUFJLENBQUMsSUFBSSxFQUFFLElBQUksQ0FBQyxJQUFJLEVBQUUsSUFBSSxDQUFDLElBQUksQ0FBQyxNQUFNLENBQUMsRUFBRSxJQUFJLENBQUMsSUFBSSxFQUFFLElBQUksVUFBVSxDQUFDLE9BQU8sQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDLE1BQU0sQ0FB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

package/license.md

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Task Venture Capital GmbH (hello@task.vc)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@push.rocks/smartlinuxrepo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "private": false,
+  "description": "A pure codec for Linux package repositories (Alpine apk, Debian apt, RPM dnf, Arch pacman): read packages into records, build index file sets and sign them.",
+  "main": "dist_ts/index.js",
+  "typings": "dist_ts/index.d.ts",
+  "exports": {
+    ".": "./dist_ts/index.js"
+  },
+  "author": "Task Venture Capital GmbH",
+  "license": "MIT",
+  "engines": {
+    "node": "^24.20.0 || >=26.6.0"
+  },
+  "devDependencies": {
+    "@git.zone/tsrepo": "^2.1.0",
+    "@openpgp/web-stream-tools": "0.3.1",
+    "@types/node": "^26.6.6"
+  },
+  "dependencies": {
+    "@napi-rs/lzma": "1.5.3",
+    "openpgp": "6.3.2"
+  },
+  "files": [
+    "ts/**/*",
+    "dist_ts/**/*",
+    ".smartconfig.json",
+    "license.md",
+    "readme.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "keywords": [
+    "linux",
+    "package repository",
+    "alpine",
+    "apk",
+    "debian",
+    "apt",
+    "rpm",
+    "dnf",
+    "arch",
+    "pacman",
+    "openpgp",
+    "codec"
+  ],
+  "homepage": "https://code.foss.global/push.rocks/smartlinuxrepo",
+  "repository": {
+    "type": "git",
+    "url": "https://code.foss.global/push.rocks/smartlinuxrepo.git"
+  },
+  "scripts": {
+    "test": "tsrepo test test/",
+    "test:gate": "tsrepo test 'test/gate/*.gate.node.ts'",
+    "build": "tsrepo build tsfolders",
+    "buildDocs": "tsrepo docs"
+  }
 }

package/readme.md

@@ -0,0 +1,176 @@
+# @push.rocks/smartlinuxrepo
+
+A pure codec for Linux package repositories: Alpine (apk), Debian (apt), RPM (dnf) and Arch (pacman). It reads package files into JSON records, builds repository index file sets and signs them, following Gitea 28.2.0. It does no storage and no network I/O; the caller owns both.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## Install
+
+```sh
+pnpm add @push.rocks/smartlinuxrepo
+```
+
+Node.js `^24.20.0 || >=26.6.0`: the releases whose `node:zlib` reports a truncated zstd frame (nodejs/node#64593). On an older Node, opening a zstd decoder throws a plain `Error`.
+
+## Status
+
+All four formats read, index and sign: `readAlpinePackage`, `readDebianPackage`, `readRpmPackage` and `readArchPackage` read packages into records; `buildAlpineIndex`, `buildDebianIndex`, `buildRpmIndex` and `buildArchIndex` build signed index file sets; `signRpmPackage` and `signArchPackage` sign packages at upload. Each format is checked against Gitea 28.2.0's own output and installed from with apk, apt, dnf and pacman. The built-in OpenPGP signer does not stream: openpgp.js 6.3.2 holds a detached-signed document in memory (see Signing).
+
+## Records
+
+`TLinuxPackageRecord` is a union of `IAlpinePackageRecord`, `IDebianPackageRecord`, `IRpmPackageRecord` and `IArchPackageRecord`, discriminated by `format`. Every record carries `name`, `version`, `architecture`, `fileName`, `digests` (size, md5, sha1, sha256, sha512 over the whole file; Alpine adds `controlSha1`) and a format-specific `metadata` object. Records are plain JSON and safe to persist; changing their shape is a major release.
+
+## Limits and errors
+
+Readers take `Partial<ILinuxPackageLimits>` per call over `DEFAULT_LINUX_PACKAGE_LIMITS`:
+
+| Limit | Default | Bounds |
+| --- | --- | --- |
+| `maxPackageBytes` | 8 GiB | the whole input |
+| `maxMetadataBytes` | 64 MiB | one buffered metadata unit (apk or deb control member, RPM headers) |
+| `maxDecompressedMetadataBytes` | 32 MiB | a decompressed control tar or `.PKGINFO` |
+| `maxPayloadBytes` | 16 GiB | the decompressed Arch payload walked for the file list |
+| `maxEntries` | 100,000 | archive entries, values per multi-valued field |
+| `maxFileListBytes` | 16 MiB | total Arch file-name bytes |
+| `maxHeaderBytes` | 4 MiB | one tar header chain or metadata line |
+
+Every failure is a `LinuxRepoError` with a stable `code` (`limit-exceeded`, `unsupported-compression`, `malformed-archive`, `malformed-header`, `missing-field`, `invalid-field`, `unsupported-package-format`, `truncated`, `digest-mismatch`, `invalid-input`, `invalid-key`, `signing-failed`) and a `detail` naming the field or limit. Errors from your own source or signer, and failures inside node:crypto or openpgp.js during key generation, are passed through unchanged.
+
+## Signing
+
+The codec never stores keys. You pass a signer on every call:
+
+```ts
+import {
+  createAlpineSigner,
+  createOpenPgpSigner,
+  generateAlpineKeyPair,
+  generateOpenPgpKeyPair,
+  giteaAlpineKeyName,
+} from '@push.rocks/smartlinuxrepo';
+
+const alpineKeys = await generateAlpineKeyPair(); // RSA-4096, PKCS#1 private + PKIX public PEM
+const alpineSigner = createAlpineSigner({
+  privateKeyPem: alpineKeys.privateKeyPem,
+  keyName: giteaAlpineKeyName('my-org', alpineKeys.publicKeyPem), // my-org@<sha256>.rsa.pub
+});
+
+const pgpKeys = await generateOpenPgpKeyPair({ userId: 'Example Repository Key', timestamp: new Date() });
+const pgpSigner = await createOpenPgpSigner({ privateKeyArmored: pgpKeys.privateKeyArmored });
+```
+
+`IAlpineSigner.sign` returns an RSA PKCS#1 v1.5 SHA-1 signature. `IOpenPgpSigner.signBinary` and `signText` return one raw OpenPGP v4 signature packet (SHA-256, created at the given timestamp). `signBinary` takes the document as an `AsyncIterable<Uint8Array>` and signs the concatenation of its chunks, reading it to its end exactly once, so a whole package can be signed while it streams; pass bytes you already hold as a single chunk. The built-in signer from `createOpenPgpSigner` does not stream yet: openpgp.js 6.3.2 keeps every chunk of a detached-signed stream and then concatenates them, so signing peaks at about twice the document size in memory. A custom `IOpenPgpSigner` implementation can stream. The codec does all armoring and cleartext framing, so any implementation of the interface (an HSM, a remote signer, a test stub) produces identically framed files. `createOpenPgpSigner` accepts unencrypted v4 keys only.
+
+`isIndexableArchitecture(architecture)` tells whether an architecture can name an index path; builders refuse entries that fail it.
+
+Every builder returns the complete file set for its input as `ILinuxIndexFile[]` (`path`, `bytes`, `sha256`, `mediaType`, `stage`, `aliases`); a previously written file that is not in the set is stale. Write every `content` file before any `pointer` file: the pointer files are the signed documents that name the content files.
+
+## Alpine
+
+```ts
+import { buildAlpineIndex, readAlpinePackage } from '@push.rocks/smartlinuxrepo';
+
+// upload() returns a fresh AsyncIterable<Uint8Array> of the package bytes; limits are optional
+const record = await readAlpinePackage(upload(), limits);
+const files = await buildAlpineIndex({
+  branch: 'v3.22',
+  repository: 'main',
+  entries: [record], // every package of this branch and repository
+  signer: alpineSigner,
+  timestamp: new Date(),
+});
+```
+
+`readAlpinePackage` reads apk v2 packages, signed or unsigned; an apk v3 (ADB) package is `unsupported-package-format`, as in Gitea. The record's `fileName` is `<name>-<version>.apk`, and `digests.controlSha1` is the SHA-1 of the whole control gzip member, which is what apk verifies (the index's `C:` value).
+
+For every architecture the entries name, `buildAlpineIndex` returns one file, `<branch>/<repository>/<architecture>/APKINDEX.tar.gz`: a gzip member with the signature entry `.SIGN.RSA.<keyName>` (the signer's `keyName`), followed by the gzip member holding `APKINDEX`. Packages of architecture `noarch` are also listed in every other architecture's index, and every entry's `A:` is the index's architecture, so apk requests a `noarch` package under the architecture's path. Your route serves package files at `<branch>/<repository>/<architecture>/<fileName>` and, as Gitea 28.2.0 does:
+
+- A package file or `APKINDEX.tar.gz` that does not exist under the requested architecture is looked up under `noarch`. A repository with only `noarch` packages has no other index, so apk gets the `noarch` one.
+- apk finds the public key by the signature entry's name: users install it as `/etc/apk/keys/<keyName>`. `giteaAlpineKeyName` gives Gitea's name, `<owner>@<sha256 of the public key>.rsa.pub`.
+
+## Debian
+
+```ts
+import { buildDebianIndex, readDebianPackage } from '@push.rocks/smartlinuxrepo';
+
+// upload() returns a fresh AsyncIterable<Uint8Array> of the package bytes; limits are optional
+const record = await readDebianPackage(upload(), limits);
+const files = await buildDebianIndex({
+  distribution: 'bookworm',
+  entries: [{ component: 'main', record }], // every package of the distribution
+  origin: 'Example',
+  label: 'Example',
+  signer: pgpSigner,
+  timestamp: new Date(),
+});
+```
+
+`readDebianPackage` reads the `control.tar` member (plain, `.gz`, `.xz` or `.zst`) and hashes the rest of the file without decompressing it. The record keeps Gitea's derived values exactly, and its `fileName` is `<name>_<version>_<architecture>.deb`.
+
+`buildDebianIndex` returns the complete set for one distribution. For every component and architecture with packages it writes `dists/<distribution>/<component>/binary-<architecture>/Packages`, `Packages.gz` and `Packages.xz` (`content` files). Packages of architecture `all` are listed only under `binary-all`, as in Gitea. Then it writes `dists/<distribution>/Release`, its armored detached signature `Release.gpg` and the cleartext-signed `InRelease` (`pointer` files). `distribution` and `component` must match `^[a-zA-Z0-9][a-zA-Z0-9.~+_-]*$`; `origin` and `label` are each one non-empty line without surrounding whitespace. Your route serves:
+
+- every file at its `path` and at each of its `aliases`, `by-hash/MD5Sum`, `SHA1`, `SHA256` and `SHA512/<hex>` next to the `Packages` file. `Release` sets `Acquire-By-Hash: yes`, and apt 2.6 and 3.x fetch `Packages.xz` through `by-hash/SHA512/<hex>`;
+- each package file at `pool/<distribution>/<component>/<fileName>`, the `Filename:` its stanza names;
+- the public key (`publicKeyArmored` from `generateOpenPgpKeyPair`), which users install as `/etc/apt/keyrings/<name>.asc` and reference with `signed-by`.
+
+## RPM
+
+```ts
+import { buildRpmIndex, mergeRpmUpdates, readRpmPackage, renderRpmRepoConfig, signRpmPackage } from '@push.rocks/smartlinuxrepo';
+
+// optional upload signing, as Gitea's ?sign=true: tags 1002 (header + payload) and 268 (header)
+const { prefix, resumeAt } = await signRpmPackage({ source: packageStream(), signer: pgpSigner, timestamp: new Date() });
+// the signed package is `prefix` followed by the original bytes from `resumeAt`
+
+const record = await readRpmPackage(signedPackageStream());
+const files = await buildRpmIndex({
+  group: 'el/9', // '' for the root group
+  entries: [record],
+  updates: [], // IRpmUpdate[] of every version with a file in the group
+  repodataNaming: 'plain', // Gitea's repodata/<type>.xml.gz, or 'content-addressed' for <sha256>-<type>.xml.gz
+  signer: pgpSigner,
+  timestamp: new Date(),
+});
+```
+
+`buildRpmIndex` returns `primary`, `filelists`, `other` (and `updateinfo` when there are updates) as `.xml.gz` content files, then `repomd.xml` and `repomd.xml.asc`. The documents follow Gitea 28.2.0 with three corrections: the `filelists` namespace is `http://linux.duke.edu/metadata/filelists`, `primary` also lists the paths createrepo_c's `cr_is_primary` selects (`/etc/…`, `*bin/*`, `/usr/lib/sendmail`), and every document lists a source RPM's architecture as `src` (its package path keeps the ARCH tag). `readRpmPackage` refuses with `invalid-field` a NAME or `[EPOCH-]VERSION-RELEASE` that cannot name a path segment (empty, `.`, `..`, `/` or a control character), which Gitea does not check. `mergeRpmUpdates` merges posted errata as Gitea's errata route does; `renderRpmRepoConfig` writes Gitea's `.repo` text, optionally with `repo_gpgcheck`.
+
+## Arch
+
+```ts
+import { buildArchIndex, readArchPackage, signArchPackage } from '@push.rocks/smartlinuxrepo';
+
+// upload() returns a fresh AsyncIterable<Uint8Array> of the package bytes; limits are optional
+const record = await readArchPackage(upload(), limits);
+const packageSignature = await signArchPackage({ source: upload(), signer: pgpSigner, timestamp: new Date(), limits });
+const files = await buildArchIndex({ repository: 'core', entries: [{ record, packageSignature }], signer: pgpSigner, timestamp: new Date() });
+```
+
+Pass `signArchPackage` the limits the package was read with. Store its result with the package: it is the package's `.sig` file, and the builder writes it into the index as `%PGPSIG%`. An entry without one has no `%PGPSIG%`, and pacman fetches `<file>.sig` instead.
+
+For every architecture that has packages, `buildArchIndex` returns two files: `<repository>/<architecture>/packages.db` (a gzip tar) and its signature `packages.db.sig`. Packages of architecture `any` also go into every other architecture's db. The files have no aliases. Your route maps request names onto them, as Gitea 28.2.0 does for `GET <repository>/<architecture>/<filename>`:
+
+- A trailing `.sig` asks for the signature of the rest of the name.
+- A name ending in `.db`, `.db.tar.gz`, `.files` or `.files.tar.gz` means `packages.db`. pacman requests `<repo>.db`, where `<repo>` is the repository's name in `pacman.conf`.
+- A name that does not exist under the requested architecture is looked up under `any`. Gitea does this for every name, so a package uploaded as `any` downloads from every architecture's URL.
+
+## License and Legal Information
+
+This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license.md) file within this repository.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+
+### Company Information
+
+Task Venture Capital GmbH
+Registered at District court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts/00_commitinfo_data.ts

@@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+  name: '@push.rocks/smartlinuxrepo',
+  version: '1.0.0',
+  description: 'A pure codec for Linux package repositories (Alpine apk, Debian apt, RPM dnf, Arch pacman): read packages into records, build index file sets and sign them.'
+}