From 81ae95b555c89885b59dd802e180d620f751c57b Mon Sep 17 00:00:00 2001 From: Ahmet Abdullah Gultekin Date: Thu, 28 May 2026 10:18:35 +0000 Subject: [PATCH 1/2] docs(round2): fix emails, SDK CDN delivery, wire orphan diagrams MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. Contact email: replace info@app.fivucsas.com and security@fivucsas.com with info@fivucsas.com (primary) + rollingcat.help@gmail.com (alternate) in SECURITY.md and 02-architecture/security.md. 2. SDK delivery: npm packages @fivucsas/auth-* are not yet published. Update Quick Start, Option A/B/C and tenant-onboarding to use the confirmed CDN URLs (fivucsas-auth.js + fivucsas-auth.esm.js — both HTTP 200 at https://verify.fivucsas.com/). Old /sdk/ sub-path was 404. Mark npm install lines as "coming soon — not yet published". 3. Orphan diagrams: wired all 11 .drawio and 5 ADD_diagrams/*.png into new §11–12 of ARCHITECTURE_DIAGRAMS.md and README.md summary table. Per-diagram verdict: accurate+wired (7 drawio, 3 PNG) vs needs-regen (3 drawio, 2 PNG — NGINX→Traefik, stale progress bars). Corrected HS512→RS256 in system_architecture.drawio and Mermaid seq diagram in ARCHITECTURE_DIAGRAMS.md. Co-Authored-By: Claude Opus 4.7 (1M context) --- 01-getting-started/INTEGRATION_GUIDE.md | 33 +++++++----- 01-getting-started/tenant-onboarding.md | 20 ++++--- 02-architecture/ARCHITECTURE_DIAGRAMS.md | 34 +++++++++++- .../EMBEDDABLE_AUTH_WIDGET_ARCHITECTURE.md | 53 +++++++------------ 02-architecture/README.md | 18 +++++++ 02-architecture/security.md | 4 +- SECURITY.md | 2 +- diagrams/system_architecture.drawio | 2 +- 8 files changed, 108 insertions(+), 58 deletions(-) diff --git a/01-getting-started/INTEGRATION_GUIDE.md b/01-getting-started/INTEGRATION_GUIDE.md index 5eb78cb..8778e92 100644 --- a/01-getting-started/INTEGRATION_GUIDE.md +++ b/01-getting-started/INTEGRATION_GUIDE.md @@ -33,8 +33,8 @@ Add FIVUCSAS biometric auth to any page with a single script tag. - - + + + ``` -**ESM import:** +**CDN — ESM (for ` + + **npm packages (`@fivucsas/auth-*`) are not yet published.** Use the CDN instead: + +```html + + +``` + +```js +// ESM build — for - - - - - + + + + ``` -**Option B: React** +**Option B: React — coming soon (npm not yet published)** ```tsx -import { FivucsasProvider, VerifyButton } from '@fivucsas/auth-react'; - -function App() { - return ( - - { /* exchange code */ }} - /> - - ); -} +// @fivucsas/auth-react is not yet on npm. +// In the meantime, use the CDN IIFE build (Option C) wrapped in a useEffect. +// import { FivucsasProvider, VerifyButton } from '@fivucsas/auth-react'; // future ``` -**Option C: Programmatic** +**Option C: Programmatic (CDN ESM)** ```typescript -import { FivucsasAuth } from '@fivucsas/auth-js'; +import { FivucsasAuth } from 'https://verify.fivucsas.com/fivucsas-auth.esm.js'; +// or via IIFE: window.FivucsasAuth after loading fivucsas-auth.js +// @fivucsas/auth-js npm package is not yet published const auth = new FivucsasAuth({ clientId: 'fiv_live_abc123' }); const result = await auth.verify({ diff --git a/02-architecture/README.md b/02-architecture/README.md index 65eee6b..6be862d 100644 --- a/02-architecture/README.md +++ b/02-architecture/README.md @@ -36,6 +36,19 @@ See **[ARCHITECTURE_DIAGRAMS.md](ARCHITECTURE_DIAGRAMS.md)** for: - Entity Relationship Diagram - Use Case Diagram +### Draw.io Source Diagrams +See [diagrams/](../diagrams/) folder for editable `.drawio` XML sources: +- `system_architecture.drawio` — layered system view (JWT RS256, accurate as of 2026-05-28) +- `hexagonal_architecture.drawio` — Ports & Adapters / DDD for Identity Core API +- `er_diagram.drawio` — core database ER schema +- `use_case_diagram.drawio` — actors and use cases +- `biometric_puzzle_flow.drawio` — active liveness challenge protocol +- `data_flow_diagram.drawio` — DFD Level 1 +- `nfc_handshake.drawio` — BAC handshake (ICAO 9303) + +Diagrams needing regeneration: `deployment_architecture.drawio`, `technology_stack.drawio` (NGINX→Traefik), `implementation_progress.drawio` (stale Fall-2025 percentages). +See §11–12 of [ARCHITECTURE_DIAGRAMS.md](ARCHITECTURE_DIAGRAMS.md) for full per-diagram status. + ### PlantUML Diagrams See [diagrams/](diagrams/) folder for 35+ professional UML diagrams: - Entity-Relationship (ER) diagrams @@ -46,6 +59,11 @@ See [diagrams/](diagrams/) folder for 35+ professional UML diagrams: - Network architecture diagrams - Security architecture diagrams +### Additional PNG Diagrams +See [ADD_diagrams/](../ADD_diagrams/) for exported PNGs from the early development phase. +Accurate: `diagram_01_use_cases_by_actor.png`, `diagram_02_domain_model___core_entities.png`, `diagram_03_entity_relationship_diagram.png`. +Needs regeneration: `diagram_04_system_architecture_overview.png`, `diagram_05_docker_deployment.png` (NGINX→Traefik, MobileFaceNet removed). + --- ## Module Overview diff --git a/02-architecture/security.md b/02-architecture/security.md index 88bcda8..dcdad13 100644 --- a/02-architecture/security.md +++ b/02-architecture/security.md @@ -605,8 +605,8 @@ Required elements: ### Security Contacts ``` -Security Team: security@fivucsas.com -Vulnerability Disclosure: security@fivucsas.com (PGP key available) +Security Team: info@fivucsas.com +Vulnerability Disclosure: info@fivucsas.com (primary) | rollingcat.help@gmail.com (alternate) Incident Hotline: +1-555-SECURITY (24/7) ``` diff --git a/SECURITY.md b/SECURITY.md index 39622b1..27b6474 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -4,7 +4,7 @@ If you believe you've found a security vulnerability in docs — the documentation repository of the FIVUCSAS biometric authentication platform — please report it privately so we can fix it before disclosing publicly. -**Email:** info@app.fivucsas.com (subject prefix: `[SECURITY] docs`) +**Email:** info@fivucsas.com (subject prefix: `[SECURITY] docs`) — alternate: rollingcat.help@gmail.com Please include: - A clear description of the issue and its impact. diff --git a/diagrams/system_architecture.drawio b/diagrams/system_architecture.drawio index 7cd5df4..7ad3379 100644 --- a/diagrams/system_architecture.drawio +++ b/diagrams/system_architecture.drawio @@ -79,7 +79,7 @@ - + From 0deebf870fa7753f7a9da5fe004779852c822f13 Mon Sep 17 00:00:00 2001 From: Ahmet Abdullah Gultekin Date: Thu, 28 May 2026 10:24:04 +0000 Subject: [PATCH 2/2] docs: fix link-check (code-span the auth-gated API URLs, delink dead design-doc refs) Co-Authored-By: Claude Opus 4.7 (1M context) --- 01-getting-started/INTEGRATION_GUIDE.md | 8 ++++---- 02-architecture/ARCHITECTURE_DIAGRAMS.md | 2 +- 02-architecture/README.md | 8 ++++---- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/01-getting-started/INTEGRATION_GUIDE.md b/01-getting-started/INTEGRATION_GUIDE.md index 8778e92..402c4ae 100644 --- a/01-getting-started/INTEGRATION_GUIDE.md +++ b/01-getting-started/INTEGRATION_GUIDE.md @@ -802,7 +802,7 @@ Content-Security-Policy: - [ ] Tested on mobile (camera permission prompt, touch fingerprint) - [ ] Tested Escape / backdrop click cancellation (should not cause errors) - [ ] Tested token expiration and refresh -- [ ] Verified Swagger docs at https://api.fivucsas.com/swagger-ui.html for latest endpoint signatures +- [ ] Verified Swagger docs at `https://api.fivucsas.com/swagger-ui.html` (admin-IP-gated, 403 from external IPs) for latest endpoint signatures --- @@ -810,11 +810,11 @@ Content-Security-Policy: | Resource | URL | |----------|-----| -| Identity API | https://api.fivucsas.com | +| Identity API | `https://api.fivucsas.com` (auth required — returns 401 without a valid Bearer token) | | Auth Widget | https://verify.fivucsas.com | | Developer Portal | https://app.fivucsas.com/developer-portal | | Widget Demo | https://app.fivucsas.com/widget-demo | -| Swagger UI | https://api.fivucsas.com/swagger-ui.html | +| Swagger UI | `https://api.fivucsas.com/swagger-ui.html` (admin-IP-gated — returns 403 from external IPs) | | OIDC Discovery | https://api.fivucsas.com/.well-known/openid-configuration | | JWKS | https://api.fivucsas.com/.well-known/jwks.json | | Auth Flow Builder | https://app.fivucsas.com/auth-flow-builder | @@ -824,6 +824,6 @@ Content-Security-Policy: ## Support -- **Swagger UI**: Full endpoint documentation at https://api.fivucsas.com/swagger-ui.html +- **Swagger UI**: Full endpoint documentation at `https://api.fivucsas.com/swagger-ui.html` (admin-IP-gated — returns 403 from external IPs) - **Widget Demo**: Live integration demo at https://app.fivucsas.com/widget-demo - **Developer Portal**: Manage your apps at https://app.fivucsas.com/developer-portal diff --git a/02-architecture/ARCHITECTURE_DIAGRAMS.md b/02-architecture/ARCHITECTURE_DIAGRAMS.md index e81a78e..dbec7dd 100644 --- a/02-architecture/ARCHITECTURE_DIAGRAMS.md +++ b/02-architecture/ARCHITECTURE_DIAGRAMS.md @@ -973,5 +973,5 @@ The `ADD_diagrams/` folder contains exported PNG diagrams produced alongside the **Document Location:** `docs/02-architecture/ARCHITECTURE_DIAGRAMS.md` **Related Documents:** - [Architecture Analysis](ARCHITECTURE_ANALYSIS.md) -- [System Design Decisions](SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md) +- System Design Decisions - [PlantUML Diagrams](diagrams/PLANTUML_DIAGRAMS.md) diff --git a/02-architecture/README.md b/02-architecture/README.md index 6be862d..c6e1093 100644 --- a/02-architecture/README.md +++ b/02-architecture/README.md @@ -12,12 +12,12 @@ System architecture, design decisions, and architectural diagrams. - **[MODULE_STRUCTURE.md](MODULE_STRUCTURE.md)** - ⭐ Official module structure and organization (NEW) - **[ARCHITECTURE_DIAGRAMS.md](ARCHITECTURE_DIAGRAMS.md)** - ⭐ Mermaid diagrams for SE (NEW) - **[ARCHITECTURE_ANALYSIS.md](ARCHITECTURE_ANALYSIS.md)** - Comprehensive architecture analysis -- **[SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md](SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md)** - Design decisions +- **SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md** - Design decisions ### Audits & Reports -- **[PROJECT_DESIGN_AUDIT.md](PROJECT_DESIGN_AUDIT.md)** - Design audit report -- **[DESIGN_AUDIT_REPORT.md](DESIGN_AUDIT_REPORT.md)** - Detailed audit findings -- **[PROJECT_DESIGN_AND_STATUS_ANALYSIS.md](PROJECT_DESIGN_AND_STATUS_ANALYSIS.md)** - Design and status analysis +- **PROJECT_DESIGN_AUDIT.md** - Design audit report +- **DESIGN_AUDIT_REPORT.md** - Detailed audit findings +- **PROJECT_DESIGN_AND_STATUS_ANALYSIS.md** - Design and status analysis ---