@coffre/conformance 0.4.1 → 0.4.2

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/dist/main.js CHANGED
@@ -85,6 +85,52 @@ function drainingConfig(server) {
85
85
  if (import.meta.main) console.log(drainingConfig(resolve(process.argv[2])));
86
86
  //#endregion
87
87
  //#region ../client/dist/index.js
88
+ /** Two colons or more, in hex: an IPv6 address, as `::1` or `2001:db8::1:443` with its port. */
89
+ const IPV6 = /[0-9a-f]*:[0-9a-f]*:[0-9a-f:]*/i;
90
+ const TIMEOUT_OR_REFUSAL = /* @__PURE__ */ new Set([
91
+ "ECONNREFUSED",
92
+ "ETIMEDOUT",
93
+ "UND_ERR_CONNECT_TIMEOUT",
94
+ "ENETUNREACH",
95
+ "EHOSTUNREACH"
96
+ ]);
97
+ /** What to try for the common causes; null for the others. */
98
+ function hint(cause) {
99
+ const code = cause.code ?? "";
100
+ if (code === "ENOTFOUND" || code === "EAI_AGAIN") return "the name does not resolve here: check the address, or flush this machine's DNS cache";
101
+ const tried = [cause, ...cause.errors ?? []].flatMap((each) => [each.address ?? "", each.message]);
102
+ if (TIMEOUT_OR_REFUSAL.has(code) && tried.some((each) => IPV6.test(each))) return "it was tried over IPv6, which this network may not carry: try NODE_OPTIONS=--dns-result-order=ipv4first";
103
+ if (/CERT|UNABLE_TO_VERIFY|SELF_SIGNED/.test(code)) return "something between you and the instance, such as a proxy or a network filter, presents its own certificate";
104
+ return null;
105
+ }
106
+ /** The cause's own words, with its code and address when they don't already say them. */
107
+ function described(cause) {
108
+ const said = cause.message || (cause.errors ?? []).map((each) => each.message).join(", ");
109
+ const address = cause.address === void 0 ? void 0 : cause.port === void 0 ? cause.address : `${cause.address}:${cause.port}`;
110
+ const more = [cause.code, address].filter((each) => each !== void 0 && !said.includes(each));
111
+ if (said === "") return more.join(" ") || cause.name;
112
+ return more.length === 0 ? said : `${said} (${more.join(", ")})`;
113
+ }
114
+ /**
115
+ * `could not reach <origin>: <why>`, and what to try when the cause is a
116
+ * common one: `could not reach https://x: getaddrinfo ENOTFOUND x; the name
117
+ * does not resolve here: …`.
118
+ */
119
+ function unreachable(origin, error) {
120
+ const cause = error instanceof Error && error.cause instanceof Error ? error.cause : null;
121
+ if (cause === null) return `could not reach ${origin}: ${error instanceof Error ? error.message : String(error)}`;
122
+ const then = hint(cause);
123
+ return `could not reach ${origin}: ${described(cause)}${then === null ? "" : `; ${then}`}`;
124
+ }
125
+ /** A request that never reached the instance: its message says why, `cause` is what `fetch` threw. */
126
+ var Unreachable = class extends Error {
127
+ origin;
128
+ constructor(origin, error) {
129
+ super(unreachable(origin, error), { cause: error });
130
+ this.name = "Unreachable";
131
+ this.origin = origin;
132
+ }
133
+ };
88
134
  /** The API's error shape, `{ error, message }`, with the HTTP status. */
89
135
  var CoffreError = class extends Error {
90
136
  status;
@@ -110,7 +156,13 @@ function place(path) {
110
156
  }
111
157
  function createClient(options) {
112
158
  const origin = options.url.replace(/\/+$/, "");
113
- const transport = options.transport ?? ((request) => fetch(request));
159
+ const transport = options.transport ?? (async (request) => {
160
+ try {
161
+ return await fetch(request);
162
+ } catch (error) {
163
+ throw new Unreachable(origin, error);
164
+ }
165
+ });
114
166
  async function send(method, path, input) {
115
167
  const url = new URL(`${origin}/api${path}`);
116
168
  const headers = new Headers(await options.headers?.());
@@ -968,8 +1020,12 @@ function token(deployment, fields) {
968
1020
  body: new URLSearchParams(fields)
969
1021
  });
970
1022
  }
971
- /** The person approves on the consent page, as its Approve does; the code comes back on the redirect. */
972
- async function connect(deployment, person, clientId, scope = "browse") {
1023
+ /**
1024
+ * The person approves on the consent page, as its Approve does, with what
1025
+ * they ticked: by default what the client asked for. The code comes back on
1026
+ * the redirect.
1027
+ */
1028
+ async function connect(deployment, person, clientId, scope = "read", ticked = scope.split(" ")) {
973
1029
  const verifier = base64url(randomBytes(32));
974
1030
  const request = {
975
1031
  client_id: clientId,
@@ -987,7 +1043,7 @@ async function connect(deployment, person, clientId, scope = "browse") {
987
1043
  const { redirect } = await person.api.oauth.decide({
988
1044
  request,
989
1045
  approve: true,
990
- scopes: scope.split(" ")
1046
+ scopes: ticked
991
1047
  });
992
1048
  const back = new URL(redirect);
993
1049
  expect(`${back.origin}${back.pathname}` === REDIRECT, `the answer went to ${back.origin}${back.pathname}, not the redirect`, redirect);
@@ -1035,7 +1091,7 @@ async function mcpConnect(deployment, people) {
1035
1091
  const anonymous = await mcp(deployment, {});
1036
1092
  const challenge = anonymous.headers.get("www-authenticate") ?? "";
1037
1093
  expect(anonymous.status === 401, `/mcp answered ${anonymous.status} without a token, not 401`);
1038
- expect(challenge.includes(`resource_metadata="${origin}/.well-known/oauth-protected-resource/mcp"`) && challenge.includes("scope=\"browse\""), "the 401's challenge does not name the resource metadata and Browse", challenge);
1094
+ expect(challenge.includes(`resource_metadata="${origin}/.well-known/oauth-protected-resource/mcp"`) && challenge.includes("scope=\"read\""), "the 401's challenge does not name the resource metadata and Read", challenge);
1039
1095
  const resource = await json(await fetch(`${origin}/.well-known/oauth-protected-resource/mcp`));
1040
1096
  expect(resource.resource === `${origin}/mcp` && resource.authorization_servers?.[0] === origin, "the protected resource metadata does not name /mcp and coffre as its issuer", resource);
1041
1097
  const server = await json(await fetch(`${origin}/.well-known/oauth-authorization-server`));
@@ -1081,7 +1137,7 @@ async function mcpConnect(deployment, people) {
1081
1137
  });
1082
1138
  expect(forged.status === 403, `another site's approval answered ${forged.status}, not 403`);
1083
1139
  const first = await redeem(deployment, clientId, await connect(deployment, people.reader, clientId));
1084
- expect(first.access_token.startsWith("coffre_mcp_") && first.refresh_token.startsWith("coffre_mcr_") && first.scope === "browse", "the tokens are not the shapes and scope coffre issues", { scope: first.scope });
1140
+ expect(first.access_token.startsWith("coffre_mcp_") && first.refresh_token.startsWith("coffre_mcr_") && first.scope === "read", "the tokens are not the shapes and scope coffre issues", { scope: first.scope });
1085
1141
  expect(await discovers(deployment, first.access_token), "a fresh access token was refused at /mcp");
1086
1142
  const atApi = await fetch(`${origin}/api/me`, { headers: { authorization: `Bearer ${first.access_token}` } });
1087
1143
  expect(atApi.status === 401, `an MCP token at /api answered ${atApi.status}, not 401`);
@@ -1192,19 +1248,19 @@ async function register(deployment) {
1192
1248
  })
1193
1249
  }))).client_id;
1194
1250
  }
