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  // SCOPE_ISSUE_WRITE allows creating, commenting on, closing and reopening
46  // issues. Wire name: issue:write.
47  SCOPE_ISSUE_WRITE = 11;
48}
49
50// Token describes a stored token. It never contains the secret nor its hash.
51message Token {
52  // Id identifies the token in ListTokens and RevokeToken. It is not the
53  // secret and cannot be used to authenticate.
54  string id = 1;
55  // Label is a human-readable name chosen at creation.
56  string label = 2;
57  // Scopes are the permissions of the token. Never empty.
58  repeated Scope scopes = 3;
59  // Repos restricts the token to these repository names. Empty means every
60  // repository.
61  repeated string repos = 4;
62  // ExpiresAt is when the token stops working. Unset means it never expires.
63  google.protobuf.Timestamp expires_at = 5;
64  // CreatedAt is when the token was created.
65  google.protobuf.Timestamp created_at = 6;
66  // LastUsedAt is when the token last authenticated a request. Unset if never
67  // used. It may lag behind the real time by a short delay.
68  google.protobuf.Timestamp last_used_at = 7;
69  // BranchPrefixes limits the branches the token may write. Each prefix ends
70  // with "/" (for example "agent/claude/"). Empty means every branch. A limited
71  // token can push, force-push and delete only branches under its prefixes; it
72  // cannot push tags or other refs, create repositories, or merge into or
73  // delete a branch outside its prefixes.
74  repeated string branch_prefixes = 8;
75}
76
77// TokenService manages stored tokens. Every RPC needs the token:admin scope.
78//
79// A token can only create tokens that are within its own limits: scopes that
80// it holds, repositories that it may access and an expiry no later than its
81// own (including its branch prefixes). The root token (ERMITE_ADMIN_TOKEN) is not a stored token and is never
82// listed.
83service TokenService {
84  // CreateToken creates a token and returns its secret. The secret is shown
85  // only in this response and cannot be retrieved later. Fails with
86  // permission_denied when the new token would exceed the caller's limits and
87  // with invalid_argument when scopes is empty or contains SCOPE_UNSPECIFIED.
88  rpc CreateToken(CreateTokenRequest) returns (CreateTokenResponse);
89  // ListTokens lists stored tokens, newest first.
90  rpc ListTokens(ListTokensRequest) returns (ListTokensResponse);
91  // RevokeToken deletes a token; it stops working immediately. Fails with
92  // not_found if the id is unknown.
93  rpc RevokeToken(RevokeTokenRequest) returns (RevokeTokenResponse);
94}
95
96// CreateTokenRequest describes the token to create.
97message CreateTokenRequest {
98  // Label is a human-readable name, for example "laptop". Not required to be
99  // unique.
100  string label = 1;
101  // Scopes are the permissions to grant. At least one is required.
102  repeated Scope scopes = 2;
103  // Repos restricts the token to these repository names. Empty means every
104  // repository.
105  repeated string repos = 3;
106  // ExpiresAt is when the token stops working. Unset means no expiry. It must
107  // be in the future.
108  google.protobuf.Timestamp expires_at = 4;
109  // BranchPrefixes limits the branches the token may write, for example
110  // "agent/claude/". Each prefix must end with "/" and be a valid branch name
111  // once the "/" is removed; at most 8 are allowed. Empty means every branch;
112  // a limited token cannot push tags or create repositories. A token that has
113  // prefixes can only create tokens whose prefixes each lie within its own.
114  // Fails with invalid_argument when a prefix is malformed.
115  repeated string branch_prefixes = 5;
116}
117
118// CreateTokenResponse holds the new token and its secret.
119message CreateTokenResponse {
120  // Token describes the created token.
121  Token token = 1;
122  // Secret is the bearer secret to present as "Authorization: Bearer <secret>".
123  // It is returned once and never stored in clear text by the server.
124  string secret = 2;
125}
126
127// ListTokensRequest selects a page of tokens.
128message ListTokensRequest {
129  // PageSize is the maximum number of tokens to return. 0 means the server
130  // default; values above the server maximum are lowered to it.
131  int32 page_size = 1;
132  // PageToken is the next_page_token of a previous response. Empty for the
133  // first page.
134  string page_token = 2;
135}
136
137// ListTokensResponse is one page of tokens.
138message ListTokensResponse {
139  // Tokens are the tokens of this page, newest first.
140  repeated Token tokens = 1;
141  // NextPageToken is passed as page_token to get the next page. Empty when
142  // there is no next page.
143  string next_page_token = 2;
144}
145
146// RevokeTokenRequest names the token to revoke.
147message RevokeTokenRequest {
148  // Id is the Token.id to revoke.
149  string id = 1;
150}
151
152// RevokeTokenResponse is empty.
153message RevokeTokenResponse {}