h4ckath0n 0.1.0

package/templates/fullstack/web/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "{{PROJECT_NAME}}-web",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "react-router": "^7.12.0",
+    "@tanstack/react-query": "^5.80.7",
+    "lucide-react": "^0.563.0",
+    "jose": "^6.0.11",
+    "idb-keyval": "^6.2.1"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
+    "@vitejs/plugin-react": "^4.5.2",
+    "typescript": "~5.9.0",
+    "vite": "^6.3.5",
+    "@tailwindcss/vite": "^4.1.10",
+    "tailwindcss": "^4.1.10",
+    "eslint": "^9.28.0",
+    "@eslint/js": "^9.28.0",
+    "typescript-eslint": "^8.33.1",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "globals": "^16.2.0",
+    "vitest": "^3.2.4",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "jsdom": "^26.1.0"
+  }
+}

package/templates/fullstack/web/public/vite.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32" fill="none">
+  <rect width="32" height="32" rx="6" fill="#6366f1"/>
+  <text x="16" y="22" text-anchor="middle" font-size="18" font-weight="bold" fill="white" font-family="system-ui">h4</text>
+</svg>

package/templates/fullstack/web/src/App.tsx

@@ -0,0 +1,45 @@
+import { Routes, Route } from "react-router";
+import { Layout } from "./components/Layout";
+import { ProtectedRoute } from "./components/ProtectedRoute";
+import { Landing } from "./pages/Landing";
+import { Register } from "./pages/Register";
+import { Login } from "./pages/Login";
+import { Dashboard } from "./pages/Dashboard";
+import { Settings } from "./pages/Settings";
+import { Admin } from "./pages/Admin";
+
+export function App() {
+  return (
+    <Routes>
+      <Route element={<Layout />}>
+        <Route path="/" element={<Landing />} />
+        <Route path="/register" element={<Register />} />
+        <Route path="/login" element={<Login />} />
+        <Route
+          path="/dashboard"
+          element={
+            <ProtectedRoute>
+              <Dashboard />
+            </ProtectedRoute>
+          }
+        />
+        <Route
+          path="/settings"
+          element={
+            <ProtectedRoute>
+              <Settings />
+            </ProtectedRoute>
+          }
+        />
+        <Route
+          path="/admin"
+          element={
+            <ProtectedRoute requiredRole="admin">
+              <Admin />
+            </ProtectedRoute>
+          }
+        />
+      </Route>
+    </Routes>
+  );
+}

package/templates/fullstack/web/src/auth/AuthContext.tsx

