@graphoria/react 0.1.0

package/src/gates.tsx

@@ -0,0 +1,33 @@
+import type { ReactNode } from "react";
+
+import { useAuth } from "./AuthContext";
+
+interface AuthorizeProps<TRole extends string> {
+  roles: TRole[];
+  fallback?: ReactNode;
+  children: ReactNode;
+}
+
+export function Authorize<TRole extends string = string>({
+  roles,
+  fallback = null,
+  children,
+}: AuthorizeProps<TRole>) {
+  const { hasAnyRole } = useAuth<TRole>();
+  return <>{hasAnyRole(roles) ? children : fallback}</>;
+}
+
+interface GateProps {
+  fallback?: ReactNode;
+  children: ReactNode;
+}
+
+export function Authenticated({ fallback = null, children }: GateProps) {
+  const { isAuthenticated } = useAuth();
+  return <>{isAuthenticated ? children : fallback}</>;
+}
+
+export function Unauthenticated({ fallback = null, children }: GateProps) {
+  const { isAuthenticated } = useAuth();
+  return <>{isAuthenticated ? fallback : children}</>;
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+export { AuthProvider, useAuth } from "./AuthContext";
+export {
+  AppProvider,
+  useRouteConfig,
+  useCanAccess,
+  type RouteConfigContextType,
+} from "./AppProvider";
+export { Authorize, Authenticated, Unauthenticated } from "./gates";
+export {
+  getAccessToken,
+  setAccessToken,
+  subscribeAccessToken,
+  ensureFreshToken,
+} from "./tokenStore";
+export { GraphQLFetchError } from "./transport";
+export type {
+  User,
+  AuthState,
+  AuthContextType,
+  TokenResponse,
+  RouteConfig,
+  AuthTransportOptions,
+} from "./types";

package/src/tokenStore.ts

@@ -0,0 +1,70 @@
+// ============================================================================
+// Token Store - framework-agnostic, module-level state.
+//
+// User's GraphQL client (Apollo/urql/relay/anything) integrates via:
+//   - getAccessToken() in its auth middleware
+//   - subscribeAccessToken() to react to changes (e.g. restart WS)
+//   - ensureFreshToken() from its 401 error handler
+// AuthProvider wires the actual refresh/logout implementations via
+// setRefreshHandler / setLogoutHandler at mount time.
+// ============================================================================
+
+type RefreshHandler = () => Promise<boolean>;
+type LogoutHandler = () => Promise<void> | void;
+type Listener = (token: string | null) => void;
+
+let inMemoryAccessToken: string | null = null;
+let refreshHandler: RefreshHandler | null = null;
+let logoutHandler: LogoutHandler | null = null;
+let inflightRefresh: Promise<boolean> | null = null;
+const listeners: Set<Listener> = new Set();
+
+export function getAccessToken(): string | null {
+  return inMemoryAccessToken;
+}
+
+export function setAccessToken(token: string | null): void {
+  if (inMemoryAccessToken === token) return;
+  inMemoryAccessToken = token;
+  for (const cb of listeners) cb(token);
+}
+
+/** Subscribe to token changes. Returns unsubscribe fn. */
+export function subscribeAccessToken(cb: Listener): () => void {
+  listeners.add(cb);
+  return () => listeners.delete(cb);
+}
+
+export function setRefreshHandler(fn: RefreshHandler | null): void {
+  refreshHandler = fn;
+}
+
+export function setLogoutHandler(fn: LogoutHandler | null): void {
+  logoutHandler = fn;
+}
+
+/**
+ * Single-flight token refresh. Call from any GraphQL client's 401 handler.
+ * Concurrent calls share one in-flight refresh. On failure, triggers logout.
+ */
+export function ensureFreshToken(): Promise<boolean> {
+  if (inflightRefresh) return inflightRefresh;
+  if (!refreshHandler) return Promise.resolve(false);
+
+  inflightRefresh = refreshHandler()
+    .then((ok) => {
+      if (!ok && logoutHandler) {
+        void logoutHandler();
+      }
+      return ok;
+    })
+    .catch(() => {
+      if (logoutHandler) void logoutHandler();
+      return false;
+    })
+    .finally(() => {
+      inflightRefresh = null;
+    });
+
+  return inflightRefresh;
+}

package/src/transport.ts

@@ -0,0 +1,84 @@
+// ============================================================================
+// Minimal GraphQL-over-fetch transport for built-in auth mutations.
+// Not exposed publicly — users bring their own GraphQL client for app queries.
+// ============================================================================
+
+export interface GraphQLError {
+  message: string;
+  extensions?: Record<string, unknown>;
+  path?: ReadonlyArray<string | number>;
+}
+
+export class GraphQLFetchError extends Error {
+  status: number;
+  body: string;
+  errors?: GraphQLError[];
+
+  constructor(message: string, status: number, body: string, errors?: GraphQLError[]) {
+    super(message);
+    this.name = "GraphQLFetchError";
+    this.status = status;
+    this.body = body;
+    this.errors = errors;
+  }
+}
+
+interface GqlFetchOptions {
+  bearer?: string | null;
+  credentials?: boolean;
+  signal?: AbortSignal;
+}
+
+interface GqlResponse<T> {
+  data?: T;
+  errors?: GraphQLError[];
+}
+
+export async function gqlFetch<T>(
+  uri: string,
+  query: string,
+  variables: Record<string, unknown> | undefined,
+  opts: GqlFetchOptions = {},
+): Promise<T> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  };
+  if (opts.bearer) headers.Authorization = `Bearer ${opts.bearer}`;
+
+  const res = await fetch(uri, {
+    method: "POST",
+    headers,
+    credentials: opts.credentials === false ? "same-origin" : "include",
+    body: JSON.stringify({ query, variables }),
+    signal: opts.signal,
+  });
+
+  const text = await res.text();
+
+  if (!res.ok) {
+    throw new GraphQLFetchError(`GraphQL request failed: ${res.status}`, res.status, text);
+  }
+
+  let parsed: GqlResponse<T>;
+  try {
+    parsed = JSON.parse(text) as GqlResponse<T>;
+  } catch {
+    throw new GraphQLFetchError("Invalid JSON response", res.status, text);
+  }
+
+  if (parsed.errors && parsed.errors.length > 0) {
+    throw new GraphQLFetchError(
+      parsed.errors[0]?.message ?? "GraphQL error",
+      res.status,
+      text,
+      parsed.errors,
+    );
+  }
+
+  if (parsed.data === undefined) {
+    throw new GraphQLFetchError("Empty GraphQL response", res.status, text);
+  }
+
+  return parsed.data;
+}

