@pantoia/auth-client 0.1.0

package/README.md

@@ -0,0 +1,145 @@
+# @pantoia/auth-client
+
+쿠키로 인증하는 API를 브라우저에서 부르는 클라이언트다.
+
+- access 토큰이 만료되면 재발급하고 요청을 다시 보낸다.
+- 내 정보를 1번 불러와 저장하고, 로그인 여부와 권한을 그 값으로 확인한다.
+- API 경로, 오류 코드, 내 정보 형태는 쓰는 쪽이 정한다.
+
+## 설치
+
+```
+npm install @pantoia/auth-client
+```
+
+React 훅을 쓰려면 React 18 이상이 필요하다.
+
+## 만들기
+
+```ts
+import { createAuthClient } from "@pantoia/auth-client";
+
+type Me = { nickname: string; permissions: string[] };
+
+export const auth = createAuthClient<Me>({
+  baseUrl: "https://api.example.com",
+  endpoints: { me: "/v1/members/me", refresh: "/v1/auth/refresh", logout: "/v1/auth/logout" },
+  codes: { unauthenticated: "UNAUTHENTICATED", refreshConflict: "IDENTITY_REFRESH_TOKEN_CONFLICT" },
+  permissionsOf: (me) => me.permissions,
+  loginUrl: "https://auth.example.com/login",
+  onUnauthenticated: () => window.location.assign(auth.loginUrl()),
+});
+```
+
+| 옵션 | 뜻 |
+|---|---|
+| `baseUrl` | API 주소. 함수면 요청할 때마다 부른다 |
+| `endpoints` | 내 정보, 재발급, 로그아웃 경로 |
+| `codes.unauthenticated` | access 토큰이 없거나 만료됐을 때 오는 401 응답의 `code` |
+| `codes.refreshConflict` | 다른 요청이 먼저 재발급했을 때 오는 409 응답의 `code` |
+| `permissionsOf` | 내 정보에서 권한 목록을 꺼내는 함수 |
+| `loginUrl` | 로그인 화면 주소. 함수면 쓸 때마다 부른다 |
+| `returnToParam` | 로그인 뒤 돌아올 주소를 담는 쿼리 이름. 기본값은 `return_to` |
+| `onUnauthenticated` | 재발급이 401로 실패했을 때 부르는 함수 |
+| `conflictRetryDelayMs` | 409 뒤에 다시 보낸 요청이 또 401일 때 기다리는 시간. 기본값은 300 |
+
+## API 부르기
+
+```ts
+const response = await auth.fetch("/v1/items", { method: "POST", body: { name: "a" } });
+const item = await response.json();
+
+await auth.fetch("/v1/auth/login", { method: "POST", body: { email, password }, auth: false });
+```
+
+- 쿠키를 포함해서 보낸다.
+- `body`가 객체면 JSON으로 보내고, `FormData`, `Blob`, `URLSearchParams`, 문자열은 그대로 보낸다.
+- 실패 응답은 `ApiError`로, 서버에 닿지 못하면 `NetworkError`로 던진다. `signal`로 중단하면 `AbortError`를 그대로 던진다.
+- `ApiError`에는 `status`, `code`, `message`(응답의 `detail`), `errors`(필드 오류), `retryAfterSeconds`가 있다.
+- 로그인이 필요 없는 API는 `auth: false`로 부른다. 재발급을 기다리지 않고, 401이어도 재발급하지 않는다.
+
+## 재발급
+
+`auth: false`가 아닌 요청이 401이고 응답의 `code`가 `codes.unauthenticated`면 재발급한다.
+
+- 한 페이지에서 여러 요청이 동시에 401을 받아도 재발급은 1번만 한다. 나머지 요청과 재발급 중에 시작한 요청은 재발급이 끝난 뒤에 보낸다.
+- 요청을 보낸 뒤 다른 요청이 재발급을 끝냈으면 재발급하지 않고 다시 보낸다.
+- 재발급이 성공하면 원래 요청을 다시 보낸다.
+- 재발급이 409이고 `code`가 `codes.refreshConflict`면 재발급을 다시 하지 않고 원래 요청을 다시 보낸다. 다시 보낸 요청이 또 401이면 `conflictRetryDelayMs` 뒤에 1번 더 보낸다.
+- 재발급이 401이면 기다리던 요청을 모두 실패로 끝내고, 저장한 내 정보를 지우고, `onUnauthenticated`를 1번 부른다.
+- 재발급이 네트워크 오류로 실패하면 요청만 실패로 끝낸다.
+
+## 내 정보와 권한
+
+| 함수 | 하는 일 |
+|---|---|
+| `getMe()` | 저장한 내 정보를 돌려준다. 없으면 요청하고, 동시에 불러도 요청은 1번이다. 로그인하지 않았으면 `null` |
+| `reloadMe()` | 내 정보를 다시 요청한다. 내 정보를 바꾼 뒤에 부른다 |
+| `isLoggedIn()` | 저장한 내 정보가 있는지 돌려준다 |
+| `hasPermission(p)`, `hasAnyPermission(ps)`, `hasAllPermissions(ps)` | 저장한 내 정보로 권한을 확인한다. 불러오기 전에는 `false` |
+| `refresh()` | 재발급한다 |
+| `logout()` | 로그아웃 API를 부르고 저장한 내 정보를 지운다 |
+| `loginUrl(returnTo)` | 로그인 화면 주소에 돌아올 주소를 붙인다. 주지 않으면 현재 주소를 붙인다 |
+
+`getMe()`는 `onUnauthenticated`를 부르지 않는다. 로그인하지 않은 사람을 어디로 보낼지는 부른 쪽이 정한다.
+
+다른 탭에는 알리지 않는다. 다른 탭에서 로그아웃하면 이 탭은 다음 요청의 재발급이 실패할 때 알게 된다.
+
+## React
+
+```tsx
+import { useHasPermission, useMe } from "@pantoia/auth-client/react";
+
+function Header() {
+  const me = useMe(auth);
+  const admin = useHasPermission(auth, "admin:app:view");
+  return <p>{me?.nickname}</p>;
+}
+```
+
+- `useMe(auth)`는 저장한 내 정보를 돌려준다. 아직 불러오지 않았으면 `undefined`를 돌려주고 불러온다. 로그인하지 않았으면 `null`이다.
+- 두 훅 모두 `reloadMe()`, `logout()`, 재발급 실패 뒤에 다시 그린다.
+
+## 로그인 확인 예
+
+React Router의 loader에서는 이렇게 쓴다.
+
+```ts
+async function requireLogin({ request }: LoaderFunctionArgs) {
+  if (!(await auth.getMe())) {
+    throw redirect(auth.loginUrl(request.url));
+  }
+
+  return null;
+}
+```
+
+## return_to 검사
+
+```ts
+resolveReturnTo(value, rule, fallback)
+isAllowedReturnTo(value, rule)
+```
+
+| 규칙 | 허용하는 주소 |
+|---|---|
+| `{ kind: "domain", domain }` | `https`이고 호스트가 `domain`이나 그 서브도메인인 주소 |
+| `{ kind: "host", hostname }` | `http`나 `https`이고 호스트 이름이 `hostname`인 주소. 포트는 가리지 않는다 |
+
+상대 경로와 사용자 정보가 든 주소(`https://user:pw@...`)는 허용하지 않는다.
+
+## 백엔드에 필요한 것
+
+- 인증 쿠키가 API 호스트로 전송되고, CORS가 `credentials`를 허용해야 한다.
+- 오류 응답은 Problem Details(RFC 9457)이고 `code`가 있어야 한다. 필드 오류는 `errors`에 `field`, `code`, `message`로 담는다.
+- 재발급 API는 성공하면 2xx, refresh 토큰이 무효면 401, 다른 요청이 먼저 재발급했으면 409를 줘야 한다.
+
+## 개발
+
+Node 20.11 이상이 필요하다.
+
+```
+npm install      처음 한 번
+npm run verify   typecheck, lint, test
+npm pack         tarball
+```

