@opencoredev/social-sdk 0.3.0 → 0.4.0

package/dist/server/bluesky-oauth.d.ts

@@ -0,0 +1,177 @@
+import { type JsonValue } from "../core/types.js";
+import type { ConnectionAccount, ConnectionAttempt, ConnectionProvider } from "./connections.js";
+/** ES256 client signing key for confidential clients (`private_key_jwt`). */
+export interface BlueskyOAuthSigningKey {
+    /** Key ID published in the client metadata `jwks` or `jwks_uri`. */
+    readonly kid: string;
+    /** Private P-256 JWK. Keep it in a server-side secret store. */
+    readonly privateJwk: JsonWebKey;
+}
+export interface BlueskyOAuthRequestOptions {
+    readonly fetch?: typeof globalThis.fetch;
+    /** Maximum time for one HTTP request or DNS lookup. Defaults to ten seconds. */
+    readonly timeoutMs?: number;
+    /** Maximum response body size. Defaults to one MiB. */
+    readonly maxResponseBytes?: number;
+    /**
+     * DNS TXT lookup used for `_atproto.<handle>`. Defaults to `resolveTxt` from
+     * `node:dns/promises`, loaded on first use.
+     */
+    readonly resolveTxt?: (hostname: string) => Promise<readonly (readonly string[])[]>;
+    /** PLC directory used for `did:plc` documents. Defaults to https://plc.directory. */
+    readonly plcDirectoryUrl?: string;
+    /**
+     * Extra check run before every outgoing request and every redirect hop, after
+     * the built-in checks. The built-in checks allow only HTTPS, reject `localhost`
+     * names, and reject IP-literal hosts in loopback, private, link-local, CGNAT,
+     * multicast, and reserved ranges. They cannot see where a hostname resolves.
+     * Throw to block the request. For DNS-level protection, also pass a `fetch`
+     * that pins resolved addresses, since a lookup here can differ from the one
+     * `fetch` makes.
+     */
+    readonly assertEgressAllowed?: (url: URL) => void | Promise<void>;
+}
+export interface BlueskyOAuthClientOptions extends BlueskyOAuthRequestOptions {
+    /** URL of the client metadata document, or a `http://localhost` development client ID. */
+    readonly clientId: string;
+    /** Present for confidential clients. Public clients omit it. */
+    readonly clientKey?: BlueskyOAuthSigningKey;
+}
+/** A DPoP-bound AT Protocol OAuth session. Contains secrets; store it encrypted. */
+export interface BlueskyOAuthSession {
+    readonly version: 1;
+    readonly did: string;
+    readonly handle?: string;
+    /** Verified PDS origin. XRPC requests go here. */
+    readonly pdsUrl: string;
+    readonly issuer: string;
+    readonly clientId: string;
+    readonly authMethod: "none" | "private_key_jwt";
+    readonly clientKeyId?: string;
+    readonly accessToken: string;
+    readonly refreshToken?: string;
+    readonly expiresAt?: string;
+    readonly scopes: readonly string[];
+    /** Private P-256 DPoP key bound to this session's tokens. */
+    readonly dpopKey: JsonWebKey;
+}
+export interface BlueskyOAuthSessionSink {
+    save(input: {
+        readonly account: ConnectionAccount;
+        readonly session: BlueskyOAuthSession;
+        readonly attempt: ConnectionAttempt;
+    }): Promise<void>;
+}
+export interface BlueskyOAuthOptions extends BlueskyOAuthClientOptions {
+    readonly redirectUri?: string;
+    /** Space-separated scopes. Must include `atproto`. Defaults to `atproto transition:generic`. */
+    readonly scope?: string;
+    /**
+     * Handle, DID, or HTTPS server URL used when `ConnectionManager.begin` has no
+     * `loginHint`. For example `https://bsky.social`.
+     */
+    readonly defaultServer?: string;
+    /** Receives the verified session. Without a sink the session is discarded. */
+    readonly sessionSink?: BlueskyOAuthSessionSink;
+}
+export interface BlueskyOAuthTransport {
+    readonly did: string;
+    /** Verified PDS origin, suitable for the adapter's `auth.service`. */
+    readonly service: string;
+    fetchHandler(pathname: string, init?: RequestInit): Promise<Response>;
+}
+export interface BlueskyOAuthClientMetadataInput {
+    /** HTTPS URL where this document is served. */
+    readonly clientId: string;
+    readonly redirectUris: readonly string[];
+    /** Every scope the client may request. Must include `atproto`. */
+    readonly scope: string;
+    readonly applicationType?: "web" | "native";
+    readonly clientName?: string;
+    readonly clientUri?: string;
+    readonly logoUri?: string;
+    readonly tosUri?: string;
+    readonly policyUri?: string;
+    /** Confidential clients publish exactly one of `jwksUri` or `jwks`. */
+    readonly jwksUri?: string;
+    readonly jwks?: {
+        readonly keys: readonly BlueskyOAuthPublishedJwk[];
+    };
+}
+/** A public signing key in the client metadata `jwks` document. */
+export type BlueskyOAuthPublishedJwk = JsonWebKey & {
+    readonly kid?: string;
+};
+export interface BlueskyOAuthClientMetadata {
+    readonly client_id: string;
+    readonly application_type: "web" | "native";
+    readonly grant_types: readonly ["authorization_code", "refresh_token"];
+    readonly response_types: readonly ["code"];
+    readonly scope: string;
+    readonly redirect_uris: readonly string[];
+    readonly dpop_bound_access_tokens: true;
+    readonly token_endpoint_auth_method: "none" | "private_key_jwt";
+    readonly token_endpoint_auth_signing_alg?: "ES256";
+    readonly jwks_uri?: string;
+    readonly jwks?: {
+        readonly keys: readonly JsonWebKey[];
+    };
+    readonly client_name?: string;
+    readonly client_uri?: string;
+    readonly logo_uri?: string;
+    readonly tos_uri?: string;
+    readonly policy_uri?: string;
+}
+/** Public JWK for the client metadata `jwks` document. Never publish the private key. */
+export declare function blueskyOAuthPublicJwk(key: BlueskyOAuthSigningKey): JsonWebKey & {
+    readonly kid: string;
+    readonly alg: "ES256";
+    readonly use: "sig";
+};
+/**
+ * AT Protocol OAuth for Bluesky accounts, driven by `ConnectionManager`.
+ *
+ * `start` resolves the login hint to an authorization server, generates a DPoP
+ * key, and sends a pushed authorization request with the manager's PKCE
+ * challenge and state. `complete` checks `iss`, exchanges the code with DPoP,
+ * and verifies that the returned DID's PDS names the same issuer before the
+ * account is returned or the session reaches `sessionSink`.
+ */
+export declare function blueskyOAuth(options: BlueskyOAuthOptions): ConnectionProvider;
+/**
+ * Validate a session loaded from storage before using it. Pass the decoded JSON
+ * document, for example the result of `JSON.parse` on the decrypted session.
+ */
+export declare function parseBlueskyOAuthSession(value: BlueskyOAuthSession | JsonValue): BlueskyOAuthSession;
+/**
+ * DPoP transport for the Bluesky adapter's `session` option. Every request gets
+ * `Authorization: DPoP <token>` and a fresh proof with `ath`. When the PDS
+ * answers 401 with `use_dpop_nonce`, a replayable request is sent once more with
+ * the new nonce (RFC 9449 section 9). It never refreshes tokens; call
+ * `refreshBlueskyOAuthSession` before `expiresAt`.
+ *
+ * A PDS response without a `DPoP-Nonce` header is returned rather than rejected:
+ * by then the PDS has already processed the request, and turning a completed
+ * write into an error would hide its outcome.
+ */
+export declare function blueskyOAuthTransport(session: BlueskyOAuthSession, options?: Pick<BlueskyOAuthRequestOptions, "fetch" | "assertEgressAllowed">): BlueskyOAuthTransport;
+/**
+ * Refresh a session with its own DPoP key and client authentication. The
+ * account's PDS is resolved again first, and the refresh fails unless it still
+ * names the session issuer. Refresh tokens rotate, so store the result with a
+ * compare-and-set write (for example `CredentialManager.rotate`).
+ */
+export declare function refreshBlueskyOAuthSession(session: BlueskyOAuthSession, options: BlueskyOAuthClientOptions): Promise<BlueskyOAuthSession>;
+/**
+ * Build and validate the client metadata document to serve at `clientId`.
+ * Adding `jwks` or `jwksUri` makes the client confidential (`private_key_jwt`).
+ */
+export declare function blueskyOAuthClientMetadata(input: BlueskyOAuthClientMetadataInput): BlueskyOAuthClientMetadata;
+/**
+ * Development client ID for a public client running on a loopback address. The
+ * authorization server derives its metadata from these query parameters.
+ */
+export declare function blueskyLoopbackClientId(input?: {
+    readonly redirectUris?: readonly string[];
+    readonly scope?: string;
+}): string;