PMIS Federation Transport

Features

• Company-scoped connections with one direction, capability, peer pair, and organization delegation.

• Native expiring API keys with exact pmis.federation scope.

• Receiver-approved scoped key rollover with a bounded overlap deadline.

• A bounded HTTPS/JSON endpoint without session-authentication fallback.

• Immutable outgoing operations and transactional incoming receipts.

• Digest-based replay protection, locked dispatch, bounded retries, and administrator review.

• External database/instance/environment binding.

• Shared-login RS256/PKCE primitives and deadline-bounded pinned HTTPS exchange, used by the separate Provider and Login adapters.

• Account-independent v1 order contract validation for RFQs, quotations, and confirmed purchase/sales orders, with frozen party/address references, productless lines, quotation dependencies, and tax-exclusive decimal amounts.

The order contract is available to adapter developers. It does not enable order delivery through the current HTTP endpoint or create native orders.

Connections and access

Depends on pmis_federation_core and Python urllib3, PyJWT, and cryptography. Administrators manage Federation > Delivery > Service Connections and delivery records within their allowed Directory Owner companies.

Each incoming connection has a separate active portal-type Federation Service Principal with company access and no internal groups. The principal has no direct directory, inbox, or outbox access. Outgoing credentials belong to protected worker configuration, not connection fields.

PMIS_FEDERATION_RUNTIME binds the exact database name and UUID, local instance UUID, environment, and future expiry. Outgoing entries also bind the endpoint, approved IP addresses, and scoped bearer token. Missing, expired, or mismatched bindings block incoming mutations and outgoing delivery.

Federation: dispatch queued profiles is inactive by default. When enabled, it runs every minute and selects at most 20 due operations.

Supported operations

POST /pmis/federation/v1/operations requires HTTPS, a bearer key, application/json, and Content-Length. Version 1 supports:

• profile.observe: remote account observations received by Hub.

• profile.apply: revision-checked profile updates applied by Account.

• membership.provision: assigned account creation handled by Account.

• account.disable: explicit one-way disablement of provisioned accounts by Account.

Unknown fields/capabilities, malformed UUIDs, duplicate JSON keys, nonfinite constants, invalid revisions, and human-actor claims are rejected. Requests and responses are limited to 64 KiB. Organization scope contains 1 to 100 distinct delegated UUIDs.

See the wire reference for exact schemas.

Delivery behavior

Business adapters create queue entries in their own transactions. Dispatch rechecks payload integrity, current delegation, runtime binding, and target state. The receiver commits the business effect and receipt together. Identical replay returns the stored result; changed-data replay is rejected. POST /pmis/federation/v1/receipts accepts the same bounded envelope and service authentication, but only retrieves an existing receipt. It never executes a business operation. Missing evidence returns HTTP 404 and does not prove absence of a remote account.

Outgoing Operations exposes pending, succeeded, review-required, and discarded operations. Incoming Receipts retains outcomes and authenticated attribution. Public writes cannot replace operation content.

Transient network errors, HTTP 408/429, and server failures back off from 30 seconds to one hour. Eight automatic attempts require review. Redirects, permanent failures, and invalid acknowledgments require review. Administrator Retry preserves operation UUID, payload, and attempt count.

The sender pins an approved resolved IP while preserving hostname/certificate verification. Redirects are not followed. Loopback, link-local, multicast, and unspecified addresses are denied; private addresses need explicit approval. Connect/read timeouts are five/fifteen seconds. A thirty-second total delivery deadline bounds DNS resolution, TCP/TLS setup, request transmission, status/header reads, chunk framing, and body reads. Deadline failures use the existing bounded retry workflow and preserve the operation identity for uncertain remote effects.

Current boundaries

account.inspect uses the separately delegated, authenticated read-only POST /pmis/federation/v1/state endpoint when Account is installed. It is an additive version-1 capability advertised by scoped capability discovery. Queries use the same JSON, runtime, pinned HTTPS, and deadline safeguards as delivery, but cannot be queued or submitted to operations/receipts endpoints. Repeated queries inspect current state without replay receipts or business effects.

• Copying external credentials and host settings requires separate host isolation; database runtime binding cannot isolate those copies.

