@atpassport/client 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,74 @@
+# @atpassport/client
+
+[@passport](https://atpassport.net) is an authentication provider tailored for the atproto ecosystem.
+Using this client library, you can easily integrate a @passport-powered "handle input assist feature" into your applications (such as browser extensions or web apps) with an OAuth-like flow.
+
+*For the Japanese documentation, please see [README_ja.md](./README_ja.md).*
+
+## Features
+- **Zero dependencies**
+- **OAuth-like secure integration flow** (Built-in CSRF protection via `atpstate`)
+- **Custom parameter passthrough** (Query parameters attached to the callback URL are automatically returned)
+
+## Installation
+
+```bash
+npm install @atpassport/client
+# or
+pnpm add @atpassport/client
+```
+
+## Usage
+
+```typescript
+import { AtPassport } from '@atpassport/client';
+
+// 1. Initialize the client
+const passport = new AtPassport({
+  callbackUrl: 'https://myapp.com/oauth/login' // Required: the URL to redirect back to
+});
+
+// 2. (Optional) Generate the authentication URL and redirect
+// You can pass custom parameters (e.g., redirect_uri to return to the original page)
+const { url, atpstate } = passport.generateAuthUrl({
+  redirect_uri: '/dashboard'
+});
+
+// 3. (Optional) For security, save the generated atpstate to sessionStorage or cookies to prevent CSRF
+sessionStorage.setItem('atpstate', atpstate);
+
+// 4. Redirect the user to the @passport handle selection screen
+window.location.assign(url);
+```
+
+```typescript
+// Receive the parameters on your callback page (https://myapp.com/oauth/callback)
+// (Optional) By passing the saved atpstate as the second argument, parseCallback will automatically
+// throw an Error if the states don't match (preventing CSRF attacks).
+const savedState = sessionStorage.getItem('atpstate');
+const result = passport.parseCallback(window.location.href, savedState);
+
+console.log('Login successful:', result);
+console.log('Authenticated User:', result.handle);
+console.log('Custom Parameters:', result.customParams['redirect_uri']); // Outputs '/dashboard'
+```
+
+---
+
+## Explained: Parameters and Placeholders
+
+When @passport redirects back to your `callbackUrl`, the following information will be attached as URL parameters.
+
+### Basic Parameters (Automatically extracted by `parseCallback`)
+- **`handle`**: The authenticated user's Bluesky / atproto handle (e.g., `alice.bsky.social`).
+- **`did`**: The user's Decentralized Identifier (DID). (e.g., `did:plc:xxxxxxxx`. Used to resolve the handle or communicate with the user's PDS.)
+- **`pdsurl`**: The endpoint URL of the user's Personal Data Server (PDS).
+- **`atpstate`**: The state string automatically generated for CSRF protection via `generateAuthUrl()`.
+
+### The `{handle}` and `{did}` Placeholder Replacement Feature
+Depending on the specific API endpoint used for integration or the exact implementation of the integrating client, there is a feature where placing `{handle}` or `{did}` string placeholders inside the `callbackUrl` string will instruct @passport to **dynamically string-replace** them with the actual handle/DID upon completion.
+
+**Example:**
+If the `callbackUrl` was `https://myapp.com/login?handle={handle}`, @passport would redirect back to `https://myapp.com/login?handle=alice.bsky.social`.
+
+*Note: With the standard flow using `@atpassport/client` (`generateAuthUrl` → `parseCallback`), @passport does not rely on string replacement. Instead, it securely appends parameters like `&handle=...` as standardized URL queries. This allows you to simply and securely receive all information using `parseCallback()` without manually formatting placeholders.*

package/README_ja.md

