@indigoai-us/hq-cloud 6.14.49 → 6.15.0

package/src/sync/feature-flags.ts

@@ -1,229 +1,62 @@
 /**
- * Per-tenant feature-flag module for the event-driven push pipeline.
+ * Local control for the dormant event-sync wiring.
  *
- * Ported from indigoai-us/hq-pro PR #112 (src/sync/feature-flags.ts) into
- * @indigoai-us/hq-cloud (Path B) per project event-driven-sync-menubar US-008.
- *
- * Why this exists
- * ───────────────
- * The event-driven push pipeline must default OFF for all tenants and be
- * enabled per-tenant ("OFF for all tenants by default, ON for Indigo only").
- * This module provides the read-only seam the watcher (and a later receiver)
- * consult at start time to decide whether to emit/ship PushEvents at all:
- *  - {@link EventDrivenPushFlagProvider} — the small read-only seam every
- *    caller consults. Returns a boolean for a given tenantId.
- *  - {@link EnvTenantListFlagProvider} — production implementation. Reads
- *    a comma-separated allow-list from {@link FEATURE_FLAG_TENANTS_ENV_VAR}
- *    AND honors the legacy global `HQ_SYNC_EVENT_DRIVEN_PUSH_ENABLED=true`
- *    as a backwards-compat global override. The legacy global wins when set
- *    — it enables all tenants.
- *  - {@link StaticFlagProvider} — small test helper. Constructor takes an
- *    iterable of enabled tenant IDs. Used by watcher + feature-flag tests.
- *  - {@link defaultFlagProvider} — factory callers default to when no
- *    provider is explicitly supplied.
- *
- * Validation posture
- * ──────────────────
- * Tenant IDs from the env are trimmed, empty entries are dropped, and
- * entries containing internal whitespace are warn-and-skipped (NOT thrown).
- * The watcher runs inside a long-lived daemon — a malformed env var must
- * not crash daemon startup; it must surface in logs and fall through to the
- * default-OFF behavior for the misconfigured entry.
- *
- * @see src/watcher.ts — the TreeWatcher consults this seam at start time to
- *   decide whether to emit + ship PushEvents (dormant when OFF).
+ * U15 removes client-side positive selectors. Environment values, tenant IDs,
+ * and cached identity cannot grant authority; the authenticated server
+ * inventory is the sole positive authority. This module preserves only the
+ * operator's local off-switch.
  */
 
-// ─── Constants ─────────────────────────────────────────────────────────────
-
-/**
- * Env var holding a comma-separated allow-list of tenant IDs for which the
- * event-driven push pipeline is enabled. Empty/unset means no tenants are
- * enabled (default OFF for all). Example: `indigo,acme`.
- *
- * Tenant matching is exact and case-sensitive after trimming. Whitespace
- * around commas is tolerated; internal whitespace within a tenant ID is
- * not (warned + skipped — see `parseTenantList` below).
- */
-export const FEATURE_FLAG_TENANTS_ENV_VAR =
-  "HQ_SYNC_EVENT_DRIVEN_PUSH_ENABLED_TENANTS";
+/** A local-only kill switch. Any other value is deliberately non-authorizing. */
+export const EVENT_SYNC_LOCAL_DISABLE_ENV_VAR = "HQ_SYNC_EVENT_SYNC";
 
 /**
- * Legacy process-wide env var. When set to the literal string `"true"`, the
- * pipeline is unconditionally enabled. Preserved as a "global override that
- * enables ALL tenants" so a single-flag rollout (or local dev) keeps working.
- *
- * Operators flipping rollout via deploy-time config should prefer the
- * per-tenant {@link FEATURE_FLAG_TENANTS_ENV_VAR} instead.
- */
-export const FEATURE_FLAG_LEGACY_GLOBAL_ENV_VAR =
-  "HQ_SYNC_EVENT_DRIVEN_PUSH_ENABLED";
-
-// ─── Public types ──────────────────────────────────────────────────────────
-
-/**
- * Read-only seam for the per-tenant event-driven push feature flag.
- *
- * Implementations are pure / synchronous. Callers MUST treat the result as
- * the truth at the moment of the call — a deploy-time env-var change does
- * NOT propagate to running daemons until they restart.
+ * Compatibility seam consumed by the existing emitter. Production event-sync
+ * supplies it only after authenticated server inventory has granted access.
  */
 export interface EventDrivenPushFlagProvider {
-  /**
-   * Returns true iff the event-driven push pipeline is enabled for
-   * `tenantId`. Defaults to false. Case-sensitive exact match against the
-   * configured allow-list (or the legacy global override).
-   */
-  isEnabled(tenantId: string): boolean;
+  isEnabled(scopeId: string): boolean;
 }
 