@@ -0,0 +1,238 @@
+import {
+  createContext,
+  useContext,
+  useState,
+  useEffect,
+  useCallback,
+  type ReactNode,
+} from "react";
+import {
+  ensureDeviceKeyMaterial,
+  getDeviceIdentity,
+  setDeviceIdentity,
+  clearDeviceKeyMaterial,
+} from "./deviceKey";
+import { clearCachedToken } from "./token";
+import { publicFetch } from "./api";
+import {
+  toCreateOptions,
+  toGetOptions,
+  serializeCreateResponse,
+  serializeGetResponse,
+} from "./webauthn";
+import { useNavigate } from "react-router";
+
+interface User {
+  id: string;
+  role: string;
+  scopes: string[];
+}
+
+interface AuthState {
+  isAuthenticated: boolean;
+  isLoading: boolean;
+  userId: string | null;
+  deviceId: string | null;
+  role: string | null;
+  displayName: string | null;
+  /** Backward-compatible user object for existing components */
+  user: User | null;
+  /** Backward-compatible loading alias */
+  loading: boolean;
+}
+
+interface AuthContextType extends AuthState {
+  register: (displayName: string) => Promise<void>;
+  login: () => Promise<void>;
+  logout: () => Promise<void>;
+}
+
+const AuthContext = createContext<AuthContextType | null>(null);
+
+export function useAuth(): AuthContextType {
+  const ctx = useContext(AuthContext);
+  if (!ctx) throw new Error("useAuth must be used within AuthProvider");
+  return ctx;
+}
+
+interface FinishResponse {
+  user_id: string;
+  device_id: string;
+  role?: string;
+  display_name?: string;
+}
+
+function buildState(
+  partial: Omit<AuthState, "user" | "loading">,
+): AuthState {
+  const user = partial.isAuthenticated && partial.userId
+    ? { id: partial.userId, role: partial.role ?? "user", scopes: [] }
+    : null;
+  return { ...partial, user, loading: partial.isLoading };
+}
+
+export function AuthProvider({ children }: { children: ReactNode }) {
+  const [state, setState] = useState<AuthState>(
+    buildState({
+      isAuthenticated: false,
+      isLoading: true,
+      userId: null,
+      deviceId: null,
+      role: null,
+      displayName: null,
+    }),
+  );
+  const navigate = useNavigate();
+
+  // Check existing device identity on mount
+  useEffect(() => {
+    (async () => {
+      try {
+        const identity = await getDeviceIdentity();
+        if (identity) {
+          setState(
+            buildState({
+              isAuthenticated: true,
+              isLoading: false,
+              userId: identity.userId,
+              deviceId: identity.deviceId,
+              role: null,
+              displayName: null,
+            }),
+          );
+        } else {
+          setState((s) => buildState({ ...s, isLoading: false }));
+        }
+      } catch {
+        setState((s) => buildState({ ...s, isLoading: false }));
+      }
+    })();
+  }, []);
+
+  const register = useCallback(
+    async (displayName: string) => {
+      const keyMaterial = await ensureDeviceKeyMaterial();
+
+      const startRes = await publicFetch<{
+        options: Record<string, unknown>;
+        flow_id: string;
+      }>("/auth/passkey/register/start", {
+        method: "POST",
+        body: JSON.stringify({ display_name: displayName }),
+      });
+      if (!startRes.ok) throw new Error("Registration start failed");
+
+      const createOptions = toCreateOptions(
+        startRes.data.options as unknown as Parameters<typeof toCreateOptions>[0],
+      );
+      const credential = (await navigator.credentials.create(
+        createOptions,
+      )) as PublicKeyCredential | null;
+      if (!credential) throw new Error("Credential creation cancelled");
+
+      const finishRes = await publicFetch<FinishResponse>(
+        "/auth/passkey/register/finish",
+        {
+          method: "POST",
+          body: JSON.stringify({
+            flow_id: startRes.data.flow_id,
+            credential: serializeCreateResponse(credential),
+            device_public_key_jwk: keyMaterial.publicJwk,
+            device_label: navigator.userAgent.slice(0, 64),
+          }),
+        },
+      );
+      if (!finishRes.ok) throw new Error("Registration finish failed");
+
+      await setDeviceIdentity(
+        finishRes.data.device_id,
+        finishRes.data.user_id,
+      );
+      setState(
+        buildState({
+          isAuthenticated: true,
+          isLoading: false,
+          userId: finishRes.data.user_id,
+          deviceId: finishRes.data.device_id,
+          role: finishRes.data.role ?? "user",
+          displayName: finishRes.data.display_name ?? displayName,
+        }),
+      );
+      navigate("/dashboard");
+    },
+    [navigate],
+  );
+
+  const login = useCallback(async () => {
+    const keyMaterial = await ensureDeviceKeyMaterial();
+
+    const startRes = await publicFetch<{
+      options: Record<string, unknown>;
+      flow_id: string;
+    }>("/auth/passkey/login/start", {
+      method: "POST",
+      body: JSON.stringify({}),
+    });
+    if (!startRes.ok) throw new Error("Login start failed");
+
+    const getOptions = toGetOptions(
+      startRes.data.options as unknown as Parameters<typeof toGetOptions>[0],
+    );
+    const credential = (await navigator.credentials.get(
+      getOptions,
+    )) as PublicKeyCredential | null;
+    if (!credential) throw new Error("Login cancelled");
+
+    const finishRes = await publicFetch<FinishResponse>(
+      "/auth/passkey/login/finish",
+      {
+        method: "POST",
+        body: JSON.stringify({
+          flow_id: startRes.data.flow_id,
+          credential: serializeGetResponse(credential),
+          device_public_key_jwk: keyMaterial.publicJwk,
+          device_label: navigator.userAgent.slice(0, 64),
+        }),
+      },
+    );
+    if (!finishRes.ok) throw new Error("Login finish failed");
+
+    await setDeviceIdentity(
+      finishRes.data.device_id,
+      finishRes.data.user_id,
+    );
+    setState(
+      buildState({
+        isAuthenticated: true,
+        isLoading: false,
+        userId: finishRes.data.user_id,
+        deviceId: finishRes.data.device_id,
+        role: finishRes.data.role ?? "user",
+        displayName: finishRes.data.display_name ?? null,
+      }),
+    );
+    navigate("/dashboard");
+  }, [navigate]);
+
+  const logout = useCallback(async () => {
+    clearCachedToken();
+    await clearDeviceKeyMaterial();
+    setState(
+      buildState({
+        isAuthenticated: false,
+        isLoading: false,
+        userId: null,
+        deviceId: null,
+        role: null,
+        displayName: null,
+      }),
+    );
+    navigate("/");
+  }, [navigate]);
+
+  return (
+    <AuthContext.Provider value={{ ...state, register, login, logout }}>
+      {children}
+    </AuthContext.Provider>
+  );
+}

