Skip to content

Add missing CID return arrows in IPFS/IPNS sequence diagrams#6

Merged
FSM1 merged 2 commits into
feat/spec-hardeningfrom
copilot/sub-pr-4-again
Jan 18, 2026
Merged

Add missing CID return arrows in IPFS/IPNS sequence diagrams#6
FSM1 merged 2 commits into
feat/spec-hardeningfrom
copilot/sub-pr-4-again

Conversation

Copilot AI commented Jan 18, 2026

Copy link
Copy Markdown
Contributor

Sequence diagrams showed the Backend adding metadata to IPFS but omitted the return arrow sending the CID back to the Client. This masked a critical dependency: the Client needs the CID to construct the IPNS record it signs in the next step.

Changes

  • Added B->>C: Return CID after all B->>IPFS: Add metadata, return CID operations across 8 sequence diagrams
  • Affected flows: File Upload, Create Folder (2 instances), Rename, Move (2 instances), Delete, Update File Content
  • Bumped documentation version 1.8.1 → 1.8.2

Example

Before:

C->>B: POST /ipfs/add (encrypted metadata)
B->>IPFS: Add metadata, return CID
C->>C: Sign IPNS record (Ed25519)  # Where does C get the CID?
C->>B: POST /ipns/publish (signed record)
Loading

After:

C->>B: POST /ipfs/add (encrypted metadata)
B->>IPFS: Add metadata, return CID
B->>C: Return CID
C->>C: Sign IPNS record (Ed25519)
C->>B: POST /ipns/publish (signed record)
Loading

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Added `B->>C: Return CID` after all `B->>IPFS: Add metadata, return CID` operations to show that the Backend returns the CID to the Client before the Client signs the IPNS record. The Client needs this CID to create the IPNS record that points to it.

Updated 8 sequence diagrams:
- File Upload Flow (IPNS publish)
- Create Folder (empty folder + update parent)
- Rename File/Folder
- Move File/Folder (destination + source)
- Delete File
- Update File Content

Bumped version to 1.8.2

Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>
Copilot AI changed the title [WIP] Update IPFS/IPNS relay endpoint details based on feedback Add missing CID return arrows in IPFS/IPNS sequence diagrams Jan 18, 2026
Copilot AI requested a review from FSM1 January 18, 2026 01:03
@FSM1 FSM1 marked this pull request as ready for review January 18, 2026 01:05
@FSM1 FSM1 merged commit f66783b into feat/spec-hardening Jan 18, 2026
@FSM1 FSM1 deleted the copilot/sub-pr-4-again branch January 18, 2026 01:05
FSM1 added a commit that referenced this pull request Jan 18, 2026
* bump version to 1.8.1 and update documentation for IPFS/IPNS relay integration

