Skip to content

session: add a new session token v2 #350

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

session: add a new session token v2 #350

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 106 additions & 7 deletions proto-docs/session.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,15 +18,20 @@

- 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)


Expand Down Expand Up @@ -147,6 +152,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. |


<a name="neo.fs.v2.session.DelegationInfo"></a>

### 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. |
| 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. |


<a name="neo.fs.v2.session.ObjectSessionContext"></a>

### Message ObjectSessionContext
Expand Down Expand Up @@ -185,6 +205,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. |
Expand Down Expand Up @@ -234,6 +255,19 @@ Verification info for the response signed by all intermediate nodes
| origin | [ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Chain of previous hops signatures |


<a name="neo.fs.v2.session.SessionContextV2"></a>

### 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. |
| verbs | [Verb](#neo.fs.v2.session.Verb) | repeated | Operations authorized for this context. |


<a name="neo.fs.v2.session.SessionToken"></a>

### Message SessionToken
Expand All @@ -256,23 +290,65 @@ Session Token body
| ----- | ---- | ----- | ----------- |
| id | [bytes](#bytes) | | Token identifier is a valid UUIDv4 in binary form |
| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Identifier of the session initiator |
| lifetime | [SessionToken.Body.TokenLifetime](#neo.fs.v2.session.SessionToken.Body.TokenLifetime) | | Lifetime of the session |
| lifetime | [TokenLifetime](#neo.fs.v2.session.TokenLifetime) | | Lifetime of the session |
| session_key | [bytes](#bytes) | | Public key used in session |
| object | [ObjectSessionContext](#neo.fs.v2.session.ObjectSessionContext) | | ObjectService session context |
| container | [ContainerSessionContext](#neo.fs.v2.session.ContainerSessionContext) | | ContainerService session context |


<a name="neo.fs.v2.session.SessionToken.Body.TokenLifetime"></a>
<a name="neo.fs.v2.session.SessionTokenV2"></a>

### 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. |


<a name="neo.fs.v2.session.SessionTokenV2.Body"></a>

### Message SessionTokenV2.Body
Session Token body.

### Message SessionToken.Body.TokenLifetime

| 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). |
| 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. |


<a name="neo.fs.v2.session.Target"></a>

### 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. |


<a name="neo.fs.v2.session.TokenLifetime"></a>

### Message TokenLifetime
Lifetime parameters of the token. Field names taken from rfc7519.


| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| exp | [uint64](#uint64) | | Expiration epoch, the last epoch when token is valid. |
| nbf | [uint64](#uint64) | | Not valid before epoch, the first epoch when token is valid. |
| iat | [uint64](#uint64) | | Issued at Epoch |
| exp | [uint64](#uint64) | | Expiration epoch, the last epoch when token is valid. For SessionTokenV2 this is the last valid Unix timestamp. |
| nbf | [uint64](#uint64) | | Not valid before epoch, the first epoch when token is valid. For SessionTokenV2 this is the first valid Unix timestamp. |
| iat | [uint64](#uint64) | | Issued at epoch. For SessionTokenV2 this is the Unix timestamp when the token was issued. |


<a name="neo.fs.v2.session.XHeader"></a>
Expand Down Expand Up @@ -338,6 +414,29 @@ Object request verbs
| RANGEHASH | 7 | Refers to object.GetRangeHash RPC call |



<a name="neo.fs.v2.session.Verb"></a>

### 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 |


<!-- end enums -->


Expand Down
165 changes: 154 additions & 11 deletions session/types.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -85,6 +127,21 @@ message ContainerSessionContext {
refs.ContainerID container_id = 3 [json_name = "containerID"];
}

// Lifetime parameters of the token. Field names taken from rfc7519.
message TokenLifetime {
// Expiration epoch, the last epoch when token is valid.
// For SessionTokenV2 this is the last valid Unix timestamp.
Copy link
Member

@roman-khimov roman-khimov Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. It's very different in semantics.
  2. Compatibility warning fires for the removal of old TokenLifetime, so we can keep it as is and add this new one for v2.

uint64 exp = 1 [json_name = "exp"];

// Not valid before epoch, the first epoch when token is valid.
// For SessionTokenV2 this is the first valid Unix timestamp.
uint64 nbf = 2 [json_name = "nbf"];

// Issued at epoch.
// For SessionTokenV2 this is the Unix timestamp when the token was issued.
uint64 iat = 3 [json_name = "iat"];
}

// NeoFS Session Token.
message SessionToken {
// Session Token body
Expand All @@ -95,17 +152,6 @@ message SessionToken {
// Identifier of the session initiator
neo.fs.v2.refs.OwnerID owner_id = 2 [json_name = "ownerID"];

// Lifetime parameters of the token. Field names taken from rfc7519.
message TokenLifetime {
// Expiration epoch, the last epoch when token is valid.
uint64 exp = 1 [json_name = "exp"];

// Not valid before epoch, the first epoch when token is valid.
uint64 nbf = 2 [json_name = "nbf"];

// Issued at Epoch
uint64 iat = 3 [json_name = "iat"];
}
// Lifetime of the session
TokenLifetime lifetime = 3 [json_name = "lifetime"];

Expand Down Expand Up @@ -175,6 +221,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"];

Expand Down Expand Up @@ -232,3 +282,96 @@ 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.
Copy link
Member

@roman-khimov roman-khimov Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mention NEP-18?

string nns_name = 2 [json_name = "nnsName"];
}
}

// 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.
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.
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).
Copy link
Member

@roman-khimov roman-khimov Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need some limits for all repeated fields.

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.
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.
repeated DelegationInfo delegation_chain = 3 [json_name = "delegationChain"];
}
Loading