# `Sofa.Security`
[🔗](https://github.com/skunkwerks/sofa/blob/0.8.1/lib/sofa/security.ex#L1)

A database's security object: who its admins and members are, by user
name and by role.

> If the only tool you have is CouchDB, then
> everything looks like `{:ok, :relax}`

See https://docs.couchdb.org/en/stable/api/database/security.html. An
empty object means every server admin is an admin and everyone else,
including anonymous users, is a member. CouchDB 3 creates databases
admin-only instead, with the `_admin` role on both grants, unless its
`default_security` setting says otherwise. Users and roles are those of
`Sofa.User` documents in `_users`.

Read and write it with `Sofa.DB.security/1` and `Sofa.DB.set_security/2`.

## Examples

    Sofa.Security.new()
    |> Sofa.Security.admin("jan")
    |> Sofa.Security.member(role: "users")
    |> then(&Sofa.DB.set_security(db, &1))

    iex> Sofa.Security.new() |> Sofa.Security.member("jan") |> Sofa.Security.member(role: "users") |> Sofa.Security.to_map()
    %{"admins" => %{"names" => [], "roles" => []}, "members" => %{"names" => ["jan"], "roles" => ["users"]}}

# `grant`

```elixir
@type grant() :: %{names: [String.t()], roles: [String.t()]}
```

User names and roles granted a level of access

# `t`

```elixir
@type t() :: %Sofa.Security{admins: grant(), members: grant()}
```

# `admin`

```elixir
@spec admin(t(), String.t() | [{:role, String.t()}]) :: t()
```

Grants admin access to a user name, or with `role:` to a role.

# `empty?`

```elixir
@spec empty?(t()) :: boolean()
```

Whether the object grants nothing, which leaves the database open to all.

# `from_map`

```elixir
@spec from_map(map()) :: t()
```

From the JSON object CouchDB returns. Missing parts are empty.

# `member`

```elixir
@spec member(t(), String.t() | [{:role, String.t()}]) :: t()
```

Grants member access to a user name, or with `role:` to a role.

# `new`

```elixir
@spec new() :: t()
```

An empty security object, as a new database has.

# `to_map`

```elixir
@spec to_map(t()) :: map()
```

To the JSON object CouchDB expects.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
