# `HushOsKeychain`
[🔗](https://github.com/edlontech/hush_os_keychain/blob/main/lib/hush_os_keychain.ex#L1)

Stores, fetches, and deletes generic passwords in macOS Keychain, Linux Secret
Service, and Windows Credential Manager.

The service is the Hush key. The account comes from the `:account` option, then
`config :hush, Hush.Provider.OsKeychain, account: ...`. Writes default to the
account `"hush"`; reads and deletes without an account search by service alone.

See the [README](readme.html) for installation, Hush setup, OS tools, lookup
rules, and platform and security limitations.

# `error`

```elixir
@type error() ::
  :not_found
  | {:unavailable, String.t()}
  | {:ambiguous, pos_integer()}
  | {:access_denied, String.t()}
  | {:invalid, String.t()}
  | {:platform, String.t()}
  | {:native_not_loaded, String.t()}
```

# `delete`

```elixir
@spec delete(String.t(), keyword()) :: :ok | {:error, error()}
```

Deletes the item stored under `service`, resolved the same way as `fetch/2`.

## Options

  * `:account` - the account of the item

## Examples

    HushOsKeychain.delete("myapp.db_password")
    #=> :ok

# `fetch`

```elixir
@spec fetch(String.t(), keyword()) :: {:ok, String.t()} | {:error, error()}
```

Fetches the secret stored under `service`.

Without an account, exactly one item with that service must exist.

## Options

  * `:account` - the account of the item

## Examples

    HushOsKeychain.fetch("myapp.db_password")
    #=> {:ok, "s3cret"}

    HushOsKeychain.fetch("myapp.db_password", account: "ygor")
    #=> {:error, :not_found}

# `format_error`

```elixir
@spec format_error(error(), String.t()) :: String.t()
```

Formats an error returned by this module, naming the OS store and the service.

## Examples

    HushOsKeychain.format_error({:access_denied, "user canceled"}, "myapp.db_password")
    #=> "macOS Keychain: access denied: user canceled (service \"myapp.db_password\")"

# `put`

```elixir
@spec put(String.t(), String.t(), keyword()) :: :ok | {:error, error()}
```

Stores `secret` under `service`, replacing an existing item for the same account.

The account falls back to `"hush"` when none is configured.

## Options

  * `:account` - the account of the item

## Examples

    HushOsKeychain.put("myapp.db_password", "s3cret")
    #=> :ok

---

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