127 lines
5.1 KiB
Markdown
127 lines
5.1 KiB
Markdown
# CASAN Assurance Kernel Migration
|
||
|
||
## Scope
|
||
|
||
This migration preserves existing native and Agentic Bridge protocols while
|
||
adding canonical kernel envelopes and changing unsafe defaults. It is designed
|
||
for incremental adoption; no big-bang H1–H7 rewrite is required.
|
||
|
||
## Behavior changes
|
||
|
||
1. H2 registry enforcement defaults on in enforce mode.
|
||
2. A missing or failed H2 dependency denies in enforce mode.
|
||
3. High-impact action classes use deterministic risk floors and require actor,
|
||
approval and evidence.
|
||
4. Failed side-effecting single-step execution defaults to halt in enforce or
|
||
production mode.
|
||
5. Enforce/production sandbox execution refuses timeout/static-only fallback.
|
||
6. Networked/production Control Plane startup requires verified JWT identity;
|
||
`CASAN_CP_TRUST_AUTH_PROXY` no longer authorizes header trust.
|
||
7. Production certification requires an external signing provider and external
|
||
immutable anchor.
|
||
8. Canonical schema `1.0.0` is dual-emitted with legacy runtime records.
|
||
|
||
## Development migration
|
||
|
||
Existing loopback development works with:
|
||
|
||
```text
|
||
CASAN_PROFILE=development
|
||
CASAN_CP_AUTH_MODE=local
|
||
CP_BIND=127.0.0.1
|
||
```
|
||
|
||
For short-lived compatibility testing only, H2 can be bypassed explicitly:
|
||
|
||
```text
|
||
CASAN_H2_REGISTRY=0
|
||
CASAN_AGENTIC_H2_REGISTRY=0
|
||
```
|
||
|
||
The bypass is high-severity, observe-only/non-certifiable and rejected in
|
||
production. Prefer registering the tool instead of retaining this setting.
|
||
|
||
Failure handling can be selected with
|
||
`CASAN_SINGLE_STEP_FAILURE_POLICY=halt|quarantine|require_approval|record_only`.
|
||
Production side effects reject `record_only` and fail closed to `halt`.
|
||
|
||
## Production Control Plane migration
|
||
|
||
1. Export the enterprise IdP's RS256 public key.
|
||
2. Configure issuer, audience, claim names and bounded clock skew in
|
||
`runtime.env` using `infra/production/runtime.env.example`.
|
||
3. Configure oauth2-proxy to pass access tokens and authorization headers.
|
||
4. Set `CASAN_CP_IDP_PUBLIC_KEY` in `casan-prod.env` for the read-only mount.
|
||
5. Add a digest-pinned `CASAN_CP_OAUTH2_PROXY_IMAGE`.
|
||
6. Remove `CASAN_CP_TRUST_AUTH_PROXY` from every environment.
|
||
7. Configure Vault/KMS and Object Lock provider variables.
|
||
8. Run `production-preflight.sh` before starting Compose.
|
||
9. Run managed endpoint smoke with an authenticated enterprise session.
|
||
|
||
The current API loads a static public key at startup. Coordinate IdP rotation by
|
||
installing the next public key and restarting the API after token overlap has
|
||
been handled operationally. Automated JWKS rollover is not yet implemented.
|
||
|
||
## Adapter migration
|
||
|
||
The native harness and Agentic Bridge already dual-emit to
|
||
`CASAN_STATE_ROOT/logs/kernel/`. Existing consumers can keep reading legacy
|
||
records. New consumers should:
|
||
|
||
1. Require `schema_version=1.0.0`.
|
||
2. Run the common verifier.
|
||
3. Respect the four separate outcome fields.
|
||
4. Reject observed-only certification.
|
||
5. Treat runtime extensions as optional namespaced data.
|
||
6. Avoid certifying legacy runs that have no canonical evidence.
|
||
|
||
For a new runtime, implement an adapter and pass the complete 10-invariant
|
||
conformance matrix before advertising kernel conformance.
|
||
|
||
## Audit compatibility
|
||
|
||
New H5 audit records use v2 hashing with action class and risk factors. The
|
||
audit verifier and head signer support v1 and v2 records. This is compatibility,
|
||
not claim upgrading: v1 records do not gain v2 risk evidence retroactively.
|
||
|
||
## Verification commands
|
||
|
||
```bash
|
||
python3 packages/casan-harness/tests/assurance-kernel-tests.py
|
||
python3 packages/casan-harness/tests/assurance-upgrade-integration-tests.py
|
||
bash packages/casan-harness/tests/phase-assurance-upgrade-tests.sh
|
||
bash packages/casan-harness/tests/phase-agentic-bridge-tests.sh
|
||
npm --workspace packages/casan-control-panel/backend test
|
||
npm --workspace packages/casan-control-panel/backend run build
|
||
npm --workspace packages/casan-control-panel/frontend run build
|
||
bash packages/casan-harness/tests/phase-production-preflight-tests.sh
|
||
```
|
||
|
||
Redirect `CASAN_STATE_ROOT` to a temporary directory for legacy suites that
|
||
write runtime evidence.
|
||
|
||
## Rollback
|
||
|
||
Code rollback can restore the previous adapters because legacy emission remains
|
||
present. Before rollback:
|
||
|
||
1. Stop new runs and preserve canonical/audit evidence.
|
||
2. Record the last v2 audit head and external anchor.
|
||
3. Roll back API, UI, Nginx and oauth2-proxy as one deployment unit.
|
||
4. Do not restore trusted-header identity on a networked deployment.
|
||
5. Do not disable production registry, isolation or trust-root requirements.
|
||
6. If operational continuity requires emergency local trust, use the explicit
|
||
break-glass override, retain the critical evidence and do not certify runs.
|
||
|
||
A rollback that reintroduces production header trust, missing-gate allow, or
|
||
silent sandbox/trust fallback is not a safe compatibility rollback.
|
||
|
||
## Expected warnings
|
||
|
||
- Development registry bypass: high severity and non-certifiable.
|
||
- Missing H2 in observe mode: degraded assurance.
|
||
- Local signer/local ledger: permitted locally, untrusted for production.
|
||
- Unsupported runtime intervention: explicit `unsupported`.
|
||
- Legacy evidence without kernel envelope: compatibility-readable but not
|
||
kernel-validated.
|