FOR DEVELOPERS / PROTOCOL

What travels through an AmoosedWeb site.

An illustrated map of the v1 document, media carriers, resource verification, and access paths. This page explains the system to humans; the full format specification defines the exact byte contract, field encodings, and limits.

One index, many verified resources

The compiler starts with an ordinary site and an app. It places the app index in the site's discovery favicon by default, then assigns app resource parts to existing media files. The host serves ordinary pages, the favicon, media, and the site-owned runtime routes. A Reader or browser runtime uses the index to locate and check every part before exposing a reconstructed resource.

AmoosedWeb build and read flowSite and app inputs go to the compiler. It emits ordinary pages, a discovery index, and media carriers. A Reader checks the index and carrier parts and exposes verified resources.Authored inputssite/ + app/document + bundleCompilerbuild + verifyPublished originordinary pages + runtime/favicon.ico index*existing media + app partsReader / browser workerlocate → hash → decodeverify complete resource*External-index editions keep the ordinary favicon and deliver a separate bearer credential.
Published app parts live in media the site already serves. The carrier paths and checksums live in the verified index.

The /amoosed.com/app/* paths are virtual: the same-origin worker serves them from checked carrier bytes. A Node.js, .NET, or native Reader can fetch resources without installing the browser runtime. An overlay alone cannot install the browser route; the host must also serve the site-owned runtime. See the host contract.

The AMW v1 document and its footer

An AMW payload starts with a 4,096-byte fixed header. Its manifest is UTF-8 JSON with exactly two contiguous v1 sections: bootstrap and document. The header supplies lengths, offsets, and SHA-256 digests for the manifest and bootstrap. The manifest supplies section digests. AMW integers are unsigned little endian; PNG and MP4 container fields keep their native big-endian encoding.

AMW payload and appended carrier layoutThe original media bytes are followed by a payload made of a 4096-byte header, manifest, bootstrap, and full document, then a 128-byte footer at the end of the file.Universal appended carrierOriginal mediaunchanged prefixFixed header4,096 bytesManifestsection mapBootstrapintroDocumentcomplete indexFooter128 bytescomplete AMW payload; max 1 GiB
For a universal appended carrier, the footer starts exactly 128 bytes before EOF. The footer points to the complete AMW payload.
StructureKey fieldsWhy it matters
Header, 4,096 bytesAMW1DOC\0, version 1, payload length, manifest and bootstrap offsets, SHA-256 digestsGives a bounded, versioned way to find and validate the first sections.
Section manifestamw.sections.v1; bootstrap then document; absolute payload offsets, lengths, SHA-256Separates a short intro from the complete document without guessing boundaries.
Universal footer, 128 bytesAMW1TAIL, original length, payload offset and length, complete hashes; v2 also stores a truncated bootstrap-prefix digestAllows suffix discovery and a checked progressive intro in v2.

A footer v2 Reader may show the intro after validating its anchored prefix and section digests. Footer v1 and bare .amw readers wait for the complete document check first. The full payload digest remains mandatory before accepting the full document. See the exact header and footer tables.

Where resource parts go

The default app data carrier appends encoded parts and an AMW1DATA footer to an existing opaque file. PNG chunk and MP4 UUID modes place data inside a native container structure and retain a data footer. Pixel, tone, and frame modes encode data in image pixels or audio samples; their offsets refer to decoded payloads, so readers fetch and decode the complete media before checking shards.

ModePlacementReader behavior
appendOriginal bytes + contiguous app data + 128-byte data footerRead exact byte ranges; verify stored part hashes.
png-chunk, mp4-uuidPNG amWd chunk or MP4 top-level uuid box + data footerRead byte-addressed parts inside the inserted container data.
png-pixelsLow RGB bits of an opaque PNG; no data footerFetch whole lossless image; recover and hash pixel payload and shards.
wav-tonesRepeated audible tones in a rewritten PCM WAVFetch whole WAV; demodulate, verify packets and shards.
frame-lumaRepeated sparse red low bits in a lossless PNG frameFetch whole frame; majority vote and hash the recovered small shard.

Serve carrier bytes unchanged. Image optimization, resizing, audio conversion, transcoding, or stripping a trailing footer can break recovery. The media profile does not grant access or prove publisher identity. For exact capacity limits, offsets, and legacy variants, use the full format specification and MEDIA-TRANSPORT.md.

The verified read sequence

For the default hosted profile, the favicon carries a public AMW index and an AES-CTR data key. The index maps each virtual resource to ordered carrier parts. The Reader checks stored bytes against the index before decoding, checks any member ciphertext before using its plaintext, then checks the assembled resource's length and SHA-256.

Hosted resource read sequenceThe caller asks a Reader for a virtual resource. The Reader fetches and validates the favicon index, requests part ranges from the origin, checks part hashes, decodes the public AES-CTR layer, optionally authenticates member AES-GCM, checks the assembled resource hash, and returns verified bytes.CallerReader / workerSame-origin hostopen site / request resourceGET /favicon.ico (hosted profile)AMW index carriercheck footer, payload,manifest and indexGET required carrier bytes / mediapart bytes or decoded-media sourcecheck stored-part hashesAES-CTR decodeoptional member GCM opencheck final length + SHA-256verified resource or error
Each resource can span several carrier parts. The sequence is repeated as needed; no unverified resource is returned.
  1. Discover and verify the index. A site root conventionally uses /favicon.ico; an explicit carrier URL can also be opened.
  2. Find the resource entry and retrieve its ordered parts. Byte-addressed carriers can use HTTP ranges; pixel, tone, and frame codecs need their complete media file.
  3. Verify each stored part hash, apply the site's AES-256-CTR transform when declared, then authenticate AES-256-GCM member parts when present.
  4. Assemble the resource and verify its declared plaintext length and SHA-256 before serving or saving it.

SHA-256 detects mismatch against the fetched index; it is not a publisher signature if an attacker can replace both the index and the carriers. HTTPS authenticates transport. The Reader does not fetch an unrelated original media prefix just to check its footer hash during a range read. See browser runtime behavior and host byte and route requirements.

Public, external, and member access

The hosted favicon profile makes the index and its AES-CTR key public. This transform obscures casual plaintext inspection of detached carrier parts; it is not secrecy. An external-index edition leaves the ordinary favicon unchanged and encrypts the complete index with AES-256-GCM in a byte-addressable first data carrier. The user receives a separate .amwkey, packed ICO, or equivalent AMQ1 token containing the index key and carrier locator.

Three access pathsThe public path verifies a hosted favicon index. The external path uses a bearer credential to locate and authenticate an encrypted index. The member path uses a separate member key to authenticate protected parts after the index is known. All paths end with verified resources.Hostedpublic /favicon.ico indexverified part map + CTR keyverified public resourceExternal.amwkey / ICO / AMQ1hash + GCM-open encryptedindex in first data carrierverified resource mapMembers.amwmember / AMM1match key ID + GCM-openprotected resource partsverified member resourceExternal and member credentials may both be needed for a protected external-index edition.
Index credentials and member credentials are separate. Both are transferable bearer secrets for matching releases.

A member edition may mix public and protected resources. Member parts use AES-256-GCM and a separate member key; the website CTR layer is applied afterward in the carrier. An external index credential is saved in origin-scoped IndexedDB only after the worker authenticates the current site's encrypted index and app identity. A member key is retained only in volatile worker memory after a protected chunk is authenticated; a worker restart may require entry again. A QR, URL token, or key file can be forwarded; old complete releases remain accessible to holders of matching old credentials. Read the access model and rotation limits before designing an entitlement flow.

Continue with the exact contracts

Runtime and host

Same-origin boot and worker behavior, route mapping, HTTP ranges, and byte-preserving deployment.

Read the host contract →

SDK surfaces

Reader methods, native public headers, and integration examples for products.

Choose an SDK →

Public protocol specifications and developer examples are distributed under the protocol and developer examples license; package-specific terms control each package.