shakun-kernel 0.1.0__py3-none-any.whl

shakun_kernel/__init__.py

@@ -0,0 +1,26 @@
+"""
+Shakun — a trust and identity kernel for AI agents.
+
+This module is the public surface. Everything a developer needs to stand
+up a kernel, obtain a caller, register identities, and delegate authority
+between them is exported here. Reaching into kernel internals or test
+helpers should never be necessary for ordinary use; if it is, that is a
+gap in this surface, not the intended path.
+"""
+
+from shakun_kernel.factory import create_shakun
+from shakun_kernel.kernel.caller import CallerContext
+from shakun_kernel.kernel.identity_keys import generate_identity_keypair
+from shakun_kernel.kernel.delegation import create_delegation
+from shakun_kernel.kernel.authorization import AuthorizationContext
+from shakun_kernel.kernel.revocation_store import InMemoryRevocationStore, RevocationRecord
+
+__all__ = [
+    "create_shakun",
+    "CallerContext",
+    "generate_identity_keypair",
+    "create_delegation",
+    "AuthorizationContext",
+    "InMemoryRevocationStore",
+    "RevocationRecord",
+]

shakun_kernel/daemon/__init__.py

@@ -0,0 +1,3 @@
+# Shakun daemon package. Intentionally empty: importing the package must
+# not eagerly import submodules, or any submodule that imports back into
+# the package creates a circular import. The CLI lives in __main__.py.

shakun_kernel/daemon/__main__.py

@@ -0,0 +1,42 @@
+import argparse
+import logging
+
+from shakun_kernel.daemon.server import run_daemon
+
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="python -m shakun_kernel.daemon",
+        description="Shakun development daemon (local-only, no authentication).",
+    )
+    parser.add_argument("--key-path", required=True,
+                        help="path to the daemon's encrypted identity key")
+    parser.add_argument("--passphrase", required=True,
+                        help="passphrase for the identity key")
+    parser.add_argument("--db", required=True, dest="sqlite_path",
+                        help="path to the kernel's sqlite event store")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8000)
+    parser.add_argument("--allow-insecure-bind", action="store_true",
+                        help="permit binding an unauthenticated daemon to a "
+                             "non-loopback interface")
+    parser.add_argument("--dev-no-auth", action="store_true",
+                        help="run WITHOUT request authentication (local dev "
+                             "only; forces loopback unless --allow-insecure-bind)")
+    args = parser.parse_args()
+
+    logging.basicConfig(level=logging.INFO)
+
+    run_daemon(
+        key_path=args.key_path,
+        passphrase=args.passphrase,
+        sqlite_path=args.sqlite_path,
+        host=args.host,
+        port=args.port,
+        authenticated=not args.dev_no_auth,
+        allow_insecure_bind=args.allow_insecure_bind,
+    )
+
+if __name__ == "__main__":
+    main()

shakun_kernel/daemon/caller_resolver.py

@@ -0,0 +1,67 @@
+from shakun_kernel.kernel.caller import CallerContext
+
+
+class CallerResolver:
+    """
+    Turns an incoming transport request into a CallerContext, or
+    refuses. This is the single place authentication happens — the
+    concrete component behind "the transport authenticates, the kernel
+    authorizes."
+
+        Transport → CallerResolver → CallerContext → Kernel
+
+    Every resolver must honour the CallerContext Trust Boundary: it may
+    only construct a CallerContext for an identity it has actually
+    verified. Constructing one from unverified request data defeats the
+    kernel's authorization model, and the kernel cannot detect that it
+    happened.
+
+    Subclasses implement resolve(). The `request` argument is the
+    transport's own native request object, passed through opaquely: the
+    resolver is free to interpret it however it needs (read headers, a
+    signature, the raw body), and is the ONLY component permitted to.
+    Below the transport boundary the request does not exist — the
+    dispatcher and kernel see only the CallerContext that comes out,
+    never the request that produced it. That is what lets the same
+    dispatcher and kernel sit behind HTTP, a signature-verifying
+    resolver, or a future network resolver without changing.
+    """
+    def resolve(self, request) -> CallerContext:
+        raise NotImplementedError
+
+
+class LocalCallerResolver(CallerResolver):
+    """
+    Development only. Resolves EVERY request to one configured local
+    identity, performing no authentication whatsoever.
+
+    This exists to exercise the request pipeline before the real trust
+    boundary (SignatureCallerResolver, CRITICAL 1) is built. It
+    performs no authentication, so a deployment using it is responsible
+    for ensuring it is never exposed to untrusted clients. That is an
+    operational guarantee the deployment must make — this class cannot
+    enforce it, since a resolver has no visibility into how or where
+    the server binds. It is never a production component.
+
+    The configured identity is normally the kernel's own genesis
+    identity — the one identity guaranteed to exist and to hold
+    registration authority — so a local developer can drive every
+    syscall without first standing up a second identity.
+    """
+
+    def __init__(self, identity_id):
+        if not isinstance(identity_id, str) or not identity_id.strip():
+            raise ValueError("LocalCallerResolver requires a non-blank identity_id")
+        self._identity_id = identity_id
+
+    def resolve(self, request):
+        # No authentication. The request is ignored for identity — every
+        # caller is the one configured local identity. The operation is
+        # read from the adapter unauthenticated, which is the entire
+        # nature of this dev resolver: it asserts nothing it verified.
+        from shakun_kernel.daemon.signature_resolver import AuthenticatedInvocation
+        fields = request.auth_fields()
+        return AuthenticatedInvocation(
+            caller=CallerContext(identity_id=self._identity_id),
+            operation=fields.get("operation"),
+        )

