The .arda
package.

Why a package at all

The alternative is a directory of files on the device's disk. That's fine when you own the machine. It stops being fine the moment the machine is on a customer's counter, because a directory of JavaScript is a directory of JavaScript — readable, copyable and modifiable by anyone with ten minutes and a USB stick.

A package gives you three things a directory can't: proof of origin (nobody can substitute a modified application), confidentiality (your business logic isn't sitting in plain text on hardware you don't control), and binding (a copied package won't run somewhere you didn't authorise).

Structure

A .arda file is a container with a small cleartext header followed by an encrypted payload. The header carries only what the runtime needs to decide whether to proceed — never anything about your application's contents.

┌─────────────────────────────────────────────┐
│ magic          "ARDA" + format version        │  cleartext
│ header         key id · binding mode · nonce │  cleartext
│ signature      ed25519 over header+payload   │  cleartext
├─────────────────────────────────────────────┤
│ payload        aes-256-gcm                   │
│   ├── manifest    arda.json                  │  encrypted
│   ├── index.html                              │  encrypted
│   ├── assets/…                                │  encrypted
│   └── integrity    per-file digests           │  encrypted
└─────────────────────────────────────────────┘

The payload is decrypted into memory at load. It is not unpacked to disk, so there is no window during which your application exists as readable files on the device.

Manifest schema

arda.json lives at the root of your project and is embedded in the package at build time.

Capabilities

Capabilities are declared at build time and enforced at load. An undeclared group is not present on the arda object at all — not a method that throws, but undefined. That distinction matters: a bug or a compromised dependency cannot call something that doesn't exist.

arda.system.info(), arda.system.log() and arda.app are always available and need no capability.

Signing and encryption

Two operations, in this order, both performed by the control plane when a release is deployed:

1. Encrypt — the payload is encrypted with AES-256-GCM under a content key. The GCM authentication tag means any modification to the ciphertext is detected on decryption.
2. Sign — an Ed25519 signature is computed over the header and the encrypted payload with the signing key held for your account. This proves the package was produced by ArdaForm for your account, and that nothing has altered it since.

The control plane packs, signs, stores and distributes the bytes. What the signature establishes is therefore that a package came from ArdaForm for your account and arrived unaltered — not that it was produced on a machine of yours. A device already trusts the control plane end to end: it pins that key at enrolment and fetches every byte through it, so this adds no party it was not already relying on.

Device binding

The bind field decides how portable the package is. Binding is enforced by the runtime at load, using values derived from the machine rather than supplied to it.

Verification order

Every check must pass before the application is allowed to run. Failure at any step means the package is discarded and the previously staged release keeps running — a bad package cannot take a device out of service.

1  magic and format version recognised          → else UNSUPPORTED_FORMAT
2  SHA-256 matches the update instruction       → else HASH_MISMATCH
3  Ed25519 signature valid for the key id       → else BAD_SIGNATURE
4  binding mode satisfied by this device        → else NOT_BOUND
5  AES-GCM tag verifies on decrypt              → else DECRYPT_FAILED
6  manifest parses and entry file present       → else BAD_MANIFEST
7  per-file integrity digests match             → else INTEGRITY_FAILED
8  capabilities resolved and bridge scoped      → load

The failure code is reported back to the control plane in the update status, so a rollout that fails on a subset of devices tells you why rather than merely that.

Key management

There is no key for you to generate, store or lose. A signing key is created for your account the first time you deploy, and the control plane holds it.

• One key per account. Every package deployed for you is signed with it, and your devices trust it from enrolment onwards.
• You never see the private half, so it cannot leak from a repository, a laptop or a CI secret store — which is where signing keys are usually lost.
• Rotation re-signs future packages. Packages already installed are not retroactively invalidated, and nothing on a device stops working because a key was rotated.
• The trade is explicit: the signature proves ArdaForm produced the package for your account, not that you produced it on your own machine. If you need the second guarantee, say so — it is a different design and we would rather hear it before you depend on this one.

A separate release key, held by the ArdaPlayer release pipeline rather than by you, signs runtime binary updates. The two are independent by design: neither can be used to forge the other's artefacts.

Limits

If you are approaching the size limit with media, put the media in device storage and sync it separately — bundling a gigabyte of video into every release makes every update a gigabyte download on a shop's broadband.