Files and Transfers

Files and Transfers

Pizarra includes a small, verified exchange channel for coordination artifacts. It is designed for reports, manifests, patches, plans, and test outputs—not large datasets or release storage.

Two access paths

Use a locally mounted shared root:

tiza share reviewer report.txt "Independent review report"
tiza files reviewer

Use the native bus when the client does not mount that filesystem:

tiza put reviewer report.txt "Independent review report"
tiza get reviewer/report.txt downloaded-report.txt
tiza cat reviewer/report.txt

The browser provides the same guarded exchange through Files and Transfers.

The exchange may be an NFS mount. Configure one absolute path—portable examples use /mnt/pizarra-shared—as both hub [shared] dir and pzweb [web] shared. Every host using tiza share must see the same mount at that path; hosts without it should use bus-mediated put and get.

Namespace

The public exchange is intentionally shallow:

shared-root/
  console/
  builder/
  reviewer/

Browser selectors expose the root and exactly one team directory level, not an arbitrary recursive filesystem API.

Destination basenames:

• begin with an alphanumeric character;
• may otherwise contain letters, digits, dot, underscore, and hyphen;
• cannot contain path separators, dot segments, or NUL bytes; and
• never overwrite an existing file.

Name collisions produce suffixes such as .2 and .3.

Verified chunked transfer

Native transfers use:

• chunks no larger than 512 KiB;
• a 10 MiB complete-file cap;
• explicit upload IDs and byte offsets;
• base64 transport inside bounded JSON frames;
• whole-file SHA-256 verification; and
• temporary staging followed by atomic publication.

sequenceDiagram
    participant C as Client
    participant H as Hub
    participant F as External shared root
    C->>H: first chunk with destination, name, ID, and offset 0
    loop exact offsets
        C->>H: base64 chunk
        H->>F: append to private staging file
    end
    C->>H: finish with SHA-256
    H->>F: verify full bytes
    H->>F: atomic publish under collision-safe name
    H-->>C: final shared path and digest

Loading

A malformed base64 chunk, wrong offset, excess size, or mismatched final digest fails without publishing the partial file.

Guarded browser deletion

Shared-file browser operations are descriptor-anchored and no-follow:

• symlink components are rejected;
• symlinks are never followed;
• deleting a symlink removes only the link;
• a non-empty directory requires explicit recursive intent;
• concurrent change may produce a reported partial outcome; and
• deletion never pretends an incomplete recursive result was atomic.

Example API intent:

{
  "dir": "reviewer",
  "name": "old-report.txt",
  "recursive": false
}

Use Web API for the exact route and response envelope.

Integrity is not trust

SHA-256 proves that the received bytes match the bytes declared by the authenticated sender. It does not prove:

• that the content is safe to execute;
• that the sender created it;
• that it was independently signed;
• that it contains no misleading instructions; or
• that it belongs in a production environment.

Treat shared files as untrusted input until the receiving process or human validates them.

Operational rules

• Keep the shared root outside source repositories and web static assets.
• Keep it outside /var/lib/pizarra; it is external exchange data, not hub state or a registry.
• Grant each service account only the paths it requires.
• Never store credentials or backup bundles in the exchange.
• Built-in migration and retirement preserve the path references but do not copy, move, archive, or delete the external tree.
• Built-in backup/restore retains only the hub config's path reference, not shared content; use a coordinated external snapshot for recovery.
• Do not use it as an update release root.
• Review collision-renamed results instead of assuming the requested name.
• Keep large artifacts in a system designed for them and share a reference.
• Record the file's purpose in the accompanying message or task note.

Files view	Transfers view

Continue with Security Model and the CLI reference.