package/dist/client.d.ts

@@ -0,0 +1,39 @@
+export type ApiRequest = {
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    body?: unknown;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    auth?: boolean;
+};
+export type AuthClientOptions<Me> = {
+    baseUrl: string | (() => string);
+    endpoints: {
+        me: string;
+        refresh: string;
+        logout: string;
+    };
+    codes: {
+        unauthenticated: string;
+        refreshConflict: string;
+    };
+    permissionsOf: (me: Me) => readonly string[];
+    loginUrl: string | (() => string);
+    returnToParam?: string;
+    onUnauthenticated?: () => void;
+    conflictRetryDelayMs?: number;
+};
+export type AuthClient<Me> = {
+    fetch: (path: string, request?: ApiRequest) => Promise<Response>;
+    getMe: () => Promise<Me | null>;
+    reloadMe: () => Promise<Me | null>;
+    isLoggedIn: () => boolean;
+    hasPermission: (permission: string) => boolean;
+    hasAnyPermission: (permissions: readonly string[]) => boolean;
+    hasAllPermissions: (permissions: readonly string[]) => boolean;
+    refresh: () => Promise<void>;
+    logout: () => Promise<void>;
+    loginUrl: (returnTo?: string) => string;
+    getSnapshot: () => Me | null | undefined;
+    subscribe: (listener: () => void) => () => void;
+};
+export declare function createAuthClient<Me>(options: AuthClientOptions<Me>): AuthClient<Me>;

