@ghostly-solutions/auth 0.1.0

package/README.md

@@ -0,0 +1,127 @@
+# @ghostly-solutions/auth
+
+Authentication SDK for Ghostly Solutions products.
+
+The SDK implements a fixed Keycloak redirect flow with Ghostly Auth API validation and typed session state.
+
+## Highlights
+
+- 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.
+
+## Fixed API Endpoints
+
+- `GET /v1/auth/keycloak/login`
+- `POST /v1/auth/keycloak/validate`
+- `GET /v1/auth/me`
+- `POST /v1/auth/logout`
+
+## Entry Points
+
+- `@ghostly-solutions/auth`
+- `@ghostly-solutions/auth/react`
+- `@ghostly-solutions/auth/next`
+
+## Install
+
+```bash
+npm install @ghostly-solutions/auth
+```
+
+## Development
+
+```bash
+npm run lint
+npm run typecheck
+npm run test
+npm run build
+```
+
+All CI and official workflows are npm-first.
+
+Bun is optional for local use through aliases in `bun.json`.
+
+## Quick Start
+
+```ts
+import { createAuthClient } from "@ghostly-solutions/auth";
+
+const authClient = createAuthClient();
+
+// Start login flow
+authClient.login();
+
+// In /auth/callback route
+await authClient.completeCallbackRedirect();
+```
+
+## Next.js "No-Glue" Integration
+
+Use the high-level Next adapter in `@ghostly-solutions/auth/next`:
+
+- `getNextServerSession()`
+- `requireNextServerSession()`
+- `createNextAuthRouteHandlers({ mode: "mock" | "proxy" })`
+
+This removes custom auth boilerplate from application code and keeps app-level integration thin.
+
+## Callback Page Helper
+
+```tsx
+import { AuthCallbackHandler } from "@ghostly-solutions/auth/react";
+
+export default function AuthCallbackPage() {
+  return (
+    <AuthCallbackHandler
+      processing={<div>Signing you in...</div>}
+      renderError={() => <div>Could not complete sign in.</div>}
+    />
+  );
+}
+```
+
+## Error Handling
+
+```ts
+import { AuthSdkError } from "@ghostly-solutions/auth";
+
+try {
+  await authClient.requireSession();
+} catch (error) {
+  if (error instanceof AuthSdkError) {
+    if (error.code === "unauthorized") {
+      authClient.login();
+    }
+  }
+}
+```
+
+## Documentation
+
+- [Docs Index](./docs/index.md)
+- [Overview](./docs/overview.md)
+- [API Reference](./docs/api-reference.md)
+- [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).

package/dist/auth-client-CAHMjodm.d.ts

@@ -0,0 +1,32 @@
+interface GhostlySession {
+    id: string;
+    username: string;
+    firstName: string | null;
+    lastName: string | null;
+    email: string;
+    role: string;
+    permissions: string[];
+}
+
+interface ProcessCallbackResult {
+    redirectTo: string;
+    session: GhostlySession;
+}
+interface LoginOptions {
+    returnTo?: string;
+}
+interface SessionRequestOptions {
+    forceRefresh?: boolean;
+}
+type SessionListener = (session: GhostlySession | null) => void;
+interface AuthClient {
+    completeCallbackRedirect(): Promise<never>;
+    getSession(options?: SessionRequestOptions): Promise<GhostlySession | null>;
+    login(options?: LoginOptions): void;
+    logout(): Promise<void>;
+    processCallback(): Promise<ProcessCallbackResult>;
+    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 };

package/dist/auth-sdk-error-DKM7PyKC.d.ts

