ocmo-api 0.8.19__py3-none-any.whl

core/api/tree.py

@@ -0,0 +1,274 @@
+from ninja import Query, Router
+from ninja.pagination import paginate
+
+from ..managers.audit import AuditManager
+from ..managers.auth import AuthManager
+from ..managers.namespace import NamespaceManager
+from ..managers.tree import TreeManager
+from ..operation_ids import (
+    COPY_ITEM,
+    DELETE_ITEM,
+    DESCRIBE_ITEM,
+    DIFF_ITEM,
+    GET_ITEM,
+    LIST_ITEM_VERSIONS,
+    MOVE_ITEM,
+    NAVIGATE_PATH,
+    NAVIGATE_ROOT,
+    SEARCH_PATH,
+    SEARCH_ROOT,
+    SET_TAG,
+)
+from ..schemas import (
+    AnyExtendedNodeSchema,
+    AnyNodeSchema,
+    CopiedItemsSchema,
+    DeleteSchema,
+    DescribePayload,
+    DiffResponseSchema,
+    ErrorSchema,
+    ExtendedConfigSchema,
+    InfoSchema,
+    LocationPayload,
+    NavigationSchema,
+    TagPayload,
+    TreeNavigationNodeSchema,
+    VersionHistoryResponseSchema,
+)
+
+router = Router()
+
+
+@router.get(
+    "/ns/{namespace}/~navigate/",
+    response={200: NavigationSchema, 404: ErrorSchema},
+    tags=["Tree"],
+    operation_id=NAVIGATE_ROOT,
+)
+def navigate_root(
+    request,
+    namespace: str,
+    recursive: bool = False,
+    limit: int = Query(100, ge=1),
+    offset: int = Query(0, ge=0),
+):
+    """Navigate tree from root."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    return TreeManager(ns, "", auth=auth).navigate(recursive=recursive, limit=limit, offset=offset)
+
+
+@router.get(
+    "/ns/{namespace}/~navigate/{path:path}",
+    response={200: NavigationSchema, 404: ErrorSchema},
+    tags=["Tree"],
+    operation_id=NAVIGATE_PATH,
+)
+def navigate_path(
+    request,
+    namespace: str,
+    path: str,
+    recursive: bool = False,
+    limit: int = Query(100, ge=1),
+    offset: int = Query(0, ge=0),
+):
+    """Navigate tree at a specific path."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    return TreeManager(ns, path, auth=auth).navigate(recursive=recursive, limit=limit, offset=offset)
+
+
+@router.get(
+    "/ns/{namespace}/~search/",
+    response={200: list[TreeNavigationNodeSchema], 404: ErrorSchema},
+    tags=["Tree"],
+    operation_id=SEARCH_ROOT,
+)
+@paginate
+def search_root(request, namespace: str, q: str | None = None, types: list[str] = Query(None)):
+    """Search from namespace root."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    return TreeManager(ns, "", auth=auth).search(query=q, node_types=types)
+
+
+@router.get(
+    "/ns/{namespace}/~search/{path:path}",
+    response={200: list[TreeNavigationNodeSchema], 404: ErrorSchema},
+    tags=["Tree"],
+    operation_id=SEARCH_PATH,
+)
+@paginate
+def search_path(request, namespace: str, path: str, q: str | None = None, types: list[str] = Query(None)):
+    """Search within a subtree."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    return TreeManager(ns, path, auth=auth).search(query=q, node_types=types)
+
+
+@router.get(
+    "/ns/{namespace}/~versions/{path:path}",
+    response={200: VersionHistoryResponseSchema, 404: ErrorSchema, 422: ErrorSchema},
+    tags=["Tree"],
+    operation_id=LIST_ITEM_VERSIONS,
+)
+def list_item_versions(
+    request,
+    namespace: str,
+    path: str,
+    limit: int = Query(100, ge=1),
+    offset: int = Query(0, ge=0),
+    q: str | None = Query(None),
+    tagged_only: bool = Query(False),
+):
+    """List all versions (metadata) for a config, template, or secret."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    return TreeManager(ns, path, auth=auth).list_versions(
+        limit=limit,
+        offset=offset,
+        q=q,
+        tagged_only=tagged_only,
+    )
+
+
+@router.get(
+    "/ns/{namespace}/~get/{path:path}",
+    response={200: AnyExtendedNodeSchema, 404: ErrorSchema},
+    tags=["Tree"],
+    operation_id=GET_ITEM,
+)
+def get_item(
+    request,
+    namespace: str,
+    path: str,
+    version: str = Query("latest"),
+    reveal: bool = Query(False),
+):
+    """Get item details. For secrets, include ?reveal=true for decrypted content."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    return TreeManager(ns, path, auth=auth).get_extended(version=version, reveal=reveal)
+
+
+@router.get(
+    "/ns/{namespace}/~diff/{path:path}",
+    response={200: DiffResponseSchema, 404: ErrorSchema, 422: ErrorSchema},
+    tags=["Tree"],
+    operation_id=DIFF_ITEM,
+)
+def diff_item(
+    request,
+    namespace: str,
+    path: str,
+    from_ref: str = Query("latest", alias="from"),
+    to_ref: str = Query("latest", alias="to"),
+    to_path: str | None = Query(None),
+    reveal: bool = Query(False),
+):
+    """
+    Diff two versions of the same item (?from=, ?to=) or two items (?to_path=).
+
+    Returns both sides for client-side diff rendering. For secrets, use
+    ?reveal=true to include decrypted content; otherwise decryption_required is set.
+    """
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    return TreeManager(ns, path, auth=auth).diff_item(
+        from_ref=from_ref,
+        to_ref=to_ref,
+        to_path=to_path,
+        reveal=reveal,
+    )
+
+
+@router.delete(
+    "/ns/{namespace}/~delete/{path:path}",
+    response={200: DeleteSchema, 404: ErrorSchema},
+    tags=["Tree"],
+    operation_id=DELETE_ITEM,
+)
+def delete_item(
+    request,
+    namespace: str,
+    path: str,
+    preview: bool = Query(True),
+    version: str | None = Query(
+        None,
+        description="Soft-delete only this version (number or tag, e.g. 2 or stable)",
+    ),
+):
+    """Delete a tree item or a specific version. preview=true (default) is a dry run."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    return TreeManager(ns, path, auth=auth).delete_item(preview, version)
+
+
+@router.post(
+    "/ns/{namespace}/~move/{path:path}",
+    response={200: AnyNodeSchema, 404: ErrorSchema, 409: ErrorSchema},
+    tags=["Tree"],
+    operation_id=MOVE_ITEM,
+)
+def move_item(request, namespace: str, path: str, payload: LocationPayload):
+    """Move an item or folder subtree to a new path."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    return TreeManager(ns, path, auth=auth).move_item(payload.target_path)
+
+
+@router.post(
+    "/ns/{namespace}/~copy/{path:path}",
+    response={200: CopiedItemsSchema, 404: ErrorSchema, 409: ErrorSchema},
+    tags=["Tree"],
+    operation_id=COPY_ITEM,
+)
+def copy_item(
+    request,
+    namespace: str,
+    path: str,
+    payload: LocationPayload,
+    tag_to_copy: str = Query("latest"),
+):
+    """Copy an item or subtree. Only the version at tag_to_copy is copied."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    return TreeManager(ns, path, auth=auth).copy_item(payload.target_path.strip("/"), tag_to_copy)
+
+
+@router.post(
+    "/ns/{namespace}/~tag/{path:path}",
+    response={200: ExtendedConfigSchema, 204: InfoSchema, 404: ErrorSchema, 422: ErrorSchema},
+    tags=["Tree"],
+    operation_id=SET_TAG,
+)
+def set_tag(request, namespace: str, path: str, payload: TagPayload):
+    """Set or delete a tag on a Config, Template, or Secret."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    return TreeManager(ns, path, auth=auth).set_item_tag(payload)
+
+
+@router.post(
+    "/ns/{namespace}/~describe/{path:path}",
+    response={200: AnyNodeSchema, 404: ErrorSchema},
+    tags=["Tree"],
+    operation_id=DESCRIBE_ITEM,
+)
+def describe_item(request, namespace: str, path: str, payload: DescribePayload):
+    """Set the Markdown description of any tree item without creating a new version."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    return TreeManager(ns, path, auth=auth).set_description(payload.description)

core/apps.py

@@ -0,0 +1,18 @@
+import logging
+
+from django.apps import AppConfig
+
+logger = logging.getLogger(__name__)
+
+
+class CoreConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "core"
+
+    def ready(self) -> None:
+        from .notice import load_notice_text
+
+        try:
+            logger.info("OCMO product notice:\n%s", load_notice_text().rstrip())
+        except FileNotFoundError as exc:
+            logger.warning("%s", exc)

core/constants/__init__.py

@@ -0,0 +1,5 @@
+from .permissions import PROBE_OPERATIONS
+from .resolve import OMIT
+from .transformers import KNOWN_TRANSFORMERS, ParameterTransformer
+
+__all__ = ["KNOWN_TRANSFORMERS", "OMIT", "ParameterTransformer", "PROBE_OPERATIONS"]

core/constants/audit_operations.py

@@ -0,0 +1,35 @@
+"""Canonical user-friendly audit operation labels stored on ``AuditEvent.operation``."""
+
+OP_RESOLVE = "Resolve"
+OP_REFERENCED_IN_RESOLVE = "Referenced in resolve"
+OP_UPDATE_ITEM = "Update item"
+OP_CREATE_ITEM = "Create item"
+OP_DELETE_ITEM = "Delete item"
+OP_SET_TAG = "Set tag"
+OP_DELETE_TAG = "Delete tag"
+OP_DIFF_ITEM = "Diff item"
+OP_LIST_VERSIONS = "List versions"
+OP_NAVIGATE = "Navigate"
+OP_SEARCH = "Search"
+OP_READ_LOCK = "Read lock"
+OP_CREATE_LOCK = "Create lock"
+OP_UPDATE_LOCK = "Update lock"
+OP_DELETE_LOCK = "Delete lock"
+OP_LIST_LOCKS = "List locks"
+OP_PROPAGATE_CONFIG = "Propagate config"
+OP_ROTATE_TOKEN = "Rotate token"
+OP_DOWNLOAD_ARTIFACT = "Download artifact"
+OP_UPDATE_DESCRIPTION = "Update description"
+OP_PROMOTE_STABLE_TAG = "Promote stable tag"
+OP_COPY_ITEM = "Copy item"
+OP_MOVE_ITEM = "Move item"
+OP_READ_NAMESPACE = "Read namespace"
+OP_CREATE_NAMESPACE = "Create namespace"
+OP_UPDATE_NAMESPACE = "Update namespace"
+OP_DELETE_NAMESPACE = "Delete namespace"
+OP_LIST_PERMISSIONS = "List permissions"
+OP_READ_PERMISSION = "Read permission"
+OP_CREATE_PERMISSION = "Create permission"
+OP_UPDATE_PERMISSION = "Update permission"
+OP_DELETE_PERMISSION = "Delete permission"
+OP_MOVE_PERMISSION = "Move permission"

core/constants/permission_actions.py

@@ -0,0 +1,59 @@
+"""Permission policy action strings accepted in ``_permissions`` configs."""
+
+from __future__ import annotations
+
+PERMISSION_ACTION_RESOURCES = ("config", "template", "resolver", "secret", "lock", "folder", "*")
+PERMISSION_ACTION_VERBS = ("read", "write", "delete", "resolve", "tag", "describe", "audit", "*")
+
+# Concrete ``<resource>:<verb>`` pairs enforced by namespace ABAC (tree managers / can-i probes).
+PERMISSION_CONCRETE_ACTIONS: tuple[str, ...] = (
+    "config:read",
+    "config:write",
+    "config:delete",
+    "config:resolve",
+    "config:tag",
+    "config:describe",
+    "config:audit",
+    "template:read",
+    "template:write",
+    "template:delete",
+    "template:tag",
+    "template:describe",
+    "template:audit",
+    "resolver:read",
+    "resolver:write",
+    "resolver:delete",
+    "resolver:audit",
+    "secret:read",
+    "secret:write",
+    "secret:delete",
+    "secret:resolve",
+    "secret:tag",
+    "secret:describe",
+    "secret:audit",
+    "lock:read",
+    "lock:write",
+    "lock:delete",
+    "folder:describe",
+    "folder:audit",
+)
+
+PERMISSION_RESOURCE_WILDCARD_ACTIONS: tuple[str, ...] = tuple(
+    f"{resource}:*" for resource in ("config", "template", "resolver", "secret", "lock")
+)
+
+PERMISSION_VERB_WILDCARD_ACTIONS: tuple[str, ...] = tuple(
+    f"*:{verb}" for verb in ("read", "write", "delete", "resolve", "tag", "describe", "audit")
+)
+
+PERMISSION_ACTIONS: tuple[str, ...] = (
+    *PERMISSION_CONCRETE_ACTIONS,
+    *PERMISSION_RESOURCE_WILDCARD_ACTIONS,
+    *PERMISSION_VERB_WILDCARD_ACTIONS,
+    "*:*",
+)
+
+PERMISSION_ACTION_PATTERN = (
+    r"^(config|template|resolver|secret|lock|folder|\*):"
+    r"(read|write|delete|resolve|tag|describe|audit|\*)$"
+)

core/constants/permissions.py

@@ -0,0 +1,41 @@
+"""Operations accepted by POST /auth/can-i/ (concrete API checks, no wildcards)."""
+
+PROBE_OPERATIONS = frozenset(
+    {
+        "global:admin",
+        "namespace:read",
+        "namespace:write",
+        "namespace:delete",
+        "namespace:audit",
+        "namespace:create",
+        "config:read",
+        "config:write",
+        "config:delete",
+        "config:resolve",
+        "config:tag",
+        "config:describe",
+        "config:audit",
+        "template:read",
+        "template:write",
+        "template:delete",
+        "template:tag",
+        "template:describe",
+        "template:audit",
+        "resolver:read",
+        "resolver:write",
+        "resolver:delete",
+        "resolver:audit",
+        "secret:read",
+        "secret:resolve",
+        "secret:write",
+        "secret:delete",
+        "secret:tag",
+        "secret:describe",
+        "secret:audit",
+        "lock:read",
+        "lock:write",
+        "lock:delete",
+        "folder:describe",
+        "folder:audit",
+    }
+)

core/constants/resolve.py

@@ -0,0 +1,3 @@
+"""Resolve pipeline sentinels shared across managers and utils."""
+
+OMIT = object()

core/constants/transformers.py

@@ -0,0 +1,22 @@
+"""Allowed parameter transformer names (validation only; runtime registry in resolve_parameters)."""
+
+from typing import Literal, get_args
+
+ParameterTransformer = Literal[
+    "lower",
+    "upper",
+    "slug",
+    "snake",
+    "trim",
+    "escape_html",
+    "b64_encode",
+    "urlencode",
+    "int",
+    "float",
+    "bool",
+    "null",
+    "multiline",
+    "omit",
+]
+
+KNOWN_TRANSFORMERS = frozenset(get_args(ParameterTransformer))

core/constants/webhook_events.py

@@ -0,0 +1,31 @@
+"""Webhook event names emitted by the API."""
+
+from __future__ import annotations
+
+WEBHOOK_EVENTS: tuple[str, ...] = (
+    "config.created",
+    "config.updated",
+    "config.deleted",
+    "config.tagged",
+    "config.resolved",
+    "resolver.created",
+    "resolver.updated",
+    "secret.created",
+    "secret.updated",
+    "secret.deleted",
+    "secret.tagged",
+    "secret.resolved",
+    "namespace.updated",
+    "lock.created",
+    "lock.updated",
+    "lock.deleted",
+    "propagation.triggered",
+)
+
+WEBHOOK_PAYLOAD_PRESETS: tuple[str, ...] = (
+    "ocmo",
+    "generic_json",
+    "slack",
+    "teams",
+    "discord",
+)

core/data/builtin_schemas/_git_sync.schema.yaml

@@ -0,0 +1,24 @@
+_ocmo:
+  is_json_schema: true
+$schema: https://json-schema.org/draft/2020-12/schema
+type: object
+additionalProperties: false
+required:
+  - enabled
+properties:
+  enabled:
+    type: boolean
+  repository_url:
+    type: string
+  ssh_private_key:
+    type: string
+  git_username:
+    type: string
+  git_password:
+    type: string
+  branch:
+    type: string
+  path_prefix:
+    type: string
+  commit_versions:
+    type: boolean