Add API Documentation

[patrick-motard]

I'm considering using Buttercup instead of lastpass. It checks all the boxes (except one, see below)

• Has a desktop app, cross platform.
• Has chrome/firefox plugins
• Mobile app
• vault can be stored in a file, or in a cloud provider
  (Side note... The firefox extension is able to connect to google drive and request permissions to modify only files that it creates, which is awesome, but the desktop app can only connect to google drive if you allow it COMPLETE control, which is not okay)

I would like to do the following with a buttercup sdk from a personal project I am working on in typescript:

• load my buttercup vaults
• read/update/delete/list username/passwords

Is buttercup-core the right package to use for this usecase?
Can we get documentation and examples around these usecases?

[perry-mitchell]

the desktop app can only connect to google drive if you allow it COMPLETE control, which is not okay

This is being addressed in our new major version of the desktop app - not too far off.

Is buttercup-core the right package to use for this usecase?

Yes :)

Can we get documentation and examples around these usecases?

There's some basic examples in the readme, but you can also see how the core is used in our mobile app, browser extension and desktop app for usage examples.

This isn't ideal I know - we had API docs (JSDoc generated) but we lost this when we migrated to typescript. Most of the code is documented so API docs would be easy enough to generate. But yes, we definitely need proper docs.. I'll try to work on this soon.

[patrick-motard]

Thanks for the response @perry-mitchell! Awesome to hear about the new version of the desktop app fixing the permissions issue. And glad to see that i've landed in the right universe.

I'll take a look at the other codebases you mentioned to see if I can work through it. In an effort to help drive forward interest in more documentation, I'll provide a firsthand account below. Maybe it'll bring some insight into what new devs are seeing when they try to use the project.

I was running through the usage example in the readme. In my case I already had a vault, and i wanted to read/list information from it. My code, following the readme example looks like:

import { Credentials, FileDatasource, Vault, init } from "buttercup";

init();

const vaultPath = '/Users/me/cloud/docs/vault-2.bcup'
const vaultRelativePath = '../../vault-2.bcup';


const datasourceCredentials = Credentials.fromDatasource({
    path: vaultRelativePath,
}, "derp!");

// console.log(datasourceCredentials.getData());
// console.log(Credentials.allPurposes())

const fileDatasource = new FileDatasource(datasourceCredentials);

fileDatasource
    .load(datasourceCredentials)
    .catch(e => {
      console.log(e);
    });

Just to rule out relative vs full path ( I don't think it's documented which it expects. Both seem to result in the same error so i assume either is fine ).

Running the code above results in the following error.

Error: Provided credentials don't allow vault decryption
    at FileDatasource.load (webpack:///./node_modules/buttercup/dist/datasources/TextDatasource.js?:131:35)
    at eval (webpack:///./node_modules/buttercup/dist/datasources/FileDatasource.js?:93:30)

Before reaching out, I went through the source code for buttercup-core to try to dig out what was wrong. Looks like the TextDataSource that FileDatasource inherits from is throwing during .load(). Presumably because the Credential instance handed to it wasn't instantiated with proper purpose.

The readme usage example doesn't mention setting any purposes on initialized Credentials, probably because the Credentials constructor defaults to enabling all purposes? So the purposes may be getting restricted at some point, but I'm not sure why. The error could also be a red-herring.

By the way, it would be really helpful if the options object that the Credentials constructor can be passed had it's keys documented. I can't tell what properties it should expect, and what their types should be. We could solve this with a typescript type definition instead of an object, or just some brief documentation above the constructor if that's all there's time for.

This is as far as I got before I decided to reach out instead of digging any further to see if I'm even using the right codebase.

[perry-mitchell]

@patrick-motard I hear you, and concur with all of your points. Definitely some blind spots there for new users.. and well basically all users that aren't me, right now. I've started adding full documentation to a new site here: https://buttercup.github.io/core-docs/#/ (this will eventually move to docs.buttercup.pw, when it's closer to done).

I actually documented Credentials and their purposes, but tldr: Credentials have a list of purposes, for security reasons, which are restricted when being consumed by various interfaces. This is to reduce over-exposure of credentials beyond what they were instantiated to do originally.

To get around this, use separate instances for the datasource constructor and the load/save methods of a datasource.

Let's also leave this issue open to track the progress of the official docs. They will also receive API-level docs for the codebase when I get time to automate that.

[omartrinidad]

Hi Perry, what do you mean by "using separate instances"?