@bskyprism/atproto-oauth-client-cloudflare-workers 0.2.2

package/lib/oauth-client/oauth-client.js

@@ -0,0 +1,276 @@
+import { Key, Keyset } from "@atproto/jwk";
+import { oauthClientMetadataSchema, } from "@atproto/oauth-types";
+import { assertAtprotoDid } from "@atproto/did";
+import { HANDLE_INVALID } from "#identity-resolver";
+import { SimpleStoreMemory } from "@atproto-labs/simple-store-memory";
+import { FALLBACK_ALG } from "./constants.js";
+import { AuthMethodUnsatisfiableError } from "./errors/auth-method-unsatisfiable-error.js";
+import { TokenRevokedError } from "./errors/token-revoked-error.js";
+import { createIdentityResolver, } from "./identity-resolver.js";
+import { OAuthAuthorizationServerMetadataResolver, } from "./oauth-authorization-server-metadata-resolver.js";
+import { OAuthCallbackError } from "./oauth-callback-error.js";
+import { negotiateClientAuthMethod } from "./oauth-client-auth.js";
+import { OAuthProtectedResourceMetadataResolver, } from "./oauth-protected-resource-metadata-resolver.js";
+import { OAuthResolver } from "./oauth-resolver.js";
+import { OAuthServerFactory } from "./oauth-server-factory.js";
+import { OAuthSession } from "./oauth-session.js";
+import { Runtime } from "./runtime.js";
+import { SessionGetter, } from "./session-getter.js";
+import { CustomEventTarget } from "./util.js";
+import { validateClientMetadata } from "./validate-client-metadata.js";
+// Export all types needed to construct OAuthClientOptions
+export { Key, Keyset, };
+export class OAuthClient extends CustomEventTarget {
+    static async fetchMetadata({ clientId, fetch = globalThis.fetch, signal, }) {
+        signal?.throwIfAborted();
+        const request = new Request(clientId, {
+            redirect: "follow",
+            signal: signal,
+        });
+        const response = await fetch(request);
+        if (response.status !== 200) {
+            response.body?.cancel?.();
+            throw new TypeError(`Failed to fetch client metadata: ${response.status}`);
+        }
+        // https://drafts.aaronpk.com/draft-parecki-oauth-client-id-metadata-document/draft-parecki-oauth-client-id-metadata-document.html#section-4.1
+        const mime = response.headers.get("content-type")?.split(";")[0].trim();
+        if (mime !== "application/json") {
+            response.body?.cancel?.();
+            throw new TypeError(`Invalid client metadata content type: ${mime}`);
+        }
+        const json = await response.json();
+        signal?.throwIfAborted();
+        return oauthClientMetadataSchema.parse(json);
+    }
+    constructor(options) {
+        const { stateStore, sessionStore, dpopNonceCache = new SimpleStoreMemory({ ttl: 60e3, max: 100 }), authorizationServerMetadataCache = new SimpleStoreMemory({
+            ttl: 60e3,
+            max: 100,
+        }), protectedResourceMetadataCache = new SimpleStoreMemory({
+            ttl: 60e3,
+            max: 100,
+        }), responseMode, clientMetadata, runtimeImplementation, keyset, } = options;
+        super();
+        this.keyset = keyset
+            ? keyset instanceof Keyset
+                ? keyset
+                : new Keyset(keyset)
+            : undefined;
+        this.clientMetadata = validateClientMetadata(clientMetadata, this.keyset);
+        this.responseMode = responseMode;
+        this.runtime = new Runtime(runtimeImplementation);
+        this.fetch = options.fetch ?? globalThis.fetch;
+        this.oauthResolver = new OAuthResolver(createIdentityResolver(options), new OAuthProtectedResourceMetadataResolver(protectedResourceMetadataCache, this.fetch, { allowHttpResource: options.allowHttp }), new OAuthAuthorizationServerMetadataResolver(authorizationServerMetadataCache, this.fetch, { allowHttpIssuer: options.allowHttp }));
+        this.serverFactory = new OAuthServerFactory(this.clientMetadata, this.runtime, this.oauthResolver, this.fetch, this.keyset, dpopNonceCache);
+        this.sessionGetter = new SessionGetter(sessionStore, this.serverFactory, this.runtime);
+        this.stateStore = stateStore;
+        // Proxy sessionGetter events
+        for (const type of ["deleted", "updated"]) {
+            this.sessionGetter.addEventListener(type, (event) => {
+                if (!this.dispatchCustomEvent(type, event.detail)) {
+                    event.preventDefault();
+                }
+            });
+        }
+    }
+    // Exposed as public API for convenience
+    get identityResolver() {
+        return this.oauthResolver.identityResolver;
+    }
+    get jwks() {
+        return this.keyset?.publicJwks ?? { keys: [] };
+    }
+    async authorize(input, { signal, ...options } = {}) {
+        const redirectUri = options?.redirect_uri ?? this.clientMetadata.redirect_uris[0];
+        if (!this.clientMetadata.redirect_uris.includes(redirectUri)) {
+            // The server will enforce this, but let's catch it early
+            throw new TypeError("Invalid redirect_uri");
+        }
+        const { identityInfo, metadata } = await this.oauthResolver.resolve(input, {
+            signal,
+        });
+        const pkce = await this.runtime.generatePKCE();
+        const dpopKey = await this.runtime.generateKey(metadata.dpop_signing_alg_values_supported || [FALLBACK_ALG]);
+        const authMethod = negotiateClientAuthMethod(metadata, this.clientMetadata, this.keyset);
+        const state = await this.runtime.generateNonce();
+        await this.stateStore.set(state, {
+            iss: metadata.issuer,
+            dpopKey,
+            authMethod,
+            verifier: pkce.verifier,
+            appState: options?.state,
+        });
+        const parameters = {
+            ...options,
+            client_id: this.clientMetadata.client_id,
+            redirect_uri: redirectUri,
+            code_challenge: pkce.challenge,
+            code_challenge_method: pkce.method,
+            state,
+            login_hint: identityInfo
+                ? identityInfo.handle !== HANDLE_INVALID
+                    ? identityInfo.handle
+                    : identityInfo.did
+                : undefined,
+            response_mode: this.responseMode,
+            response_type: "code",
+            scope: options?.scope ?? this.clientMetadata.scope,
+        };
+        const authorizationUrl = new URL(metadata.authorization_endpoint);
+        // Since the user will be redirected to the authorization_endpoint url using
+        // a browser, we need to make sure that the url is valid.
+        if (authorizationUrl.protocol !== "https:" &&
+            authorizationUrl.protocol !== "http:") {
+            throw new TypeError(`Invalid authorization endpoint protocol: ${authorizationUrl.protocol}`);
+        }
+        if (metadata.pushed_authorization_request_endpoint) {
+            const server = await this.serverFactory.fromMetadata(metadata, authMethod, dpopKey);
+            const parResponse = await server.request("pushed_authorization_request", parameters);
+            authorizationUrl.searchParams.set("client_id", this.clientMetadata.client_id);
+            authorizationUrl.searchParams.set("request_uri", parResponse.request_uri);
+            return authorizationUrl;
+        }
+        else if (metadata.require_pushed_authorization_requests) {
+            throw new Error("Server requires pushed authorization requests (PAR) but no PAR endpoint is available");
+        }
+        else {
+            for (const [key, value] of Object.entries(parameters)) {
+                if (value)
+                    authorizationUrl.searchParams.set(key, String(value));
+            }
+            // Length of the URL that will be sent to the server
+            const urlLength = authorizationUrl.pathname.length + authorizationUrl.search.length;
+            if (urlLength < 2048) {
+                return authorizationUrl;
+            }
+            else if (!metadata.pushed_authorization_request_endpoint) {
+                throw new Error("Login URL too long");
+            }
+        }
+        throw new Error("Server does not support pushed authorization requests (PAR)");
+    }
+    /**
+     * This method allows the client to proactively revoke the request_uri it
+     * created through PAR.
+     */
+    async abortRequest(authorizeUrl) {
+        const requestUri = authorizeUrl.searchParams.get("request_uri");
+        if (!requestUri)
+            return;
+        // @NOTE This is not implemented here because, 1) the request server should
+        // invalidate the request_uri after some delay anyways, and 2) I am not sure
+        // that the revocation endpoint is even supposed to support this (and I
+        // don't want to spend the time checking now).
+        // @TODO investigate actual necessity & feasibility of this feature
+    }
+    async callback(params) {
+        const responseJwt = params.get("response");
+        if (responseJwt != null) {
+            // https://openid.net/specs/oauth-v2-jarm.html
+            throw new OAuthCallbackError(params, "JARM not supported");
+        }
+        const issuerParam = params.get("iss");
+        const stateParam = params.get("state");
+        const errorParam = params.get("error");
+        const codeParam = params.get("code");
+        if (!stateParam) {
+            throw new OAuthCallbackError(params, 'Missing "state" parameter');
+        }
+        const stateData = await this.stateStore.get(stateParam);
+        if (stateData) {
+            // Prevent any kind of replay
+            await this.stateStore.del(stateParam);
+        }
+        else {
+            throw new OAuthCallbackError(params, `Unknown authorization session "${stateParam}"`);
+        }
+        try {
+            if (errorParam != null) {
+                throw new OAuthCallbackError(params, undefined, stateData.appState);
+            }
+            if (!codeParam) {
+                throw new OAuthCallbackError(params, 'Missing "code" query param', stateData.appState);
+            }
+            const server = await this.serverFactory.fromIssuer(stateData.iss, 
+            // Using the literal 'legacy' if the authMethod is not defined (because stateData was created through an old version of this lib)
+            stateData.authMethod ?? "legacy", stateData.dpopKey);
+            if (issuerParam != null) {
+                if (!server.issuer) {
+                    throw new OAuthCallbackError(params, "Issuer not found in metadata", stateData.appState);
+                }
+                if (server.issuer !== issuerParam) {
+                    throw new OAuthCallbackError(params, "Issuer mismatch", stateData.appState);
+                }
+            }
+            else if (server.serverMetadata.authorization_response_iss_parameter_supported) {
+                throw new OAuthCallbackError(params, "iss missing from the response", stateData.appState);
+            }
+            const tokenSet = await server.exchangeCode(codeParam, stateData.verifier);
+            try {
+                await this.sessionGetter.setStored(tokenSet.sub, {
+                    dpopKey: stateData.dpopKey,
+                    authMethod: server.authMethod,
+                    tokenSet,
+                });
+                const session = this.createSession(server, tokenSet.sub);
+                return { session, state: stateData.appState ?? null };
+            }
+            catch (err) {
+                await server.revoke(tokenSet.refresh_token || tokenSet.access_token);
+                throw err;
+            }
+        }
+        catch (err) {
+            // Make sure, whatever the underlying error, that the appState is
+            // available in the calling code
+            throw OAuthCallbackError.from(err, params, stateData.appState);
+        }
+    }
+    /**
+     * Load a stored session. This will refresh the token only if needed (about to
+     * expire) by default.
+     *
+     * @param refresh See {@link SessionGetter.getSession}
+     */
+    async restore(sub, refresh = "auto") {
+        // sub arg is lightly typed for convenience of library user
+        assertAtprotoDid(sub);
+        const { dpopKey, authMethod = "legacy", tokenSet, } = await this.sessionGetter.get(sub, {
+            noCache: refresh === true,
+            allowStale: refresh === false,
+        });
+        try {
+            const server = await this.serverFactory.fromIssuer(tokenSet.iss, authMethod, dpopKey, {
+                noCache: refresh === true,
+                allowStale: refresh === false,
+            });
+            return this.createSession(server, sub);
+        }
+        catch (err) {
+            if (err instanceof AuthMethodUnsatisfiableError) {
+                await this.sessionGetter.delStored(sub, err);
+            }
+            throw err;
+        }
+    }
+    async revoke(sub) {
+        // sub arg is lightly typed for convenience of library user
+        assertAtprotoDid(sub);
+        const { dpopKey, authMethod = "legacy", tokenSet, } = await this.sessionGetter.get(sub, {
+            allowStale: true,
+        });
+        // NOT using `;(await this.restore(sub, false)).signOut()` because we want
+        // the tokens to be deleted even if it was not possible to fetch the issuer
+        // data.
+        try {
+            const server = await this.serverFactory.fromIssuer(tokenSet.iss, authMethod, dpopKey);
+            await server.revoke(tokenSet.access_token);
+        }
+        finally {
+            await this.sessionGetter.delStored(sub, new TokenRevokedError(sub));
+        }
+    }
+    createSession(server, sub) {
+        return new OAuthSession(server, sub, this.sessionGetter, this.fetch);
+    }
+}