1195
- /** A client registered and connected as the person, with Browse, for a check of another's: its access token. */
1251
+ /** A client registered and connected as the person, with Read, for a check of another's: its access token. */
1196
1252
  async function connectedApp(deployment, person) {
1197
1253
  const clientId = await register(deployment);
1198
1254
  return (await redeem(deployment, clientId, await connect(deployment, person, clientId))).access_token;
1199
1255
  }
1200
1256
  /**
1201
- * The Browse tools, as a client calls them (design section 14, checks 1, 4
1257
+ * The Read tools, as a client calls them (design section 14, checks 1, 4
1202
1258
  * and 5): on 2026-07-28 and through a 2025-11-25 `initialize`, as the
1203
1259
  * reader, who sees dev and not prod. No value appears in any answer, the
1204
1260
  * headers must agree with the body, and every call is in the log under the
1205
1261
  * client, the API's own entries naming the connection.
1206
1262
  */
1207
- async function mcpBrowse(deployment, people, canaries) {
1263
+ async function mcpRead(deployment, people, canaries) {
1208
1264
  const clientId = await register(deployment);
1209
1265
  const { access_token: access } = await redeem(deployment, clientId, await connect(deployment, people.reader, clientId));
1210
1266
  const answers = [];
@@ -1214,7 +1270,7 @@ async function mcpBrowse(deployment, people, canaries) {
1214
1270
  const listed = await modern(deployment, access, "tools/list");
1215
1271
  const result = listed.body.result;
1216
1272
  const names = result?.tools?.map((tool) => tool.name) ?? [];
1217
- expect(names.includes("list_secrets") && names.includes("run_with_secrets") && result?.cacheScope === "public" && typeof result.ttlMs === "number", "tools/list does not list the Browse tools, cacheable", listed.body);
1273
+ expect(names.includes("list_secrets") && names.includes("run_with_secrets") && result?.cacheScope === "public" && typeof result.ttlMs === "number", "tools/list does not list the Read tools, cacheable", listed.body);
1218
1274
  const callTool = async (tool, args) => {
1219
1275
  const { response, body } = await modern(deployment, access, "tools/call", {
1220
1276
  name: tool,
@@ -1269,7 +1325,7 @@ async function mcpBrowse(deployment, people, canaries) {
1269
1325
  answers.push(JSON.stringify(legacyBody));
1270
1326
  expect(legacy.status === 200 && legacyBody.result?.isError !== true, `a 2025-11-25 tools/call answered ${legacy.status}`, legacyBody);
1271
1327
  const leaked = Object.entries(canaries).filter(([, value]) => answers.some((answer) => answer.includes(value))).map(([path]) => path);
1272
- expect(leaked.length === 0, "a Browse tool answered with a secret value", leaked);
1328
+ expect(leaked.length === 0, "a Read tool answered with a secret value", leaked);
1273
1329
  const { entries } = await people.admin.api.audit.list({
1274
1330
  actor: people.reader.member,
1275
1331
  detail: "1",
@@ -1288,11 +1344,11 @@ async function mcpBrowse(deployment, people, canaries) {
1288
1344
  limit: 500
1289
1345
  })).entries;
1290
1346
  expect(!shown.some((entry) => entry.action === "mcp.read"), "read-only calls are not detail");
1291
- return `on 2026-07-28 and 2025-11-25, the Browse tools as the reader: ${DEV} listed, ${PROD} refused, no value in any answer; headers held to the body; ${reads} reads as detail and the refusal shown, each under the client`;
1347
+ return `on 2026-07-28 and 2025-11-25, the Read tools as the reader: ${DEV} listed, ${PROD} refused, no value in any answer; headers held to the body; ${reads} reads as detail and the refusal shown, each under the client`;
1292
1348
  }
1293
1349
  /**
1294
1350
  * Changes, as a client asks for them (design section 14, checks 2 and 3):
1295
- * Browse cannot ask at all, and with Write nothing changes until the person
1351
+ * Read cannot ask at all, and with Write nothing changes until the person
1296
1352
  * approves on coffre's page. A client without URL elicitation gets the link
1297
1353
  * and calls again; one with it is asked to open the page, and retries with
1298
1354
  * its requestState, which no other call may use. Only the person decides,
@@ -1328,11 +1384,14 @@ async function mcpChanges(deployment, people, canaries) {
1328
1384
  };
1329
1385
  };
1330
1386
  const archived = async (key) => (await admin.api.secrets.history(`${place}/${key}`)).archived;
1331
- const browse = (await redeem(deployment, clientId, await connect(deployment, changer, clientId))).access_token;
1332
- const stepUp = await call(browse, "archive_secret", { secret: `${place}/OLD` });
1333
- expect(stepUp.status === 403 && stepUp.challenge.includes("error=\"insufficient_scope\"") && stepUp.challenge.includes("scope=\"browse write\""), `archive_secret with Browse answered ${stepUp.status}, not a step-up to Write`, stepUp.challenge);
1334
- expect(!await archived("OLD"), "archive_secret with Browse archived the secret");
1335
- const write = (await redeem(deployment, clientId, await connect(deployment, changer, clientId, "browse write"))).access_token;
1387
+ const reading = (await redeem(deployment, clientId, await connect(deployment, changer, clientId))).access_token;
1388
+ const stepUp = await call(reading, "archive_secret", { secret: `${place}/OLD` });
1389
+ expect(stepUp.status === 403 && stepUp.challenge.includes("error=\"insufficient_scope\"") && stepUp.challenge.includes("scope=\"read write\""), `archive_secret with Read answered ${stepUp.status}, not a step-up to Write`, stepUp.challenge);
1390
+ expect(stepUp.result?.isError === true && stepUp.result.content?.[0]?.text?.includes("ticking Write on coffre's consent page") === true, "archive_secret with Read does not say, as its result, how to grant Write", stepUp.result);
1391
+ expect(!await archived("OLD"), "archive_secret with Read archived the secret");
1392
+ const granted = await redeem(deployment, clientId, await connect(deployment, changer, clientId, "read", ["write"]));
1393
+ expect(granted.scope === "read write", `a connection ticked Write answered scope "${granted.scope}", not "read write"`, granted.scope);
1394
+ const write = granted.access_token;
1336
1395
  const linked = await call(write, "archive_secret", { secret: `${place}/OLD` });
1337
1396
  const approval = linked.result?.structuredContent?.approval;
1338
1397
  expect(linked.status === 200 && linked.result?.structuredContent?.status === "pending" && approval?.url === `${deployment.origin}/approvals/${approval?.id}`, "a change without URL elicitation was not answered with its approval link", linked.result);
@@ -1456,11 +1515,11 @@ async function mcpChanges(deployment, people, canaries) {
1456
1515
  "deny approved",
1457
1516
  "deny changed"
1458
1517
  ]), "the decisions, and the two refused, are not in the log", decisions);
1459
- return `Browse stepped up to Write; with Write, the link without URL elicitation and an elicitation with it; nothing changed until ${changer.email} approved on coffre's page, another person and another site refused, a replayed requestState refused; each change made once, via the client and its approval; a value typed on the page only, and one coffre made reaching no one`;
1518
+ return `Read stepped up to Write, saying how as its result; Write ticked beyond what was asked; with Write, the link without URL elicitation and an elicitation with it; nothing changed until ${changer.email} approved on coffre's page, another person and another site refused, a replayed requestState refused; each change made once, via the client and its approval; a value typed on the page only, and one coffre made reaching no one`;
1460
1519
  }
1461
1520
  /**
1462
- * Values (design section 14, checks 2 and 4): Browse cannot read one, Read
1463
- * values reads what the person may, a value shown on coffre's page goes to
1521
+ * Values (design section 14, checks 2 and 4): Read cannot get one, Reveal
1522
+ * values gets what the person may, a value shown on coffre's page goes to
1464
1523
  * the person and not the client, and one a client asks coffre to make
1465
1524
  * reaches no one.
1466
1525
  */
@@ -1481,10 +1540,10 @@ async function mcpValues(deployment, people, canaries) {
1481
1540
  };
1482
1541
  };
1483
1542
  const dev = valuesIn(canaries, DEV);
1484
- const browse = (await redeem(deployment, clientId, await connect(deployment, reader, clientId))).access_token;
1485
- const stepUp = await call(browse, "read_secret_values", { path: DEV });
1486
- expect(stepUp.status === 403 && stepUp.challenge.includes("scope=\"browse read-values\""), `read_secret_values with Browse answered ${stepUp.status}, not a step-up`, stepUp.challenge);
1487
- const show = await call(browse, "show_secret_value", { secret: `${DEV}/API_KEY` });
1543
+ const reading = (await redeem(deployment, clientId, await connect(deployment, reader, clientId))).access_token;
1544
+ const stepUp = await call(reading, "read_secret_values", { path: DEV });
1545
+ expect(stepUp.status === 403 && stepUp.challenge.includes("scope=\"read reveal\""), `read_secret_values with Read answered ${stepUp.status}, not a step-up`, stepUp.challenge);
1546
+ const show = await call(reading, "show_secret_value", { secret: `${DEV}/API_KEY` });
1488
1547
  const id = show.result?.structuredContent?.approval?.id;
1489
1548
  expect(show.result?.structuredContent?.status === "pending" && id !== void 0, "show_secret_value did not open an approval", show.result);
1490
1549
  const page = (await reader.api.approvals.get(id)).approval;
@@ -1493,17 +1552,17 @@ async function mcpValues(deployment, people, canaries) {
1493
1552
  approve: true,
1494
1553
  digest: page.digest
1495
1554
  })).shown.some((line) => line.value === dev.API_KEY), "Reveal did not show the person the value");
1496
- const told = await call(browse, "show_secret_value", { secret: `${DEV}/API_KEY` });
1555
+ const told = await call(reading, "show_secret_value", { secret: `${DEV}/API_KEY` });
1497
1556
  expect(told.result?.structuredContent?.status === "approved", "show_secret_value does not report the value as shown", told.result);
1498
- const browseLeaks = Object.entries(canaries).filter(([, value]) => answers.some((answer) => answer.includes(value))).map(([path]) => path);
1499
- expect(browseLeaks.length === 0, "a Browse answer held a value", browseLeaks);
1500
- const reading = (await redeem(deployment, clientId, await connect(deployment, reader, clientId, "browse read-values"))).access_token;
1501
- const read = await call(reading, "read_secret_values", { path: DEV });
1557
+ const readLeaks = Object.entries(canaries).filter(([, value]) => answers.some((answer) => answer.includes(value))).map(([path]) => path);
1558
+ expect(readLeaks.length === 0, "a Read answer held a value", readLeaks);
1559
+ const revealing = (await redeem(deployment, clientId, await connect(deployment, reader, clientId, "read reveal"))).access_token;
1560
+ const read = await call(revealing, "read_secret_values", { path: DEV });
1502
1561
  expect(JSON.stringify(read.result?.structuredContent?.values) === JSON.stringify(dev), `read_secret_values on ${DEV} did not answer its values`);
1503
1562
  expect(read.result?.content?.[0]?.text?.startsWith("These values are now part of this conversation") === true, "read_secret_values does not warn first", read.result?.content);
1504
- const prod = await call(reading, "read_secret_values", { path: PROD });
1563
+ const prod = await call(revealing, "read_secret_values", { path: PROD });
1505
1564
  expect(prod.result?.isError === true && !JSON.stringify(prod.result).includes(canaries[`${PROD}/API_KEY`]), `the reader read ${PROD} through MCP`, prod.result);
1506
- return `Browse stepped up for values and showed ${DEV}/API_KEY to ${reader.email} on coffre's page only; Read values answered ${DEV}'s values, warning first, and refused ${PROD}`;
1565
+ return `Read stepped up for values and showed ${DEV}/API_KEY to ${reader.email} on coffre's page only; Reveal values answered ${DEV}'s values, warning first, and refused ${PROD}`;
1507
1566
  }
1508
1567
  //#endregion
1509
1568
  //#region src/checks/storage.ts
@@ -3066,7 +3125,12 @@ function pages(people) {
3066
3125
  "/",
3067
3126
  "/login",
3068
3127
  "/unregistered",
3069
- "/account",
3128
+ ...[
3129
+ "",
3130
+ "/sessions",
3131
+ "/apps",
3132
+ "/appearance"
3133
+ ].map((tab) => `/account${tab}`),
3070
3134
  "/audit",
3071
3135
  "/settings",
3072
3136
  "/auth/device",
@@ -3863,7 +3927,7 @@ async function consentUrl(deployment) {
3863
3927
  code_challenge: "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
3864
3928
  code_challenge_method: "S256",
3865
3929
  state: "pages",
3866
- scope: "browse write"
3930
+ scope: "read write"
3867
3931
  });
3868
3932
  return `${deployment.origin}/oauth/authorize?${request}`;
3869
3933
  }
@@ -3910,8 +3974,29 @@ async function pagesInBrowser(deployment, admin, browser) {
3910
3974
  `${account}/activity`,
3911
3975
  `service:${name}`,
3912
3976
  "Activity"
3977
+ ],
3978
+ [
3979
+ "/account",
3980
+ "Account",
3981
+ "Profile"
3982
+ ],
3983
+ [
3984
+ "/account/sessions",
3985
+ "Account",
3986
+ "Sessions"
3987
+ ],
3988
+ [
3989
+ "/account/apps",
3990
+ "Account",
3991
+ "Connected apps"
3992
+ ],
3993
+ [
3994
+ "/account/appearance",
3995
+ "Account",
3996
+ "Appearance"
3913
3997
  ]
3914
3998
  ];
3999
+ const mcp = `${deployment.origin}/mcp`;
3915
4000
  const chrome = await Chrome.open(executable);
3916
4001
  try {
3917
4002
  for (const [path, heading, tab] of pages) {
@@ -3927,6 +4012,14 @@ async function pagesInBrowser(deployment, admin, browser) {
3927
4012
  }
3928
4013
  if (path === "/settings") expect(loaded.cards.includes("Keys"), "/settings does not show what the keys are checked against", loaded.cards);
3929
4014
  if (path === person) expect(loaded.cards.includes("Connected apps"), `${path} does not show an owner the person's connected apps`, loaded.cards);
4015
+ if (path === "/account/apps") {
4016
+ expect(loaded.cards.join(" then ") === "Connect an app then Connected apps", `${path} does not show Connect an app, then the connected apps`, loaded.cards);
4017
+ for (const shown of [
4018
+ mcp,
4019
+ `claude mcp add --transport http coffre ${mcp}`,
4020
+ "Add custom connector"
4021
+ ]) expect(loaded.text.includes(shown), `${path} does not show "${shown}"`, loaded.text);
4022
+ }
3930
4023
  }
3931
4024
  const project = new URL(`/projects/${PROJECT$1}`, deployment.origin).href;
3932
4025
  const walked = await chrome.load(project, admin.browser.cookies(), void 0, WALK_TABS);
@@ -3950,14 +4043,16 @@ async function pagesInBrowser(deployment, admin, browser) {
3950
4043
  "Unverified",
3951
4044
  "localhost",
3952
4045
  admin.email,
3953
- "Browse",
4046
+ "Read",
4047
+ "Reveal values",
4048
+ "Manage access",
3954
4049
  "Approve",
3955
4050
  "Deny"
3956
4051
  ]) expect(loaded.text.includes(shown), `/oauth/authorize does not show "${shown}"`, loaded.text);
3957
4052
  } finally {
3958
4053
  await chrome.close();
3959
4054
  }
3960
- return `${pages.map(([path]) => path).join(", ")}, signed in, in Chrome: each rendered, on its tab, no error from their scripts; a project's tabs by their links, back and forward; a service account shown as service:${name}, OIDC then bearer tokens, its removal previewed; the keys' checks in Settings; its grant on dev in every project with an owner's grant button; the MCP consent page, a registered client shown as unverified`;
4055
+ return `${pages.map(([path]) => path).join(", ")}, signed in, in Chrome: each rendered, on its tab, no error from their scripts; a project's tabs by their links, back and forward; a service account shown as service:${name}, OIDC then bearer tokens, its removal previewed; the keys' checks in Settings; its grant on dev in every project with an owner's grant button; the account's Connected apps tab, with this instance's MCP URL and Claude Code's command; the MCP consent page, a registered client shown as unverified`;
3961
4056
  }
3962
4057
  /**
3963
4058
  * A refused sign-in, said once: the page coffre sends the browser back to
@@ -4436,7 +4531,7 @@ async function conform(deployment, options) {
4436
4531
  await report.check("references", all, ({ people, canaries }) => references(deployment, people, canaries));
4437
4532
  await report.check("missing keys", { people }, ({ people }) => missingKeys(people));
4438
4533
  await report.check("MCP connect", { people }, ({ people }) => mcpConnect(deployment, people));
4439
- await report.check("MCP browse", all, ({ people, canaries }) => mcpBrowse(deployment, people, canaries));
4534
+ await report.check("MCP read", all, ({ people, canaries }) => mcpRead(deployment, people, canaries));
4440
4535
  await report.check("MCP changes", all, ({ people, canaries }) => mcpChanges(deployment, people, canaries));
4441
4536
  await report.check("MCP values", all, ({ people, canaries }) => mcpValues(deployment, people, canaries));
4442
4537
  await report.check("reveals audited", all, ({ people, canaries }) => revealAudited(deployment, people, canaries, "reveal"));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@coffre/conformance",
3
- "version": "0.4.1",
3
+ "version": "0.4.2",
4
4
  "description": "Checks a coffre deployment from outside: what it must never do, whatever code it runs.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -31,8 +31,8 @@
31
31
  "dependencies": {
32
32
  "jose": "6.2.3",
33
33
  "pg": "8.16.3",
34
- "@coffre/db": "0.4.1",
35
- "@coffre/cli": "0.4.1"
34
+ "@coffre/cli": "0.4.2",
35
+ "@coffre/db": "0.4.2"
36
36
  },
37
37
  "devDependencies": {
38
38
  "@types/node": "26.1.1",
@@ -41,7 +41,7 @@
41
41
  "tsdown": "0.23.0",
42
42
  "typescript": "5.9.3",
43
43
  "vite": "8.1.5",
44
- "@coffre/client": "0.4.1"
44
+ "@coffre/client": "0.4.2"
45
45
  },
46
46
  "scripts": {
47
47
  "build": "tsdown",
@@ -29,7 +29,7 @@ function pages(people: People): string[] {
29
29
  '/',
30
30
  '/login',
31
31
  '/unregistered',
32
- '/account',
32
+ ...['', '/sessions', '/apps', '/appearance'].map((tab) => `/account${tab}`),
33
33
  '/audit',
34
34
  '/settings',
35
35
  '/auth/device',
package/src/checks/mcp.ts CHANGED
@@ -52,8 +52,12 @@ function token(deployment: Deployment, fields: Record<string, string>): Promise<
52
52
  });
53
53
  }
54
54
 
55
- /** The person approves on the consent page, as its Approve does; the code comes back on the redirect. */
56
- async function connect(deployment: Deployment, person: Person, clientId: string, scope = 'browse'): Promise<{ code: string; verifier: string }> {
55
+ /**
56
+ * The person approves on the consent page, as its Approve does, with what
57
+ * they ticked: by default what the client asked for. The code comes back on
58
+ * the redirect.
59
+ */
60
+ async function connect(deployment: Deployment, person: Person, clientId: string, scope = 'read', ticked = scope.split(' ')): Promise<{ code: string; verifier: string }> {
57
61
  const verifier = base64url(randomBytes(32));
58
62
  const request = {
59
63
  client_id: clientId,
@@ -69,7 +73,7 @@ async function connect(deployment: Deployment, person: Person, clientId: string,
69
73
  expect(view.status === 'ready', 'the consent page refused a good request', view);
70
74
  expect(view.client.registration === 'dcr' && view.client.name === NAME && view.scopes.join(' ') === scope && view.loopbackOnly,
71
75
  'the consent page does not show the registered client as it is', view);
72
- const { redirect } = await person.api.oauth.decide({ request, approve: true, scopes: scope.split(' ') });
76
+ const { redirect } = await person.api.oauth.decide({ request, approve: true, scopes: ticked });
73
77
  const back = new URL(redirect);
74
78
  expect(`${back.origin}${back.pathname}` === REDIRECT, `the answer went to ${back.origin}${back.pathname}, not the redirect`, redirect);
75
79
  expect(back.searchParams.get('state') === STATE && back.searchParams.get('iss') === deployment.origin,
@@ -118,8 +122,8 @@ export async function mcpConnect(deployment: Deployment, people: People): Promis
118
122
  const anonymous = await mcp(deployment, {});
119
123
  const challenge = anonymous.headers.get('www-authenticate') ?? '';
120
124
  expect(anonymous.status === 401, `/mcp answered ${anonymous.status} without a token, not 401`);
121
- expect(challenge.includes(`resource_metadata="${origin}/.well-known/oauth-protected-resource/mcp"`) && challenge.includes('scope="browse"'),
122
- "the 401's challenge does not name the resource metadata and Browse", challenge);
125
+ expect(challenge.includes(`resource_metadata="${origin}/.well-known/oauth-protected-resource/mcp"`) && challenge.includes('scope="read"'),
126
+ "the 401's challenge does not name the resource metadata and Read", challenge);
123
127
  const resource = await json(await fetch(`${origin}/.well-known/oauth-protected-resource/mcp`));
124
128
  expect(resource.resource === `${origin}/mcp` && (resource.authorization_servers as unknown[] | undefined)?.[0] === origin,
125
129
  'the protected resource metadata does not name /mcp and coffre as its issuer', resource);
@@ -157,7 +161,7 @@ export async function mcpConnect(deployment: Deployment, people: People): Promis
157
161
 
158
162
  // The first connection: its code redeemed, then its refresh token rotated.
159
163
  const first = await redeem(deployment, clientId, await connect(deployment, people.reader, clientId));
160
- expect(first.access_token.startsWith('coffre_mcp_') && first.refresh_token.startsWith('coffre_mcr_') && first.scope === 'browse',
164
+ expect(first.access_token.startsWith('coffre_mcp_') && first.refresh_token.startsWith('coffre_mcr_') && first.scope === 'read',
161
165
  'the tokens are not the shapes and scope coffre issues', { scope: first.scope });
162
166
  expect(await discovers(deployment, first.access_token), 'a fresh access token was refused at /mcp');
163
167
 
@@ -233,20 +237,20 @@ async function register(deployment: Deployment): Promise<string> {
233
237
  return registered.client_id as string;
234
238
  }
235
239
 
236
- /** A client registered and connected as the person, with Browse, for a check of another's: its access token. */
240
+ /** A client registered and connected as the person, with Read, for a check of another's: its access token. */
237
241
  export async function connectedApp(deployment: Deployment, person: Person): Promise<string> {
238
242
  const clientId = await register(deployment);
239
243
  return (await redeem(deployment, clientId, await connect(deployment, person, clientId))).access_token;
240
244
  }
241
245
 
242
246
  /**
243
- * The Browse tools, as a client calls them (design section 14, checks 1, 4
247
+ * The Read tools, as a client calls them (design section 14, checks 1, 4
244
248
  * and 5): on 2026-07-28 and through a 2025-11-25 `initialize`, as the
245
249
  * reader, who sees dev and not prod. No value appears in any answer, the
246
250
  * headers must agree with the body, and every call is in the log under the
247
251
  * client, the API's own entries naming the connection.
248
252
  */
249
- export async function mcpBrowse(deployment: Deployment, people: People, canaries: Canaries): Promise<string> {
253
+ export async function mcpRead(deployment: Deployment, people: People, canaries: Canaries): Promise<string> {
250
254
  const clientId = await register(deployment);
251
255
  const { access_token: access } = await redeem(deployment, clientId, await connect(deployment, people.reader, clientId));
252
256
  const answers: string[] = [];
@@ -259,7 +263,7 @@ export async function mcpBrowse(deployment: Deployment, people: People, canaries
259
263
  const result = listed.body.result as { tools?: { name: string; annotations?: { readOnlyHint?: boolean } }[]; cacheScope?: string; ttlMs?: number } | undefined;
260
264
  const names = result?.tools?.map((tool) => tool.name) ?? [];
261
265
  expect(names.includes('list_secrets') && names.includes('run_with_secrets') && result?.cacheScope === 'public' && typeof result.ttlMs === 'number',
262
- 'tools/list does not list the Browse tools, cacheable', listed.body);
266
+ 'tools/list does not list the Read tools, cacheable', listed.body);
263
267
  const callTool = async (tool: string, args: Record<string, unknown>) => {
264
268
  const { response, body } = await modern(deployment, access, 'tools/call', { name: tool, arguments: args }, tool);
265
269
  answers.push(JSON.stringify(body));
@@ -298,7 +302,7 @@ export async function mcpBrowse(deployment: Deployment, people: People, canaries
298
302
 
299
303
  // No value in any answer.
300
304
  const leaked = Object.entries(canaries).filter(([, value]) => answers.some((answer) => answer.includes(value))).map(([path]) => path);
301
- expect(leaked.length === 0, 'a Browse tool answered with a secret value', leaked);
305
+ expect(leaked.length === 0, 'a Read tool answered with a secret value', leaked);
302
306
 
303
307
  // Every call in the log, under the client; the API's own refusal names the connection.
304
308
  const { entries } = await people.admin.api.audit.list({ actor: people.reader.member, detail: '1', limit: 500 });
@@ -310,7 +314,7 @@ export async function mcpBrowse(deployment: Deployment, people: People, canaries
310
314
  expect(api.length > 0, "the API's own entries for the calls do not name the connection", mine.map((entry) => entry.action));
311
315
  const shown = (await people.admin.api.audit.list({ actor: people.reader.member, limit: 500 })).entries;
312
316
  expect(!shown.some((entry) => entry.action === 'mcp.read'), 'read-only calls are not detail');
313
- return `on 2026-07-28 and 2025-11-25, the Browse tools as the reader: ${DEV} listed, ${PROD} refused, no value in any answer; headers held to the body; ${reads} reads as detail and the refusal shown, each under the client`;
317
+ return `on 2026-07-28 and 2025-11-25, the Read tools as the reader: ${DEV} listed, ${PROD} refused, no value in any answer; headers held to the body; ${reads} reads as detail and the refusal shown, each under the client`;
314
318
  }
315
319
 
316
320
  type ToolAnswer = {
@@ -324,7 +328,7 @@ type ToolAnswer = {
324
328
 
325
329
  /**
326
330
  * Changes, as a client asks for them (design section 14, checks 2 and 3):
327
- * Browse cannot ask at all, and with Write nothing changes until the person
331
+ * Read cannot ask at all, and with Write nothing changes until the person
328
332
  * approves on coffre's page. A client without URL elicitation gets the link
329
333
  * and calls again; one with it is asked to open the page, and retries with
330
334
  * its requestState, which no other call may use. Only the person decides,
@@ -349,15 +353,21 @@ export async function mcpChanges(deployment: Deployment, people: People, canarie
349
353
  };
350
354
  const archived = async (key: string) => (await admin.api.secrets.history(`${place}/${key}`)).archived;
351
355
 
352
- // Browse cannot ask for a change: 403, and the step-up's scopes; nothing reached the API.
353
- const browse = (await redeem(deployment, clientId, await connect(deployment, changer, clientId))).access_token;
354
- const stepUp = await call(browse, 'archive_secret', { secret: `${place}/OLD` });
355
- expect(stepUp.status === 403 && stepUp.challenge.includes('error="insufficient_scope"') && stepUp.challenge.includes('scope="browse write"'),
356
- `archive_secret with Browse answered ${stepUp.status}, not a step-up to Write`, stepUp.challenge);
357
- expect(!(await archived('OLD')), 'archive_secret with Browse archived the secret');
356
+ // Read cannot ask for a change: 403, the step-up's scopes, and for a client that does not step up, how to grant Write; nothing reached the API.
357
+ const reading = (await redeem(deployment, clientId, await connect(deployment, changer, clientId))).access_token;
358
+ const stepUp = await call(reading, 'archive_secret', { secret: `${place}/OLD` });
359
+ expect(stepUp.status === 403 && stepUp.challenge.includes('error="insufficient_scope"') && stepUp.challenge.includes('scope="read write"'),
360
+ `archive_secret with Read answered ${stepUp.status}, not a step-up to Write`, stepUp.challenge);
361
+ expect(stepUp.result?.isError === true && stepUp.result.content?.[0]?.text?.includes("ticking Write on coffre's consent page") === true,
362
+ 'archive_secret with Read does not say, as its result, how to grant Write', stepUp.result);
363
+ expect(!(await archived('OLD')), 'archive_secret with Read archived the secret');
364
+
365
+ // Write ticked on the consent page, though the client asked for Read only, as Claude does; the token says so.
366
+ const granted = await redeem(deployment, clientId, await connect(deployment, changer, clientId, 'read', ['write']));
367
+ expect(granted.scope === 'read write', `a connection ticked Write answered scope "${granted.scope}", not "read write"`, granted.scope);
368
+ const write = granted.access_token;
358
369
 
359
370
  // With Write, and no URL elicitation: the link, and nothing changed.
360
- const write = (await redeem(deployment, clientId, await connect(deployment, changer, clientId, 'browse write'))).access_token;
361
371
  const linked = await call(write, 'archive_secret', { secret: `${place}/OLD` });
362
372
  const approval = linked.result?.structuredContent?.approval;
363
373
  expect(linked.status === 200 && linked.result?.structuredContent?.status === 'pending' && approval?.url === `${deployment.origin}/approvals/${approval?.id}`,
@@ -435,12 +445,12 @@ export async function mcpChanges(deployment: Deployment, people: People, canarie
435
445
  expect(once.archive === 1 && once.rename === 1 && once.write === 2, 'the changes are not each made once, via the client and its approval', once);
436
446
  const decisions = entries.filter((entry) => entry.action === 'mcp.approve').map((entry) => `${entry.decision} ${entry.reason ?? ''}`.trim()).sort();
437
447
  expect(JSON.stringify(decisions) === JSON.stringify(['allow', 'allow', 'allow', 'allow', 'deny approved', 'deny changed']), 'the decisions, and the two refused, are not in the log', decisions);
438
- return `Browse stepped up to Write; with Write, the link without URL elicitation and an elicitation with it; nothing changed until ${changer.email} approved on coffre's page, another person and another site refused, a replayed requestState refused; each change made once, via the client and its approval; a value typed on the page only, and one coffre made reaching no one`;
448
+ return `Read stepped up to Write, saying how as its result; Write ticked beyond what was asked; with Write, the link without URL elicitation and an elicitation with it; nothing changed until ${changer.email} approved on coffre's page, another person and another site refused, a replayed requestState refused; each change made once, via the client and its approval; a value typed on the page only, and one coffre made reaching no one`;
439
449
  }
440
450
 
441
451
  /**
442
- * Values (design section 14, checks 2 and 4): Browse cannot read one, Read
443
- * values reads what the person may, a value shown on coffre's page goes to
452
+ * Values (design section 14, checks 2 and 4): Read cannot get one, Reveal
453
+ * values gets what the person may, a value shown on coffre's page goes to
444
454
  * the person and not the client, and one a client asks coffre to make
445
455
  * reaches no one.
446
456
  */
@@ -455,28 +465,28 @@ export async function mcpValues(deployment: Deployment, people: People, canaries
455
465
  };
456
466
  const dev = valuesIn(canaries, DEV);
457
467
 
458
- // Browse: no value to the model, but one shown to the person on coffre's page.
459
- const browse = (await redeem(deployment, clientId, await connect(deployment, reader, clientId))).access_token;
460
- const stepUp = await call(browse, 'read_secret_values', { path: DEV });
461
- expect(stepUp.status === 403 && stepUp.challenge.includes('scope="browse read-values"'), `read_secret_values with Browse answered ${stepUp.status}, not a step-up`, stepUp.challenge);
462
- const show = await call(browse, 'show_secret_value', { secret: `${DEV}/API_KEY` });
468
+ // Read: no value to the model, but one shown to the person on coffre's page.
469
+ const reading = (await redeem(deployment, clientId, await connect(deployment, reader, clientId))).access_token;
470
+ const stepUp = await call(reading, 'read_secret_values', { path: DEV });
471
+ expect(stepUp.status === 403 && stepUp.challenge.includes('scope="read reveal"'), `read_secret_values with Read answered ${stepUp.status}, not a step-up`, stepUp.challenge);
472
+ const show = await call(reading, 'show_secret_value', { secret: `${DEV}/API_KEY` });
463
473
  const id = show.result?.structuredContent?.approval?.id;
464
474
  expect(show.result?.structuredContent?.status === 'pending' && id !== undefined, 'show_secret_value did not open an approval', show.result);
465
475
  const page = (await reader.api.approvals.get(id!)).approval;
466
476
  expect(page.kind === 'reveal', 'the approval page does not say it shows a value', page);
467
477
  const shown = await reader.api.approvals.decide(id!, { approve: true, digest: page.digest });
468
478
  expect(shown.shown.some((line) => line.value === dev.API_KEY), 'Reveal did not show the person the value');
469
- const told = await call(browse, 'show_secret_value', { secret: `${DEV}/API_KEY` });
479
+ const told = await call(reading, 'show_secret_value', { secret: `${DEV}/API_KEY` });
470
480
  expect(told.result?.structuredContent?.status === 'approved', 'show_secret_value does not report the value as shown', told.result);
471
- const browseLeaks = Object.entries(canaries).filter(([, value]) => answers.some((answer) => answer.includes(value))).map(([path]) => path);
472
- expect(browseLeaks.length === 0, 'a Browse answer held a value', browseLeaks);
481
+ const readLeaks = Object.entries(canaries).filter(([, value]) => answers.some((answer) => answer.includes(value))).map(([path]) => path);
482
+ expect(readLeaks.length === 0, 'a Read answer held a value', readLeaks);
473
483
 
474
- // Read values: the values the person may read, and no others.
475
- const reading = (await redeem(deployment, clientId, await connect(deployment, reader, clientId, 'browse read-values'))).access_token;
476
- const read = await call(reading, 'read_secret_values', { path: DEV });
484
+ // Reveal values: the values the person may read, and no others.
485
+ const revealing = (await redeem(deployment, clientId, await connect(deployment, reader, clientId, 'read reveal'))).access_token;
486
+ const read = await call(revealing, 'read_secret_values', { path: DEV });
477
487
  expect(JSON.stringify(read.result?.structuredContent?.values) === JSON.stringify(dev), `read_secret_values on ${DEV} did not answer its values`);
478
488
  expect(read.result?.content?.[0]?.text?.startsWith('These values are now part of this conversation') === true, 'read_secret_values does not warn first', read.result?.content);
479
- const prod = await call(reading, 'read_secret_values', { path: PROD });
489
+ const prod = await call(revealing, 'read_secret_values', { path: PROD });
480
490
  expect(prod.result?.isError === true && !JSON.stringify(prod.result).includes(canaries[`${PROD}/API_KEY`]!), `the reader read ${PROD} through MCP`, prod.result);
481
- return `Browse stepped up for values and showed ${DEV}/API_KEY to ${reader.email} on coffre's page only; Read values answered ${DEV}'s values, warning first, and refused ${PROD}`;
491
+ return `Read stepped up for values and showed ${DEV}/API_KEY to ${reader.email} on coffre's page only; Reveal values answered ${DEV}'s values, warning first, and refused ${PROD}`;
482
492
  }
@@ -74,7 +74,7 @@ async function consentUrl(deployment: Deployment): Promise<string> {
74
74
  code_challenge: 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM',
75
75
  code_challenge_method: 'S256',
76
76
  state: 'pages',
77
- scope: 'browse write',
77
+ scope: 'read write',
78
78
  });
79
79
  return `${deployment.origin}/oauth/authorize?${request}`;
80
80
  }
@@ -101,7 +101,12 @@ export async function pagesInBrowser(deployment: Deployment, admin: Person, brow
101
101
  ['/service-accounts', 'Service accounts', null],
102
102
  [account, `service:${name}`, 'Sign-in'],
103
103
  [`${account}/activity`, `service:${name}`, 'Activity'],
104
+ ['/account', 'Account', 'Profile'],
105
+ ['/account/sessions', 'Account', 'Sessions'],
106
+ ['/account/apps', 'Account', 'Connected apps'],
107
+ ['/account/appearance', 'Account', 'Appearance'],
104
108
  ] as const;
109
+ const mcp = `${deployment.origin}/mcp`;
105
110
  const chrome = await Chrome.open(executable);
106
111
  try {
107
112
  for (const [path, heading, tab] of pages) {
@@ -120,6 +125,12 @@ export async function pagesInBrowser(deployment: Deployment, admin: Person, brow
120
125
  }
121
126
  if (path === '/settings') expect(loaded.cards.includes('Keys'), '/settings does not show what the keys are checked against', loaded.cards);
122
127
  if (path === person) expect(loaded.cards.includes('Connected apps'), `${path} does not show an owner the person's connected apps`, loaded.cards);
128
+ if (path === '/account/apps') {
129
+ expect(loaded.cards.join(' then ') === 'Connect an app then Connected apps', `${path} does not show Connect an app, then the connected apps`, loaded.cards);
130
+ for (const shown of [mcp, `claude mcp add --transport http coffre ${mcp}`, 'Add custom connector']) {
131
+ expect(loaded.text.includes(shown), `${path} does not show "${shown}"`, loaded.text);
132
+ }
133
+ }
123
134
  }
124
135
  // A project's tabs are routes: their links, back and forward move between them in the page.
125
136
  const project = new URL(`/projects/${PROJECT}`, deployment.origin).href;
@@ -144,13 +155,13 @@ export async function pagesInBrowser(deployment: Deployment, admin: Person, brow
144
155
  const loaded = await chrome.load(consent, admin.browser.cookies());
145
156
  expect(loaded.errors.length === 0, '/oauth/authorize reported errors in the browser', loaded.errors.join('\n'));
146
157
  expect(loaded.heading === `Connect ${CONSENT_CLIENT} to coffre?`, `/oauth/authorize shows ${JSON.stringify(loaded.heading)}`);
147
- for (const shown of ['Unverified', 'localhost', admin.email, 'Browse', 'Approve', 'Deny']) {
158
+ for (const shown of ['Unverified', 'localhost', admin.email, 'Read', 'Reveal values', 'Manage access', 'Approve', 'Deny']) {
148
159
  expect(loaded.text.includes(shown), `/oauth/authorize does not show "${shown}"`, loaded.text);
149
160
  }
150
161
  } finally {
151
162
  await chrome.close();
152
163
  }
153
- return `${pages.map(([path]) => path).join(', ')}, signed in, in Chrome: each rendered, on its tab, no error from their scripts; a project's tabs by their links, back and forward; a service account shown as service:${name}, OIDC then bearer tokens, its removal previewed; the keys' checks in Settings; its grant on dev in every project with an owner's grant button; the MCP consent page, a registered client shown as unverified`;
164
+ return `${pages.map(([path]) => path).join(', ')}, signed in, in Chrome: each rendered, on its tab, no error from their scripts; a project's tabs by their links, back and forward; a service account shown as service:${name}, OIDC then bearer tokens, its removal previewed; the keys' checks in Settings; its grant on dev in every project with an owner's grant button; the account's Connected apps tab, with this instance's MCP URL and Claude Code's command; the MCP consent page, a registered client shown as unverified`;
154
165
  }
155
166
 
156
167
  /**
package/src/suite.ts CHANGED
@@ -9,7 +9,7 @@ import { earlierCheckpoint } from './checks/checkpoints.ts';
9
9
  import { deletion } from './checks/deletion.ts';
10
10
  import { folders, forks, missingKeys, references } from './checks/environments.ts';
11
11
  import { appLogin, vaultLogin } from './checks/logins.ts';
12
- import { mcpBrowse, mcpChanges, mcpConnect, mcpValues } from './checks/mcp.ts';
12
+ import { mcpRead, mcpChanges, mcpConnect, mcpValues } from './checks/mcp.ts';
13
13
  import { accessAuthorship, memberTampering, noAuditNoAccess, sealingRace } from './checks/members.ts';
14
14
  import { refusedCheckpoint, missingCheckpoint, middleCut } from './checks/readiness.ts';
15
15
  import { editedGeneration, forgedCredential, forgedIdentity, forgedApproval } from './checks/signin.ts';
@@ -42,7 +42,7 @@ export async function conform(deployment: Deployment, options: { bulkLimit: numb
42
42
  await report.check('missing keys', { people }, ({ people }) => missingKeys(people));
43
43
  // Before offboarding: the leaver's CLI session is one of the credentials /mcp must refuse.
44
44
  await report.check('MCP connect', { people }, ({ people }) => mcpConnect(deployment, people));
45
- await report.check('MCP browse', all, ({ people, canaries }) => mcpBrowse(deployment, people, canaries));
45
+ await report.check('MCP read', all, ({ people, canaries }) => mcpRead(deployment, people, canaries));
46
46
  await report.check('MCP changes', all, ({ people, canaries }) => mcpChanges(deployment, people, canaries));
47
47
  await report.check('MCP values', all, ({ people, canaries }) => mcpValues(deployment, people, canaries));
48
48
  await report.check('reveals audited', all, ({ people, canaries }) => revealAudited(deployment, people, canaries, 'reveal'));