flip_api.trusts_services.services.register_trust

Trust registration service — the single write path into the trust table.

Two callers:

  • POST /admin/trusts (trusts_services.admin_create_trust) for one-off admin-driven registrations from the UI.

  • flip_api.scripts.register_trust CLI, invoked once per trust by the deploy Makefile’s register-trust target (the trust’s name comes from its kit file; the hub keeps no trust list of its own).

Both produce the same on-disk state: one Trust row with api_key_hash set, one FLKitSlot assigned, plaintext api/internal-service keys returned once for distribution to the trust host (then unrecoverable).

Exceptions

TrustRegistrationError

Base for trust registration failures.

EmptyTrustNameError

Caller supplied a blank trust name.

EmptyTrustCodeError

Caller supplied a blank (or missing) trust code — code is required.

DuplicateTrustError

A trust with the given name already exists.

NoFreeKitSlotError

The FL kit slot pool is exhausted.

Classes

RegisteredTrust

Result of a successful registration — the only place plaintext keys exist.

Functions

register_trust(→ RegisteredTrust)

Atomically register a trust: mint keys, claim an FL kit slot, insert the row.

Module Contents

exception flip_api.trusts_services.services.register_trust.TrustRegistrationError

Bases: Exception

Base for trust registration failures.

exception flip_api.trusts_services.services.register_trust.EmptyTrustNameError

Bases: TrustRegistrationError

Caller supplied a blank trust name.

exception flip_api.trusts_services.services.register_trust.EmptyTrustCodeError

Bases: TrustRegistrationError

Caller supplied a blank (or missing) trust code — code is required.

exception flip_api.trusts_services.services.register_trust.DuplicateTrustError

Bases: TrustRegistrationError

A trust with the given name already exists.

exception flip_api.trusts_services.services.register_trust.NoFreeKitSlotError

Bases: TrustRegistrationError

The FL kit slot pool is exhausted.

class flip_api.trusts_services.services.register_trust.RegisteredTrust

Result of a successful registration — the only place plaintext keys exist.

Plaintext trust_api_key and trust_internal_service_key are returned exactly once: the hub stores only the api-key’s SHA-256 hash, and the internal-service key is never persisted hub-side.

trust: flip_api.db.models.main_models.Trust
fl_kit_slot: flip_api.db.models.main_models.FLKitSlot
trust_api_key: str
trust_internal_service_key: str
flip_api.trusts_services.services.register_trust.register_trust(name: str, code: str | None, region: str | None, session: sqlmodel.Session, audit_user_id: uuid.UUID | None = None) → RegisteredTrust

Atomically register a trust: mint keys, claim an FL kit slot, insert the row.

Parameters:

  • name (str) – Friendly display name (any non-empty string after strip).

  • code (str | None) – Short code (e.g. GSTT). Required — must be non-empty after strip. Names are arbitrary/non-unique, so the code is the stable short handle used in kit filenames and operator tooling.

  • region (str | None) – Optional NHS region.

  • session (Session) – SQLModel session; the function commits before returning.

  • audit_user_id (UUID | None) – Cognito sub of the authenticated admin from the UI path, or None for the deploy-CLI path (which runs under operator IAM, not a FLIP user). Stamped on the trusts_audit row written in the same transaction as the trust insert.

Returns:

The persisted trust, its assigned FL kit slot, and the plaintext api / internal-service keys (returned once — discard from memory immediately after handing them to the operator).

Return type:

RegisteredTrust

Raises: