@econ-v1/domain 6.7.0 → 6.10.0

package/src/services/onboarding-status-service.js

@@ -0,0 +1,64 @@
+// @ts-check
+/** @import { HomeNodeClient } from "@econ-v1/ports" */
+/**  @typedef {| "bootstrap-required" | "needs-onboarding" | "needs-pairing" | "ready"} OnboardingLifecycleState */
+/**  @typedef {{ readonly id: "onboarding-status"; readonly invitationsEnabled: boolean; readonly scenario?: "new"; readonly state: OnboardingLifecycleState; }} OnboardingLifecycleStatusRow */
+/**  @typedef {{ readonly claimed?: unknown; readonly invitations_enabled?: unknown; }} OnboardingStatusWire */
+/**  @typedef {{ readonly hasActiveSession: () => boolean; readonly locallyOnboarded?: () => Promise<boolean>; readonly node: Pick<HomeNodeClient, "invoke">; }} OnboardingStatusServiceOptions */
+import { TransportError } from "../errors/index.js";
+export class OnboardingStatusService {
+    /** @type {() => boolean} */
+    #hasActiveSession;
+    /** @type {(() => Promise<boolean>) | undefined} */
+    #locallyOnboarded;
+    /** @type {Pick<HomeNodeClient, "invoke">} */
+    #node;
+    #invitationsEnabled = false;
+    /** @param {OnboardingStatusServiceOptions} options */
+    constructor(options) {
+        this.#hasActiveSession = options.hasActiveSession;
+        this.#locallyOnboarded = options.locallyOnboarded;
+        this.#node = options.node;
+    }
+    /** Synchronous read of the last flag the node reported. Injected into
+     * `OnboardingFlowService` as a getter so a value arriving after boot still takes effect. */
+    /** @returns {boolean} */
+    invitationsEnabled() {
+        return this.#invitationsEnabled;
+    }
+    /** @returns {Promise<OnboardingLifecycleStatusRow>} */
+    async status() {
+        if (this.#hasActiveSession()) {
+            return { id: "onboarding-status", invitationsEnabled: this.#invitationsEnabled, state: "ready" };
+        }
+        try {
+            if (await this.#locallyOnboarded?.() === true) {
+                return { id: "onboarding-status", invitationsEnabled: this.#invitationsEnabled, state: "ready" };
+            }
+        }
+        catch {
+            // fall through to the network derivation
+        }
+        /** @type {boolean | undefined} */
+        let claimed;
+        try {
+            const response = await this.#node.invoke({
+                operation: "GET /api/auth/onboarding-status",
+                payload: {},
+            });
+            claimed = typeof response.claimed === "boolean" ? response.claimed : undefined;
+            this.#invitationsEnabled = response.invitations_enabled === true;
+        }
+        catch (error) {
+            if (error instanceof TransportError) {
+                return { id: "onboarding-status", invitationsEnabled: this.#invitationsEnabled, state: "bootstrap-required" };
+            }
+            return { id: "onboarding-status", invitationsEnabled: this.#invitationsEnabled, state: "needs-pairing" };
+        }
+        const invitationsEnabled = this.#invitationsEnabled;
+        if (claimed === undefined)
+            return { id: "onboarding-status", invitationsEnabled, state: "needs-pairing" };
+        return claimed
+            ? { id: "onboarding-status", invitationsEnabled, state: "needs-pairing" }
+            : { id: "onboarding-status", invitationsEnabled, scenario: "new", state: "needs-onboarding" };
+    }
+}

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

@@ -1,28 +1,89 @@
+// @ts-check
+
+/**
+ * @typedef {import("../models/outbox.js").OutboxEntry} OutboxEntry
+ */
+/**
+ * @typedef {import("../models/outbox.js").OutboxIntentInput} OutboxIntentInput
+ */
+/**
+ * @typedef {import("../models/outbox.js").OutboxState} OutboxState
+ */
+/**
+ * @typedef {{ create(entry: OutboxEntry): Promise<void>; delete(id: string): Promise<void>; list(domain?: string): Promise<readonly OutboxEntry[]>; read(id: string): Promise<OutboxEntry | undefined>; update(entry: OutboxEntry): Promise<void>; }} OutboxPersistence
+ */
+/**
+ * @typedef {{ readonly maxAttempts?: number; readonly now?: () => string; }} OutboxServiceOptions
+ */
+/**
+ * @typedef {{ readonly leaseMs?: number; readonly now?: string; readonly revalidateAuthoritative?: () => Promise<boolean>; }} ClaimOptions
+ */
+/**
+ * @typedef {{ readonly now?: string; readonly owner?: string; readonly retryable: boolean; }} FailureOptions
+ */
 import { canonicalOutboxPayload, createOutboxIntent, validateOutboxIntent, } from "../models/outbox.js";
+/**
+ * @extends {Error}
+ */
 export class OutboxIdempotencyConflictError extends Error {
+    /**
+   * @readonly
+   * @type {string}
+   */
     idempotencyKey;
+    /**
+   * @param {string} idempotencyKey
+   */
     constructor(idempotencyKey) {
         super("Outbox idempotency key belongs to a different command");
         this.name = "OutboxIdempotencyConflictError";
         this.idempotencyKey = idempotencyKey;
     }
 }
+/**
+ * @extends {Error}
+ */
 export class OutboxTransitionError extends Error {
+    /**
+   * @param {string} message
+   */
     constructor(message) {
         super(message);
         this.name = "OutboxTransitionError";
     }
 }
+/**
+ * @extends {OutboxTransitionError}
+ */
 export class OutboxRevalidationRequiredError extends OutboxTransitionError {
+    /**
+   * @param {string} id
+   */
     constructor(id) {
         super(`Authoritative outbox intent ${id} requires fresh-state revalidation`);
         this.name = "OutboxRevalidationRequiredError";
     }
 }
 export class OutboxService {
+    /**
+   * @readonly
+   * @type {number}
+   */
     #maxAttempts;
+    /**
+   * @readonly
+   * @type {() => string}
+   */
     #now;
+    /**
+   * @readonly
+   * @type {OutboxPersistence}
+   */
     #persistence;
+    /**
+   * @param {OutboxPersistence} persistence
+   * @param {OutboxServiceOptions} [options]
+   */
     constructor(persistence, options = {}) {
         this.#maxAttempts = options.maxAttempts ?? 3;
         if (!Number.isInteger(this.#maxAttempts) || this.#maxAttempts < 1) {
@@ -31,6 +92,10 @@ export class OutboxService {
         this.#now = options.now ?? (() => new Date().toISOString());
         this.#persistence = persistence;
     }
+    /**
+   * @param {OutboxIntentInput} input
+   * @returns {Promise<OutboxEntry>}
+   */
     async enqueue(input) {
         const entry = createOutboxIntent(input, { maxAttempts: this.#maxAttempts, now: this.#now() });
         const existing = (await this.#persistence.list()).find((candidate) => candidate.idempotencyKey === entry.idempotencyKey);
@@ -42,6 +107,12 @@ export class OutboxService {
         await this.#persistence.create(entry);
         return entry;
     }
+    /**
+   * @param {string} domain
+   * @param {string} owner
+   * @param {ClaimOptions} [options]
+   * @returns {Promise<OutboxEntry | undefined>}
+   */
     async claimNext(domain, owner, options = {}) {
         requireNonEmpty(owner, "lease owner");
         const now = options.now ?? this.#now();
@@ -71,11 +142,22 @@ export class OutboxService {
         }
         return undefined;
     }
+    /**
+   * @param {string} id
+   * @param {string} owner
+   * @returns {Promise<OutboxEntry>}
+   */
     async acknowledge(id, owner, now = this.#now()) {
         const current = await this.requireEntry(id);
         this.assertInflightOwner(current, owner);
         return await this.save(current, { lease: undefined, state: "acked", updatedAt: now });
     }
+    /**
+   * @param {string} id
+   * @param {string} reason
+   * @param {FailureOptions} options
+   * @returns {Promise<OutboxEntry>}
+   */
     async fail(id, reason, options) {
         requireNonEmpty(reason, "failure reason");
         const current = await this.requireEntry(id);
@@ -88,6 +170,12 @@ export class OutboxService {
             ? { lease: undefined, state: "failed", terminalReason: reason, updatedAt: options.now ?? this.#now() }
             : { lease: undefined, state: "pending", updatedAt: options.now ?? this.#now() });
     }
+    /**
+   * @param {string} id
+   * @param {string} reason
+   * @param {string} [owner]
+   * @returns {Promise<OutboxEntry>}
+   */
     async conflict(id, reason, owner, now = this.#now()) {
         requireNonEmpty(reason, "conflict reason");
         const current = await this.requireEntry(id);
@@ -97,6 +185,10 @@ export class OutboxService {
             throw new OutboxTransitionError(`Outbox intent ${id} is not inflight`);
         return await this.save(current, { conflictReason: reason, lease: undefined, state: "conflict", updatedAt: now });
     }
+    /**
+   * @param {string} id
+   * @returns {Promise<boolean>}
+   */
     async cancel(id) {
         const current = await this.#persistence.read(id);
         if (current === undefined)
@@ -106,6 +198,10 @@ export class OutboxService {
         await this.#persistence.delete(id);
         return true;
     }
+    /**
+   * @param {string} [domain]
+   * @returns {Promise<number>}
+   */
     async recoverExpiredLeases(now = this.#now(), domain) {
         let recovered = 0;
         for (const entry of await this.#persistence.list(domain)) {
@@ -116,36 +212,71 @@ export class OutboxService {
         }
         return recovered;
     }
+    /**
+   * @private
+   * @param {string} id
+   * @returns {Promise<OutboxEntry>}
+   */
     async requireEntry(id) {
         const entry = await this.#persistence.read(id);
         if (entry === undefined)
             throw new OutboxTransitionError(`Outbox intent was not found: ${id}`);
         return validateOutboxIntent(entry);
     }
+    /**
+   * @private
+   * @param {OutboxEntry} entry
+   * @param {string} owner
+   * @returns {void}
+   */
     assertInflightOwner(entry, owner) {
         if (entry.state !== "inflight" || entry.lease?.owner !== owner) {
             throw new OutboxTransitionError(`Outbox lease is not held by ${owner}`);
         }
     }
+    /**
+   * @private
+   * @param {OutboxEntry} current
+   * @param {Omit<Partial<OutboxEntry>, "lease"> & { readonly lease?: OutboxEntry["lease"]; readonly state: OutboxState; }} changes
+   * @returns {Promise<OutboxEntry>}
+   */
     async save(current, changes) {
         const updated = validateOutboxIntent({ ...current, ...changes });
         await this.#persistence.update(updated);
         return updated;
     }
 }
+/**
+ * @param {OutboxEntry} left
+ * @param {OutboxEntry} right
+ * @returns {number}
+ */
 function compareEntries(left, right) {
     return left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id);
 }
+/**
+ * @param {OutboxState} state
+ * @returns {boolean}
+ */
 function isTerminal(state) {
     return state === "acked" || state === "failed" || state === "conflict";
 }
+/**
+ * @param {OutboxEntry} left
+ * @param {OutboxEntry} right
+ * @returns {boolean}
+ */
 function sameCommand(left, right) {
     return left.domain === right.domain &&
         left.authority === right.authority &&
         canonicalOutboxPayload(left.payload) === canonicalOutboxPayload(right.payload);
 }
+/**
+ * @param {string} value
+ * @param {string} label
+ * @returns {void}
+ */
 function requireNonEmpty(value, label) {
     if (value.trim() === "")
         throw new TypeError(`${label} must be a non-empty string`);
 }
-//# sourceMappingURL=outbox-service.js.map

package/src/services/owner-claim-service.js

@@ -0,0 +1,347 @@
+// @ts-check
+/** @typedef {import('@econ-v1/ports').DelayPort} DelayPort */
+/** @typedef {import('@econ-v1/ports').HomeNodeClient} HomeNodeClient */
+/** @typedef {import('@econ-v1/ports').OwnerClaimCryptoPort} OwnerClaimCryptoPort */
+/** @typedef {import('@econ-v1/ports').OwnerClaimSessionPort} OwnerClaimSessionPort */
+/** @typedef {import('@econ-v1/ports').OwnerClaimSessionTokens} OwnerClaimSessionTokens */
+const POLL_INTERVAL_MS = 2000;
+const CONFIRMATION_TIMEOUT_MS = 5 * 60 * 1000;
+export class OwnerClaimService {
+  /**
+   * @readonly
+   */
+  #crypto;
+  /**
+   * @readonly
+   */
+  #delay;
+  /**
+   * @readonly
+   */
+  #node;
+  /**
+   * @readonly
+   */
+  #session;
+  /** @type {{ confirmed: boolean, operationHash: string | undefined, requiresConfirmation: boolean } | undefined} */
+  #pending;
+  /**
+   * @param {OwnerClaimServiceOptions} options
+   */
+  constructor(options) {
+    this.#crypto = options.keys;
+    this.#delay = options.delay;
+    this.#node = options.node;
+    this.#session = options.session;
+  }
+  /**
+   * Generates this attempt's ephemeral key and asks the node to start its
+   * physical-confirmation gate for it. Safe to call again after a failed `completeClaim()` or
+   * an expired code — each call replaces whatever claim was previously pending, which is
+   * exactly what step 10's "Request a new code" needs.
+   *
+   * `accessCode`, when supplied, is sent as `access_code` — the shared secret that lets the
+   * node bind and auto-confirm this operation without a physical LCD tap. It is omitted from
+   * the payload entirely (never sent as `undefined`/`null`) when not supplied, and it is never
+   * logged.
+   * @param {string} [accessCode]
+   * @returns {Promise<OwnerClaimPrepareOutcome>}
+   */
+  async prepareClaim(accessCode) {
+    const publicKeyHex = await this.#crypto.publicKey();
+    const prepared = await this.#node.invoke({
+      operation: "POST /api/v2/node/onboarding-prepare",
+      payload: {
+        public_key_multibase: publicKeyHex,
+        ...(accessCode !== undefined ? { access_code: accessCode } : {}),
+      },
+    });
+    const requiresConfirmation = prepared.requires_lcd === true;
+    const confirmed = prepared.confirmed === true;
+    this.#pending = {
+      confirmed,
+      operationHash: prepared.operation_hash,
+      requiresConfirmation,
+    };
+    return {
+      confirmed,
+      lcdHardware: prepared.lcd_hardware === true,
+      matchCode: prepared.match_code ?? "",
+      operationHash: prepared.operation_hash,
+      requiresConfirmation,
+    };
+  }
+  /**
+   * Waits for the node's physical confirmation. This is the ONLY thing that can put the
+   * pending claim into a completable state — no browser click, no timer, no LCD-pane tap
+   * substitutes for the node reporting `confirmed`.
+   *
+   * The poll cadence comes from the injected `DelayPort`, so this contains no timer of its
+   * own and stays testable with a zero-wait fake.
+   * @param {string} operationHash
+   * @returns {Promise<OwnerClaimConfirmation>}
+   */
+  async awaitConfirmation(operationHash) {
+    const deadline = Date.now() + CONFIRMATION_TIMEOUT_MS;
+    for (;;) {
+      const status = await this.#node.invoke({
+        operation: `GET /api/v2/node/operation-status/${encodeURIComponent(operationHash)}`,
+        payload: {},
+      });
+      if (status.confirmed === true) {
+        // Only the claim this hash actually belongs to may be unlocked: `prepareClaim()` can
+        // be called again ("Request a new code") while an earlier poll is still in flight, and
+        // a stale confirmation must never carry over onto the claim that superseded it.
+        const pending = this.#pending;
+        if (pending !== undefined && pending.operationHash === operationHash)
+          pending.confirmed = true;
+        return "confirmed";
+      }
+      if (status.status === "rejected") return "rejected";
+      if (Date.now() >= deadline) return "timed-out";
+      await this.#delay.wait(POLL_INTERVAL_MS);
+    }
+  }
+  /**
+   * Runs the legacy challenge -> sign -> `complete-onboarding` sequence to actually create the
+   * owner + DID, using the identity supplied HERE rather than one captured at prepare time.
+   * Resolves `"claimed"` only when the node's own completion call reported success.
+   *
+   * RETRY-SAFE BY DESIGN: neither `#pending` nor the ephemeral key is touched until the node's
+   * completion call is known to have SUCCEEDED. A thrown challenge/complete call, or an explicit
+   * `success: false`, leaves `#pending` (and the key) exactly as they were, so the caller can
+   * invoke `completeClaim()` again on this same instance — reaching the node a second time
+   * without a new `prepareClaim()` — for as long as the underlying failure might be transient
+   * (a dropped connection, a momentarily-busy node). Clearing state on failure, or in a
+   * `finally`, would turn every transient hiccup into a forced restart of the whole claim.
+   * @param {OwnerClaimIdentity} identity
+   * @returns {Promise<OwnerClaimOutcome>}
+   */
+  async completeClaim(identity) {
+    const pending = this.#pending;
+    if (pending === undefined) return "not-prepared";
+    // Refuse without touching the node: an owner record must never be attempted, let alone
+    // created, before the node itself reported the physical confirmation.
+    if (pending.requiresConfirmation && !pending.confirmed) return "rejected";
+    const onboardingConfirmation = pending.requiresConfirmation
+      ? pending.operationHash
+      : undefined;
+    /** @type {OnboardingCompleteWire} */
+    let result;
+    try {
+      const challenge = await this.#node.invoke({
+        operation: "POST /api/auth/onboarding-challenge",
+        payload: {},
+      });
+      const signature = await this.#crypto.sign(challenge.challenge);
+      const publicKeyHex = await this.#crypto.publicKey();
+      // OPTIONAL and best-effort: a descriptor-build failure must never turn into a rejected
+      // claim, so it gets its own inner try/catch rather than sharing the outer one (which
+      // would still swallow it into "rejected" — the same outcome, but for the wrong reason,
+      // and the outer catch's comment promises retry-safety specifically for the challenge/
+      // complete round trip, not for this). `?.` also covers session ports (like
+      // `createNullOwnerClaimSession()`) that never implement the optional member at all.
+      let genesisDevice;
+      try {
+        genesisDevice = await this.#session.describeGenesisDevice?.(challenge.challenge);
+      } catch {
+        genesisDevice = undefined;
+      }
+      result = await this.#node.invoke({
+        operation: "POST /api/auth/complete-onboarding",
+        payload: {
+          challenge_id: challenge.challenge_id,
+          device_info: this.#crypto.deviceInfo(),
+          first_name: identity.displayName,
+          last_name: "",
+          onboarding_confirmation: onboardingConfirmation,
+          public_key: publicKeyHex,
+          signature,
+          username: identity.username,
+          ...(genesisDevice === undefined ? {} : { genesis_device: genesisDevice }),
+        },
+      });
+    } catch {
+      // RETRY-SAFE: `#pending` and the ephemeral key survive untouched — see the doc comment.
+      return "rejected";
+    }
+    if (result.success !== true) return "rejected";
+    // PAST THIS LINE THE OWNER AND DID EXIST ON THE NODE. Nothing below may report the claim
+    // as failed — the worst honest answer is "claimed, but this browser is not paired". That is
+    // why the session work sits outside the try/catch above rather than inside it: a throw from
+    // `adopt` inside that block would have been swallowed into `"rejected"` and told a person
+    // their setup failed after it had already succeeded.
+    //
+    // This is also the ONLY point (besides `cancel()`) where the pending claim is dropped and
+    // the ephemeral key is reset — the claim it belonged to is now settled, one way or another.
+    this.#pending = undefined;
+    this.#crypto.reset();
+    const tokens = readSessionTokens(result);
+    if (tokens === undefined) return "claimed-unpaired";
+    try {
+      return (await this.#session.adopt(tokens))
+        ? "claimed"
+        : "claimed-unpaired";
+    } catch {
+      return "claimed-unpaired";
+    }
+  }
+  /** Drops any pending claim without contacting the node — used when the person abandons or
+   * restarts the flow before `completeClaim()` runs.
+   * @returns {void}
+   */
+  cancel() {
+    this.#pending = undefined;
+    this.#crypto.reset();
+  }
+}
+/**
+ * All THREE fields must be present and non-empty before any of them is used. A node that
+ * answers with a token but no expiry is a node whose session contract this client does not
+ * understand, and guessing an expiry would produce a session that silently dies mid-use.
+ *
+ * `refresh_token` is required-present for the same reason but deliberately NOT returned: see
+ * `OwnerClaimSessionTokens`.
+ * @param {OnboardingCompleteWire} wire
+ * @returns {OwnerClaimSessionTokens | undefined}
+ */
+function readSessionTokens(wire) {
+  const accessToken = typeof wire.token === "string" ? wire.token.trim() : "";
+  const expiresAt =
+    typeof wire.token_expires_at === "string"
+      ? wire.token_expires_at.trim()
+      : "";
+  const refreshToken =
+    typeof wire.refresh_token === "string" ? wire.refresh_token.trim() : "";
+  if (
+    accessToken.length === 0 ||
+    expiresAt.length === 0 ||
+    refreshToken.length === 0
+  ) {
+    return undefined;
+  }
+  return { accessToken, expiresAt };
+}
+/** @typedef {"confirmed" | "rejected" | "timed-out"} OwnerClaimConfirmation */
+/**
+ * `claimed-unpaired` is a SUCCESS, not a failure: the owner + DID now exist on the node. It
+ * says only that this browser did not end up holding a device session, so the shell must run
+ * its ordinary pairing flow. Collapsing it into `rejected` would tell a person their setup
+ * failed after it had already, irreversibly, succeeded.
+ * @typedef {| "claimed"
+ *   | "claimed-unpaired"
+ *   | "not-prepared"
+ *   | "rejected"
+ *   | "timed-out"} OwnerClaimOutcome
+ */
+/**
+ * First-owner onboarding — "claim this unclaimed node" (#1815 DID-blocker fix).
+ *
+ * The PWA's onboarding-gate walks a person through identity + physical-confirmation
+ * screens, but until this service existed nothing behind them ever created an owner or
+ * a DID on the backend (`.superpowers/sdd/did-blocker-report.md`): `core.did.onboard` —
+ * the only code path that writes `did_documents` — is called exclusively from
+ * `AuthApplicationService::complete()`, which backs the legacy, JWT-shaped
+ * `POST /api/auth/complete-onboarding` (`system/ui`-only until now).
+ *
+ * This service drives that SAME legacy contract from the PWA, reusing the existing,
+ * already-reviewed backend surface rather than inventing a parallel owner-creation
+ * path (see the blocker report §5): an ephemeral secp256k1 keypair
+ * (`OwnerClaimCryptoPort` — deliberately distinct from the Ed25519 `IdentityPort` used
+ * for client-device pairing afterwards), `POST /api/v2/node/onboarding-prepare` to
+ * start the node's physical-confirmation gate, a poll of
+ * `GET /api/v2/node/operation-status/{hash}` for that confirmation, then
+ * `POST /api/auth/{onboarding-challenge,complete-onboarding}` to actually create the
+ * owner + DID.
+ *
+ * The claim now also carries the browser's OWN pairing identity: `completeClaim()` asks the
+ * session port for an optional signed `genesis_device` descriptor and forwards it verbatim to
+ * `complete-onboarding`, so the node's genesis DID device IS this browser (not a synthetic
+ * placeholder) and the client-device pairing that follows reconciles onto that same row instead
+ * of minting a duplicate. Building or forwarding it can never turn a successful claim into a
+ * rejected one — see the inner try/catch around it below.
+ *
+ * SECURITY: this service never decides whether the claim is authorized — the node
+ * does. `completeClaim()` only ever *attempts* the completion call; the host's
+ * `validate_physical_confirmation` gate (`core/domain/src/services/
+ * auth_application_service.rs`) is the sole authority on whether a real physical
+ * confirmation happened, and refuses the request otherwise
+ * (`enforce_physical_presence`, `core/adapters-network/src/http/server/
+ * device_management/proxy.rs`, refuses browser/remote confirmation of an "onboard"
+ * operation outright when the node has a screen — only a physical LCD tap counts).
+ * A caller of this service who never gets the node's screen tapped simply never
+ * reaches "claimed": `awaitConfirmation()` resolves `"rejected"`/`"timed-out"` and
+ * `completeClaim()` then refuses, rather than reporting success.
+ *
+ * Once a client's `prepareClaim()` succeeds, the service holds exactly one pending claim —
+ * matching the legacy flow's "ONE device keypair for the whole onboarding attempt"
+ * invariant (the node's confirmation is bound to the specific public key sent to
+ * `onboarding-prepare`, and the app-did miniapp allows only one pending "onboard"
+ * operation node-wide).
+ *
+ * SEQUENCING (design §6.1) — `prepare(identity)`/`complete()` were split into
+ * `prepareClaim()` / `awaitConfirmation()` / `completeClaim(identity)` because the flow puts
+ * the match code at step 10 and identity at step 12, deliberately: nothing is written until
+ * physical access has been proven. That split is possible with NO backend change because
+ * `onboarding-prepare`'s payload is only `{ public_key_multibase }` — the identity that used
+ * to be handed to `prepare()` was stashed purely client-side and read back at completion.
+ *
+ * The security property is preserved and strengthened: `completeClaim()` refuses outright
+ * (without contacting the node) unless `awaitConfirmation()` has already observed the node's
+ * own `confirmed` for THIS claim's operation hash, so no owner record can exist until physical
+ * confirmation AND identity submission have both happened, in that order. The node's
+ * `validate_physical_confirmation` gate remains the sole authority; this client-side guard
+ * only stops a pointless, misleading round trip.
+ * @typedef {object} OwnerClaimIdentity
+ * @property {string} displayName
+ * @property {string} username
+ */
+/**
+ * @typedef {object} OwnerClaimPrepareOutcome
+ * @property {boolean} confirmed `true` when the node already bound and auto-confirmed this operation server-side (an
+ * access code was supplied and matched) — `awaitConfirmation()` is unnecessary and
+ * `completeClaim()` proceeds straight to the challenge/complete sequence, with no LCD
+ * match-code step in between.
+ * @property {boolean} lcdHardware
+ * @property {string} matchCode
+ * @property {string | undefined} operationHash The handle `awaitConfirmation()` polls and `completeClaim()` echoes back as
+ * `onboarding_confirmation`. Absent when the node's confirmation gate is disabled.
+ * @property {boolean} requiresConfirmation
+ */
+/**
+ * @typedef {object} OwnerClaimServiceOptions
+ * @property {OwnerClaimCryptoPort} keys The ephemeral secp256k1 identity for this onboarding attempt (see `OwnerClaimCryptoPort`'s
+ * doc comment). Named `keys`, not `crypto`, so this stays a plain interface field rather
+ * than reading as a reference to the browser's `crypto` global.
+ * @property {Pick<DelayPort, "wait">} delay
+ * @property {Pick<HomeNodeClient, "invoke">} node
+ * @property {OwnerClaimSessionPort} session Turns the completion response's tokens into a real device session. Required, not optional:
+ * defaulting it would make a wiring mistake look like a node that simply issued no tokens.
+ */
+/**
+ * @typedef {object} OnboardingPrepareWire
+ * @property {boolean} [confirmed] Present (and `true`) only when the node auto-confirmed this operation from a supplied
+ * access code; omitted entirely otherwise — never sent as an explicit `false`.
+ * @property {boolean} [lcd_hardware]
+ * @property {string} [operation_hash]
+ * @property {string} [match_code]
+ * @property {boolean} requires_lcd
+ */
+/**
+ * @typedef {object} OperationStatusWire
+ * @property {boolean} confirmed
+ * @property {string} [status]
+ */
+/**
+ * @typedef {object} OnboardingChallengeWire
+ * @property {string} challenge
+ * @property {string} challenge_id
+ */
+/**
+ * @typedef {object} OnboardingCompleteWire
+ * @property {unknown} [refresh_token]
+ * @property {boolean} success
+ * @property {unknown} [token]
+ * @property {unknown} [token_expires_at]
+ */
+// @ts-check