netbox-super-cli 1.0.0__py3-none-any.whl

nsc/auth/verify.py

@@ -0,0 +1,143 @@
+"""Pre-flight verification of a profile's URL+token.
+
+`verify(profile)` issues two probes against the candidate NetBox:
+
+* `GET /api/status/` — confirms the URL is a NetBox and reports the version.
+* `GET /api/users/tokens/?limit=1` — confirms the token is accepted (the
+  endpoint requires authentication) and the response carries the calling
+  user's identity in `results[0].user.username`. NetBox does not expose a
+  top-level "current user" endpoint, so the token list is the closest signal
+  to "authenticated as <user>".
+
+Both must succeed. Either failure raises `VerifyError`; the caller maps the
+exception to an `auth_error` envelope (`ErrorType.AUTH`, exit 8). Login is not
+audited — `verify` deliberately bypasses `NetBoxClient` to keep the pre-flight
+out of `audit.jsonl`. There is no retry loop: a single failed probe fails fast.
+"""
+
+from __future__ import annotations
+
+import httpx
+from pydantic import BaseModel, ConfigDict
+
+from nsc.config.models import Profile
+
+_DEFAULT_TIMEOUT = 10.0
+
+
+class VerifyResult(BaseModel):
+    """The success-shape of a pre-flight verification."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+    username: str
+    netbox_version: str
+
+
+class VerifyError(Exception):
+    """Pre-flight verification failed.
+
+    `status_code` is the HTTP status of the failing probe, or `None` when the
+    failure was a transport error (connection refused, TLS, DNS, etc.).
+    `user_check_status` is set to the same status as `status_code` when the
+    auth probe (`/api/users/tokens/`) was the one that failed (i.e. `/api/status/`
+    returned 2xx but the token was rejected). This distinguishes
+    "wrong URL / NetBox down" from "URL fine, token rejected".
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        user_check_status: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.user_check_status = user_check_status
+
+    def __str__(self) -> str:
+        return self.message
+
+
+def verify(profile: Profile, *, timeout: float = _DEFAULT_TIMEOUT) -> VerifyResult:
+    """Confirm `profile`'s URL+token reach an authenticated NetBox.
+
+    Raises `VerifyError` on any failure. Returns a `VerifyResult` on success.
+    """
+    if not profile.token:
+        raise VerifyError(message="profile has no token; cannot verify")
+    base = str(profile.url).rstrip("/")
+    headers = {
+        "Authorization": f"Token {profile.token}",
+        "Accept": "application/json",
+    }
+    with httpx.Client(
+        base_url=base,
+        headers=headers,
+        verify=profile.verify_ssl,
+        timeout=timeout,
+    ) as client:
+        version = _probe_status(client)
+        username = _probe_users_me(client)
+    return VerifyResult(username=username, netbox_version=version)
+
+
+def _probe_status(client: httpx.Client) -> str:
+    try:
+        response = client.get("/api/status/")
+    except (httpx.RequestError, OSError) as exc:
+        raise VerifyError(message=f"could not reach NetBox: {exc}") from exc
+    if not response.is_success:
+        raise VerifyError(
+            message=f"NetBox /api/status/ returned {response.status_code}",
+            status_code=response.status_code,
+        )
+    body = _safe_json(response)
+    version = body.get("netbox-version") if isinstance(body, dict) else None
+    return str(version) if version else "unknown"
+
+
+def _probe_users_me(client: httpx.Client) -> str:
+    """Verify the token via `GET /api/users/tokens/?limit=1`.
+
+    NetBox does not expose a top-level "current user" endpoint (`/api/users/me/`
+    and `/api/users/users/me/` both return 404 on 4.5+). The token-list endpoint
+    is authenticated and its response carries a nested `user.username` for each
+    token, which is the closest signal to "authenticated as <user>". A non-admin
+    user only sees their own tokens, so `results[0].user.username` is the
+    calling user's identity in the common case. If the user has no visible
+    tokens (an unusual admin state), we surface "(unknown)" rather than failing.
+    """
+    try:
+        response = client.get("/api/users/tokens/", params={"limit": 1})
+    except (httpx.RequestError, OSError) as exc:
+        raise VerifyError(message=f"token probe failed: {exc}") from exc
+    if not response.is_success:
+        raise VerifyError(
+            message=(
+                f"NetBox accepted the URL but rejected the token "
+                f"(/api/users/tokens/ returned {response.status_code})"
+            ),
+            status_code=response.status_code,
+            user_check_status=response.status_code,
+        )
+    body = _safe_json(response)
+    if not isinstance(body, dict):
+        return "(unknown)"
+    results = body.get("results") or []
+    if not results:
+        return "(unknown)"
+    user = results[0].get("user") if isinstance(results[0], dict) else None
+    if isinstance(user, dict):
+        username = user.get("username")
+        if username:
+            return str(username)
+    return "(unknown)"
+
+
+def _safe_json(response: httpx.Response) -> object:
+    try:
+        return response.json()
+    except ValueError:
+        return None