@@ -0,0 +1,26 @@
+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";
+    readonly broadcastChannelUnsupported: "broadcast_channel_unsupported";
+    readonly serverOriginResolutionFailed: "server_origin_resolution_failed";
+};
+type AuthErrorCode = (typeof authErrorCode)[keyof typeof authErrorCode];
+
+interface AuthSdkErrorPayload {
+    code: AuthErrorCode;
+    details: unknown;
+    message: string;
+    status: number | null;
+}
+declare class AuthSdkError extends Error {
+    readonly code: AuthErrorCode;
+    readonly details: unknown;
+    readonly status: number | null;
+    constructor(payload: AuthSdkErrorPayload);
+}
+
+export { type AuthErrorCode as A, AuthSdkError as a, type AuthSdkErrorPayload as b, authErrorCode as c };

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import { A as AuthClient, G as GhostlySession } from './auth-client-CAHMjodm.js';
+export { L as LoginOptions, P as ProcessCallbackResult, S as SessionListener, a as SessionRequestOptions } from './auth-client-CAHMjodm.js';
+export { A as AuthErrorCode, a as AuthSdkError, b as AuthSdkErrorPayload, c as authErrorCode } from './auth-sdk-error-DKM7PyKC.js';
+
+declare const authEndpoints: {
+    readonly loginStart: "/v1/auth/keycloak/login";
+    readonly validateKeycloakToken: "/v1/auth/keycloak/validate";
+    readonly session: "/v1/auth/me";
+    readonly logout: "/v1/auth/logout";
+};
+
+declare const authQueryKeys: {
+    readonly token: "token";
+};
+declare const authRoutes: {
+    readonly root: "/";
+    readonly callback: "/auth/callback";
+};
+
+declare function createAuthClient(): AuthClient;
+
+interface KeycloakValidateRequest {
+    token: string;
+}
+interface KeycloakValidateResponse {
+    session: GhostlySession;
+}
+interface AuthErrorPayload {
+    code: string;
+    details: unknown;
+    message: string;
+}
+
+export { AuthClient, type AuthErrorPayload, GhostlySession, type KeycloakValidateRequest, type KeycloakValidateResponse, authEndpoints, authQueryKeys, authRoutes, createAuthClient };

package/dist/index.js

