Antarctic

Antarctic is a collection of OAuth 2.0 clients for popular providers, with a high level layer that handles the whole sign-in flow for you. It is a fork of Arctic by pilcrowOnPaper, whose work is every OAuth 2.0 client and provider here. Only the authorization code flow is supported. Built on the Fetch API, it is light weight, fully typed, and runtime agnostic.

npm install antarctic polystore

Quick start

Construct a provider with a store, send the user to the authorization URL, and read them back in your callback route.

import * as auth from "antarctic";
import kv from "polystore";

const store = kv(new Map());
const github = new auth.GitHub({ store });

// Where you start the login.
const { url } = await github.getAuthorizationURL();

// In your OAuth callback route.
const user = await github.getUser(request.url);
// { id: "1", name: "The Octocat", email: "[email protected]", image: "https://..." }

getAuthorizationURL() generates the state and the PKCE verifier, keeps them in the store, and returns them alongside the url. getUser() validates the state, exchanges the code, fetches the profile, and returns the same shape for every provider: { id, name, email, image, raw, accessToken, refreshToken, scopes }.

Credentials come from the environment when you do not pass them, so the example above reads GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET. See the high level API for the full flow, and providers for what each one supports.

Lower level

Arctic's low level API is available on the same objects, for when you want to drive the flow yourself. It is unchanged except that PKCE providers build the URL asynchronously, so createAuthorizationURL() returns a promise for them:

import * as arctic from "antarctic";

const github = new arctic.GitHub(clientId, clientSecret, redirectURI);

const state = arctic.generateState();
const url = github.createAuthorizationURL(state, ["user:email"]);
const tokens = await github.validateAuthorizationCode(code);
const accessToken = tokens.accessToken();

Start with the OAuth 2.0 guide, or OAuth 2.0 with PKCE for providers that require it.

Scope

Antarctic handles OAuth, PKCE, state, the provider APIs, and normalized identity. Sessions, cookies, your user table, and framework routing stay yours: take the user that getUser() returns and store it however your application needs.

Antarctic only supports providers that follow the OAuth 2.0 spec, including PKCE and token revocation.

Credits

Antarctic is a fork of Arctic, created and maintained by pilcrowOnPaper. The OAuth 2.0 clients, the provider implementations, and the reference documentation are their work. Antarctic adds getAuthorizationURL(), getUser(), and the option resolution around them.

Arctic is MIT licensed. Antarctic keeps that license and the original copyright notice, and adds its own for the new work.

If you only need the OAuth 2.0 clients without the high level layer, use Arctic directly. Provider issues that are not specific to Antarctic's additions are best reported upstream, where they benefit everyone.