@yadsh/dsh-qa-surface 0.3.0 → 0.4.0

package/README.md

@@ -16,7 +16,8 @@ Session and Agent Loop.
 - optionally shows a minimal per-browser chat-history sidebar
   (`ui.showSessionList`) whose switching re-runs policy attestation;
 - blocks unsupported approvals/questions instead of auto-approving them;
-- pins locked sessions to `read-only` + `approval=never` before Send is enabled;
+- pins locked sessions to the configured `read-only` or isolated
+  `workspace-write` policy plus `approval=never` before Send is enabled;
 - applies a Host-side tool allow-list plus a monotonic execution guard;
 - optionally gates the surface behind email + password accounts
   (`accounts.enabled`) with server-side session ownership, a first-login
@@ -26,6 +27,10 @@ Session and Agent Loop.
 - optionally redirects non-loopback hostnames from the harness root into the
   QA route (`entry.redirectNonLoopback`), keeping the operator's localhost
   harness UI untouched;
+- ships an operator settings card (Settings → Plugins → plugin configuration →
+  «Помощник QA») that edits the `qa-surface` namespace in place — route,
+  branding, session, interface, lockdown, accounts, sources, embedding — and
+  reports the configuration the running Host resolved;
 - uses the existing same-origin DSH connection and trust boundary.
 
 It does not add another HTTP server, provider proxy, permissive CORS rule, or
@@ -64,6 +69,17 @@ Configuration is registered under the Host settings namespace `qa-surface`.
 Composition values form the base layer; normal DSH user settings can override
 them when the deployment provides writable settings.
 