-/**
- * Optional injection seam for warnings emitted while parsing the env var
- * (invalid entries). Defaults to `console.warn`.
- */
+/** Deprecated inert compatibility shape; no environment is ever read. */
 export type FlagProviderWarnFn = (
   message: string,
   context: Record<string, unknown>,
 ) => void;
 
-// ─── Env-driven provider ───────────────────────────────────────────────────
-
-/**
- * Options for {@link EnvTenantListFlagProvider}.
- */
+/** Deprecated inert compatibility shape; no environment is ever read. */
 export interface EnvTenantListFlagProviderOptions {
-  /**
-   * Env snapshot. Defaults to `process.env`. Tests inject `{}` or a
-   * synthetic object so they don't mutate real env state.
-   */
   env?: Record<string, string | undefined>;
-  /**
-   * Where to send "invalid entry, skipping" warnings. Defaults to
-   * `console.warn`.
-   */
   warn?: FlagProviderWarnFn;
 }
 
 /**
- * Production flag provider. Reads {@link FEATURE_FLAG_TENANTS_ENV_VAR} at
- * construction time and caches the parsed set — `isEnabled()` is O(1).
- *
- * The legacy {@link FEATURE_FLAG_LEGACY_GLOBAL_ENV_VAR} (set to literal
- * `"true"`) acts as a global override: when set, `isEnabled()` returns
- * true for every tenant.
- *
- * Parse rules:
- *  - Empty / unset {@link FEATURE_FLAG_TENANTS_ENV_VAR} → no tenants enabled.
- *  - Whitespace around commas is tolerated and trimmed.
- *  - Empty entries (`",,foo,"`) are silently dropped.
- *  - Entries with INTERNAL whitespace (`"indigo team"`) are warn-and-skipped.
- *  - Matching is exact + case-sensitive.
- */
-export class EnvTenantListFlagProvider implements EventDrivenPushFlagProvider {
-  private readonly tenants: ReadonlySet<string>;
-  private readonly legacyGlobal: boolean;
-
-  constructor(opts: EnvTenantListFlagProviderOptions = {}) {
-    const env = opts.env ?? process.env;
-    const warn = opts.warn ?? defaultWarn;
-    this.tenants = parseTenantList(env[FEATURE_FLAG_TENANTS_ENV_VAR], warn);
-    this.legacyGlobal = env[FEATURE_FLAG_LEGACY_GLOBAL_ENV_VAR] === "true";
-  }
-
-  isEnabled(tenantId: string): boolean {
-    if (this.legacyGlobal) return true;
-    return this.tenants.has(tenantId);
-  }
-
-  /**
-   * Debug-only accessor — returns a defensive copy of the cached allow-list.
-   * Used by tests and the daemon's startup log line.
-   */
-  get enabledTenants(): ReadonlySet<string> {
-    return new Set(this.tenants);
-  }
-
-  /** Debug-only accessor — true iff the legacy global override is in effect. */
-  get globalOverride(): boolean {
-    return this.legacyGlobal;
-  }
-}
-
-// ─── Static provider (tests) ───────────────────────────────────────────────
-
-/**
- * In-memory provider for unit tests. The constructor takes the set of
- * enabled tenant IDs; `isEnabled()` is a plain `Set.has` check.
- *
- * Production callers should NEVER construct this — use
- * {@link EnvTenantListFlagProvider} via {@link defaultFlagProvider}.
+ * Compatibility fixture for older direct emitter tests. It represents a
+ * previously authenticated server inventory result; the supplied legacy value
+ * is deliberately ignored, so it cannot select a tenant or grant by email.
  */
 export class StaticFlagProvider implements EventDrivenPushFlagProvider {
-  private readonly tenants: ReadonlySet<string>;
-
-  constructor(enabledTenants: Iterable<string>) {
-    this.tenants = new Set(enabledTenants);
-  }
+  constructor(_authenticatedLegacyInventory: unknown) {}
 
-  isEnabled(tenantId: string): boolean {
-    return this.tenants.has(tenantId);
+  isEnabled(_scopeId: string): boolean {
+    return true;
   }
 }
 
-// ─── Factory ───────────────────────────────────────────────────────────────
-
 /**
- * Build the default {@link EventDrivenPushFlagProvider} from an env
- * snapshot. Production callers use this with no args — `process.env` is
- * the implicit input.
- */
-export function defaultFlagProvider(
-  env: Record<string, string | undefined> = process.env,
-): EventDrivenPushFlagProvider {
-  return new EnvTenantListFlagProvider({ env });
-}
-
-// ─── Internals ─────────────────────────────────────────────────────────────
-
-/**
- * Parse a raw env value into a Set of valid tenant IDs.
- *
- * Kept as a free function so unit tests can call it via the class accessor
- * with a synthetic warn spy without exporting an internal symbol.
- */
-function parseTenantList(
-  raw: string | undefined,
-  warn: FlagProviderWarnFn,
-): ReadonlySet<string> {
-  if (raw === undefined || raw === "") return new Set<string>();
-  const out = new Set<string>();
-  for (const piece of raw.split(",")) {
-    const trimmed = piece.trim();
-    if (trimmed === "") {
-      // Empty slot (`",,foo,"` or trailing commas) — silently skipped.
-      continue;
-    }
-    if (/\s/.test(trimmed)) {
-      // Internal whitespace — operator misconfiguration. Warn but don't
-      // throw: the daemon must keep starting, the misconfigured tenant
-      // just stays OFF.
-      warn("feature-flag: skipping tenant entry with internal whitespace", {
-        envVar: FEATURE_FLAG_TENANTS_ENV_VAR,
-        rawEntry: trimmed,
-      });
-      continue;
-    }
-    out.add(trimmed);
+ * Returns true only for an explicit local disable value. Values such as
+ * `true`, `1`, a tenant list, or an unrecognized string never enable sync.
+ */
+export function isEventSyncLocallyDisabled(
+  value: string | undefined,
+): boolean {
+  switch ((value ?? "").trim().toLowerCase()) {
+    case "0":
+    case "false":
+    case "no":
+    case "off":
+      return true;
+    default:
+      return false;
   }
-  return out;
-}
-
-/**
- * Default warn destination — plain `console.warn`.
- */
-function defaultWarn(
-  message: string,
-  context: Record<string, unknown>,
-): void {
-  console.warn(message, context);
 }

package/src/sync/index.ts

@@ -28,11 +28,9 @@ export type {
 } from "./push-transport.js";
 
 export {
-  FEATURE_FLAG_TENANTS_ENV_VAR,
-  FEATURE_FLAG_LEGACY_GLOBAL_ENV_VAR,
-  EnvTenantListFlagProvider,
+  EVENT_SYNC_LOCAL_DISABLE_ENV_VAR,
+  isEventSyncLocallyDisabled,
   StaticFlagProvider,
-  defaultFlagProvider,
 } from "./feature-flags.js";
 export type {
   EventDrivenPushFlagProvider,

package/src/sync/lease-client.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { RealtimeLeaseClient, RealtimePassAuthorizer } from "./lease-client.js";
+import { RealtimeRolloutClient, type RealtimeCapabilityVector } from "./realtime-rollout.js";
+
+const capability: RealtimeCapabilityVector = {
+  hqCloud: "6.14.49",
+  hqDesktop: "none",
+  protocol: 2,
+  journal: 3,
+  durableApply: 1,
+};
+
+function jsonResponse(body: unknown, status = 200) {
+  return { ok: status >= 200 && status < 300, status, text: async () => JSON.stringify(body) };
+}
+
+describe("RealtimeLeaseClient", () => {
+  it("uses the pass bearer and rejects a lease longer than sixty seconds", async () => {
+    let received: { method?: string; headers?: Record<string, string> } | undefined;
+    const fetchImpl = async (_url: string, init?: { method?: string; headers?: Record<string, string> }) => {
+      received = init;
+      return jsonResponse({
+        lease: "lease_1",
+        issuedAt: "2026-08-12T00:00:00.000Z",
+        expiresAt: "2026-08-12T00:01:01.000Z",
+        authorizationEpoch: "epoch_1",
+      });
+    };
+    const client = new RealtimeLeaseClient({ apiUrl: "https://api.example", fetchImpl, now: () => Date.parse("2026-08-12T00:00:00.000Z") });
+
+    await expect(client.issue({ bearer: "token-a", deviceId: "machine_a", capabilityVector: capability, scopeHandle: "handle_1", scopeRevision: "rev_1" })).rejects.toThrow("invalid lease lifetime");
+    expect(received).toMatchObject({
+      method: "POST",
+      headers: expect.objectContaining({ Authorization: "Bearer token-a", "X-HQ-Sync-Contract": "2" }),
+    });
+  });
+
+  it("rejects a lease issued too far into the future", async () => {
+    const fetchImpl = async () => jsonResponse({
+      lease: "lease_1",
+      issuedAt: "2026-08-12T00:00:06.000Z",
+      expiresAt: "2026-08-12T00:01:00.000Z",
+      authorizationEpoch: "epoch_1",
+    });
+    const client = new RealtimeLeaseClient({ apiUrl: "https://api.example", fetchImpl, now: () => Date.parse("2026-08-12T00:00:00.000Z") });
+    await expect(client.issue({ bearer: "token-a", deviceId: "machine_a", capabilityVector: capability, scopeHandle: "handle_1", scopeRevision: "rev_1" })).rejects.toThrow("invalid lease lifetime");
+  });
+
+  it("resolves one bearer and freshly leases every selected scope before I/O", async () => {
+    const now = Date.parse("2026-08-12T00:00:00.000Z");
+    const requests: Array<{ headers?: Record<string, string> }> = [];
+    const fetchImpl = async (url: string, init?: { headers?: Record<string, string> }) => {
+      requests.push({ headers: init?.headers });
+      if (url.endsWith("/scopes")) {
+        return jsonResponse({ scopes: [
+          { scopeUid: "prs_1", scopeHandle: "handle_1", scopeRevision: "rev_1", state: "v2-ready", cursor: "cursor_1" },
+          { scopeUid: "cmp_1", scopeHandle: "handle_2", scopeRevision: "rev_2", state: "v2-ready", cursor: "cursor_2" },
+        ] });
+      }
+      return jsonResponse({
+        lease: "lease_issued",
+        issuedAt: "2026-08-12T00:00:00.000Z",
+        expiresAt: "2026-08-12T00:01:00.000Z",
+        authorizationEpoch: "epoch_1",
+      }, 201);
+    };
+    const token = vi.fn(async () => "token-a");
+    const inventory = new RealtimeRolloutClient({ apiUrl: "https://api.example", fetchImpl, now: () => now });
+    const leases = new RealtimeLeaseClient({ apiUrl: "https://api.example", fetchImpl, now: () => now });
+    const authorizer = new RealtimePassAuthorizer(token, inventory, leases);
+    const operation = vi.fn(async () => "done");
+
+    await expect(authorizer.runBeforeIo({
+      deviceId: "machine_a",
+      capabilityVector: capability,
+      configurationFingerprint: "config-a",
+      scopeFingerprint: "prs_1,cmp_1",
+      scopeUids: ["prs_1", "cmp_1"],
+    }, operation)).resolves.toBe("done");
+
+    expect(token).toHaveBeenCalledTimes(1);
+    expect(requests).toHaveLength(3);
+    for (const call of requests) expect(call.headers?.Authorization).toBe("Bearer token-a");
+    expect(operation).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not invoke I/O when inventory loses a requested scope", async () => {
+    const fetchImpl = vi.fn(async () => jsonResponse({ scopes: [
+      { scopeUid: "prs_1", scopeHandle: "handle_1", scopeRevision: "rev_1", state: "paused", reasonCode: "maintenance" },
+    ] }));
+    const inventory = new RealtimeRolloutClient({ apiUrl: "https://api.example", fetchImpl });
+    const leases = new RealtimeLeaseClient({ apiUrl: "https://api.example", fetchImpl });
+    const authorizer = new RealtimePassAuthorizer("token-a", inventory, leases);
+    const operation = vi.fn(async () => undefined);
+
+    await expect(authorizer.runBeforeIo({
+      deviceId: "machine_a", capabilityVector: capability, configurationFingerprint: "config-a", scopeFingerprint: "prs_1", scopeUids: ["prs_1"],
+    }, operation)).rejects.toThrow("does not authorize every requested scope");
+    expect(operation).not.toHaveBeenCalled();
+  });
+
+  it("does not invoke I/O when parallel lease issues disagree on epoch", async () => {
+    let leaseCalls = 0;
+    const fetchImpl = async (url: string) => {
+      if (url.endsWith("/scopes")) return jsonResponse({ scopes: [
+        { scopeUid: "prs_1", scopeHandle: "handle_1", scopeRevision: "rev_1", state: "v2-ready", cursor: "cursor_1" },
+        { scopeUid: "cmp_1", scopeHandle: "handle_2", scopeRevision: "rev_2", state: "v2-ready", cursor: "cursor_2" },
+      ] });
+      leaseCalls += 1;
+      return jsonResponse({
+        lease: `lease_${leaseCalls}`,
+        issuedAt: "2026-08-12T00:00:00.000Z",
+        expiresAt: "2026-08-12T00:00:30.000Z",
+        authorizationEpoch: `epoch_${leaseCalls}`,
+      }, 201);
+    };
+    const now = () => Date.parse("2026-08-12T00:00:00.000Z");
+    const inventory = new RealtimeRolloutClient({ apiUrl: "https://api.example", fetchImpl, now });
+    const leases = new RealtimeLeaseClient({ apiUrl: "https://api.example", fetchImpl, now });
+    const authorizer = new RealtimePassAuthorizer("token-a", inventory, leases);
+    const operation = vi.fn(async () => undefined);
+    await expect(authorizer.runBeforeIo({
+      deviceId: "machine_a", capabilityVector: capability, configurationFingerprint: "config-a", scopeFingerprint: "all", scopeUids: ["prs_1", "cmp_1"],
+    }, operation)).rejects.toThrow("leases disagree on authorization epoch");
+    expect(operation).not.toHaveBeenCalled();
+  });
+});

package/src/sync/lease-client.ts

@@ -0,0 +1,207 @@
+import type { AuthTokenSource, FetchLike } from "./push-transport.js";
+import {
+  DEFAULT_REALTIME_AUTHORIZATION_TIMEOUT_MS,
+  REALTIME_SYNC_CONTRACT_VERSION,
+  type RealtimeCapabilityVector,
+  type RealtimeInventoryGrant,
+  type RealtimeInventoryRequest,
+  type RealtimeRolloutClient,
+  resolveRealtimeBearer,
+} from "./realtime-rollout.js";
+
+export const MAX_REALTIME_LEASE_MS = 60_000;
+export const MAX_REALTIME_LEASE_CLOCK_SKEW_MS = 5_000;
+
+export interface RealtimeLease {
+  lease: string;
+  issuedAt: string;
+  expiresAt: string;
+  authorizationEpoch: string;
+}
+
+export interface RealtimeLeaseRequest {
+  bearer: string;
+  deviceId: string;
+  capabilityVector: RealtimeCapabilityVector;
+  scopeHandle: string;
+  scopeRevision: string;
+}
+
+export interface RealtimeLeaseClientOptions {
+  apiUrl: string;
+  fetchImpl?: FetchLike;
+  now?: () => number;
+  authorizationTimeoutMs?: number;
+}
+
+function asNonEmptyString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim() === "") throw new Error(`realtime lease: ${field} must be a non-empty string`);
+  return value;
+}
+
+function parseLease(value: unknown, now: number): RealtimeLease {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("realtime lease: response is not an object");
+  const record = value as Record<string, unknown>;
+  if (Object.keys(record).some((key) => !["lease", "issuedAt", "expiresAt", "authorizationEpoch"].includes(key))) {
+    throw new Error("realtime lease: response contains an unknown field");
+  }
+  const lease: RealtimeLease = {
+    lease: asNonEmptyString(record.lease, "lease"),
+    issuedAt: asNonEmptyString(record.issuedAt, "issuedAt"),
+    expiresAt: asNonEmptyString(record.expiresAt, "expiresAt"),
+    authorizationEpoch: asNonEmptyString(record.authorizationEpoch, "authorizationEpoch"),
+  };
+  const issuedAtMs = Date.parse(lease.issuedAt);
+  const expiresAtMs = Date.parse(lease.expiresAt);
+  if (
+    !Number.isFinite(issuedAtMs) ||
+    !Number.isFinite(expiresAtMs) ||
+    issuedAtMs > now + MAX_REALTIME_LEASE_CLOCK_SKEW_MS ||
+    expiresAtMs <= now ||
+    expiresAtMs <= issuedAtMs ||
+    expiresAtMs - issuedAtMs > MAX_REALTIME_LEASE_MS ||
+    expiresAtMs > now + MAX_REALTIME_LEASE_MS
+  ) {
+    throw new Error("realtime lease: invalid lease lifetime");
+  }
+  return lease;
+}
+
+/** Issues a non-cacheable, <=60 second lease for one exact inventory grant. */
+export class RealtimeLeaseClient {
+  private readonly apiUrl: string;
+  private readonly fetchImpl: FetchLike;
+  private readonly now: () => number;
+  private readonly authorizationTimeoutMs: number;
+
+  constructor(options: RealtimeLeaseClientOptions) {
+    if (!options.apiUrl.trim()) throw new Error("realtime lease: apiUrl is required");
+    this.apiUrl = options.apiUrl.replace(/\/+$/, "");
+    this.fetchImpl = options.fetchImpl ?? ((input, init) => (globalThis.fetch as unknown as FetchLike)(input, init));
+    this.now = options.now ?? Date.now;
+    this.authorizationTimeoutMs = options.authorizationTimeoutMs ?? DEFAULT_REALTIME_AUTHORIZATION_TIMEOUT_MS;
+    if (!Number.isSafeInteger(this.authorizationTimeoutMs) || this.authorizationTimeoutMs <= 0) {
+      throw new Error("realtime lease: authorizationTimeoutMs must be a positive integer");
+    }
+  }
+
+  assertUsable(lease: RealtimeLease): void {
+    const expiresAtMs = Date.parse(lease.expiresAt);
+    if (!Number.isFinite(expiresAtMs) || expiresAtMs <= this.now()) {
+      throw new Error("realtime lease: expired before guarded I/O");
+    }
+  }
+
+  async issue(request: RealtimeLeaseRequest): Promise<RealtimeLease> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.authorizationTimeoutMs);
+    let response: Awaited<ReturnType<FetchLike>>;
+    try {
+      response = await this.fetchImpl(`${this.apiUrl}/v2/sync/leases`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${request.bearer}`,
+          Accept: "application/json",
+          "Content-Type": "application/json",
+          "X-HQ-Sync-Contract": String(REALTIME_SYNC_CONTRACT_VERSION),
+          "X-HQ-Device-ID": request.deviceId,
+          "X-HQ-Cloud-Version": request.capabilityVector.hqCloud,
+          "X-HQ-Desktop-Version": request.capabilityVector.hqDesktop,
+        },
+        body: JSON.stringify({
+          scopeHandle: request.scopeHandle,
+          scopeRevision: request.scopeRevision,
+          capabilityVector: request.capabilityVector,
+        }),
+        signal: controller.signal,
+      });
+    } catch (error) {
+      throw new Error(`realtime lease: POST /v2/sync/leases failed: ${error instanceof Error ? error.message : String(error)}`);
+    } finally {
+      clearTimeout(timeout);
+    }
+    const text = await response.text().catch((error: unknown) => {
+      throw new Error(`realtime lease: unable to read response: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    if (!response.ok) throw new Error(`realtime lease: POST /v2/sync/leases failed (${response.status}): ${text.slice(0, 300)}`);
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text);
+    } catch (error) {
+      throw new Error(`realtime lease: response is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return parseLease(parsed, this.now());
+  }
+}
+
+export interface RealtimeScopeAuthorization {
+  grant: RealtimeInventoryGrant & { state: "v2-ready" };
+  lease: RealtimeLease;
+}
+
+export interface RealtimePassAuthorization {
+  /** One resolved bearer is reused by every inventory and lease request in this pass. */
+  bearer: string;
+  scopes: readonly RealtimeScopeAuthorization[];
+}
+
+export interface RealtimePassRequest {
+  deviceId: string;
+  capabilityVector: RealtimeCapabilityVector;
+  configurationFingerprint: string;
+  scopeFingerprint: string;
+  scopeUids: readonly string[];
+}
+
+/**
+ * The only pre-I/O admission seam for later V2 work. It intentionally has no
+ * V1 fallback: malformed, stale, revoked, or non-ready inventory never gives
+ * an operation a lease. It resolves its bearer once, then reissues leases on
+ * every guarded pass so cached positives cannot cross server config/scope
+ * changes.
+ */
+export class RealtimePassAuthorizer {
+  constructor(
+    private readonly authToken: AuthTokenSource,
+    private readonly inventoryClient: RealtimeRolloutClient,
+    private readonly leaseClient: RealtimeLeaseClient,
+  ) {}
+
+  async authorize(request: RealtimePassRequest): Promise<RealtimePassAuthorization> {
+    const bearer = await resolveRealtimeBearer(this.authToken);
+    const inventoryRequest: RealtimeInventoryRequest = {
+      bearer,
+      deviceId: request.deviceId,
+      capabilityVector: request.capabilityVector,
+      configurationFingerprint: request.configurationFingerprint,
+      scopeFingerprint: request.scopeFingerprint,
+    };
+    const inventory = await this.inventoryClient.inventory(inventoryRequest);
+    const requested = new Set(request.scopeUids);
+    if (requested.size === 0) throw new Error("realtime authorization: guarded pass has no scopes");
+    const grants = inventory.scopes.filter((grant) => requested.has(grant.scopeUid));
+    if (grants.length !== requested.size || grants.some((grant) => grant.state !== "v2-ready")) {
+      throw new Error("realtime authorization: inventory does not authorize every requested scope");
+    }
+    const scopes = await Promise.all(grants.map(async (grant) => ({
+      grant: grant as RealtimeInventoryGrant & { state: "v2-ready" },
+      lease: await this.leaseClient.issue({
+        bearer,
+        deviceId: request.deviceId,
+        capabilityVector: request.capabilityVector,
+        scopeHandle: grant.scopeHandle,
+        scopeRevision: grant.scopeRevision,
+      }),
+    })));
+    const authorizationEpoch = scopes[0]?.lease.authorizationEpoch;
+    if (!authorizationEpoch || scopes.some((scope) => scope.lease.authorizationEpoch !== authorizationEpoch)) {
+      throw new Error("realtime authorization: leases disagree on authorization epoch");
+    }
+    for (const scope of scopes) this.leaseClient.assertUsable(scope.lease);
+    return { bearer, scopes };
+  }
+
+  async runBeforeIo<T>(request: RealtimePassRequest, operation: (authorization: RealtimePassAuthorization) => Promise<T>): Promise<T> {
+    return operation(await this.authorize(request));
+  }
+}