Files

tegwick ce82ada0fa STATE-WP-0062 T5: docs, first-party↔repo test, mark workplan finished

- Add /docs/services reference (two-dimension model, persistence, API) and a
  pointer note from /docs/tpsc; add it to the Reference nav.
- Add a test asserting first_party.repo_slug resolves to a managed_repos FK
  (8 services tests green).
- Mark STATE-WP-0062 tasks done / status finished.

Known classes seeded in the live catalog via the API (Gitea, Postgres as
self-hosted/third-party; State Hub as self-hosted/first-party at Level 2).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-19 21:16:37 +02:00

4.7 KiB

Raw Blame History

title

title
Third-Party Services Catalog (TPSC)

Third-Party Services Catalog (TPSC)

The TPSC tracks external service dependencies (APIs, SaaS, CLIs) across all registered repos — complementing the SBOM for package dependencies.

Now part of the broader service catalog. TPSC is the cloud_hosted + third_party quadrant of the two-dimension service catalog. Catalog rows have migrated into service_catalog; the /tpsc/* endpoints and per-repo tpsc.yaml dependency snapshots continue to work unchanged.

Why TPSC?

Package lockfiles capture Python/JS/Rust dependencies but miss the external HTTP services your code calls. These carry compliance, cost, and privacy implications that are invisible to standard SBOM tooling.

TPSC provides:

A registry of which repos use which external services
GDPR compliance maturity ratings per service
Pricing model tracking (paid/usage-based costs)
Data processing region and retention information
GDPR warnings for services not suitable in regulated environments

Primary Data Locations

Following ADR-001 (workplans as repo artefacts), TPSC data lives in two places:

Location	Purpose
`<repo>/tpsc.yaml`	Declares which services the repo uses
`the-custodian/canon/tpsc/<slug>.yaml`	Canonical service metadata (ToS, GDPR, pricing)

The state-hub is a collector — it can be rebuilt from scratch by re-ingesting all tpsc.yaml files and re-seeding the catalog from canon files.

tpsc.yaml Format

# tpsc.yaml — Third-Party Services Catalog declarations
# Ingest: cd state-hub && make ingest-tpsc REPO=<slug>

services:
  - slug: openai-api          # Must match a slug in canon/tpsc/
    purpose: LLM inference via OpenAI-compatible API
    auth: api_key             # api_key | oauth | cli | none | unknown

  - slug: stripe
    purpose: Payment processing
    auth: api_key
    endpoint: https://api.stripe.com  # Optional override if non-standard
    notes: Only used in production tier

Canon Service File Format

# canon/tpsc/openai-api.yaml
slug: openai-api
name: OpenAI API
provider: OpenAI, Inc.
category: llm_inference       # llm_inference | storage | payments | search | etc.
website_url: https://openai.com
pricing_model: usage_based    # free | paid | freemium | usage_based | unknown
gdpr_maturity: developing     # See scale below
gdpr_notes: >
  DPA available. SCCs for EU→US transfer. 30-day retention for safety.
dpa_available: true
tos_url: https://openai.com/policies/terms-of-use
privacy_policy_url: https://openai.com/policies/privacy-policy
data_processing_regions:
  - us
data_retention_notes: >
  30 days default; zero-retention available on eligible endpoints.
status: active

Based on the CNIL / IAPP CMMI Privacy Maturity Model, adapted for third-party service assessment:

Level	Name	Description	Dashboard
0	`unknown`	No information about GDPR stance	🔴 Warning
1	`non_compliant`	Known GDPR issues, no remediation	🔴 Warning
2	`initial`	Basic privacy policy only, ad hoc approach	🟠 Warning
3	`developing`	DPA available, some controls, SCCs provided	🟡
4	`defined`	Formal DPA, SCCs documented, clear retention policy	🟢
5	`managed`	Independently audited, metrics tracked	🟢
6	`certified`	ISO 27701 / SOC2 privacy certified	🟢

Services at levels 0–2 (Warning) may limit use in GDPR-regulated or corporate environments. At minimum, developing is needed for routine processing of personal data with an API provider.

Reference: CNIL GDPR maturity model, IAPP Privacy Maturity Model

Adding a New Service

Create the-custodian/canon/tpsc/<slug>.yaml following the format above
Seed it into the state-hub: cd state-hub && make api then POST to /tpsc/catalog/ (or use the MCP tool: register_service(slug=..., ...))
Add it to your repo's tpsc.yaml
Ingest: make ingest-tpsc REPO=<slug>

MCP Tools

Tool	Purpose
`register_service(slug, ...)`	Add/update a service in the catalog
`list_services(gdpr_maturity?, category?, pricing_model?)`	Browse catalog
`ingest_tpsc_tool(repo_slug)`	Parse tpsc.yaml and ingest snapshot
`get_gdpr_report()`	GDPR warning summary across all repos

Makefile Targets

make ingest-tpsc REPO=llm-connect      # Ingest single repo
make ingest-tpsc-all                    # Ingest all repos
make ingest-tpsc REPO=llm-connect DRY_RUN=1  # Preview only

4.7 KiB Raw Blame History Unescape Escape