1// SPDX-License-Identifier: AGPL-3.0-or-later
2
3package domain
4
5import (
6 "strings"
7 "time"
8)
9
10// RepoTokenPrefix starts the secret of a job repository token: the
11// "github.token" of a job, or the token of one action archive. Unlike the
12// stored tokens (TokenSecretPrefix) it is never created, listed or revoked by
13// a person: the CI engine issues it with a job and revokes it with the job.
14const RepoTokenPrefix = "ermitegh_"
15
16// IsRepoToken reports whether s has the shape of a job repository token.
17func IsRepoToken(s string) bool { return hasTokenShape(s, RepoTokenPrefix) }
18
19// repoTokenIDPrefix starts the TokenID of the principal of a job repository
20// token, so that it never collides with the ID of a stored token.
21const repoTokenIDPrefix = "job:"
22
23// IsRepoTokenID reports whether id is the TokenID of the principal of a job
24// repository token (see RepoTokenPrincipal).
25func IsRepoTokenID(id string) bool { return strings.HasPrefix(id, repoTokenIDPrefix) }
26
27// CIRepoToken is a job repository token: it reads one repository, until
28// ExpiresAt or the end of its job. The secret is never stored, only its hash.
29type CIRepoToken struct {
30 // ID identifies the token; it is not secret.
31 ID string
32 Hash TokenHash
33 // Repo is the one repository the token reads.
34 Repo RepoName
35 // RunID, RunAttempt and JobID name the job it belongs to.
36 RunID int64
37 RunAttempt int32
38 JobID string
39 // Archive is set for the token of an action archive, unset for the job's
40 // own token ("github.token"). An archive token downloads the commit Sha of
41 // Repo and nothing else.
42 Archive bool
43 // Sha is the commit an archive token is bound to; empty for the job's own.
44 Sha string
45 ExpiresAt time.Time
46 CreatedAt time.Time
47}
48
49// Expired reports whether the token is no longer valid at now.
50func (t CIRepoToken) Expired(now time.Time) bool { return !now.Before(t.ExpiresAt) }
51
52// RepoTokenGrace is how long a job repository token outlives the deadline of
53// its job at the most (a safety net: it is revoked when the job ends).
54const RepoTokenGrace = 5 * time.Minute
55
56// RepoTokenPrincipal returns the principal of the holder of a job repository
57// token.
58//
59// The job's own token is shaped like a stored token (the scope repo:read on one
60// repository, an expiry), so that every authorization rule of the forge applies
61// to it unchanged: it reads that repository, even when private, and writes
62// nothing.
63//
64// An archive token holds no scope at all: it is the grant to download one
65// commit of one repository as an archive, which only the archive endpoint
66// reads (Principal.ArchiveGrant). Git over HTTP, the repository endpoint and
67// the rest of the API see a caller with no rights, so a private repository
68// does not show itself to it.
69//
70// Both have a TokenID that starts with "job:" and matches no stored token.
71func RepoTokenPrincipal(t CIRepoToken) Principal {
72 if t.Archive {
73 return Principal{
74 kind: kindArchive, tokenID: repoTokenIDPrefix + t.ID, label: "ci archive", expiresAt: t.ExpiresAt,
75 archiveRepo: t.Repo, archiveSha: t.Sha,
76 }
77 }
78 return TokenPrincipal(Token{
79 ID: repoTokenIDPrefix + t.ID, Label: "ci job", Scopes: []Scope{ScopeRepoRead},
80 Repos: []RepoName{t.Repo}, ExpiresAt: t.ExpiresAt, CreatedAt: t.CreatedAt,
81 })
82}
83
84// CIPusherKind tells who pushed the commit of a run.
85type CIPusherKind string
86
87// Pusher kinds. The zero value is a run stored before the pusher was recorded.
88const (
89 CIPusherNone CIPusherKind = ""
90 CIPusherRoot CIPusherKind = "root"
91 CIPusherOwner CIPusherKind = "owner"
92 CIPusherToken CIPusherKind = "token"
93)
94
95// CIPusher is who pushed the commit of a run, as recorded with the run. A
96// token is recorded by its ID only: what it may read is looked up when it is
97// needed, so a token revoked since no longer reads anything on behalf of the
98// run.
99type CIPusher struct {
100 Kind CIPusherKind
101 TokenID string
102}
103
104// PusherOf records the pusher p. Anonymous callers, which cannot push, and the
105// holders of job tokens, which cannot either, are recorded as nobody.
106func PusherOf(p Principal) CIPusher {
107 switch {
108 case p.IsOwner():
109 return CIPusher{Kind: CIPusherOwner}
110 case p.IsRoot():
111 return CIPusher{Kind: CIPusherRoot}
112 case p.TokenID() != "" && !IsRepoTokenID(p.TokenID()):
113 return CIPusher{Kind: CIPusherToken, TokenID: p.TokenID()}
114 }
115 return CIPusher{}
116}
117
118// CIActionSource says where an action was found.
119type CIActionSource int
120
121// Action sources, with the numbers of ActionSource in the protocol.
122const (
123 CIActionGitHub CIActionSource = 1
124 CIActionErmite CIActionSource = 2
125)
126
127// CIActionResolution is the resolution of an action reference for one run
128// attempt: every job of the attempt gets the same commit.
129type CIActionResolution struct {
130 RunID int64
131 RunAttempt int32
132 // Key is "owner/repo@ref", lower-cased.
133 Key string
134 NameWithOwner string
135 ResolvedSHA string
136 Source CIActionSource
137}