@econ-v1/domain 6.7.0 → 6.11.0

package/src/services/onboarding-checkpoint-store.js

@@ -0,0 +1,155 @@
+// @ts-check
+/** @typedef {import('@econ-v1/ports').OnboardingCheckpointStoragePort} OnboardingCheckpointStoragePort */
+export class OnboardingCheckpointStore {
+  /**
+   * @readonly
+   */
+  #now;
+  /**
+   * @readonly
+   */
+  #storage;
+  /**
+   * @param {OnboardingCheckpointStoreOptions} options
+   */
+  constructor(options) {
+    this.#now = options.now;
+    this.#storage = options.storage;
+  }
+  /**
+   * @returns {void}
+   */
+  clear() {
+    this.#storage.clear();
+  }
+  /**
+   * @returns {OnboardingCheckpoint | undefined}
+   */
+  read() {
+    const raw = this.#storage.read();
+    if (raw === undefined) return undefined;
+    /** @type {unknown} */
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      // A slot written by an older build, a half-flushed write, or an unrelated key
+      // collision is not an error worth surfacing — it is simply "no resume point".
+      this.#storage.clear();
+      return undefined;
+    }
+    const checkpoint = toCheckpoint(parsed);
+    if (checkpoint === undefined) {
+      this.#storage.clear();
+      return undefined;
+    }
+    if (
+      checkpoint.deadline !== undefined &&
+      Date.parse(checkpoint.deadline) <= Date.parse(this.#now())
+    ) {
+      this.#storage.clear();
+      return undefined;
+    }
+    return checkpoint;
+  }
+  /**
+   * @param {OnboardingCheckpoint} checkpoint
+   * @returns {void}
+   */
+  write(checkpoint) {
+    this.#storage.write(
+      JSON.stringify({
+        stepId: checkpoint.stepId,
+        ...(checkpoint.deadline === undefined
+          ? {}
+          : { deadline: checkpoint.deadline }),
+        ...(checkpoint.operationHash === undefined
+          ? {}
+          : { operationHash: checkpoint.operationHash }),
+        ...(checkpoint.targetSsid === undefined
+          ? {}
+          : { targetSsid: checkpoint.targetSsid }),
+        ...(checkpoint.wifiOperationId === undefined
+          ? {}
+          : { wifiOperationId: checkpoint.wifiOperationId }),
+      }),
+    );
+  }
+}
+/** The default for compositions with no browser storage (tests, and the pre-existing
+ * `composition-root.test.ts` wiring): a real port whose slot simply dies with the process.
+ * @returns {OnboardingCheckpointStoragePort}
+ */
+export function createInMemoryOnboardingCheckpointStorage() {
+  /** @type {string | undefined} */
+  /** @type {string | undefined} */
+  let slot;
+  return {
+    clear: () => {
+      slot = undefined;
+    },
+    read: () => slot,
+    write: (value) => {
+      slot = value;
+    },
+  };
+}
+/**
+ * @param {unknown} value
+ * @returns {OnboardingCheckpoint | undefined}
+ */
+function toCheckpoint(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    return undefined;
+  const record = /** @type {Record<string, unknown>} */ (value);
+  if (typeof record.stepId !== "string" || record.stepId.length === 0)
+    return undefined;
+  if (!isOptionalString(record.deadline)) return undefined;
+  if (!isOptionalString(record.operationHash)) return undefined;
+  if (!isOptionalString(record.targetSsid)) return undefined;
+  if (!isOptionalString(record.wifiOperationId)) return undefined;
+  return {
+    stepId: record.stepId,
+    ...(record.deadline === undefined ? {} : { deadline: record.deadline }),
+    ...(record.operationHash === undefined
+      ? {}
+      : { operationHash: record.operationHash }),
+    ...(record.targetSsid === undefined
+      ? {}
+      : { targetSsid: record.targetSsid }),
+    ...(record.wifiOperationId === undefined
+      ? {}
+      : { wifiOperationId: record.wifiOperationId }),
+  };
+}
+/**
+ * @param {unknown} value
+ * @returns {value is string | undefined}
+ */
+function isOptionalString(value) {
+  return value === undefined || typeof value === "string";
+}
+/**
+ * The onboarding flow's resume point (design §6.3).
+ *
+ * SECURITY — this type is the whole reason the store exists rather than a bare
+ * `JSON.stringify(state)`: it names EXACTLY the fields the step table's `resume` column
+ * allows, and `write()` copies field-by-field from this allow-list. A caller cannot smuggle a
+ * Wi-Fi password (or an invitation code, or the match-code digits) into durable storage by
+ * spreading extra properties into the argument — the extras are dropped before serialisation.
+ * If a Wi-Fi operation must be retried after a reload the owner re-enters the password; the
+ * step is re-shown, never replayed.
+ * @typedef {object} OnboardingCheckpoint
+ * @property {string} [deadline] ISO instant after which the in-flight operation is dead. A checkpoint past its own
+ * deadline is discarded on read so a stale run cannot strand a later one mid-flow.
+ * @property {string} [operationHash]
+ * @property {string} stepId
+ * @property {string} [targetSsid]
+ * @property {string} [wifiOperationId]
+ */
+/**
+ * @typedef {object} OnboardingCheckpointStoreOptions
+ * @property {() => string} now
+ * @property {OnboardingCheckpointStoragePort} storage
+ */
+// @ts-check