+The browser half carries a settings card for that namespace: **Settings →
+Plugins → plugin configuration → «Помощник QA»**. It writes the user layer of
+`qa-surface` — so every change is revertible through the card's own reset — and
+shows the configuration the running Host resolved next to it. Combinations the
+Host refuses are either written together in one mutation (a provider with its
+model, per-user workspaces with the `workspace-write` sandbox) or disabled with
+the reason stated. The card renders only where the settings namespace is
+readable, which the DSH gateway pins to loopback; a browser served over the LAN
+reads the same configuration read-only through `qaSurface/describe` on the QA
+page itself.
+
 ```yaml
 config:
   enabled: true
@@ -96,16 +112,35 @@ config:
     showToolActivity: false
     showReasoning: false
     renderMarkdown: true
-    maxContentWidth: 900
+    minContentWidth: 650
     showSessionList: false
   accounts:
     enabled: false
     allowRegistration: true
     sessionTtlDays: 30
     showOtherUsersChats: false
+    perUserWorkspace: false
+    profile:
+      enabled: true
+      inject: true
+      identities: [] # e.g. [{ key: jira, label: Jira }]
+      instructionsMaxLength: 2000
   suggestedQuestions:
     - Как запросить доступ?
     - Где лежит инструкция?
+  # Phrases the running indicator cycles through (optional). An empty list
+  # restores the built-in ones.
+  thinkingPhrases:
+    - Уточняю по регламенту…
+    - Сверяюсь с инструкцией…
+  # What a visitor may attach (optional). Files are staged on the Host and
+  # read from the stored copy, so keep `read` in lockdown.toolPolicy.allow.
+  attachments:
+    textFiles: true
+    pastedTextLines: 200
+    maxFileBytes: 10485760
+    maxPending: 8
+    extensions: [md, txt, log, json, yaml, csv, sql]
   interaction:
     approvals: blocked
     questions: unsupported
@@ -166,6 +201,44 @@ uses the Host's normal default working directory. Put the system prompt, tools,
 skills, knowledge connections and permission policy in `agentPreset`, not in
 this UI plugin.
 
+### Writable per-user research space
+
+Set `accounts.perUserWorkspace: true` only together with accounts, a registered
+`session.workspaceId`, `lockdown.enforceFixedWorkspace: true`, and a
+`workspace-write` + `never` permission preset:
+
+```yaml
+session:
+  workspaceId: "<registered-workspace-uuid>"
+accounts:
+  enabled: true
+  perUserWorkspace: true
+lockdown:
+  enabled: true
+  enforceFixedWorkspace: true
+  sandboxMode: workspace-write
+  approvalPolicy: never
+  permissionPreset: qa-workspace-write
+  toolPolicy:
+    mode: allow-list
+    allow: [read, read_image, glob, grep, write, edit, web_search, web_fetch]
+```
+
+The Host resolves that Workspace record's path and creates
+`<workspace>/.qa-users/<account UUID>` with private Unix directory mode. It
+passes the child as session `cwd` but deliberately does not register or attach
+it as another DSH Workspace. Chats therefore remain ordinary entries in the
+global DSH session list rather than creating one Workspace row per account.
+
+The boundary combines DSH `workspace-write` with a Host tool guard for both
+read and write paths, canonicalizes existing ancestors to reject symlink
+escapes, propagates the root to subagent sessions, rejects shell/process/LSP
+and `dsh_git_*` escape hatches, limits one model-controlled write to 10 MiB,
+and limits an account directory to 256 MiB. `web_fetch` plus `write` is the
+intended bounded research-download path; there is no unrestricted URL-to-disk
+or shell downloader. Account directories are persistent scratch space and are
+not deleted automatically.
+
 Model override is opt-in: `provider` and `model` must be set together. Slash
 commands are rejected as plain QA input. Reasoning and tool details remain
 hidden by default. Enabling `ui.showReasoning` and `ui.showToolActivity` adds a
@@ -174,6 +247,42 @@ then collapses to `Worked for ...` before the final answer. Tool capability is
 still controlled exclusively by `lockdown.toolPolicy.allow`; the display flags
 do not grant tools.
 
+### User profile
+
+Clicking the account name in the sidebar footer opens the signed-in user's
+profile: full name, one handle per external system the deployment declares,
+and free-form instructions about how they want answers. The Host hands both
+to the QA agent as a note in the conversation, so "покажи мои задачи" resolves
+to a tracker lookup with the right login instead of a question. Because a QA
+preset can declare its persona the complete system prompt (the shipped
+`qa-research` one does, which discards every plugin prompt section), the note
+travels as injected context on the conversation instead of as prompt text. It
+is written once per profile, and subagents of the chat get their own copy.
+Values are self-declared and the note says so: the agent names the identifier
+it searched by and asks when the results contradict the request. The feature
+needs no switch beyond accounts, though `accounts.profile.enabled` and
+`inject` exist for deployments that want the form without the note, or
+neither:
+
+```yaml
+accounts:
+  enabled: true
+  profile:
+    identities:
+      - key: jira
+        label: Jira
+      - key: gitlab
+        label: GitLab
+    instructionsMaxLength: 2000
+```
+
+`qa-accounts profile <email>` fills the same fields from an operator shell
+(`--identity jira=i.ivanov`, `--instructions-file`, `--clear-identity`), which
+is how a fresh deployment gets everyone's handles in place before users log
+in. See
+[Configuration](https://github.com/xarleyn/dsh-plugins/blob/main/plugins/dsh-qa-surface/docs/CONFIGURATION.md)
+for the limits and the prompt's exact wording.
+
 Session policies:
 
 - `browser-persistent` restores the id stored in this browser, replacing stale
@@ -200,8 +309,9 @@ Sources are structured Host-owned provenance, independent of
 `ui.showToolActivity`. Successful reads/fetches, bounded web-search evidence,
 Jira/Confluence/knowledge results, and inherited subagent sources are
 normalized and deduplicated into one turn bundle. That exact bundle feeds the
-answer footer and grouped drawer and is persisted as `qa/sources`, so reload
-does not rerun tools. Search-only discovery stays hidden by default.
+answer footer and the right rail's sources tab and is persisted as
+`qa/sources`, so reload does not rerun tools. Search-only discovery stays
+hidden by default.
 
 Local file cards open a source-scoped, read-only preview after Host-side real
 path validation against the attested session root. Markdown opens rendered by
@@ -213,8 +323,8 @@ Observable local subagents are inherited recursively. The internal
 `qa_report_sources` tool covers opaque delegated providers and is admitted as
 a provenance-only capability even when it is not listed among ordinary QA
 tools. A provider that neither exposes events nor reports sources marks the
-turn provenance incomplete. The QA prompt tells models not to append a manual
-`Sources`/`Источники` bibliography.
+turn provenance incomplete. A note in the conversation tells the model not to
+append a manual `Sources`/`Источники` bibliography.
 
 Images: the composer accepts PNG/JPEG/WebP/GIF via drag & drop onto the
 composer, paste, and the picker button, several at once (soft client caps:
@@ -223,6 +333,30 @@ promotes to durable attachments, so they survive reloads; sent images
 render as clickable thumbnails on the message. Whether the model can see
 them depends on the deployment's model (vision).
 
+Attachments: the same picker, drop zone and paste path also take text files
+(`md`, `txt`, `log`, and the other extensions in `attachments.extensions`), and
+pasted text longer than `attachments.pastedTextLines` (default 200) becomes an
+attachment named after its line count instead of filling the input field. A
+file is staged on the Host through the browser upload service and the prompt
+cites the returned receipt, so the durable copy survives reloads; the transcript
+shows it as an extension badge, its name and its size. Unlike an image, a file
+reaches the model as the path of that stored copy rather than as content, so
+`lockdown.toolPolicy.allow` has to keep `read` for an attachment to be usable.
+`attachments.textFiles: false` restricts the composer to images again, while
+`maxFileBytes` and `maxPending` cap one file and the combined number of images
+plus files per message.
+
+The right rail is the chat's side panel, mirroring the Harness right Sidebar's
+pattern: a tab strip is the panel's whole top edge, and the strip's close
+control collapses the column. The sources tab carries the grouped list and
+preview the sources drawer used to render — a message footnote opens it pinned
+to that answer's subset, and «Все источники» returns to the whole chat. The
+«Файлы» tab (header button with a live count) lists every attachment this chat
+sent, grouped per message newest first, with the same file handles the
+transcript shows and image thumbnails resolved from the session's asset
+repository; each group jumps back to its message. Below 600px the rail goes
+full-bleed. The agents drawer keeps its own header drawer for now.
+
 Subagents: the deployment may opt the delegation family (`subagent`,
 `subagent_fork`, `send_message`, `list_agents`, `interrupt_agent`) into the
 lockdown allow-list; the preset must mount them. Launches then render as
@@ -259,7 +393,9 @@ scope, and local in-contour model processing. Explicit acknowledgement is
 stored as a versioned browser-local flag; changing the disclosure version
 shows it again. Other DSH routes retain the stock onboarding entry.
 
-Locked mode requires a deployment permission preset named `qa-read-only`.
+The default locked mode requires a deployment permission preset named
+`qa-read-only`. Per-user writable mode uses a separate preset such as
+`qa-workspace-write`.
 Extend the existing `@deepseek-ai/dsh-permission-presets` row without changing
 its process-wide default:
 
@@ -282,9 +418,14 @@ its process-wide default:
         approval: never
         name: QA Read Only
         description: No filesystem mutations and no permission escalation.
+      qa-workspace-write:
+        sandbox: workspace-write
+        approval: never
+        name: QA User Workspace
+        description: Writes only inside the attested per-user workspace.
 ```
 
