feat(http): add frontend-neutral mobile API readiness

[xicv]

Context and verdict

Minco 1.0 already had most of the protocol foundation required by native clients: one OpenAPI-first resource contract, RFC 9457-style problems, request IDs, opaque cursors, idempotent creates, strong ETags and If-Match, exact CORS policy, direct object-access signing, and API Gateway JWT principal mapping.

The audit found a narrower cross-client gap rather than a need for a separate mobile API:

• the default runtime CORS policy did not allow If-Match / If-None-Match, so browser clients could not use conditional resource requests through the standard stack;
• browser JavaScript could not read ETag, Location, authentication challenge, retry, link, deprecation, or sunset response metadata;
• the shared HTTP crate had no composable helper for standards-based bearer challenges, retry timing, or installed-client lifecycle signalling;
• the generated AWS HTTP API CORS policy did not carry the same request/exposure boundary, and API Gateway ignores backend CORS fields when gateway CORS is configured; and
• there was no authoritative guide separating browser constraints from native-client constraints, including direct/background transfers and current AWS sync-service constraints.

The intended architecture remains one business API for browser, iOS, Android, desktop, automation, and server clients. Client-specific concerns stay at authentication, transport, compatibility, optional attestation, and product-owned synchronization boundaries.

Changes

• Add ApiResponseMetadata / ApiResponse<T> wrappers that preserve the underlying Axum response while attaching:
  • Retry-After as delay-seconds or an application-supplied HTTP-date;
  • RFC 6750 WWW-Authenticate: Bearer challenges;
  • RFC 9745 Deprecation Structured Field Dates;
  • RFC 8594 Sunset; and
  • repeatable Link fields.
• Add non-exhaustive public error/challenge types and unit coverage for exact metadata, status preservation, both Retry-After forms, repeated links, and pre-Unix deprecation rejection.
• Extend the exact default HttpHeaderPolicy to:
  • allow If-Match and If-None-Match; and
  • expose ETag, Location, Retry-After, WWW-Authenticate, Link, Deprecation, Sunset, and X-Request-ID.
• Add a real middleware test for conditional-header preflight and browser-visible response metadata, while preserving the rule that plugin- and product-specific headers are never added globally.
• Add a small cross-client SAM wrapper that keeps the established renderer byte-identical while ensuring generated API Gateway HTTP API CORS accepts the conditional request fields and exposes the standard response fields.
• Update new-project templates, Orders deployment profiles, and checked-in AWS plan/template evidence at the exact CORS header boundaries.
• Add a current mobile/native API guide covering PKCE public clients, gateway principal mapping, bounded retries, domain-owned offline safety, direct presigned object transfer, installed-app compatibility, lifecycle metadata, optional App Attest / Play Integrity signals, API Gateway CORS ownership, and the 30 July 2026 Cognito Sync availability change.
• Add M14-T03 with exact scope, non-goals, owned paths, and evidence limits.

Compatibility and cost

• Additive public HTTP API only; no existing public type, field, route, operation, DTO, or repository is removed.
• No mobile-only API fork.
• No new crate dependency, AWS resource, worker, schedule, provisioned concurrency, NAT path, or idle cost.
• OpenAPI 3.1 remains canonical and no generated operation binding changes.
• The guide requires emitted/required fields to remain declared in each application's canonical OpenAPI document; transport helpers do not mutate contracts.
• Authorization remains application-owned; CORS and device attestation are not treated as authentication.
• The original SAM renderer remains unchanged; the new wrapper owns only the cross-client CORS normalization.

Research basis

Implementation follows current native-app OAuth and PKCE guidance, OAuth security BCP, bearer-token challenge rules, HTTP Problem Details, 429/Retry-After, HTTP deprecation/sunset standards, AWS HTTP API JWT authorizers and authoritative gateway CORS behavior, current Cognito Sync availability guidance, and current Apple/Google app-integrity guidance.

I also reviewed newer but separately scoped standards. The May 2026 IETF RateLimit fields remain an active Internet-Draft, so this shared default uses stable Retry-After rather than freezing a draft field shape. OpenAPI 3.2.0 is published, but this repository deliberately pins OpenAPI 3.1 in its ADR and compatibility tooling; migrating that contract baseline belongs in a separate toolchain-qualified change, not a mobile-only patch.

Validation status

• Exact comparison against main: one intentional commit and 19 changed files.
• No repository-wide formatting change was committed. Existing renderer source is byte-identical to main; modified configuration files change only the relevant header list.
• No repository-wide formatter or linter was run.
• The available environment has uv but no local Rust toolchain or chub; the private repository is accessible through the GitHub connector rather than a runnable checkout.
• This repository's qualification workflow is manual-only and does not run automatically for pull requests. No hosted workflow or status check is currently attached to this head.
• Compilation, tests, targeted formatting, lint, generator replay, and static validation are therefore not claimed as passes.
• The owning task records the exact targeted commands:
  • rustfmt +1.97.1 --edition 2024 --check crates/minco-http/src/lib.rs crates/minco-http/src/middleware.rs crates/minco-http/src/response.rs crates/minco-plan/src/lib.rs crates/minco-plan/src/sam_cross_client.rs
  • cargo +1.97.1 test -p minco-http -p minco-plan -p minco-cli --locked
  • bash scripts/aws/plan.sh
  • git diff --exit-code -- infra/aws/generated/plan.json infra/aws/generated/template.yaml
  • uv run --locked python scripts/validate_static.py

The PR remains draft until those exact checks run in an equipped checkout or the manual hosted workflow.

Release sequencing

main is currently the unpublished 1.1.0 candidate prepared by M14-T01. If this lands before M14-T02 publication, the 1.1 candidate and release evidence must be regenerated and requalified. Otherwise this branch should be rebased onto the next post-1.1 development boundary rather than changing an already promoted artifact.