Docs
Docs menu

Accounts and sign-in

Invite people, manage passwords and roles, let people sign in with AT Protocol, choose who may join, and pick the node's host identity.

People sign in to a node in one of two ways:

  • Handle and password. An admin invites them, and the node gives them a did:key identity whose key it keeps.
  • AT Protocol account (a Bluesky account, or any other PDS). They bring their own did:plc, and the node keeps no key for it.

Either way, a person on the node is a member or an admin. Being a member or admin of the node gives no access to anyone’s repositories: that comes from owning a repo, belonging to an organization, or being added as a collaborator. See Organizations and access.

MemberAdmin
Create repos and organizations, add runners for themselvesyesyes
Invite people, change roles, issue reset linksyes
Decide who may join through AT Protocolyes
Connect GitHub, see everyone’s runnersyes
See private repos they weren’t added tonono

Admins don’t see private repositories unless they add themselves as a collaborator, which shows in the repo’s collaborator list. Whoever runs the node can still read its disk.

The first admin#

A new node prints a setup link to its log on every start until it has an admin. Whoever opens it picks the first admin’s handle and password. See Create the first admin.

Invite people#

Admins invite people from the People page (account menu → People):

  1. Under Invite someone, type a Handle and choose Member or Admin.
  2. Click Create invite link.
  3. Send the link to the person. It works once, for 24 hours, and isn’t shown again.

They open it, set a password of at least 12 characters, and click Set password and sign in. Moru sends no email, so the link reaches them however you choose.

The same from the command line, which prints the link:

moru-node create-user jon            # a member
moru-node create-user mira --admin   # an admin

create-user uses MORU_PUBLIC_URL (or --url) for the link’s address. In the container image that’s already set.

Each person in the list shows whether their invite is pending, how many sessions and access tokens they have, and their DID. Make admin and Make member change the role; the person is signed out when it changes.

Handles and organization names share one namespace, so a handle can’t be an existing organization’s name.

Passwords and sessions#

  • Changing a password: in Account, under Password.
  • Forgotten passwords: an admin clicks Reset link next to the person on the People page. Their password and sessions stop working, and the new link lets them set a password. There’s no self-service reset.
  • Every admin locked out: run moru-node create-user mira --reset on the node. It prints a new link for that account and revokes its password and tokens.
  • Sessions last 12 hours. Sign out everywhere in Account ends all of a person’s sessions.
  • Failed sign-ins: after 5 failed passwords for one handle from one address, that address is locked out for that handle for 15 minutes. Behind a reverse proxy, set MORU_TRUSTED_PROXIES so the node sees each client’s address. See Configuration.

For git over HTTPS, people use an access token from Account → Access tokens for git as the password, with any user name. A token lasts up to 366 days (90 by default) and can be limited to one repo. A token reaches only what its person can read or write at the time of each request.

Tokens for scripts#

moru-node create-user-token prints a token for a person, for scripts and tests:

moru-node create-user-token mira --ttl 7d

It also prints a sign-in link. If the handle has no account, the command creates one as an admin, with a did:key. To give someone a normal account, use create-user instead.

Sign in with AT Protocol#

People can sign in with their own AT Protocol account, as long as its DID is a did:plc (did:web identities can’t sign in). On the sign-in page, they enter their handle or DID under Sign in with your AT Protocol account and approve the request at their PDS.

Once they’re let in (see who may join), the sign-in writes one record, com.moruforge.host.binding, to their AT Protocol repo. It authorizes this node’s host to sign for them. The node creates a member account for their DID, and keeps nothing of the OAuth session: it revokes it once the record is written.

What the node needs for this:

  • An https public URL. With one, the node is a confidential OAuth client. It serves its client metadata at /oauth-client-metadata.json, which PDSs must be able to fetch, and signs with keys/oauth-client.key, which it makes on first use. Back that key up with the others.
  • Without https, the node acts as a loopback client, which AT Protocol allows for development only. The PDS sends the browser back to http://127.0.0.1:<port>/api/v0/atproto/callback, where the port is the one the node listens on, whatever MORU_PUBLIC_URL says. So sign in from a browser on the node’s own machine, at http://127.0.0.1:<port>. A node on a LAN over plain HTTP can’t offer AT Protocol sign-in.
  • Outbound HTTPS. People’s DIDs resolve at the PLC directory (MORU_PLC_URL, by default https://plc.directory). Sign-in fetches whatever a person’s DID document and handle point to, but only https URLs at public addresses, with no proxy and no redirects.

Limits: each client address may start 10 sign-ins per 15 minutes, and at most 16 run at once.

Who may join#

New people on the People page sets what happens when someone signs in with an AT Protocol account the node hasn’t seen:

  • Ask to join (the default): their first sign-in files a request and writes nothing to their account. Admins see a badge in the header and on People, and click Approve or Decline. An approved person signs in again to get their account. A declined person is told so each time they sign in, until an admin approves them or clicks Forget (then they may ask again).
  • Open: anyone with an AT Protocol account gets a member account the first time they sign in.
  • Closed: new AT Protocol identities are refused. People who already have an account still sign in, and approved requests still get in.

Invites and linking work in every mode. Moru doesn’t notify people when you decide, so tell them.

Linking a password account#

Someone with a password account can link it to their AT Protocol identity in Account, under Link your AT Protocol identity: they enter their AT Protocol handle or DID and their current password, then approve at their PDS. Their handle and password on the node stay the same. Their identity becomes the AT Protocol DID, and repos record that the old did:key is now the new one, so their history moves with them.

Host identity#

Every node signs as part of a host: the identity that certifies the node’s key in each repo, so signatures on changes, comments and attestations can be checked anywhere, offline. host.json in the data directory records which kind of host the node has. There are two:

  • key, offline (the default for a new data directory). The host is the node key’s own did:key. Nothing is registered anywhere. It can’t be rotated, and can’t be moved to another host with trust intact.
  • plc, a did:plc registered with the PLC directory. On the first serve the node makes two keys in keys/host/ (a rotation key and a signing key) and registers a DID naming MORU_PUBLIC_URL as its moru service. It needs MORU_PUBLIC_URL, and won’t start if the directory can’t be reached the first time. Later starts refresh the DID’s log, and keep the cached one if the directory is down. Other commands never contact the directory.

To use plc, set it for the very first start:

MORU_IDENTITY=plc MORU_PUBLIC_URL=https://moru.example.com moru-node --data /var/lib/moru serve

moru-node host prints the host’s DID, its kind and the node’s DID, and for a did:plc host its current signing key. --refresh fetches the DID’s log first, as serve does. People see the host on their Account page.

keys/host/ and host.json are the host. Back them up with the rest of the data directory (moru-node backup includes them), and guard keys/host/rotation.key above everything: whoever holds it controls the DID. Change the DID document rarely, for a key rotation or a new public URL, not as routine: each change adds a snapshot to every repo the node writes to.

If you lose the host identity#

Restore host.json, keys/host/ and keys/node.key from a backup whenever you can. If you can’t, the node makes a new host on its next start, with a new DID:

  • Old signatures still load. The old host’s record stays in every repo that has it.
  • People who signed in with AT Protocol have to sign in again, so their PDS authorizes the new host.
  • People with password accounts sign with their own keys and aren’t affected, as long as keys/users/ survived.
  • Attestations signed with the old node key are untrusted until you add the old host’s DID, or the old node key, to trusted-attesters.json. Until then, merge rules that depend on them refuse the change. See Provenance.
Command menu
Search for a page, repository, change or request, or run a command