usertrust 0.2.2 → 0.2.4

package/dist/resilience/scope.js

@@ -7,8 +7,9 @@
  * Each lease locks a set of glob patterns; overlapping patterns from different
  * actors are rejected.
  *
- * Store path: `.usertools/leases.json`
+ * Store path: `.usertrust/leases.json`
  */
+import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { minimatch } from "minimatch";
@@ -16,33 +17,39 @@ import { VAULT_DIR } from "../shared/constants.js";
 // ---------------------------------------------------------------------------
 // Path Resolution
 // ---------------------------------------------------------------------------
-let storeDir = join(process.cwd(), VAULT_DIR);
+let moduleStoreDir = join(process.cwd(), VAULT_DIR);
 /**
  * Set the store directory path (for testing).
+ *
+ * @deprecated Use the `storeDir` constructor parameter on `ScopeManager` instead.
+ * This function mutates module-level state shared by all ScopeManager instances
+ * that were created without an explicit storeDir.
  */
 export function setStoreDir(dir) {
-    storeDir = dir;
+    moduleStoreDir = dir;
 }
 /**
- * Get the current store directory.
+ * Get the current module-level store directory.
+ *
+ * @deprecated Use the `storeDir` constructor parameter on `ScopeManager` instead.
  */
 export function getStoreDir() {
-    return storeDir;
+    return moduleStoreDir;
 }
