@cotal-ai/core 0.113.0 → 0.113.3

package/dist/endpoint.js

@@ -28,11 +28,12 @@ import { jetstream, jetstreamManager, AckPolicy, DeliverPolicy, JetStreamApiCode
 import {} from "@nats-io/jetstream";
 import { Kvm } from "@nats-io/kv";
 import { Bucket, KvWatchInclude } from "@nats-io/kv/internal";
-import { openMembersRegistry, commitMember, tombstoneMember, activateMember, readMember, listMembers, listLifecycleMemberChannels, durableEligible, StaleMembershipWrite, } from "./members.js";
+import { openMembersRegistry, commitMember, commitMemberRevision, tombstoneMember, activateMember, readMember, deleteMember, listMembers, listLifecycleMemberChannels, durableEligible, StaleMembershipWrite, } from "./members.js";
 import { openAclRegistry, readAcl, readAclForAlias, aclRetired, AmbiguousAclAlias, commitAcl as writeAclRecord, reissueAcl as writeAclReissue } from "./acls.js";
 import { openDeliveryRegistry } from "./lease.js";
 import { openChannelRegistry, effectiveReplay, effectiveReplayWindowMs, effectiveDeliveryClass, readChannelConfig, readChannelDefaults, decodeChannelEntry, } from "./channels.js";
-import { anycastSubject, assertValidRole, CHANNEL_DEFAULTS_KEY, chatStream, chatHistDurable, chatSubject, historyReaderConsumer, calloutReaderId, HISTORY_READERS, controlServiceSubject, livenessSubject, livenessServeFilter, CONTROL_DELIVERY, CONTROL_DELIVERY_ADMIN, dmStream, dmDurable, dlvStream, dlvDurable, dlvSubject, dinboxSubject, inboxStream, parseDinboxPrincipal, FANOUT_DURABLE, INBOX_READER_DURABLE, leaseKey, managerBucket, MANAGER_LEASE_KEY, MANAGER_RENEWAL_LEASE_KEY, managerLeaseKey, chatWildcard, assertValidChannel, channelInAllow, isConcreteChannel, normalizeMentions, parseSubject, isPrincipalOwnerToken, assertInboxConnId, presenceBucket, isPresenceRow, membershipBucket, MEMBERSHIP_FEED_KEY, principalKey, parsePrincipalKey, assertLifecycleToken, mintLifecycleUid, lifecycleNameKey, DEV_OWNER, spacePrefix, spaceWildcard, subjectMatches, taskStream, taskDurable, token, unicastSubject, unicastRecvFilter, } from "./subjects.js";
+import { isCasLoss } from "./endpoint-records.js";
+import { anycastSubject, assertValidRole, CHANNEL_DEFAULTS_KEY, chatStream, chatHistDurable, chatSubject, historyReaderConsumer, calloutReaderId, HISTORY_READERS, controlServiceSubject, livenessSubject, livenessServeFilter, CONTROL_DELIVERY, CONTROL_DELIVERY_ADMIN, dmStream, dmDurable, dlvStream, dlvDurable, dlvSubject, dinboxSubject, inboxStream, parseDinboxPrincipal, FANOUT_DURABLE, INBOX_READER_DURABLE, leaseKey, managerBucket, MANAGER_LEASE_KEY, MANAGER_RENEWAL_LEASE_KEY, managerLeaseKey, chatWildcard, assertValidChannel, channelInAllow, isConcreteChannel, normalizeMentions, parseSubject, isPrincipalOwnerToken, assertInboxConnId, presenceBucket, isPresenceRow, membershipBucket, MEMBERSHIP_FEED_KEY, principalKey, parsePrincipalKey, assertLifecycleToken, mintLifecycleUid, lifecycleNameKey, memberKey, DEV_OWNER, spacePrefix, spaceWildcard, subjectMatches, taskStream, taskDurable, token, unicastSubject, unicastRecvFilter, } from "./subjects.js";
 import { isPermissionDenied } from "./permission-denied.js";
 export { isPermissionDenied };
 export const DEFAULT_SERVER = "nats://127.0.0.1:4222";
@@ -259,7 +260,9 @@ export class CotalEndpoint extends EventEmitter {
      *  (#4965). A durable join or leave bound to one of them is refused, so no row of a retiring lifecycle
      *  is written after its inventory read starts. An entry goes when a later inventory for the same
      *  principal finds its ACL row retired; an alias that never retires again keeps its one entry until
-     *  the daemon restarts. */
+     *  the daemon restarts. This is the second layer of the fence: it covers a manager that does not
+     *  narrow the ACL row before the inventory, on this daemon process only. The first is the ACL row
+     *  each join re-reads around its write (`durableJoinFor`'s `aclFence`), which holds across daemons. */
     retiringLifecycles = new Map();
     /** The durable joins and leaves running now, by `<principal>/<lifecycleUid>`: the writes an
      *  inventory of that lifecycle waits for before it reads. */
@@ -4728,8 +4731,15 @@ export class CotalEndpoint extends EventEmitter {
      *
      * Runs on the daemon (which hosts the fan-out/reader loops + the members KV), so catch-up + the
      * activation fence read are in-process — no cross-process cursor read.
+     *
+     * `aclFence` (the `ctl.delivery` join always sets it) re-reads the lifecycle's exact ACL row
+     * immediately before the write that creates or reopens its row, and again after it. When the channel
+     * is no longer within that row, the join is refused, and a row it already wrote is removed first.
+     * A retirement narrows that ACL row before it reads the lifecycle's inventory (fenceLifecycleAcl),
+     * so a row written too late for the inventory removes itself, whichever daemon process wrote it.
+     * Without the option the write is a privileged assertion that consults no ACL.
      */
-    async durableJoinFor(owner, channel, lifecycleUid) {
+    async durableJoinFor(owner, channel, lifecycleUid, opts = {}) {
         if (!this.js)
             throw new Error("endpoint not started");
         await this.manager(); // ensure jsm — a non-consuming provisioner inits it lazily; catch-up + fence need it
@@ -4752,8 +4762,13 @@ export class CotalEndpoint extends EventEmitter {
             channel, owner, lifecycleUid, state: "durable-active", joinCursor, generation,
             activated: false, writerIdentity: this.card.id, updatedAt: Date.now(),
         };
-        if (!open)
-            await commitMember(kv, base);
+        if (!open) {
+            if (opts.aclFence && !(await this.aclAllows(owner, lifecycleUid, channel)))
+                throw new Error(`durableJoin: "${channel}" is no longer within the read ACL of lifecycle ${lifecycleUid} (narrowed or retired); no membership row was written`);
+            const written = await commitMemberRevision(kv, base);
+            if (opts.aclFence)
+                await this.keepRowIfAclAllows(kv, owner, lifecycleUid, channel, written.revision);
+        }
         const fence = Math.max(await this.chatFrontier(), await this.fanoutDeliveredSeq());
         const cu = await this.catchupCopy(owner, lifecycleUid, channel, joinCursor, fence, generation);
         if (cu.evicted) {
@@ -4781,6 +4796,44 @@ export class CotalEndpoint extends EventEmitter {
             return { durable: false, reason: "activation superseded by a concurrent leave or rejoin", generation };
         return { durable: true, generation };
     }
+    /** Whether one lifecycle's exact ACL row allows `channel` now. A leader-served read: the handle is
+     *  opened without direct reads, so a row narrowed before this read began is the row it returns. */
+    async aclAllows(owner, lifecycleUid, channel) {
+        const row = await readAcl(await this.aclRegistry(), owner, lifecycleUid);
+        return row !== undefined && channelInAllow(row.record.allowSubscribe, channel);
+    }
+    /** The post-write half of {@link durableJoinFor}'s `aclFence`: keep the row just written (at
+     *  `revision`) only on proof that the lifecycle's ACL row still allows the channel, and refuse the
+     *  join otherwise. When the ACL row proves the channel is no longer allowed, no row of the lifecycle
+     *  on that channel is wanted, so the row goes by its exact key whoever wrote its latest revision.
+     *  When the read itself fails, nothing is proven either way, so only this write is taken back: a
+     *  later revision belongs to another join of the same lifecycle, which may have been authorized. */
+    async keepRowIfAclAllows(kv, owner, lifecycleUid, channel, revision) {
+        let disallowed = false;
+        let why;
+        try {
+            if (await this.aclAllows(owner, lifecycleUid, channel))
+                return;
+            disallowed = true;
+            why = "was narrowed or retired while the row was written";
+        }
+        catch (e) {
+            why = `could not be re-read after the row was written (${e.message})`;
+        }
+        const fail = (outcome, cause) => new Error(`durableJoin: the read ACL of lifecycle ${lifecycleUid} ${why}; ${outcome}`, cause === undefined ? undefined : { cause });
+        try {
+            if (disallowed)
+                await deleteMember(kv, channel, owner, lifecycleUid);
+            else
+                await kv.purge(memberKey(channel, owner, lifecycleUid), { previousSeq: revision });
+        }
+        catch (e) {
+            if (!disallowed && isCasLoss(e))
+                throw fail(`a later write replaced its "${channel}" row, which was left to that write`);
+            throw fail(`removing its "${channel}" row failed (${e.message})`, e);
+        }
+        throw fail(`its "${channel}" row was removed`);
+    }
     /** Privileged durable-LEAVE write: tombstone the membership at `leaveCursor = frontier` so the
      *  backstop denies `seq > leaveCursor` while a pre-leave entry stays deliverable (SPEC §7 interval). */
     async durableLeaveFor(owner, channel, lifecycleUid, expectedGeneration) {
@@ -4959,8 +5012,10 @@ export class CotalEndpoint extends EventEmitter {
         if (!channelInAllow(acl.allowSubscribe, channel))
             return { ok: false, error: `channel "${channel}" is not within your read ACL [${acl.allowSubscribe.join(", ")}]` };
         const uid = acl.lifecycleUid;
+        // The lookup above may be stale by the time the row is written (a retirement can fence and purge
+        // this lifecycle meanwhile), so the write re-checks the exact ACL row itself (`aclFence`).
         try {
-            return { ok: true, data: await this.membershipWrite(caller, uid, () => this.durableJoinFor(caller, channel, uid)) };
+            return { ok: true, data: await this.membershipWrite(caller, uid, () => this.durableJoinFor(caller, channel, uid, { aclFence: true })) };
         }
         catch (e) {
             return { ok: false, error: e.message };
@@ -5575,9 +5630,11 @@ export class CotalEndpoint extends EventEmitter {
             catch (e) {
                 return { ok: false, error: `lifecycleMemberships: ${e.message}` };
             }
-            // The lifecycle is retiring, so its memberships stop changing here (#4965): a join or leave bound
-            // to it is refused from now on, and the read starts after the ones already running have finished.
-            // A row they write is then in the read; nothing it misses can be written afterwards.
+            // A retirement fences the lifecycle's ACL row before it asks (fenceLifecycleAcl), and every join
+            // re-reads that row around the row it creates, so a row written after this read begins removes
+            // itself, on whichever daemon wrote it. For a manager that does not fence, this daemon's own
+            // memberships of the lifecycle stop changing here (#4965): a join or leave bound to it is refused
+            // from now on, and the read starts after the ones already running have finished.
             let marked = this.retiringLifecycles.get(principal);
             if (marked === undefined)
                 this.retiringLifecycles.set(principal, (marked = new Set()));