@listen-fire/module-runtime 0.12.0-rc.7 → 0.12.0-rc.8

package/dist/index.d.ts

@@ -6,3 +6,4 @@ export * from './secrets/connect';
 export * from './secrets/family';
 export * from './secrets/memory';
 export * from './secrets/oauth2';
+export * from './vendor_wait';

package/dist/index.js

@@ -4,7 +4,8 @@
 // bytes as a stream, the files slot, the secrets family (resolve a credential,
 // write it back at a version, refresh it once at a time) with the generic
 // OAuth 2 refresh and connect, the in-memory vault an embedder starts from,
-// the browser slot, and a bounded concurrency queue.
+// the browser slot, a bounded concurrency queue, and how long a
+// rate-limited vendor asked to wait.
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -28,3 +29,4 @@ __exportStar(require("./secrets/connect"), exports);
 __exportStar(require("./secrets/family"), exports);
 __exportStar(require("./secrets/memory"), exports);
 __exportStar(require("./secrets/oauth2"), exports);
+__exportStar(require("./vendor_wait"), exports);

package/dist/module-wire.d.ts

@@ -2,3 +2,4 @@ export * from './module_wire/wire';
 export * from './module_wire/conformance';
 export * from './module_wire/browser';
 export * from './module_wire/scanned';
+export * from './module_wire/secrets';

package/dist/module-wire.js

@@ -24,3 +24,4 @@ __exportStar(require("./module_wire/wire"), exports);
 __exportStar(require("./module_wire/conformance"), exports);
 __exportStar(require("./module_wire/browser"), exports);
 __exportStar(require("./module_wire/scanned"), exports);
+__exportStar(require("./module_wire/secrets"), exports);

package/dist/module_wire/conformance.d.ts

@@ -33,3 +33,12 @@ export interface WakeConformanceCase {
 }
 /** The wake slot (docs/contracts/wake-slot.md). */
 export declare const wakeSlotCases: WakeConformanceCase[];
+/** The secrets slot's own cases (docs/contracts/secrets-slot.md): the list,
+ *  the lease and whole entries. `client` reaches a module that can change its
+ *  entries; the family's cases (`secretsContractCases`) hold its resolve and
+ *  write-back to the meaning every store has. */
+export declare const secretsSlotCases: SlotConformanceCase[];
+/** What a module that keeps its credentials where lf cannot change them
+ *  answers: `client` reaches one. Entries are refused by name with a reason;
+ *  everything a refresh needs still works. */
+export declare const secretsReadOnlySlotCases: SlotConformanceCase[];

package/dist/module_wire/conformance.js

@@ -1,6 +1,7 @@
 "use strict";
 // The conformance suites of the slots with no family contract of their own
-// (models, judge, files, wake, ocr), and the cases every slot module answers alike (its
+// (models, judge, files, wake, ocr), and the secrets slot's own cases beside
+// the family's (`services/secrets/contract.ts`), and the cases every slot module answers alike (its
 // manifest, the envelope's refusals). Each runs against any server over the
 // wire: written once here, they hold lf's built-ins (`lf --contract-<slot>`)
 // and a third-party module in any language to the same meaning. The store,
@@ -9,12 +10,14 @@
 // `loop_guard/contract.ts`) driven over this same wire; the browser to
 // `services/browser/contract.ts` through its wire client.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.wakeSlotCases = exports.ocrSlotCases = exports.filesSlotCases = exports.judgeSlotCases = exports.modelsSlotCases = void 0;
+exports.secretsReadOnlySlotCases = exports.secretsSlotCases = exports.wakeSlotCases = exports.ocrSlotCases = exports.filesSlotCases = exports.judgeSlotCases = exports.modelsSlotCases = void 0;
 exports.commonSlotCases = commonSlotCases;
 const node_assert_1 = require("node:assert");
+const node_crypto_1 = require("node:crypto");
 const engine_contracts_1 = require("@listen-fire/engine-contracts");
 const slots_1 = require("@listen-fire/engine-contracts/slots");
 const scanned_1 = require("./scanned");
+const zod_1 = require("zod");
 const wire_1 = require("./wire");
 async function refusedWith(code, call) {
     try {
@@ -314,3 +317,137 @@ exports.wakeSlotCases = [
         },
     },
 ];
