feat: enforce share-invite authorization and IPNS data-integrity in the API

[FSM1]

Phase 71 — Share-Invite Security and IPNS Data-Integrity (API)

Enforces share-invite authorization and cleans up IPNS/share data-integrity edges, plus a full share-plane rename purging "descriptor" vocabulary across the API, api-client, TS consumers, and Rust crates.

What shipped (9 plans, 4 waves)

• D-10 share-plane rename — read_descriptor_ref→encrypted_read_key, write_descriptor_ref→encrypted_write_key, root_ipns_name→share_root_ipns_name; TS readDescriptorRef→encryptedReadKey, etc.; Rust serde fields aligned to the regenerated OpenAPI. "descriptor" fully purged from the share domain (api / api-client / sdk-core / sdk / web / sdk-e2e / crates).
• D-01 / SC#1 child-ownership gate — createInvite and createShare verify the caller registered the shared node in ipns_records (creator marker) before persisting; ForbiddenException (403) on miss. rootNodeId stays client-asserted (D-02 residual, bounded by the crypto ceiling).
• D-07 / SC#2 widen-only claim — a re-claim over an existing share applies the later invite's grant only if it widens authority (read→write or higher generation); never downgrades write→read.
• D-04 / SC#3 claim_count CHECK — folded into the greenfield cutover migration; root-uniqueness index intentionally dropped (D-03, already covered by vault uniqueness).
• D-05 same-seq CID equivocation guard and D-06 first-publish INSERT-race → clean 409 in upsertIpnsRecord; the D-06 real race is proven against live Postgres (sdk-e2e Test 21: exactly one 200 + one 409, never 500).
• SC#5 bulk-revoke — revokeForItems is now a single DELETE query.
• SC#6 unit coverage — restored ShareInviteService getInvitesForItem / revokeInvite coverage and hardened controller fixtures.

Fix found during ship (SDK E2E gate)

The SDK E2E gate caught a real regression from the new D-05 guard: during a concurrent-add-mid-rotation, the rotation engine's republish embeds seq === dbSeq after a concurrent writer advanced the row, and the D-05 equivocation guard rejected it with a 400 instead of the 409 the engine merges. Fixed by classifying a forward-CAS attempt that lost the race (expectedSequenceNumber === embeddedSeq - 1) as a 409, not equivocation — equivocation protection is preserved (the write still never lands). Added a unit test; rotation-crash-safety and the ipns unit suite are green.

Quality gates

• Verify: passed (16/16 truths, 0 gaps)
• Secure: SECURED (12/12 threats closed; T-71-02 accepted documented residual)
• Validate (Nyquist): compliant, 0 gaps
• pnpm typecheck: green · apps/api Jest: 895 passing · cargo check --all-targets: green · sdk-core 363 + sdk 362: green
• SDK E2E: 103/105 green. The 2 remaining failures are tee-republish and are environmental (a DB reset for the greenfield cutover wiped tee_key_state; the file is unchanged and phase 71 touches no TEE code) — restore recipe captured as a todo.

Deferred (todos on this branch, out of scope for this phase)

• assertRootOwnership helper extraction (dedup the D-01 gate)
• Zero file keys on the unwrap error path in updateSharedSingleFile (pre-existing crypto hygiene)
• Reject a write-capable invite claimed without a re-wrapped write key (behavior decision)
• Reconcile stale D-01 / greenfield language in the planning docs
• Restore tee_key_state for the sdk-e2e tee-republish suite

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Share and invite APIs now use clearer encrypted-key fields and shared-root identifiers.
  • Added ownership checks to prevent unauthorized share and invite creation.
  • Added safer invite re-claim behavior that only increases permissions.
  • Added protection against conflicting IPNS updates and first-publish conflicts.

• Bug Fixes

  • Bulk share revocation is more efficient and reports accurate results.
  • Improved handling of concurrent publishing and same-content retries.

