🦋 Changeset detected

Latest commit: efa9b4f

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

❌ Failed checks (1 error)

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Fixes HYPER-181

I'm about to meet Nick and will ask him about the signatures object question.

Nick pointed me to the fact that you can have a ref to a definition which is of type array. This is actually a very well-hidden aspect of the spec:

Refs can not be declared as top-level named types in a schema defs array. This means that a ref can not point to another ref, nor a union. They can reference container types that contain nested ref types, for example an object.

That last sentence including the "for example" is the only clue given that it can also be array. And the Overview of Types section further up confirms that array and object are the only two container types.

Flatten signatures array directly onto records

Core change: app.certified.signature.list is now "type": "array" instead of "type": "object". All record lexicons use "signatures" (not "signatureData") as a direct ref to this array type.

Before: record.signatureData.signatures[0] (extra nesting via wrapper object)
After: record.signatures[0] (flat, matches the ATProto Attestation Spec)

Generated TypeScript:

// list.ts — now a type alias, not an interface
export type Main = (
  | $Typed<AppCertifiedSignatureInline.Main>
  | $Typed<ComAtprotoRepoStrongRef.Main>
  | { $type: string }
)[]

// activity.ts — flat property
export interface Main {
  // ...
  signatures?: AppCertifiedSignatureList.Main
}

Files changed: 26 files — the list.json lexicon, proof.json description fix, all 20 record lexicons (signatureData → signatures), ERD, README, SCHEMAS.md, and changeset.

All checks pass: lint, typecheck, build, 11/11 tests.

Sent to Nick:

Hey, couple more questions about the attestations spec before I forget!

Remote attestations aren't actually signatures, right? This seems a little odd to me, because

1. it means you can have `signatures[0]` being a strongRef to a non-signature, and
2. inline attestations have much stronger integrity guarantees than remote ones thanks to the signature

Or am I misunderstanding? Thanks!

I also find the term "proof" a bit of a misnomer because an attestation is really just a claim not a hard proof of anything.

@aspiers

I agree that we can use "array" type directly for a "definition", but my claim was for a "lexicon". You can not define a lexicon that has type "array" directly.
Defining a definition was not what we needed (as I thought earlier), because if we defined a lexicon instead, we can store the signature list in a record which we can reference to, later in other records.

But as I write the comment, I realize signatures would generally be different for all these records, so there doesn't stand any scenario where we might need to store the signature list in a record and then reference it.
Did that make sense?