+// ── The secrets slot ────────────────────────────────────────────────────────
+const NEW_REF = () => `conf_${(0, node_crypto_1.randomUUID)().replaceAll('-', '').slice(0, 12)}`;
+const SecretsList = zod_1.z.array(slots_1.SecretsListed);
+async function listed(client) {
+    return client.read('secrets.list', {}, SecretsList);
+}
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+/** The secrets slot's own cases (docs/contracts/secrets-slot.md): the list,
+ *  the lease and whole entries. `client` reaches a module that can change its
+ *  entries; the family's cases (`secretsContractCases`) hold its resolve and
+ *  write-back to the meaning every store has. */
+exports.secretsSlotCases = [
+    {
+        name: 'secrets: list names each credential with its external, binding and the version resolve answers',
+        async run(client) {
+            const ref = NEW_REF();
+            const binding = { credential: 'oauth' };
+            await client.read('secrets.create', { ref, external: 'acme_crm', binding, fields: { access_token: 'a1', workspace: 'w1' } }, slots_1.SecretsEntryAnswer);
+            const one = (await listed(client)).find((entry) => entry.ref === ref);
+            node_assert_1.strict.ok(one !== undefined, 'a created entry is listed');
+            node_assert_1.strict.equal(one.external, 'acme_crm');
+            node_assert_1.strict.deepEqual(one.binding, binding);
+            node_assert_1.strict.equal(one.version, (await client.read('secrets.resolve', { ref }, slots_1.SecretsRecord.nullable()))?.version);
+            await client.call('secrets.delete', { ref });
+        },
+    },
+    {
+        name: 'secrets: create, replace and delete change whole entries, each answered null',
+        async run(client) {
+            const ref = NEW_REF();
+            node_assert_1.strict.equal(await client.call('secrets.create', { ref, external: 'acme_crm', binding: 'legacy', fields: { api_key: 'k1' } }), null);
+            node_assert_1.strict.deepEqual((await client.read('secrets.resolve', { ref }, slots_1.SecretsRecord.nullable()))?.fields, { api_key: 'k1' });
+            node_assert_1.strict.equal(await client.call('secrets.replace', { ref, external: 'acme_crm', binding: 'install', fields: { api_key: 'k2', workspace: 'w2' } }), null);
+            node_assert_1.strict.deepEqual((await client.read('secrets.resolve', { ref }, slots_1.SecretsRecord.nullable()))?.fields, { api_key: 'k2', workspace: 'w2' }, 'replace is the whole entry, not a merge');
+            node_assert_1.strict.equal((await listed(client)).find((entry) => entry.ref === ref)?.binding, 'install');
+            node_assert_1.strict.equal(await client.call('secrets.delete', { ref }), null);
+            node_assert_1.strict.equal(await client.call('secrets.resolve', { ref }), null);
+            node_assert_1.strict.equal((await listed(client)).find((entry) => entry.ref === ref), undefined, 'a deleted entry is not listed');
+        },
+    },
+    {
+        name: 'secrets: create of an entry that exists, and delete of one that does not, are refused',
+        async run(client) {
+            const ref = NEW_REF();
+            const entry = { ref, external: 'acme_crm', binding: 'legacy', fields: { api_key: 'k1' } };
+            await client.call('secrets.create', entry);
+            await node_assert_1.strict.rejects(client.call('secrets.create', { ...entry, fields: { api_key: 'k9' } }), wire_1.SlotRefused);
+            node_assert_1.strict.equal((await client.read('secrets.resolve', { ref }, slots_1.SecretsRecord.nullable()))?.fields.api_key, 'k1', 'the refused create changed nothing');
+            await client.call('secrets.delete', { ref });
+            await node_assert_1.strict.rejects(client.call('secrets.delete', { ref }), wire_1.SlotRefused);
+        },
+    },
+    {
+        name: 'secrets: a second lock on a credential while one is held answers null; unlock frees it',
+        async run(client) {
+            const ref = NEW_REF();
+            const held = await client.read('secrets.lock', { ref, ttlMs: 30_000 }, slots_1.SecretsLockAnswer);
+            node_assert_1.strict.ok(held !== null, 'a free credential is locked');
+            node_assert_1.strict.equal(await client.call('secrets.lock', { ref, ttlMs: 30_000 }), null);
+            node_assert_1.strict.equal(await client.call('secrets.unlock', { ref, token: `${held.token}-not` }), null, 'a token that is not the lease\'s unlocks nothing');
+            node_assert_1.strict.equal(await client.call('secrets.lock', { ref, ttlMs: 30_000 }), null);
+            node_assert_1.strict.equal(await client.call('secrets.unlock', { ref, token: held.token }), null);
+            const again = await client.read('secrets.lock', { ref, ttlMs: 30_000 }, slots_1.SecretsLockAnswer);
+            node_assert_1.strict.ok(again !== null && again.token !== held.token, 'an unlocked credential is locked afresh, under a new token');
+            await client.call('secrets.unlock', { ref, token: again.token });
+        },
+    },
+    {
+        name: 'secrets: a lease whose ttl has lapsed is free, without an unlock',
+        async run(client) {
+            const ref = NEW_REF();
+            node_assert_1.strict.ok((await client.read('secrets.lock', { ref, ttlMs: 150 }, slots_1.SecretsLockAnswer)) !== null);
+            node_assert_1.strict.equal(await client.call('secrets.lock', { ref, ttlMs: 150 }), null, 'held until its ttl');
+            await sleep(400);
+            const taken = await client.read('secrets.lock', { ref, ttlMs: 30_000 }, slots_1.SecretsLockAnswer);
+            node_assert_1.strict.ok(taken !== null, 'a lapsed lease is taken over');
+            await client.call('secrets.unlock', { ref, token: taken.token });
+        },
+    },
+    {
+        name: 'secrets: assertWritable of a module that changes its entries answers null',
+        async run(client) {
+            node_assert_1.strict.equal(await client.call('secrets.assertWritable', { ref: NEW_REF() }), null);
+        },
+    },
+    {
+        name: 'secrets: a request without its ref, a lock without its ttl and an entry without its binding are refused as bad_request',
+        async run(client) {
+            await refusedWith('bad_request', client.call('secrets.resolve', {}));
+            await refusedWith('bad_request', client.call('secrets.lock', { ref: NEW_REF() }));
+            await refusedWith('bad_request', client.call('secrets.create', { ref: NEW_REF(), external: 'acme_crm', fields: {} }));
+        },
+    },
+];
+/** What a module that keeps its credentials where lf cannot change them
+ *  answers: `client` reaches one. Entries are refused by name with a reason;
+ *  everything a refresh needs still works. */
+exports.secretsReadOnlySlotCases = [
+    ...['secrets.create', 'secrets.replace'].map((method) => ({
+        name: `secrets: a read-only module answers ${method} with read_only and its reason, and keeps nothing`,
+        async run(client) {
+            const ref = NEW_REF();
+            const answer = await client.read(method, { ref, external: 'acme_crm', binding: 'legacy', fields: { api_key: 'k1' } }, slots_1.SecretsEntryAnswer);
+            node_assert_1.strict.ok(answer !== null && answer.kind === 'read_only' && answer.reason.length > 0, `${method} answered ${JSON.stringify(answer)}`);
+            node_assert_1.strict.equal(await client.call('secrets.resolve', { ref }), null);
+            node_assert_1.strict.equal((await listed(client)).find((entry) => entry.ref === ref), undefined);
+        },
+    })),
+    {
+        name: 'secrets: a read-only module answers secrets.delete with read_only and its reason',
+        async run(client) {
+            const answer = await client.read('secrets.delete', { ref: NEW_REF() }, slots_1.SecretsEntryAnswer);
+            node_assert_1.strict.ok(answer !== null && answer.kind === 'read_only' && answer.reason.length > 0, `secrets.delete answered ${JSON.stringify(answer)}`);
+        },
+    },
+    {
+        name: 'secrets: a read-only module answers secrets.assertWritable with read_only and its reason',
+        async run(client) {
+            const answer = await client.read('secrets.assertWritable', { ref: NEW_REF() }, slots_1.SecretsEntryAnswer);
+            node_assert_1.strict.ok(answer !== null && answer.kind === 'read_only' && answer.reason.length > 0, `secrets.assertWritable answered ${JSON.stringify(answer)}`);
+        },
+    },
+    {
+        name: 'secrets: a read-only module still lists, resolves and leases',
+        async run(client) {
+            const ref = NEW_REF();
+            node_assert_1.strict.ok(Array.isArray(await client.call('secrets.list', {})));
+            node_assert_1.strict.equal(await client.call('secrets.resolve', { ref }), null);
+            const held = await client.read('secrets.lock', { ref, ttlMs: 30_000 }, slots_1.SecretsLockAnswer);
+            node_assert_1.strict.ok(held !== null);
+            node_assert_1.strict.equal(await client.call('secrets.unlock', { ref, token: held.token }), null);
+        },
+    },
+];

