Bluesky Handle Registrar

Contents

1. What is this?
2. Backend
3. Registering
4. Requirements
5. Installation
6. FAQ

---

What is this?

This is a collection of NodeJS Applications that Allow you to host a web-form, which people can fill out to register a bluesky handle on your domain. This also allows users to customize where https://handle.domain.com redirects, either a Custom URL or Their Bluesky Profile.

Example

You can see what it would look like in practice, HERE!

How does it work?

When Bluesky Verifies any given handle, it uses one of two methods to verify.

DNS Record

In this example, we want to verify the handle "furo.lucario.social". Our Domain is "lucario.social" and our handle is "furo", so Bluesky Checks for a TXT Record at "_atproto.furo.lucario.social" which should return a DID value, that points to a users account. If the request is successful and the DNS Record exists, your handle is verified! :D But this is not the Verification method we are interested in!

Text File

An alternative to the DNS Record check, is a simple web-request! Let's keep our example handle of "furo.lucairo.social", and say that the DNS Record Check failed, what does bluesky now? It sends a API-Request to https://furo.lucario.social/.well-known/atproto-did, and expects a given DID to be returned. At it's simplest, the code for this would look like this:

app.get('/.well-known/atproto-did', (req, res) => {
  res.status(200).send("did:plc:theDIDgoesHere");
}

But You want to let people register their own handles and use your domain for that! How could that work? The answer? Databases!

Backend (scary)

Inside the backend, we have a couple of endpoints, but most importantly these:

• / (root)

The Root Path is used to redirect people to the their handle redirection target URL, or simply their bluesky Profile

• /handle

This serves the Form to Register a handle

• /redirect

This serves a form to Setup where the https://handle.domain.com URL redirects.

• /debug

This serves a Debug Page to View Registrants' data and modify it.

• /api/register

API Endpoint To Register

• /.well-known/atproto-did

Bluesky Endpoint that serves a given handle's DID value

• /api/public/registrants

API Endpoint that serves all registrants that have been verified.

• /api/getDataByUser/:username

API Endpoint that serves all users Handles that match the username.

• /api/getDataByDid/:did

API Endpoint that serves all users that match the DID.

• /api/getDataByDomain/:domain

API Endpoint that serves all users' data that match the given domain.

• /api/getDataByHandle/:handle

API Endpoint that returns a user that matches the handle.

Registering

When a user Registers a handle, they have to input their desired handle, an E-Mail, and their Bluesky Account DID. The server has a string array for "Pure" and "Reserved" Handles.

Pure Handles

A Pure handle is any handle where the handle reflects a popular object's name, or a dictionary word, such as "Lucario" or "Tree".
These handles require manual Verification by you, something you can do via the /debug endpoint.

Reserved Handles

Do you have friends? Surely you'd like to reserve them some handles! To make sure nobody registers with a handle that should belong to your friend,
the server refuses to let people register a reserved handle.

How does Verification Work?

Internally, every user has a State.

V = Verified
NV = Not Verified
V_F = Verified Pure Handle
VR = Verification Rejected
VR_F = Pure Handle Verification Rejected
PENDING = For Debug Purposes

When a user registers a Non-Pure handle, their handle's state is automatically set to "V".
When a user registers a Pure Handle, their handle's state is set to NV.

The server ONLY Responds to any endpoint requests with users that are either in the state "V" or "V_F".
To manually Verify a User, Open the /debug endpoint, find your target user,
and Click the Pen Icon and Change their state to "V_F".

What about Redirects?

Redirects are a neat Feature! Since They technically register the subdomain from you,
you can let them customize where https://theirHandle.YourDomain.com redirects!
That's what the /redirect endpoint is for!

When Setting up a Redirection, you must run the nodeJS application inside /BlueskyDMer/index.mjs!
This nodeJS application is not public,
and it's purpose is to DM Users their Unique 6 digit code to verify that THEY want to change the handle.

Requirements

• You NEED to have a Wildcard SSL Certificate!!!!
• NodeJS 20.12.1
• NPM

And These Node Packages on both NodeJS Apps:

• express
• path
• cookie-parser
• sqlite3
• axios
• util
• dotenv
• axios
• url
• @skyware/bot

To install Node Packages, simply run npm install <package name>.
To Get a Wildcard SSL Certificate, follow this guide!
To Purchase a domain, you can find domains for sale Here!
To point the port 80 to your NodeJS Application Port, follow this guide!

Installation

How do you install? Good question!

1. Download the latest Release
2. Extract Into Any Folder on your Server
3. Open The Root Folder
4. Open index.mjs
   1. Edit the "BACKEND_PASSWORD" value to a very strong password!
   2. Edit the "secretKey" value to your Google Captcha Secret Key
   3. Edit the "reservedUsernames" to set up some Pure Handles.
   4. Edit the "reservedH" array to set up some Reserved Handles.
5. Open The "BlueskyDMer" folder
6. Open index.mjs
   1. Edit the "secretKey" value to your Google Captcha Secret Key
   2. Update the Cridentials to your Auht Bot
   3. Update the botDID value to be the DID of your Auth Bot
   4. Inside the "/api/StoreUserSecret/" endpoint, update the Authorisation Header sent to reflect your "BACKEND_PASSWORD".
7. Open root/public/server/scripts/name_claim.js and edit the "FAQ" fields and other strings, that reference "YOUR_EMAIL_HERE"
8. Now run index.mjs inside the root folder and inside the "BlueskyDMer" folder using node index.mjs!
9. You're all set up! visit http://localhost:62008/handle to view your Form

Edit the Frontend

The frontend's files are located inside /public/server BE CAREFUL! the /public/server/scripts and /styles are public folders, and any files inside them can be requested at all times.

FAQ

Q: When Trying To fetch the /debug page, i get a popup saying "Unauthorized"!
A: Create a new token in your browser, the name will be "dev_token" and the value will be your BACKEND_PASSWORD. The path needs to be /debug, and the expiration date you can set as something in the far future!

This is my very first ever GitHub project! Please Give me feedback! :D