tapline-host 1.6.1 → 1.7.0

package/dist/accounts.d.ts

@@ -1,4 +1,49 @@
 import { z } from "zod";
+import { type VaultDeps } from "./vault.js";
+export declare const VAULT_KINDS: readonly ["account", "card", "address", "identity", "note", "phone"];
+export type VaultKind = (typeof VAULT_KINDS)[number];
+/** The fields each kind has. `phone` is Tapwright's: Tapline holds it and never types it. */
+export declare const KIND_FIELDS: Record<VaultKind, readonly string[]>;
+/** Version 2 (§20.1). A top-level `otp` key is Tapwright's and is ignored here. */
+export declare const vaultFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    vault: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"account">;
+        username: z.ZodOptional<z.ZodString>;
+        password: z.ZodOptional<z.ZodString>;
+        apps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"card">;
+        number: z.ZodOptional<z.ZodString>;
+        expiry: z.ZodOptional<z.ZodString>;
+        cvc: z.ZodOptional<z.ZodString>;
+        apps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"address">;
+        street: z.ZodOptional<z.ZodString>;
+        city: z.ZodOptional<z.ZodString>;
+        postcode: z.ZodOptional<z.ZodString>;
+        country: z.ZodOptional<z.ZodString>;
+        apps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"identity">;
+        name: z.ZodOptional<z.ZodString>;
+        phone: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+        birthday: z.ZodOptional<z.ZodString>;
+        apps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"note">;
+        text: z.ZodOptional<z.ZodString>;
+        apps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"phone">;
+        passcode: z.ZodOptional<z.ZodString>;
+        apps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>], "kind">>;
+}, z.core.$strip>;
+export type VaultFile = z.infer<typeof vaultFileSchema>;
+/** Version 1 (§18.6). */
 export declare const accountsFileSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     accounts: z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -9,6 +54,14 @@ export declare const accountsFileSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type AccountsFile = z.infer<typeof accountsFileSchema>;