package/dist/module_wire/secrets.d.ts

@@ -0,0 +1,14 @@
+import type { SecretFields, SecretRecord, SecretsBackend, WriteBackOutcome } from '../secrets/family';
+import { type SlotAddress } from './wire';
+export declare class SecretsSlotBackend implements SecretsBackend {
+    private readonly client;
+    constructor(address: SlotAddress, settings?: Record<string, string>);
+    resolve(ref: string): Promise<SecretRecord | null>;
+    writeBack(ref: string, fields: SecretFields, expectedVersion: string): Promise<WriteBackOutcome>;
+    /** The module's lease, asked for again until it is free, held for `body`. */
+    exclusive<T>(ref: string, body: (store: SecretsBackend) => Promise<T>): Promise<T>;
+    /** A write-back is not what `read_only` answers for: only a refusal fails here. */
+    assertWritable(ref: string): Promise<void>;
+    /** Store a new credential (a legacy entry bound to `external`). */
+    seed(ref: string, external: string, fields: SecretFields): Promise<void>;
+}

package/dist/module_wire/secrets.js

@@ -0,0 +1,52 @@
+"use strict";
+// A secrets module spoken to over the wire as the secrets family's store
+// (`SecretsBackend`, secrets/family.ts): how the family's contract cases
+// (movement-engine services/secrets/contract.ts) hold any module of the
+// secrets slot to the meaning every store has, whether the module is served
+// by lf (`lf --contract-secrets-slot`) or is a third party's.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecretsSlotBackend = void 0;
+const slots_1 = require("@listen-fire/engine-contracts/slots");
+const wire_1 = require("./wire");
+const LOCK_POLL_MS = 20;
+const LEASE_TTL_MS = 30_000;
+const LOCK_WAIT_MS = 10_000;
+class SecretsSlotBackend {
+    client;
+    constructor(address, settings = {}) {
+        this.client = new wire_1.SlotClient(address, settings);
+    }
+    resolve(ref) {
+        return this.client.read('secrets.resolve', { ref }, slots_1.SecretsRecord.nullable());
+    }
+    async writeBack(ref, fields, expectedVersion) {
+        return this.client.read('secrets.writeBack', { ref, fields, expectedVersion }, slots_1.SecretsWriteBackAnswer);
+    }
+    /** The module's lease, asked for again until it is free, held for `body`. */
+    async exclusive(ref, body) {
+        const until = Date.now() + LOCK_WAIT_MS;
+        for (;;) {
+            const lease = await this.client.read('secrets.lock', { ref, ttlMs: LEASE_TTL_MS }, slots_1.SecretsLockAnswer);
+            if (lease !== null) {
+                try {
+                    return await body(this);
+                }
+                finally {
+                    await this.client.call('secrets.unlock', { ref, token: lease.token });
+                }
+            }
+            if (Date.now() > until)
+                throw new Error(`the secrets module kept credential "${ref}" locked for ${LOCK_WAIT_MS / 1000}s`);
+            await new Promise((done) => setTimeout(done, LOCK_POLL_MS));
+        }
+    }
+    /** A write-back is not what `read_only` answers for: only a refusal fails here. */
+    async assertWritable(ref) {
+        await this.client.call('secrets.assertWritable', { ref });
+    }
+    /** Store a new credential (a legacy entry bound to `external`). */
+    async seed(ref, external, fields) {
+        await this.client.call('secrets.create', { ref, external, binding: 'legacy', fields });
+    }
+}
+exports.SecretsSlotBackend = SecretsSlotBackend;

