federation

Documentation

Index

• func NewClock() pub.Clock
• type Clock
  • func (c *Clock) Now() time.Time
• type Federator
  • func NewFederator(state *state.State, federatingDB federatingdb.DB, ...) *Federator
  • func (f *Federator) AuthenticateFederatedRequest(ctx context.Context, requestedUsername string) (*PubKeyAuth, gtserror.WithCode)
  • func (f *Federator) AuthenticateGetInbox(ctx context.Context, w http.ResponseWriter, r *http.Request) (context.Context, bool, error)
  • func (f *Federator) AuthenticateGetOutbox(ctx context.Context, w http.ResponseWriter, r *http.Request) (context.Context, bool, error)
  • func (f *Federator) AuthenticatePostInbox(ctx context.Context, w http.ResponseWriter, r *http.Request) (context.Context, bool, error)
  • func (f *Federator) Blocked(ctx context.Context, actorIRIs []*url.URL) (bool, error)
  • func (f *Federator) CheckGone(ctx context.Context, uri *url.URL) (bool, error)
  • func (f *Federator) DefaultCallback(ctx context.Context, activity pub.Activity) error
  • func (f *Federator) FederatingActor() pub.FederatingActor
  • func (f *Federator) FederatingCallbacks(ctx context.Context) (wrapped pub.FederatingWrappedCallbacks, other []any, err error)
  • func (f *Federator) FederatingDB() federatingdb.DB
  • func (f *Federator) FilterForwarding(ctx context.Context, potentialRecipients []*url.URL, a pub.Activity) ([]*url.URL, error)
  • func (f *Federator) GetInbox(ctx context.Context, r *http.Request) (vocab.ActivityStreamsOrderedCollectionPage, error)
  • func (f *Federator) GetOutbox(ctx context.Context, r *http.Request) (vocab.ActivityStreamsOrderedCollectionPage, error)
  • func (f *Federator) HandleGone(ctx context.Context, uri *url.URL) error
  • func (f *Federator) MaxDeliveryRecursionDepth(ctx context.Context) int
  • func (f *Federator) MaxInboxForwardingRecursionDepth(ctx context.Context) int
  • func (f *Federator) NewTransport(ctx context.Context, actorBoxIRI *url.URL, gofedAgent string) (pub.Transport, error)
  • func (f *Federator) PostInboxRequestBodyHook(ctx context.Context, r *http.Request, activity pub.Activity) (context.Context, error)
  • func (f *Federator) TransportController() transport.Controller
• type PubKeyAuth

Functions

func NewClock

func NewClock() pub.Clock

NewClock returns a simple pub.Clock for use in federation interfaces.

Types

type Clock

type Clock struct{}

Clock implements the Clock interface of go-fed

func (*Clock) Now

func (c *Clock) Now() time.Time

Now just returns the time now

type Federator

type Federator struct {
	dereferencing.Dereferencer
	// contains filtered or unexported fields
}

func NewFederator

func NewFederator(
	state *state.State,
	federatingDB federatingdb.DB,
	transportController transport.Controller,
	converter *typeutils.Converter,
	visFilter *visibility.Filter,
	intFilter *interaction.Filter,
	mediaManager *media.Manager,
) *Federator

NewFederator returns a new federator instance.

func (*Federator) AuthenticateFederatedRequest

func (f *Federator) AuthenticateFederatedRequest(ctx context.Context, requestedUsername string) (*PubKeyAuth, gtserror.WithCode)

AuthenticateFederatedRequest authenticates any kind of incoming federated request from a remote server. This includes things like GET requests for dereferencing our users or statuses etc, and POST requests for delivering new Activities. The function returns details of the public key(s) used to authenticate the requesting http signature.

'Authenticate' in this case is defined as making sure that the http request is actually signed by whoever claims to have signed it, by fetching the public key from the signature and checking it against the remote public key.

The provided username will be used to generate a transport for making remote requests/derefencing the public key ID of the request signature. Ideally you should pass in the username of the user *being requested*, so that the remote server can decide how to handle the request based on who's making it. Ie., if the request on this server is for https://example.org/users/some_username then you should pass in the username 'some_username'. The remote server will then know that this is the user making the dereferencing request, and they can decide to allow or deny the request depending on their settings.

This function will handle dereferencing and storage of any new remote accounts and / or instances. The returned PubKeyAuth{}.Owner account will ONLY ever be nil in the case that there is an ongoing handshake involving this account.

Note that it is also valid to pass in an empty string here, in which case the keys of the instance account will be used.

func (*Federator) AuthenticateGetInbox

