Oxicloud/docs/plan/plan-ReBAC-Permissions-Grants-Cascading.md

# OxiCloud ReBAC — Permissions, Grants, and Cascading

## Context

OxiCloud currently has a binary authorization model: the owner of a folder/file has every permission, every non-owner has none. The only user-to-user sharing is via anonymous token links (`storage.shares`) with three coarse flags (read/write/reshare). There is no way for a user to grant a named user fine-grained access to a folder, and no way to list resources others have shared with them.

This plan introduces a Relationship-Based Access Control (ReBAC) model:

- 6 named permissions: `read`, `create`, `share`, `comment`, `delete`, `update`
- Cascading: a grant on a folder applies to all descendants (sub-folders + files) via the existing `storage.folders.lpath` ltree
- Subjects: `user` (v1), `group` (future placeholder in schema), `token` (anonymous links — unified with existing `storage.shares`), `external` (future in schema for federated identities: Open Cloud Mesh / external OIDC)
- Pluggable engine: a single `AuthorizationEngine` trait, default implementation in PostgreSQL, ready for an `OpenFgaEngine` later
- **Roles** (Viewer, Commenter, Editor, Manager, Admin) as a UX/DTO sugar layer that the server expands into the underlying permission rows — storage and engine know nothing about roles

User decisions confirmed in conversation:
1. **Implicit owner** — owners have no rows in `access_grants`; the engine short-circuits when the caller is the resource's owner.
2. **`share` permission lets the holder grant to other named users** via `POST /api/grants` (not just create anonymous links).
3. **`GET /api/grants/incoming` returns direct grants only** — one row per resource explicitly granted to the caller. UI drills in via existing listing endpoints.
4. **Unify anonymous link shares under `access_grants`** with `subject_type='token'`. `storage.shares` retains token-lifecycle metadata (password, expiry, access count) only; the permission flags move to `access_grants`. One-time data migration.
5. **Roles in v1, implication chains deferred** — roles bundle the 6 raw permissions at the DTO layer (no schema impact). The storage keeps one row per granted permission. Permission implication (e.g., `update` ⊃ `comment` ⊃ `read`) is a Future optimization that compresses storage but doesn't change observable behavior.
6. **6 permissions are final for v1** — `read`, `create`, `share`, `comment`, `delete`, `update`. `download` (preview-only vs full-bytes) is a candidate for v2 if a "view-only" feature is added; trivial ALTER on the CHECK constraint then.
7. **Schema reserves `subject_type='external'` for federated identities** (Open Cloud Mesh / external OIDC). v1 adds the enum value and the `Subject::External(Uuid)` variant; the lookup table `auth.external_subjects` and the federation middleware are deferred.
8. **Architectural rule: AuthZ lives in the service layer, never in handlers.** All permission checks go through `AuthorizationEngine` via service methods. HTTP handlers (REST, WebDAV, NextCloud, CalDAV, CardDAV) authenticate the caller and pass `caller_id` into the service — they do NOT perform their own ownership/permission checks. This rule must be documented in `CLAUDE.md`.
9. **Per-row storage, not bitmap.** One row per `(subject, resource, permission)` rather than a single row with a packed bitmap. Preserves per-permission `granted_at` and `granted_by` (audit value), keeps future per-grant `expires_at` an easy addition, and maps 1:1 to OpenFGA tuples. Storage cost at OxiCloud's scale is acceptable and not on a hot path — micro-optimization deferred indefinitely. Matches the per-tuple shape used by Zanzibar, SpiceDB, OpenFGA, Permify.

Out-of-scope (deferred):
- Group creation & membership UI (the schema reserves `subject_type='group'`, but no group CRUD endpoints in this plan)
- External-user federation (`subject_type='external'` reserved in schema; `auth.external_subjects` table + OCM/OIDC federation middleware come later)
- Permission implication graph (`update` ⊃ `comment` ⊃ `read`, etc.) — storage compression with no observable behavior change
- Negative grants / deny rules (model stays additive — union of all applicable grants)
- Grant expiry per-row (token expiry stays on `storage.shares`)
- Comment feature itself (the `comment` permission is reserved; the comments table is a future feature)
- `download` permission (separation of preview-only from full-bytes export)
- Decision caching (in-process + Redis L2) — see "Future: caching layer" below

---

## Architecture overview

```
┌────────────────────┐
│   HTTP handlers    │  POST/GET/DELETE /api/grants
└──────────┬─────────┘
           ▼
┌────────────────────┐
│  FolderService     │ ────► authz.require(caller, Update, Folder(id))
│  FileManagementSvc │ ────► authz.require(caller, Create, Folder(parent))
│  FileRetrievalSvc  │ ────► authz.require(caller, Read,   Folder(id))
│  ShareService      │ ────► token grants written via authz.grant(Token(t), ...)
└──────────┬─────────┘
           ▼  Arc<dyn AuthorizationEngine>
┌─────────────────────────────────────────────┐
│  AuthorizationEngine trait                  │
│   • check(subject, perm, resource) → bool   │
│   • require(...)                            │
│   • grant / revoke                          │
│   • list_incoming / list_on_resource        │
└──────────┬────────────────────────┬─────────┘
           ▼                        ▼
  PgAclEngine (v1, default)   OpenFgaEngine (future)
       ▼
  storage.access_grants  +  storage.folders.lpath (cascading)
```

---

## Schema

### New table: `storage.access_grants`

