React login-pkce sample + extraction tooling

.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# All files require review from the CIAM team
+* @SecureAuthCorp/team-eng-ciam-ui-write

.github/dependabot.yml

@@ -0,0 +1,28 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/samples/react/login-pkce"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "deps"
+
+  - package-ecosystem: "npm"
+    directory: "/scripts"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 3
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "deps"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"

.github/workflows/extract.yml

@@ -0,0 +1,72 @@
+name: Extract Snippets
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    paths:
+      - "samples/**"
+      - "scripts/**"
+      - "placeholder-map.yaml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  extract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Install dependencies
+        run: yarn install --immutable
+
+      - name: Aggregate manifests
+        working-directory: scripts
+        run: yarn aggregate
+
+      - name: Extract snippets
+        working-directory: scripts
+        run: yarn extract
+
+      - name: Validate structure
+        working-directory: scripts
+        run: yarn validate
+
+      - name: Verify no drift (PR only)
+        if: github.event_name == 'pull_request'
+        run: |
+          git diff --exit-code snippets.json snippet-manifest.yaml || \
+            (echo "::error::Extracted artifacts are out of date. Run 'cd scripts && yarn all' and commit the results." && exit 1)
+
+      - name: Check for changes
+        id: diff
+        if: github.event_name == 'push'
+        run: |
+          git diff --quiet snippets.json snippet-manifest.yaml || echo "changed=true" >> "$GITHUB_OUTPUT"
+
+      - name: Commit updated artifacts
+        if: github.event_name == 'push' && steps.diff.outputs.changed == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add snippets.json snippet-manifest.yaml
+          git commit -m "chore: update extracted snippets and manifest"
+          git push
+
+      # - name: Notify ciam-core of snippet changes
+      #   if: steps.diff.outputs.changed == 'true'
+      #   run: |
+      #     gh api repos/SecureAuthCorp/ciam-core/dispatches \
+      #       -f event_type=quickstart-snippets-updated \
+      #       -f 'client_payload[sha]=${{ github.sha }}'
+      #   env:
+      #     GH_TOKEN: ${{ secrets.CIAM_CORE_DISPATCH_TOKEN }}

.github/workflows/test-js.yml

