Skip to content

README.md

Latest commit

 

History

History
229 lines (171 loc) · 9.08 KB

README.md

File metadata and controls

229 lines (171 loc) · 9.08 KB

@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 authorizes a logged in user to post, update, or delete data from ATProto
    • friendsOnly finds mutuals from your Bluesky account

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:
  • 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

[!IMPORTANT] > deno requires a workaround due to a CJS/ESM import issue within @atproto/oauth-client-node. For now, avoid using deno and use other package managers.

Important

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.

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

Automatic Installation

  1. Run the following command:
npx astro add @fujocoded/authproto

This will automatically install @fujocoded/authproto and add the integration to your astro.config.mjs file.

Tip

You can take a look at all the possible configuration options below.

Manual Installation

  1. Run the following command:
npm add @fujocoded/authproto
  1. Add the integration to your astro.config.mjs file, like this:
import { defineConfig } from "astro/config";
import node from "@astrojs/node";
+ import authproto from "@fujocoded/authproto";

export default defineConfig({
  output: "server", // you can read up more how this works here: https://docs.astro.build/en/guides/on-demand-rendering/
  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.

Using @fujocoded/authproto

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

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

<Login />

You can also control what permissions your app asks for on different requests using the scopes and additionalScopes props! Check out the custom scopes example for all the details.

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 under the examples folder.

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.
  • 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"]
  • defaultScopes, optional. What your app asks for when no per-request scopes are specified. Defaults to all configured scopes. Handy if you want to allow a big set of scopes but only request a subset by default!
  • resolveScopesEntrypoint, optional. Path to a module that exports a resolveScopes(atprotoId, scopes) function — use this if you need to tweak scopes on the server side before the OAuth request goes out.

Support Us

You can check out more of our plugins here:

You can also become a patron or buy some merch:

Follow Us