func (f *Federator) AuthenticateGetInbox(ctx context.Context, w http.ResponseWriter, r *http.Request) (context.Context, bool, error)

AuthenticateGetInbox delegates the authentication of a GET to an inbox.

Always called, regardless whether the Federated Protocol or Social API is enabled.

If an error is returned, it is passed back to the caller of GetInbox. In this case, the implementation must not write a response to the ResponseWriter as is expected that the client will do so when handling the error. The 'authenticated' is ignored.

If no error is returned, but authentication or authorization fails, then authenticated must be false and error nil. It is expected that the implementation handles writing to the ResponseWriter in this case.

Finally, if the authentication and authorization succeeds, then authenticated must be true and error nil. The request will continue to be processed.

func (*Federator) AuthenticateGetOutbox

func (f *Federator) AuthenticateGetOutbox(ctx context.Context, w http.ResponseWriter, r *http.Request) (context.Context, bool, error)

AuthenticateGetOutbox delegates the authentication of a GET to an outbox.

Always called, regardless whether the Federated Protocol or Social API is enabled.

If an error is returned, it is passed back to the caller of GetOutbox. In this case, the implementation must not write a response to the ResponseWriter as is expected that the client will do so when handling the error. The 'authenticated' is ignored.

If no error is returned, but authentication or authorization fails, then authenticated must be false and error nil. It is expected that the implementation handles writing to the ResponseWriter in this case.

Finally, if the authentication and authorization succeeds, then authenticated must be true and error nil. The request will continue to be processed.

func (*Federator) AuthenticatePostInbox

func (f *Federator) AuthenticatePostInbox(ctx context.Context, w http.ResponseWriter, r *http.Request) (context.Context, bool, error)

AuthenticatePostInbox delegates the authentication of a POST to an inbox.

If an error is returned, it is passed back to the caller of PostInbox. In this case, the implementation must not write a response to the ResponseWriter as is expected that the client will do so when handling the error. The 'authenticated' is ignored.

If no error is returned, but authentication or authorization fails, then authenticated must be false and error nil. It is expected that the implementation handles writing to the ResponseWriter in this case.

Finally, if the authentication and authorization succeeds, then authenticated must be true and error nil. The request will continue to be processed.

func (*Federator) Blocked

func (f *Federator) Blocked(ctx context.Context, actorIRIs []*url.URL) (bool, error)

Blocked should determine whether to permit a set of actors given by their ids are able to interact with this particular end user due to being blocked or other application-specific logic.

func (*Federator) CheckGone

func (f *Federator) CheckGone(ctx context.Context, uri *url.URL) (bool, error)

CheckGone checks if a tombstone exists in the database for AP Actor or Object with the given uri.

func (*Federator) DefaultCallback

func (f *Federator) DefaultCallback(ctx context.Context, activity pub.Activity) error

DefaultCallback is called for types that go-fed can deserialize but are not handled by the application's callbacks returned in the Callbacks method.

Applications are not expected to handle every single ActivityStreams type and extension, so the unhandled ones are passed to DefaultCallback.

func (*Federator) FederatingActor

func (f *Federator) FederatingActor() pub.FederatingActor

FederatingActor returns the underlying pub.FederatingActor, which can be used to send activities, and serve actors at inboxes/outboxes.

func (*Federator) FederatingCallbacks

func (f *Federator) FederatingCallbacks(ctx context.Context) (
	wrapped pub.FederatingWrappedCallbacks,
	other []any,
	err error,
)

FederatingCallbacks returns the application logic that handles ActivityStreams received from federating peers.

Note that certain types of callbacks will be 'wrapped' with default behaviors supported natively by the library. Other callbacks compatible with streams.TypeResolver can be specified by 'other'.

For example, setting the 'Create' field in the FederatingWrappedCallbacks lets an application dependency inject additional behaviors they want to take place, including the default behavior supplied by this library. This is guaranteed to be compliant with the ActivityPub Social protocol.

To override the default behavior, instead supply the function in 'other', which does not guarantee the application will be compliant with the ActivityPub Social Protocol.

Applications are not expected to handle every single ActivityStreams type and extension. The unhandled ones are passed to DefaultCallback.

func (*Federator) FederatingDB

func (f *Federator) FederatingDB() federatingdb.DB

FederatingDB returns the underlying FederatingDB interface.

func (*Federator) FilterForwarding

func (f *Federator) FilterForwarding(ctx context.Context, potentialRecipients []*url.URL, a pub.Activity) ([]*url.URL, error)

FilterForwarding allows the implementation to apply business logic such as blocks, spam filtering, and so on to a list of potential Collections and OrderedCollections of recipients when inbox forwarding has been triggered.