```sql
CREATE TABLE storage.access_grants (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),

    -- Subject (who has the permission)
    -- 'user'     — auth.users.id
    -- 'group'    — future: group membership
    -- 'token'    — refers to storage.shares.id (anonymous link)
    -- 'external' — future: refers to auth.external_subjects.id (OCM / federated OIDC)
    subject_type    TEXT NOT NULL CHECK (subject_type IN ('user', 'group', 'token', 'external')),
    subject_id      UUID NOT NULL,

    -- Resource (what the permission is on)
    resource_type   TEXT NOT NULL CHECK (resource_type IN ('folder', 'file')),
    resource_id     UUID NOT NULL,

    -- Permission (what action is allowed)
    permission      TEXT NOT NULL CHECK (permission IN
                      ('read', 'create', 'share', 'comment', 'delete', 'update')),

    -- Audit
    granted_by      UUID NOT NULL,                              -- user_id who created the grant
    granted_at      TIMESTAMPTZ NOT NULL DEFAULT now(),

    UNIQUE (subject_type, subject_id, resource_type, resource_id, permission)
);

CREATE INDEX idx_grants_subject  ON storage.access_grants (subject_type, subject_id);
CREATE INDEX idx_grants_resource ON storage.access_grants (resource_type, resource_id);
```

`granted_by` is always a user (group cannot grant). No FK to `auth.users` on `subject_id` or `granted_by` — those tables are in a different schema and the values are polymorphic.

### Cleanup of `storage.shares`

The permission columns move to `access_grants`. `storage.shares` keeps token-lifecycle metadata.

```sql
-- After data migration (below):
ALTER TABLE storage.shares
    DROP COLUMN permissions_read,
    DROP COLUMN permissions_write,
    DROP COLUMN permissions_reshare;
```

### Data migration (one-off, in the same migration file)

Each existing share becomes one or more rows in `access_grants` with `subject_type='token'`, `subject_id=shares.id`:

```sql
INSERT INTO storage.access_grants
    (subject_type, subject_id, resource_type, resource_id, permission, granted_by)
SELECT 'token', s.id, s.item_type, s.item_id::uuid, 'read', s.created_by
  FROM storage.shares s
 WHERE s.permissions_read;

-- 'write' on the old model implies full mutation rights for the link holder.
-- Mapped to read + create + update + delete in the new model.
INSERT INTO storage.access_grants (subject_type, subject_id, resource_type, resource_id, permission, granted_by)
SELECT 'token', s.id, s.item_type, s.item_id::uuid, p.perm, s.created_by
  FROM storage.shares s
  CROSS JOIN (VALUES ('create'), ('update'), ('delete')) AS p(perm)
 WHERE s.permissions_write;

INSERT INTO storage.access_grants (subject_type, subject_id, resource_type, resource_id, permission, granted_by)
SELECT 'token', s.id, s.item_type, s.item_id::uuid, 'share', s.created_by
  FROM storage.shares s
 WHERE s.permissions_reshare;
```

---

## Lifecycle and grant cleanup (v1 — correctness requirement)

When a resource or subject is **permanently** deleted, all `access_grants` rows referring to it must be removed. Otherwise:
- Orphan grants linger forever
- A future UUID reuse (unlikely but possible) could match a stale row
- "Shared with me" returns grants on resources that no longer exist
- Audit queries (`COUNT(*) FROM access_grants`) drift away from reality

### What triggers cleanup, and what doesn't

| Event | Affected grants | Action |
|---|---|---|
| Folder **permanently** deleted | `resource_type='folder', resource_id=F` (plus all descendant files via FK cascade chain) | DELETE |
| File **permanently** deleted | `resource_type='file', resource_id=X` | DELETE |
| Folder/file moved to **trash** (soft) | None | **No-op** — restore must resume access |
| Folder/file **restored** from trash | None | No-op |
| Trash **emptied** (permanent destruction) | Same as permanent delete | DELETE |
| User deleted | `subject_type='user', subject_id=U`. `granted_by=U` is left as-is (audit trail). | DELETE the subject rows; keep granter UUIDs |
| Anonymous share token deleted | `subject_type='token', subject_id=T` | DELETE |
| Group deleted (future) | `subject_type='group', subject_id=G` | DELETE |

### Defense-in-depth: DB triggers in the same migration

Even if a future code path bypasses the service layer (admin scripts, bulk maintenance, manual SQL), the database enforces cleanup:

```sql
CREATE OR REPLACE FUNCTION storage.cleanup_grants_on_resource_delete()
RETURNS TRIGGER AS $$
BEGIN
    DELETE FROM storage.access_grants
     WHERE resource_type = TG_ARGV[0]
       AND resource_id   = OLD.id;
    RETURN OLD;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER trg_cleanup_grants_folder
    AFTER DELETE ON storage.folders
    FOR EACH ROW
    EXECUTE FUNCTION storage.cleanup_grants_on_resource_delete('folder');

CREATE TRIGGER trg_cleanup_grants_file
    AFTER DELETE ON storage.files
    FOR EACH ROW
    EXECUTE FUNCTION storage.cleanup_grants_on_resource_delete('file');

CREATE OR REPLACE FUNCTION storage.cleanup_grants_on_subject_delete()
RETURNS TRIGGER AS $$
BEGIN
    DELETE FROM storage.access_grants
     WHERE subject_type = TG_ARGV[0]
       AND subject_id   = OLD.id;
    RETURN OLD;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER trg_cleanup_grants_user
    AFTER DELETE ON auth.users
    FOR EACH ROW
    EXECUTE FUNCTION storage.cleanup_grants_on_subject_delete('user');

CREATE TRIGGER trg_cleanup_grants_token
    AFTER DELETE ON storage.shares
    FOR EACH ROW
    EXECUTE FUNCTION storage.cleanup_grants_on_subject_delete('token');
```

`storage.files.folder_id REFERENCES storage.folders(id) ON DELETE CASCADE` already exists — when a folder is permanently deleted, the file trigger fires for each cascaded child. No need to walk the ltree subtree manually.

### Application-layer cleanup (explicit hooks)

The trait gains two cleanup methods so the application layer can invoke cleanup explicitly. This matters because a future cache layer (see Future section) needs to see the invalidation event at the engine boundary — DB triggers happen below the cache:

