4nk/smart_ide
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
smart_ide/docs/API/sso-gateway-api.md
Nicolas Cantu 58cc2493e5 chore: consolidate ia_dev module, sync tooling, and harden gateways (0.0.5) 
Initial state:
- ia_dev was historically referenced as ./ia_dev in docs and integrations, while the vendored module lives under services/ia_dev.
- AnythingLLM sync and hook installation had error masking / weak exit signaling.
- Proxy layers did not validate proxy path segments, allowing path normalization tricks.

Motivation:
- Make the IDE-oriented workflow usable (sync -> act -> deploy/preview) with explicit errors.
- Reduce security footguns in proxying and script automation.

Resolution:
- Standardize IA_DEV_ROOT usage and documentation to services/ia_dev.
- Add SSH remote data mirroring + optional AnythingLLM ingestion.
- Extend AnythingLLM pull sync to support upload-all/prefix and fail on upload errors.
- Harden smart-ide-sso-gateway and smart-ide-global-api proxying with safe-path checks and non-leaking error responses.
- Improve ia-dev-gateway runner validation and reduce sensitive path leakage.
- Add site scaffold tool (Vite/React) with OIDC + chat via sso-gateway -> orchestrator.

Root cause:
- Historical layout changes (submodule -> vendored tree) and missing central contracts for path resolution.
- Missing validation for proxy path traversal patterns.
- Overuse of silent fallbacks (|| true, exit 0 on partial failures) in automation scripts.

Impacted features:
- Project sync: git pull + AnythingLLM sync + remote data mirror ingestion.
- Site frontends: SSO gateway proxy and orchestrator intents (rag.query, chat.local).
- Agent execution: ia-dev-gateway script runner and SSE output.

Code modified:
- scripts/remote-data-ssh-sync.sh
- scripts/anythingllm-pull-sync/sync.mjs
- scripts/install-anythingllm-post-merge-hook.sh
- cron/git-pull-project-clones.sh
- services/smart-ide-sso-gateway/src/server.ts
- services/smart-ide-global-api/src/server.ts
- services/smart-ide-orchestrator/src/server.ts
- services/ia-dev-gateway/src/server.ts
- services/ia_dev/tools/site-generate.sh

Documentation modified:
- docs/** (architecture, API docs, ia_dev module + integration, scripts)

Configurations modified:
- config/services.local.env.example
- services/*/.env.example

Files in deploy modified:
- services/ia_dev/deploy/*

Files in logs impacted:
- logs/ia_dev.log (runtime only)
- .logs/* (runtime only)

Databases and other sources modified:
- None

Off-project modifications:
- None

Files in .smartIde modified:
- .smartIde/agents/*.md
- services/ia_dev/.smartIde/**

Files in .secrets modified:
- None

New patch version in VERSION:
- 0.0.5

CHANGELOG.md updated:
- yes
2026-04-04 18:36:43 +02:00

3.7 KiB
Raw Permalink Blame History

API — smart-ide-sso-gateway

Écoute par défaut : 127.0.0.1:37148. Configuration : services/smart-ide-sso-gateway/.env.example, agrégat config/services.local.env.example.

Authentification

Route Auth utilisateur
GET /health Aucune
OPTIONS * Aucune (préflight CORS si SSO_CORS_ORIGIN défini)
Toutes les autres Authorization: Bearer <access_token> OIDC (docv / Enso)

Endpoints

GET /health

Réponse 200 : { "status": "ok", "service": "smart-ide-sso-gateway" }.

GET /v1/token/verify

Vérifie le Bearer utilisateur. Réponse 200 : { "valid": true, "claims": { ... } } avec un sous-ensemble des claims (sub, iss, aud, exp, iat, email, name, preferred_username).

GET /v1/upstreams

Liste les clés de proxy disponibles (allowlist) : { "upstreams": [ "orchestrator", ... ] }.

Proxy — ANY /proxy/<upstream_key>/<path>

  • <upstream_key> : voir liste ci-dessus (repos_devtools, orchestrator, etc.).
  • <path> : relayé vers smart-ide-global-api sous /v1/upstream/<upstream_key><path> (ex. /proxy/orchestrator/v1/... → GLOBAL_API_URL/v1/upstream/orchestrator/v1/...).
  • Corps : relayé pour les méthodes avec body (limite SSO_GATEWAY_MAX_BODY_BYTES, défaut 32 MiB).
  • Réponses d’erreur : 401 si Bearer utilisateur absent ou invalide ; 403 si l’upstream est hors allowlist (SSO_ALLOWED_UPSTREAMS) ; 404 si route inconnue ; erreurs amont si l’API globale ou un micro-service refuse la requête.

L’en-tête Authorization utilisateur n’est pas transmis à l’API globale ; il est remplacé par GLOBAL_API_INTERNAL_TOKEN. Les claims OIDC sont transmis en X-OIDC-Sub / X-OIDC-Email jusqu’aux micro-services. Voir sso-gateway-service.md et global-api.md.

Journaux

Fichier .logs/sso-gateway/access.log : lignes JSON (ts, method, path, upstream, status, durationMs, oidcSub si présent). Les GET /health et OPTIONS ne sont pas journalisés.

Comptes et projets

Aucun stockage d’utilisateurs ou de comptes par projet dans ce service : uniquement validation OIDC et proxy. Les données de compte et d’appartenance projet vivent dans les bases métier des produits ; la passerelle ne les duplique pas.

Variables d’environnement (passerelle)

Variable Rôle
OIDC_ISSUER Obligatoire — URL de l’issuer OpenID
OIDC_AUDIENCE Optionnel — audience attendue du JWT
OIDC_JWKS_URI Optionnel — URI JWKS explicite
SSO_GATEWAY_HOST / SSO_GATEWAY_PORT Bind HTTP
SSO_CORS_ORIGIN Si défini, en-têtes CORS sur les réponses
SSO_GATEWAY_MAX_BODY_BYTES Taille max du corps en entrée
SSO_ALLOWED_UPSTREAMS Allowlist des upstreams (CSV). Défaut: orchestrator. */all pour autoriser tout.
GLOBAL_API_URL Base HTTP de smart-ide-global-api (défaut http://127.0.0.1:37149)
GLOBAL_API_INTERNAL_TOKEN Obligatoire — même valeur que sur smart-ide-global-api
SMART_IDE_MONOREPO_ROOT Optionnel — racine pour écrire sous .logs/sso-gateway/

Les jetons et hôtes des micro-services sont lus par smart-ide-global-api ; la liste des clés connues provient du module @4nk/smart-ide-upstreams (packages/smart-ide-upstreams/). GET /v1/upstreams applique ensuite SSO_ALLOWED_UPSTREAMS. Voir config/services.local.env.example et global-api.md.

Voir aussi