@devdogsuga/devtools 0.1.0

package/dist/bws/client.js

@@ -0,0 +1,363 @@
+/**
+ * Secrets Manager, through the official SDK. No `bws` binary to install.
+ *
+ * This wrapped the `bws` CLI until 2026-08-19. The CLI was the right call
+ * against the raw REST API: Secrets Manager is end-to-end encrypted, the
+ * server stores ciphertext, and the client derives the key that opens it from
+ * the access token, so `fetch` returns blobs and reimplementing the crypto is
+ * not a trade worth making. `@bitwarden/sdk-napi` is that same client-side
+ * crypto (the same Rust core the CLI wraps), loaded in-process, which buys two
+ * things the CLI could not:
+ *
+ *   * **Nothing to install.** The SDK is a dependency of this package, so
+ *     `pnpm install` is the whole setup. No "install bws from the releases
+ *     page" step, and no version somebody's laptop drifted on.
+ *   * **No credential in argv.** `bws secret create` took the VALUE as a
+ *     positional argument, visible to `ps` for the length of the call, a
+ *     documented property of the tool this wrapper could only apologize for.
+ *     In-process values never touch a process table.
+ *
+ * ⚠️ Imported LAZILY, at the first real call. The SDK is a native module, and
+ * loading it at import time would tax every `cli:no-env` path, the CI guards
+ * included, with a `.node` binary none of them use.
+ *
+ * The one thing the SDK needs that the CLI did not: the ORGANIZATION ID. The
+ * CLI derived it from the access token's login response; the SDK's every list
+ * and create takes it as an argument, and nothing in its API discovers it. It
+ * is a public identifier (a UUID that confers nothing), read from `BWS_ORG_ID`.
+ * See the declaration in `packages/devtools/env.ts`.
+ */
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { log, select, text } from "@clack/prompts";
+import { NoAccessTokenError, promptForToken, resolveToken } from "./token.js";
+import { withRateLimitRetry } from "./retry.js";
+import { makePacer } from "./pace.js";
+import { saveToDevEnv } from "./store.js";
+import { readTokenFromVault, saveTokenToVault, VAULT_ITEM_NAME, } from "./vault.js";
+import { unwrap } from "../ui.js";
+export class BwsError extends Error {
+}
+/**
+ * One pacer for the process: every Secrets Manager request funnels through
+ * it, spaced under the published per-IP limits so the 429 retry stays a
+ * backstop instead of the plan. See `pace.ts` for the numbers and sources.
+ */
+const pace = makePacer();
+let explicitToken;
+let resolved;
+/** Where a just-typed token goes, picked in `offerSave`, used in `save`. */
+let saveDestination = "no";
+/** Records `--access-token`, before any command runs. */
+export function setExplicitAccessToken(token) {
+    explicitToken = token;
+    resolved = undefined;
+}
+/**
+ * The access token, found once per process.
+ *
+ * Memoized as a **promise**, not a value: resolution can prompt, and a single
+ * command makes several Secrets Manager calls. Caching the value alone would
+ * still let two concurrent calls open two prompts over each other.
+ *
+ * Whatever the source, the token reaches the SDK as a function argument in
+ * this process, never argv, never a child's environment.
+ */
+export async function accessToken() {
+    resolved ??= resolveToken({
+        explicit: explicitToken,
+        env: process.env.BWS_ACCESS_TOKEN,
+        fromVault: readTokenFromVault,
+        prompt: promptForToken,
+        // The destination is picked when the save is offered, and the pick is
+        // carried into `save` by closure: the two callbacks are halves of one
+        // exchange. `.env` first: it is this repository's own file, `with-env`
+        // already loads it, and `env push` refuses the key by name, so the only
+        // machine that can read the saved copy is this one.
+        offerSave: async () => {
+            saveDestination = unwrap(await select({
+                message: "Save it, so this is the last time you paste it?",
+                options: [
+                    {
+                        value: "env",
+                        label: "yes — into .env",
+                        hint: "gitignored, this machine only; push refuses it by name",
+                    },
+                    {
+                        value: "vault",
+                        label: "yes — into my Bitwarden vault",
+                        hint: "needs `pnpm devtools bw login`; follows you across machines",
+                    },
+                    { value: "no", label: "no — ask me again next time" },
+                ],
+                initialValue: "env",
+            }));
+            return saveDestination !== "no";
+        },
+        save: async (token) => {
+            if (saveDestination === "env") {
+                await saveToDevEnv("BWS_ACCESS_TOKEN", token);
+                log.success("Stored in .env — with-env loads it on every run.");
+                return;
+            }
+            const saved = await saveTokenToVault(token);
+            if (saved) {
+                log.success(`Stored as "${VAULT_ITEM_NAME}" in your Bitwarden vault.`);
+            }
+            else {
+                log.warn("Could not save it. The command will continue with the token you " +
+                    "typed; nothing was written to your vault.");
+            }
+        },
+        onSource: (source) => {
+            if (source === "flag") {
+                log.warn("--access-token puts a live credential in argv, where `ps` can read " +
+                    "it for the length of the call, and in your shell history. Prefer " +
+                    "BWS_ACCESS_TOKEN or the vault.");
+            }
+        },
+    }).catch((err) => {
+        resolved = undefined; // so a later call can ask again
+        throw err instanceof NoAccessTokenError ? new BwsError(err.message) : err;
+    });
+    return resolved;
+}
+let resolvedOrgId;
+/**
+ * The organization the machine account belongs to: the environment, else a
+ * prompt with an offer to save.
+ *
+ * Prompted rather than only refused because it is the one Secrets Manager
+ * input with nothing secret about it: a public UUID that identifies without
+ * authorizing. Where nobody can answer (a pipe), the named refusal below is
+ * the answer, because an SDK error about a malformed UUID would send somebody
+ * debugging the token, which is the one thing that is fine.
+ */
+function organizationId() {
+    resolvedOrgId ??= (async () => {
+        const fromEnv = process.env.BWS_ORG_ID;
+        if (fromEnv)
+            return fromEnv;
+        if (!process.stdin.isTTY) {
+            throw new BwsError("BWS_ORG_ID is not set. The Secrets Manager SDK addresses everything " +
+                "by organization id — a public UUID, shown in the Secrets Manager " +
+                "URL (bitwarden.com/#/sm/<org-id>/...) and on the machine-account " +
+                "page. Put it in your .env; it identifies, it does not authorize.");
+        }
+        const typed = unwrap(await text({
+            message: "What is the Bitwarden organization id? (the UUID in the Secrets " +
+                "Manager URL: bitwarden.com/#/sm/<org-id>/...)",
+            validate: (v) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test((v ?? "").trim())
+                ? undefined
+                : "That is not a UUID.",
+        })).trim();
+        // Saved without a destination question, unlike the token: this is a
+        // public identifier with exactly one sensible home, and "ask me every
+        // run" is not a state anyone wants for a value that never changes.
+        try {
+            await saveToDevEnv("BWS_ORG_ID", typed);
+            log.success("Stored BWS_ORG_ID in .env.");
+        }
+        catch (err) {
+            log.warn(`Could not save it to .env: ${err instanceof Error ? err.message : String(err)}. ` +
+                "Continuing with the id you typed.");
+        }
+        return typed;
+    })();
+    resolvedOrgId.catch(() => {
+        resolvedOrgId = undefined; // so a later call can ask again
+    });
+    return resolvedOrgId;
+}
+/** The lazily-loaded, logged-in SDK client, one per process. */
+let sdk;
+/**
+ * Where the SDK caches its login, so a process is not a fresh authentication.
+ *
+ * ⚠️ This file is what stops the 429s. Bitwarden's identity endpoint
+ * rate-limits repeated access-token logins hard, and "push preflight, audit,
+ * push staging, audit, push production, audit" is six devtools processes in
+ * two minutes: six logins without this, ONE with it. The `bws` binary kept a
+ * state directory for exactly this reason, and the SDK migration dropped it.
+ * Per machine account (the token's client-id UUID is in the filename, public
+ * by format), under 0700 directories, and outside the repository, because it
+ * caches an auth token and must live where nothing syncs or commits it.
+ */
+function stateFileFor(accessToken) {
+    const clientId = /^\d+\.([0-9a-f-]{36})\./i.exec(accessToken)?.[1] ?? "default";
+    return join(homedir(), ".config", "devdogs-devtools", `bws-state-${clientId}.json`);
+}
+async function client() {
+    sdk ??= (async () => {
+        const token = await accessToken();
+        // Dynamic, so the native module loads only when a command actually
+        // talks to Secrets Manager. See the header.
+        const { BitwardenClient } = await import("@bitwarden/sdk-napi");
+        const instance = new BitwardenClient();
+        try {
+            const stateFile = stateFileFor(token);
+            await mkdir(dirname(stateFile), { recursive: true, mode: 0o700 });
+            await withRateLimitRetry(async () => {
+                await pace("write");
+                return instance.auth().loginAccessToken(token, stateFile);
+            }, { doing: "the login" });
+        }
+        catch (err) {
+            throw new BwsError(describeSdkFailure(err, "logging in"));
+        }
+        return instance;
+    })();
+    sdk.catch(() => {
+        sdk = undefined; // so a later call can retry with a fresh token prompt
+    });
+    return sdk;
+}
+/**
+ * Turns an SDK failure into something with a next step in it.
+ *
+ * The two that actually happen are a rejected token and a token that does not
+ * cover the project. The latter surfaces as a bare "not found", because a
+ * project you cannot see and a project that does not exist are deliberately
+ * the same answer.
+ */
+function describeSdkFailure(err, doing) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (/\b429\b|too many requests/i.test(message)) {
+        return (`${message}\n\n` +
+            "Bitwarden rate-limited this even after the automatic retries. Wait a " +
+            "minute and re-run — the login is cached in a state file now, so " +
+            "re-running does not spend another authentication.");
+    }
+    if (/404|not.?found/i.test(message)) {
+        return (`${message}\n\n` +
+            "A 404 here usually means the access token is valid but its machine " +
+            "account is not assigned to this project — Secrets Manager reports " +
+            "'invisible' and 'absent' identically.");
+    }
+    if (/401|unauthoriz|invalid|expired/i.test(message)) {
+        return `${message}\n\nThe access token was rejected while ${doing}. It may have been revoked or belong to another organization.`;
+    }
+    return message || `Secrets Manager failed with no message while ${doing}.`;
+}
+function iso(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === "string" && value !== "")
+        return value;
+    return undefined;
+}
+/** Resolves a project name to its id. Names are unique within an org. */
+export async function projectIdFor(name) {
+    const c = await client();
+    const org = await organizationId();
+    let projects;
+    try {
+        projects = (await withRateLimitRetry(async () => {
+            await pace("read");
+            return c.projects().list(org);
+        }, {
+            doing: "listing projects",
+        })).data;
+    }
+    catch (err) {
+        throw new BwsError(describeSdkFailure(err, "listing projects"));
+    }
+    const match = projects.find((p) => p.name === name);
+    if (!match) {
+        const visible = projects.map((p) => p.name).sort();
+        throw new BwsError(`No project named "${name}".\n` +
+            (visible.length > 0
+                ? `This token can see: ${visible.join(", ")}`
+                : "This token can see no projects at all, which usually means the " +
+                    "machine account has no project assignments yet."));
+    }
+    return match.id;
+}
+export async function listSecrets(projectId) {
+    const c = await client();
+    const org = await organizationId();
+    try {
+        // The SDK lists IDENTIFIERS org-wide (only what the token may see), then
+        // fetches the values in one batch. Filtered to the project HERE, so the
+        // callers' contract, "the secrets of this project", survives the transport
+        // change byte-for-byte.
+        const identifiers = (await withRateLimitRetry(async () => {
+            await pace("read");
+            return c.secrets().list(org);
+        }, {
+            doing: "listing secrets",
+        })).data;
+        if (identifiers.length === 0)
+            return [];
+        const full = (await withRateLimitRetry(async () => {
+            await pace("read");
+            return c.secrets().getByIds(identifiers.map((i) => i.id));
+        }, { doing: "reading secrets" })).data;
+        return full
+            .filter((s) => s.projectId === projectId)
+            .map((s) => ({
+            id: s.id,
+            key: s.key,
+            value: s.value,
+            note: s.note,
+            projectId,
+            revisionDate: iso(s.revisionDate),
+        }));
+    }
+    catch (err) {
+        throw new BwsError(describeSdkFailure(err, "listing secrets"));
+    }
+}
+export async function createSecret(projectId, key, value, note) {
+    const c = await client();
+    const org = await organizationId();
+    try {
+        await withRateLimitRetry(async () => {
+            await pace("write");
+            return c.secrets().create(org, key, value, note, [projectId]);
+        }, { doing: `creating ${key}` });
+    }
+    catch (err) {
+        throw new BwsError(describeSdkFailure(err, `creating ${key}`));
+    }
+}
+/**
+ * Takes the whole secret rather than an id: the SDK's update is a full
+ * replace (organization, key, project list included), and every caller
+ * already holds the listed secret it is updating.
+ */
+export async function updateSecret(secret, value, note) {
+    const c = await client();
+    const org = await organizationId();
+    try {
+        await withRateLimitRetry(async () => {
+            await pace("write");
+            return c
+                .secrets()
+                .update(org, secret.id, secret.key, value, note, [secret.projectId]);
+        }, { doing: `updating ${secret.key}` });
+    }
+    catch (err) {
+        throw new BwsError(describeSdkFailure(err, `updating ${secret.key}`));
+    }
+}
+export async function deleteSecrets(ids) {
+    if (ids.length === 0)
+        return;
+    const c = await client();
+    try {
+        await withRateLimitRetry(async () => {
+            await pace("write");
+            return c.secrets().delete(ids);
+        }, {
+            doing: "deleting secrets",
+        });
+    }
+    catch (err) {
+        throw new BwsError(describeSdkFailure(err, "deleting secrets"));
+    }
+}
+export function byKey(secrets) {
+    return new Map(secrets.map((s) => [s.key, s]));
+}

