authorization

Files (1)

• SKILL.md

SKILL.md (first lines)

# Authorization & IAM Skill

## 1. When to Use
Use this skill when defining permissions, roles, groups, IAM policies, policy evaluation statements, route guards, or resource ownership checks.

## 2. Policy Evaluation Invariants
1. **Tenant ROOT Authority**: If `identity.identityType === 'ROOT'`, access is unconditionally granted across all actions *within that identity's own tenant*. ROOT is the root of one workspace, never of the platform.
2. **Explicit Deny Precedence**: If any statement (direct, role, or group) contains `effect: 'deny'` matching the requested action, access is immediately blocked.
3. **Allow Statements & Ownership**: If an allow statement matches:
   - For `:self` actions (e.g. `profile:update:self`), verify `context.resourceOwnerId === identity.id`.
4. **Implicit Deny**: If no matching statement is found, access is denied by default.

## 2a. Multi-tenancy
Every signup creates a workspace (tenant) and makes its creator that workspace's ROOT. Everyone invited afterwards is an `EXTERNAL_USER` in the same tenant.

- **Users** belong to one tenant.
- **Roles, groups and policies** are either *platform-owned* (`tenant_id` NULL — shared, visible to every tenant, immutable) or *owned by one tenant* (invisible to all others, editable only by it). Two tenants may use the same name.
- **Permissions** (the catalog) are global.
- `IamService` methods take `tenantId` as a required first argument. A record outside the caller's tenant is **404, never 403** — confirming it exists would leak across the boundary. Routes obtain it with `tenantIdOf(request.user)`, which refuses an identity with no tenant.
- A ROOT cannot grant, attach or read another tenant's records either: `assertCanGrantPolicy` checks tenant visibility *before* the ROOT shortcut.
- **Granting needs holding.** Assigning a role or adding a user to a group requires the actor to hold every permission those confer (`assertCanGrantRole`), not merely `roles:update`.

## 2b. The Access-Control Console (`/iam`)
The web app's `/iam` area is its own route group with its own sign-in (`/iam/login`). It admits the workspace ROOT and holders of `admin:access`. That gate only decides whether to render; the API's scoping is what protects data. Users are added by invitation (`POST /api/v1/iam/users`): no password is accepted or returned, and the invitee chooses their own from an emailed link.

## 3. Policy Condition Operators
`PolicyStatement.conditions` supports exactly four operators, each mapping a context key to the value(s) it must satisfy. The canonical list lives in `SUPPORTED_CONDITION_OPERATORS` (`@packages/validation`, `packages/validation/src/iam.ts`); `packages/iam/src/policy/policy-engine.ts` imports it rather than redeclaring it, since `@packages/validation` has no dependency on `@packages/iam` and must not gain one.

| Operator | Example | Meaning |
|---|---|---|
| `StringEquals` | `{ "department": "finance" }` | `context.attributes.department === "finance"` |
| `StringNotEquals` | `{ "department": "contractors" }` | `context.attributes.department !== "contractors"` |
| `Bool` | `{ "mfaPresent": true }` | `Boolean(context.attributes.mfaPresent) === true` |
| `OwnerEquals` | `{ "resourceOwnerId": "@identity" }` | `context.resourceOwnerId === identity.id` |

- **Write-time rejection**: `PolicyStatementSchema.conditions` validates the outer keys (the operator names) against `SUPPORTED_CONDITION_OPERATORS` via `superRefine`. `POST /api/v1/iam/policies` and `PUT /api/v1/iam/policies/:id` return `400 VALIDATION_ERROR` naming the offending operator and listing the supported set — an admin can no longer save a policy with an operator the engine can't evaluate.
- **Fail-closed at evaluation time**: `evaluateConditions` still treats any operator outside this set as a denial (defense in depth, in case a statement reaches the engine by a path other than the write API — e.g. a stale row).

## 4. Operational Logging vs Audit Trail
- **Operational Logs**: Diagnostic logs for developer visibility (e.g. `iam.permission.evaluated`, `iam.user.status_updated`).
- **Audit Logs**: Durable database records for security compliance (`iam_audit_logs` table tracking administrative mutations).

## 5. Route Guards Convention
```typescript
import { requirePermission, requireAuthentication } from '@packages/iam';

// Require login
fastify.get('/profile', { preHandler: [requireAuthentication()] }, handler);

// Require specific permission
fastify.get('/users', { preHandler: [requirePermission('users:read')] }, handler);

// Require self-resource ownership
fastify.put('/users/:id', {
  preHandler: [
    requirePermission('users:update', (req) => ({ resourceOwnerId: req.params.id })),
  ],
}, handler);
```

## 6. Mandatory Testing Expectations
Every authorization change requires:
1. **Allow Cases**: Legitimate permissions allow operation.
2. **Deny Precedence**: Explicit `DENY` statement strictly overrides any matching `ALLOW`.
3. **Ownership Verification**: Resource-level ownership tests (`owner -> allowed`, `other user -> 403`, `unauthenticated -> 401`).
4. **Privilege Escalation Defense**: Negative tests proving normal external users cannot grant themselves permissions or access admin routes.
5. **Tenant Isolation**: For every new IAM method or route, a test where tenant A reaches for tenant B's user, role, group or policy and gets 404 — read, update, delete, and attach. Run it against a real database (`createTestDatabase()`), and confirm it fails when the tenant filter is removed.

From Mihir-Rabari/create-odoo-app, MIT.

More from Mihir-Rabari/create-odoo-app