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