rastack 0.0.53 → 0.0.54

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.0.54](https://github.com/theserverkid/reactapistack/compare/v0.0.53...v0.0.54) (2026-07-16)
+
 ### [0.0.53](https://github.com/theserverkid/reactapistack/compare/v0.0.52...v0.0.53) (2026-07-16)
 
 ### [0.0.52](https://github.com/theserverkid/reactapistack/compare/v0.0.51...v0.0.52) (2026-07-16)

package/auth/index.ts

@@ -1,17 +1,26 @@
 /**
- * `rastack/auth` — the whole auth surface of the stack:
+ * `rastack/auth` — the whole auth surface of the stack, both halves:
  *
- * - **Authoring** (types the compiler reads): the entity markers
- *   (`IsAuthenticated`, `AdminGroups<…>`, `OwnerScoped`, `GroupScoped`, …)
- *   and the `Owner` / `Group` access-control field brands.
- * - **Runtime**: the TypeScript auth type ({@link RastackAuth}), the
- *   client-side mirror of the server's authorization rules ({@link can},
- *   row-level security helpers, policy lookup), and the React context the
- *   provider and components share.
+ * **Authentication** (who you are) — the Cognito sign-in that produces a
+ * verified identity: `<CognitoAuthProvider>` + `useCognitoAuth()` driving the
+ * standard **Hosted UI, OAuth 2.0 Authorization Code + PKCE** browser flow
+ * (`tools/src/auth/cognito.ts` is the pure PKCE/JWT/session core), plus a
+ * `local` mode that mints an in-browser session (a server-less dev shim). The
+ * session feeds a {@link RastackAuth} straight into `<RAStackProvider auth={…}>`
+ * (see {@link cognitoToRastackAuth} / {@link useRastackAuthFromCognito}).
  *
- * See `docs/security-and-local-cache.md`.
+ * **Authorization** (what you can reach) — the type-level access rules and their
+ * runtime mirror: the entity markers (`IsAuthenticated`, `AdminGroups<…>`,
+ * `OwnerScoped`, `GroupScoped`, …) and `Owner` / `Group` field brands the
+ * compiler reads, the TypeScript auth type ({@link RastackAuth}), the
+ * client-side mirror of the server's rules ({@link can}, {@link ownsRow}, policy
+ * lookup), and the React context the provider and components share.
+ *
+ * See `docs/cognito-auth.md` (authentication) and
+ * `docs/security-and-local-cache.md` (authorization / row-level security).
  */
 
+// -- authorization (the RLS mirror + authoring markers) --
 export * from "../src/define/auth";
 export * from "./core";
 export {
@@ -21,3 +30,7 @@ export {
   type RastackAccessValue,
   type RastackAuthProviderProps,
 } from "./context";
+
+// -- authentication (Cognito sign-in) --
+export * from "../src/auth/cognito";
+export * from "./provider";

package/auth/provider.ts

@@ -0,0 +1,486 @@
+import {
+  createContext,
+  createElement,
+  ReactElement,
+  ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import {
+  authorizeUrl,
+  CognitoAuthConfig,
+  CognitoClaims,
+  CognitoSession,
+  CognitoTokenResponse,
+  CognitoUser,
+  createPkcePair,
+  isSessionValid,
+  localSession,
+  logoutUrl,
+  parseRedirect,
+  randomState,
+  sessionFromTokens,
+  tokenEndpoint,
+  tokenRequestBody,
+} from "../src/auth/cognito";
+import { anonymousAuth, authFromClaims, type RastackAuth } from "./core";
+
+/** Where a sign-in should send the browser: the real Hosted UI, or a local
+ * synthetic session for server-less (`mode:"local"`) dev. */
+export type CognitoAuthMode = "hosted-ui" | "local";
+
+/** The minimal key-value storage the provider persists a session in. */
+export interface AuthStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+export interface CognitoAuthProviderConfig extends Partial<CognitoAuthConfig> {
+  /**
+   * `hosted-ui` (default) runs the real OAuth Authorization Code + PKCE
+   * redirect against Cognito. `local` mints an unsigned in-browser session on
+   * sign-in — a server-less dev shim — so the entire app
+   * (which in `<RAStackProvider mode="local">` runs with no identity provider)
+   * can still exercise the login button and write-gating. Swap to `hosted-ui`
+   * for a deployed, Cognito-protected backend.
+   */
+  mode?: CognitoAuthMode;
+  /** The simulated user granted on sign-in in `local` mode. */
+  localUser?: {
+    sub?: string;
+    email?: string;
+    username?: string;
+    groups?: string[];
+  };
+  /** Which token to hand out as the Bearer credential. Default `"id"` (its
+   * `aud` is the app client id, matching `rastack-server --audience`). */
+  tokenType?: "id" | "access";
+  /** Persistence for the session (default `localStorage`, memory fallback). */
+  storage?: AuthStorage;
+  /** Storage key prefix (default `"rastack.auth"`). */
+  storageKey?: string;
+  /** Override `fetch` (SSR/tests). Defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch;
+  /** Injectable clock for tests. Defaults to `Date.now`. */
+  now?: () => number;
+  onSignIn?: (session: CognitoSession) => void;
+  onSignOut?: () => void;
+  onError?: (error: unknown) => void;
+}
+
+export type CognitoAuthStatus =
+  | "loading"
+  | "authenticated"
+  | "unauthenticated"
+  | "error";
+
+/** What `useCognitoAuth()` returns. */
+export interface CognitoAuthContextValue {
+  status: CognitoAuthStatus;
+  isAuthenticated: boolean;
+  isLoading: boolean;
+  /**
+   * True once auth has resolved (a session was restored, a redirect completed,
+   * or we settled on signed-out) — i.e. any time we're not still booting. The
+   * generated read hooks gate their queries on this so *viewing works whether
+   * or not the user is signed in*; write UI gates on `isAuthenticated` instead.
+   */
+  isReady: boolean;
+  user: CognitoUser | null;
+  /** Verified `cognito:groups` (empty when signed out). */
+  groups: string[];
+  claims: CognitoClaims | null;
+  error: unknown;
+  /** Start sign-in (Hosted UI redirect, or a local session in `local` mode). */
+  login: () => Promise<void>;
+  /** Sign out — clears the local session (and, in `hosted-ui`, the Cognito cookie). */
+  logout: () => Promise<void>;
+  /**
+   * A valid bearer token, refreshing first if it's near expiry. Rejects if the
+   * user isn't signed in — pass this straight to `<RAStackProvider getToken>`.
+   */
+  getToken: () => Promise<string>;
+}
+
+const CognitoAuthContext = createContext<CognitoAuthContextValue | null>(null);
+
+/**
+ * DOM globals accessed defensively through `globalThis`, so this module
+ * type-checks under a non-DOM lib (the pure `.ts` graph the components and
+ * tests import via the `rastack/auth` barrel) and stays SSR-safe — every use is
+ * still guarded before it runs.
+ */
+const dom = globalThis as unknown as {
+  window?: any;
+  document?: any;
+  localStorage?: any;
+};
+
+/** An in-memory `AuthStorage` for SSR / environments without `localStorage`. */
+function memoryStorage(): AuthStorage {
+  const map = new Map<string, string>();
+  return {
+    getItem: (k) => (map.has(k) ? map.get(k)! : null),
+    setItem: (k, v) => void map.set(k, v),
+    removeItem: (k) => void map.delete(k),
+  };
+}
+
+function defaultStorage(): AuthStorage {
+  try {
+    if (dom.localStorage) {
+      // Touch it — Safari private mode throws on write.
+      const probe = "__rastack_auth_probe__";
+      dom.localStorage.setItem(probe, "1");
+      dom.localStorage.removeItem(probe);
+      return dom.localStorage as AuthStorage;
+    }
+  } catch {
+    /* fall through to memory */
+  }
+  return memoryStorage();
+}
+
+function requireHostedConfig(
+  config: CognitoAuthProviderConfig,
+): CognitoAuthConfig {
+  if (!config.domain || !config.clientId || !config.redirectUri) {
+    throw new Error(
+      "CognitoAuthProvider: `domain`, `clientId` and `redirectUri` are required for hosted-ui mode.",
+    );
+  }
+  return config as CognitoAuthConfig;
+}
+
+/**
+ * Provides Cognito auth to the tree. Reads any persisted session on mount and,
+ * in `hosted-ui` mode, completes the code exchange if the current URL is a
+ * Cognito redirect (`?code=…&state=…`).
+ */
+export function CognitoAuthProvider({
+  config,
+  children,
+}: {
+  config: CognitoAuthProviderConfig;
+  children: ReactNode;
+}): ReactElement {
+  const mode = config.mode ?? "hosted-ui";
+  const now = config.now ?? (() => Date.now());
+  const storage = useMemo(
+    () => config.storage ?? defaultStorage(),
+    [config.storage],
+  );
+  const keyBase = config.storageKey ?? "rastack.auth";
+  const sessionKey = `${keyBase}.session`;
+  const pkceKey = `${keyBase}.pkce`;
+  const doFetch = config.fetchImpl ?? (globalThis.fetch?.bind(globalThis) as typeof fetch);
+
+  const [session, setSession] = useState<CognitoSession | null>(null);
+  const [status, setStatus] = useState<CognitoAuthStatus>("loading");
+  const [error, setError] = useState<unknown>(null);
+  const sessionRef = useRef<CognitoSession | null>(null);
+  sessionRef.current = session;
+
+  const persist = useCallback(
+    (next: CognitoSession | null) => {
+      setSession(next);
+      if (next) storage.setItem(sessionKey, JSON.stringify(next));
+      else storage.removeItem(sessionKey);
+    },
+    [storage, sessionKey],
+  );
+
+  const fail = useCallback(
+    (err: unknown) => {
+      setError(err);
+      setStatus("error");
+      config.onError?.(err);
+    },
+    [config],
+  );
+
+  // -- boot: restore a stored session, or finish a redirect ------------------
+  useEffect(() => {
+    let cancelled = false;
+
+    async function boot() {
+      // A live stored session wins.
+      const stored = storage.getItem(sessionKey);
+      if (stored) {
+        try {
+          const parsed: CognitoSession = JSON.parse(stored);
+          const valid = isSessionValid(parsed, now());
+          if (valid) {
+            if (!cancelled) {
+              setSession(parsed);
+              setStatus("authenticated");
+            }
+            return;
+          }
+          // Expired but refreshable → try below; otherwise drop it.
+          if (mode === "hosted-ui" && parsed.refreshToken) {
+            const refreshed = await refreshSession(parsed);
+            if (refreshed && !cancelled) {
+              persist(refreshed);
+              setStatus("authenticated");
+              return;
+            }
+          }
+          storage.removeItem(sessionKey);
+        } catch {
+          storage.removeItem(sessionKey);
+        }
+      }
+
+      // Complete a Hosted UI redirect if this load is one.
+      if (mode === "hosted-ui" && dom.window) {
+        const redirect = parseRedirect(dom.window.location.search);
+        if (redirect.error) {
+          clearUrl();
+          if (!cancelled) fail(new Error(redirect.errorDescription ?? redirect.error));
+          return;
+        }
+        if (redirect.code) {
+          try {
+            const exchanged = await exchangeCode(redirect.code, redirect.state);
+            clearUrl();
+            if (!cancelled) {
+              persist(exchanged);
+              setStatus("authenticated");
+              config.onSignIn?.(exchanged);
+            }
+          } catch (err) {
+            clearUrl();
+            if (!cancelled) fail(err);
+          }
+          return;
+        }
+      }
+
+      if (!cancelled) setStatus("unauthenticated");
+    }
+
+    boot();
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  /** Drop the `?code=&state=` off the address bar after a successful exchange. */
+  function clearUrl() {
+    if (!dom.window || !dom.window.history?.replaceState) return;
+    dom.window.history.replaceState(
+      {},
+      dom.document?.title ?? "",
+      dom.window.location.pathname,
+    );
+  }
+
+  async function exchangeCode(
+    code: string,
+    state?: string,
+  ): Promise<CognitoSession> {
+    const hosted = requireHostedConfig(config);
+    const pending = storage.getItem(pkceKey);
+    if (!pending) throw new Error("No pending PKCE verifier — restart sign-in.");
+    const { verifier, state: expectedState } = JSON.parse(pending) as {
+      verifier: string;
+      state: string;
+    };
+    storage.removeItem(pkceKey);
+    if (expectedState && state && expectedState !== state) {
+      throw new Error("OAuth state mismatch — possible CSRF, sign-in rejected.");
+    }
+    const response = await doFetch(tokenEndpoint(hosted), {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: tokenRequestBody(hosted, {
+        grantType: "authorization_code",
+        code,
+        codeVerifier: verifier,
+      }),
+    });
+    if (!response.ok) {
+      throw new Error(`Token exchange failed (${response.status}).`);
+    }
+    const tokens = (await response.json()) as CognitoTokenResponse;
+    return sessionFromTokens(tokens, now());
+  }
+
+  async function refreshSession(
+    prev: CognitoSession,
+  ): Promise<CognitoSession | null> {
+    if (mode === "local") {
+      return localSession(config.localUser, now());
+    }
+    if (!prev.refreshToken) return null;
+    try {
+      const hosted = requireHostedConfig(config);
+      const response = await doFetch(tokenEndpoint(hosted), {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: tokenRequestBody(hosted, {
+          grantType: "refresh_token",
+          refreshToken: prev.refreshToken,
+        }),
+      });
+      if (!response.ok) return null;
+      const tokens = (await response.json()) as CognitoTokenResponse;
+      // A refresh grant doesn't return a new refresh token — carry the old one.
+      const next = sessionFromTokens(tokens, now());
+      return { ...next, refreshToken: next.refreshToken ?? prev.refreshToken };
+    } catch {
+      return null;
+    }
+  }
+
+  const login = useCallback(async () => {
+    setError(null);
+    if (mode === "local") {
+      const next = localSession(config.localUser, now());
+      persist(next);
+      setStatus("authenticated");
+      config.onSignIn?.(next);
+      return;
+    }
+    const hosted = requireHostedConfig(config);
+    const { verifier, challenge } = await createPkcePair();
+    const state = randomState();
+    storage.setItem(pkceKey, JSON.stringify({ verifier, state }));
+    const url = authorizeUrl(hosted, { state, codeChallenge: challenge });
+    if (dom.window) dom.window.location.assign(url);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [mode, config, persist, storage, pkceKey]);
+
+  const logout = useCallback(async () => {
+    persist(null);
+    setStatus("unauthenticated");
+    config.onSignOut?.();
+    if (mode === "hosted-ui" && config.domain && config.clientId) {
+      if (dom.window) {
+        dom.window.location.assign(logoutUrl(config as CognitoAuthConfig));
+      }
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [mode, config, persist]);
+
+  const tokenType = config.tokenType ?? "id";
+  const getToken = useCallback(async () => {
+    let current = sessionRef.current;
+    if (current && !isSessionValid(current, now())) {
+      const refreshed = await refreshSession(current);
+      if (refreshed) {
+        persist(refreshed);
+        current = refreshed;
+      } else {
+        persist(null);
+        setStatus("unauthenticated");
+        current = null;
+      }
+    }
+    if (!current) throw new Error("Not authenticated.");
+    return tokenType === "access" ? current.accessToken : current.idToken;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [persist, tokenType]);
+
+  // Flip to "unauthenticated" the moment a session lapses (no refresh path).
+  useEffect(() => {
+    if (!session || mode === "local") return;
+    const ms = session.expiresAt - now();
+    if (ms <= 0) return;
+    const timer = setTimeout(() => {
+      if (!session.refreshToken) {
+        persist(null);
+        setStatus("unauthenticated");
+      }
+    }, ms);
+    return () => clearTimeout(timer);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [session, mode]);
+
+  const value = useMemo<CognitoAuthContextValue>(
+    () => ({
+      status,
+      isAuthenticated: status === "authenticated" && !!session,
+      isLoading: status === "loading",
+      isReady: status !== "loading",
+      user: session?.user ?? null,
+      groups: session?.user.groups ?? [],
+      claims: session?.claims ?? null,
+      error,
+      login,
+      logout,
+      getToken,
+    }),
+    [status, session, error, login, logout, getToken],
+  );
+
+  return createElement(CognitoAuthContext.Provider, { value }, children);
+}
+
+/**
+ * A safe default for `useCognitoAuth()` outside a `<CognitoAuthProvider>`:
+ * resolved-but-signed-out, so the generated read hooks (which only read
+ * `isReady`) keep working in an app that wires identity some other way, while
+ * the sign-in actions throw a clear error if actually invoked.
+ */
+const NO_PROVIDER_VALUE: CognitoAuthContextValue = {
+  status: "unauthenticated",
+  isAuthenticated: false,
+  isLoading: false,
+  isReady: true,
+  user: null,
+  groups: [],
+  claims: null,
+  error: null,
+  login: async () => {
+    throw new Error("login() requires a <CognitoAuthProvider>.");
+  },
+  logout: async () => {
+    throw new Error("logout() requires a <CognitoAuthProvider>.");
+  },
+  getToken: async () => {
+    throw new Error("getToken() requires a <CognitoAuthProvider>.");
+  },
+};
+
+/**
+ * Consume the Cognito auth state + actions. Outside a `<CognitoAuthProvider>`
+ * this returns a resolved, signed-out value (never throws) so the generated
+ * read hooks work with or without Cognito wired up.
+ */
+export function useCognitoAuth(): CognitoAuthContextValue {
+  return useContext(CognitoAuthContext) ?? NO_PROVIDER_VALUE;
+}
+
+/**
+ * Map the Cognito auth state to the framework-wide {@link RastackAuth} the
+ * authorization half (`can`/`ownsRow`, `<RAStackProvider auth={…}>`) consumes:
+ * the ID token's claims when signed in, an anonymous identity otherwise.
+ */
+export function cognitoToRastackAuth(
+  auth: Pick<CognitoAuthContextValue, "isAuthenticated" | "claims">,
+): RastackAuth {
+  return auth.isAuthenticated && auth.claims
+    ? authFromClaims(auth.claims as unknown as Record<string, unknown>)
+    : anonymousAuth();
+}
+
+/**
+ * The signed-in {@link RastackAuth} derived from the Cognito context — hand it
+ * to `<RAStackProvider auth={…}>` (or `<RastackAuthProvider auth={…}>`) so one
+ * Cognito identity drives the engine, owner stamping, and component gating.
+ */
+export function useRastackAuthFromCognito(): RastackAuth {
+  const auth = useCognitoAuth();
+  return useMemo(
+    () => cognitoToRastackAuth(auth),
+    [auth.isAuthenticated, auth.claims],
+  );
+}