package/lib/oauth-client/oauth-protected-resource-metadata-resolver.d.ts

@@ -0,0 +1,18 @@
+import { OAuthProtectedResourceMetadata } from "@atproto/oauth-types";
+import { Fetch } from "@atproto-labs/fetch";
+import { CachedGetter, GetCachedOptions, SimpleStore } from "@atproto-labs/simple-store";
+export type { GetCachedOptions, OAuthProtectedResourceMetadata };
+export type ProtectedResourceMetadataCache = SimpleStore<string, OAuthProtectedResourceMetadata>;
+export type OAuthProtectedResourceMetadataResolverConfig = {
+    allowHttpResource?: boolean;
+};
+/**
+ * @see {@link https://datatracker.ietf.org/doc/html/draft-ietf-oauth-resource-metadata-05}
+ */
+export declare class OAuthProtectedResourceMetadataResolver extends CachedGetter<string, OAuthProtectedResourceMetadata> {
+    private readonly fetch;
+    private readonly allowHttpResource;
+    constructor(cache: ProtectedResourceMetadataCache, fetch?: Fetch, config?: OAuthProtectedResourceMetadataResolverConfig);
+    get(resource: string | URL, options?: GetCachedOptions): Promise<OAuthProtectedResourceMetadata>;
+    private fetchMetadata;
+}

