cloudrop 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/dist/index.d.ts CHANGED
@@ -58,12 +58,16 @@ interface ListedObject {
58
58
  etag: string;
59
59
  uploadedAt: Date;
60
60
  }
61
- /** One rule of the bucket's CORS configuration, as S3's GetBucketCors returns it. */
61
+ /** One rule of the bucket's CORS configuration, as S3's GetBucketCors returns it: every field S3 documents. */
62
62
  interface BucketCorsRule {
63
+ /** Present only when the rule has one. */
64
+ id?: string;
63
65
  allowedOrigins: string[];
64
66
  allowedMethods: string[];
65
67
  allowedHeaders: string[];
66
68
  exposeHeaders: string[];
69
+ /** Present only when the rule sets it. */
70
+ maxAgeSeconds?: number;
67
71
  }
68
72
  /** One rule of the bucket's lifecycle configuration; only what cloudrop checks. */
69
73
  interface BucketLifecycleRule {
@@ -77,6 +81,12 @@ interface BucketLifecycleRule {
77
81
  prefix: string;
78
82
  /** Days after which an incomplete multipart upload is aborted, when the rule does that. */
79
83
  abortIncompleteMultipartUploadDays?: number;
84
+ /**
85
+ * The rule's XML inside `<Rule>`, exactly as the storage sent it. `putBucketLifecycle` writes it unchanged when it is
86
+ * present, so what the fields above leave out (expirations, transitions, tag and size filters) survives a read
87
+ * followed by a write. A rule without it is written from the fields above.
88
+ */
89
+ sourceXml?: string;
80
90
  }
81
91
  /** Implemented by cloudrop's presets, r2() and s3(); its methods may change before 1.0. */
82
92
  interface StorageDriver {
@@ -118,6 +128,20 @@ interface StorageDriver {
118
128
  getBucketCors(): Promise<Result<BucketCorsRule[]>>;
119
129
  /** The bucket's lifecycle rules; [] when it has none. Credentials that may not read them get STORAGE_DENIED. */
120
130
  getBucketLifecycle(): Promise<Result<BucketLifecycleRule[]>>;
131
+ /**
132
+ * Replaces the bucket's whole CORS configuration with `rules` (at least one), as S3's PutBucketCors does: to keep a
133
+ * rule, read it and pass it back. Needs credentials that may change bucket settings; others get STORAGE_DENIED.
134
+ * Optional, so a hand-written driver need not implement it. r2() and s3() do not either, to keep it out of an app's
135
+ * bundle: the `cloudrop setup --apply` command writes bucket settings.
136
+ */
137
+ putBucketCors?(rules: readonly BucketCorsRule[]): Promise<Result<void>>;
138
+ /**
139
+ * Replaces the bucket's whole lifecycle configuration with `rules` (at least one), as S3's
140
+ * PutBucketLifecycleConfiguration does. A rule read from the bucket keeps everything through its `sourceXml`; a new
141
+ * rule is written from its fields and needs `abortIncompleteMultipartUploadDays`, the only action cloudrop writes.
142
+ * Optional, like putBucketCors.
143
+ */
144
+ putBucketLifecycle?(rules: readonly BucketLifecycleRule[]): Promise<Result<void>>;
121
145
  /** `null` only when the object does not exist; every other failure is an error. */
122
146
  head(key: string): Promise<Result<ObjectInfo | null>>;
123
147
  /** Inclusive byte range. */
package/dist/index.js CHANGED
@@ -497,8 +497,8 @@ const PLAIN_EXTENSION = /^[a-z0-9]{1,16}$/;
497
497
  const MIME_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]{0,63}\/[a-z0-9][a-z0-9!#$&^_.+-]{0,63}$/;
498
498
  const ACCEPT_ENTRY = /^(\*\/\*|[a-z0-9][a-z0-9!#$&^_.+-]{0,63}\/(\*|[a-z0-9][a-z0-9!#$&^_.+-]{0,63}))$/;
499
499
  function normalizeType(type) {
500
- const lower = type === "" ? "application/octet-stream" : type.toLowerCase();
501
- return MIME_TYPE.test(lower) ? lower : null;
500
+ const essence = type === "" ? "application/octet-stream" : (type.split(";", 1)[0] ?? "").trim().toLowerCase();
501
+ return MIME_TYPE.test(essence) ? essence : null;
502
502
  }
503
503
  function isAcceptEntry(entry) {
504
504
  return ACCEPT_ENTRY.test(entry);
@@ -895,9 +895,11 @@ function allOk(results) {
895
895
  }
896
896
  // src/server/presign.ts
897
897
  const TOKEN_LIFETIME_SECONDS = 86400;
898
+ const LAST_URL_MARGIN_SECONDS = 900;
898
899
  const nowSeconds = () => Math.floor(Date.now() / 1e3);
899
900
  function urlLifetime(token) {
900
- const seconds = Math.min(900, token.exp - Math.ceil(Date.now() / 1e3));
901
+ const signUntil = token.exp - LAST_URL_MARGIN_SECONDS;
902
+ const seconds = Math.min(900, signUntil - Math.ceil(Date.now() / 1e3));
901
903
  return seconds > 0 ? seconds : null;
902
904
  }
903
905
  function toWire(signed) {
@@ -1040,7 +1042,7 @@ async function readOwner(route, context) {
1040
1042
  if (!route.definition.owner) return null;
1041
1043
  const owner = await route.definition.owner(context);
1042
1044
  if (owner === null) return null;
1043
- if (typeof owner !== "string" || owner.length < 1 || owner.length > 255) throw new TypeError(`Route "${route.name}": owner must return null or a string of 1 to 255 characters.`);
1045
+ if (typeof owner !== "string" || owner.length < 1 || owner.length > 255 || owner.includes("\0")) throw new TypeError(`Route "${route.name}": owner must return null or a string of 1 to 255 characters without NUL (U+0000).`);
1044
1046
  return owner;
1045
1047
  }
1046
1048
  const quotaUnavailable = () => new CloudropError("SERVER_ERROR", "The server could not check your storage limit. Try again in a moment.", { retryable: true });
@@ -1104,9 +1106,13 @@ async function releaseUnstarted(config, shared, unstarted, refusals) {
1104
1106
  // src/server/owner-files.ts
1105
1107
  const DEFAULT_LIMIT$1 = 100;
1106
1108
  const MAX_LIMIT$1 = 1e3;
1107
- const CURSOR$1 = /^\d{1,15}:.+$/s;
1108
- const isOwnerOrId = (value) => typeof value === "string" && value !== "" && value.length <= 255;
1109
- const badOwner = () => fail(invalidInput(`Pass the owner, a string of 1 to 255 characters, as owner() returned it.`));
1109
+ const LAST_TIME_MS = 0xe677d21fdbff;
1110
+ const isOwnerOrId = (value) => typeof value === "string" && value !== "" && value.length <= 255 && !value.includes("\0");
1111
+ const badOwner = () => fail(invalidInput(`Pass the owner, a string of 1 to 255 characters without NUL (U+0000), as owner() returned it.`));
1112
+ function isStoreCursor(cursor) {
1113
+ const match = /^(\d{1,15}):(.+)$/s.exec(cursor);
1114
+ return match !== null && Number(match[1]) <= LAST_TIME_MS && isOwnerOrId(match[2]);
1115
+ }
1110
1116
  function readOptions$2(config, given) {
1111
1117
  if (!isPlainObject(given)) return fail(invalidInput("files takes { owner }, and optionally route, limit and cursor."));
1112
1118
  const { owner, route, limit = DEFAULT_LIMIT$1, cursor } = given;
@@ -1116,7 +1122,7 @@ function readOptions$2(config, given) {
1116
1122
  return fail(invalidInput(`route must be one of this server's routes: ${names}.`));
1117
1123
  }
1118
1124
  if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT$1) return fail(invalidInput(`limit must be a whole number from 1 to ${MAX_LIMIT$1}.`));
1119
- if (cursor !== void 0 && (typeof cursor !== "string" || !CURSOR$1.test(cursor))) return fail(invalidInput("cursor must be one an earlier page of files returned. Leave it out for the first page."));
1125
+ if (cursor !== void 0 && (typeof cursor !== "string" || !isStoreCursor(cursor))) return fail(invalidInput("cursor must be one an earlier page of files returned. Leave it out for the first page."));
1120
1126
  return ok({
1121
1127
  owner,
1122
1128
  route: route ?? null,
@@ -1275,13 +1281,14 @@ async function eraseOwner(config, store, owner, given) {
1275
1281
  // src/server/sweep.ts
1276
1282
  const DEFAULT_LIMIT = 100;
1277
1283
  const MAX_LIMIT = 1e3;
1278
- const CURSOR = /^(expire|cleanup):((?:\d{1,15}:.+)?)$/s;
1284
+ const CURSOR = /^(expire|cleanup):(.*)$/s;
1279
1285
  function readCursor(cursor) {
1280
1286
  const match = CURSOR.exec(cursor);
1281
- return match ? {
1287
+ if (!match || match[2] && !isStoreCursor(match[2])) return null;
1288
+ return {
1282
1289
  pass: match[1],
1283
1290
  cursor: match[2] || null
1284
- } : null;
1291
+ };
1285
1292
  }
1286
1293
  function readAll(options) {
1287
1294
  const { all = false, signal } = options;
@@ -1524,7 +1531,8 @@ async function getUrl(storage, key, given) {
1524
1531
  });
1525
1532
  }
1526
1533
  function pageProblem(keys, prefix, previous) {
1527
- if (keys.some((key) => !key.startsWith(prefix))) return new CloudropError("STORAGE_ERROR", "The storage listed keys outside the prefix, so nothing more was deleted.");
1534
+ const folder = prefix.normalize("NFC");
1535
+ if (keys.some((key) => !key.normalize("NFC").startsWith(folder))) return new CloudropError("STORAGE_ERROR", "The storage listed keys outside the prefix, so nothing more was deleted.");
1528
1536
  if (keys.some((key) => previous.has(key))) return new CloudropError("STORAGE_ERROR", "Some keys were still listed after they were deleted. Retry deletePrefix.", { retryable: true });
1529
1537
  }
1530
1538
  async function deletePrefix(storage, prefix) {
@@ -2513,6 +2521,12 @@ const INVALID_PART_CODES = /* @__PURE__ */ new Set([
2513
2521
  "InvalidPartOrder",
2514
2522
  "EntityTooSmall"
2515
2523
  ]);
2524
+ const MAX_CLOCK_SKEW_MS = 899e3;
2525
+ const CLOCK_SKEWED = {
2526
+ matches: (_status, storageCode) => storageCode === "RequestTimeTooSkewed",
2527
+ code: "STORAGE_DENIED",
2528
+ message: "This server's clock is more than 15 minutes off from the storage service's clock. Sync the clock (NTP), then retry."
2529
+ };
2516
2530
  const RULES = [
2517
2531
  {
2518
2532
  matches: (status, storageCode) => status === 404 && storageCode === "NoSuchUpload",
@@ -2544,15 +2558,16 @@ const RULES = [
2544
2558
  code: "CHECKSUM_MISMATCH",
2545
2559
  message: "The uploaded bytes do not match their checksum. Upload them again."
2546
2560
  },
2561
+ CLOCK_SKEWED,
2547
2562
  {
2548
- matches: (_status, storageCode) => storageCode === "RequestTimeTooSkewed",
2563
+ matches: (_status, storageCode) => storageCode === "ExpiredRequest",
2549
2564
  code: "STORAGE_DENIED",
2550
- message: "This server's clock is more than 15 minutes off from the storage service's clock. Sync the clock (NTP), then retry."
2565
+ message: "The signed request expired. Sign it again and retry."
2551
2566
  },
2552
2567
  {
2553
- matches: (_status, storageCode) => storageCode === "ExpiredRequest",
2568
+ matches: (status) => status === 401,
2554
2569
  code: "STORAGE_DENIED",
2555
- message: "The signed request expired. Sign it again and retry."
2570
+ message: "The storage service did not accept these credentials. Check the access key ID and the secret access key."
2556
2571
  },
2557
2572
  {
2558
2573
  matches: (status) => status === 403,
@@ -2577,10 +2592,10 @@ const RULES = [
2577
2592
  retryable: true
2578
2593
  }
2579
2594
  ];
2580
- function storageError(status, body) {
2595
+ function storageError(status, body, clockOffsetMs = 0) {
2581
2596
  const rawCode = xmlValue(body, "Code");
2582
2597
  const storageCode = rawCode && /^[A-Za-z0-9]{1,64}$/.test(rawCode) ? rawCode : void 0;
2583
- const rule = RULES.find((candidate) => candidate.matches(status, storageCode));
2598
+ const rule = status === 403 && storageCode === void 0 && Math.abs(clockOffsetMs) > MAX_CLOCK_SKEW_MS ? CLOCK_SKEWED : RULES.find((candidate) => candidate.matches(status, storageCode));
2584
2599
  if (rule) return new CloudropError(rule.code, rule.message, {
2585
2600
  status,
2586
2601
  storageCode,
@@ -2618,13 +2633,14 @@ async function send(ctx, method, url, options = {}) {
2618
2633
  const { http, now, credentials, region } = ctx;
2619
2634
  url.search = canonicalQuery(url.searchParams);
2620
2635
  const { headers = {}, body, timeoutMs = REQUEST_TIMEOUT_MS } = options;
2636
+ const signedAt = now();
2621
2637
  const signed = await signRequest({
2622
2638
  method,
2623
2639
  url,
2624
2640
  headers,
2625
2641
  credentials,
2626
2642
  region,
2627
- date: now(),
2643
+ date: signedAt,
2628
2644
  payloadHash: body instanceof Blob ? UNSIGNED_PAYLOAD : body ? await sha256Hex(body) : EMPTY_SHA256
2629
2645
  });
2630
2646
  const sent = method === "HEAD" ? {
@@ -2638,7 +2654,10 @@ async function send(ctx, method, url, options = {}) {
2638
2654
  body,
2639
2655
  signal: AbortSignal.timeout(timeoutMs)
2640
2656
  });
2641
- if (!response.ok) return fail(storageError(response.status, await response.text()));
2657
+ if (!response.ok) {
2658
+ const clockOffsetMs = Date.parse(response.headers.get("date") ?? "") - signedAt.getTime();
2659
+ return fail(storageError(response.status, await response.text(), clockOffsetMs));
2660
+ }
2642
2661
  if (headers.range !== void 0 && response.status !== 206) {
2643
2662
  await response.body?.cancel();
2644
2663
  return fail(new CloudropError("STORAGE_ERROR", "The storage service ignored the byte range. Check that the endpoint supports ranged GET.", { status: response.status }));
@@ -2667,6 +2686,28 @@ function configurationReadError(error, missingCode, setting) {
2667
2686
  storageCode: error.storageCode
2668
2687
  }));
2669
2688
  }
2689
+ const UNREADABLE_XML = /<!\[CDATA\[|<!--|<\/?[A-Za-z_][\w.-]*:/;
2690
+ function readConfiguration(xml, root, setting) {
2691
+ if (new RegExp(`<${root}(?:\\s[^>]*)?/>`).test(xml)) return ok("");
2692
+ const configuration = xmlBlocks(xml, root)[0];
2693
+ if (configuration === void 0) return fail(incompleteResponse(`${setting} configuration`));
2694
+ if (UNREADABLE_XML.test(configuration)) return fail(new CloudropError("STORAGE_ERROR", `The bucket's ${setting} configuration uses XML that cloudrop does not read (CDATA, comments or namespace prefixes). Check its rules by hand.`));
2695
+ return ok(configuration);
2696
+ }
2697
+ function readCorsRule(rule) {
2698
+ const id = xmlText(rule, "ID");
2699
+ const maxAge = xmlValue(rule, "MaxAgeSeconds");
2700
+ const maxAgeSeconds = wholeNumber(maxAge);
2701
+ if (maxAge !== void 0 && maxAgeSeconds === void 0) return fail(incompleteResponse("valid CORS max age"));
2702
+ return ok({
2703
+ ...id === void 0 ? {} : { id },
2704
+ allowedOrigins: xmlValues(rule, "AllowedOrigin"),
2705
+ allowedMethods: xmlValues(rule, "AllowedMethod"),
2706
+ allowedHeaders: xmlValues(rule, "AllowedHeader"),
2707
+ exposeHeaders: xmlValues(rule, "ExposeHeader"),
2708
+ ...maxAgeSeconds === void 0 ? {} : { maxAgeSeconds }
2709
+ });
2710
+ }
2670
2711
  function readLifecycleRule(rule) {
2671
2712
  const days = xmlValue(xmlBlocks(rule, "AbortIncompleteMultipartUpload")[0] ?? "", "DaysAfterInitiation");
2672
2713
  if (days !== void 0 && !/^\d{1,9}$/.test(days)) return fail(incompleteResponse("valid multipart abort days"));
@@ -2674,7 +2715,8 @@ function readLifecycleRule(rule) {
2674
2715
  id: xmlText(rule, "ID") ?? "",
2675
2716
  enabled: xmlValue(rule, "Status") === "Enabled",
2676
2717
  prefix: xmlText(rule, "Prefix") ?? "",
2677
- ...days === void 0 ? {} : { abortIncompleteMultipartUploadDays: Number(days) }
2718
+ ...days === void 0 ? {} : { abortIncompleteMultipartUploadDays: Number(days) },
2719
+ sourceXml: rule
2678
2720
  });
2679
2721
  }
2680
2722
  function bucketSettingsMethods(ctx) {
@@ -2682,21 +2724,16 @@ function bucketSettingsMethods(ctx) {
2682
2724
  async getBucketCors() {
2683
2725
  const result = await sendForXml(ctx, "GET", new URL(`${ctx.bucketUrl}?cors=`));
2684
2726
  if (result.error) return configurationReadError(result.error, "NoSuchCORSConfiguration", "CORS");
2685
- const configuration = xmlBlocks(result.data, "CORSConfiguration")[0];
2686
- if (configuration === void 0) return fail(incompleteResponse("CORS configuration"));
2687
- return ok(xmlBlocks(configuration, "CORSRule").map((rule) => ({
2688
- allowedOrigins: xmlValues(rule, "AllowedOrigin"),
2689
- allowedMethods: xmlValues(rule, "AllowedMethod"),
2690
- allowedHeaders: xmlValues(rule, "AllowedHeader"),
2691
- exposeHeaders: xmlValues(rule, "ExposeHeader")
2692
- })));
2727
+ const configuration = readConfiguration(result.data, "CORSConfiguration", "CORS");
2728
+ if (configuration.error) return configuration;
2729
+ return allOk(xmlBlocks(configuration.data, "CORSRule").map(readCorsRule));
2693
2730
  },
2694
2731
  async getBucketLifecycle() {
2695
2732
  const result = await sendForXml(ctx, "GET", new URL(`${ctx.bucketUrl}?lifecycle=`));
2696
2733
  if (result.error) return configurationReadError(result.error, "NoSuchLifecycleConfiguration", "lifecycle");
2697
- const configuration = xmlBlocks(result.data, "LifecycleConfiguration")[0];
2698
- if (configuration === void 0) return fail(incompleteResponse("lifecycle configuration"));
2699
- return allOk(xmlBlocks(configuration, "Rule").map(readLifecycleRule));
2734
+ const configuration = readConfiguration(result.data, "LifecycleConfiguration", "lifecycle");
2735
+ if (configuration.error) return configuration;
2736
+ return allOk(xmlBlocks(configuration.data, "Rule").map(readLifecycleRule));
2700
2737
  }
2701
2738
  };
2702
2739
  }
@@ -3175,17 +3212,17 @@ function preset(build) {
3175
3212
  });
3176
3213
  return readsEnvironment ? lazyDriver(checked, () => buildFromEnvironment(build)) : checked;
3177
3214
  }
3178
- function buildFromEnvironment(build) {
3215
+ function buildFromEnvironment(build, env = fromEnv) {
3179
3216
  const read = [];
3180
3217
  try {
3181
3218
  return build((variable) => {
3182
- const value = fromEnv(variable);
3219
+ const value = env(variable);
3183
3220
  if (value) read.push(variable);
3184
3221
  return value;
3185
3222
  });
3186
3223
  } catch (error) {
3187
3224
  if (!(error instanceof CloudropError)) throw error;
3188
- const invalid = read.filter((variable) => readSetting(() => build((name, setting) => name === variable ? fromEnv(name) : STAND_INS[setting])).error);
3225
+ const invalid = read.filter((variable) => readSetting(() => build((name, setting) => name === variable ? env(name) : STAND_INS[setting])).error);
3189
3226
  if (invalid.length === 0) throw error;
3190
3227
  throw configError(`${error.message} Environment variables with an invalid value: ${invalid.join(", ")}.`);
3191
3228
  }
@@ -3205,15 +3242,14 @@ function checkAccountId(accountId) {
3205
3242
  }
3206
3243
  return account;
3207
3244
  }
3208
- function r2(given) {
3209
- const options = given ?? {};
3245
+ function buildR2(options, create) {
3210
3246
  const { jurisdiction } = options;
3211
3247
  if (jurisdiction !== void 0 && jurisdiction !== "eu" && jurisdiction !== "fedramp") throw configError("The R2 jurisdiction must be \"eu\" or \"fedramp\". Omit it for the default location.");
3212
- return preset((read) => {
3248
+ return (read) => {
3213
3249
  const settings = readSettings("R2", options, R2_VARIABLES, read);
3214
3250
  const bucket = checkBucket(settings.bucket, "R2");
3215
3251
  const account = checkAccountId(settings.accountId);
3216
- return createS3Driver({
3252
+ return create({
3217
3253
  endpoint: `https://${jurisdiction ? `${account}.${jurisdiction}` : account}.r2.cloudflarestorage.com`,
3218
3254
  region: "auto",
3219
3255
  bucket,
@@ -3225,13 +3261,12 @@ function r2(given) {
3225
3261
  publicUrl: options.publicUrl,
3226
3262
  fetch: options.fetch
3227
3263
  });
3228
- });
3264
+ };
3229
3265
  }
3230
- function s3(given) {
3231
- const options = given ?? {};
3232
- return preset((read) => {
3266
+ function buildS3(options, create) {
3267
+ return (read) => {
3233
3268
  const { endpoint, region, bucket, accessKeyId, secretAccessKey } = readSettings("S3", options, S3_VARIABLES, read);
3234
- return createS3Driver({
3269
+ return create({
3235
3270
  endpoint,
3236
3271
  region,
3237
3272
  bucket: checkBucket(bucket, "S3"),
@@ -3243,7 +3278,13 @@ function s3(given) {
3243
3278
  publicUrl: options.publicUrl,
3244
3279
  fetch: options.fetch
3245
3280
  });
3246
- });
3281
+ };
3282
+ }
3283
+ function r2(given) {
3284
+ return preset(buildR2(given ?? {}, createS3Driver));
3285
+ }
3286
+ function s3(given) {
3287
+ return preset(buildS3(given ?? {}, createS3Driver));
3247
3288
  }
3248
3289
  export { CloudropError, allowAnyone, createCloudrop, forbidden, r2, route, s3, unauthorized };
3249
3290