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>

scripts/issue-connector-key.ts

@@ -9,7 +9,13 @@
  * Usage:
  *   npx tsx scripts/issue-connector-key.ts --org 5561234567 --name "Byrå AB" \
  *       --instance https://bokforing.byra.se [--months 12] \
- *       [--scopes bank_sync,skatteverket,org_lookup,migration] [--notes "..."] --confirm
+ *       [--scopes bank_sync,skatteverket,org_lookup,migration,peppol] \
+ *       [--peppol-participants 5561234567,7350000000000] [--notes "..."] --confirm
+ *
+ * --peppol-participants lists the participant identifiers (org numbers, GLNs)
+ * the licensee may register and send as through Arcim's Peppol access point;
+ * the --org number is always allowed. Only issue the peppol scope where the
+ * Qvalia brokering terms permit it.
  *
  * Reads .env.local (which points at PRODUCTION in this repo: the script
  * refuses to write without --confirm and prints the target host first).
@@ -41,6 +47,11 @@ async function main(): Promise<void> {
   const scopes = (arg('scopes') ?? 'bank_sync,skatteverket').split(',').map((s) => s.trim()).filter(Boolean)
   const bankPerCompany = Number(arg('bank-connections-per-company') ?? '1')
   const skvPerCompany = Number(arg('skv-connections-per-company') ?? '1')
+  const peppolPerCompany = Number(arg('peppol-connections-per-company') ?? '1')
+  const peppolParticipants = (arg('peppol-participants') ?? '')
+    .split(',')
+    .map((v) => v.replace(/\s/g, ''))
+    .filter(Boolean)
   const syncMinInterval = Number(arg('sync-min-interval') ?? '0')
   const notes = arg('notes') ?? null
 
@@ -56,9 +67,15 @@ async function main(): Promise<void> {
   if (!Number.isInteger(months) || months <= 0 || months > 120) problems.push('--months must be an integer 1..120')
   const unknown = scopes.filter((s) => !(CONNECTOR_CAPABILITIES as readonly string[]).includes(s))
   if (unknown.length) problems.push(`unknown scopes: ${unknown.join(', ')} (allowed: ${CONNECTOR_CAPABILITIES.join(', ')})`)
-  for (const [name, v] of [['bank-connections-per-company', bankPerCompany], ['skv-connections-per-company', skvPerCompany]] as const) {
+  for (const [name, v] of [
+    ['bank-connections-per-company', bankPerCompany],
+    ['skv-connections-per-company', skvPerCompany],
+    ['peppol-connections-per-company', peppolPerCompany],
+  ] as const) {
     if (!Number.isFinite(v) || v < 0 || v > 100) problems.push(`--${name} must be 0..100`)
   }
+  const badParticipants = peppolParticipants.filter((v) => !/^[0-9]{6,20}$/.test(v))
+  if (badParticipants.length) problems.push(`--peppol-participants must be digit-only identifiers: ${badParticipants.join(', ')}`)
   if (!Number.isFinite(syncMinInterval) || syncMinInterval < 0) problems.push('--sync-min-interval must be >= 0 seconds')
   if (problems.length) {
     console.error(problems.map((p) => `  x ${p}`).join('\n'))
@@ -78,7 +95,8 @@ async function main(): Promise<void> {
   console.log(`Licensee:  ${name} (${org})`)
   console.log(`Instance:  ${new URL(instance).origin}`)
   console.log(`Scopes:    ${scopes.join(', ')}`)
-  console.log(`Limits:    ${bankPerCompany} bank + ${skvPerCompany} SKV connection(s)/company, min sync interval ${syncMinInterval}s`)
+  console.log(`Limits:    ${bankPerCompany} bank + ${skvPerCompany} SKV + ${peppolPerCompany} Peppol connection(s)/company, min sync interval ${syncMinInterval}s`)
+  console.log(`Peppol:    ${peppolParticipants.length ? peppolParticipants.join(', ') : '(own org number only)'}`)
   console.log(`Period:    until ${periodEnd.toISOString().slice(0, 10)} (${months} months)`)
   if (!flag('confirm')) {
     console.log('\nDry run. Re-run with --confirm to issue the key.')
@@ -101,8 +119,10 @@ async function main(): Promise<void> {
       limits: {
         bank_connections_per_company: Math.floor(bankPerCompany),
         skv_connections_per_company: Math.floor(skvPerCompany),
+        peppol_connections_per_company: Math.floor(peppolPerCompany),
         sync_min_interval_s: Math.floor(syncMinInterval),
       },
+      peppol_participants: peppolParticipants,
       notes,
     })
     .select('id')