Skip to content

cogni-dao/cogni / .claude/skills/operator-app-auth-routing

operator-app-auth-routing

Verified

Use this skill when changing operator app auth routing, Next.js public vs app route groups, `proxy.ts` route protection, auth-aware public chrome, `AccountSlot`, NextAuth session identity, wallet Connect button state, `/api/v1` auth rules, or route matcher tests. Trigger on requests involving `/nodes`, `/dashboard`, `/knowledge`, public-but-auth-aware pages, stale Connect state after login, or proxy matcher drift.

Operator App Auth Routing

Keep page placement, chrome state, and auth enforcement separate. proxy.ts is the routing contract; route groups and UI chrome should not become alternate auth systems.

Route Groups

  • Public pages live under nodes/operator/app/src/app/(public)/....
  • Authenticated app pages live under nodes/operator/app/src/app/(app)/....
  • A public route may still be auth-aware. Example: /nodes can stay public while showing session-aware account chrome.
  • Moving a page between route groups is not enough to change auth. Update proxy.ts and its tests when access changes.
  • Operator is the node-gallery host. Its own detail page is /nodes/operator; other nodes are node-at-root apps on their own subdomains unless their local validation guide says otherwise.

Proxy Rules

  • Treat nodes/operator/app/src/proxy.ts as the primary authority for page redirects and /api/v1 early rejection.
  • Keep APP_ROUTES and config.matcher in sync. Matcher drift caused /dashboard and /knowledge regressions before.
  • App routes redirect unauthenticated users to /; authenticated users on / redirect to /chat.
  • Do not add client-side auth redirects for page protection. Client components can render auth-aware states, but proxy owns access decisions.

Public Chrome

  • Use AccountSlot for shared identity chrome in public and app headers.
  • AccountSlot uses useSession() from NextAuth as the identity source. Wallet connection state is only for starting sign-in when no session exists.
  • Authenticated users should see the user menu and optional app link, never a stale Connect call-to-action just because wallet state lags.
  • If public chrome looks wrong after login, fix the session-aware component path before adding wallet-state special cases.

API Rules

  • /api/v1/public/* is unauthenticated by namespace.
  • /api/v1/agent/register is unauthenticated by explicit exception.
  • Other /api/v1/* routes require a NextAuth session unless they carry a Bearer cogni_ag_sk_v1_... agent token.
  • Proxy only provides early rejection. Route handlers must still enforce their own auth and identity rules server-side.

Tests To Update

  • Update nodes/operator/app/tests/unit/auth/proxy-routing.test.ts whenever an app route, public route, API exception, or matcher changes.
  • Add both unauthenticated and authenticated assertions for new app routes.
  • Include nested route examples for path families such as /knowledge/:id.
  • Assert public/auth-aware routes pass through without becoming app routes.
  • For chrome behavior, add focused component tests around AccountSlot or the header using mocked NextAuth session state.

Candidate Validation

  • Keep nodes/operator/.cogni/validation.md in sync with operator public routes, app routes, and auth expectations.
  • /validate-candidate reads node-local validation guides to choose human-axis routes. If this skill changes route policy, update that guide too.
  • Validate /nodes/operator only for operator gallery/detail changes. For non-operator nodes, validate the node's root/app pages on its own candidate subdomain.

Pitfalls

  • Public does not mean session-blind. /nodes can be public and still render auth-aware account controls.
  • Route group folders do not enforce auth. proxy.ts does.
  • APP_ROUTES without a matching config.matcher entry silently skips proxy execution.
  • config.matcher without a matching APP_ROUTES entry runs proxy but may pass through unexpectedly.
  • Wallet isConnected is not user identity. NextAuth session is the source of truth for logged-in UI.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall