@leed-ai/git-gateway-contract 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +201 -0
- package/README.md +50 -2
- package/dist/behaviour/assertions.d.ts +23 -0
- package/dist/behaviour/assertions.js +56 -0
- package/dist/behaviour/assertions.js.map +1 -0
- package/dist/behaviour/behaviour-case.d.ts +19 -0
- package/dist/behaviour/behaviour-case.js +12 -0
- package/dist/behaviour/behaviour-case.js.map +1 -0
- package/dist/behaviour/behaviour-suite.d.ts +30 -0
- package/dist/behaviour/behaviour-suite.js +50 -0
- package/dist/behaviour/behaviour-suite.js.map +1 -0
- package/dist/behaviour/commit-action-cases.d.ts +4 -0
- package/dist/behaviour/commit-action-cases.js +342 -0
- package/dist/behaviour/commit-action-cases.js.map +1 -0
- package/dist/behaviour/commit-write-cases.d.ts +4 -0
- package/dist/behaviour/commit-write-cases.js +234 -0
- package/dist/behaviour/commit-write-cases.js.map +1 -0
- package/dist/behaviour/fixtures.d.ts +29 -0
- package/dist/behaviour/fixtures.js +83 -0
- package/dist/behaviour/fixtures.js.map +1 -0
- package/dist/behaviour/lifecycle-cases.d.ts +4 -0
- package/dist/behaviour/lifecycle-cases.js +158 -0
- package/dist/behaviour/lifecycle-cases.js.map +1 -0
- package/dist/behaviour/promote-cases.d.ts +4 -0
- package/dist/behaviour/promote-cases.js +122 -0
- package/dist/behaviour/promote-cases.js.map +1 -0
- package/dist/behaviour/read-cases.d.ts +4 -0
- package/dist/behaviour/read-cases.js +248 -0
- package/dist/behaviour/read-cases.js.map +1 -0
- package/dist/behaviour/sync-cases.d.ts +4 -0
- package/dist/behaviour/sync-cases.js +205 -0
- package/dist/behaviour/sync-cases.js.map +1 -0
- package/dist/clock-B3MlpmVY.d.ts +10 -0
- package/dist/commit-BEZmeAOl.d.ts +23 -0
- package/dist/file-map-CxUveLWz.d.ts +18 -0
- package/dist/gateway-config-oVsdTEeK.d.ts +39 -0
- package/dist/gateway-error-body-BWzZFAQI.d.ts +214 -0
- package/dist/gateway-error.d.ts +30 -0
- package/dist/gateway-error.js +63 -0
- package/dist/gateway-error.js.map +1 -0
- package/dist/git-gateway-VA9Tc5tn.d.ts +358 -0
- package/dist/git-gateway.d.ts +2 -0
- package/dist/git-gateway.js +65 -0
- package/dist/git-gateway.js.map +1 -0
- package/dist/health.d.ts +9 -0
- package/dist/health.js +18 -0
- package/dist/health.js.map +1 -0
- package/dist/history-CqvHaUE-.d.ts +20 -0
- package/dist/package-name.d.ts +3 -0
- package/dist/package-name.js +6 -0
- package/dist/package-name.js.map +1 -0
- package/dist/proxy/audit-event.d.ts +61 -0
- package/dist/proxy/audit-event.js +97 -0
- package/dist/proxy/audit-event.js.map +1 -0
- package/dist/proxy/branch-rule.d.ts +72 -0
- package/dist/proxy/branch-rule.js +106 -0
- package/dist/proxy/branch-rule.js.map +1 -0
- package/dist/proxy/gateway-hooks.d.ts +58 -0
- package/dist/proxy/gateway-hooks.js +0 -0
- package/dist/proxy/git-operation.d.ts +17 -0
- package/dist/proxy/git-operation.js +32 -0
- package/dist/proxy/git-operation.js.map +1 -0
- package/dist/proxy/policy-result.d.ts +51 -0
- package/dist/proxy/policy-result.js +90 -0
- package/dist/proxy/policy-result.js.map +1 -0
- package/dist/proxy/principal.d.ts +18 -0
- package/dist/proxy/principal.js +32 -0
- package/dist/proxy/principal.js.map +1 -0
- package/dist/proxy/push-policy-result.d.ts +34 -0
- package/dist/proxy/push-policy-result.js +48 -0
- package/dist/proxy/push-policy-result.js.map +1 -0
- package/dist/proxy/push-policy.d.ts +146 -0
- package/dist/proxy/push-policy.js +112 -0
- package/dist/proxy/push-policy.js.map +1 -0
- package/dist/proxy/request-credential.d.ts +22 -0
- package/dist/proxy/request-credential.js +46 -0
- package/dist/proxy/request-credential.js.map +1 -0
- package/dist/proxy/smart-http-config.d.ts +22 -0
- package/dist/proxy/smart-http-config.js +40 -0
- package/dist/proxy/smart-http-config.js.map +1 -0
- package/dist/reference/apply-actions.d.ts +9 -0
- package/dist/reference/apply-actions.js +84 -0
- package/dist/reference/apply-actions.js.map +1 -0
- package/dist/reference/branch-methods.d.ts +7 -0
- package/dist/reference/branch-methods.js +105 -0
- package/dist/reference/branch-methods.js.map +1 -0
- package/dist/reference/bytes.d.ts +22 -0
- package/dist/reference/bytes.js +62 -0
- package/dist/reference/bytes.js.map +1 -0
- package/dist/reference/clock.d.ts +2 -0
- package/dist/reference/clock.js +18 -0
- package/dist/reference/clock.js.map +1 -0
- package/dist/reference/commit-method.d.ts +5 -0
- package/dist/reference/commit-method.js +83 -0
- package/dist/reference/commit-method.js.map +1 -0
- package/dist/reference/file-map.d.ts +2 -0
- package/dist/reference/file-map.js +24 -0
- package/dist/reference/file-map.js.map +1 -0
- package/dist/reference/hash.d.ts +10 -0
- package/dist/reference/hash.js +25 -0
- package/dist/reference/hash.js.map +1 -0
- package/dist/reference/history.d.ts +2 -0
- package/dist/reference/history.js +65 -0
- package/dist/reference/history.js.map +1 -0
- package/dist/reference/lifecycle-methods.d.ts +9 -0
- package/dist/reference/lifecycle-methods.js +48 -0
- package/dist/reference/lifecycle-methods.js.map +1 -0
- package/dist/reference/read-methods.d.ts +13 -0
- package/dist/reference/read-methods.js +68 -0
- package/dist/reference/read-methods.js.map +1 -0
- package/dist/reference/reference-gateway.d.ts +18 -0
- package/dist/reference/reference-gateway.js +35 -0
- package/dist/reference/reference-gateway.js.map +1 -0
- package/dist/reference/repo-state.d.ts +43 -0
- package/dist/reference/repo-state.js +45 -0
- package/dist/reference/repo-state.js.map +1 -0
- package/dist/reference/run-method.d.ts +13 -0
- package/dist/reference/run-method.js +15 -0
- package/dist/reference/run-method.js.map +1 -0
- package/dist/reference/three-way-merge.d.ts +16 -0
- package/dist/reference/three-way-merge.js +45 -0
- package/dist/reference/three-way-merge.js.map +1 -0
- package/dist/reference/trailer.d.ts +7 -0
- package/dist/reference/trailer.js +16 -0
- package/dist/reference/trailer.js.map +1 -0
- package/dist/reference/tree-index.d.ts +2 -0
- package/dist/reference/tree-index.js +66 -0
- package/dist/reference/tree-index.js.map +1 -0
- package/dist/reference/write-commit.d.ts +15 -0
- package/dist/reference/write-commit.js +44 -0
- package/dist/reference/write-commit.js.map +1 -0
- package/dist/rpc/commit-exists.d.ts +16 -0
- package/dist/rpc/commit-exists.js +30 -0
- package/dist/rpc/commit-exists.js.map +1 -0
- package/dist/rpc/commit.d.ts +172 -0
- package/dist/rpc/commit.js +115 -0
- package/dist/rpc/commit.js.map +1 -0
- package/dist/rpc/list-tree.d.ts +59 -0
- package/dist/rpc/list-tree.js +54 -0
- package/dist/rpc/list-tree.js.map +1 -0
- package/dist/rpc/log.d.ts +35 -0
- package/dist/rpc/log.js +41 -0
- package/dist/rpc/log.js.map +1 -0
- package/dist/rpc/mint-read-token.d.ts +17 -0
- package/dist/rpc/mint-read-token.js +36 -0
- package/dist/rpc/mint-read-token.js.map +1 -0
- package/dist/rpc/promote.d.ts +39 -0
- package/dist/rpc/promote.js +69 -0
- package/dist/rpc/promote.js.map +1 -0
- package/dist/rpc/read-file.d.ts +44 -0
- package/dist/rpc/read-file.js +56 -0
- package/dist/rpc/read-file.js.map +1 -0
- package/dist/rpc/repo-lifecycle.d.ts +39 -0
- package/dist/rpc/repo-lifecycle.js +64 -0
- package/dist/rpc/repo-lifecycle.js.map +1 -0
- package/dist/rpc/resolve-ref.d.ts +15 -0
- package/dist/rpc/resolve-ref.js +28 -0
- package/dist/rpc/resolve-ref.js.map +1 -0
- package/dist/rpc/sync-branch.d.ts +107 -0
- package/dist/rpc/sync-branch.js +114 -0
- package/dist/rpc/sync-branch.js.map +1 -0
- package/dist/schemas/commit-action.d.ts +100 -0
- package/dist/schemas/commit-action.js +138 -0
- package/dist/schemas/commit-action.js.map +1 -0
- package/dist/schemas/commit.d.ts +2 -0
- package/dist/schemas/commit.js +24 -0
- package/dist/schemas/commit.js.map +1 -0
- package/dist/schemas/content-encoding.d.ts +24 -0
- package/dist/schemas/content-encoding.js +41 -0
- package/dist/schemas/content-encoding.js.map +1 -0
- package/dist/schemas/examples.d.ts +38 -0
- package/dist/schemas/examples.js +32 -0
- package/dist/schemas/examples.js.map +1 -0
- package/dist/schemas/gateway-config.d.ts +2 -0
- package/dist/schemas/gateway-config.js +72 -0
- package/dist/schemas/gateway-config.js.map +1 -0
- package/dist/schemas/gateway-error-body.d.ts +2 -0
- package/dist/schemas/gateway-error-body.js +188 -0
- package/dist/schemas/gateway-error-body.js.map +1 -0
- package/dist/schemas/identity.d.ts +21 -0
- package/dist/schemas/identity.js +40 -0
- package/dist/schemas/identity.js.map +1 -0
- package/dist/schemas/names.d.ts +26 -0
- package/dist/schemas/names.js +58 -0
- package/dist/schemas/names.js.map +1 -0
- package/dist/schemas/ref-update.d.ts +10 -0
- package/dist/schemas/ref-update.js +25 -0
- package/dist/schemas/ref-update.js.map +1 -0
- package/dist/schemas/sha.d.ts +8 -0
- package/dist/schemas/sha.js +14 -0
- package/dist/schemas/sha.js.map +1 -0
- package/dist/schemas/tree-entry.d.ts +2 -0
- package/dist/schemas/tree-entry.js +62 -0
- package/dist/schemas/tree-entry.js.map +1 -0
- package/dist/storage/git-remote.d.ts +17 -0
- package/dist/storage/git-remote.js +31 -0
- package/dist/storage/git-remote.js.map +1 -0
- package/dist/storage/storage-backend.d.ts +61 -0
- package/dist/storage/storage-backend.js +0 -0
- package/dist/storage/storage-errors.d.ts +12 -0
- package/dist/storage/storage-errors.js +22 -0
- package/dist/storage/storage-errors.js.map +1 -0
- package/dist/storage/storage-input.d.ts +7 -0
- package/dist/storage/storage-input.js +14 -0
- package/dist/storage/storage-input.js.map +1 -0
- package/dist/storage/storage-read.d.ts +13 -0
- package/dist/storage/storage-read.js +30 -0
- package/dist/storage/storage-read.js.map +1 -0
- package/dist/storage/storage-repo-info.d.ts +16 -0
- package/dist/storage/storage-repo-info.js +30 -0
- package/dist/storage/storage-repo-info.js.map +1 -0
- package/dist/storage/storage-tree-entry.d.ts +21 -0
- package/dist/storage/storage-tree-entry.js +17 -0
- package/dist/storage/storage-tree-entry.js.map +1 -0
- package/dist/tree-entry-BM_1gou1.d.ts +41 -0
- package/dist/tree-index-Bk721Phv.d.ts +14 -0
- package/package.json +401 -4
- package/src/behaviour/assertions.ts +75 -0
- package/src/behaviour/behaviour-case.ts +28 -0
- package/src/behaviour/behaviour-suite.ts +76 -0
- package/src/behaviour/commit-action-cases.ts +253 -0
- package/src/behaviour/commit-write-cases.ts +205 -0
- package/src/behaviour/fixtures.ts +103 -0
- package/src/behaviour/lifecycle-cases.ts +104 -0
- package/src/behaviour/promote-cases.ts +78 -0
- package/src/behaviour/read-cases.ts +176 -0
- package/src/behaviour/sync-cases.ts +156 -0
- package/src/gateway-error.ts +72 -0
- package/src/git-gateway.ts +76 -0
- package/src/health.ts +26 -0
- package/src/package-name.ts +4 -0
- package/src/proxy/audit-event.ts +135 -0
- package/src/proxy/branch-rule.ts +190 -0
- package/src/proxy/gateway-hooks.ts +67 -0
- package/src/proxy/git-operation.ts +36 -0
- package/src/proxy/policy-result.ts +127 -0
- package/src/proxy/principal.ts +81 -0
- package/src/proxy/push-policy-result.ts +86 -0
- package/src/proxy/push-policy.ts +158 -0
- package/src/proxy/request-credential.ts +47 -0
- package/src/proxy/smart-http-config.ts +158 -0
- package/src/reference/apply-actions.ts +96 -0
- package/src/reference/branch-methods.ts +105 -0
- package/src/reference/bytes.ts +66 -0
- package/src/reference/clock.ts +19 -0
- package/src/reference/commit-method.ts +97 -0
- package/src/reference/file-map.ts +35 -0
- package/src/reference/hash.ts +25 -0
- package/src/reference/history.ts +78 -0
- package/src/reference/lifecycle-methods.ts +52 -0
- package/src/reference/read-methods.ts +87 -0
- package/src/reference/reference-gateway.ts +50 -0
- package/src/reference/repo-state.ts +83 -0
- package/src/reference/run-method.ts +25 -0
- package/src/reference/three-way-merge.ts +42 -0
- package/src/reference/trailer.ts +18 -0
- package/src/reference/tree-index.ts +65 -0
- package/src/reference/write-commit.ts +44 -0
- package/src/rpc/commit-exists.ts +46 -0
- package/src/rpc/commit.ts +156 -0
- package/src/rpc/list-tree.ts +78 -0
- package/src/rpc/log.ts +51 -0
- package/src/rpc/mint-read-token.ts +59 -0
- package/src/rpc/promote.ts +72 -0
- package/src/rpc/read-file.ts +75 -0
- package/src/rpc/repo-lifecycle.ts +103 -0
- package/src/rpc/resolve-ref.ts +41 -0
- package/src/rpc/sync-branch.ts +149 -0
- package/src/schemas/commit-action.ts +157 -0
- package/src/schemas/commit.ts +43 -0
- package/src/schemas/content-encoding.ts +58 -0
- package/src/schemas/examples.ts +24 -0
- package/src/schemas/gateway-config.ts +116 -0
- package/src/schemas/gateway-error-body.ts +230 -0
- package/src/schemas/identity.ts +57 -0
- package/src/schemas/names.ts +126 -0
- package/src/schemas/ref-update.ts +38 -0
- package/src/schemas/sha.ts +20 -0
- package/src/schemas/tree-entry.ts +72 -0
- package/src/storage/git-remote.ts +58 -0
- package/src/storage/storage-backend.ts +65 -0
- package/src/storage/storage-errors.ts +24 -0
- package/src/storage/storage-input.ts +14 -0
- package/src/storage/storage-read.ts +45 -0
- package/src/storage/storage-repo-info.ts +46 -0
- package/src/storage/storage-tree-entry.ts +20 -0
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import { z } from 'zod';
|
|
3
|
+
|
|
4
|
+
import { Timestamp } from '../schemas/identity.ts';
|
|
5
|
+
import { RepoName } from '../schemas/names.ts';
|
|
6
|
+
import { Sha } from '../schemas/sha.ts';
|
|
7
|
+
import { GitOperation, SmartHttpEndpoint } from './git-operation.ts';
|
|
8
|
+
import { Principal } from './principal.ts';
|
|
9
|
+
|
|
10
|
+
/** A request id: opaque, safe to log. */
|
|
11
|
+
export const RequestId = z
|
|
12
|
+
.string()
|
|
13
|
+
.min(1)
|
|
14
|
+
.max(128)
|
|
15
|
+
.regex(/^[A-Za-z0-9._:-]+$/)
|
|
16
|
+
.meta({
|
|
17
|
+
id: 'RequestId',
|
|
18
|
+
title: 'Request id',
|
|
19
|
+
description:
|
|
20
|
+
'Identifies one request in logs, audit events and the X-Request-Id response header: 1–128 characters of letters, digits, ".", "_", ":" and "-". The Cloudflare Ray id when there is one, otherwise a random UUID.',
|
|
21
|
+
examples: ['8f1c2d3e4a5b6c7d-LHR', '6f1d2c3b-9a8e-4f7d-b6c5-a4e3d2c1b0a9'],
|
|
22
|
+
});
|
|
23
|
+
|
|
24
|
+
/** A request id, inferred from {@link RequestId}. */
|
|
25
|
+
export type RequestId = z.infer<typeof RequestId>;
|
|
26
|
+
|
|
27
|
+
/** The outcome of one ref update of a push, as far as the gateway knows it. */
|
|
28
|
+
export const AuditRefOutcome = z
|
|
29
|
+
.object({
|
|
30
|
+
ref: z
|
|
31
|
+
.string()
|
|
32
|
+
.min(6)
|
|
33
|
+
.max(4096)
|
|
34
|
+
.regex(/^refs\/[^\n\0]+$/)
|
|
35
|
+
.describe(
|
|
36
|
+
'The ref the update command named, fully qualified; any namespace, since refused ones are audited too.',
|
|
37
|
+
),
|
|
38
|
+
oldSha: Sha.describe('Id the client said the ref named; all zeros when it asked to create the ref.'),
|
|
39
|
+
newSha: Sha.describe('Id the client asked the ref to name; all zeros when it asked to delete the ref.'),
|
|
40
|
+
status: z.enum(['ok', 'rejected', 'unknown']).meta({
|
|
41
|
+
description: 'What happened to the ref.',
|
|
42
|
+
enumDescriptions: {
|
|
43
|
+
ok: 'The storage host reported the ref updated.',
|
|
44
|
+
rejected: 'The gateway or the storage host refused the update; `reason` says why.',
|
|
45
|
+
unknown: 'The push was forwarded but the storage host report could not be read.',
|
|
46
|
+
},
|
|
47
|
+
}),
|
|
48
|
+
reason: z
|
|
49
|
+
.string()
|
|
50
|
+
.min(1)
|
|
51
|
+
.max(1000)
|
|
52
|
+
.nullable()
|
|
53
|
+
.describe('Why the update was refused, as git was told; null unless `status` is "rejected".'),
|
|
54
|
+
})
|
|
55
|
+
.strict()
|
|
56
|
+
.meta({
|
|
57
|
+
id: 'AuditRefOutcome',
|
|
58
|
+
title: 'Audited ref update',
|
|
59
|
+
description: 'One update command of an audited push and what became of it.',
|
|
60
|
+
examples: [
|
|
61
|
+
{
|
|
62
|
+
ref: 'refs/heads/main',
|
|
63
|
+
oldSha: '1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d',
|
|
64
|
+
newSha: '8f3c2a9e1b7d4c6f0a5e2d9b8c7a6f5e4d3c2b1a',
|
|
65
|
+
status: 'rejected',
|
|
66
|
+
reason: 'main is protected',
|
|
67
|
+
},
|
|
68
|
+
],
|
|
69
|
+
});
|
|
70
|
+
|
|
71
|
+
/** An audited ref update, inferred from {@link AuditRefOutcome}. */
|
|
72
|
+
export type AuditRefOutcome = z.infer<typeof AuditRefOutcome>;
|
|
73
|
+
|
|
74
|
+
/** One authenticated smart-HTTP operation, as handed to the audit hook. */
|
|
75
|
+
export const AuditEvent = z
|
|
76
|
+
.object({
|
|
77
|
+
requestId: RequestId.describe('The request this event records.'),
|
|
78
|
+
at: Timestamp.describe('When the gateway finished deciding and forwarding the request.'),
|
|
79
|
+
principal: Principal.describe('Who made the request (never the credential).'),
|
|
80
|
+
repo: RepoName.describe('The repository the request named.'),
|
|
81
|
+
operation: GitOperation.describe('Whether the request reads or writes the repository.'),
|
|
82
|
+
endpoint: SmartHttpEndpoint.describe('Which smart-HTTP endpoint the request reached.'),
|
|
83
|
+
outcome: z.enum(['allowed', 'denied', 'failed']).meta({
|
|
84
|
+
description: 'What the gateway did with the request.',
|
|
85
|
+
enumDescriptions: {
|
|
86
|
+
allowed:
|
|
87
|
+
'Authorized and forwarded to storage; for a push, `refs` says what storage did with each ref.',
|
|
88
|
+
denied: 'Refused by the authorizer or the branch policy; nothing reached storage.',
|
|
89
|
+
failed: 'Authorized, but the gateway or the storage host failed before an answer was complete.',
|
|
90
|
+
},
|
|
91
|
+
}),
|
|
92
|
+
reason: z
|
|
93
|
+
.string()
|
|
94
|
+
.min(1)
|
|
95
|
+
.max(1000)
|
|
96
|
+
.nullable()
|
|
97
|
+
.describe('Why the request was denied or failed, as the client was told; null when it was allowed.'),
|
|
98
|
+
refs: z
|
|
99
|
+
.array(AuditRefOutcome)
|
|
100
|
+
.max(10_000)
|
|
101
|
+
.describe(
|
|
102
|
+
'For a push (receive-pack), every update command and its outcome; empty for every other request.',
|
|
103
|
+
),
|
|
104
|
+
})
|
|
105
|
+
.strict()
|
|
106
|
+
.meta({
|
|
107
|
+
id: 'AuditEvent',
|
|
108
|
+
title: 'Audit event',
|
|
109
|
+
description:
|
|
110
|
+
'Handed to the audit hook for every authenticated smart-HTTP request once it is decided: principal, repository, operation, refs and outcome. Never contains a credential.',
|
|
111
|
+
examples: [
|
|
112
|
+
{
|
|
113
|
+
requestId: '6f1d2c3b-9a8e-4f7d-b6c5-a4e3d2c1b0a9',
|
|
114
|
+
at: '2026-11-20T09:30:00.000Z',
|
|
115
|
+
principal: { subject: 'user:42', name: null, email: null, roles: ['editor'], expiresAt: null },
|
|
116
|
+
repo: 'acme-raw-content',
|
|
117
|
+
operation: 'write',
|
|
118
|
+
endpoint: 'receive-pack',
|
|
119
|
+
outcome: 'denied',
|
|
120
|
+
reason: 'main is protected',
|
|
121
|
+
refs: [
|
|
122
|
+
{
|
|
123
|
+
ref: 'refs/heads/main',
|
|
124
|
+
oldSha: '1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d',
|
|
125
|
+
newSha: '8f3c2a9e1b7d4c6f0a5e2d9b8c7a6f5e4d3c2b1a',
|
|
126
|
+
status: 'rejected',
|
|
127
|
+
reason: 'main is protected',
|
|
128
|
+
},
|
|
129
|
+
],
|
|
130
|
+
},
|
|
131
|
+
],
|
|
132
|
+
});
|
|
133
|
+
|
|
134
|
+
/** An audit event, inferred from {@link AuditEvent}. */
|
|
135
|
+
export type AuditEvent = z.infer<typeof AuditEvent>;
|
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import { z } from 'zod';
|
|
3
|
+
|
|
4
|
+
import { Role } from './principal.ts';
|
|
5
|
+
|
|
6
|
+
/** A glob over fully qualified branch or tag refs. */
|
|
7
|
+
export const RefPattern = z
|
|
8
|
+
.string()
|
|
9
|
+
.min(12)
|
|
10
|
+
.max(266)
|
|
11
|
+
.regex(
|
|
12
|
+
new RegExp(
|
|
13
|
+
String.raw`^refs/(?:heads|tags)/(?!.*\.\.)(?!.*//)(?!.*/$)(?!.*\*{3})[^\x00-\x20\x7f~^:?[\\]+$`,
|
|
14
|
+
),
|
|
15
|
+
)
|
|
16
|
+
.meta({
|
|
17
|
+
id: 'RefPattern',
|
|
18
|
+
title: 'Ref pattern',
|
|
19
|
+
description:
|
|
20
|
+
'A glob matched against a whole fully qualified ref under refs/heads/ or refs/tags/: "*" matches any run of characters inside one path component (never "/"), "**" matches any run including "/", everything else matches itself. No "..", "//", trailing "/", whitespace, control characters, ~ ^ : ? [ or backslash; 12–266 characters.',
|
|
21
|
+
examples: ['refs/heads/main', 'refs/heads/release/*', 'refs/tags/**'],
|
|
22
|
+
});
|
|
23
|
+
|
|
24
|
+
/** A ref glob, inferred from {@link RefPattern}. */
|
|
25
|
+
export type RefPattern = z.infer<typeof RefPattern>;
|
|
26
|
+
|
|
27
|
+
const subjectName = z
|
|
28
|
+
.string()
|
|
29
|
+
.min(1)
|
|
30
|
+
.max(255)
|
|
31
|
+
.regex(/^[^\n\0]+$/)
|
|
32
|
+
.describe('A principal subject, compared exactly with Principal.subject.');
|
|
33
|
+
|
|
34
|
+
/** Which principals a rule lets push. */
|
|
35
|
+
export const PrincipalSelector = z
|
|
36
|
+
.object({
|
|
37
|
+
subjects: z
|
|
38
|
+
.array(subjectName)
|
|
39
|
+
.max(1000)
|
|
40
|
+
.default([])
|
|
41
|
+
.describe('Principals named by subject; at most 1000, default none.'),
|
|
42
|
+
roles: z
|
|
43
|
+
.array(Role)
|
|
44
|
+
.max(100)
|
|
45
|
+
.default([])
|
|
46
|
+
.describe('Principals holding any of these roles; at most 100, default none.'),
|
|
47
|
+
})
|
|
48
|
+
.strict()
|
|
49
|
+
.meta({
|
|
50
|
+
id: 'PrincipalSelector',
|
|
51
|
+
title: 'Principal selector',
|
|
52
|
+
description:
|
|
53
|
+
'Selects principals by subject or role: a principal matches when its subject is listed or it holds any listed role. With both lists empty it matches nobody.',
|
|
54
|
+
examples: [{ subjects: ['user:42'], roles: ['maintainer'] }],
|
|
55
|
+
});
|
|
56
|
+
|
|
57
|
+
/** A principal selector as written (defaults optional). */
|
|
58
|
+
export type PrincipalSelectorInput = z.input<typeof PrincipalSelector>;
|
|
59
|
+
/** A principal selector, inferred from {@link PrincipalSelector}. */
|
|
60
|
+
export type PrincipalSelector = z.output<typeof PrincipalSelector>;
|
|
61
|
+
|
|
62
|
+
const pushers = PrincipalSelector.nullable()
|
|
63
|
+
.default(null)
|
|
64
|
+
.describe(
|
|
65
|
+
'Who may update matching refs at all; null (the default) lets every principal the Authorizer allowed to write.',
|
|
66
|
+
);
|
|
67
|
+
|
|
68
|
+
/** What the rule-based branch policy allows on refs no rule matches. */
|
|
69
|
+
export const BranchPermissions = z
|
|
70
|
+
.object({
|
|
71
|
+
pushers,
|
|
72
|
+
create: z.boolean().default(true).describe('Whether a push may create a ref; default true.'),
|
|
73
|
+
delete: z.boolean().default(true).describe('Whether a push may delete a ref; default true.'),
|
|
74
|
+
forcePush: z
|
|
75
|
+
.boolean()
|
|
76
|
+
.default(false)
|
|
77
|
+
.describe(
|
|
78
|
+
'Whether a push may move a branch to a commit that does not contain its current head (a non-fast-forward, "git push --force") or move an existing tag; default false.',
|
|
79
|
+
),
|
|
80
|
+
})
|
|
81
|
+
.strict()
|
|
82
|
+
.meta({
|
|
83
|
+
id: 'BranchPermissions',
|
|
84
|
+
title: 'Branch permissions',
|
|
85
|
+
description:
|
|
86
|
+
'What the rule-based branch policy allows on a ref no rule matches. Defaults: anyone with write access, create and delete allowed, force pushes refused.',
|
|
87
|
+
examples: [{ pushers: null, create: true, delete: true, forcePush: false }],
|
|
88
|
+
});
|
|
89
|
+
|
|
90
|
+
/** Branch permissions as written (defaults optional). */
|
|
91
|
+
export type BranchPermissionsInput = z.input<typeof BranchPermissions>;
|
|
92
|
+
/** Branch permissions, inferred from {@link BranchPermissions}. */
|
|
93
|
+
export type BranchPermissions = z.output<typeof BranchPermissions>;
|
|
94
|
+
|
|
95
|
+
/** One rule of the rule-based branch policy. */
|
|
96
|
+
export const BranchRule = z
|
|
97
|
+
.object({
|
|
98
|
+
pattern: RefPattern.describe('The refs this rule governs.'),
|
|
99
|
+
pushers,
|
|
100
|
+
create: z.boolean().default(true).describe('Whether a push may create a matching ref; default true.'),
|
|
101
|
+
delete: z
|
|
102
|
+
.boolean()
|
|
103
|
+
.default(false)
|
|
104
|
+
.describe('Whether a push may delete a matching ref; default false (rules usually protect).'),
|
|
105
|
+
forcePush: z
|
|
106
|
+
.boolean()
|
|
107
|
+
.default(false)
|
|
108
|
+
.describe(
|
|
109
|
+
'Whether a push may move a matching branch to a commit that does not contain its current head, or move a matching tag; default false.',
|
|
110
|
+
),
|
|
111
|
+
message: z
|
|
112
|
+
.string()
|
|
113
|
+
.min(1)
|
|
114
|
+
.max(200)
|
|
115
|
+
.regex(/^[^\n\0]+$/)
|
|
116
|
+
.nullable()
|
|
117
|
+
.default(null)
|
|
118
|
+
.describe(
|
|
119
|
+
'Text git shows the user when this rule refuses an update, e.g. "main is protected"; one line of 1–200 characters. Null (the default) uses a message naming the ref and what was refused.',
|
|
120
|
+
),
|
|
121
|
+
})
|
|
122
|
+
.strict()
|
|
123
|
+
.meta({
|
|
124
|
+
id: 'BranchRule',
|
|
125
|
+
title: 'Branch rule',
|
|
126
|
+
description:
|
|
127
|
+
'Governs the refs matching `pattern`: who may push them, whether they may be created or deleted, and whether force pushes are allowed. Rules are tried in order and the first match decides.',
|
|
128
|
+
examples: [
|
|
129
|
+
{
|
|
130
|
+
pattern: 'refs/heads/main',
|
|
131
|
+
pushers: { subjects: [], roles: ['maintainer'] },
|
|
132
|
+
create: true,
|
|
133
|
+
delete: false,
|
|
134
|
+
forcePush: false,
|
|
135
|
+
message: 'main is protected',
|
|
136
|
+
},
|
|
137
|
+
],
|
|
138
|
+
});
|
|
139
|
+
|
|
140
|
+
/** A branch rule as written (defaults optional). */
|
|
141
|
+
export type BranchRuleInput = z.input<typeof BranchRule>;
|
|
142
|
+
/** A branch rule, inferred from {@link BranchRule}. */
|
|
143
|
+
export type BranchRule = z.output<typeof BranchRule>;
|
|
144
|
+
|
|
145
|
+
/** Configuration of the rule-based branch policy. */
|
|
146
|
+
export const BranchPolicyConfig = z
|
|
147
|
+
.object({
|
|
148
|
+
rules: z
|
|
149
|
+
.array(BranchRule)
|
|
150
|
+
.max(200)
|
|
151
|
+
.default([])
|
|
152
|
+
.describe(
|
|
153
|
+
'Rules tried in order; the first whose pattern matches a ref decides it. At most 200, default none.',
|
|
154
|
+
),
|
|
155
|
+
fallback: BranchPermissions.default({
|
|
156
|
+
pushers: null,
|
|
157
|
+
create: true,
|
|
158
|
+
delete: true,
|
|
159
|
+
forcePush: false,
|
|
160
|
+
}).describe(
|
|
161
|
+
'What applies to a branch or tag ref no rule matches; default anyone with write access, create and delete allowed, force refused.',
|
|
162
|
+
),
|
|
163
|
+
})
|
|
164
|
+
.strict()
|
|
165
|
+
.meta({
|
|
166
|
+
id: 'BranchPolicyConfig',
|
|
167
|
+
title: 'Branch policy configuration',
|
|
168
|
+
description:
|
|
169
|
+
'Configuration of the reference rule-based BranchPolicy. Refs outside refs/heads/ and refs/tags/ are always refused, whatever the rules say.',
|
|
170
|
+
examples: [
|
|
171
|
+
{
|
|
172
|
+
rules: [
|
|
173
|
+
{
|
|
174
|
+
pattern: 'refs/heads/main',
|
|
175
|
+
pushers: { subjects: [], roles: ['maintainer'] },
|
|
176
|
+
create: true,
|
|
177
|
+
delete: false,
|
|
178
|
+
forcePush: false,
|
|
179
|
+
message: 'main is protected',
|
|
180
|
+
},
|
|
181
|
+
],
|
|
182
|
+
fallback: { pushers: null, create: true, delete: true, forcePush: false },
|
|
183
|
+
},
|
|
184
|
+
],
|
|
185
|
+
});
|
|
186
|
+
|
|
187
|
+
/** A branch policy configuration as written (defaults optional). */
|
|
188
|
+
export type BranchPolicyConfigInput = z.input<typeof BranchPolicyConfig>;
|
|
189
|
+
/** A branch policy configuration, inferred from {@link BranchPolicyConfig}. */
|
|
190
|
+
export type BranchPolicyConfig = z.output<typeof BranchPolicyConfig>;
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import type { RefUpdate } from '../schemas/ref-update.ts';
|
|
3
|
+
import type { RepoName } from '../schemas/names.ts';
|
|
4
|
+
import type { AuditEvent } from './audit-event.ts';
|
|
5
|
+
import type { GitOperation } from './git-operation.ts';
|
|
6
|
+
import type { PolicyResult } from './policy-result.ts';
|
|
7
|
+
import type { Principal, PrincipalInput } from './principal.ts';
|
|
8
|
+
import type { PushPolicyNeeds, PushPolicyResultInput } from './push-policy-result.ts';
|
|
9
|
+
import type { PushPolicyInput } from './push-policy.ts';
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Establishes who a smart-HTTP request acts for. git sends credentials as HTTP Basic; the
|
|
13
|
+
* password is a bearer credential (an OAuth access token, a JWT, an API key), so a credential
|
|
14
|
+
* helper can supply one. Return null when the request carries no valid credential — the gateway
|
|
15
|
+
* then answers 401 with `WWW-Authenticate: Basic` so git asks its credential helper. The result
|
|
16
|
+
* is parsed with {@link Principal} before use.
|
|
17
|
+
*/
|
|
18
|
+
export interface Authenticator {
|
|
19
|
+
authenticate(request: Request): Promise<PrincipalInput | null>;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/** Decides whether a principal may read (clone, fetch) or write (push) a repository. */
|
|
23
|
+
export interface Authorizer {
|
|
24
|
+
authorize(principal: Principal, repo: RepoName, operation: GitOperation): Promise<boolean>;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Decides, per ref, whether a push may update it. Called with every branch or tag update of a
|
|
29
|
+
* push (refs in other namespaces are refused before it is called). Synchronous: it decides from
|
|
30
|
+
* the principal and the update commands alone; the gateway proves fast-forwards itself when the
|
|
31
|
+
* result asks for "fast-forward-only". The result is parsed with {@link PolicyResult}.
|
|
32
|
+
*/
|
|
33
|
+
export interface BranchPolicy {
|
|
34
|
+
check(principal: Principal, repo: RepoName, updates: readonly RefUpdate[]): PolicyResult;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* A deployment's own rules over what a push changes, run after the BranchPolicy on every push it
|
|
39
|
+
* allowed — e.g. which paths a principal may change, which file types or sizes are accepted.
|
|
40
|
+
* Pushes through the RPC API (`commit`, `syncBranch`, `promote`) are the calling service's and are
|
|
41
|
+
* not checked.
|
|
42
|
+
*
|
|
43
|
+
* `needs()` is called first, with the ref updates alone, and says whether `check()` needs changed
|
|
44
|
+
* paths (its result is parsed with {@link PushPolicyNeeds}). Without them, `check()` runs before
|
|
45
|
+
* the pack is read and a refusal sends nothing to storage. With them, the gateway reads the
|
|
46
|
+
* pushed pack as it streams to storage (holding back its checksum, as it does to prove
|
|
47
|
+
* fast-forwards), computes every new commit's changed paths from the pack and storage within the
|
|
48
|
+
* configured bounds, and calls `check()` before the push completes; a refusal cuts the pack short
|
|
49
|
+
* so storage writes nothing. A push that cannot be checked within the bounds is refused. Either
|
|
50
|
+
* way a refusal reaches git in-protocol ("! [remote rejected] <ref> (<reason>)"). The result is
|
|
51
|
+
* parsed with PushPolicyResult; a `check()` that throws refuses the push.
|
|
52
|
+
*/
|
|
53
|
+
export interface PushPolicy {
|
|
54
|
+
needs(
|
|
55
|
+
principal: Principal,
|
|
56
|
+
repo: RepoName,
|
|
57
|
+
updates: readonly RefUpdate[],
|
|
58
|
+
): PushPolicyNeeds | Promise<PushPolicyNeeds>;
|
|
59
|
+
check(input: PushPolicyInput): PushPolicyResultInput | Promise<PushPolicyResultInput>;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Receives every authenticated smart-HTTP operation once it is decided. It runs after the
|
|
64
|
+
* response is under way (through `waitUntil` when the runtime has it); a failure is logged and
|
|
65
|
+
* never changes the response.
|
|
66
|
+
*/
|
|
67
|
+
export type AuditHook = (event: AuditEvent) => void | Promise<void>;
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import { z } from 'zod';
|
|
3
|
+
|
|
4
|
+
/** What a smart-HTTP request does to a repository. */
|
|
5
|
+
export const GitOperation = z.enum(['read', 'write']).meta({
|
|
6
|
+
id: 'GitOperation',
|
|
7
|
+
title: 'Git operation',
|
|
8
|
+
description:
|
|
9
|
+
'What a git client asks to do to a repository through the gateway; Authorizer.authorize() decides each per principal and repository.',
|
|
10
|
+
enumDescriptions: {
|
|
11
|
+
read: 'Clone or fetch: GET info/refs?service=git-upload-pack and POST git-upload-pack.',
|
|
12
|
+
write: 'Push: GET info/refs?service=git-receive-pack and POST git-receive-pack.',
|
|
13
|
+
},
|
|
14
|
+
examples: ['read', 'write'],
|
|
15
|
+
});
|
|
16
|
+
|
|
17
|
+
/** A git operation, inferred from {@link GitOperation}. */
|
|
18
|
+
export type GitOperation = z.infer<typeof GitOperation>;
|
|
19
|
+
|
|
20
|
+
/** The smart-HTTP endpoint a request reached. */
|
|
21
|
+
export const SmartHttpEndpoint = z.enum(['info-refs', 'upload-pack', 'receive-pack']).meta({
|
|
22
|
+
id: 'SmartHttpEndpoint',
|
|
23
|
+
title: 'Smart-HTTP endpoint',
|
|
24
|
+
description: 'Which of the three git smart-HTTP endpoints of /<repo>.git a request reached.',
|
|
25
|
+
enumDescriptions: {
|
|
26
|
+
'info-refs':
|
|
27
|
+
'GET /<repo>.git/info/refs?service=…: the ref advertisement (or the protocol v2 capabilities).',
|
|
28
|
+
'upload-pack': 'POST /<repo>.git/git-upload-pack: fetch negotiation and the pack sent to the client.',
|
|
29
|
+
'receive-pack':
|
|
30
|
+
'POST /<repo>.git/git-receive-pack: ref update commands and the pack pushed by the client.',
|
|
31
|
+
},
|
|
32
|
+
examples: ['receive-pack'],
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
/** A smart-HTTP endpoint, inferred from {@link SmartHttpEndpoint}. */
|
|
36
|
+
export type SmartHttpEndpoint = z.infer<typeof SmartHttpEndpoint>;
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import { z } from 'zod';
|
|
3
|
+
|
|
4
|
+
import { FullRefName } from '../schemas/names.ts';
|
|
5
|
+
|
|
6
|
+
const policyReason = z
|
|
7
|
+
.string()
|
|
8
|
+
.min(1)
|
|
9
|
+
.max(500)
|
|
10
|
+
.regex(/^[^\n\0]+$/)
|
|
11
|
+
.describe(
|
|
12
|
+
'Why the update is or would be refused, shown to the user by git as "! [remote rejected] <ref> (<reason>)": one line of 1–500 characters.',
|
|
13
|
+
);
|
|
14
|
+
|
|
15
|
+
/** The policy allows any update of the ref, force pushes included. */
|
|
16
|
+
export const RefDecisionAllow = z
|
|
17
|
+
.object({
|
|
18
|
+
ref: FullRefName.describe('The ref the update names.'),
|
|
19
|
+
decision: z.literal('allow').describe('The update may proceed, whether or not it is a fast-forward.'),
|
|
20
|
+
})
|
|
21
|
+
.strict()
|
|
22
|
+
.meta({
|
|
23
|
+
id: 'RefDecisionAllow',
|
|
24
|
+
title: 'Ref decision: allow',
|
|
25
|
+
description: 'The branch policy allows this update as it stands, force pushes included.',
|
|
26
|
+
examples: [{ ref: 'refs/heads/feature/x', decision: 'allow' }],
|
|
27
|
+
});
|
|
28
|
+
|
|
29
|
+
/** The policy allows the update only if it is a fast-forward. */
|
|
30
|
+
export const RefDecisionFastForwardOnly = z
|
|
31
|
+
.object({
|
|
32
|
+
ref: FullRefName.describe('The ref the update names.'),
|
|
33
|
+
decision: z
|
|
34
|
+
.literal('fast-forward-only')
|
|
35
|
+
.describe(
|
|
36
|
+
'The update may proceed only if the new commit contains the current head; the gateway checks ancestry and refuses otherwise. A creation (no current head) proceeds; a deletion (no new commit) is refused.',
|
|
37
|
+
),
|
|
38
|
+
reason: policyReason,
|
|
39
|
+
})
|
|
40
|
+
.strict()
|
|
41
|
+
.meta({
|
|
42
|
+
id: 'RefDecisionFastForwardOnly',
|
|
43
|
+
title: 'Ref decision: fast-forward only',
|
|
44
|
+
description:
|
|
45
|
+
'The branch policy allows this update only as a fast-forward. The gateway proves the new commit descends from the old one (from the pushed pack and the backend) and refuses with `reason` when it does not or cannot be shown to. Creating a ref is allowed (there is no old head to lose); deleting one is refused with `reason` (there is no new commit to contain the old head). Moving an existing tag is never a fast-forward.',
|
|
46
|
+
examples: [
|
|
47
|
+
{
|
|
48
|
+
ref: 'refs/heads/main',
|
|
49
|
+
decision: 'fast-forward-only',
|
|
50
|
+
reason: 'force pushes to main are not allowed',
|
|
51
|
+
},
|
|
52
|
+
],
|
|
53
|
+
});
|
|
54
|
+
|
|
55
|
+
/** The policy refuses the update. */
|
|
56
|
+
export const RefDecisionDeny = z
|
|
57
|
+
.object({
|
|
58
|
+
ref: FullRefName.describe('The ref the update names.'),
|
|
59
|
+
decision: z.literal('deny').describe('The update is refused.'),
|
|
60
|
+
reason: policyReason,
|
|
61
|
+
})
|
|
62
|
+
.strict()
|
|
63
|
+
.meta({
|
|
64
|
+
id: 'RefDecisionDeny',
|
|
65
|
+
title: 'Ref decision: deny',
|
|
66
|
+
description: 'The branch policy refuses this update; git shows `reason` to the user.',
|
|
67
|
+
examples: [{ ref: 'refs/heads/main', decision: 'deny', reason: 'main is protected' }],
|
|
68
|
+
});
|
|
69
|
+
|
|
70
|
+
/** The branch policy's verdict on one ref update. */
|
|
71
|
+
export const RefDecision = z
|
|
72
|
+
.discriminatedUnion('decision', [RefDecisionAllow, RefDecisionFastForwardOnly, RefDecisionDeny])
|
|
73
|
+
.meta({
|
|
74
|
+
id: 'RefDecision',
|
|
75
|
+
title: 'Ref decision',
|
|
76
|
+
description: 'The branch policy verdict on one ref update, discriminated by `decision`.',
|
|
77
|
+
examples: [{ ref: 'refs/heads/main', decision: 'deny', reason: 'main is protected' }],
|
|
78
|
+
});
|
|
79
|
+
|
|
80
|
+
/** A verdict on one ref update, inferred from {@link RefDecision}. */
|
|
81
|
+
export type RefDecision = z.infer<typeof RefDecision>;
|
|
82
|
+
|
|
83
|
+
/** What BranchPolicy.check() returns for a push. */
|
|
84
|
+
export const PolicyResult = z
|
|
85
|
+
.object({
|
|
86
|
+
refs: z
|
|
87
|
+
.array(RefDecision)
|
|
88
|
+
.max(10_000)
|
|
89
|
+
.superRefine((decisions, ctx) => {
|
|
90
|
+
const seen = new Set<string>();
|
|
91
|
+
decisions.forEach((decision, index) => {
|
|
92
|
+
if (seen.has(decision.ref)) {
|
|
93
|
+
ctx.addIssue({
|
|
94
|
+
code: 'custom',
|
|
95
|
+
message: `the ref ${decision.ref} has more than one decision; a policy result names each ref once`,
|
|
96
|
+
path: [index, 'ref'],
|
|
97
|
+
});
|
|
98
|
+
}
|
|
99
|
+
seen.add(decision.ref);
|
|
100
|
+
});
|
|
101
|
+
})
|
|
102
|
+
.describe(
|
|
103
|
+
'One decision per update the policy was given, for the same refs, each ref named at most once (a result naming a ref twice is refused, so the gateway never has to pick between conflicting decisions). A push is forwarded only when every update is allowed; an update without a decision is refused.',
|
|
104
|
+
),
|
|
105
|
+
})
|
|
106
|
+
.strict()
|
|
107
|
+
.meta({
|
|
108
|
+
id: 'PolicyResult',
|
|
109
|
+
title: 'Policy result',
|
|
110
|
+
description:
|
|
111
|
+
'The branch policy verdict on every ref update of one push. The gateway forwards the push only when all of them are allowed (fast-forward-only ones after their ancestry is proven); otherwise nothing is written and git reports each refused ref with its reason.',
|
|
112
|
+
examples: [
|
|
113
|
+
{
|
|
114
|
+
refs: [
|
|
115
|
+
{
|
|
116
|
+
ref: 'refs/heads/main',
|
|
117
|
+
decision: 'fast-forward-only',
|
|
118
|
+
reason: 'force pushes to main are not allowed',
|
|
119
|
+
},
|
|
120
|
+
{ ref: 'refs/tags/v1.0.0', decision: 'deny', reason: 'tags are created by the release pipeline' },
|
|
121
|
+
],
|
|
122
|
+
},
|
|
123
|
+
],
|
|
124
|
+
});
|
|
125
|
+
|
|
126
|
+
/** A branch policy verdict, inferred from {@link PolicyResult}. */
|
|
127
|
+
export type PolicyResult = z.infer<typeof PolicyResult>;
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import { z } from 'zod';
|
|
3
|
+
|
|
4
|
+
import { Timestamp } from '../schemas/identity.ts';
|
|
5
|
+
|
|
6
|
+
/** A role or group name a deployment grants a principal. */
|
|
7
|
+
export const Role = z
|
|
8
|
+
.string()
|
|
9
|
+
.min(1)
|
|
10
|
+
.max(100)
|
|
11
|
+
.regex(/^[^\s\0]+$/)
|
|
12
|
+
.meta({
|
|
13
|
+
id: 'Role',
|
|
14
|
+
title: 'Role',
|
|
15
|
+
description:
|
|
16
|
+
'A role or group the deployment grants a principal, matched by branch-policy rules and authorizers: 1–100 characters without whitespace or NUL. Case-sensitive.',
|
|
17
|
+
examples: ['maintainer', 'site:acme:editor'],
|
|
18
|
+
});
|
|
19
|
+
|
|
20
|
+
/** A role name, inferred from {@link Role}. */
|
|
21
|
+
export type Role = z.infer<typeof Role>;
|
|
22
|
+
|
|
23
|
+
/** Who a smart-HTTP request acts for, as an Authenticator established it. */
|
|
24
|
+
export const Principal = z
|
|
25
|
+
.object({
|
|
26
|
+
subject: z
|
|
27
|
+
.string()
|
|
28
|
+
.min(1)
|
|
29
|
+
.max(255)
|
|
30
|
+
.regex(/^[^\n\0]+$/)
|
|
31
|
+
.describe(
|
|
32
|
+
'Stable identifier of the caller in the deployment (e.g. the JWT "sub" claim or a user id): 1–255 characters without newline or NUL. Used for policy matching, audit and caching; never a credential.',
|
|
33
|
+
),
|
|
34
|
+
name: z
|
|
35
|
+
.string()
|
|
36
|
+
.min(1)
|
|
37
|
+
.max(255)
|
|
38
|
+
.regex(/^[^\n\0]+$/)
|
|
39
|
+
.nullable()
|
|
40
|
+
.default(null)
|
|
41
|
+
.describe(
|
|
42
|
+
'Display name for logs and audit, 1–255 characters without newline or NUL; null (the default) when the authenticator does not know one.',
|
|
43
|
+
),
|
|
44
|
+
email: z
|
|
45
|
+
.email()
|
|
46
|
+
.max(255)
|
|
47
|
+
.nullable()
|
|
48
|
+
.default(null)
|
|
49
|
+
.describe('Email address, at most 255 characters; null (the default) when unknown.'),
|
|
50
|
+
roles: z
|
|
51
|
+
.array(Role)
|
|
52
|
+
.max(100)
|
|
53
|
+
.default([])
|
|
54
|
+
.describe('Roles or groups granted to the caller, at most 100; default none.'),
|
|
55
|
+
expiresAt: Timestamp.nullable()
|
|
56
|
+
.default(null)
|
|
57
|
+
.describe(
|
|
58
|
+
'When the credential that established this principal stops being valid, as an ISO 8601 UTC timestamp; cached decisions never outlive it. Null (the default) when the credential does not expire or the authenticator does not say.',
|
|
59
|
+
),
|
|
60
|
+
})
|
|
61
|
+
.strict()
|
|
62
|
+
.meta({
|
|
63
|
+
id: 'Principal',
|
|
64
|
+
title: 'Principal',
|
|
65
|
+
description:
|
|
66
|
+
'Who a smart-HTTP request acts for, as returned by an Authenticator. Authorizers, branch policy, the audit hook and the decision cache all key on it; it never carries the credential itself.',
|
|
67
|
+
examples: [
|
|
68
|
+
{
|
|
69
|
+
subject: 'user:42',
|
|
70
|
+
name: 'Ada Lovelace',
|
|
71
|
+
email: 'ada@example.com',
|
|
72
|
+
roles: ['maintainer'],
|
|
73
|
+
expiresAt: '2026-11-20T10:30:00.000Z',
|
|
74
|
+
},
|
|
75
|
+
],
|
|
76
|
+
});
|
|
77
|
+
|
|
78
|
+
/** A principal as an authenticator may write it (defaults optional). */
|
|
79
|
+
export type PrincipalInput = z.input<typeof Principal>;
|
|
80
|
+
/** A complete principal, inferred from {@link Principal}. */
|
|
81
|
+
export type Principal = z.output<typeof Principal>;
|