package/lib/oauth-client/oauth-protected-resource-metadata-resolver.js

@@ -0,0 +1,49 @@
+import { oauthProtectedResourceMetadataSchema, } from "@atproto/oauth-types";
+import { FetchResponseError, bindFetch, cancelBody, } from "@atproto-labs/fetch";
+import { CachedGetter, } from "@atproto-labs/simple-store";
+import { contentMime } from "./util.js";
+/**
+ * @see {@link https://datatracker.ietf.org/doc/html/draft-ietf-oauth-resource-metadata-05}
+ */
+export class OAuthProtectedResourceMetadataResolver extends CachedGetter {
+    constructor(cache, fetch = globalThis.fetch, config) {
+        super(async (origin, options) => this.fetchMetadata(origin, options), cache);
+        this.fetch = bindFetch(fetch);
+        this.allowHttpResource = config?.allowHttpResource === true;
+    }
+    async get(resource, options) {
+        const { protocol, origin } = new URL(resource);
+        if (protocol !== "https:" && protocol !== "http:") {
+            throw new TypeError(`Invalid protected resource metadata URL protocol: ${protocol}`);
+        }
+        if (protocol === "http:" && !this.allowHttpResource) {
+            throw new TypeError(`Unsecure resource metadata URL (${protocol}) only allowed in development and test environments`);
+        }
+        return super.get(origin, options);
+    }
+    async fetchMetadata(origin, options) {
+        const url = new URL(`/.well-known/oauth-protected-resource`, origin);
+        const request = new Request(url, {
+            signal: options?.signal,
+            headers: { accept: "application/json", "cache-control": "no-cache" },
+            // cache: options?.noCache ? "no-cache" : undefined,
+            redirect: "manual", // response must be 200 OK
+        });
+        const response = await this.fetch(request);
+        // https://datatracker.ietf.org/doc/html/draft-ietf-oauth-resource-metadata-05#section-3.2
+        if (response.status !== 200) {
+            await cancelBody(response, "log");
+            throw await FetchResponseError.from(response, `Unexpected status code ${response.status} for "${url}"`, undefined, { cause: request });
+        }
+        if (contentMime(response.headers) !== "application/json") {
+            await cancelBody(response, "log");
+            throw await FetchResponseError.from(response, `Unexpected content type for "${url}"`, undefined, { cause: request });
+        }
+        const metadata = oauthProtectedResourceMetadataSchema.parse(await response.json());
+        // https://datatracker.ietf.org/doc/html/draft-ietf-oauth-resource-metadata-05#section-3.3
+        if (metadata.resource !== origin) {
+            throw new TypeError(`Invalid issuer ${metadata.resource}`);
+        }
+        return metadata;
+    }
+}

