@ghostly-solutions/auth 0.2.1 → 0.2.3

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,13 +1,149 @@
 # @ghostly-solutions/auth
 
+## Purpose
+
 Authentication SDK for Ghostly Solutions products.
 
-The SDK is OAuth redirect + server-owned cookie session. Client code does not process OAuth
-callback tokens and does not define auth route handlers.
+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.
+
+Repository type: `lib-repo`.
+
+## Architecture
+
+Package entrypoints:
+
+- `@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
+
+The SDK assumes a fixed Ghostly Auth API surface and keeps token handling server-owned.
+
+## Stack
+
+- TypeScript
+- tsup
+- Vitest
+- Biome
+- npm
+
+## Build
+
+Install and validate:
+
+```bash
+npm ci
+npm run check
+```
+
+Expanded commands:
+
+```bash
+npm run lint
+npm run typecheck
+npm run test
+npm run build
+```
+
+Pack verification:
+
+```bash
+npm pack --dry-run
+```
+
+## Run
+
+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
+
+## Dependencies
+
+- 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
+
+Peer dependencies:
 
-## Contract
+- `react >= 18`
+- `react-dom >= 18`
 
-Fixed API endpoints:
+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
+```
+
+## 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
+
+## License
+
+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.
+
+## Runtime Contract
+
+The SDK assumes a fixed auth surface on your auth gateway:
 
 - `GET /oauth/authorize`
 - `GET /oauth/callback/provider`
@@ -15,24 +151,34 @@ Fixed API endpoints:
 - `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();
+const auth = createAuthClient({
+  apiOrigin: "https://api.ghostlysolutions.com",
+  application: "admin",
+});
 
 await auth.init();
 const session = await auth.getSession();
 
 if (!session) {
-  auth.login();
+  auth.login({ returnTo: window.location.pathname });
 }
 ```
 
@@ -43,10 +189,15 @@ import { AuthProvider, AuthSessionGate } from "@ghostly-solutions/auth/react";
 
 export function App() {
   return (
-    <AuthProvider>
+    <AuthProvider
+      apiOrigin="https://api.ghostlysolutions.com"
+      application="admin"
+    >
       <AuthSessionGate
         loading={<div>Loading...</div>}
-        unauthorized={({ login }) => <button onClick={() => login()}>Sign in</button>}
+        unauthorized={({ login }) => (
+          <button onClick={() => login({ returnTo: "/" })}>Sign in</button>
+        )}
         authorized={(session) => <div>{session.email}</div>}
       />
     </AuthProvider>
@@ -56,6 +207,8 @@ export function App() {
 
 ## Next.js Usage
 
+Use the server helpers to resolve the current session from request headers.
+
 ```ts
 import { requireNextServerSession } from "@ghostly-solutions/auth/next";
 
@@ -65,13 +218,11 @@ export async function getServerData(headers: Headers) {
     apiOrigin: "https://api.ghostlysolutions.com",
   });
 
-  return {
-    actorId: session.id,
-  };
+  return { actorId: session.id };
 }
 ```
 
-No Next route handlers are required.
+No Next.js route handlers are required.
 
 ## Extension Usage
 
@@ -80,26 +231,14 @@ import { createExtensionAuthClient } from "@ghostly-solutions/auth/extension";
 
 const auth = createExtensionAuthClient({
   apiOrigin: "https://api.ghostlysolutions.com",
-  launchWebAuthFlow: async ({ authorizeUrl }) => {
-    // chrome.identity.launchWebAuthFlow(...) wrapper
-    await openAuthWindow(authorizeUrl);
-  },
+  application: "ghostguard-extension",
 });
 
-await auth.loginWithWebAuthFlow();
-```
-
-## Development
-
-```bash
-npm run lint
-npm run typecheck
-npm run test
-npm run build
+await auth.login({
+  returnTo: "/",
+});
 ```
 
-Bun is optional for local shortcuts (`bun run ...`).
-
 ## Documentation
 
 - [Docs Index](./docs/index.md)

package/dist/extension.d.ts

@@ -1,16 +1,52 @@
-import { A as AuthClient, L as LoginOptions } from './auth-client-Cdkp07ii.js';
+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;
-    launchWebAuthFlow: (payload: LaunchWebAuthFlowPayload) => Promise<void>;
+    defaultReturnToPath?: 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;
+declare function createCustomExtensionAuthClient(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;
+
+declare function createExtensionAuthClient(options: ExtensionAuthClientOptions | ChromeExtensionAuthClientOptions): ExtensionAuthClient;
 
-export { type ExtensionAuthClient, type ExtensionAuthClientOptions, createExtensionAuthClient };
+export { type ChromeExtensionAuthClientOptions, type ExtensionAccessToken, type ExtensionAccessTokenRequestOptions, type ExtensionAuthClient, type ExtensionAuthClientOptions, type ExtensionStoredAccessToken, createChromeExtensionAuthClient, createCustomExtensionAuthClient, createExtensionAuthClient };