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-auth
-
masto-auth
- .Issuer
- .Client
-
.default
- new module.exports(getClient)
-
instance
-
.getRedirectUrl(url) ⇒
string
-
.getUserInfo(url, code) ⇒
Object
-
.getUserFromCallback(req) ⇒
Object
-
.getRedirectUrl(url) ⇒
-
static
-
.register(url, options) ⇒
Client
-
.register(url, options) ⇒
- .UnregisteredClientError
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
-
.default
- new module.exports(getClient)
-
instance
-
.getRedirectUrl(url) ⇒
string
-
.getUserInfo(url, code) ⇒
Object
-
.getUserFromCallback(req) ⇒
Object
-
.getRedirectUrl(url) ⇒
-
static
-
.register(url, options) ⇒
Client
-
.register(url, options) ⇒
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) |
string
default.getRedirectUrl(url) ⇒ Get the authentication URL for an issuer
Kind: instance method of default
Param | Type | Description |
---|---|---|
url | string |
URL of issuer |
Object
default.getUserInfo(url, code) ⇒ 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 |
Object
default.getUserFromCallback(req) ⇒ 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 |
Client
default.register(url, options) ⇒ 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