Module share_access 

Who may read and who may change a file’s share set.

Lives in cloudillo-core because it gates two crates: the share-entry endpoints in cloudillo-file and the ref (share-link) endpoints in cloudillo-ref. A refId is a bearer credential, so minting, listing or revoking one is share management and must pass the same gate as POST /api/files/{id}/shares.

Every require_* entry point refuses any scoped token, share-link delegation or API-key capability scope alike: a delegated link must never widen or mutate the grant that admitted it (confused-deputy), and share management is never delegable.

Handler ordering convention

Every share-entry and ref handler runs its checks in this order, so both crates answer the same request shape the same way:

1. The caller-shape check (reject_scoped, or the scope refusal inside require_unscoped_file_access) before anything, body validation included: a scoped caller must not learn even whether their request was well formed.
2. Resource authorization as soon as the resource id is known.
3. Body validation last — except where a gate needs a parsed value, such as ensure_grant_within needing the validated permission char.

Structs

ShareAuthority

A caller’s resolved authority over one file’s share set.

Enums

ShareStanding

A caller’s standing over one file’s share set. Ordered: Manager implies Reader.

Functions

ensure_grant_within

A share manager may not hand out more access than ShareAuthority::grant_ceiling allows.

ensure_standing

Enforce a minimum standing, with the denial log every call site wants.

require_share_manager

Authorize share management (create/update/delete share entries, mint/revoke share links).

require_share_reader

Authorize listing a file’s share entries or share links.

require_unscoped_file_access

Refuse any scoped token, then resolve the caller’s unscoped access to file_id.

share_standing

Resolve the caller’s standing over file_id’s share set in one pass.

share_standing_for_actor

Resolve share standing for a server-side actor named only by id_tag — no token, hence no AuthCtx to hand in. Used by the FSHR native hook, where the actor is the action’s issuer and the write it guards (create_share_entry) is the same one POST /api/files/{id}/shares makes.