Accès, audiences & confidentialité
Modèle canonique de publication partielle pour séparer documentation publique, clients, équipes internes et contenus restreints.
Principe
Le site Documentation.AI doit fonctionner en mode Partial avec JWT ou OAuth 2.0.
Le repository reste privé.
La visibilité n’est jamais déduite du nom d’un fichier : elle est déclarée dans documentation.json avec :
public: truepour une page ou un sous-arbre public ;public: falsepour un contenu protégé ;access-rolespour limiter un contenu protégé à certaines audiences.
Un contenu sensible ne doit jamais être « caché » visuellement dans une page publique. S’il doit être privé, il vit dans une page ou sous-page protégée.
Audiences canoniques
| Audience | Rôle JWT/OAuth | Usage |
|---|---|---|
| Public | aucun | Vision, concepts publics, FAQ, aide générale |
| Client authentifié | customer | Documentation liée au compte ou aux fonctions réservées |
| Partenaire | partner | Intégrations et contrats partenaires |
| Support / Success | support | Diagnostic, procédures support, previews |
| Produit / Design | product | Roadmap, source de vérité, UX, Design System |
| Engineering | engineering | Architecture, data model, tests, migrations, API draft |
| Opérations | ops | SLO, observabilité, runbooks, backups |
| Sécurité | security | Threat model, incidents, politiques sensibles |
| Founder | founder | Founder OS, stratégie privée, décisions et workflows personnels |
| Finance | finance | COGS, marges, coûts, pricing interne |
| Admin | * | Accès à toutes les pages protégées |
Les tokens peuvent porter plusieurs rôles.
Règle d’héritage
La visibilité est définie au niveau le plus haut possible, puis surchargée uniquement lorsque nécessaire.
Exemple :
{
"group": "Sécurité",
"public": false,
"access-roles": ["security", "engineering"],
"pages": [
{ "title": "Threat model", "path": "security/threat-model" }
]
}
Granularité supportée
La frontière de sécurité canonique est le nœud de navigation : tab, group, page, sous-groupe, dimension ou vue.
Pour protéger seulement une partie d’une page :
- extraire cette partie dans une sous-page ;
- placer cette sous-page sous un nœud protégé ;
- laisser dans la page publique uniquement un résumé non sensible.
Ce qui n’est PAS une ACL
Ne jamais considérer comme contrôle d’accès :
- un accordéon fermé ;
- un onglet MDX ;
- un bloc conditionnel côté navigateur ;
- CSS
display:none; - JavaScript lisant
window.dai.user; - un lien non affiché ;
- une iframe protégée uniquement par la page qui l’embarque.
Ces techniques peuvent personnaliser l’expérience, mais ne doivent pas contenir de secrets.
Prototype canonique
orbit-brain-demo.html contient des commentaires internes, des décisions d’architecture et un hub admin de développement.
Il reste donc interne.
La page prototype.mdx est protégée pour product, engineering et support.
Pour le rendre dans une iframe, la cible doit elle-même être servie par une route authentifiée Orbit. La protection Documentation.AI de la page parente ne suffit pas à sécuriser une URL externe.
Crawler & IA
En mode Partial, seules les pages publiques doivent être exposées aux surfaces publiques de découverte.
Après chaque publication, vérifier :
/llms.txt;- sitemap ;
robots.txt;- recherche Documentation.AI ;
- export markdown
/md/; - accès direct par URL.
Règle du repository
Le GitHub BoostEcom/orbit.boostecom.dev reste privé.
L’accès Documentation.AI protège le site publié, pas les fichiers d’un repository public. La source interne ne doit donc jamais dépendre de la seule ACL du site.