Build a transport-neutral REST API demo without reusable client API keys

[bordumb]

Summary

Build a public REST API demonstration showing that an agent or client can make
authenticated GET and POST requests without receiving a reusable API key,
OAuth bearer token, session cookie, or downstream provider credential.

The caller presents an Auths proof. The API independently verifies that proof
against a canonical product action, trusted context, required/executed
configuration, and durable bounded state before reading protected data or
performing a mutation.

The product claim must be precise:

No reusable API credential in the agent. Each call carries independently
verifiable, bounded authority for what it is actually trying to do.

This is not anonymous access, and it is not a claim that credentials disappear
from every trusted backend. The proof is authorization evidence; any downstream
credential remains confined to the executor.

Why this matters

This demo should make several Auths properties understandable with ordinary
curl requests:

• authority is independent of the transport carrying the proof;
• HTTPS delivers bytes but does not define or upgrade authority;
• the caller does not possess a reusable shared secret;
• authority can cover one exact request or a bounded family of future actions;
• changing the executed action invalidates the authorization;
• replay cannot create a second effect;
• sensitive reads are bounded effects, not implicitly harmless operations;
• decision, execution, and observation are distinct receipt claims.

This is a direct and accessible contrast with API keys and broad OAuth
client-credential scopes.

Architectural constraint

Do not make raw HTTP the semantic authorization model and do not move HTTP
semantics into the formal core.

The required flow is:

HTTP request
  -> bounded application decoder and router
  -> typed canonical product action
  -> Auths verifier
  -> profile-specific verified command
  -> protected read or mutation

For example, authorize CreateDemoRecord or ReadDemoRecord, not an arbitrary
bag of method, URL, headers, and body bytes.

The same canonical action and verifier result must remain meaningful if the
action is later delivered through Iroh, a queue, a Unix socket, or another
exchange transport. HTTP is an adapter and enforcement location, not a new
authority algebra.

Keep the implementation outside core/ unless a genuinely
transport-independent primitive is identified and passes the repository core
promotion rules.

Demonstration

Provide a session-isolated public sandbox API:

POST /v1/records
GET  /v1/records/{id}

Each visitor receives a short-lived demo capability for an isolated namespace.
The browser must show a copyable curl command with an Auths proof and no API
key, OAuth token, or session cookie.

Exact POST

Authorize one exact action such as:

Create record "example-1" with value "hello" exactly once.

Experiments must include:

• valid exact request creates one real durable sandbox record;
• changing one body value is denied;
• changing the record identifier is denied;
• changing the method or route is denied;
• wrong audience is denied;
• expired proof is denied;
• required/executed configuration mismatch is denied;
• replay returns the durable result without a second write.

Bounded POST

Authorize a bounded envelope such as:

Create at most three records
in namespace "visitor-abc"
with bodies no larger than 1 KiB
during the next ten minutes.

The visitor chooses the concrete records after the capability is issued.
Durable state must enforce the aggregate limit under concurrent requests.
Boundary and boundary-plus-one behavior must be visible.

Exact or bounded GET

Authorize a disclosure such as:

Read record "example-1"
with fields "value" and "created_at"
with a maximum response of 4 KiB.

Attempts to read another namespace, another record, extra fields, a larger
result, or an expired capability must stop before protected data is returned.

UX

Use the established auths-proof-site design language and the interaction
grammar of the GitHub, Radicle, Stripe, and Kubernetes demos.

The policy/action controls and current result must be adjacent and visible
without scrolling. Show:

• request method, route, canonical action, and proof status;
• current verdict and stable code;
• whether protected storage was read or mutated;
• whether a reusable API key was present (false);
• reservation/replay state;
• required and executed configuration;
• exact action, evidence, policy, and receipt commitments;
• inline canonical receipt JSON;
• a designed dedicated receipt page.

Avoid vague slogans. Explain precisely what was authorized, what changed, and
whether an effect occurred.

Security requirements

• Hard byte, nesting, collection, field, response, and work limits before
  expensive parsing or protected access.
• Deny unknown action and policy fields.
• Explicit canonical JSON or raw-body rules.
• Exact method, application route, audience, content type, and relevant query
  binding.
• Defined behavior for duplicate query parameters, path decoding, proxy
  rewriting, and router normalization.
• Presenter-key or challenge binding so a captured proof does not silently
  become an unrestricted bearer token.
• Short expiration and explicit freshness.
• Required/executed configuration equality before persistence, protected
  reads, credentials, or mutations.
• Atomic replay and aggregate-budget state.
• Denial before protected database access or downstream credential acquisition.
• Exact response-disclosure constraints for GET.
• Separate decision, transition/execution, and observation receipts.
• Proofs, secrets, and protected response data excluded from ordinary access
  logs.
• Cross-proxy and router canonicalization tests.
• Lost-response, crash/restart, concurrency, replay, and reconciliation tests.

TLS remains required for confidentiality and theft resistance. Transport
independence does not mean transport security is irrelevant; it means transport
authentication is not the source of semantic authority.

Deliverables

• A numbered specification in docs/specs/.
• A cohesive vertical product package for the demo domain.
• Native Rust backend.
• Docker-local deployment reachable through an HTTP localhost URL.
• Complete frontend connected to the native backend.
• Public frontend and native API deployment.
• Canonical fixtures and mutation corpus.
• Browser end-to-end tests.
• Receipt API, inline receipt JSON, and dedicated receipt page.
• Architecture, debugging, local deployment, cloud deployment, and about/future
  work documentation.
• Architecture and compliance inventory registration.
• Redacted deployment and live-test evidence.
• A short design note describing a future auths-http middleware and OpenAPI
  integration without prematurely implementing a generic HTTP policy engine.

Acceptance criteria

• A visitor can copy and run successful GET and POST requests without
  receiving a reusable API key, bearer token, or session cookie.
• The API verifies the Auths proof locally against typed canonical product
  actions.
• Exact mutations occur once and replay produces no second effect.
• Bounded mutations conserve aggregate capacity under concurrency.
• Unauthorized reads return no protected data.
• Mutating method, route, query, body, audience, proof, or configuration
  produces the expected stable denial or indeterminate result.
• The same authority semantics are not coupled to HTTP transport details.
• Receipts distinguish authorization, attempted execution, and observed
  outcome.
• Local Docker, public deployment, browser E2E, compliance, and authoritative
  CI pass on the exact completed revision.

Non-goals

• Replacing TLS.
• Claiming anonymous or credential-free access.
• Putting reusable provider credentials in the caller.
• Authorizing arbitrary HTTP requests with unrestricted URLs, headers, or
  bodies.
• Moving HTTP routing or product policy into the formal core.
• Building a universal API gateway or generic policy language before the
  concrete vertical proves its semantics.