package/templates/fullstack/web/src/auth/__tests__/token.test.ts

@@ -0,0 +1,22 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { isTokenValid, clearCachedToken, shouldRenewToken } from "../token";
+
+describe("token management", () => {
+  beforeEach(() => {
+    clearCachedToken();
+  });
+
+  it("isTokenValid returns false when no token is cached", () => {
+    expect(isTokenValid()).toBe(false);
+  });
+
+  it("shouldRenewToken returns true when no token is cached", () => {
+    expect(shouldRenewToken()).toBe(true);
+  });
+
+  it("clearCachedToken resets state", () => {
+    clearCachedToken();
+    expect(isTokenValid()).toBe(false);
+    expect(shouldRenewToken()).toBe(true);
+  });
+});

package/templates/fullstack/web/src/auth/__tests__/webauthn.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect } from "vitest";
+import { base64urlEncode, base64urlDecode } from "../webauthn";
+
+describe("base64url helpers", () => {
+  it("encodes an ArrayBuffer to base64url string", () => {
+    const buffer = new Uint8Array([72, 101, 108, 108, 111]).buffer;
+    const encoded = base64urlEncode(buffer);
+    // "Hello" in base64 is "SGVsbG8=", base64url removes padding
+    expect(encoded).toBe("SGVsbG8");
+  });
+
+  it("decodes a base64url string to ArrayBuffer", () => {
+    const decoded = base64urlDecode("SGVsbG8");
+    const bytes = new Uint8Array(decoded);
+    expect(Array.from(bytes)).toEqual([72, 101, 108, 108, 111]);
+  });
+
+  it("round-trips correctly", () => {
+    const original = new Uint8Array([0, 1, 2, 255, 254, 253, 128, 127]);
+    const encoded = base64urlEncode(original.buffer);
+    const decoded = new Uint8Array(base64urlDecode(encoded));
+    expect(Array.from(decoded)).toEqual(Array.from(original));
+  });
+
+  it("handles empty buffer", () => {
+    const empty = new Uint8Array(0).buffer;
+    const encoded = base64urlEncode(empty);
+    expect(encoded).toBe("");
+    const decoded = base64urlDecode("");
+    expect(new Uint8Array(decoded).length).toBe(0);
+  });
+
+  it("handles URL-unsafe characters correctly", () => {
+    // bytes that produce + and / in standard base64
+    const buffer = new Uint8Array([251, 255, 254]).buffer;
+    const encoded = base64urlEncode(buffer);
+    expect(encoded).not.toContain("+");
+    expect(encoded).not.toContain("/");
+    expect(encoded).not.toContain("=");
+    // Round-trip
+    const decoded = new Uint8Array(base64urlDecode(encoded));
+    expect(Array.from(decoded)).toEqual([251, 255, 254]);
+  });
+});

