feat(synapse): add requiredPermissions option to SynapseOptions#806
Open
juliangruber wants to merge 2 commits into
Open
feat(synapse): add requiredPermissions option to SynapseOptions#806juliangruber wants to merge 2 commits into
juliangruber wants to merge 2 commits into
Conversation
Synapse.create previously hard-coded its session key check to
DefaultFwssPermissions (all four FWSS permissions). Apps with a
least-privilege session key (for example an upload-only client scoped to
CreateDataSet + AddPieces) had to bypass Synapse.create and use the
@filoz/synapse-core constructor directly, which meant re-implementing
the viem client + transport defaults that Synapse.create provides.
Add an optional requiredPermissions?: Permission[] field on
SynapseOptions, defaulting to SessionKey.DefaultFwssPermissions. Callers
that need a narrower scope can pass it directly:
Synapse.create({
...,
sessionKey,
requiredPermissions: [
SessionKey.CreateDataSetPermission,
SessionKey.AddPiecesPermission,
],
})
The SDK still does not enforce per-operation permission checks --
calling an SDK method whose permission is not in requiredPermissions
will go through and revert on-chain if the session key is not
authorized. requiredPermissions only gates Synapse.create.
Existing callers see no behavior change.
Per #695 (comment).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
synapse-dev | 8d8b407 | Commit Preview URL Branch Preview URL |
May 29 2026, 02:14 PM |
github-project-automation
Bot
moved this from 🔎 Awaiting review
to ✔️ Approved by reviewer
in FOC
…ons-required-permissions # Conflicts: # docs/src/content/docs/developer-guides/session-keys.mdx # packages/synapse-sdk/src/synapse.ts # packages/synapse-sdk/src/test/session-keys.test.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements SgtPooki's suggestion on #695: add a
requiredPermissions?: Permission[]option onSynapseOptions, defaulting toSessionKey.DefaultFwssPermissions, so least-privilege session keys can stay on theSynapse.createhappy path.Why
Apps like filecoin-pin-website intentionally scope their session key to a subset of FWSS permissions (e.g.
CreateDataSet+AddPieces). TodaySynapse.createalways checks the fullDefaultFwssPermissionsset, so those apps have to bypassSynapse.createand use the publicSynapseconstructor through@filoz/synapse-coredirectly, which means re-implementing the viemcreateClient+ custom-transport setup thatSynapse.createprovides for free.What changed
requiredPermissions?: Permission[]field onSynapseOptions, with a docstring explaining that it gates construction (not per-operation), defaults toSessionKey.DefaultFwssPermissions, and that operations whose permissions are not listed will still revert on-chain if attempted.Synapse.createreadsoptions.requiredPermissions ?? SessionKey.DefaultFwssPermissionsinstead of the hard-codedDefaultFwssPermissions. No other behavior change.DefaultFwssPermissionswhenrequiredPermissionsis omitted (regression guard)Backwards compatibility
requiredPermissionsis optional and defaults to the previous behavior, so existing callers are unaffected.Per-operation checks
Deliberately not adding per-operation permission enforcement here — that was discussed previously as out of scope for GA, and SgtPooki's suggestion was specifically a construction-time knob. Callers must still only invoke SDK methods whose permissions they have authorized; otherwise the call will revert on-chain. The docs call this out explicitly.
Relation to #805
#805 handles the other half of #695 (better error message + docs philosophy). This PR is independent: it only changes the validation input, not the message. Both PRs touch
Synapse.createand will produce a small merge conflict whichever lands second; resolution is trivial (apply both: readrequiredPermissionsfrom options and itemize the missing ones in the error).Test plan
pnpm run buildcleanpnpm run lintclean@filoz/synapse-sdkpass, including the three new ones above🤖 Generated with Claude Code