hitomi
A desktop BlueSky client built using Rust and `iced`. tangled.org/nateledford.com/hitomi
rust-gui bluesky rust iced
Star
Fork
Watch
hitomi PRODUCT.md
3.7 kB · 75 lines
Markdown
at main

Product #

Platform #

macOS

Users #

Personal Bluesky users signing in on their own computer to use a native desktop client.

Product Purpose #

Hitomi is a native Bluesky desktop client. Its initial user journey lets a person authenticate with their existing Bluesky account through the system browser and return to an authenticated desktop application.

Positioning #

A personal macOS-native Bluesky client that follows system appearance, window, control, and interaction conventions while using standards-compliant public-client OAuth on the user’s computer rather than collecting Bluesky passwords.

Operating Context #

Hitomi is macOS-only. Users enter a Bluesky handle in the desktop app, approve authorization in their configured system browser, and return through the exact com.nateledford.hitomi:/oauth/callback LaunchServices callback. A bounded in-process callback bus delivers the URL to the active Iced login operation; dynamic loopback callbacks exist only in deterministic test support.

Capabilities and Constraints #

  • The UI must remain responsive: finite asynchronous work uses Iced Task; it must not block the UI thread.
  • One application-owned OAuth coordinator owns discovery, PAR, callback correlation, token exchange, DPoP, refresh, revocation, and session policy.
  • atproto-oauth supplies only PKCE and DPoP primitives; it does not own workflow, transport, storage, refresh, or revocation.
  • One Security.framework Keychain record stores the replacement refresh grant and DPoP key material. Access tokens exist only in process memory.
  • OAuth state, issuer, and redirect targets require exact validation; PKCE, PAR, and DPoP protections must be preserved.
  • An outcome-unknown refresh is recovery-required and never reuses the old refresh token. Logout clears local credentials first and independently reports remote refresh/access revocation outcomes.
  • The product does not collect Bluesky passwords.
  • During internal dogfooding, native screen-reader accessibility is not a release criterion because Iced does not expose the required macOS accessibility tree. Visible STATUS, WARNING, and ERROR labels remain required; Hitomi must not claim native accessibility compliance until a durable presentation-layer solution is selected.

Localization #

en-US is the complete embedded source and default locale. Additional locales and locale selection are not exposed yet.

Brand Commitments #

The product is named Hitomi. It is a FOSS application for regular everyday users, not an enterprise, corporate, or commercial deployment.

Evidence on Hand #

  • Native Rust 2024 application using Iced (Cargo.toml, src/ui.rs).
  • Packaged application icon: assets/Hitomi.icns; assets/HitomiPlaceholder.svg is the only other visual asset and is not a broader binding visual-asset library.
  • Authentication architecture and constraints: docs/architecture/authentication.md.
  • OAuth redirect decision: docs/architecture/decisions/0001-oauth-redirect-client-metadata.md.
  • No testimonials, customer claims, benchmarks, pricing, licensing claims, or accessibility standard are recorded.

Product Principles #

  • Respect user-controlled, standards-compliant authentication.
  • Keep account credentials out of the application’s plaintext storage and diagnostics.
  • Keep external systems behind application-owned boundaries.
  • Keep the desktop interface responsive during network and storage work.
  • Favor a focused personal-client experience over enterprise scope.
  • Follow macOS appearance, window, control, and interaction conventions rather than carrying generic cross-platform chrome.