feat(connect): Peppol through the connector (hosted proxy, instance transport, ownership ledger) (#2177)
* feat(connect): peppol connector foundation: capability, ledger/budget service, quota Adds the storage + package shape for brokering Peppol through the connector with the same one-address + rate-budget model as bank/skatteverket: a peppol capability (connector-gated, free on hosted), peppol as a ledger + upstream service, a conservative rate budget, and a migration extending the ledger service CHECK and the per-key limits (peppol_connections_per_company). Proxy route + instance-side Qvalia reroute follow. Switch-on gated on the Qvalia brokering-terms check. (cherry picked from commit 3cc0da6a3, migration renumbered 20260902190000) Signed-off-by: Jakob Wennberg <jakob.wennberg@arcim.io> Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MMUUom4fUk6zi4xYZSSfat * feat(connect): Peppol through the connector: hosted proxy, instance transport, ownership ledger Completes the Peppol upstream for self-hosted instances on the connector (WS3): an instance with a connector key carrying the peppol scope and no Qvalia keys of its own sends and receives e-invoices through Arcim's contracted access point, the same way bank and Skatteverket already route. Hosted: app/api/connect/peppol/[...path] speaks the PeppolTransport operations (lookup, submit, status, evidence, recipient PUT/DELETE, inbound list/xml) rather than proxying Qvalia paths, because the Qvalia account is shared by every hosted company and every instance: reads must be scoped to what the caller owns, and the inbound read endpoint is destructive for the whole account. Ownership: a receiving registration is a ledger row (service peppol, participant id in account_uids, sha256 in handle_hash so one key holds a participant at a time); outbound submissions land in the new connector_peppol_submissions table and gate status/evidence; inbound documents are served from the hosted archive filtered by the participants the key holds. Per-company quota (peppol_connections_per_company), the shared PEPPOL_RECEIVING_MAX_REGISTRATIONS cap, and the global peppol rate budget apply. Provider failures cross as CONNECTOR_UPSTREAM_ERROR with the adapter's retryable flag (422 or 502). Instance: lib/invoices/transports/connector.ts implements PeppolTransport over that API and registers itself in connector mode (key present, no QVALIA_* keys); getPeppolTransportAvailability() defaults to it when no provider is selected, so an instance needs no PEPPOL_TRANSPORT_PROVIDER. Webhooks are not brokered; the existing outbound status poll covers it. Hosted is byte-identical: it has its own keys, so connector mode is never on. Docs: SELF-HOSTING.md, SOVEREIGN.md, .env.example. Switch-on for third-party instances stays gated on the Qvalia brokering-terms check; without the scope every operation answers 403. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MMUUom4fUk6zi4xYZSSfat Signed-off-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com> * fix(connect): authorize Peppol participants per key, harden the proxy after review Review follow-ups on #2177. Authorization: a key may only register (and send as) participant identifiers Arcim recorded on the key at issuance (connector_keys.peppol_participants, migration 20260902191000) or the licensee's own org number, and a document may only be submitted as a sender the key has registered; X-Connector-Company stays an opaque per-company ref. Cap: the shared access-point cap now counts fresh pending reservations and is re-checked after this request's own reservation, so concurrent registrations cannot both pass. Inbound: both halves of the participant id are filtered in the archive query (over-fetched, then exact-pair checked), so foreign rows sharing an identifier cannot consume the limit. Delete: deregistration is a required transport capability, checked before the ledger row is revoked, and registration refuses an access point that cannot deregister. Instance transport: the hosted URL must be https (loopback http only, same rule as getConnectorConfig), and the response body is read inside the timeout window with body-read failures mapped to retryable transport errors. issue-connector-key.ts gains --peppol-participants and --peppol-connections-per-company. Declined: NOT VALID on the ledger CHECK (the table is empty until keys are issued; the validated scan is instant). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MMUUom4fUk6zi4xYZSSfat Signed-off-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com> * fix(connect): bind Peppol ownership to the instance company, query exact participant pairs Second review round on #2177. Ownership is now (key, company_ref), not key alone: a sender must be registered under the same company header, status and evidence reads look the submission up under the header company, DELETE and re-registration refuse a participant the key holds for another company, so one company on a multi-company instance cannot act on another company's registration through the shared key. The instance transport resolves the owning company from its own peppol_deliveries / peppol_registrations rows before status, evidence and deregistration calls (deps.companyFor, deps.companyForParticipant, wired in transports/index.ts). Inbound listing stays key-wide (the instance routes documents to its own companies by its own registrations). The archive query now runs one exact-pair query per scheme (scheme fixed, that scheme's identifiers), so neither foreign nor cross-pair rows can consume the limit. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MMUUom4fUk6zi4xYZSSfat Signed-off-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com> --------- Signed-off-by: Jakob Wennberg <jakob.wennberg@arcim.io> Signed-off-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com> Co-authored-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com> Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Jakob Wennberg
co-authored by
Claude Fable 5.1
Jakob Wennberg
Claude Fable 5.1
Jakob Wennberg
parent
fcfa1ba974
commit
f31eeaa603
@@ -0,0 +1,56 @@
|
||||
-- Peppol as a connector upstream (WS3, follow-up to 20260820124000; originally drafted 2026-08-23, renumbered to keep versions monotonic).
|
||||
--
|
||||
-- Lets a self-hosted instance send/receive Peppol through Arcim's contracted
|
||||
-- Qvalia Access Point with the SAME shape as bank/skatteverket: a per-company
|
||||
-- connection quota ("one address" = one active Peppol participant registration)
|
||||
-- and a global upstream rate budget. The hosted proxy route and the
|
||||
-- instance-side transport reroute are code (lib/connect + lib/invoices); this
|
||||
-- migration only extends the storage shape.
|
||||
--
|
||||
-- pg-test: covered-by tests/pg/connector-proxy-ledger.pg.test.ts
|
||||
-- NOTE: switch-on for real third-party instances is gated on the Qvalia
|
||||
-- brokering-terms check (brokering Qvalia's AP registers those companies under
|
||||
-- Arcim's AP). The schema is inert until a connector key carries a peppol scope.
|
||||
|
||||
-- 1. Allow 'peppol' in the ownership ledger. The inline CHECK from
|
||||
-- 20260820124000 is auto-named connector_connections_service_check.
|
||||
ALTER TABLE public.connector_connections
|
||||
DROP CONSTRAINT IF EXISTS connector_connections_service_check;
|
||||
ALTER TABLE public.connector_connections
|
||||
ADD CONSTRAINT connector_connections_service_check
|
||||
CHECK (service IN ('bank', 'skatteverket', 'peppol'));
|
||||
|
||||
-- 2. Add the peppol per-company connection quota to the sellable package shape.
|
||||
-- "One address" = one active Peppol participant registration per company.
|
||||
ALTER TABLE public.connector_keys
|
||||
ALTER COLUMN limits SET DEFAULT
|
||||
'{"bank_connections_per_company": 1, "skv_connections_per_company": 1, "peppol_connections_per_company": 1, "sync_min_interval_s": 0}'::jsonb;
|
||||
|
||||
-- Backfill existing keys so the proxy can read the quota without a code fallback.
|
||||
UPDATE public.connector_keys
|
||||
SET limits = limits || '{"peppol_connections_per_company": 1}'::jsonb
|
||||
WHERE NOT (limits ? 'peppol_connections_per_company');
|
||||
|
||||
-- 3. Ownership of outbound submissions made through the connector. The hosted
|
||||
-- Qvalia account is shared by every hosted company and every instance, so
|
||||
-- status polls and evidence retrieval must prove the caller submitted the
|
||||
-- document. Secret-free: the provider submission id is a provider-side
|
||||
-- handle, not a credential. Service-role only, like the ledger.
|
||||
CREATE TABLE public.connector_peppol_submissions (
|
||||
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
connector_key_id uuid NOT NULL REFERENCES public.connector_keys(id) ON DELETE CASCADE,
|
||||
company_ref text NOT NULL,
|
||||
provider text NOT NULL DEFAULT 'qvalia',
|
||||
provider_submission_id text NOT NULL CHECK (length(btrim(provider_submission_id)) BETWEEN 1 AND 128),
|
||||
idempotency_key text,
|
||||
created_at timestamptz NOT NULL DEFAULT now(),
|
||||
CONSTRAINT connector_peppol_submissions_provider_submission_unique UNIQUE (provider, provider_submission_id)
|
||||
);
|
||||
CREATE INDEX idx_connector_peppol_submissions_key
|
||||
ON public.connector_peppol_submissions (connector_key_id, created_at DESC);
|
||||
ALTER TABLE public.connector_peppol_submissions ENABLE ROW LEVEL SECURITY;
|
||||
-- No policies: service role only (same posture as connector_connections).
|
||||
COMMENT ON TABLE public.connector_peppol_submissions IS
|
||||
'Which connector key submitted which Peppol document through the shared hosted access point; gates status/evidence reads. No secrets.';
|
||||
|
||||
NOTIFY pgrst, 'reload schema';
|
||||
@@ -0,0 +1,17 @@
|
||||
-- Peppol participant allowlist per connector key (review follow-up on #2177).
|
||||
--
|
||||
-- A hosted company registers the participant its own settings declare, after
|
||||
-- BankID/TIC-verified onboarding. An instance is only a licensee: nothing on
|
||||
-- the hosted side knows which organisations it hosts, so without this column a
|
||||
-- key could publish (and send under) ANY organisation number through Arcim's
|
||||
-- access point. Arcim records, at issuance, which participant identifiers the
|
||||
-- licensee may use; the key's own org_number is always allowed.
|
||||
--
|
||||
-- pg-test: covered-by tests/pg/connector-proxy-ledger.pg.test.ts
|
||||
ALTER TABLE public.connector_keys
|
||||
ADD COLUMN IF NOT EXISTS peppol_participants text[] NOT NULL DEFAULT '{}';
|
||||
|
||||
COMMENT ON COLUMN public.connector_keys.peppol_participants IS
|
||||
'Participant identifiers (org numbers, GLNs) this key may register and send as through the hosted Peppol access point; the key org_number is implicitly allowed.';
|
||||
|
||||
NOTIFY pgrst, 'reload schema';
|
||||
Reference in New Issue
Block a user