The target storage and access contract extends the object model to private storage, controlled sharing, groups, devices, and agents. The implementation guide defines how to replace or supplement dKMS/dDRM mechanisms while preserving Runtime authority and existing object formats. These are staged design instructions; the provider sequence below retains its own source and installed acceptance gates.
Protected content is Runtime-mediated. Library and Marketplace own the creator
and buyer experience, and elacity-player owns video presentation. Runtime
owns authority, durable operations, provider selection, Wallet and Chain
coordination, lifecycle, audit, and settlement.
The intended content-distribution contract gives free and protected content the same package identity and availability path. Protected content adds rights, key release, and decryption. See Content capsule distribution for the planned catalog and Get contract.
The canonical source path is implemented but inactive. Source tests cover
same-Runtime and two-Runtime journeys. The installed product still selects the
provisional drm, rights, key, and decrypt authority surfaces until the
installed proof and atomic cutover are complete.
The source path has one operation sequence:
- Library submits a typed source object and the permitted product terms.
- Runtime creates the durable operation identity and selects the private
media-provider. media-providerprepares bounded clear fMP4 in Runtime-authorized private staging. It owns probe and transcode process behavior.- The private protect provider encrypts the prepared media, provisions the immutable 2-of-3 custody envelope, and returns bounded identities and receipts.
- Runtime publishes the encrypted object through the normal
elastos://contentpath with an exact three-replica requirement. The existing repair task keeps that same requirement after replica loss. - Runtime binds creator mint and listing effects to the verified Wallet account and operator Chain configuration. It projects a listing only after the exact effect and finalized evidence agree.
- Marketplace reads bounded immutable listings. A buy request contains only the mint identity; Runtime derives the buyer, account, effect, and Chain authority.
- Before buy or open, Runtime verifies one fresh signed availability receipt for the exact mint, content identity, CID, publisher, provider, policy, replica count, and freshness window.
- Library or Marketplace asks Home to launch
elacity-playerwith an opaque, short-lived launch authority. Runtime binds the open to the principal, object, accepted viewer, launch, decrypt session, and token. - Three independent custody nodes evaluate rights locally. Any two approved nodes return recipient-encrypted contributions.
- The private protected-content decrypt provider reconstructs and uses the CEK inside its process. It serves bounded ordered media reads to the exact viewer session and settles open, read, and close ownership.
Source tests cover this sequence across two Runtimes with separate principals, Wallets, device identities and state. The creator exports an immutable listing package; the buyer imports and verifies it before purchase and playback. Custody release authenticates the buyer Runtime issuer declared by the signed operation and bound by the buyer Profile. The creator Runtime retains provisioning authority. The funded installed localhost-to-seed journey remains open. Shared listing links work independently of global listing discovery.
Runtime journals identities, state, receipts, and settlement. Providers keep clear media, ciphertext staging, CEKs, shares, process details, and private routes inside their owned boundaries. Carrier transports only Runtime-selected remote custody traffic. Storage, provider, Carrier, and Chain topology stays private.
ProviderRegistry owns four reserved Runtime-only targets:
protectmediacustodyprotected-content-decrypt
Capsule URI lookup, public provider proxying, interface projection, and route lists exclude all four targets. Runtime registers a target only after the provider returns the exact successful identity, a valid release version (it may differ from the Runtime's after a Runtime-only update), configured state, schema or protocol version, and ordered operation set. Rejected startup settles and reaps the child before it returns an error.
Protect, media, and decrypt run as local native provider processes. Custody can use Carrier to reach a Runtime-selected remote endpoint. Runtime keeps signed operation authority, provider selection, policy, and response verification.
The CENC KID and EncryptedContentIdentityV1 are separate:
- The KID is the exact bytes16 value used by the deployed rights read.
- The encrypted-content identity binds the complete protected object and media contract.
Verified deployed read behavior is:
AuthorityGateway.hasAccessByContentId(address,bytes16) -> boolowns access reads.CentralStorage.ipReference(bytes16)is the proven KID read resolution.- Unknown KIDs revert with
UnboundContentId(bytes16); a bound KID without access returnsfalse.
The configured Base 8453 contract uses these operations. Deployed verification evidence belongs in its GitHub issue:
CentralStorage.bindIP(bytes16,address,uint256)accepts acknowledged contracts only and is called byAssetFactory.registerNewAsset.- Native
AuthorityGateway.buyAccessuses selector0xf7580ad9. - ERC20
AuthorityGateway.buyAccessuses selector0x0ede2294; Wallet first approves the operativepaymentProcessor(). - EventHub is the mint event emitter.
- A deployed bound KID has recorded allowed, denied, and unbound results.
The exact funded buy receipt and event remain installed proof. Deployed access is one boolean per holder and KID, so signed Runtime policy owns the View and Download action distinction.
The operator supplies one owner-only
protected-content/chain-provider.json with one versioned
protected_content_network. Runtime supplies its operation issuer identity
separately. Each custody node uses its own node-host Chain provider, reads 2-5
explicit private RPC sources, and requires two exact agreeing finalized
results. Generic Chain configuration remains separate and is not a
protected-content fallback.
The source policy is exactly 2-of-3 across distinct operators and failure domains. Each custody node stores one share and checks the exact signed Runtime operation, Wallet subject, KID, full encrypted-content identity, action, custody epoch, policy, finalized rights evidence, recipient authorization, and time window.
CustodyEnvelopeV1 is private Runtime provisioning material. Runtime can
carry the envelope but cannot open the node-sealed shares. Public metadata
contains bounded identities, threshold and epoch facts, the CEK commitment,
and signatures.
The decrypt provider generates each operation-scoped recipient key and keeps the secret behind an opaque handle. The authenticated Profile authorizes the exact public key. Reconstruction uses the authenticated release operation, verified signed epoch, released contributions and terminal receipt, recipient possession, and public CEK commitment. Runtime stores no playback custody envelope or sealed-share bytes. Close expires the launch authority and settles Runtime, decrypt, viewer, and staging ownership.
The current confidentiality suite is
elastos-xwing-draft06-hkdf-sha256-aes256gcm/v1 for new protected content.
External cryptographic review remains open before public dKMS or production
confidentiality claims.
Capsules receive typed object identities, product terms, progress, immutable listing projections, opaque launch authority, and bounded media output. Runtime derives the principal, Wallet account, Chain authority, provider selection, availability decision, rights evidence, and effect identity.
Visible protected-content UI may ship only as a disabled/read-only readiness rail until the installed path and atomic cutover pass. Source behavior alone is not installed or live product evidence.
Full scripts/setup-source-home.sh installs the stable Runtime under the
platform data root at bin/elastos. It writes the owner-only
receipts/source-home-installation.json receipt after components, native
providers, capsule trees, and source-home capsule metadata are final.
Run scripts/protected-content-installed-static-audit.py with explicit source
root, installed data root, installed Runtime, platform, profile, and role. Its
bounded redacted receipt separates:
- source and static artifact failures;
- operator configuration prerequisites; and
- active installed proof prerequisites.
ready_for_active_proof means the static artifacts and supplied operator
configuration passed admission. Runtime startup, signed custody validation,
live Chain evidence, replication and repair, and mint-buy-play remain active
proof.
Operator provisioning of that configuration is one explicit command surface,
elastos protected-content-config. It creates the policy authority key,
provisions each custody host's inactive state root and exports its node
descriptor, prints the Runtime operation issuer custody hosts must trust,
assembles and signs the owner-only 2-of-3 custody composition from three node
descriptors, and installs the private multi-source Chain configuration. A
generated composition or Chain configuration is proven against the Runtime
loader before success is reported, and an installed composition can be
re-verified in place. The installer never creates this operator state.
The macOS and Linux source-home restart helpers validate the installation receipt and current clean source before any stop or migration. They select only the stable installed Runtime, own one exact PID file, stop only the proven prior Runtime, preserve one bounded principal-root rollback, and write one owner-only restart receipt.
Principal-root migration writes encrypted rollback objects bound to the principal, root, object URI and recovery data key. Runtime can restore the original plaintext during migration recovery. It keeps the rollback payload through release recovery and Home acceptance. Every Home start, local or public and whether the installed Home controller, the installer or the owner started it, then removes verified payload files and keeps the migration receipts.
Home start, elastos update and Recovery status read the label at the start
of each file in the protected folders, a few kilobytes for an encrypted file.
A file without a label is read whole only when it is at most 16 MiB, to tell an
unencrypted file from a damaged one, and one pass reads at most 80 MiB of such
files. A file left over once that is spent is named as not checked in this
pass and treated as damaged until a later pass checks it. They check three
things: no unencrypted file was found, each encrypted file is labelled for this
Home's current key and for the place where it is stored, and no interrupted
encryption step is waiting. Large files and large totals do not stop Home.
File contents are checked when a file is opened: Home runs the full AES-GCM
check over the whole file and uses none of it unless the check passes. A file
that looks encrypted but does not carry a correct label is damaged. This
includes a file of your own that only looks like an encrypted file; it stays
unencrypted until you upload it again in Library. A damaged file is named in
the start log and in Recovery status, shows as Blocked in Library, and is never
encrypted again. Home never changes or deletes it by itself; a Library save
over it, Empty Trash, or a new or reset background image in System →
Appearance (for a damaged background image) still can.
Cleanup holds the installation writer lock and verifies the signed installed release, exact Home process and generation, host ownership, health response, private attach, served Home hash and configured protected roots. An active release transaction or migration journal keeps its recovery copies until it finishes. A source-home deployment keeps its encrypted copies until the installed release acceptance gate passes. Its owner also reconciles the restart receipt and payload-free proof directory before the next source-home restart.
Cleanup also checks older Runtime migration and upgrade directories under
backups/. It imports a legacy plaintext backup only when its committed
receipt, object inventory, file names, hashes and ownership agree; a backup
that fails any of these checks stays in place and is reported on each Home
start. The owner of such a backup, or of an older manual backup outside
backups/, supplies the original owner-only plan and exact backup directory:
"$ELASTOS_INSTALLED_RUNTIME" principal-root-cleanup \
--data-dir "$ELASTOS_DATA_DIR" \
--binary "$ELASTOS_INSTALLED_RUNTIME" \
--plan "$ELASTOS_MIGRATION_PLAN" \
--backup-dir "$ELASTOS_MIGRATION_BACKUP"Keep the original plan bytes, including formatting, because the receipt binds their hash. A missing plan or receipt, changed payload, link, or uncertain directory stays with its owner for reconciliation. These cleanup gaps are reported while Home remains available. Cleanup durably removes the verified files from the active filesystem; earlier snapshots and external copies have their own retention policy. The recovery key remains available for active protected objects, so this cleanup does not claim physical or cryptographic erasure.
elastos run <provider> [--with <provider>]... --carrier-addr <addr> hosts
one or more native providers standalone, outside the full Home/gateway
supervisor tree, and writes an owner-only readiness receipt at
<data_dir>/run/provider-host.ready.json once every requested provider is
registered and Carrier is bound. A custody node process is exactly this
composition: elastos run custody-provider --with availability-provider --with ipfs-provider --with chain-provider --carrier-addr <addr>. The chain
plane is not optional on a committee member: a node settles every release
by evaluating the rights request through its own
protected_content_rights_evidence call, so the host refuses to start the
chain plane without a protected-content/chain-provider.json naming the
protected-content network, and its evidence RPC URLs must be reachable from
the node itself (not only from the client).
deploy/custody-host/ builds a simulation-only container image of that
composition plus a same-host, container-per-node compose harness for three
custody nodes. Its own README states the simulation boundary explicitly:
process isolation and real Carrier transport between the containers are
faithfully simulated, but distinct hardware, distinct operators, and
distinct failure domains are not, and the image must never hold a real
recipient's key material. The operator flow over that harness is: each
node's container provisions its inactive custody state and exports a
DID-named public descriptor to a shared handoff directory on first boot, and
reads the client's protected-content chain configuration back from that same
directory on every boot (up.sh sync-chain-config derives it, rewriting
host-loopback evidence RPC URLs to the container-reachable host gateway); the
operator runs elastos node peer add against each node's exported connect
ticket from the client Runtime; the operator then runs the offline
composition ceremony described above over the three descriptors to
assemble and sign the owner-only 2-of-3 composition; a node restart (the
platform restart helper, or the container's own restart) proves the node
returns with the same DID and no required environment; and the installed
proof driver script (see scripts/README.md) drives
the resulting composition end to end.
Protected content is off by default in 0.8.0. Home shows its surfaces only
after elastos config set protected_content true.
#388 owns the rebuild
after 0.8.0, its ordered proof and its acceptance.