@@ -0,0 +1,58 @@
+name: Test JS Frameworks
+
+on:
+  push:
+    paths:
+      - "samples/react/**"
+  pull_request:
+    paths:
+      - "samples/react/**"
+  schedule:
+    - cron: "0 8 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  find-projects:
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.find.outputs.matrix }}
+    steps:
+      - uses: actions/checkout@v4
+      - id: find
+        run: |
+          DIRS=$(find samples -name "package.json" -not -path "*/node_modules/*" -exec dirname {} \; 2>/dev/null | sort | jq -R -s -c 'split("\n") | map(select(. != ""))')
+          echo "matrix=$DIRS" >> "$GITHUB_OUTPUT"
+
+  test:
+    needs: find-projects
+    if: ${{ needs.find-projects.outputs.matrix != '[]' }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        project: ${{ fromJson(needs.find-projects.outputs.matrix) }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - name: Enable Corepack
+        run: corepack enable
+      - name: Install dependencies
+        run: yarn install --immutable
+      - name: Check formatting
+        working-directory: ${{ matrix.project }}
+        run: |
+          if grep -q '"format:check"' package.json; then
+            yarn format:check
+          fi
+      - name: Build
+        working-directory: ${{ matrix.project }}
+        run: yarn build
+      - name: Test
+        working-directory: ${{ matrix.project }}
+        run: yarn test
+        if: ${{ hashFiles(format('{0}/vitest.config.ts', matrix.project)) != '' }}

.yarnrc.yml

@@ -0,0 +1,5 @@
+nodeLinker: node-modules
+
+npmRegistryServer: "https://registry.npmjs.org"
+
+yarnPath: .yarn/releases/yarn-4.13.0.cjs

README.md

@@ -1,4 +1,24 @@
-# ciam-quickstart-samples
+# CIAM Quickstart Samples
 
+Framework-specific sample apps demonstrating SecureAuth integration. Code is extracted from these samples and displayed in the SecureAuth admin dashboard's Quickstart tab.
 
-Repository for framework-specific integration sample apps
+## Structure
+
+```
+samples/          # One folder per framework
+  react/          # React sample apps
+    login-pkce/   # Login with Auth Code + PKCE
+scripts/          # Extraction and validation tools
+```
+
+## Adding a new sample
+
+1. Create `samples/<framework>/<flow>/` with a minimal working app
+2. Add `@snippet:stepN:start/end` tags and `@description` comments in source files
+3. Add a `manifest.yaml` in `samples/<framework>/`
+4. Run `cd scripts && yarn all` to validate
+5. Open a PR — CI will test the app and validate extraction
+
+## Contributing
+
+This repo is maintained by the SecureAuth CIAM team. External contributions are welcome via pull request — all PRs require team review.

package.json

@@ -0,0 +1,8 @@
+{
+  "private": true,
+  "packageManager": "yarn@4.13.0",
+  "workspaces": [
+    "samples/react/*",
+    "scripts"
+  ]
+}

placeholder-map.yaml

@@ -0,0 +1,29 @@
+# Maps env var patterns to placeholder tokens per language.
+# The extraction script uses these to replace real env var references
+# with generic {{PLACEHOLDER}} tokens in extracted snippets.
+
+js:
+  - pattern: "import.meta.env.VITE_ISSUER_URL"
+    placeholder: "{{ISSUER_URL}}"
+  - pattern: "import.meta.env.VITE_CLIENT_ID"
+    placeholder: "{{CLIENT_ID}}"
+  - pattern: "import.meta.env.VITE_REDIRECT_URI"
+    placeholder: "{{REDIRECT_URI}}"
+  - pattern: "import.meta.env.VITE_SCOPES"
+    placeholder: "{{SCOPES}}"
+  - pattern: "import.meta.env.VITE_POST_LOGOUT_URI"
+    placeholder: "{{POST_LOGOUT_URI}}"
+  - pattern: "process.env.REACT_APP_ISSUER_URL"
+    placeholder: "{{ISSUER_URL}}"
+  - pattern: "process.env.REACT_APP_CLIENT_ID"
+    placeholder: "{{CLIENT_ID}}"
+  - pattern: "process.env.REACT_APP_REDIRECT_URI"
+    placeholder: "{{REDIRECT_URI}}"
+  - pattern: "process.env.SA_ISSUER_URL"
+    placeholder: "{{ISSUER_URL}}"
+  - pattern: "process.env.SA_CLIENT_ID"
+    placeholder: "{{CLIENT_ID}}"
+  - pattern: "process.env.SA_CLIENT_SECRET"
+    placeholder: "{{CLIENT_SECRET}}"
+  - pattern: "process.env.SA_REDIRECT_URI"
+    placeholder: "{{REDIRECT_URI}}"

samples/react/login-pkce/.env.example

@@ -0,0 +1,4 @@
+VITE_ISSUER_URL=https://your-tenant.us.secureauth.com/your-workspace
+VITE_CLIENT_ID=your-client-id
+VITE_REDIRECT_URI=http://localhost:3000/callback
+VITE_SCOPES=openid profile email

samples/react/login-pkce/README.md

@@ -0,0 +1,17 @@
+# React SPA — Login with PKCE
+
+Minimal React app demonstrating OIDC login using Authorization Code + PKCE via `react-oidc-context`.
+
+## Setup
+
+1. Copy `.env.example` to `.env` and fill in your SecureAuth values
+2. `yarn install`
+3. `yarn dev`
+4. Open http://localhost:3000
+
+## What this demonstrates
+
+- OIDC configuration with PKCE (no client secret)
+- Login redirect to SecureAuth
+- Displaying the authenticated user's name
+- Logout with redirect

samples/react/login-pkce/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>SecureAuth React PKCE Login</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/index.tsx"></script>
+  </body>
+</html>

samples/react/login-pkce/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@ciam-quickstart/react-login-pkce",
+  "private": true,
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "dependencies": {
+    "oidc-client-ts": "^3.2.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "react-oidc-context": "^3.2.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "@vitejs/plugin-react": "^4.5.0",
+    "happy-dom": "^20.8.9",
+    "prettier": "^3.8.1",
+    "typescript": "^5.8.0",
+    "vite": "^6.3.0",
+    "vitest": "^4.1.3"
+  }
+}

samples/react/login-pkce/src/App.test.tsx

@@ -0,0 +1,60 @@
+import { render, screen } from "@testing-library/react";
+import { expect, test, vi } from "vitest";
+
+const mockUseAuth = vi.fn();
+
+vi.mock("react-oidc-context", () => ({
+  AuthProvider: ({ children }: { children: React.ReactNode }) => (
+    <>{children}</>
+  ),
+  useAuth: () => mockUseAuth(),
+}));
+
+import App from "./App";
+
+test("renders sign in button when not authenticated", () => {
+  mockUseAuth.mockReturnValue({
+    isLoading: false,
+    isAuthenticated: false,
+    error: null,
+    signinRedirect: vi.fn(),
+  });
+  render(<App />);
+  expect(screen.getByRole("heading")).toHaveTextContent(
+    "SecureAuth React PKCE Demo",
+  );
+  expect(screen.getByRole("button", { name: "Sign in" })).toBeDefined();
+});
+
+test("renders loading state", () => {
+  mockUseAuth.mockReturnValue({
+    isLoading: true,
+    isAuthenticated: false,
+    error: null,
+  });
+  render(<App />);
+  expect(screen.getByText("Loading...")).toBeDefined();
+});
+
+test("renders error state", () => {
+  mockUseAuth.mockReturnValue({
+    isLoading: false,
+    isAuthenticated: false,
+    error: { message: "Something went wrong" },
+  });
+  render(<App />);
+  expect(screen.getByText("Error: Something went wrong")).toBeDefined();
+});
+
+test("renders welcome message when authenticated", () => {
+  mockUseAuth.mockReturnValue({
+    isLoading: false,
+    isAuthenticated: true,
+    error: null,
+    user: { profile: { name: "Test User" } },
+    removeUser: vi.fn(),
+  });
+  render(<App />);
+  expect(screen.getByText("Welcome, Test User")).toBeDefined();
+  expect(screen.getByRole("button", { name: "Sign out" })).toBeDefined();
+});