Moreovere, if you still find a use case (I couldn't) where we might need to reference only the signature list so that it can be referenced in other records, than we need to get back to the lexicon definition.

Do all these schemas really need the signatures? Or should we limit it to those where we will actively use them?

@aspiers is this also something that we want to add to this lexicon update? Is this mostly done? (I haven't analyzed the approach myself really)

I resolved my remaining concerns with Nick. I think we have a straightforward plan for the way forward with this - it's probably already mostly ready and just needs rebasing. I definitely think we want to include this, ideally as part of the current round of updates, although it's a non-breaking change so could be added in a fast follow-up 1.1.0 release if necessary.

"array" directly. Defining a definition was not what we needed (as I thought earlier), because if we defined a lexicon instead, we can store the signature list in a record which we can reference to, later in other records.

But as I write the comment, I realize signatures would generally be different for all these records, so there doesn't stand any scenario where we might need to store the signature list in a record and then reference it. Did that make sense?

Moreovere, if you still find a use case (I couldn't) where we might need to reference only the signature list so that it can be referenced in other records, than we need to get back to the lexicon definition.

Sorry @satyam-mishra-pce I missed these good points before due to the craziness of Vancouver. I think you are right. We don't have any immediate need for a lexicon which is purely a signature list, but if we ever needed it in the future it would be easy to construct using the def we're adding here. That said, I wonder if we should avoid putting it in app.certified.signature.list because that makes it look like a normal lexicon. Maybe app.certified.signature.defs#list is better. I will do a quick bit of research into that.

Spec-conformance pass

Audited the signature lexicons against the upstream ATProtocol Attestation Specification and tightened our wording from "inspired by" to a real conformance claim. Documenting the decisions here since several earlier design choices turned out to be unjustified or actively misaligned.

What changed

1. Removed signatureType from app.certified.signature.inline. The original PR carried an optional JOSE-style algorithm tag (ES256, ES256K, Ed25519). The spec has no such field — by design, the algorithm is canonically derived from the multicodec prefix of the publicKeyMultibase on the verification method that key resolves to. A separate tag is redundant in the happy path and a downgrade-attack vector in the adversarial path (an attacker could set signatureType: "ES256K" while key points at a P-256 method). Spec verifiers correctly trust the multicodec, so the field added nothing and could disagree with the canonical source. Now removed.

2. Dropped Ed25519 from the algorithm story altogether. EdDSA isn't excluded by normative MUST/SHALL language in the spec, but the spec's signing primitive is ECDSA + BIP-0062 low-S, and its multicodec→curve table only covers 0xE701 (K-256) and 0x1200 (P-256). An Ed25519-signed record would be schema-valid but unverifiable by any spec-conforming verifier — 0xED has no spec-defined branch. Generally, Ed25519 is widely used in did:key, SSH, sigstore, JOSE/JWT (EdDSA), and some COSE/WebAuthn paths — but not in @atproto/crypto, not in spec verifier pseudocode, and not in passkeys (passkeys are ES256 / P-256). Keeping it in knownValues was just a forward-looking gesture with no concrete Hypercerts use case. Dropped.

3. Removed the maxLength: 100 cap on the signatures array. Re-read the original commit, PR design notes, and CodeRabbit summary: no rationale was ever given for the bound. Spec doesn't restrict array length. Cap dropped.

4. README rewritten to claim spec conformance explicitly: signed input is the 36-byte CIDv1, low-S ECDSA per BIP-0062, $sig repository binding for cross-repo replay defense, and a short signing/verification summary. Dropped the JOSE algorithm-identifiers table since the field it documented is gone.

5. Changeset and PR-description language updated: "inspired by" → "conforms to" / "implements". This is the actual claim now, not a soft attribution.

What I did not change

• signatureType removal is breaking to the unreleased PR shape, not to any published consumer. Since this PR hasn't shipped, treating it as part of the same minor bump rather than introducing a separate breaking-change exit ramp.
• The note and createdAt fields on app.certified.signature.proof stay. Spec only requires cid, but explicitly allows additional application-specific metadata on proof records.
• app.certified.link.evm exclusion stays — its EIP-712 wallet-ownership proof is the right integrity primitive for that DID↔wallet semantic.

Audit clean against the spec

Open questions / follow-ups welcome.

Re: my earlier comment about whether to move the list definition into a defs lexicon — this is already done. The shared list lives at app.certified.signature.defs#list and all 19 record lexicons reference it via that path. Closing that thread out.

@coderabbitai review

@s-adamantine and crew
I just came across your work after applying for some maearth.com funding and i am really impressed!

I am trying to understand where are the private keys actually stored, and how can an app use certified.app or ePDS to offer login in a way that the user can maintain local-first private keys?

Maybe I am missing something, but i don't see that in the docs (yet), so i'm asking here as its the most relevant thread i found so far.

Context: I develop local-first ipfs based apps, so i am very familiar with the crypto primitives and did system you are using, and would love to collaborate and/or rely on the certified stack as long as each agent can generate and own the private keys.

Hi @gotjoshua thanks for your interest! Firstly please note this PR is superseded by #219.

Secondly, we don't yet have any infrastructure to allow users to store local-only private keys, or even specify where private keys should live. This lexicon schema extension is just the foundation layer providing somewhere for attestation signatures to live.

Passkeys and crypto wallets are obvious candidate solutions for this, as we certainly don't want to badly reinvent wheels, especially when storage of private keys is such a security-sensitive matter. However see #217 for some of the challenges around using crypto wallets.

Like you we are very keen on the idea of adding support for users to login and attest to things using their own self-custodied private keys, and have already done some design in these areas. But I think we have some other urgent work to finish before we can go too much deeper into this.

thanks @aspiers

don't yet have any infrastructure to allow users to store local-only private keys

ok, but does that mean that the certified servers store the private key associated with each did they create?

Yes this is how almost every PDS in the ATmosphere currently works. E.g. if you sign up for an account on bsky.social, you don't get given a private key to store in the browser or in a wallet.

thanks for the clarification @aspiers !

so its a bit like a "custodial" crypto wallet situation. users trust the app servers to keep the keys and to sign on their behalf, true?

have you looked into UCAN at all?

Yes it's similar to that but users have the option to set a recovery key and migrate their account elsewhere. Yes we are familiar with UCAN. Happy to discuss further but I recommend joining the Hypercerts Telegram community and/or filing separate GitHub issues, as this PR is already closed and we're getting a bit off-topic now ;)