View Source Bonfire.Boundaries.Acls (Bonfire v0.9.10-classic-beta.156)

Provides functionality for managing Access Control Lists (ACLs) in the Bonfire system.

An Acl is a list of Grants used to define access permissions for objects. It represents fully populated access control rules that can be reused. It can be used to secure multiple objects and exists independently of any object.

ACLs (also referred to as "preset boundaries") enable you to make a list of circles and users and then grant specific roles or permissions to each of those. For example, you might create a "Fitness" ACL and grant the "Participate" role to your gym buddies, allowing them to interact with your fitness-related content, while granting the "Interact" role to your family and friends, who can view and react to your posts but not comment on them.

The corresponding Ecto schema is Bonfire.Data.AccessControl.Acl which is defined in a seperate repo.

Summary

Functions

acl_grants_to_tuples(creator, acls)

acl_id(obj)

acls()

Returns a list of special built-in ACLs (e.g., guest, local, activity_pub).

acls_from_preset(creator, to_boundaries, opts \\ [])

base_acls_from_preset(creator, preset, opts \\ [])

built_in_ids()

Returns a list of built-in ACL IDs.

cast(changeset, creator, opts)

Casts ACLs (existing ones or creating some on-the-fly) and Controlled on an object.

changeset(atom, attrs, opts)

create(attrs \\ %{}, opts)

Creates a new ACL.

default_exclude_ids(including_custom? \\ true)

Returns a list of default IDs to exclude from queries.

delete(acl, opts)

Fully delete the ACL, including permissions/grants and controlled information. This will affect all objects previously shared with this ACL.

edit(acl, user, params)

Edits an existing ACL.

exclude_stereotypes(including_custom? \\ true)

Returns a list of stereotype IDs to exclude from queries.

get(slug)

Retrieves an ACL by its slug.

get!(slug)

Retrieves an ACL by its slug, raising an error if not found.

get_for_caretaker(id, caretaker, opts \\ [])

Retrieves an ACL for a caretaker.

get_for_caretaker_q(id, caretaker, opts \\ [])

get_id(slug)

Retrieves an ACL ID by its slug.

get_id!(slug)

get_object_custom_acl(object)

get_or_create_object_custom_acl(object, caretaker \\ nil)

grant_tuples_from_preset(creator, to_boundaries, opts \\ [])

is_built_in?(acl)

Checks if an ACL is built-in.

is_object_custom?(acl)

Checks if an ACL is a custom ACL for an object.

is_stereotype?(acl)

is_stereotyped?(acl)

Checks if an ACL is stereotyped.

list(opts \\ [])

Lists ACLs the current user is permitted to see.

list_built_ins(opts \\ [])

Lists built-in ACLs.

list_my(user, opts \\ [])

Lists ACLs for a specific user.

list_my_q(user, opts \\ [])

query for list_my

list_my_with_counts(user, opts \\ [])

Lists ACLs for a specific user with grant counts (how many rules ).

list_q(opts \\ [])

maybe_by_ids(query, ids)

maybe_search(query, text)

opts_for_dropdown()

Returns options to use when querying for ACLs to show in a dropdown in the UI.

opts_for_list()

Returns options to use when querying for ACLs to show in a list.

prepare_cast(changeset_or_obj, creator, opts)

preset_acl_ids()

preset_acl_ids(preset, preset_acls \\ Config.get!(:preset_acls_match))

Returns a list of ACL IDs for a preset (eg. "local" and "public").

preview(creator, opts)

Previews ACLs as they would be set based on provided opts.

remote_public_acl_ids()

Returns a list of ACL IDs for remote public access.

set(object, creator, opts)

Sets ACLs (existing ones or creating some on-the-fly) and Controlled on an object.

simple_create(caretaker, name)

Creates a simple ACL with a name.

soft_delete(acl, opts)

Soft-delete the ACL, meaning it will not be displayed anymore, but permissions/grants and controlled information will be preserved. This will not affect objects previously shared with this ACL.

stereotype_ids()

Returns a list of stereotype ACL IDs.

user_default_acl(name)

