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 +37 -0
- package/README.md +166 -2
- package/bin/easytopaste.js +31 -0
- package/package.json +46 -6
- package/src/api.js +189 -0
- package/src/cli.js +608 -0
- package/src/crypto.js +192 -0
- package/src/index.js +19 -0
- package/src/link.js +115 -0
package/src/crypto.js
ADDED
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Client-side cryptography for the EasyToPaste CLI.
|
|
3
|
+
*
|
|
4
|
+
* This file is the terminal half of a contract the browser client already
|
|
5
|
+
* implements (frontend/src/app/crypto/crypto.utils.ts and
|
|
6
|
+
* frontend/src/app/components/create-secret/create-secret.component.ts).
|
|
7
|
+
* A secret created here must open in the web app, and a secret created in the
|
|
8
|
+
* web app must open here, so every constant below is a copy of a decision made
|
|
9
|
+
* there — not a new one:
|
|
10
|
+
*
|
|
11
|
+
* - AES-256-GCM, 96-bit IV, 128-bit tag, no additional authenticated data.
|
|
12
|
+
* - A fresh 32-byte key per secret, generated locally and never transmitted.
|
|
13
|
+
* - Inline text envelope byte layout: [iv 12][tag 16][ciphertext N].
|
|
14
|
+
* - The envelope travels base64url (RFC 4648 §5, no padding).
|
|
15
|
+
*
|
|
16
|
+
* test/compat.test.js re-reads those two frontend files and fails if the
|
|
17
|
+
* numbers drift apart, because a silent drift means every link this CLI prints
|
|
18
|
+
* is undecryptable in a browser and nothing else would notice.
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
import { webcrypto } from 'node:crypto';
|
|
22
|
+
|
|
23
|
+
const { subtle } = webcrypto;
|
|
24
|
+
// Bound, not destructured: webcrypto.getRandomValues checks its receiver and
|
|
25
|
+
// throws ERR_INVALID_THIS when it is called detached from the Crypto object.
|
|
26
|
+
const getRandomValues = webcrypto.getRandomValues.bind(webcrypto);
|
|
27
|
+
|
|
28
|
+
/** Key size in bytes (AES-256). */
|
|
29
|
+
export const KEY_BYTES = 32;
|
|
30
|
+
/** IV size in bytes (96-bit GCM nonce). */
|
|
31
|
+
export const IV_BYTES = 12;
|
|
32
|
+
/** GCM authentication tag size in bytes (128-bit). */
|
|
33
|
+
export const TAG_BYTES = 16;
|
|
34
|
+
/** Offset of the ciphertext inside the inline envelope. */
|
|
35
|
+
export const CIPHERTEXT_OFFSET = IV_BYTES + TAG_BYTES;
|
|
36
|
+
/**
|
|
37
|
+
* Largest inline envelope the API accepts (API_SPEC §4.1: 256 KB).
|
|
38
|
+
* Anything larger is a file secret and goes through the presigned-upload path,
|
|
39
|
+
* which this CLI deliberately does not implement (see README).
|
|
40
|
+
*/
|
|
41
|
+
export const MAX_INLINE_BYTES = 256 * 1024;
|
|
42
|
+
|
|
43
|
+
/** A failed GCM authentication: wrong key, or tampered ciphertext. */
|
|
44
|
+
export class DecryptionError extends Error {
|
|
45
|
+
constructor(message = 'decryption failed — wrong key, or the data was altered') {
|
|
46
|
+
super(message);
|
|
47
|
+
this.name = 'DecryptionError';
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** Malformed base64url, envelope or key material. */
|
|
52
|
+
export class EnvelopeError extends Error {
|
|
53
|
+
constructor(message) {
|
|
54
|
+
super(message);
|
|
55
|
+
this.name = 'EnvelopeError';
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** @returns {Uint8Array} 32 cryptographically random bytes. */
|
|
60
|
+
export function generateKey() {
|
|
61
|
+
return getRandomValues(new Uint8Array(KEY_BYTES));
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* base64url-encode bytes, unpadded — the alphabet the URL fragment and the
|
|
66
|
+
* API both expect.
|
|
67
|
+
* @param {Uint8Array} bytes
|
|
68
|
+
* @returns {string}
|
|
69
|
+
*/
|
|
70
|
+
export function toBase64Url(bytes) {
|
|
71
|
+
return Buffer.from(bytes).toString('base64url');
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Decode unpadded base64url back to bytes, strictly.
|
|
76
|
+
*
|
|
77
|
+
* Buffer's own base64url decoder silently skips characters outside the
|
|
78
|
+
* alphabet, so a truncated or corrupted fragment would decode to plausible
|
|
79
|
+
* garbage and surface later as a confusing GCM failure. The shape is checked
|
|
80
|
+
* first and rejected loudly instead.
|
|
81
|
+
*
|
|
82
|
+
* @param {string} value
|
|
83
|
+
* @param {string} what Label used in the error message.
|
|
84
|
+
* @returns {Uint8Array}
|
|
85
|
+
*/
|
|
86
|
+
export function fromBase64Url(value, what = 'value') {
|
|
87
|
+
if (typeof value !== 'string' || value.length === 0) {
|
|
88
|
+
throw new EnvelopeError(`${what} is empty`);
|
|
89
|
+
}
|
|
90
|
+
if (!/^[A-Za-z0-9_-]+={0,2}$/.test(value)) {
|
|
91
|
+
throw new EnvelopeError(`${what} is not valid base64url`);
|
|
92
|
+
}
|
|
93
|
+
return new Uint8Array(Buffer.from(value, 'base64url'));
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* Encrypt UTF-8 text and pack it into the inline envelope the API stores.
|
|
98
|
+
*
|
|
99
|
+
* @param {string} plaintext
|
|
100
|
+
* @param {Uint8Array} key 32 bytes.
|
|
101
|
+
* @returns {Promise<Uint8Array>} [iv 12][tag 16][ciphertext N]
|
|
102
|
+
*/
|
|
103
|
+
export async function encryptTextToEnvelope(plaintext, key) {
|
|
104
|
+
assertKey(key);
|
|
105
|
+
const iv = getRandomValues(new Uint8Array(IV_BYTES));
|
|
106
|
+
const cryptoKey = await subtle.importKey('raw', key, { name: 'AES-GCM', length: 256 }, false, [
|
|
107
|
+
'encrypt',
|
|
108
|
+
]);
|
|
109
|
+
const raw = new Uint8Array(
|
|
110
|
+
await subtle.encrypt(
|
|
111
|
+
{ name: 'AES-GCM', iv, tagLength: TAG_BYTES * 8 },
|
|
112
|
+
cryptoKey,
|
|
113
|
+
new TextEncoder().encode(plaintext),
|
|
114
|
+
),
|
|
115
|
+
);
|
|
116
|
+
|
|
117
|
+
// WebCrypto appends the tag to the ciphertext; the envelope carries it in
|
|
118
|
+
// front, exactly as the browser client packs it.
|
|
119
|
+
const ciphertext = raw.subarray(0, raw.length - TAG_BYTES);
|
|
120
|
+
const tag = raw.subarray(raw.length - TAG_BYTES);
|
|
121
|
+
|
|
122
|
+
const envelope = new Uint8Array(CIPHERTEXT_OFFSET + ciphertext.length);
|
|
123
|
+
envelope.set(iv, 0);
|
|
124
|
+
envelope.set(tag, IV_BYTES);
|
|
125
|
+
envelope.set(ciphertext, CIPHERTEXT_OFFSET);
|
|
126
|
+
return envelope;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* Unpack an inline envelope and decrypt it back to UTF-8 text.
|
|
131
|
+
*
|
|
132
|
+
* @param {Uint8Array} envelope [iv 12][tag 16][ciphertext N]
|
|
133
|
+
* @param {Uint8Array} key 32 bytes.
|
|
134
|
+
* @returns {Promise<string>}
|
|
135
|
+
*/
|
|
136
|
+
export async function decryptEnvelopeToText(envelope, key) {
|
|
137
|
+
assertKey(key);
|
|
138
|
+
if (!(envelope instanceof Uint8Array) || envelope.length < CIPHERTEXT_OFFSET) {
|
|
139
|
+
throw new EnvelopeError(
|
|
140
|
+
`envelope is too short: ${envelope?.length ?? 0} bytes, minimum ${CIPHERTEXT_OFFSET}`,
|
|
141
|
+
);
|
|
142
|
+
}
|
|
143
|
+
const iv = envelope.subarray(0, IV_BYTES);
|
|
144
|
+
const tag = envelope.subarray(IV_BYTES, CIPHERTEXT_OFFSET);
|
|
145
|
+
const ciphertext = envelope.subarray(CIPHERTEXT_OFFSET);
|
|
146
|
+
|
|
147
|
+
const combined = new Uint8Array(ciphertext.length + TAG_BYTES);
|
|
148
|
+
combined.set(ciphertext, 0);
|
|
149
|
+
combined.set(tag, ciphertext.length);
|
|
150
|
+
|
|
151
|
+
const cryptoKey = await subtle.importKey('raw', key, { name: 'AES-GCM', length: 256 }, false, [
|
|
152
|
+
'decrypt',
|
|
153
|
+
]);
|
|
154
|
+
let plaintext;
|
|
155
|
+
try {
|
|
156
|
+
plaintext = await subtle.decrypt(
|
|
157
|
+
{ name: 'AES-GCM', iv, tagLength: TAG_BYTES * 8 },
|
|
158
|
+
cryptoKey,
|
|
159
|
+
combined,
|
|
160
|
+
);
|
|
161
|
+
} catch {
|
|
162
|
+
// No byte-level detail, for the same reason the web client gives none.
|
|
163
|
+
throw new DecryptionError();
|
|
164
|
+
}
|
|
165
|
+
// Strict, for the same reason the input side is strict: a lenient decoder
|
|
166
|
+
// turns bytes it cannot read into U+FFFD, and `--raw` promises the caller
|
|
167
|
+
// the exact bytes that were encrypted. A text secret created by this CLI or
|
|
168
|
+
// by the browser is always valid UTF-8; anything else did not come from
|
|
169
|
+
// either, and silently replacing bytes would be the worst possible answer.
|
|
170
|
+
try {
|
|
171
|
+
return new TextDecoder('utf-8', { fatal: true }).decode(plaintext);
|
|
172
|
+
} catch {
|
|
173
|
+
throw new EnvelopeError(
|
|
174
|
+
'the secret decrypted correctly but is not UTF-8 text, so the CLI will not print it',
|
|
175
|
+
);
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* Overwrite key material in place. Node cannot promise the bytes were never
|
|
181
|
+
* copied by the GC, so this shortens the window rather than closing it.
|
|
182
|
+
* @param {Uint8Array} bytes
|
|
183
|
+
*/
|
|
184
|
+
export function zeroize(bytes) {
|
|
185
|
+
if (bytes instanceof Uint8Array) bytes.fill(0);
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
function assertKey(key) {
|
|
189
|
+
if (!(key instanceof Uint8Array) || key.length !== KEY_BYTES) {
|
|
190
|
+
throw new EnvelopeError(`key must be ${KEY_BYTES} bytes, got ${key?.length ?? 'none'}`);
|
|
191
|
+
}
|
|
192
|
+
}
|
package/src/index.js
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Library surface, for anyone who would rather call this from Node than shell
|
|
3
|
+
* out to the binary. Same code the CLI runs.
|
|
4
|
+
*/
|
|
5
|
+
export { ApiClient, ApiError, NetworkError } from './api.js';
|
|
6
|
+
export {
|
|
7
|
+
DecryptionError,
|
|
8
|
+
EnvelopeError,
|
|
9
|
+
KEY_BYTES,
|
|
10
|
+
MAX_INLINE_BYTES,
|
|
11
|
+
decryptEnvelopeToText,
|
|
12
|
+
encryptTextToEnvelope,
|
|
13
|
+
fromBase64Url,
|
|
14
|
+
generateKey,
|
|
15
|
+
toBase64Url,
|
|
16
|
+
zeroize,
|
|
17
|
+
} from './crypto.js';
|
|
18
|
+
export { DEFAULT_API_BASE, DEFAULT_APP_BASE, LinkError, buildLink, parseLink } from './link.js';
|
|
19
|
+
export { EXIT, VERSION, UsageError, parseArgs, run } from './cli.js';
|
package/src/link.js
ADDED
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Share-link construction and parsing.
|
|
3
|
+
*
|
|
4
|
+
* The link shape is the browser client's (result-screen.component.ts):
|
|
5
|
+
*
|
|
6
|
+
* https://app.easytopaste.com/s/<locator>#k=<base64url key>&v=1
|
|
7
|
+
*
|
|
8
|
+
* Everything after `#` is a URL fragment, which browsers and HTTP clients do
|
|
9
|
+
* not transmit — that is the whole reason the key lives there. This module
|
|
10
|
+
* never logs or forwards the fragment; it only moves it between the link and
|
|
11
|
+
* the local crypto calls.
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
import { EnvelopeError, KEY_BYTES, fromBase64Url, toBase64Url } from './crypto.js';
|
|
15
|
+
|
|
16
|
+
export const DEFAULT_APP_BASE = 'https://app.easytopaste.com';
|
|
17
|
+
export const DEFAULT_API_BASE = 'https://api.easytopaste.com';
|
|
18
|
+
|
|
19
|
+
/** Locators are base32 (A-Z2-7); the wider class is what we will *accept*. */
|
|
20
|
+
const LOCATOR_RE = /^[A-Za-z0-9_-]{8,128}$/;
|
|
21
|
+
|
|
22
|
+
export class LinkError extends Error {
|
|
23
|
+
constructor(message) {
|
|
24
|
+
super(message);
|
|
25
|
+
this.name = 'LinkError';
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* @param {{locator: string, key: Uint8Array, appBase?: string}} args
|
|
31
|
+
* @returns {string} The full one-time link, fragment included.
|
|
32
|
+
*/
|
|
33
|
+
export function buildLink({ locator, key, appBase = DEFAULT_APP_BASE }) {
|
|
34
|
+
assertLocator(locator);
|
|
35
|
+
if (!(key instanceof Uint8Array) || key.length !== KEY_BYTES) {
|
|
36
|
+
throw new LinkError(`key must be ${KEY_BYTES} bytes`);
|
|
37
|
+
}
|
|
38
|
+
const base = String(appBase).replace(/\/+$/, '');
|
|
39
|
+
return `${base}/s/${locator}#k=${toBase64Url(key)}&v=1`;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* Parse a share link back into its locator and key.
|
|
44
|
+
*
|
|
45
|
+
* Accepts the full URL, or the short `<locator>#k=<key>` form that is easier
|
|
46
|
+
* to paste between terminals.
|
|
47
|
+
*
|
|
48
|
+
* @param {string} input
|
|
49
|
+
* @returns {{locator: string, key: Uint8Array}}
|
|
50
|
+
*/
|
|
51
|
+
export function parseLink(input) {
|
|
52
|
+
if (typeof input !== 'string' || input.trim() === '') {
|
|
53
|
+
throw new LinkError('no link given');
|
|
54
|
+
}
|
|
55
|
+
const raw = input.trim();
|
|
56
|
+
const hashAt = raw.indexOf('#');
|
|
57
|
+
if (hashAt === -1) {
|
|
58
|
+
throw new LinkError(
|
|
59
|
+
'that link carries no "#k=" fragment, so it holds no key. ' +
|
|
60
|
+
'Copy the whole link, including everything after the "#".',
|
|
61
|
+
);
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
const before = raw.slice(0, hashAt);
|
|
65
|
+
const fragment = raw.slice(hashAt + 1);
|
|
66
|
+
|
|
67
|
+
const params = new URLSearchParams(fragment);
|
|
68
|
+
const keyPart = params.get('k');
|
|
69
|
+
if (!keyPart) {
|
|
70
|
+
throw new LinkError('the link fragment has no "k=" key parameter');
|
|
71
|
+
}
|
|
72
|
+
const version = params.get('v');
|
|
73
|
+
if (version !== null && version !== '1') {
|
|
74
|
+
throw new LinkError(
|
|
75
|
+
`link envelope version ${version} is newer than this CLI understands (expected 1)`,
|
|
76
|
+
);
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
let key;
|
|
80
|
+
try {
|
|
81
|
+
key = fromBase64Url(keyPart, 'key fragment');
|
|
82
|
+
} catch (err) {
|
|
83
|
+
throw new LinkError(err.message);
|
|
84
|
+
}
|
|
85
|
+
if (key.length !== KEY_BYTES) {
|
|
86
|
+
throw new LinkError(
|
|
87
|
+
`key fragment decodes to ${key.length} bytes, expected ${KEY_BYTES} — the link is truncated`,
|
|
88
|
+
);
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
const locator = extractLocator(before);
|
|
92
|
+
return { locator, key };
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
function extractLocator(before) {
|
|
96
|
+
// A link that travelled through Slack or an email client arrives with a
|
|
97
|
+
// tracking query attached: /s/<locator>?utm_source=slack#k=... The browser
|
|
98
|
+
// opens that fine, so refusing it here would be the CLI inventing a rule the
|
|
99
|
+
// product does not have. The query is not part of the locator and is dropped.
|
|
100
|
+
const trimmed = before.split('?')[0].replace(/\/+$/, '');
|
|
101
|
+
if (trimmed === '') {
|
|
102
|
+
throw new LinkError('the link has no locator before the "#"');
|
|
103
|
+
}
|
|
104
|
+
// Full URL form: .../s/<locator>. Bare form: <locator>.
|
|
105
|
+
const segments = trimmed.split('/');
|
|
106
|
+
const candidate = segments[segments.length - 1];
|
|
107
|
+
assertLocator(candidate);
|
|
108
|
+
return candidate;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
function assertLocator(locator) {
|
|
112
|
+
if (typeof locator !== 'string' || !LOCATOR_RE.test(locator)) {
|
|
113
|
+
throw new LinkError(`"${locator}" is not a valid secret locator`);
|
|
114
|
+
}
|
|
115
|
+
}
|