@williamthorsen/toolbelt.secrets 0.6.4 โ†’ 0.7.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.
@@ -1,4 +1,53 @@
1
1
  [
2
+ {
3
+ "version": "0.7.0",
4
+ "date": "2026-11-15",
5
+ "sections": [
6
+ {
7
+ "title": "๐ŸŽ‰ Features",
8
+ "audience": "all",
9
+ "items": [
10
+ {
11
+ "description": "Adds `SecretStoreError`, which `createKeychainStore` and every store method now throw when the keychain is unavailable on the platform, the `security` command cannot run, is killed, or exits non-zero, its output cannot be parsed, or a write cannot be verified or was not stored intact. (#647)",
12
+ "hash": "06a97fc63ca84b0c0068312dae677a6f405bbd05",
13
+ "entry": 1
14
+ },
15
+ {
16
+ "description": "Adds `SecretPromptError`, which `promptSecret` now throws when the two entries differ or when the input ends before a secret is entered. (#647)",
17
+ "hash": "06a97fc63ca84b0c0068312dae677a6f405bbd05",
18
+ "entry": 2
19
+ },
20
+ {
21
+ "description": "Sets the `name` of `UnstorableSecretError` to \"UnstorableSecretError\", so that a logged or serialized instance no longer identifies itself as `Error`. (#647)",
22
+ "hash": "06a97fc63ca84b0c0068312dae677a6f405bbd05",
23
+ "entry": 3
24
+ }
25
+ ]
26
+ },
27
+ {
28
+ "title": "๐Ÿงช Tests",
29
+ "audience": "dev",
30
+ "items": [
31
+ {
32
+ "description": "Adds `seedKeychainItem` to `test-utils/createTempKeychain.ts` and seeds the fixture items in `createKeychainStore.tool.test.ts` through it, which removes that test's own copies of `SECURITY_PATH` and `runSecurity`. (#643)",
33
+ "hash": "df022f7193cec3774d3a3b7563016fa8681a86c0",
34
+ "entry": 1
35
+ }
36
+ ]
37
+ },
38
+ {
39
+ "title": "๐Ÿ“š Documentation",
40
+ "audience": "dev",
41
+ "items": [
42
+ {
43
+ "description": "Adds `<!-- readme-type: library -->` to the published packages' READMEs that lacked a type marker and `<!-- readme-type: internal -->` to the `adoption` and `tools` READMEs. (#645)",
44
+ "hash": "61c75e807c79d08c13c096737ec18eb7dd365417",
45
+ "entry": 1
46
+ }
47
+ ]
48
+ }
49
+ ]
50
+ },
2
51
  {
3
52
  "version": "0.6.4",
4
53
  "date": "2026-11-15",
package/CHANGELOG.md CHANGED
@@ -2,6 +2,22 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## 0.7.0 โ€” 2026-11-15
6
+
7
+ ### ๐ŸŽ‰ Features
8
+
9
+ - Adds `SecretStoreError`, which `createKeychainStore` and every store method now throw when the keychain is unavailable on the platform, the `security` command cannot run, is killed, or exits non-zero, its output cannot be parsed, or a write cannot be verified or was not stored intact. (#647)
10
+ - Adds `SecretPromptError`, which `promptSecret` now throws when the two entries differ or when the input ends before a secret is entered. (#647)
11
+ - Sets the `name` of `UnstorableSecretError` to "UnstorableSecretError", so that a logged or serialized instance no longer identifies itself as `Error`. (#647)
12
+
13
+ ### ๐Ÿงช Tests
14
+
15
+ - Adds `seedKeychainItem` to `test-utils/createTempKeychain.ts` and seeds the fixture items in `createKeychainStore.tool.test.ts` through it, which removes that test's own copies of `SECURITY_PATH` and `runSecurity`. (#643)
16
+
17
+ ### ๐Ÿ“š Documentation
18
+
19
+ - Adds `<!-- readme-type: library -->` to the published packages' READMEs that lacked a type marker and `<!-- readme-type: internal -->` to the `adoption` and `tools` READMEs. (#645)
20
+
5
21
  ## 0.6.4 โ€” 2026-11-15
6
22
 
7
23
  ### ๐Ÿ› Bug fixes
package/README.md CHANGED
@@ -1,17 +1,17 @@
1
+ <!-- readme-type: library -->
2
+
1
3
  # @williamthorsen/toolbelt.secrets
2
4
 
3
5
  Utilities for storing and retrieving secrets in the OS credential store.
4
6
 
5
7
  <!-- section:release-notes -->
6
- ## Release notes โ€” v0.6.4 (2026-11-15)
7
-
8
- ### ๐Ÿ› Bug fixes
9
-
10
- - Fixes the issue that the store returned by `createKeychainStore` copied only the message of the error raised when `/usr/bin/security` could not be launched, and keeps that error as the `cause` of the thrown error, so that a caller can read its `code`, such as `ENOENT`. (#616)
8
+ ## Release notes โ€” v0.7.0 (2026-11-15)
11
9
 
12
- ### ๐Ÿ”’ Security
10
+ ### ๐ŸŽ‰ Features
13
11
 
14
- - Removes the password from the error that a `createKeychainStore` store's `findSecret` or `setSecret` throws when `security` prints the password as a malformed hexadecimal value or without double quotes, which exposed the secret to any log or output that recorded the error. (#615)
12
+ - Adds `SecretStoreError`, which `createKeychainStore` and every store method now throw when the keychain is unavailable on the platform, the `security` command cannot run, is killed, or exits non-zero, its output cannot be parsed, or a write cannot be verified or was not stored intact. (#647)
13
+ - Adds `SecretPromptError`, which `promptSecret` now throws when the two entries differ or when the input ends before a secret is entered. (#647)
14
+ - Sets the `name` of `UnstorableSecretError` to "UnstorableSecretError", so that a logged or serialized instance no longer identifies itself as `Error`. (#647)
15
15
  <!-- /section:release-notes -->
16
16
 
17
17
  ## Installation
@@ -69,11 +69,11 @@ store.findSecret({ account: 'me@example.com', service: 'atlassian-api-token' });
69
69
  // the token
70
70
  ```
71
71
 
72
- `findSecret` returns `undefined` when no item is stored, and throws when the keychain could not be reached, so absence is never confused with a failure. `deleteSecret` reports whether an item was there to remove.
72
+ `findSecret` returns `undefined` when no item is stored, and throws `SecretStoreError` when the keychain could not be reached or its answer could not be read, so absence is never confused with a failure. Every method throws `SecretStoreError` for such a failure, as `createKeychainStore` does off macOS. `deleteSecret` reports whether an item was there to remove.
73
73
 
74
74
  `hasSecret` reads the item's attributes rather than its data. That is the difference worth knowing: Retrieving a secret can raise a keychain access prompt when the item was created by another program, and an attribute lookup cannot.
75
75
 
76
- `setSecret` rejects an empty secret, which the keychain would store as an item indistinguishable from a stray one, and one too long for the command line that contains it. Both are `UnstorableSecretError`, which is exported: Nothing was attempted, so a caller can tell a value that the keychain cannot store from a keychain that it could not reach. Every other secret is stored and returned byte for byte, whatever it contains. Each write is read back and compared: A secret that did not survive the round trip fails at the write rather than at a later caller. Because that readback retrieves the secret, replacing an item created by another program can raise the keychain access prompt described above, and a write whose readback is refused is reported as unverified rather than as stored.
76
+ `setSecret` rejects an empty secret, which the keychain would store as an item indistinguishable from a stray one, and one too long for the command line that contains it. Both are `UnstorableSecretError`, which is exported: Nothing was attempted, so a caller can tell a value that the keychain cannot store from a keychain that it could not reach. Every other secret is stored and returned byte for byte, whatever it contains. Each write is read back and compared: A secret that did not survive the round trip fails at the write rather than at a later caller. Because that readback retrieves the secret, replacing an item created by another program can raise the keychain access prompt described above, and a write whose readback is refused is reported as unverified rather than as stored. Both a secret that did not survive and an unverified write are `SecretStoreError`.
77
77
 
78
78
  ```ts
79
79
  const projectStore = createKeychainStore({ keychain: '/Users/me/Library/Keychains/project.keychain-db' });
@@ -89,7 +89,7 @@ A named keychain accepts a write like the default search list does. `SecretStore
89
89
  promptSecret(input: NodeJS.ReadableStream, output: NodeJS.WritableStream): Promise<string>;
90
90
  ```
91
91
 
92
- Reads a secret from a terminal without echoing it, asking twice and comparing, since nothing on screen shows what was typed. It rejects when the two entries differ, and when the input ends before a secret is entered, which is the one event that `Ctrl-C`, `Ctrl-D`, and a closed stream all share.
92
+ Reads a secret from a terminal without echoing it, asking twice and comparing, since nothing on screen shows what was typed. It rejects with `SecretPromptError` when the two entries differ, and when the input ends before a secret is entered, which is the one event that `Ctrl-C`, `Ctrl-D`, and a closed stream all share.
93
93
 
94
94
  ```ts
95
95
  import { promptSecret } from '@williamthorsen/toolbelt.secrets/candidate';
@@ -0,0 +1,11 @@
1
+ /**
2
+ * A prompt that produced no secret: The two entries differed, or the input ended before a secret was entered.
3
+ * Nothing was stored when it is thrown.
4
+ *
5
+ * @category Secrets
6
+ * @experimental
7
+ * @stage candidate
8
+ */
9
+ export declare class SecretPromptError extends Error {
10
+ constructor(message: string, options?: ErrorOptions);
11
+ }
@@ -0,0 +1,6 @@
1
+ export class SecretPromptError extends Error {
2
+ constructor(message, options) {
3
+ super(message, options);
4
+ this.name = 'SecretPromptError';
5
+ }
6
+ }
@@ -0,0 +1,12 @@
1
+ /**
2
+ * A secret store that could not be reached or did not answer usably: a platform without the store, a `security`
3
+ * command that cannot run, is killed, or exits non-zero, a write that cannot be verified or did not survive intact,
4
+ * or output that cannot be parsed. An absent secret is not a failure and does not throw it.
5
+ *
6
+ * @category Secrets
7
+ * @experimental
8
+ * @stage candidate
9
+ */
10
+ export declare class SecretStoreError extends Error {
11
+ constructor(message: string, options?: ErrorOptions);
12
+ }
@@ -0,0 +1,6 @@
1
+ export class SecretStoreError extends Error {
2
+ constructor(message, options) {
3
+ super(message, options);
4
+ this.name = 'SecretStoreError';
5
+ }
6
+ }
@@ -8,4 +8,5 @@
8
8
  * @stage candidate
9
9
  */
10
10
  export declare class UnstorableSecretError extends Error {
11
+ constructor(message: string, options?: ErrorOptions);
11
12
  }
@@ -1,2 +1,6 @@
1
1
  export class UnstorableSecretError extends Error {
2
+ constructor(message, options) {
3
+ super(message, options);
4
+ this.name = 'UnstorableSecretError';
5
+ }
2
6
  }
@@ -1,7 +1,8 @@
1
1
  import type { WritableSecretStore } from './SecretStore.js';
2
2
  /**
3
- * Opens a macOS keychain as a secret store, or the default search list when no keychain is named. Throws off
4
- * macOS.
3
+ * Opens a macOS keychain as a secret store, or the default search list when no keychain is named. Throws
4
+ * `SecretStoreError` off macOS. The store's methods throw `SecretStoreError` when the keychain cannot be reached or
5
+ * answers unusably, and `setSecret` throws `UnstorableSecretError` for a value that it cannot pass to `security`.
5
6
  *
6
7
  * @category Secrets
7
8
  * @experimental
@@ -1,4 +1,6 @@
1
1
  export { createKeychainStore, type KeychainStoreOptions } from './createKeychainStore.js';
2
2
  export { promptSecret } from './promptSecret.js';
3
+ export { SecretPromptError } from './SecretPromptError.js';
3
4
  export type { SecretQuery, SecretStore, WritableSecretStore } from './SecretStore.js';
5
+ export { SecretStoreError } from './SecretStoreError.js';
4
6
  export { UnstorableSecretError } from './UnstorableSecretError.js';
@@ -1,3 +1,5 @@
1
1
  export { createKeychainStore } from "./createKeychainStore.js";
2
2
  export { promptSecret } from "./promptSecret.js";
3
+ export { SecretPromptError } from "./SecretPromptError.js";
4
+ export { SecretStoreError } from "./SecretStoreError.js";
3
5
  export { UnstorableSecretError } from "./UnstorableSecretError.js";
@@ -1,7 +1,8 @@
1
1
  /**
2
2
  * Reads a secret from a terminal without echoing it, asking twice and comparing, since nothing on screen shows
3
3
  * what was typed. `security` has a prompt of its own, but it fills a 128-byte buffer and returns nothing to
4
- * verify, so the secret is read here instead.
4
+ * verify, so the secret is read here instead. Rejects with `SecretPromptError` when the entries differ or the
5
+ * input ends before a secret is entered.
5
6
  *
6
7
  * @category Secrets
7
8
  * @experimental
@@ -1,5 +1,6 @@
1
1
  import readline from 'node:readline/promises';
2
2
  import { Writable } from 'node:stream';
3
+ import { SecretPromptError } from "./SecretPromptError.js";
3
4
  const CONFIRM_PROMPT = 'Retype secret: ';
4
5
  const SECRET_PROMPT = 'Secret: ';
5
6
  export async function promptSecret(input, output) {
@@ -10,7 +11,7 @@ export async function promptSecret(input, output) {
10
11
  const secret = await ask(reader, output, abandoned.signal, SECRET_PROMPT);
11
12
  const confirmation = await ask(reader, output, abandoned.signal, CONFIRM_PROMPT);
12
13
  if (secret !== confirmation)
13
- throw new Error('The two entries differ. Nothing was stored.');
14
+ throw new SecretPromptError('The two entries differ. Nothing was stored.');
14
15
  return secret;
15
16
  }
16
17
  finally {
@@ -26,7 +27,9 @@ async function ask(reader, output, signal, prompt) {
26
27
  }
27
28
  catch (error) {
28
29
  output.write('\n');
29
- throw signal.aborted ? new Error('The prompt ended before a secret was entered. Nothing was stored.') : error;
30
+ throw signal.aborted
31
+ ? new SecretPromptError('The prompt ended before a secret was entered. Nothing was stored.')
32
+ : error;
30
33
  }
31
34
  }
32
35
  function createSink() {
@@ -1,6 +1,7 @@
1
+ import { SecretStoreError } from "../3-candidate/SecretStoreError.js";
1
2
  const MACOS = 'darwin';
2
3
  export function assertMacosPlatform(platform = process.platform) {
3
4
  if (platform === MACOS)
4
5
  return;
5
- throw new Error(`A keychain store needs macOS, which supplies /usr/bin/security. This platform is ${platform}.`);
6
+ throw new SecretStoreError(`A keychain store needs macOS, which supplies /usr/bin/security. This platform is ${platform}.`);
6
7
  }
@@ -1,4 +1,5 @@
1
1
  import { describeError } from '@williamthorsen/toolbelt.errors';
2
+ import { SecretStoreError } from "../3-candidate/SecretStoreError.js";
2
3
  import { assertStorableSecret } from "./assertStorableSecret.js";
3
4
  import { parseSecurityPassword } from "./parseSecurityPassword.js";
4
5
  import { buildDeleteArgs, buildFindArgs, buildHasArgs, composeSetLine } from "./securityCommands.js";
@@ -18,7 +19,9 @@ export function buildKeychainStore(run, keychain) {
18
19
  }
19
20
  catch (error) {
20
21
  const detail = describeError(error);
21
- throw new Error(`The secret was written but could not be read back to verify it. ${detail}`, { cause: error });
22
+ throw new SecretStoreError(`The secret was written but could not be read back to verify it. ${detail}`, {
23
+ cause: error,
24
+ });
22
25
  }
23
26
  }
24
27
  return {
@@ -49,11 +52,11 @@ function assertStoredIntact(stored, secret) {
49
52
  if (stored === secret)
50
53
  return;
51
54
  const found = stored === undefined ? 'nothing was stored' : `${stored.length} characters came back`;
52
- throw new Error(`The secret was written but not stored intact: ${secret.length} characters went in and ${found}.`);
55
+ throw new SecretStoreError(`The secret was written but not stored intact: ${secret.length} characters went in and ${found}.`);
53
56
  }
54
57
  function assertSucceeded(result, action) {
55
58
  if (result.exitCode === 0)
56
59
  return;
57
60
  const detail = result.stderr.trim();
58
- throw new Error(`Could not ${action}. \`security\` exited ${result.exitCode}${detail === '' ? '' : `: ${detail}`}`);
61
+ throw new SecretStoreError(`Could not ${action}. \`security\` exited ${result.exitCode}${detail === '' ? '' : `: ${detail}`}`);
59
62
  }
@@ -1,11 +1,14 @@
1
+ import { describeError } from '@williamthorsen/toolbelt.errors';
2
+ import { SecretStoreError } from "../3-candidate/SecretStoreError.js";
1
3
  const HEX_FORM_PATTERN = /^0x(?<hex>(?:[\dA-Fa-f]{2})+)(?:\s|$)/;
2
4
  const PASSWORD_LINE_PATTERN = /^password: ?(?<value>.*)$/m;
3
5
  const HEX_PREFIX = '0x';
4
6
  const QUOTE = '"';
5
7
  export function parseSecurityPassword(stderr) {
6
8
  const value = PASSWORD_LINE_PATTERN.exec(stderr)?.groups?.['value'];
7
- if (value === undefined)
8
- throw new Error(`No password line in the output of \`security\`: ${summarize(stderr)}`);
9
+ if (value === undefined) {
10
+ throw new SecretStoreError(`No password line in the output of \`security\`: ${summarize(stderr)}`);
11
+ }
9
12
  if (value.startsWith(HEX_PREFIX))
10
13
  return decodeHexForm(value);
11
14
  if (value === '')
@@ -15,14 +18,21 @@ export function parseSecurityPassword(stderr) {
15
18
  function decodeHexForm(value) {
16
19
  const hex = HEX_FORM_PATTERN.exec(value)?.groups?.['hex'];
17
20
  if (hex === undefined) {
18
- throw new Error(`Malformed hexadecimal password in the output of \`security\`: a value of ${value.length} characters that does not continue 0x with pairs of hex digits`);
21
+ throw new SecretStoreError(`Malformed hexadecimal password in the output of \`security\`: a value of ${value.length} characters that does not continue 0x with pairs of hex digits`);
22
+ }
23
+ try {
24
+ return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.from(hex, 'hex'));
25
+ }
26
+ catch (error) {
27
+ throw new SecretStoreError(`Undecodable password in the output of \`security\`: ${describeError(error)}`, {
28
+ cause: error,
29
+ });
19
30
  }
20
- return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.from(hex, 'hex'));
21
31
  }
22
32
  function readQuotedForm(value) {
23
33
  const end = value.lastIndexOf(QUOTE);
24
34
  if (!value.startsWith(QUOTE) || end === 0) {
25
- throw new Error(`Unquoted password in the output of \`security\`: a value of ${value.length} characters that is not enclosed in double quotes`);
35
+ throw new SecretStoreError(`Unquoted password in the output of \`security\`: a value of ${value.length} characters that is not enclosed in double quotes`);
26
36
  }
27
37
  return value.slice(QUOTE.length, end);
28
38
  }
@@ -1,5 +1,6 @@
1
1
  import { spawnSync } from 'node:child_process';
2
- import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
2
+ import { describeError } from '@williamthorsen/toolbelt.errors';
3
+ import { SecretStoreError } from "../3-candidate/SecretStoreError.js";
3
4
  const SECURITY_PATH = '/usr/bin/security';
4
5
  const TIMEOUT_MS = 30_000;
5
6
  export function runSecurity(args, input) {
@@ -8,10 +9,11 @@ export function runSecurity(args, input) {
8
9
  input,
9
10
  timeout: TIMEOUT_MS,
10
11
  });
11
- if (error !== undefined)
12
- throw chainError(`Could not run ${SECURITY_PATH}`, error);
12
+ if (error !== undefined) {
13
+ throw new SecretStoreError(`Could not run ${SECURITY_PATH}: ${describeError(error)}`, { cause: error });
14
+ }
13
15
  if (status === null) {
14
- throw new Error(`${SECURITY_PATH} was killed before it exited. It may have been waiting on a prompt.`);
16
+ throw new SecretStoreError(`${SECURITY_PATH} was killed before it exited. It may have been waiting on a prompt.`);
15
17
  }
16
18
  return { exitCode: status, stderr, stdout };
17
19
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@williamthorsen/toolbelt.secrets",
3
- "version": "0.6.4",
3
+ "version": "0.7.0",
4
4
  "description": "Utilities for storing and retrieving secrets in the OS credential store",
5
5
  "keywords": [
6
6
  "credentials",