user_default_acls()

Functions

acl_grants_to_tuples(creator, acls)

acl_id(obj)

acls()

Returns a list of special built-in ACLs (e.g., guest, local, activity_pub).

acls_from_preset(creator, to_boundaries, opts \\ [])

base_acls_from_preset(creator, preset, opts \\ [])

built_in_ids()

Returns a list of built-in ACL IDs.

Examples

iex> Bonfire.Boundaries.Acls.built_in_ids()
["BUILT_IN_ACL_ID1", "BUILT_IN_ACL_ID2"]

cast(changeset, creator, opts)

Casts ACLs (existing ones or creating some on-the-fly) and Controlled on an object.

Examples

iex> Bonfire.Boundaries.Acls.cast(changeset, creator, [boundary: "local"])

changeset(atom, attrs, opts)

create(attrs \\ %{}, opts)

Creates a new ACL.

Examples

iex> Bonfire.Boundaries.Acls.create(%{named: %{name: "New ACL"}}, current_user: user)
{:ok, %Acl{}}

default_exclude_ids(including_custom? \\ true)

Returns a list of default IDs to exclude from queries.

Examples

iex> Bonfire.Boundaries.Acls.default_exclude_ids()
["2HEYS11ENCEDMES0CAN0TSEEME", "7HECVST0MAC1F0RAN0BJECTETC", "71MAYADM1N1STERMY0WNSTVFFS", "0H0STEDCANTSEE0RD0ANYTH1NG", "1S11ENCEDTHEMS0CAN0TP1NGME"]

delete(acl, opts)

Fully delete the ACL, including permissions/grants and controlled information. This will affect all objects previously shared with this ACL.

edit(acl, user, params)

Edits an existing ACL.

Examples

iex> Bonfire.Boundaries.Acls.edit(acl_id, user, %{name: "Updated ACL"})

iex> Bonfire.Boundaries.Acls.edit(%Acl{}, user, %{name: "Updated ACL"})

exclude_stereotypes(including_custom? \\ true)

Returns a list of stereotype IDs to exclude from queries.

Examples

iex> Bonfire.Boundaries.Acls.exclude_stereotypes()
["2HEYS11ENCEDMES0CAN0TSEEME", "7HECVST0MAC1F0RAN0BJECTETC"]

iex> Bonfire.Boundaries.Acls.exclude_stereotypes(false)
["2HEYS11ENCEDMES0CAN0TSEEME"]

get(slug)

Retrieves an ACL by its slug.

Examples

iex> Bonfire.Boundaries.Acls.get(:instance_care)

iex> Bonfire.Boundaries.Acls.get(:non_existent)
nil

get!(slug)

Retrieves an ACL by its slug, raising an error if not found.

get_for_caretaker(id, caretaker, opts \\ [])

Retrieves an ACL for a caretaker.

Examples

iex> Bonfire.Boundaries.Acls.get_for_caretaker("ACL_ID", user)
{:ok, %Acl{}}

get_for_caretaker_q(id, caretaker, opts \\ [])

get_id(slug)

Retrieves an ACL ID by its slug.

Examples

iex> Bonfire.Boundaries.Acls.get_id(:instance_care)
"01SETT1NGSF0R10CA11NSTANCE"

iex> Bonfire.Boundaries.Acls.get_id(:non_existent)
nil

get_id!(slug)

get_object_custom_acl(object)

get_or_create_object_custom_acl(object, caretaker \\ nil)

grant_tuples_from_preset(creator, to_boundaries, opts \\ [])

is_built_in?(acl)

Checks if an ACL is built-in.

Examples

iex> Bonfire.Boundaries.Acls.is_built_in?("BUILT_IN_ACL_ID")
true

iex> Bonfire.Boundaries.Acls.is_built_in?("CUSTOM_ACL_ID")
false

is_object_custom?(acl)

Checks if an ACL is a custom ACL for an object.

Examples

iex> Bonfire.Boundaries.Acls.is_object_custom?(%Acl{stereotyped: %{stereotype_id: "CUSTOM_ACL_ID"}})
true

