@amalgm/shell 0.1.113 → 0.1.115

package/PURPOSE.md

@@ -13,7 +13,9 @@ shell only assembles.
 
 2. **Bricks arrive through the registry.** Every `@amalgm/*` dependency is a
    published npm version — never a `file:` link, never a copied source tree.
-   Upgrading the runtime means bumping a version, not merging code.
+   Upgrading the runtime means bumping a version, not merging code. Registry
+   proof runs under the supported Node executable that launched the gate;
+   ambient package-manager shims are not runtime evidence.
 
 3. **Parity gates each released service.** The target begins with
    `amalgm-engine`'s runtime surface, then subtracts only owner-approved
@@ -45,8 +47,8 @@ shell only assembles.
 
 8. **The shell is the production runtime for its signed release.** The `amalgm`
    bootstrap may install, supervise, and update the shell, but it never starts
-   an Engine implementation of Core or Files beside it or falls back to copied
-   Engine behavior. The current release is deliberately Core + Files only.
+   an Engine implementation beside it or falls back to copied Engine behavior.
+   The current release is Core + Files + Agents + Tools + Chat.
 
 9. **Login is Core followed by Live.** Core owns authentication, credential
    separation, installation verification, restart proof, and readiness. Its
@@ -209,6 +211,13 @@ shell only assembles.
     declared cargo is bounded, Shell supplies the cached manifest and blocks to
     Live for the same submit frame; otherwise it uses the ordinary missing-block
     effect. The cloud, not Shell, owns the final seal-before-number decision.
+    Cache bytes remain only while an unresolved durable operation names their
+    content head or while the current verified text or repository head is the
+    one exact base for that entity's next delta. Once Send acceptance is
+    durable, Shell removes every sealed artifact and manifest that neither a
+    pending Record nor a current replay base retains; restart performs the same
+    derivation from SQLite, so accepted history cannot accumulate as machine
+    storage.
 
 25. **Each cold stage performs only its necessary byte pass.** Registration
     reads every ordinary text or binary file once through the bounded capture
@@ -695,10 +704,62 @@ shell only assembles.
     across restart, and all pre-page journal shapes convert atomically without
     dropping an unknown authority outcome.
 
+60. **Runtime binding is proved, never inferred.** A platform adapter adopts
+    an existing runtime only when Shell's published loopback address answers
+    its authenticated health probe for the selected user and runtime label. A
+    durable ready registration with no answering runtime may be resumed; an
+    absent or incomplete registration requires login. A UI marker, PID, open
+    port, or installed executable alone is never service readiness.
+
+61. **Browser is composed once and driven through capability ports.** Shell
+    owns the one `BrowserService` composition for a machine runtime. A fresh,
+    private Electron host may supply Browser's visible driver and isolated
+    cookie adapter; without that capability Browser selects headless. Shell
+    never implements a second browser action, registry, profile, cookie, or
+    authentication authority, and a Browser session never changes backend. A
+    signed machine release that does not declare Browser must not instantiate
+    Browser state merely because the SDK is installed.
+
+62. **PTY is one authenticated Shell host capability.** The running machine
+    runtime mounts the Core-owned PTY contract through Shell's native process
+    adapter and closes every spawned process with that runtime. A UI targeting
+    this computer connects through the published authenticated loopback
+    binding; only a different computer uses the remote relay. Electron never
+    creates a second PTY implementation. A session with no explicit working
+    directory starts at that signed-in user's portable Amalgm root.
+
+63. **Chat has one execution path.** Agents resolves an installed identity and
+    exact immutable revision; Tools resolves the selected catalog revision;
+    Chat owns the conversation, provider pump, journal, reconnect, usage, and
+    interrupt. Shell mounts Chat's public HTTP adapter in both `bootShell` and
+    the signed `MachineHost`; it owns no session store, event translation, or
+    callback driver.
+
+64. **One installation device key and broker serve every local product.**
+    Before registration, Shell creates one P-256 private key for the physical
+    installation, binds its public thumbprint into the approved setup intent,
+    and proves possession before pinning that thumbprint across the computer's
+    runtime labels. The key stays in macOS Keychain or a Windows DPAPI envelope
+    where available (or one mode-0600 fallback file). A registered runtime
+    treats missing or corrupt key material as a visible failure; it never
+    generates a replacement during startup. Replacement is an explicit,
+    browser-approved recovery: Shell stages one candidate, proves its private
+    key, reuses it across uncertain retries, and promotes it only after the
+    control plane conditionally accepts the server-derived prior thumbprint.
+    Shell mints short-lived grants through Core's broker and creates a fresh
+    DPoP proof for each request. Chat, Apps, and future products never receive
+    the key or durable machine credential.
+
+65. **A Shell release is tested as the artifact users install.** The release
+    gate packs Shell, installs that tarball with the exact public Amalgm
+    dependency versions declared by its manifest, and exercises authorization
+    through Chat using package exports only. Sibling repositories and source
+    paths are never an integration-test dependency.
+
 ## Relationship to amalgm-engine
 
 Stage 1 cut the bricks out of the engine. Stage 2 proves them here, composed.
 Stage 3 ships each signed service from this shell and retires its Engine copy.
