Media and HTTP

Softchat validates the bounded imeta union and performs compatibility or streaming attachment transforms. The host owns file descriptors, private staging, HTTP execution, redirects, background work, and final publication.

Attachment metadata

Operation contractmedia.metadata

Parse and preserve bounded Softchat imeta metadata.

Inputs and exact bounds

• at most 128 fields
• at most 16 fallback URLs

Output

Validated metadata retaining unknown fields.

Trust and authentication

Metadata does not authenticate downloaded bytes.

Stable errors

invalid_attachment_metadata · handling and retry rules

Ownership, lifecycle, and execution rules

Ownership

Rust owns protocol semantics, Android account SQLite/use-case state, and optional native relay I/O; the host owns account lifecycle, HTTP/media/background effects, files, and UI.

Retry

Retry only host transport or explicitly retryable session work; validation and authentication failures are permanent for the same input.

Lifecycle

Language ownership is automatic; explicitly cancel or erase only at the operation-specific authority boundary.

Concurrency

Serialize mutable session capabilities; immutable values follow the language type system.

Cancellation

The host owns async cancellation; use cancel, shutdown, close, or erase only where exposed.

Exact public symbols

Rust

parse_attachment_metadataAttachmentMetadata

Android

AttachmentMetadata.parse

Swift

AttachmentMetadata.init(tagValues:)

TypeScript

AttachmentMetadata.parse

Parse untrusted imeta tag values before using a URL, media type, size, hash, dimensions, duration, blurhash, or encryption fields. Unknown or malformed fields fail under the bounded Softchat profile. Waveform samples stay local and are not emitted in the interoperable tag.

Rust

let metadata = parse_attachment_metadata(vec![
    "url https://cdn.example/file".into(),
    "m image/jpeg".into(),
    "dim 1200x800".into(),
])?;

Android

val metadata = AttachmentMetadata.parse(
    listOf(
        "url https://cdn.example/file",
        "m image/jpeg",
        "dim 1200x800",
    ),
)

Use the validated URL only after the application’s network policy accepts it.

Swift

let metadata = try AttachmentMetadata(tagValues: [
    "url https://cdn.example/file",
    "m image/jpeg",
    "dim 1200x800",
])

TypeScript

const metadata = AttachmentMetadata.parse([
  "url https://cdn.example/file",
  "m image/jpeg",
  "dim 1200x800",
]);

Stream encryption

Operation contractmedia.encrypt

Stream attachment encryption into private staging.

Inputs and exact bounds

• chunks at most 1 MiB
• stream at most 16 GiB

Output

Nonce, ciphertext chunks, final tag, and hashes.

Trust and authentication

Output is private staging until finish succeeds.

Stable errors

attachment_too_large, attachment_encryption_failed · handling and retry rules

Ownership, lifecycle, and execution rules

Ownership

Rust owns protocol semantics, Android account SQLite/use-case state, and optional native relay I/O; the host owns account lifecycle, HTTP/media/background effects, files, and UI.

Retry

Retry only host transport or explicitly retryable session work; validation and authentication failures are permanent for the same input.

Lifecycle

Language ownership is automatic; explicitly cancel or erase only at the operation-specific authority boundary.

Concurrency

Serialize mutable session capabilities; immutable values follow the language type system.

Cancellation

The host owns async cancellation; use cancel, shutdown, close, or erase only where exposed.

Exact public symbols

Rust

AttachmentEncryptionStream

Android

AttachmentEncryptionStream

Swift

AttachmentEncryptionStream

TypeScript

AttachmentEncryptionStream

Create a stream with a 32-byte attachment key, persist its nonce with the encrypted object, feed bounded chunks, and store the final authentication tag and hashes returned by finish.

Rust

let stream = AttachmentEncryptionStream::new(key)?;
let nonce = stream.nonce();
for chunk in plaintext_chunks {
    encrypted_file.write_all(&stream.update(chunk)?)?;
}
let final_value = stream.finish()?;

Android

AttachmentEncryptionStream(key).use { stream ->
    val nonce = stream.nonce
    input.forEachChunk { output.write(stream.update(it)) }
    val finalValue = stream.finish()
}

Read and write in bounded chunks on an IO dispatcher. Use a private cache or app-files path; persist transfer state separately for WorkManager restart.

