@pkcprotocol/pkc-js 0.0.41 → 0.0.42

package/dist/node/test/test-util.d.ts

@@ -202,8 +202,334 @@ export declare function getAvailablePKCConfigsToTestAgainst(opts?: {
 export declare function createNewIpns(): Promise<{
     signer: import("../signer/index.js").SignerWithPublicKeyAddress;
     publishToIpns: (content: string) => Promise<void>;
+    publishToIpnsValue: (value: string, opts?: {
+        verifyResolves?: boolean;
+    }) => Promise<void>;
     pkc: PKC;
 }>;
+export declare function createDelegatedCommunityIpns(communityOpts?: Partial<CommunityIpfsType>, opts?: {
+    contentSigner?: SignerType;
+    intermediateHopsCount?: number;
+}): Promise<{
+    anchorName: string;
+    terminalName: string;
+    intermediateNames: string[];
+    ipnsHops: string[];
+    communityRecord: {
+        challenges: {
+            [x: string]: unknown;
+            type: string;
+            exclude?: {
+                [x: string]: unknown;
+                community?: {
+                    addresses: string[];
+                    maxCommentCids: number;
+                    postScore?: number | undefined;
+                    replyScore?: number | undefined;
+                    firstCommentTimestamp?: number | undefined;
+                } | undefined;
+                postScore?: number | undefined;
+                replyScore?: number | undefined;
+                postCount?: number | undefined;
+                replyCount?: number | undefined;
+                firstCommentTimestamp?: number | undefined;
+                challenges?: number[] | undefined;
+                role?: string[] | undefined;
+                address?: string[] | undefined;
+                rateLimit?: number | undefined;
+                rateLimitChallengeSuccess?: boolean | undefined;
+                publicationType?: {
+                    [x: string]: unknown;
+                    post?: boolean | undefined;
+                    reply?: boolean | undefined;
+                    vote?: boolean | undefined;
+                    commentEdit?: boolean | undefined;
+                    commentModeration?: boolean | undefined;
+                    communityEdit?: boolean | undefined;
+                } | undefined;
+            }[] | undefined;
+            description?: string | undefined;
+            challenge?: string | undefined;
+            caseInsensitive?: boolean | undefined;
+            pendingApproval?: boolean | undefined;
+        }[];
+        signature: {
+            type: string;
+            signature: string;
+            publicKey: string;
+            signedPropertyNames: string[];
+        };
+        encryption: {
+            [x: string]: unknown;
+            type: string;
+            publicKey: string;
+        };
+        createdAt: number;
+        updatedAt: number;
+        statsCid: string;
+        protocolVersion: string;
+        posts?: {
+            pages: Record<string, {
+                comments: {
+                    comment: {
+                        [x: string]: unknown;
+                        timestamp: number;
+                        signature: {
+                            type: string;
+                            signature: string;
+                            publicKey: string;
+                            signedPropertyNames: string[];
+                        };
+                        protocolVersion: string;
+                        depth: number;
+                        flairs?: {
+                            [x: string]: unknown;
+                            text: string;
+                            backgroundColor?: string | undefined;
+                            textColor?: string | undefined;
+                            expiresAt?: number | undefined;
+                        }[] | undefined;
+                        communityPublicKey?: string | undefined;
+                        communityName?: string | undefined;
+                        link?: string | undefined;
+                        spoiler?: boolean | undefined;
+                        nsfw?: boolean | undefined;
+                        content?: string | undefined;
+                        title?: string | undefined;
+                        linkWidth?: number | undefined;
+                        linkHeight?: number | undefined;
+                        linkHtmlTagName?: string | undefined;
+                        parentCid?: string | undefined;
+                        postCid?: string | undefined;
+                        quotedCids?: string[] | undefined;
+                        author?: {
+                            [x: string]: unknown;
+                            name?: string | undefined;
+                            previousCommentCid?: string | undefined;
+                            displayName?: string | undefined;
+                            wallets?: Record<string, {
+                                address: string;
+                                timestamp: number;
+                                signature: {
+                                    signature: string;
+                                    type: string;
+                                };
+                            }> | undefined;
+                            avatar?: {
+                                [x: string]: unknown;
+                                chainTicker: string;
+                                address: string;
+                                id: string;
+                                timestamp: number;
+                                signature: {
+                                    signature: string;
+                                    type: string;
+                                };
+                            } | undefined;
+                            flairs?: {
+                                [x: string]: unknown;
+                                text: string;
+                                backgroundColor?: string | undefined;
+                                textColor?: string | undefined;
+                                expiresAt?: number | undefined;
+                            }[] | undefined;
+                        } | undefined;
+                        thumbnailUrl?: string | undefined;
+                        thumbnailUrlWidth?: number | undefined;
+                        thumbnailUrlHeight?: number | undefined;
+                        previousCid?: string | undefined;
+                        pseudonymityMode?: "per-post" | "per-reply" | "per-author" | undefined;
+                    };
+                    commentUpdate: {
+                        [x: string]: unknown;
+                        cid: string;
+                        upvoteCount: number;
+                        downvoteCount: number;
+                        replyCount: number;
+                        updatedAt: number;
+                        signature: {
+                            type: string;
+                            signature: string;
+                            publicKey: string;
+                            signedPropertyNames: string[];
+                        };
+                        protocolVersion: string;
+                        childCount?: number | undefined;
+                        number?: number | undefined;
+                        postNumber?: number | undefined;
+                        edit?: {
+                            [x: string]: unknown;
+                            timestamp: number;
+                            signature: {
+                                type: string;
+                                signature: string;
+                                publicKey: string;
+                                signedPropertyNames: string[];
+                            };
+                            protocolVersion: string;
+                            commentCid: string;
+                            flairs?: {
+                                [x: string]: unknown;
+                                text: string;
+                                backgroundColor?: string | undefined;
+                                textColor?: string | undefined;
+                                expiresAt?: number | undefined;
+                            }[] | undefined;
+                            communityPublicKey?: string | undefined;
+                            communityName?: string | undefined;
+                            spoiler?: boolean | undefined;
+                            nsfw?: boolean | undefined;
+                            reason?: string | undefined;
+                            content?: string | undefined;
+                            deleted?: boolean | undefined;
+                            author?: {
+                                [x: string]: unknown;
+                                name?: string | undefined;
+                                previousCommentCid?: string | undefined;
+                                displayName?: string | undefined;
+                                wallets?: Record<string, {
+                                    address: string;
+                                    timestamp: number;
+                                    signature: {
+                                        signature: string;
+                                        type: string;
+                                    };
+                                }> | undefined;
+                                avatar?: {
+                                    [x: string]: unknown;
+                                    chainTicker: string;
+                                    address: string;
+                                    id: string;
+                                    timestamp: number;
+                                    signature: {
+                                        signature: string;
+                                        type: string;
+                                    };
+                                } | undefined;
+                                flairs?: {
+                                    [x: string]: unknown;
+                                    text: string;
+                                    backgroundColor?: string | undefined;
+                                    textColor?: string | undefined;
+                                    expiresAt?: number | undefined;
+                                }[] | undefined;
+                            } | undefined;
+                        } | undefined;
+                        flairs?: {
+                            [x: string]: unknown;
+                            text: string;
+                            backgroundColor?: string | undefined;
+                            textColor?: string | undefined;
+                            expiresAt?: number | undefined;
+                        }[] | undefined;
+                        spoiler?: boolean | undefined;
+                        nsfw?: boolean | undefined;
+                        pinned?: boolean | undefined;
+                        locked?: boolean | undefined;
+                        archived?: boolean | undefined;
+                        removed?: boolean | undefined;
+                        reason?: string | undefined;
+                        approved?: boolean | undefined;
+                        author?: {
+                            [x: string]: unknown;
+                            community?: {
+                                [x: string]: unknown;
+                                postScore: number;
+                                replyScore: number;
+                                firstCommentTimestamp: number;
+                                lastCommentCid: string;
+                                banExpiresAt?: number | undefined;
+                                flairs?: {
+                                    [x: string]: unknown;
+                                    text: string;
+                                    backgroundColor?: string | undefined;
+                                    textColor?: string | undefined;
+                                    expiresAt?: number | undefined;
+                                }[] | undefined;
+                            } | undefined;
+                        } | undefined;
+                        lastChildCid?: string | undefined;
+                        lastReplyTimestamp?: number | undefined;
+                        replies?: {
+                            pages: Record<string, /*elided*/ any>;
+                            pageCids?: Record<string, string> | undefined;
+                        } | undefined;
+                    };
+                }[];
+                nextCid?: string | undefined;
+            }>;
+            pageCids?: Record<string, string> | undefined;
+        } | undefined;
+        modQueue?: {
+            pageCids: Record<string, string>;
+        } | undefined;
+        name?: string | undefined;
+        pubsubTopic?: string | undefined;
+        postUpdates?: Record<string, string> | undefined;
+        title?: string | undefined;
+        description?: string | undefined;
+        roles?: Record<string, {
+            [x: string]: unknown;
+            role: string;
+        }> | undefined;
+        rules?: string[] | undefined;
+        lastPostCid?: string | undefined;
+        lastCommentCid?: string | undefined;
+        features?: {
+            [x: string]: unknown;
+            noVideos?: boolean | undefined;
+            noSpoilers?: boolean | undefined;
+            noImages?: boolean | undefined;
+            noVideoReplies?: boolean | undefined;
+            noSpoilerReplies?: boolean | undefined;
+            noImageReplies?: boolean | undefined;
+            noReplyLinks?: boolean | undefined;
+            noPolls?: boolean | undefined;
+            noCrossposts?: boolean | undefined;
+            noNestedReplies?: boolean | undefined;
+            safeForWork?: boolean | undefined;
+            authorFlairs?: boolean | undefined;
+            requireAuthorFlairs?: boolean | undefined;
+            postFlairs?: boolean | undefined;
+            requirePostFlairs?: boolean | undefined;
+            noMarkdownImages?: boolean | undefined;
+            noMarkdownVideos?: boolean | undefined;
+            noMarkdownAudio?: boolean | undefined;
+            noAudio?: boolean | undefined;
+            noAudioReplies?: boolean | undefined;
+            markdownImageReplies?: boolean | undefined;
+            markdownVideoReplies?: boolean | undefined;
+            noPostUpvotes?: boolean | undefined;
+            noReplyUpvotes?: boolean | undefined;
+            noPostDownvotes?: boolean | undefined;
+            noReplyDownvotes?: boolean | undefined;
+            noUpvotes?: boolean | undefined;
+            noDownvotes?: boolean | undefined;
+            requirePostLink?: boolean | undefined;
+            requirePostLinkIsMedia?: boolean | undefined;
+            requireReplyLink?: boolean | undefined;
+            requireReplyLinkIsMedia?: boolean | undefined;
+            pseudonymityMode?: "per-post" | "per-reply" | "per-author" | undefined;
+        } | undefined;
+        suggested?: {
+            [x: string]: unknown;
+            primaryColor?: string | undefined;
+            secondaryColor?: string | undefined;
+            avatarUrl?: string | undefined;
+            bannerUrl?: string | undefined;
+            backgroundUrl?: string | undefined;
+            language?: string | undefined;
+        } | undefined;
+        flairs?: Record<string, {
+            [x: string]: unknown;
+            text: string;
+            backgroundColor?: string | undefined;
+            textColor?: string | undefined;
+            expiresAt?: number | undefined;
+        }[]> | undefined;
+    };
+    cid: string;
+}>;
 export declare function publishCommunityRecordWithExtraProp(opts?: {
     includeExtraPropInSignedPropertyNames: boolean;
     extraProps: Object;
@@ -212,6 +538,9 @@ export declare function publishCommunityRecordWithExtraProp(opts?: {
     ipnsObj: {
         signer: import("../signer/index.js").SignerWithPublicKeyAddress;
         publishToIpns: (content: string) => Promise<void>;
+        publishToIpnsValue: (value: string, opts?: {
+            verifyResolves?: boolean;
+        }) => Promise<void>;
         pkc: PKC;
     };
 }>;
@@ -533,6 +862,9 @@ export declare function createMockedCommunityIpns(communityOpts: CreateNewLocalC
     ipnsObj: {
         signer: import("../signer/index.js").SignerWithPublicKeyAddress;
         publishToIpns: (content: string) => Promise<void>;
+        publishToIpnsValue: (value: string, opts?: {
+            verifyResolves?: boolean;
+        }) => Promise<void>;
         pkc: PKC;
     };
 }>;
@@ -546,7 +878,7 @@ export declare function createStaticCommunityRecordForComment(opts?: {
     commentCid: string;
     communityAddress: string;
 }>;
-export declare function jsonifyCommunityAndRemoveInternalProps(community: RemoteCommunity): Omit<any, "signer" | "state" | "clients" | "settings" | "updatingState" | "startedState" | "editable" | "started">;
+export declare function jsonifyCommunityAndRemoveInternalProps(community: RemoteCommunity): Omit<any, "signer" | "state" | "clients" | "settings" | "updatingState" | "ipnsHops" | "startedState" | "editable" | "started">;
 export declare function jsonifyLocalCommunityWithNoInternalProps(community: LocalCommunity): Omit<{
     address: string;
     publicKey?: string | undefined;
@@ -632,6 +964,7 @@ export declare function jsonifyLocalCommunityWithNoInternalProps(community: Loca
     readonly updatingState: RemoteCommunity["updatingState"];
     raw: RpcLocalCommunity["raw"];
     updateCid?: string | undefined;
+    ipnsHops?: string[] | undefined;
     startedState: import("../community/types.js").CommunityStartedState;
     editable: Pick<RpcLocalCommunity, keyof import("../community/types.js").CommunityEditOptions>;
     started: boolean;

package/dist/node/test/test-util.js

@@ -1193,8 +1193,14 @@ export async function createNewIpns() {
         url: pkc.kuboRpcClientsOptions[0].url.toString(),
         headers: pkc.kuboRpcClientsOptions[0].headers
     });
-    const publishToIpns = async (content) => {
-        const cid = await addStringToIpfs(content);
+    // Publishes an arbitrary IPNS value under this signer's key. `value` may be a bare CID,
+    // an "/ipfs/<cid>" path, or an "/ipns/<name>" path (the latter creates a recursive/
+    // delegated IPNS record). Records are published with allowOffline: true. `verifyResolves`
+    // ONLY controls the helper's own post-publish name.resolve() sanity check (which syncs Kubo's
+    // cache for RPC tests) — it does NOT change what name.publish does. Set it false when
+    // publishing a hop whose target isn't resolvable yet, so that resolve check doesn't fail.
+    const publishToIpnsValue = async (value, opts) => {
+        const verifyResolves = opts?.verifyResolves ?? true;
         // Wrapped in retry because Kubo can transiently ETIMEDOUT in CI
         await new Promise((resolve, reject) => {
             const operation = retry.operation({
@@ -1204,7 +1210,7 @@ export async function createNewIpns() {
             });
             operation.attempt(async () => {
                 try {
-                    await ipfsClient._client.name.publish(cid, {
+                    await ipfsClient._client.name.publish(value, {
                         key: signer.address,
                         allowOffline: true
                     });
@@ -1217,10 +1223,12 @@ export async function createNewIpns() {
                 }
             });
         });
+        if (!verifyResolves)
+            return;
         // Verify the IPNS record is resolvable before returning
         // This ensures Kubo's cache is properly synced for RPC tests
         // Wrapped in retry because Kubo can transiently ETIMEDOUT in CI
-        const resolvedCid = await new Promise((resolve, reject) => {
+        await new Promise((resolve, reject) => {
             const operation = retry.operation({
                 retries: 3,
                 factor: 2,
@@ -1245,12 +1253,70 @@ export async function createNewIpns() {
             });
         });
     };
+    const publishToIpns = async (content) => {
+        const cid = await addStringToIpfs(content);
+        await publishToIpnsValue(cid);
+    };
     return {
         signer,
         publishToIpns,
+        publishToIpnsValue,
         pkc
     };
 }
+// Builds a DELEGATED community IPNS chain for tests, mirroring issue #93 (delegated IPNS
+// publishing): an anchor IPNS name (An) whose record points to a minter IPNS name (Mn),
+// whose record points to the /ipfs/ CID of a community record signed by Mn. Clients load
+// the anchor (An) but the content is signed by the terminal/minter key (Mn).
+// See docs/protocol/delegated-ipns.md. Note: delegate-side publishing is NOT part of pkc-js,
+// so this helper constructs the chain directly via kubo.
+export async function createDelegatedCommunityIpns(communityOpts, opts) {
+    // anchor (owner) keypair (An)
+    const anchor = await createNewIpns();
+    // optional intermediate delegate keypairs: anchor -> intermediate[0] -> ... -> minter
+    const intermediates = [];
+    for (let i = 0; i < (opts?.intermediateHopsCount ?? 0); i++)
+        intermediates.push(await createNewIpns());
+    // minter (terminal delegate) keypair (Mn) — signs the content
+    const minter = await createNewIpns();
+    // ordered chain [anchor, ...intermediates, minter]
+    const chain = [anchor, ...intermediates, minter];
+    try {
+        const communityRecord = {
+            ...(await getTemplateCommunityRecord(anchor.pkc)),
+            posts: undefined,
+            pubsubTopic: minter.signer.address,
+            ...communityOpts
+        };
+        if (!communityRecord.posts)
+            delete communityRecord.posts;
+        // content is signed by the MINTER key (Mn) by default — the terminal of the chain. A test
+        // may override contentSigner to simulate a record whose signer is NOT the terminal key.
+        communityRecord.signature = await signCommunity({ community: communityRecord, signer: opts?.contentSigner ?? minter.signer });
+        const communityRecordJson = JSON.stringify(communityRecord);
+        const cid = await addStringToIpfs(communityRecordJson);
+        // Publish TERMINAL-FIRST so each hop's target already resolves before its parent is
+        // published — this keeps the reliable verifyResolves path for every hop:
+        //   minter -> /ipfs/<cid>, then each node -> /ipns/<next node>, finally anchor -> /ipns/<first delegate>.
+        await minter.publishToIpnsValue(cid);
+        for (let i = chain.length - 2; i >= 0; i--)
+            await chain[i].publishToIpnsValue(`/ipns/${chain[i + 1].signer.address}`);
+        return {
+            anchorName: anchor.signer.address, // == community.publicKey / user-facing identity (An)
+            terminalName: minter.signer.address, // signs the content (Mn)
+            intermediateNames: intermediates.map((node) => node.signer.address),
+            ipnsHops: chain.map((node) => node.signer.address), // [anchor, ...intermediates, terminal]
+            communityRecord,
+            cid
+        };
+    }
+    finally {
+        // The records now live on the kubo node; the helper PKCs are no longer needed. Destroy them
+        // even if signing/publishing threw, otherwise their Kubo/libp2p handles leak.
+        for (const node of chain)
+            await node.pkc.destroy();
+    }
+}
 async function getTemplateCommunityRecord(pkc) {
     const community = await pkc.createCommunity({ address: "12D3KooWANwdyPERMQaCgiMnTT1t3Lr4XLFbK1z4ptFVhW2ozg1z" });
     await community.update();
@@ -1373,7 +1439,22 @@ export function jsonifyCommunityAndRemoveInternalProps(community) {
     }
     _stripNameResolvedFromPages(jsonfied["posts"]);
     _stripNameResolvedFromPages(jsonfied["modQueue"]);
-    return remeda.omit(jsonfied, ["startedState", "started", "signer", "settings", "editable", "clients", "updatingState", "state"]);
+    // ipnsHops records the IPNS delegation chain traversed to RESOLVE a community, so it only exists
+    // on a freshly-resolved remote instance — a local community (which owns the keys and publishes
+    // rather than resolves) and a not-yet-resolved instance legitimately have none. It is a runtime
+    // resolution artifact (a CommunityIpfs reserved field, like nameResolved), so strip it before
+    // comparing community content/identity. See docs/protocol/delegated-ipns.md.
+    return remeda.omit(jsonfied, [
+        "ipnsHops",
+        "startedState",
+        "started",
+        "signer",
+        "settings",
+        "editable",
+        "clients",
+        "updatingState",
+        "state"
+    ]);
 }
 export function jsonifyLocalCommunityWithNoInternalProps(community) {
     const localJson = JSON.parse(JSON.stringify(community));