scalio-connect

Signed calls between the Scalio apps and Compass. One format ("v2", header Scalio-Signature) for every direction:

• Compass -> app: control key K3 on /api/provision/* (replaced the old X-Provision-Control-Signature, which is refused since 0.13.0)
• app -> Compass: instance key on the support intake /api/support/v1/* (scalio_connect.support)

Contract: scalio-docs interfaces/signed-request-v2.md. Decision: scalio-docs ADR 0020.

What is signed

Scalio-Signature: v=2,kid=k3,ts=1793131200,nonce=vector-nonce-0000000001,sig=<base64 Ed25519>

scalio-sig-v2
<kid>
<METHOD>
<audience = receiver origin, e.g. https://acme.eu.scalionexus.com>
<path and query as sent, e.g. /api/provision/admin>
<ts>
<nonce>
<sha256 of the raw body, hex>

Lines joined by \n, no line break at the end. Time window +-300 s, each (kid, nonce) once. Because receiver and path are signed, a captured request does not work on another instance or another endpoint (security review H9).

Usage

from scalio_connect import sign, verify, SignatureError
from scalio_connect.nonces import use_nonce

# sender
headers = sign(private_key, "k3", "POST", "https://acme.eu.scalionexus.com/api/provision/admin", body)

# receiver (raw body bytes, path with query as received)
try:
    v = verify(request.headers["Scalio-Signature"], request.method, path_with_query, body,
               audiences=["https://acme.eu.scalionexus.com"], keys_for=lambda kid: k3_keys if kid == "k3" else [])
except SignatureError:
    raise HTTPException(401)
if not await use_nonce(db, v.kid, v.nonce):
    raise HTTPException(401)

audiences are the receiver's own public origins from its configuration. Do not take them from the Host header.

K3 (Compass -> app)

from scalio_connect.k3 import K3Error, audiences_from_env, check_request

try:
    await check_request(db, request.headers, request.method, path_with_query, body,
                        keys=k3_public_keys, audiences=audiences_from_env())
except K3Error as e:
    raise HTTPException(401, str(e))

Accepts only format v2 (since 0.13.0, security review M13). The old X-Provision-* headers are ignored and a call with only those is refused. The call must be signed for one of the instance's public URLs (SCALIO_PUBLIC_URLS, APP_PUBLIC_URL, FRONTEND_URL, PUBLIC_URL; http and https of the same host both match); without a public URL the provisioning API stays closed.

Development

pip install -e ".[dev]"
ruff check . && pytest -q

tests/vector.json is the shared test vector (throwaway seed). Compass and every app test against the same file. Release: bump pyproject.toml, a scalio-docs PR with python3 tools/changelog.py --repo scalio-connect release <version> (changelog in scalio-docs changelog/scalio-connect/, ADR 0066), merge, then "Publish" (cockpit or Actions) with the version, no v.

Support connection (app -> Compass)

pip install "scalio-connect[support]". Decision: scalio-docs ADR 0022, contract interfaces/support-intake.md.

from scalio_connect.support import SupportClient, cipher_from_secret, build_diagnostics
from scalio_connect.support import connection, outbox

cipher = cipher_from_secret(os.environ["JWT_SECRET"])          # any app secret of 16+ characters
conn = await connection.load(db, cipher) or await connection.create(db, cipher, "nexus", portal_url)
client = SupportClient(conn)
await client.pair(app="nexus", version=VERSION, mode="saas", code=one_time_code)   # SaaS / dev / test
await connection.set_status(db, "active")

item = await outbox.enqueue(db, "ticket", {"subject": ..., "description": ..., "reporter": {...},
                                           "diagnostics": build_diagnostics(app="nexus", ...)},
                            reporter_email=user_email)
await outbox.flush(db, client if conn.usable else None)       # again when the drawer opens

Ready-made routers for a FastAPI app (pip install "scalio-connect[support-web]"):

from scalio_connect.support.service import SupportService
from scalio_connect.support.web import provision_support_router, support_router
from scalio_license.web import require_provision

support = SupportService("citadel", lambda: db, mode=mode, app_url=app_url, build_info=build_info,
                         license_info=lambda: {"edition": ..., "valid": ...}, stage=stage,
                         portal=lambda: licensing.runtime.state.get("portal"))
app.include_router(support_router(support, current_user=get_current_user, require_admin=require_admin,
                                  enabled=lambda: features()["support"], audit=audit), prefix="/api")
app.include_router(provision_support_router(support, require_provision(lambda: db), audit), prefix="/api")
# startup: await support.ensure_indexes(); asyncio.create_task(support.loop())

AppSupport (from 0.11.0) builds the service with the parts every app had the same: mode, public address, license block, portal claim and maintenance flag.

from scalio_connect.support.app import AppSupport

app_support = AppSupport("citadel", lambda: db, saas_mode=saas_mode, stage=stage,
                         license_state=lambda: licensing.runtime.state, build_info=build_info)
support = app_support.service   # app_support.mode(), .app_url(), .maintenance_active()

Portal per stage (support.portals): an instance on stage dev connects only to portaldev.scaliocloud.com, test only to portaltest.scaliocloud.com, everything else (production, demo, SaaS, self-hosted customers) to portal.scaliocloud.com by default and never to the dev or test portal. Without an address the admin form uses the stage's portal (default_portal in GET /support/connection). stage is optional; without it the stage follows mode(). POST /provision/support skips the check: the call comes from the Compass that created the instance.

Self-hosted (ADR 0022, T11/T12): in production portal() (the license's issuing portal, scalio-license portal) is the default. A self-hosted instance without a connection takes no tickets; GET /support/status tells the drawer to link to <portal>/support instead (link_only). The admin can hide the button (PUT /support/connection/button); the app reads await support.button_hidden() for its features().

Scalio Ideen (ADR 0050, from 0.8.0): the same connection carries feature requests, votes and comments to Compass (/api/ideas/v1/*, contract in scalio-docs interfaces/ideas-intake.md):

from scalio_connect.support.ideas_web import ideas_router
app.include_router(ideas_router(support, current_user=get_current_user, enabled=lambda: features()["support"],
                                audit=audit), prefix="/api")

GET /ideas/status tells the drawer whether it can list ideas (connected) or only link to the public page (link_only, page = <portal>/ideen?product=<app>). New ideas belong to the app itself or to compass.

The instance key never leaves the instance. If the app secret changes, the key cannot be decrypted any more and the admin connects again.

SaaS updates (ADR 0074, from 0.14.0): the same connection reads the update offer Compass made for this instance and passes on the customer's choice (/api/updates/v1/{state,now,postpone,mode,window}, contract in scalio-docs interfaces/saas-updates.md). Compass runs the update itself; the app only shows it:

from scalio_connect.support.updates_web import saas_updates_router
app.include_router(saas_updates_router(support, current_user=get_current_user, require_admin=require_admin,
                                       saas=lambda: SAAS_MODE, is_admin=lambda u: u["role"] == "admin",
                                       audit=audit), prefix="/api")

GET /saas-updates/banner (everyone: version, planned time, deadline), GET /saas-updates (admin, cached 15 minutes, ?refresh=1), POST /saas-updates/{now,postpone,mode,window} (admin). Self-hosted answers {"saas": false}. The UI blocks are UpdateBanner and SaasUpdatesPanel in @scalio-cloud/ui 0.30.0.

Pairing with Beacon (app <-> Beacon, from 0.9.0)

scalio_connect.peers pairs an app (Citadel, Rosetta, Foundry, Nexus) with a Scalio Beacon instance (decisions itsm/P3-1, P3-2 in scalio-docs concepts/beacon-suite.md; contract interfaces/peer-findings.md).

• The Beacon admin creates a one-time code bpc_… (24 hours, Beacon stores only its sha256). The app admin enters the Beacon address and the code. The app makes a key for this pairing and signs the pair call with it; Beacon answers with its own new public key. From then on both sides call each other signed (format v2, kid = the key id of the pairing): the app sends findings, Beacon calls actions.
• Keys are stored encrypted in scalio_peers (Fernet from a random secret in scalio_peer_secret, like the support key; never part of an export). Removing a pairing deletes the key.
• findings.report(...) sends the state of one source for one tenant after each check, only when it changed or once a day; findings.event(...) sends single run events. Texts are scrubbed. outbox.flush sends with retries.

from scalio_connect.peers import findings
from scalio_connect.peers.web import PeerService, admin_router, peer_router

peers = PeerService(get_db=lambda: db, app="citadel", own_url=lambda: PUBLIC_URL, version=VERSION)
app.include_router(admin_router(peers, require_admin=require_admin, audit=audit), prefix="/api")  # /api/peers
app.include_router(peer_router(peers), prefix="/api")                                             # /api/peers/v1/ping

# after a check
await findings.report(db, source="citadel.conformity", tenant_id=tid, tenant_name=name, items=[...])
# periodic job
await peers.flush()

Beacon (host) uses codes.create, pairing.accept and auth.fastapi_dependency for its own /api/peers/v1/* routes and checks every snapshot again with findings.snapshot(...).