token.proto RawHistoryFolder

1// SPDX-License-Identifier: MIT
2
3syntax = "proto3";
4
5package ermite;
6
7import "google/protobuf/timestamp.proto";
8
9// Scope is a permission carried by a token. The API knows scopes only; any
10// grouping into presets is a client concern.
11enum Scope {
12  // Not set. Rejected in requests, never returned by the server.
13  SCOPE_UNSPECIFIED = 0;
14  // SCOPE_REPO_READ allows reading private repositories (public ones need no
15  // token). Wire name: repo:read.
16  SCOPE_REPO_READ = 1;
17  // SCOPE_REPO_WRITE allows pushing and creating repositories. Wire name:
18  // repo:write.
19  SCOPE_REPO_WRITE = 2;
20  // SCOPE_REPO_ADMIN allows deleting a repository and changing its visibility,
21  // description or default branch. Wire name: repo:admin.
22  SCOPE_REPO_ADMIN = 3;
23  // SCOPE_MR_WRITE allows creating, commenting on and closing merge requests.
24  // Wire name: mr:write.
25  SCOPE_MR_WRITE = 4;
26  // SCOPE_MR_MERGE allows merging merge requests. Wire name: mr:merge.
27  SCOPE_MR_MERGE = 5;
28  // SCOPE_CI_WRITE allows re-running or cancelling CI runs. Wire name:
29  // ci:write.
30  SCOPE_CI_WRITE = 6;
31  // SCOPE_SECRETS_WRITE allows managing secrets, variables and environments
32  // (SecretService, VariableService, EnvironmentService), reads included. A
33  // token limited to branches is refused them even with this scope. Wire name:
34  // secrets:write.
35  SCOPE_SECRETS_WRITE = 7;
36  // SCOPE_RUNNER_REGISTER allows registering a CI runner. Wire name:
37  // runner:register.
38  SCOPE_RUNNER_REGISTER = 8;
39  // SCOPE_TOKEN_ADMIN allows creating, listing and revoking tokens. Wire name:
40  // token:admin.
41  SCOPE_TOKEN_ADMIN = 9;
42  // SCOPE_MR_REVIEW allows setting a verdict (approve, changes requested) on
43  // merge request notes. Wire name: mr:review.
44  SCOPE_MR_REVIEW = 10;
45}
46
47// Token describes a stored token. It never contains the secret nor its hash.
48message Token {
49  // Id identifies the token in ListTokens and RevokeToken. It is not the
50  // secret and cannot be used to authenticate.
51  string id = 1;
52  // Label is a human-readable name chosen at creation.
53  string label = 2;
54  // Scopes are the permissions of the token. Never empty.
55  repeated Scope scopes = 3;
56  // Repos restricts the token to these repository names. Empty means every
57  // repository.
58  repeated string repos = 4;
59  // ExpiresAt is when the token stops working. Unset means it never expires.
60  google.protobuf.Timestamp expires_at = 5;
61  // CreatedAt is when the token was created.
62  google.protobuf.Timestamp created_at = 6;
63  // LastUsedAt is when the token last authenticated a request. Unset if never
64  // used. It may lag behind the real time by a short delay.
65  google.protobuf.Timestamp last_used_at = 7;
66  // BranchPrefixes limits the branches the token may write. Each prefix ends
67  // with "/" (for example "agent/claude/"). Empty means every branch. A limited
68  // token can push, force-push and delete only branches under its prefixes; it
69  // cannot push tags or other refs, create repositories, or merge into or
70  // delete a branch outside its prefixes.
71  repeated string branch_prefixes = 8;
72}
73
74// TokenService manages stored tokens. Every RPC needs the token:admin scope.
75//
76// A token can only create tokens that are within its own limits: scopes that
77// it holds, repositories that it may access and an expiry no later than its
78// own (including its branch prefixes). The root token (ERMITE_ADMIN_TOKEN) is not a stored token and is never
79// listed.
80service TokenService {
81  // CreateToken creates a token and returns its secret. The secret is shown
82  // only in this response and cannot be retrieved later. Fails with
83  // permission_denied when the new token would exceed the caller's limits and
84  // with invalid_argument when scopes is empty or contains SCOPE_UNSPECIFIED.
85  rpc CreateToken(CreateTokenRequest) returns (CreateTokenResponse);
86  // ListTokens lists stored tokens, newest first.
87  rpc ListTokens(ListTokensRequest) returns (ListTokensResponse);
88  // RevokeToken deletes a token; it stops working immediately. Fails with
89  // not_found if the id is unknown.
90  rpc RevokeToken(RevokeTokenRequest) returns (RevokeTokenResponse);
91}
92
93// CreateTokenRequest describes the token to create.
94message CreateTokenRequest {
95  // Label is a human-readable name, for example "laptop". Not required to be
96  // unique.
97  string label = 1;
98  // Scopes are the permissions to grant. At least one is required.
99  repeated Scope scopes = 2;
100  // Repos restricts the token to these repository names. Empty means every
101  // repository.
102  repeated string repos = 3;
103  // ExpiresAt is when the token stops working. Unset means no expiry. It must
104  // be in the future.
105  google.protobuf.Timestamp expires_at = 4;
106  // BranchPrefixes limits the branches the token may write, for example
107  // "agent/claude/". Each prefix must end with "/" and be a valid branch name
108  // once the "/" is removed; at most 8 are allowed. Empty means every branch;
109  // a limited token cannot push tags or create repositories. A token that has
110  // prefixes can only create tokens whose prefixes each lie within its own.
111  // Fails with invalid_argument when a prefix is malformed.
112  repeated string branch_prefixes = 5;
113}
114
115// CreateTokenResponse holds the new token and its secret.
116message CreateTokenResponse {
117  // Token describes the created token.
118  Token token = 1;
119  // Secret is the bearer secret to present as "Authorization: Bearer <secret>".
120  // It is returned once and never stored in clear text by the server.
121  string secret = 2;
122}
123
124// ListTokensRequest selects a page of tokens.
125message ListTokensRequest {
126  // PageSize is the maximum number of tokens to return. 0 means the server
127  // default; values above the server maximum are lowered to it.
128  int32 page_size = 1;
129  // PageToken is the next_page_token of a previous response. Empty for the
130  // first page.
131  string page_token = 2;
132}
133
134// ListTokensResponse is one page of tokens.
135message ListTokensResponse {
136  // Tokens are the tokens of this page, newest first.
137  repeated Token tokens = 1;
138  // NextPageToken is passed as page_token to get the next page. Empty when
139  // there is no next page.
140  string next_page_token = 2;
141}
142
143// RevokeTokenRequest names the token to revoke.
144message RevokeTokenRequest {
145  // Id is the Token.id to revoke.
146  string id = 1;
147}
148
149// RevokeTokenResponse is empty.
150message RevokeTokenResponse {}