@kestack/web-platform 0.0.0-stage → 0.0.1

package/src/app/gate/domain/check.ts

@@ -0,0 +1,76 @@
+import { Effect, Schema } from 'effect';
+import { SignIn } from '@kestack/auth-toolkit/client';
+import { Device } from './services.ts';
+import type { Held, User } from './types.ts';
+
+/** The Backend could not be reached, and nobody was open here before to
+ * open without it. */
+export class Unreachable extends Schema.Error<Unreachable>(
+  '@kestack/auth-toolkit/gate/Unreachable',
+)({ _tag: Schema.tag('Unreachable') }) {}
+
+/** Who is signed in, and whose Session to open. */
+export type Checked = {
+  readonly accounts: ReadonlyArray<Held>;
+  /** Null with nobody to open, or while an account is lost. */
+  readonly chosen: Held | null;
+  /** The account found lost, still waiting for the User. */
+  readonly lost: User | null;
+  /** Whether the Backend answered; when it did not, everything is as the
+   * device remembers it. */
+  readonly answered: boolean;
+};
+
+const activeOf = (accounts: ReadonlyArray<Held>) =>
+  accounts.find(({ active }) => active) ?? accounts[0] ?? null;
+
+/**
+ * Asks the Backend who is signed in, remembers it, and chooses the Active
+ * Account. `open` is the account open now: if the Backend no longer names
+ * it, and this device did not sign it out, it is lost, and stays lost until
+ * the User signs in to it again or someone new signs in. What the device
+ * keeps for anyone else is deleted. When the Backend can't be reached, the
+ * Remembered Accounts stand in for its answer.
+ */
+export const check = (
+  open: User | null,
+): Effect.Effect<Checked, Unreachable, SignIn | Device> =>
+  Effect.gen(function* () {
+    const signIn = yield* SignIn;
+    const device = yield* Device;
+    const remembered = yield* device.remembered;
+    const listed = yield* Effect.result(signIn.list);
+    if (listed._tag === 'Failure') {
+      const chosen =
+        remembered.lost === null ? activeOf(remembered.accounts) : null;
+      if (remembered.lost === null && chosen === null)
+        return yield* new Unreachable();
+      return { ...remembered, chosen, answered: false };
+    }
+    const accounts: ReadonlyArray<Held> = listed.success;
+    const named = (id: string) => accounts.some(({ user }) => user.id === id);
+    const someoneNew = accounts.some(
+      ({ user }) => !remembered.accounts.some((was) => was.user.id === user.id),
+    );
+    const lost =
+      remembered.lost !== null
+        ? named(remembered.lost.id) || someoneNew
+          ? null
+          : remembered.lost
+        : open !== null &&
+            !named(open.id) &&
+            !(yield* device.signedOutHere(open.id))
+          ? open
+          : null;
+    yield* device.remember({ accounts, lost });
+    yield* device.keep([
+      ...accounts.map(({ user }) => user.id),
+      ...(lost === null ? [] : [lost.id]),
+    ]);
+    return {
+      accounts,
+      chosen: lost === null ? activeOf(accounts) : null,
+      lost,
+      answered: true,
+    };
+  });

package/src/app/gate/domain/index.ts

@@ -0,0 +1,3 @@
+export { gateMachine } from './machine.ts';
+export { Device, Sessions, Switching } from './services.ts';
+export type { GateNotice, GateView, Held, User } from './types.ts';

package/src/app/gate/domain/machine.ts

@@ -0,0 +1,439 @@
+import { Effect, Schema, Stream } from 'effect';
+import { fromEffect, fromEffectEventStream, setupEffect } from '@xstate/effect';
+import { SignIn } from '@kestack/auth-toolkit/client';
+import { type Checked, check } from './check.ts';
+import { Device, type Remembered, Sessions, Switching } from './services.ts';
+import type { Held, User } from './types.ts';
+
+/** Everything the Gate knows about who is signed in, and the open Session. */
+export type GateContext = {
+  /** Every Signed-in Account on this device. */
+  readonly accounts: ReadonlyArray<Held>;
+  /** Whose Session is open, or opening. */
+  readonly account: Held | null;
+  /** What the open Session gave, from when it is ready until it
+   * ends. */
+  readonly session: unknown;
+  /** Whether the last check failed with nobody to open without it. */
+  readonly unreachable: boolean;
+  /** Whether the browser-wide Account Switch to `account` is still owed. */
+  readonly pending: boolean;
+  /** Whether `accounts` were just checked, so the open needs no check. */
+  readonly fresh: boolean;
+  /** How many times in a row `account` failed to open. */
+  readonly failures: number;
+  /** The account found lost, until the User signs in to it again or opens
+   * another. */
+  readonly lost: User | null;
+};
+
+// The context holds a live Session, so it is typed, not parsed.
+const GateContextSchema = Schema.declare(
+  (value: unknown): value is GateContext =>
+    typeof value === 'object' && value !== null && 'accounts' in value,
+);
+
+const events = {
+  /** The app or the network came back, or another tab changed something:
+   * ask who is signed in. */
+  CHECK: Schema.Struct({}),
+  /** An Account Switch to another Signed-in Account. */
+  SWITCH: Schema.Struct({ userId: Schema.String }),
+  /** Sign the Active Account out of this device. */
+  SIGN_OUT: Schema.Struct({}),
+  /** Sign every account out of this device. */
+  SIGN_OUT_EVERYONE: Schema.Struct({}),
+  /** Try again to open an account that would not open. */
+  RETRY: Schema.Struct({}),
+  /** The invoked Session is open. */
+  SESSION_OPENED: Schema.Struct({ session: Schema.Unknown }),
+};
+
+// Holds one account's Session while the machine stays in the state
+// that invokes it: opened on entry, announced with SESSION_OPENED, ended on
+// exit.
+const session = fromEffectEventStream(({ input }: { input: Held }) =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const opened = yield* (yield* Sessions).open(input);
+      return Stream.concat(
+        Stream.make({ type: 'SESSION_OPENED' as const, session: opened }),
+        Stream.never,
+      );
+    }),
+  ),
+);
+
+const remembered = fromEffect(() =>
+  Effect.gen(function* () {
+    return yield* (yield* Device).remembered;
+  }),
+);
+
+// Asks who is signed in, nobody being open.
+const checking = fromEffect(() => check(null));
+
+type Verify = {
+  readonly account: Held;
+  readonly pending: boolean;
+  readonly fresh: boolean;
+};
+
+// The token of a Remembered Account, which holds none until the Backend
+// answers: asked of the Backend, null once it no longer names the account.
+const tokenOf = (account: Held) =>
+  Effect.gen(function* () {
+    if (account.token !== null) return account.token;
+    const accounts = yield* (yield* SignIn).list;
+    return (
+      accounts.find(({ user }) => user.id === account.user.id)?.token ?? null
+    );
+  });
+
+// Confirms the open account behind the screen: first the Account Switch
+// still owed, then who is signed in. Null when the accounts were just
+// checked, or when the switch is still owed and the Backend is out of
+// reach, so no answer from before the switch can undo it.
+const verifying = fromEffect(({ input }: { input: Verify }) =>
+  Effect.gen(function* () {
+    if (input.fresh) return null;
+    if (input.pending) {
+      const token = yield* Effect.result(tokenOf(input.account));
+      if (token._tag === 'Failure') return null;
+      if (token.success !== null) {
+        const switching = yield* Switching;
+        yield* switching.switchTo(token.success);
+        yield* switching.announce();
+      }
+    }
+    return yield* check(input.account.user);
+  }),
+);
+
+// Forgets the lost account, so the check after it deletes its Copy, and
+// tells the other tabs it is no Account Lost there.
+const forgetting = fromEffect(({ input }: { input: User }) =>
+  Effect.gen(function* () {
+    const device = yield* Device;
+    const remembered = yield* device.remembered;
+    yield* device.remember({ ...remembered, lost: null });
+    yield* (yield* Switching).announce([input.id]);
+  }),
+);
+
+type SignOut = {
+  readonly account: Held | null;
+  readonly quiet: ReadonlyArray<string>;
+};
+
+// Signs one account out, or every account given none; an account still
+// only remembered is signed out by the token the Backend names it with. The
+// check after it deletes what the device kept for them and opens whoever is
+// left.
+const signingOut = fromEffect(({ input }: { input: SignOut }) =>
+  Effect.gen(function* () {
+    const signIn = yield* SignIn;
+    if (input.account === null) yield* signIn.signOutAll;
+    else {
+      const token = yield* tokenOf(input.account);
+      if (token !== null) yield* signIn.signOut(token);
+    }
+    yield* (yield* Switching).announce(input.quiet);
+  }),
+);
+
+// How often an open account is confirmed, besides when asked.
+const RECHECK = 60_000;
+
+/** What a check means for the machine, from wherever it ran. */
+const settle = (checked: Checked, context: GateContext) => {
+  const current = context.account;
+  const { accounts, chosen, lost } = checked;
+  const base = {
+    ...context,
+    accounts,
+    session: null,
+    unreachable: false,
+    pending: false,
+    failures: 0,
+    lost,
+  };
+  if (lost !== null) {
+    return {
+      target: '#gate.accountLost',
+      context: { ...base, account: null, fresh: false },
+    };
+  }
+  if (chosen === null) {
+    return {
+      target: '#gate.signedOut',
+      context: { ...base, account: null, fresh: false },
+    };
+  }
+  if (current !== null && chosen.user.id === current.user.id) return null;
+  return {
+    target: '#gate.open',
+    reenter: true,
+    context: { ...base, account: chosen, fresh: true },
+  };
+};
+
+// Leaving the open account: another account, or nobody.
+type Leave = { readonly context: GateContext };
+
+const leaving = {
+  SWITCH: ({
+    context,
+    event,
+  }: Leave & { readonly event: { readonly userId: string } }) => {
+    const to = context.accounts.find(({ user }) => user.id === event.userId);
+    if (to === undefined || to.user.id === context.account?.user.id) return;
+    return {
+      target: '#gate.open',
+      reenter: true,
+      context: {
+        ...context,
+        account: to,
+        session: null,
+        pending: true,
+        fresh: false,
+        failures: 0,
+      },
+    };
+  },
+  SIGN_OUT: ({ context }: Leave) => ({
+    target: '#gate.signingOut',
+    context: { ...context, session: null },
+  }),
+  SIGN_OUT_EVERYONE: ({ context }: Leave) => ({
+    target: '#gate.signingOut',
+    context: { ...context, account: null, session: null },
+  }),
+};
+
+const initialContext = (): GateContext => ({
+  accounts: [],
+  account: null,
+  session: null,
+  unreachable: false,
+  pending: false,
+  fresh: false,
+  failures: 0,
+  lost: null,
+});
+
+/**
+ * The Gate's lifecycle on one Backend. An account the device remembers opens
+ * first and is confirmed behind it (Open First); with nobody remembered it
+ * finds who is signed in. It holds the Active Account's Session
+ * open until an Account Switch, a sign-out, or the account turning out to
+ * be signed out (Account Lost). Leaving `open` ends the Session, so
+ * nothing of one account outlives its state.
+ */
+export const gateMachine = setupEffect({
+  schemas: { context: GateContextSchema, events },
+  actors: {
+    session,
+    remembered,
+    checking,
+    verifying,
+    signingOut,
+    forgetting,
+  },
+}).createMachine({
+  id: 'gate',
+  context: initialContext,
+  initial: 'starting',
+  states: {
+    starting: {
+      invoke: {
+        src: 'remembered',
+        onDone: ({ context, event }) => {
+          const { accounts, lost } = event.output as Remembered;
+          if (lost !== null)
+            return {
+              target: 'accountLost',
+              context: { ...context, accounts, lost },
+            };
+          const account =
+            accounts.find(({ active }) => active) ?? accounts[0] ?? null;
+          if (account === null) return { target: 'checking' };
+          return { target: 'open', context: { ...context, accounts, account } };
+        },
+        onError: { target: 'checking' },
+      },
+    },
+    checking: {
+      invoke: {
+        src: 'checking',
+        onDone: ({ context, event }) =>
+          settle(event.output as Checked, context) ?? undefined,
+        onError: ({ context }) => ({
+          target: 'signedOut',
+          context: { ...context, unreachable: true },
+        }),
+      },
+    },
+    signedOut: {
+      on: { CHECK: { target: 'checking' } },
+    },
+    signingOut: {
+      invoke: {
+        src: 'signingOut',
+        input: ({ context }): SignOut =>
+          context.account === null
+            ? {
+                account: null,
+                quiet: context.accounts.map(({ user }) => user.id),
+              }
+            : {
+                account: context.account,
+                quiet: [context.account.user.id],
+              },
+        onDone: ({ context }) => ({
+          target: 'checking',
+          context: { ...context, account: null },
+        }),
+        onError: { target: 'checking' },
+      },
+    },
+    accountLost: {
+      initial: 'verifying',
+      on: {
+        SWITCH: ({ context, event }) => {
+          const to = context.accounts.find(
+            ({ user }) => user.id === event.userId,
+          );
+          if (to === undefined) return;
+          return {
+            target: 'forgetting',
+            context: { ...context, account: to, pending: true, fresh: false },
+          };
+        },
+        // Nobody is left to switch to: forget the lost account.
+        SIGN_OUT: ({ context }) => ({
+          target: 'forgetting',
+          context: { ...context, account: null },
+        }),
+      },
+      states: {
+        idle: { on: { CHECK: { target: 'verifying' } } },
+        // Whether the User signed in to the lost account again, or someone
+        // new signed in.
+        verifying: {
+          invoke: {
+            src: 'checking',
+            onDone: ({ context, event }) => {
+              const checked = event.output as Checked;
+              if (checked.lost !== null)
+                return {
+                  target: 'idle',
+                  context: { ...context, accounts: checked.accounts },
+                };
+              return settle(checked, context) ?? { target: 'idle' };
+            },
+            onError: { target: 'idle' },
+          },
+        },
+      },
+    },
+    forgetting: {
+      invoke: {
+        src: 'forgetting',
+        input: ({ context }) => context.lost as User,
+        onDone: ({ context }) => ({
+          target: context.account === null ? 'checking' : 'open',
+          context: { ...context, lost: null },
+        }),
+        onError: ({ context }) => ({
+          target: context.account === null ? 'checking' : 'open',
+          context: { ...context, lost: null },
+        }),
+      },
+    },
+    unopenable: {
+      on: {
+        RETRY: ({ context }) => ({
+          target: 'open',
+          context: { ...context, failures: 0 },
+        }),
+        SIGN_OUT: { target: 'signingOut' },
+      },
+    },
+    open: {
+      invoke: {
+        src: 'session',
+        input: ({ context }) => context.account as Held,
+        onError: ({ context }) =>
+          context.failures + 1 >= 2
+            ? {
+                target: 'unopenable',
+                context: { ...context, session: null, failures: 0 },
+              }
+            : {
+                target: '#gate.open',
+                reenter: true,
+                context: {
+                  ...context,
+                  session: null,
+                  failures: context.failures + 1,
+                },
+              },
+      },
+      on: leaving,
+      initial: 'opening',
+      states: {
+        opening: {
+          on: {
+            SESSION_OPENED: ({ context, event }) => ({
+              target: 'ready',
+              context: { ...context, session: event.session },
+            }),
+          },
+        },
+        ready: {
+          initial: 'verifying',
+          states: {
+            idle: {
+              after: { [RECHECK]: { target: 'verifying' } },
+              on: { CHECK: { target: 'verifying' } },
+            },
+            verifying: {
+              invoke: {
+                src: 'verifying',
+                input: ({ context }): Verify => ({
+                  account: context.account as Held,
+                  pending: context.pending,
+                  fresh: context.fresh,
+                }),
+                onDone: ({ context, event }) => {
+                  const checked = event.output as Checked | null;
+                  // Just checked, or the Backend was not reached: nothing
+                  // new.
+                  if (checked === null || !checked.answered)
+                    return {
+                      target: 'idle',
+                      context: { ...context, fresh: false },
+                    };
+                  const moved = settle(checked, context);
+                  if (moved !== null) return moved;
+                  return {
+                    target: 'idle',
+                    context: {
+                      ...context,
+                      fresh: false,
+                      pending: false,
+                      accounts: checked.accounts,
+                      account: checked.chosen,
+                    },
+                  };
+                },
+                onError: { target: 'idle' },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+});

package/src/app/gate/domain/services.ts

@@ -0,0 +1,46 @@
+import { Context, type Effect, type Scope } from 'effect';
+import type { Held, User } from './types.ts';
+
+/** What the device remembers about one Backend: its Remembered Accounts,
+ * with no tokens, and the account found lost, if one is. */
+export type Remembered = {
+  readonly accounts: ReadonlyArray<Held>;
+  readonly lost: User | null;
+};
+
+/** What this device keeps for one Backend. */
+export class Device extends Context.Service<
+  Device,
+  {
+    readonly remembered: Effect.Effect<Remembered>;
+    readonly remember: (remembered: Remembered) => Effect.Effect<void>;
+    /** Whether this device signed `userId` out itself, in this tab or
+     * another; asking forgets it. */
+    readonly signedOutHere: (userId: string) => Effect.Effect<boolean>;
+    /** Keeps what the device holds for these accounts and deletes the
+     * rest. */
+    readonly keep: (userIds: ReadonlyArray<string>) => Effect.Effect<void>;
+  }
+>()('@kestack/auth-toolkit/gate/Device') {}
+
+/** Opens Sessions; each ends with its scope. */
+export class Sessions extends Context.Service<
+  Sessions,
+  {
+    readonly open: (
+      account: Held,
+    ) => Effect.Effect<unknown, never, Scope.Scope>;
+  }
+>()('@kestack/auth-toolkit/gate/Sessions') {}
+
+/** The browser-wide Account Switch, one at a time, the last one asked for
+ * winning; and telling the device's other tabs what changed. */
+export class Switching extends Context.Service<
+  Switching,
+  {
+    readonly switchTo: (token: string) => Effect.Effect<void, unknown>;
+    /** Tells the other tabs to look again; `quiet` are accounts this tab
+     * signed out, so they are not reported lost there. */
+    readonly announce: (quiet?: ReadonlyArray<string>) => Effect.Effect<void>;
+  }
+>()('@kestack/auth-toolkit/gate/Switching') {}

package/src/app/gate/domain/types.ts

@@ -0,0 +1,36 @@
+import type { Account, LoginError, User } from '@kestack/auth-toolkit/client';
+
+/** An Account as the Gate holds it, marked active or not. Its token is null
+ * while it is only remembered, as when it opened before the Backend
+ * answered. */
+export type Held = Account & { readonly active: boolean };
+
+/** What every screen asks the Gate. */
+export type GateView<S> =
+  | { readonly kind: 'checking' }
+  | { readonly kind: 'signedOut'; readonly unreachable: boolean }
+  | { readonly kind: 'opening'; readonly account: Account }
+  | { readonly kind: 'signingOut' }
+  | {
+      readonly kind: 'open';
+      readonly session: S;
+      readonly account: Account;
+      readonly accounts: ReadonlyArray<Account>;
+    }
+  | { readonly kind: 'unopenable'; readonly account: Account }
+  /** The account that was open is signed out on another device or app. The
+   * User signs in to it again, keeping its Sync, or opens another account,
+   * deleting it; `accounts` are those still signed in. */
+  | {
+      readonly kind: 'accountLost';
+      readonly account: Account;
+      readonly accounts: ReadonlyArray<Account>;
+    };
+
+/** A message the Gate leaves for the app once. */
+export type GateNotice = {
+  readonly kind: 'loginError';
+  readonly error: LoginError;
+};
+
+export type { User };