Co-authored-by: jcwalker3 <[email protected]>
This commit was merged in pull request #839.
This commit is contained in:
@@ -0,0 +1,892 @@
|
||||
"""ARCH-01 Foundation Slice A — atomic platform installation + authority kernel (#822).
|
||||
|
||||
Parents: #820, #821. **First implementation leaf of the ARCH-01 program.**
|
||||
|
||||
This module implements the smallest executable ARCH-01 foundation:
|
||||
|
||||
* a connection-bound authenticated actor context (``cp_actor_*`` /
|
||||
``cp_operation_mode`` / ``cp_context_epoch`` SQLite scalar functions that SQL
|
||||
may *read* but can never *set* — ``[TRUSTED-SERVICE]`` authenticity);
|
||||
* an immutable authority-dominance lattice with an exact seeded tuple set
|
||||
(``[SCHEMA]``);
|
||||
* the principal-equivalence root (a class exists *before* its first principal;
|
||||
``principals.current_class_id`` is ``NOT NULL``; ``[SCHEMA]``);
|
||||
* a single-transaction platform installation that seeds the initial
|
||||
``platform.bootstrap`` grant and an immutable ``installed`` marker, validated
|
||||
by a fail-closed ``install_state`` ``BEFORE INSERT`` trigger (``[SCHEMA]``).
|
||||
|
||||
Everything else in the ARCH-01/02/04 program (evidence stores, repository
|
||||
bindings, workspaces, PostgreSQL parity, full grant succession, full principal
|
||||
merge) is out of scope here and tracked in its own issue — see #822 §5/§17.
|
||||
|
||||
**Readiness / production posture.** This subsystem is *disabled by default*.
|
||||
Nothing in the running MCP server imports or enables it. It becomes a security
|
||||
boundary only once its readiness checks (the ACs in #822) pass in the target
|
||||
environment. Instantiating :class:`PlatformKernel` creates an isolated SQLite
|
||||
database and never touches the operational control-plane store.
|
||||
|
||||
Enforcement classification (per #820 vocabulary):
|
||||
|
||||
* ``[TRUSTED-SERVICE]`` — actor-context authenticity: the scalar functions are
|
||||
registered by the trusted Python process; SQL cannot define or redefine them.
|
||||
* ``[SCHEMA]`` — fail-closed aborts, the dominance/immutability/NOT-NULL-class/
|
||||
last-active-grant invariants, enforced by CHECK/FK/trigger.
|
||||
* ``[RUNTIME-ADAPTER]`` — *none* in this slice.
|
||||
|
||||
SQLite-first. ``BEGIN IMMEDIATE`` serializes concurrent installs and concurrent
|
||||
grant/revoke on the singleton invariant row. PostgreSQL parity is a distinct
|
||||
issue (#827); this module does **not** claim it.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import sqlite3
|
||||
import threading
|
||||
from contextlib import contextmanager
|
||||
from dataclasses import dataclass
|
||||
from datetime import datetime, timezone
|
||||
from typing import Iterator, Optional
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# Closed enumerations (#822 §4).
|
||||
# --------------------------------------------------------------------------- #
|
||||
|
||||
ACTOR_KINDS = ("operator", "supervisor", "service", "installer")
|
||||
OPERATION_MODES = ("normal", "install", "merge", "internal_service")
|
||||
|
||||
# Exact seeded authority-dominance tuple set (#822 §4). This set is normative:
|
||||
# the install-state trigger rejects any missing, additional, or malformed tuple.
|
||||
DOMINANCE_TUPLES = (
|
||||
("platform.bootstrap", "platform.bootstrap"),
|
||||
("platform.bootstrap", "project.admin"),
|
||||
("platform.bootstrap", "supervisor.root.establish"),
|
||||
("supervisor.root", "supervisor.register"),
|
||||
("supervisor.root", "supervisor.verify"),
|
||||
("supervisor.root", "supervisor.recover"),
|
||||
)
|
||||
|
||||
# The distinguished operator-key issuer seeded during install.
|
||||
DISTINGUISHED_ISSUER_KIND = "operator-key"
|
||||
DISTINGUISHED_ISSUER_ID = "platform.bootstrap.operator-key"
|
||||
|
||||
# Structured result codes (#822 §10).
|
||||
INSTALLED = "INSTALLED"
|
||||
ALREADY_INSTALLED = "ALREADY_INSTALLED"
|
||||
INVALID_ACTOR_CONTEXT = "INVALID_ACTOR_CONTEXT"
|
||||
INVALID_BOOTSTRAP_STATE = "INVALID_BOOTSTRAP_STATE"
|
||||
DOMINANCE_SET_MISMATCH = "DOMINANCE_SET_MISMATCH"
|
||||
AUTHORIZATION_DENIED = "AUTHORIZATION_DENIED"
|
||||
CONCURRENT_INSTALLATION_LOST = "CONCURRENT_INSTALLATION_LOST"
|
||||
|
||||
# Required audit events (#822 §14).
|
||||
EVT_PLATFORM_INSTALLED = "platform_installed"
|
||||
EVT_GRANT_CREATED = "platform_grant_created"
|
||||
EVT_GRANT_REVOKED = "platform_grant_revoked"
|
||||
EVT_PRINCIPAL_REGISTERED = "principal_registered"
|
||||
|
||||
SCHEMA_VERSION = 1
|
||||
|
||||
DB_PATH_ENV = "ARCH01_PLATFORM_DB"
|
||||
|
||||
|
||||
class PlatformKernelError(RuntimeError):
|
||||
"""Base class for structured, code-bearing kernel failures."""
|
||||
|
||||
def __init__(self, code: str, message: str = "") -> None:
|
||||
super().__init__(message or code)
|
||||
self.code = code
|
||||
|
||||
|
||||
class ActorContextError(PlatformKernelError):
|
||||
"""Raised when a mutation is attempted without a valid actor context."""
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# Schema (#822 §6). Tables + fail-closed triggers.
|
||||
#
|
||||
# Every *mutating* trigger opens with the actor protocol: read the context
|
||||
# epoch, read the actor fields, and abort unless the context is present,
|
||||
# non-null, mode/kind well-formed, and epoch-consistent with the active
|
||||
# transaction. The scalar functions ``cp_*`` are registered from Python only;
|
||||
# SQL has no statement that can set them, which is the trusted-service boundary.
|
||||
# --------------------------------------------------------------------------- #
|
||||
|
||||
_ACTOR_KINDS_SQL = ", ".join("'%s'" % k for k in ACTOR_KINDS)
|
||||
_OP_MODES_SQL = ", ".join("'%s'" % m for m in OPERATION_MODES)
|
||||
|
||||
# Actor-protocol predicate: TRUE when the context is INVALID and the trigger
|
||||
# must abort. ``cp_actor_context_valid()`` folds "present + non-expired +
|
||||
# live-epoch == bound-epoch" (the read/re-read epoch equality of #822 §4) into
|
||||
# one trusted-service answer; the remaining reads assert field well-formedness.
|
||||
_INVALID_ACTOR = (
|
||||
"cp_actor_context_valid() IS NOT 1 "
|
||||
"OR cp_context_epoch() IS NULL "
|
||||
"OR cp_actor_principal() IS NULL "
|
||||
"OR cp_actor_kind() NOT IN (%s) "
|
||||
"OR cp_operation_mode() NOT IN (%s)" % (_ACTOR_KINDS_SQL, _OP_MODES_SQL)
|
||||
)
|
||||
|
||||
_ACTOR_GUARD = (
|
||||
"SELECT CASE WHEN (%s) "
|
||||
"THEN RAISE(ABORT, 'INVALID_ACTOR_CONTEXT') END;" % _INVALID_ACTOR
|
||||
)
|
||||
|
||||
# require_installed: abort a privileged mutation when there is no install
|
||||
# marker and we are not currently installing (#822 §4).
|
||||
_REQUIRE_INSTALLED = (
|
||||
"SELECT CASE WHEN ((SELECT COUNT(*) FROM install_state) = 0 "
|
||||
"AND cp_operation_mode() <> 'install') "
|
||||
"THEN RAISE(ABORT, 'NOT_INSTALLED') END;"
|
||||
)
|
||||
|
||||
_SCHEMA_SQL = f"""
|
||||
PRAGMA foreign_keys = ON;
|
||||
|
||||
CREATE TABLE IF NOT EXISTS arch01_meta (
|
||||
key TEXT PRIMARY KEY,
|
||||
value TEXT NOT NULL
|
||||
);
|
||||
|
||||
-- Equivalence classes are created BEFORE their first principal (#822 §4).
|
||||
CREATE TABLE IF NOT EXISTS principal_equivalence_classes (
|
||||
class_id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
created_at TEXT NOT NULL
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS authoritative_issuers (
|
||||
issuer_id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
issuer_kind TEXT NOT NULL,
|
||||
issuer_ref TEXT NOT NULL,
|
||||
created_at TEXT NOT NULL,
|
||||
UNIQUE (issuer_kind, issuer_ref)
|
||||
);
|
||||
|
||||
-- current_class_id is NOT NULL: a principal cannot exist without a class
|
||||
-- (#822 AC6). issuer_id is nullable ONLY for the installer during install
|
||||
-- (#822 AC7), enforced by trg_principals_null_issuer below.
|
||||
CREATE TABLE IF NOT EXISTS principals (
|
||||
principal_id TEXT PRIMARY KEY,
|
||||
actor_kind TEXT NOT NULL CHECK (actor_kind IN ({_ACTOR_KINDS_SQL})),
|
||||
current_class_id INTEGER NOT NULL REFERENCES principal_equivalence_classes(class_id),
|
||||
issuer_id INTEGER REFERENCES authoritative_issuers(issuer_id),
|
||||
registered_by TEXT REFERENCES principals(principal_id),
|
||||
created_at TEXT NOT NULL
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS authority_dominance (
|
||||
dominant TEXT NOT NULL,
|
||||
subordinate TEXT NOT NULL,
|
||||
PRIMARY KEY (dominant, subordinate)
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS platform_bootstrap_seed (
|
||||
seed_id INTEGER PRIMARY KEY CHECK (seed_id = 1),
|
||||
installer_principal_id TEXT NOT NULL REFERENCES principals(principal_id),
|
||||
created_at TEXT NOT NULL
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS platform_bootstrap_grants (
|
||||
grant_id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
grantee_principal_id TEXT NOT NULL REFERENCES principals(principal_id),
|
||||
granted_by TEXT REFERENCES principals(principal_id),
|
||||
active INTEGER NOT NULL DEFAULT 1 CHECK (active IN (0, 1)),
|
||||
created_at TEXT NOT NULL,
|
||||
revoked_at TEXT
|
||||
);
|
||||
|
||||
-- Singleton row; active_count floored at 1 by CHECK so the last active grant
|
||||
-- can never be revoked (#822 AC11).
|
||||
CREATE TABLE IF NOT EXISTS platform_active_invariant (
|
||||
id INTEGER PRIMARY KEY CHECK (id = 1),
|
||||
active_count INTEGER NOT NULL CHECK (active_count >= 1)
|
||||
);
|
||||
|
||||
-- The immutable install marker; inserted LAST in the install transaction.
|
||||
CREATE TABLE IF NOT EXISTS install_state (
|
||||
id INTEGER PRIMARY KEY CHECK (id = 1),
|
||||
marker TEXT NOT NULL CHECK (marker = 'installed'),
|
||||
installed_at TEXT NOT NULL
|
||||
);
|
||||
|
||||
-- Append-only (#822 AC14).
|
||||
CREATE TABLE IF NOT EXISTS audit_records (
|
||||
audit_id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
event TEXT NOT NULL,
|
||||
principal_id TEXT,
|
||||
detail TEXT,
|
||||
created_at TEXT NOT NULL
|
||||
);
|
||||
|
||||
-- ------------------------------------------------------------------------- --
|
||||
-- Actor protocol on every mutating trigger (#822 §4, [SCHEMA] fail-closed).
|
||||
-- ------------------------------------------------------------------------- --
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_classes_actor
|
||||
BEFORE INSERT ON principal_equivalence_classes
|
||||
BEGIN
|
||||
{_ACTOR_GUARD}
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_issuers_actor
|
||||
BEFORE INSERT ON authoritative_issuers
|
||||
BEGIN
|
||||
{_ACTOR_GUARD}
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_principals_actor
|
||||
BEFORE INSERT ON principals
|
||||
BEGIN
|
||||
{_ACTOR_GUARD}
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_dominance_actor
|
||||
BEFORE INSERT ON authority_dominance
|
||||
BEGIN
|
||||
{_ACTOR_GUARD}
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_seed_actor
|
||||
BEFORE INSERT ON platform_bootstrap_seed
|
||||
BEGIN
|
||||
{_ACTOR_GUARD}
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_grants_actor_insert
|
||||
BEFORE INSERT ON platform_bootstrap_grants
|
||||
BEGIN
|
||||
{_ACTOR_GUARD}
|
||||
{_REQUIRE_INSTALLED}
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_grants_actor_update
|
||||
BEFORE UPDATE ON platform_bootstrap_grants
|
||||
BEGIN
|
||||
{_ACTOR_GUARD}
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_invariant_actor_insert
|
||||
BEFORE INSERT ON platform_active_invariant
|
||||
BEGIN
|
||||
{_ACTOR_GUARD}
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_invariant_actor_update
|
||||
BEFORE UPDATE ON platform_active_invariant
|
||||
BEGIN
|
||||
{_ACTOR_GUARD}
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_audit_actor
|
||||
BEFORE INSERT ON audit_records
|
||||
BEGIN
|
||||
{_ACTOR_GUARD}
|
||||
END;
|
||||
|
||||
-- ------------------------------------------------------------------------- --
|
||||
-- NOT-NULL-issuer exception for the installer only (#822 AC7).
|
||||
-- A NULL issuer_id is accepted solely for an installer principal during
|
||||
-- install mode, before the marker exists; any other NULL-issuer principal is
|
||||
-- rejected. install-time issuer linkage (installer -> distinguished issuer)
|
||||
-- is applied by a later UPDATE, permitted while no marker exists.
|
||||
-- ------------------------------------------------------------------------- --
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_principals_null_issuer
|
||||
BEFORE INSERT ON principals
|
||||
WHEN NEW.issuer_id IS NULL
|
||||
BEGIN
|
||||
SELECT CASE WHEN NOT (
|
||||
NEW.actor_kind = 'installer'
|
||||
AND cp_operation_mode() = 'install'
|
||||
AND (SELECT COUNT(*) FROM install_state) = 0
|
||||
AND (SELECT COUNT(*) FROM principals WHERE issuer_id IS NULL) = 0
|
||||
) THEN RAISE(ABORT, 'INVALID_BOOTSTRAP_STATE') END;
|
||||
END;
|
||||
|
||||
-- ------------------------------------------------------------------------- --
|
||||
-- Post-install immutability of the authority root (#822 §4, AC9).
|
||||
-- Registration fields freeze only AFTER the marker exists, so the install
|
||||
-- transaction's own installer issuer-linkage UPDATE is permitted.
|
||||
-- ------------------------------------------------------------------------- --
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_principals_frozen_update
|
||||
BEFORE UPDATE ON principals
|
||||
WHEN (SELECT COUNT(*) FROM install_state) > 0
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_PRINCIPAL');
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_principals_frozen_delete
|
||||
BEFORE DELETE ON principals
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_PRINCIPAL');
|
||||
END;
|
||||
|
||||
-- Distinguished issuer identity is immutable once written.
|
||||
CREATE TRIGGER IF NOT EXISTS trg_issuers_immutable_update
|
||||
BEFORE UPDATE ON authoritative_issuers
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_ISSUER');
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_issuers_immutable_delete
|
||||
BEFORE DELETE ON authoritative_issuers
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_ISSUER');
|
||||
END;
|
||||
|
||||
-- The dominance lattice is immutable once seeded.
|
||||
CREATE TRIGGER IF NOT EXISTS trg_dominance_immutable_update
|
||||
BEFORE UPDATE ON authority_dominance
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_DOMINANCE');
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_dominance_immutable_delete
|
||||
BEFORE DELETE ON authority_dominance
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_DOMINANCE');
|
||||
END;
|
||||
|
||||
-- The bootstrap seed is immutable once written.
|
||||
CREATE TRIGGER IF NOT EXISTS trg_seed_immutable_update
|
||||
BEFORE UPDATE ON platform_bootstrap_seed
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_SEED');
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_seed_immutable_delete
|
||||
BEFORE DELETE ON platform_bootstrap_seed
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_SEED');
|
||||
END;
|
||||
|
||||
-- The install marker is immutable once written.
|
||||
CREATE TRIGGER IF NOT EXISTS trg_install_state_immutable_update
|
||||
BEFORE UPDATE ON install_state
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_INSTALL_STATE');
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_install_state_immutable_delete
|
||||
BEFORE DELETE ON install_state
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_INSTALL_STATE');
|
||||
END;
|
||||
|
||||
-- Grants: identity is immutable; the ONLY permitted mutation is a single
|
||||
-- active 1 -> 0 revocation (#822 §4 initial-grant identity immutability +
|
||||
-- grant/revoke). Reactivation and identity edits are rejected.
|
||||
CREATE TRIGGER IF NOT EXISTS trg_grants_identity_frozen
|
||||
BEFORE UPDATE ON platform_bootstrap_grants
|
||||
WHEN NOT (
|
||||
NEW.grant_id = OLD.grant_id
|
||||
AND NEW.grantee_principal_id = OLD.grantee_principal_id
|
||||
AND NEW.granted_by IS OLD.granted_by
|
||||
AND NEW.created_at = OLD.created_at
|
||||
AND OLD.active = 1
|
||||
AND NEW.active = 0
|
||||
)
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_GRANT');
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_grants_no_delete
|
||||
BEFORE DELETE ON platform_bootstrap_grants
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_GRANT');
|
||||
END;
|
||||
|
||||
-- audit_records is append-only.
|
||||
CREATE TRIGGER IF NOT EXISTS trg_audit_immutable_update
|
||||
BEFORE UPDATE ON audit_records
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_AUDIT');
|
||||
END;
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_audit_immutable_delete
|
||||
BEFORE DELETE ON audit_records
|
||||
BEGIN
|
||||
SELECT RAISE(ABORT, 'IMMUTABLE_AUDIT');
|
||||
END;
|
||||
|
||||
-- ------------------------------------------------------------------------- --
|
||||
-- install_state BEFORE INSERT: validate the whole bootstrap atomically
|
||||
-- (#822 §4, AC4). Each dominance tuple is checked individually; a missing,
|
||||
-- additional, or malformed tuple -> DOMINANCE_SET_MISMATCH. The seed<->installer
|
||||
-- link, the single active NULL-grantor installer grant, the installer's
|
||||
-- non-NULL issuer, the active invariant, and "no extra principal created under
|
||||
-- the NULL-issuer exception" -> INVALID_BOOTSTRAP_STATE.
|
||||
-- ------------------------------------------------------------------------- --
|
||||
|
||||
CREATE TRIGGER IF NOT EXISTS trg_install_state_validate
|
||||
BEFORE INSERT ON install_state
|
||||
BEGIN
|
||||
SELECT CASE WHEN NOT (
|
||||
(SELECT COUNT(*) FROM authority_dominance) = {len(DOMINANCE_TUPLES)}
|
||||
AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='platform.bootstrap' AND subordinate='platform.bootstrap')
|
||||
AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='platform.bootstrap' AND subordinate='project.admin')
|
||||
AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='platform.bootstrap' AND subordinate='supervisor.root.establish')
|
||||
AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='supervisor.root' AND subordinate='supervisor.register')
|
||||
AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='supervisor.root' AND subordinate='supervisor.verify')
|
||||
AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='supervisor.root' AND subordinate='supervisor.recover')
|
||||
) THEN RAISE(ABORT, 'DOMINANCE_SET_MISMATCH') END;
|
||||
|
||||
SELECT CASE WHEN NOT (
|
||||
(SELECT COUNT(*) FROM platform_bootstrap_seed) = 1
|
||||
AND (SELECT COUNT(*) FROM principals) = 1
|
||||
AND (SELECT actor_kind FROM principals
|
||||
WHERE principal_id = (SELECT installer_principal_id FROM platform_bootstrap_seed WHERE seed_id = 1)
|
||||
) = 'installer'
|
||||
AND (SELECT issuer_id FROM principals
|
||||
WHERE principal_id = (SELECT installer_principal_id FROM platform_bootstrap_seed WHERE seed_id = 1)
|
||||
) IS NOT NULL
|
||||
AND (SELECT COUNT(*) FROM platform_bootstrap_grants
|
||||
WHERE granted_by IS NULL AND active = 1
|
||||
AND grantee_principal_id = (SELECT installer_principal_id FROM platform_bootstrap_seed WHERE seed_id = 1)
|
||||
) = 1
|
||||
AND (SELECT COUNT(*) FROM platform_bootstrap_grants) = 1
|
||||
AND (SELECT active_count FROM platform_active_invariant WHERE id = 1) = 1
|
||||
) THEN RAISE(ABORT, 'INVALID_BOOTSTRAP_STATE') END;
|
||||
END;
|
||||
"""
|
||||
|
||||
|
||||
def default_db_path() -> str:
|
||||
return os.environ.get(
|
||||
DB_PATH_ENV,
|
||||
os.path.expanduser("~/.cache/gitea-tools/arch01/platform.sqlite3"),
|
||||
)
|
||||
|
||||
|
||||
def _utc_now_iso() -> str:
|
||||
return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class OperationResult:
|
||||
"""Structured result of a kernel operation (#822 §10)."""
|
||||
|
||||
code: str
|
||||
detail: str = ""
|
||||
|
||||
@property
|
||||
def ok(self) -> bool:
|
||||
return self.code in (INSTALLED, ALREADY_INSTALLED)
|
||||
|
||||
|
||||
@dataclass
|
||||
class _ActorContext:
|
||||
principal: str
|
||||
kind: str
|
||||
mode: str
|
||||
session: Optional[str]
|
||||
bound_epoch: int
|
||||
live_epoch: int
|
||||
expired: bool = False
|
||||
|
||||
|
||||
class PlatformKernel:
|
||||
"""ARCH-01 authority kernel over a single SQLite connection.
|
||||
|
||||
The connection carries the trusted-service actor context: the ``cp_*``
|
||||
scalar functions read the context this object holds. Only Python code here
|
||||
can bind or clear it, so no SQL statement can assert an actor identity — the
|
||||
trusted-service authenticity boundary of #822 §4.
|
||||
"""
|
||||
|
||||
def __init__(self, db_path: Optional[str] = None, *, busy_timeout_ms: int = 5000) -> None:
|
||||
self.db_path = db_path or default_db_path()
|
||||
if self.db_path != ":memory:":
|
||||
parent = os.path.dirname(self.db_path)
|
||||
if parent:
|
||||
os.makedirs(parent, exist_ok=True)
|
||||
self._ctx: Optional[_ActorContext] = None
|
||||
self._epoch_seq = 0
|
||||
self._lock = threading.Lock()
|
||||
# check_same_thread=False is safe: every mutation path is serialized
|
||||
# by self._lock, so the connection is never used concurrently even when
|
||||
# callers drive the kernel from different threads (concurrency tests).
|
||||
self._conn = sqlite3.connect(
|
||||
self.db_path, isolation_level=None, check_same_thread=False
|
||||
)
|
||||
self._conn.execute("PRAGMA foreign_keys = ON")
|
||||
self._conn.execute(f"PRAGMA busy_timeout = {int(busy_timeout_ms)}")
|
||||
self._register_actor_functions()
|
||||
self._migrate()
|
||||
|
||||
# -- trusted-service actor functions ---------------------------------- #
|
||||
|
||||
def _register_actor_functions(self) -> None:
|
||||
c = self._conn
|
||||
c.create_function("cp_actor_principal", 0, lambda: self._ctx.principal if self._ctx else None)
|
||||
c.create_function("cp_actor_kind", 0, lambda: self._ctx.kind if self._ctx else None)
|
||||
c.create_function("cp_operation_mode", 0, lambda: self._ctx.mode if self._ctx else None)
|
||||
c.create_function("cp_service_session", 0, lambda: self._ctx.session if self._ctx else None)
|
||||
c.create_function("cp_context_epoch", 0, self._fn_context_epoch)
|
||||
# Trusted-service helper: folds present + non-expired + epoch-consistent
|
||||
# into the read/re-read epoch equality of #822 §4.
|
||||
c.create_function("cp_actor_context_valid", 0, self._fn_context_valid)
|
||||
|
||||
def _fn_context_epoch(self) -> Optional[int]:
|
||||
if self._ctx is None or self._ctx.expired:
|
||||
return None
|
||||
return self._ctx.live_epoch
|
||||
|
||||
def _fn_context_valid(self) -> int:
|
||||
ctx = self._ctx
|
||||
if ctx is None or ctx.expired:
|
||||
return 0
|
||||
# read/re-read epoch equality: a context whose live epoch has drifted
|
||||
# from the epoch it was bound to (a stale/replaced connection context)
|
||||
# is not bound to the active transaction and fails closed.
|
||||
if ctx.live_epoch != ctx.bound_epoch:
|
||||
return 0
|
||||
if ctx.principal is None:
|
||||
return 0
|
||||
if ctx.kind not in ACTOR_KINDS or ctx.mode not in OPERATION_MODES:
|
||||
return 0
|
||||
return 1
|
||||
|
||||
# -- context lifecycle ------------------------------------------------ #
|
||||
|
||||
@contextmanager
|
||||
def actor_context(
|
||||
self, principal: str, kind: str, mode: str, session: Optional[str] = None
|
||||
) -> Iterator[None]:
|
||||
"""Bind a trusted actor context for the duration of the block."""
|
||||
prev = self._ctx
|
||||
self._epoch_seq += 1
|
||||
epoch = self._epoch_seq
|
||||
self._ctx = _ActorContext(
|
||||
principal=principal, kind=kind, mode=mode, session=session,
|
||||
bound_epoch=epoch, live_epoch=epoch,
|
||||
)
|
||||
try:
|
||||
yield
|
||||
finally:
|
||||
self._ctx = prev
|
||||
|
||||
def _clear_context(self) -> None:
|
||||
self._ctx = None
|
||||
|
||||
# -- migration -------------------------------------------------------- #
|
||||
|
||||
def _migrate(self) -> None:
|
||||
self._conn.executescript(_SCHEMA_SQL)
|
||||
self._conn.execute(
|
||||
"INSERT OR IGNORE INTO arch01_meta(key, value) VALUES ('schema_version', ?)",
|
||||
(str(SCHEMA_VERSION),),
|
||||
)
|
||||
self._conn.execute(
|
||||
"INSERT OR IGNORE INTO arch01_meta(key, value) VALUES "
|
||||
"('architecture', 'ARCH-01 Slice A: atomic install + authority kernel (#822); "
|
||||
"disabled by default until readiness checks pass')"
|
||||
)
|
||||
|
||||
# -- introspection ---------------------------------------------------- #
|
||||
|
||||
def is_installed(self) -> bool:
|
||||
row = self._conn.execute("SELECT COUNT(*) FROM install_state").fetchone()
|
||||
return bool(row[0])
|
||||
|
||||
def active_grant_count(self) -> int:
|
||||
row = self._conn.execute(
|
||||
"SELECT active_count FROM platform_active_invariant WHERE id = 1"
|
||||
).fetchone()
|
||||
return int(row[0]) if row else 0
|
||||
|
||||
def audit_events(self) -> list[str]:
|
||||
return [
|
||||
r[0]
|
||||
for r in self._conn.execute(
|
||||
"SELECT event FROM audit_records ORDER BY audit_id"
|
||||
).fetchall()
|
||||
]
|
||||
|
||||
def close(self) -> None:
|
||||
self._conn.close()
|
||||
|
||||
# -- operations ------------------------------------------------------- #
|
||||
|
||||
def install_platform(
|
||||
self,
|
||||
installer_principal_id: str = "platform.installer",
|
||||
*,
|
||||
session: Optional[str] = None,
|
||||
) -> OperationResult:
|
||||
"""Single atomic install transaction (#822 §4/§7).
|
||||
|
||||
``BEGIN IMMEDIATE`` serializes concurrent installs; the loser rechecks
|
||||
the marker and returns ``ALREADY_INSTALLED``, or — if it never acquires
|
||||
the write lock — ``CONCURRENT_INSTALLATION_LOST``. On any stage failure
|
||||
the whole transaction rolls back leaving no partial rows (AC3/AC5).
|
||||
"""
|
||||
now = _utc_now_iso()
|
||||
with self._lock:
|
||||
try:
|
||||
self._conn.execute("BEGIN IMMEDIATE")
|
||||
except sqlite3.OperationalError as exc:
|
||||
if "locked" in str(exc).lower() or "busy" in str(exc).lower():
|
||||
return OperationResult(CONCURRENT_INSTALLATION_LOST, str(exc))
|
||||
raise
|
||||
try:
|
||||
if self.is_installed():
|
||||
self._conn.execute("ROLLBACK")
|
||||
return OperationResult(ALREADY_INSTALLED, "install marker already present")
|
||||
|
||||
with self.actor_context(installer_principal_id, "installer", "install", session):
|
||||
c = self._conn
|
||||
# class -> installer principal (temporary NULL issuer)
|
||||
cur = c.execute(
|
||||
"INSERT INTO principal_equivalence_classes(created_at) VALUES (?)",
|
||||
(now,),
|
||||
)
|
||||
class_id = cur.lastrowid
|
||||
c.execute(
|
||||
"INSERT INTO principals"
|
||||
"(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) "
|
||||
"VALUES (?, 'installer', ?, NULL, ?, ?)",
|
||||
(installer_principal_id, class_id, installer_principal_id, now),
|
||||
)
|
||||
# distinguished operator-key issuer
|
||||
cur = c.execute(
|
||||
"INSERT INTO authoritative_issuers(issuer_kind, issuer_ref, created_at) "
|
||||
"VALUES (?, ?, ?)",
|
||||
(DISTINGUISHED_ISSUER_KIND, DISTINGUISHED_ISSUER_ID, now),
|
||||
)
|
||||
issuer_id = cur.lastrowid
|
||||
# link installer -> issuer (permitted pre-marker)
|
||||
c.execute(
|
||||
"UPDATE principals SET issuer_id = ? WHERE principal_id = ?",
|
||||
(issuer_id, installer_principal_id),
|
||||
)
|
||||
# dominance tuples
|
||||
c.executemany(
|
||||
"INSERT INTO authority_dominance(dominant, subordinate) VALUES (?, ?)",
|
||||
DOMINANCE_TUPLES,
|
||||
)
|
||||
# seed
|
||||
c.execute(
|
||||
"INSERT INTO platform_bootstrap_seed(seed_id, installer_principal_id, created_at) "
|
||||
"VALUES (1, ?, ?)",
|
||||
(installer_principal_id, now),
|
||||
)
|
||||
# initial grant (granted_by NULL, active)
|
||||
c.execute(
|
||||
"INSERT INTO platform_bootstrap_grants"
|
||||
"(grantee_principal_id, granted_by, active, created_at) "
|
||||
"VALUES (?, NULL, 1, ?)",
|
||||
(installer_principal_id, now),
|
||||
)
|
||||
# active invariant
|
||||
c.execute(
|
||||
"INSERT INTO platform_active_invariant(id, active_count) VALUES (1, 1)"
|
||||
)
|
||||
# audit rows for the security-sensitive operation
|
||||
c.execute(
|
||||
"INSERT INTO audit_records(event, principal_id, detail, created_at) "
|
||||
"VALUES (?, ?, ?, ?)",
|
||||
(EVT_PRINCIPAL_REGISTERED, installer_principal_id, "installer", now),
|
||||
)
|
||||
c.execute(
|
||||
"INSERT INTO audit_records(event, principal_id, detail, created_at) "
|
||||
"VALUES (?, ?, ?, ?)",
|
||||
(EVT_GRANT_CREATED, installer_principal_id, "initial platform.bootstrap grant", now),
|
||||
)
|
||||
# install marker LAST -> fires the whole-bootstrap validator
|
||||
c.execute(
|
||||
"INSERT INTO install_state(id, marker, installed_at) VALUES (1, 'installed', ?)",
|
||||
(now,),
|
||||
)
|
||||
c.execute(
|
||||
"INSERT INTO audit_records(event, principal_id, detail, created_at) "
|
||||
"VALUES (?, ?, ?, ?)",
|
||||
(EVT_PLATFORM_INSTALLED, installer_principal_id, "platform installed", now),
|
||||
)
|
||||
self._conn.execute("COMMIT")
|
||||
return OperationResult(INSTALLED, "platform installed")
|
||||
except sqlite3.Error as exc:
|
||||
self._safe_rollback()
|
||||
return OperationResult(self._classify(exc), str(exc))
|
||||
|
||||
def register_principal(
|
||||
self,
|
||||
principal_id: str,
|
||||
actor_kind: str,
|
||||
issuer_ref: str,
|
||||
*,
|
||||
actor_principal: str,
|
||||
actor_kind_ctx: str = "operator",
|
||||
session: Optional[str] = None,
|
||||
) -> OperationResult:
|
||||
"""Atomically create an equivalence class and its first principal.
|
||||
|
||||
The class is inserted *before* the principal, and ``current_class_id``
|
||||
is ``NOT NULL`` (#822 AC6): a principal can never exist classless.
|
||||
The principal references an existing issuer (non-NULL); the temporary
|
||||
NULL-issuer exception is reserved for the installer during install
|
||||
(AC7).
|
||||
"""
|
||||
if actor_kind not in ACTOR_KINDS:
|
||||
return OperationResult(INVALID_BOOTSTRAP_STATE, f"bad actor_kind {actor_kind!r}")
|
||||
now = _utc_now_iso()
|
||||
with self._lock:
|
||||
try:
|
||||
self._conn.execute("BEGIN IMMEDIATE")
|
||||
except sqlite3.OperationalError as exc:
|
||||
return OperationResult(AUTHORIZATION_DENIED, str(exc))
|
||||
try:
|
||||
if not self.is_installed():
|
||||
self._conn.execute("ROLLBACK")
|
||||
return OperationResult(INVALID_BOOTSTRAP_STATE, "platform not installed")
|
||||
row = self._conn.execute(
|
||||
"SELECT issuer_id FROM authoritative_issuers WHERE issuer_ref = ?",
|
||||
(issuer_ref,),
|
||||
).fetchone()
|
||||
if row is None:
|
||||
self._conn.execute("ROLLBACK")
|
||||
return OperationResult(INVALID_BOOTSTRAP_STATE, f"unknown issuer {issuer_ref!r}")
|
||||
issuer_id = row[0]
|
||||
with self.actor_context(actor_principal, actor_kind_ctx, "normal", session):
|
||||
cur = self._conn.execute(
|
||||
"INSERT INTO principal_equivalence_classes(created_at) VALUES (?)",
|
||||
(now,),
|
||||
)
|
||||
class_id = cur.lastrowid
|
||||
self._conn.execute(
|
||||
"INSERT INTO principals"
|
||||
"(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) "
|
||||
"VALUES (?, ?, ?, ?, ?, ?)",
|
||||
(principal_id, actor_kind, class_id, issuer_id, actor_principal, now),
|
||||
)
|
||||
self._conn.execute(
|
||||
"INSERT INTO audit_records(event, principal_id, detail, created_at) "
|
||||
"VALUES (?, ?, ?, ?)",
|
||||
(EVT_PRINCIPAL_REGISTERED, principal_id, actor_kind, now),
|
||||
)
|
||||
self._conn.execute("COMMIT")
|
||||
return OperationResult(INSTALLED, f"registered {principal_id}")
|
||||
except sqlite3.Error as exc:
|
||||
self._safe_rollback()
|
||||
return OperationResult(self._classify(exc), str(exc))
|
||||
|
||||
def grant_platform_bootstrap(
|
||||
self,
|
||||
grantee_principal_id: str,
|
||||
granted_by: str,
|
||||
*,
|
||||
actor_kind_ctx: str = "operator",
|
||||
session: Optional[str] = None,
|
||||
) -> OperationResult:
|
||||
"""Create an additional active platform.bootstrap grant.
|
||||
|
||||
Serialized on the singleton invariant row via ``BEGIN IMMEDIATE``.
|
||||
"""
|
||||
now = _utc_now_iso()
|
||||
with self._lock:
|
||||
try:
|
||||
self._conn.execute("BEGIN IMMEDIATE")
|
||||
except sqlite3.OperationalError as exc:
|
||||
return OperationResult(AUTHORIZATION_DENIED, str(exc))
|
||||
try:
|
||||
if not self.is_installed():
|
||||
self._conn.execute("ROLLBACK")
|
||||
return OperationResult(INVALID_BOOTSTRAP_STATE, "platform not installed")
|
||||
with self.actor_context(granted_by, actor_kind_ctx, "normal", session):
|
||||
self._conn.execute(
|
||||
"INSERT INTO platform_bootstrap_grants"
|
||||
"(grantee_principal_id, granted_by, active, created_at) "
|
||||
"VALUES (?, ?, 1, ?)",
|
||||
(grantee_principal_id, granted_by, now),
|
||||
)
|
||||
self._conn.execute(
|
||||
"UPDATE platform_active_invariant SET active_count = active_count + 1 WHERE id = 1"
|
||||
)
|
||||
self._conn.execute(
|
||||
"INSERT INTO audit_records(event, principal_id, detail, created_at) "
|
||||
"VALUES (?, ?, ?, ?)",
|
||||
(EVT_GRANT_CREATED, grantee_principal_id, f"granted_by={granted_by}", now),
|
||||
)
|
||||
self._conn.execute("COMMIT")
|
||||
return OperationResult(INSTALLED, f"granted to {grantee_principal_id}")
|
||||
except sqlite3.Error as exc:
|
||||
self._safe_rollback()
|
||||
return OperationResult(self._classify(exc), str(exc))
|
||||
|
||||
def revoke_platform_bootstrap(
|
||||
self,
|
||||
grant_id: int,
|
||||
*,
|
||||
actor_principal: str,
|
||||
actor_kind_ctx: str = "operator",
|
||||
session: Optional[str] = None,
|
||||
) -> OperationResult:
|
||||
"""Revoke an active grant, floored so the last one can never drop.
|
||||
|
||||
The ``active_count >= 1`` CHECK plus ``BEGIN IMMEDIATE`` serialization
|
||||
make two concurrent revocations unable to remove the final active grant
|
||||
(#822 AC11): the decrement that would reach zero fails and rolls back.
|
||||
"""
|
||||
now = _utc_now_iso()
|
||||
with self._lock:
|
||||
try:
|
||||
self._conn.execute("BEGIN IMMEDIATE")
|
||||
except sqlite3.OperationalError as exc:
|
||||
return OperationResult(AUTHORIZATION_DENIED, str(exc))
|
||||
try:
|
||||
if not self.is_installed():
|
||||
self._conn.execute("ROLLBACK")
|
||||
return OperationResult(INVALID_BOOTSTRAP_STATE, "platform not installed")
|
||||
row = self._conn.execute(
|
||||
"SELECT active, grantee_principal_id FROM platform_bootstrap_grants WHERE grant_id = ?",
|
||||
(grant_id,),
|
||||
).fetchone()
|
||||
if row is None or row[0] != 1:
|
||||
self._conn.execute("ROLLBACK")
|
||||
return OperationResult(AUTHORIZATION_DENIED, "grant absent or already inactive")
|
||||
grantee = row[1]
|
||||
with self.actor_context(actor_principal, actor_kind_ctx, "normal", session):
|
||||
# Decrement first: the CHECK floor rejects dropping below 1,
|
||||
# aborting the whole revoke before the grant flips inactive.
|
||||
self._conn.execute(
|
||||
"UPDATE platform_active_invariant SET active_count = active_count - 1 WHERE id = 1"
|
||||
)
|
||||
self._conn.execute(
|
||||
"UPDATE platform_bootstrap_grants SET active = 0, revoked_at = ? WHERE grant_id = ?",
|
||||
(now, grant_id),
|
||||
)
|
||||
self._conn.execute(
|
||||
"INSERT INTO audit_records(event, principal_id, detail, created_at) "
|
||||
"VALUES (?, ?, ?, ?)",
|
||||
(EVT_GRANT_REVOKED, grantee, f"grant_id={grant_id}", now),
|
||||
)
|
||||
self._conn.execute("COMMIT")
|
||||
return OperationResult(INSTALLED, f"revoked grant {grant_id}")
|
||||
except sqlite3.Error as exc:
|
||||
self._safe_rollback()
|
||||
return OperationResult(self._classify(exc), str(exc))
|
||||
|
||||
# -- helpers ---------------------------------------------------------- #
|
||||
|
||||
def _safe_rollback(self) -> None:
|
||||
try:
|
||||
self._conn.execute("ROLLBACK")
|
||||
except sqlite3.Error:
|
||||
pass
|
||||
|
||||
@staticmethod
|
||||
def _classify(exc: sqlite3.Error) -> str:
|
||||
msg = str(exc)
|
||||
if "INVALID_ACTOR_CONTEXT" in msg:
|
||||
return INVALID_ACTOR_CONTEXT
|
||||
if "DOMINANCE_SET_MISMATCH" in msg:
|
||||
return DOMINANCE_SET_MISMATCH
|
||||
if "active_count" in msg or "CHECK constraint failed: platform_active_invariant" in msg:
|
||||
# last-active-grant floor tripped
|
||||
return AUTHORIZATION_DENIED
|
||||
if any(tag in msg for tag in (
|
||||
"INVALID_BOOTSTRAP_STATE", "IMMUTABLE_", "NOT_INSTALLED",
|
||||
)):
|
||||
return INVALID_BOOTSTRAP_STATE
|
||||
return INVALID_BOOTSTRAP_STATE
|
||||
Reference in New Issue
Block a user