Extending shard.lock with cryptographic signatures after Crystal 1.0.0

Before the design details, one clarification: as of the documented shards releases, lock-file signatures are not an accepted Crystal roadmap feature, and Crystal 1.0.0's contribution was deterministic lock generation, not signing. So treat this as a design proposal to validate against the shards changelog and GitHub RFCs before implementing — not as behavior you can rely on today.

Recommended field format

Store the signature as a nested mapping per dependency, alongside version and the existing checksum, rather than as a flat string:

dependencies:\n  some_shard:\n    github: owner/some_shard\n    version: 1.2.3\n    signature:\n      algorithm: ed25519\n      value: <base64 signature>

The explicit algorithm key lets the scheme evolve (e.g., a future post-quantum algorithm) without changing the parser contract. The signature should be computed over the resolved tarball bytes or their content hash — never over timestamps, paths, or machine-specific data — so that identical shards.yml input still produces an identical lock file. That means signatures must be computed at lock-generation time from the fetched artifacts.

How older versions should treat the field

YAML parsers ignore unknown keys, so older shards releases will silently skip a signature block. Parsing is safe; the risk is a verification gap: an old toolchain installs code with no signature checking and no warning. The likely best mitigation is a top-level marker in the lock file — a lock-format version bump or a signed: true flag — that newer tools enforce, and that documentation instructs users of older toolchains to treat as a signal to upgrade rather than delete. This is a design recommendation, not confirmed shards behavior; verify how your installed version handles unknown keys by hand-adding a test field and running shards check.

Extend shards check or add a subcommand?

Extending shards check is the lower-friction path: it already performs integrity verification, so signature validation is a natural extension. A separate shards verify-signature subcommand is justified only if verification needs its own trust configuration — keyrings, trusted publisher keys, revocation — that would complicate check. A pragmatic split:

• shards check validates signatures when present and warns (or fails behind a flag) when they are missing or invalid.
• Key material and trust policy live in a separate config file, not in shard.lock, keeping the lock file deterministic and machine-independent.

The trust-model caveat

Signatures without a key-distribution story add complexity without real supply-chain protection: who signs, and where do verifiers get trustworthy public keys? Also note that a signature binds to a specific artifact — if tarballs regenerated from the same git tag differ byte-for-byte, verification fails unless the ecosystem pins canonical archives. Both points need resolution in the proposal before the field ships.

Verification before committing

1. Confirm determinism: run lock generation on two clean machines from the same shards.yml and diff the results.
2. Prototype the flow: sign a tarball with ed25519, add the field, and test shards check with valid, invalid, and missing signatures.
3. Check the shards changelog and Crystal RFCs for any accepted signature proposal so the design doesn't conflict with official direction.

This draft is conservative pending confirmation of current shards behavior; the parsing and determinism claims should be re-verified against the release you target.