-The shipped tool allow-list is empty. Add only reviewed read-only tool names
+The shipped tool allow-list is empty. Add only reviewed tool names
 from the actual deployment. A name that is not registered fails closed. The
 Host restriction retains exact allow-listed tools from the agent preset's
 ancestor scope, and the additional execution guard also denies session-scoped
@@ -342,11 +483,11 @@ What a LAN deployment does not change:
   version in that browser's local storage. The stock DSH notice remains
   unchanged on operator routes.
 
-See [Configuration](docs/CONFIGURATION.md) for the config-channel details.
+See [Configuration](https://github.com/xarleyn/dsh-plugins/blob/main/plugins/dsh-qa-surface/docs/CONFIGURATION.md) for the config-channel details.
 
-See [Architecture](docs/ARCHITECTURE.md),
-[Configuration](docs/CONFIGURATION.md), and
-[Compatibility](docs/COMPATIBILITY.md).
+See [Architecture](https://github.com/xarleyn/dsh-plugins/blob/main/plugins/dsh-qa-surface/docs/ARCHITECTURE.md),
+[Configuration](https://github.com/xarleyn/dsh-plugins/blob/main/plugins/dsh-qa-surface/docs/CONFIGURATION.md), and
+[Compatibility](https://github.com/xarleyn/dsh-plugins/blob/main/plugins/dsh-qa-surface/docs/COMPATIBILITY.md).
 
 ## Develop
 

package/lib/account-remotes.js

@@ -0,0 +1,100 @@
+import { QaAccounts, QaAccountsError, defaultAccountsFilePath, } from "./accounts/store.js";
+const ACCOUNTS_DISABLED_ERROR = "QA accounts are not enabled on this deployment.";
+/** Build the account-remotes context for one `QaSurface` service instance. */
+export function createQaAccountRemotes(options) {
+    const { getConfig, logger } = options;
+    // Memoized across remotes: rebuilt only when the account-affecting options
+    // change; the file is shared across rebuilds.
+    let accounts;
+    let accountsOptions;
+    const resolve = (config) => {
+        if (!config.accounts.enabled)
+            return undefined;
+        const memoKey = JSON.stringify([
+            config.accounts.sessionTtlDays,
+            config.accounts.allowRegistration,
+            config.accounts.profile.instructionsMaxLength,
+            config.accounts.profile.identities,
+        ]);
+        if (accounts === undefined || accountsOptions !== memoKey) {
+            accounts = new QaAccounts(defaultAccountsFilePath(), {
+                sessionTtlDays: config.accounts.sessionTtlDays,
+                allowRegistration: config.accounts.allowRegistration,
+                instructionsMaxLength: config.accounts.profile.instructionsMaxLength,
+                identityFields: config.accounts.profile.identities,
+            });
+            accountsOptions = memoKey;
+        }
+        return accounts;
+    };
+    /** The accounts store, or the disabled refusal the browser maps to copy. */
+    const requireAccounts = () => {
+        const store = resolve(getConfig());
+        if (store === undefined) {
+            throw new Error(ACCOUNTS_DISABLED_ERROR);
+        }
+        return store;
+    };
+    const run = (operation, sessionIdForLog) => {
+        try {
+            return operation();
+        }
+        catch (error) {
+            if (error instanceof QaAccountsError) {
+                logger.warn("accounts.rejected", {
+                    reason: error.reason,
+                    sessionId: sessionIdForLog,
+                });
+                throw new Error(`QA accounts refused the request (reason: ${error.reason})`, {
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+    };
+    return {
+        resolve,
+        run,
+        register: (email, password) => {
+            const store = requireAccounts();
+            return run(() => store.register(email, password));
+        },
+        login: (email, password) => {
+            const store = requireAccounts();
+            return run(() => store.login(email, password));
+        },
+        whoami: (token) => {
+            if (!getConfig().accounts.enabled)
+                return { authenticated: false };
+            const store = requireAccounts();
+            return run(() => store.whoami(token));
+        },
+        claimSessions: (token, sessionIds) => {
+            const store = requireAccounts();
+            return run(() => store.claimSessions(token, sessionIds));
+        },
+        ownedSessions: (token) => {
+            if (!getConfig().accounts.enabled)
+                return { ids: [] };
+            const store = requireAccounts();
+            return run(() => ({ ids: store.ownedSessionIds(token) }));
+        },
+        listOwnership: (token) => {
+            if (!getConfig().accounts.enabled)
+                return { entries: [] };
+            const store = requireAccounts();
+            return run(() => ({ entries: store.listOwnership(token) }));
+        },
+        updateProfile: (token, input) => {
+            const config = getConfig();
+            const store = requireAccounts();
+            return run(() => {
+                if (!config.accounts.profile.enabled) {
+                    throw new QaAccountsError("profile-disabled", "self-service profiles are disabled on this deployment");
+                }
+                return store.updateOwnProfile(token, input);
+            });
+        },
+    };
+}
+//# sourceMappingURL=account-remotes.js.map

package/lib/account-remotes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-remotes.js","sourceRoot":"","sources":["../src/account-remotes.ts"],"names":[],"mappings":"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"}

package/lib/accounts/credentials.js

@@ -0,0 +1,27 @@
+import { QaAccountsError } from "./errors.js";
+const MIN_PASSWORD_LENGTH = 8;
+const MAX_PASSWORD_LENGTH = 200;
+const MAX_DISPLAY_NAME_LENGTH = 100;
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/u;
+/**
+ * The email/password/display-name gate shared by self-registration and the
+ * operator's addUser, so both paths reject unusable input with the same
+ * errors and messages, in the same order. Returns the normalized address and
+ * trimmed display name; the caller still decides uniqueness and role.
+ */
+export function validateCredentials(email, password, displayName) {
+    const normalized = email.trim().toLowerCase();
+    if (!EMAIL_PATTERN.test(normalized) || normalized.length > 254) {
+        throw new QaAccountsError("invalid-email", "email is not a usable address");
+    }
+    if (password.length < MIN_PASSWORD_LENGTH ||
+        password.length > MAX_PASSWORD_LENGTH) {
+        throw new QaAccountsError("weak-password", `password must be ${MIN_PASSWORD_LENGTH} to ${MAX_PASSWORD_LENGTH} characters`);
+    }
+    const name = (displayName ?? "").trim();
+    if (name.length > MAX_DISPLAY_NAME_LENGTH) {
+        throw new QaAccountsError("invalid-display-name", `display name must be at most ${MAX_DISPLAY_NAME_LENGTH} characters`);
+    }
+    return { email: normalized, displayName: name };
+}
+//# sourceMappingURL=credentials.js.map

package/lib/accounts/credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../../src/accounts/credentials.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAC9B,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAChC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AACpC,MAAM,aAAa,GAAG,6BAA6B,CAAC;AASpD;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAa,EACb,QAAgB,EAChB,WAA+B;IAE/B,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QAC/D,MAAM,IAAI,eAAe,CAAC,eAAe,EAAE,+BAA+B,CAAC,CAAC;IAC9E,CAAC;IACD,IACE,QAAQ,CAAC,MAAM,GAAG,mBAAmB;QACrC,QAAQ,CAAC,MAAM,GAAG,mBAAmB,EACrC,CAAC;QACD,MAAM,IAAI,eAAe,CACvB,eAAe,EACf,oBAAoB,mBAAmB,OAAO,mBAAmB,aAAa,CAC/E,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACxC,IAAI,IAAI,CAAC,MAAM,GAAG,uBAAuB,EAAE,CAAC;QAC1C,MAAM,IAAI,eAAe,CACvB,sBAAsB,EACtB,gCAAgC,uBAAuB,aAAa,CACrE,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;AAClD,CAAC"}

package/lib/accounts/errors.js

@@ -0,0 +1,9 @@
+export class QaAccountsError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "QaAccountsError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/lib/accounts/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/accounts/errors.ts"],"names":[],"mappings":"AAqBA,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAE7B,MAAM;IADjB,YACW,MAA6B,EACtC,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;sBAHN,MAAM;QAIf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF"}

package/lib/accounts/file.js

@@ -0,0 +1,101 @@
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { base64Url } from "./token.js";
+/** A stamp no real file can match, so the first load always reads the disk. */
+export function createFileStampRef() {
+    return { current: { mtimeMs: Number.NEGATIVE_INFINITY, size: -1 } };
+}
+export function stampOf(stat) {
+    return { mtimeMs: stat.mtimeMs, size: stat.size };
+}
+const SECRET_BYTES = 32;
+/** The accounts file lives next to the DSH home the launcher exports. */
+export function defaultAccountsFilePath() {
+    const home = process.env.DSH_HOME?.trim();
+    return path.join(home !== undefined && home !== "" ? home : process.cwd(), "qa-accounts.json");
+}
+/**
+ * Read the accounts file, or create it on first run with a fresh token
+ * secret. The stamp ref is left pointing at the version just read.
+ */
+export function loadAccountsFile(filePath, stamp) {
+    let raw;
+    let stat;
+    try {
+        raw = readFileSync(filePath, "utf8");
+        stat = statSync(filePath);
+    }
+    catch (error) {
+        // Only a missing file means "first run": anything else (permissions,
+        // a directory in the way, I/O failure) must surface, or the store
+        // would silently reset every account it cannot read.
+        if (error.code !== "ENOENT")
+            throw error;
+        const created = {
+            version: 1,
+            secret: base64Url(randomBytes(SECRET_BYTES)),
+            users: [],
+            ownership: {},
+        };
+        persistAccountsFile(filePath, created, stamp);
+        return created;
+    }
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        parsed.version !== 1 ||
+        typeof parsed.secret !== "string" ||
+        !Array.isArray(parsed.users)) {
+        throw new Error(`qa-accounts: ${filePath} is not a recognizable accounts file; refusing to overwrite it`);
+    }
+    const file = parsed;
+    if (stat !== undefined)
+        stamp.current = stampOf(stat);
+    return {
+        version: 1,
+        secret: file.secret,
+        users: file.users,
+        ownership: file.ownership ?? {},
+    };
+}
+/**
+ * Persist the accounts file atomically (temp file + rename) and leave the
+ * stamp ref pointing at the freshly written version.
+ */
+export function persistAccountsFile(filePath, file, stamp) {
+    mkdirSync(path.dirname(filePath), { recursive: true });
+    // A per-process temp name: the Host and the CLI never race on one file.
+    const temp = `${filePath}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(file, null, 2)}\n`, "utf8");
+    renameSync(temp, filePath);
+    stamp.current = stampOf(statSync(filePath));
+}
+/**
+ * The qa-accounts CLI runs in its own process against the same file. Re-read
+ * it whenever it changed on disk, before every read or read-modify-write:
+ * without this a running Host would keep honoring tokens the CLI revoked
+ * and its next save would resurrect the CLI's change from a stale snapshot.
+ * One file, one writer at a time remains the deployment's discipline; LAN
+ * scale keeps the stat per operation trivial.
+ *
+ * Returns the freshly loaded file, or undefined when the caller should keep
+ * serving its in-memory state.
+ */
+export function reloadAccountsFileIfChanged(filePath, stamp) {
+    let stat;
+    try {
+        stat = statSync(filePath);
+    }
+    catch {
+        // The file vanished between operations (never by our hand): keep
+        // serving the in-memory state instead of resetting every account.
+        return undefined;
+    }
+    if (stat.mtimeMs === stamp.current.mtimeMs &&
+        stat.size === stamp.current.size) {
+        return undefined;
+    }
+    return loadAccountsFile(filePath, stamp);
+}
+//# sourceMappingURL=file.js.map

package/lib/accounts/file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.js","sourceRoot":"","sources":["../../src/accounts/file.ts"],"names":[],"mappings":"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"}