package/dist/vendor_wait.d.ts

@@ -0,0 +1,8 @@
+/**
+ * How long the vendor asked a rate-limited caller to wait, or undefined when
+ * it did not say. Read from `e.headers` (a plain object or `Headers`; a
+ * `Response` is one) or `e.response.headers`, else Google's `RetryInfo` in an
+ * error's message. Clamped to [1s, 120s] so a hostile or absurd value can
+ * neither spin nor stall a caller.
+ */
+export declare function vendorWaitMs(e: unknown, now?: number): number | undefined;

package/dist/vendor_wait.js

@@ -0,0 +1,64 @@
+"use strict";
+// How long a rate-limited vendor asked its caller to wait. Here, below both
+// the engine and the module kit, so the kit's limits door and the engine's
+// limiter (`throttleAfter`, movement-engine/public/limiter) read one parser.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vendorWaitMs = vendorWaitMs;
+const SECOND = 1000;
+const MIN_WAIT_MS = 1 * SECOND;
+const MAX_WAIT_MS = 120 * SECOND;
+function clamp(ms) {
+    return Math.min(MAX_WAIT_MS, Math.max(MIN_WAIT_MS, Math.round(ms)));
+}
+/** `Retry-After` is either whole seconds or an HTTP date. */
+function fromHeaderValue(value, now) {
+    const trimmed = value.trim();
+    if (/^\d+(\.\d+)?$/.test(trimmed))
+        return Number(trimmed) * SECOND;
+    const date = Date.parse(trimmed);
+    return Number.isNaN(date) ? undefined : date - now;
+}
+function readHeader(headers, name) {
+    if (!headers || typeof headers !== 'object')
+        return undefined;
+    if ('get' in headers && typeof headers.get === 'function') {
+        const value = headers.get(name);
+        return typeof value === 'string' ? value : undefined;
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === name && typeof value === 'string')
+            return value;
+    }
+    return undefined;
+}
+function field(value, name) {
+    return typeof value === 'object' && value !== null ? Reflect.get(value, name) : undefined;
+}
+/**
+ * Google's `google.rpc.RetryInfo` detail: `"retryDelay": "17s"` (or
+ * `"17.5s"`) on the wire, `{ seconds: 17 }` in a decoded form. The genai SDK's
+ * `ApiError` carries the JSON body only as text in its message.
+ */
+function fromRetryInfo(text) {
+    const quoted = /"retryDelay"\s*:\s*"(\d+(?:\.\d+)?)s"/.exec(text);
+    if (quoted)
+        return Number(quoted[1]) * SECOND;
+    const object = /"retryDelay"\s*:\s*\{\s*"seconds"\s*:\s*"?(\d+)"?/.exec(text);
+    return object ? Number(object[1]) * SECOND : undefined;
+}
+/**
+ * How long the vendor asked a rate-limited caller to wait, or undefined when
+ * it did not say. Read from `e.headers` (a plain object or `Headers`; a
+ * `Response` is one) or `e.response.headers`, else Google's `RetryInfo` in an
+ * error's message. Clamped to [1s, 120s] so a hostile or absurd value can
+ * neither spin nor stall a caller.
+ */
+function vendorWaitMs(e, now = Date.now()) {
+    const header = readHeader(field(e, 'headers'), 'retry-after') ?? readHeader(field(field(e, 'response'), 'headers'), 'retry-after');
+    const fromHeader = header === undefined ? undefined : fromHeaderValue(header, now);
+    if (fromHeader !== undefined)
+        return clamp(fromHeader);
+    const text = e instanceof Error ? e.message : undefined;
+    const fromBody = text === undefined ? undefined : fromRetryInfo(text);
+    return fromBody === undefined ? undefined : clamp(fromBody);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@listen-fire/module-runtime",
   "license": "Apache-2.0",
-  "version": "0.12.0-rc.7",
+  "version": "0.12.0-rc.8",
   "description": "What a module and the host that loads it share at run time on Node, beside the runtime-neutral contracts (@listen-fire/engine-contracts): a live adapter's file bytes as a stream, the files slot, the secrets family with the generic OAuth 2 refresh and connect, the in-memory vault, the browser slot and a bounded concurrency queue. The engine and the module kit both depend on it, so the kit never depends on the engine",
   "engines": {
     "node": "22.20.0"
@@ -22,7 +22,7 @@
   "type": "commonjs",
   "dependencies": {
     "zod": "4.1.12",
-    "@listen-fire/engine-contracts": "^0.12.0-rc.7"
+    "@listen-fire/engine-contracts": "^0.12.0-rc.8"
   },
   "devDependencies": {
     "@types/node": "20.16.5",