package/templates/fullstack/web/src/auth/api.ts

@@ -0,0 +1,63 @@
+import { getOrMintToken, clearCachedToken } from "./token";
+import { getDeviceIdentity } from "./deviceKey";
+
+const API_BASE = import.meta.env.VITE_API_BASE_URL || "/api";
+
+export class AuthError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AuthError";
+  }
+}
+
+export interface ApiResponse<T = unknown> {
+  ok: boolean;
+  status: number;
+  data: T;
+}
+
+export async function apiFetch<T = unknown>(
+  path: string,
+  options: RequestInit = {},
+  auth = true,
+): Promise<ApiResponse<T>> {
+  const url = `${API_BASE}${path}`;
+  const headers = new Headers(options.headers);
+
+  if (!headers.has("Content-Type") && options.body) {
+    headers.set("Content-Type", "application/json");
+  }
+
+  if (auth) {
+    const identity = await getDeviceIdentity();
+    if (!identity) {
+      throw new AuthError("Not authenticated");
+    }
+    const token = await getOrMintToken("http");
+    headers.set("Authorization", `Bearer ${token}`);
+  }
+
+  const response = await fetch(url, { ...options, headers });
+
+  if (response.status === 401) {
+    clearCachedToken();
+    throw new AuthError("Unauthorized");
+  }
+
+  let data: T;
+  try {
+    data = (await response.json()) as T;
+  } catch {
+    // Non-JSON responses (e.g. 204 No Content) return null
+    data = null as T;
+  }
+  return { ok: response.ok, status: response.status, data };
+}
+
+// Unauthenticated fetch for login/register endpoints
+export async function publicFetch<T = unknown>(
+  path: string,
+  options: RequestInit = {},
+): Promise<ApiResponse<T>> {
+  return apiFetch<T>(path, options, false);
+}

package/templates/fullstack/web/src/auth/deviceKey.ts

@@ -0,0 +1,71 @@
+import { get, set, del } from "idb-keyval";
+
+const DB_PRIVATE_KEY = "h4ckath0n_device_private_key";
+const DB_PUBLIC_JWK = "h4ckath0n_device_public_jwk";
+const DB_DEVICE_ID = "h4ckath0n_device_id";
+const DB_USER_ID = "h4ckath0n_user_id";
+
+export interface DeviceKeyMaterial {
+  privateKey: CryptoKey;
+  publicJwk: JsonWebKey;
+}
+
+export interface DeviceIdentity {
+  deviceId: string;
+  userId: string;
+}
+
+export async function ensureDeviceKeyMaterial(): Promise<DeviceKeyMaterial> {
+  const existing = await loadDeviceKeyMaterial();
+  if (existing) return existing;
+  return generateDeviceKeyMaterial();
+}
+
+async function loadDeviceKeyMaterial(): Promise<DeviceKeyMaterial | null> {
+  const privateKey = await get<CryptoKey>(DB_PRIVATE_KEY);
+  const publicJwk = await get<JsonWebKey>(DB_PUBLIC_JWK);
+  if (privateKey && publicJwk) return { privateKey, publicJwk };
+  return null;
+}
+
+async function generateDeviceKeyMaterial(): Promise<DeviceKeyMaterial> {
+  const keyPair = await crypto.subtle.generateKey(
+    { name: "ECDSA", namedCurve: "P-256" },
+    false, // non-extractable private key
+    ["sign", "verify"],
+  );
+  const publicJwk = await crypto.subtle.exportKey("jwk", keyPair.publicKey);
+  await set(DB_PRIVATE_KEY, keyPair.privateKey);
+  await set(DB_PUBLIC_JWK, publicJwk);
+  return { privateKey: keyPair.privateKey, publicJwk };
+}
+
+export async function getPrivateKey(): Promise<CryptoKey | null> {
+  return (await get<CryptoKey>(DB_PRIVATE_KEY)) ?? null;
+}
+
+export async function getPublicJwk(): Promise<JsonWebKey | null> {
+  return (await get<JsonWebKey>(DB_PUBLIC_JWK)) ?? null;
+}
+
+export async function getDeviceIdentity(): Promise<DeviceIdentity | null> {
+  const deviceId = await get<string>(DB_DEVICE_ID);
+  const userId = await get<string>(DB_USER_ID);
+  if (deviceId && userId) return { deviceId, userId };
+  return null;
+}
+
+export async function setDeviceIdentity(
+  deviceId: string,
+  userId: string,
+): Promise<void> {
+  await set(DB_DEVICE_ID, deviceId);
+  await set(DB_USER_ID, userId);
+}
+
+export async function clearDeviceKeyMaterial(): Promise<void> {
+  await del(DB_PRIVATE_KEY);
+  await del(DB_PUBLIC_JWK);
+  await del(DB_DEVICE_ID);
+  await del(DB_USER_ID);
+}