package/lib/oauth-client/oauth-resolver-error.d.ts

@@ -0,0 +1,6 @@
+export declare class OAuthResolverError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+    static from(cause: unknown, message?: string): OAuthResolverError;
+}

package/lib/oauth-client/oauth-resolver-error.js

@@ -0,0 +1,18 @@
+import { ZodError } from "zod";
+export class OAuthResolverError extends Error {
+    constructor(message, options) {
+        super(message, options);
+    }
+    static from(cause, message) {
+        if (cause instanceof OAuthResolverError)
+            return cause;
+        const validationReason = cause instanceof ZodError
+            ? `${cause.errors[0].path} ${cause.errors[0].message}`
+            : null;
+        const fullMessage = (message ?? `Unable to resolve identity`) +
+            (validationReason ? ` (${validationReason})` : "");
+        return new OAuthResolverError(fullMessage, {
+            cause,
+        });
+    }
+}

package/lib/oauth-client/oauth-resolver.d.ts

@@ -0,0 +1,71 @@
+import { OAuthAuthorizationServerMetadata } from "@atproto/oauth-types";
+import { IdentityInfo, IdentityResolver, ResolveIdentityOptions } from "#identity-resolver";
+import { GetCachedOptions, OAuthAuthorizationServerMetadataResolver } from "./oauth-authorization-server-metadata-resolver.js";
+import { OAuthProtectedResourceMetadataResolver } from "./oauth-protected-resource-metadata-resolver.js";
+export type { GetCachedOptions };
+export type ResolveOAuthOptions = GetCachedOptions & ResolveIdentityOptions;
+export declare class OAuthResolver {
+    readonly identityResolver: IdentityResolver;
+    readonly protectedResourceMetadataResolver: OAuthProtectedResourceMetadataResolver;
+    readonly authorizationServerMetadataResolver: OAuthAuthorizationServerMetadataResolver;
+    constructor(identityResolver: IdentityResolver, protectedResourceMetadataResolver: OAuthProtectedResourceMetadataResolver, authorizationServerMetadataResolver: OAuthAuthorizationServerMetadataResolver);
+    /**
+     * @param input - A handle, DID, PDS URL or Entryway URL
+     */
+    resolve(input: string, options?: ResolveOAuthOptions): Promise<{
+        identityInfo?: IdentityInfo;
+        metadata: OAuthAuthorizationServerMetadata;
+    }>;
+    /**
+     * @note this method can be used to verify if a particular uri supports OAuth
+     * based sign-in (for compatibility with legacy implementation).
+     */
+    resolveFromService(input: string, options?: ResolveOAuthOptions): Promise<{
+        metadata: OAuthAuthorizationServerMetadata;
+    }>;
+    resolveFromIdentity(input: string, options?: ResolveOAuthOptions): Promise<{
+        identityInfo: IdentityInfo;
+        metadata: OAuthAuthorizationServerMetadata;
+        pds: URL;
+    }>;
+    resolveIdentity(input: string, options?: ResolveIdentityOptions): Promise<IdentityInfo>;
+    getAuthorizationServerMetadata(issuer: string, options?: GetCachedOptions): Promise<OAuthAuthorizationServerMetadata>;
+    getResourceServerMetadata(pdsUrl: string | URL, options?: GetCachedOptions): Promise<{
+        issuer: `http://[::1]${string}` | "http://localhost" | `http://localhost#${string}` | `http://localhost?${string}` | `http://localhost/${string}` | `http://localhost:${string}` | "http://127.0.0.1" | `http://127.0.0.1#${string}` | `http://127.0.0.1?${string}` | `http://127.0.0.1/${string}` | `http://127.0.0.1:${string}` | `https://${string}`;
+        authorization_endpoint: `http://[::1]${string}` | "http://localhost" | `http://localhost#${string}` | `http://localhost?${string}` | `http://localhost/${string}` | `http://localhost:${string}` | "http://127.0.0.1" | `http://127.0.0.1#${string}` | `http://127.0.0.1?${string}` | `http://127.0.0.1/${string}` | `http://127.0.0.1:${string}` | `https://${string}`;
+        token_endpoint: `http://[::1]${string}` | "http://localhost" | `http://localhost#${string}` | `http://localhost?${string}` | `http://localhost/${string}` | `http://localhost:${string}` | "http://127.0.0.1" | `http://127.0.0.1#${string}` | `http://127.0.0.1?${string}` | `http://127.0.0.1/${string}` | `http://127.0.0.1:${string}` | `https://${string}`;
+        token_endpoint_auth_methods_supported: string[];
+        jwks_uri?: `http://[::1]${string}` | "http://localhost" | `http://localhost#${string}` | `http://localhost?${string}` | `http://localhost/${string}` | `http://localhost:${string}` | "http://127.0.0.1" | `http://127.0.0.1#${string}` | `http://127.0.0.1?${string}` | `http://127.0.0.1/${string}` | `http://127.0.0.1:${string}` | `https://${string}` | undefined;
+        claims_supported?: string[] | undefined;
+        claims_locales_supported?: string[] | undefined;
+        claims_parameter_supported?: boolean | undefined;
+        request_parameter_supported?: boolean | undefined;
+        request_uri_parameter_supported?: boolean | undefined;
+        require_request_uri_registration?: boolean | undefined;
+        scopes_supported?: string[] | undefined;
+        subject_types_supported?: string[] | undefined;
+        response_types_supported?: string[] | undefined;
+        response_modes_supported?: string[] | undefined;
+        grant_types_supported?: string[] | undefined;
+        code_challenge_methods_supported?: ("S256" | "plain")[] | undefined;
+        ui_locales_supported?: string[] | undefined;
+        id_token_signing_alg_values_supported?: string[] | undefined;
+        display_values_supported?: string[] | undefined;
+        request_object_signing_alg_values_supported?: string[] | undefined;
+        authorization_response_iss_parameter_supported?: boolean | undefined;
+        authorization_details_types_supported?: string[] | undefined;
+        request_object_encryption_alg_values_supported?: string[] | undefined;
+        request_object_encryption_enc_values_supported?: string[] | undefined;
+        token_endpoint_auth_signing_alg_values_supported?: string[] | undefined;
+        revocation_endpoint?: `http://[::1]${string}` | "http://localhost" | `http://localhost#${string}` | `http://localhost?${string}` | `http://localhost/${string}` | `http://localhost:${string}` | "http://127.0.0.1" | `http://127.0.0.1#${string}` | `http://127.0.0.1?${string}` | `http://127.0.0.1/${string}` | `http://127.0.0.1:${string}` | `https://${string}` | undefined;
+        introspection_endpoint?: `http://[::1]${string}` | "http://localhost" | `http://localhost#${string}` | `http://localhost?${string}` | `http://localhost/${string}` | `http://localhost:${string}` | "http://127.0.0.1" | `http://127.0.0.1#${string}` | `http://127.0.0.1?${string}` | `http://127.0.0.1/${string}` | `http://127.0.0.1:${string}` | `https://${string}` | undefined;
+        pushed_authorization_request_endpoint?: `http://[::1]${string}` | "http://localhost" | `http://localhost#${string}` | `http://localhost?${string}` | `http://localhost/${string}` | `http://localhost:${string}` | "http://127.0.0.1" | `http://127.0.0.1#${string}` | `http://127.0.0.1?${string}` | `http://127.0.0.1/${string}` | `http://127.0.0.1:${string}` | `https://${string}` | undefined;
+        require_pushed_authorization_requests?: boolean | undefined;
+        userinfo_endpoint?: `http://[::1]${string}` | "http://localhost" | `http://localhost#${string}` | `http://localhost?${string}` | `http://localhost/${string}` | `http://localhost:${string}` | "http://127.0.0.1" | `http://127.0.0.1#${string}` | `http://127.0.0.1?${string}` | `http://127.0.0.1/${string}` | `http://127.0.0.1:${string}` | `https://${string}` | undefined;
+        end_session_endpoint?: `http://[::1]${string}` | "http://localhost" | `http://localhost#${string}` | `http://localhost?${string}` | `http://localhost/${string}` | `http://localhost:${string}` | "http://127.0.0.1" | `http://127.0.0.1#${string}` | `http://127.0.0.1?${string}` | `http://127.0.0.1/${string}` | `http://127.0.0.1:${string}` | `https://${string}` | undefined;
+        registration_endpoint?: `http://[::1]${string}` | "http://localhost" | `http://localhost#${string}` | `http://localhost?${string}` | `http://localhost/${string}` | `http://localhost:${string}` | "http://127.0.0.1" | `http://127.0.0.1#${string}` | `http://127.0.0.1?${string}` | `http://127.0.0.1/${string}` | `http://127.0.0.1:${string}` | `https://${string}` | undefined;
+        dpop_signing_alg_values_supported?: string[] | undefined;
+        protected_resources?: (`http://[::1]${string}` | "http://localhost" | `http://localhost#${string}` | `http://localhost?${string}` | `http://localhost/${string}` | `http://localhost:${string}` | "http://127.0.0.1" | `http://127.0.0.1#${string}` | `http://127.0.0.1?${string}` | `http://127.0.0.1/${string}` | `http://127.0.0.1:${string}` | `https://${string}`)[] | undefined;
+        client_id_metadata_document_supported?: boolean | undefined;
+    }>;
+}