-The first production release is the closed Core + Files login/registration
-slice; later services cross the same parity gate without creating a second
-runtime for anything already released.
+The current signed release is Core + Files + Agents + Tools + Chat. Later
+services cross the same parity gate without creating a second runtime for
+anything already released.

package/README.md

@@ -1,18 +1,22 @@
 # @amalgm/shell
 
-The Amalgm runtime, assembled from published `@amalgm/*` SDK bricks instead of
-the monolith. This repo is the composition and parity ground for the
-lego-driven rewrite of `amalgm-engine` — see [PURPOSE.md](PURPOSE.md) for the
-axioms.
+The Amalgm runtime, assembled from published `@amalgm/*` SDK capabilities.
+This repository owns their host composition; see [PURPOSE.md](PURPOSE.md) for
+the axioms.
 
-The first signed production release is intentionally Core + Files: Core owns
-machine login and readiness, Live owns the portable entity graph, and Shell
-injects the real filesystem, SQLite, watcher, and authenticated cloud wire.
+The signed runtime composes Core + Files + Agents + Tools + Chat. Agents owns
+identity and immutable revision resolution; Chat alone owns durable
+conversations, turns, reconnect, and interrupt; Shell supplies the host effects
+and one authenticated `/chat` protocol.
 
 ## Layout
 
 - `src/boot.ts` — assembles the HTTP/MCP runtime from bricks.
 - `src/machine-host.ts` — production effects injected into Core's machine setup.
+- `src/runtime-command-host.ts` — authenticated loopback publication and the
+  read-only runtime-health contract used by platform adapters.
+- `src/authorization/` — the installation device key, UI issuance adapter, and
+  Core credential-broker composition shared by local products.
 - `src/user-ground-host.ts` — production effects injected into Live registration.
 - `src/wire-client.ts` — the single authenticated gateway control path.
 - `src/content-direct.ts` — authorized direct-R2 download and local envelope opening.
@@ -20,12 +24,24 @@ injects the real filesystem, SQLite, watcher, and authenticated cloud wire.
   health, and retry; portable Watch law remains in `@amalgm/live`.
 - `tests/` — parity, adapter, restart, watcher, and two-device examinations.
 
