@econ-v1/rpc 6.7.0 → 6.11.0

package/src/onboarding/discovery-contract.js

@@ -0,0 +1,83 @@
+// @ts-check
+
+import { isJsonObject } from "../errors.js";
+
+/**
+ * The #1815 interim "search the node on the LAN" seam. Client-only vertical slice: the
+ * discovery screen probes explicit candidate addresses (manually entered today, a signed
+ * bootstrap descriptor's `lan_candidates` in the Phase-2 follow-on — see
+ * `docs/superpowers/plans/2026-07-25-client-node-lan-discovery.md`) and the kernel reports
+ * live per-candidate progress. Mirrors `./onboarding-contract.js`'s idiom: locked wire-name
+ * constants + JSON-safe view/payload types + a runtime validator per command payload.
+ *
+ * `DISCOVERY_QUERY` is both a one-shot `query()` and a `liveQuery()` name (the kernel's
+ * `LiveQueryDefinition` row type is `DiscoveryCandidateView`, keyed by `address`) — the same
+ * dual usage every other query in `@econ-v1/kernel`'s `LiveQueryEngine` supports.
+ */
+
+export const DISCOVERY_QUERY = "onboarding.discovery.v1";
+export const DISCOVERY_PROBE_COMMAND = "onboarding.discovery.probe.v1";
+export const DISCOVERY_PROMOTE_COMMAND = "onboarding.discovery.promote.v1";
+export const DISCOVER_NODE_COMMAND = "onboarding.discovery.discover-node.v1";
+
+/** @typedef {"probing" | "reachable" | "verified" | "unreachable"} DiscoveryCandidateStatus */
+
+/**
+ * The verified node's non-secret projection: nothing here is (or derives) a routable
+ * address, macaroon, or key — only what the found-node card renders.
+ *
+ * @typedef {{
+ *   readonly displayName: string,
+ *   readonly maskedNodeId: string
+ * }} DiscoveryFoundNode
+ */
+
+/**
+ * @typedef {{
+ *   readonly address: string,
+ *   readonly node?: DiscoveryFoundNode,
+ *   readonly status: DiscoveryCandidateStatus
+ * }} DiscoveryCandidateView
+ */
+
+/** @typedef {{ readonly addresses: readonly string[] }} ProbeCandidatesPayload */
+/** @typedef {{ readonly address: string }} PromoteCandidatePayload */
+/** @typedef {{ readonly address: string }} DiscoverNodePayload */
+/** @typedef {{ readonly address: string, readonly id: string, readonly path: "lan-direct" }} NodeDiscoveryCandidate */
+/**
+ * @typedef {
+ *   | { readonly status: "verified", readonly candidate: NodeDiscoveryCandidate }
+ *   | { readonly status: "reached-but-invalid", readonly reason: string }
+ *   | { readonly status: "unreachable-or-untrusted" }
+ * } NodeDiscoveryResult
+ */
+
+/**
+ * @param {unknown} value
+ * @returns {value is ProbeCandidatesPayload}
+ */
+export function isProbeCandidatesPayload(value) {
+  if (!isJsonObject(value)) return false;
+  const { addresses } = value;
+  return Array.isArray(addresses)
+    && addresses.length > 0
+    && addresses.every((item) => typeof item === "string" && item.trim().length > 0);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is PromoteCandidatePayload}
+ */
+export function isPromoteCandidatePayload(value) {
+  if (!isJsonObject(value)) return false;
+  return typeof value.address === "string" && value.address.trim().length > 0;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is DiscoverNodePayload}
+ */
+export function isDiscoverNodePayload(value) {
+  if (!isJsonObject(value)) return false;
+  return typeof value.address === "string" && value.address.trim().length > 0;
+}

package/src/onboarding/onboarding-contract.js

