@ghostly-solutions/auth

Purpose

Authentication SDK for Ghostly Solutions products.

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:

npm ci
npm run check

Expanded commands:

npm run lint
npm run typecheck
npm run test
npm run build

Pack verification:

npm pack --dry-run

Run

This repository does not start a long-running application by default.

For local manual exploration:

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
• authPathPrefix
• 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:

• 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:

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. 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
• 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.

If auth is reverse-proxied under a path prefix such as /admin, configure authPathPrefix: "/admin". The effective runtime contract becomes /admin/oauth/*.

Install

npm install @ghostly-solutions/auth

Peer dependencies:

• react >= 18
• react-dom >= 18

Core Usage

import { createAuthClient } from "@ghostly-solutions/auth";

const auth = createAuthClient({
  apiOrigin: "https://api.ghostlysolutions.com",
  authPathPrefix: "/admin",
  application: "admin",
});

await auth.init();
const session = await auth.getSession();

if (!session) {
  auth.login({ returnTo: window.location.pathname });
}

React Usage

import { AuthProvider, AuthSessionGate } from "@ghostly-solutions/auth/react";

export function App() {
  return (
    <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>
  );
}

Next.js Usage

Use the server helpers to resolve the current session from request headers.

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

import { createExtensionAuthClient } from "@ghostly-solutions/auth/extension";

const auth = createExtensionAuthClient({
  apiOrigin: "https://api.ghostlysolutions.com",
  application: "ghostguard-extension",
});

await auth.login({
  returnTo: "/",
});

Documentation

• Docs Index
• Overview
• API Reference
• Integration Guide
• Architecture
• Development and CI
• Demo