@cloudbitmaps/gcs 0.20.0 → 0.22.0

package/README.md

@@ -14,7 +14,14 @@ second service to run.
 pnpm add @cloudbitmaps/roaring @cloudbitmaps/gcs
 ```
 
-On npm 12 and pnpm 10 and later, allow `roaring`'s one install script first, or the install exits 0 and the package throws at `import`. Put this in your `package.json`: `{ "allowScripts": { "roaring": true }, "pnpm": { "onlyBuiltDependencies": ["roaring"] } }`. npm 11 runs the script but warns until you allow it the same way; pnpm 9 needs nothing extra. [Details](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/getting-started.md#cannot-find-module-buildreleaseroaringnode-after-a-successful-install).
+`roaring` needs its one install script to fetch its native binary, and newer clients run a dependency's script only if you allow it. Allow it before you install:
+
+- **npm 12:** add `{ "allowScripts": { "roaring": true } }` to your `package.json`. Without it the install exits 0 and the package throws at `import`. npm 11 runs the script but warns until you allow it the same way.
+- **pnpm 11 and later:** put `allowBuilds: { roaring: true }` in a `pnpm-workspace.yaml` beside your `package.json`. Those versions no longer read the `package.json` `pnpm` key. Without it the install exits 1 with `ERR_PNPM_IGNORED_BUILDS`.
+- **pnpm 10:** add `{ "pnpm": { "onlyBuiltDependencies": ["roaring"] } }` to your `package.json`. Without it the install exits 0 and the package throws at `import`.
+- **pnpm 9:** nothing extra.
+
+[Details](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/getting-started.md#cannot-find-module-buildreleaseroaringnode-after-a-successful-install).
 
 `@google-cloud/storage` (`^7 || ^8`) is a real dependency of this package, so installing it is the whole step.
 `@cloudbitmaps/core`, the engine underneath, arrives with it and you never name it.
@@ -109,6 +116,30 @@ It builds its own client from Application Default Credentials. Any other key is
   store's clock).
 
 The [production checklist](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/production.md) covers each item, and the ones every backend shares: backups of the data and the registry, and a schedule for your loads.
+- **The driver redacts the credentials it recognises from an error before it throws it.** The SDK keeps the response it
+  got on the error (`response`), and through it the request it sent, with the bearer token in its `Authorization`
+  header, and the HTTP agent it shares with other calls; a resumable upload's or a token request's error keeps the
+  request's `config`. On a download, and wherever a body lists no errors, the SDK makes the response body the error's
+  message, so a proxy's page or a JSON body that quotes the request puts the token in the message. In the error the
+  driver throws, the value under a credential's name is replaced by `[redacted]` (`authorization`,
+  `x-goog-encryption-key`, `x-goog-api-key`, `X-Goog-Signature`, `X-Goog-Credential`, `access_token`, `refresh_token`,
+  `client_secret`, `private_key` and the like; a service account's `client_email` and `private_key_id` are kept), and so
+  are the value after one in a header list or under one in a map, the value beside one in a record (a `{ name, value }`
+  pair, a `{ th, td }` row; a number, a boolean, and the `message`, `reason` and `location` of a Google error item are
+  kept), and, anywhere in its text, a credential header line; an `Authorization` value, an encryption key, an API key,
+  an OAuth token or client secret, or a signed URL's signature or credential after its name; a cookie header's value
+  after its name; a bearer token after its scheme; a Google access token (`ya29.`) or a JWT on its own; a V2 signed
+  URL's `Signature=`; a PEM private key's body; the text of an element named for a credential, such as the
+  `<CanonicalRequest>` a service quotes back; and the text of the cell after one that names a credential (a
+  `<th>`/`<td>` row, a `<dt>`/`<dd>` pair, after a heading or a caption too). A credential in another form is not
+  recognised (a header table laid out by column, a user and password written into a URL, a colon written as an HTML
+  entity such as `&colon;` in a body a download quotes as it came), and a text these steps cannot finish is replaced
+  whole. An SDK error that carries its transport or shows a credential, and every error it reaches (its `cause` chain,
+  an `AggregateError`'s `errors`), is thrown as a copy: a native error with the same prototype, name, message, stack,
+  `code`, `status` and `errors`, with `response` reduced to its status and status text, so classification is unchanged,
+  without `config`, the request, its agent or socket, any function or accessor property, or anything nested deeper than
+  ten levels. The live error is never changed, and an error that holds only plain data and shows no credential is thrown
+  as it is.
 
 ## Documentation
 

package/dist/backend.d.ts

@@ -1,16 +1,10 @@
-/**
- * `GcsStorage` — the Google Cloud Storage backend as one object: generations and pointer, one bucket, stated once.
- *
- * See {@link StorageBackend} for why the two halves are configured together rather than separately.
- *
- * **A note on the word.** `@google-cloud/storage` names its own client class `Storage`, so the driver option
- * that takes it is also called `storage` — which, since this library calls its durable tier storage too, reads
- * as the same word meaning two things. That is why this class builds the client itself: `new GcsStorage({ bucket })`
- * never makes you write `{ storage: storage }`. Supply `client` when you need your own.
- */
 import { STORAGE_BACKEND } from '@cloudbitmaps/core/driver-kit';
 import type { IRegistryDriver, IStorageDriver, StorageBackend } from '@cloudbitmaps/core/driver-kit';
 import { Storage as GcsClient } from '@google-cloud/storage';
+/**
+ * What {@link GcsStorage} takes: a `bucket`, and either a `client` or the two settings that build one (`projectId`,
+ * `apiEndpoint`), never both.
+ */
 export interface GcsStorageOptions {
     /** Target bucket (must already exist). */
     readonly bucket: string;
@@ -77,6 +71,16 @@ export interface GcsStorageOptions {
  * for a client pointed at an emulator that is production traffic from a wiring typo.
  */
 export declare const GCS_STORAGE_OPTION_KEYS: readonly ["bucket", "prefix", "client", "projectId", "apiEndpoint", "maxObjectBytes", "simpleUploadThresholdBytes", "now", "readTimeoutMs", "conditionalDelete"];
+/**
+ * `GcsStorage` — the Google Cloud Storage backend as one object: generations and pointer, one bucket, stated once.
+ *
+ * See {@link StorageBackend} for why the two halves are configured together rather than separately.
+ *
+ * **A note on the word.** `@google-cloud/storage` names its own client class `Storage`, so the driver option
+ * that takes it is also called `storage` — which, since this library calls its durable tier storage too, reads
+ * as the same word meaning two things. That is why this class builds the client itself: `new GcsStorage({ bucket })`
+ * never makes you write `{ storage: storage }`. Supply `client` when you need your own.
+ */
 export declare class GcsStorage implements StorageBackend {
     /** Cross-bundle brand, stamped non-enumerably in the constructor so a spread cannot carry it. */
     readonly [STORAGE_BACKEND]: true;