toolroll 0.9.61 → 0.9.63

package/dist/tool-secret-store.d.ts

@@ -0,0 +1,170 @@
+export type SecretStoreKind = "macos-keychain" | "secret-service" | "files";
+/** One item's address: what the store lists, never a secret (a folder's or project's hash, a tool's name). */
+export type SecretItem = {
+    service: string;
+    account: string;
+};
+export type SecretBackend = {
+    kind: Exclude<SecretStoreKind, "files">;
+    /** Values are [A-Za-z0-9._-] only, at most `limit` characters. */
+    limit: number;
+    get(item: SecretItem): string | null;
+    /** `create`: only when no item is there yet ("exists" when one is). */
+    set(item: SecretItem, value: string, options?: {
+        create?: boolean;
+    }): "ok" | "exists";
+    remove(item: SecretItem): void;
+};
+export declare class SecretStoreError extends Error {
+}
+/** The words Settings and `toolroll integrations` use for where secrets rest. */
+export declare const STORE_WORDS: Readonly<Record<SecretStoreKind, string>>;
+/** Said instead when a keyring is installed but doesn't answer, so files are all there is. */
+export declare const UNANSWERED_WORDS = "Secrets are protected by owner-only files on this computer: its keyring isn't answering.";
+/** The macOS Keychain, through `security -i` (`keychain`: a keychain file instead of the user's own, for tests). */
+export declare function macosKeychain(options?: {
+    keychain?: string;
+    binary?: string;
+}): SecretBackend;
+/** The Secret Service (GNOME Keyring, KWallet), through `secret-tool` at `binary`, an absolute path; the value goes on its stdin. */
+export declare function secretService(options: {
+    binary: string;
+}): SecretBackend;
+/**
+ * `path` when it is a program only the system (or, for a test's stand-in, one of `owners`) can have put there: a real
+ * executable file nobody else can change, in folders nobody else can either. Null otherwise.
+ */
+export declare function trustedProgram(path: string, owners?: readonly number[]): string | null;
+/** Where `secret-tool` may be: the system's own folders, never the PATH a process was given. */
+export declare const SECRET_TOOL_PATHS: readonly string[];
+/** This computer's store as found: a backend, or none, and when none, whether one is installed but not answering. */
+export type DetectedStore = {
+    backend: SecretBackend | null;
+    unanswered: boolean;
+};
+/**
+ * Find this computer's store: the macOS Keychain where the system's `security` is; a Secret Service where the system's
+ * `secret-tool` is and answers; else none (files). A `secret-tool` that is there but can't reach a keyring (no session
+ * bus) is none too, and says so.
+ */
+export declare function detectSecretStore(options?: {
+    platform?: NodeJS.Platform;
+    secretTools?: readonly string[];
+    owners?: readonly number[];
+}): DetectedStore;
+/** Tests choose the store (a keychain file of their own, files, or what detection found); null goes back to this computer's. */
+export declare function chooseSecretStore(store: SecretBackend | "files" | DetectedStore | null): void;
+/** This computer's store (found once), or null for owner-only files. */
+export declare function secretBackend(env?: NodeJS.ProcessEnv): SecretBackend | null;
+export declare const secretStoreKind: () => SecretStoreKind;
+/** Where secrets rest, in the words Settings and `toolroll integrations` share; `problem` when Toolroll's folder can't be used. */
+export declare function secretStorage(): {
+    kind: SecretStoreKind;
+    words: string;
+    filesOnly: boolean;
+    problem?: string;
+};
+/** The text stored at `item`, or null when nothing is. A head read while a writer replaces it is read again. */
+export declare function readValue(backend: SecretBackend, item: SecretItem): string | null;
+/**
+ * Store `text` at `item`: the chunks of a new generation first, then the head that names them, then the old
+ * generation's chunks are removed. `create`: only when nothing is stored there yet.
+ */
+export declare function writeValue(backend: SecretBackend, item: SecretItem, text: string, options?: {
+    create?: boolean;
+}): "ok" | "exists";
+/** Remove what is stored at `item`, every chunk with it. */
+export declare function removeValue(backend: SecretBackend, item: SecretItem): void;
+/** The folder's name, beside the database. */
+export declare const SECRET_FOLDER = "tool-secrets";
+/** Where Toolroll records which sealing key it made: the database, which no build can write. */
+export type KeyAnchor = {
+    read(): string | null;
+    swap(expected: string | null, next: string): boolean;
+};
+/** An anchor kept in this process alone: a test's own folder. */
+export declare function memoryAnchor(): KeyAnchor;
+/** Toolroll's folder for secrets, checked: its key in hand, and where the files kept before it are (`legacy`). */
+export type SecretFolder = {
+    readonly root: string;
+    readonly dir: string;
+    readonly legacy: string | null;
+    dev: number;
+    ino: number;
+    key: Buffer;
+    digest: string;
+    anchor: KeyAnchor;
+};
+/**
+ * Prepare Toolroll's folder for secrets beside `stateDir` (the folder holding the database), checked against what
+ * `anchor` recorded: made with its sealing key when it isn't there yet (`create`), refused when something else put a
+ * folder, key or link there. `standing`: the folder this process uses by default (Toolroll's own start).
+ */
+export declare function prepareSecretFolder(stateDir: string, anchor: KeyAnchor, options?: {
+    create?: boolean;
+    legacy?: string | null;
+    standing?: boolean;
+}): {
+    ok: true;
+    dir: string;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * Name Toolroll's folder for secrets (beside `stateDir`, the database's folder) and the record to check it against,
+ * without touching it yet: it is prepared the first time a secret is used. `standing`: this process's default.
+ */
+export declare function registerSecretFolder(stateDir: string, anchor: KeyAnchor, options?: {
+    legacy?: string | null;
+}): void;
+/**
+ * Toolroll's folder for secrets, checked again now: the one prepared at start when `state` is absent, else the one
+ * beside `state` (a test's own folder is prepared the first time it is used, against an anchor in this process).
+ */
+export declare function secretFolder(state?: string): SecretFolder;
+/** Forget every prepared folder (tests). */
+export declare function forgetSecretFolders(): void;
+/** The keychain service for everything kept for this folder's Toolroll: its folder, hashed. Never a secret. */
+export declare const serviceOf: (folder: SecretFolder) => string;
+/**
+ * A path inside `base` (the folder, or Toolroll's own folder above it), each folder on the way checked: a real folder
+ * of this user's that nobody else can write, never a link. Made owner-only when `make` (else a missing one ends the
+ * walk: nothing is there).
+ */
+export declare function pathIn(base: string, parts: readonly string[], options?: {
+    make?: boolean;
+}): string;
+/** A file's text, read without following a link; null when there is none. Anything not plainly Toolroll's is refused. */
+export declare function readOwnFile(path: string): string | null;
+/** Write a file whole and owner-only: a new file beside it, then renamed over it, so a link or second name planted there is replaced, never written through. */
+export declare function writeOwnFile(path: string, text: string): void;
+/** A file's bytes overwritten, then the file removed (a link is only removed, never followed). */
+export declare function destroyOwnFile(path: string): void;
+/** One change at a time to what `name` keeps, across Toolroll's processes (a lock file in the folder), re-entrant within one. */
+export declare function withSecretLock<T>(folder: SecretFolder, name: string, work: () => T): T;
+/** The same, for work that waits on the network (renewing a sign-in): other processes wait for it, up to `waitMs`. */
+export declare function withSecretLockAsync<T>(folder: SecretFolder, name: string, work: () => Promise<T>, options?: {
+    staleMs?: number;
+    waitMs?: number;
+}): Promise<T>;
+/** `text` sealed for `item` with the folder's key. */
+export declare function seal(text: string, item: SecretItem, folder: SecretFolder): string;
+/** What `seal` sealed for `item`; refused when it was sealed for another item, with another key, or changed. */
+export declare function unseal(sealed: string, item: SecretItem, folder: SecretFolder): string;
+/** The sealed text kept at `item`, opened; null when nothing is. */
+export declare function readSealed(backend: SecretBackend, folder: SecretFolder, item: SecretItem): string | null;
+/** Keep `text` at `item`, sealed. */
+export declare function writeSealed(backend: SecretBackend, folder: SecretFolder, item: SecretItem, text: string, options?: {
+    create?: boolean;
+}): "ok" | "exists";
+/**
+ * A secret Toolroll holds for an integration, by `name` ("linear-key", "google-mail", "flow-hook.12"), for the
+ * Toolroll whose folder is `state`. `file` (inside `state`) is where it was kept before, and still is where there's no
+ * keychain. The first read or write with a keychain moves the file in.
+ */
+export declare function readHeldSecret(state: string, name: string, file: readonly string[]): string | null;
+/** Keep (or, with null, remove) a held secret: see readHeldSecret. */
+export declare function writeHeldSecret(state: string, name: string, file: readonly string[], value: string | null): void;
+/** Whether a held secret has a value, without reading it where that can be helped. */
+export declare function heldSecretSet(state: string, name: string, file: readonly string[]): boolean;