@spine-event-engine/auth 2.0.0-snapshot.25 → 2.0.0-snapshot.28

package/dist/subscriptions/index.js

@@ -13,6 +13,7 @@
  */
 import { clone, create, fromBinary, toBinary } from "@bufbuild/protobuf";
 import { SUBSCRIPTION_ACTIVATION_HANDSHAKE_MS } from "@spine-event-engine/core/spi/subscription-lifecycle";
+import { ReaderIdentities, snapshotTrustedReader, } from "@spine-event-engine/core/spi/trusted-reader";
 import { ActorContextSchema, TenantIdSchema } from "@spine-event-engine/proto";
 import { SubscriptionSchema, SubscriptionUpdateSchema, TopicSchema, } from "@spine-event-engine/proto/client";
 import { IncomingRequests } from "../request/index.js";
@@ -34,6 +35,7 @@ export class InMemorySubscriptionBindings {
     #limits;
     /**
      * Creates the in-memory binding store.
+     *
      * @param options Supplies identifiers, process limits, and disposal behavior.
      */
     constructor(options) {
@@ -43,6 +45,7 @@ export class InMemorySubscriptionBindings {
     }
     /**
      * Returns the number of retained private bindings for lifecycle observability.
+     *
      * @returns Returns the retained binding count.
      */
     get size() {
@@ -50,6 +53,7 @@ export class InMemorySubscriptionBindings {
     }
     /**
      * Removes already-expired logical bindings without a background timer.
+     *
      * @param nowMs Supplies the current time in milliseconds.
      * @returns Completes after expired envelopes are removed.
      */
@@ -61,14 +65,13 @@ export class InMemorySubscriptionBindings {
     }
     /**
      * Closes the store by aborting work and waiting for bounded cleanup.
-     *
      * Cooperative callbacks allow cleanup to complete before this method resolves.
      * Non-cooperative raw callbacks cause an `AggregateError` after
      * `shutdownTimeoutMs`; their exactly-once disposal remains queued until they
      * settle.
+     * `AggregateError` when cleanup exceeds its shutdown limit.
      *
      * @returns Completes after bounded cooperative cleanup, or rejects with an
-     * `AggregateError` when cleanup exceeds its shutdown limit.
      */
     async close() {
         this.#closed = true;
@@ -84,6 +87,7 @@ export class InMemorySubscriptionBindings {
     }
     /**
      * Creates an inactive binding from a trusted rewritten topic.
+     *
      * @param input Supplies the topic and expiry.
      * @returns Returns the retained public subscription wire.
      */
@@ -103,6 +107,7 @@ export class InMemorySubscriptionBindings {
             this.#bindings.set(id, {
                 definition: wire.wire.bytes.slice(),
                 context: clone(ActorContextSchema, topic.context),
+                reader: input.reader,
                 expiresAtMs: input.whenExpires,
                 state: "inactive",
                 controller: new AbortController(),
@@ -120,6 +125,7 @@ export class InMemorySubscriptionBindings {
     }
     /**
      * Activates only an owned inactive binding and restores retry state after callback failure.
+     *
      * @param input Supplies ownership facts and the backend callback.
      * @returns Returns the ownership transition outcome.
      */
@@ -134,6 +140,9 @@ export class InMemorySubscriptionBindings {
                 return { kind: "denied" };
             binding.state = "active";
             binding.controller = new AbortController();
+            /**
+             * Cancels this activation when the caller aborts.
+             */
             const abort = () => {
                 binding.controller.abort();
             };
@@ -155,6 +164,7 @@ export class InMemorySubscriptionBindings {
     }
     /**
      * Cancels an owned binding and retains retry state after failed cleanup.
+     *
      * @param input Supplies ownership facts and the backend callback.
      * @returns Returns the ownership transition outcome.
      */
@@ -182,7 +192,12 @@ export class InMemorySubscriptionBindings {
             return { kind: "closed" };
         });
     }
-    #owned(input) {
+    /**
+     * Checks whether the retained binding still matches its current ID slot.
+     *
+     * @param input Retained binding and current lifecycle state.
+     * @returns Whether this binding is still current.
+     */ #owned(input) {
         const binding = this.#bindings.get(input.id);
         if (binding === undefined)
             return Promise.resolve(undefined);
@@ -190,15 +205,22 @@ export class InMemorySubscriptionBindings {
             this.#expire(input.id, binding);
             return Promise.resolve(undefined);
         }
-        return SubscriptionGatewayValues.contextsEqual(binding.context, input.context)
+        return SubscriptionGatewayValues.contextsEqual(binding.context, input.context) &&
+            ReaderIdentities.matches(binding.reader, input.reader)
             ? Promise.resolve(binding)
             : Promise.resolve(undefined);
     }
-    #precheck(input) {
+    /**
+     * Checks retained binding state before an asynchronous effect.
+     *
+     * @param input Retained binding and current lifecycle state.
+     * @returns Whether the effect may proceed.
+     */ #precheck(input) {
         const binding = this.#bindings.get(input.id);
         if (binding === undefined)
             return "absent";
-        if (!SubscriptionGatewayValues.contextsEqual(binding.context, input.context))
+        if (!SubscriptionGatewayValues.contextsEqual(binding.context, input.context) ||
+            !ReaderIdentities.matches(binding.reader, input.reader))
             return "denied";
         if (binding.expiring ||
             (binding.expiresAtMs !== undefined && binding.expiresAtMs <= input.nowMs)) {
@@ -207,7 +229,12 @@ export class InMemorySubscriptionBindings {
         }
         return "owned";
     }
-    #expire(id, binding) {
+    /**
+     * Expires one retained binding only if it is still current.
+     *
+     * @param id The stable identifier for this record.
+     * @param binding Retained subscription binding.
+     */ #expire(id, binding) {
         if (binding.expiring || this.#bindings.get(id) !== binding)
             return;
         binding.expiring = true;
@@ -215,16 +242,33 @@ export class InMemorySubscriptionBindings {
         // spine-log-boundary: auth.subscription_expiry_cleanup
         void this.#disposeAfterWork(id, binding).catch(() => undefined);
     }
-    #dispose(id, binding) {
+    /**
+     * Clears retained definition bytes and releases binding state.
+     *
+     * @param id The stable identifier for this record.
+     * @param binding Retained subscription binding.
+     */ #dispose(id, binding) {
         binding.definition.fill(0);
         binding.state = "closed";
         this.#bindings.delete(id);
     }
-    async #runEffect(binding, callback) {
+    /**
+     * Starts one retained definition effect and tracks its completion.
+     *
+     * @param binding Retained subscription binding.
+     * @param callback Definition or lifecycle callback.
+     * @returns Completion after the operation settles.
+     */ async #runEffect(binding, callback) {
         const effect = this.#startEffect(binding, callback);
         await SubscriptionGatewayValues.withTimeout(effect, this.#limits.operationTimeoutMs, binding.controller);
     }
-    async #runActiveEffect(binding, callback) {
+    /**
+     * Runs a retained binding effect while observing cancellation.
+     *
+     * @param binding Retained subscription binding.
+     * @param callback Definition or lifecycle callback.
+     * @returns Completion after the operation settles.
+     */ async #runActiveEffect(binding, callback) {
         let observeAbort = () => undefined;
         const aborted = new Promise((resolve) => {
             observeAbort = () => {
@@ -245,7 +289,13 @@ export class InMemorySubscriptionBindings {
         }
         throw new Error("subscription operation aborted");
     }
-    #startEffect(binding, callback) {
+    /**
+     * Builds the public definition callback effect for a retained binding.
+     *
+     * @param binding Retained subscription binding.
+     * @param callback Definition or lifecycle callback.
+     * @returns Completion after the operation settles.
+     */ #startEffect(binding, callback) {
         const definition = SubscriptionGatewayValues.copyPublic({
             kind: "public-subscription",
             bytes: binding.definition,
@@ -265,7 +315,13 @@ export class InMemorySubscriptionBindings {
         void settled.then(() => definition.bytes.fill(0));
         return effect;
     }
-    #disposeAfterWork(id, binding) {
+    /**
+     * Waits for active callback work before clearing a binding.
+     *
+     * @param id The stable identifier for this record.
+     * @param binding Retained subscription binding.
+     * @returns Completion after the operation settles.
+     */ #disposeAfterWork(id, binding) {
         const cleanup = binding.tail
             .then(() => binding.effectTail)
             .then(() => this.#disposeWithCallback(id, binding));
@@ -275,10 +331,21 @@ export class InMemorySubscriptionBindings {
         void cleanup.catch(() => undefined);
         return cleanup;
     }
-    #waitForShutdown(cleanup) {
+    /**
+     * Waits for accepted binding effects before disposal.
+     *
+     * @param cleanup Resource cleanup operation.
+     * @returns Completion after the operation settles.
+     */ #waitForShutdown(cleanup) {
         return SubscriptionGatewayValues.withTimeout(cleanup, this.#limits.shutdownTimeoutMs, new AbortController());
     }
-    async #disposeWithCallback(id, binding) {
+    /**
+     * Detaches a retained binding and invokes its cleanup callback.
+     *
+     * @param id The stable identifier for this record.
+     * @param binding Retained subscription binding.
+     * @returns Completion after the operation settles.
+     */ async #disposeWithCallback(id, binding) {
         if (this.#bindings.get(id) !== binding)
             return;
         const definition = SubscriptionGatewayValues.copyPublic({
@@ -337,8 +404,10 @@ export class SubscriptionGateway {
     #publicPendingTimers = new Map();
     #cancellations = new Map();
     #closed = false;
+    #operations = new Set();
     /**
      * Creates the subscription gateway.
+     *
      * @param options Supplies admission, authorization, binding, and backend collaborators.
      */
     constructor(options) {
@@ -349,6 +418,7 @@ export class SubscriptionGateway {
     }
     /**
      * Handles one admitted subscription RPC request.
+     *
      * @param request Supplies the copied request admission facts.
      * @returns Returns the opaque operation result.
      */
@@ -367,10 +437,13 @@ export class SubscriptionGateway {
     }
     /**
      * Closes admission and closes retained bindings.
+     *
      * @returns Completes after retained bindings close.
      */
     async close() {
         this.#closed = true;
+        for (const operation of this.#operations)
+            operation.abort();
         for (const timer of this.#expiryTimers)
             clearTimeout(timer);
         this.#expiryTimers.clear();
@@ -381,9 +454,19 @@ export class SubscriptionGateway {
     }
     /**
      * Schedules finite local expiry cleanup for a recovered durable definition.
+     *
      * @param whenExpires Supplies the retained expiry in epoch milliseconds.
      */
     scheduleExpiry(whenExpires) {
+        this.#scheduleExpiry(whenExpires);
+    }
+    /**
+     * Retains one finite cleanup timer and exposes its handle for admission rollback.
+     *
+     * @param whenExpires Retained definition expiry in epoch milliseconds.
+     * @returns Scheduled timer, or nothing when scheduling is unavailable.
+     */
+    #scheduleExpiry(whenExpires) {
         const nowMs = this.#nowMs();
         if (nowMs === undefined || this.#closed)
             return;
@@ -393,8 +476,136 @@ export class SubscriptionGateway {
             void this.#options.bindings.purgeExpired(whenExpires).catch(() => undefined);
         }, Math.max(0, whenExpires - nowMs));
         this.#expiryTimers.add(timer);
+        return () => {
+            clearTimeout(timer);
+            this.#expiryTimers.delete(timer);
+        };
+    }
+    /**
+     * Rejects stale or malformed gateway operations before binding mutations.
+     *
+     * @param request The request being processed.
+     * @returns Authorized result or a structured rejection.
+     */ async #handleOperation(request) {
+        const operation = new AbortController();
+        const onAbort = () => {
+            operation.abort();
+        };
+        request.signal?.addEventListener("abort", onAbort, { once: true });
+        if (request.signal?.aborted)
+            onAbort();
+        this.#operations.add(operation);
+        let invalidated;
+        try {
+            const prepared = await this.#prepareOperation(request, operation.signal);
+            if ("kind" in prepared)
+                return prepared;
+            invalidated = prepared.invalidated;
+            invalidated?.addEventListener("abort", onAbort, { once: true });
+            if (invalidated?.aborted)
+                onAbort();
+            if (operation.signal.aborted)
+                return SubscriptionGatewayValues.rejected("denied");
+            const result = await this.#perform(prepared, request.updates, operation.signal);
+            // The admitted operation can end while #perform settles.
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            if (operation.signal.aborted)
+                return await this.#rejectLate(prepared, result);
+            if (result.kind === "subscribed") {
+                const finished = this.#finishCreated(prepared, result, operation.signal);
+                return finished instanceof Promise ? await finished : finished;
+            }
+            return result;
+        }
+        finally {
+            operation.abort();
+            this.#operations.delete(operation);
+            request.signal?.removeEventListener("abort", onAbort);
+            invalidated?.removeEventListener("abort", onAbort);
+        }
+    }
+    /**
+     * Schedules a confirmed result and returns it without an additional success await.
+     *
+     * @param prepared Captured actor, reader and expiry facts.
+     * @param result Confirmed created definition.
+     * @param signal Effective operation lifetime.
+     * @returns Result, denial or failure after any required cleanup.
+     */
+    #finishCreated(prepared, result, signal) {
+        try {
+            this.#scheduleCreated(prepared, result, signal);
+        }
+        catch (error) {
+            return this.#failCreated(prepared, result, error);
+        }
+        if (signal.aborted)
+            return this.#rejectLate(prepared, result);
+        return result;
+    }
+    /**
+     * Starts local maintenance only after a Subscribe result passes final admission.
+     *
+     * @param prepared Captured actor, reader and expiry facts.
+     * @param result Confirmed created definition.
+     * @param signal Effective operation lifetime.
+     */
+    #scheduleCreated(prepared, result, signal) {
+        const id = fromBinary(SubscriptionSchema, result.wire.bytes).id?.value;
+        if (id === undefined || id.length === 0)
+            throw new Error("retained subscription has no ID");
+        if (this.#options.publicAccess === true)
+            this.#schedulePublicPending(id, prepared.context);
+        if (prepared.expiresAtMs !== undefined) {
+            const cancelTimer = this.#scheduleExpiry(prepared.expiresAtMs);
+            if (signal.aborted)
+                cancelTimer?.();
+        }
+        if (signal.aborted)
+            this.#clearPublicPending(id);
     }
-    async #handleOperation(request) {
+    /**
+     * Preserves a scheduling failure and any subsequent definition cleanup failure.
+     *
+     * @param prepared Captured actor and reader facts.
+     * @param result Confirmed created definition.
+     * @param error Scheduling failure.
+     * @returns Rejected completion after cleanup is attempted.
+     */
+    async #failCreated(prepared, result, error) {
+        try {
+            await this.#rejectLate(prepared, result);
+        }
+        catch (cleanup) {
+            throw new AggregateError([error, cleanup], "Subscription scheduling cleanup failed.");
+        }
+        throw error;
+    }
+    /**
+     * Denies an outcome completed after operation invalidation and clears confirmed creation.
+     *
+     * @param prepared Captured actor and reader facts.
+     * @param result Completed operation outcome.
+     * @returns Denial after any confirmed definition is removed.
+     */
+    async #rejectLate(prepared, result) {
+        if (result.kind === "subscribed") {
+            const id = fromBinary(SubscriptionSchema, result.wire.bytes).id?.value;
+            if (id === undefined || id.length === 0)
+                throw new Error("retained subscription has no ID");
+            await this.#discardCreated(id, prepared.context, prepared.reader, this.#nowMs() ?? prepared.nowMs, { ...result.wire, reader: prepared.reader }, new AbortController());
+            this.#clearPublicPending(id);
+        }
+        return SubscriptionGatewayValues.rejected("denied");
+    }
+    /**
+     * Validates request and security before the selected operation mutates state.
+     *
+     * @param request Copied admission facts.
+     * @param signal Host-managed operation cancellation.
+     * @returns Prepared operation or rejection.
+     */
+    async #prepareOperation(request, signal) {
         const kind = SubscriptionGatewayValues.operationFor(request);
         if (kind === undefined)
             return SubscriptionGatewayValues.rejected("unknown-operation");
@@ -409,12 +620,18 @@ export class SubscriptionGateway {
                 return SubscriptionGatewayValues.rejected("binding-busy");
             throw error;
         }
-        const prepared = await this.#prepareSecurity(kind, request);
-        if ("kind" in prepared)
-            return prepared;
-        return this.#perform(prepared, request.updates, request.signal);
+        if (signal.aborted)
+            return SubscriptionGatewayValues.rejected("denied");
+        return this.#prepareSecurity(kind, request, signal);
     }
-    async #prepareSecurity(kind, request) {
+    /**
+     * Resolves the session and policy decision for one subscription operation.
+     *
+     * @param kind Requested subscription operation.
+     * @param request The request being processed.
+     * @param signal Host-managed operation cancellation.
+     * @returns Prepared operation or an authentication/policy rejection.
+     */ async #prepareSecurity(kind, request, signal) {
         const source = SubscriptionGatewayValues.decode(kind, request.wire.bytes, request.transport);
         if (source === undefined)
             return SubscriptionGatewayValues.rejected("malformed-request");
@@ -422,128 +639,304 @@ export class SubscriptionGateway {
             ? { principal: SubscriptionGatewayValues.publicPrincipal }
             : request.credential === undefined
                 ? undefined
-                : await this.#options.sessions.resolve(request.credential);
+                : await this.#options.sessions.resolve(request.credential, signal);
         if (session === undefined)
             return SubscriptionGatewayValues.rejected("unauthenticated");
+        const verified = this.#snapshotSession(session);
+        if (signal.aborted || verified.invalidated?.aborted)
+            return SubscriptionGatewayValues.rejected("denied");
         const authorization = SubscriptionGatewayValues.decode(kind, request.wire.bytes, request.transport);
         if (authorization === undefined ||
-            !(await this.#options.authorize(session.principal, authorization)))
+            !(await this.#options.authorize(verified.principal, authorization)))
             return SubscriptionGatewayValues.rejected("forbidden");
-        return this.#resolveTrusted(kind, request, source, session);
+        // Authorization can suspend while either signal changes.
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (signal.aborted || verified.invalidated?.aborted)
+            return SubscriptionGatewayValues.rejected("denied");
+        return this.#resolveTrusted(kind, request, source, verified);
+    }
+    /**
+     * Captures session identity, expiry and invalidation before downstream awaits.
+     *
+     * @param session Resolver result or explicit public session.
+     * @returns Detached immutable admission facts with the original signal.
+     */
+    #snapshotSession(session) {
+        const principal = snapshotTrustedReader({ principal: session.principal }).principal;
+        if (principal === undefined)
+            throw new Error("Resolved session has no principal.");
+        const expiresAt = session.expiresAt;
+        const invalidated = session.invalidated;
+        return Object.freeze({
+            principal,
+            ...(expiresAt === undefined
+                ? {}
+                : { expiresAt: Object.freeze({ seconds: expiresAt.seconds, nanos: expiresAt.nanos }) }),
+            ...(invalidated === undefined ? {} : { invalidated }),
+        });
     }
-    async #resolveTrusted(kind, request, source, session) {
+    /**
+     * Builds detached trusted reader and actor facts after policy admission.
+     *
+     * @param kind Requested subscription operation.
+     * @param request The request being processed.
+     * @param source Decoded incoming subscription request.
+     * @param session Resolved gateway session or explicit public principal.
+     * @returns Prepared operation or a structured context rejection.
+     */ async #resolveTrusted(kind, request, source, session) {
         const contextRequest = SubscriptionGatewayValues.decode(kind, request.wire.bytes, request.transport);
         if (contextRequest === undefined)
             return SubscriptionGatewayValues.rejected("malformed-request");
-        const context = SubscriptionGatewayValues.trustedContext(await this.#options.contexts.resolve(session.principal, contextRequest, this.#options.clock));
+        const resolved = await this.#options.contexts.resolve(session.principal, contextRequest, this.#options.clock);
+        const context = SubscriptionGatewayValues.trustedContext(resolved);
+        const reader = this.#trustedReader(session.principal, resolved);
         const nowMs = this.#nowMs();
-        const expiresAtMs = session.expiresAt === undefined
-            ? undefined
-            : SubscriptionGatewayValues.timestampMs(session.expiresAt.seconds, session.expiresAt.nanos);
-        if (nowMs === undefined ||
-            (this.#options.publicAccess !== true && expiresAtMs === undefined) ||
-            (expiresAtMs !== undefined && expiresAtMs <= nowMs) ||
-            !SubscriptionGatewayValues.matches(source.requestedContext, context))
+        const expiresAtMs = this.#expiresAtMs(session.expiresAt);
+        if (nowMs === undefined || !this.#validContext(source, context, nowMs, expiresAtMs))
             return SubscriptionGatewayValues.rejected("denied");
         return {
             source,
             context,
+            reader,
             expiresAtMs,
             nowMs,
+            ...(session.invalidated === undefined ? {} : { invalidated: session.invalidated }),
         };
     }
-    #nowMs() {
+    /**
+     * Converts a verified session expiry into the gateway clock's millisecond unit.
+     *
+     * @param value Verified session expiry timestamp, if present.
+     * @returns The expiry in epoch milliseconds.
+     */
+    #expiresAtMs(value) {
+        return value === undefined
+            ? undefined
+            : SubscriptionGatewayValues.timestampMs(value.seconds, value.nanos);
+    }
+    /**
+     * Detaches the verified principal and current authority facts from the resolver.
+     *
+     * @param principal Verified principal from session resolution.
+     * @param resolved Resolved context and authority facts.
+     * @returns The detached verified reader facts.
+     */
+    #trustedReader(principal, resolved) {
+        return snapshotTrustedReader({
+            ...(this.#options.publicAccess === true ? {} : { principal }),
+            ...(this.#options.publicAccess === true || resolved.authorityFacts === undefined
+                ? {}
+                : { authorityFacts: resolved.authorityFacts }),
+        });
+    }
+    /**
+     * Checks session time and the resolver's trusted actor/tenant against the request.
+     *
+     * @param source Decoded incoming subscription request.
+     * @param context The trusted context for this operation.
+     * @param nowMs The current time in milliseconds.
+     * @param expiresAtMs The session expiry in milliseconds, when present.
+     * @returns The validated actor context.
+     */
+    #validContext(source, context, nowMs, expiresAtMs) {
+        return ((this.#options.publicAccess === true || expiresAtMs !== undefined) &&
+            (expiresAtMs === undefined || expiresAtMs > nowMs) &&
+            SubscriptionGatewayValues.matches(source.requestedContext, context));
+    }
+    /**
+     * Reads the configured clock as finite epoch milliseconds.
+     *
+     * @returns Current epoch milliseconds, if valid.
+     */ #nowMs() {
         const now = this.#options.clock.now();
         return SubscriptionGatewayValues.timestampMs(now.seconds, now.nanos);
     }
-    async #perform(prepared, updates, signal) {
-        const { source, context, expiresAtMs, nowMs } = prepared;
+    /**
+     * Runs the prepared subscription operation after security checks.
+     *
+     * @param prepared Policy-admitted subscription operation.
+     * @param updates The admitted subscription update sink.
+     * @param signal The cancellation signal for this operation.
+     * @returns The admitted subscription outcome.
+     */ async #perform(prepared, updates, signal) {
+        const { source, context, reader, expiresAtMs, nowMs } = prepared;
         const rewritten = SubscriptionGatewayValues.rewrite(source, context);
+        if (signal.aborted)
+            return SubscriptionGatewayValues.rejected("denied");
         if (source.kind === "subscribe")
-            return this.#subscribe(rewritten, context, expiresAtMs);
+            return this.#subscribe(rewritten, context, reader, expiresAtMs, signal);
         const id = source.subscription.id?.value;
         if (id === undefined || id.length === 0)
             return SubscriptionGatewayValues.rejected("denied");
-        return source.kind === "activate"
-            ? this.#activate(id, context, nowMs, expiresAtMs, updates ?? SubscriptionGatewayValues.discardUpdate, signal)
-            : this.#cancel(id, context, nowMs);
+        if (source.kind === "cancel") {
+            const result = await this.#cancel(id, context, nowMs, reader);
+            // Binding cleanup can finish after this invocation is invalidated.
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            return signal.aborted ? SubscriptionGatewayValues.rejected("denied") : result;
+        }
+        return this.#activate(id, context, reader, nowMs, expiresAtMs, updates ?? SubscriptionGatewayValues.discardUpdate, signal);
     }
-    async #activate(id, context, nowMs, expiresAtMs, updates, signal) {
-        const activeController = new AbortController();
-        const active = activeController.signal;
-        const abort = () => {
-            activeController.abort();
-        };
+    /**
+     * Verifies membership and activates a retained subscription.
+     *
+     * @param id The stable identifier for this record.
+     * @param context The trusted context for this operation.
+     * @param reader The verified reader facts for this operation.
+     * @param nowMs The current time in milliseconds.
+     * @param expiresAtMs The session expiry in milliseconds, when present.
+     * @param updates The admitted subscription update sink.
+     * @param signal The cancellation signal for this operation.
+     * @returns The update stream after admission.
+     */ async #activate(id, context, reader, nowMs, expiresAtMs, updates, signal) {
         if (signal?.aborted)
             return SubscriptionGatewayValues.rejected("denied");
         if (this.#options.publicAccess === true)
             this.#clearPublicPending(id);
-        signal?.addEventListener("abort", abort, { once: true });
-        const expiry = expiresAtMs === undefined
-            ? undefined
-            : setTimeout(() => {
-                activeController.abort();
-            }, Math.max(0, expiresAtMs - nowMs));
         let activationFailure;
         let outcome = SubscriptionGatewayValues.rejected("denied");
         try {
-            const result = await this.#options.bindings.activate({
-                id,
-                context,
-                nowMs,
-                signal: active,
-                onDefinition: (definition, effectSignal) => this.#forwardActivate(definition, updates, effectSignal),
+            outcome = await this.#activationEffect(id, context, reader, nowMs, expiresAtMs, updates, signal);
+        }
+        catch (error) {
+            activationFailure = this.#activationError(error);
+        }
+        if (this.#options.publicAccess === true)
+            await this.#publicActivationCleanup(id, context, reader, nowMs, activationFailure);
+        if (activationFailure !== undefined)
+            throw activationFailure;
+        return outcome;
+    }
+    /**
+     * Preserves a non-Error activation failure as a throwable cause.
+     *
+     * @param error The failure being classified or propagated.
+     * @returns The structured activation error.
+     */
+    #activationError(error) {
+        return error instanceof Error
+            ? error
+            : new Error("Public subscription activation failed with a non-Error value.", {
+                cause: error,
             });
-            outcome =
-                result.kind === "activated"
-                    ? { kind: "activated" }
-                    : SubscriptionGatewayValues.rejected("denied");
+    }
+    /**
+     * Releases a public definition while retaining both activation and cleanup failures.
+     *
+     * @param id The stable identifier for this record.
+     * @param context The trusted context for this operation.
+     * @param reader The verified reader facts for this operation.
+     * @param nowMs The current time in milliseconds.
+     * @param activationFailure Failure raised while activating the subscription.
+     * @returns Completion after the operation settles.
+     */
+    async #publicActivationCleanup(id, context, reader, nowMs, activationFailure) {
+        try {
+            await this.#cancel(id, context, this.#nowMs() ?? nowMs, reader);
+        }
+        catch (error) {
+            const cleanupFailure = error instanceof Error
+                ? error
+                : new Error("Public subscription cleanup failed with a non-Error value.", {
+                    cause: error,
+                });
+            if (activationFailure !== undefined)
+                throw new AggregateError([activationFailure, cleanupFailure], "public subscription cleanup failed");
+            throw cleanupFailure;
+        }
+    }
+    /**
+     * Runs one reader-bound binding activation under cancellation and session expiry.
+     *
+     * @param id The stable identifier for this record.
+     * @param context The trusted context for this operation.
+     * @param reader The verified reader facts for this operation.
+     * @param nowMs The current time in milliseconds.
+     * @param expiresAtMs The session expiry in milliseconds, when present.
+     * @param updates The admitted subscription update sink.
+     * @param signal The cancellation signal for this operation.
+     * @returns The tracked activation effect.
+     */
+    async #activationEffect(id, context, reader, nowMs, expiresAtMs, updates, signal) {
+        const activeController = new AbortController();
+        const active = activeController.signal;
+        /**
+         * Cancels this activation when the caller aborts.
+         */
+        const abort = () => {
+            activeController.abort();
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+        const expiry = this.#activationExpiry(expiresAtMs, nowMs, activeController);
+        try {
+            const result = await this.#activateBinding(id, context, reader, nowMs, active, updates);
+            return result.kind === "activated"
+                ? { kind: "activated" }
+                : SubscriptionGatewayValues.rejected("denied");
         }
         catch (error) {
             if (error instanceof Error && error.message === "binding-busy")
-                outcome = SubscriptionGatewayValues.rejected("binding-busy");
-            else
-                activationFailure =
-                    error instanceof Error
-                        ? error
-                        : new Error("Public subscription activation failed with a non-Error value.", {
-                            cause: error,
-                        });
+                return SubscriptionGatewayValues.rejected("binding-busy");
+            throw error;
         }
         finally {
             if (expiry !== undefined)
                 clearTimeout(expiry);
             signal?.removeEventListener("abort", abort);
         }
-        let cleanupFailure;
-        if (this.#options.publicAccess === true)
-            try {
-                await this.#cancel(id, context, this.#nowMs() ?? nowMs);
-            }
-            catch (error) {
-                cleanupFailure =
-                    error instanceof Error
-                        ? error
-                        : new Error("Public subscription cleanup failed with a non-Error value.", {
-                            cause: error,
-                        });
-            }
-        if (activationFailure !== undefined) {
-            if (cleanupFailure !== undefined)
-                throw new AggregateError([activationFailure, cleanupFailure], "public subscription cleanup failed");
-            throw activationFailure;
-        }
-        if (cleanupFailure !== undefined)
-            throw cleanupFailure;
-        return outcome;
     }
-    #cancel(id, context, nowMs) {
+    /**
+     * Cancels activation when the admitted reader session reaches its expiry.
+     *
+     * @param expiresAtMs The session expiry in milliseconds, when present.
+     * @param nowMs The current time in milliseconds.
+     * @param controller Abort controller for the active operation.
+     * @returns The pending activation expiry.
+     */
+    #activationExpiry(expiresAtMs, nowMs, controller) {
+        return expiresAtMs === undefined
+            ? undefined
+            : setTimeout(() => {
+                controller.abort();
+            }, Math.max(0, expiresAtMs - nowMs));
+    }
+    /**
+     * Sends one reader-bound activation to the durable binding port.
+     *
+     * @param id The stable identifier for this record.
+     * @param context The trusted context for this operation.
+     * @param reader The verified reader facts for this operation.
+     * @param nowMs The current time in milliseconds.
+     * @param signal The cancellation signal for this operation.
+     * @param updates The admitted subscription update sink.
+     * @returns The activated reader-bound definition.
+     */
+    #activateBinding(id, context, reader, nowMs, signal, updates) {
+        return this.#options.bindings.activate({
+            id,
+            context,
+            reader: ReaderIdentities.from(reader),
+            nowMs,
+            signal,
+            onDefinition: (definition, effectSignal) => this.#forwardActivate({ ...definition, reader }, updates, effectSignal),
+        });
+    }
+    /**
+     * Verifies reader membership and removes a retained subscription.
+     *
+     * @param id The stable identifier for this record.
+     * @param context The trusted context for this operation.
+     * @param nowMs The current time in milliseconds.
+     * @param reader The verified reader facts for this operation.
+     * @returns The cancellation acknowledgment.
+     */ #cancel(id, context, nowMs, reader = {}) {
+        const identity = ReaderIdentities.from(reader);
         const active = this.#cancellations.get(id) ?? [];
-        const matching = active.find((entry) => SubscriptionGatewayValues.contextsEqual(entry.context, context));
+        const matching = active.find((entry) => SubscriptionGatewayValues.contextsEqual(entry.context, context) &&
+            ReaderIdentities.matches(entry.reader, identity));
         if (matching !== undefined)
             return matching.promise;
-        const promise = this.#cancelOnce(id, context, nowMs);
-        const entry = { context: clone(ActorContextSchema, context), promise };
+        const promise = this.#cancelOnce(id, context, nowMs, reader);
+        const entry = { context: clone(ActorContextSchema, context), reader: identity, promise };
         active.push(entry);
         this.#cancellations.set(id, active);
         // spine-log-boundary: auth.subscription_cancel_finally_observer
@@ -561,13 +954,22 @@ export class SubscriptionGateway {
             .catch(() => undefined);
         return promise;
     }
-    async #cancelOnce(id, context, nowMs) {
+    /**
+     * Serializes one cancellation against concurrent work for its ID.
+     *
+     * @param id The stable identifier for this record.
+     * @param context The trusted context for this operation.
+     * @param nowMs The current time in milliseconds.
+     * @param reader The verified reader facts for this operation.
+     * @returns The cancellation outcome.
+     */ async #cancelOnce(id, context, nowMs, reader) {
         try {
             const result = await this.#options.bindings.cancel({
                 id,
                 context,
+                reader: ReaderIdentities.from(reader),
                 nowMs,
-                onDefinition: (definition, effectSignal) => this.#forwardCancel(definition, effectSignal),
+                onDefinition: (definition, effectSignal) => this.#forwardCancel({ ...definition, reader }, effectSignal),
             });
             if (result.kind === "denied")
                 return SubscriptionGatewayValues.rejected("denied");
@@ -580,52 +982,156 @@ export class SubscriptionGateway {
             throw error;
         }
     }
-    async #subscribe(bytes, context, expiresAtMs) {
+    /**
+     * Validates and retains a reader-bound subscription definition.
+     *
+     * @param bytes The serialized message bytes.
+     * @param context The trusted context for this operation.
+     * @param reader The verified reader facts for this operation.
+     * @param expiresAtMs The session expiry in milliseconds, when present.
+     * @param signal The admitted operation lifetime.
+     * @returns The new subscription definition.
+     */ async #subscribe(bytes, context, reader, expiresAtMs, signal) {
         const wire = await this.#options.bindings.create({
             topic: { kind: "subscription-topic", bytes: bytes.slice() },
+            reader: ReaderIdentities.from(reader),
             ...(expiresAtMs === undefined ? {} : { whenExpires: expiresAtMs }),
         });
+        const admittedWire = { ...wire, reader };
         const id = fromBinary(SubscriptionSchema, wire.bytes).id?.value;
         if (id === undefined || id.length === 0)
             throw new Error("retained subscription has no ID");
         const controller = new AbortController();
+        if (signal.aborted) {
+            await this.#discardBinding(id, context, reader, this.#nowMs() ?? 0);
+            return SubscriptionGatewayValues.rejected("denied");
+        }
+        return this.#deliverCreated(id, context, reader, expiresAtMs, admittedWire, controller, signal);
+    }
+    /**
+     * Completes backend Subscribe and checks the same operation after each await.
+     *
+     * @param id Stable created definition ID.
+     * @param context Trusted actor context.
+     * @param reader Verified reader facts.
+     * @param expiresAtMs Session expiry, when present.
+     * @param wire Created definition bytes.
+     * @param controller Backend operation controller.
+     * @param signal Admitted operation lifetime.
+     * @returns Definition only while its reader remains admitted.
+     */
+    async #deliverCreated(id, context, reader, expiresAtMs, wire, controller, signal) {
         try {
             await this.#receiveBackend(wire, controller);
-            const nowMs = this.#nowMs();
-            if (nowMs === undefined || (expiresAtMs !== undefined && expiresAtMs <= nowMs)) {
-                await this.#compensateDefinition(wire, controller);
-                await this.#options.bindings.cancel({
-                    id,
-                    context,
-                    nowMs: nowMs ?? expiresAtMs ?? 0,
-                    onDefinition: () => Promise.resolve(),
-                });
-                return SubscriptionGatewayValues.rejected("denied");
-            }
-            if (expiresAtMs !== undefined)
-                this.scheduleExpiry(expiresAtMs);
-            if (this.#options.publicAccess === true)
-                this.#schedulePublicPending(id, context);
-            return { kind: "subscribed", wire: SubscriptionGatewayValues.copyPublic(wire) };
         }
         catch (error) {
-            try {
-                await this.#compensateDefinition(wire, controller);
-                await this.#options.bindings.cancel({
-                    id,
-                    context,
-                    nowMs: this.#nowMs() ?? expiresAtMs ?? 0,
-                    onDefinition: () => Promise.resolve(),
-                });
-                // spine-log-boundary: auth.subscription_recovered_cleanup
-            }
-            catch {
-                // Retain the row: a later request can retry backend cleanup.
-            }
+            await this.#discardFailed(id, context, reader, expiresAtMs, wire, controller);
             throw error;
         }