+/** An entry as the store holds it, whatever file version it came from. */
+export interface VaultEntry {
+    kind: VaultKind;
+    values: Record<string, string>;
+    apps?: string[];
+}
+/** Where `value=` and the other answers name a value: `<home's street>`. */
+export declare function placeholderOf(name: string, field: string): string;
 export type AccountField = "username" | "password";
 export type AccountResolved = {
     ok: true;
@@ -19,16 +72,26 @@ export type AccountResolved = {
     message: string;
 };
 export interface AccountStore {
-    /** The accounts' names, never their values. */
+    /** The entries' names, never their values. */
     names(): string[];
-    /** One value of an account, for an app. */
-    resolve(name: string, field: AccountField, appId: string): AccountResolved;
-    /** Replaces every username with `<tester2's username>` and every password with `<tester2's password>`. */
+    /** What kind an entry is. */
+    kindOf(name: string): VaultKind | undefined;
+    /** One value of an account, for an app (`${account.<field>}`: the call's `account` names the entry, and it is an `account`). */
+    resolve(name: string, field: string, appId: string): AccountResolved;
+    /** One value of any entry, for an app (`${vault.<name>.<field>}`). */
+    resolveEntry(name: string, field: string, appId: string): AccountResolved;
+    /** Replaces every vault value with its placeholder, such as `<tester2's username>` or `<home's street>`. */
     redact(text: string): string;
 }
-/** What the accounts file gave: its accounts, or why none were loaded (the git message). */
+/** What the vault file gave: its entries (and the plain file's warning), or why none were loaded. */
 export type AccountsLoad = {
     store: AccountStore;
+    note?: string;
+    /**
+     * HMAC-SHA256 under `key` of the vault's canonical JSON as it was decrypted (every value and every per-app permission), so two
+     * loads of the same vault agree and a changed one differs, while nothing in it can be guessed from the hash alone.
+     */
+    fingerprint?: (key: string) => string;
 } | {
     store: null;
     blocked: string;
@@ -42,31 +105,85 @@ export interface GitProbe {
 /** The real probe: the user's own git, run without a shell. When git can't run, a `.git` above the file counts as a work tree. */
 export declare const realGitProbe: GitProbe;
 /** What the user is told wherever the accounts option is described (the parameter text, `--help`, `doctor`). */
-export declare const ACCOUNTS_WARNING = "A password stays out of pictures only while its field is secure; a \"show password\" toggle shows it. Keep the accounts file outside the folders the agent may read.";
+export declare const ACCOUNTS_WARNING = "A password stays out of pictures only while its field is secure; a \"show password\" toggle shows it. Keep the vault file outside the folders the agent may read.";
 /** The refusal's words, for the first answer, `doctor` and every use. */
 export declare function blockedMessage(file: string): string;
+/**
+ * The shapes a value can take on its way back: as it is, with direction marks and zero-width characters stripped, with
+ * whitespace collapsed (as the app's `normalizeText` leaves it), each of those inside a JSON string (also twice, and with
+ * non-ASCII escaped), and in a URL (percent or form encoded, either case of hex). A value the app cuts at 200 characters
+ * leaves its first 200.
+ */
+export declare function variantsOf(value: string): string[];
+/**
+ * A scrubber for loose values that are not vault entries (a one-time code, AGENT-TOOLS 1.14 §20.4): each shows as `token`.
+ * The same forms and the same minimum length as a vault value.
+ */
+export declare function looseScrubber(values: readonly string[], token: string): (text: string) => string;
+/**
+ * One scrubber over the values of several stores (the current one and the ones a reload retired): every value is matched against the
+ * ORIGINAL text in one pass and the spans are merged leftmost-longest, so a value two stores share a prefix, a suffix or a middle
+ * of is never half-scrubbed by the other one. Each value keeps its own entry's placeholder.
+ */
+export declare function combinedRedact(stores: readonly AccountStore[], codes?: {
+    values: readonly string[];
+    token: string;
+}): (text: string) => string;
+/** The registered one-time codes, as the one matcher needs them: the codes (the same array until one is added) and their placeholder. */
+export interface CodeSource {
+    values(): readonly string[];
+    readonly token: string;
+    redact(text: string): string;
+}
+/** A store that also scrubs every retired store's values (redaction is cumulative for a session, section 20.3), in one matcher. */
+export declare function historyStore(current: AccountStore, retired: readonly AccountStore[]): AccountStore;
+/**
+ * Scrubs a text of every vault value (current and retired) AND every registered one-time code with ONE matcher over the original
+ * text, never one scrubber after another: where a code and a vault value overlap, the longer complete match wins. The matcher is
+ * cached until a code is registered or the vault's stores change.
+ */
+export declare function redactAll(store: AccountStore | null | undefined, codes: CodeSource, text: string): string;
+/** The store of a version 1 file (the accounts of §18.6). */
 export declare function accountStore(file: AccountsFile): AccountStore;
+/** The store of a version 2 file (§20.1). */
+export declare function vaultStore(file: VaultFile): AccountStore;
 /**
- * Reads the accounts file. Inside a git work tree that doesn't ignore it, nothing is read or loaded. A file that can't
- * be read or isn't the format throws a plain message that never quotes the file (it holds secrets).
+ * Reads the vault file. A plain file inside a git work tree that doesn't ignore it is not loaded (a protected file holds no
+ * value, so that rule doesn't apply to it). A protected file that can't be opened loads nothing and says why. A file that
+ * can't be read or isn't the format throws a plain message that never quotes the file (it holds secrets).
  */
-export declare function loadAccounts(file: string, probe?: GitProbe): Promise<AccountsLoad>;
+export declare function loadAccounts(file: string, probe?: GitProbe, deps?: VaultDeps, signal?: AbortSignal): Promise<AccountsLoad>;
 /**
  * Scrubs every string in a JSON value (an app's answer), keeping its shape. Property names are scrubbed too; two names
  * that come out the same stay apart with a numbered suffix.
  */
 export declare function redactValue(value: unknown, redact: (text: string) => string): unknown;
+/**
+ * The backstop at a writer of files (§20.3): scrubs the content values of a JSON value, never its keys, so a script keeps
+ * its tool names and its `${vault.home.street}` placeholders.
+ */
+export declare function redactContent(value: unknown, redact: (text: string) => string): unknown;
+/** Whether a text refers to the vault (`${account.…}`, `${vault.…}`) or to a one-time code (`${otp.<app>}`, §20.4). */
+export declare function mentionsVault(text: string): boolean;
+/** What a reference named: which entry and field, and its kind. */
+export interface VaultUse {
+    name: string;
+    kind: VaultKind;
+    field: string;
+}
 export type AccountText = {
     ok: true;
     text: string;
-    field: AccountField | null;
+    field: string | null;
+    use?: VaultUse;
 } | {
     ok: false;
     code: "not_found" | "bad_params";
     message: string;
 };
 /**
- * `${account.username}` or `${account.password}` becomes the value, but only when it is the whole text: joined with
- * other text it could get a password past the secure-field rule. Text without a placeholder passes unchanged (field null).
+ * `${account.username}`, `${account.password}` or `${vault.<name>.<field>}` becomes the value, but only when it is the whole
+ * text: joined with other text it could get a password past the secure-field rule. Text without a reference passes unchanged
+ * (field null).
  */
 export declare function substituteAccount(text: string, store: AccountStore, name: string | undefined, appId: string): AccountText;