The activity is provided as a reference for more intelligent logic to be used, but the implementation must not modify it.

func (*Federator) GetInbox

func (f *Federator) GetInbox(ctx context.Context, r *http.Request) (vocab.ActivityStreamsOrderedCollectionPage, error)

GetInbox returns the OrderedCollection inbox of the actor for this context. It is up to the implementation to provide the correct collection for the kind of authorization given in the request.

AuthenticateGetInbox will be called prior to this.

Always called, regardless whether the Federated Protocol or Social API is enabled.

func (*Federator) GetOutbox

func (f *Federator) GetOutbox(ctx context.Context, r *http.Request) (vocab.ActivityStreamsOrderedCollectionPage, error)

GetOutbox returns the OrderedCollection inbox of the actor for this context. It is up to the implementation to provide the correct collection for the kind of authorization given in the request.

AuthenticateGetOutbox will be called prior to this.

Always called, regardless whether the Federated Protocol or Social API is enabled.

func (*Federator) HandleGone

func (f *Federator) HandleGone(ctx context.Context, uri *url.URL) error

HandleGone puts a tombstone in the database, which marks an AP Actor or Object with the given uri as gone.

func (*Federator) MaxDeliveryRecursionDepth

func (f *Federator) MaxDeliveryRecursionDepth(ctx context.Context) int

MaxDeliveryRecursionDepth determines how deep to search within collections owned by peers when they are targeted to receive a delivery.

Zero or negative numbers indicate infinite recursion.

func (*Federator) MaxInboxForwardingRecursionDepth

func (f *Federator) MaxInboxForwardingRecursionDepth(ctx context.Context) int

MaxInboxForwardingRecursionDepth determines how deep to search within an activity to determine if inbox forwarding needs to occur.

Zero or negative numbers indicate infinite recursion.

func (*Federator) NewTransport

func (f *Federator) NewTransport(ctx context.Context, actorBoxIRI *url.URL, gofedAgent string) (pub.Transport, error)

NewTransport returns a new Transport on behalf of a specific actor.

The actorBoxIRI will be either the inbox or outbox of an actor who is attempting to do the dereferencing or delivery. Any authentication scheme applied on the request must be based on this actor. The request must contain some sort of credential of the user, such as a HTTP Signature.

The gofedAgent passed in should be used by the Transport implementation in the User-Agent, as well as the application-specific user agent string. The gofedAgent will indicate this library's use as well as the library's version number.

Any server-wide rate-limiting that needs to occur should happen in a Transport implementation. This factory function allows this to be created, so peer servers are not DOS'd.

Any retry logic should also be handled by the Transport implementation.

Note that the library will not maintain a long-lived pointer to the returned Transport so that any private credentials are able to be garbage collected.

func (*Federator) PostInboxRequestBodyHook

func (f *Federator) PostInboxRequestBodyHook(ctx context.Context, r *http.Request, activity pub.Activity) (context.Context, error)

PostInboxRequestBodyHook callback after parsing the request body for a federated request to the Actor's inbox.

Can be used to set contextual information based on the Activity received.

Warning: Neither authentication nor authorization has taken place at this time. Doing anything beyond setting contextual information is strongly discouraged.

If an error is returned, it is passed back to the caller of PostInbox. In this case, the DelegateActor implementation must not write a response to the ResponseWriter as is expected that the caller to PostInbox will do so when handling the error.

func (*Federator) TransportController

func (f *Federator) TransportController() transport.Controller

TransportController returns the underlying transport controller.

type PubKeyAuth

type PubKeyAuth struct {
	// CachedPubKey is the public key found in the db
	// for the Actor whose request we're now authenticating.
	// Will be set only in cases where we had the Owner
	// of the key stored in the database already.
	CachedPubKey *rsa.PublicKey

	// FetchedPubKey is an up-to-date public key fetched
	// from the remote instance. Will be set in cases
	// where EITHER we hadn't seen the Actor before whose
	// request we're now authenticating, OR a CachedPubKey
	// was found in our database, but was expired.
	FetchedPubKey *rsa.PublicKey

	// OwnerURI is the ActivityPub id of the owner of
	// the public key used to sign the request we're
	// now authenticating. This will always be set.
	OwnerURI *url.URL

	// Owner is the account corresponding to
	// OwnerURI. This will always be set UNLESS
	// the PubKeyAuth.Handshaking field is set..
	Owner *gtsmodel.Account

	// Handshaking indicates that uncached owner
	// account was NOT dereferenced due to an ongoing
	// handshake with another instance.
	Handshaking bool
}

PubKeyAuth models authorization information for a remote Actor making a signed HTTP request to this GtS instance using a public key.