@econ-v1/domain 6.7.0 → 6.10.0

package/src/services/abort-signal.js

@@ -0,0 +1,69 @@
+// @ts-check
+
+/**
+ * @typedef {{
+ *   readonly capture?: boolean;
+ * }} AbortEventListenerOptions
+ */
+
+/**
+ * @typedef {AbortEventListenerOptions & {
+ *   readonly once?: boolean;
+ *   readonly passive?: boolean;
+ *   readonly signal?: AbortSignalPort;
+ * }} AbortAddEventListenerOptions
+ */
+
+/**
+ * @typedef {{
+ *   readonly bubbles: boolean;
+ *   cancelBubble: boolean;
+ *   readonly cancelable: boolean;
+ *   readonly composed: boolean;
+ *   readonly currentTarget: AbortEventTarget | null;
+ *   readonly defaultPrevented: boolean;
+ *   readonly eventPhase: number;
+ *   readonly isTrusted: boolean;
+ *   returnValue: boolean;
+ *   readonly srcElement: AbortEventTarget | null;
+ *   readonly target: AbortEventTarget | null;
+ *   readonly timeStamp: number;
+ *   readonly type: string;
+ *   composedPath(): AbortEventTarget[];
+ *   initEvent(type: string, bubbles?: boolean, cancelable?: boolean): void;
+ *   preventDefault(): void;
+ *   stopImmediatePropagation(): void;
+ *   stopPropagation(): void;
+ *   readonly NONE: 0;
+ *   readonly CAPTURING_PHASE: 1;
+ *   readonly AT_TARGET: 2;
+ *   readonly BUBBLING_PHASE: 3;
+ * }} AbortEvent
+ */
+
+/** @typedef {(event: AbortEvent) => void} AbortEventListener */
+/** @typedef {{ handleEvent(event: AbortEvent): void }} AbortEventListenerObject */
+
+/**
+ * @typedef {{
+ *   addEventListener(type: string, listener: AbortEventListener | AbortEventListenerObject | null, options?: boolean | AbortAddEventListenerOptions): void;
+ *   dispatchEvent(event: AbortEvent): boolean;
+ *   removeEventListener(type: string, listener: AbortEventListener | AbortEventListenerObject | null, options?: boolean | AbortEventListenerOptions): void;
+ * }} AbortEventTarget
+ */
+
+/**
+ * Platform-neutral structural equivalent of a native AbortSignal instance.
+ *
+ * This internal contract preserves the native AbortSignal surface without
+ * expanding the public ports package.
+ *
+ * @typedef {AbortEventTarget & {
+ *   readonly aborted: boolean;
+ *   onabort: ((this: AbortSignalPort, event: AbortEvent) => unknown) | null;
+ *   readonly reason: unknown;
+ *   throwIfAborted(): void;
+ * }} AbortSignalPort
+ */
+
+export {};

package/src/services/certificate-trust-service.js

