feat: pass gaia hub to both get and putFile fns

[aulneau]

Description

If someone wants to build an app that allows for collaborative editing of shared files, we need to allow the application to provide any gaia hub config that could contain the scoped auth token for that file. This PR implements the minimum amount of changes to allow for this kind of api:

const upload = await userSession.putFile(filename, contents {gaiaHubConfig: gaiaHubConfigWithScopedAuthToken});
const read = await userSession.getFile(filename, {gaiaHubConfig: gaiaHubConfigWithScopedAuthToken});

This would also allow the application to generate a new auth tokens that can change the way gaia writes their files (for example: automatic versioning with putFileArchival):

type ScopeTypes =
  | 'putFile'
  | 'putFilePrefix'
  | 'deleteFile'
  | 'deleteFilePrefix'
  | 'putFileArchival'
  | 'putFileArchivalPrefix';

related to #545

Type of Change

• New feature
• Bug fix
• API reference/documentation update
• Other

Does this introduce a breaking change?

no

Are documentation updates required?

Yes, to explain the additional option and probably show them how to generate the tokens

Checklist

• Code is commented where needed
• Unit test coverage for new or modified code paths
• npm run test passes
• Changelog is updated
• Tag 1 of @yknl or @zone117x for review

[hstove]

Dope! Now add the code to add scopes to the auth token :)

[aulneau]

@zone117x @reedrosenbluth @yknl @hstove maybe we can set up some time to talk through this kind of thing / use case in a sync meeting?

[yknl]

Let's discuss this, I would prefer an approach that abstracts away the Gaia hub config for developers. For example, when you create a scoped auth token for another user, it could be stored on your hub and encrypted using the public key of the authorized user. When the authorized user is making a putFile request, they would just provide a username and the auth token/hub config lookup would be automatic.

[aulneau]

Let's discuss this, I would prefer an approach that abstracts away the Gaia hub config for developers. For example, when you create a scoped auth token for another user, it could be stored on your hub and encrypted using the public key of the authorized user. When the authorized user is making a putFile request, they would just provide a username and the auth token/hub config lookup would be automatic.

Sure thing! I am just trying to make the thing I am building work, and this seems to be the way that I've found so far. I wonder how what you suggest would work when each file shared has a different auth token? (scoped to that file/path)

[yknl]

I wonder how what you suggest would work when each file shared has a different auth token? (scoped to that file/path)

I think that can be handled by having a list of auth tokens stored on your own Gaia hub, keyed by the hash of the file name. The authorized user already supplies a file name to putFile.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[agraebe]

closing this for now. please re-open if you think this requires attention. if you re-open, please also suggest who could help resolve and carry it to the finish line 🙏🏼