masto-auth

A simple library for authenticating against mastodon.

Usage no npm install needed!

<script type="module">
  import mastoAuth from 'https://cdn.skypack.dev/masto-auth';
</script>

README

Masto Auth

A simple library for authenticating against mastodon.

Doesn't provide API access, only verifies who the user is.

Use it to provide OIDC-like auth/login services for mastodon users on your own site.

If you need integration with the mastodon API, try looking at a mastodon API client instead.

import Auth, {UnregisteredClientError} from 'masto-auth';

// Provide a name for your client and the URL to redirect to after the user has authenticated on mastodon.
const clientOptions = {
    client_name: 'My app',
    redirect_uri: 'http://example.com/auth'
}

// Register one or more clients
// Serialise with toJSON and save the details somewhere
// like a database or environment variable
const ms = (await Auth.register('https://mastodon.social', clientOptions)).toJSON();
const kk = (await Auth.register('https://kith.kitchen', clientOptions)).toJSON();

// Create an instance of Auth with a function that retrieves your clients
const auth = new Auth(url => {
    switch(url){
        case: 'https://mastodon.social':
            return ms;
        case: 'https://kith.kitchen':
            return kk;
        default:
            // If no client matches, return null to throw an UnregisteredClientError
            return null;
    }
});

export default async (req, res) => {
    const { pathname } = new URL('file://' + req.url);

    // Get the login URL for each client -
    // here I've hard-coded the instance URLs but
    // you could use a form input to get them from the user
    if(pathname === '/login/kith.kitchen') {
        res.end(await auth.getRedirectUrl('https://kith.kitchen'));
    } else if(pathname === '/login/mastodon.social') {
        res.end(await auth.getRedirectUrl('https://mastodon.social'));

    // This is the auth endpoint we specified in clientOptions - get the user object and do whatever you want with it.
    } else if(pathname === '/auth') {
        res.end(JSON.stringify(await auth.getUserFromCallback(req)))
    }
}

Dependencies

  • masto-id-connect: ^1.1.1

masto-auth

masto-auth.Issuer

Class representing the mastodon instance

Kind: static class of masto-auth

masto-auth.Client

Class representing an app registration against the instance's API

Kind: static class of masto-auth

masto-auth.default

Manage mastodon authentication

Kind: static class of masto-auth

new module.exports(getClient)

Create a new instance of Auth

Param Type Description
getClient function Function that returns the serialized client (i.e. the result of calling Client#toJSON)

default.getRedirectUrl(url) ⇒ string

Get the authentication URL for an issuer

Kind: instance method of default

Param Type Description
url string URL of issuer

default.getUserInfo(url, code) ⇒ Object

Get the user info object for a user who has obtained an authentication code

Kind: instance method of default

Param Type Description
url string The URL of the issuer
code string The code returned from the user auth flow

default.getUserFromCallback(req) ⇒ Object

Get the user info object from an auth callback request. Parse the issuer url and code from a callback request and call getUserInfo

Kind: instance method of default

Param Type Description
req http.IncommingRequest Callback request

default.register(url, options) ⇒ Client

Register with a mastodon instance and return a new instance of Client

Kind: static method of default

Param Type Description
url string The URL of the mastodon instance (any part other than the origin will be ignored)
options Object Client options
options.redirectUri string The URI to redirect the user to after they have authenticated on their mastodon instance.
options.clientName string The name of your application

masto-auth.UnregisteredClientError

Error thrown when no client can be found for a given issuer

Kind: static class of masto-auth