Docs Angular Auth Implementation

Technical documentation for the docs-angular authentication and access control implementation (Session 217–219)

Docs Angular Auth Implementation

This document describes the authentication and access control implementation for the docs-angular application, completed across sessions 217–219.

Overview

The docs-angular app now uses backend-api (shared platform auth) instead of the legacy backend-docs-api password-based admin login. Admin access is restricted to T0/T1 roles (executives, developers, admins, system). Documentation content remains accessible to any user based on privacy level (public/private) and project selection.

Access Control Summary

Area	Who Can Access	Guard / Mechanism
Admin (`/admin`, `/admin/config`, etc.)	Executives, developers, admins, system only	`docsAdminGuard`
Documentation content	Any user (based on project selection + privacy)	`projectSelectedGuard` + `AccessService`
Login (`/auth/login`)	Unauthenticated users (redirect if already logged in)	`docsLoginPageGuard`

Architecture

Frontend (docs-angular)

Auth source: @auth-ui (AuthService, authInterceptor, LoginComponent)
API base: backendApiUrl → backend-api (port 3000) for login
Docs API base: docsApiUrl → backend-docs-api for admin endpoints (watch, scan, folders-config)
Guards:
- docsAdminGuard: T0/T1 only; redirects unauthenticated to /auth/login, unauthorized roles to /unauthorized
- docsLoginPageGuard: Redirects authenticated users to returnUrl or /admin
- projectSelectedGuard: Ensures a project is selected before docs content; whitelists admin, select-project

Backend (backend-docs-api)

Admin endpoints: Protected with JwtAuthGuard + RolesGuard + @Roles(SystemRoles.EXECUTIVE, SystemRoles.DEVELOPER, SystemRoles.ADMIN, SystemRoles.SYSTEM)
JWT: Same JWT_SECRET as backend-api; tokens from backend-api login are valid

Environment Configuration

Environment	docsApiUrl	backendApiUrl	Content source
Dev	`undefined` (MarkdownService)	`/api`	Static files
Dev	`/api` (DocsApiService)	`/api`	—
Prod	`https://docs-api.gograb.space/docs-api`	`https://api.gograb.space/api`	Static + API

Key Files

File	Purpose
`apps/docs-angular/src/app/guards/docs-admin.guard.ts`	T0/T1 admin guard
`apps/docs-angular/src/app/pages/docs-login/docs-login.component.ts`	Login wrapper (no guest mode)
`apps/docs-angular/src/app/services/dynamic-routes.service.ts`	Route definitions, guards
`apps/docs-angular/src/environments/environment.ts`	Dev config (docsApiUrl undefined for content)
`APIs/backend-docs-api/src/app/admin/admin.controller.ts`	RolesGuard on admin endpoints

Proxy Configuration (Dev)

/api/admin/docs  → localhost:5011 (docs-admin-proxy)
/api             → localhost:3000 (backend-api)

Content vs Admin Loading

Content (MarkdownService): Reads environment.docsApiUrl. When undefined in dev, uses static files. No API calls for content in default dev mode.
Admin (DocsApiService): Uses DOCS_API_URL from DI (/api in dev). Admin endpoints (/admin/docs/*) go through proxy to 5011 or backend-docs-api.

Migration from Legacy Auth

Removed: AdminAuthService usage in admin components; password form in admin dashboard
Deprecated: POST /admin/auth/login (DOCS_ADMIN_PASS) on backend-docs-api — still present for compatibility
Replaced: admin-auth-token localStorage with JWT from AuthService (authInterceptor adds it)

Troubleshooting: 401 on Login

If POST /api/auth/login returns 401 Unauthorized:

Backend running: Ensure backend-api is running on port 3000 (yarn serve:backend-api or equivalent).
Proxy: proxy.conf.json routes /api → localhost:3000. Verify no port mismatch.
Credentials: 401 usually means invalid email/password. Check backend logs for details.
Network tab: Inspect request payload (email, password) and response body for backend error message.

Session Documentation

Session README: docs/english/sessions/S219/README.md
Non-developer timeline: docs-auth-progress-timeline.md