aslice Repositories — Sources, Trust Levels, and Signing Keys

State, identity, privilege, and recovery contracts: STATE-AND-RECOVERY. Protected-volume patching: SYSTEM-VOLUMES. These specifications do not establish completed implementation or platform validation.

• Status: Design draft, v1.17 — September 2026
• Companion to: DESIGN.md, PACKAGE-FORMAT.md, BUILD-INFRA.md, ORCHARD-POLICY.md
• Scope: the shipped official source list, adding third-party repositories, the inherent trust-level model, and the dual signature scheme (Ed25519 canonical, OpenPGP supported).
• Vocabulary: NOMENCLATURE.md — project terms, acronyms, and the Homebrew translation table.

1. Axioms

1. Trust is per-repository, never global (DESIGN §9.6). When you add a repository, it acquires the capabilities of its trust level, and nothing beyond them.
2. Trust levels are inherent, not labels. A level is a set of enforced capabilities: which namespaces the repo may serve, whether its binaries may install, whether it may serve [system] packages. The checks live in the solver and the verifier, in code — not in documentation. A repository cannot talk its way into a higher level; only the user (or the project's countersignature, for verified repos) can raise one.
3. Every served artifact is signed. No trust level permits unsigned binaries to install. What varies between levels is whose signature is required and what the repo is allowed to offer; what never varies is that verification happens.
4. No repository can execute code at install time outside the graft mechanism, regardless of level (DESIGN §10.1 and DESIGN §12.15). The only package code that can ever run is a declared, approved, manifest-sandboxed graft — and §3's table says who may serve even that. Trust levels govern distribution, not the structural guarantees.
5. The official list is data, signed and versioned — not hardcoded logic. aslice ships a source list file; you can inspect it, diff it, and — if you are the paranoid sort — replace it wholesale with a pinned copy.

2. The shipped source list

An aslice installation carries /opt/aslice/etc/sources.toml. The file is part of the bootstrap package and updates through the normal TUF channel — it is a TUF target like any other metadata: versioned, rollback-protected, and diffable with aslice repo list --sources-diff.

# aslice official source list — ships with the bootstrap, updated via TUF.
# Schema versioned; unknown fields rejected.

[sources.core]
url          = "https://repo.aslice.sh/core"
mirrors      = ["https://ghcr.io/aslice/core", "https://mirror.example.org/core"]
trust        = "official"
namespace    = "core"
tuf_root_fingerprint = "ed25519:ROOT0…" # initial TUF anchor
key_fingerprint = "ed25519:RWQ0…"       # separate package-signing key
enabled      = true

[sources.extended]
url          = "https://repo.aslice.sh/extended"
trust        = "official"
namespace    = "extended"
tuf_root_fingerprint = "ed25519:ROOT1…"
key_fingerprint = "ed25519:RWQ1…"
enabled      = true

[sources.audio-lab]
url          = "https://repo.audio-lab.example/aslice"
trust        = "verified"           # project-countersigned community repo (§3)
namespace    = "audiolab"
tuf_root_fingerprint = "ed25519:ROOT2…"
key_fingerprint = "openpgp:9F3C 77AA …"
countersigned_by = "ed25519:RWQ0…"  # the core key vouches for this repo's key
enabled      = false                # listed for discovery; off until the user opts in

The properties that matter:

• The initial TUF root fingerprint is compiled into bootstrap. It authenticates the initial anchor. Authenticated sequential root transitions establish the current root; discovery-file edits cannot bypass that chain or reset trusted metadata versions (STATE-AND-RECOVERY §7).
• The list is also where verified community repositories are advertised (§3): known, project-vouched, and disabled by default. Discovery without implicit trust.
• You may edit the file directly or through aslice repo add/remove/enable/disable. Both paths validate against the schema. Discovery cannot replace retained trust: authenticated root rotation follows the existing chain; an unauthenticated replacement blocks updates and requires independently verified rebootstrap or re-pinning.
• A completely offline or air-gapped machine works with the shipped file plus file:// mirrors. The list is plain data (§8), and plain data travels.
• Mirrors replicate the whole tree, sources included. The blobs/sha256/ area vendors every source artifact the farm has ever fetched (DESIGN §9.6); a mirror is therefore a full survival copy of the orchard's inputs, not just its outputs.

3. Trust levels

Four levels, ordered by what a repository is permitted to do:

Every repository serving binaries uses Ed25519 TUF metadata. Package signatures are additionally verified: minisign-format Ed25519 for official releases, or the declared supported package-signature scheme for other repositories. An OpenPGP package key never replaces a TUF root (STATE-AND-RECOVERY §7). Unsigned local recipes remain a separate local-only source-build path. The rules below define capabilities and their conditions; a short table cell does not waive them.

Some rules hold at every level:

• A level can only be lowered by the user, and raised only by the defined path. There is no --trust-just-this-once flag that bypasses a level's capability set — a bypass flag would make the levels decorative.
• Only core has bare package names. curl identifies the core package. Every other repository, including extended and local repositories, requires its registered name as a prefix: extended:ffmpeg, extended:vendorcli, audiolab:convolver. Equal suffixes in different namespaces are different package identities. There is no cross-repository fallback, overlap prompt, or remembered repository preference (§10).
• Vendor-binary packages (type = "binary") follow the same levels. A third-party repo may serve vendor slices — payload-only, or graft-bearing under the unsigned-manifest warning below — subject to the signer-pinning rules of DESIGN §12.4 unchanged. Note that the Apple code-signing identity pin is additional to the repo signature, never a substitute for it.
• Graft behavior manifests are signed index metadata (DESIGN §12.15). For official repos the farm rehearses every graft in per-OS VMs and the project signs the verified manifest (ORCHARD-POLICY §10 gate 5). A verified repo signs its own manifests with its vouched key — behavior signing is part of what the vouch covers. third-party manifests are unsigned by construction: the client shows the unsigned-graft warning — provenance, the full declared behavior, a per-decision prompt that is never persisted — and the install proceeds only through it. local trees answer to the machine's owner alone. A manifest signature is additional to both the slice signature and any Apple signer pin, never a substitute.
• System packages ([system], DESIGN §12.7) are a per-level capability, not a package property. official and verified repositories may serve them. third-party repositories never may — no warning flow makes a stranger's kernel extension acceptable. local repositories may, on the user's own machine, with the same warnings. The solver refuses a [system] package from a non-capable repository with a message that names the level and the remedy, not a generic error. The same capability gates root-domain services (domain = "system" in the [service] table, DESIGN §12.8): running code as root is the privilege that matters, so a third-party repository may declare user agents but never root daemons. The refusal happens at solve time, with the same named-level message.
• System patches ([system-patch], DESIGN §12.11) carry their own, stricter capability — the strictest gate in the system. The reason for the extra gate is the blast radius: a [system-patch] package replaces an Apple-provided file for every user and every process on the machine. Serving one therefore requires the system-patch capability: official and local repositories have it; third-party never does. A verified repository receives it only through an explicit per-repo grant from the machine's owner — aslice repo allow-system-patch <name>, refused by default, recorded in the state DB, revocable with aslice repo deny-system-patch <name> (DESIGN open question #10, resolved in DESIGN v1.8). Contrast this with system, which rides on verified with no grant: the countersignature vets a repository to distribute software, and rewriting the OS warrants one more decision beyond that vetting. The grant gates serving; the DESIGN §12.11 consent flow is unchanged and applies whoever serves the package. A non-capable or ungranted repository that serves a [system-patch] package gets a solver refusal naming the level and the remedy.
• Demotion of a verified repo is a blocking event. If a verified repo's countersignature is revoked, or its key rotates without a re-vouch, the client freezes the repo at its last good snapshot and refuses updates. Every operation that touches the repo prints the reason, and keeps printing it, until the user re-pins or removes it.

4. Adding a third-party repository

All orchards, including third-party orchards, follow the shared environment and promotion contract: dev → develop, staging → beta, prod → master. These branches belong to one repository identity, replicated by its mirrors; environment selection changes the branch pointer, not the repository or mirror URL. Production is the default, and dev/staging require explicit selection with no automatic cross-environment fallback. Each environment has isolated cached metadata and rollback-protection state. Promotion reuses immutable artifacts under the release-version rules. Third-party publishers use their own authorities; this workflow does not alter trust levels or capabilities. Maintenance promotion records follow ORCHARD-POLICY; implementation remains pending. TUF metadata itself is unchanged.

$ aslice repo add https://repo.example.org/aslice
Fetching TUF root metadata…
Repository:  example.org community repo
Namespace:   example
TUF root:    ed25519:ROOT…
Package key: openpgp:7A3F 19C2 88E4 0D1B …
Trust level: third-party (binaries allowed; cannot shadow core packages)

Verify this fingerprint out-of-band — project website, release notes,
a signed email. Anyone can serve a repository; the fingerprint IS the
identity. Pin it? [y/N]

• The initial TUF anchor and package-signing identity are displayed separately and retained in authoritative trust state, with a read-only DB cache. Sequential TUF root updates satisfying the old and new thresholds need no manual re-pin. An unauthenticated replacement blocks updates; aslice repo re-pin requires independent verification (STATE-AND-RECOVERY §7).
• aslice repo add --trust local file:///… is the only way to obtain the local level. official and verified cannot be granted by the CLI at all: verified requires the project's countersignature, which arrives through the official source list. That indirection is the point — it is how the project can vouch for a repository without holding anyone's keys.
• Removal is aslice repo remove example. Packages installed from the repo remain in the store — they are content-addressed and generation-pinned — but the namespace stops resolving. doctor may propose an explicit replacement plan; it cannot reparent packages automatically. Namespace reuse by a different repository identity never transfers existing requests, selections, grants, plans, or locks.

5. Signing keys: two schemes, one verification pipeline

5.1 Why two schemes

The canonical scheme is Ed25519 in minisign-compatible format under TUF (DESIGN §10.2). The virtues are practical: tiny keys, tiny signatures, a verification routine small enough to audit in an afternoon, and no dependency on the GnuPG ecosystem. This remains the scheme for the official repositories and for aslice's own releases.

Repositories exist, however, so that other ecosystems can distribute through aslice — and those ecosystems already sign with OpenPGP: upstream release tarballs, vendor checksum files, existing project keyrings. Telling every third-party operator to re-key into minisign would amount to telling the platform's most valuable niche communities (audio, lab, retro) to change their release process for our sake. OpenPGP verification is therefore a first-class, built-in scheme:

• Implementation: a self-contained OpenPGP verifier inside aslice, in the Sequoia-PGP style, linked in. There is no dependency on a gpg binary and no keyserver lookup at verify time. The supported subset is the modern one: Ed25519 and ECDSA/RSA OpenPGP keys, detached and cleartext signatures, SHA-256+ digest algorithms only. SHA-1 signatures are rejected.
• Key acquisition: fingerprints are pinned in the source entry or at repo add (TOFU, §4). Full keys are fetched from the repository itself (keys/ in the repo tree, §6) or via WKD as a convenience. Verification, however, always runs against the pinned fingerprint — so a hostile keyserver or a swapped keys/ file produces a hard failure, not a wrong key.
• No web of trust. aslice evaluates exactly two things: whether the key matches the pinned fingerprint, and whether it produced a valid signature over the artifact. WoT pathfinding is explicitly out of scope; TOFU plus (for verified) the project's countersignature replaces it.

5.2 Where each signature lives

The client's rule is uniform: the scheme is a property of the repository, the fingerprint is a property of the pin, and both are enforced before content is trusted. A mixed ecosystem — an OpenPGP vendor repo alongside the Ed25519 official repos — is the expected steady state, not an edge case.

5.3 Rotation and revocation

• Official keys: an initial 1-of-1 root on an offline Pi, distinct targets, snapshot, and slice-signing keys on a dedicated networked release Pi, and the timestamp key on the publisher (KEY-RUNBOOK). Planned rotations and later multi-party adoption use sequential TUF roots satisfying both old and new root thresholds; all intermediate versions remain available. Replacing any top-level role key requires a root update; refreshing metadata with unchanged keys does not. Root compromise or loss without a usable backup requires explicit trust rebootstrap, not a silent pin change. The compiled-in bootstrap pin is updated through self-update (DESIGN §12.12), and each rotation is announced.
• Third-party keys: every repository follows the same sequential TUF root-update rules. Package-key transitions must be authenticated by trusted metadata. A transition signature alone cannot bypass TUF thresholds, revocation, or a required project countersignature. Unauthenticated replacement requires an independently verified re-pin; root compromise requires rebootstrap (STATE-AND-RECOVERY §7).
• Revocation: expired TUF metadata blocks repository updates; stopping publication does not instantly revoke client trust. Installed software keeps running. On top of that mechanism, official source-list updates can carry a revoked_keys list: a kill switch for a verified repo's countersignature that does not require a client release.

6. Repository tree addition: keys/

The repository tree of DESIGN §9.6 gains one directory:

repo.example.org/
 ├── tuf/
 ├── index/
 ├── formulas/
 ├── keys/           # full public keys for every fingerprint the repo asks clients to pin
 └── blobs/sha256/

One characterization covers keys/: convenience distribution, not authority. Its contents verify against the pinned fingerprint or are rejected. For verified repos, keys/ additionally holds the project's countersignature file, refreshed by source-list updates.

7. aslice repo command surface, completed

aslice repo list [--json]                 # namespaces, levels, key fingerprints, health
aslice repo add <url|file://> [--trust local]
aslice repo remove <name>
aslice repo enable / disable <name>       # verified repos ship disabled; user opts in
aslice repo re-pin <name>                 # guided fingerprint change with transition proof
aslice repo keys <name>                   # show the pinned keyring, scheme, countersignatures
aslice repo audit <name>                  # signature coverage report: every target signed? by which key?
aslice repo allow-system-patch / deny-system-patch <name>  # the per-repo verified grant (§3)
aslice repo build / sign / publish        # authoring side (DESIGN §9.6); --sign-with ed25519|openpgp
aslice repo list --sources-diff           # what the last source-list TUF update changed

Official authoring retains repo build / sign / publish: after owner-approved merge and all gates, the publisher sends an authenticated candidate to the dedicated networked release Pi for automatic signing, verifies the returned signatures and complete staged content, then publishes atomically. KEY-RUNBOOK §2.1 defines authorization, serialized activation, signing-state persistence, stale-candidate reconciliation, and idempotent retries. Root metadata is valid for one year, targets/snapshot for 90 days, and timestamps for 48 hours with daily refresh. Targets/snapshot renew automatically when fewer than 30 days remain using the last approved content; root renewal and top-level key replacement remain deliberate offline operations. Timestamp refresh cannot extend targets/snapshot expiry. Normal client metadata refresh discovers published slices for search, install, and upgrade; publication forces no installation. These services remain implementation work; no client signature-format, schema, or command-group change is introduced.

aslice repo audit re-verifies the signature over every target in a repo's current snapshot and reports scheme, key, and coverage. It exists so that an operator can prove "everything is signed" is true today — not at some ceremony in the past.

7.1 Authenticated index refresh

Fetch indexes by immutable SHA-256 address and authenticated byte length. TUF targets authorize the compressed object and a version-1 index-diff record binding repository/environment, base and result index digests and lengths, and ordered patch objects. Index digest means the exact uncompressed JSON bytes; parse only after reconstruction verifies that identity. The full compressed object's authenticated record also binds expanded digest and length. Reject duplicate JSON keys and unsupported snapshot formats.

Initial client limits are 16 patches, 64 MiB total patch transfer, 256 MiB expanded index, 512 MiB reconstruction memory, and 30 seconds reconstruction time. Enforce each bound during streaming, with checked arithmetic. A bad/missing base, unsupported patch codec, digest/length mismatch, or exceeded limit discards staged reconstruction and falls back once to the full authenticated index, under the same expanded-size/memory bounds. Version 1 uses byte-splice-v1 payloads described by the index-patch schema. Each payload binds its exact base/result and at most 100,000 ordered operations: copy appends a positive-length range from the verified base (checked offset plus length); insert appends decoded lowercase hexadecimal bytes. Output is append-only in staging. Reject overflow, out-of-range reads, unknown operations, duplicate JSON keys, excess output, or a chain whose next base differs from the preceding result. Reconstruction budgets include base, patch, and output memory. Patch instructions never name files or execute code. A failed full fetch leaves the previous snapshot active and reports failure.

Stage the new snapshot and every object required by the refresh transaction before activation; verify identity, length, signatures, schema, freshness, and cross-references, then switch the local current-snapshot pointer atomically. Missing objects during mirror publication cannot activate a partial snapshot. Lazy payloads outside the refresh set remain subject to complete transaction preparation before installation.

Try at most three configured mirrors, at most two attempts per mirror, with finite time/byte budgets (30 seconds per attempt by default). All attempts request the same authenticated identities and selected release. Retain and report integrity failures even if another mirror succeeds. A mirror never changes the trust anchor, repository identity, environment, or selected version. If refresh is required for freshness, a retained expired snapshot cannot authorize an update.

An unrelated unavailable repository does not block a transaction whose complete input closure is independently authorized and available. A required unavailable repository blocks that transaction: no silent package omission, repository substitution, or downgrade. Explicit whole-repository refresh still reports each failure. APT by-hash and PDiff controls motivate stable object retrieval; these bounds and activation semantics are aslice's contract.

8. Failure and edge cases

9. Amendments carried into the other documents

• DESIGN §9.6: the "Trust is per-repository" bullet is superseded by the level model of §3 here; the bullet now points at this document.
• DESIGN §10.2: the signature section now reads as dual-scheme — Ed25519/minisign canonical for official infrastructure, OpenPGP as a built-in first-class scheme for third-party repositories and formula-declared upstream verification.
• README: vocabulary gains nothing (a repository is still a repository); the security bullet now mentions trust levels and dual signature schemes.
• §3 trust levels (v0.4): the capability sets gain system — serving declared system-software packages (kexts, SIP-off development tools; DESIGN §12.7). official and verified may; third-party never may; local may on the user's own machine.
• §3 trust levels (v0.5): the system capability now also covers root-domain services (DESIGN v1.3 §12.8, PACKAGE-FORMAT v0.4 [service] with domain = "system"): user agents are ungated; root daemons require official, verified, or local.
• §3 trust levels (v0.6): the capability sets gain system-patch — serving declared system-patch packages (flagged replacement of Apple-provided files; DESIGN v1.7 §12.11, PACKAGE-FORMAT v0.6 §3.16). official and local may; verified and third-party never may — a deliberately stricter gate than system, because the countersignature vets a repository to distribute software, not to rewrite the OS. (Amended by v0.7 below.)
• §3 trust levels (v0.7): DESIGN open question #10 resolved (DESIGN v1.8 §15) — a verified repository may receive the system-patch capability through an explicit per-repo grant: aslice repo allow-system-patch <name>, refused by default, recorded in the state DB, revocable with aslice repo deny-system-patch <name>. Third-party repositories: never. The grant gates serving; the per-decision consent flow of DESIGN §12.11 is unchanged.
• Open question #6: ~~should verified repos be installable-binary-capable immediately at enable time, or should enabling one additionally require a per-repo --accept-binaries step?~~ Resolved (DESIGN v1.8 §15): enable implies binaries stands — the countersignature ceremony is the consent; the extra click was judged ceremony without security content.

10. Overlapping packages across repositories

Only core packages can be addressed by a bare name. Every other repository requires its registered namespace, including extended:package. Names are resolved exactly; enabling another repository never changes what a bare name means.

10.1 When overlap is detected

A duplicate complete package identity within a repository is an index error. The same suffix in two repositories is permitted because audiolab:convolver and plugins:convolver are distinct identities. Registering a second repository with an existing namespace is refused.

10.2 The prompt

There is no overlap prompt. A bare name absent from core fails with an actionable error. Search may list qualified alternatives, but installing one requires the user to name it explicitly.

10.3 Decisions are remembered — in the state database

No repository-resolution preference is stored. Plans, locks, request roots, and dependency bindings retain the repository identity and qualified package name. Installing or enabling a repository cannot reparent existing packages.

10.4 Pre-seeding and fleets

Machine files, recipes, and scripts use the same naming rule. Use extended:vendorcli or audiolab:convolver explicitly. The previously proposed preference/resolution commands and table are superseded; they are not part of the current interface.

Virtual providers, aliases, and replacements obey the same namespace boundary as concrete package names. A declaration cannot make other:provider satisfy a core request implicitly. Cross-namespace selection requires an explicit choice naming the requested identity, selected namespace/name, repository identity, and selection kind (provider, alias, or replacement). Retain that choice in requests, plans, and locks and revalidate its authority on replay. Removing a repository or reusing its namespace cannot transfer a choice to another identity. A same-namespace alias still requires authenticated metadata from that namespace's authority.

11. The state database's role

SQLite separates client state from the disposable cache. Protected system state, the farm coordinator, publisher, and release signer have distinct owner databases. DATABASE owns their executable schemas, lifecycles, maintenance commands, and disaster recovery; this section summarizes repository interactions.

• WAL and prepared statements apply within each owner database. Use the pinned SQLite build and connection policy in DATABASE. There is no cross-database atomic commit; journals coordinate projections and external effects.
• Security authority lives in trust/. Pins, root chains, grants, revocations, version high-water marks, and offline receipts remain independently retained per repository/environment. Database reconstruction preserves that authority; missing trust fails closed and never silently restarts TOFU (STATE-AND-RECOVERY §7).
• Inspection is read-only. aslice db lists roles, shows schemas, queries bounded snapshots, checks integrity and records, and performs owner-authorized backup/restore. Deleting the cache loses no choices; deleting durable projections stops mutations until reconstruction and recovery finish.

History

Source document