Swift

let stream = try AttachmentEncryptionStream(key: key)
let nonce = stream.nonce
for chunk in chunks {
    try encryptedHandle.write(contentsOf: stream.update(chunk))
}
let finalValue = try stream.finish()

TypeScript

const stream = new AttachmentEncryptionStream(key);
const nonce = stream.nonce;
for (const chunk of chunks) output.write(stream.update(chunk));
const finalValue = stream.finish();

Transfer chunk ArrayBuffers to a Worker rather than copying them through multiple application layers.

Rust

Measured performancedescriptive host audit

Median

109 µs

p95

109 µs

Equivalent rate

9,150 calls/s

Payload throughput

558 MiB/s

64,000-byte input · optimized Rust 1.97.0 on hosted Ubuntu 24.04 x86_64; 3 paired processes

Descriptive single-thread benchmark, 2026-07-26, revision 5e7c0c65e6e8. Full audit and methodology.

Android

Measured performanceone-device migration audit

Median

972 µs

p95

1.14 ms

Equivalent rate

1,030 calls/s

Payload throughput

62.8 MiB/s

Allocations

598 / call

64,000-byte input · non-debuggable AndroidX Benchmark on Pixel 9 Pro Fold, API 37 userdebug, arm64; 3 independent runs (30 legacy-pair or 50 public-account measurements each)

Descriptive single-thread benchmark, 2026-08-04, revision bb3cfc8ddc51. Full audit and methodology.

Swift

Measured performancemacOS host audit, not iOS

Median

681 µs

p95

688 µs

Equivalent rate

1,470 calls/s

Payload throughput

89.6 MiB/s

64,000-byte input · optimized SoftchatKit facade on hosted macOS 15 arm64, Swift 6.1.2; 3 paired processes

Descriptive single-thread benchmark, 2026-07-26, revision 5e7c0c65e6e8. Full audit and methodology.

TypeScript

Measured performanceNode/Wasm audit, not browser

Median

743 µs

p95

766 µs

Equivalent rate

1,350 calls/s

Payload throughput

82.1 MiB/s

64,000-byte input · authored package on hosted Ubuntu 24.04 x86_64, Node.js 22.23.1; 3 paired processes

Descriptive single-thread benchmark, 2026-07-26, revision 5e7c0c65e6e8. Full audit and methodology.

Authenticate before exposing plaintext

Operation contractmedia.decrypt

Stream attachment decryption with final authentication.

Inputs and exact bounds

• chunks at most 1 MiB
• stream at most 16 GiB

Output

Unauthenticated staged chunks then authenticated hashes.

Trust and authentication

All update output is untrusted and must be deleted unless finish succeeds.

Stable errors

attachment_too_large, attachment_decryption_failed · handling and retry rules

Ownership, lifecycle, and execution rules

Ownership

Rust owns protocol semantics, Android account SQLite/use-case state, and optional native relay I/O; the host owns account lifecycle, HTTP/media/background effects, files, and UI.

Retry

Retry only host transport or explicitly retryable session work; validation and authentication failures are permanent for the same input.

Lifecycle

Language ownership is automatic; explicitly cancel or erase only at the operation-specific authority boundary.

Concurrency

Serialize mutable session capabilities; immutable values follow the language type system.

Cancellation

The host owns async cancellation; use cancel, shutdown, close, or erase only where exposed.

Exact public symbols

Rust

AttachmentDecryptionStream

Android

AttachmentDecryptionStream

Swift

AttachmentDecryptionStream

TypeScript

AttachmentDecryptionStream

Decryption update returns staged bytes, not trusted media. Write them only to a private temporary destination. Call finish(authenticationTag) after the last ciphertext chunk. Only a successful finish permits an atomic move or UI exposure. On error or cancellation, delete the staging object.

Never stream unauthenticated plaintext directly to a decoder, gallery, media scanner, shared URL, or browser object URL.

Rust

let stream = AttachmentDecryptionStream::new(key, nonce)?;
for chunk in ciphertext_chunks {
    staging.write_all(&stream.update(chunk)?)?;
}
stream.finish(authentication_tag)?;
atomic_publish(staging)?;

Android

