@econ-v1/domain 6.7.0 → 6.11.0

package/src/services/owner-view-refresh-service.js

@@ -0,0 +1,208 @@
+// @ts-check
+
+/** @typedef {import("@econ-v1/ports").RepositoryJsonValue} RepositoryJsonValue */
+/** @typedef {import("../events/index.js").DomainEvent} DomainEvent */
+/** @typedef {import("../models/owner-views.js").FeedItem} FeedItem */
+/** @typedef {import("../models/owner-views.js").HomeSummary} HomeSummary */
+/** @typedef {import("../models/owner-views.js").OperationalSummary} OperationalSummary */
+/** @typedef {import("../models/owner-views.js").OwnerViewRepository} OwnerViewRepository */
+/** @typedef {import("../models/owner-views.js").PeerDirectoryEntry} PeerDirectoryEntry */
+
+const OWNER_VIEW_PROJECTION_KEYS = Object.freeze({
+    feed: "feed:default",
+    home: "home",
+    operations: "operations",
+    peers: "peers:default",
+});
+
+export class OwnerViewRefreshService {
+    /** @readonly @type {OwnerViewRepository} */
+    #network;
+    /** @readonly @type {() => string} */
+    #now;
+    /** @readonly @type {OwnerViewProjectionStore} */
+    #projections;
+    /** @readonly @type {(event: DomainEvent) => void} */
+    #publish;
+    /** @readonly @type {() => Promise<void>} */
+    #validatePersistence;
+
+    /** @param {OwnerViewRefreshServiceOptions} options */
+    constructor(options) {
+        this.#network = options.network;
+        this.#now = options.now ?? (() => new Date().toISOString());
+        this.#projections = options.projections;
+        this.#publish = options.publish ?? (() => undefined);
+        this.#validatePersistence = options.validatePersistence ?? (async () => undefined);
+    }
+
+    /** @returns {Promise<void>} */
+    async refreshAll() {
+        const homeValue = await this.#network.readHomeSummary();
+        const home = homeValue === undefined ? null : parseHome(homeValue);
+        const peers = [...parsePeers(await this.#network.listPeers({}))];
+        const feed = [...parseFeed(await this.#network.listFeed({}))];
+        const operationsValue = await this.#network.readOperationalSummary();
+        const operations = operationsValue === undefined ? null : parseOperational(operationsValue);
+
+        await this.#persist([
+            { key: OWNER_VIEW_PROJECTION_KEYS.home, payload: home },
+            { key: OWNER_VIEW_PROJECTION_KEYS.peers, payload: peers },
+            { key: OWNER_VIEW_PROJECTION_KEYS.feed, payload: feed },
+            { key: OWNER_VIEW_PROJECTION_KEYS.operations, payload: operations },
+        ]);
+    }
+
+    /** @returns {Promise<void>} */
+    async refreshHome() {
+        const value = await this.#network.readHomeSummary();
+        await this.#persist([{
+            key: OWNER_VIEW_PROJECTION_KEYS.home,
+            payload: value === undefined ? null : parseHome(value),
+        }]);
+    }
+
+    /** @returns {Promise<void>} */
+    async refreshPeers() {
+        const value = await this.#network.listPeers({});
+        await this.#persist([{
+            key: OWNER_VIEW_PROJECTION_KEYS.peers,
+            payload: [...parsePeers(value)],
+        }]);
+    }
+
+    /** @returns {Promise<void>} */
+    async refreshFeed() {
+        const value = await this.#network.listFeed({});
+        await this.#persist([{
+            key: OWNER_VIEW_PROJECTION_KEYS.feed,
+            payload: [...parseFeed(value)],
+        }]);
+    }
+
+    /** @returns {Promise<void>} */
+    async refreshOperational() {
+        const value = await this.#network.readOperationalSummary();
+        await this.#persist([{
+            key: OWNER_VIEW_PROJECTION_KEYS.operations,
+            payload: value === undefined ? null : parseOperational(value),
+        }]);
+    }
+
+    /** @param {readonly { readonly key: string, readonly payload: RepositoryJsonValue }[]} batch */
+    async #persist(batch) {
+        const cachedAt = requiredTimestamp(this.#now(), "owner-view cachedAt");
+        await this.#validatePersistence();
+        await this.#projections.writeBatch(batch, cachedAt);
+        for (const { key } of batch) {
+            this.#publish({
+                occurredAt: cachedAt,
+                payload: { action: "updated", entityId: key, entityType: "owner-view" },
+                type: "domain.entity-changed",
+            });
+        }
+    }
+}
+
+/** @param {unknown} value @returns {HomeSummary} */
+function parseHome(value) {
+    const record = exactRecord(value, ["displayName", "homeNodeId", "lastSyncedAt", "status"], "home summary");
+    const lastSyncedAt = optionalTimestamp(record.lastSyncedAt, "home summary lastSyncedAt");
+    return {
+        displayName: requiredString(record.displayName, "home summary displayName"),
+        homeNodeId: requiredString(record.homeNodeId, "home summary homeNodeId"),
+        ...(lastSyncedAt === undefined ? {} : { lastSyncedAt }),
+        status: oneOf(record.status, ["offline", "online", "unknown"], "home summary status"),
+    };
+}
+
+/** @param {unknown} value @returns {readonly PeerDirectoryEntry[]} */
+function parsePeers(value) {
+    if (!Array.isArray(value)) throw invalid("peer directory");
+    return value.map((entry, index) => {
+        const label = `peer directory[${index}]`;
+        const record = exactRecord(entry, ["displayName", "id", "lastSeenAt", "status"], label);
+        const lastSeenAt = optionalTimestamp(record.lastSeenAt, `${label} lastSeenAt`);
+        return {
+            displayName: requiredString(record.displayName, `${label} displayName`),
+            id: requiredString(record.id, `${label} id`),
+            ...(lastSeenAt === undefined ? {} : { lastSeenAt }),
+            status: oneOf(record.status, ["offline", "online", "unknown"], `${label} status`),
+        };
+    });
+}
+
+/** @param {unknown} value @returns {readonly FeedItem[]} */
+function parseFeed(value) {
+    if (!Array.isArray(value)) throw invalid("feed");
+    return value.map((entry, index) => {
+        const label = `feed[${index}]`;
+        const record = exactRecord(entry, ["body", "createdAt", "id", "kind", "read", "title"], label);
+        if (typeof record.read !== "boolean") throw invalid(`${label} read`);
+        return {
+            body: requiredString(record.body, `${label} body`),
+            createdAt: requiredTimestamp(record.createdAt, `${label} createdAt`),
+            id: requiredString(record.id, `${label} id`),
+            kind: oneOf(record.kind, ["activity", "message", "system"], `${label} kind`),
+            read: record.read,
+            title: requiredString(record.title, `${label} title`),
+        };
+    });
+}
+
+/** @param {unknown} value @returns {OperationalSummary} */
+function parseOperational(value) {
+    const record = exactRecord(value, ["outboxDepth", "storage", "sync", "transport"], "operational summary");
+    if (!Number.isSafeInteger(record.outboxDepth) || /** @type {number} */ (record.outboxDepth) < 0) {
+        throw invalid("operational summary outboxDepth");
+    }
+    return {
+        outboxDepth: /** @type {number} */ (record.outboxDepth),
+        storage: oneOf(record.storage, ["blocked", "ready", "recovering"], "operational summary storage"),
+        sync: oneOf(record.sync, ["current", "stale", "syncing"], "operational summary sync"),
+        transport: oneOf(record.transport, ["iroh-relay", "lan-direct", "lan-webtransport", "offline", "wan-direct", "webrtc-direct"], "operational summary transport"),
+    };
+}
+
+/** @param {unknown} value @param {readonly string[]} allowed @param {string} label */
+function exactRecord(value, allowed, label) {
+    if (!isRecord(value) || Object.keys(value).some((key) => !allowed.includes(key))) throw invalid(label);
+    return value;
+}
+
+/** @param {unknown} value @param {string} label */
+function requiredString(value, label) {
+    if (typeof value !== "string" || value.trim() !== value || value.length === 0) throw invalid(label);
+    return value;
+}
+
+/** @param {unknown} value @param {string} label */
+function requiredTimestamp(value, label) {
+    const timestamp = requiredString(value, label);
+    if (!Number.isFinite(Date.parse(timestamp))) throw invalid(label);
+    return timestamp;
+}
+
+/** @param {unknown} value @param {string} label */
+function optionalTimestamp(value, label) {
+    return value === undefined ? undefined : requiredTimestamp(value, label);
+}
+
+/** @template {string} T @param {unknown} value @param {readonly T[]} values @param {string} label @returns {T} */
+function oneOf(value, values, label) {
+    if (typeof value !== "string" || !values.includes(/** @type {T} */ (value))) throw invalid(label);
+    return /** @type {T} */ (value);
+}
+
+/** @param {string} label */
+function invalid(label) {
+    return new TypeError(`Invalid ${label}`);
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** @typedef {{ read(key: string): Promise<{ readonly cachedAt: string, readonly payload: RepositoryJsonValue } | undefined>, writeBatch(batch: readonly { readonly key: string, readonly payload: RepositoryJsonValue }[], cachedAt: string): Promise<void> }} OwnerViewProjectionStore */
+/** @typedef {{ readonly network: OwnerViewRepository, readonly now?: () => string, readonly projections: OwnerViewProjectionStore, readonly publish?: (event: DomainEvent) => void, readonly validatePersistence?: () => Promise<void> }} OwnerViewRefreshServiceOptions */

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

@@ -0,0 +1,87 @@
+// @ts-check
+
+/**
+ * @typedef {import("../models/owner-views.js").FeedItem} FeedItem
+ */
+/**
+ * @typedef {import("../models/owner-views.js").FeedQuery} FeedQuery
+ */
+/**
+ * @typedef {import("../models/owner-views.js").HomeSummary} HomeSummary
+ */
+/**
+ * @typedef {import("../models/owner-views.js").OperationalSummary} OperationalSummary
+ */
+/**
+ * @typedef {import("../models/owner-views.js").OwnerViewRepository} OwnerViewRepository
+ */
+/**
+ * @typedef {import("../models/owner-views.js").PeerDirectoryEntry} PeerDirectoryEntry
+ */
+/**
+ * @typedef {import("../models/owner-views.js").PeerDirectoryQuery} PeerDirectoryQuery
+ */
+export class OwnerViewService {
+    /**
+   * @readonly
+   * @type {OwnerViewRepository}
+   */
+    #repository;
+    /** @readonly @type {OwnerViewRepository} */
+    #onlineRepository;
+    /**
+   * @param {OwnerViewRepository} repository Local repository for declared default projections.
+   * @param {OwnerViewRepository} [onlineRepository=repository] Online repository for undeclared filtered queries.
+   */
+    constructor(repository, onlineRepository = repository) {
+        this.#repository = repository;
+        this.#onlineRepository = onlineRepository;
+    }
+    /**
+   * @returns {Promise<readonly HomeSummary[]>}
+   */
+    async readHome() {
+        const summary = await this.#repository.readHomeSummary();
+        return summary === undefined ? [] : [summary];
+    }
+    /**
+   * @param {PeerDirectoryQuery} params
+   * @returns {Promise<readonly PeerDirectoryEntry[]>}
+   */
+    async listPeers(params) {
+        return await (isDefaultPeerQuery(params)
+            ? this.#repository.listPeers(params)
+            : this.#onlineRepository.listPeers(params));
+    }
+    /**
+   * @param {FeedQuery} params
+   * @returns {Promise<readonly FeedItem[]>}
+   */
+    async listFeed(params) {
+        return await (isDefaultFeedQuery(params)
+            ? this.#repository.listFeed(params)
+            : this.#onlineRepository.listFeed(params));
+    }
+    /**
+   * @returns {Promise<readonly OperationalSummary[]>}
+   */
+    async readOperational() {
+        const summary = await this.#repository.readOperationalSummary();
+        return summary === undefined ? [] : [summary];
+    }
+}
+
+const DEFAULT_LIST_LIMIT = 50;
+
+/** @param {PeerDirectoryQuery} params */
+function isDefaultPeerQuery(params) {
+    return params.status === undefined
+        && (params.limit ?? DEFAULT_LIST_LIMIT) === DEFAULT_LIST_LIMIT;
+}
+
+/** @param {FeedQuery} params */
+function isDefaultFeedQuery(params) {
+    return params.before === undefined
+        && params.unreadOnly === undefined
+        && (params.limit ?? DEFAULT_LIST_LIMIT) === DEFAULT_LIST_LIMIT;
+}

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

@@ -1,6 +1,24 @@
+// @ts-check
+
+/**
+ * @typedef {import("@econ-v1/ports").HomeNodeCandidate} HomeNodeCandidate
+ */
+/**
+ * @typedef {import("@econ-v1/ports").HomeNodeClient} HomeNodeClient
+ */
+/**
+ * @typedef {{ readonly directAddresses: readonly string[]; readonly did: string; readonly irohNodeId: string; readonly observedAt: string; }} PeerAdvertisement
+ */
+/**
+ * @typedef {{ readonly iroh_direct_addresses?: unknown; readonly iroh_endpoint_id?: unknown; readonly listening_addresses?: unknown; readonly node_id?: unknown; }} NodeMetadataWire
+ */
 const MAX_DIRECT_ADDRESSES = 8;
 export class PeerDirectoryService {
     #peers = new Map();
+    /**
+   * @param {PeerAdvertisement} advertisement
+   * @returns {boolean}
+   */
     upsert(advertisement) {
         const normalized = normalizeAdvertisement(advertisement);
         const current = this.#peers.get(normalized.irohNodeId);
@@ -9,15 +27,30 @@ export class PeerDirectoryService {
         this.#peers.set(normalized.irohNodeId, normalized);
         return true;
     }
+    /**
+   * @param {string} irohNodeId
+   * @returns {boolean}
+   */
     remove(irohNodeId) {
         return this.#peers.delete(irohNodeId);
     }
+    /**
+   * @param {string} irohNodeId
+   * @returns {PeerAdvertisement | undefined}
+   */
     get(irohNodeId) {
         return this.#peers.get(irohNodeId);
     }
+    /**
+   * @returns {readonly PeerAdvertisement[]}
+   */
     list() {
         return [...this.#peers.values()].sort((left, right) => right.observedAt.localeCompare(left.observedAt));
     }
+    /**
+   * @param {HomeNodeClient} home
+   * @returns {Promise<readonly HomeNodeCandidate[]>}
+   */
     async refreshLanCandidates(home) {
         const metadata = await home.invoke({
             operation: "GET /api/v2/node/metadata",
@@ -26,6 +59,10 @@ export class PeerDirectoryService {
         return nodeMetadataCandidates(metadata);
     }
 }
+/**
+ * @param {PeerAdvertisement} advertisement
+ * @returns {PeerAdvertisement}
+ */
 export function normalizeAdvertisement(advertisement) {
     requireText(advertisement.did, "Peer advertisement did");
     requireText(advertisement.irohNodeId, "Peer advertisement irohNodeId");
@@ -37,6 +74,10 @@ export function normalizeAdvertisement(advertisement) {
         observedAt: advertisement.observedAt,
     };
 }
+/**
+ * @param {NodeMetadataWire} metadata
+ * @returns {readonly HomeNodeCandidate[]}
+ */
 export function nodeMetadataCandidates(metadata) {
     const id = textOrUndefined(metadata.iroh_endpoint_id) ?? textOrUndefined(metadata.node_id);
     if (id === undefined)
@@ -47,25 +88,54 @@ export function nodeMetadataCandidates(metadata) {
     ]).slice(0, MAX_DIRECT_ADDRESSES);
     return addresses.map((address) => ({ address, id, path: "lan-direct" }));
 }
+/**
+ * @param {readonly string[]} addresses
+ * @returns {readonly string[]}
+ */
 export function uniqueAddresses(addresses) {
     return [...new Set(addresses.map((address) => address.trim()).filter((address) => address.length > 0))];
 }
+/**
+ * @param {readonly string[]} addresses
+ * @returns {readonly string[]}
+ */
 export function secureAddresses(addresses) {
     return uniqueAddresses(addresses)
         .map(toSecureAddress)
-        .filter((address) => address !== undefined)
+        .filter(/**
+ * @returns {address is string}
+ */ (address) => address !== undefined)
         .slice(0, MAX_DIRECT_ADDRESSES);
 }
+/**
+ * @param {unknown} value
+ * @returns {readonly string[]}
+ */
 function stringArray(value) {
-    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+    return Array.isArray(value) ? value.filter(/**
+   * @returns {item is string}
+   */ (item) => typeof item === "string") : [];
 }
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
 function textOrUndefined(value) {
     return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
 }
+/**
+ * @param {string} value
+ * @param {string} label
+ * @returns {void}
+ */
 function requireText(value, label) {
     if (typeof value !== "string" || value.trim().length === 0)
         throw new TypeError(`${label} must be non-empty`);
 }
+/**
+ * @param {string} address
+ * @returns {string | undefined}
+ */
 function toSecureAddress(address) {
     const value = address.includes("://") ? address : `https://${address}`;
     const match = /^https:\/\/([^/?#:\s]+)(?::(\d{1,5}))?(?:\/)?$/u.exec(value);
@@ -76,4 +146,3 @@ function toSecureAddress(address) {
         return undefined;
     return port === undefined ? `https://${match[1]}` : `https://${match[1]}:${port}`;
 }
-//# sourceMappingURL=peer-directory-service.js.map

package/src/services/release-manifest-verifier.js

@@ -0,0 +1,108 @@
+// @ts-check
+
+/** @typedef {import("@econ-v1/ports").CryptoPort} CryptoPort */
+/** @typedef {import("../models/release-manifest.js").ReleaseManifestAsset} ReleaseManifestAsset */
+/** @typedef {import("../models/release-manifest.js").SignedReleaseManifest} SignedReleaseManifest */
+
+import { canonicalOutboxPayload } from "../models/outbox.js";
+import {
+  parseSignedReleaseManifest,
+  unsignedReleaseManifestToJson,
+} from "../models/release-manifest.js";
+import { encodeUtf8 } from "./runtime-globals.js";
+
+/** @type {readonly ["malformed", "bad-signature", "hash-mismatch", "incompatible-protocol", "incompatible-schema", "channel-not-allowed"]} */
+export const RELEASE_MANIFEST_REJECTION_REASONS = [
+  "malformed",
+  "bad-signature",
+  "hash-mismatch",
+  "incompatible-protocol",
+  "incompatible-schema",
+  "channel-not-allowed",
+];
+
+/** @typedef {(typeof RELEASE_MANIFEST_REJECTION_REASONS)[number]} ReleaseManifestRejectionReason */
+/** @typedef {{ readonly manifest: SignedReleaseManifest, readonly ok: true } | { readonly ok: false, readonly reason: ReleaseManifestRejectionReason }} ReleaseManifestVerification */
+/** @typedef {{ readonly keyId: string, readonly publicKey: Uint8Array }} ReleaseManifestTrustedKey */
+/** @typedef {{ readonly allowedChannels: readonly string[], readonly cryptoPort: Pick<CryptoPort, "digestSha256" | "verifyEd25519">, readonly currentProtocolVersion: number, readonly currentStorageSchemaVersion: number }} ReleaseManifestVerifyOptions */
+
+/**
+ * @param {unknown} candidate
+ * @param {readonly ReleaseManifestTrustedKey[]} trustedPublicKeys
+ * @param {ReleaseManifestVerifyOptions} options
+ * @returns {Promise<ReleaseManifestVerification>}
+ */
+export async function verifyReleaseManifest(candidate, trustedPublicKeys, options) {
+  const manifest = parseSignedReleaseManifest(candidate);
+  if (manifest === undefined) return { ok: false, reason: "malformed" };
+
+  const trustedKey = trustedPublicKeys.find((key) => key.keyId === manifest.signingKeyId);
+  if (trustedKey === undefined) return { ok: false, reason: "bad-signature" };
+
+  const signatureBytes = hexToBytes(manifest.signature);
+  if (signatureBytes === undefined) return { ok: false, reason: "malformed" };
+
+  const canonicalPayload = encodeUtf8(
+    canonicalOutboxPayload(unsignedReleaseManifestToJson(manifest)),
+  );
+  /** @type {boolean} */
+  let signatureValid;
+  try {
+    signatureValid = await options.cryptoPort.verifyEd25519(canonicalPayload, signatureBytes, trustedKey.publicKey);
+  } catch {
+    return { ok: false, reason: "bad-signature" };
+  }
+  if (!signatureValid) return { ok: false, reason: "bad-signature" };
+
+  const expectedShellVersion = await deriveShellVersion(manifest.shellAssets, options.cryptoPort);
+  if (expectedShellVersion !== manifest.shellVersion) return { ok: false, reason: "hash-mismatch" };
+
+  if (!options.allowedChannels.includes(manifest.channel)) return { ok: false, reason: "channel-not-allowed" };
+
+  if (isOutOfRange(options.currentProtocolVersion, manifest.protocolCompatibility)) {
+    return { ok: false, reason: "incompatible-protocol" };
+  }
+
+  if (isOutOfRange(options.currentStorageSchemaVersion, manifest.storageSchemaCompatibility)) {
+    return { ok: false, reason: "incompatible-schema" };
+  }
+
+  return { manifest, ok: true };
+}
+
+/**
+ * @param {readonly ReleaseManifestAsset[]} shellAssets
+ * @param {Pick<CryptoPort, "digestSha256">} cryptoPort
+ * @returns {Promise<string>}
+ */
+async function deriveShellVersion(shellAssets, cryptoPort) {
+  const sorted = [...shellAssets].sort((left, right) => left.url.localeCompare(right.url));
+  const payload = JSON.stringify(sorted.map((asset) => ({ sha256: asset.sha256, url: asset.url })));
+  const digest = await cryptoPort.digestSha256(encodeUtf8(payload));
+  return digest.slice(0, 16);
+}
+
+/**
+ * @param {number} value
+ * @param {{ readonly max: number, readonly min: number }} range
+ * @returns {boolean}
+ */
+function isOutOfRange(value, range) {
+  return value < range.min || value > range.max;
+}
+
+/**
+ * @param {string} hex
+ * @returns {Uint8Array | undefined}
+ */
+function hexToBytes(hex) {
+  if (hex.length % 2 !== 0) return undefined;
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let index = 0; index < bytes.length; index += 1) {
+    const byteHex = hex.slice(index * 2, index * 2 + 2);
+    const byte = Number.parseInt(byteHex, 16);
+    if (Number.isNaN(byte)) return undefined;
+    bytes[index] = byte;
+  }
+  return bytes;
+}