web/docs/governance-install-spec.md

Governance Install Specification (First Paid License)

This spec defines deterministic installation of the governance runtime after membership and governance entitlement purchase.

Preconditions

1. Launcher is installed and wallet is initialized locally.
2. Membership is active for ownership wallet.
3. Governance entitlement is active for ownership wallet.
4. Workspace target boundary matches active suite entitlement org_root_id.
5. Availability state for acting principal is not PARKED.
6. Acting principal role for install/update control is ORG_ROOT_OWNER.

Install Flow

1. Launcher requests governance install token from backend.
2. Backend verifies membership, governance entitlement, org boundary, and availability state.
3. Backend returns signed install bundle metadata:

• package url
• package hash
• signer key id
• policy hash
• expiry

4. Launcher downloads package.
5. Launcher verifies package hash.
6. Launcher verifies package signature against trusted signer set.
7. Launcher writes immutable install receipt locally.
8. Launcher hands off to governance runtime bootstrap.
9. Governance runtime re-verifies entitlement receipt and policy hash.
10. Runtime activation state transitions to ACTIVE.

Provisioning Profiles

The install flow supports multiple interaction profiles on the same governed path:

1. quick (recommended): sequential connector/auth setup with minimal operator overhead.
2. manual: explicit step-by-step setup for each integration.
3. advanced_edut_bootstrap: owner-only fast provisioning for managed devices.

Profile rules:

1. advanced_edut_bootstrap is only available to ORG_ROOT_OWNER.
2. workspace_member principals must never see or invoke advanced install controls.
3. Advanced profile may streamline permission/setup orchestration, but cannot skip:
   • package hash/signature verification
   • entitlement validation
   • boundary checks
   • provider/connector OAuth consent boundaries
4. All profile selections and resulting scope grants must be evidence-logged.

Activation State Machine

NOT_INSTALLED -> DOWNLOADED -> VERIFIED -> BOOTSTRAPPED -> ACTIVE

Failure states:

• VERIFY_FAILED
• RECEIPT_INVALID
• ENTITLEMENT_INACTIVE
• POLICY_MISMATCH

Deterministic Rules

1. Any missing signature/hash mismatch blocks install.
2. Any inactive/unknown entitlement blocks activation.
3. Any policy hash mismatch blocks activation.
4. Activation requires both launcher and runtime verification passes.
5. Reinstall with same package hash must be idempotent.
6. Boundary mismatch or PARKED availability state blocks install token issuance.
7. Non-owner principal role blocks install/update control paths.
8. Any attempt to invoke advanced_edut_bootstrap as non-owner is rejected and audit-logged.
9. Advanced bootstrap cannot be used to widen workspace boundary or entitlement scope.

Ownership vs Payment Wallet

1. Entitlement ownership wallet controls activation rights.
2. Payment wallet may differ from ownership wallet.
3. Activation checks only ownership wallet + entitlement state.

Evidence Requirements

Each successful install must persist evidence containing:

1. ownership wallet
2. entitlement id
3. package hash
4. signer key id
5. policy hash
6. activation timestamp
7. launcher version
8. runtime version

Non-Goals

1. Running governance runtime before entitlement verification.
2. Trusting unsigned packages.
3. Allowing active runtime on revoked entitlement.