AttachmentDecryptionStream(key, nonce).use { stream ->
    encrypted.forEachChunk { staging.write(stream.update(it)) }
    stream.finish(authenticationTag)
}
atomicPublish(staging)

Delete the private staging file on cancellation, process loss, or any failure.

Swift

let stream = try AttachmentDecryptionStream(key: key, nonce: nonce)
for chunk in chunks {
    try staging.write(contentsOf: stream.update(chunk))
}
_ = try stream.finish(authenticationTag: authenticationTag)
try atomicPublish(staging)

TypeScript

const stream = new AttachmentDecryptionStream(key, nonce);
for (const chunk of chunks) staging.write(stream.update(chunk));
stream.finish(authenticationTag);
await atomicPublish(staging);

NIP-98 request plans

Operation contractmedia.nip98

Plan exact-request NIP-98 authorization without executing HTTP.

Inputs and exact bounds

• absolute normalized HTTP(S) URL from 1 through 8,192 UTF-8 bytes
• ASCII-letter HTTP method from 1 through 32 bytes
• optional request payload at most 16 MiB
• explicit timestamp from 0 through 9,007,199,254,740,991

Output

An immutable authorization header and verified event.

Trust and authentication

Redirects require a new exact-URL plan; headers must not be forwarded.

Stable errors

invalid_http_authorization · handling and retry rules

Ownership, lifecycle, and execution rules

Ownership

Rust owns protocol semantics, Android account SQLite/use-case state, and optional native relay I/O; the host owns account lifecycle, HTTP/media/background effects, files, and UI.

Retry

Retry only host transport or explicitly retryable session work; validation and authentication failures are permanent for the same input.

Lifecycle

Language ownership is automatic; explicitly cancel or erase only at the operation-specific authority boundary.

Concurrency

Serialize mutable session capabilities; immutable values follow the language type system.

Cancellation

The host owns async cancellation; use cancel, shutdown, close, or erase only where exposed.

Exact public symbols

Rust

create_nip98_authorizationHttpAuthorizationPlan

Android

SoftchatIdentity.createNip98AuthorizationHttpAuthorizationPlan

Swift

SoftchatIdentity.createNip98AuthorizationHttpAuthorizationPlan

TypeScript

SoftchatIdentity.createNip98AuthorizationHttpAuthorizationPlan

createNip98Authorization binds a signed event to one normalized method, exact URL, optional payload hash, and caller timestamp. The result contains the Authorization header and explicitly says that authorization must not be forwarded across a redirect. Methods are 1–32 ASCII letters, URLs are bounded to 8 KiB, and this whole-buffer helper hashes at most 16 MiB of request body. The Android account's media.authorizeUpload(method, url, payloadSha256) accepts an already streamed lowercase hexadecimal SHA-256, so larger uploads need no whole-body allocation. Hash the bytes required by the HTTP service's profile: the released Softrelay /api/v2/files endpoint authenticates the multipart file part, including the nonce and authentication tag for encrypted files. It excludes multipart boundaries and headers. Passing a hash of the full multipart body to that endpoint produces an authentication rejection even when the SDK signature is valid. A separate full-body digest can still protect the host's replay/stream integrity. Generic NIP-98 body hashing remains distinct from this file-service profile.

Rust

let plan = create_nip98_authorization(
    &identity,
    "PUT",
    url,
    Some(body.as_slice()),
    now,
)?;
http.execute(plan.method, plan.url, plan.authorization_header, body)?;

Android

val plan = identity.createNip98Authorization("PUT", url, body, now)
httpClient.execute(plan.method, plan.url, plan.authorizationHeader, body)

Execute the plan with the application’s maintained HTTP client. If the server redirects, strip the header and request a fresh plan for the exact new URL.

Swift

let plan = try identity.createNip98Authorization(
    method: "PUT", url: url, payload: body, createdAt: now
)

Build a URLRequest from the immutable plan. Keep URLSession delegate and redirect decisions in the application.

TypeScript

const plan = identity.createNip98Authorization("PUT", url, body, now);
await fetch(plan.url, {
  method: plan.method,
  headers: { Authorization: plan.authorizationHeader },
  body,
  redirect: "manual",
});

Do not reuse a plan for another method, URL, payload, redirect target, or timestamp.