mesh-catalog/modules/gnome-keyring/README.md

gnome-keyring

The secret service as a module (novox/hq ADR 0208, ADR 0102).

• Installs gnome-keyring (it brings gcr-4, whose ssh agent this uses), libsecret (the client library and secret-tool) and seahorse (the keyrings' manager, for the operator).
• Claims the mesh's node-secret-service seat (no verbs yet, ADR 0208 §2). It requires no display: the secret service is a D-Bus service, and a Wayland session uses the same module.
• Writes the PAM lines into the stacks, never over them (ADR 0102). Each is a marked block at the end of the file; every other line stays the distribution's.
  • /etc/pam.d/login: auth optional pam_gnome_keyring.so and session optional pam_gnome_keyring.so auto_start. The login manager's stack includes login, so the password typed at the login screen unlocks the login keyring, and the login session starts the daemon.
  • /etc/pam.d/passwd: password optional pam_gnome_keyring.so, so changing the account's password changes the keyring's, and the next login still unlocks it.
• Starts no daemon. PAM starts it at login, and D-Bus would if PAM had not.
• Names gcr's ssh agent socket for the session, in the xinitrc slot first: SSH_AUTH_SOCK is $XDG_RUNTIME_DIR/gcr/ssh. The agent itself is gcr-ssh-agent.socket, a user unit the package enables by preset.

Tools

None reads a secret. They ask the Secret Service for names, counts and lock states, and the agent for fingerprints.

tool	does
gnome_keyring_unlocked	the login and default keyrings, locked or not; whether the daemon runs
gnome_keyring_lock	lock a keyring now (login by default); unlocking stays the operator's
gnome_keyring_collections	every keyring: id, label, locked, item count, created, changed, default
gnome_keyring_ssh_keys	the agent's keys by fingerprint, size, type and comment

What it improves on what was found

• The desktop's login unlocks the keyring. Its /etc/pam.d/login had no keyring lines, so the keyring stayed locked after every login, and a script prompted for the password to unlock it. Both workstations now get the same lines.
• One daemon. The session's start ran gnome-keyring-daemon --start a second time, asking for an ssh component that gnome-keyring no longer has, and the window manager ran an unlock-prompt script. Both go.
• The session has an ssh agent. The found export SSH_AUTH_SOCK exported nothing: the second daemon printed no socket. The session's processes had no agent, although gcr's was listening.

The default keyring is not the login keyring

On both workstations, measured on 2026-10-04, the default keyring, where programs store new secrets, is a second keyring, Default_keyring. The login keyring holds one item at most. PAM unlocks only the login keyring. Another keyring opens with it only if its password is stored in the login keyring ("unlock automatically"). On the desktop the login keyring was locked and the default one unlocked, which the unlock-prompt script did.

After the first login with this module: gnome_keyring_unlocked shows both. If the default keyring is still locked, choose one, once, in seahorse:

• tick its unlock automatically when prompted;
• or move its items into the login keyring and make that the default.

Which keyring is the default is the operator's data, never the module's.

Blockers and a proposal

SSH_AUTH_SOCK belongs in the account's environment, and ADR 0203 cannot say it yet. The value is a path under the account's runtime directory (/run/user/<uid>). ADR 0203 forbids $ in a contributed value, and no ${machine:…} fact names that directory. So today the variable reaches only the X session and what it starts, through the xinitrc slot. An ssh login, the login shell's execute and the user manager's services do not get it.

Proposed: a machine fact ${machine:account-runtime-dir}, resolved like ${machine:account-home} from the account's uid. The variable then becomes an environment contribution:

environment.variables.SSH_AUTH_SOCK = ${machine:account-runtime-dir}/gcr/ssh

The slot contribution then goes. That is a progressive insight on ADR 0203, or a small record of its own. It changes the controller's machine facts, not this module's shape.

User-scoped units (mesh-host #72). gcr-ssh-agent.socket and gnome-keyring-daemon.socket are enabled by the package's presets on both workstations, and nothing in the mesh asserts it. Once user units ship, this module should declare both enabled.

What it leaves as found

• The keyrings themselves (~/.local/share/keyrings/): the operator's data, never touched.
• ~/.config/i3/unlock-keyring.sh, the unlock-prompt script.

Migration (ADR 0182)

1. On the laptop, /etc/pam.d/login already has the two lines outside any block. After the first push they are there twice. Delete the two hand-written ones, outside the # BEGIN mesh block.
2. Once the xorg module writes the session's start, delete from your own part of ~/.xinitrc the eval $(/usr/bin/gnome-keyring-daemon --start …) line and the export SSH_AUTH_SOCK after it.
3. Once the i3 module carries the main configuration, its exec … unlock-keyring.sh line is gone. Delete ~/.config/i3/unlock-keyring.sh.
4. On the desktop, log in again after the first push. The keyring is unlocked by the login from then on.

Blockers

• node-secret-service and the xinitrc slot are ADR 0208's. Until the controller knows them, mctl reads them as unknown.
• The environment fact above, and user-scoped units (mesh-host #72).