STAC Catalog Authorization

The EOCube.Ro STAC catalog enforces ownership- and visibility-based access control on every collection and item. Whether a request can read, create, update or delete an entity is decided from two fields carried by the entity itself, the identity of the caller, and the groups that caller belongs to.

This page describes the rules an application must follow when publishing, searching, updating, or deleting STAC entities. Follow them and your data will be visible and modifiable exactly as you intend; ignore them and entities may be rejected on write or silently hidden on read.

Who you are

Every authenticated request carries:

• a username (your identity), and
• the set of groups you belong to (group paths such as eocube-users/uvt-users/team-a).

Requests may also be anonymous (no identity). Anonymous callers can only ever read, and only public entities.

A small number of accounts are administrators; they bypass the rules below and may read, write, and delete anything. Everything that follows describes the rules for ordinary (non-admin) accounts.

The two control fields

Every collection and item you publish must carry these two fields:

Field	Type	Meaning
eocube:owner	string	The username that owns the entity.
eocube:visibility	array of strings	Grant tokens that decide who else may read or write the entity.

Where to put them

• On items, both fields live under properties (properties.eocube:owner, properties.eocube:visibility).
• On collections, both fields live at the top level of the collection object.

eocube:visibility must be an array, even for a single grant (["public"], not "public").

eocube:owner

• The owner always has full read, write, and delete access to the entity.
• On creation, eocube:owner must be set to your own username. You cannot create an entity owned by somebody else.
• Only administrators may change the owner of an existing entity.

eocube:visibility

A list of grant tokens. Each token extends read or read+write access beyond the owner. The owner's own access does not depend on this list.

Token	Grants
public	Read for everyone, including anonymous callers. Use for open data.
private	No additional access (owner-only). A no-op marker, equivalent to an empty list.
group:ro:<group>	Read for members of <group> and any of its sub-groups.
group:rw:<group>	Read and write for members of <group> and any of its sub-groups.
user:ro:<username>	Read for that user. Use user:ro:* for any authenticated user.
user:rw:<username>	Read and write for that user. Use user:rw:* for any authenticated user.

Group prefix matching. A group grant applies to the named group and every sub-group beneath it. For example group:rw:eocube-users grants write access to a member of eocube-users/uvt-users/team-a, because eocube-users is an ancestor of that user's group path.

Combining tokens. Tokens are additive; list as many as you need:

["public", "group:rw:eocube-users", "user:rw:ion.popescu"]

This entity is readable by anyone, and writable by members of eocube-users (and its sub-groups) and by the user ion.popescu.

Visibility is required

There is no implicit default. An entity published without an eocube:visibility array is visible and modifiable only by its owner — it will not appear in anonymous or other users' searches. Always set visibility explicitly (use ["public"] for open data, ["private"] for owner-only).

Collection naming

When you create a collection, its id must be prefixed with your username:

<your-username>-<name>

For example, user ion.popescu may create ion.popescu-my-aoi but not my-aoi or someone-else-aoi. Collections whose id does not match this pattern are rejected. (Items are not subject to a naming rule; they are scoped by the collection they belong to.)

Rules per operation

Searching and reading

• An entity appears in your results only if you own it or its eocube:visibility grants you read access — that is, it contains public, a group:ro:/group:rw: token for one of your groups (or an ancestor), a user:ro:/user:rw: token for your username, or a * wildcard.
• Anonymous callers only ever see entities whose visibility contains public.
• Results are filtered, not refused: entities you are not allowed to see are simply omitted from search results and individual lookups behave as if they do not exist. A search never fails because some entities are private.

Creating (publishing)

When you publish a new collection or item:

1. Set eocube:owner to your own username. A create whose owner is missing or is not you is rejected.
2. For collections, name the id as <your-username>-<name>.
3. Set eocube:visibility to the access you intend (e.g. ["public"], ["private"], or a list of group/user grants).

You cannot publish an entity on behalf of another user, and visibility grants do not let you create entities inside another user's namespace.

Updating

• You may update an entity only if you own it or its eocube:visibility grants you write access — a group:rw: token for one of your groups, a user:rw:<you> token, or user:rw:*.
• Read-only grants do not allow updates. A group:ro:/user:ro: token lets a user see the entity but not change it.
• Preserve eocube:owner on update — only administrators may reassign ownership.

Deleting

• Deletion follows the same rule as updating: you may delete an entity only if you own it or you have a write grant on it (group:rw:, user:rw:<you>, or user:rw:*).
• A read grant never permits deletion.
• Anonymous callers cannot delete anything.

Checklist for publishers

• [ ] Every item and collection carries both eocube:owner and eocube:visibility.
• [ ] eocube:owner is your username.
• [ ] eocube:visibility is an array of valid tokens.
• [ ] Item fields are under properties; collection fields are at the top level.
• [ ] Collection ids are <your-username>-<name>.
• [ ] You publish open data with ["public"], private data with ["private"], and shared data with the appropriate group:rw: / user:rw: tokens.

Examples

Public item, owned by you (fields under properties):

{
  "type": "Feature",
  "id": "S2A_...",
  "collection": "sentinel-2-l1c",
  "properties": {
    "eocube:owner": "ion.popescu",
    "eocube:visibility": ["public"]
  }
}

Private collection, owner-only:

{
  "type": "Collection",
  "id": "ion.popescu-experiments",
  "eocube:owner": "ion.popescu",
  "eocube:visibility": ["private"]
}

Item shared read+write with a team, readable by all:

{
  "properties": {
    "eocube:owner": "ion.popescu",
    "eocube:visibility": ["public", "group:rw:eocube-users/uvt-users/team-a"]
  }
}