PRD: Finite Identity Authority for VIP Email, NIP-05, and Principal Resolution #3

Problem Statement

Finite tools and products need one shared way to understand who someone is. Today the local finite-identity crate owns the shared on-disk Nostr key, while reusable email proof, NIP-98 control-plane auth, email-only collaborator behavior, and email-to-native linking live in Finite Sites. Finite Brain needs the same identity capabilities, and Finite VIP onboarding needs a first-class path where proving localpart@finite.vip binds that name to a Nostr public key and publishes the matching NIP-05 Name.

Without a dedicated Identity Authority, each product will keep reimplementing email proof, Nostr request signing, email-only collaborator fallback, Principal Resolution, and NIP-05 behavior. That creates inconsistent onboarding, fragile migrations, and unclear ownership of product permissions versus identity state.

Solution

Make Finite Identity the source of truth for shared identity. The existing local identity contract remains non-custodial: clients generate, import, load, and sign with Local Identity Keys. A new Identity Authority owns public identity state: Finite VIP Emails, NIP-05 Names, Email Challenges, Native Principals, Email-Only Principals, Principal Links, Principal Resolution, Disabled Bindings, and the NIP-05 Endpoint for the Finite VIP Domain.

The v1 user experience is: a user proves localpart@finite.vip, the client loads or generates the Local Identity Key, the redeem request is NIP-98 authenticated by that key, and the Identity Authority creates an immutable v1 binding from the Finite VIP Email to the Native Principal. The Identity Authority then serves /.well-known/nostr.json?name=localpart for finite.vip, returning the matching lowercase hex public key in the NIP-05 names map.

Finite Sites and Finite Brain continue to own their Product Grants and product-specific permissions. They consume Finite Identity through an HTTP Identity Contract for Principal Resolution and may keep short-lived Resolution Caches that fail closed when missing, expired, or uncertain.

User Stories

1. As a Finite VIP user, I want proving my finite.vip email to bind that same email-shaped name to my Nostr key, so that I have one identity across Finite.
2. As a Finite VIP user, I want my NIP-05 Name to be identical to my Finite VIP Email, so that the identity I share with humans is the identity Nostr clients can verify.
3. As a Finite VIP user, I want my Local Identity Key generated and stored locally, so that the Identity Authority does not custody my secret key.
4. As a Finite VIP user, I want re-proving the same email with the same key to be idempotent, so that retrying onboarding is safe.
5. As a Finite VIP user, I do not want a different key to silently take over my already-bound NIP-05 Name, so that v1 does not accidentally define recovery or product data migration.
6. As a user who loses a key, I want Recovery to be explicitly designed later, so that key replacement does not unexpectedly move or strand product data.
7. As a Nostr client, I want https://finite.vip/.well-known/nostr.json?name=alice to return alice mapped to a lowercase hex public key, so that standard NIP-05 verification works.
8. As a product user, I want to grant access to an email address before the recipient has a native identity, so that collaboration stays low-friction.
9. As an invited collaborator, I want to prove an Invited Email and work as an Email-Only Principal, so that I can participate before adopting a Native Principal.
10. As an invited collaborator, I want an email-only access path to be reusable across Finite products, so that Sites and Brain do not require different onboarding rituals.
11. As a collaborator who later creates a Native Principal, I want my existing email-shaped Product Grants to resolve to my native key, so that access follows identity without requiring every product to rewrite rows immediately.
12. As a Sites owner, I want Sites to keep owning site, project, git, and sharing permissions, so that identity extraction does not blur product ownership.
13. As a Brain owner, I want Brain to grant access to Native Principals or Invited Emails, so that Brain sharing can use the same collaboration model as Sites.
14. As a product maintainer, I want Products to store Product Grants as entered, so that audit trails remain human-readable.
15. As a product maintainer, I want Principal Resolution to decide whether a caller satisfies an email-shaped grant, so that identity links work without brittle migration jobs.
16. As a product maintainer, I want the Identity Authority to be the source of truth, so that Sites and Brain do not implement competing identity stores.
17. As a product maintainer, I want short-lived Resolution Caches to be allowed, so that high-traffic reads can avoid unnecessary latency while failing closed on uncertainty.
18. As a CLI user, I want product CLIs to expose product-shaped wrappers around Identity Client Flows, so that I can onboard inside fsite or fbrain workflows.
19. As an operator, I want a standalone identity CLI to be possible, so that debugging and production inspection do not require a product CLI.
20. As an operator, I want read-only inspection of Finite VIP Email, NIP-05 Name, Principal Link, and Email Challenge audit metadata, so that production state can be understood.
21. As an operator, I want to disable an abusive binding without deleting history, so that production has a safety brake without creating v1 Recovery.
22. As an operator, I do not want v1 operator actions to reassign names or migrate product data, so that Recovery remains an explicit future design.
23. As a developer, I want Email Challenges to be opaque, short-lived, single-use, and hashed at rest, so that email proof is simple and replay-resistant.
24. As a developer, I want Binding Proof to require both an Email Challenge token and NIP-98 authentication, so that the requester proves control of the email name and the target Nostr key.
25. As a developer, I want the NIP-05 Endpoint served directly by the Identity Authority in v1, so that freshness and tests stay centralized.
26. As a developer, I want mail delivery behind a Mailer Adapter, so that dev outbox and production providers share the same identity semantics.
27. As a developer, I want third-party NIP-05 resolution documented as future work, so that v1 does not accidentally trust arbitrary external domains.
28. As an agent implementing a slice, I want the domain language and ADRs to be explicit, so that AFK implementation follows the same model.
29. As a maintainer, I want the earlier NIP-05 proposal to remain visible as prior context, so that the new identity-owned design is understood as a broader successor.
30. As a Finite product user, I want one identity to work across Sites and Brain, so that I do not repeat onboarding or wonder which product owns my identity.