@@ -0,0 +1,119 @@
+// @ts-check
+/** @typedef {import('@econ-v1/ports').CertificateTrustPlatform} CertificateTrustPlatform */
+/** @typedef {import('@econ-v1/ports').CertificateTrustProbePort} CertificateTrustProbePort */
+export class CertificateTrustService {
+  /** @readonly @type {string} */
+  #origin;
+  /** @readonly @type {CertificateTrustPlatform} */
+  #platform;
+  /** @readonly @type {CertificateTrustProbePort} */
+  #probe;
+  /** @readonly @type {(snapshot: CertificateTrustSnapshot) => void} */
+  #onChange;
+  /** @type {CertificateTrustSnapshot} */
+  #snapshot;
+  /**
+   * @param {CertificateTrustServiceOptions} options
+   */
+  constructor(options) {
+    this.#origin = options.origin;
+    this.#platform = options.platform;
+    this.#probe = options.probe;
+    this.#onChange = options.onChange ?? (() => undefined);
+    this.#snapshot = {
+      status: "unknown",
+      origin: options.origin,
+      platform: options.platform,
+    };
+  }
+  /**
+   * @returns {CertificateTrustSnapshot}
+   */
+  status() {
+    return this.#snapshot;
+  }
+  /**
+   * @returns {CertificateTrustSnapshot}
+   */
+  restartInstall() {
+    return this.#set({ status: "installing", lastError: undefined });
+  }
+  /**
+   * @returns {CertificateTrustSnapshot}
+   */
+  skip() {
+    return this.#set({ status: "skipped", lastError: undefined });
+  }
+  /**
+   * @returns {Promise<CertificateTrustSnapshot>}
+   */
+  async verify() {
+    try {
+      const result = await this.#probe.probe(this.#origin);
+      // Only an answering node reports a fingerprint; an unreachable one has
+      // nothing to report and must not clear a previously observed value.
+      const fingerprint =
+        result.status === "unreachable" ? undefined : result.fingerprint;
+      this.#snapshot = {
+        ...this.#snapshot,
+        ...(fingerprint === undefined ? {} : { fingerprint }),
+      };
+      if (result.status === "trusted") {
+        return this.#set({ status: "verified", lastError: undefined });
+      }
+      // A node that never answered has not refused anything. Reporting "does not
+      // trust the CA yet" here would tell someone to go re-install a certificate
+      // when the real problem is that nothing is listening — the same unmet
+      // prerequisite reported as the wrong one.
+      if (result.status === "unreachable") {
+        return this.#set({
+          status: "unavailable",
+          lastError: "The node could not be reached over HTTPS.",
+        });
+      }
+      return this.#set({
+        status: "failed",
+        lastError: "The device does not trust the node CA yet.",
+      });
+    } catch {
+      return this.#set({
+        status: "unavailable",
+        lastError: "The node could not be reached over HTTPS.",
+      });
+    }
+  }
+  /**
+   * @param {{ readonly status: CertificateTrustStatus; readonly lastError?: string | undefined }} next
+   * @returns {CertificateTrustSnapshot}
+   */
+  #set(next) {
+    this.#snapshot = {
+      origin: this.#origin,
+      platform: this.#platform,
+      status: next.status,
+      ...(this.#snapshot.fingerprint === undefined
+        ? {}
+        : { fingerprint: this.#snapshot.fingerprint }),
+      ...(next.lastError === undefined ? {} : { lastError: next.lastError }),
+    };
+    this.#onChange(this.#snapshot);
+    return this.#snapshot;
+  }
+}
+/** @typedef {"unknown" | "installing" | "verified" | "failed" | "skipped" | "unavailable"} CertificateTrustStatus */
+/**
+ * @typedef {object} CertificateTrustSnapshot
+ * @property {CertificateTrustStatus} status
+ * @property {string} origin
+ * @property {CertificateTrustPlatform} platform
+ * @property {string} [fingerprint]
+ * @property {string} [lastError]
+ */
+/**
+ * @typedef {object} CertificateTrustServiceOptions
+ * @property {string} origin
+ * @property {CertificateTrustPlatform} platform
+ * @property {CertificateTrustProbePort} probe
+ * @property {(snapshot: CertificateTrustSnapshot) => void} [onChange]
+ */
+// @ts-check

package/{dist → src}/services/conversation-service.js