package/dist/bws/environments.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The targets whose values live in Bitwarden, and what backs each.
+ *
+ * ⚠️ DERIVED, NOT DECLARED. The vault targets and each one's project name come
+ * from the one target table in `@devdogsuga/env`
+ * (Backstage's `packages/env/src/targets.ts`); only the prose summaries are added here.
+ * This file used to declare its own `preflight | staging | production` enum
+ * beside that package's `development | staging | production` one, both behind
+ * a flag spelled `--env`, and the two agreeing on the words `staging` and
+ * `production` is what let `push --env staging` read the development `.env`
+ * while `init --env staging` wrote `.env.staging`. See the table's own comment
+ * for the full account.
+ *
+ * **Bitwarden is the source of truth, and CI never reads it.** Values are
+ * curated in a local env file and sent onward by `pnpm devtools env push`,
+ * which writes Bitwarden AND the GitHub environment secrets in one go. Deploy
+ * jobs then read `${{ secrets.* }}` like any other workflow.
+ *
+ * That decision sets the whole budget. Nothing machine-shaped authenticates to
+ * Secrets Manager, so there are **no CI machine accounts**, just one `admin`
+ * account, held by a person, read/write on all three projects:
+ *
+ *   | Used | Free plan |
+ *   |------|-----------|
+ *   | 3 projects: preflight, staging, production | 3 |
+ *   | 1 machine account, `admin` | 3 |
+ *
+ * Two machine accounts spare, where the previous shape had none and could not
+ * afford a project for `preflight`.
+ *
+ * There are three projects and FOUR targets: `development` has none. `.env` is
+ * one contributor's own file, there is no shared development credential set to
+ * sync it against, and `pull`/`push`/`audit` refuse that target by name rather
+ * than falling through to a default project.
+ *
+ * The sync costs a second copy that cannot be read back: GitHub secrets are
+ * write-only, so `env audit` compares names and `updatedAt` against each
+ * secret's `revisionDate` here. That catches the realistic failure, a rotation
+ * pushed to Bitwarden and never propagated, without ever comparing values.
+ *
+ * ⚠️ These projects hold the PUBLIC per-environment values too, not only the
+ * secrets: `PROJECT_REF`, `BASE_URL`, `PUBLISHABLE_KEY` and the rest go on to
+ * GitHub as *variables* rather than secrets. "Bitwarden is the source of truth"
+ * has to be true of a whole target for `pull` to rebuild an env file an app can
+ * boot from; while it was true of the secret half only, 27 values existed
+ * nowhere but somebody's laptop. Variables ARE readable back, so for those keys
+ * the audit compares values and the paragraph above does not apply.
+ *
+ * What it buys: no `bws` binary and no Bitwarden network call in the deploy
+ * path, and `${{ secrets.* }}` is masked in workflow logs automatically, which
+ * a value pulled at run time is not unless somebody remembers `::add-mask::`.
+ */
+import type { EnvTarget, VaultTarget } from "@devdogsuga/env";
+export type { VaultTarget };
+export declare const isVaultTarget: (target: EnvTarget) => target is VaultTarget;
+export interface EnvironmentSpec {
+    /** BWS project name. Resolved to a UUID at run time, never committed. */
+    project: string;
+    /** Extra confirmation before writing. */
+    guarded: boolean;
+    summary: string;
+}
+/**
+ * Was a module-level constant, computed eagerly at import time. Now lazy:
+ * `VAULT_TARGETS`/`projectFor`/`isGuarded` come from the repo-resolved
+ * `@devdogsuga/env` (see `repo/peers.ts`), which is not available until
+ * SOMETHING has awaited `loadEnv()` — every real caller already does, via
+ * `env/discovery.ts`'s `loadRegistry()` or `pick.ts`'s own `loadEnv()` call.
+ * Caching keeps repeat reads (env commands call this per target) cheap.
+ */
+export declare function environmentSpecs(): Record<VaultTarget, EnvironmentSpec>;
+/**
+ * `--target development` reached `pull`, `push` or `audit`.
+ *
+ * Its own error rather than a lookup that returns `undefined`, because the old
+ * shape of this mistake was silence: `development` was not in the vault enum,
+ * so nothing named it and nothing said why. It is a real target with a real
+ * file; what it lacks is a shared credential set to sync against.
+ */
+export declare class NoVaultProjectError extends Error {
+    readonly target: EnvTarget;
+    constructor(target: EnvTarget);
+}
+/** Said wherever the refusal is reported, so the advice cannot drift. */
+export declare function noVaultProjectHints(): string[];
+/**
+ * Refuses the one target that has no project, and narrows the rest.
+ *
+ * Called at the top of every command that talks to a vault, so the refusal is a
+ * property of the commands rather than of the argument parser alone: a new
+ * subcommand that forgets to validate its flag still cannot fall through to a
+ * default project. It narrows as well as throws, so everything after the call
+ * is typed as a target that HAS a project rather than merely believed to be
+ * one.
+ */
+export declare function assertVaultTarget(target: EnvTarget): asserts target is VaultTarget;

package/dist/bws/environments.js

@@ -0,0 +1,111 @@
+import { getEnvSync } from "../repo/peers.js";
+export const isVaultTarget = (target) => getEnvSync().isVaultTarget(target);
+const SUMMARIES = {
+    // ⚠️ "Read-only by construction" is now enforced rather than described:
+    // `preflight` is the one row with `deployEnv: false`, and `ignoredFor()`
+    // reads that as "carries only the keys declared `narrowed`". Until it did,
+    // `env push --target preflight` uploaded all 45 routable keys, including
+    // SUPABASE_JWT_SIGNING_KEY, SECRET_KEY and GH_APP_PRIVATE_KEY, into a project
+    // whose GitHub environment `main` can reach.
+    //
+    // `DB_URL` is the one key `narrowed: true` opts in today, so this project
+    // carries nothing else.
+    preflight: "Credentials for the dry runs that precede a promotion to production. " +
+        "Read-only by construction: a Postgres role that can see only the " +
+        "migrations table and nothing else.",
+    staging: "Everything the two Next apps consume, pointed at staging.",
+    production: "The live values. Shared with the production-apply environment, which " +
+        "is the same project behind required reviewers.",
+};
+/**
+ * Project *names*, not ids. See `TargetSpec.project` for why.
+ *
+ * Assembled from the target table rather than typed out again: a second copy of
+ * "staging means staging" is a copy that can disagree, and the disagreement
+ * would be silent in exactly the direction that matters.
+ */
+let cachedSpecs;
+/**
+ * Was a module-level constant, computed eagerly at import time. Now lazy:
+ * `VAULT_TARGETS`/`projectFor`/`isGuarded` come from the repo-resolved
+ * `@devdogsuga/env` (see `repo/peers.ts`), which is not available until
+ * SOMETHING has awaited `loadEnv()` — every real caller already does, via
+ * `env/discovery.ts`'s `loadRegistry()` or `pick.ts`'s own `loadEnv()` call.
+ * Caching keeps repeat reads (env commands call this per target) cheap.
+ */
+export function environmentSpecs() {
+    if (cachedSpecs)
+        return cachedSpecs;
+    const env = getEnvSync();
+    cachedSpecs = Object.fromEntries(env.VAULT_TARGETS.map((target) => [
+        target,
+        {
+            // Non-null by construction: `VAULT_TARGETS` is the targets whose
+            // `project` is not null.
+            project: env.projectFor(target),
+            guarded: env.isGuarded(target),
+            summary: SUMMARIES[target],
+        },
+    ]));
+    return cachedSpecs;
+}
+/**
+ * `--target development` reached `pull`, `push` or `audit`.
+ *
+ * Its own error rather than a lookup that returns `undefined`, because the old
+ * shape of this mistake was silence: `development` was not in the vault enum,
+ * so nothing named it and nothing said why. It is a real target with a real
+ * file; what it lacks is a shared credential set to sync against.
+ */
+export class NoVaultProjectError extends Error {
+    target;
+    constructor(target) {
+        super(`--target ${target} has no Bitwarden project, so there is nothing to ` +
+            `pull from, push to, or audit against. ${getEnvSync().fileFor(target)} is your own ` +
+            `file — nobody else's copy is meant to match it.`);
+        this.target = target;
+        this.name = "NoVaultProjectError";
+    }
+}
+/** Said wherever the refusal is reported, so the advice cannot drift. */
+export function noVaultProjectHints() {
+    return [
+        `Pass --target ${getEnvSync().VAULT_TARGETS.join(" | ")} instead.`,
+        "`pnpm devtools env reset` blanks the values in a local file, keeping each",
+        "recoverable as a comment. `pnpm devtools setup` creates a fresh .env.",
+    ];
+}
+/**
+ * Refuses the one target that has no project, and narrows the rest.
+ *
+ * Called at the top of every command that talks to a vault, so the refusal is a
+ * property of the commands rather than of the argument parser alone: a new
+ * subcommand that forgets to validate its flag still cannot fall through to a
+ * default project. It narrows as well as throws, so everything after the call
+ * is typed as a target that HAS a project rather than merely believed to be
+ * one.
+ */
+export function assertVaultTarget(target) {
+    if (!getEnvSync().isVaultTarget(target))
+        throw new NoVaultProjectError(target);
+}
+// ── Where the key sets went ──────────────────────────────────────────────────
+//
+// The hand-maintained arrays that used to live here (NEVER_STORE_KEYS,
+// NEVER_SECRET_KEYS, APPLY_ONLY_KEYS) are now DERIVED from the declarations in
+// each app's env manifest: `neverStoreKeys()`, `neverSecretKeys()`,
+// `applyOnlyKeys()` and `storableKeys()` from `@devdogsuga/env`, populated by
+// devtools' `env/discovery.ts` (`loadRegistry()`). The arrays were correct;
+// what they could not do is STAY correct, because nothing connected them to the
+// schemas they described. A key added to an `env.ts` and not here was pushed to
+// Bitwarden as a secret by omission.
+//
+// The reasoning moved with the keys, onto the declarations themselves:
+//
+//   * why `BWS_ACCESS_TOKEN` is refused storage anywhere (a key locked inside
+//     the box it opens): its `define()` doc in `packages/devtools/env.ts`;
+//   * why apply-tier is a GITHUB routing rule and not a Bitwarden one (the
+//     production BWS project deliberately holds the apply credential): the
+//     `EnvTier` doc in Backstage's `packages/env/src/meta.ts`;
+//   * why the apply credential stays out of staging/preflight: `ignoredFor()`
+//     in `../env/selection.ts`.

package/dist/bws/pace.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Spacing Secrets Manager calls so the rate limit never fires.
+ *
+ * Bitwarden's published server config (enforced on cloud, per IP, per
+ * endpoint) allows 60 POSTs and 200 GETs per minute and answers 429 beyond.
+ * Community reports show burst enforcement tighter than that per-minute
+ * arithmetic. The identity endpoint's login limit is undocumented and tighter
+ * still; the state-file login cache is what handles that one. Researched
+ * 2026-08-20: https://bitwarden-server.mintlify.app/services/api
+ *
+ * So writes (create, update, delete, login) start no closer than 1.1s apart,
+ * 60/min with margin, and reads (list, getByIds) no closer than 350ms. A full
+ * first push (~48 creates) takes a predictable ~55 seconds instead of a sprint
+ * into a 429; later pushes touch few keys and barely notice. The 429 retry is
+ * the backstop for whatever the undocumented parts still throw.
+ *
+ * One shared gate rather than one per class, and the write interval applies to
+ * the gap after a write whatever follows it: the limiter cares about the
+ * request stream from this IP, not our taxonomy of it.
+ */
+export type CallKind = "read" | "write";
+export declare const WRITE_GAP_MS = 1100;
+export declare const READ_GAP_MS = 350;
+export interface Pacer {
+    (kind: CallKind): Promise<void>;
+}
+export declare function makePacer(now?: () => number, sleep?: (ms: number) => Promise<void>): Pacer;