package/lib/oauth-client/oauth-resolver.js

@@ -0,0 +1,117 @@
+import { oauthIssuerIdentifierSchema, } from "@atproto/oauth-types";
+import { OAuthResolverError } from "./oauth-resolver-error.js";
+export class OAuthResolver {
+    constructor(identityResolver, protectedResourceMetadataResolver, authorizationServerMetadataResolver) {
+        this.identityResolver = identityResolver;
+        this.protectedResourceMetadataResolver = protectedResourceMetadataResolver;
+        this.authorizationServerMetadataResolver = authorizationServerMetadataResolver;
+    }
+    /**
+     * @param input - A handle, DID, PDS URL or Entryway URL
+     */
+    async resolve(input, options) {
+        // Allow using an entryway, or PDS url, directly as login input (e.g.
+        // when the user forgot their handle, or when the handle does not
+        // resolve to a DID)
+        return /^https?:\/\//.test(input)
+            ? this.resolveFromService(input, options)
+            : this.resolveFromIdentity(input, options);
+    }
+    /**
+     * @note this method can be used to verify if a particular uri supports OAuth
+     * based sign-in (for compatibility with legacy implementation).
+     */
+    async resolveFromService(input, options) {
+        try {
+            // Assume first that input is a PDS URL (as required by ATPROTO)
+            const metadata = await this.getResourceServerMetadata(input, options);
+            return { metadata };
+        }
+        catch (err) {
+            if (!options?.signal?.aborted && err instanceof OAuthResolverError) {
+                try {
+                    // Fallback to trying to fetch as an issuer (Entryway)
+                    const result = oauthIssuerIdentifierSchema.safeParse(input);
+                    if (result.success) {
+                        const metadata = await this.getAuthorizationServerMetadata(result.data, options);
+                        return { metadata };
+                    }
+                }
+                catch {
+                    // Fallback failed, throw original error
+                }
+            }
+            throw err;
+        }
+    }
+    async resolveFromIdentity(input, options) {
+        const identityInfo = await this.resolveIdentity(input, options);
+        options?.signal?.throwIfAborted();
+        const pds = extractPdsUrl(identityInfo.didDoc);
+        const metadata = await this.getResourceServerMetadata(pds, options);
+        return { identityInfo, metadata, pds };
+    }
+    async resolveIdentity(input, options) {
+        try {
+            return await this.identityResolver.resolve(input, options);
+        }
+        catch (cause) {
+            console.error(cause);
+            throw OAuthResolverError.from(cause, `Failed to resolve identity: ${input}`);
+        }
+    }
+    async getAuthorizationServerMetadata(issuer, options) {
+        try {
+            return await this.authorizationServerMetadataResolver.get(issuer, options);
+        }
+        catch (cause) {
+            console.error(cause);
+            throw OAuthResolverError.from(cause, `Failed to resolve OAuth server metadata for issuer: ${issuer}`);
+        }
+    }
+    async getResourceServerMetadata(pdsUrl, options) {
+        try {
+            const rsMetadata = await this.protectedResourceMetadataResolver.get(pdsUrl, options);
+            // ATPROTO requires one, and only one, authorization server entry
+            if (rsMetadata.authorization_servers?.length !== 1) {
+                throw new OAuthResolverError(rsMetadata.authorization_servers?.length
+                    ? `Unable to determine authorization server for PDS: ${pdsUrl}`
+                    : `No authorization servers found for PDS: ${pdsUrl}`);
+            }
+            const issuer = rsMetadata.authorization_servers[0];
+            options?.signal?.throwIfAborted();
+            const asMetadata = await this.getAuthorizationServerMetadata(issuer, options);
+            // https://datatracker.ietf.org/doc/html/draft-ietf-oauth-resource-metadata-05#section-4
+            if (asMetadata.protected_resources) {
+                if (!asMetadata.protected_resources.includes(rsMetadata.resource)) {
+                    throw new OAuthResolverError(`PDS "${pdsUrl}" not protected by issuer "${issuer}"`);
+                }
+            }
+            return asMetadata;
+        }
+        catch (cause) {
+            console.error(cause);
+            throw OAuthResolverError.from(cause, `Failed to resolve OAuth server metadata for resource: ${pdsUrl}`);
+        }
+    }
+}
+function isAtprotoPersonalDataServerService(s) {
+    return (typeof s.serviceEndpoint === "string" &&
+        s.type === "AtprotoPersonalDataServer" &&
+        (s.id.startsWith("#")
+            ? s.id === "#atproto_pds"
+            : s.id === `${this.id}#atproto_pds`));
+}
+function extractPdsUrl(document) {
+    const service = document.service?.find((isAtprotoPersonalDataServerService), document);
+    if (!service) {
+        throw new OAuthResolverError(`Identity "${document.id}" does not have a PDS URL`);
+    }
+    try {
+        return new URL(service.serviceEndpoint);
+    }
+    catch (cause) {
+        console.error(cause);
+        throw new OAuthResolverError(`Invalid PDS URL in DID document: ${service.serviceEndpoint}`, { cause });
+    }
+}