iex> Bonfire.Boundaries.Acls.is_object_custom?(%Acl{})
false

is_stereotype?(acl)

is_stereotyped?(acl)

Checks if an ACL is stereotyped.

Examples

iex> Bonfire.Boundaries.Acls.is_stereotyped?(%Acl{stereotyped: %{stereotype_id: "STEREOTYPE_ID"}})
true

iex> Bonfire.Boundaries.Acls.is_stereotyped?("STEREOTYPE_ID")
true

iex> Bonfire.Boundaries.Acls.is_stereotyped?(%Acl{})
false

list(opts \\ [])

Lists ACLs the current user is permitted to see.

Examples

iex> Bonfire.Boundaries.Acls.list(current_user: user)
[%Acl{}, %Acl{}]

list_built_ins(opts \\ [])

Lists built-in ACLs.

Examples

iex> Bonfire.Boundaries.Acls.list_built_ins()
[%Acl{}, %Acl{}]

list_my(user, opts \\ [])

Lists ACLs for a specific user.

Includes the ACLs we are the registered caretakers of that we are permitted to see. If any are created without permitting the user to see them, they will not be shown.

Examples

iex> Bonfire.Boundaries.Acls.list_my(user)
[%Acl{}, %Acl{}]

list_my_q(user, opts \\ [])

query for list_my

list_my_with_counts(user, opts \\ [])

Lists ACLs for a specific user with grant counts (how many rules ).

Examples

iex> Bonfire.Boundaries.Acls.list_my_with_counts(user)
[%{acl: %Acl{}, grants_count: 5}, %{acl: %Acl{}, grants_count: 2}]

list_q(opts \\ [])

maybe_by_ids(query, ids)

maybe_search(query, text)

opts_for_dropdown()

Returns options to use when querying for ACLs to show in a dropdown in the UI.

Examples

iex> Bonfire.Boundaries.Acls.opts_for_dropdown()
[exclude_ids: [...], extra_ids_to_include: [...]]

opts_for_list()

Returns options to use when querying for ACLs to show in a list.

Examples

iex> Bonfire.Boundaries.Acls.opts_for_list()
[exclude_ids: [...]]

prepare_cast(changeset_or_obj, creator, opts)

preset_acl_ids()

preset_acl_ids(preset, preset_acls \\ Config.get!(:preset_acls_match))

Returns a list of ACL IDs for a preset (eg. "local" and "public").

preview(creator, opts)

Previews ACLs as they would be set based on provided opts.

Examples

iex> Bonfire.Boundaries.Acls.preview(creator, [
  preview_for_id: object_id,
  boundary: "mentions",
  to_circles: mentioned_users_or_custom_circles
])

iex> Bonfire.Boundaries.Acls.preview(creator, [
  preview_for_id: object_id,
  boundary: "clone_context",
  context_id: context_object_id
])

remote_public_acl_ids()

Returns a list of ACL IDs for remote public access.

Examples

iex> Bonfire.Boundaries.Acls.remote_public_acl_ids()
["5REM0TEPE0P1E1NTERACTREACT", "5REM0TEPE0P1E1NTERACTREP1Y", "7REM0TEACT0RSCANC0NTR1BVTE"]

set(object, creator, opts)

Sets ACLs (existing ones or creating some on-the-fly) and Controlled on an object.

Examples

iex> Bonfire.Boundaries.Acls.set(%{}, creator, [boundary: "local"])
{:ok, :granted}

simple_create(caretaker, name)

Creates a simple ACL with a name.

Examples

iex> Bonfire.Boundaries.Acls.simple_create(user, "My ACL")
{:ok, %Acl{}}

soft_delete(acl, opts)

Soft-delete the ACL, meaning it will not be displayed anymore, but permissions/grants and controlled information will be preserved. This will not affect objects previously shared with this ACL.

stereotype_ids()

Returns a list of stereotype ACL IDs.

Examples

iex> Bonfire.Boundaries.Acls.stereotype_ids()
["STEREOTYPE_ACL_ID1", "STEREOTYPE_ACL_ID2"]