@@ -0,0 +1,106 @@
+// @ts-check
+/**  @typedef {"new" | "pair" | "wifi" | "expired" | "lost"} OnboardingScenario */
+/**  @typedef {"scan" | "invite" | "identity" | "matchcode" | "handoff" | "done"} OnboardingScreen */
+/**  @typedef {"connect" | "install" | "secure" | "identify" | "ready"} OnboardingPhase */
+/**  @typedef {| "bootstrap-required" | "needs-onboarding" | "needs-pairing" | "ready"} OnboardingLifecycleState */
+/**  @typedef {{ readonly invitationsEnabled?: boolean; readonly scenario?: OnboardingScenario; readonly state: OnboardingLifecycleState; }} OnboardingLifecycleStatus */
+/**  @typedef {{ readonly id: string; readonly maskedNodeId: string; readonly name: string; readonly ownership: "checking" | "owned" | "unowned"; }} OnboardingDiscoveryCandidate */
+/**  @typedef {| "waiting" | "approved" | "rejected" | "expired" | "cancelled"} OnboardingApprovalState */
+/**  @typedef {{ readonly approvalExpiresAt?: string; readonly approvalState?: OnboardingApprovalState; readonly candidates?: readonly OnboardingDiscoveryCandidate[]; readonly matchcodeDigits?: readonly string[]; readonly phase: OnboardingPhase; readonly reasonCode?: string; readonly scenario: OnboardingScenario; readonly screen: OnboardingScreen; }} OnboardingView */
+/**  @typedef {OnboardingView} OnboardingEvent */
+/**  @typedef {(typeof ONBOARDING_STEP_IDS)[number]} OnboardingStepId */
+/**  @typedef {| "onboard_qr" | "onboard_open_browser" | "onboard_wifi_setup" | "wifi_setup_connecting" | "onboard_home_qr" | "onboard_wifi_joined" | "onboard_working" | "onboard_code" | "onboard_trusted" | "onboard_rejected"} OnboardingLcdScreenId */
+/**  @typedef {"open" | "wep" | "wpa2" | "wpa3"} OnboardingWifiSecurity */
+/**
+ * Onboarding access-code rail (2026-08-10 design): a code-active node refused this device's
+ * claim outright — either the code is already bound to a different device
+ * (`code-already-bound`) or the supplied/missing code did not match (`access-code-invalid`,
+ * covering both `ACCESS_CODE_INVALID` and `ACCESS_CODE_REQUIRED`).
+ * @typedef {| "approval-expired" | "approval-rejected" | "wifi-credentials-rejected" | "wifi-scan-failed" | "wifi-unreachable" | "invitation-invalid" | "claim-failed" | "code-already-bound" | "access-code-invalid"} OnboardingReasonCode
+ */
+/**  @typedef {{ readonly security: OnboardingWifiSecurity; readonly signal: number; readonly ssid: string; }} OnboardingNetwork */
+/**  @typedef {{ readonly lcdScreenId: OnboardingLcdScreenId; readonly phase: OnboardingPhase; readonly reasonCode?: OnboardingReasonCode; readonly stepIndex: number; readonly totalSteps: number; }} OnboardingFlowBase */
+/**  @typedef {| (OnboardingFlowBase & { readonly networks: readonly OnboardingNetwork[]; readonly scanning: boolean; readonly stepId: "choose-network"; }) | (OnboardingFlowBase & { readonly security: OnboardingWifiSecurity; readonly ssid: string; readonly stepId: "network-password"; }) | (OnboardingFlowBase & { readonly approvalState: OnboardingApprovalState; readonly digits: readonly string[]; readonly remainingSeconds: number; readonly stepId: "match-code"; }) | (OnboardingFlowBase & { readonly stepId: "invitation" }) | (OnboardingFlowBase & { readonly displayName: string; readonly displayNameLocked: boolean; readonly stepId: "identity"; readonly submitting: boolean; }) | (OnboardingFlowBase & { readonly sessionEstablished: boolean; readonly stepId: "trusted"; }) | (OnboardingFlowBase & { readonly ssid: string; readonly stepId: "handoff"; }) | (OnboardingFlowBase & { readonly stepId: Exclude< OnboardingStepId, | "choose-network" | "handoff" | "identity" | "invitation" | "match-code" | "network-password" | "trusted" >; })} OnboardingFlowView */
+/**  @typedef {{ readonly children?: readonly OnboardingLcdScreenTree[]; readonly id: string; readonly type: string; readonly [extra: string]: unknown; }} OnboardingLcdScreenTree */
+/**  @typedef {Readonly<Record<string, number | string>>} OnboardingLcdScreenState */
+/**  @typedef {"not-registered" | "unreachable"} OnboardingLcdUnavailableReason */
+/**  @typedef {{ readonly awaitingNode: boolean; readonly physicalTapOnly: boolean; readonly screenId: OnboardingLcdScreenId; readonly state: OnboardingLcdScreenState; }} OnboardingLcdScreenBase */
+/**  @typedef {| (OnboardingLcdScreenBase & { readonly kind: "authored" }) | (OnboardingLcdScreenBase & { readonly kind: "tree"; readonly tree: OnboardingLcdScreenTree }) | (OnboardingLcdScreenBase & { readonly kind: "unavailable"; readonly reason: OnboardingLcdUnavailableReason; })} OnboardingLcdScreenView */
+/**  @typedef {| { readonly kind: "advance" } | { readonly kind: "select-network"; readonly security: OnboardingWifiSecurity; readonly ssid: string; } | { readonly kind: "rescan-networks" } | { readonly kind: "reselect-network" } | { readonly kind: "submit-network-password"; readonly secret: string } | { readonly decision: "continue-in-browser" | "installed"; readonly kind: "install-decision" } | { readonly componentId: string; readonly kind: "lcd-tap" } | { readonly kind: "advance-discovery" } | { readonly code: string; readonly kind: "redeem-invitation" } | { readonly displayName: string; readonly kind: "submit-identity"; readonly username: string; } | { readonly kind: "submit-wifi"; readonly secret: string; readonly ssid: string } | { readonly kind: "retry-approval" } | { readonly kind: "reconcile-completion" } | { readonly kind: "choose-path"; readonly scenario: OnboardingScenario } | { readonly kind: "cancel" }} OnboardingCommand */
+import { isJsonObject } from "../errors.js";
+export const ONBOARDING_STATUS_QUERY = /** @type {const} */ ("onboarding.status.v1");
+export const ONBOARDING_COMMAND = /** @type {const} */ ("onboarding.command.v1");
+export const ONBOARDING_EVENTS = /** @type {const} */ ("onboarding.events.v1");
+export const ONBOARDING_FLOW_QUERY = /** @type {const} */ ("onboarding.flow.v1");
+export const ONBOARDING_LCD_SCREEN_QUERY = /** @type {const} */ ("onboarding.lcd-screen.v1");
+/**
+ * The pager's declarative order. `stepIndex`/`totalSteps` are DERIVED from this list with
+ * gated rows removed (`invitation` today), so invitations-off yields ten steps and shifts
+ * every later index with no second table and no hole — the total can never be a constant.
+ *
+ * `begin-setup` ("Connect") is absent by design: its discovery scan ran only after the shell
+ * had ALREADY reached the node over HTTP, so on the shipped path it discovered nothing and was
+ * auto-advanced. Its screen still exists off-rail for the unreachable-node bootstrap case —
+ * see `OnboardingFlowService`'s `STEP_TABLE` comment.
+ */
+export const ONBOARDING_STEP_IDS = /** @type {const} */ ([
+    "join-qr",
+    "open-browser",
+    "choose-network",
+    "network-password",
+    "handoff",
+    "way-back",
+    "install",
+    "match-code",
+    "invitation",
+    "identity",
+    "trusted",
+]);
+/** @param {unknown} value @returns {value is OnboardingCommand} */
+export function isOnboardingCommand(value) {
+    if (!isJsonObject(value) || typeof value.kind !== "string")
+        return false;
+    switch (value.kind) {
+        case "redeem-invitation":
+            return typeof value.code === "string";
+        case "advance":
+        case "advance-discovery":
+        case "rescan-networks":
+        case "reselect-network":
+        case "retry-approval":
+        case "reconcile-completion":
+        case "cancel":
+            return true;
+        case "lcd-tap":
+            return typeof value.componentId === "string" && value.componentId.length > 0;
+        case "select-network":
+            return typeof value.ssid === "string"
+                && value.ssid.length > 0
+                && isOnboardingWifiSecurity(value.security);
+        case "submit-network-password":
+            return typeof value.secret === "string";
+        case "install-decision":
+            return value.decision === "installed" || value.decision === "continue-in-browser";
+        case "submit-identity":
+            return typeof value.username === "string"
+                && typeof value.displayName === "string";
+        case "submit-wifi":
+            return typeof value.ssid === "string" && typeof value.secret === "string";
+        case "choose-path":
+            return isOnboardingScenario(value.scenario);
+        default:
+            return false;
+    }
+}
+/** @param {unknown} value @returns {value is OnboardingWifiSecurity} */
+function isOnboardingWifiSecurity(value) {
+    return value === "open" || value === "wep" || value === "wpa2" || value === "wpa3";
+}
+/** @param {unknown} value @returns {value is OnboardingScenario} */
+function isOnboardingScenario(value) {
+    return value === "new"
+        || value === "pair"
+        || value === "wifi"
+        || value === "expired"
+        || value === "lost";
+}

