@lapis-notes/api 0.1.0 → 0.1.3

package/dist/plugin-distribution/nostr-registry-adapter.js

@@ -0,0 +1,152 @@
+import { PluginDistributionError } from "./errors";
+import { verifyNostrPluginPayload, } from "./plugin-bundle-verifier";
+import { parsePluginDistributionMetadata, pluginCatalogDetailSchema, pluginCatalogIndexSchema, } from "./schemas";
+export function createNostrPluginRegistryAdapter(options) {
+    const fetchImpl = options.fetch ?? ((url, init) => fetch(url, init));
+    return {
+        async refresh(source, refreshOptions) {
+            if (refreshOptions?.force) {
+                await options.catalogSource.refresh?.();
+            }
+            const index = parsePluginDistributionMetadata(pluginCatalogIndexSchema, normalizeNostrCatalogIndex(await options.catalogSource.loadIndex()));
+            const status = options.catalogSource.getStatus();
+            return {
+                index,
+                installReady: status.installReady,
+                stale: !status.fresh,
+                ...(status.message ? { message: status.message } : {}),
+            };
+        },
+        async getDetail(_source, entry) {
+            return parsePluginDistributionMetadata(pluginCatalogDetailSchema, normalizeNostrCatalogDetail(await options.catalogSource.loadPluginDetail(entry)));
+        },
+        async getVerifiedBundle(source, entry, detail, version, installOptions) {
+            const curatorPubkeys = source.curatorPubkeys ?? [];
+            if (curatorPubkeys.length === 0) {
+                throw new PluginDistributionError("metadata-invalid", `Nostr registry ${source.name} has no pinned curator keys.`);
+            }
+            const release = requireRelease(detail, version);
+            const artifactUrl = resolveArtifactUrl(source, release.bundle);
+            const response = await fetchImpl(artifactUrl, {
+                signal: installOptions?.signal,
+            });
+            if (!response.ok) {
+                throw new PluginDistributionError("metadata-invalid", `Plugin payload fetch failed for ${artifactUrl}: ${response.status} ${response.statusText}`);
+            }
+            const [artifact, proof] = await Promise.all([
+                response.arrayBuffer().then((value) => new Uint8Array(value)),
+                options.catalogSource.loadReleaseProof(entry.id, version, {
+                    signal: installOptions?.signal,
+                }),
+            ]);
+            return verifyNostrPluginPayload({
+                artifact,
+                proof,
+                trustedCuratorPubkeys: new Set(curatorPubkeys),
+                verifyReleaseProof: options.verifyReleaseProof,
+                signal: installOptions?.signal,
+                relayFresh: true,
+            });
+        },
+        async verifyOfflineBundle(source, bundle, installOptions) {
+            const curatorPubkeys = source.curatorPubkeys ?? [];
+            if (curatorPubkeys.length === 0) {
+                throw new PluginDistributionError("metadata-invalid", `Nostr registry ${source.name} has no pinned curator keys.`);
+            }
+            return verifyNostrPluginPayload({
+                artifact: bundle.payload,
+                proof: bundle.proof,
+                trustedCuratorPubkeys: new Set(curatorPubkeys),
+                verifyReleaseProof: options.verifyReleaseProof,
+                signal: installOptions?.signal,
+                relayFresh: false,
+            });
+        },
+        async revalidateInstalledProof(source, record, installOptions) {
+            const stored = requireStoredProof(record);
+            const curatorPubkeys = source.curatorPubkeys ?? [];
+            if (curatorPubkeys.length === 0) {
+                throw new PluginDistributionError("metadata-invalid", `Nostr registry ${source.name} has no pinned curator keys.`);
+            }
+            const status = options.catalogSource.getStatus();
+            if (!status.installReady || !status.fresh) {
+                throw new PluginDistributionError("metadata-invalid", `Nostr registry ${source.name} has not reached install quorum.`);
+            }
+            const proof = await options.catalogSource.loadReleaseProof(record.pluginId, record.installedVersion, { signal: installOptions?.signal });
+            const verified = await options.verifyReleaseProof(proof, {
+                artifact: {
+                    sha256: stored.artifactSha256,
+                    size: stored.artifactSize,
+                },
+                trustedCuratorPubkeys: new Set(curatorPubkeys),
+            });
+            if (verified.releaseEventId !== stored.releaseEventId) {
+                throw new PluginDistributionError("metadata-invalid", "Live Nostr proof names a different immutable release event.");
+            }
+            return {
+                authorizationEventId: verified.authorizationEventId,
+                releaseEventId: verified.releaseEventId,
+                decisionEventId: verified.decisionEventId,
+                manifestSha256: verified.manifestSha256,
+                artifactSha256: verified.artifactSha256,
+                artifactSize: verified.artifactSize,
+                requiresRelayRefresh: false,
+            };
+        },
+    };
+}
+function normalizeNostrCatalogIndex(value) {
+    if (!isRecord(value) || !Array.isArray(value.plugins))
+        return value;
+    return {
+        ...value,
+        plugins: value.plugins.map((entry) => removeNonHttpsReadmeUrl(entry)),
+    };
+}
+function normalizeNostrCatalogDetail(value) {
+    return removeNonHttpsReadmeUrl(value);
+}
+function removeNonHttpsReadmeUrl(value) {
+    if (!isRecord(value))
+        return value;
+    const readmeUrl = value.readmeUrl;
+    if (readmeUrl === undefined || isHttpsUrl(readmeUrl))
+        return value;
+    const { readmeUrl: _readmeUrl, ...rest } = value;
+    return rest;
+}
+function isHttpsUrl(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        return new URL(value).protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireStoredProof(record) {
+    if (!record.nostrProof) {
+        throw new PluginDistributionError("metadata-invalid", "Installed plugin has no stored Nostr proof.");
+    }
+    return record.nostrProof;
+}
+function requireRelease(detail, version) {
+    const release = detail.versions[version];
+    if (!release) {
+        throw new PluginDistributionError("metadata-invalid", `${detail.id} has no Nostr release ${version}.`);
+    }
+    return release;
+}
+function resolveArtifactUrl(source, bundle) {
+    const location = bundle.downloadUrl ?? bundle.url;
+    try {
+        return new URL(location).toString();
+    }
+    catch {
+        return new URL(location, source.url).toString();
+    }
+}

package/dist/plugin-distribution/plugin-bundle-verifier.d.ts

@@ -21,8 +21,51 @@ export interface VerifiedPluginBundlePayload {
     releaseManifest: PluginReleaseManifest;
     releaseManifestSha256: string;
     files: Map<string, Uint8Array>;
+    nostrProof?: {
+        authorizationEventId: string;
+        releaseEventId: string;
+        decisionEventId: string;
+        manifestSha256: string;
+        artifactSha256: string;
+        artifactSize: number;
+        requiresRelayRefresh: boolean;
+    };
+}
+export interface VerifiedNostrReleaseProofResult {
+    pluginId: string;
+    version: string;
+    authorizationEventId: string;
+    releaseEventId: string;
+    decisionEventId: string;
+    manifestSha256: string;
+    artifactSha256: string;
+    artifactSize: number;
+    requiresRelayRefresh: true;
+    manifest: {
+        release: {
+            metadata: Record<string, unknown>;
+        };
+    };
+}
+export type NostrReleaseProofVerifier = (proof: unknown, options: {
+    artifact: Uint8Array | {
+        sha256: string;
+        size: number;
+    };
+    trustedCuratorPubkeys: ReadonlySet<string>;
+}) => VerifiedNostrReleaseProofResult | Promise<VerifiedNostrReleaseProofResult>;
+export interface VerifyNostrPluginPayloadOptions {
+    artifact: ArrayBuffer | Uint8Array;
+    proof: unknown;
+    trustedCuratorPubkeys: ReadonlySet<string>;
+    verifyReleaseProof: NostrReleaseProofVerifier;
+    signal?: AbortSignal;
+    onProgress?: (event: PluginBundleVerificationProgressEvent) => void;
+    /** True only when a live source reached its configured install quorum. */
+    relayFresh?: boolean;
 }
 export declare const verifyPluginBundlePayload: (options: VerifyPluginBundlePayloadOptions) => Promise<VerifiedPluginBundlePayload>;
+export declare const verifyNostrPluginPayload: (options: VerifyNostrPluginPayloadOptions) => Promise<VerifiedPluginBundlePayload>;
 export declare function throwIfAborted(signal: AbortSignal | undefined): void;
 export declare function createAbortError(): Error;
 export declare function exactArrayBuffer(bytes: Uint8Array): ArrayBuffer;

package/dist/plugin-distribution/plugin-bundle-verifier.js

@@ -1,6 +1,6 @@
 import { sha256Hex, verifySha256 } from "./hashes";
 import { assertSafePluginRelativePath } from "./path-safety";
-import { PLUGIN_BUNDLE_RELEASE_MANIFEST_PATH, parsePluginBundle, } from "./plugin-bundle";
+import { PLUGIN_BUNDLE_RELEASE_MANIFEST_PATH, parsePluginBundle, parsePluginPayload, } from "./plugin-bundle";
 import { parsePluginDistributionMetadata, pluginReleaseManifestSchema, signedEnvelopeSchema, } from "./schemas";
 import { verifySignedEnvelope } from "./signing";
 import { PluginDistributionError } from "./errors";
@@ -74,6 +74,69 @@ export const verifyPluginBundlePayload = async (options) => {
         files,
     };
 };
+export const verifyNostrPluginPayload = async (options) => {
+    throwIfAborted(options.signal);
+    const artifact = toUint8(options.artifact);
+    options.onProgress?.({
+        phase: "verifying-bundle",
+        message: "Verifying Nostr release proof",
+    });
+    const verified = await options.verifyReleaseProof(options.proof, {
+        artifact,
+        trustedCuratorPubkeys: options.trustedCuratorPubkeys,
+    });
+    const releaseManifest = parsePluginDistributionMetadata(pluginReleaseManifestSchema, verified.manifest.release.metadata.lapisRelease);
+    if (releaseManifest.pluginId !== verified.pluginId ||
+        releaseManifest.version !== verified.version) {
+        throw new PluginDistributionError("metadata-invalid", "Nostr proof release coordinates do not match the plugin payload manifest.");
+    }
+    const bundledFiles = parsePluginPayload(artifact, {
+        onProgress: options.onProgress,
+    });
+    const files = new Map();
+    const expectedPaths = new Set();
+    const fileCount = releaseManifest.files.length;
+    for (const [index, file] of releaseManifest.files.entries()) {
+        throwIfAborted(options.signal);
+        assertSafePluginRelativePath(file.path);
+        expectedPaths.add(file.path);
+        const bytes = bundledFiles.get(file.path);
+        if (!bytes) {
+            throw new PluginDistributionError("metadata-invalid", `Plugin payload is missing curated file: ${file.path}`);
+        }
+        if (bytes.byteLength !== file.size) {
+            throw new PluginDistributionError("hash-mismatch", `Plugin file ${file.path} size mismatch: expected ${file.size}, got ${bytes.byteLength}.`);
+        }
+        options.onProgress?.({
+            phase: "verifying-files",
+            message: `Verifying ${file.path}`,
+            filePath: file.path,
+            fileIndex: index + 1,
+            fileCount,
+        });
+        await verifySha256(bytes, file.sha256);
+        files.set(file.path, bytes);
+    }
+    const extraPaths = [...bundledFiles.keys()].filter((path) => !expectedPaths.has(path));
+    if (extraPaths.length) {
+        throw new PluginDistributionError("metadata-invalid", "Plugin payload includes files that are not listed in the curated release manifest.", { details: { paths: extraPaths } });
+    }
+    return {
+        releaseEnvelope: { signed: releaseManifest, signatures: [] },
+        releaseManifest,
+        releaseManifestSha256: verified.manifestSha256,
+        files,
+        nostrProof: {
+            authorizationEventId: verified.authorizationEventId,
+            releaseEventId: verified.releaseEventId,
+            decisionEventId: verified.decisionEventId,
+            manifestSha256: verified.manifestSha256,
+            artifactSha256: verified.artifactSha256,
+            artifactSize: verified.artifactSize,
+            requiresRelayRefresh: options.relayFresh !== true,
+        },
+    };
+};
 export function throwIfAborted(signal) {
     if (!signal?.aborted) {
         return;

package/dist/plugin-distribution/plugin-bundle.d.ts

@@ -1,4 +1,6 @@
 export declare const PLUGIN_BUNDLE_RELEASE_MANIFEST_PATH = "release.signed.json";
+export declare const NOSTR_PLUGIN_BUNDLE_PROOF_PATH = "release.nostr.json";
+export declare const NOSTR_PLUGIN_BUNDLE_PAYLOAD_PATH = "payload.zip";
 export declare const PLUGIN_BUNDLE_STORED_METHOD = 0;
 export declare const PLUGIN_BUNDLE_DEFLATE_METHOD = 8;
 export interface ParsePluginBundleProgressEvent {
@@ -14,3 +16,15 @@ export interface ParsePluginBundleOptions {
     onProgress?: (event: ParsePluginBundleProgressEvent) => void;
 }
 export declare const parsePluginBundle: (input: ArrayBuffer | Uint8Array, options?: ParsePluginBundleOptions) => Map<string, Uint8Array>;
+/** Parse the deterministic inner payload used by Nostr proof bundles. */
+export declare const parsePluginPayload: (input: ArrayBuffer | Uint8Array, options?: ParsePluginBundleOptions) => Map<string, Uint8Array>;
+export interface ParsedNostrPluginBundle {
+    proof: unknown;
+    payload: Uint8Array;
+}
+/**
+ * Parse the portable offline Nostr container, or return null for a legacy
+ * root-signed bundle. Once either v2 marker is present, malformed containers
+ * fail closed instead of falling back to the legacy verifier.
+ */
+export declare const parseNostrPluginBundle: (input: ArrayBuffer | Uint8Array, options?: ParsePluginBundleOptions) => ParsedNostrPluginBundle | null;

package/dist/plugin-distribution/plugin-bundle.js

@@ -2,11 +2,46 @@ import { Unzip, UnzipInflate } from "fflate";
 import { PluginDistributionError } from "./errors";
 import { assertSafePluginRelativePath } from "./path-safety";
 export const PLUGIN_BUNDLE_RELEASE_MANIFEST_PATH = "release.signed.json";
+export const NOSTR_PLUGIN_BUNDLE_PROOF_PATH = "release.nostr.json";
+export const NOSTR_PLUGIN_BUNDLE_PAYLOAD_PATH = "payload.zip";
 export const PLUGIN_BUNDLE_STORED_METHOD = 0;
 export const PLUGIN_BUNDLE_DEFLATE_METHOD = 8;
-export const parsePluginBundle = (input, options = {}) => {
+export const parsePluginBundle = (input, options = {}) => parsePluginArchive(input, options, true);
+/** Parse the deterministic inner payload used by Nostr proof bundles. */
+export const parsePluginPayload = (input, options = {}) => parsePluginArchive(input, options, false);
+/**
+ * Parse the portable offline Nostr container, or return null for a legacy
+ * root-signed bundle. Once either v2 marker is present, malformed containers
+ * fail closed instead of falling back to the legacy verifier.
+ */
+export const parseNostrPluginBundle = (input, options = {}) => {
+    const entries = parsePluginArchive(input, options, false);
+    const hasNostrMarker = entries.has(NOSTR_PLUGIN_BUNDLE_PROOF_PATH) ||
+        entries.has(NOSTR_PLUGIN_BUNDLE_PAYLOAD_PATH);
+    if (!hasNostrMarker)
+        return null;
+    const paths = [...entries.keys()];
+    if (paths.length !== 2 ||
+        paths[0] !== NOSTR_PLUGIN_BUNDLE_PROOF_PATH ||
+        paths[1] !== NOSTR_PLUGIN_BUNDLE_PAYLOAD_PATH) {
+        throw invalidBundle(".lapis-plugin Nostr bundle must contain only release.nostr.json and payload.zip.");
+    }
+    const proofBytes = entries.get(NOSTR_PLUGIN_BUNDLE_PROOF_PATH);
+    let proof;
+    try {
+        proof = JSON.parse(new TextDecoder().decode(proofBytes));
+    }
+    catch (error) {
+        throw invalidBundle(".lapis-plugin release.nostr.json is invalid JSON.", error);
+    }
+    return {
+        proof,
+        payload: entries.get(NOSTR_PLUGIN_BUNDLE_PAYLOAD_PATH),
+    };
+};
+const parsePluginArchive = (input, options, requireSignedManifest) => {
     const bytes = toUint8(input);
-    const expectedEntries = inspectPluginBundleMetadata(bytes);
+    const expectedEntries = inspectPluginBundleMetadata(bytes, requireSignedManifest);
     const entries = new Map();
     let seenFileCount = 0;
     let processedBytes = 0;
@@ -82,12 +117,13 @@ export const parsePluginBundle = (input, options = {}) => {
             throw invalidBundle(`.lapis-plugin bundle did not extract ${expectedEntry.path}.`);
         }
     }
-    if (!entries.has(PLUGIN_BUNDLE_RELEASE_MANIFEST_PATH)) {
+    if (requireSignedManifest &&
+        !entries.has(PLUGIN_BUNDLE_RELEASE_MANIFEST_PATH)) {
         throw invalidBundle(".lapis-plugin bundle is missing release.signed.json.");
     }
     return entries;
 };
-const inspectPluginBundleMetadata = (bytes) => {
+const inspectPluginBundleMetadata = (bytes, requireSignedManifest) => {
     const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
     const eocdOffset = findEndOfCentralDirectory(view);
     const totalEntries = readUint16(view, eocdOffset + 10);
@@ -155,13 +191,16 @@ const inspectPluginBundleMetadata = (bytes) => {
     }
     const localOrder = [...entries].sort((left, right) => left.localHeaderOffset - right.localHeaderOffset);
     const firstEntry = localOrder[0];
-    if (firstEntry?.path !== PLUGIN_BUNDLE_RELEASE_MANIFEST_PATH) {
+    if (requireSignedManifest &&
+        firstEntry?.path !== PLUGIN_BUNDLE_RELEASE_MANIFEST_PATH) {
         throw invalidBundle(".lapis-plugin bundle must store release.signed.json as the first entry.");
     }
-    if (firstEntry.compressionMethod !== PLUGIN_BUNDLE_STORED_METHOD) {
+    if (requireSignedManifest &&
+        firstEntry.compressionMethod !== PLUGIN_BUNDLE_STORED_METHOD) {
         throw invalidBundle(".lapis-plugin release.signed.json entry must be stored.");
     }
-    if (!seenPaths.has(PLUGIN_BUNDLE_RELEASE_MANIFEST_PATH)) {
+    if (requireSignedManifest &&
+        !seenPaths.has(PLUGIN_BUNDLE_RELEASE_MANIFEST_PATH)) {
         throw invalidBundle(".lapis-plugin bundle is missing release.signed.json.");
     }
     return localOrder;

package/dist/plugin-distribution/plugin-markdown.d.ts

@@ -0,0 +1,6 @@
+import type { PluginMarkdownReference } from "./types";
+export declare const MAX_PLUGIN_MARKDOWN_BYTES: number;
+type FetchLike = typeof fetch;
+export declare function clearVerifiedPluginMarkdownCache(): void;
+export declare function fetchVerifiedPluginMarkdown(reference: PluginMarkdownReference, fetchImpl?: FetchLike): Promise<string>;
+export {};

package/dist/plugin-distribution/plugin-markdown.js

@@ -0,0 +1,94 @@
+import { PluginDistributionError } from "./errors";
+import { verifySha256 } from "./hashes";
+export const MAX_PLUGIN_MARKDOWN_BYTES = 256 * 1024;
+const markdownCache = new Map();
+export function clearVerifiedPluginMarkdownCache() {
+    markdownCache.clear();
+}
+export async function fetchVerifiedPluginMarkdown(reference, fetchImpl = fetch) {
+    validateReference(reference);
+    const cacheKey = referenceCacheKey(reference);
+    let pending = markdownCache.get(cacheKey);
+    if (!pending) {
+        pending = fetchAndVerify(reference, fetchImpl).catch((error) => {
+            markdownCache.delete(cacheKey);
+            throw error;
+        });
+        markdownCache.set(cacheKey, pending);
+    }
+    return pending;
+}
+function validateReference(reference) {
+    if (reference.mediaType !== "text/markdown" ||
+        !Number.isInteger(reference.size) ||
+        reference.size < 0 ||
+        reference.size > MAX_PLUGIN_MARKDOWN_BYTES ||
+        !/^[a-fA-F0-9]{64}$/.test(reference.sha256)) {
+        throw new PluginDistributionError("metadata-invalid", "Plugin Markdown reference is invalid or exceeds the supported size.", { details: { url: reference.url, size: reference.size } });
+    }
+    for (const [label, value] of [
+        ["registry", reference.url],
+        ["source", reference.sourceUrl],
+    ]) {
+        try {
+            if (new URL(value).protocol !== "https:")
+                throw new Error("not HTTPS");
+        }
+        catch (error) {
+            throw new PluginDistributionError("metadata-invalid", `Plugin Markdown ${label} URL must use HTTPS.`, { cause: error, details: { url: value } });
+        }
+    }
+}
+async function fetchAndVerify(reference, fetchImpl) {
+    let response;
+    try {
+        response = await fetchImpl(reference.url, {
+            headers: { Accept: "text/markdown" },
+        });
+    }
+    catch (error) {
+        throw new PluginDistributionError("metadata-invalid", "Plugin Markdown request failed.", { cause: error, details: { url: reference.url } });
+    }
+    if (!response.ok) {
+        throw new PluginDistributionError("metadata-invalid", `Plugin Markdown request failed with HTTP ${response.status}.`, { details: { url: reference.url, status: response.status } });
+    }
+    const declaredLength = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declaredLength) &&
+        (declaredLength !== reference.size ||
+            declaredLength > MAX_PLUGIN_MARKDOWN_BYTES)) {
+        throw new PluginDistributionError("metadata-invalid", "Plugin Markdown response size does not match signed metadata.", {
+            details: {
+                url: reference.url,
+                expectedSize: reference.size,
+                actualSize: declaredLength,
+            },
+        });
+    }
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    if (bytes.byteLength !== reference.size ||
+        bytes.byteLength > MAX_PLUGIN_MARKDOWN_BYTES) {
+        throw new PluginDistributionError("metadata-invalid", "Plugin Markdown bytes do not match the signed size.", {
+            details: {
+                url: reference.url,
+                expectedSize: reference.size,
+                actualSize: bytes.byteLength,
+            },
+        });
+    }
+    await verifySha256(bytes, reference.sha256);
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch (error) {
+        throw new PluginDistributionError("metadata-invalid", "Plugin Markdown is not valid UTF-8.", { cause: error, details: { url: reference.url } });
+    }
+}
+function referenceCacheKey(reference) {
+    return [
+        reference.url,
+        reference.sourceUrl,
+        reference.sha256.toLowerCase(),
+        reference.size,
+        reference.mediaType,
+    ].join("\u0000");
+}

package/dist/plugin-distribution/registry-client.d.ts

@@ -1,4 +1,4 @@
-import type { PluginCatalogDetail, PluginCatalogEntry, PluginCatalogIndex, PluginRegistrySource, PluginRevocationIndex, SignatureRecord, TrustedSigningKey } from "./types";
+import type { PluginCatalogDetail, PluginCatalogEntry, PluginCatalogIndex, PluginDownloadStatsSummary, PluginRegistrySource, PluginRevocationIndex, SignatureRecord, TrustedSigningKey } from "./types";
 import { PluginRegistryCache } from "./registry-cache";
 export type PluginRegistryFetch = (url: string, init?: RequestInit) => Promise<Pick<Response, "ok" | "status" | "statusText" | "text">>;
 export interface PluginRegistryRefreshResult {
@@ -24,10 +24,15 @@ export declare class PluginRegistryClient {
     refresh(source: PluginRegistrySource): Promise<PluginRegistryRefreshResult>;
     getDetail(entry: PluginCatalogEntry): Promise<PluginRegistryDetailResult>;
     getCachedIndex(): PluginCatalogIndex | null;
+    getDownloadStats(source: PluginRegistrySource, options?: {
+        force?: boolean;
+        now?: Date;
+    }): Promise<PluginDownloadStatsSummary | null>;
     private fetchJson;
     private verifyIndex;
     private fetchRevocations;
     private verifyDetail;
+    private verifyOriginal;
     private normalizeEntry;
     private trustedKeysFor;
 }

package/dist/plugin-distribution/registry-client.js

@@ -1,6 +1,7 @@
 import { PluginDistributionError } from "./errors";
 import { assertPluginIdAllowedForProvenance } from "./reserved-ids";
-import { pluginCatalogDetailSchema, pluginCatalogIndexSchema, pluginRevocationIndexSchema, parsePluginDistributionMetadata, } from "./schemas";
+import { pluginDownloadStatsSummarySchema, pluginCatalogDetailSchema, pluginCatalogIndexSchema, pluginRevocationIndexSchema, parsePluginDistributionMetadata, } from "./schemas";
+import { isUsablePluginDownloadStatsSummary } from "./download-stats";
 import { verifySignedEnvelope } from "./signing";
 import { PluginRegistryCache } from "./registry-cache";
 export class PluginRegistryClient {
@@ -56,16 +57,33 @@ export class PluginRegistryClient {
     getCachedIndex() {
         return this.currentIndex ?? this.cache.getMemory()?.index ?? null;
     }
-    async fetchJson(url) {
-        const response = await this.fetchImpl(url);
+    async getDownloadStats(source, options = {}) {
+        if (!source.downloadStatsUrl)
+            return null;
+        try {
+            const metadata = await this.fetchJson(new URL(source.downloadStatsUrl, source.url).toString(), {
+                cache: options.force ? "reload" : "no-cache",
+                headers: { accept: "application/json" },
+            });
+            const summary = parsePluginDistributionMetadata(pluginDownloadStatsSummarySchema, metadata);
+            return isUsablePluginDownloadStatsSummary(summary, options.now ?? new Date())
+                ? summary
+                : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async fetchJson(url, init) {
+        const response = await this.fetchImpl(url, init);
         if (!response.ok) {
             throw new PluginDistributionError("metadata-invalid", `Registry fetch failed for ${url}: ${response.status} ${response.statusText}`, { details: { url, status: response.status } });
         }
         return JSON.parse(await response.text());
     }
     async verifyIndex(metadata, source) {
-        const index = parsePluginDistributionMetadata(pluginCatalogIndexSchema, metadata);
-        const verified = (await verifyInlineSignedMetadata(index, index.signatures, this.trustedKeysFor(source.trustTier)));
+        const verifiedInput = await this.verifyOriginal(metadata, this.trustedKeysFor(source.trustTier));
+        const verified = parsePluginDistributionMetadata(pluginCatalogIndexSchema, verifiedInput);
         return {
             ...verified,
             plugins: verified.plugins.map((entry) => this.normalizeEntry(entry, source)),
@@ -74,18 +92,22 @@ export class PluginRegistryClient {
     async fetchRevocations(source) {
         const url = new URL("revoked.json", source.url).toString();
         const metadata = await this.fetchJson(url);
-        const revocations = parsePluginDistributionMetadata(pluginRevocationIndexSchema, metadata);
-        const verified = await verifyInlineSignedMetadata(revocations, revocations.signatures, this.trustedKeysFor(source.trustTier));
-        return verified;
+        const verifiedInput = await this.verifyOriginal(metadata, this.trustedKeysFor(source.trustTier));
+        return parsePluginDistributionMetadata(pluginRevocationIndexSchema, verifiedInput);
     }
     async verifyDetail(metadata, entry) {
-        const detail = parsePluginDistributionMetadata(pluginCatalogDetailSchema, metadata);
-        const verified = (await verifyInlineSignedMetadata(detail, detail.signatures, this.options.trustedKeys));
+        const verifiedInput = await this.verifyOriginal(metadata, this.options.trustedKeys);
+        const verified = parsePluginDistributionMetadata(pluginCatalogDetailSchema, verifiedInput);
         if (verified.id !== entry.id) {
             throw new PluginDistributionError("metadata-invalid", `Plugin detail id ${verified.id} does not match catalog entry ${entry.id}.`, { details: { entryId: entry.id, detailId: verified.id } });
         }
         return verified;
     }
+    async verifyOriginal(metadata, keys) {
+        if (!metadata || typeof metadata !== "object" || Array.isArray(metadata))
+            throw new PluginDistributionError("metadata-invalid", "Expected signed registry object.");
+        return verifyInlineSignedMetadata(metadata, metadata.signatures, keys);
+    }
     normalizeEntry(entry, source) {
         const provenance = source.trustTier === "official" ? "official" : "community";
         assertPluginIdAllowedForProvenance(entry.id, provenance);

package/dist/plugin-distribution/registry-source-state.d.ts

@@ -0,0 +1,15 @@
+import type { DataAdapter } from "../storage/fs";
+import type { PluginRegistrySourcePreferencesState } from "./types";
+export declare class PluginRegistrySourcePreferenceStore {
+    private readonly adapter;
+    private readonly options;
+    constructor(adapter: DataAdapter, options?: {
+        path?: string;
+        now?: () => Date;
+    });
+    load(): Promise<PluginRegistrySourcePreferencesState>;
+    save(state: PluginRegistrySourcePreferencesState): Promise<void>;
+    private emptyState;
+    private get path();
+    private now;
+}

package/dist/plugin-distribution/registry-source-state.js

@@ -0,0 +1,42 @@
+import { dirname } from "../storage/path";
+import { ensureFolder } from "./installed-plugin-state";
+import { parsePluginDistributionMetadata, pluginRegistrySourcePreferencesStateSchema, } from "./schemas";
+export class PluginRegistrySourcePreferenceStore {
+    adapter;
+    options;
+    constructor(adapter, options = {}) {
+        this.adapter = adapter;
+        this.options = options;
+    }
+    async load() {
+        try {
+            const raw = await this.adapter.read(this.path);
+            return parsePluginDistributionMetadata(pluginRegistrySourcePreferencesStateSchema, JSON.parse(raw));
+        }
+        catch {
+            return this.emptyState();
+        }
+    }
+    async save(state) {
+        const next = {
+            schemaVersion: 1,
+            updatedAt: this.now(),
+            sources: state.sources ?? {},
+        };
+        await ensureFolder(this.adapter, dirname(this.path));
+        await this.adapter.write(this.path, JSON.stringify(next, null, 2));
+    }
+    emptyState() {
+        return {
+            schemaVersion: 1,
+            updatedAt: this.now(),
+            sources: {},
+        };
+    }
+    get path() {
+        return this.options.path ?? ".obsidian/plugin-registry-sources.json";
+    }
+    now() {
+        return (this.options.now?.() ?? new Date()).toISOString();
+    }
+}