```rust
/// Removes all grants targeting this resource. Returns count removed.
async fn revoke_all_for_resource(&self, resource: Resource)
    -> Result<usize, DomainError>;

/// Removes all grants where this subject is the holder.
async fn revoke_all_for_subject(&self, subject: Subject)
    -> Result<usize, DomainError>;
```

Service call sites:

| Service method | Cleanup call |
|---|---|
| `FolderService::delete_folder_with_perms` (permanent delete) | `authz.revoke_all_for_resource(Folder(id))` |
| `FileManagementService::delete_file_with_perms` | `authz.revoke_all_for_resource(File(id))` |
| `FileManagementService::delete_and_cleanup_with_perms` | Same |
| `TrashService::delete_permanently` | `authz.revoke_all_for_resource(...)` per item |
| `TrashService::empty_trash` | Loop over items, same call |
| `TrashService::move_to_trash` | **No cleanup** (soft delete; grants preserved for eventual restore) |
| `TrashService::restore_item` | No action (grants are still there) |
| `ShareService::delete_shared_link` | `authz.revoke_all_for_subject(Token(share_id))` |
| `AuthApplicationService::delete_user` (admin) | `authz.revoke_all_for_subject(User(user_id))` |

DB triggers stay as defense-in-depth — they catch anything the application forgets, and they catch bulk maintenance operations. The application-layer hook is the canonical path; the trigger is the safety net.

### File lifecycle hook integration

There's an existing `FileDeletedHook` trait in `src/application/ports/file_lifecycle.rs` that already fires after permanent file deletion (used today for blob-ref-count decrement). Implement an additional hook:

```rust
struct GrantCleanupHook { authz: Arc<dyn AuthorizationEngine> }

#[async_trait::async_trait]
impl FileDeletedHook for GrantCleanupHook {
    async fn on_file_deleted(&self, file_id: Uuid) -> Result<(), DomainError> {
        self.authz.revoke_all_for_resource(Resource::File(file_id)).await?;
        Ok(())
    }
}
```

