ocmo-api 0.8.19__py3-none-any.whl

core/data/builtin_schemas/_permissions.schema.yaml

@@ -0,0 +1,211 @@
+_ocmo:
+  is_json_schema: true
+$schema: https://json-schema.org/draft/2020-12/schema
+title: Namespace permissions policy document
+description: ABAC policies evaluated on every namespace operation. Policies are matched top-to-bottom;
+  explicit Deny wins over Allow.
+type: object
+additionalProperties: false
+required:
+- policies
+properties:
+  policies:
+    type: array
+    description: Ordered list of allow/deny policies.
+    items:
+      type: object
+      additionalProperties: false
+      required:
+      - effect
+      - actors
+      - actions
+      - resources
+      properties:
+        id:
+          type: string
+          minLength: 1
+          maxLength: 200
+          description: Optional stable identifier for audits and documentation.
+          examples:
+          - allow-dev-readers
+        description:
+          type: string
+          maxLength: 500
+          description: Human-readable summary of what this policy grants or denies.
+          examples:
+          - Allow developers read access to project/dev/**
+        effect:
+          type: string
+          enum:
+          - Allow
+          - Deny
+          description: Whether matching requests are allowed or denied.
+          examples:
+          - Allow
+        actors:
+          type: array
+          minItems: 1
+          description: Who the policy applies to. User actors match OIDC claims; Resolver actors match
+            resolver identities by tree path.
+          items:
+            oneOf:
+            - type: object
+              additionalProperties: false
+              required:
+              - kind
+              - claims
+              properties:
+                kind:
+                  const: User
+                  description: Match authenticated human users.
+                claims:
+                  type: object
+                  minProperties: 1
+                  description: OIDC claim names mapped to literal values or ``*``. Use ``{!user.<claim>}``
+                    only in resource globs, not here.
+                  additionalProperties:
+                    type: string
+                    minLength: 1
+                    pattern: ^(\*|\{!user\.[a-zA-Z0-9_]+\}|(?!.*\{!).+)$
+                    description: Claim value, wildcard ``*``, or interpolation placeholder.
+                    examples:
+                    - alice@example.com
+                    - '*'
+                  examples:
+                  - email: alice@example.com
+            - type: object
+              additionalProperties: false
+              required:
+              - kind
+              - path
+              properties:
+                kind:
+                  const: Resolver
+                  description: Match a resolver identity by its tree path.
+                path:
+                  type: string
+                  minLength: 1
+                  maxLength: 512
+                  format: uri-reference
+                  x-ocmo-uri-reference: resolver
+                  description: Resolver tree path. Use ``*`` to match any resolver. Relative paths resolve
+                    from the ``_permissions`` folder.
+                  examples:
+                  - deploy/prod
+                  - '*'
+        actions:
+          type: array
+          minItems: 1
+          description: Permission operations this policy governs. Use ``resource:verb`` pairs; ``*`` wildcards
+            match any resource or verb.
+          items:
+            type: string
+            pattern: ^(config|template|resolver|secret|lock|folder|\*):(read|write|delete|resolve|tag|describe|audit|\*)$
+            enum:
+            - 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
+            - config:*
+            - template:*
+            - resolver:*
+            - secret:*
+            - lock:*
+            - '*:read'
+            - '*:write'
+            - '*:delete'
+            - '*:resolve'
+            - '*:tag'
+            - '*:describe'
+            - '*:audit'
+            - '*:*'
+            description: Concrete ``<resource>:<verb>`` pair or glob such as ``config:*``, ``*:read``,
+              or ``*:*``.
+            examples:
+            - config:read
+            - config:*
+            - '*:read'
+            - '*:*'
+          examples:
+          - - config:read
+            - config:describe
+        resources:
+          type: array
+          minItems: 1
+          description: Resource path globs the policy applies to. Supports ``*`` and ``**`` fnmatch patterns
+            and ``{!user.claim}`` interpolation.
+          items:
+            type: string
+            minLength: 1
+            maxLength: 512
+            format: uri-reference
+            x-ocmo-uri-reference: resource
+            description: Tree path or glob (e.g. ``project/dev/**``, ``secrets/**``). Folder paths may
+              end with ``/**`` to match all descendants under the folder.
+            examples:
+            - project/dev/**
+            - app/prod/**
+            - '**'
+          examples:
+          - - project/dev/**
+        conditions:
+          type: object
+          additionalProperties: false
+          description: Optional constraints that must all match for the policy to apply.
+          properties:
+            ip_range:
+              type: array
+              minItems: 1
+              description: Client IP ranges (IPv4/IPv6 CIDR). Denied when IP is unknown.
+              items:
+                type: string
+                pattern: ^(?:(?:\d{1,3}\.){3}\d{1,3}(?:\/(?:\d|[1-2]\d|3[0-2]))?|[0-9a-fA-F:]+(?:\/\d{1,3})?)$
+                description: IPv4 or IPv6 network in CIDR notation.
+                examples:
+                - 10.0.0.0/8
+                - 2001:db8::/32
+            time_of_day:
+              type: array
+              minItems: 1
+              description: UTC time windows when the policy is active (half-open intervals).
+              items:
+                type: string
+                pattern: ^(?:[01]\d|2[0-3]):[0-5]\d-(?:[01]\d|2[0-3]):[0-5]\d$
+                description: UTC time range ``HH:MM-HH:MM``.
+                examples:
+                - 09:00-17:30
+    examples:
+    - - effect: Allow
+        actors:
+        - kind: User
+          claims:
+            email: '*'
+        actions:
+        - config:read
+        resources:
+        - project/**

core/data/builtin_schemas/_webhooks.schema.yaml

@@ -0,0 +1,145 @@
+_ocmo:
+  is_json_schema: true
+$schema: https://json-schema.org/draft/2020-12/schema
+title: Namespace webhook delivery configuration
+description: Outbound HTTP notifications for namespace events. Each entry is evaluated independently;
+  payloads are HMAC-signed.
+type: object
+additionalProperties: false
+required:
+- webhooks
+properties:
+  webhooks:
+    type: array
+    description: Webhook delivery entries.
+    items:
+      type: object
+      additionalProperties: false
+      required:
+      - id
+      - enabled
+      - url
+      - events
+      - signature_key
+      properties:
+        id:
+          type: string
+          minLength: 1
+          maxLength: 100
+          pattern: ^[a-zA-Z][a-zA-Z0-9_-]*$
+          description: Stable identifier unique within this config.
+          examples:
+          - prod-notify
+        enabled:
+          type: boolean
+          description: When false, the entry is skipped without removing it.
+          examples:
+          - true
+        url:
+          type: string
+          minLength: 1
+          maxLength: 2048
+          format: uri
+          description: HTTPS endpoint that receives POST requests.
+          examples:
+          - https://hooks.example.com/ocmo
+        events:
+          type: array
+          minItems: 1
+          description: Event names that trigger delivery for this entry.
+          items:
+            type: string
+            enum:
+            - 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
+            description: Namespace event identifier.
+            examples:
+            - config.updated
+          examples:
+          - - config.updated
+            - config.tagged
+        filter:
+          type: object
+          additionalProperties: false
+          description: Optional narrowing of which item paths fire this webhook.
+          properties:
+            paths:
+              type: array
+              minItems: 1
+              description: Fnmatch globs matched against the event item path. Omit the filter block to
+                receive all subscribed events.
+              items:
+                type: string
+                minLength: 1
+                maxLength: 512
+                format: uri-reference
+                x-ocmo-uri-reference: resource
+                description: Tree path glob (e.g. ``project/**``).
+                examples:
+                - project/**
+                - app/prod/**
+        signature_header:
+          type: string
+          minLength: 1
+          maxLength: 100
+          description: HTTP header carrying the HMAC-SHA256 hex digest.
+          default: X-OCMO-Signature
+          examples:
+          - X-OCMO-Signature
+        signature_key:
+          type: string
+          minLength: 1
+          maxLength: 512
+          description: HMAC signing key literal or ``{!param}`` reference resolved from ``_ocmo.parameters``.
+          examples:
+          - '{!hmac_signing_key}'
+        payload:
+          type: object
+          additionalProperties: true
+          description: Payload shape controls. Set ``preset`` or ``template`` (mutually exclusive).
+          properties:
+            preset:
+              type: string
+              enum:
+              - ocmo
+              - generic_json
+              - slack
+              - teams
+              - discord
+              description: Built-in payload formatter.
+              examples:
+              - ocmo
+            template:
+              type: string
+              minLength: 1
+              description: Jinja2 template rendered to the request body.
+            headers:
+              type: object
+              description: Extra HTTP headers appended to each delivery.
+              additionalProperties:
+                type: string
+                minLength: 1
+    examples:
+    - - id: example
+        enabled: false
+        url: https://example.com/ocmo/webhook
+        events:
+        - config.updated
+        signature_key: '{!hmac_signing_key}'
+        payload:
+          preset: ocmo

core/decorators/__init__.py

@@ -0,0 +1,14 @@
+"""Cross-cutting manager method decorators."""
+
+from .audit import audit, enrich_audit
+from .permissions import PermCheck, arg, require_permissions
+from .webhook import webhook
+
+__all__ = [
+    "audit",
+    "enrich_audit",
+    "arg",
+    "PermCheck",
+    "require_permissions",
+    "webhook",
+]

core/decorators/audit.py

@@ -0,0 +1,105 @@
+"""@audit decorator for append-only operation logging."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable
+from contextvars import ContextVar
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class AuditEventContext:
+    """Public post-call fields a method may supply to the active audit event."""
+
+    operation: str | None = None
+    object_version: int | None = None
+    subresource_type: str | None = None
+    subresource: str | None = None
+
+
+_audit_operation_context: ContextVar[AuditEventContext | None] = ContextVar(
+    "audit_operation_context",
+    default=None,
+)
+
+
+def enrich_audit(**kwargs) -> None:
+    """Set post-call audit fields from inside a decorated method body.
+
+    Safe to call when no audit is active (no-op).
+    Body values take precedence over decorator defaults.
+    """
+    ctx = _audit_operation_context.get()
+    if ctx is None:
+        return
+    for key, value in kwargs.items():
+        if value is not None and hasattr(ctx, key):
+            setattr(ctx, key, value)
+
+
+def _take_audit_context() -> AuditEventContext | None:
+    """Consume and clear the ContextVar; called by run_decorated after func()."""
+    ctx = _audit_operation_context.get()
+    _audit_operation_context.set(None)
+    return ctx
+
+
+def audit(
+    object_type: str | Callable,
+    *,
+    object_id_attr: str | Callable | None = None,
+    namespace_attribute: str = "namespace",
+    resolve_type: str | None = None,
+    operation: str | Callable | None = None,
+    subresource_type: str | Callable | None = None,
+    subresource: str | Callable | None = None,
+    object_version: int | str | Callable | None = None,
+    skip_when: Callable | None = None,
+    skip_when_no_auth: bool = True,
+    auth_manager_attribute: str = "auth",
+) -> Callable:
+    """Decorator for manager public methods — logs outcome after execution."""
+
+    def decorator(func: Callable) -> Callable:
+        try:
+            sig = inspect.signature(func)
+            func_params = [
+                name
+                for name, p in sig.parameters.items()
+                if name != "self" and p.kind not in (p.VAR_POSITIONAL, p.VAR_KEYWORD)
+            ]
+        except (ValueError, TypeError):
+            func_params = []
+
+        @functools.wraps(func)
+        def wrapper(self, *args, **kwargs):
+            from ..managers.audit import AuditManager
+
+            audit_mgr = AuditManager.for_decorated_call(
+                self,
+                auth_manager_attribute=auth_manager_attribute,
+                skip_when_no_auth=skip_when_no_auth,
+            )
+            if audit_mgr is None:
+                return func(self, *args, **kwargs)
+            return audit_mgr.run_decorated(
+                func,
+                self,
+                args,
+                kwargs,
+                object_type=object_type,
+                object_id_attr=object_id_attr,
+                skip_when=skip_when,
+                func_params=func_params,
+                resolve_type=resolve_type,
+                operation=operation,
+                subresource_type=subresource_type,
+                subresource=subresource,
+                object_version=object_version,
+            )
+
+        return wrapper
+
+    return decorator

core/decorators/binding.py

@@ -0,0 +1,49 @@
+"""Shared argument-binding helpers for manager method decorators."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+
+def bind_args(param_names: list[str], args: tuple, kwargs: dict) -> dict[str, Any]:
+    """Map positional + keyword call arguments to a name→value dict."""
+    bound: dict[str, Any] = {}
+    for i, name in enumerate(param_names):
+        if i < len(args):
+            bound[name] = args[i]
+    bound.update(kwargs)
+    return bound
+
+
+@functools.lru_cache(maxsize=512)
+def _callable_extra_params(fn: Callable) -> tuple[str, ...]:
+    """Return declared parameter names beyond 'self' (cached per callable)."""
+    try:
+        sig = inspect.signature(fn)
+        params = list(sig.parameters.values())
+        return tuple(p.name for p in params[1:] if p.kind not in (p.VAR_POSITIONAL, p.VAR_KEYWORD))
+    except (ValueError, TypeError):
+        return ()
+
+
+def invoke(fn: Callable, instance, bound_args: dict[str, Any]):
+    """Call fn(instance) or fn(instance, **matching_bound_args) from its signature."""
+    extra = _callable_extra_params(fn)
+    if not extra:
+        return fn(instance)
+    kwargs = {name: bound_args[name] for name in extra if name in bound_args}
+    return fn(instance, **kwargs)
+
+
+def resolve_resource(instance, resource, bound_args: dict[str, Any]) -> str:
+    """Resolve a resource specification to a string."""
+    if resource is None:
+        return getattr(instance, "path", "")
+    if callable(resource):
+        if getattr(resource, "_is_arg_extractor", False):
+            return resource(instance, bound_args)
+        return invoke(resource, instance, bound_args)
+    return getattr(instance, resource, "")

core/decorators/permissions.py

@@ -0,0 +1,129 @@
+"""@require_permissions decorator and PermCheck configuration."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+from ..exceptions import CapabilityDenied, NotFound, PermissionDenied
+from .binding import bind_args, invoke, resolve_resource
+
+_NAMESPACE_PREFIX = "namespace"
+_GLOBAL_PREFIX = "global"
+
+
+@dataclass
+class PermCheck:
+    """One permission check: action on a resource with optional error masking."""
+
+    action: str | Callable
+    resource: str | Callable | None = None
+    mask_as_not_found: bool = False
+    not_found_message: str | Callable | None = None
+
+
+def arg(name: str, transform: Callable | None = None) -> Callable:
+    """Create a resource callable that extracts a named method argument."""
+
+    def _extractor(instance, bound_args: dict) -> str:
+        value = bound_args.get(name, "")
+        return transform(value) if transform else value
+
+    _extractor._is_arg_extractor = True  # type: ignore[attr-defined]
+    return _extractor
+
+
+def _coerce_check(check: PermCheck | str | Callable) -> PermCheck:
+    if isinstance(check, PermCheck):
+        return check
+    return PermCheck(action=check)
+
+
+def _apply_check(
+    check: PermCheck,
+    instance,
+    bound_args: dict,
+    auth,
+    pm,
+) -> None:
+    try:
+        resolved = invoke(check.action, instance, bound_args) if callable(check.action) else check.action
+        if resolved is None:
+            return
+
+        if isinstance(resolved, list):
+            pairs = resolved
+        else:
+            resource = resolve_resource(instance, check.resource, bound_args)
+            pairs = [(resolved, resource)]
+
+        for action, resource in pairs:
+            type_, _, verb = action.partition(":")
+
+            if type_ == _GLOBAL_PREFIX and verb == "admin":
+                if not auth.is_global_admin:
+                    raise PermissionDenied("Global administrator access required")
+
+            elif type_ == _NAMESPACE_PREFIX:
+                pm.require_namespace_object(resource, verb)
+
+            else:
+                request_ctx: dict[str, Any] = {"time": datetime.now(UTC)}
+                pm.require_tree(action, resource, request_ctx)
+
+    except PermissionDenied as exc:
+        if check.mask_as_not_found:
+            if check.not_found_message is None:
+                msg = str(exc)
+            elif callable(check.not_found_message):
+                msg = check.not_found_message(instance)
+            else:
+                msg = check.not_found_message
+            raise NotFound(msg) from exc
+        raise
+
+
+def require_permissions(
+    *checks: PermCheck | str | Callable,
+    auth_manager_attribute: str = "auth",
+    namespace_attribute: str = "namespace",
+) -> Callable:
+    """Decorator for manager public methods."""
+
+    def decorator(func: Callable) -> Callable:
+        try:
+            sig = inspect.signature(func)
+            func_params = [
+                name
+                for name, p in sig.parameters.items()
+                if name != "self" and p.kind not in (p.VAR_POSITIONAL, p.VAR_KEYWORD)
+            ]
+        except (ValueError, TypeError):
+            func_params = []
+
+        @functools.wraps(func)
+        def wrapper(self, *args, **kwargs):
+            auth = getattr(self, auth_manager_attribute, None)
+
+            if auth is None:
+                return func(self, *args, **kwargs)
+
+            bound_args = bind_args(func_params, args, kwargs)
+            namespace = getattr(self, namespace_attribute, None)
+            pm = auth.permissions(namespace)
+
+            for check in checks:
+                _apply_check(_coerce_check(check), self, bound_args, auth, pm)
+
+            try:
+                return func(self, *args, **kwargs)
+            except CapabilityDenied as exc:
+                raise PermissionDenied(str(exc)) from exc
+
+        return wrapper
+
+    return decorator