@@ -0,0 +1,483 @@
+// src/constants/auth-endpoints.ts
+var authApiPrefix = "/v1/auth";
+var authEndpoints = {
+  loginStart: `${authApiPrefix}/keycloak/login`,
+  validateKeycloakToken: `${authApiPrefix}/keycloak/validate`,
+  session: `${authApiPrefix}/me`,
+  logout: `${authApiPrefix}/logout`
+};
+
+// src/constants/auth-keys.ts
+var authQueryKeys = {
+  token: "token"
+};
+var authStorageKeys = {
+  returnTo: "ghostly-auth:return-to"
+};
+var authBroadcast = {
+  channelName: "ghostly-auth-channel",
+  sessionUpdatedEvent: "session-updated"
+};
+var authRoutes = {
+  root: "/",
+  callback: "/auth/callback"
+};
+
+// src/constants/http-status.ts
+var httpStatus = {
+  ok: 200,
+  noContent: 204,
+  badRequest: 400,
+  unauthorized: 401
+};
+
+// src/errors/auth-sdk-error.ts
+var AuthSdkError = class extends Error {
+  code;
+  details;
+  status;
+  constructor(payload) {
+    super(payload.message);
+    this.name = "AuthSdkError";
+    this.code = payload.code;
+    this.details = payload.details;
+    this.status = payload.status;
+  }
+};
+
+// src/types/auth-error-code.ts
+var authErrorCode = {
+  callbackMissingToken: "callback_missing_token",
+  callbackInvalidToken: "callback_invalid_token",
+  callbackValidationFailed: "callback_validation_failed",
+  unauthorized: "unauthorized",
+  networkError: "network_error",
+  apiError: "api_error",
+  broadcastChannelUnsupported: "broadcast_channel_unsupported",
+  serverOriginResolutionFailed: "server_origin_resolution_failed"
+};
+
+// src/core/object-guards.ts
+function isObjectRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isStringValue(value) {
+  return typeof value === "string";
+}
+
+// src/core/session-parser.ts
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((entry) => isStringValue(entry));
+}
+function isGhostlySession(value) {
+  if (!isObjectRecord(value)) {
+    return false;
+  }
+  return isStringValue(value.id) && isStringValue(value.username) && (value.firstName === null || isStringValue(value.firstName)) && (value.lastName === null || isStringValue(value.lastName)) && isStringValue(value.email) && isStringValue(value.role) && isStringArray(value.permissions);
+}
+
+// src/core/broadcast-sync.ts
+function isSessionUpdatedMessage(value) {
+  if (!isObjectRecord(value)) {
+    return false;
+  }
+  if (!isStringValue(value.type)) {
+    return false;
+  }
+  if (value.type !== authBroadcast.sessionUpdatedEvent) {
+    return false;
+  }
+  return value.session === null || isGhostlySession(value.session);
+}
+function createUnsupportedBroadcastChannelError() {
+  return new AuthSdkError({
+    code: authErrorCode.broadcastChannelUnsupported,
+    details: null,
+    message: "BroadcastChannel is unavailable in this runtime.",
+    status: null
+  });
+}
+function createBroadcastSync(options) {
+  if (typeof BroadcastChannel === "undefined") {
+    throw createUnsupportedBroadcastChannelError();
+  }
+  const channel = new BroadcastChannel(authBroadcast.channelName);
+  const onMessage = (event) => {
+    const messageEvent = event;
+    if (!isSessionUpdatedMessage(messageEvent.data)) {
+      return;
+    }
+    options.onSessionUpdated(messageEvent.data.session);
+  };
+  channel.addEventListener("message", onMessage);
+  return {
+    close() {
+      channel.removeEventListener("message", onMessage);
+      channel.close();
+    },
+    publishSession(session) {
+      const payload = {
+        session,
+        type: authBroadcast.sessionUpdatedEvent
+      };
+      channel.postMessage(payload);
+    }
+  };
+}
+
+// src/core/callback-url.ts
+function readCallbackToken(url) {
+  return url.searchParams.get(authQueryKeys.token);
+}
+function removeCallbackToken(url) {
+  const nextUrl = new URL(url.toString());
+  nextUrl.searchParams.delete(authQueryKeys.token);
+  return nextUrl;
+}
+function replaceBrowserHistory(url) {
+  window.history.replaceState(null, "", url.toString());
+}
+
+// src/core/http-client.ts
+var jsonContentType = "application/json";
+var jsonHeaderName = "content-type";
+var includeCredentials = "include";
+var noStoreCache = "no-store";
+function toTypedValue(value) {
+  return value;
+}
+function mapHttpStatusToAuthErrorCode(status) {
+  if (status === httpStatus.unauthorized) {
+    return authErrorCode.unauthorized;
+  }
+  return authErrorCode.apiError;
+}
+async function parseJsonPayload(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+async function parseErrorPayload(response) {
+  const payload = await parseJsonPayload(response);
+  if (!isObjectRecord(payload)) {
+    return {
+      code: null,
+      details: null,
+      message: null
+    };
+  }
+  const maybeCode = payload.code;
+  const maybeMessage = payload.message;
+  return {
+    code: isStringValue(maybeCode) ? maybeCode : null,
+    details: "details" in payload ? payload.details : null,
+    message: isStringValue(maybeMessage) ? maybeMessage : null
+  };
+}
+function buildApiErrorMessage(method, path) {
+  return `Auth API request failed: ${method} ${path}`;
+}
+function buildNetworkErrorMessage(method, path) {
+  return `Auth API network failure: ${method} ${path}`;
+}
+async function request(options) {
+  const expectedStatus = options.expectedStatus ?? httpStatus.ok;
+  const headers = new Headers();
+  const hasBody = typeof options.body !== "undefined";
+  if (hasBody) {
+    headers.set(jsonHeaderName, jsonContentType);
+  }
+  const requestInit = {
+    cache: noStoreCache,
+    credentials: includeCredentials,
+    headers,
+    method: options.method
+  };
+  if (hasBody) {
+    requestInit.body = JSON.stringify(options.body);
+  }
+  let response;
+  try {
+    response = await fetch(options.path, requestInit);
+  } catch (error) {
+    throw new AuthSdkError({
+      code: authErrorCode.networkError,
+      details: error,
+      message: buildNetworkErrorMessage(options.method, options.path),
+      status: null
+    });
+  }
+  if (response.status !== expectedStatus) {
+    const parsed = await parseErrorPayload(response);
+    throw new AuthSdkError({
+      code: mapHttpStatusToAuthErrorCode(response.status),
+      details: {
+        apiCode: parsed.code,
+        apiDetails: parsed.details
+      },
+      message: parsed.message ?? buildApiErrorMessage(options.method, options.path),
+      status: response.status
+    });
+  }
+  if (response.status === httpStatus.noContent) {
+    return toTypedValue(null);
+  }
+  const payload = await parseJsonPayload(response);
+  return toTypedValue(payload);
+}
+function getJson(path) {
+  return request({
+    method: "GET",
+    path
+  });
+}
+function postJson(path, body) {
+  return request({
+    body,
+    method: "POST",
+    path
+  });
+}
+function postEmpty(path) {
+  return request({
+    expectedStatus: httpStatus.noContent,
+    method: "POST",
+    path
+  });
+}
+
+// src/core/runtime.ts
+var browserRuntimeErrorMessage = "Browser runtime is required for this auth operation.";
+function isBrowserRuntime() {
+  return typeof window !== "undefined";
+}
+function assertBrowserRuntime() {
+  if (isBrowserRuntime()) {
+    return;
+  }
+  throw new AuthSdkError({
+    code: authErrorCode.apiError,
+    details: null,
+    message: browserRuntimeErrorMessage,
+    status: null
+  });
+}
+
+// src/core/return-to-storage.ts
+function sanitizeReturnTo(value) {
+  if (!value) {
+    return authRoutes.root;
+  }
+  if (!value.startsWith(authRoutes.root)) {
+    return authRoutes.root;
+  }
+  const protocolRelativePrefix = "//";
+  if (value.startsWith(protocolRelativePrefix)) {
+    return authRoutes.root;
+  }
+  return value;
+}
+function getCurrentBrowserPath() {
+  return `${window.location.pathname}${window.location.search}${window.location.hash}`;
+}
+function saveReturnToPath(returnTo) {
+  assertBrowserRuntime();
+  const fallbackPath = getCurrentBrowserPath();
+  const sanitized = sanitizeReturnTo(returnTo ?? fallbackPath);
+  window.sessionStorage.setItem(authStorageKeys.returnTo, sanitized);
+  return sanitized;
+}
+function consumeReturnToPath() {
+  assertBrowserRuntime();
+  const value = window.sessionStorage.getItem(authStorageKeys.returnTo);
+  window.sessionStorage.removeItem(authStorageKeys.returnTo);
+  return sanitizeReturnTo(value);
+}
+
+// src/core/session-store.ts
+var SessionStore = class {
+  listeners = /* @__PURE__ */ new Set();
+  resolvedSession = null;
+  resolveState = "pending";
+  getSessionIfResolved() {
+    if (this.resolveState === "pending") {
+      return null;
+    }
+    return this.resolvedSession;
+  }
+  hasResolvedSession() {
+    return this.resolveState === "resolved";
+  }
+  setSession(session) {
+    this.resolveState = "resolved";
+    this.resolvedSession = session;
+    for (const listener of this.listeners) {
+      listener(session);
+    }
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+};
+
+// src/core/auth-client.ts
+function createPendingRedirectPromise() {
+  return new Promise(() => {
+  });
+}
+function createInvalidSessionPayloadError(path) {
+  return new AuthSdkError({
+    code: authErrorCode.apiError,
+    details: null,
+    message: `Auth API response has invalid session shape: ${path}`,
+    status: null
+  });
+}
+function toValidatedSession(payload, path) {
+  if (!isGhostlySession(payload)) {
+    throw createInvalidSessionPayloadError(path);
+  }
+  return payload;
+}
+function toCallbackFailure(error) {
+  if (error instanceof AuthSdkError) {
+    if (error.status === httpStatus.unauthorized) {
+      return new AuthSdkError({
+        code: authErrorCode.callbackInvalidToken,
+        details: error.details,
+        message: "Callback JWT is invalid or expired.",
+        status: error.status
+      });
+    }
+    return new AuthSdkError({
+      code: authErrorCode.callbackValidationFailed,
+      details: error.details,
+      message: "Keycloak callback validation failed.",
+      status: error.status
+    });
+  }
+  return new AuthSdkError({
+    code: authErrorCode.callbackValidationFailed,
+    details: error,
+    message: "Keycloak callback validation failed.",
+    status: null
+  });
+}
+function createNoopBroadcastSync() {
+  return {
+    close() {
+    },
+    publishSession() {
+    }
+  };
+}
+function createSafeBroadcastSync(onSessionUpdated) {
+  try {
+    return createBroadcastSync({
+      onSessionUpdated
+    });
+  } catch (error) {
+    if (error instanceof AuthSdkError && error.code === authErrorCode.broadcastChannelUnsupported) {
+      return createNoopBroadcastSync();
+    }
+    throw error;
+  }
+}
+async function fetchCurrentSessionFromApi() {
+  const payload = await getJson(authEndpoints.session);
+  if (payload === null) {
+    return null;
+  }
+  return toValidatedSession(payload, authEndpoints.session);
+}
+function createAuthClient() {
+  assertBrowserRuntime();
+  const sessionStore = new SessionStore();
+  const broadcastSync = createSafeBroadcastSync((session) => {
+    sessionStore.setSession(session);
+  });
+  const getSession = async (options) => {
+    const forceRefresh = options?.forceRefresh ?? false;
+    if (sessionStore.hasResolvedSession() && !forceRefresh) {
+      return sessionStore.getSessionIfResolved();
+    }
+    const session = await fetchCurrentSessionFromApi();
+    sessionStore.setSession(session);
+    broadcastSync.publishSession(session);
+    return session;
+  };
+  const requireSession = async () => {
+    const session = await getSession();
+    if (session) {
+      return session;
+    }
+    throw new AuthSdkError({
+      code: authErrorCode.unauthorized,
+      details: null,
+      message: "Authenticated session is required.",
+      status: httpStatus.unauthorized
+    });
+  };
+  const login = (options) => {
+    saveReturnToPath(options?.returnTo);
+    window.location.assign(authEndpoints.loginStart);
+  };
+  const processCallback = async () => {
+    const currentUrl = new URL(window.location.href);
+    const token = readCallbackToken(currentUrl);
+    if (!token) {
+      throw new AuthSdkError({
+        code: authErrorCode.callbackMissingToken,
+        details: null,
+        message: "Missing callback token query parameter.",
+        status: httpStatus.badRequest
+      });
+    }
+    const cleanedUrl = removeCallbackToken(currentUrl);
+    replaceBrowserHistory(cleanedUrl);
+    try {
+      const payload = await postJson(
+        authEndpoints.validateKeycloakToken,
+        { token }
+      );
+      const session = toValidatedSession(payload.session, authEndpoints.validateKeycloakToken);
+      sessionStore.setSession(session);
+      broadcastSync.publishSession(session);
+      return {
+        redirectTo: consumeReturnToPath(),
+        session
+      };
+    } catch (error) {
+      throw toCallbackFailure(error);
+    }
+  };
+  const completeCallbackRedirect = async () => {
+    const result = await processCallback();
+    window.location.replace(result.redirectTo);
+    return createPendingRedirectPromise();
+  };
+  const logout = async () => {
+    await postEmpty(authEndpoints.logout);
+    sessionStore.setSession(null);
+    broadcastSync.publishSession(null);
+  };
+  const subscribe = sessionStore.subscribe.bind(sessionStore);
+  return {
+    completeCallbackRedirect,
+    getSession,
+    login,
+    logout,
+    processCallback,
+    requireSession,
+    subscribe
+  };
+}
+
+export { AuthSdkError, authEndpoints, authErrorCode, authQueryKeys, authRoutes, createAuthClient };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map