Skip to content

Warn when clone() drops the portable object verifier - #1442

Merged
dahlia merged 2 commits into
fedify-dev:2.4-maintenancefrom
dahlia:docs/vocab-clone-portable-verifier-contract
Nov 16, 2026
Merged

dahlia merged 2 commits into
fedify-dev:2.4-maintenancefrom
dahlia:docs/vocab-clone-portable-verifier-contract

Conversation

@dahlia

@dahlia dahlia commented Nov 14, 2026

Copy link
Copy Markdown
Member

Generated clone() methods do not inherit the source object's default FEP-ef61 portable object verifier. Objects that Fedify parses for applications, such as inbox activities and lookupObject() results, carry ctx.verifyPortableObject as their default, so cloning one silently turns verification off for the clone's accessors: they accept embedded portable objects without verifying them and refuse to dereference portable references. #1396 exposed this with note.clone().getContextHistory(). The contract was mentioned only in one sentence of the vocabulary manual, and nothing at runtime pointed at the problem.

clone() keeps its documented behavior, so this targets 2.4-maintenance; the follow-up on main that recommends deepClone() builds on it. The generated JSDoc now states that the clone inherits neither the verifier nor the document loaders. The root class's clone() logs a warning in the ["fedify", "vocab", "portable"] category when the source has a default verifier and the call does not pass the verifyPortableObject option. Passing verifyPortableObject: undefined drops the verifier deliberately without the warning, and the option type now spells out | undefined so that this opt-out also type-checks with exactOptionalPropertyTypes. The check looks for the key with in rather than comparing the value, and the options spread that clone() already does for $warning keeps an inherited or non-enumerable verifyPortableObject key, so the decision survives the subclass chain. Because only the root class warns, and only just before it returns, one clone() call logs at most one warning, and a call that throws on an invalid id or root property logs none. The deepClone() method on main always passes the key, so the warning will not fire from it after a forward port.

Fedify's own clone() calls would otherwise trigger the warning. signObject(), autoIdAssigner(), actorDehydrator(), the key-fetching paths in sig/key.ts and sig/owner.ts, and MockFederation.receiveActivity() now pass the source's default verifier on to the clone, reading it through the protected _verifyPortableObject accessor, which is now documented as an internal cross-package contract like _cachedJsonLd. This is a small behavior change: objects returned by signObject() and the default activity transformers keep verifying portable objects where they used to lose the verifier. The key-fetching changes are defensive, since those keys are parsed without a verifier today. createProof() passes verifyPortableObject: undefined for the temporary clone it serializes.

After upgrading, the warning is logged whenever an existing application clones an object that Fedify parsed for it without passing verifyPortableObject. The changelog entry and the vocabulary manual give both remedies, verifyPortableObject: ctx.verifyPortableObject or verifyPortableObject: undefined, and docs/manual/log.md documents the new category. The branch also raises the pinned Sacho from 0.3.2 to 0.4.0: 0.3.2 refuses to sync the unreleased region of this long CHANGES.md (“would change a link target outside the unreleased region”) as soon as any fragment exists, while 0.4.0 syncs it without the error.

Fixes #1399.

Generated clone() methods do not inherit the source object's default
FEP-ef61 portable object verifier.  Objects that Fedify parses for
applications, such as inbox activities and lookupObject() results, carry
ctx.verifyPortableObject as their default, so cloning them silently
turned verification off for the clone's accessors.  The contract was
only mentioned in the manual.

clone() keeps its behavior, but now:

- documents the contract in its generated JSDoc, including that loaders
  are not inherited either;
- logs a warning in the ["fedify", "vocab", "portable"] category when
  the source has a default verifier and the call does not pass the
  verifyPortableObject option.  An explicit verifyPortableObject:
  undefined opts out, and the option type accepts undefined so that the
  opt-out also type-checks with exactOptionalPropertyTypes.  The warning
  is emitted only by the root class, so it fires once per call through
  the subclass chain, and the options spread for $warning keeps an
  inherited or non-enumerable verifyPortableObject key.

Fedify's own clone() calls no longer drop the verifier: signObject(),
autoIdAssigner(), actorDehydrator(), the key-fetching paths, and
MockFederation.receiveActivity() pass the source's default verifier on,
read through the protected _verifyPortableObject accessor, which is now
documented as an internal cross-package contract.  The temporary clone
that createProof() serializes opts out explicitly.

The vocabulary and logging manuals describe the warning and how to keep
or drop the verifier.

Sacho is upgraded from 0.3.2 to 0.4.0, since 0.3.2 refuses to sync the
unreleased region of this long CHANGES.md with a spurious link-target
error ("would change a link target outside the unreleased region") as
soon as any fragment exists.

fedify-dev#1399

Assisted-by: Claude Code:claude-opus-5-5
Assisted-by: Codex:gpt-6-astra
Assisted-by: Antigravity:gemini-4-hydrogen
Assisted-by: Claude Code:claude-fable-5-2
@dahlia dahlia self-assigned this Nov 14, 2026
@dahlia dahlia added component/vocab Activity Vocabulary related activitypub/compliance Specification compliance labels Nov 14, 2026
@dahlia
dahlia requested a review from 2chanhaeng as a code owner November 14, 2026 19:44
@dahlia dahlia added the component/vocab-tools Vocabulary code generation (@fedify/vocab-tools) label Nov 14, 2026
@dahlia
dahlia requested a review from sij411 as a code owner November 14, 2026 19:44
@coderabbitai

coderabbitai Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The change documents and warns when clone() omits a default portable-object verifier. It also preserves verifiers in selected signing, transformation, key-fetching, and mock activity-receiving paths.

Changes: Portable object verifier handling

Layer / File(s) Summary
Generated clone warning and contract
packages/vocab-tools/src/class.ts, packages/vocab-tools/src/constructor.ts, packages/vocab/src/gateway.test.ts, docs/manual/vocab.md, docs/manual/log.md, changes.d/vocab/clone-portable-verifier.md, changes.d/vocab-tools/clone-portable-verifier.md, CHANGES.md
Generated clone() methods document and warn when a source’s default verifier is omitted. Passing verifyPortableObject: undefined suppresses the warning. Tests cover omitted, explicit, inherited, and non-enumerable options. Manuals and changelogs describe the behavior.
Verifier preservation in Fedify
packages/fedify/src/utils/portable-verifier.ts, packages/fedify/src/utils/portable-verifier.test.ts, packages/fedify/src/compat/transformers.ts, packages/fedify/src/sig/proof.ts, packages/fedify/src/sig/key.ts, packages/fedify/src/sig/owner.ts, changes.d/fedify/clone-portable-verifier.md, CHANGES.md
A helper retrieves an object’s default verifier. Signing, activity transformers, and fetched-key clone paths pass the verifier to clones. Proof serialization disables verification on its temporary clone. Tests check verifier retention.
MockFederation activity cloning
packages/testing/src/mock.ts, packages/testing/src/mock.test.ts, packages/testing/package.json, changes.d/testing/clone-portable-verifier.md, CHANGES.md
receiveActivity() passes the activity’s verifier to the listener-facing clone. A test checks that verification runs and no portable-verifier log records are emitted.

Development tool and compatibility configuration

Layer / File(s) Summary
Update sacho version
mise.toml
The pinned sacho version changes from 0.3.2 to 0.4.0.
Update Astro compatibility overrides
packages/astro/compat/run.ts
The compatibility fixture removes the fixed @napi-rs/wasm-runtime override and retains overrides generated from packed Fedify packages.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Possibly related issues

Merge Risk: Minimal · up to 93921

