98 lines
3.4 KiB
Markdown
98 lines
3.4 KiB
Markdown
# 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.
|