From 16a9c7f744a5c85c2385bdf23a28d5b4d65c8585 Mon Sep 17 00:00:00 2001 From: Elle Mouton Date: Sun, 19 Mar 2023 19:48:16 +0200 Subject: [PATCH] litrpc: add comments and lncli directives to Sessions service --- litrpc/lit-sessions.pb.go | 102 ++++++++++++++++------- litrpc/lit-sessions.proto | 148 ++++++++++++++++++++++++++++++--- litrpc/lit-sessions_grpc.pb.go | 14 ++++ 3 files changed, 224 insertions(+), 40 deletions(-) diff --git a/litrpc/lit-sessions.pb.go b/litrpc/lit-sessions.pb.go index afbc6836..b21ab02f 100644 --- a/litrpc/lit-sessions.pb.go +++ b/litrpc/lit-sessions.pb.go @@ -135,13 +135,22 @@ type AddSessionRequest struct { sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - Label string `protobuf:"bytes,1,opt,name=label,proto3" json:"label,omitempty"` - SessionType SessionType `protobuf:"varint,2,opt,name=session_type,json=sessionType,proto3,enum=litrpc.SessionType" json:"session_type,omitempty"` - ExpiryTimestampSeconds uint64 `protobuf:"varint,3,opt,name=expiry_timestamp_seconds,json=expiryTimestampSeconds,proto3" json:"expiry_timestamp_seconds,omitempty"` - MailboxServerAddr string `protobuf:"bytes,4,opt,name=mailbox_server_addr,json=mailboxServerAddr,proto3" json:"mailbox_server_addr,omitempty"` - DevServer bool `protobuf:"varint,5,opt,name=dev_server,json=devServer,proto3" json:"dev_server,omitempty"` + // A user assigned label for the session. + Label string `protobuf:"bytes,1,opt,name=label,proto3" json:"label,omitempty"` + // The session type. This will be used during macaroon construction to + // determine how restrictive to make the macaroon and thus the session access. + SessionType SessionType `protobuf:"varint,2,opt,name=session_type,json=sessionType,proto3,enum=litrpc.SessionType" json:"session_type,omitempty"` + // The time at which the session should automatically be revoked. + ExpiryTimestampSeconds uint64 `protobuf:"varint,3,opt,name=expiry_timestamp_seconds,json=expiryTimestampSeconds,proto3" json:"expiry_timestamp_seconds,omitempty"` + // The address of the mailbox server that the LNC connection should use. + MailboxServerAddr string `protobuf:"bytes,4,opt,name=mailbox_server_addr,json=mailboxServerAddr,proto3" json:"mailbox_server_addr,omitempty"` + // If set to true, tls will be skipped when connecting to the mailbox. + DevServer bool `protobuf:"varint,5,opt,name=dev_server,json=devServer,proto3" json:"dev_server,omitempty"` + // Any custom permissions to add the session's macaroon. MacaroonCustomPermissions []*MacaroonPermission `protobuf:"bytes,6,rep,name=macaroon_custom_permissions,json=macaroonCustomPermissions,proto3" json:"macaroon_custom_permissions,omitempty"` - AccountId string `protobuf:"bytes,7,opt,name=account_id,json=accountId,proto3" json:"account_id,omitempty"` + // The ID of the account to associate this session with. This should only be + // set if the session_type is TYPE_MACAROON_ACCOUNT. + AccountId string `protobuf:"bytes,7,opt,name=account_id,json=accountId,proto3" json:"account_id,omitempty"` } func (x *AddSessionRequest) Reset() { @@ -236,11 +245,11 @@ type MacaroonPermission struct { Entity string `protobuf:"bytes,1,opt,name=entity,proto3" json:"entity,omitempty"` // The action that is granted. If entity is set to "uri", then action must // be set to either: - // - a particular URI to which access should be granted. - // - a URI regex, in which case access will be granted to each URI that - // matches the regex. - // - the "***readonly***" keyword. This will result in the access being - // granted to all read-only endpoints. + // - a particular URI to which access should be granted. + // - a URI regex, in which case access will be granted to each URI that + // matches the regex. + // - the "***readonly***" keyword. This will result in the access being + // granted to all read-only endpoints. Action string `protobuf:"bytes,2,opt,name=action,proto3" json:"action,omitempty"` } @@ -295,6 +304,7 @@ type AddSessionResponse struct { sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields + // The session of the newly created session. Session *Session `protobuf:"bytes,1,opt,name=session,proto3" json:"session,omitempty"` } @@ -342,21 +352,44 @@ type Session struct { sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - Id []byte `protobuf:"bytes,14,opt,name=id,proto3" json:"id,omitempty"` - Label string `protobuf:"bytes,1,opt,name=label,proto3" json:"label,omitempty"` - SessionState SessionState `protobuf:"varint,2,opt,name=session_state,json=sessionState,proto3,enum=litrpc.SessionState" json:"session_state,omitempty"` - SessionType SessionType `protobuf:"varint,3,opt,name=session_type,json=sessionType,proto3,enum=litrpc.SessionType" json:"session_type,omitempty"` - ExpiryTimestampSeconds uint64 `protobuf:"varint,4,opt,name=expiry_timestamp_seconds,json=expiryTimestampSeconds,proto3" json:"expiry_timestamp_seconds,omitempty"` - MailboxServerAddr string `protobuf:"bytes,5,opt,name=mailbox_server_addr,json=mailboxServerAddr,proto3" json:"mailbox_server_addr,omitempty"` - DevServer bool `protobuf:"varint,6,opt,name=dev_server,json=devServer,proto3" json:"dev_server,omitempty"` - PairingSecret []byte `protobuf:"bytes,7,opt,name=pairing_secret,json=pairingSecret,proto3" json:"pairing_secret,omitempty"` - PairingSecretMnemonic string `protobuf:"bytes,8,opt,name=pairing_secret_mnemonic,json=pairingSecretMnemonic,proto3" json:"pairing_secret_mnemonic,omitempty"` - LocalPublicKey []byte `protobuf:"bytes,9,opt,name=local_public_key,json=localPublicKey,proto3" json:"local_public_key,omitempty"` - RemotePublicKey []byte `protobuf:"bytes,10,opt,name=remote_public_key,json=remotePublicKey,proto3" json:"remote_public_key,omitempty"` - CreatedAt uint64 `protobuf:"varint,11,opt,name=created_at,json=createdAt,proto3" json:"created_at,omitempty"` - MacaroonRecipe *MacaroonRecipe `protobuf:"bytes,12,opt,name=macaroon_recipe,json=macaroonRecipe,proto3" json:"macaroon_recipe,omitempty"` - AccountId string `protobuf:"bytes,13,opt,name=account_id,json=accountId,proto3" json:"account_id,omitempty"` - AutopilotFeatureInfo map[string]*RulesMap `protobuf:"bytes,15,rep,name=autopilot_feature_info,json=autopilotFeatureInfo,proto3" json:"autopilot_feature_info,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"` + // A unique ID assigned to the session. It is derived from the session + // macaroon. + Id []byte `protobuf:"bytes,14,opt,name=id,proto3" json:"id,omitempty"` + // A user assigned label for the session. + Label string `protobuf:"bytes,1,opt,name=label,proto3" json:"label,omitempty"` + // The current state that the session is in. This will give an indication of + // if the session is currently usable or not. + SessionState SessionState `protobuf:"varint,2,opt,name=session_state,json=sessionState,proto3,enum=litrpc.SessionState" json:"session_state,omitempty"` + // The session type. The will given an indication of the restrictions applied + // to the macaroon assigned to the session. + SessionType SessionType `protobuf:"varint,3,opt,name=session_type,json=sessionType,proto3,enum=litrpc.SessionType" json:"session_type,omitempty"` + // The time at which the session will automatically be revoked. + ExpiryTimestampSeconds uint64 `protobuf:"varint,4,opt,name=expiry_timestamp_seconds,json=expiryTimestampSeconds,proto3" json:"expiry_timestamp_seconds,omitempty"` + // The address of the mailbox server that the LNC connection should use. + MailboxServerAddr string `protobuf:"bytes,5,opt,name=mailbox_server_addr,json=mailboxServerAddr,proto3" json:"mailbox_server_addr,omitempty"` + // If set to true, tls will be skipped when connecting to the mailbox. + DevServer bool `protobuf:"varint,6,opt,name=dev_server,json=devServer,proto3" json:"dev_server,omitempty"` + // The LNC pairing phrase in byte form. + PairingSecret []byte `protobuf:"bytes,7,opt,name=pairing_secret,json=pairingSecret,proto3" json:"pairing_secret,omitempty"` + // The LNC pairing phrase in mnemonic form. + PairingSecretMnemonic string `protobuf:"bytes,8,opt,name=pairing_secret_mnemonic,json=pairingSecretMnemonic,proto3" json:"pairing_secret_mnemonic,omitempty"` + // The long term, local static public key used by this node for the LNC + // connection. + LocalPublicKey []byte `protobuf:"bytes,9,opt,name=local_public_key,json=localPublicKey,proto3" json:"local_public_key,omitempty"` + // The long term, remote static public key used by the remote party for the + // LNC connection. + RemotePublicKey []byte `protobuf:"bytes,10,opt,name=remote_public_key,json=remotePublicKey,proto3" json:"remote_public_key,omitempty"` + // The time at which the session was created. + CreatedAt uint64 `protobuf:"varint,11,opt,name=created_at,json=createdAt,proto3" json:"created_at,omitempty"` + // The recipe used for creating a macaroon to use with this session. This will + // be closely linked to the session type. + MacaroonRecipe *MacaroonRecipe `protobuf:"bytes,12,opt,name=macaroon_recipe,json=macaroonRecipe,proto3" json:"macaroon_recipe,omitempty"` + // If the session is for a specific account, then this will be the account ID + // it is associated with. + AccountId string `protobuf:"bytes,13,opt,name=account_id,json=accountId,proto3" json:"account_id,omitempty"` + // If this session is for Autopilot use, then this will be the set of features + // that the session can be used for along with the rules for each feature. + AutopilotFeatureInfo map[string]*RulesMap `protobuf:"bytes,15,rep,name=autopilot_feature_info,json=autopilotFeatureInfo,proto3" json:"autopilot_feature_info,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"` // The unix timestamp indicating the time at which the session was revoked. // Note that this field has not been around since the beginning and so it // could be the case that a session has been revoked but that this field @@ -515,8 +548,10 @@ type MacaroonRecipe struct { sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields + // A list of permissions that should be included in the macaroon. Permissions []*MacaroonPermission `protobuf:"bytes,1,rep,name=permissions,proto3" json:"permissions,omitempty"` - Caveats []string `protobuf:"bytes,2,rep,name=caveats,proto3" json:"caveats,omitempty"` + // A list of caveats to add to the macaroon. + Caveats []string `protobuf:"bytes,2,rep,name=caveats,proto3" json:"caveats,omitempty"` } func (x *MacaroonRecipe) Reset() { @@ -608,6 +643,7 @@ type ListSessionsResponse struct { sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields + // A list of sessions. Sessions []*Session `protobuf:"bytes,1,rep,name=sessions,proto3" json:"sessions,omitempty"` } @@ -655,6 +691,7 @@ type RevokeSessionRequest struct { sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields + // The local static key of the session to be revoked. LocalPublicKey []byte `protobuf:"bytes,8,opt,name=local_public_key,json=localPublicKey,proto3" json:"local_public_key,omitempty"` } @@ -1238,7 +1275,9 @@ type OffChainBudget struct { sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - MaxAmtMsat uint64 `protobuf:"varint,1,opt,name=max_amt_msat,json=maxAmtMsat,proto3" json:"max_amt_msat,omitempty"` + // The maximum amount that can be spent off-chain excluding fees. + MaxAmtMsat uint64 `protobuf:"varint,1,opt,name=max_amt_msat,json=maxAmtMsat,proto3" json:"max_amt_msat,omitempty"` + // The maximum amount that can be spent off-chain on fees. MaxFeesMsat uint64 `protobuf:"varint,2,opt,name=max_fees_msat,json=maxFeesMsat,proto3" json:"max_fees_msat,omitempty"` } @@ -1293,8 +1332,10 @@ type OnChainBudget struct { sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields + // The maximum amount that can be spent on-chain including fees. AbsoluteAmtSats uint64 `protobuf:"varint,1,opt,name=absolute_amt_sats,json=absoluteAmtSats,proto3" json:"absolute_amt_sats,omitempty"` - MaxSatPerVByte uint64 `protobuf:"varint,2,opt,name=max_sat_per_v_byte,json=maxSatPerVByte,proto3" json:"max_sat_per_v_byte,omitempty"` + // The maximum amount that can be spent on-chain in fees. + MaxSatPerVByte uint64 `protobuf:"varint,2,opt,name=max_sat_per_v_byte,json=maxSatPerVByte,proto3" json:"max_sat_per_v_byte,omitempty"` } func (x *OnChainBudget) Reset() { @@ -1386,6 +1427,8 @@ type ChannelRestrict struct { sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields + // A list of channel IDs that the Autopilot should _not_ perform any actions + // on. ChannelIds []uint64 `protobuf:"varint,1,rep,packed,name=channel_ids,json=channelIds,proto3" json:"channel_ids,omitempty"` } @@ -1433,6 +1476,7 @@ type PeerRestrict struct { sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields + // A list of peer IDs that the Autopilot should _not_ perform any actions on. PeerIds []string `protobuf:"bytes,1,rep,name=peer_ids,json=peerIds,proto3" json:"peer_ids,omitempty"` } diff --git a/litrpc/lit-sessions.proto b/litrpc/lit-sessions.proto index 27737f33..ee6289e0 100644 --- a/litrpc/lit-sessions.proto +++ b/litrpc/lit-sessions.proto @@ -7,10 +7,20 @@ option go_package = "github.com/lightninglabs/lightning-terminal/litrpc"; // Sessions is a service that gives access to the core functionalities of the // daemon's session system. service Sessions { + /* litcli: `sessions add` + AddSession adds and starts a new LNC session. + */ rpc AddSession (AddSessionRequest) returns (AddSessionResponse); + /* litcli: `sessions list` + ListSessions returns all sessions known to the session store. + */ rpc ListSessions (ListSessionsRequest) returns (ListSessionsResponse); + /* litcli: `sessions revoke` + RevokeSession revokes a single session and also stops it if it is currently + active. + */ rpc RevokeSession (RevokeSessionRequest) returns (RevokeSessionResponse); } @@ -24,34 +34,61 @@ enum SessionType { } message AddSessionRequest { + /* + A user assigned label for the session. + */ string label = 1; + /* + The session type. This will be used during macaroon construction to + determine how restrictive to make the macaroon and thus the session access. + */ SessionType session_type = 2; + /* + The time at which the session should automatically be revoked. + */ uint64 expiry_timestamp_seconds = 3 [jstype = JS_STRING]; + /* + The address of the mailbox server that the LNC connection should use. + */ string mailbox_server_addr = 4; + /* + If set to true, tls will be skipped when connecting to the mailbox. + */ bool dev_server = 5; + /* + Any custom permissions to add the session's macaroon. + */ repeated MacaroonPermission macaroon_custom_permissions = 6; + /* + The ID of the account to associate this session with. This should only be + set if the session_type is TYPE_MACAROON_ACCOUNT. + */ string account_id = 7; } message MacaroonPermission { - // The entity a permission grants access to. If a entity is set to the - // "uri" keyword then the action entry should be one of the special cases - // described in the comment for action. + /* + The entity a permission grants access to. If a entity is set to the + "uri" keyword then the action entry should be one of the special cases + described in the comment for action. + */ string entity = 1; - // The action that is granted. If entity is set to "uri", then action must - // be set to either: - // - a particular URI to which access should be granted. - // - a URI regex, in which case access will be granted to each URI that - // matches the regex. - // - the "***readonly***" keyword. This will result in the access being - // granted to all read-only endpoints. + /* + The action that is granted. If entity is set to "uri", then action must + be set to either: + - a particular URI to which access should be granted. + - a URI regex, in which case access will be granted to each URI that + matches the regex. + - the "***readonly***" keyword. This will result in the access being + granted to all read-only endpoints. + */ string action = 2; } @@ -63,38 +100,94 @@ enum SessionState { } message AddSessionResponse { + /* + The session of the newly created session. + */ Session session = 1; } message Session { + /* + A unique ID assigned to the session. It is derived from the session + macaroon. + */ bytes id = 14; + /* + A user assigned label for the session. + */ string label = 1; + /* + The current state that the session is in. This will give an indication of + if the session is currently usable or not. + */ SessionState session_state = 2; + /* + The session type. The will given an indication of the restrictions applied + to the macaroon assigned to the session. + */ SessionType session_type = 3; + /* + The time at which the session will automatically be revoked. + */ uint64 expiry_timestamp_seconds = 4 [jstype = JS_STRING]; + /* + The address of the mailbox server that the LNC connection should use. + */ string mailbox_server_addr = 5; + /* + If set to true, tls will be skipped when connecting to the mailbox. + */ bool dev_server = 6; + /* + The LNC pairing phrase in byte form. + */ bytes pairing_secret = 7; + /* + The LNC pairing phrase in mnemonic form. + */ string pairing_secret_mnemonic = 8; + /* + The long term, local static public key used by this node for the LNC + connection. + */ bytes local_public_key = 9; + /* + The long term, remote static public key used by the remote party for the + LNC connection. + */ bytes remote_public_key = 10; + /* + The time at which the session was created. + */ uint64 created_at = 11 [jstype = JS_STRING]; + /* + The recipe used for creating a macaroon to use with this session. This will + be closely linked to the session type. + */ MacaroonRecipe macaroon_recipe = 12; + /* + If the session is for a specific account, then this will be the account ID + it is associated with. + */ string account_id = 13; + /* + If this session is for Autopilot use, then this will be the set of features + that the session can be used for along with the rules for each feature. + */ map autopilot_feature_info = 15; /* @@ -109,8 +202,14 @@ message Session { } message MacaroonRecipe { + /* + A list of permissions that should be included in the macaroon. + */ repeated MacaroonPermission permissions = 1; + /* + A list of caveats to add to the macaroon. + */ repeated string caveats = 2; } @@ -118,10 +217,16 @@ message ListSessionsRequest { } message ListSessionsResponse { + /* + A list of sessions. + */ repeated Session sessions = 1; } message RevokeSessionRequest { + /* + The local static key of the session to be revoked. + */ bytes local_public_key = 8; } @@ -230,12 +335,26 @@ message ChannelPolicyBounds { } message OffChainBudget { + /* + The maximum amount that can be spent off-chain excluding fees. + */ uint64 max_amt_msat = 1 [jstype = JS_STRING]; + + /* + The maximum amount that can be spent off-chain on fees. + */ uint64 max_fees_msat = 2 [jstype = JS_STRING]; } message OnChainBudget { + /* + The maximum amount that can be spent on-chain including fees. + */ uint64 absolute_amt_sats = 1 [jstype = JS_STRING]; + + /* + The maximum amount that can be spent on-chain in fees. + */ uint64 max_sat_per_v_byte = 2 [jstype = JS_STRING]; } @@ -243,9 +362,16 @@ message SendToSelf { } message ChannelRestrict { + /* + A list of channel IDs that the Autopilot should _not_ perform any actions + on. + */ repeated uint64 channel_ids = 1 [jstype = JS_STRING]; } message PeerRestrict { + /* + A list of peer IDs that the Autopilot should _not_ perform any actions on. + */ repeated string peer_ids = 1; -} \ No newline at end of file +} diff --git a/litrpc/lit-sessions_grpc.pb.go b/litrpc/lit-sessions_grpc.pb.go index 845fcde4..a12f4645 100644 --- a/litrpc/lit-sessions_grpc.pb.go +++ b/litrpc/lit-sessions_grpc.pb.go @@ -18,8 +18,15 @@ const _ = grpc.SupportPackageIsVersion7 // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. type SessionsClient interface { + // litcli: `sessions add` + // AddSession adds and starts a new LNC session. AddSession(ctx context.Context, in *AddSessionRequest, opts ...grpc.CallOption) (*AddSessionResponse, error) + // litcli: `sessions list` + // ListSessions returns all sessions known to the session store. ListSessions(ctx context.Context, in *ListSessionsRequest, opts ...grpc.CallOption) (*ListSessionsResponse, error) + // litcli: `sessions revoke` + // RevokeSession revokes a single session and also stops it if it is currently + // active. RevokeSession(ctx context.Context, in *RevokeSessionRequest, opts ...grpc.CallOption) (*RevokeSessionResponse, error) } @@ -62,8 +69,15 @@ func (c *sessionsClient) RevokeSession(ctx context.Context, in *RevokeSessionReq // All implementations must embed UnimplementedSessionsServer // for forward compatibility type SessionsServer interface { + // litcli: `sessions add` + // AddSession adds and starts a new LNC session. AddSession(context.Context, *AddSessionRequest) (*AddSessionResponse, error) + // litcli: `sessions list` + // ListSessions returns all sessions known to the session store. ListSessions(context.Context, *ListSessionsRequest) (*ListSessionsResponse, error) + // litcli: `sessions revoke` + // RevokeSession revokes a single session and also stops it if it is currently + // active. RevokeSession(context.Context, *RevokeSessionRequest) (*RevokeSessionResponse, error) mustEmbedUnimplementedSessionsServer() }