Ověřování oprávnění (/check)

Endpointy /check slouží k ověřování oprávnění uživatelů. Jsou navrženy pro service-to-service volání z backend aplikací — nevyžadují JWT token.

POST /check — ověření jednoho oprávnění

POST /api/check
Content-Type: application/json

Request body

{
  "email": "uzivatel@firma.cz",
  "app": "moje-app",
  "permission": "documents.edit",
  "resourceType": "document",      // volitelné
  "resourceId": "42"               // volitelné
}

Pole	Typ	Povinné	Popis
email	string	✓	Email uživatele
app	string	✓	Kód aplikace
permission	string	✓	Kód oprávnění
resourceType	string	✗	Typ zdroje pro resource-level check
resourceId	string	✗	ID konkrétního záznamu

Response

{
  "success": true,
  "data": {
    "allowed": true
  }
}

Příklady

Základní check:

curl -X POST http://localhost:3001/api/check \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jan.novak@firma.cz",
    "app": "crm",
    "permission": "contacts.read"
  }'

Resource-level check (přístup ke konkrétnímu projektu):

curl -X POST http://localhost:3001/api/check \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jan.novak@firma.cz",
    "app": "crm",
    "permission": "projects.view",
    "resourceType": "project",
    "resourceId": "proj-123"
  }'

---

POST /check/bulk — ověření více oprávnění

Efektivní způsob jak ověřit více oprávnění v jednom dotazu (parallelní vyhodnocení).

POST /api/check/bulk
Content-Type: application/json

Request body

{
  "email": "uzivatel@firma.cz",
  "app": "moje-app",
  "permissions": ["documents.read", "documents.edit", "users.manage"],
  "resourceType": "document",   // volitelné — platí pro všechna oprávnění
  "resourceId": "42"            // volitelné
}

Response

{
  "success": true,
  "data": {
    "documents.read": true,
    "documents.edit": false,
    "users.manage": false
  }
}

Příklad

curl -X POST http://localhost:3001/api/check/bulk \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jan.novak@firma.cz",
    "app": "crm",
    "permissions": ["contacts.read", "contacts.edit", "deals.view"]
  }'

---

POST /check/effective — všechna efektivní oprávnění

Vrátí kompletní přehled všech oprávnění uživatele v dané aplikaci, včetně access_level a zdroje.

POST /api/check/effective
Content-Type: application/json

Request body

{
  "email": "uzivatel@firma.cz",
  "app": "moje-app",
  "resourceType": "document",   // volitelné
  "resourceId": "42"            // volitelné
}

Response

{
  "success": true,
  "data": [
    {
      "code": "documents.read",
      "type": "binary",
      "groupName": "Dokumenty",
      "accessLevel": "allowed",
      "granted": true,
      "source": "role"
    },
    {
      "code": "documents.edit",
      "type": "tiered",
      "groupName": "Dokumenty",
      "accessLevel": "view",
      "granted": true,
      "source": "role"
    },
    {
      "code": "users.manage",
      "type": "tiered",
      "groupName": "Uživatelé",
      "accessLevel": null,
      "granted": false,
      "source": null
    }
  ]
}

Pole	Popis
code	Kód oprávnění
type	"binary" nebo "tiered"
groupName	Skupina pro zobrazení v UI
accessLevel	"allowed", "view", "edit" nebo null
granted	Finální výsledek (true/false)
source	"role", "override", "superadmin" nebo null

---

POST /check/cache/clear — vyčistit cache

Okamžitě invaliduje celou LRU cache oprávnění.

POST /api/check/cache/clear

Response

{
  "success": true,
  "data": {
    "message": "Permission cache cleared"
  }
}

Kdy použít?

Po hromadných změnách rolí nebo oprávnění, pokud nechcete čekat na TTL expiraci (30 sekund).

---

Použití z backend aplikace (TypeScript)

// Pomocná funkce pro permission check
async function canUser(
  email: string,
  app: string,
  permission: string
): Promise<boolean> {
  const res = await fetch('http://atrea-user-api/api/check', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-internal-api-key': process.env.USER_API_KEY!,
    },
    body: JSON.stringify({ email, app, permission }),
  });
  const json = await res.json();
  return json.data?.allowed ?? false;
}

// Použití v Express middleware
app.delete('/api/documents/:id', async (req, res) => {
  const email = req.user.email;
  const allowed = await canUser(email, 'moje-app', 'documents.delete');
  
  if (!allowed) {
    return res.status(403).json({ error: 'Forbidden' });
  }
  
  // ... smazání dokumentu
});

Poznámky o výkonu

• Výsledky jsou cachované 30 sekund v LRU cache
• Cache HIT: < 1 ms
• Cache MISS (DB): 5–30 ms
• Bulk check provádí paralelní vyhodnocení
• Max 5 000 cache záznamů (LRU eviction)

Viz Cache oprávnění pro detaily.