Implementation Decisions

• Finite Identity owns the Identity Authority and identity-owned storage.
• The Identity Authority exposes an HTTP Identity Contract for production product integrations.
• Rust modules may provide shared domain types, client helpers, and internal engine/store implementations, but products must not directly mutate identity storage.
• The Local Identity Key remains non-custodial. The Identity Authority never generates, stores, or returns user secret key material in v1.
• Finite VIP Email means localpart@finite.vip; the NIP-05 Name is exactly the same string in v1.
• The Finite VIP Domain is finite.vip for v1.
• The Identity Authority serves the Finite VIP Domain NIP-05 Endpoint directly in v1.
• NIP-05 support starts with names only; relay metadata is out of scope for v1.
• Binding a Finite VIP Email to a Native Principal requires a Binding Proof: valid Email Challenge token plus a NIP-98-authenticated request signed by the target Local Identity Key.
• Email Challenges are opaque random tokens, hashed at rest, short-lived, and single-use.
• Finite VIP Email bindings are immutable in v1 except for idempotent re-proving with the same key.
• Recovery, key replacement, and product data migration after key loss are out of scope for v1.
• A Disabled Binding keeps audit history but is no longer served or resolved.
• Principal is the shared identity subject; a Principal is either Native or Email-Only.
• An Invited Email can become an Email-Only Principal even when the address is not on finite.vip.
• Only Finite VIP Emails can become Finite-owned NIP-05 Names in v1.
• Third-Party NIP-05 Names are future work and are not trusted as product grantees in v1.
• Products own Product Grants and store grantees as entered.
• Principal Resolution decides whether a caller satisfies a Product Grant.
• Products may keep short-lived Resolution Caches, but the Identity Authority remains the source of truth and uncertain authorization fails closed.
• Mail delivery is handled by a Mailer Adapter selected by deployment configuration.
• Product CLIs wrap reusable Identity Client Flows; a standalone identity CLI is allowed but not required before first product integration.
• V1 operator actions are inspect and disable, not reassign, recover, or migrate.
• This PRD supersedes the narrower direction in Contract v1.1 proposal: NIP-05 identification layer #1 by making Finite Identity the owner of the full reusable identity authority, while preserving the principle that NIP-05 is identification and Nostr signatures remain the auth primitive.

Testing Decisions

• The highest-value test seam is the Identity Contract exercised through HTTP against temporary identity-owned storage, a fake Mailer Adapter, and a test clock.
• Tests should assert external behavior: request an Email Challenge, redeem a Binding Proof, publish and fetch a NIP-05 Name, resolve Principals, reject conflicting bindings, and disable bindings.
• Tests should not assert private table layout or internal helper boundaries except where storage invariants are only observable through persistence.
• NIP-98 tests should verify URL, method, body hash, freshness window, and signer pubkey behavior at the identity contract seam.
• NIP-05 tests should verify standard names JSON, lowercase hex pubkeys, finite.vip localpart constraints, disabled bindings, and unknown names.
• Email Challenge tests should verify token hashing, expiry, single-use redemption, email mismatch rejection, and rate-limit behavior where implemented.
• Principal Resolution tests should verify Native Principal, Email-Only Principal, Principal Link, Product Grant satisfaction, short-lived cache semantics where product adapters exist, and fail-closed behavior.
• Product integration tests in Sites and Brain should verify that products consume identity answers correctly. They should not re-test token hashing, NIP-05 JSON construction, or NIP-98 internals.
• Prior art exists in Finite Sites: NIP-98-signed API calls, email token redemption, email-only keys, native email linking, and e2e tests around auth flows.

Out of Scope

• Key-loss Recovery.
• Rebinding a Finite VIP Email or NIP-05 Name to a different pubkey.
• Product data migration from an old key to a new key.
• Server-side custody of user secret keys.
• Third-party NIP-05 resolution and trust policy.
• NIP-05 relay metadata.
• Arbitrary alternate handles, display names, or non-finite.vip Finite VIP Domains.
• Product-owned permission rewrites as a required migration step.
• Full standalone identity CLI as a prerequisite for first product integration.
• Closing or rewriting existing product-specific authorization systems beyond their identity integration points.

Further Notes

The domain glossary and ADR set for this plan have been drafted in the local finite-identity checkout. The key decisions are: immutable v1 bindings, Identity-owned Principal Resolution, authorization-time Principal Links, Identity Authority plus short-lived Resolution Caches, non-custodial Local Identity Keys, direct v1 NIP-05 serving, Binding Proof via Email Challenge plus NIP-98, opaque one-time Email Challenges, product consumption over HTTP, Product Grants stored as entered, v1 grantee limits, Mailer Adapter delivery, product CLI wrappers, and inspect/disable-only operator actions.