Delivery protocol

Protocol version 1 is the common boundary for all five SDK families. Flutter and Web publish the localisync_sdk package on pub.dev and npm respectively, with public source repositories; native iOS, Android and React Native remain separate deliveries. packages/delivery-protocol contains shared schemas and a verification harness, not a customer SDK.

Request sequence

1. Send a distribution/channel-scoped bearer key to GET /delivery/v1/distributions/{id}/channels/{channel}/manifest.
2. Verify the compact JWS signature against a provisioned trusted key ID. Require alg: EdDSA, typ: localisync+json and Ed25519 key material. Never trust a key merely because a response advertises its ID.
3. Check distribution/channel scope and reject a revision older than the last accepted revision. Select the compatible publication with the largest activation sequence.
4. Fetch its release manifest, verify the SHA-256 digest from the channel catalog, signature, release identity and project.
5. Fetch locale files by the exact hashes and sizes in that release manifest. Verify each digest, release identity and locale. Include required fallback languages from the same release.
6. Activate a complete verified package atomically. Never combine languages from different releases or display unverified partial files.

When one address fails, try the other for the same immutable content. Keep the last verified package on network or integrity failure. The reference verifier exercises this sequence but does not implement application startup, disk cache or native SDK APIs.

Data and fallback

A locale file contains protocol/release/locale identity and entries with key name, plain or icu format, named variable contracts and an independent nullable value. null means Missing. Do not coerce it to a translated empty string. Follow the explicit manifest fallback graph only; regional locale names do not imply an extra link.

When another locale supplies an ICU message, format using that value’s locale rules. Preserve the common parameter names/types and require a verified compatible message before evaluation. Runtime files contain no customer email, audit history, file bindings, private notes or signing secrets.

Caching and authorization

The channel response includes an ETag and uses private revalidation. If-None-Match can return 304 after authorization. Immutable manifests and files use private immutable caching after scoped authorization. Shared proxy caching is disabled in the supplied Nginx configuration.

Read keys belong in the Authorization header. Web Origin must match the distribution’s exact allowlist; CORS does not replace a read key. Production keys do not grant Preview access. Revocation cannot delete bytes an application already holds.

Signing and rotation

The publishing worker alone holds the Ed25519 private key and signs deterministic UTF-8 JSON as compact JWS. Nodes and reference clients receive only a kid → public PEM trust map. Files use SHA-256. The JOSE Ed25519 specification and SemVer specification define the underlying formats.

Provision the new public key on both nodes and clients before switching the worker’s signing key ID. Restart nodes to load a changed trust map. Retain old public keys while retained manifests use them; do not remove trust for existing packages prematurely. A compromised-key rotation requires an explicit operational incident plan and republishing reviewed decisions, not accepting unsigned data.

See the delivery API reference for downloadable contracts. Internal deployment controls require separate management credentials and mTLS; they are not public read-key operations.