@williamthorsen/toolbelt.secrets 0.2.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +35 -9
- package/README.md +11 -43
- package/bin/tb-secret.js +1 -1
- package/dist/esm/3-candidate/UnstorableSecretError.d.ts +1 -1
- package/dist/esm/bin/runTbSecret.d.ts +1 -1
- package/dist/esm/internal/assertStorableSecret.d.ts +1 -1
- package/dist/esm/internal/securityCommands.d.ts +2 -3
- package/dist/esm/internal/securityCommands.js +1 -1
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -2,9 +2,35 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
|
|
5
|
+
## 0.3.0 — 2026-09-15
|
|
6
|
+
|
|
7
|
+
### 🎉 Features
|
|
8
|
+
|
|
9
|
+
- 🚨 **Breaking:** Move createTempTree from toolbelt.filesystem to toolbelt.testing (#313)
|
|
10
|
+
|
|
11
|
+
- Moves `CreateTempTreeOptions` and the `TempTree` handle to `@williamthorsen/toolbelt.testing/candidate` along with `createTempTree`.
|
|
12
|
+
|
|
13
|
+
Migration: Import `createTempTree`, `CreateTempTreeOptions`, and `TempTree` from `@williamthorsen/toolbelt.testing/candidate`, and declare `@williamthorsen/toolbelt.testing` in the manifest that declared `@williamthorsen/toolbelt.filesystem` for them.
|
|
14
|
+
|
|
15
|
+
### ⚙️ Tooling
|
|
16
|
+
|
|
17
|
+
- Remove the stale repo-local cliff.toml and normalize changelog titles (#327)
|
|
18
|
+
|
|
19
|
+
- Stops `release-kit prepare` from printing a "skipped due to grouping error(s)" warning for each releasable workspace by letting it resolve the git-cliff template bundled with release-kit, previously overridden by the root `cliff.toml`.
|
|
20
|
+
- Excludes commits without a ticket prefix from future changelog entries.
|
|
21
|
+
- Renames the section titles in every `packages/*/.meta/changelog.json`, except `Dependency updates`, to the headings of release-kit's work-type taxonomy, such as "🎉 Features" and "🏗️ Internal features", and regenerates each `CHANGELOG.md` so that release-kit orders existing and new sections by the same rule.
|
|
22
|
+
- Causes the next `release-kit prepare` to plan patch releases of `dstructs`, `hof`, and `sets`, which had no other commits since their last release, because the changelog commit touches every workspace.
|
|
23
|
+
|
|
24
|
+
### 📚 Documentation
|
|
25
|
+
|
|
26
|
+
- Align prose with plain-speech doctrine and writing conventions (#306)
|
|
27
|
+
|
|
28
|
+
- Copy-edits prose across the repo: comments, test names, package READMEs, and `AGENTS.md`.
|
|
29
|
+
- Rewrites a few user-facing strings as well, among them `configure-project`'s help text and the errors from `parseProjectSpec`, `securityCommands`, and `hashString`.
|
|
30
|
+
|
|
5
31
|
## 0.2.0 — 2026-09-06
|
|
6
32
|
|
|
7
|
-
### Features
|
|
33
|
+
### 🎉 Features
|
|
8
34
|
|
|
9
35
|
- Add createKeychainStore and tb-secret to toolbelt.secrets (#276)
|
|
10
36
|
|
|
@@ -19,7 +45,7 @@ All notable changes to this project will be documented in this file.
|
|
|
19
45
|
- Adds `resolveJiraSite`, `findJiraTokenSource`, and `JiraTransportError` to `@williamthorsen/toolbelt.atlassian/candidate`, so library code can resolve the site, name which link of the token chain would answer without reading the token, and tell a request that Jira rejected from one that never reached Jira.
|
|
20
46
|
- Adds `promptSecret` and `UnstorableSecretError` to `@williamthorsen/toolbelt.secrets/candidate`, so a caller outside that package can prompt for a secret without echoing it and can tell a token refused by the keychain from a keychain that could not be reached.
|
|
21
47
|
|
|
22
|
-
### Bug fixes
|
|
48
|
+
### 🐛 Bug fixes
|
|
23
49
|
|
|
24
50
|
- Stop truncating a secret longer than 128 characters (#278)
|
|
25
51
|
|
|
@@ -38,7 +64,13 @@ All notable changes to this project will be documented in this file.
|
|
|
38
64
|
- Fixes an issue where `tb-secret set` and `tb-jira auth set` failed with `EAGAIN: resource temporarily unavailable` when the producer of a piped credential delayed its first byte, as `tb-secret get`, `op read`, and `gh auth token` all do.
|
|
39
65
|
- Stops `tb-secret`, `tb-jira`, and `tb-git` from crashing with an unhandled `EPIPE` when the reader on their stdout or stderr exits first, so that `tb-secret get | head -1` ends quietly, as a program that ignores `SIGPIPE` does.
|
|
40
66
|
|
|
41
|
-
###
|
|
67
|
+
### 🏗️ Internal features
|
|
68
|
+
|
|
69
|
+
- Scaffold toolbelt.secrets for credential storage (#275)
|
|
70
|
+
|
|
71
|
+
Scaffolds `packages/secrets`, an empty workspace for storing and retrieving secrets in the OS credential store, publishing to npm as `@williamthorsen/toolbelt.secrets`.
|
|
72
|
+
|
|
73
|
+
### 📚 Documentation
|
|
42
74
|
|
|
43
75
|
- Repair the repository's prose and record every rejection's ground (#290)
|
|
44
76
|
|
|
@@ -48,10 +80,4 @@ All notable changes to this project will be documented in this file.
|
|
|
48
80
|
|
|
49
81
|
- Revises documentation and comments to align with plain-speech doctrine and writing conventions.
|
|
50
82
|
|
|
51
|
-
### Internal
|
|
52
|
-
|
|
53
|
-
- Scaffold toolbelt.secrets for credential storage (#275)
|
|
54
|
-
|
|
55
|
-
Scaffolds `packages/secrets`, an empty workspace for storing and retrieving secrets in the OS credential store, publishing to npm as `@williamthorsen/toolbelt.secrets`.
|
|
56
|
-
|
|
57
83
|
<!-- Generated by release-kit. Do not edit this file. Use .meta/changelog-overrides.json to override entries. -->
|
package/README.md
CHANGED
|
@@ -3,47 +3,15 @@
|
|
|
3
3
|
Utilities for storing and retrieving secrets in the OS credential store.
|
|
4
4
|
|
|
5
5
|
<!-- section:release-notes -->
|
|
6
|
-
## Release notes — v0.
|
|
6
|
+
## Release notes — v0.3.0 (2026-09-15)
|
|
7
7
|
|
|
8
|
-
### Features
|
|
8
|
+
### 🎉 Features
|
|
9
9
|
|
|
10
|
-
-
|
|
10
|
+
- 🚨 **Breaking:** Move createTempTree from toolbelt.filesystem to toolbelt.testing (#313)
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
Supports macOS only.
|
|
12
|
+
- Moves `CreateTempTreeOptions` and the `TempTree` handle to `@williamthorsen/toolbelt.testing/candidate` along with `createTempTree`.
|
|
15
13
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
- Adds the `tb-jira` binary to `@williamthorsen/toolbelt.atlassian`: Its `configure-project` subcommand reconciles a Jira project's statuses, workflow transitions, and board features against a spec file owned by the consuming repo, and `--dry-run` prints the plan and writes nothing.
|
|
19
|
-
- Adds a `tb-jira auth` subcommand, which stores, replaces, and removes the Jira API token in the keychain and reports which source would supply it without printing the token.
|
|
20
|
-
- Adds `resolveJiraSite`, `findJiraTokenSource`, and `JiraTransportError` to `@williamthorsen/toolbelt.atlassian/candidate`, so library code can resolve the site, name which link of the token chain would answer without reading the token, and tell a request that Jira rejected from one that never reached Jira.
|
|
21
|
-
- Adds `promptSecret` and `UnstorableSecretError` to `@williamthorsen/toolbelt.secrets/candidate`, so a caller outside that package can prompt for a secret without echoing it and can tell a token refused by the keychain from a keychain that could not be reached.
|
|
22
|
-
|
|
23
|
-
### Bug fixes
|
|
24
|
-
|
|
25
|
-
- Stop truncating a secret longer than 128 characters (#278)
|
|
26
|
-
|
|
27
|
-
Fixes an issue where `tb-secret set` and `setSecret` stored the first 128 bytes of a longer secret and reported success, so an API token of ordinary length was silently corrupted. Secrets of up to ~2,000 bytes can now be stored; an empty secret or a secret that exceeds the limit is refused.
|
|
28
|
-
|
|
29
|
-
At a terminal, `tb-secret set` now prompts for the secret twice. An abandoned prompt reports that nothing was stored.
|
|
30
|
-
|
|
31
|
-
Separately, a write can now target a named keychain: `createKeychainStore` returns a writable store for any keychain, and `tb-secret set` now has a `--keychain` option.
|
|
32
|
-
|
|
33
|
-
- Point every package bin at a committed wrapper (#296)
|
|
34
|
-
|
|
35
|
-
- Points the `tb-git`, `tb-jira`, and `tb-secret` commands at committed wrappers under each package's `bin/`, so the target exists when the package manager links the command rather than only after a build.
|
|
36
|
-
|
|
37
|
-
- Fix piped-stdin reads and unhandled EPIPE in the CLIs (#301)
|
|
38
|
-
|
|
39
|
-
- Fixes an issue where `tb-secret set` and `tb-jira auth set` failed with `EAGAIN: resource temporarily unavailable` when the producer of a piped credential delayed its first byte, as `tb-secret get`, `op read`, and `gh auth token` all do.
|
|
40
|
-
- Stops `tb-secret`, `tb-jira`, and `tb-git` from crashing with an unhandled `EPIPE` when the reader on their stdout or stderr exits first, so that `tb-secret get | head -1` ends quietly, as a program that ignores `SIGPIPE` does.
|
|
41
|
-
|
|
42
|
-
### Internal
|
|
43
|
-
|
|
44
|
-
- Scaffold toolbelt.secrets for credential storage (#275)
|
|
45
|
-
|
|
46
|
-
Scaffolds `packages/secrets`, an empty workspace for storing and retrieving secrets in the OS credential store, publishing to npm as `@williamthorsen/toolbelt.secrets`.
|
|
14
|
+
Migration: Import `createTempTree`, `CreateTempTreeOptions`, and `TempTree` from `@williamthorsen/toolbelt.testing/candidate`, and declare `@williamthorsen/toolbelt.testing` in the manifest that declared `@williamthorsen/toolbelt.filesystem` for them.
|
|
47
15
|
<!-- /section:release-notes -->
|
|
48
16
|
|
|
49
17
|
## Installation
|
|
@@ -52,15 +20,15 @@ Utilities for storing and retrieving secrets in the OS credential store.
|
|
|
52
20
|
pnpm add @williamthorsen/toolbelt.secrets
|
|
53
21
|
```
|
|
54
22
|
|
|
55
|
-
Requires Node.js 24 or later, and macOS:
|
|
23
|
+
Requires Node.js 24 or later, and macOS: The one backend is the macOS keychain, reached through `/usr/bin/security`. Constructing a store on another platform throws, naming the platform, rather than failing later at the first call.
|
|
56
24
|
|
|
57
25
|
## How a secret is stored
|
|
58
26
|
|
|
59
|
-
An item is named by a **service** and an **account**. The service is the caller's own name for the secret, never derived from a host or a URL, so one item can serve every product that accepts the same token. The account is optional and defaults to the empty account, which is matched exactly:
|
|
27
|
+
An item is named by a **service** and an **account**. The service is the caller's own name for the secret, never derived from a host or a URL, so one item can serve every product that accepts the same token. The account is optional and defaults to the empty account, which is matched exactly: A lookup on a service holding several accounts returns the one that is asked for, rather than an arbitrary one.
|
|
60
28
|
|
|
61
|
-
A secret reaches `security` through its interactive mode, which takes a whole command on stdin, so the secret never sits in an argument vector that any local process could read. It travels as hexadecimal, which
|
|
29
|
+
A secret reaches `security` through its interactive mode, which takes a whole command on stdin, so the secret never sits in an argument vector that any local process could read. It travels as hexadecimal, which encodes every byte, a line break included, and every write is read back and compared before it is reported as stored.
|
|
62
30
|
|
|
63
|
-
One command line
|
|
31
|
+
One command line contains the secret together with the service, the account, and the keychain, and `security` reads at most 4,095 bytes of it. That leaves room for a secret of roughly 2,000 bytes, and the exact ceiling falls as the other three grow. A secret that would not fit is refused, naming the room left; none is ever stored in part.
|
|
64
32
|
|
|
65
33
|
An item created here is local to the Mac that created it. `security` offers no iCloud Keychain synchronization, so a secret stored on one machine has to be stored again on the next.
|
|
66
34
|
|
|
@@ -151,9 +119,9 @@ store.findSecret({ account: 'me@example.com', service: 'atlassian-api-token' });
|
|
|
151
119
|
|
|
152
120
|
`findSecret` returns `undefined` where no item is stored, and throws where the keychain could not be reached, so absence is never confused with a failure. `deleteSecret` reports whether an item was there to remove.
|
|
153
121
|
|
|
154
|
-
`hasSecret` reads the item's attributes rather than its data. That is the difference worth knowing:
|
|
122
|
+
`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 where the item was created by another program, and an attribute lookup cannot.
|
|
155
123
|
|
|
156
|
-
`setSecret` rejects an empty secret, which the keychain would hold as an item indistinguishable from a stray one, and one too long for the command line that
|
|
124
|
+
`setSecret` rejects an empty secret, which the keychain would hold 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 holds. Each write is read back and compared, so a secret that did not survive the round trip fails at the write rather than at a later caller. That readback retrieves the secret, so 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.
|
|
157
125
|
|
|
158
126
|
```ts
|
|
159
127
|
const projectStore = createKeychainStore({ keychain: '/Users/me/Library/Keychains/project.keychain-db' });
|
package/bin/tb-secret.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
|
|
3
|
-
// Imports only node builtins:
|
|
3
|
+
// Imports only node builtins: A top-level import resolves before the gate below runs, so an unresolvable
|
|
4
4
|
// dependency would replace this file's build-first message with ERR_MODULE_NOT_FOUND.
|
|
5
5
|
import { existsSync } from 'node:fs';
|
|
6
6
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Reports a value that cannot reach `security` intact. It is distinct from a failure to reach the keychain,
|
|
3
|
-
* since nothing was attempted:
|
|
3
|
+
* since nothing was attempted: The caller gave a secret, service, or account that no command line can contain.
|
|
4
4
|
*
|
|
5
5
|
* @category Secrets
|
|
6
6
|
* @experimental
|
|
@@ -6,7 +6,7 @@ import type { WritableSecretStore } from '../3-candidate/SecretStore.js';
|
|
|
6
6
|
* @internal
|
|
7
7
|
*/
|
|
8
8
|
export declare function runTbSecret(args: string[], effects: TbSecretEffects): Promise<TbSecretResult>;
|
|
9
|
-
/** The effects deferred to the entry point, which
|
|
9
|
+
/** The effects deferred to the entry point, which keeps the runner free of I/O. */
|
|
10
10
|
export interface TbSecretEffects {
|
|
11
11
|
readonly createStore: (keychain: string | undefined) => WritableSecretStore;
|
|
12
12
|
readonly isStdinTty: () => boolean;
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Rejects an empty secret, which the keychain would hold as an item indistinguishable from a stray one. Every
|
|
3
|
-
* other value is storable: The secret reaches `security` as hexadecimal, which
|
|
3
|
+
* other value is storable: The secret reaches `security` as hexadecimal, which encodes any byte sequence.
|
|
4
4
|
*
|
|
5
5
|
* @internal
|
|
6
6
|
*/
|
|
@@ -6,8 +6,7 @@ import type { SecretQuery } from '../3-candidate/SecretStore.js';
|
|
|
6
6
|
*/
|
|
7
7
|
export declare function buildDeleteArgs(query: SecretQuery, keychain?: string): string[];
|
|
8
8
|
/**
|
|
9
|
-
* Builds the arguments that read a secret. `-g`
|
|
10
|
-
* `parseSecurityPassword` reads.
|
|
9
|
+
* Builds the arguments that read a secret. `-g` prints it, in the two forms that `parseSecurityPassword` reads.
|
|
11
10
|
*
|
|
12
11
|
* @internal
|
|
13
12
|
*/
|
|
@@ -22,7 +21,7 @@ export declare function buildHasArgs(query: SecretQuery, keychain?: string): str
|
|
|
22
21
|
/**
|
|
23
22
|
* Composes the one command line that `security -i` runs to store a secret. Interactive mode takes the whole
|
|
24
23
|
* command on stdin, which keeps the secret off argv, where any local process could read it, and away from the
|
|
25
|
-
* 128-byte buffer that `security` fills when `-w`
|
|
24
|
+
* 128-byte buffer that `security` fills when `-w` has no value.
|
|
26
25
|
*
|
|
27
26
|
* The secret goes in as `-X <hex>`. Its alphabet is closed, so no secret can alter the line's structure, and
|
|
28
27
|
* every byte sequence is representable, a line break included. The service, account, and keychain have no such
|
|
@@ -34,7 +34,7 @@ function assertLineFits(line, fixedBytes) {
|
|
|
34
34
|
function assertOneLine(value, field) {
|
|
35
35
|
if (!LINE_BREAK_PATTERN.test(value))
|
|
36
36
|
return;
|
|
37
|
-
throw new UnstorableSecretError(`The ${field}
|
|
37
|
+
throw new UnstorableSecretError(`The ${field} contains a line break, which \`security\` reads as the end of a command.`);
|
|
38
38
|
}
|
|
39
39
|
function encodeHex(secret) {
|
|
40
40
|
return Buffer.from(secret, 'utf8').toString('hex');
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@williamthorsen/toolbelt.secrets",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "Utilities for storing and retrieving secrets in the OS credential store",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"credentials",
|
|
@@ -48,7 +48,7 @@
|
|
|
48
48
|
"dist/*"
|
|
49
49
|
],
|
|
50
50
|
"devDependencies": {
|
|
51
|
-
"@williamthorsen/toolbelt.
|
|
51
|
+
"@williamthorsen/toolbelt.testing": "0.6.0"
|
|
52
52
|
},
|
|
53
53
|
"engines": {
|
|
54
54
|
"node": ">=24.0.0"
|