package/templates/fullstack/web/src/auth/index.ts

@@ -0,0 +1,26 @@
+export { useAuth, AuthProvider } from "./AuthContext";
+export {
+  ensureDeviceKeyMaterial,
+  getDeviceIdentity,
+  setDeviceIdentity,
+  clearDeviceKeyMaterial,
+  getPublicJwk,
+  getPrivateKey,
+} from "./deviceKey";
+export {
+  getOrMintToken,
+  mintToken,
+  clearCachedToken,
+  isTokenValid,
+  shouldRenewToken,
+} from "./token";
+export { apiFetch, publicFetch, AuthError, type ApiResponse } from "./api";
+export {
+  base64urlEncode,
+  base64urlDecode,
+  toCreateOptions,
+  toGetOptions,
+  serializeCreateResponse,
+  serializeGetResponse,
+} from "./webauthn";
+export { createAuthWebSocket, sendReauth } from "./ws";

package/templates/fullstack/web/src/auth/token.ts

@@ -0,0 +1,59 @@
+import { SignJWT } from "jose";
+import { getPrivateKey, getDeviceIdentity } from "./deviceKey";
+
+let cachedToken: string | null = null;
+let cachedExp: number = 0;
+
+const TOKEN_LIFETIME = 900; // 15 minutes in seconds
+const RENEWAL_BUFFER = 60; // renew 60s before expiry
+
+export function isTokenValid(): boolean {
+  if (!cachedToken) return false;
+  const now = Math.floor(Date.now() / 1000);
+  return now < cachedExp - RENEWAL_BUFFER;
+}
+
+export async function getOrMintToken(aud?: string): Promise<string> {
+  if (isTokenValid() && cachedToken) return cachedToken;
+  return mintToken(aud);
+}
+
+export async function mintToken(aud?: string): Promise<string> {
+  const privateKey = await getPrivateKey();
+  const identity = await getDeviceIdentity();
+  if (!privateKey || !identity) {
+    throw new Error("No device key material or identity found");
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  const exp = now + TOKEN_LIFETIME;
+
+  let builder = new SignJWT({ sub: identity.userId })
+    .setProtectedHeader({
+      alg: "ES256",
+      typ: "JWT",
+      kid: identity.deviceId,
+    })
+    .setIssuedAt(now)
+    .setExpirationTime(exp);
+
+  if (aud) {
+    builder = builder.setAudience(aud);
+  }
+
+  const token = await builder.sign(privateKey);
+  cachedToken = token;
+  cachedExp = exp;
+  return token;
+}
+
+export function clearCachedToken(): void {
+  cachedToken = null;
+  cachedExp = 0;
+}
+
+export function shouldRenewToken(): boolean {
+  if (!cachedToken) return true;
+  const now = Math.floor(Date.now() / 1000);
+  return now >= cachedExp - RENEWAL_BUFFER;
+}