easytopaste 0.0.0-stage → 0.1.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/LICENSE.md ADDED
@@ -0,0 +1,37 @@
1
+ # EasyToPaste CLI — licence
2
+
3
+ Copyright © 2026 EasyToPaste. All rights reserved.
4
+
5
+ ## What you may do
6
+
7
+ You are granted a free, worldwide, non-exclusive, revocable licence to
8
+ **download, install and run** this package — personally, inside a company, and
9
+ in automated systems such as CI — for any lawful purpose, including commercial
10
+ use. No registration, payment or notice to us is required.
11
+
12
+ You may read the source. It is published unminified on purpose: this tool
13
+ encrypts your secrets on your own machine, and a client you cannot inspect is a
14
+ client you cannot check.
15
+
16
+ ## What you may not do
17
+
18
+ You may not redistribute, republish, sublicense or sell this package or a
19
+ derivative of it, and you may not modify it for distribution to others.
20
+ Installing it from npm as a dependency of your own project is not
21
+ redistribution and is expressly allowed.
22
+
23
+ ## No warranty
24
+
25
+ This package is provided "as is", without warranty of any kind, express or
26
+ implied, including the warranties of merchantability, fitness for a particular
27
+ purpose and non-infringement. To the fullest extent permitted by law, the
28
+ copyright holder is not liable for any claim, damages or other liability
29
+ arising from this package or its use.
30
+
31
+ ## Not an open-source promise
32
+
33
+ This licence grants use, not stewardship. Publishing this package is not a
34
+ commitment to maintain it as an open-source project, to accept contributions,
35
+ or to keep publishing future versions.
36
+
37
+ Questions: https://easytopaste.com/legal/contact
package/README.md CHANGED
@@ -1,3 +1,167 @@
1
- # Temporary Holding Version
1
+ # easytopaste
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Pipe a secret in, get a one-time link out.
4
+
5
+ ```console
6
+ $ printf '%s' "$DB_PASSWORD" | easytopaste
7
+ https://app.easytopaste.com/s/MFRGGZDFMZTWQ2LKNNWG23TP#k=0xN1uhC9lNq2YvF7s3zKj8qQaE-Xb5cT4Rd0WfGhIjM&v=1
8
+ ```
9
+
10
+ The secret is encrypted on your machine with AES-256-GCM. The key goes in the
11
+ link's `#fragment`, which no HTTP client transmits, so the server stores
12
+ ciphertext it cannot read and a link is the only thing that opens it. Send the
13
+ link; the first person to open it gets the secret, and the link dies.
14
+
15
+ > **Status: built, not yet published.** This package is not on npm today, so
16
+ > `npx easytopaste` does not work yet — publishing is a separate, deliberate
17
+ > decision. Until then, install it from a checkout (see *Install* below).
18
+
19
+ ## Install
20
+
21
+ Once published:
22
+
23
+ ```console
24
+ npm install -g easytopaste # or run it without installing: npx easytopaste
25
+ ```
26
+
27
+ From a checkout, today:
28
+
29
+ ```console
30
+ cd cli
31
+ npm link # puts `easytopaste` on your PATH
32
+ node bin/easytopaste.js # or run it in place, from this directory
33
+ ```
34
+
35
+ Node 18.17 or newer. No dependencies — the package installs nothing but
36
+ itself, which is the point for a tool you hand secrets to.
37
+
38
+ ## Use
39
+
40
+ ```console
41
+ # From a pipe (the normal case)
42
+ printf '%s' "$DB_PASSWORD" | easytopaste
43
+
44
+ # From a flag, kept for seven days instead of one
45
+ easytopaste --text 'deploy key: abc123' --days 7
46
+
47
+ # From a text file
48
+ easytopaste --file ./credentials.env
49
+
50
+ # Read one, from any machine
51
+ easytopaste read 'https://app.easytopaste.com/s/MFRG...#k=...&v=1'
52
+ ```
53
+
54
+ ### Create options
55
+
56
+ | Option | Meaning |
57
+ | --- | --- |
58
+ | `-t, --text <string>` | The secret, instead of reading stdin |
59
+ | `-f, --file <path>` | Read the secret from a UTF-8 text file |
60
+ | `-d, --days <1-30>` | Days until it expires on its own (default: 1) |
61
+ | `--multi` | Allow repeat reads until expiry (default: one-time) |
62
+ | `--json` | Print `{"link","locator","expiresAt","oneTime"}` instead of the link |
63
+
64
+ ### Read options
65
+
66
+ | Option | Meaning |
67
+ | --- | --- |
68
+ | `--keep` | Do not burn a one-time secret after reading it |
69
+ | `--raw` | Write the secret verbatim, with no trailing newline added |
70
+ | `--json` | Print `{"secret","oneTime","burnPending"}` instead of the plaintext |
71
+
72
+ ### Common options
73
+
74
+ | Option | Meaning |
75
+ | --- | --- |
76
+ | `--api <url>` | API base URL (default `https://api.easytopaste.com`) |
77
+ | `--app <url>` | App base URL used to build links (default `https://app.easytopaste.com`) |
78
+ | `-q, --quiet` | Suppress the status lines on stderr |
79
+ | `-h, --help` / `-V, --version` | The usual |
80
+
81
+ Only the link — or, on `read`, the secret — goes to stdout. Status lines,
82
+ warnings and errors go to stderr, so piping does what you expect:
83
+
84
+ ```console
85
+ printf '%s' "$TOKEN" | easytopaste --quiet | clip
86
+ easytopaste read "$LINK" --quiet --raw > recovered.txt
87
+ ```
88
+
89
+ `read` adds a trailing newline so the secret does not run into your shell
90
+ prompt. That one byte matters when the secret is a key or a token, so `--raw`
91
+ writes exactly the bytes that were encrypted and nothing else.
92
+
93
+ ### Exit codes
94
+
95
+ | Code | Meaning |
96
+ | --- | --- |
97
+ | `0` | Done |
98
+ | `1` | Failed — a secret that would not decrypt, one that could not be written to stdout (in which case it was not burned), or any other API failure (a 500, a secret too large for the API) |
99
+ | `2` | Usage mistake, or a secret this CLI cannot handle |
100
+ | `3` | Gone: burned, expired, revoked, or no such link |
101
+ | `4` | Rate limited, or the daily quota is used up |
102
+ | `5` | The API could not be reached |
103
+
104
+ ## What it does, exactly
105
+
106
+ 1. Generates a 32-byte key with the OS CSPRNG. It never leaves the process.
107
+ 2. Encrypts the text with AES-256-GCM: a fresh 96-bit IV per secret, a 128-bit
108
+ authentication tag, no additional authenticated data.
109
+ 3. Packs `[iv 12][tag 16][ciphertext n]`, base64url, and `POST`s that to
110
+ `/v1/secrets` together with its length and the expiry you chose.
111
+ 4. Prints `https://app.easytopaste.com/s/<locator>#k=<key>&v=1`, assembled
112
+ locally from the locator the API returned and the key that never left.
113
+
114
+ `read` reverses it: fetch the envelope by locator, decrypt locally, write the
115
+ secret out, and only then — on a one-time secret, after a successful decrypt
116
+ *and* a successful write — call `/burn`.
117
+
118
+ Both halves of that order are deliberate. Burning before the decrypt would
119
+ destroy a secret the reader never got. Burning before the write would do the
120
+ same thing more quietly: `easytopaste read "$LINK" | grep -q x` closes the
121
+ pipe, and a burn there would destroy the only copy of a secret that reached
122
+ nobody. So a failed write means no burn, an explicit message, and exit 1 —
123
+ the link stays live and can be read again.
124
+
125
+ If the burn itself fails, the secret is still printed and stderr says the link
126
+ is still live. That warning is **not** suppressed by `--quiet`: a one-time link
127
+ that survived being read is not a status line. It is also why `--json` reports
128
+ `burnPending` rather than `burned` — the secret is written before the burn is
129
+ attempted, so no truthful `burned` value exists at the moment the object is
130
+ printed.
131
+
132
+ ## What it deliberately does not do
133
+
134
+ * **No file or binary secrets.** Those are encrypted in chunks and streamed to
135
+ object storage; the browser app at <https://app.easytopaste.com> does that.
136
+ Anything over 256 KB is refused here, and so is anything that is not valid
137
+ UTF-8 text — whether it arrives through `--file` or through the pipe. It is
138
+ refused with a pointer rather than mangled into replacement characters,
139
+ which is what a lenient decoder would silently upload.
140
+ * **No passphrase mode and no sign-in-gated secrets.** The CLI says what the
141
+ secret needs and names the browser URL to open instead, and exits 2.
142
+ * **No telemetry, no analytics, no crash reporting, no update check.** The only
143
+ network calls it makes are the three API calls above. The request carries a
144
+ `user-agent` of `easytopaste-cli/<version>` and nothing else about you.
145
+ * **No key storage.** Nothing is written to disk by this tool: no config file,
146
+ no history, no cache. Note what that does *not* cover — if you pass a secret
147
+ with `--text`, your own shell writes it to its history file and `ps` shows it
148
+ to anyone else on the machine while it runs. Piping (`printf '%s' "$X" |
149
+ easytopaste`) avoids both.
150
+ The link is yours to pass on; lose it and the secret is unreachable, which
151
+ is the design.
152
+
153
+ ## Compatibility
154
+
155
+ A link made here opens in the browser app, and a link made in the browser app
156
+ opens here — the envelope format and the link shape are a single contract. The
157
+ test suite reads the browser client's source and the API's validators and fails
158
+ if those numbers drift apart, because nothing else would notice.
159
+
160
+ ## Development
161
+
162
+ ```console
163
+ cd cli
164
+ node --test test/ # the whole suite: no network, no dependencies
165
+ ```
166
+
167
+ The Python gate runs the same suite: `pytest work/ops/tests/test_cli_package.py`.
@@ -0,0 +1,31 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Entry point. Keeps process plumbing - argv slicing, exit code, EPIPE - out
4
+ * of the testable surface in src/cli.js.
5
+ */
6
+ import { run } from '../src/cli.js';
7
+
8
+ // A closed stdout (`easytopaste | head -1`, a reader that quit) must not take
9
+ // the process down with an unhandled 'error' event - but it must not be
10
+ // swallowed either. src/cli.js watches the write itself and decides what it
11
+ // means: on the read path it is the difference between burning a secret that
12
+ // reached someone and burning one that reached nobody.
13
+ process.stdout.on('error', () => {});
14
+ // stderr too: a closed stderr threw out of the write and turned a documented
15
+ // exit code into 1 - and on the read path it could land between the secret
16
+ // being written and the burn, leaving a one-time link quietly alive.
17
+ process.stderr.on('error', () => {});
18
+
19
+ run(process.argv.slice(2), {
20
+ stdout: process.stdout,
21
+ stderr: process.stderr,
22
+ stdin: process.stdin,
23
+ }).then(
24
+ (code) => {
25
+ process.exitCode = code;
26
+ },
27
+ (e) => {
28
+ process.stderr.write(`easytopaste: ${e?.stack ?? e}\n`);
29
+ process.exitCode = 1;
30
+ },
31
+ );
package/package.json CHANGED
@@ -1,6 +1,46 @@
1
- {
2
- "name": "easytopaste",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
1
+ {
2
+ "name": "easytopaste",
3
+ "version": "0.1.0",
4
+ "description": "Pipe a secret in, get a one-time link out. Encrypted on your machine with AES-256-GCM; the key never leaves it.",
5
+ "type": "module",
6
+ "bin": {
7
+ "easytopaste": "bin/easytopaste.js"
8
+ },
9
+ "main": "src/index.js",
10
+ "exports": {
11
+ ".": "./src/index.js"
12
+ },
13
+ "engines": {
14
+ "node": ">=18.17"
15
+ },
16
+ "files": [
17
+ "bin",
18
+ "src",
19
+ "README.md",
20
+ "LICENSE.md"
21
+ ],
22
+ "scripts": {
23
+ "test": "node --test test/"
24
+ },
25
+ "keywords": [
26
+ "secret",
27
+ "one-time",
28
+ "onetime-secret",
29
+ "password-sharing",
30
+ "end-to-end-encryption",
31
+ "zero-knowledge",
32
+ "aes-256-gcm",
33
+ "cli",
34
+ "devops",
35
+ "secrets-management"
36
+ ],
37
+ "homepage": "https://easytopaste.com",
38
+ "bugs": {
39
+ "url": "https://easytopaste.com/legal/contact"
40
+ },
41
+ "license": "SEE LICENSE IN LICENSE.md",
42
+ "_private_why": "Published 2026-11-19 under the owner's standing instruction to release the CLI without asking. private:true was removed in the same edit as the licence, which is what that flag was guarding.",
43
+ "publishConfig": {
44
+ "access": "public"
45
+ }
46
+ }
package/src/api.js ADDED
@@ -0,0 +1,189 @@
1
+ /**
2
+ * The HTTP half of the CLI: three calls against the public secrets API.
3
+ *
4
+ * What this module is allowed to send is as important as what it does send.
5
+ * It posts ciphertext and metadata, and nothing else — no plaintext, no key,
6
+ * no file path, no environment detail, no telemetry of any kind. The
7
+ * zero-knowledge posture is a product promise, so the request body built here
8
+ * is asserted field-by-field in test/api.test.js rather than trusted.
9
+ */
10
+
11
+ import { DEFAULT_API_BASE } from './link.js';
12
+
13
+ const USER_AGENT_PREFIX = 'easytopaste-cli';
14
+
15
+ /** An error the API itself reported, carrying its machine-readable code. */
16
+ export class ApiError extends Error {
17
+ /**
18
+ * @param {string} message Human-readable, already suitable for stderr.
19
+ * @param {{code?: string, status?: number, requestId?: string, retryAfter?: string}} info
20
+ */
21
+ constructor(message, info = {}) {
22
+ super(message);
23
+ this.name = 'ApiError';
24
+ this.code = info.code ?? 'unknown';
25
+ this.status = info.status ?? 0;
26
+ this.requestId = info.requestId ?? null;
27
+ this.retryAfter = info.retryAfter ?? null;
28
+ }
29
+ }
30
+
31
+ /** The request never reached the API, or the API never answered. */
32
+ export class NetworkError extends Error {
33
+ constructor(message, cause) {
34
+ super(message, { cause });
35
+ this.name = 'NetworkError';
36
+ }
37
+ }
38
+
39
+ export class ApiClient {
40
+ /**
41
+ * @param {{baseUrl?: string, version?: string, timeoutMs?: number, fetchImpl?: typeof fetch}} opts
42
+ */
43
+ constructor({ baseUrl = DEFAULT_API_BASE, version = '0.0.0', timeoutMs = 20_000, fetchImpl } = {}) {
44
+ this.baseUrl = String(baseUrl).replace(/\/+$/, '');
45
+ this.version = version;
46
+ this.timeoutMs = timeoutMs;
47
+ this.fetchImpl = fetchImpl ?? globalThis.fetch;
48
+ }
49
+
50
+ /**
51
+ * POST /v1/secrets — store one inline ciphertext envelope.
52
+ *
53
+ * @param {{ciphertextB64: string, sizeBytes: number, oneTime: boolean, expiresInDays: number}} args
54
+ * @returns {Promise<{locator: string, code?: string, expiresAt?: string}>}
55
+ */
56
+ async createSecret({ ciphertextB64, sizeBytes, oneTime, expiresInDays }) {
57
+ const body = {
58
+ type: 'text',
59
+ mode: 'link',
60
+ envelopeVersion: 1,
61
+ sizeBytes,
62
+ oneTime,
63
+ expiresInDays,
64
+ requiresRecipientLogin: false,
65
+ mimeHint: 'text/plain',
66
+ ciphertext: ciphertextB64,
67
+ };
68
+ const { json } = await this.#request('POST', '/v1/secrets', body);
69
+ if (!json || typeof json.locator !== 'string') {
70
+ throw new ApiError('the API accepted the secret but returned no locator');
71
+ }
72
+ return json;
73
+ }
74
+
75
+ /**
76
+ * GET /v1/secrets/{locator} — metadata plus, for inline text, the envelope.
77
+ * This call deliberately does not burn; see burnSecret.
78
+ *
79
+ * @param {string} locator
80
+ */
81
+ async retrieveSecret(locator) {
82
+ const { json } = await this.#request('GET', `/v1/secrets/${encodeURIComponent(locator)}`);
83
+ return json ?? {};
84
+ }
85
+
86
+ /**
87
+ * POST /v1/secrets/{locator}/burn — destroy a one-time secret.
88
+ *
89
+ * Called only after a successful local decrypt, for the reason the web
90
+ * client records: burning first would destroy a secret the reader never got.
91
+ *
92
+ * @param {string} locator
93
+ */
94
+ async burnSecret(locator) {
95
+ const { json } = await this.#request(
96
+ 'POST',
97
+ `/v1/secrets/${encodeURIComponent(locator)}/burn`,
98
+ {},
99
+ );
100
+ return json ?? {};
101
+ }
102
+
103
+ async #request(method, path, body) {
104
+ const url = `${this.baseUrl}${path}`;
105
+ const headers = {
106
+ accept: 'application/json',
107
+ 'user-agent': `${USER_AGENT_PREFIX}/${this.version}`,
108
+ };
109
+ if (body !== undefined) headers['content-type'] = 'application/json';
110
+
111
+ const controller = new AbortController();
112
+ const timer = setTimeout(() => controller.abort(), this.timeoutMs);
113
+ let response;
114
+ try {
115
+ response = await this.fetchImpl(url, {
116
+ method,
117
+ headers,
118
+ body: body === undefined ? undefined : JSON.stringify(body),
119
+ signal: controller.signal,
120
+ });
121
+ } catch (cause) {
122
+ if (cause?.name === 'AbortError') {
123
+ throw new NetworkError(`${method} ${url} timed out after ${this.timeoutMs} ms`, cause);
124
+ }
125
+ throw new NetworkError(`cannot reach ${this.baseUrl} — ${cause?.message ?? cause}`, cause);
126
+ } finally {
127
+ clearTimeout(timer);
128
+ }
129
+
130
+ const text = await response.text();
131
+ let json = null;
132
+ if (text) {
133
+ try {
134
+ json = JSON.parse(text);
135
+ } catch {
136
+ json = null;
137
+ }
138
+ }
139
+
140
+ if (!response.ok) {
141
+ throw toApiError(response, json);
142
+ }
143
+ return { json, response };
144
+ }
145
+ }
146
+
147
+ /**
148
+ * Turn an API error envelope into a message a person can act on.
149
+ * API_SPEC §1.2: `{ "error": { code, message, request_id, hint? } }`.
150
+ */
151
+ function toApiError(response, json) {
152
+ const err = json && typeof json === 'object' ? json.error : null;
153
+ const code = err?.code ?? `http_${response.status}`;
154
+ const requestId = err?.request_id ?? err?.requestId ?? null;
155
+ const base = err?.message || `the API answered ${response.status}`;
156
+ const hint = err?.hint ? ` ${err.hint}` : '';
157
+ return new ApiError(`${explain(code)}${base}${hint}`, {
158
+ code,
159
+ status: response.status,
160
+ requestId,
161
+ retryAfter: response.headers?.get?.('retry-after') ?? null,
162
+ });
163
+ }
164
+
165
+ /** Short prefixes that say what the code means for *this* CLI's user. */
166
+ function explain(code) {
167
+ switch (code) {
168
+ case 'not_found':
169
+ return 'no such secret — it was burned, expired, or the link is wrong: ';
170
+ case 'already_accessed':
171
+ return 'this one-time secret has already been read: ';
172
+ case 'expired':
173
+ return 'this secret has expired: ';
174
+ case 'revoked':
175
+ return 'the sender revoked this secret: ';
176
+ case 'rate_limited':
177
+ return 'too many requests, wait a minute: ';
178
+ case 'quota_exceeded':
179
+ return 'daily quota reached: ';
180
+ case 'payload_too_large':
181
+ return 'the secret is too large for an inline link: ';
182
+ case 'recipient_denied':
183
+ case 'unauthorized':
184
+ case 'forbidden':
185
+ return 'this secret requires a signed-in recipient, open it in a browser: ';
186
+ default:
187
+ return '';
188
+ }
189
+ }