CloudFinger

A WebFinger Responder

This is a webfinger service, intended to run locally or as a Cloudflare Worker, consumes a list of mappings from an web identity to another identity as used by services like Mastodon.

The mappings are store in a Cloudflare KV Store and should be manipulated via the Cloudflare Dashboard (for now).

This service exposes a very simple (read-only) API and lacks a frontend. I will be adding the rest of the API next.

Features

• Stores mappings as KV pairs, where the key the web identity like idisposable@github365.com and the value is the destination identity like @idisposable@mastodon.world. Example
• Exposes a public endpoint at /.well-known/webfinger/ that acts like a normal webfinger server and responds to the normal ?resource=acct:identity parameter.
• Returns a webidentity like any normal Mastodon Identity server without the entire infrastructure of a Mastondon install.
• Exposes a public health endpoint at /.well-known/webfinger/hello that returns the worker name and version number
• Exposes a public status endpoint at /.well-known/webfinger/status that returns the number of mappings in the KV store
• Exposes a secured (via preshared auth token) API at /api/ that current only allows listing of the mappings API to come

Setup

• Clone this repository
• npm install to get all the packages installed
• Login to the CloudFlare Dashboard
• Do a wrangler whomai to ensure that wrangler has access to your CloudFlare account
• Create a cloudfinger Worker (whether you intend to run locally or not)
• Randomly generate some Bearer token to secure the API, perhaps with something like openssl rand -base64 32. Make sure you keep this value somewhere safe as we need to pass it as a Bearer token for any API-secured calls
• wrangler secret put AUTH_TOKEN and paste in that freshly generated token
• wrangler kv:namespace create webfinger to create the KV namespace for the webfinger
• Update the wrangler.toml file to have your namespace mapping's ID and replace what's there with the id shown in the previous step (Note: this isn't super secret, the ID is useless without the account ID)
• Lookup your CloudFlare account ID (this is account-level, NOT domain-level) from the Dashboard
• wrangler secret put CF_ACCT_ID and paste in the ID from above to store the CloudFlare account id for the API
• Provision a Cloudflare API token to write to it
  • On the dashboard right side, just below the account number, click API Tokens or just https://dash.cloudflare.com/profile/api-tokens
  • Create a token:
    • Either Quick start this this URL to prefill the form this far (thanks to James Ross @Cherry for this URL generator tool.)
    • Or By hand
      • Click Create Token
      • Scroll down to the Custom token section and click Get started
      • Fill in the Create Custom Token form:
        • Enter a name (for example cloudfinger)
        • In Permissions section
          • Choose Account
          • Choose Workers KV Storage
          • Choose Edit to allow the API to update values
    • continue either way
    • In the Account Resources section
      • Choose Include
      • Choose either All Accounts or the specific account you're building this worker for
    • In the Client IP Address Filter section, just leave things blank (would be nice if CloudFlare would allow you to lock it down to only your IPs and the CloudFlare Worker IPs... but not yet)
    • Leave the TTL section alone, we want the Token to last until revoked
  • Click Continue to summary to advance to the review screen
  • Click Create token to generte the token
  • Click Copy to get the token value on your clipboard (Note: you can copy/paste the curl command shown to validate your token, but remember that shell histories will record that token in the clear, make sure you elide it from your ~/.zsh_history or ~/.bash_history or you're risking leaking the token)
• wrangler secret put CF_API_TOKEN and the paste in the token from above
• That's the Wrangler Secrets, verify they have been setup with the right names (you won't be able to see the values, they're secret) with a wrangler secret list and you should see AUTH_TOKEN, CF_ACCT_ID, and CF_API_TOKEN
• Confirm in wrangler.toml that the default values are acceptable for: CF_API_ENDDPOINT, you can get the current version from the Cloudflare API page, which was https://api.cloudflare.com/client/v4 at the time this worker was developed
• Do a trial build with npm run build
• Deploy cloudfinger to Workers with npm run deploy or use npm run start to run it locally.

Usage

• Start with npm run start which will run the local version
• Press b to start a local browser against the wrangler-host (typically http://127.0.0.1:8787 which will respond with a 404 NO FOUND message)
• Request /.well-known/webfinger/hello to get the current worker version
• Request /.well-known/webfinger/status to confirm that the CloudFlare API values are correct
• Request /.well-known/webfinger/?resource=acct:foo to verify webfinger requests are being accepted
• Request /.well-known/webfinger/?resource=acct:your@example.org (where you can replace with any KV value entered in either the CloudFlare web interface or via `wrangler kv:)
• Request /api/list to see the current list of key-value pairs in the bound KV namespace
  • When doing any API calls, pass the Bearer token to authenticate requests

Setting up production routes

• Go to the Dashboard
• Select Workers / Overview on the left menu
• Select your cloudfinger worker in the right panel
• Click Routes View in the cloudfinger info panel
• Click the Add Route above the routes list (you may have to scroll up a bit)
• Fill in the form with the domain(s) CloudFlare is handling
  • Fill in the Route domain portion, for example github365.com
  • Append the /.well-known/webfinger/* suffix as required by the webfinger protocol
  • In the Zone, select the specific zone you want this route applied to (typically matches the domain prefix above)
  • Click the Add Route
• Repeat above steps if you want to bind the same worker to multiple domains.

Known Limitations

• This ONLY provides the endpoint needed to handle the webfinger protocol using the standard protocol, it does NOT do anything or provide any actual Mastodon functionality
• There's no frontend
• I need to document how to setup the KV values from the command line and/or dashboard

Troubleshooting

• You may need to purge routes from CDN cache if a webfinger result does not take immediate effect.
• If you get an CloudFlare error, you can check the worker logs
• The examples in the documentation are for my actual live deploy so feel free to finger this