@ghostly-solutions/auth 0.1.1 → 0.2.2

package/LICENSE

@@ -0,0 +1,13 @@
+Proprietary License
+
+Copyright (c) Ghostly Solutions.
+All rights reserved.
+
+This repository and all source code, configuration, documentation, and related materials
+are proprietary and confidential unless a separate written agreement states otherwise.
+
+No permission is granted to use, copy, modify, distribute, sublicense, publish, or sell
+any part of this repository without prior written authorization from Ghostly Solutions.
+
+Third-party components included through declared package managers remain subject to their
+own licenses.

package/README.md

@@ -1,42 +1,44 @@
 # @ghostly-solutions/auth
 
+## Purpose
+
 Authentication SDK for Ghostly Solutions products.
 
-The SDK implements a fixed Keycloak redirect flow with Ghostly Auth API validation and typed session state.
+This repository contains the npm package that implements a browser-first OAuth redirect flow
+backed by a server-owned cookie session. Client code does not parse callback tokens and does not
+define auth route handlers.
 
-## Highlights
+Repository type: `lib-repo`.
 
-- Fixed API contract (no runtime endpoint configuration).
-- Typed core client with deterministic error codes.
-- Dedicated callback flow with immediate token URL cleanup.
-- Session state with lazy revalidation.
-- Cross-tab synchronization via `BroadcastChannel`.
-- React adapter (`AuthProvider`, `useAuth`).
-- React callback helpers (`AuthCallbackHandler`, `useAuthCallbackRedirect`).
-- React session gate (`AuthSessionGate`).
-- Next adapter (server and client guards).
-- Next Auth Kit with ready route handlers (`mock` or `proxy`) and server-session helpers.
+## Architecture
 
-## Fixed API Endpoints
+Package entrypoints:
 
-- `GET /v1/auth/keycloak/login`
-- `POST /v1/auth/keycloak/validate`
-- `GET /v1/auth/me`
-- `POST /v1/auth/logout`
+- `@ghostly-solutions/auth`: browser/core client
+- `@ghostly-solutions/auth/react`: React provider and session gates
+- `@ghostly-solutions/auth/next`: Next.js server helpers
+- `@ghostly-solutions/auth/extension`: extension-oriented auth helpers
 
-## Entry Points
+The SDK assumes a fixed Ghostly Auth API surface and keeps token handling server-owned.
 
-- `@ghostly-solutions/auth`
-- `@ghostly-solutions/auth/react`
-- `@ghostly-solutions/auth/next`
+## Stack
 
-## Install
+- TypeScript
+- tsup
+- Vitest
+- Biome
+- npm
+
+## Build
+
+Install and validate:
 
 ```bash
-npm install @ghostly-solutions/auth
+npm ci
+npm run check
 ```
 
-## Development
+Expanded commands:
 
 ```bash
 npm run lint
@@ -45,65 +47,204 @@ npm run test
 npm run build
 ```
 
-All CI and official workflows are npm-first.
+Pack verification:
 
-Bun is optional for local use through aliases in `bun.json`.
+```bash
+npm pack --dry-run
+```
 
-## Quick Start
+## Run
 