@@ -0,0 +1,73 @@
+# @atpassport/client
+
+[@passport](https://atpassport.net) は、atproto エコシステム向けの認証プロバイダーです。
+このクライアントライブラリを使うことで、あなたのアプリケーション（ブラウザ拡張機能やWebアプリ）に、@passport を利用した「ハンドル入力のアシスト機能」を簡単に組み込むことができます。
+
+*For the English documentation, please see [README.md](./README.md).*
+
+## 特徴
+- 依存関係ゼロ（Zero dependencies）
+- OAuthライクなセキュアな連携フロー（CSRF対策のための `atpstate` 対応）
+- 複数のカスタムパラメータの引き回し（コールバックに付与したパラメータが自動で返却されます）
+
+## インストール
+
+```bash
+npm install @atpassport/client
+# or
+pnpm add @atpassport/client
+```
+
+## 使い方
+
+```typescript
+import { AtPassport } from '@atpassport/client';
+
+// 1. クライアントの初期化
+const passport = new AtPassport({
+  callbackUrl: 'https://myapp.com/oauth/login' // 必須: 認証後に戻ってくるURL
+});
+
+// 2. (任意)認証URLの生成とリダイレクト
+// カスタムパラメータ（例: ログイン後に元いたページに戻すための redirect_uri など）を指定できます
+const { url, atpstate } = passport.generateAuthUrl({
+  redirect_uri: '/dashboard'
+});
+
+// 3.(任意)セキュリティのため、発行された atpstate をセッションや sessionStorage 等に保存します
+sessionStorage.setItem('atpstate', atpstate);
+
+// 4. @passport のハンドル選択画面へリダイレクト
+window.location.assign(url);
+```
+
+```typescript
+// コールバック先 (https://myapp.com/oauth/callback) でのパラメータ受け取り
+// (任意)保存していた atpstate を第2引数に渡すことで、状態が不一致（CSRFの疑い）の場合はエラー（例外）が発生します
+const savedState = sessionStorage.getItem('atpstate');
+const result = passport.parseCallback(window.location.href, savedState);
+
+console.log('ログイン成功:', result);
+console.log('認証ユーザー:', result.handle);
+console.log('カスタムパラメータ:', result.customParams['redirect_uri']); // '/dashboard' が取れる
+```
+
+---
+
+## パラメータ・プレースホルダーの解説
+
+@passport からコールバック URL にリダイレクトされる際、以下の情報が URL パラメータとして付与されます。
+
+### 基本パラメータ（`parseCallback` で自動取得されるもの）
+- **`handle`**: 認証されたユーザーの Bluesky / atproto ハンドル名（例: `alice.bsky.social`）
+- **`did`**: ユーザーの分散型識別子（DID）。（例: `did:plc:xxxxxxxx`。ハンドルの解決やPDSとの通信に利用します）
+- **`pdsurl`**: ユーザーのデータが保存されている PDS (Personal Data Server) のエンドポイント URL。
+- **`atpstate`**: `generateAuthUrl()` で自動生成された CSRF 防止用のステート文字列。リクエスト元の検証に用います。
+
+### `{handle}` などのプレースホルダー置換機能
+特定のエンドポイントを利用した連携や、組み込み先のクライアント実装次第では、`callbackUrl` 内に `{handle}` や `{did}` といった文字列（プレースホルダー）を含めておくことで、認証完了時に @passport 側でユーザーの実際のハンドルや DID に**動的に文字列置換**されてリダイレクトされる機能があります。
+
+**例:**
+`callbackUrl` を `https://myapp.com/login?handle={handle}` にして @passport へ送ると、完了時に `https://myapp.com/login?handle=alice.bsky.social` として戻ってきます。
+
+※ `@atpassport/client` を使った標準の `generateAuthUrl` → `parseCallback` フローでは、@passport はプレースホルダー置換ではなく、安全に `&handle=...` のように標準的なクエリパラメータとして追記する形を採っているため、意識せずに `parseCallback()` だけで全ての情報を簡単に安全に受け取ることができます。

package/dist/__tests__/client.test.js

@@ -1,50 +1,11 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 const vitest_1 = require("vitest");
 const index_1 = require("../index");
-const jose_1 = require("jose");
 (0, vitest_1.describe)('AtPassport', () => {
     const baseUrl = 'https://passport.atproto.com';
     const callbackUrl = 'https://app.com/callback';
-    let privateKey;
-    let publicKey;
     (0, vitest_1.beforeEach)(async () => {
-        const keyPair = await (0, jose_1.generateKeyPair)('RS256');
-        privateKey = await (0, jose_1.exportPKCS8)(keyPair.privateKey);
-        publicKey = await (0, jose_1.exportSPKI)(keyPair.publicKey);
         // Polyfill crypto.randomUUID for vitest environment if needed
         if (typeof crypto === 'undefined' || typeof crypto.randomUUID !== 'function') {
             const g = global;
@@ -70,19 +31,6 @@ const jose_1 = require("jose");
         (0, vitest_1.expect)(parsed.pathname).toBe('/api/resolve');
         (0, vitest_1.expect)(parsed.searchParams.get('callbackUrl')).toBe('https://app.com/resolve-callback');
     });
-    (0, vitest_1.it)('gets session from a valid token', async () => {
-        const passport = new index_1.AtPassport({ baseUrl, callbackUrl, publicKey });
-        const payload = { did: 'did:plc:123', handle: 'alice.bsky.social', uuid: 'uuid-123' };
-        const token = await new jose_1.SignJWT(payload)
-            .setProtectedHeader({ alg: 'RS256' })
-            .setIssuedAt()
-            .setExpirationTime('1h')
-            .setIssuer('atpassport')
-            .sign(await importPKCS8(privateKey, 'RS256'));
-        const verified = await passport.get(token);
-        (0, vitest_1.expect)(verified.did).toBe(payload.did);
-        (0, vitest_1.expect)(verified.handle).toBe(payload.handle);
-    });
     (0, vitest_1.it)('generates correct auth URL and state', () => {
         const passport = new index_1.AtPassport({ baseUrl, callbackUrl });
         const { url, atpstate } = passport.generateAuthUrl({ theme: 'dark' });
@@ -97,7 +45,7 @@ const jose_1 = require("jose");
     (0, vitest_1.it)('parses callback URL correctly', () => {
         const passport = new index_1.AtPassport({ callbackUrl });
         const testUrl = 'https://app.com/callback?handle=alice.bsky.social&did=did:plc:123&pdsurl=https://pds.example.com&atpstate=test-state&extra=param';
-        const result = passport.parseCallback(testUrl);
+        const result = passport.parseCallback(testUrl, 'test-state');
         (0, vitest_1.expect)(result.handle).toBe('alice.bsky.social');
         (0, vitest_1.expect)(result.did).toBe('did:plc:123');
         (0, vitest_1.expect)(result.pdsUrl).toBe('https://pds.example.com');
@@ -105,8 +53,9 @@ const jose_1 = require("jose");
         (0, vitest_1.expect)(result.customParams.extra).toBe('param');
         (0, vitest_1.expect)(result.customParams.handle).toBeUndefined();
     });
+    (0, vitest_1.it)('throws on CSRF state mismatch', () => {
+        const passport = new index_1.AtPassport({ callbackUrl });
+        const testUrl = 'https://app.com/callback?handle=alice.bsky.social&atpstate=test-state';
+        (0, vitest_1.expect)(() => passport.parseCallback(testUrl, 'wrong-state')).toThrow('Invalid atpstate: CSRF validation failed.');
+    });
 });
-async function importPKCS8(pkcs8, alg) {
-    const { importPKCS8 } = await Promise.resolve().then(() => __importStar(require('jose')));
-    return await importPKCS8(pkcs8, alg);
-}

package/dist/index.d.ts

@@ -1,19 +1,12 @@
-export interface AtPassportSession {
-    did: string;
-    handle: string;
-    uuid: string;
-}
 export interface AtPassportOptions {
     callbackUrl: string;
     baseUrl?: string;
-    publicKey?: string;
 }
 /**
  * AtPassport Client
  */
 export declare class AtPassport {
     private readonly baseUrl;
-    private readonly publicKey?;
     private readonly callbackUrl;
     constructor(options: AtPassportOptions);
     /**
@@ -24,10 +17,6 @@ export declare class AtPassport {
      * Generates the URL for identity resolution.
      */
     resolveUrl(callback: string): string;
-    /**
-     * Verifies the token and returns the session.
-     */
-    get(token: string): Promise<AtPassportSession>;
     /**
      * Generates the authentication URL and state.
      * By saving the state on the app side and verifying it in parseCallback,
@@ -39,8 +28,9 @@ export declare class AtPassport {
     };
     /**
      * Parses the callback URL returned from AtPassport and extracts parameters.
+     * If `expectedState` is provided, it throws an error if the returned state does not match.
      */
-    parseCallback(currentUrl: string): {
+    parseCallback(currentUrl: string, expectedState?: string | null): {
         handle: string | null;
         did: string | null;
         pdsUrl: string | null;

package/dist/index.js

@@ -1,17 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AtPassport = void 0;
-const jose_1 = require("jose");
 /**
  * AtPassport Client
  */
 class AtPassport {
     baseUrl;
-    publicKey;
     callbackUrl;
     constructor(options) {
         this.baseUrl = (options.baseUrl || "https://atpassport.net").replace(/\/$/, "");
-        this.publicKey = options.publicKey;
         this.callbackUrl = options.callbackUrl;
     }
     /**
@@ -31,20 +28,6 @@ class AtPassport {
         url.searchParams.set("callbackUrl", callback);
         return url.toString();
     }
-    /**
-     * Verifies the token and returns the session.
-     */
-    async get(token) {
-        if (!this.publicKey) {
-            throw new Error("Public key is required for verification");
-        }
-        const spki = this.publicKey.includes("BEGIN")
-            ? this.publicKey
-            : Buffer.from(this.publicKey, 'base64').toString();
-        const key = await (0, jose_1.importSPKI)(spki, "RS256");
-        const { payload } = await (0, jose_1.jwtVerify)(token, key, { issuer: "atpassport" });
-        return payload;
-    }
     /**
      * Generates the authentication URL and state.
      * By saving the state on the app side and verifying it in parseCallback,
@@ -65,13 +48,17 @@ class AtPassport {
     }
     /**
      * Parses the callback URL returned from AtPassport and extracts parameters.
+     * If `expectedState` is provided, it throws an error if the returned state does not match.
      */
-    parseCallback(currentUrl) {
+    parseCallback(currentUrl, expectedState) {
         const url = new URL(currentUrl);
         const handle = url.searchParams.get("handle");
         const did = url.searchParams.get("did");
         const pdsUrl = url.searchParams.get("pdsurl");
         const atpstate = url.searchParams.get("atpstate");
+        if (expectedState && atpstate !== expectedState) {
+            throw new Error("Invalid atpstate: CSRF validation failed.");
+        }
         const customParams = {};
         url.searchParams.forEach((value, key) => {
             if (!["handle", "did", "pdsurl", "atpstate"].includes(key)) {

package/package.json

@@ -1,22 +1,21 @@
 {
   "name": "@atpassport/client",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "README_ja.md"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "build": "tsc",
+    "deploy": "npm publish --access public",
     "test": "vitest run"
   },
-  "dependencies": {
-    "jose": "^5.0.0"
-  },
   "devDependencies": {
     "@types/node": "^25.5.0",
     "typescript": "^5.0.0",