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