@ghostly-solutions/auth 0.1.1 → 0.2.2

package/docs/integration-guide.md

@@ -6,96 +6,64 @@
 npm install @ghostly-solutions/auth
 ```
 
-## 2. Core Browser Integration
+## 2. Browser App
 
 ```ts
 import { createAuthClient } from "@ghostly-solutions/auth";
 
-const authClient = createAuthClient();
+const auth = createAuthClient({ application: "admin" });
 
-export function onLoginClick(): void {
-  authClient.login();
-}
-
-export async function loadCurrentSession() {
-  return authClient.getSession();
-}
-```
-
-## 3. Callback Route (`/auth/callback`)
-
-```ts
-import { createAuthClient } from "@ghostly-solutions/auth";
-
-const authClient = createAuthClient();
+await auth.init();
 
-await authClient.completeCallbackRedirect();
-```
-
-Or use the ready React helper:
-
-```tsx
-import { AuthCallbackHandler } from "@ghostly-solutions/auth/react";
-
-export default function AuthCallbackPage() {
-  return (
-    <AuthCallbackHandler
-      processing={<div>Signing in...</div>}
-      renderError={() => <div>Sign in failed. Please retry.</div>}
-    />
-  );
+const session = await auth.getSession();
+if (!session) {
+  auth.login({
+    returnTo: "/",
+  });
 }
 ```
 
-Alternative when app controls redirect manually:
-
-```ts
-const result = await authClient.processCallback();
-window.location.replace(result.redirectTo);
-```
-
-## 4. React Integration
+## 3. React App
 
 ```tsx
 import { AuthProvider, AuthSessionGate } from "@ghostly-solutions/auth/react";
+import type { GhostlySession } from "@ghostly-solutions/auth";
 
-function SessionGate() {
+function Root({ initialSession }: { initialSession?: GhostlySession | null }) {
   return (
-    <AuthSessionGate
-      loading={<div>Loading...</div>}
-      unauthorized={({ login }) => <button onClick={() => login()}>Sign in</button>}
-      authorized={(session) => <div>{session.email}</div>}
-    />
-  );
-}
-
-export function AppRoot() {
-  return (
-    <AuthProvider>
-      <SessionGate />
+    <AuthProvider initialSession={initialSession}>
+      <AuthSessionGate
+        loading={<div>Loading...</div>}
+        unauthorized={({ login }) => <button onClick={() => login()}>Sign in</button>}
+        authorized={(session) => <div>{session.username}</div>}
+      />
     </AuthProvider>
   );
 }
 ```
 
-## 5. Next.js App Router Integration
+When `initialSession` is passed from server rendering, React UI starts in a resolved auth state without guest/auth flicker.
+
+## 4. Next.js App Router (Server)
 
 ```ts
-import { requireServerSession } from "@ghostly-solutions/auth/next";
+import { requireNextServerSession } from "@ghostly-solutions/auth/next";
 
-export async function loadProtectedData(requestHeaders: Headers) {
-  const session = await requireServerSession({
-    headers: requestHeaders,
+export async function readProtectedData(headers: Headers) {
+  const session = await requireNextServerSession({
+    headers,
+    apiOrigin: "https://api.ghostlysolutions.com",
   });
 
   return {
     actorId: session.id,
-    actorRole: session.role,
   };
 }
 ```
 
-Client-side guard:
+No route handlers are required from the application.
+
+## 5. Next/React Client Guard
 
 ```ts
 import { ensureClientAuthenticated } from "@ghostly-solutions/auth/next";
@@ -103,40 +71,46 @@ import { ensureClientAuthenticated } from "@ghostly-solutions/auth/next";
 await ensureClientAuthenticated();
 ```
 
-No-glue server helper:
+If session is missing, helper triggers `login()` and redirects browser.
+
+## 6. Extension Integration
 
 ```ts
-import { getNextServerSession } from "@ghostly-solutions/auth/next";
+import { createChromeExtensionAuthClient } from "@ghostly-solutions/auth/extension";
+
+const auth = createChromeExtensionAuthClient({
+  apiOrigin: "https://auth.ghostlysolutions.com",
+  application: "extension",
+});
 
-const session = await getNextServerSession();
+const session = await auth.getSession({ forceRefresh: true });
+if (!session) {
+  await auth.loginWithTabFlow({
+    returnTo: "/",
+  });
+}
 ```
 
-Ready route handlers (mock/proxy):
+`createChromeExtensionAuthClient()` is the preferred extension entrypoint. It manages:
 
-```ts
-import { createNextAuthRouteHandlers } from "@ghostly-solutions/auth/next";
+- `chrome.tabs.create(...)` for login tab flow
+- `chrome.cookies` access for `gs_auth_session`
+- `chrome.storage.local` persistence for exchanged bearer token and cached session
 
-const authHandlers = createNextAuthRouteHandlers({
-  mode: "mock",
-});
+`loginWithTabFlow()` opens the authorize URL in a regular browser tab and relies on later `init()` / `getSession()` calls to observe the server-owned session.
 
-export const GET = authHandlers.keycloakLoginGet;
-```
+`loginWithWebAuthFlow()` remains available through the lower-level `createExtensionAuthClient()` for `chrome.identity.launchWebAuthFlow(...)` integrations.
 
-## 6. Error Handling Pattern
+## 7. Error Handling
 
 ```ts
-import { AuthSdkError } from "@ghostly-solutions/auth";
+import { AuthSdkError, authErrorCode } from "@ghostly-solutions/auth";
 
 try {
-  await authClient.processCallback();
+  await auth.requireSession();
 } catch (error) {
-  if (error instanceof AuthSdkError) {
-    if (error.code === "callback_invalid_token") {
-      // show explicit re-login state
-    }
+  if (error instanceof AuthSdkError && error.code === authErrorCode.unauthorized) {
+    auth.login();
   }
-
-  throw error;
 }
 ```

package/docs/overview.md

@@ -1,41 +1,40 @@
 # Overview
 
-`@ghostly-solutions/auth` is a focused authentication SDK for Ghostly Solutions products.
+`@ghostly-solutions/auth` is a product SDK for Ghostly OAuth authentication.
 
-## Design Goals
+## Goals
 
-- Keep authentication behavior deterministic and product-wide consistent.
-- Expose strict TypeScript contracts for sessions and errors.
-- Work in browser apps, React apps, and Next.js App Router environments.
-- Keep API shape minimal: login, callback processing, session, logout, and guards.
+- One fixed browser flow for all products.
+- Cookie-only session in browser (`HttpOnly`, server-owned).
+- No callback token parsing in frontend code.
+- No app-side auth route handlers.
 
-## Fixed External Contract
+## OAuth Flow
 
-The SDK uses fixed API routes and does not accept runtime endpoint configuration:
+1. `auth.login()` redirects browser to `GET /oauth/authorize?return_to=...`, and may include logical `app=...`.
+2. OAuth provider completes login and returns to `GET /oauth/callback/provider`.
+3. API validates provider response, creates session, sets cookie.
+4. API redirects browser back to `return_to`.
+5. SDK calls `GET /oauth/session` during `init()` and exposes typed session state.
 
-- `GET /v1/auth/keycloak/login`
-- `POST /v1/auth/keycloak/validate`
-- `GET /v1/auth/me`
-- `POST /v1/auth/logout`
+## Fixed API Endpoints
 
-Callback route and token input are fixed:
+- `GET /oauth/authorize`
+- `GET /oauth/callback/provider`
+- `GET /oauth/session`
+- `POST /oauth/refresh`
+- `POST /oauth/logout`
 
-- Callback path: `/auth/callback`
-- Callback JWT query param: `token`
+The SDK can optionally identify the logical application, for example `admin` or `extension`, but it must not expose raw IdP client configuration such as Keycloak `client_id`.
 
-## What The SDK Handles
+## Runtime Scope
 
-- Redirect start to login endpoint.
-- Callback token extraction and immediate URL cleanup.
-- JWT validation request through Ghostly API.
-- Session fetch and lazy revalidation.
-- In-memory session state and subscription API.
-- Cross-tab synchronization via `BroadcastChannel`.
-- React state adapter and Next.js guard helpers.
+- Core browser SDK (`@ghostly-solutions/auth`)
+- React adapter (`@ghostly-solutions/auth/react`)
+- Next server helpers (`@ghostly-solutions/auth/next`)
+- Browser-extension adapter (`@ghostly-solutions/auth/extension`)
 
-## What The SDK Does Not Do
+The extension adapter supports two orchestration modes:
 
-- No fallback endpoint discovery.
-- No dynamic base URL/runtime host config.
-- No localStorage token persistence.
-- No background polling refresh loop.
+- tab flow: open `/oauth/authorize` in a regular browser tab
+- web auth flow: wrap `chrome.identity.launchWebAuthFlow(...)`

package/package.json

@@ -1,7 +1,14 @@
 {
   "name": "@ghostly-solutions/auth",
-  "version": "0.1.1",
-  "description": "Authentication SDK for Ghostly Solutions products using Keycloak redirect and Ghostly Auth API session validation.",
+  "version": "0.2.2",
+  "description": "Authentication SDK for Ghostly Solutions products using OAuth redirect and Ghostly Auth API session validation.",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.ghostlysolutions.com/ghostlysolutions/shared/sdk/auth-client.git"
+  },
+  "homepage": "https://gitlab.ghostlysolutions.com/ghostlysolutions/shared/sdk/auth-client",
+  "author": "Ghostly Solutions",
+  "license": "UNLICENSED",
   "type": "module",
   "private": false,
   "packageManager": "npm@11.6.3",
@@ -27,6 +34,7 @@
     },
     "./react": {
       "types": "./dist/react.d.ts",
+      "react-server": "./react-client.js",
       "import": "./react-client.js",
       "default": "./react-client.js"
     },
@@ -34,6 +42,11 @@
       "types": "./dist/next.d.ts",
       "import": "./dist/next.js",
       "default": "./dist/next.js"
+    },
+    "./extension": {
+      "types": "./dist/extension.d.ts",
+      "import": "./dist/extension.js",
+      "default": "./dist/extension.js"
     }
   },
   "publishConfig": {