[Epic] First-class application-to-application service access #873

Reconciliation — 2026-10-05

The generic Mercaria → Moovo resource-grant epic remains open. The accepted #1519/#1571 work provides these reusable milestones:

• Asymmetric service-token/JWKS foundation (Move Oxy service tokens to asymmetric signing and JWKS verification #877), canonical workload identity and published shared receiver adoption: ADR0012; ADR0026; ADR0035; I04/I11 accepted publication, consumer and runtime evidence.
• Explicit Alia machine-principal SDK and consumer adoption shipped (Oxy #1577, Alia #666). This is the Alia-specific app-only contract, not the generic service-grant model below.

The unchecked child issues and generic cross-resource acceptance remain pending. In particular, no accepted evidence here establishes a Mercaria→Moovo resource audience/grant plus generic incoming/outgoing Console administration. The original specification below is retained; prior dated status is historical.

Status 2026-09-30 (audited against main f345d27)
#877 (EdDSA service tokens + JWKS, HS256 removed) is DONE (ADR 0012, #1374). Nothing else has landed. Related, not part of this epic: ADR 0026 workload identities (first-party services authenticate as their infra role; tokens still aud: oxy-api) — the Mercaria/Moovo canary credentials should now be workload identities. Per project rules (no real users, clean cut, no config switches): drop the "migration path", compatibility routes and rollout flags from criteria and children.

Outcome

Oxy Console and Oxy Auth become the single control plane for service-to-service access across the Oxy ecosystem.

A registered Oxy Application is the canonical identity of a product such as Mercaria or Moovo. Applications can call another application's API with short-lived, audience-bound service tokens and explicit grants, without creating duplicate application records, sharing ad hoc secrets, or adding one-off authorization systems to each repository.

Non-negotiable identity rules

1. One real product has one canonical Oxy Application identity.
2. Mercaria, Moovo, Oxy Pay and other products may have several credentials by environment or workload, but those credentials all belong to the existing application.
3. A service grant is a relationship between two applications, not another identity.
4. The caller application id is derived from a verified token, never accepted from a request body, query parameter or arbitrary header.
5. ApplicationCredential.publicKey is a client id for one credential; it is not the application id.
6. credentialId is retained for audit, rotation and revocation; it does not replace application ownership.
7. Backend-to-backend service permission is separate from user OAuth consent and must not be placed indiscriminately in user-facing Application.scopes.
8. Service access is environment-bound. Development or staging credentials cannot call production resources.
9. Resource servers verify the intended audience and exact granted scopes.
10. No shared SERVICE_SECRET, synthetic appId: internal, or application-name allowlist may be introduced as a shortcut.

Target model

Application: Mercaria
  -> ApplicationCredential: production API
  -> ApplicationServiceGrant
       resource: Moovo
       environment: production
       scopes: transport quotes/create/read/returns

Application: Moovo
  -> exposes versioned service API capabilities
  -> accepts an audience-bound token whose caller is Mercaria

The token identity remains:

caller application = Mercaria Application id
audience/resource = Moovo Application id
credential = exact Mercaria service credential
environment = production
effective scopes = requested scopes constrained by resource API, grant and credential

Child issues

Architecture and authority

• ADR: define canonical application principals, resource audiences and service grants #874
• Model resource service APIs and application-to-application grants #875

Token issuance and verification

• Mint audience-bound service tokens from application grants #876
• Move Oxy service tokens to asymmetric signing and JWKS verification #877

Shared SDK and control plane

• Add audience-aware service clients and resource-server auth to @oxy.so/core #878
• Add generic application service access management to Oxy Console #879

Migration and cleanup

• Migrate existing service-token consumers to the generic application service-access model #880

Recommended execution order

1. Complete ADR: define canonical application principals, resource audiences and service grants #874 first.
2. After ADR: define canonical application principals, resource audiences and service grants #874, Model resource service APIs and application-to-application grants #875 and the cryptographic design/implementation in Move Oxy service tokens to asymmetric signing and JWKS verification #877 can proceed in parallel.
3. Implement Mint audience-bound service tokens from application grants #876 once the grant query contract from Model resource service APIs and application-to-application grants #875 is stable; token-claim work may coordinate with Move Oxy service tokens to asymmetric signing and JWKS verification #877 in parallel.
4. Build Add audience-aware service clients and resource-server auth to @oxy.so/core #878 against the accepted token, JWKS and grant contracts.
5. Build Add generic application service access management to Oxy Console #879 against the stable Model resource service APIs and application-to-application grants #875 APIs; its UI work can proceed in parallel with Mint audience-bound service tokens from application grants #876 through Add audience-aware service clients and resource-server auth to @oxy.so/core #878 after contracts are fixed.
6. Complete Migrate existing service-token consumers to the generic application service-access model #880 after the foundations are usable in at least one canary resource server.
7. Consumer repositories remove local shared-secret paths only after Add audience-aware service clients and resource-server auth to @oxy.so/core #878 is published and their audience/grants exist.

Cross-repository canary

The first complete canary is:

Existing Mercaria Application
  -> audience-bound token
  -> existing Moovo Application
  -> Moovo resource API

Mercaria acts as its application principal for both authenticated and guest orders. It does not impersonate the buyer merely because the buyer is the shipment recipient.

Completion criteria

1. An existing Mercaria application credential can mint a short-lived token specifically for the existing Moovo application.
2. Moovo can verify the token, audience, environment and scopes through the shared SDK without consulting a local application allowlist.
3. Revoking the grant or credential prevents new usable tokens and is visible in Console and audit history.
4. No duplicate Mercaria or Moovo application is created.
5. User OAuth permissions and backend service permissions remain distinct.
6. Oxy Console is the only administrative control plane for application identity, credentials and service grants.
7. Existing service-token consumers have a documented, tested migration path.
8. Shared-secret and synthetic-principal paths can be removed from consumer repositories without replacing them with another local auth framework.