rastack 0.0.52 → 0.0.54

package/src/auth/cognito.ts

@@ -0,0 +1,410 @@
+/**
+ * `rastack/auth` — the framework-free Cognito auth core.
+ *
+ * React API Stack verifies Cognito RS256 JWTs on the server (`rastack-server
+ * --jwks --issuer --audience`) and scopes row-level security by the token's
+ * `sub` / `cognito:groups`. This module is the *client* half: the pure,
+ * dependency-free logic for the standard browser sign-in flow — **Cognito
+ * Hosted UI, OAuth 2.0 Authorization Code + PKCE** — that produces exactly the
+ * `identity` (`sub`), `groups`, and bearer `getToken` the `<RAStackProvider>`
+ * consumes.
+ *
+ * Everything here is a pure function (no React, no `window`, no network): URL
+ * builders, PKCE (S256 over Web Crypto), the `/oauth2/token` request body,
+ * JWT decoding, expiry checks, redirect parsing, and session shaping. The React
+ * layer (`tools/auth/provider.tsx`) is a thin wrapper over these; the tests
+ * (`tools/test/auth.spec.ts`) drive them directly.
+ */
+
+/** Static configuration of a Cognito Hosted UI app client (public SPA client). */
+export interface CognitoAuthConfig {
+  /**
+   * The Hosted UI domain, without a scheme — either the Cognito prefix domain
+   * (`myapp.auth.us-east-1.amazoncognito.com`) or a custom domain
+   * (`auth.example.com`).
+   */
+  domain: string;
+  /** The app client id (a public SPA client, *no* client secret). */
+  clientId: string;
+  /** An allowed callback URL — where Cognito redirects back after sign-in. */
+  redirectUri: string;
+  /**
+   * An allowed sign-out URL — where Cognito redirects after sign-out. Defaults
+   * to `redirectUri`.
+   */
+  logoutUri?: string;
+  /** OAuth scopes to request. Defaults to `["openid", "email", "profile"]`. */
+  scopes?: string[];
+  /** AWS region — used only to derive the default issuer for reference. */
+  region?: string;
+  /** The Cognito user pool id — used only to derive the default issuer. */
+  userPoolId?: string;
+}
+
+/** The claims we read off a decoded Cognito ID/access token. */
+export interface CognitoClaims {
+  sub: string;
+  exp?: number;
+  iat?: number;
+  iss?: string;
+  aud?: string;
+  token_use?: string;
+  email?: string;
+  email_verified?: boolean;
+  "cognito:username"?: string;
+  "cognito:groups"?: string[];
+  [claim: string]: unknown;
+}
+
+/** The signed-in user, projected from the ID token's claims. */
+export interface CognitoUser {
+  /** The Cognito `sub` — the stable identity the framework stamps rows with. */
+  sub: string;
+  email?: string;
+  username?: string;
+  /** `cognito:groups` — the verified group claims (empty array if none). */
+  groups: string[];
+}
+
+/** A live session: the tokens plus the decoded user and its expiry. */
+export interface CognitoSession {
+  idToken: string;
+  accessToken: string;
+  refreshToken?: string;
+  /** Absolute expiry, epoch milliseconds. */
+  expiresAt: number;
+  user: CognitoUser;
+  claims: CognitoClaims;
+}
+
+/** The raw shape of a Cognito `/oauth2/token` JSON response. */
+export interface CognitoTokenResponse {
+  id_token: string;
+  access_token: string;
+  refresh_token?: string;
+  expires_in?: number;
+  token_type?: string;
+}
+
+/** What `parseRedirect` recovers from a callback URL's query string. */
+export interface RedirectParams {
+  code?: string;
+  state?: string;
+  error?: string;
+  errorDescription?: string;
+}
+
+const DEFAULT_SCOPES = ["openid", "email", "profile"];
+
+/** Strip any scheme/trailing slash a caller may have included in `domain`. */
+function normalizeDomain(domain: string): string {
+  return domain.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+}
+
+/** The Hosted UI origin, e.g. `https://myapp.auth.us-east-1.amazoncognito.com`. */
+export function hostedUiOrigin(config: CognitoAuthConfig): string {
+  return `https://${normalizeDomain(config.domain)}`;
+}
+
+/** The issuer a Cognito user pool signs tokens with (for server verification). */
+export function issuerUrl(config: CognitoAuthConfig): string | undefined {
+  if (!config.region || !config.userPoolId) return undefined;
+  return `https://cognito-idp.${config.region}.amazonaws.com/${config.userPoolId}`;
+}
+
+/** Build the Hosted UI `/oauth2/authorize` URL to redirect the browser to. */
+export function authorizeUrl(
+  config: CognitoAuthConfig,
+  params: { state: string; codeChallenge: string },
+): string {
+  const query = new URLSearchParams({
+    response_type: "code",
+    client_id: config.clientId,
+    redirect_uri: config.redirectUri,
+    scope: (config.scopes ?? DEFAULT_SCOPES).join(" "),
+    state: params.state,
+    code_challenge: params.codeChallenge,
+    code_challenge_method: "S256",
+  });
+  return `${hostedUiOrigin(config)}/oauth2/authorize?${query.toString()}`;
+}
+
+/** Build the Hosted UI `/logout` URL that clears the Cognito session cookie. */
+export function logoutUrl(config: CognitoAuthConfig): string {
+  const query = new URLSearchParams({
+    client_id: config.clientId,
+    logout_uri: config.logoutUri ?? config.redirectUri,
+  });
+  return `${hostedUiOrigin(config)}/logout?${query.toString()}`;
+}
+
+/** The token endpoint the authorization code is exchanged at. */
+export function tokenEndpoint(config: CognitoAuthConfig): string {
+  return `${hostedUiOrigin(config)}/oauth2/token`;
+}
+
+/**
+ * The `application/x-www-form-urlencoded` body for a `/oauth2/token` call —
+ * either exchanging an authorization `code` or a `refresh_token` grant.
+ */
+export function tokenRequestBody(
+  config: CognitoAuthConfig,
+  grant:
+    | { grantType: "authorization_code"; code: string; codeVerifier: string }
+    | { grantType: "refresh_token"; refreshToken: string },
+): string {
+  const body = new URLSearchParams({
+    client_id: config.clientId,
+  });
+  if (grant.grantType === "authorization_code") {
+    body.set("grant_type", "authorization_code");
+    body.set("code", grant.code);
+    body.set("redirect_uri", config.redirectUri);
+    body.set("code_verifier", grant.codeVerifier);
+  } else {
+    body.set("grant_type", "refresh_token");
+    body.set("refresh_token", grant.refreshToken);
+  }
+  return body.toString();
+}
+
+// -- base64url ---------------------------------------------------------------
+
+/** Encode raw bytes as base64url (no padding). Browser + Node safe. */
+export function base64UrlEncode(bytes: Uint8Array): string {
+  let base64: string;
+  if (typeof btoa === "function") {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+    base64 = btoa(binary);
+  } else {
+    base64 = Buffer.from(bytes).toString("base64");
+  }
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/** Decode a base64url string to bytes. */
+export function base64UrlDecodeToBytes(input: string): Uint8Array {
+  const base64 = input
+    .replace(/-/g, "+")
+    .replace(/_/g, "/")
+    .padEnd(Math.ceil(input.length / 4) * 4, "=");
+  if (typeof atob === "function") {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return bytes;
+  }
+  return new Uint8Array(Buffer.from(base64, "base64"));
+}
+
+/** Decode a base64url string to a UTF-8 string. */
+export function base64UrlDecode(input: string): string {
+  const bytes = base64UrlDecodeToBytes(input);
+  if (typeof TextDecoder !== "undefined") {
+    return new TextDecoder().decode(bytes);
+  }
+  return Buffer.from(bytes).toString("utf-8");
+}
+
+/** UTF-8 encode a string to bytes. */
+function utf8Bytes(input: string): Uint8Array {
+  if (typeof TextEncoder !== "undefined") return new TextEncoder().encode(input);
+  return new Uint8Array(Buffer.from(input, "utf-8"));
+}
+
+// -- PKCE --------------------------------------------------------------------
+
+function subtleCrypto(subtle?: SubtleCrypto): SubtleCrypto {
+  const s = subtle ?? (globalThis.crypto && globalThis.crypto.subtle);
+  if (!s) {
+    throw new Error(
+      "Web Crypto (crypto.subtle) is required for PKCE; pass a SubtleCrypto explicitly.",
+    );
+  }
+  return s;
+}
+
+/** A cryptographically random PKCE `code_verifier` (43–128 chars, base64url). */
+export function randomCodeVerifier(random?: Uint8Array): string {
+  let bytes = random;
+  if (!bytes) {
+    bytes = new Uint8Array(new ArrayBuffer(32));
+    if (globalThis.crypto?.getRandomValues) {
+      globalThis.crypto.getRandomValues(bytes as any);
+    } else {
+      throw new Error(
+        "crypto.getRandomValues is required to generate a code verifier.",
+      );
+    }
+  }
+  return base64UrlEncode(bytes);
+}
+
+/** The S256 `code_challenge` derived from a verifier (SHA-256 → base64url). */
+export async function codeChallengeFromVerifier(
+  verifier: string,
+  subtle?: SubtleCrypto,
+): Promise<string> {
+  const digest = await subtleCrypto(subtle).digest(
+    "SHA-256",
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    utf8Bytes(verifier) as any,
+  );
+  return base64UrlEncode(new Uint8Array(digest));
+}
+
+/** Generate a fresh PKCE `{ verifier, challenge }` pair. */
+export async function createPkcePair(
+  random?: Uint8Array,
+  subtle?: SubtleCrypto,
+): Promise<{ verifier: string; challenge: string }> {
+  const verifier = randomCodeVerifier(random);
+  const challenge = await codeChallengeFromVerifier(verifier, subtle);
+  return { verifier, challenge };
+}
+
+/** A random opaque `state` value to correlate the redirect (CSRF guard). */
+export function randomState(random?: Uint8Array): string {
+  return randomCodeVerifier(random ?? undefined);
+}
+
+// -- JWT ---------------------------------------------------------------------
+
+/**
+ * Decode a JWT's payload **without verifying its signature** — the client only
+ * reads claims for UX; the server is the sole authority that *verifies* the
+ * token (RS256 against the pinned JWKS). Throws on a malformed token.
+ */
+export function decodeJwt<T = CognitoClaims>(token: string): T {
+  const parts = token.split(".");
+  if (parts.length < 2) throw new Error("Malformed JWT: expected 3 segments.");
+  try {
+    return JSON.parse(base64UrlDecode(parts[1])) as T;
+  } catch (error) {
+    throw new Error(`Malformed JWT payload: ${(error as Error).message}`);
+  }
+}
+
+/** Project a decoded ID token's claims into the app-facing `CognitoUser`. */
+export function userFromClaims(claims: CognitoClaims): CognitoUser {
+  const groups = claims["cognito:groups"];
+  return {
+    sub: claims.sub,
+    email: claims.email,
+    username: claims["cognito:username"] ?? claims.email ?? claims.sub,
+    groups: Array.isArray(groups) ? groups : [],
+  };
+}
+
+/** Build a `CognitoSession` from a token response, decoding the ID token. */
+export function sessionFromTokens(
+  tokens: CognitoTokenResponse,
+  now: number = Date.now(),
+): CognitoSession {
+  const claims = decodeJwt<CognitoClaims>(tokens.id_token);
+  // Prefer the token's own `exp`; fall back to `expires_in` from the response.
+  const expiresAt = claims.exp
+    ? claims.exp * 1000
+    : now + (tokens.expires_in ?? 3600) * 1000;
+  return {
+    idToken: tokens.id_token,
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token,
+    expiresAt,
+    user: userFromClaims(claims),
+    claims,
+  };
+}
+
+/**
+ * Whether a session is still usable — present and not within `skewMs` of its
+ * expiry (so callers refresh a little early rather than mid-request).
+ */
+export function isSessionValid(
+  session: CognitoSession | null | undefined,
+  now: number = Date.now(),
+  skewMs = 30_000,
+): boolean {
+  return !!session && session.expiresAt - skewMs > now;
+}
+
+// -- Redirect parsing --------------------------------------------------------
+
+/**
+ * Parse the callback URL's query string into the OAuth params. Accepts a full
+ * URL, a bare search string (`?code=…`), or a `URLSearchParams`.
+ */
+export function parseRedirect(
+  input: string | URLSearchParams,
+): RedirectParams {
+  let params: URLSearchParams;
+  if (input instanceof URLSearchParams) {
+    params = input;
+  } else {
+    const q = input.includes("?") ? input.slice(input.indexOf("?") + 1) : input;
+    params = new URLSearchParams(q);
+  }
+  return {
+    code: params.get("code") ?? undefined,
+    state: params.get("state") ?? undefined,
+    error: params.get("error") ?? undefined,
+    errorDescription: params.get("error_description") ?? undefined,
+  };
+}
+
+// -- Local (server-less) sessions -------------------------------------------
+
+/**
+ * Base64url-encode a JSON value — the building block of the unsigned tokens the
+ * local session mode mints.
+ */
+function encodeSegment(value: unknown): string {
+  return base64UrlEncode(utf8Bytes(JSON.stringify(value)));
+}
+
+/**
+ * Mint a **local, unsigned** session for server-less development.
+ * `<RAStackProvider mode="local">` runs the whole API in the browser with no
+ * identity provider to redirect to, so `mode: "local"` on the auth provider
+ * grants a simulated Cognito session on sign-in: a real-shaped
+ * (header.payload.signature) JWT carrying `sub` / `cognito:groups`, so
+ * `decodeJwt`, owner stamping, and the write-gating UI all behave exactly as
+ * they would against a real pool — the server-less dev shim.
+ * **Never trust these tokens on a server** — they carry a literal `"local"`
+ * signature; swap `mode` to `"hosted-ui"` for a deployed, Cognito-protected
+ * backend.
+ */
+export function localSession(
+  user: {
+    sub?: string;
+    email?: string;
+    username?: string;
+    groups?: string[];
+  } = {},
+  now: number = Date.now(),
+  ttlMs = 3600_000,
+): CognitoSession {
+  const sub = user.sub ?? "local-dev";
+  const exp = Math.floor((now + ttlMs) / 1000);
+  const claims: CognitoClaims = {
+    sub,
+    email: user.email,
+    email_verified: true,
+    "cognito:username": user.username ?? user.email ?? sub,
+    "cognito:groups": user.groups ?? [],
+    token_use: "id",
+    iss: "rastack:local",
+    iat: Math.floor(now / 1000),
+    exp,
+  };
+  const header = { alg: "none", typ: "JWT", kid: "rastack-local" };
+  const token = `${encodeSegment(header)}.${encodeSegment(claims)}.local`;
+  return {
+    idToken: token,
+    accessToken: token,
+    expiresAt: exp * 1000,
+    user: userFromClaims(claims),
+    claims,
+  };
+}

package/src/auth/index.ts

@@ -0,0 +1,2 @@
+/** `rastack/auth` pure core — Cognito Hosted UI / PKCE, JWT, and session logic. */
+export * from "./cognito";

package/src/entity-generation/get-method.ts

@@ -36,7 +36,7 @@ export function generateGetAPIMethod(
     export function use${operationIdUpper}(
   options?: ListQueryOptions<${paramNames}, ${responseBody}>
 ) {
-  const { isAuthenticated } = useAuth0();
+  const { isReady } = useCognitoAuth();
   const pathParameters: (keyof ${paramNames})[] = [${pathParameters.map((item) => `'${item}'`).join(", ")}]
   ${pathParameterString.join("\n")}
 
@@ -44,7 +44,7 @@ export function generateGetAPIMethod(
     ${method}Url: \`${url}\`,
     queryKey: ${modelCamel}QueriesKeys.${operationId},
     pathParameters,
-    isAuthenticated,
+    isAuthenticated: isReady,
     options,
   });
 }`,
@@ -59,7 +59,7 @@ export function generateGetAPIMethod(
 export function use${operationIdUpper}(
   options?: GetQueryOptions<${paramNames}>
 ) {
-  const { isAuthenticated } = useAuth0();
+  const { isReady } = useCognitoAuth();
   const pathParameters: string[] = [${pathParameters.map((item) => `'${item}'`).join(", ")}]
   ${pathParameterString.join("\n")}
   const requiredParams: string[] = [${requiredParameters.map((item) => `'${item}'`).join(", ")}]
@@ -70,7 +70,7 @@ export function use${operationIdUpper}(
     pathParameters,
     //@ts-ignore
     requiredParams,
-    isAuthenticated,
+    isAuthenticated: isReady,
     options,
   });
 }`,

package/src/entity-generation/imports.ts

@@ -73,7 +73,7 @@ export function generateImportStatements(
 
   let importData =
     "import { useForm, FormProps, FormUpdate, useUpdateQuery } from 'rastack/hooks';\n";
-  importData = importData + 'import { useAuth0 } from "@auth0/auth0-react";\n';
+  importData = importData + 'import { useCognitoAuth } from "rastack/auth";\n';
   if (queryImports) {
     importData += `import { ${queryImports} } from 'rastack/hooks';\n`;
   }