Autorisation

Vue d'ensemble

Yayaw utilise Better Auth pour l'identité, les sessions, les organisations et les enregistrements d'appartenance. L'autorisation applicative est gérée par le moteur RBAC propre à Yayaw au-dessus de ces identités.

Le modèle est basé sur les groupes:

1. Les utilisateurs appartiennent à des groupes.
2. Les groupes reçoivent des rôles via des bindings explicites.
3. Les rôles contiennent des policies.
4. Les policies accordent ou refusent des actions sur des ressources.
5. Les bindings et vérifications peuvent être scopés globalement, par organisation ou par ressource.

Le helper booléen can(...) est la façade utilisée par la plupart des loaders de routes, actions serveur et services. L'évaluateur détaillé enregistre la chaîne de décision pour les workflows de débogage et d'audit.

Concepts clés

Les ressources sont déclarées dans src/lib/server/authz/contracts.ts. Les familles de ressources actuelles incluent:

• organisations et membres
• utilisateurs plateforme
• clés API
• plans de facturation, produits, entitlements, événements webhook et accès au code
• événements d'audit du plan de contrôle (control plane)
• ressources d'administration de l'autorisation
• médias, pages, sections, composants, données globales, design tokens et thèmes
• réglages système, organisation et préférences utilisateur

Les actions sont:

• read
• list
• create
• update
• delete
• invite
• manage

manage est l'action administrative large pour une ressource. Préférez des actions plus étroites lorsqu'une UI ou un service n'a besoin que d'un comportement read/list/update.

Tables

Tables d'autorisation:

• groups
• group_memberships
• roles
• role_policies
• group_role_bindings
• authorization_audit_events
• authorization_decision_logs

group_role_bindings est la table de scope clé. Un groupe peut recevoir un rôle avec:

• scope global
• scope organization
• scope resource

C'est pourquoi l'accès organisation est modélisé comme des rôles appliqués à des groupes, et non comme des lignes directes utilisateur-permission.

Rôles seedés

Le seed crée les rôles plateforme:

• Super Admin
• Organization Admin
• Organization Manager
• Organization Member
• Authenticated User

Super Admin reçoit une couverture manage pour chaque ressource déclarée et est bindé au groupe superadmins.

L'administration des utilisateurs plateforme utilise la paire ressource/action user:manage. N'utilisez pas user.role de Better Auth comme autorité d'autorisation Yayaw; les permissions Yayaw restent exclusivement users -> groups -> roles -> policies.

Lorsqu'une organisation est créée, Yayaw crée des groupes scopés par organisation:

• <organizationSlug>-admin
• <organizationSlug>-manager
• <organizationSlug>-member

Chaque groupe est bindé au rôle d'organisation correspondant avec scopeType = "organization" et scopeId = <organizationId>.

Synchronisation d'organisation

Les hooks d'organisation Better Auth gardent les groupes d'autorisation Yayaw synchronisés:

• la création d'organisation crée les groupes par défaut et assigne le créateur au groupe admin
• l'acceptation d'invitation ajoute les membres au bon groupe d'organisation
• les changements de rôle de membre déplacent les appartenances entre les groupes d'organisation
• le retrait d'un membre supprime l'appartenance au groupe interne

Services clés:

• src/lib/server/services/authz/organization-setup-drizzle.ts
• src/lib/server/services/authz/better-auth-sync-drizzle.ts
• src/config/better-auth.config.ts

Ne créez pas de membres d'organisation Better Auth par un chemin qui contourne le service de synchronisation, sauf si le code répare aussi l'appartenance au groupe correspondante.

Évaluation des policies

Fichiers principaux:

• src/lib/server/authz/can.ts
• src/lib/server/authz/policy-loader.ts
• src/lib/server/authz/drizzle-group-membership-delegate.ts

Règles d'évaluation:

• les ressources/actions inconnues sont refusées par défaut
• les règles deny correspondantes gagnent sur les allows
• le scope de binding doit correspondre au scope demandé par la vérification
• les vérifications scopées par organisation exigent l'id d'organisation dans le scope
• les vérifications scopées par ressource exigent l'id de ressource dans le scope
• authorizeDetailed(...) retourne une chaîne de décision pour l'explicabilité
• can(...) retourne un booléen pour les guards de routes et d'actions