package/lib/oauth-client/oauth-response-error.d.ts

@@ -0,0 +1,10 @@
+import { Json } from "@atproto-labs/fetch";
+export declare class OAuthResponseError extends Error {
+    readonly response: Response;
+    readonly payload: Json;
+    readonly error?: string;
+    readonly errorDescription?: string;
+    constructor(response: Response, payload: Json);
+    get status(): number;
+    get headers(): Headers;
+}

package/lib/oauth-client/oauth-response-error.js

@@ -0,0 +1,22 @@
+import { ifString } from "./util.js";
+export class OAuthResponseError extends Error {
+    constructor(response, payload) {
+        const objPayload = typeof payload === "object" ? payload : undefined;
+        const error = ifString(objPayload?.["error"]);
+        const errorDescription = ifString(objPayload?.["error_description"]);
+        const messageError = error ? `"${error}"` : "unknown";
+        const messageDesc = errorDescription ? `: ${errorDescription}` : "";
+        const message = `OAuth ${messageError} error${messageDesc}`;
+        super(message);
+        this.response = response;
+        this.payload = payload;
+        this.error = error;
+        this.errorDescription = errorDescription;
+    }
+    get status() {
+        return this.response.status;
+    }
+    get headers() {
+        return this.response.headers;
+    }
+}

