Package Exports

@fujocoded/authproto
@fujocoded/authproto/components
@fujocoded/authproto/helpers

Readme

`@fujocoded/authproto`

ATproto authentication for your Astro site. Free and Easy™!

What is `@fujocoded/authproto`?

@fujocoded/authproto allows your visitors to log into your website using their account on any ATproto services (like Bluesky) or in technical terms their PDS!

Under the hood, @fujocoded/authproto adds OAuth authentication to your site through @atproto/oauth-client-node, then uses Astro's session adapters (based on @unjs/unstorage) to store your visitor's credentials.

What's included in `@fujocoded/authproto`?

In this package, you'll find:

@fujocoded/authproto, an Astro integration that:
- Adds the authentication routes you need
- Lets you easily access the DID and handle of a logged in user, if any
@fujocoded/authproto/components, which includes:
- A basic login/logout component to get started quickly
@fujocoded/authproto/helpers,
- getPdsAgent etc.?
- friendsOnly function (or similar)

What can you do with `@fujocoded/authproto`?

Let visitors log in to your site with their ATproto account (such as a Bluesky account). With this, you can:
- Build private, friends-only spaces and pages
- Gate certain content from the public
Read data from other ATproto services, including Bluesky, Streamplace, Teal.FM, and more! Among the many uses, you can:
- Show a list of your favorite Bluesky posts, or embed Leaflet publications
- Tell everyone about the music you love by listing your Rocksky stats
Create, update, and delete data on ATproto services, both existing ones or your own!
- Post on Bluesky from your own website
- Build guestbooks that others on ATproto can interact with
- Make your own ATproto app that shares data with the rest of the network

Built with Authproto

Getting started

Pre-requisites

Node
NPM/pnpm/yarn
Terminal

[!IMPORTANT] deno requires a workaround due to a CJS/ESM import issue within @atproto/oauth-client-node.

// TODO: we can move this in a details tab

Requires some familiarity with Astro, but if you want to jump in head first:

Install Astro by following their official tutorial. Once you do, set your Astro site to server mode.
Install any of the adapters.

You can start out with Node, since that's a widely supported runtime.

Run the following command:

npm install @fujocoded/authproto

npx astro add @fujocoded/authproto

Add the integration to your astro.config.mjs file, like this:

// TODO: add a note that this requires a server and an adapter that supports // some type of storage...? I'm unsure how it works on e.g. netlify for the // various session handlers

// TODO: we might also want to make sure people do not set certain adapters // or even better just disallow the ones they shouldn't.

import { defineConfig } from "astro/config";
+ import node from "@astrojs/node";
+ import authproto from "@fujocoded/authproto";

export default defineConfig({
  output: "server",
+ adapter: node({ mode: "standalone" }), // ... or whichever adapter you're using!
+ integrations: [
+   authproto({
+     // config options here
+   }),
+ ],
});

[!TIP] You can take a look at all the possible configuration options below.

Add the <Login /> component to your site, like this:

// src/pages/index.astro
---
import { Login } from "@fujocoded/authproto/components";
---

<Login />

[!TIP] You might run into a naming collision issue if you also have a page named login. You can fix this by replacing { Login } with { Login as LoginComponent }.

It'll look like a plain form:

To make a page only visible to logged in users:

// src/pages/secret.astro
---
const loggedInUser = Astro.locals.loggedInUser;

// if they're not logged in, send them back to a login page
if (!loggedInUser) {
  return Astro.redirect("/login");
}
---

<h1>Secret</h1>
<p>This is a secret page that only authenticated users can see!</p>

... And you've got authentication working on your Astro site!

Okay how do I actually do stuff with this?

Check out the example sites included:

__example__ shows you how to set up a login flow.
__example_status__ has some examples of creating new records on a PDS.

Configuration options

applicationName, required. The name of your application. For example, you can set this to "My personal guestbook"!
applicationDomain, required. It should be a domain that your site is on, or you can just put in "localhost:4321" for now.
defaultDevUser, optional. The default handle that gets filled out in the <Login /> component during development.
driver, optional. The driver used to store data about OAuth sessions. This takes Astro's session driver options. You can also set this with name: "astro:db" to utilize Astro's DB integration for OAuth sessions. This will set up tables for sessions in your database.
- NOTE: The default driver is memory. This is fine for development, but it's recommended that you switch to a more reliable solution for production.
- NOTE: Using either localStorage or sessionStorage will result in a "Session storage could not be initialized." error (and is considered insecure for handling sessions anyway). Consider other options, like a database.
scopes, optional. By default, only the "atproto" scope is added. This scope is included with any other scope that's enabled. See ATproto's documentation for OAuth scopes.
- email: boolean, optional. Only used to identify you by email. Does nothing to a PDS.
- genericData: boolean, optional. Allows you to read/write data to a user's PDS, but does not access BlueSky direct messages.
- directMessages: boolean, optional. Allows you to access BlueSky direct messages for a user's account. Requires genericData to be enabled.
- additionalScopes: array, optional. This is used in case you need to expand permissions to include other services. This should be an array of strings, like this: ["scope1", "scope2"]

Support Us

You can check out more of our plugins here:

You can also become a patron or buy some merch:

JSPM