shakun_kernel/daemon/delegation_wire.py

@@ -0,0 +1,61 @@
+from shakun_kernel.kernel.schemas import DelegationRecord
+
+
+# The wire form of a DelegationRecord: a flat JSON object with exactly
+# these keys. This mapping IS the protocol — a client in any language
+# produces this shape — so it is declared explicitly here rather than
+# derived from the dataclass by introspection, and every field is
+# covered by a round-trip test. If DelegationRecord gains a field, this
+# fails loudly (missing key) rather than silently dropping it.
+_DELEGATION_FIELDS = (
+    "version",
+    "delegation_id",
+    "delegator_identity_id",
+    "delegate_identity_id",
+    "issuer_identity_id",
+    "scope_id",
+    "mission_id",
+    "issued_at",
+    "expires_at",
+    "revocation_reference",
+    "signature",
+)
+
+# Membership set for validation — the tuple gives deterministic
+# reconstruction order, this gives O(1) presence/absence checks without
+# rebuilding a list on every call.
+_DELEGATION_FIELD_SET = frozenset(_DELEGATION_FIELDS)
+
+
+def delegation_to_dict(record: DelegationRecord) -> dict:
+    """Serialize a DelegationRecord to its wire form. Explicit per-field
+    so the wire shape is a deliberate contract, not an accident of
+    dataclass layout."""
+    return {field: getattr(record, field) for field in _DELEGATION_FIELDS}
+
+
+def delegation_from_dict(data: dict) -> DelegationRecord:
+    """
+    Reconstruct a DelegationRecord from its wire form.
+
+    Every field must be present. A missing field is a malformed
+    delegation and raises — we never silently default one, because a
+    defaulted field would change the bytes verify_delegation checks and
+    produce a confusing 'invalid signature' far from the real cause
+    (a truncated delegation). optional-VALUED fields (mission_id,
+    revocation_reference) may be null, but the KEY must exist.
+    """
+    if not isinstance(data, dict):
+        raise ValueError("delegation must be a JSON object")
+    keys = set(data)
+    missing = _DELEGATION_FIELD_SET - keys
+    if missing:
+        raise ValueError(f"delegation is missing required field(s): {sorted(missing)}")
+    extra = keys - _DELEGATION_FIELD_SET
+    if extra:
+        # Strict protocol boundary: unknown fields are rejected, not
+        # ignored. Catches client typos (e.g. delegate_identity vs
+        # delegate_identity_id) immediately, at the boundary, rather than
+        # as a downstream signature mismatch.
+        raise ValueError(f"delegation contains unknown field(s): {sorted(extra)}")
+    return DelegationRecord(**{field: data[field] for field in _DELEGATION_FIELDS})

shakun_kernel/daemon/dispatcher.py