package/dist/client.js

@@ -0,0 +1,211 @@
+import { ApiError, NetworkError, readProblem } from "./problem.js";
+function resolve(value) {
+    return typeof value === "function" ? value() : value;
+}
+function encodeBody(body) {
+    if (body === undefined) {
+        return { body: undefined, contentType: undefined };
+    }
+    if (body instanceof FormData || body instanceof Blob || body instanceof URLSearchParams || typeof body === "string") {
+        return { body, contentType: undefined };
+    }
+    return { body: JSON.stringify(body), contentType: "application/json" };
+}
+function wait(ms) {
+    return new Promise((done) => {
+        setTimeout(done, ms);
+    });
+}
+export function createAuthClient(options) {
+    const conflictRetryDelayMs = options.conflictRetryDelayMs ?? 300;
+    const returnToParam = options.returnToParam ?? "return_to";
+    const listeners = new Set();
+    let me;
+    let loading = null;
+    let refreshing = null;
+    let settled = 0;
+    let last = { outcome: "refreshed" };
+    let notified = false;
+    function setMe(value) {
+        me = value;
+        if (value !== null) {
+            notified = false;
+        }
+        for (const listener of listeners) {
+            listener();
+        }
+    }
+    async function send(path, { method = "GET", body, headers, signal }) {
+        const encoded = encodeBody(body);
+        try {
+            return await fetch(`${resolve(options.baseUrl)}${path}`, {
+                method,
+                credentials: "include",
+                headers: encoded.contentType ? { "Content-Type": encoded.contentType, ...headers } : headers,
+                body: encoded.body,
+                signal,
+            });
+        }
+        catch (error) {
+            if (error instanceof DOMException && error.name === "AbortError") {
+                throw error;
+            }
+            throw new NetworkError();
+        }
+    }
+    async function isUnauthenticated(response) {
+        if (response.status !== 401) {
+            return false;
+        }
+        try {
+            const body = await response.clone().json();
+            return typeof body === "object" && body !== null && body.code === options.codes.unauthenticated;
+        }
+        catch {
+            return false;
+        }
+    }
+    async function checked(response) {
+        if (!response.ok) {
+            throw await readProblem(response);
+        }
+        return response;
+    }
+    function expire() {
+        setMe(null);
+    }
+    function notifyUnauthenticated() {
+        if (notified) {
+            return;
+        }
+        notified = true;
+        options.onUnauthenticated?.();
+    }
+    async function runRefresh() {
+        const response = await send(options.endpoints.refresh, { method: "POST" });
+        if (response.ok) {
+            notified = false;
+            return "refreshed";
+        }
+        const error = await readProblem(response);
+        if (error.status === 409 && error.code === options.codes.refreshConflict) {
+            return "conflict";
+        }
+        if (error.status === 401) {
+            expire();
+        }
+        throw error;
+    }
+    function refreshOnce() {
+        if (!refreshing) {
+            refreshing = runRefresh().then((outcome) => {
+                last = { outcome };
+                return outcome;
+            }, (error) => {
+                last = { error };
+                throw error;
+            }).finally(() => {
+                settled += 1;
+                refreshing = null;
+            });
+        }
+        return refreshing;
+    }
+    function settledResult() {
+        return "outcome" in last ? Promise.resolve(last.outcome) : Promise.reject(last.error);
+    }
+    async function awaitRefresh(promise, notify) {
+        try {
+            return await promise;
+        }
+        catch (error) {
+            if (notify && error instanceof ApiError && error.status === 401) {
+                notifyUnauthenticated();
+            }
+            throw error;
+        }
+    }
+    async function request(path, sendOptions = {}) {
+        const { auth = true, notify = true } = sendOptions;
+        if (!auth) {
+            return checked(await send(path, sendOptions));
+        }
+        if (refreshing) {
+            await awaitRefresh(refreshing, notify);
+        }
+        const sentAt = settled;
+        let response = await send(path, sendOptions);
+        if (!(await isUnauthenticated(response))) {
+            return checked(response);
+        }
+        const outcome = await awaitRefresh(settled === sentAt ? refreshOnce() : settledResult(), notify);
+        response = await send(path, sendOptions);
+        if (outcome === "conflict" && (await isUnauthenticated(response))) {
+            await wait(conflictRetryDelayMs);
+            response = await send(path, sendOptions);
+        }
+        return checked(response);
+    }
+    async function load() {
+        try {
+            const response = await request(options.endpoints.me, { notify: false });
+            const value = (await response.json());
+            setMe(value);
+            return value;
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.status === 401) {
+                setMe(null);
+                return null;
+            }
+            throw error;
+        }
+    }
+    function startLoad() {
+        const promise = load();
+        loading = promise;
+        const clear = () => {
+            if (loading === promise) {
+                loading = null;
+            }
+        };
+        promise.then(clear, clear);
+        return promise;
+    }
+    function permissions() {
+        return me ? options.permissionsOf(me) : [];
+    }
+    return {
+        fetch: (path, apiRequest) => request(path, apiRequest),
+        getMe: () => {
+            if (me !== undefined) {
+                return Promise.resolve(me);
+            }
+            return loading ?? startLoad();
+        },
+        reloadMe: startLoad,
+        isLoggedIn: () => me !== undefined && me !== null,
+        hasPermission: (permission) => permissions().includes(permission),
+        hasAnyPermission: (wanted) => wanted.some((permission) => permissions().includes(permission)),
+        hasAllPermissions: (wanted) => wanted.every((permission) => permissions().includes(permission)),
+        refresh: async () => {
+            await refreshOnce();
+        },
+        logout: async () => {
+            await request(options.endpoints.logout, { method: "POST", auth: false });
+            setMe(null);
+        },
+        loginUrl: (returnTo = window.location.href) => {
+            const url = new URL(resolve(options.loginUrl));
+            url.searchParams.set(returnToParam, returnTo);
+            return url.href;
+        },
+        getSnapshot: () => me,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { type ApiRequest, type AuthClient, type AuthClientOptions, createAuthClient } from "./client.js";
+export { ApiError, type FieldViolation, NetworkError } from "./problem.js";
+export { isAllowedReturnTo, RETURN_TO_PARAM, resolveReturnTo, type ReturnToRule } from "./return-to.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createAuthClient } from "./client.js";
+export { ApiError, NetworkError } from "./problem.js";
+export { isAllowedReturnTo, RETURN_TO_PARAM, resolveReturnTo } from "./return-to.js";

package/dist/problem.d.ts

@@ -0,0 +1,16 @@
+export type FieldViolation = {
+    field: string;
+    code: string;
+    message: string;
+};
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly errors: FieldViolation[];
+    readonly retryAfterSeconds: number | undefined;
+    constructor(status: number, code: string | undefined, detail: string | undefined, errors: FieldViolation[], retryAfterSeconds: number | undefined);
+}
+export declare class NetworkError extends Error {
+    constructor();
+}
+export declare function readProblem(response: Response): Promise<ApiError>;

