@coffre/conformance 0.1.5 → 0.1.7

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.
@@ -1,321 +0,0 @@
1
- // What can be checked of an instance that is already running, from outside
2
- // and without writing anything: as no one, and with a service token the
3
- // operator set up for it, which reads one canary. The local run takes the
4
- // same checks against the deployment it booted, so they run in CI too.
5
- //
6
- // Each run with a token adds a few entries to the instance's audit log,
7
- // which is append-only, so they stay: the canary's read, and the reads it
8
- // was refused. It changes nothing else.
9
- import { CoffreError, type AuthInfo, type CoffreClient } from '@coffre/client';
10
-
11
- import { bearer } from '../browser.ts';
12
- import { expect, refused, Skip, type Report } from '../report.ts';
13
- import { everyRoute, getCalls, getUrls } from '../routes.ts';
14
- import { headers, reachable } from './surface.ts';
15
-
16
- /** The page anyone may open. Every other page sends no one to /login. */
17
- const OPEN_PAGES = ['/login'];
18
- /** The pages behind sign-in, whatever the instance holds. */
19
- const CLOSED_PAGES = [
20
- '/',
21
- '/account',
22
- '/access',
23
- '/audit',
24
- '/auth/device',
25
- '/settings',
26
- '/projects',
27
- '/users',
28
- '/tokens',
29
- '/unregistered',
30
- ];
31
-
32
- /** A made-up place and member, which no instance has. */
33
- const NOWHERE = { project: 'conformance-nowhere', environment: 'none' };
34
- const NOBODY = 'token:conformance-nobody';
35
-
36
- /** A secret the operator set up, and its value, for the token to read and to look for. */
37
- export type Canary = { project: string; environment: string; key: string; value: string };
38
-
39
- /** Parse `<project>/<environment>/<KEY>=<value>`, or the path alone with the value given apart. */
40
- export function parseCanary(text: string, value?: string): Canary {
41
- const at = text.indexOf('=');
42
- const path = at === -1 ? text : text.slice(0, at);
43
- const given = at === -1 ? value : text.slice(at + 1);
44
- const parts = path.split('/');
45
- if (parts.length !== 3 || parts.some((part) => part === '')) {
46
- throw new Error(`the canary is <project>/<environment>/<KEY>, not "${path}"`);
47
- }
48
- if (given === undefined || given === '') throw new Error('the canary has no value: pass it after =, on stdin, or in COFFRE_CONFORMANCE_CANARY');
49
- const [project, environment, key] = parts as [string, string, string];
50
- return { project, environment, key, value: given };
51
- }
52
-
53
- /** The checks anyone can run: no sign-in, nothing written. `health` false when the caller checked it already. */
54
- export async function anonymousChecks(report: Report, origin: string, options: { health: boolean }): Promise<void> {
55
- if (options.health) await report.check('health', {}, () => reachable(origin));
56
- await report.check('headers', {}, () => headers(origin));
57
- await report.check('anonymous api', {}, () => anonymousApi(origin));
58
- await report.check('forged cross-site', {}, () => forgedCrossSite(origin));
59
- await report.check('sign-in info', {}, () => signinInfo(origin));
60
- await report.check('anonymous answers', {}, () => anonymousAnswers(origin));
61
- }
62
-
63
- /** The checks with a service token that reads the canary, and audits its project. */
64
- export async function tokenChecks(report: Report, origin: string, setup: { token?: string; canary?: Canary }): Promise<void> {
65
- const api = setup.token === undefined ? undefined : bearer(origin, setup.token);
66
- const token = await report.check('token', { api, canary: setup.canary }, ({ api, canary }) => whoIsToken(origin, api, canary));
67
- const needs = { api, canary: setup.canary, token, secret: setup.token };
68
- await report.check('token reveal', needs, ({ api, canary, token }) => tokenReveal(api, canary, token));
69
- await report.check('token scan', needs, ({ canary, secret }) => tokenScan(origin, secret, canary));
70
- await report.check('token scope', needs, ({ api, canary }) => tokenScope(api, canary));
71
- await report.check('token verification', { api }, ({ api }) => tokenVerification(api));
72
- }
73
-
74
- // --- as no one ----------------------------------------------------------------
75
-
76
- /** Every route, whatever its method, turns away a caller with no credential, and says nothing else. */
77
- async function anonymousApi(origin: string): Promise<string> {
78
- const routes = everyRoute(origin);
79
- for (const { key, method, url } of routes) {
80
- const response = await fetch(url, {
81
- method,
82
- headers: { 'content-type': 'application/json' },
83
- body: method === 'GET' ? undefined : '{}',
84
- });
85
- const text = await response.text();
86
- expect(response.status === 401, `${key} answered ${response.status} to no one`, text);
87
- expect(onlyRefusal(text), `${key} refused no one with more than a refusal`, text);
88
- }
89
- return `${routes.length} routes, every method: 401, and nothing but the refusal`;
90
- }
91
-
92
- /**
93
- * A change sent with a session cookie from another site's page is refused
94
- * before the cookie is even looked at, so a made-up one shows it: a real
95
- * cookie would get the same answer. Behind Cloudflare Access the same holds
96
- * for its cookie and assertion.
97
- */
98
- async function forgedCrossSite(origin: string): Promise<string> {
99
- const changes = everyRoute(origin).filter((route) => route.method !== 'GET');
100
- const forged = {
101
- cookie: 'coffre_session=conformance-forged; __Host-coffre_session=conformance-forged; CF_Authorization=conformance-forged',
102
- 'cf-access-jwt-assertion': 'conformance-forged',
103
- origin: 'https://attacker.example',
104
- 'sec-fetch-site': 'cross-site',
105
- 'content-type': 'application/json',
106
- };
107
- for (const { key, method, url } of [...changes, { key: 'POST /auth/signout', method: 'POST', url: `${origin}/auth/signout` }]) {
108
- const response = await fetch(url, { method, headers: forged, body: '{}', redirect: 'manual' });
109
- const text = await response.text();
110
- expect(response.status === 403, `${key} from another site answered ${response.status}`, text);
111
- }
112
- return `${changes.length + 1} changes, sign-out included, from another site with a session cookie: 403`;
113
- }
114
-
115
- /** `GET /api/auth` names how to sign in, and nothing more. */
116
- async function signinInfo(origin: string): Promise<string> {
117
- const response = await fetch(`${origin}/api/auth`);
118
- expect(response.ok, `/api/auth answered ${response.status}`);
119
- const info = (await response.json()) as AuthInfo;
120
- expect(sameKeys(info, ['access', 'signin']), '/api/auth says more than how to sign in', info);
121
- expect((info.signin === null) !== (info.access === null), '/api/auth names neither or both ways in', info);
122
- if (info.access !== null) {
123
- expect(sameKeys(info.access, ['assertion']) && info.access.assertion === false, '/api/auth says more of Access than whether it vouched', info);
124
- return 'Cloudflare Access, and nothing more';
125
- }
126
- const signin = info.signin!;
127
- expect(sameKeys(signin, ['note', 'providers', 'title']), '/api/auth says more of its sign-in than a page needs', signin);
128
- for (const provider of signin.providers) {
129
- expect(sameKeys(provider, ['brand', 'id', 'label']), `/api/auth says more of ${provider.id} than its button`, provider);
130
- }
131
- return `coffre's sign-in through ${signin.providers.map((provider) => provider.id).join(', ')}, and nothing more`;
132
- }
133
-
134
- /**
135
- * Nothing that could be a stored value in what no one is shown. Without a
136
- * canary this is a best effort: the API's refusals are checked to be only
137
- * refusals above, every closed page must send no one to /login with an
138
- * empty body, and the open pages must carry no credential coffre issues.
139
- */
140
- async function anonymousAnswers(origin: string): Promise<string> {
141
- const pages = [...CLOSED_PAGES, `/projects/${NOWHERE.project}`, `/projects/${NOWHERE.project}/${NOWHERE.environment}`];
142
- for (const path of pages) {
143
- // Followed by hand, on this origin only, each hop without a body.
144
- let at = path;
145
- for (let hop = 0; at !== '/login'; hop++) {
146
- const response = await fetch(`${origin}${at}`, { redirect: 'manual' });
147
- const text = await response.text();
148
- const to = new URL(response.headers.get('location') ?? at, origin);
149
- expect(
150
- hop < 3 && response.status >= 300 && response.status < 400 && to.origin === origin,
151
- `${at} answered no one ${response.status}${response.headers.has('location') ? ` to ${to.href}` : ''}, not a redirect on to /login`,
152
- text.slice(0, 2000),
153
- );
154
- expect(text.trim().length < 512, `${at} sent no one a body with its redirect`, text.slice(0, 2000));
155
- at = to.pathname;
156
- }
157
- }
158
- for (const path of OPEN_PAGES) {
159
- const response = await fetch(`${origin}${path}`, { redirect: 'manual' });
160
- const text = await response.text();
161
- expect(response.status === 200, `${path} answered ${response.status}`);
162
- const issued = /coffre_(svc|cli|web)_[A-Za-z0-9_-]{20,}/.exec(text);
163
- expect(issued === null, `${path} carries a credential coffre issues`, issued?.[0]);
164
- }
165
- return `best effort, without a canary: ${pages.length} closed pages send no one to /login with nothing else; /login carries no credential`;
166
- }
167
-
168
- // --- with a token ---------------------------------------------------------------
169
-
170
- type Token = { member: string };
171
-
172
- /** The token is a service's, and reads the canary's environment. */
173
- async function whoIsToken(origin: string, api: CoffreClient, canary: Canary): Promise<{ detail: string; value: Token }> {
174
- const auth = (await (await fetch(`${origin}/api/auth`)).json()) as AuthInfo;
175
- if (auth.signin === null) throw new Skip("behind Cloudflare Access, coffre issues no service tokens: the token's checks need coffre's own sign-in");
176
- const me = await api.me();
177
- expect(me.principal.type === 'service', `the token is ${me.principal.type}:${me.principal.id}'s, not a service's`);
178
- const member = `token:${me.principal.id}`;
179
- const place = `${canary.project}/${canary.environment}`;
180
- const reads = me.environments.find((env) => `${env.project}/${env.environment}` === place);
181
- expect(reads?.permissions.includes('secret.read'), `${member} cannot read ${place}`, me.environments);
182
- const { keys } = await api.secrets.list(place);
183
- expect(keys.some((key) => key.key === canary.key), `${place} holds no ${canary.key}`, keys.map((key) => key.key));
184
- return { detail: `${member}, reading ${place}`, value: { member } };
185
- }
186
-
187
- /** Reveal the canary once, and find its `secret.read` in the audit log, by the reveal's request. */
188
- async function tokenReveal(api: CoffreClient, canary: Canary, token: Token): Promise<string> {
189
- const path = `${canary.project}/${canary.environment}`;
190
- const { operationId, values } = await api.secrets.reveal(`${path}/${canary.key}`);
191
- expect(values[canary.key] === canary.value, `${path}/${canary.key} is not the value given as the canary`);
192
- let entries;
193
- try {
194
- ({ entries } = await api.audit.list({ path, actor: token.member, limit: 50 }));
195
- } catch (error) {
196
- if (error instanceof CoffreError && error.status === 403) {
197
- throw new Skip(`the token holds no audit.read on ${canary.project}, so the reveal's entry cannot be looked for`);
198
- }
199
- throw error;
200
- }
201
- const read = entries.filter((entry) => entry.operationId === operationId);
202
- expect(read.length === 1, `the reveal is logged ${read.length} times, not once`, entries.slice(0, 5));
203
- const [entry] = read as [(typeof read)[number]];
204
- expect(
205
- entry.action === 'secret.read' && entry.decision === 'allow' && entry.key === canary.key && entry.requestId !== null,
206
- "the reveal's entry is not an allowed read of the canary, under a request",
207
- entry,
208
- );
209
- return `one secret.read of ${canary.key}, entry ${entry.seq}, under request ${entry.requestId}`;
210
- }
211
-
212
- /**
213
- * The canary's value, in any answer to a GET route as the token or as no
214
- * one, or in any page. The reveal is the only answer allowed to carry it.
215
- */
216
- async function tokenScan(origin: string, token: string, canary: Canary): Promise<string> {
217
- const api = bearer(origin, token);
218
- const me = await api.me();
219
- const member = `token:${me.principal.id}`;
220
- const listed = me.environments.map(({ project, environment }) => ({ project, environment }));
221
- const places = [...listed, NOWHERE];
222
- const calls = getCalls({
223
- places,
224
- secrets: [{ project: canary.project, environment: canary.environment, key: canary.key }, { ...NOWHERE, key: 'NONE' }],
225
- members: [member, NOBODY, 'user:nobody@conformance.example'],
226
- services: [member, NOBODY],
227
- });
228
- const forms = [canary.value, Buffer.from(canary.value).toString('base64'), Buffer.from(canary.value).toString('hex')];
229
- const leaks: string[] = [];
230
- const callers: [string, Record<string, string>][] = [
231
- ['the token', { authorization: `Bearer ${token}` }],
232
- ['no one', {}],
233
- ];
234
- let answers = 0;
235
- const look = async (what: string, url: string, headers: Record<string, string>) => {
236
- const text = await (await fetch(url, { headers, redirect: 'manual' })).text();
237
- answers++;
238
- if (forms.some((form) => text.includes(form))) leaks.push(what);
239
- };
240
- for (const { key, url } of getUrls(origin, calls)) {
241
- for (const [name, headers] of callers) await look(`${key} as ${name}`, url, headers);
242
- }
243
- const pages = [
244
- ...OPEN_PAGES,
245
- ...CLOSED_PAGES,
246
- ...listed.flatMap(({ project, environment }) => [`/projects/${project}`, `/projects/${project}/${environment}`]),
247
- ];
248
- for (const path of new Set(pages)) {
249
- for (const [name, headers] of callers) await look(`the page ${path} as ${name}`, `${origin}${path}`, headers);
250
- }
251
- expect(leaks.length === 0, "the canary's value was found outside its reveal", leaks);
252
- return `${answers} answers from ${Object.keys(calls).length} GET routes and ${new Set(pages).size} pages, as the token and as no one: no value`;
253
- }
254
-
255
- /** The token reaches the canary's project and nothing else: not another environment, project or member. */
256
- async function tokenScope(api: CoffreClient, canary: Canary): Promise<string> {
257
- const { projects } = await api.projects.list();
258
- const seen = projects.map((project) => project.slug);
259
- expect(seen.length === 1 && seen[0] === canary.project, `the token sees ${seen.join(', ') || 'no project'}, not only ${canary.project}`);
260
- const me = await api.me();
261
- const own = `${canary.project}/${canary.environment}`;
262
- const reads = me.environments.filter((env) => env.permissions.includes('secret.read')).map((env) => `${env.project}/${env.environment}`);
263
- expect(reads.length === 1 && reads[0] === own, `the token reads ${reads.join(', ')}, not only ${own}`);
264
- const more = [...new Set(me.environments.flatMap((env) => env.permissions))].filter(
265
- (permission) => permission !== 'secret.read' && permission !== 'audit.read',
266
- );
267
- expect(more.length === 0, `the token holds more than reading: ${more.join(', ')}`);
268
-
269
- const others = projects[0]!.environments.map((env) => `${canary.project}/${env.slug}`).filter((path) => path !== own);
270
- const nowhere = `${NOWHERE.project}/${NOWHERE.environment}`;
271
- let refusals = 0;
272
- for (const path of [...others, nowhere]) {
273
- await refused(`the token listed ${path}`, api.secrets.list(path));
274
- await refused(`the token revealed ${path}`, api.secrets.reveal(path));
275
- await refused(`the token read ${path}'s syncs`, api.syncs.list(path));
276
- refusals += 3;
277
- }
278
- // Its project's log is the token's to read, as `audit.read` there; another's is not.
279
- await refused(`the token read ${nowhere}'s audit`, api.audit.list({ path: nowhere, limit: 1 }));
280
- await refused('the token listed the members', api.members.list());
281
- await refused(`the token read ${NOBODY}`, api.members.get(NOBODY));
282
- refusals += 3;
283
- try {
284
- const { entries } = await api.audit.list({ limit: 500 });
285
- const outside = entries.filter((entry) => entry.project !== null && entry.project !== canary.project);
286
- expect(outside.length === 0, `the token reads audit entries about ${[...new Set(outside.map((entry) => entry.project))].join(', ')}`);
287
- } catch (error) {
288
- if (!(error instanceof CoffreError && error.status === 403)) throw error;
289
- }
290
- const elsewhere = others.length === 0 ? 'no other environment' : `${others.length} other environment${others.length === 1 ? '' : 's'}`;
291
- return `only ${own}; ${refusals} reads elsewhere refused: ${elsewhere} of ${canary.project}, a made-up place, the members`;
292
- }
293
-
294
- async function tokenVerification(api: CoffreClient): Promise<string> {
295
- let verified;
296
- try {
297
- verified = await api.audit.verify();
298
- } catch (error) {
299
- if (error instanceof CoffreError && error.status === 403) {
300
- throw new Skip('verification is for owners and root admins, which this token is not: not checked');
301
- }
302
- throw error;
303
- }
304
- expect(verified.ok, 'the audit log does not verify', verified);
305
- return `${verified.entries} entries verify, through entry ${verified.through}`;
306
- }
307
-
308
- // --- helpers --------------------------------------------------------------------
309
-
310
- /** `{ error, message }` and nothing else. */
311
- function onlyRefusal(text: string): boolean {
312
- try {
313
- return sameKeys(JSON.parse(text), ['error', 'message']);
314
- } catch {
315
- return false;
316
- }
317
- }
318
-
319
- function sameKeys(value: unknown, keys: string[]): boolean {
320
- return typeof value === 'object' && value !== null && JSON.stringify(Object.keys(value).sort()) === JSON.stringify(keys);
321
- }
package/src/routes.ts DELETED
@@ -1,112 +0,0 @@
1
- // The API's routes, as the checks call them. Both tables are typed over the
2
- // client's route map, so a route added to the server fails the typecheck
3
- // here until it is listed, and from then on every check that walks a table
4
- // covers it: the anonymous refusal, the canary scans, the cross-site one.
5
- import type { Params, RouteInput, RouteKey } from '@coffre/client';
6
-
7
- export type GetKey = Extract<RouteKey, `GET ${string}`>;
8
-
9
- /** Each GET route, with what to ask it. */
10
- export type GetCalls = { [K in GetKey]: { params: Params<K>; input?: RouteInput<K> }[] };
11
-
12
- /** What the GET routes are asked about: places, secrets and members to name. */
13
- export type Subjects = {
14
- places: { project: string; environment: string }[];
15
- /** Secrets whose history to ask for. */
16
- secrets: { project: string; environment: string; key: string }[];
17
- /** `user:…` and `token:…`. */
18
- members: string[];
19
- /** Tokens whose credentials to list. */
20
- services: string[];
21
- };
22
-
23
- export function getCalls({ places, secrets, members, services }: Subjects): GetCalls {
24
- const first = places[0];
25
- return {
26
- 'GET /me': [{ params: {} }],
27
- 'GET /projects': [{ params: {} }],
28
- 'GET /secrets/:project/:environment': places.map((params) => ({ params })),
29
- 'GET /secrets/:project/:environment/:key/versions': secrets.map((params) => ({ params })),
30
- 'GET /members': [
31
- { params: {} },
32
- ...(first === undefined ? [] : [{ params: {}, input: { path: `${first.project}/${first.environment}` } }]),
33
- ],
34
- 'GET /members/:member': members.map((member) => ({ params: { member } })),
35
- 'GET /members/:member/tokens': services.map((member) => ({ params: { member } })),
36
- 'GET /sessions': [{ params: {} }],
37
- 'GET /identities': [{ params: {} }],
38
- 'GET /device-logins/:code': [{ params: { code: 'BCDF-GHJK' } }],
39
- 'GET /syncs/providers': [{ params: {} }],
40
- 'GET /syncs/:project/:environment': places.map((params) => ({ params })),
41
- 'GET /audit': [{ params: {}, input: { limit: 500 } }, { params: {}, input: { limit: 500, detail: '1' } }],
42
- 'GET /audit/verification': [{ params: {} }],
43
- };
44
- }
45
-
46
- /** Each GET call as a URL, with its parameters and query filled in. */
47
- export function getUrls(origin: string, calls: GetCalls): { key: GetKey; url: string }[] {
48
- const urls: { key: GetKey; url: string }[] = [];
49
- for (const [key, asks] of Object.entries(calls) as [GetKey, { params: Record<string, string>; input?: object }[]][]) {
50
- for (const { params, input } of asks) urls.push({ key, url: address(origin, key, params, input) });
51
- }
52
- return urls;
53
- }
54
-
55
- /** Every route, whatever its method. */
56
- const EVERY_ROUTE: { [K in RouteKey]: true } = {
57
- 'GET /me': true,
58
- 'GET /projects': true,
59
- 'PUT /projects/:project': true,
60
- 'PATCH /projects/:project': true,
61
- 'PUT /projects/:project/:environment': true,
62
- 'PATCH /projects/:project/:environment': true,
63
- 'GET /secrets/:project/:environment': true,
64
- 'PATCH /secrets/:project/:environment': true,
65
- 'PATCH /secrets/:project/:environment/:key': true,
66
- 'GET /secrets/:project/:environment/:key/versions': true,
67
- 'POST /secrets/:project/:environment/:key/restore': true,
68
- 'POST /reveals': true,
69
- 'GET /members': true,
70
- 'GET /members/:member': true,
71
- 'PUT /members/:member': true,
72
- 'DELETE /members/:member': true,
73
- 'GET /members/:member/tokens': true,
74
- 'POST /members/:member/tokens': true,
75
- 'DELETE /members/:member/tokens/:id': true,
76
- 'PATCH /access/:member': true,
77
- 'GET /sessions': true,
78
- 'DELETE /sessions/:id': true,
79
- 'GET /identities': true,
80
- 'DELETE /identities/:id': true,
81
- 'GET /device-logins/:code': true,
82
- 'POST /device-logins/:code': true,
83
- 'GET /syncs/providers': true,
84
- 'GET /syncs/:project/:environment': true,
85
- 'POST /syncs/:project/:environment': true,
86
- 'PATCH /syncs/by-id/:id': true,
87
- 'DELETE /syncs/by-id/:id': true,
88
- 'POST /syncs/by-id/:id/runs': true,
89
- 'GET /audit': true,
90
- 'GET /audit/verification': true,
91
- };
92
-
93
- /**
94
- * Every route as a method and a URL, each parameter a made-up value: what
95
- * a caller with no right to any of them would send.
96
- */
97
- export function everyRoute(origin: string): { key: RouteKey; method: string; url: string }[] {
98
- return (Object.keys(EVERY_ROUTE) as RouteKey[]).map((key) => {
99
- const [method, pattern] = key.split(' ') as [string, string];
100
- const path = pattern.replace(/:(\w+)/g, (_, name: string) =>
101
- encodeURIComponent(name === 'member' ? 'token:conformance-nobody' : 'conformance-nobody'),
102
- );
103
- return { key, method, url: `${origin}/api${path}` };
104
- });
105
- }
106
-
107
- function address(origin: string, key: GetKey, params: Record<string, string>, input: object | undefined): string {
108
- const path = key.slice('GET '.length).replace(/:(\w+)/g, (_, name: string) => encodeURIComponent(params[name]!));
109
- const url = new URL(`${origin}/api${path}`);
110
- for (const [name, value] of Object.entries(input ?? {})) url.searchParams.set(name, String(value));
111
- return url.href;
112
- }