package/src/types.ts

@@ -0,0 +1,53 @@
+// ============================================================================
+// Auth Types
+// ============================================================================
+
+export interface TokenResponse<TRole extends string = string> {
+  access_token: string;
+  expires_in: number; // seconds until access_token expires
+  role: TRole;
+}
+
+export interface User<TRole extends string = string> {
+  role: TRole;
+}
+
+export interface AuthState<TRole extends string = string> {
+  isAuthenticated: boolean;
+  isLoading: boolean;
+  user: User<TRole> | null;
+  error: string | null;
+}
+
+export interface AuthContextType<TRole extends string = string> extends AuthState<TRole> {
+  login: (username: string, password: string) => Promise<User<TRole> | null>;
+  logout: () => Promise<void>;
+  hasRole: (role: TRole) => boolean;
+  hasAnyRole: (roles: TRole[]) => boolean;
+  /** Manually trigger a token refresh */
+  refreshToken: () => Promise<boolean>;
+}
+
+// ============================================================================
+// Route Configuration Types
+// ============================================================================
+
+export interface RouteConfig<TRole extends string = string> {
+  /** Map of path to required roles (null = public) */
+  permissions: Record<string, TRole[] | null>;
+  /** Default route for each role after login */
+  defaultRoutes: Partial<Record<TRole, string>>;
+  /** Fallback route if role not in defaultRoutes */
+  fallbackRoute: string;
+}
+
+// ============================================================================
+// Auth Transport Options
+// ============================================================================
+
+export interface AuthTransportOptions {
+  /** GraphQL HTTP endpoint for auth mutations (default: "/graphql") */
+  httpUri?: string;
+  /** Include credentials (cookies) in requests (default: true) */
+  includeCredentials?: boolean;
+}