• Tests

  • Expanded unit and end-to-end coverage for authorization, invite lifecycle, key handling, and publishing races.

[github-actions]

Release Preview

Package	Bump	Label	Source
api	minor	release:api:feat	Direct (feat commit)
cipherbox-fuse	minor	release:cipherbox-fuse:feat	Direct (feat commit)
cipherbox-sdk	minor	release:cipherbox-sdk:feat	Direct (feat commit)
desktop	minor	release:desktop:fix	Cascade (api minor)
sdk	minor	release:sdk:feat	Direct (feat commit)
sdk-core	minor	release:sdk-core:feat	Direct (feat commit)
tee-worker	patch	release:tee-worker:fix	Cascade (sdk-core minor)
web	minor	release:web:feat	Direct (feat commit)

Cascade Details

• api minor -> desktop patch (direct dependency)
• sdk-core minor -> tee-worker patch (direct dependency)

[codecov]

Codecov Report

❌ Patch coverage is 92.43697% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.60%. Comparing base (d5486e5) to head (abe0a9a).

Files with missing lines	Patch %	Lines
packages/sdk-core/src/share/grant.ts	81.25%	3 Missing ⚠️
packages/sdk/src/client.ts	83.33%	2 Missing ⚠️
apps/api/src/shares/share-invite.service.ts	95.65%	0 Missing and 1 partial ⚠️
apps/api/src/shares/shares.service.ts	93.33%	0 Missing and 1 partial ⚠️
crates/fuse/src/write_ops/grant_scope.rs	87.50%	1 Missing ⚠️
crates/sdk/src/rotation/engine.rs	88.88%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #599      +/-   ##
==========================================
+ Coverage   66.61%   75.60%   +8.99%     
==========================================
  Files         155      195      +40     
  Lines       15249    31838   +16589     
  Branches     1839     1853      +14     
==========================================
+ Hits        10158    24072   +13914     
- Misses       4841     7514    +2673     
- Partials      250      252       +2     