* Fix date inconsistency in TECHNICAL_ARCHITECTURE.md (#7)

* Initial plan

* Fix date inconsistency in TECHNICAL_ARCHITECTURE.md

Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

* Fix date inconsistency in DATA_FLOWS.md frontmatter (#8)

* Initial plan

* Fix date inconsistency in DATA_FLOWS.md frontmatter

Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

* Add missing CID return arrows in IPFS/IPNS sequence diagrams (#6)

* Initial plan

* Add missing return arrows in IPFS/IPNS sequence diagrams

Added `B->>C: Return CID` after all `B->>IPFS: Add metadata, return CID` operations to show that the Backend returns the CID to the Client before the Client signs the IPNS record. The Client needs this CID to create the IPNS record that points to it.

Updated 8 sequence diagrams:
- File Upload Flow (IPNS publish)
- Create Folder (empty folder + update parent)
- Rename File/Folder
- Move File/Folder (destination + source)
- Delete File
- Update File Content

Bumped version to 1.8.2

Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

* Add missing Backend→Client CID return flows in IPFS/IPNS sequence diagrams (#5)

* Initial plan

* Add return arrows from Backend to Client in IPFS/IPNS sequence diagrams

Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

* Add missing Backend→Client CID return arrows in IPFS sequence diagrams (#10)

* Initial plan

* Add missing Backend->Client CID return arrows in sequence diagrams

Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

* Add missing CID return step in IPNS publish sequence diagrams (#16)

* Initial plan

* Add missing return CID step in IPNS publish sequences

Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

* Fix date inconsistency in API_SPECIFICATION.md (#14)

* Initial plan

* Fix date inconsistency in API_SPECIFICATION.md

Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

* Fix missing YAML frontmatter delimiter in API_SPECIFICATION.md (#15)

* Initial plan

* Fix YAML frontmatter: add missing opening delimiter to API_SPECIFICATION.md

Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

* Fix missing Backend→Client CID return in IPFS/IPNS sequence diagrams (#11)

* Initial plan

* Fix sequence diagrams: add missing Backend->Client CID return arrows

Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

* Fix missing return arrow in IPNS publishing sequence diagram (#13)

* Initial plan

* Add missing return arrow in IPNS publishing sequence diagram

Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

* Fix date inconsistency in CLIENT_SPECIFICATION.md (#9)

* Initial plan

* Fix date inconsistency in CLIENT_SPECIFICATION.md

Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

* Add missing Backend→Client CID return flows in IPFS metadata upload sequences (#12)

* Initial plan

* Add missing return arrows showing CID returned from backend to client after IPFS metadata upload

Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

* Fix documentation inconsistencies and clarify IPFS/IPNS relay architecture (#17)

* Initial plan

* Fix all PR review feedback items

Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

* Improve documentation clarity per code review feedback

Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

* Add BASE64 encoding steps in IPNS publish sequences and bump to v1.9.0 (#18)

* Initial plan

* Add BASE64 encoding steps in IPNS sequences and bump version to 1.9.0

Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

* Fix inconsistent indentation in mermaid sequence diagrams (#19)

* Initial plan

* Fix mermaid diagram indentation to use consistent 4-space formatting

Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: FSM1 <12774278+FSM1@users.noreply.github.com>

---------

Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
FSM1 added a commit that referenced this pull request May 25, 2026
- Scope Tauri events per attempt via port-specific event names (review #1)
- Validate POST requests with server-generated nonce (review #2)
- Use absolute deadline instead of per-connection timeout (review #3)
- Use actual popup counter value for cleanup (review #4)
- Fail fast when all preferred ports are taken (review #6)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Entire-Checkpoint: 172d4ce72f72
FSM1 added a commit that referenced this pull request May 25, 2026
…#459)

* fix(desktop): use localhost callback server for Google OAuth in Tauri

Google OAuth rejects custom URI schemes like `tauri://localhost` which
is what `window.location.origin` resolves to in production Tauri builds.
This caused Error 400: invalid_request when attempting Google login.

Replace the localStorage-polling approach with a temporary localhost HTTP
server (Rust-side) that receives the OAuth redirect, extracts the id_token
from the URL fragment via an injected callback page, and emits it back to
the main webview via a Tauri event.

- Add `start_oauth_server` Tauri command with preferred port selection
  (14200-14202) and random fallback
- Rewrite `getGoogleCredential()` to use the callback server + Tauri
  event listener instead of localStorage polling
- Add `core:event:default` permission for Tauri event API access
- Content-Length-aware HTTP body reading for reliable POST parsing

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Entire-Checkpoint: 51734dbce9b4

* chore(release): set release targets for PR #459

* fix(desktop): address PR review comments on OAuth callback server

- Scope Tauri events per attempt via port-specific event names (review #1)
- Validate POST requests with server-generated nonce (review #2)
- Use absolute deadline instead of per-connection timeout (review #3)
- Use actual popup counter value for cleanup (review #4)
- Fail fast when all preferred ports are taken (review #6)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Entire-Checkpoint: 172d4ce72f72

* docs: implement temporary localhost HTTP server for Google OAuth callback in Tauri

Entire-Checkpoint: ac0f39da9ff3

* fix(desktop): address second round of PR review comments

- Update JSDoc to reflect fixed-port strategy (no dynamic/loopback)
- Validate OAuth state before handling errors (prevents DoS via crafted error)
- Loop-read TCP until headers are complete before parsing Content-Length
- Update debug doc to match current implementation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Entire-Checkpoint: 72dff9156bda

* fix(desktop): address CodeRabbit review on OAuth callback server

- Move cleanup() after state validation to prevent promise hang on mismatch
- Use OsRng (CSPRNG) instead of thread_rng for nonce generation
- Remove Access-Control-Allow-Origin: * from GET responses (prevents
  local pages from fetching callback HTML to steal the nonce)
- Close OAuth popup windows on server timeout
- Gate callback HTML serving to /callback path only (404 for others)
- Remove stale review-cycle comment

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Entire-Checkpoint: 60247aaac75c

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
FSM1 added a commit that referenced this pull request Jun 21, 2026
* docs: file resolved hardening todos and add deferred-findings phases 56-58

Bookkeeping (verified against live code via parallel review agents):
- File #5 IPNS S1/S2/S3 review to completed/ (bulk shipped in PR #529); residue tracked by phase 58 todos.
- File #10 large-file refactor survey to completed/ (Tier-1/2 shipped in PR #538); re-capture the 14 open Tier-3 items.
- Fold the per-file-IPNS-conflict todo into the PR #538 robustness todo (one unified site post-#538) and file to completed/.
- Trim the metadata zeroize todo to its one remaining helper (spawn_metadata_publish).

New phases via gsd-tools phase.add (HARD-07..09):
- 56 FUSE & IPNS Durability Hardening — PR #538 deferred findings.
- 57 API CID/Provider Hardening & Module Dedup.
- 58 IPNS Signature-Verify Coverage — Phase 51 / PR #529 S1/S2 residue.

Update ROADMAP (sections, progress table, execution order), REQUIREMENTS (HARD-07..09 + traceability), and STATE body. STATE frontmatter progress counts left unreconciled (pre-existing drift, todo #6).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Entire-Checkpoint: f7d4c3a60cd5

* docs(56): capture phase context

Entire-Checkpoint: bd91ecff0d20

* docs(state): record phase 56 context session

Entire-Checkpoint: e93a1c24b15f

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
FSM1 added a commit that referenced this pull request Jun 30, 2026
#6 fail closed when unsealed node has no recoverable write body, preventing
a read-only node from being promoted to write-capable without key proof.

#2+#7 zero each child newWriteKey immediately after sealChildWriteKey (inline
in the map callback) and add a post-Promise.all defensive sweep for any
unclaimed child results — D-09 terminal-owner rule.

#8 check createAndPublishIpnsRecord return value success flag before firing
tombstones or grant mutations so a non-throwing rejection cannot leave the
write plane inconsistent.

#9 assert rootResult.nodeId matches caller-supplied rootNodeId before grant
mutations to prevent rewrapping grants for a different node.

#10 wrap tombstone and grant callbacks in try/finally so the root write key
is zeroed even when a callback throws — D-09 terminal-owner rule.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
FSM1 added a commit that referenced this pull request Jun 30, 2026
#583)

* docs(65): capture phase context

Entire-Checkpoint: aed8bf6fa830

* docs(state): record phase 65 context session

Entire-Checkpoint: f49b3b2fe198

* docs(phase-65): research write-chain, bin re-link, and invite claim

Entire-Checkpoint: ef5c6ef6e756

* docs(65): add validation strategy

Entire-Checkpoint: fe7e071404d5

* docs(65): map phase patterns

Entire-Checkpoint: 3c9673822b65

* docs(65): create phase 65 write-chain plan (7 plans, 4 waves)

WRITE-01 write-body Ed25519 under writeKey (role 0x04), WRITE-02 full
Ed25519 write-revocation (child-first cascade), WRITE-03 co-writer
re-wrap + offline error, WRITE-04 tombstone-intent; bin re-link +
invite re-wrap (Success Criterion 4). Mock-seam discipline (D-02);
sdk-e2e round-trip gate (D-04). OQ-1 (BinEntry.nodeReadKey) and OQ-2
(child-first cascade) resolved.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NUSYqMyCLbNGDLcn1cp1eh
Entire-Checkpoint: 9638c8677236

* docs(65): address plan-checker warnings — surface e2e typecheck and mark research OQs resolved

Entire-Checkpoint: e025a94f56f3

* docs(65): record planning complete and annotate roadmap waves

Entire-Checkpoint: 7a6909081de9

* docs(phase-65): begin phase execution tracking

Entire-Checkpoint: 2a373269bfea

* test(65-01): add failing role-0x04 write-chain seal KAT and round-trip

- round-trip: sealChildWriteKey then unsealChildWriteKey recovers 32-byte key
- role isolation: role-0x02 blob rejected by role-0x04 unseal and vice versa
- AAD binding: childId / childKind / childGeneration / wrong key all throw
- terminal-owner: input buffers unchanged after both calls (D-09 / T-65-04)

* feat(65-01): implement sealChildWriteKey and unsealChildWriteKey with role 0x04

- verbatim copy of sealChildReadKey / unsealChildReadKey with role byte 0x02 → 0x04
- AAD: buildNodeAad(childId, kindByte, childGeneration, 0x04) — child-writekey role frozen
- no new imports: reuses sealAesGcmAad / unsealAesGcmAad / buildNodeAad from @cipherbox/crypto
- D-09 terminal-owner: neither function zeros caller-supplied buffers
- exported from packages/core/src/node/index.ts and packages/core/src/index.ts
- all 9 role-0x04 tests green (round-trip, cross-role rejection, AAD-mismatch, terminal-owner)

* test(65-03): add failing claimInvite service-flow test

- RED: claimInvite import fails — function does not exist yet
- Asserts getInviteDataFn called once per claim
- Asserts insertShareFn called once with no encryptedChildKeys
- Asserts two independent claims of same invite yield two separate grants

* docs(65-01): complete plan summary for role-0x04 write-chain seal primitives

* feat(65-03): implement claimInvite service flow and barrel export

- Add claimInvite to packages/sdk-core/src/share/grant.ts composing
  claimInviteReadKey with injected getInviteDataFn and insertShareFn callbacks
- Re-export claimInvite from packages/sdk-core/src/share/index.ts
- One re-wrapped root readKey per claimer, no per-child key fan-out
- Zero sdk-layer consumption of the fan-out path confirmed by grep gate

* docs(65-03): complete invite-claim service flow plan summary

* test(65-02): add failing bin re-link spec for addToBin and restoreFromBin

- add nodeReadKey and nodeIpnsName fields to BinEntry in @cipherbox/core
- un-skip addToBin and restoreFromBin describe blocks
- remove legacy originalFolderKeyEncrypted and FolderChild references
- add 4 addToBin tests covering happy-path, revoke ordering, abort-on-revoke-fail, and not-loaded guard
- add 5 restoreFromBin tests including AEAD asymmetry proof via real sealChildReadKey
- switch vi.mock to importOriginal spread keeping real AES-GCM primitives for asymmetry test

* feat(65-02): implement addToBin and restoreFromBin as pure key re-link

addToBin:
- resolve child IPNS record to extract plaintext PublishedNode id and kind
- unseal nodeReadKey from source parent folderKey via unsealChildReadKey
- revoke shares before destructive folder mutation (fail-closed ordering)
- capture nodeReadKey and nodeIpnsName on BinEntry for restore

restoreFromBin:
- re-seal entry.nodeReadKey under destination folderKey via sealChildReadKey (role 0x02)
- build SealedChildRef with re-linked readKeySealed (no content re-encryption)
- add restored ref to target folder and publish; remove entry from bin

also fix test fixture: use valid UUID for nodeRef.id to satisfy uuidToBytes validator;
replace vi.restoreAllMocks with targeted sealSpy.mockRestore to prevent resetting
module-level vi.fn mocks (deriveBinIpnsKeypair) in subsequent test cases

* docs(65-02): complete bin re-link plan

* docs(phase-65): update tracking after wave 1

Entire-Checkpoint: 02004cb54e8b

* test(65-05): add failing write-body-reseal tests for rotateOne write-plane preservation

- Tests 1-4: assert unsealNode called with nodeWriteKey, sealNode receives real writeKey
  not all-zeros placeholder, writeBody.ipnsPrivateKey preserved post-rotation
- Tests 5-6: fail-closed guard -- writeSealed present without valid writeKey throws
- Test 7: nodeKeySource.writeKey threads through BFS to sealNode
- All 6 write-plane assertions fail RED against placeholder engine

* feat(65-05): thread real writeKey through rotateOne, remove PLACEHOLDER_WRITE_KEY

- Add nodeWriteKey to RotateOneParams and nodeKeySource return type
- unsealNode now called with nodeWriteKey to recover write-body on rotation
- Fail-closed guard: throws when published.writeSealed present but nodeWriteKey
  is absent or all-zeros, mirroring the IPNS-key guard pattern
- writeKeyForReseal = node.writeBody ? nodeWriteKey : empty; used at all three
  sealNode sites: main reseal and both CAS-409 merge paths
- PLACEHOLDER_WRITE_KEY deleted from all three sites
- rotateReadFromNode BFS threads nodeKeySource.writeKey at root, child, grandchild
  and dirty-resume enqueue sites
- Existing IPNS fail-closed guard retained unchanged
- Folds FLAG-63-U1 / rotateone-placeholder-writekey-phase65

* docs(65-05): complete write-body-reseal plan summary

* feat(65-04): implement shared-write on write-body model with WRITE-01 security and WRITE-03 offline error

- Reshape SharedWriteContext: writeKey + readKey + publishedNode replaces raw folderKey and ipnsPrivateKey fields
- Add publishNodeFn and addToIpfsFn transport seams for mock-testable operations
- Add buildChildWriteLink helper sealing child writeKey under parent writeKey via role 0x04
- Add walkChildWriteKey helper walking the write chain via unsealChildWriteKey
- Prove WRITE-01 security: unsealNode without writeKey returns no writeBody; read-only holder cannot reach ipnsPrivateKey
- Prove NODE-03: SealedChildRef carries no write field; write link lives only in parent writeBody.writeChildren
- Implement createSharedSubfolder: mint child keypair, build write-body, seal, publish, add SealedChildRef + WriteChildRef to parent
- Implement uploadToSharedFolder: same pattern for file node with AES-256-GCM content encryption via addToIpfsFn
- Implement renameInSharedFolder: mutate read-body child name, preserve writeChildren, re-publish parent
- Implement deleteFromSharedFolder: remove from children and writeChildren by IPNS name, re-publish parent
- Implement updateSharedFile: caller-supplied fileReadKey + fileWriteKey + fileIpnsPrivateKey, re-seal + re-publish
- Implement moveInSharedFolder: re-seal child readKey under dest readKey via sealChildReadKey, walk write chain for writeKey re-link
- Add CannotWriteUntilRefetchError with stable code CANNOT_WRITE_UNTIL_REFETCH for tombstoned publish targets
- addShareKeysFn never invoked across all six operations
- All 29 shared-write tests pass including WRITE-01 security, write-link round-trip, and WRITE-03 tombstone tests

* docs(65-04): fix stale Phase-65 convention comments in shared-write

WriteChildRef.childId is a UUID from crypto.randomUUID matching Node.id,
not the IPNS name. Clarify deleteFromSharedFolder itemId semantics and
remove incorrect module-header annotation.

* docs(65-04): complete plan 04 shared-write write-body model

* fix(65-04): reconcile client SharedWriteContext consumers with write-body model

* docs(phase-65): update tracking after wave 2

Entire-Checkpoint: 0c43e1d2e603

* test(65-06): add failing write-revocation driver contract test

- Specifies rotateWriteFromNode behavior: per-node new Ed25519 keypair + k51 name + writeKey
- Asserts child-first cascade, first-publish at 1n, tombstone-intent teeUnenrollFn calls
- Asserts co-writer re-wrap via wrapKey and revoked grant drop via deleteWriteGrantFn
- Asserts read-plane invariance: no generation bump, no new readKey minted
- Asserts parent SealedChildRef.ipnsName re-pointed to new child name
- Tests RED because rotateWriteFromNode is not yet exported from rotation engine

* feat(65-06): implement rotateWriteFromNode with child-first write-revocation cascade

- Exports WriteRevocationCallbacks type and rotateWriteFromNode function from rotation engine
- Child-first bottom-up traversal: leaves get new Ed25519 keypair + k51 name + writeKey first
- First-publishes each new k51 name at sequenceNumber 1n via createAndPublishIpnsRecord
- Fires teeUnenrollFn for each old name after the new name is published
- Re-seals write-body with new ipnsPrivateKey and re-pointed writeChildren under new parent writeKey
- Updates parent SealedChildRef.ipnsName to new child name while leaving readKeySealed unchanged
- Handles co-writer grants: wrapKey for survivors, deleteWriteGrantFn for revoked recipients
- Read plane invariant: no readKey minted, no generation bump on any node
- Zeros minted writeKey and Ed25519 seeds on failure paths only (D-09 / Pitfall 4)
- Adds createAndPublishIpnsRecord and sealChildWriteKey/unsealChildWriteKey to engine imports
- All 70 rotation suite tests pass including 8 new write-revocation tests

* docs(65-06): complete write-revocation plan summary

* docs(phase-65): update tracking after wave 3

Entire-Checkpoint: 1669fd50ff58

* feat(65-07): export rotateWriteFromNode and WriteRevocationCallbacks from sdk-core

- Adds rotateWriteFromNode to the sdk-core top-level barrel so the
  sdk-e2e suite can import it via the package name rather than an
  internal subpath (Rule 3 fix: missing export blocked the D-04 gate test)
- Adds WriteRevocationCallbacks type export alongside the function

* test(65-07): add D-04 write-chain rotation E2E suite

- Creates tests/sdk-e2e/src/suites/write-chain-rotation.test.ts as the
  D-04 phase gate for WRITE-02/03/04 against the live docker API stack
- publishWriteCapableNode helper seals folder nodes with real write-bodies
  and first-publishes each new k51 name at sequenceNumber 1n
- Test 1: builds a 2-level subtree (root + child), asserts pre-rotation
  baseline: write-body unseals under writeKey; parent write link unseals
  to child writeKey; generation 0 for both nodes
- Test 2: drives rotateWriteFromNode with vi.fn() callbacks, asserts WRITE-02
  (new k51 names + parent re-point cascade), WRITE-04 (teeUnenrollFn per
  old name), WRITE-03 (survivor re-wrap unwraps with bob private key;
  revoked grant dropped), and read-plane invariance (generation unchanged)
- Derives new IPNS names from captured getRandomValues spy in child-first
  order (child-ed25519, child-writeKey, root-ed25519, root-writeKey)

* docs(65-07): complete write-chain rotation plan summary

* docs(phase-65): update tracking after wave 4

Entire-Checkpoint: c40a8c198c21

* docs(phase-65): complete phase execution

Entire-Checkpoint: 77baeecc7244

* docs(phase-65): close rotateone-placeholder-writekey todo resolved by plan 65-05

Entire-Checkpoint: f69e0ef17961

* docs(phase-66): re-tag bin-pin-leak todo to phase 66 where apps/api/shares is in scope

Entire-Checkpoint: f7bf47fb6251

* docs(65): security audit — all 29 threats closed

Static analysis of Plans 01-07 threat models: 29 mitigations
verified in implementation (seal.ts role-0x04, engine.ts writeKey
threading + PLACEHOLDER removal, shared-write.ts write-body model,
bin/index.ts pure re-link, grant.ts claimInvite). Two accepted risks
(T-65-07 Q3 sub-share, T-65-09 invite link) documented. threats_open=0.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(65): nyquist validation audit — fill coverage map, mark compliant

Retroactive audit of phase 65 validation gaps. Maps all 15 tasks
across 7 plans to their concrete test files and commands. Marks
nyquist_compliant: true; records the one explicitly-deferred item
(WRITE-04 live publish-gate) with Phase 66 evidence.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Entire-Checkpoint: 4f25369a581a

* docs(phase-68): defer shared-write context publishedNode wiring from phase-65 coderabbit review

Entire-Checkpoint: 9406964c08bd

* fix(65): resolve CR cluster-B findings in shared-write

- F1 zeroization: fill(0) minted key buffers before null on success paths
  in createSharedSubfolder, uploadToSharedFolder, and updateSharedFile
- F2 childId alignment: add fileNodeId param to updateSharedFile so
  Node.id stays aligned with WriteChildRef.childId across content updates
- F3 publish order: publish dest before src in moveInSharedFolder so a
  partial failure leaves a duplicate rather than an orphaned item
- F4 sequence number: pass swCtx.sequenceNumber + 1n in
  resealAndPublishParent so parent updates use the correct next sequence
- F5 fail-closed: throw when neither childWriteKey nor a walkable src
  write link is available; zero derived key in finally (D-09)

Tests: update callers for new fileNodeId param; add fail-closed test for
moveInSharedFolder; 36 tests pass (was 35)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(65): fail-closed restoreFromBin and reorder addToBin for atomicity

- restoreFromBin: throw instead of defaulting nodeIpnsName/nodeRef to
  empty values — prevents sealChildReadKey binding to wrong AAD
- addToBin: persist bin entry before the destructive folder publish so
  a failed save cannot orphan the item with no restore key
- grant.ts claimInvite: reject empty/whitespace inviteToken, rootNodeId,
  rootIpnsName before any I/O or crypto work

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(65): make revocation-failure test self-contained

Add setupAddToBinMocks() to stub resolveIpnsRecord and fetchFromIpfs so
the test reaches the revocation step independently of prior test cases.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(65): defer tombstones post-subtree, tighten key lifecycle, fix childKey zeroing

Findings addressed: F5 CRITICAL, F6 major, F7 major, F4 major.

F5: move teeUnenrollFn calls from inside rotateWriteSubtree to after the
full subtree rotation in rotateWriteFromNode. Adds pendingTombstones[]
collection so a failed ancestor publish cannot leave the TEE with a
unenrolled child name the parent still references.

F6: remove unused newIpnsPrivateKey from WriteRotationResult; zero
newKeypair.privateKey immediately after createAndPublishIpnsRecord; zero
rootResult.newWriteKey at end of rotateWriteFromNode after grants loop.

F7: wrap both unsealChildReadKey and unsealChildWriteKey in a single
try/finally so childReadKey is zeroed even when unsealChildWriteKey
throws before childReadKey enters the inner try scope.

F4: change rotateWriteFromNode return type from Promise<void> to
Promise<{ newRootIpnsName: string }> so callers can persist the new
root IPNS pointer alongside the grant descriptor.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(65): add missing core mocks, strengthen write-key assertions in rotation unit tests

Findings addressed: F3 major, F1 minor, F8 minor.

F3: add sealChildWriteKey and unsealChildWriteKey to the @cipherbox/core
mock in write-body-reseal.test.ts so the module does not silently export
undefined for these symbols if the write-rotation code path is hit.

F1: assert sealChildWriteKey call arguments in write-revocation Test 8 --
child write key identity, parent write key shape, and AAD binding args.

F8: strengthen write-body-reseal Test 7 to assert both NODE_WRITE_KEY and
CHILD_WRITE_KEY appear per-node in the BFS; remove the .catch that was
masking rotation errors in GREEN.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(65): zero captured Ed25519 seeds early and verify survivor write key opens write body

Findings addressed: F10 minor, F11 major.

F10: call clearCapturedKeys immediately after deriving new IPNS names so
Ed25519 seed material does not linger in the spy array until afterAll.

F11: after unwrapping the survivor write-descriptor with bob private key,
call unsealNode on the new root with the unwrapped key and assert
writeBody is present; proves the persisted descriptor is the actual new
root write key and not merely some 32-byte value.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(65): defer write-chain e2e seed index-stability hardening from coderabbit review

Entire-Checkpoint: 0a6ec17e80ef

* fix(65): deleteFromSharedFolder write-body filter uses UUID not ipnsName

WriteChildRef.childId is a UUID minted at creation time; filtering by
params.itemId (an IPNS name) never matched, leaving a stale WriteChildRef
that later crashed rotateWriteFromNode.

Add childNodeId param to deleteFromSharedFolder (mirroring moveInSharedFolder)
so read-body is filtered by ipnsName and write-body by UUID.  Also extend
updateSharedFile with optional originalCreatedAt / originalVersions so callers
can preserve immutable metadata; Phase-68 will supply prior values.

Update client.deleteFromSharedFolder signature to thread childNodeId through.
Remove the misleading "childId === ipnsName" module-level comment.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(65): cover write-body WriteChildRef removal on delete

Add a test that seeds the parent write-body with a WriteChildRef, calls
deleteFromSharedFolder with both itemId and childNodeId, then unseals the
republished parent envelope and asserts writeBody.writeChildren is empty.

Extend buildSealedParent to accept optional writeChildren so tests can
seed real write-body state.  Update existing delete tests to supply
the new required childNodeId param.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(65): harden write-rotation engine against security edge cases

#6 fail closed when unsealed node has no recoverable write body, preventing
a read-only node from being promoted to write-capable without key proof.

#2+#7 zero each child newWriteKey immediately after sealChildWriteKey (inline
in the map callback) and add a post-Promise.all defensive sweep for any
unclaimed child results — D-09 terminal-owner rule.

#8 check createAndPublishIpnsRecord return value success flag before firing
tombstones or grant mutations so a non-throwing rejection cannot leave the
write plane inconsistent.

#9 assert rootResult.nodeId matches caller-supplied rootNodeId before grant
mutations to prevent rewrapping grants for a different node.

#10 wrap tombstone and grant callbacks in try/finally so the root write key
is zeroed even when a callback throws — D-09 terminal-owner rule.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(65): harden rotation test hygiene for zeroed buffer handling

#4 remove swallowed .catch handlers in write-body-reseal green-path tests —
RED-phase workaround is no longer needed; let failures surface.

#5 return fresh Uint8Array copies from crypto mocks in write-revocation tests
so engine fill(0) zeroisation does not mutate shared fixture constants and
pollute subsequent tests.

#5 same treatment for generateRandomBytes write key mocks.

Test 8 in write-revocation now captures fresh copies of sealChildWriteKey
arguments via a custom mock implementation, since the engine zeroes the child
write key after sealing.

#20 zero the minted IPNS private key in publishWriteCapableNode e2e helper
after publish in a finally block, narrowing the return type to only ipnsName.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(65): address coderabbit round-2 findings for bin and grant

- FIX #16 restoreFromBin: check target folder for existing child by
  ipnsName before appending restoredItem so a retry after
  saveBinMetadata failure cannot duplicate the restored child ref.
- FIX #11 claimInvite: snapshot ephemeralPrivateKey and claimerPublicKey
  buffers before the first await so a caller zeroing the inputs mid-await
  cannot corrupt the subsequent re-wrap; zero the owned copy in finally.
- FIX #12 claimInvite: trim rootNodeId/rootIpnsName before using and
  persisting them so whitespace-padded inputs are not stored as-is.
- test(65): add idempotency test for restoreFromBin, trim-input test
  and snapshot-before-await test for claimInvite; update toBe →
  toStrictEqual for recipientPublicKey (now a snapshotted copy).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(phase-68): add SDK envelope-return enablers from coderabbit PR review

Entire-Checkpoint: 4710f9a40648

* fix(65): hex-encode bin nodeReadKey on the wire so restoreFromBin survives JSON round-trip

Entire-Checkpoint: 19c3208fe45e

* fix(65): fail closed on non-32-byte bin nodeReadKey and missing deleteFromSharedFolder childNodeId

Entire-Checkpoint: c7f2d3a74cdf

* fix(65): route shared-write content uploads through pinWithMode to honor BYO pinning

Entire-Checkpoint: e99a4ebfa963

* fix(65): fail closed on non-throwing IPNS publish rejection in publishNodeFn

The shared-write publishNodeFn closure ignored pubResult.success, so a 2xx
relay response carrying success:false would proceed as if the node were
committed — leaving the parent's SealedChildRef pointing at an IPNS name that
was never published. Guard on success and throw, mirroring rotateWriteSubtree.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Entire-Checkpoint: 9e04bdf55b05

* fix(65): use childRef.generation for bin AAD, not stale envelope generation

addToBin reconstructed the child-readkey AAD from publishedNode.generation,
sourced from an independent IPNS resolve of the child. A stale-CID serve makes
that diverge from childRef.generation (the parent mirror the readKeySealed blob
was sealed under), so unsealChildReadKey fails GCM auth closed even when the
parent folder state is current. Pass childRef.generation per the §2.6
generation-source rule, matching moveItem and navigate.ts. Also capture
nodeRef.generation from childRef so restoreFromBin re-seals under the same
generation as the unsealed key.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Entire-Checkpoint: 1af3242d5c34

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants