Service mode & the OpenAPI contract

The contract

Service mode is embedded mode plus transport: the same SDK wrapped in a thin first-party HTTP service that you deploy next to your backend. It adds no authority, exposes no extra options, and runs the identical nine-condition pipeline — there is no "lite" verification path. It exists so that non-Python backends (TypeScript today, PHP next) can integrate through transport-only clients.

The service speaks a versioned OpenAPI contract, frozen under the project's standards process, with exactly three operations: issue one signed challenge bound to the deployment's registered identity, validate one presentation and return the decision, and report the artifact's release pins (versions — never secrets). The frozen contract document ships to integrators with the SDK.

Semver at the contract level: decision semantics or reason-vocabulary changes are major; additive surface is minor.

Deliberately absent from the wire — these are invariants, not parameters: any lifetime setting (10 seconds is a constant), any skip flag for the conditions, and any per-request staleness widening (staleness policy is local deployment configuration, fixed at service start — a compromised web tier must not be able to widen what the service accepts).

Decision vs transport error

• Anything parseable into the contract schema flows through the pipeline and returns a decision — accept or reject — plus exactly one decision record server-side.
• A transport-level error exists only for bodies that cannot be parsed into the schema at all (no session identity exists, so no decision record is possible).
• If proven chain state is unavailable, the service refuses to issue a challenge — fail closed; retry, never work around.

Deploying

Notes that matter:

• Identity is deployment configuration (origin, verifier id, request key) — bound to your on-chain registrations, never accepted from HTTP callers.
• Challenge signing is your key custody. The service takes a request signer you provide — typically an HSM wrapper. An insecure unsigned mode exists for devnet integration only, and warns loudly.
• The built-in runner is a single-threaded reference server for devnet and integration; front it with your own web tier for anything more.
• The service holds no state: durability lives in the nonce store and the decision log you configured.

Trust boundaries, restated

Your service instance is part of your verifier. Deploy it inside your perimeter, point your transport clients at it, and never at anyone else's — outsourcing the service outsources the decision, which the protocol explicitly does not allow anyone to sell.