+        if (signal.aborted)
+            return this.#rejectCreated(id, context, reader, wire, controller);
+        const result = await this.#confirmCreated(id, context, reader, expiresAtMs, wire, controller);
+        // Confirmation can suspend in expiry cleanup while admission ends.
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (!signal.aborted || result.kind !== "subscribed")
+            return result;
+        return this.#rejectCreated(id, context, reader, wire, controller);
     }
-    #schedulePublicPending(id, context) {
+    /**
+     * Clears a created definition after admission ends without returning a credential.
+     *
+     * @param id Created definition ID.
+     * @param context Trusted actor context.
+     * @param reader Verified reader facts.
+     * @param wire Created definition bytes.
+     * @param controller Backend operation controller.
+     * @returns Rejection after required cleanup completes.
+     */
+    async #rejectCreated(id, context, reader, wire, controller) {
+        await this.#discardCreated(id, context, reader, this.#nowMs() ?? 0, wire, controller);
+        return SubscriptionGatewayValues.rejected("denied");
+    }
+    /**
+     * Retains the original backend failure while attempting conditional cleanup.
+     *
+     * @param id Created definition ID.
+     * @param context Trusted actor context.
+     * @param reader Verified reader facts.
+     * @param expiresAtMs Session expiry, when present.
+     * @param wire Created definition bytes.
+     * @param controller Backend operation controller.
+     * @returns Completion after cleanup is attempted.
+     */
+    async #discardFailed(id, context, reader, expiresAtMs, wire, controller) {
+        try {
+            await this.#discardCreated(id, context, reader, this.#nowMs() ?? expiresAtMs ?? 0, wire, controller);
+            // spine-log-boundary: auth.subscription_recovered_cleanup
+        }
+        catch {
+            // Retain the row: a later request can retry backend cleanup.
+        }
+    }
+    /**
+     * Returns an admitted public definition only while its reader session remains valid.
+     *
+     * @param id The stable identifier for this record.
+     * @param context The trusted context for this operation.
+     * @param reader The verified reader facts for this operation.
+     * @param expiresAtMs The session expiry in milliseconds, when present.
+     * @param wire Canonical serialized subscription bytes.
+     * @param controller Abort controller for the active operation.
+     * @returns The confirmed retained definition.
+     */
+    async #confirmCreated(id, context, reader, expiresAtMs, wire, controller) {
+        const nowMs = this.#nowMs();
+        if (nowMs === undefined || (expiresAtMs !== undefined && expiresAtMs <= nowMs)) {
+            await this.#discardCreated(id, context, reader, nowMs ?? expiresAtMs ?? 0, wire, controller);
+            return SubscriptionGatewayValues.rejected("denied");
+        }
+        return {
+            kind: "subscribed",
+            wire: { kind: "public-subscription", bytes: wire.bytes.slice() },
+        };
+    }
+    /**
+     * Compensates a created definition before it can escape admission.
+     *
+     * @param id The stable identifier for this record.
+     * @param context The trusted context for this operation.
+     * @param reader The verified reader facts for this operation.
+     * @param nowMs The current time in milliseconds.
+     * @param wire Canonical serialized subscription bytes.
+     * @param controller Abort controller for the active operation.
+     * @returns Completion after the operation settles.
+     */
+    async #discardCreated(id, context, reader, nowMs, wire, controller) {
+        await this.#compensateDefinition(wire, controller);
+        await this.#discardBinding(id, context, reader, nowMs);
+    }
+    /**
+     * Clears a created local binding without assuming backend Subscribe began.
+     *
+     * @param id Created definition ID.
+     * @param context Trusted actor context.
+     * @param reader Verified reader facts.
+     * @param nowMs Trusted cleanup time.
+     * @returns Completion after local removal.
+     */
+    async #discardBinding(id, context, reader, nowMs) {
+        await this.#options.bindings.cancel({
+            id,
+            context,
+            reader: ReaderIdentities.from(reader),
+            nowMs,
+            onDefinition: () => Promise.resolve(),
+        });
+    }
+    /**
+     * Schedules activation retry for a public subscription.
+     *
+     * @param id The stable identifier for this record.
+     * @param context The trusted context for this operation.
+     */ #schedulePublicPending(id, context) {
         this.#clearPublicPending(id);
         const timer = setTimeout(() => {
             if (this.#publicPendingTimers.get(id) !== timer)
@@ -641,24 +1147,52 @@ export class SubscriptionGateway {
         }, SUBSCRIPTION_ACTIVATION_HANDSHAKE_MS);
         this.#publicPendingTimers.set(id, timer);
     }
-    #retryPublicPending(id, context) {
+    /**
+     * Retries pending public activation after backend availability changes.
+     *
+     * @param id The stable identifier for this record.
+     * @param context The trusted context for this operation.
+     */ #retryPublicPending(id, context) {
         if (!this.#closed && !this.#publicPendingTimers.has(id))
             this.#schedulePublicPending(id, context);
     }
-    #clearPublicPending(id) {
+    /**
+     * Clears the pending public activation timer for an ID.
+     *
+     * @param id The stable identifier for this record.
+     */ #clearPublicPending(id) {
         const timer = this.#publicPendingTimers.get(id);
         if (timer !== undefined)
             clearTimeout(timer);
         this.#publicPendingTimers.delete(id);
     }
