= libsecret/gosecret
Brent Saner <bts@square-r00t.net>
:doctype: book
:docinfo: shared
:data-uri:
:imagesdir: images
:sectlinks:
:sectnums:
:sectnumlevels: 7
:toc: preamble
:toc2: left
:idprefix:
:toclevels: 7
:source-highlighter: rouge

image::https://pkg.go.dev/badge/r00t2.io/gosecret.svg[link="https://pkg.go.dev/r00t2.io/gosecret"]

This project is originally forked from https://github.com/gsterjov/go-libsecret[go-libsecret^] due to:

* Lack of response from the developer
* Complete lack of documentation
* Poor, ineffecient, or just plain antipattern design
* Missing functionality

and as such, hopefully this library should serve as a more effective libsecret/SecretService interface.

== Backwards Compatability/Drop-In Replacement Support

Version series `v0.X.X` of this library promises full and non-breaking backwards support of API interaction with the original project. The only changes should be internal optimizations, adding documentation, some file reorganizing, adding Golang module support, etc. -- all transparent from the library API itself.

To use this library as a replacement without significantly modifying your code, you can simply use a `replace` directive:

// TODO: did I do this correctly? I never really use replacements so someone PR if this is incorrect.
.go.mod
[source]
----
// ...
replace (
	github.com/gsterjov/go-libsecret dev => r00t2.io/gosecret v0
)
----

and then run `go mod tidy`.

== New Developer API

Starting from `v1.0.0` onwards, entirely breaking changes can be assumed from the original project.

To use the new version,

[source,go]
----
import (
	`r00t2.io/gosecret/v1`
)
----

To reflect the absolute breaking changes, the module name changes as well from `libsecret` to `gosecret`.

=== Status

The new API is underway, and all functionality in V0 is present. However, it's not "complete". https://github.com/johnnybubonic/gosecret/pulls[PRs^] welcome, of course, but this will be an ongoing effort for a bit of time.

== SecretService Concepts

For reference:

* A `*Service*` allows one to retrieve and operate on/with `*Session*` and `*Collection*` objects.
* A `*Session*` allows one to operate on/with `*Item*` objects (e.g. parsing/decoding/decrypting them).
* A `*Collection*` allows one to retrieve and operate on/with `*Item*` objects.
* An `*Item*` allows one to retrieve and operate on/with `*Secret*` objects.

(`*Secrets*` are considered "terminating objects" in this model, and contain
actual secret value(s) and metadata).

Various interactions are handled by `*Prompts*`.

So the object hierarchy in *theory* looks kind of like this:

----
Service
├─ Session "A"
├─ Session "B"
├─ Collection "A"
│	├─ Item "A.1"
│	│	├─ Secret "A_1_a"
│	│	└─ Secret "A_1_b"
│	└─ Item "A.2"
│		├─ Secret "A_2_a"
│		└─ Secret "A_2_b"
└─ Collection "B"
    ├─ Item "B.1"
    │	├─ Secret "B_1_a"
    │	└─ Secret "B_1_b"
    └─ Item "B.2"
        ├─ Secret "B_2_a"
        └─ Secret "B_2_b"
----

And so on.

In *practice*, however, most users will only have two Session types:

* a default "system" one, and
* a temporary one that may or may not exist, running in memory for the current login session

and a single Collection, named `login` (and aliased to `default`, usually).

== Usage

Full documentation can be found via inline documentation. Either via the https://pkg.go.dev/r00t2.io/gosecret[pkg.go.dev documentation^] or https://pkg.go.dev/golang.org/x/tools/cmd/godoc[`godoc`^] (or `go doc`) in the source root.

////
However, here's a quick demonstration.
////