NAP-UPLOAD: shell-mediated file and blob upload

[dskvr]

Summary

Adds NAP-UPLOAD, a shell-mediated upload interface for napplets. Napplets can inspect coarse upload rail support with optional upload.info, then hand the shell raw bytes plus upload intent. The shell selects or validates a rail, signs rail authorization, performs the upload, reports progress/status, and returns URL plus integrity metadata for attaching the result to Nostr events.

The interface is named around uploading rather than any single protocol so shells can support multiple storage rails without changing the napplet API. NIP-96 HTTP file storage and Blossom blob storage are the first concrete backends; result metadata follows NIP-94 so a napplet can publish a file event or build an imeta tag through NAP-RELAY.

Namespace

window.napplet.upload

Status

draft

Changes

• Defines upload.info, upload.upload, upload.status, and shell-pushed upload.status.changed.
• Keeps upload.info advisory; it is not a required preflight before upload.upload.
• Models rails as nip96, blossom, or runtime-defined strings.
• Returns sha256 / originalSha256, URL/fallback URLs, MIME, dimensions, blurhash, and ready-to-attach NIP-94 tags when available.
• Keeps server selection, credentials, NIP-98/BUD authorization signing, quota/MIME policy, progress, and consent runtime-owned.

Downstream

Napplets submit file bytes and intent, not signing keys, server credentials, or direct HTTP access. Runtimes can expose coarse rail availability for UI adaptation while preserving the direct upload path for callers that skip introspection.

Reference

• NIP-5D napplet transport and shell boundary
• NIP-96 (HTTP file storage), Blossom (blob storage), NIP-94 (file metadata), NIP-98 (HTTP auth)

Changelog

• 5dd8458 - Introduced NAP-UPLOAD for shell-mediated file and blob upload.
• ef147c9 - Added upload.info rail introspection for supported upload rails and policy limits.

[dskvr]

fix code smell upload.upload

[hzrd149]

I think NAP-UPLOAD is missing a small introspection endpoint.

Suggested addition:

upload.info() -> UploadInfo

Purpose: let napplets optionally inspect which upload rails the runtime supports, without making rail selection mandatory.

Example shape:

UploadInfo = {
  rails: [* UploadRailInfo],
  ? maxBytes: uint,
  ? mimeTypes: [* tstr],
}

UploadRailInfo = {
  rail: tstr,          ; "nip96" / "blossom" / ...
  enabled: bool,
  ? returns: [* tstr], ; URI/result forms, e.g. "https" / "blossom"
}

Important semantics:

• Napplets MAY call upload.info() to adapt UI or intentionally choose a rail.
• Napplets MUST NOT be required to call info() before upload().
• upload({ data, ... }) with no rail should remain the simple/default path: the runtime selects the best configured rail according to user/runtime policy.
• If rail is supplied, the runtime SHOULD honor it when supported and allowed; otherwise return unsupported rail.

This preserves runtime-owned defaults while giving advanced napplets a clean way to discover supported protocols and expected returned URI forms.

[jodobear]

While implementing Blossom uploads in Kehto/Paja, we added ordered replication across configured servers. The first verified upload is returned as url, with later verified copies in fallbackUrls. Failures for individual servers remain internal to the host.

The current NAP-UPLOAD result cannot describe what happened for each attempted server when some replicas fail and others succeed. Would per-attempt outcomes or machine-readable error codes be useful here, while keeping url and fallbackUrls backward compatible?

This is implementation feedback, not a proposed schema. Kehto has not added any custom wire fields.

[hzrd149]

The current NAP-UPLOAD result cannot describe what happened for each attempted server when some replicas fail and others succeed. Would per-attempt outcomes or machine-readable error codes be useful here, while keeping url and fallbackUrls backward compatible?

The napplet that is using this api shouldn't care or be aware of what protocol is being used. IMO the intent with this api is to upload bytes from a napplet and return a single publicly accessible URL