@logscord/authorizer

Client et serveur d'autorisation pour applications Logscord.

Documentation

• Guide utilisateur
• Reference YAML
• Exemple bot Discord

Serveur

npm install
npm run build
npm run start

Par défaut le serveur écoute sur 127.0.0.1:9990, lit config.yml, charge les fichiers policies/*.yml, les variables de variables.yml, puis applique les templates de templates.yml.

config.yml:

server:
  host: 127.0.0.1
  port: 9990

policies:
  paths:
    - policies/*.yml
  refreshIntervalMs: 5000

templates:
  path: templates.yml

variables:
  path: variables.yml

Le serveur vérifie si les policies, variables ou templates ont changé au maximum toutes les refreshIntervalMs. Le rechargement peut être forcé avec GET /refresh ou POST /refresh.

Le serveur distribue les policies compilees, mais n'execute pas les decisions d'autorisation. Les appels can() sont evalues localement par le client.

Endpoints exposés:

• GET /health
• GET /policies?application=warrior
• GET|POST /refresh

GET /policies renvoie une version et supporte ETag / If-None-Match:

{
  "version": "abc123",
  "policies": {
    "default": "deny",
    "policies": []
  }
}

Si la version client est deja a jour, le serveur repond 304 Not Modified.

Client

import { AuthorizationClient } from "@logscord/authorizer";

const authz = new AuthorizationClient({
    endpoint: "http://localhost:9990",
    application: "warrior",
    refresh: {
        intervalMs: 5000,
        staleAfterMs: 60_000,
        maxStaleMs: 10 * 60_000,
        timeoutMs: 2000,
        retry: {
            attempts: 3,
            backoffMs: 500,
            maxBackoffMs: 5000,
            jitter: true
        }
    },
    consistency: {
        startup: "require-fresh",
        stale: "allow-stale",
        expired: "deny"
    }
});

await authz.ready();

const authorizer = authz.createContext({
    subject: {
        id: user.id,
        roles: user.roles.map((role) => role.id)
    },
    target: {
        id: targetUser.id
    }
});

if (!authorizer.can("lockname", { target: targetUser.id })) {
    console.log(authorizer.reason?.message);
}

can() est synchrone et utilise le cache local des policies. canAsync() existe seulement comme wrapper async local; il ne fait pas d'aller-retour HTTP.

Le client utilise un snapshot immutable des policies. Un refresh telecharge et valide une nouvelle version, puis remplace le snapshot en une seule affectation. can() ne prend donc pas de lock et n'attend jamais le reseau.

La configuration de coherence controle le cycle de vie du cache:

• cache frais: evaluation locale immediate;
• cache stale: evaluation locale et refresh en arriere-plan par defaut;
• cache expire: deny, throw, wait-for-refresh ou allow-stale;
• pas de cache au demarrage: ready() exige une version fraiche par defaut.

Policies

Chaque fichier dans policies/*.yml peut représenter une application. Si le champ application est absent, le nom du fichier est utilisé.

Les règles sont évaluées dans l'ordre après expansion des templates. La première règle qui match gagne.

variables.yml:

variables:
  global:
    ownerId: "123456789012345678"

  warrior:
    locknameRoles:
      - moderator
      - administrator
    locknameDenyReason: Vous n'avez pas la permission de faire cette commande sur ce membre.

policies/warrior.yml:

default: deny
defaultReason:
  message: "{{ vars.local.locknameDenyReason }}"

variables:
  ownerId: "{{ vars.global.ownerId }}"
  locknameRoles: "{{ vars.warrior.locknameRoles }}"
  locknameDenyReason: "{{ vars.warrior.locknameDenyReason }}"

policies:
  - id: lockname-owner
    effect: allow
    actions:
      - lockname
    subjects:
      ids:
        - "{{ vars.local.ownerId }}"

  - id: lockname-self
    effect: deny
    actions:
      - lockname
    when:
      all:
        - path: subject.id
          operator: equals
          valueFrom: target.id
    reason:
      message: Vous ne pouvez pas faire cette commande sur vous-même.

  - id: "@refs/rbac"
    inputs:
      action: lockname
      roles: "{{ vars.local.locknameRoles }}"
      denyReason: "{{ vars.local.locknameDenyReason }}"

Une policy avec id: "@refs/<template>" est remplacée à cet endroit exact par les règles du template. L'ordre du tableau policies est donc l'ordre d'évaluation final.

Variables disponibles:

• {{ vars.global.<name> }} pour le namespace global.
• {{ vars.<application>.<name> }} pour un namespace précis, par exemple vars.warrior.locknameRoles.
• {{ vars.app.<name> }} pour le namespace de l'application en cours.
• {{ vars.local.<name> }} pour les variables définies dans le fichier de policy en cours.

Les variables locales sont aussi fusionnées dans vars.app et vars.<application> avec priorité sur variables.yml.

templates.yml:

templates:
  rbac:
    inputs:
      action:
        required: true
      roles:
        required: true
      denyReason:
        default: Vous n'avez pas la permission de faire cette action.
    policies:
      - id: "{{ action }}-rbac"
        effect: allow
        actions:
          - "{{ action }}"
        subjects:
          roles: "{{ roles }}"

      - id: "{{ action }}-rbac-deny"
        effect: deny
        actions:
          - "{{ action }}"
        reason:
          message: "{{ denyReason }}"

Quand un placeholder occupe toute la valeur, comme "{{ roles }}", la valeur garde son type réel. Ici roles reste donc un tableau.

Opérateurs supportés: equals, notEquals, includes, notIncludes, in, notIn, exists, notExists, matches, gt, gte, lt, lte.