antarctic 0.5.0 → 0.7.0

package/dist/providers/withings.js

@@ -1,6 +1,6 @@
 import { ArcticFetchError, createOAuth2Request, createOAuth2RequestError, UnexpectedErrorResponseBodyError, UnexpectedResponseError } from "../request.js";
 import { OAuth2Tokens } from "../oauth2.js";
-import { consumeOAuthState, generateOAuthState, parseCallbackQuery, profileId, requireAuthConfig, resolveAuthConfig, resolveScopes, saveOAuthState } from "../auth.js";
+import { extractOAuthTokens, generateOAuthState, parseCallbackQuery, profileId, requireAuthConfig, resolveAuthConfig, resolveOAuthState, resolveScopes } from "../auth.js";
 const authorizationEndpoint = "https://account.withings.com/oauth2_user/authorize2";
 const tokenEndpoint = "https://wbsapi.withings.net/v2/oauth2";
 const envPrefix = "WITHINGS";
@@ -10,7 +10,7 @@ export class Withings {
     clientSecret;
     redirectURI;
     auth = null;
-    constructor(clientIdOrOptions, clientSecret, redirectURI) {
+    constructor(clientIdOrOptions = {}, clientSecret, redirectURI) {
         if (typeof clientIdOrOptions === "object") {
             this.auth = resolveAuthConfig(envPrefix, clientIdOrOptions, {
                 clientSecret: true,
@@ -55,13 +55,13 @@ export class Withings {
         const auth = requireAuthConfig(this.auth);
         const state = generateOAuthState();
         const url = this.createAuthorizationURL(state, resolveScopes(scopes, auth, defaultScopes));
-        await saveOAuthState(auth.store, state, {});
-        return url;
+        const payload = {};
+        return { url, state, payload };
     }
-    async getUser(query) {
-        const auth = requireAuthConfig(this.auth);
+    async getUser(query, saved) {
+        requireAuthConfig(this.auth);
         const { code, state } = parseCallbackQuery(query);
-        await consumeOAuthState(auth.store, state);
+        resolveOAuthState(state, saved);
         const tokens = await this.validateAuthorizationCode(code);
         // Withings has no profile API; the token response only carries the user id.
         const data = tokens.data;
@@ -70,7 +70,8 @@ export class Withings {
             name: null,
             email: null,
             image: null,
-            raw: data
+            raw: data,
+            ...extractOAuthTokens(tokens)
         };
     }
 }

package/dist/providers/workos.d.ts

@@ -1,5 +1,5 @@
 import { type OAuth2Tokens } from "../oauth2.js";
-import type { OAuthCallbackQuery, OAuthUser, ProviderOptions } from "../auth.js";
+import type { AuthorizationRequest, OAuthCallbackQuery, OAuthUser, ProviderOptions, SavedOAuthState } from "../auth.js";
 export interface WorkOSOptions extends ProviderOptions {
 }
 export declare class WorkOS {
@@ -7,10 +7,10 @@ export declare class WorkOS {
     private clientSecret;
     private redirectURI;
     private auth;
-    constructor(options: WorkOSOptions);
+    constructor(options?: WorkOSOptions);
     constructor(clientId: string, clientSecret: string | null, redirectURI: string);
     createAuthorizationURL(state: string, codeVerifier: string | null): Promise<URL>;
     validateAuthorizationCode(code: string, codeVerifier: string | null): Promise<OAuth2Tokens>;
-    getAuthorizationURL(): Promise<URL>;
-    getUser(query: OAuthCallbackQuery): Promise<OAuthUser>;
+    getAuthorizationURL(): Promise<AuthorizationRequest>;
+    getUser(query: OAuthCallbackQuery, saved: SavedOAuthState): Promise<OAuthUser>;
 }

package/dist/providers/workos.js

@@ -1,5 +1,5 @@
 import { createOAuth2Request, sendTokenRequest } from "../request.js";
-import { consumeOAuthState, fetchUserProfile, generateOAuthCodeVerifier, generateOAuthState, InvalidOAuthCallbackError, parseCallbackQuery, profileId, profileString, requireAuthConfig, resolveAuthConfig, saveOAuthState } from "../auth.js";
+import { extractOAuthTokens, fetchUserProfile, generateOAuthCodeVerifier, generateOAuthState, InvalidOAuthCallbackError, parseCallbackQuery, profileId, profileString, requireAuthConfig, resolveAuthConfig, resolveOAuthState } from "../auth.js";
 import { createS256CodeChallenge } from "../oauth2.js";
 const authorizationEndpoint = "https://api.workos.com/sso/authorize";
 const tokenEndpoint = "https://api.workos.com/sso/token";
@@ -10,7 +10,7 @@ export class WorkOS {
     clientSecret;
     redirectURI;
     auth = null;
-    constructor(clientIdOrOptions, clientSecret, redirectURI) {
+    constructor(clientIdOrOptions = {}, clientSecret, redirectURI) {
         if (typeof clientIdOrOptions === "object") {
             this.auth = resolveAuthConfig(envPrefix, clientIdOrOptions, { redirectURI: true });
             this.clientId = this.auth.clientId;
@@ -53,17 +53,17 @@ export class WorkOS {
         return tokens;
     }
     async getAuthorizationURL() {
-        const auth = requireAuthConfig(this.auth);
+        requireAuthConfig(this.auth);
         const state = generateOAuthState();
         const codeVerifier = generateOAuthCodeVerifier();
         const url = await this.createAuthorizationURL(state, codeVerifier);
-        await saveOAuthState(auth.store, state, { codeVerifier });
-        return url;
+        const payload = { codeVerifier };
+        return { url, state, payload };
     }
-    async getUser(query) {
-        const auth = requireAuthConfig(this.auth);
+    async getUser(query, saved) {
+        requireAuthConfig(this.auth);
         const { code, state } = parseCallbackQuery(query);
-        const stored = await consumeOAuthState(auth.store, state);
+        const stored = resolveOAuthState(state, saved);
         if (typeof stored.codeVerifier !== "string") {
             throw new InvalidOAuthCallbackError("Missing PKCE code verifier for OAuth state");
         }
@@ -77,7 +77,8 @@ export class WorkOS {
             name: profileString(profile.name) ?? (fullName !== "" ? fullName : null),
             email: profileString(profile.email),
             image: profileString(profile.profile_picture_url),
-            raw: profile
+            raw: profile,
+            ...extractOAuthTokens(tokens)
         };
     }
 }

package/dist/providers/yahoo.d.ts

@@ -1,15 +1,15 @@
 import type { OAuth2Tokens } from "../oauth2.js";
-import type { OAuthCallbackQuery, OAuthUser, ProviderOptions } from "../auth.js";
+import type { AuthorizationRequest, OAuthCallbackQuery, OAuthUser, ProviderOptions, SavedOAuthState } from "../auth.js";
 export interface YahooOptions extends ProviderOptions {
 }
 export declare class Yahoo {
     private client;
     private auth;
-    constructor(options: YahooOptions);
+    constructor(options?: YahooOptions);
     constructor(clientId: string, clientSecret: string, redirectURI: string);
     createAuthorizationURL(state: string, scopes: string[]): URL;
     validateAuthorizationCode(code: string): Promise<OAuth2Tokens>;
     refreshAccessToken(refreshToken: string): Promise<OAuth2Tokens>;
-    getAuthorizationURL(scopes?: string[]): Promise<URL>;
-    getUser(query: OAuthCallbackQuery): Promise<OAuthUser>;
+    getAuthorizationURL(scopes?: string[]): Promise<AuthorizationRequest>;
+    getUser(query: OAuthCallbackQuery, saved: SavedOAuthState): Promise<OAuthUser>;
 }

package/dist/providers/yahoo.js

@@ -1,6 +1,6 @@
 import { OAuth2Client } from "../client.js";
 import { decodeIdToken } from "../oidc.js";
-import { consumeOAuthState, fetchUserProfile, generateOAuthState, parseCallbackQuery, profileId, profileString, requireAuthConfig, resolveAuthConfig, resolveScopes, saveOAuthState } from "../auth.js";
+import { extractOAuthTokens, fetchUserProfile, generateOAuthState, parseCallbackQuery, profileId, profileString, requireAuthConfig, resolveAuthConfig, resolveOAuthState, resolveScopes } from "../auth.js";
 const authorizationEndpoint = "https://api.login.yahoo.com/oauth2/request_auth";
 const tokenEndpoint = "https://api.login.yahoo.com/oauth2/get_token";
 const userinfoEndpoint = "https://api.login.yahoo.com/openid/v1/userinfo";
@@ -9,7 +9,7 @@ const defaultScopes = ["openid", "profile", "email"];
 export class Yahoo {
     client;
     auth = null;
-    constructor(clientIdOrOptions, clientSecret, redirectURI) {
+    constructor(clientIdOrOptions = {}, clientSecret, redirectURI) {
         if (typeof clientIdOrOptions === "object") {
             this.auth = resolveAuthConfig(envPrefix, clientIdOrOptions, {
                 clientSecret: true,
@@ -37,13 +37,13 @@ export class Yahoo {
         const auth = requireAuthConfig(this.auth);
         const state = generateOAuthState();
         const url = this.createAuthorizationURL(state, resolveScopes(scopes, auth, defaultScopes));
-        await saveOAuthState(auth.store, state, {});
-        return url;
+        const payload = {};
+        return { url, state, payload };
     }
-    async getUser(query) {
-        const auth = requireAuthConfig(this.auth);
+    async getUser(query, saved) {
+        requireAuthConfig(this.auth);
         const { code, state } = parseCallbackQuery(query);
-        await consumeOAuthState(auth.store, state);
+        resolveOAuthState(state, saved);
         const tokens = await this.validateAuthorizationCode(code);
         let claims;
         if ("id_token" in tokens.data) {
@@ -60,7 +60,8 @@ export class Yahoo {
             name: profileString(claims.name) ?? (fullName !== "" ? fullName : null),
             email: profileString(claims.email),
             image: profileString(claims.picture),
-            raw: claims
+            raw: claims,
+            ...extractOAuthTokens(tokens)
         };
     }
 }

package/dist/providers/yandex.d.ts

@@ -1,15 +1,15 @@
 import type { OAuth2Tokens } from "../oauth2.js";
-import type { OAuthCallbackQuery, OAuthUser, ProviderOptions } from "../auth.js";
+import type { AuthorizationRequest, OAuthCallbackQuery, OAuthUser, ProviderOptions, SavedOAuthState } from "../auth.js";
 export interface YandexOptions extends ProviderOptions {
 }
 export declare class Yandex {
     private client;
     private auth;
-    constructor(options: YandexOptions);
+    constructor(options?: YandexOptions);
     constructor(clientId: string, clientSecret: string, redirectURI: string);
     createAuthorizationURL(state: string, scopes: string[]): URL;
     validateAuthorizationCode(code: string): Promise<OAuth2Tokens>;
     refreshAccessToken(refreshToken: string): Promise<OAuth2Tokens>;
-    getAuthorizationURL(scopes?: string[]): Promise<URL>;
-    getUser(query: OAuthCallbackQuery): Promise<OAuthUser>;
+    getAuthorizationURL(scopes?: string[]): Promise<AuthorizationRequest>;
+    getUser(query: OAuthCallbackQuery, saved: SavedOAuthState): Promise<OAuthUser>;
 }

package/dist/providers/yandex.js

@@ -1,5 +1,5 @@
 import { OAuth2Client } from "../client.js";
-import { consumeOAuthState, fetchUserProfile, generateOAuthState, parseCallbackQuery, profileId, profileString, requireAuthConfig, resolveAuthConfig, resolveScopes, saveOAuthState } from "../auth.js";
+import { extractOAuthTokens, fetchUserProfile, generateOAuthState, parseCallbackQuery, profileId, profileString, requireAuthConfig, resolveAuthConfig, resolveOAuthState, resolveScopes } from "../auth.js";
 const authorizationEndpoint = "https://oauth.yandex.com/authorize";
 const tokenEndpoint = "https://oauth.yandex.com/token";
 const userEndpoint = "https://login.yandex.ru/info?format=json";
@@ -8,7 +8,7 @@ const defaultScopes = ["login:info", "login:email", "login:avatar"];
 export class Yandex {
     client;
     auth = null;
-    constructor(clientIdOrOptions, clientSecret, redirectURI) {
+    constructor(clientIdOrOptions = {}, clientSecret, redirectURI) {
         if (typeof clientIdOrOptions === "object") {
             this.auth = resolveAuthConfig(envPrefix, clientIdOrOptions, {
                 clientSecret: true,
@@ -36,13 +36,13 @@ export class Yandex {
         const auth = requireAuthConfig(this.auth);
         const state = generateOAuthState();
         const url = this.createAuthorizationURL(state, resolveScopes(scopes, auth, defaultScopes));
-        await saveOAuthState(auth.store, state, {});
-        return url;
+        const payload = {};
+        return { url, state, payload };
     }
-    async getUser(query) {
-        const auth = requireAuthConfig(this.auth);
+    async getUser(query, saved) {
+        requireAuthConfig(this.auth);
         const { code, state } = parseCallbackQuery(query);
-        await consumeOAuthState(auth.store, state);
+        resolveOAuthState(state, saved);
         const tokens = await this.validateAuthorizationCode(code);
         const accessToken = tokens.accessToken();
         // Yandex expects the "OAuth" scheme instead of "Bearer".
@@ -61,7 +61,8 @@ export class Yandex {
                 profileString(profile.login),
             email: profileString(profile.default_email),
             image,
-            raw: profile
+            raw: profile,
+            ...extractOAuthTokens(tokens)
         };
     }
 }

package/dist/providers/zoom.d.ts

@@ -1,16 +1,16 @@
 import type { OAuth2Tokens } from "../oauth2.js";
-import type { OAuthCallbackQuery, OAuthUser, ProviderOptions } from "../auth.js";
+import type { AuthorizationRequest, OAuthCallbackQuery, OAuthUser, ProviderOptions, SavedOAuthState } from "../auth.js";
 export interface ZoomOptions extends ProviderOptions {
 }
 export declare class Zoom {
     private client;
     private auth;
-    constructor(options: ZoomOptions);
+    constructor(options?: ZoomOptions);
     constructor(clientId: string, clientSecret: string, redirectURI: string);
     createAuthorizationURL(state: string, codeVerifier: string, scopes: string[]): Promise<URL>;
     validateAuthorizationCode(code: string, codeVerifier: string): Promise<OAuth2Tokens>;
     refreshAccessToken(refreshToken: string): Promise<OAuth2Tokens>;
     revokeToken(token: string): Promise<void>;
-    getAuthorizationURL(scopes?: string[]): Promise<URL>;
-    getUser(query: OAuthCallbackQuery): Promise<OAuthUser>;
+    getAuthorizationURL(scopes?: string[]): Promise<AuthorizationRequest>;
+    getUser(query: OAuthCallbackQuery, saved: SavedOAuthState): Promise<OAuthUser>;
 }

package/dist/providers/zoom.js

@@ -1,5 +1,5 @@
 import { OAuth2Client, CodeChallengeMethod } from "../client.js";
-import { consumeOAuthState, fetchUserProfile, generateOAuthCodeVerifier, generateOAuthState, InvalidOAuthCallbackError, parseCallbackQuery, profileId, profileString, requireAuthConfig, resolveAuthConfig, resolveScopes, saveOAuthState } from "../auth.js";
+import { extractOAuthTokens, fetchUserProfile, generateOAuthCodeVerifier, generateOAuthState, InvalidOAuthCallbackError, parseCallbackQuery, profileId, profileString, requireAuthConfig, resolveAuthConfig, resolveOAuthState, resolveScopes } from "../auth.js";
 const authorizationEndpoint = "https://zoom.us/oauth/authorize";
 const tokenEndpoint = "https://zoom.us/oauth/token";
 const tokenRevocationEndpoint = "https://zoom.us/oauth/revoke";
@@ -9,7 +9,7 @@ const defaultScopes = ["user:read:user"];
 export class Zoom {
     client;
     auth = null;
-    constructor(clientIdOrOptions, clientSecret, redirectURI) {
+    constructor(clientIdOrOptions = {}, clientSecret, redirectURI) {
         if (typeof clientIdOrOptions === "object") {
             this.auth = resolveAuthConfig(envPrefix, clientIdOrOptions, {
                 clientSecret: true,
@@ -41,13 +41,13 @@ export class Zoom {
         const state = generateOAuthState();
         const codeVerifier = generateOAuthCodeVerifier();
         const url = await this.createAuthorizationURL(state, codeVerifier, resolveScopes(scopes, auth, defaultScopes));
-        await saveOAuthState(auth.store, state, { codeVerifier });
-        return url;
+        const payload = { codeVerifier };
+        return { url, state, payload };
     }
-    async getUser(query) {
-        const auth = requireAuthConfig(this.auth);
+    async getUser(query, saved) {
+        requireAuthConfig(this.auth);
         const { code, state } = parseCallbackQuery(query);
-        const stored = await consumeOAuthState(auth.store, state);
+        const stored = resolveOAuthState(state, saved);
         if (typeof stored.codeVerifier !== "string") {
             throw new InvalidOAuthCallbackError("Missing PKCE code verifier for OAuth state");
         }
@@ -61,7 +61,8 @@ export class Zoom {
             name: profileString(profile.display_name) ?? (fullName !== "" ? fullName : null),
             email: profileString(profile.email),
             image: profileString(profile.pic_url),
-            raw: profile
+            raw: profile,
+            ...extractOAuthTokens(tokens)
         };
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "antarctic",
-	"version": "0.5.0",
+	"version": "0.7.0",
 	"description": "High-level OAuth 2.0 clients for popular providers, forked from Arctic",
 	"type": "module",
 	"main": "dist/index.js",
@@ -20,6 +20,7 @@
 		"pilcrowOnPaper (author of Arctic, which Antarctic is a fork of)"
 	],
 	"license": "MIT",
+	"homepage": "https://antarcticjs.dev",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/franciscop/antarctic.git"

package/readme.md

@@ -1,155 +0,0 @@
-# Antarctic
-
-Antarctic is a fork of [Arctic](https://arcticjs.dev) by [pilcrowOnPaper](https://github.com/pilcrowOnPaper), adding a high level auth layer on top of its OAuth 2.0 clients. Only the authorization code flow is supported. Built on top of the Fetch API, it's light weight, fully-typed, and runtime-agnostic.
-
-All of the OAuth 2.0 clients and provider coverage are Arctic's work. If you only need those, use [Arctic](https://arcticjs.dev) directly. See [credits](#credits).
-
-```
-npm install antarctic
-```
-
-## High-level API
-
-Construct a provider with an options object and get two methods that handle the whole flow: `getAuthorizationURL()` and `getUser()`. State and PKCE values are generated for you and kept in a [polystore](https://polystore.dev) compatible key-value store.
-
-```ts
-import * as auth from "antarctic";
-import kv from "polystore";
-
-const store = kv(new Map());
-const scopes = ["read:user", "user:email"];
-
-const github = new auth.GitHub({ store, scopes });
-
-// Redirect the user here to sign in.
-const url = await github.getAuthorizationURL();
-
-// In the OAuth callback route:
-const user = await github.getUser(request.url);
-// { id: "1", name: "The Octocat", email: "octocat@github.com", image: "https://..." }
-```
-
-`getUser()` accepts the callback query as a full URL, a query string, a `URLSearchParams`, or a plain object. It validates the `state`, exchanges the code (with PKCE where the provider supports it), fetches the profile, deletes the consumed state, and returns a normalized user: `{ id, name, email, image }`.
-
-Options resolve as `explicit > environment > provider default`. Every option except `store` can come from the environment, named after the provider:
-
-```
-GITHUB_CLIENT_ID
-GITHUB_CLIENT_SECRET
-GITHUB_REDIRECT_URI
-GITHUB_SCOPES
-
-GOOGLE_CLIENT_ID
-...
-```
-
-`GITHUB_SCOPES` takes a list separated by commas, whitespace, or both. Scopes resolve as `argument > constructor > environment > provider default`, where the provider default is the minimal set that yields a full profile:
-
-```ts
-await github.getAuthorizationURL(["repo"]); // overrides the constructor and the environment
-```
-
-The environment is read when the provider is constructed, so load your `.env` file first. See the [documentation](https://documentation.page/github/franciscop/antarctic/) for the details.
-
-Errors thrown by the high-level layer: `InvalidOAuthStateError`, `InvalidOAuthCallbackError`, `OAuthConfigurationError`, and `OAuthProviderError`.
-
-Sessions, cookies, and your user database remain your responsibility: take the returned user and plug it into your framework of choice.
-
-## Low-level API
-
-Arctic's low level API remains available on the same objects, including the positional constructors. It is unchanged except that PKCE providers build the URL asynchronously, so `createAuthorizationURL()` returns a promise for them:
-
-```ts
-import * as arctic from "antarctic";
-
-const github = new arctic.GitHub(clientId, clientSecret, redirectURI);
-
-const state = arctic.generateState();
-const scopes = ["user:email"];
-const authorizationURL = github.createAuthorizationURL(state, scopes);
-
-// ...
-
-const tokens = await github.validateAuthorizationCode(code);
-const accessToken = tokens.accessToken();
-```
-
-> Antarctic only supports providers that follow the OAuth 2.0 spec (including PKCE and token revocation).
-
-## Credits
-
-Antarctic is a fork of [Arctic](https://github.com/pilcrowonpaper/arctic), created and maintained by [pilcrowOnPaper](https://github.com/pilcrowOnPaper). The OAuth 2.0 clients, the provider implementations, the docs those pages grew from, and the design that makes all of it consistent are their work. Antarctic adds one layer on top: `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. See [LICENSE](./LICENSE).
-
-If you only need the OAuth 2.0 clients without the high level layer, use [Arctic](https://arcticjs.dev) directly. Please report provider issues that are not specific to Antarctic's additions upstream, where they benefit everyone.
-
-## Semver
-
-Antarctic does not strictly follow semantic versioning. While we aim to only introduce breaking changes in major versions, we may introduce them in a minor update if a provider updates their API in a non-backward compatible way. However, they will never be introduced in a patch update.
-
-## Supported providers
-
-- 42 School
-- Amazon Cognito
-- AniList
-- Apple
-- Atlassian
-- Auth0
-- Authentik
-- Autodesk Platform Services
-- Battle.net
-- Bitbucket
-- Box
-- Bungie
-- Coinbase
-- Discord
-- DonationAlerts
-- Dribbble
-- Dropbox
-- Etsy
-- Epic Games
-- Facebook
-- Figma
-- Gitea
-- GitHub
-- GitLab
-- Google
-- Intuit
-- Kakao
-- KeyCloak
-- Kick
-- Lichess
-- Line
-- Linear
-- LinkedIn
-- Mastodon
-- MercadoLibre
-- MercadoPago
-- Microsoft Entra ID
-- MyAnimeList
-- Naver
-- Notion
-- Okta
-- osu!
-- Patreon
-- Polar
-- Reddit
-- Roblox
-- Salesforce
-- Shikimori
-- Slack
-- Spotify
-- Start.gg
-- Strava
-- Synology
-- TikTok
-- Tiltify
-- Tumblr
-- Twitch
-- Twitter
-- VK
-- WorkOS
-- Yahoo
-- Yandex
-- Zoom