L'autorisation côté serveur doit rester dans le chemin de mutation/requête. La visibilité de navigation UI est seulement une commodité et ne doit jamais être le seul contrôle d'accès.

Administration du tableau de bord

L'administration de l'autorisation vit à:

• /dashboard/admin/authorization
• /dashboard/admin/authorization/groups/[groupId]
• /dashboard/admin/users

L'UI admin prend en charge:

• l'inspection des rôles et policies
• les vues liste/détail de groupes
• la gestion des appartenances de groupes
• la gestion des bindings groupe-rôle
• le listing des utilisateurs plateforme, la maintenance des appartenances d'organisation et les mises à jour d'organisation par défaut
• l'évaluation rapide de permissions
• les diagnostics de décision/audit

La surface utilisateurs permet aux superadmins d'ajouter un utilisateur à une autre organisation sans supprimer les appartenances existantes, de modifier le rôle d'appartenance Better Auth à une organisation, de retirer des appartenances et de démarrer une session d'impersonation vérifiée par le RBAC Yayaw. Les endpoints d'impersonation enveloppent intentionnellement les mécaniques de session Better Auth derrière des vérifications user:manage et bloquent l'impersonation d'un autre utilisateur qui possède aussi user:manage.

Utilisez cette page pour inspecter pourquoi un utilisateur peut ou ne peut pas accéder à une ressource avant de modifier les policies de seed.

Contrats de routes et d'actions

Les routes déclarent leur intention de permission dans la configuration navigation/route. Les actions de base de données générées déclarent aussi des paires ressource/action. Les tests de contrat assurent que les ressources déclarées restent dans le contrat authz canonique.

Test important:

bun test src/lib/server/authz/contracts.test.ts

Cela protège:

• les ressources de navigation
• les ressources des actions DB générées
• la couverture de seed Super Admin
• la couverture de réparation de l'administration utilisateur
• la couverture de réparation authz des sections
• les racines navigables du tableau de bord

Attentes courantes par ressource

Valeurs par défaut d'organisation:

Super Admin reçoit un accès manage global plateforme, y compris aux produits de facturation, indicateurs de fonctionnalité, réglages système, modèles de registre, utilisateurs plateforme et ressources d'autorisation.

L'accès au code exige toujours l'éligibilité de facturation. code-access:read permet à un utilisateur d'atteindre la surface d'accès au code, mais le service de facturation décide si les livrables payants sont déverrouillés.

Ajouter une ressource

Lors de l'ajout d'une ressource:

1. Ajoutez-la à RESOURCES dans src/lib/server/authz/contracts.ts.
2. Ajoutez les policies de seed pour Super Admin.
3. Ajoutez les policies de rôles d'organisation lorsque la ressource est scopée par organisation.
4. Ajoutez des migrations ou du SQL de réparation pour les installations existantes si nécessaire.
5. Ajoutez ou mettez à jour les permissions de configuration de routes.
6. Ajoutez les mappings d'actions générées si la ressource a des actions de base de données.
7. Mettez à jour les docs anglaises et content/llm/llm-source.md lorsque la ressource change l'architecture ou les consignes assistant.
8. Exécutez les tests de contrat authz.

Déboguer un accès

Lorsqu'un utilisateur ne peut pas accéder à une page:

1. Confirmez que l'organisation active est correcte.
2. Confirmez que l'appartenance Better Auth existe.
3. Confirmez que l'appartenance au groupe Yayaw correspondant existe.
4. Confirmez que le groupe a un binding de rôle scopé.
5. Confirmez que le rôle a une policy pour la ressource/action demandée.
6. Utilisez l'évaluateur rapide dans /dashboard/admin/authorization.
7. Vérifiez authorization_decision_logs lorsque la journalisation détaillée est activée.

Validation

Vérifications utiles après des changements authz:

bun test src/lib/server/authz/policy-loader.test.ts
bun test src/lib/server/authz/contracts.test.ts
bun test src/lib/server/services/authz/authz-service.test.ts
bun run check
bunx tsc --noEmit