package/src/onboarding/owner-claim-contract.js

@@ -0,0 +1,59 @@
+// @ts-check
+
+import { isJsonObject } from "../errors.js";
+/**
+ * First-owner "claim this unclaimed node" seam (#1815 DID-blocker fix,
+ * `.superpowers/sdd/did-blocker-report.md`). Deliberately separate from the generic
+ * (unwired) `ONBOARDING_COMMAND` in `./onboarding-contract.ts` — the same precedent as
+ * `DISCOVER_NODE_COMMAND` in `./discovery-contract.ts`, which is also "wired separately"
+ * rather than folded into a bigger, not-yet-built generic seam. `prepare` and `complete`
+ * are two commands (not one) because a person may spend anywhere from seconds to
+ * minutes physically walking to the node between them; `client/domain`'s
+ * `OwnerClaimService` holds the pending claim between the two calls and only unlocks it
+ * once the node itself has reported the physical confirmation.
+ * @type {"onboarding.owner-claim.prepare.v1"}
+ */
+export const OWNER_CLAIM_PREPARE_COMMAND = "onboarding.owner-claim.prepare.v1";
+export const OWNER_CLAIM_COMPLETE_COMMAND = "onboarding.owner-claim.complete.v1";
+/**
+ * @param {unknown} value
+ * @returns {value is OwnerClaimCompletePayload}
+ */
+export function isOwnerClaimCompletePayload(value) {
+    if (!isJsonObject(value))
+        return false;
+    return typeof value.displayName === "string" && value.displayName.trim().length > 0
+        && typeof value.username === "string" && value.username.trim().length > 0;
+}
+/**
+ * `claimed-unpaired` is a SUCCESS: the owner + DID exist on the node, but the completion
+ * response carried no usable session tokens (or adopting them did not produce a session), so
+ * the shell must fall back to its ordinary device-pairing flow. Collapsing it into `claimed`
+ * would make the UI assert a trust relationship the browser does not actually hold.
+ * @typedef {| "claimed"
+ *   | "claimed-unpaired"
+ *   | "not-prepared"
+ *   | "rejected"
+ *   | "timed-out"} OwnerClaimCompleteOutcome
+ */
+/**
+ * `prepare` carries NO payload (design §6.1): the node's `onboarding-prepare` route only ever
+ * received `{ public_key_multibase }`, and the identity that used to ride along was stashed
+ * purely client-side. Moving it to `complete` is what lets the match code appear at step 10
+ * while identity is not collected until step 12 — nothing is written until physical access
+ * has been proven.
+ * @typedef {Object} OwnerClaimPrepareResult
+ * @property {boolean} lcdHardware
+ * @property {string} matchCode
+ * @property {string} operationHash Empty string when the node's confirmation gate is disabled.
+ * @property {boolean} requiresConfirmation
+ */
+/**
+ * @typedef {Object} OwnerClaimCompletePayload
+ * @property {string} displayName
+ * @property {string} username
+ */
+/**
+ * @typedef {Object} OwnerClaimCompleteResult
+ * @property {OwnerClaimCompleteOutcome} outcome
+ */

