@adakrpos/auth 0.0.1

package/README.md

@@ -0,0 +1,221 @@
+# @adakrpos/auth
+
+Authentication SDK for Apple Developer Academy @ POSTECH services.
+
+## Installation
+
+```bash
+pnpm add @adakrpos/auth
+```
+
+## Quick Start
+
+Get an API key from the [ADA Developer Portal](https://ada-kr-pos.com/developer), then:
+
+```typescript
+import { adakrposAuth, getAuth } from '@adakrpos/auth/hono';
+
+app.use('*', adakrposAuth({ apiKey: env.ADAKRPOS_API_KEY }));
+
+app.get('/protected', async (c) => {
+  const auth = await getAuth(c);
+  if (!auth.isAuthenticated) return c.json({ error: 'Unauthorized' }, 401);
+  return c.json({ user: auth.user });
+});
+```
+
+## Usage
+
+### Hono
+
+```typescript
+import { Hono } from 'hono';
+import { adakrposAuth, getAuth, requireAuth } from '@adakrpos/auth/hono';
+
+const app = new Hono();
+
+// Optional auth — check manually
+app.use('*', adakrposAuth({ apiKey: env.ADAKRPOS_API_KEY }));
+
+app.get('/profile', async (c) => {
+  const auth = await getAuth(c);
+  if (!auth.isAuthenticated) return c.json({ error: 'Login required' }, 401);
+  return c.json({ user: auth.user });
+});
+
+// Required auth — auto 401 if not authenticated
+app.get('/dashboard', requireAuth({ apiKey: env.ADAKRPOS_API_KEY }), (c) => {
+  return c.json({ message: 'Welcome!' });
+});
+```
+
+### Express
+
+```typescript
+import express from 'express';
+import { adakrposAuthExpress, requireAuthExpress } from '@adakrpos/auth/express';
+
+const app = express();
+
+// Optional auth
+app.use(adakrposAuthExpress({ apiKey: process.env.ADAKRPOS_API_KEY! }));
+
+app.get('/profile', async (req, res) => {
+  const auth = await req.auth?.();
+  if (!auth?.isAuthenticated) return res.status(401).json({ error: 'Unauthorized' });
+  res.json({ user: auth.user });
+});
+
+// Required auth
+app.get('/dashboard', requireAuthExpress({ apiKey: process.env.ADAKRPOS_API_KEY! }), (req, res) => {
+  res.json({ message: 'Welcome!' });
+});
+```
+
+### Generic (Web Standard Request)
+
+Works with Cloudflare Workers, Deno, Bun, and any Web standard environment:
+
+```typescript
+import { verifyRequest } from '@adakrpos/auth/generic';
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const auth = await verifyRequest(request, { apiKey: env.ADAKRPOS_API_KEY });
+    if (!auth.isAuthenticated) {
+      return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 });
+    }
+    return new Response(JSON.stringify({ user: auth.user }));
+  }
+};
+```
+
+## API Reference
+
+### `adakrposAuth(config)` — Hono middleware
+
+Attaches a lazy `auth` function to the Hono context. Call `getAuth(c)` in your handler to resolve it.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `apiKey` | `string` | required | Your API key from the developer portal |
+| `authUrl` | `string` | `https://ada-kr-pos.com` | Auth server URL (for self-hosting) |
+
+### `getAuth(c)` — Hono helper
+
+```typescript
+const auth = await getAuth(c); // AuthContext
+```
+
+Returns the `AuthContext` for the current request. Must be called after `adakrposAuth` middleware.
+
+### `requireAuth(config)` — Hono middleware
+
+Drop-in middleware that returns `401` automatically if the request isn't authenticated. No need to call `getAuth` manually.
+
+### `adakrposAuthExpress(config)` — Express middleware
+
+Attaches `req.auth()` as a lazy async function. Call it in your handler to get the `AuthContext`.
+
+### `requireAuthExpress(config)` — Express middleware
+
+Same as `adakrposAuthExpress`, but automatically returns `401` if not authenticated.
+
+### `verifyRequest(request, config)` — Generic helper
+
+```typescript
+const auth = await verifyRequest(request, { apiKey: env.ADAKRPOS_API_KEY });
+```
+
+Takes a Web standard `Request` and returns `AuthContext`. No middleware needed.
+
+### `createAdakrposAuth(config)`
+
+Creates a raw auth client for advanced use cases.
+
+```typescript
+import { createAdakrposAuth } from '@adakrpos/auth';
+
+const client = createAdakrposAuth({ apiKey: env.ADAKRPOS_API_KEY });
+```
+
+Returns an `AdakrposAuthClient` with these methods:
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `verifySession(sessionId)` | `Promise<{user, session} \| null>` | Verify a session ID directly |
+| `getUser(userId)` | `Promise<AdakrposUser \| null>` | Fetch a user by ID |
+| `getCurrentUser(sessionId)` | `Promise<AdakrposUser \| null>` | Get the user from a session |
+
+### Types
+
+```typescript
+interface AdakrposUser {
+  id: string;
+  email: string | null;           // Apple email
+  verifiedEmail: string | null;   // @pos.idserve.net email
+  nickname: string | null;
+  name: string | null;
+  profilePhotoUrl: string | null;
+  bio: string | null;
+  contact: string | null;
+  snsLinks: Record<string, string>;
+  isVerified: boolean;            // true if @pos.idserve.net verified
+  createdAt: number;              // Unix ms
+  updatedAt: number;              // Unix ms
+}
+
+interface AdakrposSession {
+  id: string;
+  userId: string;
+  expiresAt: number;  // Unix ms
+  createdAt: number;  // Unix ms
+}
+
+type AuthContext = AdakrposAuthContext | AdakrposUnauthContext;
+
+interface AdakrposAuthContext {
+  user: AdakrposUser;
+  session: AdakrposSession;
+  isAuthenticated: true;
+}
+
+interface AdakrposUnauthContext {
+  user: null;
+  session: null;
+  isAuthenticated: false;
+}
+```
+
+## Caching
+
+API key validation results are cached in-memory for 30 seconds to reduce latency. This means:
+
+- First request: validates with auth server (~50ms)
+- Subsequent requests within 30s: instant (cached)
+- After 30s: re-validates with auth server
+
+You can clear the cache manually if needed:
+
+```typescript
+import { clearApiKeyCache } from '@adakrpos/auth';
+
+clearApiKeyCache();
+```
+
+## FAQ
+
+**Q: Where do I get an API key?**
+Log in at [ada-kr-pos.com](https://ada-kr-pos.com) with your @pos.idserve.net email, then visit the [Developer Portal](https://ada-kr-pos.com/developer).
+
+**Q: Can I use this on the client side?**
+No. API keys must stay server-side only. Never expose your API key in browser code.
+
+**Q: What happens when a session expires?**
+`auth.isAuthenticated` will be `false`. Redirect the user to `https://ada-kr-pos.com/login`.
+
+**Q: Does this work with Cloudflare Workers?**
+Yes. Use `@adakrpos/auth/generic` with `verifyRequest`, or `@adakrpos/auth/hono` if you're using Hono.
+
+**Q: What's the difference between `adakrposAuth` and `requireAuth`?**
+`adakrposAuth` is optional auth: it attaches the auth context but lets unauthenticated requests through. `requireAuth` blocks unauthenticated requests with a `401` automatically.

package/__tests__/basic.test.ts

@@ -0,0 +1,7 @@
+import { describe, it, expect } from "vitest";
+
+describe("Auth SDK", () => {
+  it("SDK test infrastructure is set up", () => {
+    expect(true).toBe(true);
+  });
+});

package/__tests__/client.test.ts

@@ -0,0 +1,206 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createAdakrposAuth } from "../src/client";
+import {
+  clearApiKeyCache,
+  getCachedApiKeyValidity,
+  setCachedApiKeyValidity,
+} from "../src/cache";
+
+describe("createAdakrposAuth", () => {
+  beforeEach(() => {
+    clearApiKeyCache();
+  });
+
+  afterEach(() => {
+    clearApiKeyCache();
+    vi.restoreAllMocks();
+  });
+
+  it("returns a client with verifySession, getUser, and getCurrentUser", () => {
+    const client = createAdakrposAuth({ apiKey: "ak_test" });
+
+    expect(client.verifySession).toBeTypeOf("function");
+    expect(client.getUser).toBeTypeOf("function");
+    expect(client.getCurrentUser).toBeTypeOf("function");
+  });
+
+  it("sends verifySession requests to the SDK verify endpoint", async () => {
+    const fetchSpy = vi.spyOn(global, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ user: null, session: null }), { status: 404 }),
+    );
+    const client = createAdakrposAuth({
+      apiKey: "ak_test",
+      authUrl: "https://example.com",
+    });
+
+    await client.verifySession("session_123");
+
+    expect(fetchSpy).toHaveBeenCalledWith(
+      "https://example.com/api/sdk/verify-session",
+      expect.objectContaining({
+        method: "POST",
+        body: JSON.stringify({ sessionId: "session_123" }),
+        headers: expect.objectContaining({
+          Authorization: "Bearer ak_test",
+          "Content-Type": "application/json",
+        }),
+      }),
+    );
+  });
+
+  it("returns null when verifySession receives a 401 response", async () => {
+    vi.spyOn(global, "fetch").mockResolvedValue(new Response(null, { status: 401 }));
+    const client = createAdakrposAuth({ apiKey: "ak_test" });
+
+    await expect(client.verifySession("session_123")).resolves.toBeNull();
+    expect(getCachedApiKeyValidity("ak_test")).toBe(false);
+  });
+
+  it("returns user and session data when verifySession succeeds", async () => {
+    const payload = {
+      user: {
+        id: "user_123",
+        email: "user@example.com",
+        verifiedEmail: "verified@example.com",
+        nickname: "ada",
+        name: "Ada",
+        profilePhotoUrl: null,
+        bio: null,
+        contact: null,
+        snsLinks: {},
+        isVerified: true,
+        createdAt: 1,
+        updatedAt: 2,
+      },
+      session: {
+        id: "session_123",
+        userId: "user_123",
+        expiresAt: 10,
+        createdAt: 5,
+      },
+    };
+    vi.spyOn(global, "fetch").mockResolvedValue(
+      new Response(JSON.stringify(payload), { status: 200 }),
+    );
+    const client = createAdakrposAuth({ apiKey: "ak_test" });
+
+    await expect(client.verifySession("session_123")).resolves.toEqual(payload);
+    expect(getCachedApiKeyValidity("ak_test")).toBe(true);
+  });
+
+  it("sends getUser requests to the SDK user endpoint", async () => {
+    const fetchSpy = vi.spyOn(global, "fetch").mockResolvedValue(
+      new Response(null, { status: 404 }),
+    );
+    const client = createAdakrposAuth({
+      apiKey: "ak_test",
+      authUrl: "https://example.com/base",
+    });
+
+    await client.getUser("user_123");
+
+    expect(fetchSpy).toHaveBeenCalledWith(
+      "https://example.com/api/sdk/users/user_123",
+      expect.objectContaining({
+        method: "GET",
+        headers: expect.objectContaining({
+          Authorization: "Bearer ak_test",
+        }),
+      }),
+    );
+  });
+
+  it("returns null when getUser receives a 404 response", async () => {
+    vi.spyOn(global, "fetch").mockResolvedValue(new Response(null, { status: 404 }));
+    const client = createAdakrposAuth({ apiKey: "ak_test" });
+
+    await expect(client.getUser("missing_user")).resolves.toBeNull();
+    expect(getCachedApiKeyValidity("ak_test")).toBe(true);
+  });
+
+  it("returns the authenticated user from getCurrentUser", async () => {
+    vi.spyOn(global, "fetch").mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          user: {
+            id: "user_123",
+            email: null,
+            verifiedEmail: null,
+            nickname: null,
+            name: "Ada",
+            profilePhotoUrl: null,
+            bio: null,
+            contact: null,
+            snsLinks: {},
+            isVerified: false,
+            createdAt: 1,
+            updatedAt: 2,
+          },
+          session: {
+            id: "session_123",
+            userId: "user_123",
+            expiresAt: 10,
+            createdAt: 5,
+          },
+        }),
+        { status: 200 },
+      ),
+    );
+    const client = createAdakrposAuth({ apiKey: "ak_test" });
+
+    await expect(client.getCurrentUser("session_123")).resolves.toEqual(
+      expect.objectContaining({ id: "user_123", name: "Ada" }),
+    );
+  });
+
+  it("skips duplicate requests after caching an invalid API key", async () => {
+    const fetchSpy = vi.spyOn(global, "fetch").mockResolvedValue(
+      new Response(null, { status: 401 }),
+    );
+    const client = createAdakrposAuth({ apiKey: "ak_test" });
+
+    await expect(client.verifySession("session_123")).resolves.toBeNull();
+    await expect(client.verifySession("session_123")).resolves.toBeNull();
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("API key cache", () => {
+  beforeEach(() => {
+    clearApiKeyCache();
+  });
+
+  afterEach(() => {
+    clearApiKeyCache();
+    vi.restoreAllMocks();
+  });
+
+  it("returns null for unknown API keys", () => {
+    expect(getCachedApiKeyValidity("unknown")).toBeNull();
+  });
+
+  it("stores and retrieves cached API key validity", () => {
+    setCachedApiKeyValidity("ak_test", true);
+
+    expect(getCachedApiKeyValidity("ak_test")).toBe(true);
+  });
+
+  it("returns null when a cache entry expires", () => {
+    vi.useFakeTimers();
+    setCachedApiKeyValidity("ak_test", true, 100);
+
+    vi.advanceTimersByTime(101);
+
+    expect(getCachedApiKeyValidity("ak_test")).toBeNull();
+    vi.useRealTimers();
+  });
+
+  it("clears all cached API key entries", () => {
+    setCachedApiKeyValidity("ak_test", true);
+    clearApiKeyCache();
+
+    expect(getCachedApiKeyValidity("ak_test")).toBeNull();
+  });
+});

package/__tests__/express.test.ts

@@ -0,0 +1,241 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { clearApiKeyCache } from "../src/cache";
+import { adakrposAuthExpress, requireAuthExpress } from "../src/express";
+import { verifyRequest } from "../src/generic";
+
+const config = {
+  apiKey: "ak_test",
+  authUrl: "https://example.com",
+};
+
+const validSession = {
+  user: {
+    id: "user_123",
+    email: "user@example.com",
+    verifiedEmail: "verified@example.com",
+    nickname: "ada",
+    name: "Ada Lovelace",
+    profilePhotoUrl: null,
+    bio: null,
+    contact: null,
+    snsLinks: {},
+    isVerified: true,
+    createdAt: 1,
+    updatedAt: 2,
+  },
+  session: {
+    id: "session_123",
+    userId: "user_123",
+    expiresAt: 10,
+    createdAt: 5,
+  },
+};
+
+describe("Express middleware", () => {
+  beforeEach(() => {
+    clearApiKeyCache();
+  });
+
+  afterEach(() => {
+    clearApiKeyCache();
+    vi.restoreAllMocks();
+  });
+
+  it("attaches auth function to req", async () => {
+    const middleware = adakrposAuthExpress(config);
+    const req = { headers: {} };
+    const res = {};
+    let nextCalled = false;
+
+    await middleware(req, res, () => {
+      nextCalled = true;
+    });
+
+    expect(nextCalled).toBe(true);
+    expect(typeof req.auth).toBe("function");
+  });
+
+  it("returns an unauthenticated context when no session cookie is present", async () => {
+    const fetchSpy = vi.spyOn(global, "fetch");
+    const middleware = adakrposAuthExpress(config);
+    const req = { headers: {} };
+    const res = {};
+
+    await middleware(req, res, () => {});
+
+    const authContext = await req.auth();
+
+    expect(authContext).toEqual({
+      user: null,
+      session: null,
+      isAuthenticated: false,
+    });
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("returns an authenticated context when the session is valid", async () => {
+    const fetchSpy = vi.spyOn(global, "fetch").mockResolvedValue(
+      new Response(JSON.stringify(validSession), { status: 200 }),
+    );
+    const middleware = adakrposAuthExpress(config);
+    const req = { headers: { cookie: "adakrpos_session=session_123" } };
+    const res = {};
+
+    await middleware(req, res, () => {});
+
+    const authContext = await req.auth();
+
+    expect(authContext).toEqual({
+      ...validSession,
+      isAuthenticated: true,
+    });
+    expect(fetchSpy).toHaveBeenCalledWith(
+      "https://example.com/api/sdk/verify-session",
+      expect.objectContaining({
+        method: "POST",
+        body: JSON.stringify({ sessionId: "session_123" }),
+      }),
+    );
+  });
+
+  it("returns 401 when auth is required and no session exists", async () => {
+    const middleware = requireAuthExpress(config);
+    const req = { headers: {} };
+    const res = {
+      status: vi.fn().mockReturnThis(),
+      json: vi.fn().mockReturnValue({}),
+    };
+
+    await middleware(req, res, () => {});
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(res.json).toHaveBeenCalledWith({ error: "Unauthorized" });
+  });
+
+  it("allows authenticated requests through requireAuthExpress", async () => {
+    const fetchSpy = vi.spyOn(global, "fetch").mockResolvedValue(
+      new Response(JSON.stringify(validSession), { status: 200 }),
+    );
+    const middleware = requireAuthExpress(config);
+    const req = { headers: { cookie: "adakrpos_session=session_123" } };
+    const res = {
+      status: vi.fn().mockReturnThis(),
+      json: vi.fn(),
+    };
+    let nextCalled = false;
+
+    await middleware(req, res, () => {
+      nextCalled = true;
+    });
+
+    expect(nextCalled).toBe(true);
+    expect(res.status).not.toHaveBeenCalled();
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not call the auth server until auth is invoked", async () => {
+    const fetchSpy = vi.spyOn(global, "fetch").mockResolvedValue(
+      new Response(JSON.stringify(validSession), { status: 200 }),
+    );
+    const middleware = adakrposAuthExpress(config);
+    const req = { headers: { cookie: "adakrpos_session=session_123" } };
+    const res = {};
+
+    await middleware(req, res, () => {});
+
+    expect(fetchSpy).not.toHaveBeenCalled();
+
+    await req.auth();
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("caches auth result on subsequent calls", async () => {
+    const fetchSpy = vi.spyOn(global, "fetch").mockResolvedValue(
+      new Response(JSON.stringify(validSession), { status: 200 }),
+    );
+    const middleware = adakrposAuthExpress(config);
+    const req = { headers: { cookie: "adakrpos_session=session_123" } };
+    const res = {};
+
+    await middleware(req, res, () => {});
+
+    await req.auth();
+    await req.auth();
+    await req.auth();
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("Generic verifyRequest helper", () => {
+  beforeEach(() => {
+    clearApiKeyCache();
+  });
+
+  afterEach(() => {
+    clearApiKeyCache();
+    vi.restoreAllMocks();
+  });
+
+  it("returns an unauthenticated context when no session cookie is present", async () => {
+    const fetchSpy = vi.spyOn(global, "fetch");
+    const request = new Request("http://localhost/", {
+      headers: {},
+    });
+
+    const authContext = await verifyRequest(request, config);
+
+    expect(authContext).toEqual({
+      user: null,
+      session: null,
+      isAuthenticated: false,
+    });
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("returns an authenticated context when the session is valid", async () => {
+    const fetchSpy = vi.spyOn(global, "fetch").mockResolvedValue(
+      new Response(JSON.stringify(validSession), { status: 200 }),
+    );
+    const request = new Request("http://localhost/", {
+      headers: { Cookie: "adakrpos_session=session_123" },
+    });
+
+    const authContext = await verifyRequest(request, config);
+
+    expect(authContext).toEqual({
+      ...validSession,
+      isAuthenticated: true,
+    });
+    expect(fetchSpy).toHaveBeenCalledWith(
+      "https://example.com/api/sdk/verify-session",
+      expect.objectContaining({
+        method: "POST",
+        body: JSON.stringify({ sessionId: "session_123" }),
+      }),
+    );
+  });
+
+  it("handles URL-encoded session IDs", async () => {
+    const fetchSpy = vi.spyOn(global, "fetch").mockResolvedValue(
+      new Response(JSON.stringify(validSession), { status: 200 }),
+    );
+    const encodedSessionId = encodeURIComponent("session_with_special_chars=123");
+    const request = new Request("http://localhost/", {
+      headers: { Cookie: `adakrpos_session=${encodedSessionId}` },
+    });
+
+    const authContext = await verifyRequest(request, config);
+
+    expect(authContext.isAuthenticated).toBe(true);
+    expect(fetchSpy).toHaveBeenCalledWith(
+      "https://example.com/api/sdk/verify-session",
+      expect.objectContaining({
+        method: "POST",
+        body: JSON.stringify({ sessionId: "session_with_special_chars=123" }),
+      }),
+    );
+  });
+});