diff --git a/proto-docs/session.md b/proto-docs/session.md index 50e5367..fc67cbc 100644 --- a/proto-docs/session.md +++ b/proto-docs/session.md @@ -18,15 +18,21 @@ - Messages - [ContainerSessionContext](#neo.fs.v2.session.ContainerSessionContext) + - [DelegationInfo](#neo.fs.v2.session.DelegationInfo) - [ObjectSessionContext](#neo.fs.v2.session.ObjectSessionContext) - [ObjectSessionContext.Target](#neo.fs.v2.session.ObjectSessionContext.Target) - [RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) - [RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) - [ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) - [ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) + - [SessionContextV2](#neo.fs.v2.session.SessionContextV2) - [SessionToken](#neo.fs.v2.session.SessionToken) - [SessionToken.Body](#neo.fs.v2.session.SessionToken.Body) - [SessionToken.Body.TokenLifetime](#neo.fs.v2.session.SessionToken.Body.TokenLifetime) + - [SessionTokenV2](#neo.fs.v2.session.SessionTokenV2) + - [SessionTokenV2.Body](#neo.fs.v2.session.SessionTokenV2.Body) + - [Target](#neo.fs.v2.session.Target) + - [TokenLifetime](#neo.fs.v2.session.TokenLifetime) - [XHeader](#neo.fs.v2.session.XHeader) @@ -147,6 +153,21 @@ Context information for Session Tokens related to ContainerService requests. | container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Particular container to which the action applies. Ignored if wildcard flag is set. | + + +### Message DelegationInfo +DelegationInfo represents a single delegation in a chain of trust. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| issuer | [Target](#neo.fs.v2.session.Target) | | Account that performed this delegation. | +| subjects | [Target](#neo.fs.v2.session.Target) | repeated | Accounts that received the delegation. Maximum number of subjects: 100. | +| lifetime | [TokenLifetime](#neo.fs.v2.session.TokenLifetime) | | Lifetime of this delegation. Allows each delegation in the chain to have its own validity window. | +| verbs | [Verb](#neo.fs.v2.session.Verb) | repeated | List of verbs authorized by this delegation. | +| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of the issuer confirming this delegation record. The signature is created over the deterministic serialization of this DelegationInfo message excluding this field. | + + ### Message ObjectSessionContext @@ -185,6 +206,7 @@ request meta headers are folded in matryoshka style. | ttl | [uint32](#uint32) | | Maximum number of intermediate nodes in the request route | | x_headers | [XHeader](#neo.fs.v2.session.XHeader) | repeated | Request X-Headers | | session_token | [SessionToken](#neo.fs.v2.session.SessionToken) | | Session token within which the request is sent | +| session_token_v2 | [SessionTokenV2](#neo.fs.v2.session.SessionTokenV2) | | Session token v2 with delegation chain support. If both session_token and session_token_v2 are set, session_token_v2 takes precedence. | | bearer_token | [neo.fs.v2.acl.BearerToken](#neo.fs.v2.acl.BearerToken) | | `BearerToken` with eACL overrides for the request | | origin | [RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | `RequestMetaHeader` of the origin request | | magic_number | [uint64](#uint64) | | NeoFS network magic. Must match the value for the network that the server belongs to. | @@ -234,6 +256,19 @@ Verification info for the response signed by all intermediate nodes | origin | [ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Chain of previous hops signatures | + + +### Message SessionContextV2 +SessionContextV2 carries unified context for both ObjectService and ContainerService requests. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| container | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Container where operation is allowed. For container operations, this is the container being operated on. For object operations, this is the container holding the objects. | +| objects | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | Specific objects where operation is allowed. Only relevant for object operations. Empty list means all objects in the container. Maximum number of objects: 1000. | +| verbs | [Verb](#neo.fs.v2.session.Verb) | repeated | Operations authorized for this context. | + + ### Message SessionToken @@ -275,6 +310,61 @@ Lifetime parameters of the token. Field names taken from rfc7519. | iat | [uint64](#uint64) | | Issued at Epoch | + + +### Message SessionTokenV2 +SessionTokenV2 represents NeoFS Session Token with delegation support. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| body | [SessionTokenV2.Body](#neo.fs.v2.session.SessionTokenV2.Body) | | Session token body. | +| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of the body by the issuer. | +| delegation_chain | [DelegationInfo](#neo.fs.v2.session.DelegationInfo) | repeated | DelegationInfo is a full history of authority delegation (chain of trust). Similar to X.509 certificate chains, each delegation entry is independently signed by its issuer. Maximum chain depth: 10. | + + + + +### Message SessionTokenV2.Body +Session Token body. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| version | [uint32](#uint32) | | Token version. | +| id | [bytes](#bytes) | | Token identifier (UUIDv4 in binary form). | +| issuer | [Target](#neo.fs.v2.session.Target) | | Account that issued this token (who signed it). | +| subjects | [Target](#neo.fs.v2.session.Target) | repeated | Accounts authorized by this token (who can use it). Maximum number of subjects: 100. | +| lifetime | [TokenLifetime](#neo.fs.v2.session.TokenLifetime) | | Lifetime of this token. | +| contexts | [SessionContextV2](#neo.fs.v2.session.SessionContextV2) | repeated | Unified session contexts for both object and container operations. Multiple contexts allow authorization for different combinations. Maximum number of contexts: 100. | + + + + +### Message Target +Target account for SessionTokenV2. +It can be either direct (OwnerID) or indirect (NNS domain). + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Direct account reference via OwnerID (hash of verification script). | +| nns_name | [string](#string) | | Indirect account reference via NeoFS Name Service. NNS name is a domain name that resolves to an OwnerID through the NeoFS Name Service. The name must be a valid DNS-like domain name (e.g., "example.neofs") that is registered in the NNS contract on the Neo blockchain. The NNS record should contain a string record with the corresponding OwnerID value in NEP-18 address format. | + + + + +### Message TokenLifetime +Lifetime parameters of the token v2. Field names taken from rfc7519. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| exp | [uint64](#uint64) | | Expiration, the last valid Unix timestamp. | +| nbf | [uint64](#uint64) | | Not valid before, the first valid Unix timestamp. | +| iat | [uint64](#uint64) | | Issued at, the Unix timestamp when the token was issued. | + + ### Message XHeader @@ -338,6 +428,29 @@ Object request verbs | RANGEHASH | 7 | Refers to object.GetRangeHash RPC call | + + + +### Verb +Verb represents all possible operations in NeoFS that can be authorized +via session tokens or delegation chains. This enum covers both object and +container service operations. + +| Name | Number | Description | +| ---- | ------ | ----------- | +| VERB_UNSPECIFIED | 0 | Unknown verb | +| OBJECT_PUT | 1 | Refers to object.Put RPC call | +| OBJECT_GET | 2 | Refers to object.Get RPC call | +| OBJECT_HEAD | 3 | Refers to object.Head RPC call | +| OBJECT_SEARCH | 4 | Refers to object.Search RPC call | +| OBJECT_DELETE | 5 | Refers to object.Delete RPC call | +| OBJECT_RANGE | 6 | Refers to object.GetRange RPC call | +| OBJECT_RANGEHASH | 7 | Refers to object.GetRangeHash RPC call | +| CONTAINER_PUT | 8 | Refers to container.Put RPC call | +| CONTAINER_DELETE | 9 | Refers to container.Delete RPC call | +| CONTAINER_SETEACL | 10 | Refers to container.SetExtendedACL RPC call | + + diff --git a/session/types.proto b/session/types.proto index dcfef8c..f90197b 100644 --- a/session/types.proto +++ b/session/types.proto @@ -9,6 +9,48 @@ import "status/types.proto"; option csharp_namespace = "Neo.FileStorage.API.Session"; option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/session"; +// Verb represents all possible operations in NeoFS that can be authorized +// via session tokens or delegation chains. This enum covers both object and +// container service operations. +enum Verb { + // Unknown verb + VERB_UNSPECIFIED = 0; + + // Object operations + + // Refers to object.Put RPC call + OBJECT_PUT = 1; + + // Refers to object.Get RPC call + OBJECT_GET = 2; + + // Refers to object.Head RPC call + OBJECT_HEAD = 3; + + // Refers to object.Search RPC call + OBJECT_SEARCH = 4; + + // Refers to object.Delete RPC call + OBJECT_DELETE = 5; + + // Refers to object.GetRange RPC call + OBJECT_RANGE = 6; + + // Refers to object.GetRangeHash RPC call + OBJECT_RANGEHASH = 7; + + // Container operations + + // Refers to container.Put RPC call + CONTAINER_PUT = 8; + + // Refers to container.Delete RPC call + CONTAINER_DELETE = 9; + + // Refers to container.SetExtendedACL RPC call + CONTAINER_SETEACL = 10; +} + // Context information for Session Tokens related to ObjectService requests message ObjectSessionContext { // Object request verbs @@ -175,6 +217,10 @@ message RequestMetaHeader { // Session token within which the request is sent SessionToken session_token = 5 [json_name = "sessionToken"]; + // Session token v2 with delegation chain support. + // If both session_token and session_token_v2 are set, session_token_v2 takes precedence. + SessionTokenV2 session_token_v2 = 9 [json_name = "sessionTokenV2"]; + // `BearerToken` with eACL overrides for the request neo.fs.v2.acl.BearerToken bearer_token = 6 [json_name = "bearerToken"]; @@ -232,3 +278,114 @@ message ResponseVerificationHeader { // Chain of previous hops signatures ResponseVerificationHeader origin = 4 [json_name = "origin"]; } + +// Session Token v2 + +// Target account for SessionTokenV2. +// It can be either direct (OwnerID) or indirect (NNS domain). +message Target { + // Account identifier. + oneof identifier { + // Direct account reference via OwnerID (hash of verification script). + neo.fs.v2.refs.OwnerID owner_id = 1 [json_name = "ownerID"]; + + // Indirect account reference via NeoFS Name Service. + // NNS name is a domain name that resolves to an OwnerID through the + // NeoFS Name Service. The name must be a valid DNS-like domain name + // (e.g., "example.neofs") that is registered in the NNS contract on + // the Neo blockchain. The NNS record should contain a string record with + // the corresponding OwnerID value in NEP-18 address format. + string nns_name = 2 [json_name = "nnsName"]; + } +} + +// Lifetime parameters of the token v2. Field names taken from rfc7519. +message TokenLifetime { + // Expiration, the last valid Unix timestamp. + uint64 exp = 1 [json_name = "exp"]; + + // Not valid before, the first valid Unix timestamp. + uint64 nbf = 2 [json_name = "nbf"]; + + // Issued at, the Unix timestamp when the token was issued. + uint64 iat = 3 [json_name = "iat"]; +} + + +// DelegationInfo represents a single delegation in a chain of trust. +message DelegationInfo { + // Account that performed this delegation. + Target issuer = 1 [json_name = "issuer"]; + + // Accounts that received the delegation. + // Maximum number of subjects: 100. + repeated Target subjects = 2 [json_name = "subjects"]; + + // Lifetime of this delegation. + // Allows each delegation in the chain to have its own validity window. + TokenLifetime lifetime = 3 [json_name = "lifetime"]; + + // List of verbs authorized by this delegation. + repeated Verb verbs = 4 [json_name = "verbs"]; + + // Signature of the issuer confirming this delegation record. + // The signature is created over the deterministic serialization + // of this DelegationInfo message excluding this field. + neo.fs.v2.refs.Signature signature = 5 [json_name = "signature"]; +} + +// SessionContextV2 carries unified context for both ObjectService and ContainerService requests. +message SessionContextV2 { + // Container where operation is allowed. + // For container operations, this is the container being operated on. + // For object operations, this is the container holding the objects. + neo.fs.v2.refs.ContainerID container = 1 [json_name = "container"]; + + // Specific objects where operation is allowed. + // Only relevant for object operations. + // Empty list means all objects in the container. + // Maximum number of objects: 1000. + repeated neo.fs.v2.refs.ObjectID objects = 2 [json_name = "objects"]; + + // Operations authorized for this context. + repeated Verb verbs = 3 [json_name = "verbs"]; +} + +// SessionTokenV2 represents NeoFS Session Token with delegation support. +message SessionTokenV2 { + // Session Token body. + message Body { + // Token version. + uint32 version = 1 [json_name = "version"]; + + // Token identifier (UUIDv4 in binary form). + bytes id = 2 [json_name = "id"]; + + // Account that issued this token (who signed it). + Target issuer = 3 [json_name = "issuer"]; + + // Accounts authorized by this token (who can use it). + // Maximum number of subjects: 100. + repeated Target subjects = 4 [json_name = "subjects"]; + + // Lifetime of this token. + TokenLifetime lifetime = 5 [json_name = "lifetime"]; + + // Unified session contexts for both object and container operations. + // Multiple contexts allow authorization for different combinations. + // Maximum number of contexts: 100. + repeated SessionContextV2 contexts = 6 [json_name = "contexts"]; + } + + // Session token body. + Body body = 1 [json_name = "body"]; + + // Signature of the body by the issuer. + neo.fs.v2.refs.Signature signature = 2 [json_name = "signature"]; + + // DelegationInfo is a full history of authority delegation (chain of trust). + // Similar to X.509 certificate chains, each delegation entry + // is independently signed by its issuer. + // Maximum chain depth: 10. + repeated DelegationInfo delegation_chain = 3 [json_name = "delegationChain"]; +}