atproto-better-auth 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,211 @@
+import type { User } from "better-auth";
+import type { NodeOAuthClientOptions } from "@atproto/oauth-client-node";
+/**
+ * ES256 JSON Web Key with private key component
+ */
+export interface ES256PrivateJwk {
+    kty: "EC";
+    crv: "P-256";
+    x: string;
+    y: string;
+    d: string;
+    alg?: "ES256";
+    kid?: string;
+}
+/**
+ * ES256 JSON Web Key (public only, for JWKS endpoint)
+ */
+export interface ES256PublicJwk {
+    kty: "EC";
+    crv: "P-256";
+    x: string;
+    y: string;
+    alg?: "ES256";
+    kid?: string;
+}
+/**
+ * OAuth client metadata that must be served at the clientId URL
+ */
+export interface AtprotoClientMetadata {
+    client_id: string;
+    client_name: string;
+    client_uri?: string;
+    logo_uri?: string;
+    tos_uri?: string;
+    policy_uri?: string;
+    redirect_uris: string[];
+    grant_types: ["authorization_code", "refresh_token"];
+    response_types: ["code"];
+    scope: string;
+    dpop_bound_access_tokens: true;
+    application_type: "web" | "native";
+    token_endpoint_auth_method: "private_key_jwt" | "none";
+    token_endpoint_auth_signing_alg?: "ES256";
+    jwks_uri?: string;
+}
+/**
+ * ATProto user profile information
+ */
+export interface AtprotoProfile {
+    did: string;
+    handle: string;
+    displayName?: string;
+    avatar?: string;
+    description?: string;
+    banner?: string;
+}
+/**
+ * Client metadata input with required URLs.
+ * Used for utility functions like createClientMetadata() where URLs cannot be auto-derived.
+ */
+export interface AtprotoClientMetadataInput {
+    /**
+     * Human-readable name of your application
+     */
+    clientName: string;
+    /**
+     * The URL where your client-metadata.json is hosted.
+     * This becomes your OAuth client_id.
+     */
+    clientId: string;
+    /**
+     * Homepage URL for your application.
+     */
+    clientUri?: string;
+    /**
+     * URL to your application's logo
+     */
+    logoUri?: string;
+    /**
+     * URL to your terms of service
+     */
+    tosUri?: string;
+    /**
+     * URL to your privacy policy
+     */
+    policyUri?: string;
+    /**
+     * OAuth redirect URIs. Should include your callback endpoint.
+     */
+    redirectUris: string[];
+    /**
+     * OAuth scopes to request. Defaults to "atproto transition:generic"
+     */
+    scope?: string;
+    /**
+     * URL where your JWKS (public keys) are hosted.
+     * Required for confidential (web service) clients.
+     */
+    jwksUri?: string;
+}
+/**
+ * Plugin configuration options
+ */
+export interface AtprotoAuthOptions {
+    /**
+     * Client metadata configuration.
+     * URLs are automatically derived from Better Auth's baseURL unless explicitly set.
+     */
+    clientMetadata: {
+        /**
+         * Human-readable name of your application
+         */
+        clientName: string;
+        /**
+         * The URL where your client-metadata.json is hosted.
+         * This becomes your OAuth client_id.
+         * Defaults to `{baseURL}/client-metadata.json`
+         */
+        clientId?: string;
+        /**
+         * Homepage URL for your application.
+         * Defaults to Better Auth's baseURL (with /api/auth stripped).
+         */
+        clientUri?: string;
+        /**
+         * URL to your application's logo
+         */
+        logoUri?: string;
+        /**
+         * URL to your terms of service
+         */
+        tosUri?: string;
+        /**
+         * URL to your privacy policy
+         */
+        policyUri?: string;
+        /**
+         * OAuth redirect URIs. Should include your callback endpoint.
+         * Defaults to `[{baseURL}/callback/atproto]`
+         */
+        redirectUris?: string[];
+        /**
+         * OAuth scopes to request. Defaults to "atproto transition:generic"
+         */
+        scope?: string;
+        /**
+         * URL where your JWKS (public keys) are hosted.
+         * Required for confidential (web service) clients.
+         * Defaults to `{appBaseURL}/jwks.json`
+         */
+        jwksUri?: string;
+    };
+    /**
+     * ES256 private key in JWK format.
+     * Must include the "d" (private key) component.
+     * Generate at https://jwkset.com/generate with:
+     * - Key type: ECDSA
+     * - Key algorithm: ES256
+     * - Key use: Signature
+     */
+    privateKey: ES256PrivateJwk;
+    /**
+     * Map ATProto profile to user fields during account creation/linking
+     */
+    mapProfileToUser?: (profile: AtprotoProfile) => Partial<User>;
+    /**
+     * Custom NodeOAuthClient options for advanced configuration.
+     * Merged with generated options from clientMetadata.
+     */
+    oauthClientOptions?: Partial<NodeOAuthClientOptions>;
+}
+/**
+ * Stored OAuth state during authorization flow
+ */
+export interface AtprotoStateRecord {
+    key: string;
+    state: string;
+    expiresAt: Date;
+}
+/**
+ * Stored ATProto OAuth session
+ */
+export interface AtprotoSessionRecord {
+    did: string;
+    session: string;
+    userId: string;
+    updatedAt: Date;
+}
+/**
+ * ATProto session info returned to client
+ */
+export interface AtprotoSessionInfo {
+    did: string;
+    handle: string;
+    displayName?: string;
+    avatar?: string;
+    active: boolean;
+}
+/**
+ * Sign-in request parameters
+ */
+export interface AtprotoSignInParams {
+    /**
+     * The user's ATProto handle (e.g., "user.bsky.social")
+     */
+    handle: string;
+    /**
+     * URL to redirect to after successful authentication
+     */
+    callbackURL?: string;
+}