• Module uninstall requires stopped delivery and an acknowledged current history export.

See the repository-wide development backlog.

Discovery and receipt recovery

Authenticated GET /pmis/federation/v1/capabilities reports protocol support, the payload limit, receipt lookup support, and only the authenticated connection's capability when its receiver adapter is installed. Receiver policy still applies.

Before every operation, state query, or receipt lookup, the sender checks this discovery response through the same pinned HTTPS destination and scoped credential. Discovery and the subsequent request share one thirty-second deadline. Version 1 remains usable when a peer also advertises newer versions or unknown capabilities; the queued version, UUID, digest, and payload are never changed for negotiation. The requested capability and peer payload limit must match. Receipt recovery needs version, size, and receipt support, but not an installed business adapter.

Missing discovery (including an older peer returning HTTP 404), malformed replies, unsupported versions/capabilities, and insufficient byte limits prevent the request and require review. HTTP 408/429, server errors, and network failures retain normal bounded retry behavior. Discovery never substitutes for target authorization.

Administrators use Reconcile Receipt in Outgoing Operations to retrieve historical evidence for observations, profile updates, provisioning, and disablement. Installed business adapters recheck the target. Lookup never replays an effect or resets attempts; a missing receipt preserves uncertainty. Historical evidence does not establish the receiver's current state after independent local changes.

Service credential revocation

On an incoming connection, Revoke Federation Service Keys lets a company-authorized administrator remove all native API keys with the exact pmis.federation scope for that connection's dedicated principal. The action also works on archived connections, so traffic need not be enabled to revoke credentials. Other principals and other key scopes, including global keys, are preserved. Global keys remain unsuitable for federation authentication.

The action does not generate a replacement or edit sender runtime settings. Issue a new exact-scope key through the native receiver-owned credential workflow and configure it out of band on the sender before resuming delivery. No cleartext keys are placed in connection, directory, or delivery records. Use Rotate Federation Service Keys for planned rollover. Issue an expiring native key with exact pmis.federation scope for this principal, install it in the sender's protected runtime settings, and confirm successful delivery first. Select the replacement's metadata and acknowledge installation. The retirement deadline defaults to 24 hours and must be in the future within seven days. The replacement must expire after the deadline. Persistent or longer-lived previous scoped keys receive that deadline; earlier expiries, other scopes, and other principals remain unchanged. Both credentials work during overlap. Repeating the request does not extend previous-key validity. Native expiration blocks retired keys without relying on scheduled cleanup, which may later remove their metadata. Archived connections and inactive principals cannot rotate, but can still revoke keys. Rollover changes no operation, receipt, or sender setting and stores no cleartext secret. Receiver-owned user password resets remain in the backlog.

Resolver isolation

A copied database alone cannot activate traffic without a matching external runtime binding. External credentials and host settings require their own isolation.

DNS uses at most four isolated child processes per worker. Expired or interrupted lookups are killed and reaped before their slots are released. Children receive routing inputs with a minimal environment, without credentials or Odoo settings. Waiting for capacity uses the same delivery deadline. Process startup adds a small cost to each delivery.

Delivery retention

An active daily job compacts settled outgoing profile text after 90 days, in batches of 100. pmis_federation_transport.retention_days accepts 1–3650 days. Pending or uncertain deliveries remain complete. Original digests, operation UUIDs, routing, scope, revisions, and outcomes remain traceable. Incoming replay receipts are permanent; compaction never makes settled operations executable again.

Delivery > Export Delivery History provides the complete stopped-delivery snapshot required before uninstall. Save and acknowledge it with external runtime disabled. After reinstall, restore replay evidence before re-enabling runtime; the export is not an automatic importer. Uninstall never reverses already applied remote effects. See identity review, retention, and leases for exact boundaries.

Localization

English source strings and a Slovenian catalog (i18n/sl.po) are included.

Bug Tracker

Bugs are tracked on PMISuite Repository Issues.

Credits

Maintainers

Current maintainer:

Luxim is an independent R&D and deployment company focused on solving complex problems in the Odoo ecosystem.

Luxim is an active member of OCA (Odoo Community Association).