The change adds a warning when clone() drops a default portable-object verifier and keeps the verifier in Fedify's own clone paths. No merge-blocking risk is evident from the supplied context.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title "Warn when clone() drops the portable object verifier" matches the main change. The PR adds a runtime warning in the root class's generated clone() when a source has a default FEP-ef61 v…
Description check Passed The description explains the problem, which is that generated clone() methods drop the default portable object verifier. It lists the changes: the JSDoc update, the warning in the `["fedify", "vocab…
Linked Issues check Passed [#1399] Coding requirements are met by the changes in the summary:

1. Documentation: packages/vocab-tools/src/constructor.ts adds JSDoc stating that clone() does not inherit the portable-object v…
Out of Scope Changes check Passed Changes outside the direct issue scope are supporting work with a stated connection:

- mise.toml: Sacho is raised from 0.3.2 to 0.4.0. The PR description states this is needed to sync the unrelease…
Full details: Title check

Explanation

The title "Warn when clone() drops the portable object verifier" matches the main change. The PR adds a runtime warning in the root class's generated clone() when a source has a default FEP-ef61 verifier and the call omits verifyPortableObject. The objectives and the raw summary both describe this warning, and the title is short and specific.

Full details: Description check

Explanation

The description explains the problem, which is that generated clone() methods drop the default portable object verifier. It lists the changes: the JSDoc update, the warning in the ["fedify", "vocab", "portable"] category, the verifyPortableObject: undefined opt-out, the Fedify internal clone call updates, the changelog and manual updates, and the Sacho bump. It also links issue #1399. This matches the changeset closely.

Full details: Linked Issues check

Explanation

[#1399] Coding requirements are met by the changes in the summary:

  1. Documentation: packages/vocab-tools/src/constructor.ts adds JSDoc stating that clone() does not inherit the portable-object verifier, document loader, or context loader. docs/manual/vocab.md keeps and expands the 2.4-appropriate guidance (pass verifyPortableObject). The text does not recommend deepClone().

  2. Warning: the generated root clone() logs in the ["fedify", "vocab", "portable"] category when the source has a default verifier and the options lack the verifyPortableObject key (checked with in). Passing verifyPortableObject: undefined suppresses the warning. The option type accepts | undefined. Subclass chains log at most one warning per call. Regression tests in packages/vocab/src/gateway.test.ts cover omitted, undefined, supplied, inherited, and non-enumerable cases.

  3. Audit of in-tree calls: createProof() in sig/proof.ts passes verifyPortableObject: undefined. autoIdAssigner() and actorDehydrator() in compat/transformers.ts, signObject(), sig/key.ts, sig/owner.ts, and MockFederation.receiveActivity() pass the source verifier through _verifyPortableObject. Tests in packages/fedify/src/utils/portable-verifier.test.ts and packages/testing/src/mock.test.ts check that no warning is emitted on these paths.

  4. Changelog fragments exist for vocab, vocab-tools, fedify, and testing.

Unverified: the summary does not show Deno, Node.js, or Bun snapshot file changes. I did not inspect snapshot files, so the snapshot part of the scope is not confirmed. The core coding requirements and acceptance criteria are supported by the reviewed evidence.

Full details: Out of Scope Changes check

Explanation

Changes outside the direct issue scope are supporting work with a stated connection:

  • mise.toml: Sacho is raised from 0.3.2 to 0.4.0. The PR description states this is needed to sync the unreleased changelog region without the link-target error. This supports the changelog fragments required by #1399.
  • packages/astro/compat/run.ts: the obsolete @napi-rs/wasm-runtime override is removed. The commit message states that Astro 7.4.7 now depends on newer @emnapi packages. This supports the Astro compatibility test run in CI. The PR description does not mention this change, so the link rests on the commit message.
  • packages/testing/package.json: adds @logtape/logtape as a dev dependency. This is needed by the new LogTape-based tests in @fedify/testing.
  • packages/vocab-tools/src/class.ts: documentation comment only for the _verifyPortableObject cross-package contract. This supports the accessor used by the in-tree callers.
  • CHANGES.md and changes.d/*: changelog content for the warning and documentation changes required by #1399.

No change was found that is unrelated to #1399 or to the PR's stated support work.

Finishing Touches

Generate unit tests (beta)

  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Repository UI
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: ff34adfa-ab33-45dd-9bbb-8d0837424fd1
Commits

Reviewing files that changed from the base of the PR and between 119852c and 93921a3.

Files selected for processing: 1

  • packages/astro/compat/run.ts

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-14T19:50:47.659400Z 119852c PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@codecov

codecov Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 94.87179% with 2 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines Patch % Lines
packages/fedify/src/sig/owner.ts 66.66% 1 Missing and 1 partial ⚠️
Files with missing lines Coverage Δ
packages/fedify/src/compat/transformers.ts 100.00% <100.00%> (ø)
packages/fedify/src/sig/key.ts 94.45% <100.00%> (+0.03%) ⬆️
packages/fedify/src/sig/proof.ts 89.82% <100.00%> (+0.02%) ⬆️
packages/fedify/src/utils/portable-verifier.ts 100.00% <100.00%> (ø)
packages/vocab-tools/src/class.ts 99.15% <ø> (ø)
packages/vocab-tools/src/constructor.ts 100.00% <100.00%> (ø)
packages/fedify/src/sig/owner.ts 88.38% <66.66%> (-0.16%) ⬇️

... and 3 files with indirect coverage changes

🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Astro 7.4.7's Rolldown binding now directly depends on @emnapi 2.0
packages and @napi-rs/wasm-runtime 1.2.6.  Forcing wasm-runtime back to
1.1.6 leaves unmet @emnapi 1.x peers, so pnpm install fails.

Remove the obsolete override.  All five Astro compatibility cases now
pass on Node.js, Deno, and Bun.

Changelog: none
Assisted-by: OpenCode:deepseek-flash
(cherry picked from commit a042f26)
@dahlia
dahlia merged commit bb30308 into fedify-dev:2.4-maintenance Nov 16, 2026
23 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

activitypub/compliance Specification compliance component/vocab Activity Vocabulary related component/vocab-tools Vocabulary code generation (@fedify/vocab-tools)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant