toolcraft 0.0.310 → 0.0.312

package/composition.json

@@ -98,7 +98,7 @@
     },
     {
       "name": "tiny-http-mcp-server",
-      "version": "0.1.25",
+      "version": "0.1.29",
       "license": "MIT"
     },
     {
@@ -113,7 +113,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.310",
+      "version": "0.0.312",
       "license": "MIT"
     },
     {
@@ -123,7 +123,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.310",
+      "version": "0.0.312",
       "license": "MIT"
     },
     {

package/dist/composition.json

@@ -98,7 +98,7 @@
     },
     {
       "name": "tiny-http-mcp-server",
-      "version": "0.1.25",
+      "version": "0.1.29",
       "license": "MIT"
     },
     {
@@ -113,7 +113,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.310",
+      "version": "0.0.312",
       "license": "MIT"
     },
     {
@@ -123,7 +123,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.310",
+      "version": "0.0.312",
       "license": "MIT"
     },
     {

package/node_modules/auth-store/README.md

@@ -25,6 +25,22 @@ const value = await store.get(); // "secret-value"
 await store.delete();
 ```
 
+Both built-in backends expose `store.withLock(operation, { signal, timeoutMs })`
+for transactions spanning a read, external operation and write. Independent
+instances and processes serialize the same encrypted file or Keychain
+service/account; unrelated identities proceed independently. The default
+acquisition timeout is 30 seconds. Cancellation during acquisition does not
+release the active owner's lock. Individual `get`, `set` and `delete` calls do
+not implicitly acquire it.
+
+Locks use private filesystem claim directories, containing PID/random names
+and numeric tickets without credentials. Dead-owner claims are recovered;
+live claims are never stolen because of age. Empty directories remain so an
+arriving contender cannot race directory removal. Keychain lock storage defaults
+to `~/.auth-store/keychain-locks`; `keychainStore.lock` can select another
+directory or filesystem adapter. Injected encrypted-file adapters need
+`readdir` support when using transactions.
+
 ## Backends
 
 | `backendEnvVar` value | Platform | Backend        |
@@ -40,6 +56,10 @@ await store.delete();
 - Configurable salt, directory, and file name
 - File permissions: `0600`
 - Random IV per write
+- `fileStore.throwOnInvalidDocument: true` makes malformed or unauthenticated
+  existing documents fail with a safe diagnostic; missing files still return
+  `null`. The default treats invalid documents as absent. Strict reads preserve
+  the existing file until an explicit reset or replacement.
 
 ### macOS Keychain
 

package/node_modules/auth-store/dist/encrypted-file-store.d.ts

@@ -1,9 +1,11 @@
 import type { SecretStore } from "./types.js";
+import { type SecretStoreLockOptions } from "./transaction-lock.js";
 export interface MachineIdentity {
     hostname: string;
     username: string;
 }
 export interface EncryptedFileStoreFileSystem {
+    readdir?(path: string): Promise<string[]>;
     readFile(path: string, encoding: BufferEncoding): Promise<string>;
     writeFile(path: string, data: string | NodeJS.ArrayBufferView, options?: {
         encoding?: BufferEncoding;
@@ -29,6 +31,8 @@ export interface EncryptedFileStoreInput {
     getMachineIdentity?: () => MachineIdentity | Promise<MachineIdentity>;
     getHomeDirectory?: () => string;
     getRandomBytes?: (size: number) => Buffer;
+    /** Fail closed instead of treating malformed or unauthenticated documents as absent. */
+    throwOnInvalidDocument?: boolean;
 }
 export declare class EncryptedFileStore implements SecretStore {
     private readonly fs;
@@ -38,8 +42,10 @@ export declare class EncryptedFileStore implements SecretStore {
     private readonly getMachineIdentity;
     private readonly getRandomBytes;
     private keyPromise;
+    private readonly throwOnInvalidDocument;
     constructor(input: EncryptedFileStoreInput);
     get(): Promise<string | null>;
+    withLock<T>(operation: () => Promise<T>, options?: SecretStoreLockOptions): Promise<T>;
     set(value: string): Promise<void>;
     delete(): Promise<void>;
     private assertCredentialPathHasNoSymbolicLinks;

package/node_modules/auth-store/dist/encrypted-file-store.js

@@ -3,6 +3,7 @@ import { promises as fs } from "node:fs";
 import { homedir, hostname, userInfo } from "node:os";
 import path from "node:path";
 import { hasOwnErrorCode } from "./error-codes.js";
+import { withSecretStoreFileLock } from "./transaction-lock.js";
 const derivedKeyCache = new Map();
 const ENCRYPTION_ALGORITHM = "aes-256-gcm";
 const ENCRYPTION_VERSION = 1;
@@ -18,6 +19,7 @@ export class EncryptedFileStore {
     getMachineIdentity;
     getRandomBytes;
     keyPromise = null;
+    throwOnInvalidDocument;
     constructor(input) {
         this.fs = input.fs ?? fs;
         this.salt = input.salt;
@@ -36,6 +38,7 @@ export class EncryptedFileStore {
         }
         this.getMachineIdentity = input.getMachineIdentity ?? defaultMachineIdentity;
         this.getRandomBytes = input.getRandomBytes ?? randomBytes;
+        this.throwOnInvalidDocument = input.throwOnInvalidDocument ?? false;
     }
     async get() {
         await this.assertCredentialPathHasNoSymbolicLinks(this.filePath);
@@ -51,6 +54,8 @@ export class EncryptedFileStore {
         }
         const document = parseEncryptedDocument(rawDocument);
         if (!document) {
+            if (this.throwOnInvalidDocument)
+                throw new Error("Invalid encrypted credential document; reset the store explicitly to recover");
             return null;
         }
         const key = await this.getEncryptionKey();
@@ -60,6 +65,8 @@ export class EncryptedFileStore {
             const ciphertext = Buffer.from(document.ciphertext, "base64");
             if (iv.byteLength !== ENCRYPTION_IV_BYTES ||
                 authTag.byteLength !== ENCRYPTION_AUTH_TAG_BYTES) {
+                if (this.throwOnInvalidDocument)
+                    throw new Error("Invalid encrypted credential document; reset the store explicitly to recover");
                 return null;
             }
             const decipher = createDecipheriv(ENCRYPTION_ALGORITHM, key, iv);
@@ -68,9 +75,17 @@ export class EncryptedFileStore {
             return plaintext.toString("utf8");
         }
         catch {
+            if (this.throwOnInvalidDocument)
+                throw new Error("Invalid encrypted credential document; reset the store explicitly to recover");
             return null;
         }
     }
+    async withLock(operation, options = {}) {
+        await this.assertCredentialPathHasNoSymbolicLinks(`${this.filePath}.lock`);
+        if (this.fs.readdir === undefined)
+            throw new Error("Secret-store transaction locks require filesystem readdir support");
+        return withSecretStoreFileLock(this.fs, `${this.filePath}.lock`, operation, options);
+    }
     async set(value) {
         await this.assertCredentialPathHasNoSymbolicLinks(this.filePath);
         const key = await this.getEncryptionKey();

package/node_modules/auth-store/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { createSecretStore } from "./create-secret-store.js";
 export { EncryptedFileStore } from "./encrypted-file-store.js";
 export { KeychainStore } from "./keychain-store.js";
+export type { SecretStoreLockOptions, SecretStoreLockFileSystem } from "./transaction-lock.js";
 export { key, MigratingSecretStore } from "./provider-store.js";
 export type { SecretStore, StoreBackend, CreateSecretStoreInput, CreateSecretStoreResult } from "./types.js";
 export type { MachineIdentity, EncryptedFileStoreInput, EncryptedFileStoreFileSystem } from "./encrypted-file-store.js";

package/node_modules/auth-store/dist/keychain-store.d.ts

@@ -1,4 +1,5 @@
 import type { SecretStore } from "./types.js";
+import { type SecretStoreLockFileSystem, type SecretStoreLockOptions } from "./transaction-lock.js";
 export interface KeychainCommandResult {
     stdout: string;
     stderr: string;
@@ -12,13 +13,20 @@ export interface KeychainStoreInput {
     runCommand?: KeychainCommandRunner;
     service: string;
     account: string;
+    lock?: {
+        fs?: SecretStoreLockFileSystem;
+        directory?: string;
+    };
 }
 export declare class KeychainStore implements SecretStore {
     private readonly runCommand;
     private readonly service;
     private readonly account;
+    private readonly lockFs;
+    private readonly lockDirectory;
     constructor(input: KeychainStoreInput);
     get(): Promise<string | null>;
+    withLock<T>(operation: () => Promise<T>, options?: SecretStoreLockOptions): Promise<T>;
     set(value: string): Promise<void>;
     delete(): Promise<void>;
     private executeSecurityCommand;

package/node_modules/auth-store/dist/keychain-store.js

@@ -1,14 +1,23 @@
 import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { promises as nodeFs } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { withSecretStoreFileLock } from "./transaction-lock.js";
 const SECURITY_CLI = "security";
 const KEYCHAIN_ITEM_NOT_FOUND_EXIT_CODE = 44;
 export class KeychainStore {
     runCommand;
     service;
     account;
+    lockFs;
+    lockDirectory;
     constructor(input) {
         this.runCommand = input.runCommand ?? runSecurityCommand;
         this.service = input.service.trim();
         this.account = input.account.trim();
+        this.lockFs = input.lock?.fs ?? nodeFs;
+        this.lockDirectory = input.lock?.directory ?? path.join(homedir(), ".auth-store", "keychain-locks");
         if (this.service.length === 0) {
             throw new Error("Keychain service must not be empty");
         }
@@ -26,6 +35,10 @@ export class KeychainStore {
         }
         throw createSecurityCliFailure("read secret from macOS Keychain", result);
     }
+    async withLock(operation, options = {}) {
+        const identity = createHash("sha256").update(JSON.stringify([this.service, this.account])).digest("hex");
+        return withSecretStoreFileLock(this.lockFs, path.join(this.lockDirectory, identity), operation, options);
+    }
     async set(value) {
         if (value.includes("\n") || value.includes("\r")) {
             throw new Error("Keychain secrets cannot contain line breaks");

package/node_modules/auth-store/dist/transaction-lock.d.ts

@@ -0,0 +1,24 @@
+export interface SecretStoreLockOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface SecretStoreLockFileSystem {
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+        mode?: number;
+    }): Promise<unknown>;
+    readdir(path: string): Promise<string[]>;
+    readFile(path: string, encoding: BufferEncoding): Promise<string>;
+    writeFile(path: string, value: string, options: {
+        encoding: BufferEncoding;
+        flag: string;
+        mode: number;
+    }): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    lstat(path: string): Promise<{
+        isSymbolicLink(): boolean;
+    }>;
+}
+/** Filesystem bakery lock: unique claims allow dead-owner cleanup without deleting a replacement owner's lock. */
+export declare function withSecretStoreFileLock<T>(fs: SecretStoreLockFileSystem, lockDirectory: string, operation: () => Promise<T>, options?: SecretStoreLockOptions): Promise<T>;

package/node_modules/auth-store/dist/transaction-lock.js

@@ -0,0 +1,152 @@
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { hasOwnErrorCode } from "./error-codes.js";
+/** Filesystem bakery lock: unique claims allow dead-owner cleanup without deleting a replacement owner's lock. */
+export async function withSecretStoreFileLock(fs, lockDirectory, operation, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0 || timeoutMs > 2_147_483_647)
+        throw new Error("Invalid secret-store transaction lock timeout");
+    options.signal?.throwIfAborted();
+    const deadline = performance.now() + timeoutMs;
+    const directory = path.resolve(lockDirectory);
+    await assertLockDirectoryPath(fs, directory);
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    await assertLockDirectoryPath(fs, directory);
+    const name = `${process.pid}-${randomUUID()}.claim`;
+    const claimPath = path.join(directory, name);
+    const temporaryPath = `${claimPath}.tmp`;
+    let claimed = true;
+    let temporaryCreated = false;
+    let outcome;
+    try {
+        try {
+            await fs.writeFile(claimPath, JSON.stringify({ ticket: null }), { encoding: "utf8", flag: "wx", mode: 0o600 });
+        }
+        catch (error) {
+            if (hasOwnErrorCode(error, "EEXIST"))
+                claimed = false;
+            throw error;
+        }
+        const existing = await readClaims(fs, directory, name);
+        const ticket = existing.reduce((max, claim) => Math.max(max, claim.ticket ?? 0), 0) + 1;
+        if (!Number.isSafeInteger(ticket))
+            throw new Error("Secret-store transaction lock ticket overflow");
+        temporaryCreated = true;
+        try {
+            await fs.writeFile(temporaryPath, JSON.stringify({ ticket }), { encoding: "utf8", flag: "wx", mode: 0o600 });
+        }
+        catch (error) {
+            if (hasOwnErrorCode(error, "EEXIST"))
+                temporaryCreated = false;
+            throw error;
+        }
+        await fs.rename(temporaryPath, claimPath);
+        temporaryCreated = false;
+        for (;;) {
+            options.signal?.throwIfAborted();
+            const peers = await readClaims(fs, directory, name);
+            if (!peers.some(peer => peer.ticket === null || peer.ticket < ticket || (peer.ticket === ticket && peer.name < name)))
+                break;
+            const remaining = deadline - performance.now();
+            if (remaining <= 0)
+                throw new Error("Timed out waiting for secret-store transaction lock");
+            await new Promise((resolve, reject) => {
+                const abort = () => { clearTimeout(timer); options.signal?.removeEventListener("abort", abort); reject(options.signal?.reason); };
+                const timer = setTimeout(() => { options.signal?.removeEventListener("abort", abort); resolve(); }, Math.min(10, remaining));
+                options.signal?.addEventListener("abort", abort, { once: true });
+                if (options.signal?.aborted)
+                    abort();
+            });
+        }
+        options.signal?.throwIfAborted();
+        outcome = { result: await operation() };
+    }
+    catch (error) {
+        outcome = { error };
+    }
+    const cleanup = [];
+    for (const target of [...(temporaryCreated ? [temporaryPath] : []), ...(claimed ? [claimPath] : [])]) {
+        try {
+            await fs.unlink(target);
+        }
+        catch (error) {
+            if (!hasOwnErrorCode(error, "ENOENT"))
+                cleanup.push(error);
+        }
+    }
+    if (cleanup.length)
+        throw new AggregateError([...("error" in outcome ? [outcome.error] : []), ...cleanup], "Secret-store transaction lock cleanup failed");
+    if ("error" in outcome)
+        throw outcome.error;
+    return outcome.result;
+}
+async function assertNoSymbolicLink(fs, target) {
+    try {
+        if ((await fs.lstat(target)).isSymbolicLink())
+            throw new Error("Refusing secret-store transaction lock through symbolic link");
+    }
+    catch (error) {
+        if (!hasOwnErrorCode(error, "ENOENT"))
+            throw error;
+    }
+}
+async function assertLockDirectoryPath(fs, directory) {
+    const root = path.parse(directory).root;
+    const segments = directory.slice(root.length).split(path.sep).filter(Boolean);
+    let current = root;
+    for (const [index, segment] of segments.entries()) {
+        current = path.join(current, segment);
+        // Match encrypted credential paths: allow OS root aliases such as macOS /var.
+        if (index > 0 || segments.length === 1)
+            await assertNoSymbolicLink(fs, current);
+    }
+}
+async function readClaims(fs, directory, ownName) {
+    const claims = [];
+    for (const name of await fs.readdir(directory)) {
+        if (name === ownName || !name.endsWith(".claim"))
+            continue;
+        const pidText = name.slice(0, name.indexOf("-"));
+        const pid = Number(pidText);
+        if (!Number.isSafeInteger(pid) || pid < 1 || String(pid) !== pidText)
+            throw new Error("Malformed secret-store transaction lock owner");
+        const target = path.join(directory, name);
+        await assertNoSymbolicLink(fs, target);
+        let alive = true;
+        try {
+            process.kill(pid, 0);
+        }
+        catch (error) {
+            alive = !hasOwnErrorCode(error, "ESRCH");
+        }
+        if (!alive) {
+            try {
+                await fs.unlink(target);
+            }
+            catch (error) {
+                if (!hasOwnErrorCode(error, "ENOENT"))
+                    throw error;
+            }
+            continue;
+        }
+        let ticket = null;
+        let raw;
+        try {
+            raw = await fs.readFile(target, "utf8");
+        }
+        catch (error) {
+            if (hasOwnErrorCode(error, "ENOENT"))
+                continue;
+            throw error;
+        }
+        try {
+            const value = JSON.parse(raw);
+            if (value !== null && typeof value === "object" && "ticket" in value &&
+                typeof value.ticket === "number" && Number.isSafeInteger(value.ticket) && value.ticket > 0)
+                ticket = value.ticket;
+        }
+        catch { /* Incomplete live claims remain in the choosing phase; never steal them by age. */ }
+        claims.push({ name, ticket });
+    }
+    return claims;
+}

package/node_modules/auth-store/dist/types.d.ts

@@ -1,11 +1,13 @@
 import type { EncryptedFileStoreInput } from "./encrypted-file-store.js";
 import type { KeychainStoreInput } from "./keychain-store.js";
+import type { SecretStoreLockOptions } from "./transaction-lock.js";
 export interface SecretStore {
     get(options?: {
         readOnly?: boolean;
     }): Promise<string | null>;
     set(value: string): Promise<void>;
     delete(): Promise<void>;
+    withLock?<T>(operation: () => Promise<T>, options?: SecretStoreLockOptions): Promise<T>;
 }
 export type StoreBackend = "file" | "keychain";
 export interface CreateSecretStoreInput {

package/node_modules/tiny-http-mcp-server/dist/composition.json

@@ -18,7 +18,7 @@
     },
     {
       "name": "tiny-http-mcp-server",
-      "version": "0.1.25",
+      "version": "0.1.29",
       "license": "MIT"
     },
     {

package/node_modules/tiny-http-mcp-server/node_modules/mcp-oauth/README.md

@@ -41,6 +41,7 @@ const verifier = createJwksTokenVerifier({
   - `mode: "dynamic"` with optional `metadata`
   - `mode: "static"` with `clientId`, optional `clientSecret`, optional `metadata`
 - `allowInteractive: false` prevents interactive login while retaining cached tokens and silent refresh
+- `sessionLockTimeoutMs` limits acquisition waits for a session transaction lock (default 30,000 ms; integer from 1 to 2147483647)
 - `initialGrant: { resource, tokens }` optionally imports an existing Bearer grant for one HTTP resource; requires the original client ID
 - `browser.openBrowser(url)` optional
 - `browser.readLine()` optional
@@ -106,6 +107,35 @@ Input tokens are copied and invalid expiry values fail before authorization.
 
 `createAuthStoreSessionStore(options)` accepts the standard `auth-store` config.
 
+Providers sharing the same `sessionStore` object serialize the complete session
+read, refresh/authorization and persistence transaction for each resource.
+Waiting requests can cancel or time out independently; they cannot release an
+active owner's lock. Custom stores may implement
+`withLock(resource, operation, { signal, timeoutMs })` to serialize the same
+transaction across store instances or processes. The hook must honor acquisition
+cancellation and keep the lock until the operation settles. The timeout bounds
+acquisition, while token and browser operations retain their own deadlines.
+The native `auth-store` session adapter implements this hook for both encrypted
+files and Keychain identities, including across independent processes. Locks
+cover the complete read, refresh/authorization and persisted winner. Dead-owner
+claims are recovered without stealing a live transaction.
+
+Before sending a refresh request, the provider persists a tokenless session with
+`refreshState: "pending"`, retaining the original client and discovery binding.
+A successful response replaces it with the rotated grant. A crash, cancellation,
+network disconnect or incomplete response leaves the marker, so another process
+cannot replay a possibly consumed refresh token or revive the initial import.
+Such a session requires fresh authorization. Interactive unauthorized handling
+can recover it; headless requests fail with an explicit unknown-outcome error.
+Only complete OAuth error responses establish a rejected request and allow a
+transient retry or restoration of the original grant. Gateway error pages do not.
+
+Native persisted OAuth reads always reject corrupt encrypted documents and
+invalid stored JSON, with diagnostics that omit decrypted contents. They retain
+the existing record for explicit reset rather than interpreting corruption as
+an absent session and reviving an initial grant. Caller file-backend settings
+cannot disable this policy.
+
 ## Environment Variables
 
 This package exposes no direct environment variables. When `authStore` is used,

package/node_modules/tiny-http-mcp-server/node_modules/mcp-oauth/dist/client/auth-store-session-store.js

@@ -11,13 +11,25 @@ const DEFAULT_CLIENT_KEYCHAIN_SERVICE = "poe-code-mcp-oauth-clients";
 const MAX_JS_DATE_MS = 8_640_000_000_000_000;
 export function createAuthStoreSessionStore(options = {}) {
     return {
+        async withLock(resource, operation, lockOptions) {
+            const store = createResourceSecretStore(resource, options);
+            if (store.withLock === undefined)
+                throw new Error("OAuth secret-store backend does not support transaction locks");
+            return store.withLock(operation, lockOptions);
+        },
         async load(resource) {
             const store = createResourceSecretStore(resource, options);
             const value = await store.get();
             if (value === null) {
                 return null;
             }
-            const parsed = JSON.parse(value);
+            let parsed;
+            try {
+                parsed = JSON.parse(value);
+            }
+            catch {
+                throw new Error("Stored OAuth session must be valid JSON; reset the store explicitly to recover");
+            }
             if (isStoredOAuthSession(parsed)) {
                 return parsed;
             }
@@ -41,7 +53,13 @@ export function createAuthStoreClientStore(options) {
             if (value === null) {
                 return null;
             }
-            const parsed = JSON.parse(value);
+            let parsed;
+            try {
+                parsed = JSON.parse(value);
+            }
+            catch {
+                throw new Error("Stored OAuth client must be valid JSON; reset the store explicitly to recover");
+            }
             const clientId = isObjectRecord(parsed) ? getOwnString(parsed, "clientId") : undefined;
             if (clientId !== undefined) {
                 const client = { clientId };
@@ -69,6 +87,7 @@ function createNamedSecretStore(key, options, defaults) {
     const parsedFilePath = configuredFilePath === undefined ? null : path.parse(configuredFilePath);
     const fileStore = {
         ...options.fileStore,
+        throwOnInvalidDocument: true,
         filePath: parsedFilePath === null
             ? undefined
             : path.join(parsedFilePath.dir, `${parsedFilePath.name}-${hash}${parsedFilePath.ext || ".enc"}`),
@@ -119,6 +138,8 @@ function isStoredOAuthSession(value) {
         isNonBlankOwnString(value, "authorizationServer") &&
         isStoredOAuthClient(getOwnEntry(value, "client")) &&
         isStoredOAuthDiscovery(getOwnEntry(value, "discovery")) &&
+        (getOwnEntry(value, "refreshState") === undefined ||
+            (getOwnEntry(value, "refreshState") === "pending" && getOwnEntry(value, "tokens") === undefined)) &&
         isStoredOAuthTokensOrMissing(getOwnEntry(value, "tokens")));
 }
 function isStoredOAuthClient(value) {