-```ts
-import { createAuthClient } from "@ghostly-solutions/auth";
+This repository does not start a long-running application by default.
+
+For local manual exploration:
+
+```bash
+npm run demo
+```
+
+Bun is optional for local demo shortcuts only.
+
+## Config
+
+This package is configured by the consuming application at runtime, not by repository-level
+environment files.
+
+Core client configuration typically includes:
+
+- `apiOrigin`
+- `application`
+- browser callback destination or extension auth hooks, depending on entrypoint
 
-const authClient = createAuthClient();
+## Dependencies
 
-// Start login flow
-authClient.login();
+- browser login/logout against Ghostly Auth API
+- session bootstrap for React and Next.js apps
+- server-side session access for Next.js
+- extension auth helpers for tab-based or custom auth flows
 
-// In /auth/callback route
-await authClient.completeCallbackRedirect();
+Peer dependencies:
+
+- `react >= 18`
+- `react-dom >= 18`
+
+Package artifacts are built from `src/` and published to npm. `dist/` and tarballs must not be
+committed as release storage.
+
+## CI
+
+GitLab CI validates this repository through `.gitlab-ci.yml`.
+
+Current pipeline contract:
+
+- `validate`: lint + typecheck
+- `test`: unit tests
+- `build`: bundle build + pack verification
+- `release`: tag-driven npm publish gate
+
+Green pipeline means:
+
+- `npm run lint`
+- `npm run typecheck`
+- `npm run test`
+- `npm run build`
+- `npm pack --dry-run`
+
+## Release
+
+The release artifact is the npm package `@ghostly-solutions/auth`.
+
+Release path:
+
+1. merge with green CI
+2. create a semver tag
+3. let GitLab CI publish through the tag-gated release job
+
+Current published version can be verified with:
+
+```bash
+npm view @ghostly-solutions/auth version dist-tags --json
 ```
 
-## Next.js "No-Glue" Integration
+## Troubleshooting
+
+- auth contract mismatch: verify the backend exposes the required `/oauth/*` routes
+- session fetch fails in Next.js: confirm headers are forwarded into `requireNextServerSession`
+- package publish blocked: verify npm auth token and protected branch/tag permissions in GitLab
+- local bundle drift: run `npm run check && npm pack --dry-run`
+
+## Ownership
+
+- Repo owners: @kirill
 
-Use the high-level Next adapter in `@ghostly-solutions/auth/next`:
+## License
 
-- `getNextServerSession()`
-- `requireNextServerSession()`
-- `createNextAuthRouteHandlers({ mode: "mock" | "proxy" })`
+See [LICENSE](/home/winicred/ghostly-solutions/@ghostly-solutions__auth/LICENSE). Public package availability does not override repository license terms unless Ghostly Solutions publishes separate licensing terms.
 
-This removes custom auth boilerplate from application code and keeps app-level integration thin.
+## Runtime Contract
 
-## Callback Page Helper
+The SDK assumes a fixed auth surface on your auth gateway:
+
+- `GET /oauth/authorize`
+- `GET /oauth/callback/provider`
+- `GET /oauth/session`
+- `POST /oauth/refresh`
+- `POST /oauth/logout`
+
+If your backend does not expose this contract, the SDK is not a drop-in fit.
+
+## Install
+
+```bash
+npm install @ghostly-solutions/auth
+```
+
+Peer dependencies:
+
+- `react >= 18`
+- `react-dom >= 18`
+
+## Core Usage
+
+```ts
+import { createAuthClient } from "@ghostly-solutions/auth";
+
+const auth = createAuthClient({
+  apiOrigin: "https://api.ghostlysolutions.com",
+  application: "admin",
+});
+
+await auth.init();
+const session = await auth.getSession();
+
+if (!session) {
+  auth.login({ returnTo: window.location.pathname });
+}
+```
+
+## React Usage
 
 ```tsx
-import { AuthCallbackHandler } from "@ghostly-solutions/auth/react";
+import { AuthProvider, AuthSessionGate } from "@ghostly-solutions/auth/react";
 
-export default function AuthCallbackPage() {
+export function App() {
   return (
-    <AuthCallbackHandler
-      processing={<div>Signing you in...</div>}
-      renderError={() => <div>Could not complete sign in.</div>}
-    />
+    <AuthProvider
+      apiOrigin="https://api.ghostlysolutions.com"
+      application="admin"
+    >
+      <AuthSessionGate
+        loading={<div>Loading...</div>}
+        unauthorized={({ login }) => (
+          <button onClick={() => login({ returnTo: "/" })}>Sign in</button>
+        )}
+        authorized={(session) => <div>{session.email}</div>}
+      />
+    </AuthProvider>
   );
 }
 ```
 
-## Error Handling
+## Next.js Usage
+
+Use the server helpers to resolve the current session from request headers.
 
 ```ts
-import { AuthSdkError } from "@ghostly-solutions/auth";
-
-try {
-  await authClient.requireSession();
-} catch (error) {
-  if (error instanceof AuthSdkError) {
-    if (error.code === "unauthorized") {
-      authClient.login();
-    }
-  }
+import { requireNextServerSession } from "@ghostly-solutions/auth/next";
+
+export async function getServerData(headers: Headers) {
+  const session = await requireNextServerSession({
+    headers,
+    apiOrigin: "https://api.ghostlysolutions.com",
+  });
+
+  return { actorId: session.id };
 }
 ```
 
+No Next.js route handlers are required.
+
+## Extension Usage
+
+```ts
+import { createExtensionAuthClient } from "@ghostly-solutions/auth/extension";
+
+const auth = createExtensionAuthClient({
+  apiOrigin: "https://api.ghostlysolutions.com",
+  application: "ghostguard-extension",
+  openAuthorizePage: async ({ authorizeUrl }) => {
+    await chrome.tabs.create({ url: authorizeUrl });
+  },
+  launchWebAuthFlow: async ({ authorizeUrl }) => {
+    await openAuthWindow(authorizeUrl);
+  },
+});
+
+await auth.loginWithTabFlow({
+  returnTo: "/oauth/complete",
+});
+```
+
 ## Documentation
 
 - [Docs Index](./docs/index.md)
@@ -112,16 +253,4 @@ try {
 - [Integration Guide](./docs/integration-guide.md)
 - [Architecture](./docs/architecture.md)
 - [Development and CI](./docs/development-and-ci.md)
-
-## Interactive Demo
-
-Run the simulated authentication page in this repository:
-
-```bash
-npm run demo
-```
-
-Then open `http://localhost:4100/` to test login, callback processing, session retrieval,
-and logout.
-
-Detailed demo docs: [demo/README.md](./demo/README.md).
+- [Demo](./demo/README.md)

package/dist/{auth-client-CAHMjodm.d.ts → auth-client-Cdkp07ii.d.ts}

@@ -8,25 +8,33 @@ interface GhostlySession {
     permissions: string[];
 }
 
-interface ProcessCallbackResult {
-    redirectTo: string;
-    session: GhostlySession;
+interface AuthClientOptions {
+    apiOrigin?: string;
+    application?: string;
+}
+interface AuthInitOptions {
+    forceRefresh?: boolean;
+}
+interface AuthInitResult {
+    session: GhostlySession | null;
+    status: "authenticated" | "unauthenticated";
 }
 interface LoginOptions {
     returnTo?: string;
+    application?: string;
 }
 interface SessionRequestOptions {
     forceRefresh?: boolean;
 }
 type SessionListener = (session: GhostlySession | null) => void;
 interface AuthClient {
-    completeCallbackRedirect(): Promise<never>;
+    init(options?: AuthInitOptions): Promise<AuthInitResult>;
     getSession(options?: SessionRequestOptions): Promise<GhostlySession | null>;
     login(options?: LoginOptions): void;
     logout(): Promise<void>;
-    processCallback(): Promise<ProcessCallbackResult>;
+    refresh(): Promise<GhostlySession | null>;
     requireSession(): Promise<GhostlySession>;
     subscribe(listener: SessionListener): () => void;
 }
 
-export type { AuthClient as A, GhostlySession as G, LoginOptions as L, ProcessCallbackResult as P, SessionListener as S, SessionRequestOptions as a };
+export type { AuthClient as A, GhostlySession as G, LoginOptions as L, SessionListener as S, AuthClientOptions as a, AuthInitOptions as b, AuthInitResult as c, SessionRequestOptions as d };

package/dist/{auth-sdk-error-DKM7PyKC.d.ts → auth-sdk-error-D3gsfK9d.d.ts}

@@ -1,7 +1,4 @@
 declare const authErrorCode: {
-    readonly callbackMissingToken: "callback_missing_token";
-    readonly callbackInvalidToken: "callback_invalid_token";
-    readonly callbackValidationFailed: "callback_validation_failed";
     readonly unauthorized: "unauthorized";
     readonly networkError: "network_error";
     readonly apiError: "api_error";

package/dist/extension.d.ts

@@ -0,0 +1,49 @@
+import { G as GhostlySession, A as AuthClient, L as LoginOptions } from './auth-client-Cdkp07ii.js';
+
+interface LaunchWebAuthFlowPayload {
+    authorizeUrl: string;
+}
+interface OpenAuthorizePagePayload {
+    authorizeUrl: string;
+}
+type PersistAccessToken = (token: ExtensionStoredAccessToken | null) => Promise<void> | void;
+type ResolveSessionId = () => Promise<string | null>;
+type RestoreAccessToken = (() => Promise<ExtensionStoredAccessToken | null>) | (() => ExtensionStoredAccessToken | null);
+interface ExtensionAccessToken {
+    accessToken: string;
+    application: string;
+    expiresAt: string | null;
+    session: GhostlySession | null;
+    tokenType: string;
+}
+interface ExtensionAccessTokenRequestOptions {
+    forceRefresh?: boolean;
+}
+interface ExtensionStoredAccessToken extends ExtensionAccessToken {
+}
+interface ExtensionAuthClientOptions {
+    apiOrigin: string;
+    application?: string;
+    clearSessionId?: () => Promise<void> | void;
+    launchWebAuthFlow?: (payload: LaunchWebAuthFlowPayload) => Promise<void>;
+    openAuthorizePage?: (payload: OpenAuthorizePagePayload) => Promise<void>;
+    persistAccessToken?: PersistAccessToken;
+    resolveSessionId?: ResolveSessionId;
+    restoreAccessToken?: RestoreAccessToken;
+}
+interface ExtensionAuthClient extends AuthClient {
+    getAccessToken(options?: ExtensionAccessTokenRequestOptions): Promise<ExtensionAccessToken | null>;
+    loginWithTabFlow(options?: LoginOptions): Promise<void>;
+    loginWithWebAuthFlow(options?: LoginOptions): Promise<void>;
+}
+declare function createExtensionAuthClient(options: ExtensionAuthClientOptions): ExtensionAuthClient;
+
+interface ChromeExtensionAuthClientOptions extends Omit<ExtensionAuthClientOptions, "clearSessionId" | "openAuthorizePage" | "persistAccessToken" | "resolveSessionId" | "restoreAccessToken"> {
+    accessTokenStorageKey?: string;
+    sessionCookieName?: string;
+    sessionStorageKey?: string;
+    tokenExpiresAtStorageKey?: string;
+}
+declare function createChromeExtensionAuthClient(options: ChromeExtensionAuthClientOptions): ExtensionAuthClient;
+
+export { type ChromeExtensionAuthClientOptions, type ExtensionAccessToken, type ExtensionAccessTokenRequestOptions, type ExtensionAuthClient, type ExtensionAuthClientOptions, type ExtensionStoredAccessToken, createChromeExtensionAuthClient, createExtensionAuthClient };