add encryption support to UserStateSubject

libs/common/src/tools/dependencies.ts

@@ -3,6 +3,8 @@ import { Observable } from "rxjs";
 import { Policy } from "@bitwarden/common/admin-console/models/domain/policy";
 import { UserId } from "@bitwarden/common/types/guid";
 
+import { UserEncryptor } from "./state/user-encryptor.abstraction";
+
 /** error emitted when the `SingleUserDependency` changes Ids */
 export type UserChangedError = {
   /** the userId pinned by the single user dependency */
@@ -45,6 +47,12 @@ export type UserDependency = {
   userId$: Observable<UserId>;
 };
 
+export type UserBound<K extends keyof any, T> = { [P in K]: T } & { userId: UserId };
+
+export type SingleUserEncryptorDependency = {
+  singleUserEncryptor$: Observable<UserBound<"encryptor", UserEncryptor>>;
+};
+
 /** A pattern for types that depend upon a fixed userid and return
  *  an observable.
  *

libs/common/src/tools/private-classifier.ts

@@ -0,0 +1,31 @@
+import { Jsonify } from "type-fest";
+
+import { Classifier } from "@bitwarden/common/tools/state/classifier";
+
+export class PrivateClassifier<Data> implements Classifier<Data, Record<string, never>, Data> {
+  constructor(private keys: (keyof Jsonify<Data>)[] = undefined) {}
+
+  classify(value: Data): { disclosed: Jsonify<Record<string, never>>; secret: Jsonify<Data> } {
+    const pickMe = JSON.parse(JSON.stringify(value));
+    const keys: (keyof Jsonify<Data>)[] = this.keys ?? (Object.keys(pickMe) as any);
+
+    const picked: Partial<Jsonify<Data>> = {};
+    for (const key of keys) {
+      picked[key] = pickMe[key];
+    }
+    const secret = picked as Jsonify<Data>;
+
+    return { disclosed: null, secret };
+  }
+
+  declassify(_disclosed: Jsonify<Record<keyof Data, never>>, secret: Jsonify<Data>) {
+    const result: Partial<Jsonify<Data>> = {};
+    const keys: (keyof Jsonify<Data>)[] = this.keys ?? (Object.keys(secret) as any);
+
+    for (const key of keys) {
+      result[key] = secret[key];
+    }
+
+    return result as Jsonify<Data>;
+  }
+}

libs/common/src/tools/public-classifier.ts

@@ -0,0 +1,29 @@
+import { Jsonify } from "type-fest";
+
+import { Classifier } from "@bitwarden/common/tools/state/classifier";
+
+export class PublicClassifier<Data> implements Classifier<Data, Data, Record<string, never>> {
+  constructor(private keys: (keyof Jsonify<Data>)[]) {}
+
+  classify(value: Data): { disclosed: Jsonify<Data>; secret: Jsonify<Record<string, never>> } {
+    const pickMe = JSON.parse(JSON.stringify(value));
+
+    const picked: Partial<Jsonify<Data>> = {};
+    for (const key of this.keys) {
+      picked[key] = pickMe[key];
+    }
+    const disclosed = picked as Jsonify<Data>;
+
+    return { disclosed, secret: null };
+  }
+
+  declassify(disclosed: Jsonify<Data>, _secret: Jsonify<Record<keyof Data, never>>) {
+    const result: Partial<Jsonify<Data>> = {};
+
+    for (const key of this.keys) {
+      result[key] = disclosed[key];
+    }
+
+    return result as Jsonify<Data>;
+  }
+}

libs/common/src/tools/rx.ts

@@ -1,4 +1,20 @@
-import { map, distinctUntilChanged, OperatorFunction } from "rxjs";
+import {
+  map,
+  distinctUntilChanged,
+  OperatorFunction,
+  Observable,
+  ignoreElements,
+  endWith,
+  race,
+  pipe,
+  connect,
+  ReplaySubject,
+  concat,
+  zip,
+  first,
+  takeUntil,
+  withLatestFrom,
+} from "rxjs";
 
 /**
  * An observable operator that reduces an emitted collection to a single object,
@@ -36,3 +52,81 @@ export function distinctIfShallowMatch<Item>(): OperatorFunction<Item, Item> {
     return isDistinct;
   });
 }
+
+/** Create an observable that, once subscribed, emits `true` then completes when
+ *   any input completes. If an input is already complete when the subscription
+ *   occurs, it emits immediately.
+ *  @param watch$ the observable(s) to watch for completion; if an array is passed,
+ *   null and undefined members are ignored. If `watch$` is empty, `anyComplete`
+ *   will never complete.
+ *  @returns An observable that emits `true` when any of its inputs
+ *   complete. The observable forwards the first error from its input.
+ *  @remarks This method is particularly useful in combination with `takeUntil` and
+ *   streams that are not guaranteed to complete on their own.
+ */
+export function anyComplete(watch$: Observable<any> | Observable<any>[]): Observable<any> {
+  if (Array.isArray(watch$)) {
+    const completes$ = watch$
+      .filter((w$) => !!w$)
+      .map((w$) => w$.pipe(ignoreElements(), endWith(true)));
+    const completed$ = race(completes$);
+    return completed$;
+  } else {
+    return watch$.pipe(ignoreElements(), endWith(true));
+  }
+}
+
+/**
+ * Create an observable that delays the input stream until all watches have
+ *  emitted a value. The watched values are not included in the source stream.
+ *  The last emission from the source is output when all the watches have
+ *  emitted at least once.
+ * @param watch$ the observable(s) to watch for readiness. If `watch$` is empty,
+ *  `ready` will never emit.
+ * @returns An observable that emits when the source stream emits. The observable
+ *   errors if one of its watches completes before emitting. It also errors if one
+ *   of its watches errors.
+ */
+export function ready<T>(watch$: Observable<any> | Observable<any>[]) {
+  const watching$ = Array.isArray(watch$) ? watch$ : [watch$];
+  return pipe(
+    connect<T, Observable<T>>((source$) => {
+      // this subscription is safe because `source$` connects only after there
+      // is an external subscriber.
+      const source = new ReplaySubject<T>(1);
+      source$.subscribe(source);
+
+      // `concat` is subscribed immediately after it's returned, at which point
+      // `zip` blocks until all items in `watching$` are ready. If that occurs
+      // after `source$` is hot, then the replay subject sends the last-captured
+      // emission through immediately. Otherwise, `ready` waits for the next
+      // emission
+      return concat(zip(watching$).pipe(first(), ignoreElements()), source).pipe(
+        takeUntil(anyComplete(source)),
+      );
+    }),
+  );
+}
+
+export function withLatestReady<Source, Watch>(
+  watch$: Observable<Watch>,
+): OperatorFunction<Source, [Source, Watch]> {
+  return pipe((source$) => {
+    // these subscriptions are safe because `source$` connects only after there
+    // is an external subscriber.
+    const source = new ReplaySubject<Source>(1);
+    source$.subscribe(source);
+    const watch = new ReplaySubject<Watch>(null);
+    watch$.subscribe(watch);
+
+    // `concat` is subscribed immediately after it's returned, at which point
+    // `zip` blocks until all items in `watching$` are ready. If that occurs
+    // after `source$` is hot, then the replay subject sends the last-captured
+    // emission through immediately. Otherwise, `ready` waits for the next
+    // emission
+    return concat(zip(watch).pipe(first(), ignoreElements()), source).pipe(
+      withLatestFrom(watch),
+      takeUntil(anyComplete(source)),
+    );
+  });
+}

libs/common/src/tools/state/classified-format.ts

@@ -17,3 +17,9 @@ export type ClassifiedFormat<Id, Disclosed> = {
    */
   readonly disclosed: Jsonify<Disclosed>;
 };
+
+export function isClassifiedFormat<Id, Disclosed>(
+  value: any,
+): value is ClassifiedFormat<Id, Disclosed> {
+  return "id" in value && "secret" in value && "disclosed" in value;
+}

libs/common/src/tools/state/identity-state-constraint.ts

@@ -1,4 +1,11 @@
-import { Constraints, StateConstraints } from "../types";
+import { BehaviorSubject, Observable } from "rxjs";
+
+import {
+  Constraints,
+  DynamicStateConstraints,
+  StateConstraints,
+  SubjectConstraints,
+} from "../types";
 
 // The constraints type shares the properties of the state,
 // but never has any members
@@ -9,16 +16,30 @@ const EMPTY_CONSTRAINTS = new Proxy<any>(Object.freeze({}), {
 });
 
 /** A constraint that does nothing. */
-export class IdentityConstraint<State extends object> implements StateConstraints<State> {
+export class IdentityConstraint<State extends object>
+  implements StateConstraints<State>, DynamicStateConstraints<State>
+{
   /** Instantiate the identity constraint */
   constructor() {}
 
   readonly constraints: Readonly<Constraints<State>> = EMPTY_CONSTRAINTS;
 
+  calibrate() {
+    return this;
+  }
+
   adjust(state: State) {
     return state;
   }
+
   fix(state: State) {
     return state;
   }
 }
+
+export function unconstrained$<State extends object>(): Observable<SubjectConstraints<State>> {
+  const identity = new IdentityConstraint<State>();
+  const constraints$ = new BehaviorSubject(identity);
+
+  return constraints$;
+}

libs/common/src/tools/state/state-constraints-dependency.ts

@@ -1,6 +1,6 @@
 import { Observable } from "rxjs";
 
-import { DynamicStateConstraints, StateConstraints } from "../types";
+import { DynamicStateConstraints, StateConstraints, SubjectConstraints } from "../types";
 
 /** A pattern for types that depend upon a dynamic set of constraints.
  *
@@ -10,12 +10,12 @@ import { DynamicStateConstraints, StateConstraints } from "../types";
  * last-emitted constraints. If `constraints$` completes, the consumer should
  * continue using the last-emitted constraints.
  */
-export type StateConstraintsDependency<State> = {
+export type SubjectConstraintsDependency<State> = {
   /** A stream that emits constraints when subscribed and when the
    *  constraints change. The stream should not emit `null` or
    *  `undefined`.
    */
-  constraints$: Observable<StateConstraints<State> | DynamicStateConstraints<State>>;
+  constraints$: Observable<SubjectConstraints<State>>;
 };
 
 /** Returns `true` if the input constraint is a `DynamicStateConstraints<T>`.

libs/common/src/tools/state/subject-key.ts

@@ -0,0 +1,53 @@
+import { UserKeyDefinition, UserKeyDefinitionOptions } from "../../platform/state";
+// eslint-disable-next-line -- `StateDefinition` used as a type
+import type { StateDefinition } from "../../platform/state/state-definition";
+
+import { ClassifiedFormat } from "./classified-format";
+import { Classifier } from "./classifier";
+
+/** A key for storing JavaScript objects (`{ an: "example" }`)
+ * in a UserStateSubject.
+ */
+// FIXME: promote to class: `ObjectConfiguration<State, Secret, Disclosed>`.
+//        The class receives `encryptor`, `prepareNext`, `adjust`, and `fix`
+//        From `UserStateSubject`. `UserStateSubject` keeps `classify` and
+//        `declassify`. The class should also include serialization
+//        facilities (to be used in place of JSON.parse/stringify) in it's
+//        options. Also allow swap between "classifier" and "classification"; the
+//        latter is a list of properties/arguments to the specific classifier in-use.
+export type ObjectKey<State, Secret = State, Disclosed = Record<string, never>> = {
+  target: "object";
+  key: string;
+  state: StateDefinition;
+  classifier: Classifier<void, Disclosed, Secret>;
+  format: "plain" | "classified";
+  options: UserKeyDefinitionOptions<State>;
+};
+
+export function isObjectKey(key: any): key is ObjectKey<unknown> {
+  return key.target === "object" && "format" in key && "classifier" in key;
+}
+
+export function toUserKeyDefinition<State, Secret, Disclosed>(
+  key: ObjectKey<State, Secret, Disclosed>,
+) {
+  if (key.format === "plain") {
+    const plain = new UserKeyDefinition<State>(key.state, key.key, key.options);
+
+    return plain;
+  } else if (key.format === "classified") {
+    const classified = new UserKeyDefinition<ClassifiedFormat<void, Disclosed>>(
+      key.state,
+      key.key,
+      {
+        cleanupDelayMs: key.options.cleanupDelayMs,
+        deserializer: (jsonValue) => jsonValue as ClassifiedFormat<void, Disclosed>,
+        clearOn: key.options.clearOn,
+      },
+    );
+
+    return classified;
+  } else {
+    throw new Error(`unknown format: ${key.format}`);
+  }
+}

libs/common/src/tools/state/user-state-subject-dependencies.ts

@@ -1,15 +1,23 @@
-import { Simplify } from "type-fest";
+import { RequireExactlyOne, Simplify } from "type-fest";
 
-import { Dependencies, SingleUserDependency, WhenDependency } from "../dependencies";
+import {
+  Dependencies,
+  SingleUserDependency,
+  SingleUserEncryptorDependency,
+  WhenDependency,
+} from "../dependencies";
 
-import { StateConstraintsDependency } from "./state-constraints-dependency";
+import { SubjectConstraintsDependency } from "./state-constraints-dependency";
 
 /** dependencies accepted by the user state subject */
 export type UserStateSubjectDependencies<State, Dependency> = Simplify<
-  SingleUserDependency &
+  RequireExactlyOne<
+    SingleUserDependency & SingleUserEncryptorDependency,
+    "singleUserEncryptor$" | "singleUserId$"
+  > &
     Partial<WhenDependency> &
     Partial<Dependencies<Dependency>> &
-    Partial<StateConstraintsDependency<State>> & {
+    Partial<SubjectConstraintsDependency<State>> & {
       /** Compute the next stored value. If this is not set, values
        *  provided to `next` unconditionally override state.
        *  @param current the value stored in state

libs/common/src/tools/state/user-state-subject.spec.ts

@@ -1,5 +1,6 @@
 import { BehaviorSubject, of, Subject } from "rxjs";
 
+import { GENERATOR_DISK, UserKeyDefinition } from "@bitwarden/common/platform/state";
 import { UserId } from "@bitwarden/common/types/guid";
 
 import { awaitAsync, FakeSingleUserState, ObservableTracker } from "../../../spec";
@@ -9,6 +10,10 @@ import { UserStateSubject } from "./user-state-subject";
 
 const SomeUser = "some user" as UserId;
 type TestType = { foo: string };
+const SomeKey = new UserKeyDefinition<TestType>(GENERATOR_DISK, "TestKey", {
+  deserializer: (d) => d as TestType,
+  clearOn: [],
+});
 
 function fooMaxLength(maxLength: number): StateConstraints<TestType> {
   return Object.freeze({
@@ -43,7 +48,11 @@ describe("UserStateSubject", () => {
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const nextValue = jest.fn((_, next) => next);
       const when$ = new BehaviorSubject(true);
-      const subject = new UserStateSubject(state, { singleUserId$, nextValue, when$ });
+      const subject = new UserStateSubject(SomeKey, () => state, {
+        singleUserId$,
+        nextValue,
+        when$,
+      });
 
       // the interleaved await asyncs are only necessary b/c `nextValue` is called asynchronously
       subject.next({ foo: "next" });
@@ -65,7 +74,11 @@ describe("UserStateSubject", () => {
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const nextValue = jest.fn((_, next) => next);
       const when$ = new BehaviorSubject(true);
-      const subject = new UserStateSubject(state, { singleUserId$, nextValue, when$ });
+      const subject = new UserStateSubject(SomeKey, () => state, {
+        singleUserId$,
+        nextValue,
+        when$,
+      });
 
       // the interleaved await asyncs are only necessary b/c `nextValue` is called asynchronously
       subject.next({ foo: "next" });
@@ -83,7 +96,7 @@ describe("UserStateSubject", () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, { foo: "init" });
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const constraints$ = new Subject<StateConstraints<TestType>>();
-      const subject = new UserStateSubject(state, { singleUserId$, constraints$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, constraints$ });
       const tracker = new ObservableTracker(subject);
 
       constraints$.next(fooMaxLength(3));
@@ -97,7 +110,7 @@ describe("UserStateSubject", () => {
     it("emits the next value", async () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, { foo: "init" });
       const singleUserId$ = new BehaviorSubject(SomeUser);
-      const subject = new UserStateSubject(state, { singleUserId$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$ });
       const expected: TestType = { foo: "next" };
 
       let actual: TestType = null;
@@ -114,7 +127,7 @@ describe("UserStateSubject", () => {
       const initialState = { foo: "init" };
       const state = new FakeSingleUserState<TestType>(SomeUser, initialState);
       const singleUserId$ = new BehaviorSubject(SomeUser);
-      const subject = new UserStateSubject(state, { singleUserId$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$ });
 
       let actual: TestType = null;
       subject.subscribe((value) => {
@@ -132,7 +145,7 @@ describe("UserStateSubject", () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, initialValue);
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const shouldUpdate = jest.fn(() => true);
-      const subject = new UserStateSubject(state, { singleUserId$, shouldUpdate });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, shouldUpdate });
 
       const nextVal: TestType = { foo: "next" };
       subject.next(nextVal);
@@ -147,7 +160,7 @@ describe("UserStateSubject", () => {
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const shouldUpdate = jest.fn(() => true);
       const dependencyValue = { bar: "dependency" };
-      const subject = new UserStateSubject(state, {
+      const subject = new UserStateSubject(SomeKey, () => state, {
         singleUserId$,
         shouldUpdate,
         dependencies$: of(dependencyValue),
@@ -165,7 +178,7 @@ describe("UserStateSubject", () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, initialValue);
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const shouldUpdate = jest.fn(() => true);
-      const subject = new UserStateSubject(state, { singleUserId$, shouldUpdate });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, shouldUpdate });
       const expected: TestType = { foo: "next" };
 
       let actual: TestType = null;
@@ -183,7 +196,7 @@ describe("UserStateSubject", () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, initialValue);
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const shouldUpdate = jest.fn(() => false);
-      const subject = new UserStateSubject(state, { singleUserId$, shouldUpdate });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, shouldUpdate });
 
       subject.next({ foo: "next" });
       await awaitAsync();
@@ -200,7 +213,7 @@ describe("UserStateSubject", () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, initialValue);
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const nextValue = jest.fn((_, next) => next);
-      const subject = new UserStateSubject(state, { singleUserId$, nextValue });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, nextValue });
 
       const nextVal: TestType = { foo: "next" };
       subject.next(nextVal);
@@ -215,7 +228,7 @@ describe("UserStateSubject", () => {
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const nextValue = jest.fn((_, next) => next);
       const dependencyValue = { bar: "dependency" };
-      const subject = new UserStateSubject(state, {
+      const subject = new UserStateSubject(SomeKey, () => state, {
         singleUserId$,
         nextValue,
         dependencies$: of(dependencyValue),
@@ -236,7 +249,11 @@ describe("UserStateSubject", () => {
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const nextValue = jest.fn((_, next) => next);
       const when$ = new BehaviorSubject(true);
-      const subject = new UserStateSubject(state, { singleUserId$, nextValue, when$ });
+      const subject = new UserStateSubject(SomeKey, () => state, {
+        singleUserId$,
+        nextValue,
+        when$,
+      });
 
       const nextVal: TestType = { foo: "next" };
       subject.next(nextVal);
@@ -253,7 +270,11 @@ describe("UserStateSubject", () => {
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const nextValue = jest.fn((_, next) => next);
       const when$ = new BehaviorSubject(false);
-      const subject = new UserStateSubject(state, { singleUserId$, nextValue, when$ });
+      const subject = new UserStateSubject(SomeKey, () => state, {
+        singleUserId$,
+        nextValue,
+        when$,
+      });
 
       const nextVal: TestType = { foo: "next" };
       subject.next(nextVal);
@@ -265,42 +286,30 @@ describe("UserStateSubject", () => {
       expect(nextValue).toHaveBeenCalled();
     });
 
-    it("waits to evaluate nextValue until singleUserId$ emits", async () => {
-      // this test looks for `nextValue` because a subscription isn't necessary for
+    it("waits to evaluate `UserState.update` until singleUserId$ emits", async () => {
+      // this test looks for `nextMock` because a subscription isn't necessary for
       // the subject to update.
       const initialValue: TestType = { foo: "init" };
       const state = new FakeSingleUserState<TestType>(SomeUser, initialValue);
       const singleUserId$ = new Subject<UserId>();
       const nextValue = jest.fn((_, next) => next);
-      const subject = new UserStateSubject(state, { singleUserId$, nextValue });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, nextValue });
 
       const nextVal: TestType = { foo: "next" };
       subject.next(nextVal);
       await awaitAsync();
-      expect(nextValue).not.toHaveBeenCalled();
+      expect(state.nextMock).not.toHaveBeenCalled();
       singleUserId$.next(SomeUser);
       await awaitAsync();
 
-      expect(nextValue).toHaveBeenCalled();
-    });
-
-    it("applies constraints$ on init", async () => {
-      const state = new FakeSingleUserState<TestType>(SomeUser, { foo: "init" });
-      const singleUserId$ = new BehaviorSubject(SomeUser);
-      const constraints$ = new BehaviorSubject(fooMaxLength(2));
-      const subject = new UserStateSubject(state, { singleUserId$, constraints$ });
-      const tracker = new ObservableTracker(subject);
-
-      const [result] = await tracker.pauseUntilReceived(1);
-
-      expect(result).toEqual({ foo: "in" });
+      expect(state.nextMock).toHaveBeenCalled();
     });
 
     it("applies dynamic constraints", async () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, { foo: "init" });
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const constraints$ = new BehaviorSubject(DynamicFooMaxLength);
-      const subject = new UserStateSubject(state, { singleUserId$, constraints$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, constraints$ });
       const tracker = new ObservableTracker(subject);
       const expected: TestType = { foo: "next" };
       const emission = tracker.expectEmission();
@@ -311,24 +320,11 @@ describe("UserStateSubject", () => {
       expect(actual).toEqual({ foo: "" });
     });
 
-    it("applies constraints$ on constraints$ emission", async () => {
-      const state = new FakeSingleUserState<TestType>(SomeUser, { foo: "init" });
-      const singleUserId$ = new BehaviorSubject(SomeUser);
-      const constraints$ = new BehaviorSubject(fooMaxLength(2));
-      const subject = new UserStateSubject(state, { singleUserId$, constraints$ });
-      const tracker = new ObservableTracker(subject);
-
-      constraints$.next(fooMaxLength(1));
-      const [, result] = await tracker.pauseUntilReceived(2);
-
-      expect(result).toEqual({ foo: "i" });
-    });
-
     it("applies constraints$ on next", async () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, { foo: "init" });
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const constraints$ = new BehaviorSubject(fooMaxLength(2));
-      const subject = new UserStateSubject(state, { singleUserId$, constraints$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, constraints$ });
       const tracker = new ObservableTracker(subject);
 
       subject.next({ foo: "next" });
@@ -341,7 +337,7 @@ describe("UserStateSubject", () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, { foo: "init" });
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const constraints$ = new BehaviorSubject(fooMaxLength(2));
-      const subject = new UserStateSubject(state, { singleUserId$, constraints$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, constraints$ });
       const tracker = new ObservableTracker(subject);
 
       constraints$.next(fooMaxLength(3));
@@ -355,7 +351,7 @@ describe("UserStateSubject", () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, { foo: "init" });
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const constraints$ = new Subject<StateConstraints<TestType>>();
-      const subject = new UserStateSubject(state, { singleUserId$, constraints$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, constraints$ });
       const tracker = new ObservableTracker(subject);
 
       subject.next({ foo: "next" });
@@ -370,7 +366,7 @@ describe("UserStateSubject", () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, { foo: "init" });
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const constraints$ = new BehaviorSubject(fooMaxLength(3));
-      const subject = new UserStateSubject(state, { singleUserId$, constraints$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, constraints$ });
       const tracker = new ObservableTracker(subject);
 
       constraints$.error({ some: "error" });
@@ -384,7 +380,7 @@ describe("UserStateSubject", () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, { foo: "init" });
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const constraints$ = new BehaviorSubject(fooMaxLength(3));
-      const subject = new UserStateSubject(state, { singleUserId$, constraints$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, constraints$ });
       const tracker = new ObservableTracker(subject);
 
       constraints$.complete();
@@ -399,7 +395,7 @@ describe("UserStateSubject", () => {
     it("emits errors", async () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, { foo: "init" });
       const singleUserId$ = new BehaviorSubject(SomeUser);
-      const subject = new UserStateSubject(state, { singleUserId$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$ });
       const expected: TestType = { foo: "error" };
 
       let actual: TestType = null;
@@ -418,7 +414,7 @@ describe("UserStateSubject", () => {
       const initialState = { foo: "init" };
       const state = new FakeSingleUserState<TestType>(SomeUser, initialState);
       const singleUserId$ = new BehaviorSubject(SomeUser);
-      const subject = new UserStateSubject(state, { singleUserId$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$ });
 
       let actual: TestType = null;
       subject.subscribe({
@@ -437,7 +433,7 @@ describe("UserStateSubject", () => {
       const initialState = { foo: "init" };
       const state = new FakeSingleUserState<TestType>(SomeUser, initialState);
       const singleUserId$ = new BehaviorSubject(SomeUser);
-      const subject = new UserStateSubject(state, { singleUserId$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$ });
 
       let shouldNotRun = false;
       subject.subscribe({
@@ -457,7 +453,7 @@ describe("UserStateSubject", () => {
     it("emits completes", async () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, { foo: "init" });
       const singleUserId$ = new BehaviorSubject(SomeUser);
-      const subject = new UserStateSubject(state, { singleUserId$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$ });
 
       let actual = false;
       subject.subscribe({
@@ -475,7 +471,7 @@ describe("UserStateSubject", () => {
       const initialState = { foo: "init" };
       const state = new FakeSingleUserState<TestType>(SomeUser, initialState);
       const singleUserId$ = new BehaviorSubject(SomeUser);
-      const subject = new UserStateSubject(state, { singleUserId$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$ });
 
       let shouldNotRun = false;
       subject.subscribe({
@@ -496,7 +492,7 @@ describe("UserStateSubject", () => {
       const initialState = { foo: "init" };
       const state = new FakeSingleUserState<TestType>(SomeUser, initialState);
       const singleUserId$ = new BehaviorSubject(SomeUser);
-      const subject = new UserStateSubject(state, { singleUserId$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$ });
 
       let timesRun = 0;
       subject.subscribe({
@@ -513,11 +509,36 @@ describe("UserStateSubject", () => {
   });
 
   describe("subscribe", () => {
+    it("applies constraints$ on init", async () => {
+      const state = new FakeSingleUserState<TestType>(SomeUser, { foo: "init" });
+      const singleUserId$ = new BehaviorSubject(SomeUser);
+      const constraints$ = new BehaviorSubject(fooMaxLength(2));
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, constraints$ });
+      const tracker = new ObservableTracker(subject);
+
+      const [result] = await tracker.pauseUntilReceived(1);
+
+      expect(result).toEqual({ foo: "in" });
+    });
+
+    it("applies constraints$ on constraints$ emission", async () => {
+      const state = new FakeSingleUserState<TestType>(SomeUser, { foo: "init" });
+      const singleUserId$ = new BehaviorSubject(SomeUser);
+      const constraints$ = new BehaviorSubject(fooMaxLength(2));
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, constraints$ });
+      const tracker = new ObservableTracker(subject);
+
+      constraints$.next(fooMaxLength(1));
+      const [, result] = await tracker.pauseUntilReceived(2);
+
+      expect(result).toEqual({ foo: "i" });
+    });
+
     it("completes when singleUserId$ completes", async () => {
       const initialValue: TestType = { foo: "init" };
       const state = new FakeSingleUserState<TestType>(SomeUser, initialValue);
       const singleUserId$ = new BehaviorSubject(SomeUser);
-      const subject = new UserStateSubject(state, { singleUserId$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$ });
 
       let actual = false;
       subject.subscribe({
@@ -536,7 +557,7 @@ describe("UserStateSubject", () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, initialValue);
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const when$ = new BehaviorSubject(true);
-      const subject = new UserStateSubject(state, { singleUserId$, when$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, when$ });
 
       let actual = false;
       subject.subscribe({
@@ -557,7 +578,7 @@ describe("UserStateSubject", () => {
       const initialValue: TestType = { foo: "init" };
       const state = new FakeSingleUserState<TestType>(SomeUser, initialValue);
       const singleUserId$ = new BehaviorSubject(SomeUser);
-      const subject = new UserStateSubject(state, { singleUserId$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$ });
       const errorUserId = "error" as UserId;
 
       let error = false;
@@ -576,7 +597,7 @@ describe("UserStateSubject", () => {
       const initialValue: TestType = { foo: "init" };
       const state = new FakeSingleUserState<TestType>(SomeUser, initialValue);
       const singleUserId$ = new BehaviorSubject(SomeUser);
-      const subject = new UserStateSubject(state, { singleUserId$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$ });
       const expected = { error: "description" };
 
       let actual = false;
@@ -596,7 +617,7 @@ describe("UserStateSubject", () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, initialValue);
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const when$ = new BehaviorSubject(true);
-      const subject = new UserStateSubject(state, { singleUserId$, when$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, when$ });
       const expected = { error: "description" };
 
       let actual = false;
@@ -616,7 +637,7 @@ describe("UserStateSubject", () => {
     it("returns the userId to which the subject is bound", () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, { foo: "init" });
       const singleUserId$ = new Subject<UserId>();
-      const subject = new UserStateSubject(state, { singleUserId$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$ });
 
       expect(subject.userId).toEqual(SomeUser);
     });
@@ -626,7 +647,7 @@ describe("UserStateSubject", () => {
     it("emits the next value with an empty constraint", async () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, { foo: "init" });
       const singleUserId$ = new BehaviorSubject(SomeUser);
-      const subject = new UserStateSubject(state, { singleUserId$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$ });
       const tracker = new ObservableTracker(subject.withConstraints$);
       const expected: TestType = { foo: "next" };
       const emission = tracker.expectEmission();
@@ -642,7 +663,7 @@ describe("UserStateSubject", () => {
       const initialState = { foo: "init" };
       const state = new FakeSingleUserState<TestType>(SomeUser, initialState);
       const singleUserId$ = new BehaviorSubject(SomeUser);
-      const subject = new UserStateSubject(state, { singleUserId$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$ });
       const tracker = new ObservableTracker(subject.withConstraints$);
 
       subject.complete();
@@ -657,7 +678,7 @@ describe("UserStateSubject", () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, { foo: "init" });
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const constraints$ = new BehaviorSubject(fooMaxLength(2));
-      const subject = new UserStateSubject(state, { singleUserId$, constraints$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, constraints$ });
       const tracker = new ObservableTracker(subject.withConstraints$);
       const expected = fooMaxLength(1);
       const emission = tracker.expectEmission();
@@ -673,7 +694,7 @@ describe("UserStateSubject", () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, { foo: "init" });
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const constraints$ = new BehaviorSubject(DynamicFooMaxLength);
-      const subject = new UserStateSubject(state, { singleUserId$, constraints$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, constraints$ });
       const tracker = new ObservableTracker(subject.withConstraints$);
       const expected: TestType = { foo: "next" };
       const emission = tracker.expectEmission();
@@ -690,7 +711,7 @@ describe("UserStateSubject", () => {
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const expected = fooMaxLength(2);
       const constraints$ = new BehaviorSubject(expected);
-      const subject = new UserStateSubject(state, { singleUserId$, constraints$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, constraints$ });
       const tracker = new ObservableTracker(subject.withConstraints$);
       const emission = tracker.expectEmission();
 
@@ -705,7 +726,7 @@ describe("UserStateSubject", () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, { foo: "init" });
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const constraints$ = new BehaviorSubject(fooMaxLength(2));
-      const subject = new UserStateSubject(state, { singleUserId$, constraints$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, constraints$ });
       const tracker = new ObservableTracker(subject.withConstraints$);
       const expected = fooMaxLength(3);
       constraints$.next(expected);
@@ -722,7 +743,7 @@ describe("UserStateSubject", () => {
       const state = new FakeSingleUserState<TestType>(SomeUser, { foo: "init" });
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const constraints$ = new Subject<StateConstraints<TestType>>();
-      const subject = new UserStateSubject(state, { singleUserId$, constraints$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, constraints$ });
       const tracker = new ObservableTracker(subject.withConstraints$);
       const expected = fooMaxLength(3);
 
@@ -740,7 +761,7 @@ describe("UserStateSubject", () => {
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const expected = fooMaxLength(3);
       const constraints$ = new BehaviorSubject(expected);
-      const subject = new UserStateSubject(state, { singleUserId$, constraints$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, constraints$ });
       const tracker = new ObservableTracker(subject.withConstraints$);
 
       constraints$.error({ some: "error" });
@@ -756,7 +777,7 @@ describe("UserStateSubject", () => {
       const singleUserId$ = new BehaviorSubject(SomeUser);
       const expected = fooMaxLength(3);
       const constraints$ = new BehaviorSubject(expected);
-      const subject = new UserStateSubject(state, { singleUserId$, constraints$ });
+      const subject = new UserStateSubject(SomeKey, () => state, { singleUserId$, constraints$ });
       const tracker = new ObservableTracker(subject.withConstraints$);
 
       constraints$.complete();

libs/common/src/tools/state/user-state-subject.ts

@@ -8,12 +8,8 @@ import {
   Subject,
   takeUntil,
   pairwise,
-  combineLatest,
   distinctUntilChanged,
   BehaviorSubject,
-  race,
-  ignoreElements,
-  endWith,
   startWith,
   Observable,
   Subscription,
@@ -22,16 +18,32 @@ import {
   combineLatestWith,
   catchError,
   EMPTY,
+  concatMap,
+  OperatorFunction,
+  pipe,
+  first,
+  withLatestFrom,
+  scan,
+  skip,
 } from "rxjs";
 
-import { SingleUserState } from "@bitwarden/common/platform/state";
+import { EncString } from "@bitwarden/common/platform/models/domain/enc-string";
+import { SingleUserState, UserKeyDefinition } from "@bitwarden/common/platform/state";
+import { UserId } from "@bitwarden/common/types/guid";
 
-import { WithConstraints } from "../types";
+import { UserBound } from "../dependencies";
+import { anyComplete, ready, withLatestReady } from "../rx";
+import { Constraints, SubjectConstraints, WithConstraints } from "../types";
 
-import { IdentityConstraint } from "./identity-state-constraint";
+import { ClassifiedFormat, isClassifiedFormat } from "./classified-format";
+import { unconstrained$ } from "./identity-state-constraint";
 import { isDynamic } from "./state-constraints-dependency";
+import { isObjectKey, ObjectKey, toUserKeyDefinition } from "./subject-key";
+import { UserEncryptor } from "./user-encryptor.abstraction";
 import { UserStateSubjectDependencies } from "./user-state-subject-dependencies";
 
+type Constrained<State> = { constraints: Readonly<Constraints<State>>; state: State };
+
 /**
  * Adapt a state provider to an rxjs subject.
  *
@@ -44,14 +56,19 @@ import { UserStateSubjectDependencies } from "./user-state-subject-dependencies"
  * @template State the state stored by the subject
  * @template Dependencies use-specific dependencies provided by the user.
  */
-export class UserStateSubject<State extends object, Dependencies = null>
+export class UserStateSubject<
+    State extends object,
+    Secret = State,
+    Disclosed = never,
+    Dependencies = null,
+  >
   extends Observable<State>
   implements SubjectLike<State>
 {
   /**
    * Instantiates the user state subject
-   * @param state the backing store of the subject
-   * @param dependencies tailor the subject's behavior for a particular
+   * @param getState the backing store of the subject
+   * @param context tailor the subject's behavior for a particular
    *   purpose.
    * @param dependencies.when$ blocks updates to the state subject until
    *   this becomes true. When this occurs, only the last-received update
@@ -61,93 +78,299 @@ export class UserStateSubject<State extends object, Dependencies = null>
    *   is available.
    */
   constructor(
-    private state: SingleUserState<State>,
-    private dependencies: UserStateSubjectDependencies<State, Dependencies>,
+    private key: UserKeyDefinition<State> | ObjectKey<State, Secret, Disclosed>,
+    getState: (key: UserKeyDefinition<unknown>) => SingleUserState<unknown>,
+    private context: UserStateSubjectDependencies<State, Dependencies>,
   ) {
     super();
 
+    if (isObjectKey(this.key)) {
+      // classification and encryption only supported with `ObjectKey`
+      this.objectKey = this.key;
+      this.stateKey = toUserKeyDefinition(this.key);
+      this.state = getState(this.stateKey);
+    } else {
+      // raw state access granted with `UserKeyDefinition`
+      this.objectKey = null;
+      this.stateKey = this.key as UserKeyDefinition<State>;
+      this.state = getState(this.stateKey);
+    }
+
     // normalize dependencies
-    const when$ = (this.dependencies.when$ ?? new BehaviorSubject(true)).pipe(
-      distinctUntilChanged(),
-    );
-    const userIdAvailable$ = this.dependencies.singleUserId$.pipe(
-      startWith(state.userId),
-      pairwise(),
-      map(([expectedUserId, actualUserId]) => {
-        if (expectedUserId === actualUserId) {
-          return true;
-        } else {
-          throw { expectedUserId, actualUserId };
-        }
-      }),
-      distinctUntilChanged(),
-    );
-    const constraints$ = (
-      this.dependencies.constraints$ ?? new BehaviorSubject(new IdentityConstraint<State>())
-    ).pipe(
-      // FIXME: this should probably log that an error occurred
-      catchError(() => EMPTY),
-    );
+    const when$ = (this.context.when$ ?? new BehaviorSubject(true)).pipe(distinctUntilChanged());
 
-    // normalize input in case this `UserStateSubject` is not the only
-    // observer of the backing store
-    const input$ = combineLatest([this.input, constraints$]).pipe(
-      map(([input, constraints]) => {
-        const calibration = isDynamic(constraints) ? constraints.calibrate(input) : constraints;
-        const state = calibration.adjust(input);
-        return state;
-      }),
-    );
+    // manage dependencies through replay subjects since `UserStateSubject`
+    // reads them in multiple places
+    const encryptor$ = new ReplaySubject<UserEncryptor>(1);
+    const { singleUserId$, singleUserEncryptor$ } = this.context;
+    this.encryptor(singleUserEncryptor$ ?? singleUserId$).subscribe(encryptor$);
 
-    // when the output subscription completes, its last-emitted value
-    // loops around to the input for finalization
-    const finalize$ = this.pipe(
-      last(),
-      combineLatestWith(constraints$),
-      map(([output, constraints]) => {
-        const calibration = isDynamic(constraints) ? constraints.calibrate(output) : constraints;
-        const state = calibration.fix(output);
-        return state;
-      }),
-    );
-    const updates$ = concat(input$, finalize$);
+    const constraints$ = new ReplaySubject<SubjectConstraints<State>>(1);
+    (this.context.constraints$ ?? unconstrained$<State>())
+      .pipe(
+        // FIXME: this should probably log that an error occurred
+        catchError(() => EMPTY),
+      )
+      .subscribe(constraints$);
 
-    // observe completion
-    const whenComplete$ = when$.pipe(ignoreElements(), endWith(true));
-    const inputComplete$ = this.input.pipe(ignoreElements(), endWith(true));
-    const userIdComplete$ = this.dependencies.singleUserId$.pipe(ignoreElements(), endWith(true));
-    const completion$ = race(whenComplete$, inputComplete$, userIdComplete$);
+    const dependencies$ = new ReplaySubject<Dependencies>(1);
+    if (this.context.dependencies$) {
+      this.context.dependencies$.subscribe(dependencies$);
+    } else {
+      dependencies$.next(null);
+    }
 
     // wire output before input so that output normalizes the current state
     // before any `next` value is processed
     this.outputSubscription = this.state.state$
-      .pipe(
-        combineLatestWith(constraints$),
-        map(([rawState, constraints]) => {
-          const calibration = isDynamic(constraints)
-            ? constraints.calibrate(rawState)
-            : constraints;
-          const state = calibration.adjust(rawState);
-          return {
-            constraints: calibration.constraints,
-            state,
-          };
-        }),
-      )
+      .pipe(this.declassify(encryptor$), this.adjust(combineLatestWith(constraints$)))
       .subscribe(this.output);
-    this.inputSubscription = combineLatest([updates$, when$, userIdAvailable$])
+
+    const last$ = new ReplaySubject<State>(1);
+    this.output
       .pipe(
-        filter(([_, when]) => when),
-        map(([state]) => state),
-        takeUntil(completion$),
+        last(),
+        map((o) => o.state),
       )
+      .subscribe(last$);
+
+    // the update stream simulates the stateProvider's "shouldUpdate"
+    // functionality & applies policy
+    const updates$ = concat(
+      // normalize input in case this `UserStateSubject` is not the only
+      // observer of the backing store
+      this.input.pipe(
+        this.when(when$),
+        this.adjust(withLatestReady(constraints$)),
+        this.prepareUpdate(this, dependencies$),
+      ),
+      // when the output subscription completes, its last-emitted value
+      // loops around to the input for finalization
+      last$.pipe(this.fix(constraints$), this.prepareUpdate(last$, dependencies$)),
+    );
+
+    // classification/encryption bound to the input subscription's lifetime
+    // to ensure that `fix` has access to the encryptor key
+    //
+    // FIXME: this should probably timeout when a lock occurs
+    this.inputSubscription = updates$
+      .pipe(this.classify(encryptor$), takeUntil(anyComplete([when$, this.input, encryptor$])))
       .subscribe({
-        next: (r) => this.onNext(r),
+        next: (state) => this.onNext(state),
         error: (e: unknown) => this.onError(e),
         complete: () => this.onComplete(),
       });
   }
 
+  private stateKey: UserKeyDefinition<unknown>;
+  private objectKey: ObjectKey<State, Secret, Disclosed>;
+
+  private encryptor(
+    singleUserEncryptor$: Observable<UserBound<"encryptor", UserEncryptor> | UserId>,
+  ): Observable<UserEncryptor> {
+    return singleUserEncryptor$.pipe(
+      // normalize inputs
+      map((maybe): UserBound<"encryptor", UserEncryptor> => {
+        if (typeof maybe === "object" && "encryptor" in maybe) {
+          return maybe;
+        } else if (typeof maybe === "string") {
+          return { encryptor: null, userId: maybe as UserId };
+        } else {
+          throw new Error(`Invalid encryptor input received for ${this.key.key}.`);
+        }
+      }),
+      // fail the stream if the state desyncs from the bound userId
+      startWith({ userId: this.state.userId, encryptor: null } as UserBound<
+        "encryptor",
+        UserEncryptor
+      >),
+      pairwise(),
+      map(([expected, actual]) => {
+        if (expected.userId === actual.userId) {
+          return actual;
+        } else {
+          throw {
+            expectedUserId: expected.userId,
+            actualUserId: actual.userId,
+          };
+        }
+      }),
+      // reduce emissions to when encryptor changes
+      distinctUntilChanged(),
+      map(({ encryptor }) => encryptor),
+    );
+  }
+
+  private when(when$: Observable<boolean>): OperatorFunction<State, State> {
+    return pipe(
+      combineLatestWith(when$.pipe(distinctUntilChanged())),
+      filter(([_, when]) => !!when),
+      map(([input]) => input),
+    );
+  }
+
+  private prepareUpdate(
+    init$: Observable<State>,
+    dependencies$: Observable<Dependencies>,
+  ): OperatorFunction<Constrained<State>, State> {
+    return (input$) =>
+      concat(
+        // `init$` becomes the accumulator for `scan`
+        init$.pipe(
+          first(),
+          map((init) => [init, null] as const),
+        ),
+        input$.pipe(
+          map((constrained) => constrained.state),
+          withLatestFrom(dependencies$),
+        ),
+      ).pipe(
+        // scan only emits values that can cause updates
+        scan(([prev], [pending, dependencies]) => {
+          const shouldUpdate = this.context.shouldUpdate?.(prev, pending, dependencies) ?? true;
+          if (shouldUpdate) {
+            // actual update
+            const next = this.context.nextValue?.(prev, pending, dependencies) ?? pending;
+            return [next, dependencies];
+          } else {
+            // false update
+            return [prev, null];
+          }
+        }),
+        // the first emission primes `scan`s aggregator
+        skip(1),
+        map(([state]) => state),
+
+        // clean up false updates
+        distinctUntilChanged(),
+      );
+  }
+
+  private adjust(
+    withConstraints: OperatorFunction<State, [State, SubjectConstraints<State>]>,
+  ): OperatorFunction<State, Constrained<State>> {
+    return pipe(
+      // how constraints are blended with incoming emissions varies:
+      // * `output` needs to emit when constraints update
+      // * `input` needs to wait until a message flows through the pipe
+      withConstraints,
+      map(([loadedState, constraints]) => {
+        const calibration = isDynamic(constraints)
+          ? constraints.calibrate(loadedState)
+          : constraints;
+        const adjusted = calibration.adjust(loadedState);
+
+        return {
+          constraints: calibration.constraints,
+          state: adjusted,
+        };
+      }),
+    );
+  }
+
+  private fix(
+    constraints$: Observable<SubjectConstraints<State>>,
+  ): OperatorFunction<State, Constrained<State>> {
+    return pipe(
+      combineLatestWith(constraints$),
+      map(([loadedState, constraints]) => {
+        const calibration = isDynamic(constraints)
+          ? constraints.calibrate(loadedState)
+          : constraints;
+        const fixed = calibration.fix(loadedState);
+
+        return {
+          constraints: calibration.constraints,
+          state: fixed,
+        };
+      }),
+    );
+  }
+
+  private declassify(encryptor$: Observable<UserEncryptor>): OperatorFunction<unknown, State> {
+    // short-circuit if they key lacks encryption support
+    if (!this.objectKey || this.objectKey.format === "plain") {
+      return (input$) => input$ as Observable<State>;
+    }
+
+    // if the key supports encryption, enable encryptor support
+    if (this.objectKey && this.objectKey.format === "classified") {
+      return pipe(
+        combineLatestWith(encryptor$),
+        concatMap(async ([input, encryptor]) => {
+          // pass through null values
+          if (input === null || input === undefined) {
+            return null;
+          }
+
+          // fail fast if the format is incorrect
+          if (!isClassifiedFormat(input)) {
+            throw new Error(`Cannot declassify ${this.key.key}; unknown format.`);
+          }
+
+          // decrypt classified data
+          const { secret, disclosed } = input;
+          const encrypted = EncString.fromJSON(secret);
+          const decryptedSecret = await encryptor.decrypt<Secret>(encrypted);
+
+          // assemble into proper state
+          const declassified = this.objectKey.classifier.declassify(disclosed, decryptedSecret);
+          const state = this.objectKey.options.deserializer(declassified);
+
+          return state;
+        }),
+      );
+    }
+
+    throw new Error(`unknown serialization format: ${this.objectKey.format}`);
+  }
+
+  private classify(encryptor$: Observable<UserEncryptor>): OperatorFunction<State, unknown> {
+    // short-circuit if they key lacks encryption support
+    if (!this.objectKey || this.objectKey.format === "plain") {
+      return pipe(
+        ready(encryptor$),
+        map((input) => input as unknown),
+      );
+    }
+
+    // if the key supports encryption, enable encryptor support
+    if (this.objectKey && this.objectKey.format === "classified") {
+      return pipe(
+        combineLatestWith(encryptor$),
+        concatMap(async ([input, encryptor]) => {
+          // fail fast if there's no value
+          if (input === null || input === undefined) {
+            return null;
+          }
+
+          // split data by classification level
+          const serialized = JSON.parse(JSON.stringify(input));
+          const classified = this.objectKey.classifier.classify(serialized);
+
+          // protect data
+          const encrypted = await encryptor.encrypt(classified.secret);
+          const secret = JSON.parse(JSON.stringify(encrypted));
+
+          // wrap result in classified format envelope for storage
+          const envelope = {
+            id: null as void,
+            secret,
+            disclosed: classified.disclosed,
+          } satisfies ClassifiedFormat<void, Disclosed>;
+
+          // deliberate type erasure; the type is restored during `declassify`
+          return envelope as unknown;
+        }),
+      );
+    }
+
+    // FIXME: add "encrypted" format --> key contains encryption logic
+    // CONSIDER: should "classified format" algorithm be embedded in subject keys...?
+
+    throw new Error(`unknown serialization format: ${this.objectKey.format}`);
+  }
+
   /** The userId to which the subject is bound.
    */
   get userId() {
@@ -178,6 +401,7 @@ export class UserStateSubject<State extends object, Dependencies = null>
   // if greater efficiency becomes desirable, consider implementing
   // `SubjectLike` directly
   private input = new Subject<State>();
+  private state: SingleUserState<unknown>;
   private readonly output = new ReplaySubject<WithConstraints<State>>(1);
 
   /** A stream containing settings and their last-applied constraints. */
@@ -188,25 +412,8 @@ export class UserStateSubject<State extends object, Dependencies = null>
   private inputSubscription: Unsubscribable;
   private outputSubscription: Unsubscribable;
 
-  private onNext(value: State) {
-    const nextValue = this.dependencies.nextValue ?? ((_: State, next: State) => next);
-    const shouldUpdate = this.dependencies.shouldUpdate ?? ((_: State) => true);
-
-    this.state
-      .update(
-        (state, dependencies) => {
-          const next = nextValue(state, value, dependencies);
-          return next;
-        },
-        {
-          shouldUpdate(current, dependencies) {
-            const update = shouldUpdate(current, value, dependencies);
-            return update;
-          },
-          combineLatestWith: this.dependencies.dependencies$,
-        },
-      )
-      .catch((e: any) => this.onError(e));
+  private onNext(value: unknown) {
+    this.state.update(() => value).catch((e: any) => this.onError(e));
   }
 
   private onError(value: any) {
@@ -232,8 +439,8 @@ export class UserStateSubject<State extends object, Dependencies = null>
   private dispose() {
     if (!this.isDisposed) {
       // clean up internal subscriptions
-      this.inputSubscription.unsubscribe();
-      this.outputSubscription.unsubscribe();
+      this.inputSubscription?.unsubscribe();
+      this.outputSubscription?.unsubscribe();
       this.inputSubscription = null;
       this.outputSubscription = null;
 

libs/common/src/tools/types.ts

@@ -131,6 +131,8 @@ export type StateConstraints<State> = {
   fix: (state: State) => State;
 };
 
+export type SubjectConstraints<T> = StateConstraints<T> | DynamicStateConstraints<T>;
+
 /** Options that provide contextual information about the application state
  *  when a generator is invoked.
  */
@@ -146,6 +148,7 @@ export type VaultItemRequest = {
 /** Options that provide contextual information about the application state
  *  when a generator is invoked.
  */
-export type GenerationRequest = Partial<VaultItemRequest> & Partial<{
-  integration: IntegrationId | null
-}>;
+export type GenerationRequest = Partial<VaultItemRequest> &
+  Partial<{
+    integration: IntegrationId | null;
+  }>;

libs/tools/generator/core/src/engine/forwarder.ts

@@ -1,30 +1,29 @@
 import { I18nService } from "@bitwarden/common/platform/abstractions/i18n.service";
-import { ApiSettings, IntegrationRequest, RestClient } from "@bitwarden/common/tools/integration/rpc";
+import {
+  ApiSettings,
+  IntegrationRequest,
+  RestClient,
+} from "@bitwarden/common/tools/integration/rpc";
 import { GenerationRequest } from "@bitwarden/common/tools/types";
 
-import {
-  CredentialGenerator,
-  GeneratedCredential,
-} from "../types";
+import { CredentialGenerator, GeneratedCredential } from "../types";
 
 import { AccountRequest, ForwarderConfiguration } from "./forwarder-configuration";
 import { ForwarderContext } from "./forwarder-context";
 import { CreateForwardingAddressRpc, GetAccountIdRpc } from "./rpc";
 
 /** Generation algorithms that produce randomized email addresses */
-export class Forwarder
-  implements
-    CredentialGenerator<ApiSettings>
-{
+export class Forwarder implements CredentialGenerator<ApiSettings> {
   /** Instantiates the email randomizer
    *  @param random data source for random data
    */
-  constructor(private configuration: ForwarderConfiguration<ApiSettings>, private client: RestClient, private i18nService: I18nService) {}
+  constructor(
+    private configuration: ForwarderConfiguration<ApiSettings>,
+    private client: RestClient,
+    private i18nService: I18nService,
+  ) {}
 
-  async generate(
-    request: GenerationRequest,
-    settings: ApiSettings,
-  ) {
+  async generate(request: GenerationRequest, settings: ApiSettings) {
     const requestOptions: IntegrationRequest & AccountRequest = { website: request.website };
 
     const getAccount = await this.getAccountId(this.configuration, settings);

libs/tools/generator/core/src/types/generator-type.ts

@@ -14,12 +14,18 @@ export type EmailAlgorithm = (typeof EmailAlgorithms)[number];
 export type ForwarderIntegration = { forwarder: IntegrationId };
 
 /** Returns true when the input algorithm is a forwarder integration. */
-export function isForwarderIntegration(algorithm: CredentialAlgorithm) : algorithm is ForwarderIntegration {
-  return (typeof algorithm === "object") && "forwarder" in algorithm;
+export function isForwarderIntegration(
+  algorithm: CredentialAlgorithm,
+): algorithm is ForwarderIntegration {
+  return typeof algorithm === "object" && "forwarder" in algorithm;
 }
 
 /** A type of credential that may be generated by the credential generator. */
-export type CredentialAlgorithm = PasswordAlgorithm | UsernameAlgorithm | EmailAlgorithm | ForwarderIntegration;
+export type CredentialAlgorithm =
+  | PasswordAlgorithm
+  | UsernameAlgorithm
+  | EmailAlgorithm
+  | ForwarderIntegration;
 
 /** Compound credential types supported by the credential generator. */
 export const CredentialCategories = Object.freeze({