package/dist/utils.d.ts

@@ -0,0 +1,88 @@
+import type { ES256PrivateJwk, ES256PublicJwk, AtprotoClientMetadata, AtprotoClientMetadataInput } from "./types.js";
+/**
+ * Extracts the public key from an ES256 private JWK.
+ * Use this to create your JWKS endpoint content.
+ *
+ * @param privateKey - The ES256 private key in JWK format
+ * @returns The public key in JWK format (without the "d" component)
+ */
+export declare function getPublicJwk(privateKey: ES256PrivateJwk): ES256PublicJwk;
+/**
+ * Creates a JWKS (JSON Web Key Set) object from a private key.
+ * This is what should be served at your /jwks.json endpoint.
+ *
+ * @param privateKey - The ES256 private key in JWK format
+ * @returns A JWKS object with the public key
+ */
+export declare function createJwks(privateKey: ES256PrivateJwk): {
+    keys: ES256PublicJwk[];
+};
+/**
+ * Options for createClientMetadata utility function.
+ */
+export interface CreateClientMetadataOptions {
+    clientMetadata: AtprotoClientMetadataInput;
+    privateKey: ES256PrivateJwk;
+}
+/**
+ * Creates the client metadata object for the /client-metadata.json endpoint.
+ *
+ * @param options - The client metadata and private key
+ * @returns The client metadata object to serve at your clientId URL
+ */
+export declare function createClientMetadata(options: CreateClientMetadataOptions): AtprotoClientMetadata;
+/**
+ * Generates a new ES256 key pair for ATProto OAuth.
+ *
+ * Note: This uses the Web Crypto API which is available in Node.js 15+
+ * and modern browsers. For older environments, use a library like jose.
+ *
+ * @returns A promise that resolves to an ES256 private key in JWK format
+ */
+export declare function generateES256Key(): Promise<ES256PrivateJwk>;
+/**
+ * Validates that a JWK has all required fields for an ES256 private key.
+ *
+ * @param jwk - The JWK to validate
+ * @returns True if the JWK is a valid ES256 private key
+ */
+export declare function isValidES256PrivateKey(jwk: unknown): jwk is ES256PrivateJwk;
+/**
+ * Helper to create a Next.js API route handler for /client-metadata.json
+ *
+ * @example
+ * ```ts
+ * // app/client-metadata.json/route.ts
+ * import { createClientMetadataHandler } from "atproto-better-auth/utils";
+ *
+ * export const GET = createClientMetadataHandler({
+ *   clientMetadata: {
+ *     clientId: "https://example.com/client-metadata.json",
+ *     clientName: "My App",
+ *     redirectUris: ["https://example.com/api/auth/callback/atproto"],
+ *     jwksUri: "https://example.com/jwks.json",
+ *   },
+ *   privateKey,
+ * });
+ * ```
+ */
+export declare function createClientMetadataHandler(options: CreateClientMetadataOptions): () => Response;
+/**
+ * Helper to create a Next.js API route handler for /jwks.json
+ *
+ * @example
+ * ```ts
+ * // app/jwks.json/route.ts
+ * import { createJwksHandler } from "atproto-better-auth/utils";
+ * import { authOptions } from "@/lib/auth";
+ *
+ * export const GET = createJwksHandler(authOptions.privateKey);
+ * ```
+ */
+export declare function createJwksHandler(privateKey: ES256PrivateJwk): () => Response;
+/**
+ * Default scopes for ATProto OAuth.
+ * - atproto: Required for all ATProto OAuth requests
+ * - transition:generic: Transitional scope for general API access
+ */
+export declare const DEFAULT_ATPROTO_SCOPES = "atproto transition:generic";

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "atproto-better-auth",
+  "version": "0.1.0",
+  "description": "A better-auth plugin for ATProto/Bluesky OAuth authentication",
+  "author": "AugusDogus",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./client": {
+      "import": "./dist/client.js",
+      "types": "./dist/client.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "better-auth",
+    "atproto",
+    "bluesky",
+    "oauth",
+    "authentication"
+  ],
+  "homepage": "https://github.com/AugusDogus/atproto-better-auth",
+  "repository": "github:AugusDogus/atproto-better-auth",
+  "bugs": "https://github.com/AugusDogus/atproto-better-auth/issues",
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "bun run clean && bun build:types && bun build:js",
+    "build:js": "bun build ./src/index.ts ./src/client.ts --outdir ./dist --target node --format esm --splitting --packages external",
+    "build:types": "tsc",
+    "test": "bun test",
+    "prepublishOnly": "cp ../../README.md .",
+    "release": "bumpp --commit --push --tag"
+  },
+  "peerDependencies": {
+    "better-auth": ">=1.0.0"
+  },
+  "dependencies": {
+    "@atproto/api": "^0.18.17",
+    "@atproto/oauth-client-node": "^0.3.15",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.6",
+    "better-auth": "^1.4.17",
+    "bumpp": "^10.4.0",
+    "typescript": "^5.9.3"
+  }
+}