adm_access_control_api

This document contains the API documentation for the adm_access_control_api package.

Functions and Procedures

assert_admin

Raises adm_error.c_err_admin_required unless the current context has the ADMIN role.

Meant to be the first statement of every administrative operation, in place of spelling out if not user_is_admin then raise at each call site.

Signature:

procedure assert_admin (
  p_operation in varchar2
);

Parameters:

Name	Direction	Type	Description
p_operation	in	varchar2	What is being attempted, for the error message

---

embed_trash_owner

Whose trash an EMBED session may move a document into - the token’s creator, or null.

An embed’s trash problem is that every trash is /users/<name>/trash, which is outside every embed scope: there is no destination inside the window the token names. The signed identity’s own trash is one answer and it is what a DELETE grant used to mean, but it fails for the ordinary case - a visitor who is shown a folder and owns nothing of their own cannot receive it, so the grant was inert exactly where it was most wanted.

The token’s CREATOR is the better answer, and it is safe for a reason specific to this grant. adm_document_api.trash_document refuses a third party’s trash because parking a row under somebody’s home hands them view and owner rights on it - an escalation. Minting a DELETE grant already requires OWNER on the asset (adm_embed_api.generate_token), so the creator holds those rights over the subtree ALREADY and gains nothing from the move. The escalation the rule guards against cannot happen here.

That is verified rather than assumed, because rights change after a token is minted: the answer is null unless the creator still owns this document today, and null means the caller falls back to whatever it did before. So this can widen what succeeds and can never widen who holds what.

Null - the operation is not delegated - whenever any of these is false: the session is behind a live embed token, that token grants DELETE, it covers this document, its created_by is a known user, and that user owns the document (or administers the instance, which is the same rights by another route).

Signature:

function embed_trash_owner (
  p_document_id in adm_documents.document_id%type,
  p_embed_token in adm_embed_tokens.embed_token%type default sys_context(adm_context_api.c_ctx_namespace,
  adm_context_api.c_ctx_embed_token
);

Parameters:

Name	Direction	Type	Description
p_document_id	in	adm_documents.document_id%type	The document being trashed
p_embed_token	in	adm_embed_tokens.embed_token%type default sys_context(adm_context_api.c_ctx_namespace	The token; defaults to ADM_CONTEXT.ADM_EMBED_TOKEN, so an ordinary

                 session passes null and is answered null |

Returns: varchar2 - The username whose trash the document may go into, or null

---

embed_may_trash_document

Whether this session may move a document into p_trash_owner’s trash on an embed’s authority. The predicate form of embed_trash_owner, for the two gates in adm_document_api.trash_document.

Signature:

function embed_may_trash_document (
  p_document_id in adm_documents.document_id%type,
  p_trash_owner in varchar2
) return boolean;

Parameters:

Name	Direction	Type	Description
p_document_id	in	adm_documents.document_id%type	The document being trashed
p_trash_owner	in	varchar2	The proposed trash owner

Returns: boolean - true only when embed_trash_owner names exactly this user; never null

---