Skip to content

institutional_guide.md

Latest commit

 

History

History
95 lines (73 loc) · 4.65 KB

institutional_guide.md

File metadata and controls

95 lines (73 loc) · 4.65 KB
Raw

Institutional Guide

Institutions adopting SCOPE 2.2 should start with the institutional pilot guide for workshop flow and runbooks/ for operator procedures, then use this page for production wiring and CI. Live IdP, WORM Object Lock, and remote ledger authority remain external (see definition_of_done.md).

Adoption checklist

  1. Configure and version-pin policy/ files for local role assignments and scope boundaries
  2. Map lab personnel to reviewer roles; generate Ed25519 keypairs and register public keys
  3. Build and sign an authorization manifest (SCOPE_AUTHORIZATION_MANIFEST_PATH + public key); ensure policy_signing_key_registry.yaml lists an active key
  4. Integrate AKTA review triggers via scope akta review or scope packet create
  5. Enable production mode (SCOPE_PRODUCTION_MODE=true) with OIDC IdP (SCOPE_OIDC_JWKS_URL or SCOPE_OIDC_PUBLIC_KEY_PEM) and org RBAC (SCOPE_ENFORCE_RBAC=true)
  6. Wire Postgres ledger (SCOPE_LEDGER_DATABASE_URL / SCOPE_POSTGRES_URL); do not use SQLite in production without SCOPE_ALLOW_SQLITE_LEDGER_IN_PRODUCTION=1
  7. Enforce grants at runtime via PF-Core or equivalent
  8. Archive SCOPE ledger events with PCS release packages
  9. Run the institutional CI profile before promoting a release

Production env (deploy without spelunking)

Authoritative template: env.institutional.example. Summary also in production_deployment.md. Minimum set:

Variable Required
SCOPE_PRODUCTION_MODE=true yes
SCOPE_OIDC_JWKS_URL or SCOPE_OIDC_PUBLIC_KEY_PEM yes (live IdP material)
SCOPE_OIDC_ISSUER / SCOPE_OIDC_AUDIENCE recommended
SCOPE_TENANT_POLICY_MAP yes
SCOPE_POLICY_DIR yes
SCOPE_ARTIFACT_STORE_ROOT yes
SCOPE_LEDGER_DATABASE_URL or SCOPE_POSTGRES_URL yes (institutional)
SCOPE_ISSUER_SIGNING_KEY / SCOPE_ISSUER_PUBLIC_KEY yes
SCOPE_AUTHORIZATION_MANIFEST_PATH yes
SCOPE_AUTHORIZATION_MANIFEST_PUBLIC_KEY yes

Check readiness without contacting IdP:

python scripts/validate_institutional_env.py

Dev-only keys (never production): python scripts/generate_dev_institutional_keys.py --out-dir .scope/dev-keys --exports

Sibling repos + Institutional CI

# Clone into ../siblings (set clone URLs first), or point at existing checkouts:
eval "$(bash scripts/clone_sibling_contracts.sh)"
# or:
export PF_CORE_REPO_PATH=/path/to/pf-core
export PCS_CORE_REPO_PATH=/path/to/pcs-core
export AKTA_REPO_PATH=/path/to/akta

export SCOPE_LEDGER_DATABASE_URL=postgresql://scope:scope@127.0.0.1:5432/scope
export SCOPE_REQUIRE_LIVE_CONTRACTS=true   # fail-closed if any sibling missing
bash scripts/ci.sh --institutional

GitHub Actions org/repo variables for job institutional:

Variable Role
PF_CORE_REPO (alias PF_CORE_REPO_CLONE_URL) Clone URL
PCS_CORE_REPO (alias PCS_CORE_REPO_CLONE_URL) Clone URL
AKTA_REPO (alias AKTA_REPO_CLONE_URL) Clone URL
*_REPO_PATH Self-hosted pre-mounted paths
SCOPE_REQUIRE_LIVE_CONTRACTS=true Fail-closed when siblings missing

Job dependency-audit is fail-closed on release/** branches. Live IdP JWKS endpoints and production private keys remain human-provided deploy secrets.

Evidence for auditors

  • Who reviewed (role, ID, identity assurance level, authority checks, credential evidence on REST)
  • What scope was approved and what remained blocked
  • Signing assurance level on decisions and grants
  • When grants expired and whether runtime respected grants
  • Trust root hashes binding policy and key registry (signed authorization manifest)

SCOPE provides the authorization trail; it does not certify scientific correctness or regulatory compliance.

Related documentation

Offline gates (prefer before institutional CI):

python scripts/run_institutional_offline_gates.py