Offline share-token creation fails: sharing.rs head_object bypasses offline-fallback

[ehsan6sha]

Summary

create_share_token and create_share_token_with_mode in crates/fula-flutter/src/api/sharing.rs call guard.inner().head_object(&bucket, &storage_key) directly to retrieve the wrapped DEK from the S3 x-fula-encryption HTTP header. This bypasses the offline-fallback infrastructure (get_object_with_offline_fallback plus forest_entry.user_metadata fallback) that the download path already uses, so share-token creation fails whenever the master S3 endpoint is unreachable — even though the wrapped DEK is already available locally in the AEAD-protected forest_entry.user_metadata["x-fula-encryption"] field that the SDK populates at upload time (crates/fula-client/src/encryption.rs:5955-5968).

Reproduction

1. Sign in to a v0.5.x SDK consumer (FxFiles) and upload one or more files to a bucket via the encrypted SDK.
2. Change the gateway endpoint URL to an unresolvable hostname (e.g., s33.cloud.fx.land instead of s3.cloud.fx.land) to simulate master-unreachable. Restart the app.
3. Trigger any flow that creates share tokens — for example, the automatic tag-share refresh (SharingService._buildManifestEntries in FxFiles).
4. Observe: listObjects(bucket) succeeds via the warm-cache forest fallback (Forest loaded for bucket: images / listObjects(images, prefix=""): 34 files), but every createShareToken call fails with:

AnyhowException(Failed to fetch object metadata: HTTP error:
  error sending request for url (https://<unreachable-host>/<bucket>/<storage_key>)
  ... dns error ... No address associated with hostname)

followed by [TagManifestUpdate] re-published share <id> with 0 files.

Root Cause (file:line)

• crates/fula-flutter/src/api/sharing.rs:47 in create_share_token:

let head_result = guard.inner().head_object(&bucket, &storage_key).await
    .map_err(|e| anyhow::anyhow!("Failed to fetch object metadata: {}", e))?;

• crates/fula-flutter/src/api/sharing.rs:144 in create_share_token_with_mode: identical pattern.

Both call head_object directly on the inner FulaClient. The inner head_object issues a raw HTTP HEAD against the configured master endpoint — no block-cache check, no IPFS gateway race, no forest-entry fallback.

The download path is wired correctly: get_object_decrypted_inner at crates/fula-client/src/encryption.rs:1432-1463 uses get_object_with_offline_fallback_known_cid (or get_object_with_offline_fallback if no CID hint) and has a get_meta helper that falls back from HTTP headers to forest_entry.user_metadata. Share-token creation was written before that pattern landed and never updated.

Expected vs Actual

• Expected: share-token creation succeeds offline for any file whose forest entry carries the encryption JSON in user_metadata (true for all uploads since encryption.rs:5955-5968 landed). The wrapped DEK can be unwrapped locally without any network call.
• Actual: every share-token creation issues a HEAD against the configured master, even though all the inputs needed are already in the local AEAD-protected forest.

Suggested Fix

Mirror the pattern already in get_object_decrypted_inner:

1. Look up the forest entry for the given (bucket, storage_key) via the existing forest_entry_lookup helper.
2. Read x-fula-encryption from forest_entry.user_metadata first; fall back to head_object only when the forest entry is missing OR has no x-fula-encryption key (legacy uploads pre-encryption.rs:5955).
3. Parse the same JSON shape currently parsed from the HEAD response.

Approximate diff: ~30 LOC in sharing.rs, no fula-crypto change, no FFI signature change.

Severity

Medium-High. Confirmed broken: any share-token-dependent workflow when master is unreachable, including FxFiles automatic tag-share refresh, manual create-share-link, and any UI that uses share tokens to display files.

The direct file-download path (get_flat) is correctly wired through the offline-fallback infrastructure, so plain downloads work offline for files in the warm cache or reachable via IPFS gateway. Only share-token flows break.

Verification Plan

A failing unit test will be added under tests/ that:

1. Sets up an in-memory blockstore client and uploads an encrypted file.
2. Marks the master backend unreachable.
3. Calls create_share_token on the uploaded file.
4. Asserts it currently fails — proving the bug.

After the fix lands, the same test should pass.

---

Reported by FxFiles team during offline-mode audit. Will follow with PR.

[ehsan6sha]

Update — fix design refined after advisor consultation

Failing test landed at tests/issue_11_share_token_offline_test.rs. Reproduces the bug end-to-end via the FFI: spawns local gateway, uploads via put_flat, aborts the gateway, calls create_share_token, and gets the exact same "Failed to fetch object metadata: HTTP error: error sending request for url ..." shape the FxFiles logs show.

External-advisor review (Gemini + Codex) on the original "forest-first, head_object fallback" design surfaced a secondary issue that changes the fix direction:

Secondary finding (related, separate concern)

fula-client/src/encryption.rs:8729-8800 (rewrap_object_dek, used by rotate_bucket) re-wraps the DEK and PUTs the updated x-fula-encryption header to S3, but never updates forest_entry.user_metadata["x-fula-encryption"]. After any key rotation, the forest carries the OLD wrapped DEK while S3 has the new one. If the share-token path prioritizes forest over head_object, post-rotation token creation produces tokens whose embedded wrapped DEK fails to unwrap under the sender's current KEK.

This isn't the issue #11 bug — but it constrains the issue #11 fix design.

Final fix design (issue #11)

Replace head_object calls in sharing.rs:47 and :144 with a HEAD-first, forest-fallback lookup:

1. Try head_object first. On Ok, use the response header. Identical to today for online flows.
2. On a transport-error failure (DNS / connect / timeout / MasterUnreachable), fall back to forest_entry.user_metadata.get("x-fula-encryption").
3. On any other failure (404, 403, auth error, parse error), propagate as-is — those are real errors, not master-down.

This preserves "live S3 = source of truth" so post-rotation online flows are byte-identical to today. Only fully-offline flows take the new path. Post-rotation + offline is a documented limitation that requires the secondary fix (sync rotation into forest user_metadata) to fully resolve.

Plan

1. Implement HEAD-first + transport-error-fallback in sharing.rs (both create_share_token and _with_mode).
2. Add a public EncryptedClient helper that returns x-fula-encryption with the offline fallback baked in (so the logic isn't duplicated and can be reused by future call sites).
3. Verify tests/issue_11_share_token_offline_test.rs passes after the fix.
4. Run the broader test suite to confirm no regressions.
5. Document the rotation-doesn't-sync-forest secondary finding as a follow-up — likely deserves its own issue once this PR lands.

PR coming next.

[ehsan6sha]

Fixed and merged in 2460a01

Fix landed on main. Summary:

Code change (commit):

1. New helper in crates/fula-client/src/encryption.rs — EncryptedClient::get_object_encryption_metadata_with_fallback(bucket, storage_key) -> Result<String>:

   • Tries head_object against master first (preserves "live S3 = source of truth" for online flows; byte-identical to prior behavior on the success path).
   • On a transport-layer failure (MasterUnreachable, DNS, connect, timeout, request errors), falls back to forest_entry.user_metadata["x-fula-encryption"] (populated at upload by encryption.rs:5955-5968).
   • Other errors (404, AccessDenied, parse errors) propagate as-is.

2. Call-site update in crates/fula-flutter/src/api/sharing.rs:47 and :144 (create_share_token and create_share_token_with_mode) — both now use the new helper instead of head_object directly.

Verification:

• tests/issue_11_share_token_offline_test.rs (added in this commit) reproduces the FxFiles offline scenario end-to-end: spawns a local gateway, uploads via FFI put_flat, aborts the gateway, calls FFI create_share_token. Failed before the fix with the exact "Failed to fetch object metadata: HTTP error: error sending request for url ..." shape from the FxFiles logs. Passes after the fix.
• 53 existing tests across security_audit_tests, api_tests, and audit2_tests (covering rotation_integration, sharing_integration, migration_security, and friends) all pass — no regressions.

Follow-up filed as a known limitation in the commit message:

rewrap_object_dek (encryption.rs:8729-8800) updates S3's x-fula-encryption during key rotation but does NOT update forest_entry.user_metadata. Online flows fetch fresh data via HEAD and remain correct under this fix. Fully-offline flows AFTER a key rotation may surface stale wrapped DEKs until a separate follow-up mirrors the rewrap into the forest entry. Recommend opening a new issue for that one.

Closing. FxFiles offline share-token creation should now work as expected once it pulls a fula_client release containing 2460a01.