@@ -1,9 +1,77 @@
+// @ts-check
+
+/**
+ * @typedef {import("@econ-v1/ports").Conversation} Conversation
+ */
+/**
+ * @typedef {import("@econ-v1/ports").ConversationListParams} ConversationListParams
+ */
+/**
+ * @typedef {import("@econ-v1/ports").ConversationLogDelta} ConversationLogDelta
+ */
+/**
+ * @typedef {import("@econ-v1/ports").ConversationMessage} ConversationMessage
+ */
+/**
+ * @typedef {import("@econ-v1/ports").ConversationRepository} ConversationRepository
+ */
+/**
+ * @typedef {import("@econ-v1/ports").Notification} Notification
+ */
+/**
+ * @typedef {import("@econ-v1/ports").NotificationListParams} NotificationListParams
+ */
+/**
+ * @typedef {import("@econ-v1/ports").NotificationRepository} NotificationRepository
+ */
+/**
+ * @typedef {import("@econ-v1/ports").OutboxRecord} OutboxRecord
+ */
+/**
+ * @typedef {import("@econ-v1/ports").OutboxRepository} OutboxRepository
+ */
+/**
+ * @typedef {import("@econ-v1/ports").RepositoryEvent} RepositoryEvent
+ */
+/**
+ * @typedef {{ readonly body: string; readonly conversationId: string; readonly idempotencyKey: string; readonly messageId?: string; readonly senderId: string; }} SendMessageInput
+ */
+/**
+ * @typedef {{ readonly id: () => string; readonly now?: () => string; }} ConversationServiceOptions
+ */
+/**
+ * @typedef {RepositoryEvent} ConversationRepositoryWrite
+ */
 export class ConversationService {
+    /**
+   * @readonly
+   * @type {ConversationRepository}
+   */
     #conversations;
+    /**
+   * @readonly
+   * @type {() => string}
+   */
     #id;
+    /**
+   * @readonly
+   * @type {NotificationRepository}
+   */
     #notifications;
+    /**
+   * @readonly
+   * @type {() => string}
+   */
     #now;
+    /**
+   * @readonly
+   * @type {OutboxRepository}
+   */
     #outbox;
+    /**
+   * @param {{ readonly conversations: ConversationRepository; readonly notifications: NotificationRepository; readonly outbox: OutboxRepository; }} dependencies
+   * @param {ConversationServiceOptions} options
+   */
     constructor(dependencies, options) {
         this.#conversations = dependencies.conversations;
         this.#id = options.id;
@@ -11,12 +79,17 @@ export class ConversationService {
         this.#now = options.now ?? (() => new Date().toISOString());
         this.#outbox = dependencies.outbox;
     }
+    /**
+   * @param {SendMessageInput} input
+   * @returns {Promise<ConversationMessage>}
+   */
     async sendMessage(input) {
         requireText(input.body, "message body");
         requireText(input.conversationId, "conversation id");
         requireText(input.idempotencyKey, "message idempotency key");
         requireText(input.senderId, "message sender id");
         const createdAt = this.#now();
+        /** @type {ConversationMessage} */
         const message = {
             body: input.body,
             ...(input.messageId === undefined ? {} : { clientMessageId: input.messageId }),
@@ -27,6 +100,7 @@ export class ConversationService {
             state: "pending",
         };
         await this.#conversations.appendPendingMessage({ message }).commit();
+        /** @type {OutboxRecord} */
         const outbox = {
             createdAt,
             domain: "conversation",
@@ -45,6 +119,10 @@ export class ConversationService {
         await this.#outbox.create(outbox);
         return message;
     }
+    /**
+   * @param {ConversationLogDelta} delta
+   * @returns {Promise<void>}
+   */
     async applyDelta(delta) {
         switch (delta.kind) {
             case "notification.read":
@@ -59,6 +137,10 @@ export class ConversationService {
                 return;
         }
     }
+    /**
+   * @param {{ readonly acknowledgedAt?: string; readonly messageId: string; readonly serverMessageId?: string; }} input
+   * @returns {Promise<void>}
+   */
     async acknowledgeMessage(input) {
         await this.#conversations.acknowledgeMessage({
             acknowledgedAt: input.acknowledgedAt ?? this.#now(),
@@ -66,6 +148,10 @@ export class ConversationService {
             ...(input.serverMessageId === undefined ? {} : { serverMessageId: input.serverMessageId }),
         });
     }
+    /**
+   * @param {{ readonly messageId: string; readonly reason: string; readonly failedAt?: string }} input
+   * @returns {Promise<void>}
+   */
     async failMessage(input) {
         requireText(input.reason, "message failure reason");
         await this.#conversations.failMessage({
@@ -74,22 +160,43 @@ export class ConversationService {
             reason: input.reason,
         });
     }
+    /**
+   * @param {ConversationListParams} [params]
+   * @returns {Promise<readonly Conversation[]>}
+   */
     async listConversations(params) {
         return await this.#conversations.listConversations(params);
     }
+    /**
+   * @param {string} conversationId
+   * @param {{ readonly before?: string; readonly limit?: number }} [params]
+   * @returns {Promise<readonly ConversationMessage[]>}
+   */
     async listMessages(conversationId, params) {
         return await this.#conversations.listMessages(conversationId, params);
     }
+    /**
+   * @param {NotificationListParams} [params]
+   * @returns {Promise<readonly Notification[]>}
+   */
     async listNotifications(params) {
         return await this.#notifications.listNotifications(params);
     }
+    /**
+   * @param {string} notificationId
+   * @returns {Promise<void>}
+   */
     async markNotificationRead(notificationId, readAt = this.#now()) {
         requireText(notificationId, "notification id");
         await this.#notifications.markRead({ notificationId, readAt }).commit();
     }
 }
+/**
+ * @param {string} value
+ * @param {string} label
+ * @returns {void}
+ */
 function requireText(value, label) {
     if (value.trim() === "")
         throw new TypeError(`${label} must be a non-empty string`);
 }
-//# sourceMappingURL=conversation-service.js.map

package/src/services/conversation-sync.js

@@ -0,0 +1,28 @@
+// @ts-check
+
+/**
+ * @typedef {import("../models/conversation.js").ConversationLogDelta} ConversationLogDelta
+ */
+/**
+ * @typedef {import("../models/sync.js").SyncDeltaContext} SyncDeltaContext
+ */
+/**
+ * @typedef {import("./conversation-service.js").ConversationService} ConversationService
+ */
+/**
+ * @typedef {SyncDeltaContext} ConversationSyncContext
+ */
+import { LogSync } from "./sync/log-sync.js";
+/**
+ * @param {Pick<ConversationService, "applyDelta">} service
+ * @returns {LogSync<ConversationLogDelta>}
+ */
+export function createConversationLogSync(service) {
+    return new LogSync({
+        apply: /**
+     * @param {ConversationLogDelta} payload
+     */ async (payload) => {
+            await service.applyDelta(payload);
+        },
+    });
+}

package/src/services/device-boot-state-service.js

@@ -0,0 +1,45 @@
+// @ts-check
+/** @import { IdentityPort } from "@econ-v1/ports" */
+/** @import { DeviceBootState } from "../models/device-boot-state.js" */
+/**  @typedef {{ readonly identity: Pick<IdentityPort, "loadDelegation" | "loadLifecycle">; readonly now: () => string; }} DeviceBootStateServiceOptions */
+export class DeviceBootStateService {
+    /** @type {DeviceBootStateServiceOptions["identity"]} */
+    #identity;
+    /** @type {() => string} */
+    #now;
+    /** @param {DeviceBootStateServiceOptions} options */
+    constructor(options) {
+        this.#identity = options.identity;
+        this.#now = options.now;
+    }
+    /** @returns {Promise<DeviceBootState>} */
+    async state() {
+        /** @type {"active" | "revoked" | undefined} */
+        let lifecycle;
+        try {
+            lifecycle = await this.#identity.loadLifecycle?.();
+        }
+        catch {
+            // A store we cannot read must fail toward pairing, never toward a crash or
+            // toward rendering cached data on an unverified device (spec §5).
+            return { kind: "unpaired" };
+        }
+        if (lifecycle === "revoked")
+            return { kind: "revoked" };
+        /** @type {Awaited<ReturnType<IdentityPort["loadDelegation"]>>} */
+        let delegation;
+        try {
+            delegation = await this.#identity.loadDelegation();
+        }
+        catch {
+            return { kind: "unpaired" };
+        }
+        if (delegation === undefined)
+            return { kind: "unpaired" };
+        const expiresAtMs = Date.parse(delegation.expiresAt);
+        const expired = Number.isNaN(expiresAtMs) || expiresAtMs <= Date.parse(this.#now());
+        return expired
+            ? { kind: "paired-expired", delegationExpiresAt: delegation.expiresAt }
+            : { kind: "paired", delegationExpiresAt: delegation.expiresAt };
+    }
+}

package/src/services/device-cleanup-service.js

@@ -0,0 +1,112 @@
+// @ts-check
+/** @typedef {import("@econ-v1/ports").DelayPort} DelayPort */
+/** @typedef {"pending" | "approved" | "declined" | "expired" | "no_candidate" | "not_needed" | "failed"} DeviceCleanupState */
+/** @typedef {{ cleanupStatus: (sessionId: string) => Promise<{ readonly state: DeviceCleanupState }>; requestCleanup: () => Promise<{ readonly sessionId: string; readonly state: DeviceCleanupState }> }} DeviceCleanupPort */
+/** @typedef {{ cleanup: DeviceCleanupPort; delay: Pick<DelayPort, "wait">; publish: (state: DeviceCleanupState | undefined) => void }} DeviceCleanupServiceOptions */
+const POLL_BASE_DELAY_MS = 2_000;
+const POLL_MAX_DELAY_MS = 30_000;
+/** Unchanged from the shell's original `cleanupPollDelayMs`: 2s -> 4s -> 8s -> 16s -> 30s
+ * ceiling. The owner may take anywhere from seconds to minutes to walk to the node's screen,
+ * and the pending-op TTL server-side is 5 minutes, so polling every couple of seconds the
+ * whole time would just be noise. */
+/** @param {number} attempt */
+function pollDelayMs(attempt) {
+    return Math.min(POLL_BASE_DELAY_MS * (2 ** attempt), POLL_MAX_DELAY_MS);
+}
+export class DeviceCleanupService {
+    /** @type {DeviceCleanupPort} */
+    #cleanup;
+    /** @type {Pick<DelayPort, "wait">} */
+    #delay;
+    /** @type {(state: DeviceCleanupState | undefined) => void} */
+    #publish;
+    /** Invalidates a stale poll continuation after `cancel()` or a fresh `start()` — the same
+     * generation-counter guard `OwnerClaimService`/`OnboardingFlowService` use for their own
+     * long-running polls. */
+    #generation = 0;
+    /** @type {DeviceCleanupState | undefined} */
+    #state;
+    /** @param {DeviceCleanupServiceOptions} options */
+    constructor(options) {
+        this.#cleanup = options.cleanup;
+        this.#delay = options.delay;
+        this.#publish = options.publish;
+    }
+    /** The live-query-facing read: `undefined` while no ceremony has ever run for the current
+     * generation (nothing requested yet, or `cancel()` cleared it). */
+    state() {
+        return this.#state;
+    }
+    /**
+     * Opens/resumes the node's one live cleanup session (`client-device.cleanup-request.v1`)
+     * and, if it comes back `pending`, starts the bounded-backoff poll loop. Safe to call again
+     * — each call invalidates whatever poll was previously in flight, matching the ceremony's
+     * original "Ask the owner" re-request behaviour.
+     *
+     * A `requestCleanup()` failure is deliberately NOT caught here: it propagates to the caller
+     * exactly as it did when `pairing-gate.ts` awaited the command directly, so the shell's own
+     * catch (which renders `cleanupState: "failed"` onto the still-locally-held device-limit
+     * card) keeps working unchanged — this service has no base error state to merge it onto.
+     */
+    async start() {
+        const generation = ++this.#generation;
+        const result = await this.#cleanup.requestCleanup();
+        if (generation !== this.#generation)
+            return result;
+        this.#state = result.state;
+        this.#publish(this.#state);
+        // The session id lives only in this closure and the one `#poll` call it seeds — nothing
+        // else ever needs to read it back, so it is not duplicated onto a field (there is no
+        // "current session id" accessor for the same reason `state()` has no "current attempt
+        // count" sibling: both are captured by the generation-guarded loop that owns them).
+        if (result.state === "pending")
+            void this.#poll(result.sessionId, generation);
+        return result;
+    }
+    /**
+     * Cancels any in-flight poll and clears the ceremony state. Called from every point that
+     * used to invalidate the shell's own poll loop: a client change, suspension, `showRevoked()`,
+     * and disconnect (`pairing-gate.ts`'s `client-device.cleanup-cancel.v1` command, fired at
+     * exactly those four points).
+     */
+    cancel() {
+        this.#generation += 1;
+        if (this.#state === undefined)
+            return;
+        this.#state = undefined;
+        this.#publish(undefined);
+    }
+    /**
+     * The poll loop `start()` hands off to. Only ever continues while the node keeps answering
+     * `pending` — every other {@link DeviceCleanupState} (including `failed`, produced here when
+     * `cleanupStatus()` itself throws) is terminal and stops the loop, which is the rule under
+     * test in `device-cleanup-service.test.ts`'s backoff/termination coverage.
+     */
+    /** @param {string} sessionId @param {number} generation */
+    async #poll(sessionId, generation) {
+        let attempt = 0;
+        for (;;) {
+            await this.#delay.wait(pollDelayMs(attempt));
+            if (generation !== this.#generation)
+                return;
+            let result;
+            try {
+                result = await this.#cleanup.cleanupStatus(sessionId);
+            }
+            catch {
+                if (generation !== this.#generation)
+                    return;
+                this.#state = "failed";
+                this.#publish(this.#state);
+                return;
+            }
+            if (generation !== this.#generation)
+                return;
+            this.#state = result.state;
+            this.#publish(this.#state);
+            if (result.state !== "pending")
+                return;
+            attempt += 1;
+        }
+    }
+}