Update SDK session key error string & docs

[wjmelements]

Currently the synapse SDK crashes if your session key does not have 4 permissions (and one of them is fictional, see #693).

I should be able to authorize an app to add pieces but not to remove them. I should be able to authorize an app to add and remove pieces but not to create a new dataset. This is not currently possible with the SynapseSDK.

The error is

Session key does not have the required permissions.

Furthermore, the error is not helpful or informative because it does not list the required permissions or whether they have expired.

The app will know which permissions they need. So, I think the correct time to fail is when attempting the unauthorized operation. If the app initialized the SDK with a session key that has no unexpired permissions, you can fail earlier.

[BigLep]

2026-04-09 conversation:

• Agreed to
  • Update docs to discuss our philosophy about session keys (synapse-sdk requires all of them, synapse-core if you want to be more selective)
  • Create a more informative error message (maybe even linking to the doc)

[SgtPooki]

a little aside in addition to better error messages: we ran into this on filecoin-pin-website (see slack thread). Our session key is scoped only to CreateDataSet + AddPieces on purpose. With that scope, Synapse.create blows up, including read-only ops like loading wallet balances.

I worked around it in filecoin-project/filecoin-pin-website#178 by going through @filoz/synapse-core directly and calling the public Synapse constructor instead of Synapse.create. It works, but I had to re-implement the viem createClient + custom-transport setup that Synapse.create does for you, re-derive the chain/transport defaults.

I know there was a discussion prior about not wanting to check permissions per operation because thats more difficult and not going to happen before GA, but a requiredPermissions?: Permission[] on SynapseOptions, defaulting to DefaultFwssPermissions would unblock filecoin-pin-website. That keeps existing behavior, but lets least-privilege apps stay on the Synapse.create happy path instead of needing the constructor escape hatch at all.