-function getLeasesPath() {
+// ---------------------------------------------------------------------------
+// File Operations (parameterized by storeDir)
+// ---------------------------------------------------------------------------
+function getLeasesPath(storeDir) {
     return join(storeDir, "leases.json");
 }
-function ensureStoreDir() {
+function ensureStoreDir(storeDir) {
     if (!existsSync(storeDir)) {
         mkdirSync(storeDir, { recursive: true });
     }
 }
-// ---------------------------------------------------------------------------
-// File Operations
-// ---------------------------------------------------------------------------
-function readLeases() {
-    ensureStoreDir();
-    const path = getLeasesPath();
+function readLeases(storeDir) {
+    ensureStoreDir(storeDir);
+    const path = getLeasesPath(storeDir);
     if (!existsSync(path)) {
         return {};
     }
@@ -54,16 +61,15 @@ function readLeases() {
         return {};
     }
 }
-function writeLeases(store) {
-    ensureStoreDir();
-    writeFileSync(getLeasesPath(), JSON.stringify(store, null, "\t"));
+function writeLeases(store, storeDir) {
+    ensureStoreDir(storeDir);
+    writeFileSync(getLeasesPath(storeDir), JSON.stringify(store, null, "\t"));
 }
 // ---------------------------------------------------------------------------
-// ID Generation
+// ID Generation (AUD-466: crypto.randomUUID replaces Math.random)
 // ---------------------------------------------------------------------------
 function generateLeaseId() {
-    const hex = Math.random().toString(16).substring(2, 10);
-    return `ls_${hex}`;
+    return `ls_${randomUUID().replace(/-/g, "").substring(0, 16)}`;
 }
 // ---------------------------------------------------------------------------
 // Scope Overlap
@@ -111,18 +117,35 @@ export function fileMatchesScope(file, scope) {
  *
  * Provides `acquireLease`, `releaseLease`, `findConflicts`, and `expireStale`
  * for coordinating parallel workers operating on overlapping file scopes.
+ *
+ * AUD-465: Accepts an optional `storeDir` constructor parameter to avoid
+ * reliance on module-level mutable state. Falls back to the module-level
+ * `moduleStoreDir` for backward compatibility.
  */
 export class ScopeManager {
     clock;
-    constructor(clock) {
-        this.clock = clock ?? Date.now;
+    storeDir;
+    /**
+     * @param optionsOrClock - Either an options object `{ clock?, storeDir? }`
+     *   or a legacy clock function `() => number` for backward compatibility.
+     */
+    constructor(optionsOrClock) {
+        if (typeof optionsOrClock === "function") {
+            // Legacy constructor: ScopeManager(clock)
+            this.clock = optionsOrClock;
+            this.storeDir = moduleStoreDir;
+        }
+        else {
+            this.clock = optionsOrClock?.clock ?? Date.now;
+            this.storeDir = optionsOrClock?.storeDir ?? moduleStoreDir;
+        }
     }
     /**
      * Acquire a lease for the given scope.
      * Throws if scope overlaps with another actor's active lease.
      */
     acquireLease(options) {
-        const store = readLeases();
+        const store = readLeases(this.storeDir);
         const ttlMin = options.ttlMin ?? 60;
         // Expire stale leases first
         this.expireStaleInStore(store);
@@ -147,14 +170,28 @@ export class ScopeManager {
             status: "active",
         };
         store[leaseId] = lease;
-        writeLeases(store);
+        writeLeases(store, this.storeDir);
         return lease;
     }
     /**
      * Renew an existing lease, extending its TTL.
+     *
+     * AUD-466: When `actor` is provided, verifies the caller matches the lease
+     * owner to prevent unauthorized renewal by a different actor. Callers SHOULD
+     * always pass `actor` — omitting it is supported only for backward
+     * compatibility and will be removed in a future major version.
      */
-    renewLease(leaseId, ttlMin = 60) {
-        const store = readLeases();
+    renewLease(leaseId, actorOrTtl, ttlMin) {
+        let actor;
+        let ttl;
+        if (typeof actorOrTtl === "string") {
+            actor = actorOrTtl;
+            ttl = ttlMin ?? 60;
+        }
+        else {
+            ttl = actorOrTtl ?? 60;
+        }
+        const store = readLeases(this.storeDir);
         const lease = store[leaseId];
         if (!lease) {
             throw new Error(`Lease ${leaseId} not found`);
@@ -162,29 +199,40 @@ export class ScopeManager {
         if (lease.status !== "active") {
             throw new Error(`Lease ${leaseId} is ${lease.status}, cannot renew`);
         }
-        lease.expires_at = new Date(this.clock() + ttlMin * 60_000).toISOString();
+        if (actor !== undefined && lease.actor !== actor) {
+            throw new Error(`Actor "${actor}" cannot renew lease ${leaseId} owned by "${lease.actor}"`);
+        }
+        lease.expires_at = new Date(this.clock() + ttl * 60_000).toISOString();
         lease.last_renewed_at = new Date(this.clock()).toISOString();
-        writeLeases(store);
+        writeLeases(store, this.storeDir);
         return lease;
     }
     /**
      * Release a lease, marking it as released.
+     *
+     * AUD-466: When `actor` is provided, verifies the caller matches the lease
+     * owner to prevent unauthorized release by a different actor. Callers SHOULD
+     * always pass `actor` — omitting it is supported only for backward
+     * compatibility and will be removed in a future major version.
      */
-    releaseLease(leaseId) {
-        const store = readLeases();
+    releaseLease(leaseId, actor) {
+        const store = readLeases(this.storeDir);
         const lease = store[leaseId];
         if (!lease) {
             throw new Error(`Lease ${leaseId} not found`);
         }
+        if (actor !== undefined && lease.actor !== actor) {
+            throw new Error(`Actor "${actor}" cannot release lease ${leaseId} owned by "${lease.actor}"`);
+        }
         lease.status = "released";
-        writeLeases(store);
+        writeLeases(store, this.storeDir);
         return lease;
     }
     /**
      * Find conflicts for a proposed scope against active leases.
      */
     findConflicts(scope, excludeActor) {
-        const store = readLeases();
+        const store = readLeases(this.storeDir);
         this.expireStaleInStore(store);
         return this.findConflictsInStore(store, scope, excludeActor);
     }
@@ -193,10 +241,10 @@ export class ScopeManager {
      * Returns the number of leases expired.
      */
     expireStale() {
-        const store = readLeases();
+        const store = readLeases(this.storeDir);
         const count = this.expireStaleInStore(store);
         if (count > 0) {
-            writeLeases(store);
+            writeLeases(store, this.storeDir);
         }
         return count;
     }
@@ -204,14 +252,14 @@ export class ScopeManager {
      * Get all active leases.
      */
     getActiveLeases() {
-        const store = readLeases();
+        const store = readLeases(this.storeDir);
         return Object.values(store).filter((l) => l.status === "active");
     }
     /**
      * Get a lease by ID.
      */
     getLease(leaseId) {
-        const store = readLeases();
+        const store = readLeases(this.storeDir);
         return store[leaseId];
     }
     // ── Private helpers ──

package/dist/resilience/scope.js.map

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

package/dist/shared/errors.d.ts

@@ -2,30 +2,44 @@ export declare class InsufficientBalanceError extends Error {
     readonly userId: string;
     readonly required: number;
     readonly available: number;
+    readonly hint: string;
+    readonly docsUrl: string;
     constructor(userId: string, required: number, available: number);
 }
 export declare class PolicyDeniedError extends Error {
     readonly reason: string;
+    readonly hint: string;
+    readonly docsUrl: string;
     constructor(reason: string);
 }
 export declare class AccountNotFoundError extends Error {
     readonly userId: string;
+    readonly hint: string;
+    readonly docsUrl: string;
     constructor(userId: string);
 }
 export declare class IdempotencyConflictError extends Error {
     readonly key: string;
+    readonly hint: string;
+    readonly docsUrl: string;
     constructor(key: string);
 }
 export declare class LedgerUnavailableError extends Error {
     readonly cause_message: string;
+    readonly hint: string;
+    readonly docsUrl: string;
     constructor(reason: string);
 }
 export declare class AuditDegradedError extends Error {
     readonly cause_message: string;
+    readonly hint: string;
+    readonly docsUrl: string;
     constructor(reason: string);
 }
 export declare class VaultNotInitializedError extends Error {
     readonly path: string;
+    readonly hint: string;
+    readonly docsUrl: string;
     constructor(path: string);
 }
 //# sourceMappingURL=errors.d.ts.map

package/dist/shared/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAGA,qBAAa,wBAAyB,SAAQ,KAAK;IAClD,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,SAAS,EAAE,MAAM,CAAC;gBAEtB,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAO/D;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAC3C,SAAgB,MAAM,EAAE,MAAM,CAAC;gBAEnB,MAAM,EAAE,MAAM;CAK1B;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC9C,SAAgB,MAAM,EAAE,MAAM,CAAC;gBAEnB,MAAM,EAAE,MAAM;CAK1B;AAED,qBAAa,wBAAyB,SAAQ,KAAK;IAClD,SAAgB,GAAG,EAAE,MAAM,CAAC;gBAEhB,GAAG,EAAE,MAAM;CAKvB;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAChD,SAAgB,aAAa,EAAE,MAAM,CAAC;gBAE1B,MAAM,EAAE,MAAM;CAK1B;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC5C,SAAgB,aAAa,EAAE,MAAM,CAAC;gBAE1B,MAAM,EAAE,MAAM;CAK1B;AAED,qBAAa,wBAAyB,SAAQ,KAAK;IAClD,SAAgB,IAAI,EAAE,MAAM,CAAC;gBAEjB,IAAI,EAAE,MAAM;CAKxB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAGA,qBAAa,wBAAyB,SAAQ,KAAK;IAClD,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,OAAO,EAAE,MAAM,CAAC;gBAEpB,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAa/D;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAC3C,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,OAAO,EAAE,MAAM,CAAC;gBAEpB,MAAM,EAAE,MAAM;CAU1B;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC9C,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,OAAO,EAAE,MAAM,CAAC;gBAEpB,MAAM,EAAE,MAAM;CAU1B;AAED,qBAAa,wBAAyB,SAAQ,KAAK;IAClD,SAAgB,GAAG,EAAE,MAAM,CAAC;IAC5B,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,OAAO,EAAE,MAAM,CAAC;gBAEpB,GAAG,EAAE,MAAM;CASvB;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAChD,SAAgB,aAAa,EAAE,MAAM,CAAC;IACtC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,OAAO,EAAE,MAAM,CAAC;gBAEpB,MAAM,EAAE,MAAM;CAU1B;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC5C,SAAgB,aAAa,EAAE,MAAM,CAAC;IACtC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,OAAO,EAAE,MAAM,CAAC;gBAEpB,MAAM,EAAE,MAAM;CAS1B;AAED,qBAAa,wBAAyB,SAAQ,KAAK;IAClD,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,OAAO,EAAE,MAAM,CAAC;gBAEpB,IAAI,EAAE,MAAM;CASxB"}

package/dist/shared/errors.js

@@ -4,60 +4,102 @@ export class InsufficientBalanceError extends Error {
     userId;
     required;
     available;
+    hint;
+    docsUrl;
     constructor(userId, required, available) {
-        super(`Insufficient balance for user ${userId}: need ${required}, have ${available}`);
+        const hint = "Increase the budget in trust() options or add funds via the ledger.";
+        const docsUrl = "https://usertrust.ai/docs/errors/insufficient-balance";
+        super(`Insufficient balance for user ${userId}: need ${required}, have ${available}\n\n  Hint: ${hint}\n  Docs: ${docsUrl}`);
         this.name = "InsufficientBalanceError";
         this.userId = userId;
         this.required = required;
         this.available = available;
+        this.hint = hint;
+        this.docsUrl = docsUrl;
     }
 }
 export class PolicyDeniedError extends Error {
     reason;
+    hint;
+    docsUrl;
     constructor(reason) {
-        super(`Policy denied: ${reason}`);
+        const hint = 'Check your policy rules in .usertrust/policies/ or use { pii: "warn" } to downgrade PII enforcement.';
+        const docsUrl = "https://usertrust.ai/docs/errors/policy-denied";
+        super(`Policy denied: ${reason}\n\n  Hint: ${hint}\n  Docs: ${docsUrl}`);
         this.name = "PolicyDeniedError";
         this.reason = reason;
+        this.hint = hint;
+        this.docsUrl = docsUrl;
     }
 }
 export class AccountNotFoundError extends Error {
     userId;
+    hint;
+    docsUrl;
     constructor(userId) {
-        super(`Account not found for user: ${userId}`);
+        const hint = 'Run "npx usertrust init" to create accounts, or verify the userId matches your config.';
+        const docsUrl = "https://usertrust.ai/docs/errors/account-not-found";
+        super(`Account not found for user: ${userId}\n\n  Hint: ${hint}\n  Docs: ${docsUrl}`);
         this.name = "AccountNotFoundError";
         this.userId = userId;
+        this.hint = hint;
+        this.docsUrl = docsUrl;
     }
 }
 export class IdempotencyConflictError extends Error {
     key;
+    hint;
+    docsUrl;
     constructor(key) {
-        super(`Idempotency conflict for key: ${key}`);
+        const hint = "This transfer was already submitted. Use a unique transferId for retries.";
+        const docsUrl = "https://usertrust.ai/docs/errors/idempotency-conflict";
+        super(`Idempotency conflict for key: ${key}\n\n  Hint: ${hint}\n  Docs: ${docsUrl}`);
         this.name = "IdempotencyConflictError";
         this.key = key;
+        this.hint = hint;
+        this.docsUrl = docsUrl;
     }
 }
 export class LedgerUnavailableError extends Error {
     cause_message;
+    hint;
+    docsUrl;
     constructor(reason) {
-        super(`Ledger unavailable: ${reason}`);
+        const hint = 'Start TigerBeetle with "npx usertrust tb start" or use { dryRun: true } to skip the ledger.';
+        const docsUrl = "https://usertrust.ai/docs/errors/ledger-unavailable";
+        super(`Ledger unavailable: ${reason}\n\n  Hint: ${hint}\n  Docs: ${docsUrl}`);
         this.name = "LedgerUnavailableError";
         this.cause_message = reason;
+        this.hint = hint;
+        this.docsUrl = docsUrl;
     }
 }
 export class AuditDegradedError extends Error {
     cause_message;
+    hint;
+    docsUrl;
     constructor(reason) {
-        super(`Audit degraded: ${reason}`);
+        const hint = "Check disk space and permissions on the .usertrust/audit/ directory.";
+        const docsUrl = "https://usertrust.ai/docs/errors/audit-degraded";
+        super(`Audit degraded: ${reason}\n\n  Hint: ${hint}\n  Docs: ${docsUrl}`);
         this.name = "AuditDegradedError";
         this.cause_message = reason;
+        this.hint = hint;
+        this.docsUrl = docsUrl;
     }
 }
 export class VaultNotInitializedError extends Error {
     path;
+    hint;
+    docsUrl;
     constructor(path) {
-        super(`Vault not initialized at: ${path}`);
+        const hint = 'Run "npx usertrust init" to create the vault directory.';
+        const docsUrl = "https://usertrust.ai/docs/errors/vault-not-initialized";
+        super(`Vault not initialized at: ${path}\n\n  Hint: ${hint}\n  Docs: ${docsUrl}`);
         this.name = "VaultNotInitializedError";
         this.path = path;
+        this.hint = hint;
+        this.docsUrl = docsUrl;
     }
 }
 //# sourceMappingURL=errors.js.map

package/dist/shared/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAClC,MAAM,CAAS;IACf,QAAQ,CAAS;IACjB,SAAS,CAAS;IAElC,YAAY,MAAc,EAAE,QAAgB,EAAE,SAAiB;QAC9D,KAAK,CAAC,iCAAiC,MAAM,UAAU,QAAQ,UAAU,SAAS,EAAE,CAAC,CAAC;QACtF,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC5B,CAAC;CACD;AAED,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC3B,MAAM,CAAS;IAE/B,YAAY,MAAc;QACzB,KAAK,CAAC,kBAAkB,MAAM,EAAE,CAAC,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACtB,CAAC;CACD;AAED,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC9B,MAAM,CAAS;IAE/B,YAAY,MAAc;QACzB,KAAK,CAAC,+BAA+B,MAAM,EAAE,CAAC,CAAC;QAC/C,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACtB,CAAC;CACD;AAED,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAClC,GAAG,CAAS;IAE5B,YAAY,GAAW;QACtB,KAAK,CAAC,iCAAiC,GAAG,EAAE,CAAC,CAAC;QAC9C,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IAChB,CAAC;CACD;AAED,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAChC,aAAa,CAAS;IAEtC,YAAY,MAAc;QACzB,KAAK,CAAC,uBAAuB,MAAM,EAAE,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC;IAC7B,CAAC;CACD;AAED,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC5B,aAAa,CAAS;IAEtC,YAAY,MAAc;QACzB,KAAK,CAAC,mBAAmB,MAAM,EAAE,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC;IAC7B,CAAC;CACD;AAED,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAClC,IAAI,CAAS;IAE7B,YAAY,IAAY;QACvB,KAAK,CAAC,6BAA6B,IAAI,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IAClB,CAAC;CACD"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "usertrust",
-	"version": "0.2.2",
+	"version": "0.2.4",
 	"description": "Financial governance for AI agents. Every LLM call becomes an immutable, auditable transaction.",
 	"license": "Apache-2.0",
 	"author": "Usertools, Inc. <hello@usertools.ai> (https://usertrust.ai)",