+Authorization issuers must be HTTPS origins outside loopback development,
+credential-bearing redirects are rejected, and missing or unreadable stored
+key material fails closed rather than silently rotating a server-pinned
+identity. Recovery stages a separate candidate, requires browser approval and
+candidate-key proof, and promotes only the server-accepted key.
+Consumers use the contained `@amalgm/shell/authorization` export; importing
+authorization does not load unrelated native runtime adapters.
+
 ## Run
 
 ```bash
 npm install
 npm test
 
+# Pack Shell, install its exact released Amalgm dependencies in isolation,
+# and exercise issuance, renewal, revocation, Chat egress, and key recovery.
+npm run test:released-package
+
 # Isolated real-kernel Watch certification (macOS/Linux/Windows)
 AMALGM_NATIVE_WATCH=1 node --test tests/watching/native.test.js
 
@@ -37,6 +53,12 @@ npx --package @amalgm/shell amalgm login --no-open
 # Resume one user on a machine that has several
 npx --package @amalgm/shell amalgm run --user person@example.com
 
+# Inspect registration and authenticated runtime health without starting either
+npx --package @amalgm/shell amalgm status --user person@example.com
+
+# Explicitly recover a missing, corrupt, or server-rejected device key
+npx --package @amalgm/shell amalgm auth recover --user person@example.com
+
 # In another shell, declare an external workspace; the running Watch performs registration
 npx --package @amalgm/shell amalgm files register ./project --user person@example.com
 
@@ -46,6 +68,15 @@ npx --package @amalgm/shell amalgm files add <workspace-id> --user person@exampl
 
 Requires Node ≥ 20.19 (native `require(esm)` support; all bricks are ESM).
 
+Package releases use `.github/workflows/publish-package.yml`. A reviewed main
+commit is tagged exactly `v<package version>`; trusted npm publishing stages
+that package, and a maintainer approves the staged artifact with 2FA. Manual
+dirty-worktree publishing is not a release path. The release workflow also
+installs the packed Shell in a clean temporary project and runs the public
+authorization/Chat E2E against the exact registry versions in `package.json`.
+The published `npm-shrinkwrap.json` fixes the complete dependency tree, and
+that examination rejects any installed direct dependency that differs from it.
+
 Every push to `main` and every pull request runs the complete suite plus the
 isolated real-kernel Watch examination on GitHub-hosted Linux, macOS, and
 Windows machines. This certifies the same create, change, rename, move, delete,

package/dist/authorization/device-key.d.ts

@@ -0,0 +1,19 @@
+import { type JsonWebKey } from "node:crypto";
+import { type DpopSignerPort } from "@amalgm/core/authorization";
+import type { DeviceKeyStore, StoredDeviceKey } from "./key-store.js";
+export interface DeviceKey extends DpopSignerPort {
+    readonly publicJwk: JsonWebKey;
+}
+export declare function loadDeviceKey(store: DeviceKeyStore, ports?: Readonly<{
+    nowMs?: () => number;
+    randomUuid?: () => string;
+}>): Promise<DeviceKey>;
+export declare function requireDeviceKey(store: DeviceKeyStore, ports?: Readonly<{
+    nowMs?: () => number;
+    randomUuid?: () => string;
+}>): Promise<DeviceKey>;
+export declare function generateStoredDeviceKey(): StoredDeviceKey;
+export declare function deviceKeyFromStored(stored: StoredDeviceKey, ports: Readonly<{
+    nowMs?: () => number;
+    randomUuid?: () => string;
+}>): DeviceKey;

package/dist/authorization/device-key.js

@@ -0,0 +1,81 @@
+import { createHash, createPrivateKey, generateKeyPairSync, randomUUID, sign, } from "node:crypto";
+import { normalizeDpopHtu, normalizeDpopMethod, } from "@amalgm/core/authorization";
+export async function loadDeviceKey(store, ports = {}) {
+    let stored = await store.load();
+    if (!stored) {
+        stored = generateStoredDeviceKey();
+        await store.save(stored);
+    }
+    return deviceKeyFromStored(stored, ports);
+}
+export async function requireDeviceKey(store, ports = {}) {
+    const stored = await store.load();
+    if (!stored) {
+        throw Object.assign(new Error("Stored authorization key is missing"), {
+            code: "authorization_key_missing",
+        });
+    }
+    return deviceKeyFromStored(stored, ports);
+}
+export function generateStoredDeviceKey() {
+    const { privateKey } = generateKeyPairSync("ec", { namedCurve: "P-256" });
+    return Object.freeze({
+        version: 1,
+        privateJwk: privateKey.export({ format: "jwk" }),
+    });
+}
+export function deviceKeyFromStored(stored, ports) {
+    const privateJwk = stored.privateJwk;
+    if (stored.version !== 1
+        || privateJwk.kty !== "EC"
+        || privateJwk.crv !== "P-256"
+        || !privateJwk.x
+        || !privateJwk.y
+        || !privateJwk.d) {
+        throw new Error("Stored authorization key is not a P-256 private JWK");
+    }
+    const publicJwk = Object.freeze({
+        kty: "EC",
+        crv: "P-256",
+        x: privateJwk.x,
+        y: privateJwk.y,
+    });
+    const keyThumbprint = base64url(createHash("sha256").update(JSON.stringify({
+        crv: publicJwk.crv,
+        kty: publicJwk.kty,
+        x: publicJwk.x,
+        y: publicJwk.y,
+    })).digest());
+    const privateKey = createPrivateKey({ key: privateJwk, format: "jwk" });
+    return Object.freeze({
+        publicJwk,
+        keyThumbprint,
+        signProof: async (input) => {
+            const header = base64url(JSON.stringify({
+                typ: "dpop+jwt",
+                alg: "ES256",
+                jwk: publicJwk,
+            }));
+            const payload = base64url(JSON.stringify({
+                htm: normalizeDpopMethod(input.method),
+                htu: normalizeDpopHtu(input.url),
+                iat: Math.floor((ports.nowMs?.() ?? Date.now()) / 1000),
+                jti: ports.randomUuid?.() ?? randomUUID(),
+                ...(input.accessToken ? { ath: tokenHash(input.accessToken) } : {}),
+            }));
+            const signingInput = `${header}.${payload}`;
+            const signature = sign("sha256", Buffer.from(signingInput), {
+                key: privateKey,
+                dsaEncoding: "ieee-p1363",
+            });
+            return `${signingInput}.${base64url(signature)}`;
+        },
+    });
+}
+function tokenHash(token) {
+    return base64url(createHash("sha256").update(token).digest());
+}
+function base64url(value) {
+    return Buffer.from(value).toString("base64url");
+}
+//# sourceMappingURL=device-key.js.map

package/dist/authorization/device-key.js.map

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

package/dist/authorization/index.d.ts

@@ -0,0 +1,65 @@
+import { CredentialBroker } from "@amalgm/core/authorization";
+import type { DeviceKeyStore } from "./key-store.js";
+import { type DeviceKeyRecoveryStores } from "./recovery.js";
+export { requestAuthorizationKeyRecovery } from "./recovery-client.js";
+export type { AuthorizationRecoveryClientOptions } from "./recovery-client.js";
+export interface ShellAuthorizationOptions {
+    /** Installation-scoped Shell state directory, shared by every local product. */
+    readonly stateDir: string;
+    readonly appUrl: string;
+    readonly computerAuthToken: string;
+    readonly computerId: string;
+    readonly deviceId: string;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly platform?: NodeJS.Platform;
+    readonly keyStore?: DeviceKeyStore;
+    readonly nowMs?: () => number;
+    readonly random?: () => number;
+}
+export declare function loadInstallationDeviceKey(options: Readonly<{
+    stateDir: string;
+    deviceId: string;
+    platform?: NodeJS.Platform;
+    keyStore?: DeviceKeyStore;
+    nowMs?: () => number;
+}>): Promise<import("./device-key.js").DeviceKey>;
+export declare function requireInstallationDeviceKey(options: Readonly<{
+    stateDir: string;
+    deviceId: string;
+    platform?: NodeJS.Platform;
+    keyStore?: DeviceKeyStore;
+    nowMs?: () => number;
+}>): Promise<import("./device-key.js").DeviceKey>;
+export declare function installationDeviceKeyStores(options: Readonly<{
+    stateDir: string;
+    deviceId: string;
+    platform?: NodeJS.Platform;
+    keyStore?: DeviceKeyStore;
+    recoveryKeyStore?: DeviceKeyStore;
+}>): DeviceKeyRecoveryStores;
+export declare function stageInstallationDeviceKeyRecovery(options: Readonly<{
+    stateDir: string;
+    deviceId: string;
+    platform?: NodeJS.Platform;
+    keyStore?: DeviceKeyStore;
+    recoveryKeyStore?: DeviceKeyStore;
+    nowMs?: () => number;
+}>): Promise<import("./device-key.js").DeviceKey>;
+export declare function promoteInstallationDeviceKeyRecovery(options: Readonly<{
+    stateDir: string;
+    deviceId: string;
+    acceptedKeyThumbprint: string;
+    platform?: NodeJS.Platform;
+    keyStore?: DeviceKeyStore;
+    recoveryKeyStore?: DeviceKeyStore;
+}>): Promise<import("./device-key.js").DeviceKey>;
+/** Compose one key and one live broker for every local product in this runtime. */
+export declare function createShellAuthorization(options: ShellAuthorizationOptions): Promise<CredentialBroker>;
+export { deviceKeyFromStored, generateStoredDeviceKey, loadDeviceKey, requireDeviceKey, } from "./device-key.js";
+export type { DeviceKey } from "./device-key.js";
+export { createDeviceKeyStore } from "./key-store.js";
+export type { DeviceKeyStore, StoredDeviceKey } from "./key-store.js";
+export { promoteDeviceKeyRecovery, stageDeviceKeyRecovery } from "./recovery.js";
+export type { DeviceKeyRecoveryStores } from "./recovery.js";
+export { createShellCredentialIssuer } from "./issuer.js";
+export type { ShellCredentialIssuerOptions } from "./issuer.js";

package/dist/authorization/index.js

@@ -0,0 +1,63 @@
+import { join } from "node:path";
+import { CredentialBroker } from "@amalgm/core/authorization";
+import { loadDeviceKey, requireDeviceKey } from "./device-key.js";
+import { createShellCredentialIssuer } from "./issuer.js";
+import { createDeviceKeyStore } from "./key-store.js";
+import { promoteDeviceKeyRecovery, stageDeviceKeyRecovery, } from "./recovery.js";
+export { requestAuthorizationKeyRecovery } from "./recovery-client.js";
+export async function loadInstallationDeviceKey(options) {
+    const store = options.keyStore ?? createDeviceKeyStore({
+        file: join(options.stateDir, "authorization", "device-key.json"),
+        account: `device:${options.deviceId}`,
+        ...(options.platform ? { platform: options.platform } : {}),
+    });
+    return loadDeviceKey(store, { nowMs: options.nowMs });
+}
+export async function requireInstallationDeviceKey(options) {
+    const stores = installationDeviceKeyStores(options);
+    return requireDeviceKey(stores.active, { nowMs: options.nowMs });
+}
+export function installationDeviceKeyStores(options) {
+    const platform = options.platform ? { platform: options.platform } : {};
+    return Object.freeze({
+        active: options.keyStore ?? createDeviceKeyStore({
+            file: join(options.stateDir, "authorization", "device-key.json"),
+            account: `device:${options.deviceId}`,
+            ...platform,
+        }),
+        pending: options.recoveryKeyStore ?? createDeviceKeyStore({
+            file: join(options.stateDir, "authorization", "device-key-recovery.json"),
+            account: `device:${options.deviceId}:recovery`,
+            ...platform,
+        }),
+    });
+}
+export async function stageInstallationDeviceKeyRecovery(options) {
+    return stageDeviceKeyRecovery(installationDeviceKeyStores(options), { nowMs: options.nowMs });
+}
+export async function promoteInstallationDeviceKeyRecovery(options) {
+    return promoteDeviceKeyRecovery(installationDeviceKeyStores(options), options.acceptedKeyThumbprint);
+}
+/** Compose one key and one live broker for every local product in this runtime. */
+export async function createShellAuthorization(options) {
+    const signer = await requireInstallationDeviceKey(options);
+    const issuer = createShellCredentialIssuer({
+        appUrl: options.appUrl,
+        computerAuthToken: options.computerAuthToken,
+        computerId: options.computerId,
+        deviceId: options.deviceId,
+        signer,
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+    });
+    return new CredentialBroker({
+        issuer,
+        signer,
+        nowMs: options.nowMs ?? (() => Date.now()),
+        random: options.random ?? (() => Math.random()),
+    });
+}
+export { deviceKeyFromStored, generateStoredDeviceKey, loadDeviceKey, requireDeviceKey, } from "./device-key.js";
+export { createDeviceKeyStore } from "./key-store.js";
+export { promoteDeviceKeyRecovery, stageDeviceKeyRecovery } from "./recovery.js";
+export { createShellCredentialIssuer } from "./issuer.js";
+//# sourceMappingURL=index.js.map

package/dist/authorization/index.js.map

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

package/dist/authorization/issuer.d.ts

@@ -0,0 +1,11 @@
+import type { CredentialIssuerPort, DpopSignerPort } from "@amalgm/core/authorization";
+export interface ShellCredentialIssuerOptions {
+    readonly appUrl: string;
+    readonly computerAuthToken: string;
+    readonly computerId: string;
+    readonly deviceId: string;
+    readonly clientId?: string;
+    readonly signer: DpopSignerPort;
+    readonly fetch?: typeof globalThis.fetch;
+}
+export declare function createShellCredentialIssuer(options: ShellCredentialIssuerOptions): CredentialIssuerPort;

package/dist/authorization/issuer.js

@@ -0,0 +1,76 @@
+export function createShellCredentialIssuer(options) {
+    const endpoint = `${authorizationOrigin(options.appUrl)}/api/authorization/v1/tokens`;
+    const request = options.fetch ?? globalThis.fetch;
+    return {
+        issue: async (grant) => {
+            const proof = await options.signer.signProof({ method: "POST", url: endpoint });
+            const response = await request(endpoint, {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${options.computerAuthToken}`,
+                    "content-type": "application/json",
+                    dpop: proof,
+                },
+                redirect: "error",
+                body: JSON.stringify({
+                    computer_id: options.computerId,
+                    device_id: options.deviceId,
+                    client_id: options.clientId ?? "amalgm-shell",
+                    audience: grant.audience,
+                    scopes: grant.scopes,
+                }),
+            });
+            const body = await response.json().catch(() => ({}));
+            if (!response.ok) {
+                throw Object.assign(new Error(text(body.error) || "Access credential issuance failed"), {
+                    code: text(body.code) || `authorization_http_${response.status}`,
+                    status: response.status,
+                });
+            }
+            return issuedCredential(body, grant.keyThumbprint);
+        },
+    };
+}
+function authorizationOrigin(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new TypeError("appUrl must be an HTTPS origin");
+    }
+    const local = url.hostname === "localhost" || url.hostname === "127.0.0.1";
+    if ((url.protocol !== "https:" && !(local && url.protocol === "http:"))
+        || url.username
+        || url.password
+        || url.search
+        || url.hash
+        || url.pathname !== "/")
+        throw new TypeError("appUrl must be an HTTPS origin");
+    return url.origin;
+}
+function issuedCredential(body, keyThumbprint) {
+    const accessToken = text(body.access_token);
+    const audience = text(body.audience);
+    const scopes = Array.isArray(body.scopes)
+        ? body.scopes.filter((scope) => typeof scope === "string")
+        : [];
+    const expiresAtMs = Date.parse(text(body.expires_at));
+    if (!accessToken || body.token_type !== "DPoP" || !audience || scopes.length === 0 || !Number.isFinite(expiresAtMs)) {
+        throw Object.assign(new Error("Authorization server returned an invalid credential"), {
+            code: "invalid_authorization_response",
+        });
+    }
+    return Object.freeze({
+        accessToken,
+        tokenType: "DPoP",
+        audience,
+        scopes: Object.freeze(scopes),
+        expiresAtMs,
+        keyThumbprint,
+    });
+}
+function text(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+//# sourceMappingURL=issuer.js.map

package/dist/authorization/issuer.js.map

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

package/dist/authorization/key-store.d.ts

@@ -0,0 +1,15 @@
+import type { JsonWebKey } from "node:crypto";
+export interface StoredDeviceKey {
+    readonly version: 1;
+    readonly privateJwk: JsonWebKey;
+}
+export interface DeviceKeyStore {
+    load(): Promise<StoredDeviceKey | null>;
+    save(key: StoredDeviceKey): Promise<void>;
+    remove(): Promise<void>;
+}
+export declare function createDeviceKeyStore(input: Readonly<{
+    file: string;
+    account: string;
+    platform?: NodeJS.Platform;
+}>): DeviceKeyStore;