@only-cli/oc 0.4.0 → 0.5.1

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/src/cookies.js ADDED
@@ -0,0 +1,530 @@
1
+ /**
2
+ * Per-session cookie jar, stored in a sidecar file next to the page-state
3
+ * JSON. Credentials never live in the session snapshot itself.
4
+ */
5
+
6
+ import net from 'node:net';
7
+ import { join } from 'node:path';
8
+ import { mkdirSync, readFileSync, writeFileSync, unlinkSync, readdirSync, chmodSync } from 'node:fs';
9
+
10
+ import { sessionDir, assertSafeName } from './session.js';
11
+
12
+ const DEFAULT_EXPIRES_MS = 60 * 60 * 1000; // 1h
13
+ export { DEFAULT_EXPIRES_MS };
14
+ const FILE_MODE = 0o600;
15
+
16
+ // A jar is one login's worth of cookies, not a browser profile. The cap is
17
+ // what stops a hostile page from growing the sidecar without bound through
18
+ // Set-Cookie, and 4KB per cookie is the ceiling browsers already enforce.
19
+ export const MAX_COOKIES = 50;
20
+ export const MAX_COOKIE_BYTES = 4096;
21
+
22
+ // RFC 6265 cookie-name is an RFC 7230 token. Real cookie names are always one.
23
+ const COOKIE_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
24
+ // RFC 6265's cookie-value is stricter than this - no space, comma, quote, or
25
+ // backslash - but real browser cookies carry all four, so a strict rule would
26
+ // reject headers a user correctly copied out of devtools. "Printable ASCII, no
27
+ // semicolon" keeps those and still rejects CR, LF, NUL, and every other
28
+ // control character, which is all a header-injection attempt has to work with.
29
+ const COOKIE_VALUE = /^[\x20-\x3A\x3C-\x7E]*$/;
30
+
31
+ // Hostnames only: no scheme, port, path, userinfo, or IPv6 literal.
32
+ const HOSTNAME = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$/;
33
+
34
+ /** Returned by loadCookieJar when a sidecar existed but its session ceiling had passed. */
35
+ export const JAR_EXPIRED = Object.freeze({ expired: true });
36
+
37
+ let purged = false;
38
+
39
+ /**
40
+ * A user-supplied string as it can safely appear in an error message: control
41
+ * characters escaped so a CR cannot rewrite the line, and clipped so a huge
42
+ * value does not become the error.
43
+ * @param {unknown} value
44
+ * @returns {string}
45
+ */
46
+ function clip(value) {
47
+ const s = String(value).replace(/[\x00-\x1f\x7f]/g, (c) => `\\x${c.charCodeAt(0).toString(16).padStart(2, '0')}`);
48
+ return s.length > 40 ? `${s.slice(0, 40)}...` : s;
49
+ }
50
+
51
+ /**
52
+ * @param {string} name
53
+ * @returns {string}
54
+ */
55
+ export function cookieJarPath(name) {
56
+ return join(sessionDir(), `${assertSafeName(name)}.cookies.json`);
57
+ }
58
+
59
+ /**
60
+ * Parse --expires values like 1h, 30m, 2d into milliseconds.
61
+ * @param {string} value
62
+ * @returns {number}
63
+ */
64
+ export function parseExpires(value) {
65
+ const m = String(value).trim().match(/^(\d+(?:\.\d+)?)(h|m|d|s)?$/i);
66
+ if (!m) throw new Error(`invalid --expires '${value}', use a duration like 1h, 30m, or 2d`);
67
+ const n = Number(m[1]);
68
+ const unit = (m[2] ?? 'h').toLowerCase();
69
+ const mult = unit === 'd' ? 86_400_000 : unit === 'h' ? 3_600_000 : unit === 'm' ? 60_000 : 1000;
70
+ return n * mult;
71
+ }
72
+
73
+ /**
74
+ * The hostname a jar is scoped to.
75
+ *
76
+ * domainMatches is a suffix match, so the value here decides how far the
77
+ * cookies reach: '--domain com' would hand them to every .com host the session
78
+ * ever fetches. --domain is trusted input, but the caller is often an agent and
79
+ * the failure mode is silent credential spray, so a bare name is refused. The
80
+ * rule needs no Public Suffix List: at least one dot, unless the value is an IP
81
+ * literal or localhost. It does not catch multi-label public suffixes
82
+ * ('--domain co.uk' still passes); a PSL is the only thing that would, and it
83
+ * is a dependency this project will not take.
84
+ * @param {string} domain
85
+ * @returns {string} the lowercased, dot-stripped hostname
86
+ */
87
+ export function normalizeDomain(domain) {
88
+ const host = String(domain ?? '').trim().toLowerCase().replace(/^\./, '').replace(/\.$/, '');
89
+ if (!host || !HOSTNAME.test(host)) {
90
+ throw new Error(`--domain must be a hostname like example.com (got '${clip(domain)}')`);
91
+ }
92
+ if (net.isIP(host) || host === 'localhost') return host;
93
+ if (!host.includes('.')) {
94
+ throw new Error(
95
+ `--domain '${host}' is a bare name, so these cookies would be sent to every host under it; `
96
+ + 'use the full hostname they belong to, like example.com',
97
+ );
98
+ }
99
+ return host;
100
+ }
101
+
102
+ /**
103
+ * @param {string} name
104
+ * @param {string} value
105
+ * @returns {boolean}
106
+ */
107
+ function isValidCookie(name, value) {
108
+ return COOKIE_NAME.test(name)
109
+ && COOKIE_VALUE.test(value)
110
+ && Buffer.byteLength(name) + Buffer.byteLength(value) <= MAX_COOKIE_BYTES;
111
+ }
112
+
113
+ /**
114
+ * Fail at `oc login` rather than deep inside a transport. A CR or LF in a
115
+ * seeded cookie surfaces later as node's own header-validation error, which
116
+ * says nothing about which cookie is wrong, and whatever curl does with it
117
+ * through impers is a separate question this closes off for both transports.
118
+ * @param {string} name
119
+ * @param {string} value
120
+ */
121
+ function assertValidCookie(name, value) {
122
+ if (!COOKIE_NAME.test(name)) {
123
+ throw new Error(`invalid cookie name '${clip(name)}', names are letters, digits, and !#$%&'*+-.^_\`|~`);
124
+ }
125
+ if (!COOKIE_VALUE.test(value)) {
126
+ throw new Error(
127
+ `invalid value for cookie '${clip(name)}', cookie values cannot hold control characters or non-ASCII bytes`,
128
+ );
129
+ }
130
+ if (Buffer.byteLength(name) + Buffer.byteLength(value) > MAX_COOKIE_BYTES) {
131
+ throw new Error(`cookie '${clip(name)}' is over the ${MAX_COOKIE_BYTES}-byte limit`);
132
+ }
133
+ }
134
+
135
+ /**
136
+ * @typedef {Object} Cookie
137
+ * @property {string} name
138
+ * @property {string} value
139
+ * @property {string} domain
140
+ * @property {string} path
141
+ * @property {boolean} [secure]
142
+ * @property {boolean} [httpOnly]
143
+ * @property {string} [expires] - ISO timestamp
144
+ */
145
+
146
+ /**
147
+ * @typedef {Object} CookieJar
148
+ * @property {string} expiresAt - ISO session ceiling
149
+ * @property {Cookie[]} cookies
150
+ */
151
+
152
+ /**
153
+ * Seed a jar from a Cookie request header string.
154
+ *
155
+ * Seeded cookies are marked secure unless the caller opts out: they were
156
+ * almost certainly copied out of an https browser session, and cookieHeaderFor
157
+ * withholds a secure cookie from a plain-http request, so the default is that
158
+ * they never travel in cleartext - including on an https page that 302s to
159
+ * http, where the user never typed the downgrade.
160
+ * @param {string} header
161
+ * @param {string} domain
162
+ * @param {{ expiresMs?: number, allowHttp?: boolean }} [opts]
163
+ * @returns {CookieJar}
164
+ */
165
+ export function jarFromCookieHeader(header, domain, { expiresMs = DEFAULT_EXPIRES_MS, allowHttp = false } = {}) {
166
+ const host = normalizeDomain(domain);
167
+ /** @type {Cookie[]} */
168
+ const cookies = [];
169
+ for (const part of String(header ?? '').split(';')) {
170
+ const trimmed = part.trim();
171
+ if (!trimmed) continue;
172
+ const eq = trimmed.indexOf('=');
173
+ if (eq <= 0) continue;
174
+ const name = trimmed.slice(0, eq).trim();
175
+ const value = trimmed.slice(eq + 1).trim();
176
+ if (!name) continue;
177
+ assertValidCookie(name, value);
178
+ cookies.push({ name, value, domain: host, path: '/', ...(allowHttp ? {} : { secure: true }) });
179
+ }
180
+ if (!cookies.length) throw new Error('no cookies found in --cookie string');
181
+ if (cookies.length > MAX_COOKIES) {
182
+ throw new Error(`--cookie holds ${cookies.length} cookies, more than the ${MAX_COOKIES} a session keeps`);
183
+ }
184
+ return {
185
+ expiresAt: new Date(Date.now() + expiresMs).toISOString(),
186
+ cookies,
187
+ };
188
+ }
189
+
190
+ /**
191
+ * @param {CookieJar} jar
192
+ * @returns {boolean}
193
+ */
194
+ export function isSessionExpired(jar) {
195
+ return Date.now() >= Date.parse(jar.expiresAt);
196
+ }
197
+
198
+ /**
199
+ * @param {Cookie} cookie
200
+ * @param {string} sessionCeiling
201
+ * @returns {boolean}
202
+ */
203
+ function isCookieExpired(cookie, sessionCeiling) {
204
+ const ceiling = Date.parse(sessionCeiling);
205
+ if (Date.now() >= ceiling) return true;
206
+ if (!cookie.expires) return false;
207
+ const exp = Date.parse(cookie.expires);
208
+ if (Number.isNaN(exp)) return false;
209
+ return exp <= Date.now() || exp > ceiling;
210
+ }
211
+
212
+ /**
213
+ * @param {CookieJar} jar
214
+ * @returns {CookieJar}
215
+ */
216
+ function pruneExpiredCookies(jar) {
217
+ return {
218
+ ...jar,
219
+ cookies: jar.cookies.filter((c) => !isCookieExpired(c, jar.expiresAt)),
220
+ };
221
+ }
222
+
223
+ /**
224
+ * Read this session's jar before the process-wide purge can erase the evidence
225
+ * of expiry; then sweep other stale sidecars.
226
+ * @param {string} name
227
+ * @returns {CookieJar | typeof JAR_EXPIRED | null}
228
+ */
229
+ export function loadCookieJar(name) {
230
+ let result = null;
231
+ try {
232
+ const jar = /** @type {CookieJar} */ (JSON.parse(readFileSync(cookieJarPath(name), 'utf8')));
233
+ if (!jar?.expiresAt || !Array.isArray(jar.cookies)) {
234
+ result = null;
235
+ } else if (isSessionExpired(jar)) {
236
+ clearCookieJar(name);
237
+ result = JAR_EXPIRED;
238
+ } else {
239
+ const pruned = pruneExpiredCookies(jar);
240
+ if (!pruned.cookies.length) {
241
+ clearCookieJar(name);
242
+ result = JAR_EXPIRED;
243
+ } else {
244
+ result = pruned;
245
+ }
246
+ }
247
+ } catch {
248
+ result = null;
249
+ }
250
+ ensurePurged();
251
+ return result;
252
+ }
253
+
254
+ /**
255
+ * @param {string} name
256
+ * @param {CookieJar} jar
257
+ */
258
+ export function saveCookieJar(name, jar) {
259
+ mkdirSync(sessionDir(), { recursive: true });
260
+ // writeFileSync only sets the mode on create, so an existing sidecar has its
261
+ // owner-only mode reasserted on every save.
262
+ const path = cookieJarPath(name);
263
+ writeFileSync(path, JSON.stringify(pruneExpiredCookies(jar)), { mode: FILE_MODE });
264
+ chmodSync(path, FILE_MODE);
265
+ }
266
+
267
+ /**
268
+ * @param {string} name
269
+ */
270
+ export function clearCookieJar(name) {
271
+ try {
272
+ unlinkSync(cookieJarPath(name));
273
+ } catch {
274
+ // missing file is fine
275
+ }
276
+ }
277
+
278
+ /**
279
+ * Delete expired sidecar jars under OC_HOME/sessions.
280
+ */
281
+ export function purgeExpiredJars() {
282
+ let dir;
283
+ try {
284
+ dir = sessionDir();
285
+ readdirSync(dir);
286
+ } catch {
287
+ return;
288
+ }
289
+ for (const file of readdirSync(dir)) {
290
+ if (!file.endsWith('.cookies.json')) continue;
291
+ const name = file.slice(0, -'.cookies.json'.length);
292
+ try {
293
+ const jar = /** @type {CookieJar} */ (JSON.parse(readFileSync(join(dir, file), 'utf8')));
294
+ if (isSessionExpired(jar)) clearCookieJar(name);
295
+ } catch {
296
+ try { unlinkSync(join(dir, file)); } catch {}
297
+ }
298
+ }
299
+ }
300
+
301
+ function ensurePurged() {
302
+ if (purged) return;
303
+ purged = true;
304
+ purgeExpiredJars();
305
+ }
306
+
307
+ /** Reset purge-once guard (tests). */
308
+ export function _resetPurgeGuard() {
309
+ purged = false;
310
+ }
311
+
312
+ /**
313
+ * RFC 6265 domain matching (host-only and domain cookies).
314
+ * @param {Cookie} cookie
315
+ * @param {string} host
316
+ */
317
+ function domainMatches(cookie, host) {
318
+ const d = cookie.domain.toLowerCase().replace(/^\./, '');
319
+ return host === d || host.endsWith(`.${d}`);
320
+ }
321
+
322
+ /**
323
+ * @param {Cookie} cookie
324
+ * @param {string} path
325
+ */
326
+ function pathMatches(cookie, path) {
327
+ const p = cookie.path || '/';
328
+ if (path === p) return true;
329
+ if (!path.startsWith(p)) return false;
330
+ return p.endsWith('/') || path[p.length] === '/';
331
+ }
332
+
333
+ /**
334
+ * @param {Cookie} cookie
335
+ * @param {CookieJar} jar
336
+ * @param {string} host
337
+ * @param {string} path
338
+ */
339
+ function scopeMatches(cookie, jar, host, path) {
340
+ return !isCookieExpired(cookie, jar.expiresAt) && domainMatches(cookie, host) && pathMatches(cookie, path);
341
+ }
342
+
343
+ /**
344
+ * Cookies to send for a request URL.
345
+ * @param {CookieJar} jar
346
+ * @param {string} urlStr
347
+ * @returns {string | undefined}
348
+ */
349
+ export function cookieHeaderFor(jar, urlStr) {
350
+ let url;
351
+ try {
352
+ url = new URL(urlStr);
353
+ } catch {
354
+ return undefined;
355
+ }
356
+ const host = url.hostname.toLowerCase();
357
+ const path = url.pathname || '/';
358
+ const secure = url.protocol === 'https:';
359
+ const active = jar.cookies.filter((c) => {
360
+ if (c.secure && !secure) return false;
361
+ return scopeMatches(c, jar, host, path);
362
+ });
363
+ if (!active.length) return undefined;
364
+ return active.map((c) => `${c.name}=${c.value}`).join('; ');
365
+ }
366
+
367
+ /**
368
+ * Whether this URL would have received cookies but for its scheme. The CLI
369
+ * uses it to name --allow-http, rather than fetching without credentials and
370
+ * leaving the caller to wonder why an authenticated page came back a login
371
+ * form.
372
+ * @param {CookieJar} jar
373
+ * @param {string} urlStr
374
+ * @returns {boolean}
375
+ */
376
+ export function withheldForScheme(jar, urlStr) {
377
+ let url;
378
+ try {
379
+ url = new URL(urlStr);
380
+ } catch {
381
+ return false;
382
+ }
383
+ if (url.protocol !== 'http:') return false;
384
+ const host = url.hostname.toLowerCase();
385
+ const path = url.pathname || '/';
386
+ return jar.cookies.some((c) => c.secure && scopeMatches(c, jar, host, path));
387
+ }
388
+
389
+ /**
390
+ * Parse one Set-Cookie header value.
391
+ * @param {string} header
392
+ * @param {string} requestUrl
393
+ * @returns {Cookie | null}
394
+ */
395
+ export function parseSetCookie(header, requestUrl) {
396
+ const parts = header.split(';').map((p) => p.trim()).filter(Boolean);
397
+ if (!parts.length) return null;
398
+ const eq = parts[0].indexOf('=');
399
+ if (eq <= 0) return null;
400
+ const name = parts[0].slice(0, eq).trim();
401
+ const value = parts[0].slice(eq + 1).trim();
402
+ if (!name) return null;
403
+ // A response is untrusted input, and whatever it sets here is echoed back in
404
+ // the Cookie header of the next request, so it faces the same rule a seeded
405
+ // cookie does. Dropped silently: a page setting a junk cookie is the page's
406
+ // problem, not a reason to fail the render.
407
+ if (!isValidCookie(name, value)) return null;
408
+
409
+ const url = new URL(requestUrl);
410
+ /** @type {Cookie} */
411
+ const cookie = {
412
+ name,
413
+ value,
414
+ domain: url.hostname.toLowerCase(),
415
+ path: '/',
416
+ // A cookie learned over https is pinned secure whether or not the response
417
+ // said so, so a later hop to http - a redirect, or a link the agent
418
+ // follows - cannot carry it in cleartext.
419
+ ...(url.protocol === 'https:' ? { secure: true } : {}),
420
+ };
421
+
422
+ for (const attr of parts.slice(1)) {
423
+ const sep = attr.indexOf('=');
424
+ const key = (sep === -1 ? attr : attr.slice(0, sep)).trim().toLowerCase();
425
+ const val = sep === -1 ? '' : attr.slice(sep + 1).trim();
426
+ // The Domain attribute is deliberately ignored: cookies learned from a
427
+ // response are pinned host-only to the host that set them. Honoring Domain
428
+ // safely needs the Public Suffix List (a site could otherwise scope a
429
+ // cookie to '.com' and have it sent to every site under it), and a PSL is a
430
+ // dependency this project will not take. User-seeded cookies still scope by
431
+ // the --domain they pass, which normalizeDomain holds to the same floor.
432
+ if (key === 'path') {
433
+ cookie.path = val || '/';
434
+ } else if (key === 'secure') {
435
+ cookie.secure = true;
436
+ } else if (key === 'httponly') {
437
+ cookie.httpOnly = true;
438
+ } else if (key === 'max-age') {
439
+ const age = Number(val);
440
+ if (Number.isFinite(age)) {
441
+ cookie.expires = new Date(Date.now() + age * 1000).toISOString();
442
+ }
443
+ } else if (key === 'expires') {
444
+ const exp = Date.parse(val);
445
+ if (!Number.isNaN(exp)) cookie.expires = new Date(exp).toISOString();
446
+ }
447
+ }
448
+ return cookie;
449
+ }
450
+
451
+ /**
452
+ * Extract Set-Cookie header values from a fetch/impers response.
453
+ * @param {any} res
454
+ * @returns {string[]}
455
+ */
456
+ export function getSetCookieHeaders(res) {
457
+ if (typeof res.headers?.getSetCookie === 'function') {
458
+ const list = res.headers.getSetCookie();
459
+ if (Array.isArray(list) && list.length) return list;
460
+ }
461
+ const raw = res.headers?.get?.('set-cookie');
462
+ if (!raw) return [];
463
+ // Undici joins with ", " but Expires contains commas: split only on ", " followed by a token=
464
+ return raw.split(/,\s(?=[\w!#$%&'*+\-.^`|~]+=)/);
465
+ }
466
+
467
+ /**
468
+ * Apply Set-Cookie headers to the jar for a response URL.
469
+ * @param {CookieJar} jar
470
+ * @param {string} url
471
+ * @param {string[]} setCookieHeaders
472
+ * @returns {CookieJar}
473
+ */
474
+ export function storeFromResponse(jar, url, setCookieHeaders) {
475
+ if (!setCookieHeaders.length) return jar;
476
+ let cookies = [...jar.cookies];
477
+ for (const header of setCookieHeaders) {
478
+ const parsed = parseSetCookie(header, url);
479
+ if (!parsed) continue;
480
+ // Max-Age=0 or Expires in the past deletes the cookie
481
+ if (parsed.expires && Date.parse(parsed.expires) <= Date.now()) {
482
+ cookies = cookies.filter((c) => !(c.name === parsed.name && domainMatches(c, parsed.domain)));
483
+ continue;
484
+ }
485
+ cookies = cookies.filter((c) => !(c.name === parsed.name && domainMatches(c, parsed.domain)));
486
+ // Replacing a cookie the jar already holds is always allowed; growing past
487
+ // the cap is not, so a page cannot bloat the sidecar with fresh names. The
488
+ // cookies already there - the seeded login among them - are what survive.
489
+ if (cookies.length >= MAX_COOKIES) continue;
490
+ if (parsed.expires) {
491
+ const ceiling = Date.parse(jar.expiresAt);
492
+ const exp = Date.parse(parsed.expires);
493
+ if (exp > ceiling) parsed.expires = jar.expiresAt;
494
+ }
495
+ cookies.push(parsed);
496
+ }
497
+ return { ...jar, cookies };
498
+ }
499
+
500
+ /**
501
+ * Mutable jar wrapper for fetch to update in place.
502
+ * @param {string} sessionName
503
+ * @param {CookieJar} data
504
+ */
505
+ export function createJarHandle(sessionName, data) {
506
+ let jar = data;
507
+ return {
508
+ sessionName,
509
+ cookieHeaderFor(url) {
510
+ return cookieHeaderFor(jar, url);
511
+ },
512
+ storeFromResponse(url, headers) {
513
+ jar = storeFromResponse(jar, url, headers);
514
+ },
515
+ toJSON() {
516
+ return jar;
517
+ },
518
+ };
519
+ }
520
+
521
+ /**
522
+ * @param {string} name
523
+ * @param {string} header
524
+ * @param {string} domain
525
+ * @param {{ expiresMs?: number, allowHttp?: boolean }} [opts]
526
+ */
527
+ export function loginCookieJar(name, header, domain, opts) {
528
+ const jar = jarFromCookieHeader(header, domain, opts);
529
+ saveCookieJar(name, jar);
530
+ }