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:
co-authored by
Claude Fable 5.1
Jakob Wennberg
parent
fcfa1ba974
commit
f31eeaa603
@@ -15,7 +15,7 @@ const ROW = {
|
||||
status: 'active',
|
||||
current_period_end: '2027-01-01T00:00:00.000Z',
|
||||
rate_limited: false,
|
||||
limits: { bank_connections_per_company: 2, skv_connections_per_company: 1, sync_min_interval_s: 3600 },
|
||||
limits: { bank_connections_per_company: 2, skv_connections_per_company: 1, peppol_connections_per_company: 1, sync_min_interval_s: 3600 },
|
||||
}
|
||||
|
||||
describe('connector key primitives', () => {
|
||||
@@ -57,7 +57,7 @@ describe('validateConnectorKey', () => {
|
||||
scopes: ['bank_sync', 'skatteverket'],
|
||||
status: 'active',
|
||||
currentPeriodEnd: '2027-01-01T00:00:00.000Z',
|
||||
limits: { bank_connections_per_company: 2, skv_connections_per_company: 1, sync_min_interval_s: 3600 },
|
||||
limits: { bank_connections_per_company: 2, skv_connections_per_company: 1, peppol_connections_per_company: 1, sync_min_interval_s: 3600 },
|
||||
},
|
||||
})
|
||||
})
|
||||
@@ -65,7 +65,7 @@ describe('validateConnectorKey', () => {
|
||||
it('fills default limits when the RPC returns null limits', async () => {
|
||||
const { key } = generateConnectorKey()
|
||||
const result = await validateConnectorKey(key, supabaseWithRpc({ data: [{ ...ROW, limits: null }] }).supabase)
|
||||
expect(result.ok && result.key.limits).toEqual({ bank_connections_per_company: 1, skv_connections_per_company: 1, sync_min_interval_s: 0 })
|
||||
expect(result.ok && result.key.limits).toEqual({ bank_connections_per_company: 1, skv_connections_per_company: 1, peppol_connections_per_company: 1, sync_min_interval_s: 0 })
|
||||
})
|
||||
|
||||
it('maps no row (unknown/revoked) to 401, but an RPC error to 503', async () => {
|
||||
|
||||
@@ -28,12 +28,15 @@ export function isConnectorKeyFormat(key: string): boolean {
|
||||
export interface ConnectorKeyLimits {
|
||||
bank_connections_per_company: number
|
||||
skv_connections_per_company: number
|
||||
/** Active Peppol receiving registrations per company ("one address"). */
|
||||
peppol_connections_per_company: number
|
||||
sync_min_interval_s: number
|
||||
}
|
||||
|
||||
export const DEFAULT_CONNECTOR_LIMITS: ConnectorKeyLimits = {
|
||||
bank_connections_per_company: 1,
|
||||
skv_connections_per_company: 1,
|
||||
peppol_connections_per_company: 1,
|
||||
sync_min_interval_s: 0,
|
||||
}
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@ import type { SupabaseClient } from '@supabase/supabase-js'
|
||||
* session id, SKV access token) is hashed; the value never rests here.
|
||||
*/
|
||||
|
||||
export type ConnectorService = 'bank' | 'skatteverket'
|
||||
export type ConnectorService = 'bank' | 'skatteverket' | 'peppol'
|
||||
|
||||
export function hashHandle(handle: string): string {
|
||||
return crypto.createHash('sha256').update(handle).digest('hex')
|
||||
|
||||
@@ -0,0 +1,204 @@
|
||||
import type { SupabaseClient } from '@supabase/supabase-js'
|
||||
import { isPeppolTransportError, type PeppolParticipant } from '@/lib/invoices/peppol-transport'
|
||||
import { hashHandle } from './ledger'
|
||||
|
||||
/**
|
||||
* Peppol-specific reads over the connector ledger (hosted side).
|
||||
*
|
||||
* A Peppol "connection" is a receiving registration: one participant id
|
||||
* (scheme:identifier) published under Arcim's access point on behalf of one
|
||||
* company on one instance. The ledger row stores the participant id in
|
||||
* `account_uids` (it is public directory data, not a secret) so inbound
|
||||
* documents can be routed to the key that owns the recipient, and its sha256
|
||||
* in `handle_hash` so the partial unique index makes a participant claimable
|
||||
* by exactly one key at a time.
|
||||
*
|
||||
* Outbound submissions are tracked in `connector_peppol_submissions`: the
|
||||
* hosted Qvalia account is shared, so status polls and evidence reads must
|
||||
* prove the caller submitted the document.
|
||||
*/
|
||||
|
||||
export function peppolHandle(participant: PeppolParticipant): string {
|
||||
return `${participant.scheme}:${participant.identifier.replace(/\s/g, '')}`
|
||||
}
|
||||
|
||||
export function parsePeppolHandle(handle: string): PeppolParticipant | null {
|
||||
const colon = handle.indexOf(':')
|
||||
if (colon === -1) return null
|
||||
const scheme = handle.slice(0, colon)
|
||||
const identifier = handle.slice(colon + 1)
|
||||
// ISO 6523 ICD scheme: four digits (not a BAS account, hence no shared schema).
|
||||
if (scheme.length !== 4 || !/^\d+$/.test(scheme) || !identifier) return null
|
||||
return { scheme, identifier }
|
||||
}
|
||||
|
||||
/**
|
||||
* Every participant this key currently holds an active registration for,
|
||||
* optionally narrowed to one company on the instance. Inbound routing is
|
||||
* key-wide (the instance's inbound sync lists for all its companies and
|
||||
* routes by its own registrations); everything else is company-bound.
|
||||
*/
|
||||
export async function listActivePeppolParticipants(
|
||||
supabase: SupabaseClient,
|
||||
keyId: string,
|
||||
companyRef?: string,
|
||||
): Promise<PeppolParticipant[]> {
|
||||
let query = supabase
|
||||
.from('connector_connections')
|
||||
.select('account_uids')
|
||||
.eq('connector_key_id', keyId)
|
||||
.eq('service', 'peppol')
|
||||
.eq('status', 'active')
|
||||
if (companyRef) query = query.eq('company_ref', companyRef)
|
||||
const { data, error } = await query
|
||||
if (error) throw new Error(`ledger read failed: ${error.message}`)
|
||||
const participants: PeppolParticipant[] = []
|
||||
for (const row of (data ?? []) as Array<{ account_uids: string[] | null }>) {
|
||||
for (const uid of row.account_uids ?? []) {
|
||||
const parsed = parsePeppolHandle(uid)
|
||||
if (parsed) participants.push(parsed)
|
||||
}
|
||||
}
|
||||
return participants
|
||||
}
|
||||
|
||||
/** Whether ANY key holds an active registration for this participant. */
|
||||
export async function isPeppolParticipantHeld(supabase: SupabaseClient, handle: string): Promise<boolean> {
|
||||
const { data, error } = await supabase
|
||||
.from('connector_connections')
|
||||
.select('id')
|
||||
.eq('service', 'peppol')
|
||||
.eq('status', 'active')
|
||||
.eq('handle_hash', hashHandle(handle))
|
||||
.limit(1)
|
||||
.maybeSingle()
|
||||
if (error) throw new Error(`ledger read failed: ${error.message}`)
|
||||
return !!data
|
||||
}
|
||||
|
||||
/** Whether a HOSTED company holds a live registration for this participant at the provider. */
|
||||
export async function isHostedPeppolParticipantLive(
|
||||
supabase: SupabaseClient,
|
||||
params: { provider: string; participant: PeppolParticipant },
|
||||
): Promise<boolean> {
|
||||
const { data, error } = await supabase
|
||||
.from('peppol_registrations')
|
||||
.select('id')
|
||||
.eq('provider', params.provider)
|
||||
.eq('participant_scheme', params.participant.scheme)
|
||||
.eq('participant_identifier', params.participant.identifier.replace(/\s/g, ''))
|
||||
.in('status', ['pending', 'registered'])
|
||||
.limit(1)
|
||||
.maybeSingle()
|
||||
if (error) throw new Error(`peppol registration read failed: ${error.message}`)
|
||||
return !!data
|
||||
}
|
||||
|
||||
/** Same reservation window as countHeldConnections in ./ledger.ts. */
|
||||
const PENDING_CAP_WINDOW_MS = 15 * 60 * 1000
|
||||
|
||||
/**
|
||||
* Connector-held registrations across every key, for the provider-account
|
||||
* cap: active rows plus fresh pending reservations, so two concurrent
|
||||
* registrations cannot both pass the cap check and both land.
|
||||
*/
|
||||
export async function countConnectorPeppolRegistrations(supabase: SupabaseClient, now: Date = new Date()): Promise<number> {
|
||||
const freshPendingSince = new Date(now.getTime() - PENDING_CAP_WINDOW_MS).toISOString()
|
||||
const [active, pending] = await Promise.all([
|
||||
supabase
|
||||
.from('connector_connections')
|
||||
.select('id', { count: 'exact', head: true })
|
||||
.eq('service', 'peppol')
|
||||
.eq('status', 'active'),
|
||||
supabase
|
||||
.from('connector_connections')
|
||||
.select('id', { count: 'exact', head: true })
|
||||
.eq('service', 'peppol')
|
||||
.eq('status', 'pending')
|
||||
.gte('created_at', freshPendingSince),
|
||||
])
|
||||
if (active.error) throw new Error(`ledger count failed: ${active.error.message}`)
|
||||
if (pending.error) throw new Error(`ledger count failed: ${pending.error.message}`)
|
||||
return (active.count ?? 0) + (pending.count ?? 0)
|
||||
}
|
||||
|
||||
/**
|
||||
* Participant identifiers a key may publish under Arcim's access point: the
|
||||
* allowlist Arcim recorded at issuance plus the licensee's own org number.
|
||||
* Whitespace is stripped the same way peppolHandle() does.
|
||||
*/
|
||||
export async function getPeppolAllowedIdentifiers(supabase: SupabaseClient, keyId: string): Promise<Set<string>> {
|
||||
const { data, error } = await supabase
|
||||
.from('connector_keys')
|
||||
.select('org_number, peppol_participants')
|
||||
.eq('id', keyId)
|
||||
.maybeSingle()
|
||||
if (error) throw new Error(`connector key read failed: ${error.message}`)
|
||||
const row = data as { org_number: string | null; peppol_participants: string[] | null } | null
|
||||
const allowed = new Set<string>()
|
||||
for (const value of [row?.org_number ?? '', ...(row?.peppol_participants ?? [])]) {
|
||||
const cleaned = value.replace(/\s/g, '')
|
||||
if (cleaned) allowed.add(cleaned)
|
||||
}
|
||||
return allowed
|
||||
}
|
||||
|
||||
export async function recordPeppolSubmission(
|
||||
supabase: SupabaseClient,
|
||||
params: { keyId: string; companyRef: string; provider: string; providerSubmissionId: string; idempotencyKey: string },
|
||||
): Promise<void> {
|
||||
const { error } = await supabase
|
||||
.from('connector_peppol_submissions')
|
||||
.upsert(
|
||||
{
|
||||
connector_key_id: params.keyId,
|
||||
company_ref: params.companyRef,
|
||||
provider: params.provider,
|
||||
provider_submission_id: params.providerSubmissionId,
|
||||
idempotency_key: params.idempotencyKey,
|
||||
},
|
||||
{ onConflict: 'provider,provider_submission_id', ignoreDuplicates: true },
|
||||
)
|
||||
if (error) throw new Error(`submission record failed: ${error.message}`)
|
||||
}
|
||||
|
||||
/** The submission row for (key, company, provider submission id): both the key and the company must match. */
|
||||
export async function findOwnedPeppolSubmission(
|
||||
supabase: SupabaseClient,
|
||||
params: { keyId: string; companyRef: string; provider: string; providerSubmissionId: string },
|
||||
): Promise<{ id: string; company_ref: string } | null> {
|
||||
const { data, error } = await supabase
|
||||
.from('connector_peppol_submissions')
|
||||
.select('id, company_ref')
|
||||
.eq('connector_key_id', params.keyId)
|
||||
.eq('company_ref', params.companyRef)
|
||||
.eq('provider', params.provider)
|
||||
.eq('provider_submission_id', params.providerSubmissionId)
|
||||
.maybeSingle()
|
||||
if (error) throw new Error(`submission read failed: ${error.message}`)
|
||||
return (data as { id: string; company_ref: string } | null) ?? null
|
||||
}
|
||||
|
||||
export interface PeppolUpstreamFailure {
|
||||
/** Short, adapter-classified text (never a raw provider body). */
|
||||
text: string
|
||||
retryable: boolean
|
||||
/** Adapter detail, capped; the instance surfaces it as PeppolTransportError.detail. */
|
||||
hint: string | null
|
||||
}
|
||||
|
||||
/**
|
||||
* Summarize a transport failure for the connector response. The Qvalia
|
||||
* adapter already classifies failures (network, auth, protocol, rejected,
|
||||
* duplicate) into its own message text; only that classified text and its
|
||||
* capped detail cross to the instance. Anything that is not a transport
|
||||
* error is a hosted bug and is not summarized here (the caller rethrows).
|
||||
*/
|
||||
export function describePeppolUpstreamFailure(err: unknown): PeppolUpstreamFailure | null {
|
||||
if (!isPeppolTransportError(err)) return null
|
||||
return {
|
||||
text: err.message.slice(0, 200),
|
||||
retryable: err.retryable,
|
||||
hint: err.detail ? err.detail.slice(0, 300) : null,
|
||||
}
|
||||
}
|
||||
@@ -35,6 +35,14 @@ export function budgetFor(service: UpstreamService): Budget {
|
||||
hourMax: intFromEnv('CONNECT_BANK_RPH_BUDGET', 3000), // ~30% of EB's 10 000/h
|
||||
}
|
||||
}
|
||||
if (service === 'peppol') {
|
||||
// Peppol is low-volume (invoices, not polling), so a modest ceiling well
|
||||
// under Qvalia's limits is plenty; tune via env if a busy byrå needs more.
|
||||
return {
|
||||
minuteMax: intFromEnv('CONNECT_PEPPOL_RPM_BUDGET', 60),
|
||||
hourMax: intFromEnv('CONNECT_PEPPOL_RPH_BUDGET', 1000),
|
||||
}
|
||||
}
|
||||
return {
|
||||
minuteMax: intFromEnv('CONNECT_SKV_RPM_BUDGET', 120),
|
||||
hourMax: intFromEnv('CONNECT_SKV_RPH_BUDGET', 4000),
|
||||
|
||||
@@ -1,12 +1,14 @@
|
||||
import { describe, it, expect, afterEach, vi } from 'vitest'
|
||||
import {
|
||||
bankConnectorMode,
|
||||
peppolConnectorMode,
|
||||
skatteverketConnectorMode,
|
||||
hasOwnEnableBankingCredentials,
|
||||
hasOwnPeppolCredentials,
|
||||
hasOwnSkatteverketCredentials,
|
||||
} from '../upstreams'
|
||||
|
||||
const ENV = ['GNUBOK_CONNECTOR_KEY', 'GNUBOK_CONNECT_URL', 'ENABLE_BANKING_PRIVATE_KEY', 'ENABLE_BANKING_APP_ID', 'ENABLE_BANKING_PRIVATE_KEY_PRODUCTION', 'ENABLE_BANKING_APP_ID_PRODUCTION', 'SKATTEVERKET_OAUTH2_CLIENT_ID', 'SKATTEVERKET_APIGW_CLIENT_ID'] as const
|
||||
const ENV = ['GNUBOK_CONNECTOR_KEY', 'GNUBOK_CONNECT_URL', 'ENABLE_BANKING_PRIVATE_KEY', 'ENABLE_BANKING_APP_ID', 'ENABLE_BANKING_PRIVATE_KEY_PRODUCTION', 'ENABLE_BANKING_APP_ID_PRODUCTION', 'SKATTEVERKET_OAUTH2_CLIENT_ID', 'SKATTEVERKET_APIGW_CLIENT_ID', 'QVALIA_API_KEY', 'QVALIA_PARTNER_REG_NO'] as const
|
||||
|
||||
afterEach(() => vi.unstubAllEnvs())
|
||||
function clear() {
|
||||
@@ -56,3 +58,15 @@ describe('connector-mode detection', () => {
|
||||
expect(skatteverketConnectorMode()).not.toBeNull()
|
||||
})
|
||||
})
|
||||
|
||||
describe('peppol connector mode', () => {
|
||||
it('is off without a key and off with own Qvalia keys, on otherwise', () => {
|
||||
clear()
|
||||
expect(peppolConnectorMode()).toBeNull()
|
||||
vi.stubEnv('GNUBOK_CONNECTOR_KEY', 'gnubok_ck_x')
|
||||
expect(peppolConnectorMode()).toEqual({ baseUrl: 'https://app.gnubok.se/api/connect/peppol', key: 'gnubok_ck_x' })
|
||||
vi.stubEnv('QVALIA_PARTNER_REG_NO', '5560000000')
|
||||
expect(hasOwnPeppolCredentials()).toBe(true)
|
||||
expect(peppolConnectorMode()).toBeNull()
|
||||
})
|
||||
})
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
import { getConnectorConfig } from './config'
|
||||
import {
|
||||
hasOwnEnableBankingCredentials,
|
||||
hasOwnPeppolCredentials,
|
||||
hasOwnSkatteverketCredentials,
|
||||
} from '@/lib/entitlements/own-credentials'
|
||||
|
||||
@@ -24,7 +25,7 @@ export const CONNECTOR_COMPANY_HEADER = 'X-Connector-Company'
|
||||
export const CONNECTOR_UPSTREAM_AUTH_HEADER = 'X-Connector-Upstream-Authorization'
|
||||
export const CONNECTOR_UPSTREAM_CONTENT_TYPE_HEADER = 'X-Connector-Upstream-Content-Type'
|
||||
|
||||
export { hasOwnEnableBankingCredentials, hasOwnSkatteverketCredentials }
|
||||
export { hasOwnEnableBankingCredentials, hasOwnPeppolCredentials, hasOwnSkatteverketCredentials }
|
||||
|
||||
export interface ConnectorUpstream {
|
||||
/** Base URL to send upstream requests to (the hosted proxy). */
|
||||
@@ -46,3 +47,15 @@ export function skatteverketConnectorMode(): ConnectorUpstream | null {
|
||||
if (!cfg) return null
|
||||
return { baseUrl: `${cfg.baseUrl}/api/connect/skv`, key: cfg.key }
|
||||
}
|
||||
|
||||
/**
|
||||
* Peppol through Arcim's contracted access point. Same rule as the other
|
||||
* upstreams: an instance with its own Qvalia partner keys runs Peppol itself
|
||||
* and is never routed here.
|
||||
*/
|
||||
export function peppolConnectorMode(): ConnectorUpstream | null {
|
||||
if (hasOwnPeppolCredentials()) return null
|
||||
const cfg = getConnectorConfig()
|
||||
if (!cfg) return null
|
||||
return { baseUrl: `${cfg.baseUrl}/api/connect/peppol`, key: cfg.key }
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user