nsc/builder/__init__.py

@@ -0,0 +1,5 @@
+"""Convert a parsed OpenAPI document into a CommandModel."""
+
+from nsc.builder.build import build_command_model
+
+__all__ = ["build_command_model"]

nsc/builder/build.py

@@ -0,0 +1,514 @@
+"""Schema → CommandModel.
+
+The algorithm is deterministic and depends solely on the OpenAPI document.
+No NetBox-specific knowledge is hard-coded.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+from nsc.model.command_model import (
+    CommandModel,
+    FieldShape,
+    HttpMethod,
+    Operation,
+    Parameter,
+    ParameterLocation,
+    PrimitiveType,
+    RequestBodyShape,
+    Resource,
+    Tag,
+)
+from nsc.schema.loader import LoadedSchema
+from nsc.schema.models import OpenAPIDocument, PathItem, SchemaObject
+from nsc.schema.models import Operation as SchemaOperation
+from nsc.schema.models import Parameter as SchemaParameter
+
+_PARAM_SEGMENT = re.compile(r"^\{[^}]+\}$")
+_CANONICAL_SENSITIVE_NAMES: frozenset[str] = frozenset(
+    {
+        "password",
+        "secret",
+        "token",
+        "api_key",
+        "apikey",
+        "private_key",
+        "passphrase",
+        "client_secret",
+    }
+)
+_HTTP_METHODS: tuple[tuple[str, HttpMethod], ...] = (
+    ("get", HttpMethod.GET),
+    ("post", HttpMethod.POST),
+    ("patch", HttpMethod.PATCH),
+    ("put", HttpMethod.PUT),
+    ("delete", HttpMethod.DELETE),
+    ("options", HttpMethod.OPTIONS),
+    ("head", HttpMethod.HEAD),
+)
+# api / <tag> / <resource> = at least 3 non-empty path parts
+_MIN_PATH_PARTS = 3
+
+
+def build_command_model(loaded: LoadedSchema) -> CommandModel:
+    doc = loaded.document
+    tags: dict[str, _MutableTag] = {}
+
+    for path, item in doc.paths.items():
+        for attr_name, http_method in _HTTP_METHODS:
+            schema_op: SchemaOperation | None = getattr(item, attr_name)
+            if schema_op is None:
+                continue
+            _assimilate(tags, path, http_method, schema_op, item, doc)
+
+    final_tags = {
+        name: Tag(
+            name=name,
+            description=mt.description,
+            resources={rname: _finalize_resource(rname, mr) for rname, mr in mt.resources.items()},
+        )
+        for name, mt in sorted(tags.items())
+    }
+
+    return CommandModel(
+        info_title=doc.info.title,
+        info_version=doc.info.version,
+        schema_hash=loaded.hash,
+        tags=final_tags,
+    )
+
+
+# --- internals -------------------------------------------------------------
+
+
+class _MutableResource:
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self.list_op: Operation | None = None
+        self.get_op: Operation | None = None
+        self.create_op: Operation | None = None
+        self.update_op: Operation | None = None
+        self.replace_op: Operation | None = None
+        self.delete_op: Operation | None = None
+        self.custom_actions: list[Operation] = []
+
+
+class _MutableTag:
+    def __init__(self, name: str, description: str | None) -> None:
+        self.name = name
+        self.description = description
+        self.resources: dict[str, _MutableResource] = {}
+
+
+def _assimilate(
+    tags: dict[str, _MutableTag],
+    path: str,
+    http_method: HttpMethod,
+    schema_op: SchemaOperation,
+    item: PathItem,
+    doc: OpenAPIDocument,
+) -> None:
+    tag_name = schema_op.tags[0] if schema_op.tags else None
+    if tag_name is None:
+        return  # untagged operations are skipped intentionally
+
+    resource_name, is_collection_path = _resource_from_path(path, tag_name)
+    if resource_name is None:
+        return  # paths that don't match the /api/<tag>/<resource>/... shape
+
+    tag = tags.get(tag_name)
+    if tag is None:
+        tag = _MutableTag(tag_name, _tag_description(tag_name, doc))
+        tags[tag_name] = tag
+
+    resource = tag.resources.get(resource_name)
+    if resource is None:
+        resource = _MutableResource(resource_name)
+        tag.resources[resource_name] = resource
+
+    op = _to_model_operation(path, http_method, schema_op, item, doc)
+    classification = _classify(http_method, path, schema_op, resource_name)
+    _attach(resource, classification, op, is_collection_path)
+
+
+def _resource_from_path(path: str, tag: str) -> tuple[str | None, bool]:
+    """Return (resource_name, is_collection_path).
+
+    A path is a collection path if it has no further parameter segments after
+    the resource name. `is_collection_path=True` for `/api/dcim/devices/`
+    and `False` for `/api/dcim/devices/{id}/`.
+    """
+    parts = [p for p in path.split("/") if p]
+    if not parts or parts[0] != "api":
+        return None, False
+    # Top-level resources (e.g., /api/search/, /api/status/) — single segment after /api/.
+    # The segment itself is the resource name and is always a collection path.
+    if len(parts) == 2:  # noqa: PLR2004
+        return parts[1], True
+    # Expect: api / <tag-or-tag-with-dashes> / <resource> / [...]
+    if len(parts) < _MIN_PATH_PARTS:
+        return None, False
+    # Some plugin endpoints have nested tags (e.g., ['plugins', '<plugin>']).
+    # The tag string from the spec is authoritative; just find <resource>.
+    # Strategy: skip leading non-parameter segments until we've consumed the
+    # tag's words and reached a resource segment.
+    # Easier heuristic that works for NetBox: the resource is the first
+    # segment after the segment that begins the tag's path-form.
+    tag_form = tag.replace(" ", "-").lower()
+    try:
+        anchor = parts.index(tag_form)
+    except ValueError:
+        # Fall back: assume parts[1] is the tag, parts[2] is the resource.
+        anchor = 1
+    if anchor + 1 >= len(parts):
+        return None, False
+    resource = parts[anchor + 1]
+    if _PARAM_SEGMENT.match(resource):
+        return None, False
+    remainder = parts[anchor + 2 :]
+    is_collection = all(not _PARAM_SEGMENT.match(p) for p in remainder) and not remainder
+    # If the only remaining segment is `{id}` it's the per-item path:
+    if len(remainder) == 1 and _PARAM_SEGMENT.match(remainder[0]):
+        is_collection = False
+    return resource, is_collection
+
+
+_CRUD_MAP: dict[tuple[HttpMethod, bool], str] = {
+    (HttpMethod.GET, False): "list",
+    (HttpMethod.GET, True): "get",
+    (HttpMethod.POST, False): "create",
+    (HttpMethod.PATCH, True): "update",
+    (HttpMethod.PUT, True): "replace",
+    (HttpMethod.DELETE, True): "delete",
+}
+
+
+def _classify(
+    method: HttpMethod,
+    path: str,
+    schema_op: SchemaOperation,
+    resource_name: str,
+) -> str:
+    has_id = "{id}" in path
+    extra_path_segments = path.rstrip("/").split("/")[-1]
+    # Path is a custom action endpoint if `{id}` appears AND the last segment
+    # is a literal name (not itself a path parameter like `{id}`).
+    is_action_endpoint = has_id and not _PARAM_SEGMENT.match(extra_path_segments)
+
+    if is_action_endpoint:
+        return "custom"
+
+    return _CRUD_MAP.get((method, has_id), "custom")
+
+
+def _attach(
+    resource: _MutableResource,
+    classification: str,
+    op: Operation,
+    is_collection_path: bool,  # kept for future heuristics
+) -> None:
+    match classification:
+        case "list":
+            resource.list_op = op
+        case "get":
+            resource.get_op = op
+        case "create":
+            resource.create_op = op
+        case "update":
+            resource.update_op = op
+        case "replace":
+            resource.replace_op = op
+        case "delete":
+            resource.delete_op = op
+        case _:
+            resource.custom_actions.append(op)
+
+
+def _to_model_operation(
+    path: str,
+    http_method: HttpMethod,
+    schema_op: SchemaOperation,
+    item: PathItem,
+    doc: OpenAPIDocument,
+) -> Operation:
+    if schema_op.operation_id is None:
+        # Synthesize one — operationId is required in practice but we degrade
+        # gracefully rather than crashing on hand-rolled schemas.
+        synthesized = f"{http_method.value.lower()}_{path.strip('/').replace('/', '_')}"
+        operation_id = synthesized
+    else:
+        operation_id = schema_op.operation_id
+
+    seen: dict[str, Parameter] = {}
+    for source_param in (*item.parameters, *schema_op.parameters):
+        seen[source_param.name] = _to_model_parameter(source_param)
+    parameters = list(seen.values())
+
+    return Operation(
+        operation_id=operation_id,
+        http_method=http_method,
+        path=path,
+        summary=schema_op.summary,
+        description=schema_op.description,
+        parameters=parameters,
+        request_body=_to_request_body_shape(schema_op, doc),
+        default_columns=_default_columns_from_response(schema_op, doc),
+    )
+
+
+def _to_model_parameter(p: SchemaParameter) -> Parameter:
+    enum_values: list[str] | None = None
+    primitive = PrimitiveType.UNKNOWN
+    if p.schema_ is not None:
+        primitive = _primitive(p.schema_)
+        if p.schema_.enum:
+            enum_values = [str(v) for v in p.schema_.enum]
+    return Parameter(
+        name=p.name,
+        location=ParameterLocation(p.in_.value),
+        primitive=primitive,
+        required=p.required,
+        description=p.description,
+        enum=enum_values,
+    )
+
+
+def _to_request_body_shape(
+    schema_op: SchemaOperation, doc: OpenAPIDocument
+) -> RequestBodyShape | None:
+    if schema_op.request_body is None:
+        return None
+    media = schema_op.request_body.content.get("application/json")
+    if media is None or media.schema_ is None:
+        return None
+    schema = _resolve_ref(media.schema_, doc)
+    if schema is None:
+        return None
+    top_level = _classify_top_level(schema, doc)
+    if top_level is None:
+        return None
+    if top_level in ("object", "object_or_array"):
+        branch = _object_branch(schema, doc)
+        required = list(branch.required or []) if branch is not None else []
+    else:
+        required = []
+    fields = _flat_fields(schema, doc) if top_level in ("object", "object_or_array") else {}
+    raw_paths = _collect_sensitive_paths(schema, doc)
+    sensitive_paths = tuple(sorted({".".join(p) for p in raw_paths if p}))
+    return RequestBodyShape(
+        top_level=top_level,
+        required=required,
+        fields=fields,
+        sensitive_paths=sensitive_paths,
+    )
+
+
+def _branch_type(raw: object, doc: OpenAPIDocument) -> str | None:
+    """Return the top-level "type" for a oneOf/anyOf branch, resolving $ref once."""
+    if not isinstance(raw, dict):
+        return None
+    direct = raw.get("type")
+    if direct in {"object", "array"}:
+        return str(direct)
+    ref = raw.get("$ref")
+    if isinstance(ref, str):
+        candidate = SchemaObject.model_validate({"$ref": ref})
+        resolved = _resolve_ref(candidate, doc)
+        if resolved is not None and resolved.type in ("object", "array"):
+            return resolved.type
+    return None
+
+
+def _classify_top_level(
+    schema: SchemaObject, doc: OpenAPIDocument
+) -> Literal["object", "array", "object_or_array"] | None:
+    if schema.type in ("object", "array"):
+        return schema.type  # type: ignore[return-value]
+    one_of = schema.model_extra.get("oneOf") if schema.model_extra else None
+    any_of = schema.model_extra.get("anyOf") if schema.model_extra else None
+    candidates = one_of or any_of or None
+    if not candidates:
+        return None
+    types = {t for raw in candidates if (t := _branch_type(raw, doc)) is not None}
+    if {"object", "array"}.issubset(types):
+        return "object_or_array"
+    if types == {"object"}:
+        return "object"
+    return "array" if types == {"array"} else None
+
+
+def _object_branch(schema: SchemaObject, doc: OpenAPIDocument) -> SchemaObject | None:
+    """Find the object-shaped variant of a oneOf/anyOf, resolving $ref branches."""
+    if schema.type == "object":
+        return schema
+    candidates = (
+        (schema.model_extra or {}).get("oneOf") or (schema.model_extra or {}).get("anyOf") or []
+    )
+    for raw in candidates:
+        if not isinstance(raw, dict):
+            continue
+        if raw.get("type") == "object":
+            return SchemaObject.model_validate(raw)
+        ref = raw.get("$ref")
+        if isinstance(ref, str):
+            resolved = _resolve_ref(SchemaObject.model_validate({"$ref": ref}), doc)
+            if resolved is not None and resolved.type == "object":
+                return resolved
+    return None
+
+
+def _flat_fields(schema: SchemaObject, doc: OpenAPIDocument) -> dict[str, FieldShape]:
+    target = _object_branch(schema, doc)
+    if target is None or not target.properties:
+        return {}
+    out: dict[str, FieldShape] = {}
+    for name, prop in target.properties.items():
+        resolved = _resolve_ref(prop, doc) or prop
+        primitive = _primitive(resolved)
+        enum = [str(v) for v in resolved.enum] if resolved.enum else None
+        out[name] = FieldShape(primitive=primitive, enum=enum)
+    return out
+
+
+def _primitive(schema: SchemaObject) -> PrimitiveType:
+    if schema.type is None:
+        return PrimitiveType.UNKNOWN
+    try:
+        return PrimitiveType(schema.type)
+    except ValueError:
+        return PrimitiveType.UNKNOWN
+
+
+_SCALAR_TYPES = {"string", "integer", "number", "boolean"}
+_PRIORITY_NAMES = ("name", "slug", "display")
+_MAX_DEFAULT_COLUMNS = 6
+
+
+def _resolve_ref(schema: SchemaObject, doc: OpenAPIDocument) -> SchemaObject | None:
+    if schema.ref is None:
+        return schema
+    # OpenAPI refs look like "#/components/schemas/<Name>" — we only support that form.
+    prefix = "#/components/schemas/"
+    if not schema.ref.startswith(prefix):
+        return None
+    name = schema.ref[len(prefix) :]
+    return doc.components.schemas.get(name)
+
+
+def _is_sensitive_field(name: str, schema: SchemaObject) -> bool:
+    if name.lower() in _CANONICAL_SENSITIVE_NAMES:
+        return True
+    return getattr(schema, "format", None) == "password"
+
+
+def _collect_sensitive_paths(
+    schema: SchemaObject,
+    doc: OpenAPIDocument,
+    *,
+    prefix: tuple[str, ...] = (),
+    seen: frozenset[str] = frozenset(),
+) -> list[tuple[str, ...]]:
+    """Return all dotted paths to sensitive fields under `schema`.
+
+    `seen` carries already-traversed `$ref` targets to break cycles in
+    self-referential schemas (NetBox has a few via `tags`).
+    """
+    target = _resolve_ref(schema, doc) or schema
+    new_seen = seen
+    if target.ref is not None:
+        if target.ref in seen:
+            return []
+        new_seen = seen | {target.ref}
+    elif schema.ref is not None:
+        if schema.ref in seen:
+            return []
+        new_seen = seen | {schema.ref}
+
+    paths: list[tuple[str, ...]] = []
+
+    if target.type == "object" and target.properties:
+        for name, prop in target.properties.items():
+            child_prefix = (*prefix, name)
+            resolved_prop = _resolve_ref(prop, doc) or prop
+            if _is_sensitive_field(name, resolved_prop):
+                paths.append(child_prefix)
+                continue
+            paths.extend(
+                _collect_sensitive_paths(resolved_prop, doc, prefix=child_prefix, seen=new_seen)
+            )
+
+    if target.type == "array" and target.items is not None:
+        paths.extend(_collect_sensitive_paths(target.items, doc, prefix=prefix, seen=new_seen))
+
+    candidates = (
+        (target.model_extra or {}).get("oneOf") or (target.model_extra or {}).get("anyOf") or []
+    )
+    for raw in candidates:
+        if isinstance(raw, dict):
+            branch = SchemaObject.model_validate(raw)
+            paths.extend(_collect_sensitive_paths(branch, doc, prefix=prefix, seen=new_seen))
+
+    return paths
+
+
+def _record_shape(response_schema: SchemaObject, doc: OpenAPIDocument) -> SchemaObject | None:
+    resolved = _resolve_ref(response_schema, doc)
+    if resolved is None:
+        return None
+    props = resolved.properties or {}
+    results = props.get("results")
+    if results is not None and results.type == "array" and results.items is not None:
+        return _resolve_ref(results.items, doc)
+    return resolved
+
+
+def _default_columns_from_response(
+    schema_op: SchemaOperation, doc: OpenAPIDocument
+) -> list[str] | None:
+    response = schema_op.responses.get("200")
+    if response is None:
+        return None
+    media = response.content.get("application/json")
+    if media is None or media.schema_ is None:
+        return None
+    record = _record_shape(media.schema_, doc)
+    if record is None or not record.properties:
+        return None
+
+    cols: list[str] = []
+    if "id" in record.properties:
+        cols.append("id")
+    for name in _PRIORITY_NAMES:
+        if name in record.properties and name not in cols:
+            cols.append(name)
+    for name, prop in record.properties.items():
+        if len(cols) >= _MAX_DEFAULT_COLUMNS:
+            break
+        if name in cols:
+            continue
+        if (prop.type or "") not in _SCALAR_TYPES:
+            continue
+        cols.append(name)
+    return cols if cols else None
+
+
+def _tag_description(name: str, doc: OpenAPIDocument) -> str | None:
+    for tag in doc.tags:
+        if tag.name == name:
+            return tag.description
+    return None
+
+
+def _finalize_resource(name: str, m: _MutableResource) -> Resource:
+    return Resource(
+        name=name,
+        list_op=m.list_op,
+        get_op=m.get_op,
+        create_op=m.create_op,
+        update_op=m.update_op,
+        replace_op=m.replace_op,
+        delete_op=m.delete_op,
+        custom_actions=list(m.custom_actions),
+    )

nsc/cache/__init__.py

@@ -0,0 +1,5 @@
+"""On-disk cache for generated CommandModels."""
+
+from nsc.cache.store import CacheStore
+
+__all__ = ["CacheStore"]