Skip to content

Control Plane: service graph and product identity audit contract #16

Description

@mdheller

Context

The Apple/macOS review showed that modern applications are process families, not single PIDs. BearBrowser also exposed product-identity leakage risk: upstream engine names can leak through launch, process, helper, profile, and crash surfaces.

Scope

Define and implement a minimal service graph and product-identity audit contract.

Deliverables

  • Service graph fixture format using schemas/sourceos-service.schema.json.
  • Product identity audit checklist for bundle, dock, menu, process, helper, profile, crash, update, and log surfaces.
  • sourceos_eventctl.py or separate tooling to validate service fixtures.
  • Example pass/fail outputs for BearBrowser-style browser product identity.

Acceptance criteria

  • make validate passes.
  • BearBrowser fixture remains valid.
  • Product identity mismatch produces an identity_mismatch incident bundle shape.
  • The contract is product-neutral enough for TurtleTerm and future SourceOS apps.

Non-goals

  • Patching BearBrowser itself in this issue.
  • Full process inventory daemon implementation.

Activity

mdheller commented on May 7, 2026

@mdheller
ContributorAuthor

Implementation tranche landed on main for the service graph and product identity audit contract.

Completed scope:

  • examples/services/bearbrowser.service.json defines the BearBrowser service graph fixture.
  • examples/launch/bearbrowser.launch-manifest.json defines the hermetic launch/product identity fixture.
  • examples/incidents/bearbrowser-identity-leak.incident.json captures the identity-mismatch incident shape.
  • tools/sourceos_identity_audit.py checks product identity invariants across service + launch manifests.
  • examples/launch/invalid/bearbrowser-upstream-leak.launch-manifest.json provides a negative upstream-leak fixture.
  • tools/smoke_identity_audit.py proves the good fixture passes and the upstream-leak fixture fails.
  • make validate now includes the identity audit smoke test.

The audit currently checks: display-name alignment, product ID/bundle identity, expected process name, dock/menu/crash/helper naming, profile policy, no inherited shell environment, duplicate PATH entries, developer/toolchain PATH warning, denied pollution variables, and required identity.product.upstream_leak denial.

Evidence limitation: connector did not surface a GitHub Actions run or combined status for the latest commit, so CI pass is not yet independently confirmed here. Keep the issue open until CI status is visible or make install-dev && make validate output is recorded.

mdheller commented on May 7, 2026

@mdheller
ContributorAuthor

Additional tranche landed on main for service graph tooling.

Completed:

  • Added tools/sourceos_service_graph.py.
  • Added validate-service-graph to make validate.
  • Documented service graph commands in README.

The tool validates service manifests, summarizes services by owner and authority domain, indexes required/optional/denied capabilities, and checks release-gate basics: non-empty capabilities/data/triggers/resources, event emission enabled, incident bundle support, app product-identity guardrails, and owner metadata.

CI/status caveat: the connector still does not show a visible Actions run or combined status for the latest commit, so this remains awaiting independent validation output.

mdheller commented on Jul 18, 2026

@mdheller
ContributorAuthor

Closed: service graph and product identity audit contract shipped in PR #43 (controller-sovereignty-contract-20260603). Service graph fixture format, product identity audit checklist, identity_mismatch incident bundle shape, and BearBrowser-style browser product identity examples are included.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions