refactor!: complete ed25519_dalek to iroh-base public API migration#102
Merged
dignifiedquire merged 1 commit intoMay 27, 2026
Merged
Conversation
cbenhagen
force-pushed
the
refactor/iroh-base-public-api
branch
2 times, most recently
from
3a489ce to
4bea133
Compare
matheus23
previously requested changes
May 26, 2026
Member
matheus23
left a comment
matheus23
left a comment
There was a problem hiding this comment.
just... a couple comments too many for my taste perhaps?
The previous commit moved `EntrySignature` to `iroh::Signature` for wire
stability, but `iroh_docs::keys` still leaked `ed25519_dalek::{SigningKey,
VerifyingKey, SignatureError}` through `Author`, `NamespaceSecret`,
`AuthorPublicKey`, `NamespacePublicKey`, `PublicKeyStore`, and friends.
iroh-base PR #3529 ("feat(iroh-base)!: reduce external types in the
iroh-base API for keys") established the pattern for this migration -
see iroh-relay's matching `SignatureError` -> `KeyParsingError` rename
in that PR - and iroh-docs is one of the last iroh crates still leaking
these types through its public surface. This commit finishes that
migration so the iroh-docs public API no longer pins callers to a
specific upstream `ed25519_dalek`.
Concretely:
- `SigningKey` -> `iroh::SecretKey` (a transparent wrapper around dalek's
`SigningKey` - serde passes straight through, so the on-disk format
of `Author` / `NamespaceSecret` is byte-identical to before). The
postcard snapshot tests in the previous commit
(`test_author_postcard_snapshot`, `test_namespace_secret_postcard_snapshot`)
lock that format so any future upstream `SigningKey::serialize` drift
is caught before shipping.
- `VerifyingKey` -> `iroh::PublicKey` inside the `AuthorPublicKey` /
`NamespacePublicKey` newtypes. `iroh::PublicKey`'s serde format
differs from dalek's `VerifyingKey` (raw 32 bytes vs varint-length-
prefixed 32 bytes), but iroh-docs itself never serializes these
types - the redb store uses raw `&[u8; 32]` and the wire uses the
raw bytes inside `RecordIdentifier` - so this is an API-only change.
- `ed25519_dalek::SignatureError` -> `iroh::SignatureError` for everything
that's truly a signature-verification failure (`Author::verify`,
`EntrySignature::verify`, etc.).
- Key-parsing failures (`AuthorPublicKey::from_bytes`,
`PublicKeyStore::public_key`, the `TryFrom<AuthorId>` /
`TryFrom<NamespaceId>` impls) now return `iroh::KeyParsingError`,
which carries the actual reason (`InvalidKeyData`, `InvalidLength`,
etc.) instead of opaquely reusing `SignatureError`.
- `SignedEntry::verify` now returns a small `SignedEntryVerifyError`
enum that separates the two failure modes (key parsing vs signature
mismatch) instead of conflating them.
`Author::new` / `NamespaceSecret::new` consume 32 bytes via
`rng.fill_bytes`, matching `ed25519_dalek::SigningKey::generate`'s
byte-consumption pattern exactly, so seeded-RNG tests
(`test_replica_queries_*`, etc.) stay deterministic across the
migration.
BREAKING CHANGE: Multiple public API return types and error types
change. Affected items include `AuthorPublicKey::from_bytes`,
`NamespacePublicKey::from_bytes`, `AuthorId::{public_key, into_public_key}`,
`NamespaceId::{public_key, into_public_key}`,
`PublicKeyStore::{public_key, namespace_key, author_key}`, the
`TryFrom<AuthorId>` / `TryFrom<NamespaceId>` impls, and
`SignedEntry::verify` (now returns `SignedEntryVerifyError`). The
`From<SigningKey>` impls on `Author` / `NamespaceSecret` become
`From<SecretKey>`.
cbenhagen
force-pushed
the
refactor/iroh-base-public-api
branch
from
4bea133 to
b42d497
Compare
matheus23
reviewed
May 26, 2026
Member
matheus23
left a comment
matheus23
left a comment
There was a problem hiding this comment.
Thank you for this!
We should hold off on merging this for now - as we might want to keep main in its current state for publishing a 0.99.1. (We're still somewhat undecided about doing that. In theory we should be releasing 0.100 tomorrow anyways, but we're not 100% sure if that's the right way to do this)
Anyways - just to give some context on why I'm not yet giving it a formal ✅
dignifiedquire
approved these changes
May 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Finishes the migration n0-computer/iroh#3529 started. iroh-docs is one of the last iroh crates still leaking
ed25519_dalek::{SigningKey, VerifyingKey, SignatureError}through its public surface.SigningKeybecomesiroh::SecretKey(transparent serde; on-disk format byte-identical, locked bytest_postcard_format_stable).VerifyingKeybecomesiroh::PublicKeyinsideAuthorPublicKey/NamespacePublicKey(API-only; iroh-docs never serializes these).SignatureErrorbecomesiroh::SignatureErrorfor verification failures.iroh::KeyParsingErrorinstead of reusingSignatureError.SignedEntry::verifyreturns a newSignedEntryVerifyErrorenum that separates key-parsing from signature-mismatch failures.Breaking Changes
All breakage is in error-return positions; no method names, parameters, or semantic behavior change.
Return types changed from
Result<_, SignatureError>toResult<_, KeyParsingError>on:AuthorPublicKey::from_bytes,NamespacePublicKey::from_bytesAuthorId::public_key,AuthorId::into_public_keyNamespaceId::public_key,NamespaceId::into_public_keyPublicKeyStore::public_key,PublicKeyStore::namespace_key,PublicKeyStore::author_keyTryFrom<AuthorId> for AuthorPublicKey,TryFrom<NamespaceId> for NamespacePublicKeyOther changes:
SignedEntry::verifynow returnsResult<(), SignedEntryVerifyError>.From<ed25519_dalek::SigningKey>impls onAuthor/NamespaceSecretbecomeFrom<iroh::SecretKey>.Migration: callers using
?oranyhoware unaffected. Callers pattern-matching onSignatureErrorshould switch toKeyParsingErrorfor parse failures or to the newSignedEntryVerifyErrorvariants for verify failures. CustomPublicKeyStoreimpls need to update their return types.Notes & open questions
Targets 0.100.0. Stacked on #101 (the 0.99.1 wire-compat fix lands first)
Change checklist