package/src/pairing-status-contract.js

@@ -0,0 +1,36 @@
+// @ts-check
+export const CLIENT_DEVICE_PAIRING_STATUS_QUERY = "client-device.pairing-status.v1";
+/**
+ * Device-pairing wire-error codes shared verbatim across the Rust host and this TS client
+ * boundary (review recommendation, PR #2274). Canonical contract table:
+ * `docs/development/CAPABILITY_REGISTRY.md` § "Device-pairing wire-error contract" (mirrored
+ * on the Rust side by `core/domain/src/services/client_device_pairing_service.rs`'s
+ * `CLIENT_DEVICE_WIRE_ERROR_*` constants). These are the exact strings that travel over the
+ * wire — changing any value here is a cross-repo wire-contract change, not a local rename;
+ * every producer/consumer in that table must move together.
+ */
+export const CLIENT_DEVICE_WIRE_ERROR_NAME_TAKEN = "name_taken";
+/** @see CLIENT_DEVICE_WIRE_ERROR_NAME_TAKEN */
+export const CLIENT_DEVICE_WIRE_ERROR_LAST_DEVICE = "last_device";
+/** @see CLIENT_DEVICE_WIRE_ERROR_NAME_TAKEN */
+export const CLIENT_DEVICE_WIRE_ERROR_LAST_DEVICE_PROTECTED = "last_device_protected";
+/** @see CLIENT_DEVICE_WIRE_ERROR_NAME_TAKEN */
+export const CLIENT_DEVICE_WIRE_ERROR_DEVICE_NOT_REGISTERED = "device_not_registered";
+/**
+ * Kernel-owned view of the CURRENT pairing attempt this browser has in flight (design M4,
+ * `docs/superpowers/plans/2026-08-11-pwa-trusted-devices.md`). Single-slot — there is never
+ * more than one attempt live at a time — so the row's `id` is always the literal
+ * `"pairing-status"`, mirroring `client-device.cleanup.v1`'s single fixed-id row
+ * (`client/kernel/src/queries/device-cleanup.js`).
+ *
+ * `status` is a superset of what `<node-pairing-gate>` renders directly: `"idle"` (no attempt
+ * has begun, or the last one was reset), `"pairing"` (an attempt is in flight, matches the
+ * gate's own `"pairing"` display status), `"ready"` (the owner approved — or session
+ * establishment simply succeeded on its own), `"declined"`, `"revoked"`, `"expired"`, and
+ * `"name_conflict"` (the requested device name collided with another active/pending device —
+ * `pairing-status-service.js`'s `isNameTaken`). `"error"` is reserved for a future
+ * non-transient failure this service does not yet classify — `PairingStatusService` never
+ * emits it today; every unclassified failure keeps the row at `"pairing"` and lets the next
+ * poll attempt retry (see that file's doc comment).
+ * @typedef {{ readonly id: "pairing-status", readonly status: "idle"|"pairing"|"ready"|"declined"|"revoked"|"expired"|"name_conflict"|"error", readonly message?: string }} ClientDevicePairingStatusRow
+ */