package/dist/problem.js

@@ -0,0 +1,47 @@
+export class ApiError extends Error {
+    status;
+    code;
+    errors;
+    retryAfterSeconds;
+    constructor(status, code, detail, errors, retryAfterSeconds) {
+        super(detail ?? "");
+        this.name = "ApiError";
+        this.status = status;
+        this.code = code;
+        this.errors = errors;
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+export class NetworkError extends Error {
+    constructor() {
+        super("");
+        this.name = "NetworkError";
+    }
+}
+function isViolation(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const item = value;
+    return typeof item.field === "string" && typeof item.code === "string" && typeof item.message === "string";
+}
+function readRetryAfter(response) {
+    const seconds = Number(response.headers.get("Retry-After"));
+    return Number.isFinite(seconds) && seconds > 0 ? seconds : undefined;
+}
+export async function readProblem(response) {
+    let body = {};
+    try {
+        const parsed = await response.json();
+        if (typeof parsed === "object" && parsed !== null) {
+            body = parsed;
+        }
+    }
+    catch {
+        body = {};
+    }
+    const code = typeof body.code === "string" ? body.code : undefined;
+    const detail = typeof body.detail === "string" ? body.detail : undefined;
+    const errors = Array.isArray(body.errors) ? body.errors.filter(isViolation) : [];
+    return new ApiError(response.status, code, detail, errors, readRetryAfter(response));
+}

package/dist/react.d.ts

@@ -0,0 +1,3 @@
+import type { AuthClient } from "./client.js";
+export declare function useMe<Me>(auth: AuthClient<Me>): Me | null | undefined;
+export declare function useHasPermission<Me>(auth: AuthClient<Me>, permission: string): boolean;

package/dist/react.js

@@ -0,0 +1,14 @@
+import { useEffect, useSyncExternalStore } from "react";
+export function useMe(auth) {
+    const me = useSyncExternalStore(auth.subscribe, auth.getSnapshot, auth.getSnapshot);
+    useEffect(() => {
+        if (me === undefined) {
+            auth.getMe().catch(() => undefined);
+        }
+    }, [auth, me]);
+    return me;
+}
+export function useHasPermission(auth, permission) {
+    const read = () => auth.hasPermission(permission);
+    return useSyncExternalStore(auth.subscribe, read, read);
+}

package/dist/return-to.d.ts

@@ -0,0 +1,10 @@
+export type ReturnToRule = {
+    kind: "domain";
+    domain: string;
+} | {
+    kind: "host";
+    hostname: string;
+};
+export declare const RETURN_TO_PARAM = "return_to";
+export declare function isAllowedReturnTo(value: string, rule: ReturnToRule): boolean;
+export declare function resolveReturnTo(value: string | null | undefined, rule: ReturnToRule, fallback: string): string;

package/dist/return-to.js

@@ -0,0 +1,22 @@
+export const RETURN_TO_PARAM = "return_to";
+export function isAllowedReturnTo(value, rule) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    if (url.username || url.password) {
+        return false;
+    }
+    if (rule.kind === "domain") {
+        const inDomain = url.hostname === rule.domain || url.hostname.endsWith(`.${rule.domain}`);
+        return url.protocol === "https:" && inDomain;
+    }
+    const web = url.protocol === "http:" || url.protocol === "https:";
+    return web && url.hostname === rule.hostname;
+}
+export function resolveReturnTo(value, rule, fallback) {
+    return value && isAllowedReturnTo(value, rule) ? new URL(value).href : fallback;
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@pantoia/auth-client",
+  "version": "0.1.0",
+  "description": "쿠키 인증 API 클라이언트. 토큰 재발급, 내 정보, 권한 확인, 로그아웃",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pantoia/pantoia-auth-client.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    }
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.11"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint --deny-warnings",
+    "test": "vitest run",
+    "verify": "npm run typecheck && npm run lint && npm run test"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/react": "^16.3.3",
+    "@types/react": "^19.2.18",
+    "happy-dom": "^20.14.5",
+    "oxlint": "^1.81.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
+  }
+}