Register it in `common/di.rs` alongside the existing hooks. The folder/user/token cases get inline calls in their respective services (no hook trait for those yet — adding one if it's needed for a third caller is a future refactor).

### Verification — lifecycle scenarios in `grants.hurl`

1. **Resource delete clears grants**
   - Alice creates folder F, grants Bob read, then permanently deletes F (via empty trash)
   - Bob's `GET /api/grants/incoming` returns 0 entries containing F
   - Direct SQL check (in a debug endpoint or via a test fixture): `SELECT COUNT(*) FROM access_grants WHERE resource_id = F` is 0

2. **Trash retains grants**
   - Alice grants Bob read on F, moves F to trash, then restores F
   - Bob still has `read` access after restore (regression: before any lifecycle change, this must continue to work)

3. **User delete clears subject grants but preserves granter**
   - Alice grants Bob and Carol read on F. Admin deletes Bob.
   - Carol's grant on F survives; her `granted_by=alice` still references Alice (intact)
   - Bob's row is gone

4. **Token delete clears token grants**
   - Alice creates a public share link on F → `access_grants` has rows with `subject_type='token'`
   - Alice deletes the share link → token rows in `access_grants` are gone

5. **Orphan invariant (post-test SQL)**
   ```sql
   SELECT COUNT(*) FROM storage.access_grants g
    WHERE (g.resource_type = 'folder'
           AND NOT EXISTS (SELECT 1 FROM storage.folders WHERE id = g.resource_id))
       OR (g.resource_type = 'file'
           AND NOT EXISTS (SELECT 1 FROM storage.files WHERE id = g.resource_id));
   ```
   Must always be 0 after every Hurl run.

---

## Domain types

New module `src/domain/services/authorization.rs`:

```rust
use uuid::Uuid;

#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
pub enum Subject {
    User(Uuid),
    Group(Uuid),     // schema reserved, no CRUD endpoints in v1
    Token(Uuid),     // refers to storage.shares.id
    External(Uuid),  // future: refers to auth.external_subjects.id (OCM / federated OIDC)
}

#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
pub enum Resource {
    Folder(Uuid),
    File(Uuid),
}

#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
pub enum Permission {
    Read, Create, Share, Comment, Delete, Update,
}

pub struct Grant {
    pub id: Uuid,
    pub subject: Subject,
    pub resource: Resource,
    pub permission: Permission,
    pub granted_by: Uuid,
    pub granted_at: chrono::DateTime<chrono::Utc>,
}
```

Conversion helpers (`as_str()` for SQL binding, `TryFrom<&str>` for row decoding) live alongside.

---

## Port: `AuthorizationEngine`

New file `src/application/ports/authorization_ports.rs`:

```rust
use crate::common::errors::DomainError;
use crate::domain::services::authorization::{Grant, Permission, Resource, Subject};

#[async_trait::async_trait]
pub trait AuthorizationEngine: Send + Sync + 'static {
    /// Returns true if `subject` has `permission` on `resource`,
    /// considering owner short-circuit AND cascading from folder ancestors.
    async fn check(
        &self,
        subject: Subject,
        permission: Permission,
        resource: Resource,
    ) -> Result<bool, DomainError>;

    /// Convenience: returns Ok(()) when check passes; DomainError::not_found
    /// otherwise (anti-enumeration — same error for "no such resource" and
    /// "exists but you can't see it").
    async fn require(
        &self,
        subject: Subject,
        permission: Permission,
        resource: Resource,
    ) -> Result<(), DomainError> {
        if self.check(subject, permission, resource).await? {
            Ok(())
        } else {
            let (kind, id) = match resource {
                Resource::Folder(id) => ("Folder", id),
                Resource::File(id)   => ("File", id),
            };
            Err(DomainError::not_found(kind, id.to_string()))
        }
    }

    /// Resources explicitly granted to `subject`. Direct grants only — no
    /// cascade expansion. Used by GET /api/grants/incoming.
    async fn list_incoming_grants(
        &self,
        subject: Subject,
        permission_filter: Option<Permission>,
    ) -> Result<Vec<Grant>, DomainError>;

    /// All grants on a specific resource (for "Manage sharing" UI).
    /// Caller-side must verify the caller has `share` on the resource.
    async fn list_grants_on_resource(
        &self,
        resource: Resource,
    ) -> Result<Vec<Grant>, DomainError>;

    /// Idempotent (UNIQUE constraint absorbs duplicates).
    async fn grant(
        &self,
        granted_by: Uuid,
        subject: Subject,
        permission: Permission,
        resource: Resource,
    ) -> Result<Grant, DomainError>;

    /// Revoke by id.
    async fn revoke(&self, grant_id: Uuid) -> Result<(), DomainError>;
}
```

Wired into `AppState` in `src/common/di.rs` as `pub authorization: Arc<dyn AuthorizationEngine>`. The factory selects the implementation from `OXICLOUD_AUTHZ_ENGINE` env var (default: `postgres`).

---

## PgAclEngine implementation

New file `src/infrastructure/services/pg_acl_engine.rs`. Holds `Arc<DbPools>`, `Arc<FolderDbRepository>`, `Arc<FileBlobReadRepository>` (for owner lookups).

### `check()` algorithm

```rust
async fn check(&self, subject: Subject, perm: Permission, resource: Resource) -> Result<bool, _> {
    // Step 1 — owner short-circuit (only for user subjects)
    if let Subject::User(uid) = subject {
        let owner = match resource {
            Resource::Folder(id) => self.folder_repo.get_folder_user_id(&id.to_string()).await?,
            Resource::File(id)   => self.file_repo.get_file_user_id(&id.to_string()).await?,
        };
        if owner == uid { return Ok(true); }
    }

    // Step 2 — direct or cascading grant via SQL
    self.grant_exists(subject, perm, resource).await
}
```

### Cascading SQL — folders

```sql
SELECT EXISTS (
    SELECT 1
      FROM storage.access_grants g
      JOIN storage.folders gf ON gf.id = g.resource_id
     WHERE g.subject_type = $1 AND g.subject_id = $2
       AND g.permission   = $3
       AND g.resource_type = 'folder'
       AND gf.lpath @> (SELECT lpath FROM storage.folders WHERE id = $4)
)
```

`gf.lpath @> target.lpath` means "gf is an ancestor of (or equal to) target". Uses the existing GiST index `idx_folders_lpath` — O(log N).

### Cascading SQL — files

A file inherits from its containing folder. Two-branch query:

```sql
SELECT EXISTS (
    -- direct file grant
    SELECT 1 FROM storage.access_grants
     WHERE subject_type = $1 AND subject_id = $2 AND permission = $3
       AND resource_type = 'file' AND resource_id = $4
    UNION ALL
    -- cascading from any ancestor folder of the file's containing folder
    SELECT 1
      FROM storage.access_grants g
      JOIN storage.folders gf      ON gf.id = g.resource_id
      JOIN storage.files target_f  ON target_f.id = $4
     WHERE g.subject_type = $1 AND g.subject_id = $2
       AND g.permission = $3
       AND g.resource_type = 'folder'
       AND target_f.folder_id IS NOT NULL
       AND gf.lpath @> (SELECT lpath FROM storage.folders WHERE id = target_f.folder_id)
)
```

Files at root (`folder_id IS NULL`) only match the direct branch.

### Engine selection in `AppState`

```rust
// src/common/di.rs (build_app_state)
let authz: Arc<dyn AuthorizationEngine> = match env::var("OXICLOUD_AUTHZ_ENGINE").as_deref() {
    Ok("openfga") => unimplemented!("OpenFgaEngine — future"),
    _ => Arc::new(PgAclEngine::new(
        pools.clone(),
        repositories.folder_repository.clone(),
        repositories.file_read_repository.clone(),
    )),
};
```

---

## Service integration

Each `*_with_perms` method already calls `verify_owner`. Replace the call with `authz.require(...)`. The semantics broaden (grants count, not just ownership) but the signature and error mapping stay the same.

### Folder permission mapping (folder_service.rs)

| Method | Permission(s) checked |
|---|---|
| `create_folder_with_perms(dto, caller)` | `Create` on `Folder(parent_id)` |
| `get_folder_with_perms(id, caller)` | `Read` on `Folder(id)` |
| `rename_folder_with_perms(id, dto, caller)` | `Update` on `Folder(id)` |
| `move_folder_with_perms(id, dto, caller)` | `Update` on `Folder(id)` AND `Create` on `Folder(new_parent)` |
| `delete_folder_with_perms(id, caller)` | `Delete` on `Folder(id)` |

### File permission mapping (file_management_service.rs)

| Method | Permission(s) checked |
|---|---|
| `move_file_with_perms(file_id, caller, target)` | `Update` on `File(file_id)` AND `Create` on `Folder(target)` if target is Some |
| `copy_file_with_perms(file_id, caller, target)` | `Read` on `File(file_id)` AND `Create` on `Folder(target)` if target is Some |
| `rename_file_with_perms(file_id, caller, name)` | `Update` on `File(file_id)` |
| `delete_file_with_perms(id, caller)` | `Delete` on `File(id)` |
| `copy_folder_tree_with_perms(src, caller, target, name)` | `Read` on `Folder(src)` AND `Create` on `Folder(target)` if target is Some |

### File retrieval mapping (file_retrieval_service.rs)

`get_file_owned`, `list_files_owned`, `get_file_stream_owned`, `get_file_optimized_owned`, `get_file_range_stream_owned`, `list_files_batch_for_owner` → each becomes `authz.require(caller, Read, File(id))` before delegating to the unchecked variant.

### Path-based lookups (currently unchecked IDOR risk)

`folder_service::get_folder_by_path(path)` and `file_retrieval_service::get_file_by_path(path)` resolve a path then return the resource without any check. After this plan: resolve, then `authz.require(caller, Read, …)`. This closes a known IDOR documented in the previous plan's "Out of scope" section.

### Owner short-circuit ensures zero behavior change for current users

Because every existing user-vs-own-resource interaction is an owner check, the engine's owner short-circuit makes those calls equivalent to the current `verify_owner`. No grant lookups on the hot path until a real cross-user grant exists.

---

## REST endpoints

New handler `src/interfaces/api/handlers/grant_handler.rs`. Registered under `/api/grants`.

### `POST /api/grants` — create a grant

```json
{
  "subject":  { "type": "user",   "id": "<uuid>" },
  "resource": { "type": "folder", "id": "<uuid>" },
  "permissions": ["read", "comment"]
}
```

Behavior:
1. Authenticated caller required.
2. `authz.require(caller, Share, resource)` — caller must have `share` on the resource (owners always pass via short-circuit).
3. For each permission in the list: `authz.grant(caller_id, subject, perm, resource)`. UNIQUE constraint makes repeats no-ops.
4. Returns 201 with the list of created/existing grants.

### `DELETE /api/grants/{id}` — revoke a grant

1. Look up the grant.
2. Allow if caller is the grant's `granted_by` user OR caller has `share` on the underlying resource.
3. `authz.revoke(id)`.
4. Returns 204.

### `GET /api/grants/incoming?permission=read&type=folder` — what others have shared with me

Direct grants only (per user decision). Subject is the authenticated caller's `User(id)`. Optional filters by permission and resource type.

Returns:
```json
[
  {
    "id": "<grant-uuid>",
    "resource": { "type": "folder", "id": "<uuid>", "name": "Photos", "path": "..." },
    "permission": "read",
    "granted_by": { "id": "<uuid>", "username": "alice" },
    "granted_at": "2026-05-20T10:51:13Z"
  }
]
```

Resource name/path is enriched via a JOIN to `storage.folders` / `storage.files`.

### `GET /api/grants?resource_type=folder&resource_id={id}` — list grants on a resource

Requires `authz.require(caller, Share, resource)` (you can see who has access only if you can manage sharing).

Returns the same shape as incoming, but for the specified resource.

### `GET /api/grants/outgoing` — grants I have created

Filtered by `granted_by = caller_id`. Useful for "Manage all my shares" UI.

---

## Roles (UX / DTO layer)

Roles are **preset bundles of permissions** that the API exposes for UI convenience. The server expands a role into its underlying permission list before writing rows; storage and engine know nothing about roles.

### Role catalog

| Role | Permissions |
|---|---|
| `Viewer`    | `read` |
| `Commenter` | `read`, `comment` |
| `Editor`    | `read`, `comment`, `create`, `update` |
| `Manager`   | `read`, `comment`, `create`, `update`, `share` |
| `Admin`     | `read`, `comment`, `create`, `update`, `share`, `delete` |

Defined as a Rust enum in `src/application/dtos/grant_dto.rs`:

```rust
#[derive(Clone, Copy, Debug, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Role { Viewer, Commenter, Editor, Manager, Admin }

impl Role {
    pub fn expand(self) -> &'static [Permission] {
        match self {
            Role::Viewer    => &[Permission::Read],
            Role::Commenter => &[Permission::Read, Permission::Comment],
            Role::Editor    => &[Permission::Read, Permission::Comment,
                                 Permission::Create, Permission::Update],
            Role::Manager   => &[Permission::Read, Permission::Comment,
                                 Permission::Create, Permission::Update,
                                 Permission::Share],
            Role::Admin     => &[Permission::Read, Permission::Comment,
                                 Permission::Create, Permission::Update,
                                 Permission::Share, Permission::Delete],
        }
    }
}
```

### `POST /api/grants` accepts either shape

```json
// Either explicit permissions:
{ "subject":  { "type": "user", "id": "<uuid>" },
  "resource": { "type": "folder", "id": "<uuid>" },
  "permissions": ["read", "comment"] }

// Or a role:
{ "subject":  { "type": "user", "id": "<uuid>" },
  "resource": { "type": "folder", "id": "<uuid>" },
  "role": "editor" }
```

The DTO uses `#[serde(untagged)]` or two separate fields with server-side validation that exactly one is provided. Server expands `role` → permission list, then writes the rows.

### `PUT /api/grants/role` — reconcile a subject's role on a resource

```json
{ "subject":  { "type": "user", "id": "<uuid>" },
  "resource": { "type": "folder", "id": "<uuid>" },
  "role": "manager" }
```

Behavior:
1. `authz.require(caller, Share, resource)`.
2. Read the current set of permissions held by `subject` on `resource`.
3. Compute the diff vs `role.expand()`: which permissions to INSERT, which to DELETE.
4. Apply both in one transaction.
5. Returns 200 with the new full set.

This is the canonical way for a UI to set "Bob is now Editor of /Photos" — the frontend doesn't track which specific rows exist.

### Why roles are pure DTO sugar (not stored)

- **Roles can evolve without schema migrations** — adding "Reviewer" tomorrow is a code change, no ALTER.
- **Mixing is allowed** — a future UI can start from "Editor" and add `share` manually; the result is a custom mixture, not "Editor + share".
- **OpenFGA migration unaffected** — tuples are per-permission regardless of how they were granted.
- **Revocation is granular** — removing a single permission doesn't require touching a "role" abstraction.

---

## File changes

### New files
- `migrations/2026MMDDHHMMSS_rebac_access_grants.sql` — table + indexes + data migration from `storage.shares`
- `src/domain/services/authorization.rs` — `Subject` (including `External` variant), `Resource`, `Permission`, `Grant` enums/structs
- `src/application/ports/authorization_ports.rs` — `AuthorizationEngine` trait
- `src/infrastructure/services/pg_acl_engine.rs` — default impl
- `src/interfaces/api/handlers/grant_handler.rs` — REST endpoints (`POST/DELETE/GET /api/grants`, `PUT /api/grants/role`, `GET /api/grants/incoming|outgoing`)
- `src/application/dtos/grant_dto.rs` — request/response DTOs including `Role` enum + `Role::expand()`

### Modified
- `CLAUDE.md` — add a section under the Backend Architecture documenting the rule: **AuthZ is enforced exclusively in the application service layer. HTTP handlers (REST, WebDAV, NextCloud, CalDAV, CardDAV) only authenticate the caller and pass `caller_id` to the service. Never duplicate permission checks at the exposition layer.** This prevents drift between layers and matches the existing pattern of `*_with_perms` methods.
- `src/common/di.rs` — wire `authz` into `AppState`; inject into Folder/FileManagement/FileRetrieval services
- `src/application/services/folder_service.rs` — replace `verify_owner` calls with `authz.require`; add path-based check to `get_folder_by_path`
- `src/application/services/file_management_service.rs` — same; remove the private `verify_target_folder_owner` wrapper (engine does both)
- `src/application/services/file_retrieval_service.rs` — replace owner checks; add path-based check to `get_file_by_path`
- `src/application/services/share_service.rs` — on `create_shared_link`, also write the corresponding `access_grants` rows so that token-based access goes through the engine uniformly
- `src/interfaces/api/routes.rs` — register `/api/grants` routes
- `src/application/ports/mod.rs` — `pub mod authorization_ports`
- `src/domain/services/mod.rs` — `pub mod authorization`
- `src/infrastructure/services/mod.rs` — `pub mod pg_acl_engine`

### Removed
- The fields `permissions_read`, `permissions_write`, `permissions_reshare` from `storage.shares` (and their domain/dto representations) — replaced by `access_grants` rows. Migration script preserves existing data.

---

## Verification

### Build & lint
```
cargo fmt --all
cargo clippy --all-features --all-targets -- -D warnings
cargo test --workspace
```

### Hurl integration tests (new file `tests/api/grants.hurl`)

Run via the existing `tests/api/run.sh` (add `permissions.hurl` AND the new `grants.hurl` to the runner).

Setup (admin token + bob token, both already available from `permissions.hurl`):

1. **Grant + check**
   - Alice creates folder `/api/folders {parent: home, name: "Shared"}` → captures `folder_id`
   - Alice grants Bob `read` on the folder: `POST /api/grants` with subject=user/bob, resource=folder/Shared, perms=[read]
   - Bob calls `GET /api/folders/{folder_id}/contents` → 200 (was 404 before grant)
   - Bob calls `PUT /api/folders/{folder_id}/rename` → 404 (no `update` grant)

2. **Cascading**
   - Alice creates a sub-folder `Shared/Inner`
   - Alice uploads a file `vacation.jpg` inside `Inner`
   - Bob (with `read` on `Shared`) calls `GET /api/files/{file_id}` → 200 (cascaded via lpath)

3. **Incoming list**
   - Bob calls `GET /api/grants/incoming` → returns 1 entry with the folder, permission=read

4. **Re-share**
   - Carol (new user) — Alice grants Bob `share` additionally
   - Bob now successfully calls `POST /api/grants` to grant Carol `read`
   - Carol calls `GET /api/folders/{folder_id}/contents` → 200

5. **Revoke**
   - Alice deletes Bob's grant via `DELETE /api/grants/{grant_id}` → 204
   - Bob's `GET /api/folders/{folder_id}/contents` → 404

6. **Roles**
   - Alice grants `POST /api/grants` with `role: "editor"` for Bob on a new folder
   - Bob can read AND rename a file inside (Editor includes `update`)
   - Bob CANNOT delete the folder (Editor excludes `delete`) → 404
   - Alice calls `PUT /api/grants/role` with `role: "admin"` for Bob
   - Bob can now delete the folder → 200
   - Alice calls `PUT /api/grants/role` with `role: "viewer"` for Bob
   - Bob loses update/delete/comment/create/share; can only read → rename returns 404

7. **Token unification (regression)**
   - `permissions.hurl` already covers existing share-link flows. After migration, those still pass — the engine reads from `access_grants` for token subjects, transparently.

### Unit tests
- New tests in `src/application/services/idor_protection_test.rs`:
  - `engine.check(non_owner, Read, file)` with no grant → false
  - `engine.check(owner, _, _)` → true (owner short-circuit) without touching `access_grants`
  - `engine.check(grantee, Read, file)` after `grant()` → true
  - Cascade: grant on parent folder → child file check returns true
  - Revoke removes the row → next check returns false
- Tests use a stub repo for owners and an in-memory grant store, OR run against the real PG via the existing test harness.

### Storage growth sanity check (manual)
- Before migration: count rows in `storage.shares`.
- After migration: count rows in `storage.access_grants` with `subject_type='token'` ≈ shares × {1 + flag count}.
- Confirm no owner-self rows were created (validates implicit-owner choice).

---

## Rollout sequencing

1. **PR 1** — migration + schema (creates `access_grants`, migrates `storage.shares` permission flags). No code changes yet. Deploy and verify the migration runs cleanly.
2. **PR 2** — `AuthorizationEngine` trait + `PgAclEngine` + DI wiring. No services changed yet — engine is built but unused.
3. **PR 3** — service integration. Replace `verify_owner` with `authz.require` in `*_with_perms` methods. Add path-based checks. Hurl integration: `permissions.hurl` must still pass (engine's owner short-circuit ensures no behavior change for existing flows).
4. **PR 4** — REST endpoints (`/api/grants/*`) + new `grants.hurl` tests covering cross-user grant/revoke/cascade scenarios.
5. **PR 5** — `share_service` writes `access_grants` rows for new token shares (so token authz goes through the engine). At this point `storage.shares.permissions_*` columns are no longer read from anywhere — drop them.

Each PR is independently mergeable and the system stays functional throughout. PR 1-3 ship with zero observable change to users; PR 4 introduces the new feature; PR 5 retires the dead columns.

---

## Future: caching layer (in-process + Redis)

### Why

Every mutating service operation calls `authz.require(...)` at least once. The cascading SQL (`gf.lpath @> target.lpath` joined against `access_grants`) is O(log N) per check thanks to the GiST index, but at scale these costs compound:

- A batch delete of 1000 files = 1000 checks
- WebDAV PROPFIND on a deep folder may call `read` for every descendant
- A user with many active sessions hammers the same `(subject, perm, resource)` repeatedly
- Cascading means even a "no" answer requires walking the full ancestor chain — short-circuited only when the GiST index returns empty

A cache changes the cost of repeat checks from "JOIN + ltree GiST lookup" to "HashMap get" (L1) or "Redis GET" (L2). For mostly-read workloads, hit rate should be very high.

### Architecture — decorator over the trait

The `AuthorizationEngine` trait is unchanged. A `CachedAuthorizationEngine` wraps any underlying engine:

```rust
pub struct CachedAuthorizationEngine<E: AuthorizationEngine> {
    inner: E,
    l1: moka::future::Cache<DecisionKey, bool>,   // in-process, fast, per-instance
    l2: Option<Arc<dyn DistributedCache>>,         // Redis (or similar), shared across instances
}

#[derive(Hash, Eq, PartialEq, Clone)]
struct DecisionKey {
    subject: Subject,
    permission: Permission,
    resource: Resource,
}

impl<E: AuthorizationEngine> AuthorizationEngine for CachedAuthorizationEngine<E> {
    async fn check(&self, subject: Subject, perm: Permission, resource: Resource)
        -> Result<bool, DomainError>
    {
        let key = DecisionKey { subject, permission: perm, resource };

        // L1: in-process
        if let Some(decision) = self.l1.get(&key).await { return Ok(decision); }

        // L2: Redis
        if let Some(l2) = &self.l2
            && let Some(decision) = l2.get(&key).await? {
            self.l1.insert(key.clone(), decision).await;
            return Ok(decision);
        }

        // Miss — query the underlying engine and backfill
        let decision = self.inner.check(subject, perm, resource).await?;
        self.l1.insert(key.clone(), decision).await;
        if let Some(l2) = &self.l2 {
            l2.set(&key, decision, CACHE_TTL).await?;
        }
        Ok(decision)
    }

    async fn grant(...) -> Result<Grant, _> {
        let g = self.inner.grant(...).await?;
        self.invalidate_for(g.subject, g.resource).await;
        Ok(g)
    }

    async fn revoke(...) -> Result<(), _> {
        self.inner.revoke(...).await?;
        // need the affected (subject, resource) — revoke() takes only grant_id today,
        // so the trait gains a small helper or returns the deleted grant for invalidation.
        Ok(())
    }
}
```

### Three tiers worth distinguishing

1. **Per-request cache** (cheapest to ship). A `HashMap<DecisionKey, bool>` lives in a request extension. Cleared at request end. Avoids repeat checks during a single batch op (e.g., a 1000-file delete only hits the DB once per unique `(subject, perm, file)`). No invalidation problem — request scope.

2. **In-process L1** (`moka::future::Cache`). Bounded LRU with TTL. Per-server-instance. Hit on hot resources, no network. Invalidated on local `grant`/`revoke`.

3. **Distributed L2** (Redis). Shared across multiple OxiCloud server instances. Worth adding only when running multi-instance (HA / horizontal scale). Cross-instance invalidation via Redis pub/sub or short TTL.

### Invalidation — the hard part

Cascading makes per-key invalidation hard. When Alice grants Bob `read` on folder F:

- Bob's `read` on F becomes true → invalidate `(bob, read, F)`
- Bob's `read` on every descendant of F also becomes true (live cascade) → invalidate `(bob, read, child)` for every child

There's no efficient way to enumerate all descendants and invalidate each entry. Three pragmatic options:

| Strategy | Granularity | Implementation cost | Trade-off |
|---|---|---|---|
| **Subject-scoped flush** | All cached entries for `subject` regardless of resource | Cheap (one `bucket -> drop`) | Coarse — bob's checks on unrelated resources also dropped |
| **Resource-scoped flush** | All entries on `resource` and its descendants | Need to walk ltree on invalidation OR mark a "version" on the folder root | More targeted but more code |
| **Short TTL + eventual consistency** | None — wait for TTL | Trivial | Stale `true` after revoke for up to TTL seconds (bad), stale `false` after grant for up to TTL seconds (mildly annoying) |

Recommendation when this lands: subject-scoped flush as the simple default; switch to resource-scoped flush if subject churn is too painful for cache hit rate.

### Cache key normalization for cascading

Important detail: the cached entry for "bob can read folder F" doesn't need a separate entry per descendant. The engine's `check(bob, read, child)` would still go through the SQL because the cache key is `(bob, read, child)`, distinct from `(bob, read, F)`. So caching gives no descendant boost UNLESS we:

- Pre-resolve to "bob's effective grants" once (list all `(subject_id, permission, resource_id)` rows for bob) and cache that bundle, then evaluate any `check()` against the in-memory bundle. This is a classic Zanzibar-style "user list" cache.

That's a separate L1 design: cache the **bundle** of bob's grants, not individual decisions. Hit rate is high (one cached blob per active user). Invalidation is per-subject (when bob receives/loses a grant). The check becomes "is the requested resource an ltree descendant of any folder in bob's grant bundle?" — done in process, no DB round-trip.

This is probably the right L1 shape for OxiCloud given the cascade semantics.

### Config

```rust
// In OxiCloud config:
OXICLOUD_AUTHZ_CACHE=disabled  // default in v1
OXICLOUD_AUTHZ_CACHE=in_memory // L1 only
OXICLOUD_AUTHZ_CACHE=redis     // L1 + L2 (requires OXICLOUD_REDIS_URL)
OXICLOUD_AUTHZ_CACHE_TTL=300   // seconds
```

The engine selection in `common/di.rs` wraps the underlying `PgAclEngine` based on this config. Disabled by default to keep v1 minimal.

### Why this is a clean follow-up, not v1

- The `AuthorizationEngine` trait is unchanged → the cache is a pure decorator
- Owner short-circuit already avoids the DB for the most common case (caller acting on own resources) — caching's marginal value is highest only once cross-user grants are common
- Adding caching too early hides whether the uncached SQL is actually slow at production scale; better to measure first
- Redis adds a new infrastructure dependency; introducing it before there's measured pressure is premature

### When to revisit

Add per-request cache when batch ops show repeated DB checks in tracing. Add L1 in-process cache when single-instance `check` p99 latency exceeds a threshold under cross-user workloads. Add L2 Redis only when running multi-instance and cross-instance cache coherence becomes a hit-rate problem.

---

## Future (v2): extend ReBAC to calendars, address books, playlists

Three resource types already have user-to-user sharing implemented as bespoke per-feature tables. After v1 proves the engine shape on files/folders, absorb them in a follow-up plan per resource type.

### Existing share infrastructure to migrate

| Resource | Today's share table | Today's permission shape |
|---|---|---|
| Calendar (CalDAV) | `caldav.calendar_shares (calendar_id, user_id, access_level)` | `'read' | 'write' | 'owner'` |
| Address book (CardDAV) | `carddav.address_book_shares (address_book_id, user_id, can_write)` | binary `can_write` |
| Playlist (audio) | `audio.playlist_shares (playlist_id, user_id, can_write)` | binary `can_write` |

### Required changes per resource type

Each migration is small and self-contained:

1. **Schema** — extend `resource_type` CHECK constraint:
   ```sql
   ALTER TABLE storage.access_grants
       DROP CONSTRAINT access_grants_resource_type_check,
       ADD  CONSTRAINT access_grants_resource_type_check
            CHECK (resource_type IN ('folder', 'file', 'calendar', 'address_book', 'playlist'));
   ```
2. **Domain** — extend `Resource` enum with `Calendar(Uuid)`, `AddressBook(Uuid)`, `Playlist(Uuid)`.
3. **Engine** — no cascading needed (these are flat containers, not trees). The `check()` SQL becomes a simple direct lookup with no ltree join for these branches.
4. **Service refactor** — remove the bespoke `share_calendar` / `share_address_book` / `share_playlist` methods. Sharing goes through `POST /api/grants` uniformly.
5. **Cleanup triggers** — add AFTER DELETE triggers on `caldav.calendars`, `carddav.address_books`, `audio.playlists` (same pattern as v1 triggers on `storage.folders`/`storage.files`).
6. **Data migration** — convert existing share rows:
   ```sql
   INSERT INTO storage.access_grants (subject_type, subject_id, resource_type, resource_id, permission, granted_by)
   SELECT 'user', cs.user_id, 'calendar', cs.calendar_id, p.perm, c.owner_id
     FROM caldav.calendar_shares cs
     JOIN caldav.calendars c ON c.id = cs.calendar_id
     CROSS JOIN LATERAL (
       SELECT unnest(CASE cs.access_level
         WHEN 'read'  THEN ARRAY['read']
         WHEN 'write' THEN ARRAY['read','update','create','delete']
         WHEN 'owner' THEN ARRAY['read','update','create','delete','share']
       END) AS perm
     ) p;
   -- Same shape for address_book_shares (FALSE → ['read'], TRUE → ['read','update','create','delete'])
   -- Same shape for playlist_shares.
   ```
7. **Protocol mapping** (CalDAV / CardDAV only) — the WebDAV sharing properties (`<DAV:share-access>`, `<oc:invite>`) need to be re-implemented on top of the new grants. This is the largest unknown and the main reason for deferral.

### Why deferred, not in v1

- v1 must prove the `AuthorizationEngine` trait shape works before three more services land on it. If the trait needs an adjustment after running it on files, fixing it before three more migrations is much cheaper.
- The CalDAV/CardDAV protocol layer expects sharing semantics expressed via WebDAV properties — that's its own piece of work decoupled from the v1 grant table.
- Calendars/playlists are niche compared to file sharing — low migration risk if deferred.
- The 6-permission model already accommodates these without extension; the change is mechanical, just not yet.

### Suggested rollout (one PR per resource)

- **PR A** — calendars: schema constraint + Resource enum + CalendarService refactor + Hurl tests + CalDAV property mapping
- **PR B** — address books: same shape, simpler (binary `can_write`)
- **PR C** — playlists: same shape, also binary
- Each PR drops the corresponding bespoke share table at the end.

---

## Future: OpenFGA plug-in

Implementing `OpenFgaEngine` later requires:
1. Define the OpenFGA model:
   ```
   type folder
     relations
       define parent: [folder]
       define reader: [user, folder#reader]
       define creator: [user, folder#creator]
       define updater: [user, folder#updater]
       define deleter: [user, folder#deleter]
       define sharer:  [user, folder#sharer]
       define owner:   [user]
   type file
     relations
       define parent: [folder]
       define reader: [user, folder#reader]
       ...
   ```
2. On engine init, sync owner relationships (walk `storage.folders` + `storage.files`).
3. On every `grant()`, also write the tuple to OpenFGA.
4. On `check()`, query OpenFGA's `/check` endpoint.

The `AuthorizationEngine` trait shape is identical, so swapping engines is a configuration change. The PG engine remains the source of truth for `storage.access_grants` rows; OpenFGA becomes an indexed read cache.