Update README

BUILDING.md

@@ -0,0 +1,163 @@
+# Prerequisites
+
+## Build system
+
+This project uses Meson, Ninja, and Cargo.
+
+We use Meson 1.5.0+. If your package manager has an older version, you can
+install a new version [using the pip module][meson-pip-install].
+
+There is currently no documented minimum support Rust version (MSRV), but 1.85+
+should work.
+
+[meson-pip-install]: https://mesonbuild.com/Quick-guide.html#installation-using-python
+
+## Package requirements
+
+- GTK4
+- gettext
+- libdbus-1
+- libssl/openssl
+- libudev
+- desktop-file-utils
+
+Using the web extension also requires `python3-dbus-next`.
+
+## Examples
+
+### Debian/Ubuntu
+
+```shell
+sudo apt update && sudo apt install \
+  # Build dependencies
+  curl git build-essential \
+  # Meson/Ninja dependencies
+  meson ninja-build \
+  # project dependencies
+  libgtk-4-dev gettext libdbus-1-dev libssl-dev libudev-dev \
+  # packaging dependencies
+  desktop-file-utils \
+  # web extension dependencies
+  python3-dbus-next
+```
+
+### Fedora
+
+```shell
+# Build dependencies
+sudo dnf groupinstall "Development Tools"
+sudo dnf install \
+  curl git \
+  # Meson/Ninja dependencies
+  meson ninja-build \
+  # project dependencies
+  gtk4-devel gettext dbus-devel openssl-devel systemd-udev \
+  # packaging dependencies
+  desktop-file-utils \
+  # web extension dependencies
+  python3-dbus-next
+```
+
+# For Installing/Testing
+
+If you are interested in installing the program, you can use `meson install` to
+install the details. (If you would like to test without installing, you can
+follow the [build instructions for development](#for-development) below.)
+
+```shell
+git clone https://github.com/linux-credentials/credentialsd
+cd credentialsd
+meson setup -Dprefix=/usr/local build-release
+cd build-release
+meson install
+```
+
+Note that since Meson is installing to `/usr/local`, it will ask you to use
+`sudo` to elevate privileges to install.
+
+## Running the installed server
+
+When using the installed server, systemd or D-Bus should take care of starting
+the services on demand, so you don't need to start it manually.
+
+The first time you install this, though, you must log out and log back in again
+for the service activation files to take effect.
+
+## Testing installed builds with Firefox Web Add-On
+
+Note: If you are testing the Firefox web extension, you will need to link the
+native messaging manifest to your home directory, since Firefox does not read
+from `/usr/local`:
+
+```shell
+mkdir -p ~/.mozilla/native-messaging-hosts/
+ln -s /usr/local/lib64/mozilla/native-messaging-hosts/xyz.iinuwa.credentialsd_helper.json ~/.mozilla/native-messaging-hosts/
+```
+
+# For Development
+
+```
+git clone https://github.com/linux-credentials/credentialsd
+cd credentialsd
+meson setup -Dprofile=development build
+ninja -C build
+```
+
+## Running the server for development
+
+To run the required services during development, you need to add some
+environment variables.
+
+```shell
+# Run the server, with debug logging enabled
+export GSETTINGS_SCHEMA_DIR=build/credentialsd-ui/data
+export RUST_LOG=credentialsd=debug,credentials_ui=debug
+./build/credentialsd/target/debug/credentialsd &
+./build/credentialsd-ui/target/debug/credentialsd-ui
+```
+
+## Testing development builds with Firefox Web Add-On
+
+If you are using the Firefox add-on to build, follow the instructions for
+development in [`webext/README.md`](/webext/README.md#for-development).
+
+# For Packaging
+
+There are a few Meson options to control the build that may be useful for packagers.
+
+```
+# list available options
+
+> meson configure
+# ...
+Project options    Default Value        Possible Values      Description
+-----------------  -------------        ---------------      -----------
+cargo_home                                                   The directory to
+                                                             store files
+                                                             downloaded by
+                                                             Cargo
+cargo_offline      false                [true, false]        Whether to
+                                                             perform an
+                                                             offline build
+                                                             with Cargo.
+                                                             Defaults to false
+                                                             to download
+                                                             crates from
+                                                             registries.
+profile            default              [default,            The build profile
+                                         development]        for Credential
+                                                             Manager. One of
+                                                             "default" or
+                                                             "development".
+```
+
+> TODO: rename `default` profile to `release` to reduce confusion.
+
+# Running Tests
+
+Due to some unknown reason, tests hang unless you pass the `--interactive` flag to Meson, available since 1.5.0.
+
+```
+cd build
+meson test --interactive
+```

GOALS.md

@@ -0,0 +1,71 @@
+# Goals
+
+The goal of this repository is to define a spec and implementation for clients
+(apps, browsers, etc.) to retrieve user credentials in a uniform way across
+Linux desktop environments.
+
+## Motivation
+
+Our primary motivation is to get passkey into the hands of users. Passkeys are
+growing as a powerful authentication mechanism for users. As the ecosystem
+becomes more mature, browsers are deferring access to passkeys to OS APIs on
+other platforms, like Windows Hello, Keychain on macOS and iOS, and
+Credential Manager on Android.
+
+On Linux, there is no OS API so handling passkeys is entirely up to the browser,
+which is at a disadvantage to the OS in terms of hardware access and desktop
+integration. This situation also requires each individual browser or application
+to reimplement the same features. We want to change that!
+
+## Direction
+
+Some high-level goals:
+
+- define an API to securely create and retrieve local credentials
+  (passwords, passkeys, security keys)
+- create and retrieve credentials on remote devices (e.g. via CTAP 2 BLE/hybrid
+  transports)
+- Provide a uniform interface for third-party credential providers
+  (password/passkey managers like GNOME Secrets, Bitwarden, Keepass, LastPass,
+  etc.) to hook into
+
+Some nice-to-haves:
+
+- Design a specification for a platform authenticator. I'm not sure whether this
+  needs to be specified, or whether it could be considered and implemented as a
+  first-party credential provider.
+- A security key manager (e.g., for setting security key client PIN)
+
+Some non-goals:
+
+- Fully integrate with any specific desktop environment. Each desktop
+  environment (GNOME, KDE, etc.) has its own UI and UX conventions, as well as
+  system configuration methods (e.g., GNOME Settings), which this API will need
+  to integrate with.
+  Because of the variation, we intend to leave integration with these other
+  components to developers more familiar with each of the desktop environments.
+  For now, we are using bare GTK to build a UI for testing, but any UI
+  implementation in this repository is for reference purposes. If anyone is
+  willing to do some of this integration work, feel free to contact us!
+
+- Create a full-featured password manager. Features like Password syncing,
+  password generation, rotation, etc. is not part of this specficiation. Other
+  password manager projects should be able to use this to make their credentials
+  available to the user uniformly, though.
+
+- BSD support. While we'd love to help out all open desktop environments, we don't
+  know enough about any BSD to make it useful for them. Hopefully, the design
+  process is transparent enough that someone else could design something that
+  works for BSDs.
+
+## Progress
+
+- April 2025: Added web extension for testing in Firefox.
+- March 2025: Integrated libwebauthn to support USB authenticators.
+- May 2024: Met with developers in GNOME and systemd to design internals for
+  securely storing device credentials.
+- Jan 2024: Defined the [scenarios](/doc/historical/scenarios.md) that we expect this
+  API to cover. We are working on extracting [API methods](/doc/api.md) required to
+  implement the interactions between the client, portal frontend, portal backend,
+  machine and mobile devices. Once that is done, I intend to convert the API into
+  a [portal spec](/doc/historical/design-doc.md), making it fit normal D-Bus/portal patterns.