Proposed change to powerbox request flow to add a server-side exchange step for better security.

[kentonv]

This is a proposal, not yet ready to merge.

Backwards-compatibility plan: claimRequest() actually has the same ordinal and signature as the old restore() method. Existing SPKs that call restore() will thus end up calling claimRequest() instead. We will temporarily allow requestTokens to be long-lived to avoid breaking existing code. We'll then update the existing apps to properly use claimRequest() and restore() -- there is only one such app in production today and it is only used by us (namely, the feature key vendor app). Once everything is updated, we'll switch requestTokens to be short-lived.

[zarvox]

Design seems fine. I'm also perfectly happy just breaking the feature key vendor app as-is and assuming we'll update the pair together.

To summarize my understanding of the flow now: apps should:

• JS postMessages a powerboxRequest with an appropriate descriptor
• JS add an event listener window.addEventListener("message", ...) to receive the requestToken as the token in the postMessage reply
• JS sends the requestToken to the app's backend
• backend calls claimRequest() and receives a liveref
• backend considers calling save() if it wants to have a sturdyref

Given that there's now a necessary backend step to exchange the requestToken, and that the app now has to call save() itself to get a sturdyref, does it make more sense to have claimRequest() also return the token's PowerboxDescriptor instead of attaching it as the base64-serialized thing in the postMessage reply?

[dwrensha]

What about SessionContext.request()? I know that this method currently unimplemented, but we should make sure that its signature continues to make sense. Currently that signature is

request @3 (query :List(PowerboxDescriptor)) -> (cap :Capability, descriptor :PowerboxDescriptor);

and if we remove the requiredPermissions argument from SandstormApi.restore(), then the app never gets a chance to specify a list of permissions that must be held by the introducer.

Some possibilities:

1. SessionContext.request() returns a requestToken rather than a Capability, forcing callers to go through claimRequest().
2. SessionContext.request() gets a second parameter, requiredPermissions.
3. SandstormApi.restore() keeps its `requiredPermissions parameter.

[kentonv]

I think option 2 is correct -- request() should get a new parameter. The multi-step exchange is only needed in the case of client-side requests because we don't trust the client.

[dwrensha]

Closing because this change was merged as part of #2027.