@@ -0,0 +1,213 @@
+from shakun_kernel.kernel.caller import CallerContext
+
+# NOTE (future): as transport-level validation grows, these one-off
+# dispatcher exceptions want to become a small hierarchy (a DispatcherError
+# base with MalformedDelegation / DelegationUnavailable / ... subclasses),
+# so dispatch() catches the base once and maps code/type off the exception
+# instead of accumulating except-clauses. Deferred until a third such
+# exception makes the shared shape clear — building it with two members
+# would be structure ahead of the load that justifies it.
+class _DelegationUnavailable(Exception):
+    """A delegated request reached a daemon with no revocation store.
+    Fails closed — see _auth_context."""
+
+class SyscallDispatcher:
+    """
+    Turns a resolved caller and a parsed request body into exactly one
+    kernel syscall, and returns the kernel's structured response
+    unchanged.
+
+        Transport → CallerResolver → CallerContext ─┐
+                                                     ├→ Dispatcher → Kernel
+                    parsed request body ─────────────┘
+
+    This is the one place that knows the mapping from a named operation
+    to a kernel syscall and the shape of each operation's arguments.
+    It performs NO authentication (that already happened in the
+    resolver) and NO authorization (that happens inside the kernel).
+    Its whole job is: pick the syscall, pull named fields out of the
+    body, thread the caller through, hand back what the kernel returns.
+
+    It never calls a non-syscall_ kernel method. The syscall_ layer is
+    the boundary — see the Trust Boundary Law — and the dispatcher
+    stays on the outside of it.
+
+    A request that names an unknown operation, or omits a field a
+    syscall requires, is a client error and comes back as a structured
+    error dict, never an exception through the transport.
+    """
+
+    def __init__(self, kernel, revocation_store=None):
+        self._kernel = kernel
+        # The daemon's durable revocation store, used to build an
+        # AuthorizationContext for delegated requests. Optional: a daemon
+        # with no delegated operations (or the dev/local path) can run
+        # without one, in which case a request carrying a delegation is
+        # refused rather than silently unverified against revocation.
+        self._revocation_store = revocation_store
+        self._operations = {
+            "create_scope": self._create_scope,
+            "create_mission": self._create_mission,
+            "start_mission": self._start_mission,
+            "record_observation": self._record_observation,
+            "close_mission": self._close_mission,
+            "get_mission_state": self._get_mission_state,
+            "record_retrieval_event": self._record_retrieval_event,
+            "commit_memory": self._commit_memory,
+        }
+
+    def dispatch(self, operation, body, caller: CallerContext):
+        handler = self._operations.get(operation)
+        if handler is None:
+            return {
+                "status": "error",
+                "error": {
+                    "type": "UnknownOperation",
+                    "code": "dispatch.unknown_operation",
+                    "reason": f"no such operation: {operation}",
+                },
+            }
+        try:
+            return handler(body, caller)
+        except _DelegationUnavailable as e:
+            return {
+                "status": "error",
+                "error": {
+                    "type": "DelegationUnavailable",
+                    "code": "dispatch.delegation_unavailable",
+                    "reason": str(e),
+                },
+            }
+        except ValueError as e:
+            # Malformed delegation (bad wire shape, missing/unknown field).
+            # A client error, surfaced clearly rather than as a 500.
+            return {
+                "status": "error",
+                "error": {
+                    "type": "MalformedDelegation",
+                    "code": "dispatch.malformed_delegation",
+                    "reason": str(e),
+                },
+            }
+        except KeyError as missing:
+            # ONLY transport-level errors are caught here. Kernel errors
+            # (authorization, invariants, domain rules) are returned by
+            # _run_syscall as structured dicts, not raised — they pass
+            # through untouched. Do not add a broad except: it would
+            # create a second error vocabulary competing with the
+            # kernel's own.
+            return {
+                "status": "error",
+                "error": {
+                    "type": "MissingField",
+                    "code": "dispatch.missing_field",
+                    "reason": f"request is missing required field: {missing.args[0]}",
+                },
+            }
+
+    def _auth_context(self, body):
+        """
+        Assembles an AuthorizationContext from a request body, if the body
+        carries a delegation. Returns None for a direct-authority request
+        (no delegation field) — the kernel treats auth_context=None as
+        "direct authority only", exactly as for an in-process direct call.
+
+        This is the single place body-delegation becomes an
+        AuthorizationContext. delegation_wire only reconstructs the
+        DelegationRecord; this method is the one that knows about the
+        revocation store. The kernel still consumes only AuthorizationContext.
+        """
+        from shakun_kernel.daemon.delegation_wire import delegation_from_dict
+        from shakun_kernel.kernel.authorization import AuthorizationContext
+
+        raw = body.get("delegation")
+        if raw is None:
+            return None
+
+        if self._revocation_store is None:
+            # A delegation was presented but this daemon has no revocation
+            # store to check it against. Refuse rather than verify a
+            # delegation we couldn't confirm is unrevoked — failing closed
+            # is the only safe choice for an authority grant.
+            raise _DelegationUnavailable(
+                "this daemon is not configured to accept delegated requests"
+            )
+
+        delegation = delegation_from_dict(raw)
+        return AuthorizationContext(
+            delegation_record=delegation,
+            revocation_store=self._revocation_store,
+        )
+    
+    # ── operation handlers ──────────────────────────────────────────────
+    # Each pulls the fields its syscall needs out of `body` and threads
+    # the caller through. A missing required field raises KeyError, which
+    # dispatch() turns into a clean dispatch.missing_field error.
+
+    def _create_scope(self, body, caller):
+        return self._kernel.syscall_create_scope(
+            body["scope_id"],
+            caller=caller,
+            parent_scope_id=body.get("parent_scope_id"),
+        )
+
+    def _create_mission(self, body, caller):
+        return self._kernel.syscall_create_mission(
+            body["goal_spec"],
+            scope_id=body["scope_id"],
+            caller=caller,
+            auth_context=self._auth_context(body),
+        )
+
+    def _start_mission(self, body, caller):
+        return self._kernel.syscall_start_mission(
+            body["mission_id"],
+            caller=caller,
+            auth_context=self._auth_context(body),
+        )
+
+    def _record_observation(self, body, caller):
+        return self._kernel.syscall_record_observation(
+            body["observation"],
+            scope_id=body["scope_id"],
+            mission_id=body.get("mission_id"),
+            caller=caller,
+            auth_context=self._auth_context(body),
+        )
+
+    def _close_mission(self, body, caller):
+        return self._kernel.syscall_close_mission(
+            body["mission_id"],
+            evidence_event_ids=body.get("evidence_event_ids"),
+            caller=caller,
+            auth_context=self._auth_context(body),
+        )
+
+    def _get_mission_state(self, body, caller):
+        return self._kernel.syscall_get_mission_state(
+            body["mission_id"],
+            caller=caller,
+        )
+
+    def _record_retrieval_event(self, body, caller):
+        return self._kernel.syscall_record_retrieval_event(
+            source_id=body["source_id"],
+            source_type=body["source_type"],
+            query=body["query"],
+            scope_id=body["scope_id"],
+            mission_id=body.get("mission_id"),
+            caller=caller,
+            auth_context=self._auth_context(body),
+        )
+
+    def _commit_memory(self, body, caller):
+        from shakun_kernel.kernel.kernel import MemoryType
+        return self._kernel.syscall_commit_memory(
+            memory_type=MemoryType(body["memory_type"]),
+            scope_id=body["scope_id"],
+            provenance=body["provenance"],
+            content=body["content"],
+            schema_version=body.get("schema_version", 1),
+            caller=caller,
+            auth_context=self._auth_context(body),
+        )