Flag	Coverage Δ
api	80.29% <92.30%> (+0.23%)	⬆️
api-client	80.29% <92.30%> (+0.23%)	⬆️
core	80.29% <92.30%> (+0.23%)	⬆️
crypto	80.29% <92.30%> (+0.23%)	⬆️
desktop	21.41% <ø> (-10.03%)	⬇️
rust	78.53% <92.85%> (?)
sdk	80.29% <92.30%> (+0.23%)	⬆️
sdk-core	80.29% <92.30%> (+0.23%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
apps/api/src/ipns/ipns.service.ts	87.19% <100.00%> (+0.55%)	⬆️
apps/api/src/shares/invites.controller.ts	82.75% <100.00%> (ø)
apps/api/src/shares/share-invites.controller.ts	74.07% <ø> (ø)
apps/api/src/shares/shares.controller.ts	71.18% <100.00%> (ø)
crates/api-client/src/shares.rs	77.14% <100.00%> (ø)
crates/fuse/src/write_ops/implementation/delete.rs	89.62% <100.00%> (ø)
crates/fuse/src/write_ops/implementation/rename.rs	69.03% <100.00%> (ø)
packages/sdk-core/src/rotation/engine.ts	79.98% <100.00%> (ø)
packages/sdk-core/src/rotation/scope.ts	100.00% <100.00%> (ø)
packages/sdk-core/src/share/navigate.ts	94.02% <100.00%> (ø)
... and 7 more

... and 92 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[greptile-apps]

Greptile Summary

Phase 71 enforces share-invite authorization (D-01/SC#1 ownership gate, D-07/SC#2 widen-only re-claim), hardens IPNS data-integrity (D-05 equivocation guard, D-06 first-publish INSERT-race → 409), optimizes bulk revocation to a single DELETE query (SC#5), and executes a full rename purging "descriptor" vocabulary across the share domain.

• D-01/SC#1: createShare and createInvite now read ipns_records to verify the caller registered the node before persisting the share/invite; a 403 is returned on miss. Correctly treated as defense-in-depth (non-authoritative) since the true boundary is cryptographic.
• D-07/SC#2: claimInvite re-claim path applies a later invite's grant only if it widens authority (read→write or higher generation); a pre-transaction guard rejects write-capable claim attempts that omit encryptedWriteKey before the invite is consumed.
• D-05/D-06 + IPNS forward-CAS race fix: upsertIpnsRecord distinguishes a genuine same-seq equivocation (400) from a forward-CAS attempt that lost a concurrent race (expectedSequenceNumber === embeddedSeq - 1 → fall through to 409 without triggering the equivocation guard).

Confidence Score: 5/5

Safe to merge; all new authorization gates and IPNS integrity checks are well-tested and the rename is consistent across all layers.

The D-01 ownership check, D-07 widen-only re-claim, D-05 equivocation guard, and D-06 first-publish race translation are all implemented correctly and covered by new unit and e2e tests. The isForwardCasRace detection (expectedSequenceNumber === embeddedSeq - 1) is logically sound: it preserves the equivocation-protection invariant while allowing the CAS UPDATE to produce the correct 409 for a lost rotation race. The bulk DELETE refactor in revokeForItems and the CHK_share_invites_claim_count constraint are straightforward. No regressions were found in the changed paths.

No files require special attention. share-invite.service.ts carries the highest complexity (re-claim branching), but the widen-only logic and the write-key presence gate are both covered by unit tests for all combinations.

Important Files Changed

Filename	Overview
apps/api/src/shares/share-invite.service.ts	Core of this PR: adds D-01 ownership gate, D-07 widen-only re-claim logic, write-key presence guard before transaction, and full rename; the generation-bump-via-read-only-invite stale write key edge case (previous thread) is a known open concern
apps/api/src/shares/shares.service.ts	Adds D-01 ownership gate before createShare, replaces manager.find+remove with single QueryBuilder DELETE for revokeForItems (SC#5), full descriptor→encrypted-key rename; logic is clean and well-tested
apps/api/src/ipns/ipns.service.ts	Adds D-05 equivocation guard (same-seq/different-CID → 400), introduces isForwardCasRace detection to avoid misclassifying a lost CAS race as equivocation, and adds D-06 first-publish INSERT-race 409 translation; logic is sound and covered by new unit tests
apps/api/src/migrations/1750000000000-ApiSchemaCutover.ts	Renames columns (read_descriptor_ref→encrypted_read_key, write_descriptor_ref→encrypted_write_key, root_ipns_name→share_root_ipns_name), adds composite indexes for (sharer_id, share_root_ipns_name) on both shares and share_invites, and adds CHK_share_invites_claim_count DB-level CHECK constraint
apps/api/src/shares/shares.module.ts	Adds IpnsRecord to TypeOrmModule.forFeature so both SharesService and ShareInviteService can inject the IpnsRecord repository for the D-01 ownership gate
apps/api/src/shares/entities/share.entity.ts	Column rename (readDescriptorRef→encryptedReadKey, writeDescriptorRef→encryptedWriteKey, rootIpnsName→shareRootIpnsName) and adds IDX_shares_sharer_root composite index on entity level
apps/api/src/shares/entities/share-invite.entity.ts	Column renames plus adds @check constraint on claim_count and @Index for (sharerId, shareRootIpnsName); consistent with migration SQL
apps/api/src/shares/share-invite.service.spec.ts	Restores getInvitesForItem/revokeInvite coverage, adds generation-bump unit tests including a test for the Greptile P1 stale-write-key fix (write invite + write-capable existing + higher gen), and a no-downgrade backstop test
apps/api/src/ipns/ipns.service.spec.ts	Adds three new D-05 unit tests: equivocation rejection (same-seq/different-CID), forward-CAS-race 409 passthrough, and idempotent same-CID re-sign; covers the isForwardCasRace distinction introduced in the service

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant C as Client
    participant SI as ShareInvitesController
    participant SIS as ShareInviteService
    participant IPNS as IpnsRecordRepo
    participant DB as Postgres

    Note over C,DB: createInvite (D-01/SC#1 ownership gate)
    C->>SI: "POST /invites {shareRootIpnsName, encryptedReadKey, ...}"
    SI->>SIS: createInvite(sharerId, dto)
    SIS->>IPNS: "findOne({ipnsName, userId}) — D-01 gate"
    alt not owner
        IPNS-->>SIS: null
        SIS-->>C: 403 ForbiddenException
    else owner confirmed
        IPNS-->>SIS: IpnsRecord
        SIS->>DB: INSERT share_invites
        SIS-->>C: "invite {token, shareRootIpnsName, ...}"
    end

    Note over C,DB: claimInvite (atomic widen-only re-claim D-07/SC#2)
    C->>SI: "POST /invites/:token/claim {encryptedReadKey, [encryptedWriteKey]}"
    SI->>SIS: claimInvite(token, claimerId, dto)
    SIS->>DB: findOne(invite) — pre-tx expiry/status check
    alt write-capable invite + no dto.encryptedWriteKey
        SIS-->>C: 400 BadRequestException
    end
    SIS->>DB: BEGIN TRANSACTION
    SIS->>DB: "UPDATE share_invites SET status=claimed WHERE ... AND claim_count < max_claims"
    alt "affected=0"
        SIS-->>C: 409 ConflictException
    end
    SIS->>DB: "findOne(Share, {sharerId, recipientId, rootNodeId})"
    alt existingShare found
        Note over SIS: D-07: widen-only (isWriteUpgrade OR isGenerationBump)
        SIS->>DB: UPDATE share (encryptedReadKey, [encryptedWriteKey, rootGeneration])
    else no existing share
        SIS->>DB: INSERT share (write authority from invite, not claimer input)
    end
    SIS->>DB: COMMIT
    SIS-->>C: "{shareId}"

    Note over C,DB: upsertIpnsRecord (D-05 equivocation + D-06 first-publish race)
    C->>IPNS: "publishRecord({ipnsName, embeddedSeq, expectedSeq, CID})"
    alt "embeddedSeq==dbSeq AND isForwardCasRace (expectedSeq==embeddedSeq-1)"
        Note over IPNS: Skip D-05 guard — lost CAS race, fall through to 409
    else "embeddedSeq==dbSeq AND same CID"
        Note over IPNS: Idempotent re-sign (isIdempotentRepublish=true)
    else "embeddedSeq==dbSeq AND different CID"
        IPNS-->>C: 400 BadRequestException (equivocation)
    end
    IPNS->>DB: "CAS UPDATE WHERE seq=expected AND gen<=incoming"
    alt "affected=0"
        IPNS-->>C: 409 ConflictException
    else "affected=1"
        IPNS-->>C: updated IpnsRecord
    end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant C as Client
    participant SI as ShareInvitesController
    participant SIS as ShareInviteService
    participant IPNS as IpnsRecordRepo
    participant DB as Postgres

    Note over C,DB: createInvite (D-01/SC#1 ownership gate)
    C->>SI: "POST /invites {shareRootIpnsName, encryptedReadKey, ...}"
    SI->>SIS: createInvite(sharerId, dto)
    SIS->>IPNS: "findOne({ipnsName, userId}) — D-01 gate"
    alt not owner
        IPNS-->>SIS: null
        SIS-->>C: 403 ForbiddenException
    else owner confirmed
        IPNS-->>SIS: IpnsRecord
        SIS->>DB: INSERT share_invites
        SIS-->>C: "invite {token, shareRootIpnsName, ...}"
    end

    Note over C,DB: claimInvite (atomic widen-only re-claim D-07/SC#2)
    C->>SI: "POST /invites/:token/claim {encryptedReadKey, [encryptedWriteKey]}"
    SI->>SIS: claimInvite(token, claimerId, dto)
    SIS->>DB: findOne(invite) — pre-tx expiry/status check
    alt write-capable invite + no dto.encryptedWriteKey
        SIS-->>C: 400 BadRequestException
    end
    SIS->>DB: BEGIN TRANSACTION
    SIS->>DB: "UPDATE share_invites SET status=claimed WHERE ... AND claim_count < max_claims"
    alt "affected=0"
        SIS-->>C: 409 ConflictException
    end
    SIS->>DB: "findOne(Share, {sharerId, recipientId, rootNodeId})"
    alt existingShare found
        Note over SIS: D-07: widen-only (isWriteUpgrade OR isGenerationBump)
        SIS->>DB: UPDATE share (encryptedReadKey, [encryptedWriteKey, rootGeneration])
    else no existing share
        SIS->>DB: INSERT share (write authority from invite, not claimer input)
    end
    SIS->>DB: COMMIT
    SIS-->>C: "{shareId}"

    Note over C,DB: upsertIpnsRecord (D-05 equivocation + D-06 first-publish race)
    C->>IPNS: "publishRecord({ipnsName, embeddedSeq, expectedSeq, CID})"
    alt "embeddedSeq==dbSeq AND isForwardCasRace (expectedSeq==embeddedSeq-1)"
        Note over IPNS: Skip D-05 guard — lost CAS race, fall through to 409
    else "embeddedSeq==dbSeq AND same CID"
        Note over IPNS: Idempotent re-sign (isIdempotentRepublish=true)
    else "embeddedSeq==dbSeq AND different CID"
        IPNS-->>C: 400 BadRequestException (equivocation)
    end
    IPNS->>DB: "CAS UPDATE WHERE seq=expected AND gen<=incoming"
    alt "affected=0"
        IPNS-->>C: 409 ConflictException
    else "affected=1"
        IPNS-->>C: updated IpnsRecord
    end

Loading

_{Reviews (4): Last reviewed commit: "fix(test): resolve pre-existing tsc --no..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

apps/api/src/shares/shares.controller.ts (1)

47-50: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Add missing @ApiResponse decorators for new error statuses.

createShare can now return 403 (ownership check per Phase 71 objectives) but only documents 201/401/404/409. updateGrant can throw BadRequestException (400 — mutual exclusivity) and ConflictException (409 — rootGeneration regression) in the service, but only documents 204/401/403/404.

📝 Proposed fix

   `@ApiResponse`({ status: 201, description: 'Share created', type: CreateShareResponseDto })
   `@ApiResponse`({ status: 401, description: 'Unauthorized' })
+  `@ApiResponse`({ status: 403, description: 'Caller does not own the share root' })
   `@ApiResponse`({ status: 404, description: 'Recipient not found' })
   `@ApiResponse`({ status: 409, description: 'Share already exists or self-share' })

   `@ApiResponse`({ status: 204, description: 'Grant updated' })
   `@ApiResponse`({ status: 401, description: 'Unauthorized' })
   `@ApiResponse`({ status: 403, description: 'Only the sharer can update' })
   `@ApiResponse`({ status: 404, description: 'Share not found' })
+  `@ApiResponse`({ status: 400, description: 'encryptedWriteKey and clearEncryptedWriteKey are mutually exclusive' })
+  `@ApiResponse`({ status: 409, description: 'rootGeneration regression rejected' })

As per coding guidelines, after modifying controllers in apps/api, ensure the API client is regenerated with pnpm api:generate.

Also applies to: 236-239

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/api/src/shares/shares.controller.ts` around lines 47 - 50, Add
`@ApiResponse` decorators documenting 403 for createShare and 400/409 for
updateGrant, alongside their existing response annotations; locate these methods
by their names in the shares controller. After updating the controller,
regenerate the API client with pnpm api:generate.

Source: Coding guidelines

🧹 Nitpick comments (3)

apps/api/src/shares/share-invite.service.spec.ts (2)

311-408: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Cover stale-generation re-claims.

The suite tests equal and newer rootGeneration, but not an older invite generation. Add a case asserting a stale re-claim neither saves nor replaces the existing generation/read key; otherwise an anti-rollback regression can pass this widen-only coverage.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/api/src/shares/share-invite.service.spec.ts` around lines 311 - 408,
Extend the D-07 re-claim tests for service.claimInvite with a stale-generation
case where the invite rootGeneration is lower than the existing share’s. Assert
the result keeps the existing share ID, mockManager.save is not called, and both
the existing rootGeneration and encryptedReadKey remain unchanged.

Source: Path instructions

---

167-181: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Assert encrypted DTO serialization.

This test claims DTO fields are copied but does not verify encryptedReadKey, optional encryptedWriteKey, or itemNameEncrypted. A regression in encrypted-key persistence or Buffer conversion would still pass.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/api/src/shares/share-invite.service.spec.ts` around lines 167 - 181, The
createInvite test should also verify encrypted DTO fields are persisted and
correctly serialized. In the test for service.createInvite, assert
encryptedReadKey, optional encryptedWriteKey, and itemNameEncrypted against the
DTO, accounting for expected Buffer conversion where applicable.

Source: Path instructions

apps/api/src/migrations/1750000000000-ApiSchemaCutover.ts (1)

41-125: 🚀 Performance & Scalability | 🔵 Trivial

Consider adding indexes on share_root_ipns_name for shares and share_invites.

revokeForItems issues WHERE sharer_id = :sharerId AND share_root_ipns_name IN (:...names) against both tables. The existing sharer_id index narrows the scan, but the IN filter still scans all of a sharer's rows. A composite index on (sharer_id, share_root_ipns_name) for both tables would turn this into an index lookup, improving bulk revocation performance for users with many shares.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/api/src/migrations/1750000000000-ApiSchemaCutover.ts` around lines 41 -
125, Add composite indexes on ("sharer_id", "share_root_ipns_name") for both
"shares" and "share_invites" in the migration, using clear unique index names
and ensuring the migration’s rollback removes them appropriately.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
@.planning/phases/71-share-invite-security-and-ipns-data-integrity-api/deferred-items.md:
- Line 5: Update the deferred-items entry to distinguish the command’s target
files from the files that actually contain diagnostics: state that the
type-check targets shares.service.ts and shares.service.spec.ts, while the
reported errors occur in the listed crypto resolution, ipns.service.ts, and
http-metrics.interceptor.spec.ts files. Preserve that these issues are
pre-existing and out of scope.

In @.planning/STATE.md:
- Around line 27-34: Synchronize the phase transition metadata in STATE.md:
update the Current focus and Status fields from Phase 71 to Phase 72, and revise
any stale stopped_at value to reflect Phase 72 execution, matching the Phase,
Plan, and last-activity fields already declaring Phase 72.

In `@apps/api/src/shares/share-invite.service.ts`:
- Around line 183-235: Reject write-capable claims missing a re-wrapped write
key before the atomic claim UPDATE, returning a 400 error so the invite is not
consumed. In the claim handling method, use invite.encryptedWriteKey and
dto.encryptedWriteKey to validate this condition before any database mutation;
retain the existing write-key assignment logic for valid claims. Add service
tests covering both a new write claim and a read-to-write upgrade with the write
ciphertext omitted.

In `@apps/api/src/shares/share-invites.controller.ts`:
- Line 60: Add Swagger documentation for the ownership-gate 403 response on both
controller methods: add an `@ApiResponse({ status: 403, ... })` decorator
alongside the existing response decorators for `createInvite` and `listInvites`,
using a clear description consistent with the runtime error.

---

Outside diff comments:
In `@apps/api/src/shares/shares.controller.ts`:
- Around line 47-50: Add `@ApiResponse` decorators documenting 403 for createShare
and 400/409 for updateGrant, alongside their existing response annotations;
locate these methods by their names in the shares controller. After updating the
controller, regenerate the API client with pnpm api:generate.

---

Nitpick comments:
In `@apps/api/src/migrations/1750000000000-ApiSchemaCutover.ts`:
- Around line 41-125: Add composite indexes on ("sharer_id",
"share_root_ipns_name") for both "shares" and "share_invites" in the migration,
using clear unique index names and ensuring the migration’s rollback removes
them appropriately.

In `@apps/api/src/shares/share-invite.service.spec.ts`:
- Around line 311-408: Extend the D-07 re-claim tests for service.claimInvite
with a stale-generation case where the invite rootGeneration is lower than the
existing share’s. Assert the result keeps the existing share ID,
mockManager.save is not called, and both the existing rootGeneration and
encryptedReadKey remain unchanged.
- Around line 167-181: The createInvite test should also verify encrypted DTO
fields are persisted and correctly serialized. In the test for
service.createInvite, assert encryptedReadKey, optional encryptedWriteKey, and
itemNameEncrypted against the DTO, accounting for expected Buffer conversion
where applicable.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4d13e95a-8bc1-4495-9903-bc11225e125d

📥 Commits

Reviewing files that changed from the base of the PR and between d5486e5 and 07b144f.

⛔ Files ignored due to path filters (13)

• packages/api-client/openapi.json is excluded by !packages/api-client/**
• packages/api-client/src/generated/invites/invites.ts is excluded by !**/generated/**, !**/generated/**, !packages/api-client/**
• packages/api-client/src/generated/shares/shares.ts is excluded by !**/generated/**, !**/generated/**, !packages/api-client/**
• packages/api-client/src/models/claimInviteDto.ts is excluded by !packages/api-client/**
• packages/api-client/src/models/createInviteDto.ts is excluded by !packages/api-client/**
• packages/api-client/src/models/createShareDto.ts is excluded by !packages/api-client/**
• packages/api-client/src/models/createShareResponseDto.ts is excluded by !packages/api-client/**
• packages/api-client/src/models/inviteDataResponseDto.ts is excluded by !packages/api-client/**
• packages/api-client/src/models/inviteResponseDto.ts is excluded by !packages/api-client/**
• packages/api-client/src/models/receivedShareResponseDto.ts is excluded by !packages/api-client/**
• packages/api-client/src/models/sentShareResponseDto.ts is excluded by !packages/api-client/**
• packages/api-client/src/models/shareInvitesControllerListInvitesParams.ts is excluded by !packages/api-client/**
• packages/api-client/src/models/updateGrantDto.ts is excluded by !packages/api-client/**

📒 Files selected for processing (96)

• .planning/PROJECT.md
• .planning/ROADMAP.md
• .planning/STATE.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-01-PLAN.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-01-SUMMARY.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-02-PLAN.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-02-SUMMARY.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-03-PLAN.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-03-SUMMARY.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-04-PLAN.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-04-SUMMARY.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-05-PLAN.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-05-SUMMARY.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-06-PLAN.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-06-SUMMARY.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-07-PLAN.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-07-SUMMARY.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-08-PLAN.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-08-SUMMARY.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-09-PLAN.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-09-SUMMARY.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-CONTEXT.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-DISCUSSION-LOG.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-PATTERNS.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-RESEARCH.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-SECURITY.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-VALIDATION.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/71-VERIFICATION.md
• .planning/phases/71-share-invite-security-and-ipns-data-integrity-api/deferred-items.md
• .planning/todos/pending/2026-07-10-extract-assert-root-ownership-helper.md
• .planning/todos/pending/2026-07-10-reconcile-phase71-planning-docs-d01-greenfield.md
• .planning/todos/pending/2026-07-10-reject-write-invite-claimed-without-write-key.md
• .planning/todos/pending/2026-07-10-restore-tee-key-state-for-sdk-e2e-tee-republish.md
• .planning/todos/pending/2026-07-10-zeroize-file-keys-on-unwrap-error-path.md
• apps/api/src/ipns/ipns.service.spec.ts
• apps/api/src/ipns/ipns.service.ts
• apps/api/src/migrations/1750000000000-ApiSchemaCutover.ts
• apps/api/src/shares/dto/claim-invite.dto.ts
• apps/api/src/shares/dto/create-invite.dto.ts
• apps/api/src/shares/dto/create-share.dto.ts
• apps/api/src/shares/dto/get-invites-for-item-query.dto.ts
• apps/api/src/shares/dto/invite-response.dto.ts
• apps/api/src/shares/dto/share-response.dto.ts
• apps/api/src/shares/dto/update-grant.dto.ts
• apps/api/src/shares/entities/share-invite.entity.ts
• apps/api/src/shares/entities/share.entity.ts
• apps/api/src/shares/invites.controller.spec.ts
• apps/api/src/shares/invites.controller.ts
• apps/api/src/shares/share-invite.service.spec.ts
• apps/api/src/shares/share-invite.service.ts
• apps/api/src/shares/share-invites.controller.spec.ts
• apps/api/src/shares/share-invites.controller.ts
• apps/api/src/shares/shares.controller.spec.ts
• apps/api/src/shares/shares.controller.ts
• apps/api/src/shares/shares.module.ts
• apps/api/src/shares/shares.service.spec.ts
• apps/api/src/shares/shares.service.ts
• apps/web/src/components/file-browser/ShareDialog.tsx
• apps/web/src/hooks/useAuth.ts
• apps/web/src/hooks/useMutationFailureUx.ts
• apps/web/src/hooks/useSharedNavigationActions.ts
• apps/web/src/lib/crypto/key-wrapping.ts
• apps/web/src/services/invite.service.ts
• apps/web/src/services/owner-reconcile.service.ts
• apps/web/src/services/rotation-driver.service.ts
• apps/web/src/services/share.service.ts
• apps/web/src/stores/share.store.ts
• crates/api-client/src/shares.rs
• crates/fuse/src/write_ops/grant_scope.rs
• crates/fuse/src/write_ops/implementation/delete.rs
• crates/fuse/src/write_ops/implementation/rename.rs
• crates/sdk/src/rotation/engine.rs
• packages/sdk-core/src/__tests__/rotation/grant-remint.test.ts
• packages/sdk-core/src/__tests__/rotation/scope.test.ts
• packages/sdk-core/src/__tests__/rotation/write-revocation.test.ts
• packages/sdk-core/src/__tests__/share/grant.test.ts
• packages/sdk-core/src/__tests__/share/navigate.test.ts
• packages/sdk-core/src/rotation/engine.ts
• packages/sdk-core/src/rotation/scope.ts
• packages/sdk-core/src/share/grant.ts
• packages/sdk-core/src/share/navigate.ts
• packages/sdk/src/__tests__/client-rotation.test.ts
• packages/sdk/src/__tests__/client-write-descriptor.test.ts
• packages/sdk/src/__tests__/download-shared-file.test.ts
• packages/sdk/src/__tests__/owner-reconcile.test.ts
• packages/sdk/src/__tests__/resolve-share-root.test.ts
• packages/sdk/src/__tests__/update-shared-single-file.test.ts
• packages/sdk/src/client.ts
• packages/sdk/src/share/owner-reconcile.ts
• packages/sdk/src/types.ts
• tests/sdk-e2e/src/suites/invite-link.test.ts
• tests/sdk-e2e/src/suites/ipns-publish-gate.test.ts
• tests/sdk-e2e/src/suites/read-chain-navigation.test.ts
• tests/sdk-e2e/src/suites/rotation-crash-safety.test.ts
• tests/sdk-e2e/src/suites/share-operations.test.ts
• tests/sdk-e2e/src/suites/write-chain-rotation.test.ts