@coffre/core 0.4.1 → 0.4.3

package/dist/dotenv.d.ts

@@ -17,9 +17,14 @@ export type ParsedEntry = {
   value: string;
   line: number;
 };
+/**
+ * A line that could not be parsed: its number, why, and its key when it has
+ * a valid one. Never the line's text: a line without its "=", or with a key
+ * that is not one, may be a secret pasted on its own, `c2stbGl2ZS0xMjM0NQ==`.
+ */
 export type ParseProblem = {
   line: number;
-  text: string;
+  key?: string;
   reason: string;
 };
 export type ParseResult = {

package/dist/dotenv.js

@@ -1,4 +1,9 @@
 //#region src/dotenv.ts
+/**
+* A secret's key, as the API's `secretKey` (`schemas.ts`) has it: a plain
+* pattern, so that the browser's import does not carry zod. The tests hold
+* the two in agreement.
+*/
 const KEY_RE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
 function parseDotenv(input) {
 	const entries = [];
@@ -14,7 +19,6 @@ function parseDotenv(input) {
 		if (equals === -1) {
 			problems.push({
 				line: lineNumber,
-				text: trimmed,
 				reason: "no \"=\" on this line"
 			});
 			continue;
@@ -23,7 +27,6 @@ function parseDotenv(input) {
 		if (!KEY_RE.test(key)) {
 			problems.push({
 				line: lineNumber,
-				text: key,
 				reason: "key must match ^[A-Za-z_][A-Za-z0-9_]*$"
 			});
 			continue;
@@ -35,7 +38,7 @@ function parseDotenv(input) {
 			if (closing === -1) {
 				problems.push({
 					line: lineNumber,
-					text: key,
+					key,
 					reason: "unterminated double quote (multi-line values are not supported)"
 				});
 				continue;
@@ -44,7 +47,7 @@ function parseDotenv(input) {
 			if (trailingIsSignificant(rest.slice(closing + 1))) {
 				problems.push({
 					line: lineNumber,
-					text: key,
+					key,
 					reason: "unexpected text after the closing quote"
 				});
 				continue;
@@ -54,7 +57,7 @@ function parseDotenv(input) {
 			if (closing === -1) {
 				problems.push({
 					line: lineNumber,
-					text: key,
+					key,
 					reason: "unterminated single quote (multi-line values are not supported)"
 				});
 				continue;
@@ -63,20 +66,34 @@ function parseDotenv(input) {
 			if (trailingIsSignificant(rest.slice(closing + 1))) {
 				problems.push({
 					line: lineNumber,
-					text: key,
+					key,
 					reason: "unexpected text after the closing quote"
 				});
 				continue;
 			}
 		} else {
-			const comment = rest.indexOf(" #");
-			if (comment !== -1) rest = rest.slice(0, comment);
-			value = rest.trim();
+			const text = withoutExport.slice(equals + 1);
+			const comment = text.search(/\s#/);
+			value = (comment === -1 ? text : text.slice(0, comment)).trim();
+			if (/^=+$/.test(value)) {
+				problems.push({
+					line: lineNumber,
+					reason: "a value pasted on its own, not KEY=value: only \"=\" follows what would be its key"
+				});
+				continue;
+			}
+			if (value === "") {
+				problems.push({
+					line: lineNumber,
+					reason: "no value: write KEY=\"\" for an empty one"
+				});
+				continue;
+			}
 		}
 		if (value.includes("\0")) {
 			problems.push({
 				line: lineNumber,
-				text: key,
+				key,
 				reason: "value contains a NUL byte, which cannot be passed in an environment"
 			});
 			continue;
@@ -84,7 +101,7 @@ function parseDotenv(input) {
 		if (seen.has(key)) {
 			problems.push({
 				line: lineNumber,
-				text: key,
+				key,
 				reason: "duplicate key in this file"
 			});
 			continue;
@@ -167,7 +184,7 @@ function assertEnvironmentEntry(key, value) {
 	if (value.includes("\0")) throw new Error(`${key} contains a NUL byte`);
 }
 function quoteDotenv(value) {
-	if (PLAIN_VALUE.test(value)) return value;
+	if (PLAIN_VALUE.test(value) && !/^=*$/.test(value)) return value;
 	if (!/['\n\r]/.test(value)) return `'${value}'`;
 	return `"${value.replace(/[\\"\n\r]/g, (character) => {
 		switch (character) {

package/dist/mcp.d.ts

@@ -5,8 +5,8 @@
  * 4 and 5). Plain functions over strings, for the server and the consent
  * page alike.
  */
-/** In the order the consent page lists them; `browse` is always granted. */
-export declare const MCP_SCOPES: readonly ["browse", "write", "read-values", "manage-access"];
+/** In the order the consent page lists them; `read` is always granted. */
+export declare const MCP_SCOPES: readonly ["read", "write", "reveal", "manage-access"];
 export type McpScope = (typeof MCP_SCOPES)[number];
 export declare const MCP_SCOPE_INFO: Record<McpScope, {
   label: string;
@@ -15,7 +15,7 @@ export declare const MCP_SCOPE_INFO: Record<McpScope, {
 export declare function isMcpScope(value: string): value is McpScope;
 /**
  * The scopes a space-separated `scope` asks for, in catalogue order, with
- * `browse` always among them; and the ones coffre does not know, which the
+ * `read` always among them; and the ones coffre does not know, which the
  * caller refuses as `invalid_scope`.
  */
 export declare function parseScopes(value: string | null | undefined): {
@@ -24,8 +24,13 @@ export declare function parseScopes(value: string | null | undefined): {
 };
 /** Scopes as one string, in catalogue order: how a connection stores them and a token answer says them. */
 export declare function scopeString(scopes: Iterable<McpScope>): string;
-/** A person's choice at consent: what was asked, minus what they unticked, and never without `browse`. */
-export declare function grantedScopes(asked: readonly McpScope[], chosen: readonly string[]): McpScope[];
+/**
+ * A person's choice at consent: what they ticked, whatever the client asked
+ * for, and never without `read`. What a client asks for only decides what
+ * starts ticked: clients ask for what the resource metadata names, `read`,
+ * and not every one asks for more later (docs/design/mcp.md, section 5).
+ */
+export declare function grantedScopes(chosen: readonly string[]): McpScope[];
 /**
  * Whether a connection granted `granted` supersedes an earlier one of the
  * same client that holds `held`: it grants all of that and more, as a

package/dist/mcp.js

@@ -5,24 +5,24 @@
 * 4 and 5). Plain functions over strings, for the server and the consent
 * page alike.
 */
-/** In the order the consent page lists them; `browse` is always granted. */
+/** In the order the consent page lists them; `read` is always granted. */
 const MCP_SCOPES = [
-	"browse",
+	"read",
 	"write",
-	"read-values",
+	"reveal",
 	"manage-access"
 ];
 const MCP_SCOPE_INFO = {
-	browse: {
-		label: "Browse",
+	read: {
+		label: "Read",
 		description: "Projects, environments, key names, history, access and the audit log. Never a value."
 	},
 	write: {
 		label: "Write",
 		description: "Set, generate, rename, archive and restore secrets; create projects and environments. Each change waits for your approval on coffre."
 	},
-	"read-values": {
-		label: "Read values",
+	reveal: {
+		label: "Reveal values",
 		description: "Secret values, sent to the app. They become part of its conversation, wherever it keeps it."
 	},
 	"manage-access": {
@@ -37,14 +37,14 @@ function isMcpScope(value) {
 }
 /**
 * The scopes a space-separated `scope` asks for, in catalogue order, with
-* `browse` always among them; and the ones coffre does not know, which the
+* `read` always among them; and the ones coffre does not know, which the
 * caller refuses as `invalid_scope`.
 */
 function parseScopes(value) {
 	const asked = new Set((value ?? "").split(" ").filter((scope) => scope !== "" && !IGNORED_SCOPES.has(scope)));
 	const unknown = [...asked].filter((scope) => !isMcpScope(scope));
 	return {
-		scopes: MCP_SCOPES.filter((scope) => scope === "browse" || asked.has(scope)),
+		scopes: MCP_SCOPES.filter((scope) => scope === "read" || asked.has(scope)),
 		unknown
 	};
 }
@@ -53,10 +53,15 @@ function scopeString(scopes) {
 	const held = new Set(scopes);
 	return MCP_SCOPES.filter((scope) => held.has(scope)).join(" ");
 }
-/** A person's choice at consent: what was asked, minus what they unticked, and never without `browse`. */
-function grantedScopes(asked, chosen) {
+/**
+* A person's choice at consent: what they ticked, whatever the client asked
+* for, and never without `read`. What a client asks for only decides what
+* starts ticked: clients ask for what the resource metadata names, `read`,
+* and not every one asks for more later (docs/design/mcp.md, section 5).
+*/
+function grantedScopes(chosen) {
 	const picked = new Set(chosen);
-	return MCP_SCOPES.filter((scope) => scope === "browse" || asked.includes(scope) && picked.has(scope));
+	return MCP_SCOPES.filter((scope) => scope === "read" || picked.has(scope));
 }
 /**
 * Whether a connection granted `granted` supersedes an earlier one of the

package/dist/schemas.d.ts

@@ -29,8 +29,8 @@ export declare const principalType: z.ZodEnum<{
 }>;
 export declare const principalId: z.ZodString;
 export declare const instanceRole: z.ZodEnum<{
-  user: "user";
   owner: "owner";
+  user: "user";
 }>;
 export declare const grantId: z.ZodString;
 export declare const emailAddress: z.ZodString;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/core",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "What coffre's packages share: roles, envelopes, identity, the audit chain and the vault's contract.",
   "license": "MIT",
   "repository": {
@@ -84,7 +84,7 @@
     "@types/node": "26.1.1",
     "tsdown": "0.23.0",
     "typescript": "5.9.3",
-    "@coffre/conformance": "0.4.1"
+    "@coffre/conformance": "0.4.3"
   },
   "scripts": {
     "build": "tsdown",

package/src/dotenv.ts

@@ -13,13 +13,23 @@
  */
 
 export type ParsedEntry = { key: string; value: string; line: number };
-export type ParseProblem = { line: number; text: string; reason: string };
+/**
+ * A line that could not be parsed: its number, why, and its key when it has
+ * a valid one. Never the line's text: a line without its "=", or with a key
+ * that is not one, may be a secret pasted on its own, `c2stbGl2ZS0xMjM0NQ==`.
+ */
+export type ParseProblem = { line: number; key?: string; reason: string };
 
 export type ParseResult = {
   entries: ParsedEntry[];
   problems: ParseProblem[];
 };
 
+/**
+ * A secret's key, as the API's `secretKey` (`schemas.ts`) has it: a plain
+ * pattern, so that the browser's import does not carry zod. The tests hold
+ * the two in agreement.
+ */
 const KEY_RE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
 
 export function parseDotenv(input: string): ParseResult {
@@ -45,17 +55,13 @@ export function parseDotenv(input: string): ParseResult {
 
     const equals = withoutExport.indexOf('=');
     if (equals === -1) {
-      problems.push({ line: lineNumber, text: trimmed, reason: 'no "=" on this line' });
+      problems.push({ line: lineNumber, reason: 'no "=" on this line' });
       continue;
     }
 
     const key = withoutExport.slice(0, equals).trim();
     if (!KEY_RE.test(key)) {
-      problems.push({
-        line: lineNumber,
-        text: key,
-        reason: 'key must match ^[A-Za-z_][A-Za-z0-9_]*$',
-      });
+      problems.push({ line: lineNumber, reason: 'key must match ^[A-Za-z_][A-Za-z0-9_]*$' });
       continue;
     }
 
@@ -67,7 +73,7 @@ export function parseDotenv(input: string): ParseResult {
       if (closing === -1) {
         problems.push({
           line: lineNumber,
-          text: key,
+          key,
           reason: 'unterminated double quote (multi-line values are not supported)',
         });
         continue;
@@ -79,7 +85,7 @@ export function parseDotenv(input: string): ParseResult {
       if (trailingIsSignificant(rest.slice(closing + 1))) {
         problems.push({
           line: lineNumber,
-          text: key,
+          key,
           reason: 'unexpected text after the closing quote',
         });
         continue;
@@ -89,7 +95,7 @@ export function parseDotenv(input: string): ParseResult {
       if (closing === -1) {
         problems.push({
           line: lineNumber,
-          text: key,
+          key,
           reason: 'unterminated single quote (multi-line values are not supported)',
         });
         continue;
@@ -99,16 +105,28 @@ export function parseDotenv(input: string): ParseResult {
       if (trailingIsSignificant(rest.slice(closing + 1))) {
         problems.push({
           line: lineNumber,
-          text: key,
+          key,
           reason: 'unexpected text after the closing quote',
         });
         continue;
       }
     } else {
-      // Unquoted: strip a trailing comment, then trailing whitespace.
-      const comment = rest.indexOf(' #');
-      if (comment !== -1) rest = rest.slice(0, comment);
-      value = rest.trim();
+      // Unquoted: a "#" after whitespace starts a comment, found before trimming, as dotenv does:
+      // `KEY= # later` has no value, `KEY=a #b` is `a`; `KEY=#fff` and `KEY=a#b` keep theirs.
+      const text = withoutExport.slice(equals + 1);
+      const comment = text.search(/\s#/);
+      value = (comment === -1 ? text : text.slice(0, comment)).trim();
+      // A secret pasted on its own line, its base64 padding taken for the "=": `c2stbGl2ZS0xMjM0NTY3OA==`
+      // leaves "=" after it, `c2stbGl2ZS0xMjM0NTY3ODk=` nothing. Its text would be the key: never named.
+      // An empty value is meant only quoted, `KEY=""`; unquoted, it can't be told from that padding.
+      if (/^=+$/.test(value)) {
+        problems.push({ line: lineNumber, reason: 'a value pasted on its own, not KEY=value: only "=" follows what would be its key' });
+        continue;
+      }
+      if (value === '') {
+        problems.push({ line: lineNumber, reason: 'no value: write KEY="" for an empty one' });
+        continue;
+      }
     }
 
     // A NUL byte cannot survive being put in a process environment: execve
@@ -118,14 +136,14 @@ export function parseDotenv(input: string): ParseResult {
     if (value.includes('\u0000')) {
       problems.push({
         line: lineNumber,
-        text: key,
+        key,
         reason: 'value contains a NUL byte, which cannot be passed in an environment',
       });
       continue;
     }
 
     if (seen.has(key)) {
-      problems.push({ line: lineNumber, text: key, reason: 'duplicate key in this file' });
+      problems.push({ line: lineNumber, key, reason: 'duplicate key in this file' });
       continue;
     }
     seen.add(key);
@@ -212,7 +230,8 @@ export function assertEnvironmentEntry(key: string, value: string): void {
 }
 
 function quoteDotenv(value: string): string {
-  if (PLAIN_VALUE.test(value)) return value;
+  // Empty, or only "=", a value is quoted: unquoted, the parser refuses it as a pasted secret's padding.
+  if (PLAIN_VALUE.test(value) && !/^=*$/.test(value)) return value;
   if (!/['\n\r]/.test(value)) return `'${value}'`;
   const escaped = value.replace(/[\\"\n\r]/g, (character) => {
     switch (character) {

package/src/mcp.ts

@@ -5,22 +5,22 @@
  * page alike.
  */
 
-/** In the order the consent page lists them; `browse` is always granted. */
-export const MCP_SCOPES = ['browse', 'write', 'read-values', 'manage-access'] as const;
+/** In the order the consent page lists them; `read` is always granted. */
+export const MCP_SCOPES = ['read', 'write', 'reveal', 'manage-access'] as const;
 
 export type McpScope = (typeof MCP_SCOPES)[number];
 
 export const MCP_SCOPE_INFO: Record<McpScope, { label: string; description: string }> = {
-  browse: {
-    label: 'Browse',
+  read: {
+    label: 'Read',
     description: 'Projects, environments, key names, history, access and the audit log. Never a value.',
   },
   write: {
     label: 'Write',
     description: 'Set, generate, rename, archive and restore secrets; create projects and environments. Each change waits for your approval on coffre.',
   },
-  'read-values': {
-    label: 'Read values',
+  reveal: {
+    label: 'Reveal values',
     description: 'Secret values, sent to the app. They become part of its conversation, wherever it keeps it.',
   },
   'manage-access': {
@@ -38,13 +38,13 @@ export function isMcpScope(value: string): value is McpScope {
 
 /**
  * The scopes a space-separated `scope` asks for, in catalogue order, with
- * `browse` always among them; and the ones coffre does not know, which the
+ * `read` always among them; and the ones coffre does not know, which the
  * caller refuses as `invalid_scope`.
  */
 export function parseScopes(value: string | null | undefined): { scopes: McpScope[]; unknown: string[] } {
   const asked = new Set((value ?? '').split(' ').filter((scope) => scope !== '' && !IGNORED_SCOPES.has(scope)));
   const unknown = [...asked].filter((scope) => !isMcpScope(scope));
-  return { scopes: MCP_SCOPES.filter((scope) => scope === 'browse' || asked.has(scope)), unknown };
+  return { scopes: MCP_SCOPES.filter((scope) => scope === 'read' || asked.has(scope)), unknown };
 }
 
 /** Scopes as one string, in catalogue order: how a connection stores them and a token answer says them. */
@@ -53,10 +53,15 @@ export function scopeString(scopes: Iterable<McpScope>): string {
   return MCP_SCOPES.filter((scope) => held.has(scope)).join(' ');
 }
 
-/** A person's choice at consent: what was asked, minus what they unticked, and never without `browse`. */
-export function grantedScopes(asked: readonly McpScope[], chosen: readonly string[]): McpScope[] {
+/**
+ * A person's choice at consent: what they ticked, whatever the client asked
+ * for, and never without `read`. What a client asks for only decides what
+ * starts ticked: clients ask for what the resource metadata names, `read`,
+ * and not every one asks for more later (docs/design/mcp.md, section 5).
+ */
+export function grantedScopes(chosen: readonly string[]): McpScope[] {
   const picked = new Set(chosen);
-  return MCP_SCOPES.filter((scope) => scope === 'browse' || (asked.includes(scope) && picked.has(scope)));
+  return MCP_SCOPES.filter((scope) => scope === 'read' || picked.has(scope));
 }
 
 /**