package/lib/oauth-client/oauth-server-agent.d.ts

@@ -0,0 +1,54 @@
+import { AtprotoDid } from "@atproto/did";
+import { Key, Keyset } from "@atproto/jwk";
+import { OAuthAuthorizationRequestPar, OAuthAuthorizationServerMetadata, OAuthEndpointName, OAuthParResponse, OAuthTokenRequest } from "@atproto/oauth-types";
+import { Fetch, Json } from "@atproto-labs/fetch";
+import { SimpleStore } from "@atproto-labs/simple-store";
+import { AtprotoScope, AtprotoTokenResponse } from "./atproto-token-response.js";
+import { ClientAuthMethod, ClientCredentialsFactory } from "./oauth-client-auth.js";
+import { OAuthResolver } from "./oauth-resolver.js";
+import { Runtime } from "./runtime.js";
+import { ClientMetadata } from "./types.js";
+export type TokenSet = {
+    iss: string;
+    sub: AtprotoDid;
+    aud: string;
+    scope: AtprotoScope;
+    refresh_token?: string;
+    access_token: string;
+    token_type: "DPoP";
+    /** ISO Date */
+    expires_at?: string;
+};
+export type DpopNonceCache = SimpleStore<string, string>;
+export declare class OAuthServerAgent {
+    readonly authMethod: ClientAuthMethod;
+    readonly dpopKey: Key;
+    readonly serverMetadata: OAuthAuthorizationServerMetadata;
+    readonly clientMetadata: ClientMetadata;
+    readonly dpopNonces: DpopNonceCache;
+    readonly oauthResolver: OAuthResolver;
+    readonly runtime: Runtime;
+    readonly keyset?: Keyset | undefined;
+    protected dpopFetch: Fetch<unknown>;
+    protected clientCredentialsFactory: ClientCredentialsFactory;
+    /**
+     * @throws see {@link createClientCredentialsFactory}
+     */
+    constructor(authMethod: ClientAuthMethod, dpopKey: Key, serverMetadata: OAuthAuthorizationServerMetadata, clientMetadata: ClientMetadata, dpopNonces: DpopNonceCache, oauthResolver: OAuthResolver, runtime: Runtime, keyset?: Keyset | undefined, fetch?: Fetch);
+    get issuer(): `http://[::1]${string}` | "http://localhost" | `http://localhost#${string}` | `http://localhost?${string}` | `http://localhost/${string}` | `http://localhost:${string}` | "http://127.0.0.1" | `http://127.0.0.1#${string}` | `http://127.0.0.1?${string}` | `http://127.0.0.1/${string}` | `http://127.0.0.1:${string}` | `https://${string}`;
+    revoke(token: string): Promise<void>;
+    exchangeCode(code: string, codeVerifier?: string): Promise<TokenSet>;
+    refresh(tokenSet: TokenSet): Promise<TokenSet>;
+    /**
+     * VERY IMPORTANT ! Always call this to process token responses.
+     *
+     * Whenever an OAuth token response is received, we **MUST** verify that the
+     * "sub" is a DID, whose issuer authority is indeed the server we just
+     * obtained credentials from. This check is a critical step to actually be
+     * able to use the "sub" (DID) as being the actual user's identifier.
+     *
+     * @returns The user's PDS URL (the resource server for the user)
+     */
+    protected verifyIssuer(sub: AtprotoDid): Promise<string>;
+    request<Endpoint extends OAuthEndpointName>(endpoint: Endpoint, payload: Endpoint extends "token" ? OAuthTokenRequest : Endpoint extends "pushed_authorization_request" ? OAuthAuthorizationRequestPar : Record<string, unknown>): Promise<Endpoint extends "token" ? AtprotoTokenResponse : Endpoint extends "pushed_authorization_request" ? OAuthParResponse : Json>;
+}