Repository navigation
feat: make encrypted certificate-addressed provenance sharing transport-independent #153
Description
Summary
Make encrypted, certificate-addressed provenance sharing a first-class LocalSetup workflow built on the existing shared OpenPGP foundation. The same protected artifact should retain its recipient addressing, authenticated origin, and provenance regardless of where it is stored or how it is delivered.
Transport is an interchangeable carrier of opaque bytes. OpenPGP certificates and independently established local trust determine who can decrypt and whose statements a receiving system can accept.
Problem or workflow
People and agents need to exchange assets, blobs, documents, evidence, and provenance between machines that may have no shared network or storage provider. The artifact may pass through public S3, another cloud, a NAS, a shared drive, removable media, email, or even a Telegram attachment.
The desired guarantee is the same in every case: data and provenance remain encrypted whenever they rest outside the explicitly trusted secure local workstation or equivalent protected local environment. A storage account, filename, message sender, download URL, or successful transfer must not establish the artifact's identity or authority.
Users should be able to apply this process through LocalSetup's normal workflows without inventing a separate security convention for each service or handoff.
Affected area
Shared OpenPGP envelopes and trust lifecycle, provenance and artifact handoffs, Agent Q/file exchange, authorized file reading, and the relevant agent skills and documentation across supported platforms.
This extends the existing foundation tracked in #100, #103, #104, and #105. It asks for consistent user-facing adoption across sharing and off-workstation storage, rather than another cryptographic engine or a provider-specific storage product. The inspected baseline is LocalSetup v4.57.0 and its shared OpenPGP runtime contract.
Proposed behavior
Encrypted data and provenance outside the local trust boundary
- Protect the payload and its provenance together before either leaves protected local handling. Keep both encrypted on intermediate systems and at rest on external media; provider encryption and transport TLS do not replace this end-to-end protection.
- Cover arbitrary relevant files and binary assets as well as text documents. Protect original filenames, paths, source hashes, identities, recipient lists, and operational metadata inside the envelope. Expose only the minimal necessary format information and opaque external identifiers.
- Never silently fall back to plaintext when a key, enrollment record, or required capability is unavailable. Keep the artifact pending locally and explain the concrete missing input.
- Release plaintext only within an explicitly authorized local trust boundary after verification. Do not make every receiving machine trusted merely because it can obtain the file.
Certificate-based addressing and authenticated origin
- Use each enrolled machine's own OpenPGP identity for routine origin signatures, and select the intended recipients by their approved full certificate fingerprints.
- Treat recipient encryption as the artifact's cryptographic addressing: the carrier routes bytes, while possession of an authorized recipient private key enables decryption. A network location or account name does not substitute for a certificate identity.
- Resolve expected signer, recipient, role, and scope from independently trusted configuration or owner/controller-approved enrollment. An incoming object, downloaded certificate, or sender's self-assertion cannot enroll itself.
- Bind content, provenance, origin, intended audience, purpose, and applicable version/freshness evidence so that substitution, impersonation, replay, and stale-policy poisoning can be detected before acceptance.
- Successful decryption is insufficient: verify the expected authorized signature, integrity, provenance, scope, and current trust policy before exposing or acting on content. A valid signature establishes attribution within its authorized role; it does not grant permission to execute embedded instructions.
Owner/controller-approved distributions
- For deployments with a controller, preserve each originating machine's signatures and evidence. Fleet-wide provenance or policy distributions receive the configured master/controller's approval signature and are encrypted to the approved recipient machines.
- Keep master private keys on the controlling workstation or other approved controller boundary. Remote machines must not need shared master secrets.
- Support audience-scoped sharing. A fleet-wide distribution includes all active enrolled recipients in its intended scope; an ordinary artifact need not be disclosed to the whole fleet. Referenced payloads must be decryptable by that audience too.
- Preserve stricter backup/recovery recipient policies. Handle enrollment, rotation, revocation, historical access, and authenticated trust changes through the existing key lifecycle.
- Explain that multi-recipient encryption lets each recipient decrypt independently, removal controls future distributions, and newly enrolled recipients do not automatically gain access to historical ciphertext.
One process across any carrier
- Preparing and accepting an artifact must use the same LocalSetup trust and envelope rules whether the ciphertext is uploaded, copied to a NAS, attached to a message, or delivered manually.
- Changing the carrier must not require changing the artifact's security model, adding a new signer, sharing private keys, or trusting the storage operator.
- Distinguish byte transfer, cryptographic verification, and acceptance. Preserve authenticated evidence for each, with receipts and sensitive locators protected appropriately.
- Give people and agents concise preparation, verification, pending-state, and recovery guidance through existing LocalSetup entrypoints. Reuse existing components; no particular cloud, central storage hub, account, messaging provider, or shared network is required.
Compatibility impact
Preserve the existing OpenPGP/trust contracts and historical verification behavior. Integrate through the current owning skills and workflows, with clear capability discovery and supported-platform limits. Installing LocalSetup alone must not generate keys, enroll machines, activate services, or authorize disclosure.
Transport confidentiality remains subject to the applicable carrier policy. This request does not require building adapters for every example carrier; moving the same intact encrypted file manually should retain the same recipient addressing and verification rules. File sizes, timing, or other carrier observations should not be described as completely hidden.
Validation ideas
- Prepare a signed encrypted artifact once, move the same bytes through an object store, local/NAS file copy, and message-attachment or equivalent offline fixture, then demonstrate equivalent verified acceptance.
- Show that intended recipients can decrypt, an unaddressed machine cannot, and carrier/account identity does not override certificate policy.
- Reject tampering, substituted provenance, impersonating or unenrolled signers, unauthorized recipients, replayed/stale authority, and incorrectly scoped distributions.
- Confirm filenames and provenance do not leak through external object metadata, envelope literals, diagnostics, or receipts.
- Demonstrate fail-closed missing-key behavior, authorized local plaintext handling, preserved historical access, and honest reporting when recovery is impossible.
- Verify that encrypted transfer alone cannot trigger enrollment, policy replacement, task execution, or a claim of fleet-wide acceptance.
Additional context
This is a feature-only request describing desired behavior. No implementation, code archive, deployment identity, private infrastructure detail, or storage credential is submitted.
Activity
CruxExperts commentedon Oct 23, 2026
Additional requirement: a minimal, machine-readable recipient header followed by an encrypted OpenPGP message body.
The container should expose only the metadata needed for a machine to recognize that it may be an intended recipient: minimal format/version information and a bounded list of n recipient-key entries, corresponding to the machines or keys authorized to decrypt. Keep the header compact and readily parseable, without presentation-oriented formatting or unrelated descriptive fields.
“Signatures” in the original request refers to identifying the recipient machines/keys. Cryptographically, these addressing entries are recipient key identifiers associated with approved OpenPGP certificates; sender/controller signatures authenticate origin and approval and remain a separate requirement. Reuse OpenPGP's recipient-addressing capabilities rather than treating a transport account or filename as identity.
The entire message body remains OpenPGP encrypted, including document contents, original filenames/paths, provenance, detailed identities, catalog records, and other descriptive metadata. This refines the original issue's encrypted-metadata requirement: the minimal recipient-discovery information is the deliberate public exception; the rest stays inside encryption.
The intended workflow is that a participant can scan available encrypted containers in a bucket, directory, NAS, or other carrier, recognize potentially addressed objects from the minimal header, and build or update a private catalog of the objects it is authorized to open. Any persisted catalog must itself be encrypted to its intended participants. Scanning must not expose document details or private catalog entries to nonparticipants, and must work without trusting the carrier.
Header entries are discovery hints, not proof of identity, enrollment, decryption rights, or acceptance. Bind the header to the authenticated encrypted envelope and verify it against the actual recipient policy, trusted certificates, signatures, and provenance before accepting content. A forged or modified header must not permit catalog poisoning, trust changes, or execution. The deliberately public recipient identifiers can be observed by anyone able to inspect the containers; the body and private catalog contents cannot.
The feature should preserve this same minimal-header/encrypted-body contract regardless of storage medium or delivery channel. This comment specifies desired behavior only; no implementation or new cryptographic format is proposed.
CruxExperts commentedon Oct 23, 2026
Clarification to the recipient-header requirement: the actual metadata must also be OpenPGP encrypted, but independently accessible from the large encrypted payload.
The desired container has three logical parts:
A recipient should be able to read, decrypt, and verify the metadata block first, with bounded work, without decrypting or parsing the whole large file. Where the carrier supports partial access, locating that block should not require downloading the bulk payload either. This is the intended meaning of inspecting metadata before opening the whole encrypted document.
The encrypted metadata contains the real descriptive information: document identity, names, provenance, origin/approval evidence, audience/scope, versions, and the information needed to build the participant's private catalog. None of that becomes public frontmatter.
Authenticate the metadata independently and cryptographically bind it to the exact encrypted payload and artifact/version. A substituted metadata block, altered boundary/locator, or metadata copied from another object must not cause a different payload to be accepted. Keep the metadata and payload addressed according to the approved recipient policy.
Metadata verification allows a recipient to inspect and catalog an authenticated description. It must remain distinct from verifying the bulk payload itself: report the latter as pending until its actual bytes and required cryptographic evidence have been checked.
This refines the previous comment: the clear recipient-discovery header is not the real metadata block, and a single encrypted archive that requires opening the entire large payload just to inspect metadata does not meet the requirement. The behavior remains independent of storage or transport, and this is a feature clarification only, not an implementation proposal.
CruxExperts commentedon Oct 23, 2026
Container naming and format requirement: Local Setup Secure Container, using the custom file extension
.lssc.Everything belongs inside this single, self-contained, YAML-parseable envelope:
The YAML structure organizes the container; it does not make the real metadata or payload plaintext. Their contents remain encrypted within the envelope. Cataloging and provenance must not depend on an unprotected sidecar file.
Preserve the earlier metadata-first requirement: a recipient must be able to locate, decrypt, and authenticate the small metadata block without decrypting the large payload. YAML framing must support bounded inspection of that section rather than requiring the entire payload to be loaded or decoded first. Where the carrier permits partial access, retrieving metadata should not require retrieving the bulk payload.
The encrypted metadata must remain cryptographically bound to the exact payload and container identity/version so that blocks cannot be substituted or mixed between containers. Minimal public recipient hints remain discovery hints, not trust authority.
The same
.lsscfile should retain these properties when copied between storage systems or delivered through any carrier. This names the requested format and its observable behavior; it does not submit an implementation or prescribe a detailed YAML schema.CruxExperts commentedon Oct 23, 2026
Multi-file requirement for Local Setup Secure Container (
.lssc):A container can hold one or more files. Each file is its own independent OpenPGP-encrypted message, rather than all files being combined into a single encrypted payload.
The single YAML-parseable envelope still contains its minimal public discovery/framing fields, the separately encrypted and authenticated metadata, and the independently encrypted file messages. An authorized recipient should be able to inspect the metadata/catalog first, select a file, and decrypt and verify that file without decrypting the other file messages.
The protected metadata must identify and authenticate the individual file entries and bind each entry to its exact encrypted message, container identity/version, provenance, and approved recipient policy. Swapping, replacing, or mixing file messages between entries or containers must be detected before acceptance. No protected filenames or file details should leak into public YAML framing. Independent file encryption must preserve the established origin-signature and verification requirements.
The format should not impose an arbitrary fixed maximum file count or file size as a defining property. Implementations must nevertheless enforce and report practical, configurable limits for file size, total container size, number of entries, parsing, memory, processing, and extraction. Large-container support must not require loading the whole YAML document or every encrypted file message into memory. Reaching an implementation or carrier limit must produce an explicit result, not silent truncation or a claim of unlimited resources.
This extends the earlier “encrypted bulk payload” terminology: the body can contain multiple independently encrypted file messages within the same
.lsscenvelope. It remains a feature requirement only.CruxExperts commentedon Oct 23, 2026
Add size-based chunking and verified reassembly to the Local Setup Secure Container (
.lssc) requirements.A logical file larger than a configured threshold can be divided into multiple segments, similar to multipart file distribution through newsgroups. Each chunk is its own independently OpenPGP-encrypted and authenticated message carrying only a portion of that logical file. A smaller file may remain a single message. Preserve one-or-more logical files per container.
The separately encrypted metadata/manifest must let authorized recipients determine:
Keep names, detailed manifests, provenance, and reassembly metadata encrypted. Minimal public recipient-discovery and framing information remains subject to the earlier disclosure rule. Cryptographically bind each chunk to its logical file, segment identity, manifest/version, and approved sender/recipient policy so that segments cannot be substituted or mixed between unrelated files or versions.
Recipients must be able to receive segments out of order, identify missing or duplicate segments, retain verified progress, and resume by obtaining only missing or invalid segments. Never promote incomplete or conflicting segments as a complete file. Verify each segment before accepting it and verify the reconstructed file against the authenticated end-to-end evidence before reporting successful reassembly. Preserve exact original bytes.
Allow independently transferable chunk messages so a logical file can span multiple physical delivery files or
.lsscvolumes when a carrier or storage system imposes a per-object or per-attachment size limit. A recipient must be able to discover the expected segments from the encrypted manifest even when the segments arrive separately through different carriers. This extends “self-contained” to the independently verifiable container/volume: a single volume need not contain every segment of a multipart logical file.Expose practical configurable chunk and processing limits. When splitting for a carrier's size ceiling, account for the final encrypted and serialized message/container overhead, not only plaintext chunk length. Reassembly must support bounded processing and protected temporary storage without requiring the entire original file in memory or exposing plaintext chunks on untrusted media.
This is ordinary segmentation and reassembly; recovery/parity segments or a new transport protocol are not required by this request. It remains a feature description, with no implementation submitted.
CruxExperts commentedon Oct 23, 2026
Refine the chunking defaults and packing behavior:
The default should therefore favor intact files and convenient roughly 100 MB delivery units, while splitting oversized individual blobs only when necessary. This is a behavioral requirement, not a prescribed packing algorithm or implementation.
CruxExperts commentedon Oct 23, 2026
Add deterministic local indexing and ledger maintenance when secure-container indexing mode is enabled.
LocalSetup should maintain its own persistent, schema-defined local ledger of discovered
.lssccontainers, their file/segment entries, and the encrypted headers/metadata it has successfully decrypted and authenticated. This is a LocalSetup-owned index, not a catalog supplied by or trusted from the storage provider.Periodic reconciliation
Schema-defined local ledger
Define and version the ledger schema, including migrations. It should express stable container/file/segment identities, source observations/locators, authenticated decrypted metadata, provenance and signer/recipient authority references, versions, expected segment inventories, verification evidence/status, and reconciliation history. Keep observation state separate from authenticated claims.
Decrypted headers and sensitive catalog information belong only inside the authorized protected local trust boundary. Keep private ledger data out of public logs and repositories. If persisted outside that boundary, copied, synchronized or backed up, protect it with the same applicable encrypted-container and recipient policies.
Deterministic operation
Once this mode and its source/identity/policy configuration are authorized, routine scanning, metadata verification and ledger reconciliation should run automatically without repeated agent prompting or an LLM making index-state decisions.
Given the same observed bytes and the same explicit configuration, trust policy, prior ledger state and evaluation time, produce the same index decisions. Scan ordering, duplicate delivery and process restarts must not change acceptance. Record time/freshness inputs explicitly rather than hiding nondeterministic decisions in the scanner.
Unchanged inputs should be idempotent: do not re-decrypt unchanged verified metadata or invent new artifact versions on each scan. Cached acceptance remains subject to current trust, authorization, revocation, expiry and freshness policy. Use atomic ledger updates and resumable reconciliation so an interrupted scan cannot leave partially accepted records or silently roll trust/index state backward.
The scan interval, configured sources, resource bounds and enabled/disabled state should be discoverable and configurable. Enabling this operational mode authorizes its routine bounded maintenance; installation alone must not activate recurring work, enroll keys or add storage sources.
Acceptance ideas
Demonstrate equivalent results across shuffled discovery order, duplicate objects, interrupted/restarted scans and unchanged rescans; authenticated handling of altered headers or revoked authority; explicit source-outage and missing-segment states; and schema migration that preserves provenance and verification distinctions.
This remains a feature requirement, with no implementation submitted.
CruxExperts commentedon Oct 23, 2026
Clarify the execution model for all of the above: secure-container handling must be a deterministic runtime capability that is transparent to the consuming agent.
The agent should only need to point at a file, container, artifact or indexed reference through the normal authorized reading interface. LocalSetup resolves that reference and makes the permitted information available. The agent should not need to know the
.lssclayout, inspect YAML, choose cryptographic operations, manage key selection, parse manifests, scan sources, maintain the ledger, discover segments, or orchestrate reassembly.This applies to the entire operational path: discovery, periodic reconciliation, recipient matching, metadata decryption/authentication, index maintenance, source resolution, chunk retrieval and verification, reassembly, and authorized content reading. These operations belong to deterministic framework components under the configured policy, not to prompts, LLM reasoning, or a sequence of agent-issued maintenance commands.
Configure identity, trusted sources, authority, access grants, operating mode and resource bounds at the operator/runtime boundary. Once authorized and enabled, carry out routine work automatically. An agent's reference does not enroll a key, add a trusted source, override policy or authorize broader disclosure.
Expose normal bounded content/metadata results or clear structured states such as pending, incomplete, unavailable or unauthorized. Never ask the agent to guess a missing security decision, approve a forged header, repair an index through reasoning, or treat unverified content as available. Preserve the distinction between verified metadata and verified payload internally and in any result where it matters.
Reuse LocalSetup's existing shared OpenPGP, persistent trust, file-reading and task-authorization capabilities. The agent-facing experience should be as simple as requesting the information it is allowed to read; the secure storage, catalog and transport mechanics are handled beneath that interface.
Acceptance should demonstrate this workflow using an ordinary authorized reference/read request with no container-specific instructions or model decisions. Changes in delivery order, carrier or process restarts must not require a different agent procedure or alter deterministic acceptance. This is a feature-only clarification.
CruxExperts commentedon Oct 23, 2026
Add concurrent version preservation, explicit merging, and collision-safe object names to the
.lsscrequirements.Preserve both concurrent edits
Treat a logical file's identity separately from its immutable versions. If two authorized agents or machines modify the same base version, retain both resulting versions and their common ancestry. Do not silently overwrite either version or select a winner merely because it was uploaded last. The local ledger should represent multiple current heads and a conflict/pending-merge state where appropriate.
Record authenticated version identity, parent version(s), originating machine/signing identity, applicable scope, and payload/manifest integrity evidence inside protected metadata. Agent display names, filenames and wall-clock timestamps alone cannot establish unique identity, ordering or authority.
Merge into a new version
Provide a procedure analogous to Git branching and merging: compare the versions against their common base where available, preserve both inputs, and create a new version with the merged result and both parent references. The merge must retain provenance and the required signatures/approval. Successful merging must not erase the original versions or their history.
The deterministic runtime detects divergent ancestry, maintains the version graph and exposes the relevant versions through the normal authorized interface. Safe automatic merges may follow explicit deterministic policy; ambiguous content changes require a separately authorized human or agent merge task. The indexer must not ask a model to invent a winner as part of routine reconciliation. Binary or otherwise unmergeable content remains available as separate versions until explicitly resolved.
Shared bucket prefixes and immutable object identities
Define and document a canonical namespace/prefix scheme for shared storage so that different organizations/tenants, projects or workspaces, publishing machines, artifacts, versions, volumes and segments cannot accidentally target the same mutable object name.
Use only authorized, non-sensitive namespace identifiers in the externally visible prefix, with collision-resistant opaque immutable identifiers for the remaining objects. Keep human filenames, private version-graph details and other protected metadata inside encryption. Bind each object's external storage identity and its authenticated logical identity/version through the protected manifest and ledger.
Validate and normalize namespace components and keep all writes within the assigned scope; reject path/prefix ambiguity or escape. Do not derive object identity solely from a basename, agent name, timestamp or shared “latest” filename. Repeated publication of the same immutable object may be idempotent, but different bytes must never silently replace an existing immutable identity. Reconcile uncertain writes before retrying.
Treat prefixes as organization, not proof of authorization or a substitute for storage permissions and cryptographic trust. The logical version graph and acceptance rules must survive moving the same encrypted objects to another bucket, directory or transport.
If discovery uses a mutable head/catalog reference, protect updates against concurrent writers and retain divergent heads when reconciliation is necessary. Where a carrier cannot provide conditional updates, the immutable records must still allow deterministic discovery/reconciliation without losing either writer's version. A mutable catalog must never be the sole surviving evidence of a version.
Acceptance ideas
Two writers starting from one base produce two preserved, independently verifiable heads; reversed arrival order produces the same graph; a later approved merge creates a new version with both parents; same-named files in distinct assigned namespaces do not collide; retries do not overwrite different bytes; and version acceptance still follows the approved signer/recipient policy.
This is a feature description only. It does not prescribe a storage provider, exact prefix syntax, merge engine or implementation.
CruxExperts commentedon Oct 23, 2026
Design direction to research: immutable encrypted diffs with reconstruction and periodic snapshot consolidation, with configurable responsibility for doing that work.
When modifying an existing logical file/archive, a writer should be able to publish a diff/change record against an identified version instead of rewriting and uploading the entire archive. Preserve that independently encrypted and authenticated change record and its provenance. A receiving runtime reconstructs the requested version from a verified base plus the applicable changes, and an authorized consolidation operation can publish a new complete encrypted snapshot.
Configurable consolidation modes
Support the following operational choices without changing the container, trust or versioning semantics:
The consuming agent still only references the artifact through the ordinary interface. Diff discovery, verification, reconstruction and configured consolidation are deterministic runtime work, not an LLM-managed maintenance procedure. A read grant alone must not imply authority to upload, sign for another identity or delete history.
Preserve concurrent changes during consolidation
A consolidation operation must identify exactly which verified base/version and change records it includes. Publish the resulting full snapshot as a new immutable version with that provenance and a well-defined covered set/checkpoint.
New diffs may arrive while reconstruction or upload is in progress. They must remain discoverable and pending for the next reconstruction/consolidation; publishing a snapshot must not overwrite or hide them. Do not claim to have included “everything” based on a scan whose observed set changed during processing.
Preserve independent branches and conflicting edits. Applying diffs is not permission to arbitrarily serialize conflicting changes or choose a winner. Reconstruction of an unambiguous requested version and merging divergent versions remain distinct operations, following the earlier ancestry/merge requirements.
Multiple clients may attempt consolidation simultaneously. Results must converge or remain explicitly reconcilable without losing edits. In designated-worker mode, define how exclusivity, restart/failover and stale-worker publication are handled without relying on an unverified claim that a process is the designated worker.
Required integrity and recovery properties
Each protected diff record must bind its exact base/parent, logical artifact/version, change identity, author/signing authority and resulting content integrity evidence. Verify the base, changes and reconstructed bytes before accepting the reconstructed version. Keep diff contents, filenames, dependency details and provenance encrypted.
Interrupted consolidation must be resumable or safely restartable. Retain sufficient verified bases, changes and snapshots for reconstruction and audit; do not discard inputs merely because an upload succeeded. Any eventual history cleanup needs an explicit retention/recovery policy and evidence that required versions remain reconstructible.
Research and validation requested
Evaluate suitable delta representations for text, binary files and archives; whole-container versus per-file diffs; chain length/checkpoint strategy; bounded reconstruction costs; large-file/chunk interaction; and the trade-offs between client-driven and designated-worker consolidation. Reuse mature approaches where appropriate rather than inventing a merge algorithm.
Validate concurrent writes and consolidations, new diffs arriving during snapshot upload, out-of-order or missing dependencies, duplicate deliveries, corrupted changes, worker restarts and partitioned sources. Compare correctness and resource costs across all three modes, including carriers without reliable conditional writes.
This is a proposed direction for investigation and feature design, not a claim that a particular diff algorithm, ordering rule or worker protocol is already selected or implemented.