package/dist/bws/pace.js

@@ -0,0 +1,43 @@
+/**
+ * Spacing Secrets Manager calls so the rate limit never fires.
+ *
+ * Bitwarden's published server config (enforced on cloud, per IP, per
+ * endpoint) allows 60 POSTs and 200 GETs per minute and answers 429 beyond.
+ * Community reports show burst enforcement tighter than that per-minute
+ * arithmetic. The identity endpoint's login limit is undocumented and tighter
+ * still; the state-file login cache is what handles that one. Researched
+ * 2026-08-20: https://bitwarden-server.mintlify.app/services/api
+ *
+ * So writes (create, update, delete, login) start no closer than 1.1s apart,
+ * 60/min with margin, and reads (list, getByIds) no closer than 350ms. A full
+ * first push (~48 creates) takes a predictable ~55 seconds instead of a sprint
+ * into a 429; later pushes touch few keys and barely notice. The 429 retry is
+ * the backstop for whatever the undocumented parts still throw.
+ *
+ * One shared gate rather than one per class, and the write interval applies to
+ * the gap after a write whatever follows it: the limiter cares about the
+ * request stream from this IP, not our taxonomy of it.
+ */
+export const WRITE_GAP_MS = 1_100;
+export const READ_GAP_MS = 350;
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+export function makePacer(now = Date.now, sleep = wait) {
+    let notBefore = 0;
+    let chain = Promise.resolve();
+    return (kind) => {
+        const gap = kind === "write" ? WRITE_GAP_MS : READ_GAP_MS;
+        const turn = chain.then(async () => {
+            const pause = notBefore - now();
+            if (pause > 0)
+                await sleep(pause);
+            // The NEXT call may not start until this one's gap has passed.
+            // Reserved before the call runs, so concurrent callers queue instead
+            // of all measuring from the same stale timestamp.
+            notBefore = now() + gap;
+        });
+        // The chain never rejects: a pacer that fails closed would wedge every
+        // later call behind a rejection that had nothing to do with them.
+        chain = turn.catch(() => { });
+        return turn;
+    };
+}

package/dist/bws/retry.d.ts

@@ -0,0 +1,12 @@
+export declare function isRateLimited(err: unknown): boolean;
+export interface RetryOptions {
+    /** Attempts AFTER the first. */
+    retries?: number;
+    /** First wait; doubles per retry (5s, 10s, 20s by default). */
+    baseMs?: number;
+    /** Injectable for tests. */
+    sleep?: (ms: number) => Promise<void>;
+    /** What to call the operation in the wait message. */
+    doing: string;
+}
+export declare function withRateLimitRetry<T>(op: () => Promise<T>, { retries, baseMs, sleep, doing }: RetryOptions): Promise<T>;