-    async #receiveBackend(wire, controller) {
+    /**
+     * Attaches the native backend subscription after admission.
+     *
+     * @param wire Canonical serialized subscription bytes.
+     * @param controller Abort controller for the active operation.
+     * @returns Completion after the operation settles.
+     */ async #receiveBackend(wire, controller) {
         return SubscriptionGatewayValues.withTimeout(this.#options.creator.subscribe(SubscriptionGatewayValues.copyPublic(wire), controller.signal, this.#limits.maxBackendEnvelopeBytes), this.#limits.operationTimeoutMs, controller);
     }
-    async #compensateDefinition(wire, controller) {
+    /**
+     * Removes a definition after a failed backend subscription step.
+     *
+     * @param wire Canonical serialized subscription bytes.
+     * @param controller Abort controller for the active operation.
+     * @returns Completion after the operation settles.
+     */ async #compensateDefinition(wire, controller) {
         const signal = controller.signal.aborted ? new AbortController().signal : controller.signal;
         await this.#options.creator.cancel({ wire: SubscriptionGatewayValues.copyPublic(wire) }, signal);
     }
-    async #forwardActivate(definition, updates, signal) {
+    /**
+     * Forwards activation with the verified reader assertion.
+     *
+     * @param definition The serialized subscription definition.
+     * @param updates The admitted subscription update sink.
+     * @param signal The cancellation signal for this operation.
+     * @returns Completion after the operation settles.
+     */ async #forwardActivate(definition, updates, signal) {
         const privateWire = SubscriptionGatewayValues.copyPublic(definition);
         try {
             const publicSubscription = fromBinary(SubscriptionSchema, definition.bytes);
@@ -666,6 +1200,8 @@ export class SubscriptionGateway {
                 wire: privateWire,
                 updates: async (update) => {
                     try {
+                        if (signal.aborted)
+                            return;
                         const decoded = fromBinary(SubscriptionUpdateSchema, update.bytes);
                         decoded.subscription = clone(SubscriptionSchema, publicSubscription);
                         await updates({
@@ -683,7 +1219,13 @@ export class SubscriptionGateway {
             privateWire.bytes.fill(0);
         }
     }
-    async #forwardCancel(definition, signal) {
+    /**
+     * Forwards cancellation with the verified reader assertion.
+     *
+     * @param definition The serialized subscription definition.
+     * @param signal The cancellation signal for this operation.
+     * @returns Completion after the operation settles.
+     */ async #forwardCancel(definition, signal) {
         const privateWire = SubscriptionGatewayValues.copyPublic(definition);
         try {
             await this.#options.creator.cancel({ wire: privateWire }, signal);
@@ -715,7 +1257,11 @@ const SubscriptionGatewayValues = Object.freeze({
      * @returns Copied public subscription bytes.
      */
     copyPublic(wire) {
-        return { kind: wire.kind, bytes: wire.bytes.slice() };
+        return {
+            kind: wire.kind,
+            bytes: wire.bytes.slice(),
+            ...(wire.reader === undefined ? {} : { reader: snapshotTrustedReader(wire.reader) }),
+        };
     },
     /**
      * Builds a successful subscription response.