shakun_kernel/daemon/nonce_store.py

@@ -0,0 +1,133 @@
+import sqlite3
+from datetime import timedelta
+
+from shakun_kernel.kernel.clock import parse_iso_timestamp
+
+
+class NonceStore:
+    """
+    Replay-prevention state: has this (identity, nonce) been seen before?
+
+    Same abstraction family as EventStore, RevocationStore, and the
+    keystores — the resolver depends on this interface, and durability is
+    a property of the chosen backend, not of the authentication protocol.
+
+    Nonces are scoped per identity: two different identities may
+    legitimately use the same nonce string, and one identity's nonces are
+    never another's concern.
+    """
+
+    def seen(self, identity_id, nonce) -> bool:
+        raise NotImplementedError
+
+    def record(self, identity_id, nonce, timestamp) -> None:
+        raise NotImplementedError
+
+
+class InMemoryNonceStore(NonceStore):
+    """
+    Development / single-process store. Holds seen (identity, nonce)
+    pairs in memory.
+
+    LIMITATION, by design: this forgets every nonce on restart. Within
+    the SignedInvocation timestamp-skew window, a captured request could
+    therefore be replayed once across a restart. That is a property of
+    THIS backend, not of the protocol — a durable NonceStore
+    (SQLite/Redis/etc.) closes it without any change to the resolver.
+    Same category of deferred-durability as revocation persistence.
+
+    `timestamp` is recorded so a future implementation can prune entries
+    older than the skew window; this in-memory version keeps them for the
+    process lifetime, which is correct (never under-rejects) if wasteful.
+    """
+
+    def __init__(self):
+        self._seen = set()
+
+    def seen(self, identity_id, nonce) -> bool:
+        return (identity_id, nonce) in self._seen
+
+    def record(self, identity_id, nonce, timestamp) -> None:
+        self._seen.add((identity_id, nonce))
+
+
+class SQLiteNonceStore(NonceStore):
+    """
+    A durable NonceStore backed by SQLite. Same contract as
+    InMemoryNonceStore — has this (identity, nonce) been seen — but
+    survives restart, closing the cross-restart replay window that the
+    in-memory store leaves open (audit follow-up to HIGH 7).
+
+    Self-pruning: a nonce only needs to be remembered as long as a
+    request bearing it could still be ACCEPTED, which is the resolver's
+    timestamp-skew window. Past that, the resolver rejects the request as
+    stale regardless of the nonce check, so keeping the nonce is
+    pointless. Each record() therefore deletes entries older than
+    retention_seconds. This keeps an otherwise unbounded table bounded,
+    with no background worker or startup scan — cleanup happens naturally
+    as the daemon serves requests.
+
+    CRITICAL COUPLING: retention_seconds MUST be >= the resolver's
+    max_skew_seconds. If retention were shorter, a nonce could be pruned
+    while a request bearing it is still within the acceptance window —
+    silently reopening the exact replay hole this store exists to close.
+    The daemon must derive both values from one shared constant; see
+    build_daemon. This store validates only that retention is positive;
+    it cannot see the resolver's skew, so the >= relationship is the
+    daemon's responsibility to guarantee.
+    """
+
+    def __init__(self, db_path, *, retention_seconds=60):
+        if not isinstance(retention_seconds, (int, float)) or retention_seconds <= 0:
+            raise ValueError("retention_seconds must be a positive number")
+        self._db_path = db_path
+        self._retention = timedelta(seconds=retention_seconds)
+        self._conn = sqlite3.connect(db_path, check_same_thread=False)
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.execute("""
+            CREATE TABLE IF NOT EXISTS nonces (
+                identity_id TEXT NOT NULL,
+                nonce       TEXT NOT NULL,
+                timestamp   TEXT NOT NULL,
+                PRIMARY KEY (identity_id, nonce)
+            )
+        """)
+        # Index for the prune range query — without it, pruning becomes a
+        # full table scan that worsens exactly as the table grows.
+        self._conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_nonce_timestamp ON nonces(timestamp)"
+        )
+        self._conn.commit()
+
+    def seen(self, identity_id, nonce) -> bool:
+        row = self._conn.execute(
+            "SELECT 1 FROM nonces WHERE identity_id = ? AND nonce = ?",
+            (identity_id, nonce),
+        ).fetchone()
+        return row is not None
+
+    def record(self, identity_id, nonce, timestamp) -> None:
+        # Prune first: drop everything older than the retention window,
+        # computed from the newly-recorded request's own timestamp so the
+        # store needs no external clock. The cutoff is produced as an ISO
+        # string the same way stored timestamps are, so the string
+        # comparison below matches chronological order.
+        cutoff = (parse_iso_timestamp(timestamp) - self._retention).isoformat()
+        self._conn.execute("DELETE FROM nonces WHERE timestamp < ?", (cutoff,))
+
+        # INSERT OR IGNORE: recording the same (identity, nonce) twice is a
+        # no-op. The resolver only ever records a nonce it has already
+        # confirmed unseen, so a collision here would mean a genuine replay
+        # that the resolver's seen() check should have caught — ignoring is
+        # safe and the seen() check is the real guard.
+        self._conn.execute(
+            "INSERT OR IGNORE INTO nonces (identity_id, nonce, timestamp) "
+            "VALUES (?, ?, ?)",
+            (identity_id, nonce, timestamp),
+        )
+        self._conn.commit()
+
+    def close(self):
+        """Closes the connection explicitly — deterministic lifecycle for
+        the daemon at shutdown and for tests before reopen/delete."""
+        self._conn.close()