@williamthorsen/toolbelt.secrets 0.3.1 โ 0.4.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 +7 -0
- package/README.md +9 -2
- package/dist/esm/bin/runTbSecret.js +119 -158
- package/package.json +4 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,13 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
|
|
5
|
+
## 0.4.0 โ 2026-10-06
|
|
6
|
+
|
|
7
|
+
### ๐ Features
|
|
8
|
+
|
|
9
|
+
- Moves the argument parsing, dispatch, and help of `tb-git`, `tb-jira`, `tb-node`, and `tb-secret` to `@williamthorsen/toolbelt.cli`, which generates each command's help from its schema and reports a usage error as `Error: <message>`, followed by a `Did you mean` line for a mistyped command and a pointer to that command's `--help`. (#365)
|
|
10
|
+
- Adds `-V` to `tb-git`, `tb-jira`, `tb-node`, and `tb-secret` as a short form of `--version`. (#365)
|
|
11
|
+
|
|
5
12
|
## 0.3.1 โ 2026-10-02
|
|
6
13
|
|
|
7
14
|
### ๐งช Tests
|
package/README.md
CHANGED
|
@@ -2,7 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
Utilities for storing and retrieving secrets in the OS credential store.
|
|
4
4
|
|
|
5
|
-
<!-- section:release-notes
|
|
5
|
+
<!-- section:release-notes -->
|
|
6
|
+
## Release notes โ v0.4.0 (2026-10-06)
|
|
7
|
+
|
|
8
|
+
### ๐ Features
|
|
9
|
+
|
|
10
|
+
- Moves the argument parsing, dispatch, and help of `tb-git`, `tb-jira`, `tb-node`, and `tb-secret` to `@williamthorsen/toolbelt.cli`, which generates each command's help from its schema and reports a usage error as `Error: <message>`, followed by a `Did you mean` line for a mistyped command and a pointer to that command's `--help`. (#365)
|
|
11
|
+
- Adds `-V` to `tb-git`, `tb-jira`, `tb-node`, and `tb-secret` as a short form of `--version`. (#365)
|
|
12
|
+
<!-- /section:release-notes -->
|
|
6
13
|
|
|
7
14
|
## Installation
|
|
8
15
|
|
|
@@ -31,7 +38,7 @@ pnpm add --global @williamthorsen/toolbelt.secrets # puts tb-secret on PATH
|
|
|
31
38
|
npx @williamthorsen/toolbelt.secrets get my-token # or run it without installing
|
|
32
39
|
```
|
|
33
40
|
|
|
34
|
-
`tb-secret --help`, each subcommand's `--help`, and `tb-secret --version` report the surface and the installed version.
|
|
41
|
+
`tb-secret --help`, each subcommand's `--help`, and `tb-secret --version` (or `-V`) report the surface and the installed version.
|
|
35
42
|
|
|
36
43
|
| Subcommand | Effect |
|
|
37
44
|
| ---------------------------- | ---------------------------------------------------- |
|
|
@@ -1,65 +1,76 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { createCli, runCli, UsageError } from '@williamthorsen/toolbelt.cli/candidate';
|
|
2
2
|
import { UnstorableSecretError } from "../3-candidate/UnstorableSecretError.js";
|
|
3
3
|
const EXIT_OK = 0;
|
|
4
4
|
const EXIT_NO_RESULT = 1;
|
|
5
|
-
const EXIT_USAGE = 2;
|
|
6
5
|
const EXIT_KEYSTORE = 3;
|
|
7
|
-
const
|
|
8
|
-
const
|
|
9
|
-
const
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
A secret is named by a service and an optional account, so one service can hold a secret per account. An item
|
|
6
|
+
const { defineCommand, defineGroup } = createCli();
|
|
7
|
+
const SERVICE_OPERAND = { name: 'service', description: 'The service that names the secret' };
|
|
8
|
+
const SECRET_FLAGS = {
|
|
9
|
+
account: {
|
|
10
|
+
type: 'string',
|
|
11
|
+
description: 'Account holding the secret (default: the empty account)',
|
|
12
|
+
short: 'a',
|
|
13
|
+
valueHint: 'name',
|
|
14
|
+
},
|
|
15
|
+
keychain: {
|
|
16
|
+
type: 'string',
|
|
17
|
+
description: 'Keychain to act on, rather than the default search list',
|
|
18
|
+
short: 'k',
|
|
19
|
+
valueHint: 'path',
|
|
20
|
+
},
|
|
21
|
+
};
|
|
22
|
+
const ROOT = defineGroup({
|
|
23
|
+
summary: 'Store and read secrets in the macOS keychain. Requires macOS.',
|
|
24
|
+
epilog: `A secret is named by a service and an optional account, so one service can hold a secret per account. An item
|
|
26
25
|
is local to this Mac: \`security\` offers no iCloud Keychain synchronization.
|
|
27
26
|
|
|
28
27
|
Exit codes:
|
|
29
28
|
0 The command succeeded
|
|
30
29
|
1 No secret is stored under that service and account
|
|
31
30
|
2 Usage or validation error
|
|
32
|
-
3 The keychain could not be reached
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
Remove a secret,
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
const
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
31
|
+
3 The keychain could not be reached`,
|
|
32
|
+
commands: {
|
|
33
|
+
delete: defineCommand({
|
|
34
|
+
summary: 'Remove a secret',
|
|
35
|
+
description: 'Remove a secret, exiting 1 when none is stored.',
|
|
36
|
+
flags: SECRET_FLAGS,
|
|
37
|
+
operands: [SERVICE_OPERAND],
|
|
38
|
+
run: ({ context, flags, operands, stderr }) => reportFailures(stderr, () => {
|
|
39
|
+
const query = buildQuery(operands.service, flags.account);
|
|
40
|
+
const removed = callKeystore(() => context.createStore(flags.keychain).deleteSecret(query));
|
|
41
|
+
return removed ? EXIT_OK : EXIT_NO_RESULT;
|
|
42
|
+
}),
|
|
43
|
+
}),
|
|
44
|
+
get: defineCommand({
|
|
45
|
+
summary: 'Print a secret',
|
|
46
|
+
description: 'Print a secret, exiting 1 when none is stored.',
|
|
47
|
+
flags: SECRET_FLAGS,
|
|
48
|
+
operands: [SERVICE_OPERAND],
|
|
49
|
+
run: ({ context, flags, operands, stderr, stdout }) => reportFailures(stderr, () => {
|
|
50
|
+
const query = buildQuery(operands.service, flags.account);
|
|
51
|
+
const secret = callKeystore(() => context.createStore(flags.keychain).findSecret(query));
|
|
52
|
+
if (secret === undefined)
|
|
53
|
+
return EXIT_NO_RESULT;
|
|
54
|
+
stdout.write(`${secret}\n`);
|
|
55
|
+
return EXIT_OK;
|
|
56
|
+
}),
|
|
57
|
+
}),
|
|
58
|
+
has: defineCommand({
|
|
59
|
+
summary: 'Report whether a secret is stored, printing nothing',
|
|
60
|
+
description: `Exit 0 when a secret is stored and 1 when none is, printing nothing either way. The secret itself is never
|
|
61
|
+
read, so this raises no keychain access prompt.`,
|
|
62
|
+
flags: SECRET_FLAGS,
|
|
63
|
+
operands: [SERVICE_OPERAND],
|
|
64
|
+
run: ({ context, flags, operands, stderr }) => reportFailures(stderr, () => {
|
|
65
|
+
const query = buildQuery(operands.service, flags.account);
|
|
66
|
+
const stored = callKeystore(() => context.createStore(flags.keychain).hasSecret(query));
|
|
67
|
+
return stored ? EXIT_OK : EXIT_NO_RESULT;
|
|
68
|
+
}),
|
|
69
|
+
}),
|
|
70
|
+
set: defineCommand({
|
|
71
|
+
summary: 'Store a secret',
|
|
72
|
+
description: 'Store a secret, replacing one already stored under the same service and account.',
|
|
73
|
+
epilog: `At a terminal the secret is prompted for twice and echoed nowhere; piped, it is read from stdin and one
|
|
63
74
|
trailing newline is dropped, since \`echo\` adds one. Either way it is passed to \`security\` inside a command
|
|
64
75
|
sent on stdin, so it never enters an argument vector that any local process could read.
|
|
65
76
|
|
|
@@ -68,26 +79,31 @@ another program created can therefore raise a keychain access prompt, since veri
|
|
|
68
79
|
secret.
|
|
69
80
|
|
|
70
81
|
A secret can be about 2,000 bytes long. The exact ceiling depends on the service, account, and keychain, which
|
|
71
|
-
share one 4,095-byte command line with it; a secret that would not fit is refused rather than stored in part
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
82
|
+
share one 4,095-byte command line with it; a secret that would not fit is refused rather than stored in part.`,
|
|
83
|
+
flags: SECRET_FLAGS,
|
|
84
|
+
operands: [SERVICE_OPERAND],
|
|
85
|
+
run: ({ context, flags, operands, stderr }) => reportFailures(stderr, () => runSet(operands.service, flags, context)),
|
|
86
|
+
}),
|
|
87
|
+
},
|
|
88
|
+
});
|
|
77
89
|
export async function runTbSecret(args, effects) {
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
90
|
+
const stdout = createTextBuffer();
|
|
91
|
+
const stderr = createTextBuffer();
|
|
92
|
+
const exitCode = await runCli(args, ROOT, {
|
|
93
|
+
name: 'tb-secret',
|
|
94
|
+
context: effects,
|
|
95
|
+
version: () => resolveVersion(effects),
|
|
96
|
+
stdout,
|
|
97
|
+
stderr,
|
|
98
|
+
});
|
|
99
|
+
return { exitCode, stderr: stderr.text, stdout: stdout.text };
|
|
86
100
|
}
|
|
87
101
|
class KeystoreError extends Error {
|
|
88
102
|
}
|
|
89
|
-
function buildQuery(
|
|
90
|
-
|
|
103
|
+
function buildQuery(service, account) {
|
|
104
|
+
if (service === '')
|
|
105
|
+
throw new Error('The service name is empty.');
|
|
106
|
+
return { account, service };
|
|
91
107
|
}
|
|
92
108
|
function callKeystore(operation) {
|
|
93
109
|
try {
|
|
@@ -99,105 +115,50 @@ function callKeystore(operation) {
|
|
|
99
115
|
throw new KeystoreError(describeError(error));
|
|
100
116
|
}
|
|
101
117
|
}
|
|
118
|
+
function createTextBuffer() {
|
|
119
|
+
let text = '';
|
|
120
|
+
return {
|
|
121
|
+
get text() {
|
|
122
|
+
return text;
|
|
123
|
+
},
|
|
124
|
+
write(chunk) {
|
|
125
|
+
text += chunk;
|
|
126
|
+
},
|
|
127
|
+
};
|
|
128
|
+
}
|
|
102
129
|
function describeError(error) {
|
|
103
130
|
return error instanceof Error ? error.message : String(error);
|
|
104
131
|
}
|
|
105
|
-
async function
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
return succeed(effects.resolveVersion());
|
|
119
|
-
if (command === undefined)
|
|
120
|
-
return fail('A subcommand is required.', command);
|
|
121
|
-
return fail(`Unknown ${command.startsWith('-') ? 'option' : 'subcommand'}: ${command}`, command);
|
|
122
|
-
}
|
|
123
|
-
function fail(message, command) {
|
|
124
|
-
const scope = command !== undefined && SUBCOMMANDS.has(command) ? `tb-secret ${command}` : 'tb-secret';
|
|
125
|
-
return { exitCode: EXIT_USAGE, stderr: `${message}\nTry \`${scope} --help\`.\n`, stdout: '' };
|
|
126
|
-
}
|
|
127
|
-
function runDelete(args, effects) {
|
|
128
|
-
const { positionals, values } = parseArgs({
|
|
129
|
-
allowPositionals: true,
|
|
130
|
-
args,
|
|
131
|
-
options: { ...ACCOUNT_OPTION, ...HELP_OPTION, ...KEYCHAIN_OPTION },
|
|
132
|
-
strict: true,
|
|
133
|
-
});
|
|
134
|
-
if (values.help === true)
|
|
135
|
-
return succeed(DELETE_HELP);
|
|
136
|
-
const query = buildQuery(positionals, values.account);
|
|
137
|
-
const removed = callKeystore(() => effects.createStore(values.keychain).deleteSecret(query));
|
|
138
|
-
return removed ? succeedSilently() : reportNoResult();
|
|
139
|
-
}
|
|
140
|
-
function runGet(args, effects) {
|
|
141
|
-
const { positionals, values } = parseArgs({
|
|
142
|
-
allowPositionals: true,
|
|
143
|
-
args,
|
|
144
|
-
options: { ...ACCOUNT_OPTION, ...HELP_OPTION, ...KEYCHAIN_OPTION },
|
|
145
|
-
strict: true,
|
|
146
|
-
});
|
|
147
|
-
if (values.help === true)
|
|
148
|
-
return succeed(GET_HELP);
|
|
149
|
-
const query = buildQuery(positionals, values.account);
|
|
150
|
-
const secret = callKeystore(() => effects.createStore(values.keychain).findSecret(query));
|
|
151
|
-
return secret === undefined ? reportNoResult() : succeed(secret);
|
|
132
|
+
async function reportFailures(stderr, body) {
|
|
133
|
+
try {
|
|
134
|
+
return await body();
|
|
135
|
+
}
|
|
136
|
+
catch (error) {
|
|
137
|
+
if (error instanceof UsageError)
|
|
138
|
+
throw error;
|
|
139
|
+
if (error instanceof KeystoreError) {
|
|
140
|
+
stderr.write(`${error.message}\n`);
|
|
141
|
+
return EXIT_KEYSTORE;
|
|
142
|
+
}
|
|
143
|
+
throw new UsageError(describeError(error), { cause: error });
|
|
144
|
+
}
|
|
152
145
|
}
|
|
153
|
-
function
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
}
|
|
160
|
-
if (values.help === true)
|
|
161
|
-
return succeed(HAS_HELP);
|
|
162
|
-
const query = buildQuery(positionals, values.account);
|
|
163
|
-
const stored = callKeystore(() => effects.createStore(values.keychain).hasSecret(query));
|
|
164
|
-
return stored ? succeedSilently() : reportNoResult();
|
|
146
|
+
function resolveVersion(effects) {
|
|
147
|
+
try {
|
|
148
|
+
return effects.resolveVersion();
|
|
149
|
+
}
|
|
150
|
+
catch (error) {
|
|
151
|
+
throw new UsageError(describeError(error), { cause: error });
|
|
152
|
+
}
|
|
165
153
|
}
|
|
166
|
-
async function runSet(
|
|
167
|
-
const
|
|
168
|
-
|
|
169
|
-
args,
|
|
170
|
-
options: { ...ACCOUNT_OPTION, ...HELP_OPTION, ...KEYCHAIN_OPTION },
|
|
171
|
-
strict: true,
|
|
172
|
-
});
|
|
173
|
-
if (values.help === true)
|
|
174
|
-
return succeed(SET_HELP);
|
|
175
|
-
const query = buildQuery(positionals, values.account);
|
|
176
|
-
const store = callKeystore(() => effects.createStore(values.keychain));
|
|
154
|
+
async function runSet(service, flags, effects) {
|
|
155
|
+
const query = buildQuery(service, flags.account);
|
|
156
|
+
const store = callKeystore(() => effects.createStore(flags.keychain));
|
|
177
157
|
const secret = effects.isStdinTty()
|
|
178
158
|
? await effects.promptSecret()
|
|
179
159
|
: stripOneTrailingNewline(await effects.readStdin());
|
|
180
160
|
callKeystore(() => store.setSecret(query, secret));
|
|
181
|
-
return
|
|
182
|
-
}
|
|
183
|
-
function reportNoResult() {
|
|
184
|
-
return { exitCode: EXIT_NO_RESULT, stderr: '', stdout: '' };
|
|
185
|
-
}
|
|
186
|
-
function selectService(positionals) {
|
|
187
|
-
if (positionals.length > 1)
|
|
188
|
-
throw new Error(`Expected one service name. Received ${positionals.length}.`);
|
|
189
|
-
const [service] = positionals;
|
|
190
|
-
if (service === undefined)
|
|
191
|
-
throw new Error('A service name is required.');
|
|
192
|
-
if (service === '')
|
|
193
|
-
throw new Error('The service name is empty.');
|
|
194
|
-
return service;
|
|
195
|
-
}
|
|
196
|
-
function succeed(output) {
|
|
197
|
-
return { exitCode: EXIT_OK, stderr: '', stdout: `${output}\n` };
|
|
198
|
-
}
|
|
199
|
-
function succeedSilently() {
|
|
200
|
-
return { exitCode: EXIT_OK, stderr: '', stdout: '' };
|
|
161
|
+
return EXIT_OK;
|
|
201
162
|
}
|
|
202
163
|
function stripOneTrailingNewline(input) {
|
|
203
164
|
return input.replace(/\r?\n$/, '');
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@williamthorsen/toolbelt.secrets",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "Utilities for storing and retrieving secrets in the OS credential store",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"credentials",
|
|
@@ -47,6 +47,9 @@
|
|
|
47
47
|
"CHANGELOG.md",
|
|
48
48
|
"dist/*"
|
|
49
49
|
],
|
|
50
|
+
"dependencies": {
|
|
51
|
+
"@williamthorsen/toolbelt.cli": "0.2.0"
|
|
52
|
+
},
|
|
50
53
|
"devDependencies": {
|
|
51
54
|
"@williamthorsen/toolbelt.testing": "0.6.2"
|
|
52
55
|
},
|