avr-cli 0.1.0__py3-none-any.whl

avrea_cli/assets/logo_mark.svg

@@ -0,0 +1,25 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 90 24" fill="none" role="img" aria-label="Avrea logo">
+<g clip-path="url(#avrea-logo-clip)">
+<path d="M43.641 7.08765H45.892L47.9816 12.1759C48.4867 13.4141 48.9463 14.5614 49.4293 15.7984H49.4748C49.98 14.5146 50.463 13.3231 50.9903 12.0382L53.0343 7.08765H55.1941L50.4617 18.3659H48.3943L43.6398 7.08765H43.641Z" fill="white"/>
+<path d="M57.604 7.08771H59.6714V8.73787L59.717 8.76124C60.4981 7.66072 61.7388 6.99548 63.0707 6.99548C63.3011 6.99548 63.5537 7.01885 63.8062 7.08771V9.12767C63.5302 9.06004 63.2543 9.03668 63.0017 9.03668C61.4628 9.03668 60.3835 9.81626 59.6714 11.0311V18.3671H57.604V7.08771Z" fill="white"/>
+<path d="M71.7186 18.6179C68.1345 18.6179 65.5853 16.348 65.5853 12.7723C65.5853 9.19648 68.1123 6.83435 71.19 6.83435C73.9695 6.83435 76.3573 8.75996 76.3573 12.3136C76.3573 12.6579 76.3351 13.1166 76.3117 13.3674H67.6749C67.9509 15.5451 69.6043 16.7612 71.8553 16.7612C73.3252 16.7612 74.657 16.2337 75.7376 15.4553V17.5641C74.7038 18.2294 73.1416 18.6179 71.7173 18.6179H71.7186ZM74.3601 11.6951C74.1999 9.49528 72.5921 8.69233 71.1678 8.69233C69.6056 8.69233 68.0445 9.67726 67.6996 11.6951H74.3601Z" fill="white"/>
+<path d="M88.301 7.63608C87.3597 7.15529 86.326 6.83313 85.1543 6.83313C81.6749 6.83313 79.2354 9.32806 79.1874 12.7366C79.2367 16.1452 81.6762 18.6401 85.1543 18.6401C86.326 18.6401 87.3597 18.3191 88.301 17.8371L90.0012 18.2269V7.24629L88.301 7.63608ZM87.9338 16.0271C87.2217 16.4858 86.2114 16.8067 85.1777 16.8067C82.7776 16.8067 81.2893 15.036 81.2745 12.7378C81.2893 10.4384 82.7776 8.66897 85.1777 8.66897C86.2114 8.66897 87.2217 8.98868 87.9338 9.44856V16.0283V16.0271Z" fill="white"/>
+<path d="M39.0639 7.63608C38.1226 7.15529 37.0889 6.83313 35.9172 6.83313C32.4379 6.83313 29.9984 9.32806 29.9503 12.7366C29.9996 16.1452 32.4391 18.6401 35.9172 18.6401C37.0889 18.6401 38.1226 18.3191 39.0639 17.8371L40.7642 18.2269V7.24629L39.0639 7.63608ZM38.6968 16.0271C37.9846 16.4858 36.9743 16.8067 35.9406 16.8067C33.5406 16.8067 32.0522 15.036 32.0374 12.7378C32.0522 10.4384 33.5406 8.66897 35.9406 8.66897C36.9743 8.66897 37.9846 8.98868 38.6968 9.44856V16.0283V16.0271Z" fill="white"/>
+<path d="M15.6435 21.8875C15.5461 21.8789 15.232 21.8433 15.142 21.8347C14.3239 21.7117 14.8488 19.8906 14.8291 19.6336C14.8242 19.5377 14.1736 18.4851 14.1736 18.4851C14.0282 17.9626 13.3752 15.3988 14.2611 14.2195C14.5617 13.8175 15.0065 13.606 15.5424 13.606C15.9774 13.606 16.4677 13.7388 17.0419 14.013C17.2316 14.104 17.345 14.3032 17.3265 14.5134L16.2607 21.4732C16.193 21.8457 16.055 21.9318 15.6422 21.8851L15.6435 21.8875Z" fill="#D88D26"/>
+<path d="M15.5425 13.6084C15.9774 13.6084 16.4677 13.7412 17.0419 14.0154C17.2316 14.1064 17.345 14.3056 17.3265 14.5159L16.2608 21.4756C16.2041 21.7892 16.0981 21.8986 15.8209 21.8986C15.7679 21.8986 15.7088 21.8949 15.6423 21.8875C15.5449 21.8789 15.2308 21.8433 15.1408 21.8347C14.3215 21.7117 14.8476 19.8906 14.8279 19.6336C14.8229 19.5377 14.1724 18.4851 14.1724 18.4851C14.027 17.9626 13.374 15.3988 14.2599 14.2195C14.5605 13.8175 15.0053 13.606 15.5412 13.606M15.5425 12.7501C14.7355 12.7501 14.0356 13.0895 13.5736 13.7068C12.5054 15.1282 13.0586 17.6834 13.3469 18.7151C13.3691 18.7926 13.4011 18.8663 13.443 18.9352C13.6229 19.2266 13.8324 19.5771 13.9482 19.7824C13.9445 19.8033 13.942 19.8242 13.9383 19.8427C13.8016 20.6813 13.7042 21.5519 14.1478 22.1581C14.356 22.4433 14.664 22.629 15.0151 22.6819C15.0299 22.6843 15.0447 22.6856 15.0595 22.6868C15.0989 22.6905 15.1839 22.7003 15.2739 22.7089C15.3835 22.72 15.4993 22.7323 15.556 22.7384C15.6533 22.7495 15.7408 22.7544 15.8221 22.7544C16.2263 22.7544 16.931 22.6081 17.1072 21.6256C17.1084 21.6183 17.1097 21.6109 17.1109 21.6035L18.1766 14.6438C18.1791 14.6253 18.1815 14.6069 18.1828 14.5884C18.2321 14.0253 17.9216 13.4842 17.4127 13.2408C16.7203 12.91 16.1092 12.7489 15.5425 12.7489V12.7501Z" fill="#5D3B20"/>
+<path d="M16.6637 0.857056C16.8522 0.857056 17.0383 0.898863 17.207 0.988627C17.8255 1.31202 17.9241 2.16293 17.791 2.79004C17.7652 2.913 17.8231 3.03597 17.9364 3.09007C18.6215 3.42084 20.286 4.2988 21.7287 5.5641C22.9472 6.63388 22.2721 10.5048 21.6018 11.1884C21.4478 11.3483 21.4256 11.368 21.3234 11.368C21.2568 11.368 21.2076 11.3434 21.1755 11.2991C20.9981 11.0544 21.6302 9.25915 21.0683 9.25915C21.04 9.25915 21.008 9.26775 20.971 9.28374C20.4782 9.50507 20.7874 11.5131 19.6798 11.9729C19.0367 12.2398 18.4502 12.3984 17.7701 12.3984C15.3121 12.3984 13.7979 10.9437 13.2607 10.5908C13.2546 10.5872 13.2472 10.5847 13.241 10.5847C13.2164 10.5847 13.1967 10.6105 13.209 10.6376C13.464 11.1602 14.9228 12.4476 16.4875 12.9517C17.2329 13.162 17.4227 13.0858 17.4227 13.0858C17.4227 13.0858 17.5335 15.561 16.798 16.7611C16.1191 17.869 14.2353 19.1651 14.2353 19.1651C14.2291 19.2524 14.1971 19.4491 14.1983 19.4762L13.7782 22.5244C13.7055 23.0433 13.5922 23.1417 13.2866 23.1417C12.524 23.0888 12.2911 23.2389 12.1938 22.383C12.1248 22.0277 11.8808 20.8017 11.7724 20.2496C11.5223 20.3923 11.1416 20.4464 10.7596 20.5042C10.3395 20.5669 9.06925 20.8054 8.44459 20.7685C8.22282 20.755 9.86023 19.8254 9.74195 18.3548C9.69883 17.8137 9.61505 17.5063 9.45611 18.4728C9.13454 20.4181 5.81659 20.9124 5.81659 20.9124C9.65694 21.6428 10.7313 22.0105 10.7941 22.2736L10.8447 22.5564C10.9013 22.7864 10.7757 23.0089 10.5391 23.0089L5.93856 22.506C3.96972 22.2441 0.859985 21.2419 0.859985 16.9837C0.859985 13.1423 3.49538 11.668 7.13736 9.70673C8.56656 8.93698 7.70165 6.20842 8.74275 4.30741C8.79326 4.21519 8.7908 4.10575 8.73659 4.01722C8.70579 3.9668 8.67622 3.91639 8.64788 3.86228C8.06511 2.75684 8.2339 1.52352 9.01996 1.11282C9.21586 1.00953 9.4327 0.965263 9.65324 0.965263C10.3186 0.965263 11.0134 1.37842 11.266 1.88503C11.2907 1.93299 11.4742 2.31663 11.5506 2.48263C11.5691 2.52075 11.6073 2.54534 11.648 2.54534H11.664C12.0582 2.48509 12.4969 2.45066 12.9884 2.44697H13.0981C13.6722 2.44697 14.2402 2.48509 14.7947 2.55149H14.8082C14.8612 2.55149 14.9055 2.5146 14.9154 2.46296C14.9536 2.27728 15.0201 2.09776 15.1138 1.92069C15.4612 1.25669 16.0822 0.857056 16.6625 0.857056H16.6662H16.6637Z" fill="#D88D26"/>
+<path d="M16.6637 0.857055C16.8522 0.857055 17.0382 0.898863 17.207 0.988626C17.8255 1.31202 17.9241 2.16293 17.791 2.79004C17.7652 2.913 17.8231 3.03597 17.9364 3.09007C18.6215 3.42084 20.286 4.2988 21.7287 5.56409C22.9472 6.63388 22.2721 10.5048 21.6018 11.1884C21.4478 11.3483 21.4256 11.368 21.3234 11.368C21.2568 11.368 21.2088 11.3434 21.1755 11.2991C20.9981 11.0544 21.6302 9.25915 21.0683 9.25915C21.04 9.25915 21.008 9.26775 20.971 9.28374C20.4782 9.50507 20.7874 11.5131 19.6798 11.9729C19.0367 12.2398 18.4502 12.3984 17.7701 12.3984C15.3121 12.3984 13.7979 10.9437 13.2607 10.5908C13.2546 10.5872 13.2472 10.5847 13.241 10.5847C13.2164 10.5847 13.1967 10.6105 13.209 10.6376C13.464 11.1602 14.9228 12.4476 16.4875 12.9517C16.9212 13.0735 17.1676 13.0993 17.297 13.0993C17.3894 13.0993 17.4227 13.0858 17.4227 13.0858C17.4227 13.0858 17.5335 15.561 16.798 16.7611C16.1191 17.869 14.2353 19.1651 14.2353 19.1651C14.2291 19.2524 14.1971 19.4491 14.1983 19.4762L13.7782 22.5244C13.7055 23.0433 13.5922 23.1417 13.2866 23.1417C12.524 23.0888 12.2911 23.2389 12.1938 22.383C12.1248 22.0277 11.8808 20.8017 11.7724 20.2496C11.5223 20.3923 11.1416 20.4464 10.7596 20.5042C10.3691 20.5632 9.2442 20.7722 8.58627 20.7722C8.53576 20.7722 8.48894 20.7722 8.44458 20.7685C8.22281 20.755 9.86023 19.8254 9.74195 18.3548C9.71854 18.067 9.68528 17.8457 9.63353 17.8457C9.58794 17.8457 9.53003 18.0191 9.45488 18.4728C9.13331 20.4181 5.81535 20.9124 5.81535 20.9124C9.65571 21.6428 10.7301 22.0105 10.7929 22.2736L10.8434 22.5564C10.9001 22.7864 10.7744 23.0089 10.5379 23.0089L5.93733 22.506C3.96849 22.2441 0.85875 21.2419 0.85875 16.9837C0.85875 13.1423 3.49414 11.668 7.13613 9.70673C8.56533 8.93698 7.70042 6.20842 8.74151 4.30741C8.79203 4.21519 8.78956 4.10575 8.73535 4.01721C8.70455 3.9668 8.67498 3.91638 8.64664 3.86228C8.06388 2.75684 8.23267 1.52352 9.01873 1.11282C9.21463 1.00953 9.43147 0.965263 9.65201 0.965263C10.3173 0.965263 11.0122 1.37842 11.2648 1.88503C11.2894 1.93298 11.473 2.31663 11.5494 2.48263C11.5679 2.52075 11.6061 2.54534 11.6467 2.54534H11.6627C12.057 2.48509 12.4956 2.45066 12.9872 2.44697H13.0969C13.671 2.44697 14.239 2.48509 14.7934 2.55149H14.807C14.86 2.55149 14.9043 2.5146 14.9142 2.46296C14.9524 2.27728 15.0189 2.09776 15.1125 1.92069C15.46 1.25669 16.0809 0.857055 16.6612 0.857055H16.6649M16.6637 0H16.66C15.7421 0 14.8353 0.597602 14.3499 1.52352C14.3302 1.56164 14.3105 1.60098 14.292 1.64033C13.8854 1.60713 13.485 1.58992 13.0956 1.58992H12.9798C12.673 1.59238 12.3773 1.6059 12.0952 1.63172C12.0644 1.56901 12.041 1.52106 12.0324 1.50384C11.6295 0.697203 10.6278 0.110667 9.65078 0.110667C9.27623 0.110667 8.92879 0.193053 8.61831 0.356594C7.99488 0.683677 7.57475 1.32432 7.46756 2.11497C7.37761 2.78266 7.51068 3.51429 7.84457 4.18445C7.4195 5.11405 7.33326 6.12481 7.25687 7.02613C7.18172 7.9127 7.11149 8.75008 6.72708 8.95666C3.11836 10.8982 0 12.5767 0 16.9849C0 20.5951 2.06864 22.8577 5.82398 23.3569H5.83384L5.84369 23.3594L10.4442 23.8623L10.491 23.8672H10.5379C10.9013 23.8672 11.2377 23.7061 11.4582 23.4245C11.4927 23.3803 11.5235 23.3348 11.5519 23.2868C11.6307 23.4381 11.7367 23.577 11.8845 23.6938C12.2258 23.9631 12.604 23.9742 12.9379 23.9852C13.0291 23.9877 13.1227 23.9914 13.225 23.9988L13.2546 24.0012H13.2841C14.4361 24.0012 14.579 22.9806 14.6259 22.6449L15.0398 19.6434C15.6522 19.1921 16.9323 18.1814 17.5274 17.2112C18.2777 15.9877 18.2974 13.8949 18.2839 13.2321C18.8334 13.1755 19.3829 13.0255 20.0075 12.7673C20.3722 12.616 20.6396 12.3849 20.8392 12.1144C20.9846 12.1881 21.1484 12.2287 21.3209 12.2287C21.7916 12.2287 22.0269 11.9852 22.2179 11.7885C22.9078 11.079 23.3119 9.02183 23.2565 7.54135C23.2109 6.32401 22.8869 5.44359 22.2955 4.92346C20.9809 3.77129 19.5233 2.94129 18.6941 2.51337C18.7533 1.6305 18.4551 0.675069 17.605 0.231171C17.3192 0.0811559 16.9927 0.00245927 16.6637 0.00245927V0ZM11.0085 21.3354C11.0418 21.3305 11.0738 21.3255 11.1071 21.3206C11.1132 21.3489 11.1182 21.3772 11.1243 21.4055C11.0874 21.3809 11.0492 21.3587 11.0085 21.3354Z" fill="#5D3B20"/>
+<path d="M9.45611 18.474C9.13454 20.4193 5.81659 20.9136 5.81659 20.9136C9.65694 21.644 10.7313 22.0117 10.7941 22.2748L10.8447 22.5576C10.9013 22.7876 10.7757 23.0101 10.5391 23.0101L5.93856 22.5072C3.96972 22.2453 0.859985 21.2432 0.859985 16.9849C0.859985 16.9849 1.21852 12.2877 5.76854 13.103C10.5095 13.9514 9.45735 18.474 9.45735 18.474H9.45611Z" fill="#DEA752"/>
+<path d="M20.3993 5.73014L18.4945 6.1556L18.8309 8.33697C18.8309 8.33697 21.0092 7.89799 21.035 8.92473C21.035 8.92473 21.2962 7.96562 22.3977 7.71108C22.3977 6.03755 21.7077 5.53955 21.7077 5.53955L20.398 5.72891L20.3993 5.73014Z" fill="#BB7624"/>
+<path d="M11.6578 2.54785C11.6159 2.54785 9.32549 3.23522 8.74149 4.30869C7.67699 6.21339 8.56531 8.969 7.13611 9.70801C7.13611 9.70801 8.49631 9.06245 11.0775 11.4111C13.6119 13.6724 13.4689 11.1664 13.2139 10.6438C13.2016 10.6179 13.2225 10.5909 13.2459 10.5909C13.2521 10.5909 13.2595 10.5909 13.2656 10.597C13.8053 10.9499 15.3195 12.4046 17.775 12.4046C18.4539 12.4046 19.8412 7.36187 18.6559 6.21954C17.2021 4.81776 12.2603 2.71262 11.6553 2.54785" fill="#DEA752"/>
+<path d="M11.6578 2.54783H11.6739C12.0681 2.48758 12.5067 2.45315 12.9983 2.44946H13.108C13.6821 2.44946 14.2501 2.48758 14.8045 2.55398H14.8181C14.8711 2.55398 17.8342 3.03846 17.9475 3.09256C18.6326 3.42333 20.2737 4.32711 21.7398 5.56659C22.0996 5.87154 21.6856 6.14943 20.8441 6.29453C17.5102 6.87 20.0926 5.83711 11.6566 2.5466L11.6591 2.54906L11.6578 2.54783Z" fill="#E6BE86"/>
+<path d="M19.6219 7.47492C19.4519 8.07621 17.9784 7.802 18.1484 7.15029C18.4096 6.63631 19.6441 6.86994 19.6256 7.46139L19.6219 7.47492Z" fill="#5D3B20"/>
+<path d="M23.068 6.30186C23.3341 6.86749 22.0392 7.62249 21.7411 7.01874C21.6006 6.45925 22.6885 5.82968 23.0618 6.28833L23.0717 6.2994L23.0692 6.30186H23.068Z" fill="#5D3B20"/>
+<path d="M13.05 4.89639C13.549 4.89639 14.0037 5.05747 14.356 5.3243C14.3942 5.30586 14.3782 5.31446 14.4152 5.29602C14.3905 4.65046 13.7905 4.13647 13.0513 4.13647C12.312 4.13647 11.7108 4.65292 11.6874 5.29602C11.7256 5.31446 11.7096 5.30586 11.7465 5.3243C12.0964 5.05747 12.5535 4.89639 13.0525 4.89639H13.05Z" fill="#5D3B20"/>
+</g>
+<defs>
+<clipPath id="avrea-logo-clip">
+<rect width="90" height="24" fill="white"/>
+</clipPath>
+</defs>
+</svg>

avrea_cli/audit.py

@@ -0,0 +1,153 @@
+"""Audit events CLI commands."""
+
+from avrea_cli.api_client import ApiClient
+from avrea_cli.config import CliConfig
+from avrea_cli.helpers import ensure_authenticated
+from avrea_cli.helpers import ensure_ctx
+from avrea_cli.helpers import get_org_id
+from avrea_cli.helpers import handle_http_error
+from avrea_cli.helpers import validate_cursor
+from avrea_cli.json_output import emit_json
+from avrea_cli.json_output import handle_json_meta
+from avrea_cli.json_output import make_schema
+from avrea_cli.json_output import split_fields
+from avrea_cli.output import format_timestamp
+from avrea_cli.output import output_list
+import click
+import httpx
+import json
+
+_AUDIT_FIELDS = make_schema(
+    "event_id",
+    "created_at",
+    "actor_user_id",
+    "actor_type",
+    "acting_api_key_id",
+    "client_ip",
+    "resource_type",
+    "resource_id",
+    "action",
+    "event_data",
+)
+
+
+@click.group("audit-events")
+@click.pass_context
+def audit_events(ctx):
+    """View audit events for organization writes."""
+    ensure_ctx(ctx)
+
+
+@audit_events.command("list")
+@click.option("--org", "org_id", help="Organization ID. Uses default org if not specified (see: avr config set org).")
+@click.option("--resource-type", "resource_type", default=None, help="Filter by resource type (e.g. api_key, user).")
+@click.option("--action", "action", default=None, help="Filter by action (CREATE, UPDATE, DELETE, ...).")
+@click.option("--actor-user-id", "actor_user_id", default=None, help="Filter by acting user id.")
+@click.option(
+    "--from",
+    "--created-after",
+    "created_after",
+    default=None,
+    help="ISO-8601 lower bound (inclusive) on created_at.",
+)
+@click.option(
+    "--to",
+    "--created-before",
+    "created_before",
+    default=None,
+    help="ISO-8601 upper bound (exclusive) on created_at.",
+)
+@click.option(
+    "-L",
+    "--limit",
+    type=click.IntRange(1, 1000),
+    default=100,
+    show_default=True,
+    help="Max events to return.",
+)
+@click.option("--cursor", default=None, help="Opaque cursor from a previous response's next_cursor.")
+@click.option(
+    "--json",
+    "json_fields",
+    default=None,
+    help='Output JSON. Pass comma-separated field names, "*" for all fields, or "?" to list available fields.',
+)
+@click.option("-q", "--jq", "jq_expr", default=None, help="Filter --json output through a jq expression.")
+@click.pass_context
+def audit_events_list(
+    ctx,
+    org_id,
+    resource_type,
+    action,
+    actor_user_id,
+    created_after,
+    created_before,
+    limit,
+    cursor,
+    json_fields,
+    jq_expr,
+):
+    """List audit events for the organization.
+
+    \b
+    JSON FIELDS
+        acting_api_key_id, action, actor_type, actor_user_id, client_ip,
+        created_at, event_data, event_id, resource_id, resource_type
+    """
+    if handle_json_meta(json_fields, jq_expr, _AUDIT_FIELDS):
+        return
+
+    client: ApiClient = ctx.obj["client"]
+    config: CliConfig = ctx.obj["config"]
+    ensure_authenticated(config)
+    org_id = get_org_id(config, org_id, client=client)
+    cursor = validate_cursor(cursor)
+
+    params: dict = {"limit": limit}
+    if resource_type:
+        params["resource_type"] = resource_type
+    if action:
+        params["action"] = action
+    if actor_user_id:
+        params["actor_user_id"] = actor_user_id
+    if created_after:
+        params["created_after"] = created_after
+    if created_before:
+        params["created_before"] = created_before
+    if cursor:
+        params["cursor"] = cursor
+
+    try:
+        response = client.public_get(f"/orgs/{org_id}/audit-events", params=params)
+    except httpx.HTTPStatusError as exc:
+        handle_http_error(exc, "list audit events")
+
+    rows = response.get("data", [])
+
+    if json_fields is not None:
+        emit_json(rows, split_fields(json_fields, _AUDIT_FIELDS), _AUDIT_FIELDS, jq_expr)
+        return
+
+    for row in rows:
+        row["created_at_display"] = format_timestamp(row.get("created_at"))
+        row["target"] = row.get("resource_id") or "-"
+        row["actor"] = row.get("actor_user_id") or row.get("actor_type") or "-"
+        row["event_data_display"] = json.dumps(row.get("event_data") or {}, separators=(",", ":"))
+
+    output_list(
+        rows,
+        columns=[
+            "created_at_display",
+            "actor",
+            "actor_type",
+            "resource_type",
+            "target",
+            "action",
+            "event_data_display",
+        ],
+        column_labels=["Time", "Actor", "Type", "Resource", "Target", "Action", "Data"],
+    )
+
+    next_cursor = (response.get("pagination") or {}).get("next_cursor")
+    if next_cursor:
+        click.echo(f"\nMore results available. Re-run with --cursor {next_cursor}", err=True)

avrea_cli/auth.py

@@ -0,0 +1,457 @@
+"""CLI authentication via browser OAuth flow.
+
+Credentials live in ``hosts.json`` keyed by full API URL:
+
+    {
+      "default_host": "https://api.avrea.com",
+      "hosts": {
+        "https://api.avrea.com": {
+          "token": "avk_...",
+          "default_org": "org-..."
+        }
+      }
+    }
+
+``default_host`` is the URL used when ``AVR_HOST`` isn't set. It's written
+on first login (when there are no other entries yet) and updated explicitly
+via ``avr auth switch <url>``. Multiple host entries accumulate naturally
+when the user logs in to additional API endpoints (e.g. self-hosted Avrea).
+"""
+
+from avrea_cli.paths import PATHS
+from http.server import BaseHTTPRequestHandler
+from http.server import HTTPServer
+from pathlib import Path
+from typing import Any
+from typing import override
+from urllib.parse import parse_qs
+from urllib.parse import urlparse
+import click
+import html as html_module
+import httpx
+import json
+import os
+import socket
+import webbrowser
+
+# Sibling asset so the file stays byte-identical to the console's Logo.
+# Update this file when the console Logo changes.
+_LOGO_SVG = (Path(__file__).parent / "assets" / "logo_mark.svg").read_text(encoding="utf-8")
+
+HOSTS_FILE = PATHS.hosts_file
+
+
+def _read() -> dict[str, Any]:
+    """Load the hosts file. Returns an empty wrapper if missing or malformed
+    — callers treat absence as 'no credentials yet'."""
+    empty: dict[str, Any] = {"default_host": None, "hosts": {}}
+    if not HOSTS_FILE.exists():
+        return empty
+    try:
+        data = json.loads(HOSTS_FILE.read_text())
+    except OSError, ValueError:
+        return empty
+    if not isinstance(data, dict):
+        return empty
+    hosts = data.get("hosts")
+    if not isinstance(hosts, dict):
+        return empty
+    default_host = data.get("default_host")
+    return {
+        "default_host": default_host if isinstance(default_host, str) and default_host in hosts else None,
+        "hosts": hosts,
+    }
+
+
+def _write(payload: dict[str, Any]) -> None:
+    HOSTS_FILE.parent.mkdir(parents=True, exist_ok=True)
+    HOSTS_FILE.write_text(json.dumps(payload, indent=2))
+    # Contains a bearer token; refuse group/other read. On Windows os.chmod
+    # only toggles the read-only bit — the file inherits NTFS ACLs from
+    # %USERPROFILE%, which is typically already user-private. A dedicated
+    # icacls / pywin32 hardening pass is a TODO if we ship on shared Windows
+    # boxes.
+    HOSTS_FILE.chmod(0o600)
+
+
+def list_hosts() -> list[str]:
+    """All hosts the user has stored credentials for, in insertion order."""
+    return list(_read()["hosts"].keys())
+
+
+def load_default_host() -> str | None:
+    """The pinned default URL, or None if unset.
+
+    ``CliConfig`` falls back to ``https://api.avrea.com`` when this is None,
+    so a brand-new install still has somewhere to point ``avr auth login``.
+    """
+    return _read()["default_host"]
+
+
+def set_default_host(host: str) -> None:
+    """Pin ``host`` as the default for commands without ``AVR_HOST``. The
+    host must already have credentials stored; we don't auto-create empty
+    entries — that would let `auth switch` silently misconfigure the file."""
+    payload = _read()
+    if host not in payload["hosts"]:
+        raise KeyError(host)
+    payload["default_host"] = host
+    _write(payload)
+
+
+def load_token(*, host: str) -> str | None:
+    """API key for ``host``, or None if not authenticated against it."""
+    entry = _read()["hosts"].get(host)
+    if not isinstance(entry, dict):
+        return None
+    token = entry.get("token")
+    return token if isinstance(token, str) and token else None
+
+
+def store_token(token: str, *, host: str) -> None:
+    """Persist ``token`` under ``host``. Preserves any default_org already
+    there. Promotes ``host`` to ``default_host`` when no default is set —
+    a first-time login should "just work" without an extra ``auth switch``.
+    """
+    payload = _read()
+    entry = payload["hosts"].setdefault(host, {})
+    if not isinstance(entry, dict):
+        # Replaces a corrupted entry rather than throwing — the auth flow
+        # has already issued a valid key, refusing to save would be worse.
+        entry = {}
+        payload["hosts"][host] = entry
+    entry["token"] = token
+    if not payload["default_host"]:
+        payload["default_host"] = host
+    _write(payload)
+
+
+def load_default_org(*, host: str) -> str | None:
+    entry = _read()["hosts"].get(host)
+    if not isinstance(entry, dict):
+        return None
+    org = entry.get("default_org")
+    return org if isinstance(org, str) and org else None
+
+
+def store_default_org(org_id: str, *, host: str) -> None:
+    payload = _read()
+    entry = payload["hosts"].setdefault(host, {})
+    if not isinstance(entry, dict):
+        entry = {}
+        payload["hosts"][host] = entry
+    entry["default_org"] = org_id
+    _write(payload)
+
+
+def clear_default_org(*, host: str) -> bool:
+    """Drop the stored default org for ``host``. Returns True if the entry
+    existed. Leaves the rest of the host record (token, etc.) intact."""
+    payload = _read()
+    entry = payload["hosts"].get(host)
+    if not isinstance(entry, dict) or "default_org" not in entry:
+        return False
+    del entry["default_org"]
+    _write(payload)
+    return True
+
+
+def clear(*, host: str) -> bool:
+    """Remove the host's entry. Returns True if anything was removed.
+
+    If the cleared host was ``default_host``, promote another stored host
+    to default (insertion order) so the CLI keeps working without a manual
+    ``auth switch``. If no hosts remain, unlink the file entirely."""
+    payload = _read()
+    if host not in payload["hosts"]:
+        return False
+    payload["hosts"].pop(host)
+    if payload["default_host"] == host:
+        remaining = list(payload["hosts"].keys())
+        payload["default_host"] = remaining[0] if remaining else None
+    if payload["hosts"]:
+        _write(payload)
+    else:
+        # Empty file would still satisfy `hosts.json exists`; remove it so a
+        # fresh `auth login` starts from a clean state.
+        try:
+            HOSTS_FILE.unlink()
+        except FileNotFoundError:
+            pass
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Browser OAuth flow
+# ---------------------------------------------------------------------------
+
+
+class OAuthCallbackHandler(BaseHTTPRequestHandler):
+    """Handle OAuth callback and extract session cookie and CSRF token."""
+
+    session_cookie = None
+    csrf_token = None
+    # Set by login() before the server runs so the handler can call /users/me
+    # with the just-issued session cookie and surface the email on the page.
+    public_api_url: str | None = None
+
+    @override
+    def log_message(self, format, *args):
+        pass
+
+    def do_GET(self):
+        # Query-param path covers localhost redirects; the cookie-header path
+        # covers same-domain redirects.
+        query = parse_qs(urlparse(self.path).query)
+        if "session" in query:
+            OAuthCallbackHandler.session_cookie = query["session"][0]
+        if "csrf_token" in query:
+            OAuthCallbackHandler.csrf_token = query["csrf_token"][0]
+        if not OAuthCallbackHandler.session_cookie:
+            cookie_header = self.headers.get("Cookie", "")
+            if "avrea_session=" in cookie_header:
+                for cookie in cookie_header.split(";"):
+                    if "avrea_session=" in cookie:
+                        OAuthCallbackHandler.session_cookie = cookie.split("=", 1)[1].strip()
+
+        email = self._fetch_email()
+
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html")
+        self.end_headers()
+        self.wfile.write(_render_success_html(email).encode("utf-8"))
+
+    def _fetch_email(self) -> str | None:
+        """Best-effort lookup so the page can show the signed-in user's email
+        instead of 'CLI session connected'. Failures are silent — the page still renders."""
+        if not OAuthCallbackHandler.session_cookie or not OAuthCallbackHandler.public_api_url:
+            return None
+        try:
+            r = httpx.get(
+                f"{OAuthCallbackHandler.public_api_url}/users/me",
+                cookies={"avrea_session": OAuthCallbackHandler.session_cookie},
+                timeout=3.0,
+            )
+            r.raise_for_status()
+            return r.json().get("email")
+        except httpx.HTTPError, ValueError, KeyError:
+            return None
+
+
+def _render_success_html(email: str | None) -> str:
+    """Render the post-login confirmation page. Mirrors the console's
+    ``NotLoggedIn`` layout (LogoMark, Sorts Mill Goudy headline, theme palette).
+    Self-contained: SVG and palette are inlined; the only network fetch is the
+    Google Font."""
+    email_block = f'<p class="email">{html_module.escape(email)}</p>' if email else ""
+    return f"""<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Authenticated · Avrea</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Sorts+Mill+Goudy&amp;display=swap" rel="stylesheet">
+<style>
+:root {{
+  color-scheme: dark;
+  --bg: linear-gradient(306deg, #0e1018 8.16%, #1a1622 89.66%);
+  --fg: #f1f1f1;
+  --muted: #a09aae;
+  --card: #26222e;
+  --card-border: rgba(255, 255, 255, 0.08);
+  --accent: #b7bdeb;
+  --code-bg: #1b1623;
+}}
+* {{ box-sizing: border-box; }}
+html, body {{ margin: 0; padding: 0; min-height: 100dvh; }}
+body {{
+  background: var(--bg);
+  color: var(--fg);
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 16px;
+}}
+.box {{
+  background: var(--card);
+  border: 1px solid var(--card-border);
+  border-radius: 12px;
+  padding: 32px;
+  width: 100%;
+  max-width: 480px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  text-align: center;
+  box-shadow: 0 20px 60px rgba(0, 0, 0, 0.4);
+}}
+.logo {{
+  display: block;
+}}
+.logo svg {{
+  height: 32px;
+  width: auto;
+  display: block;
+}}
+.headline {{
+  font-family: "Sorts Mill Goudy", Iowan Old Style, "Palatino Linotype", Georgia, serif;
+  font-size: 30px;
+  line-height: 1.1;
+  margin: 24px 0 0;
+  color: var(--fg);
+  font-weight: 400;
+}}
+.subhead {{
+  margin: 16px 0 0;
+  font-size: 15px;
+  color: var(--fg);
+}}
+.email {{
+  margin: 6px 0 0;
+  font-size: 14px;
+  color: var(--muted);
+}}
+hr {{
+  border: 0;
+  border-top: 1px solid var(--card-border);
+  margin: 28px 0 24px;
+  width: 100%;
+}}
+.next, .close {{
+  margin: 0;
+  font-size: 14px;
+  color: var(--muted);
+}}
+.code-row {{
+  margin: 12px 0 24px;
+}}
+code {{
+  display: inline-block;
+  background: var(--code-bg);
+  color: var(--accent);
+  padding: 8px 12px;
+  border-radius: 8px;
+  font-family: "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
+  font-size: 13px;
+}}
+</style>
+</head>
+<body>
+  <div class="box">
+    <span class="logo">{_LOGO_SVG}</span>
+    <h1 class="headline">You're all set.</h1>
+    <p class="subhead">Your CLI session is now connected.</p>
+    {email_block}
+    <hr>
+    <p class="next">Head back to your terminal and try:</p>
+    <p class="code-row"><code>&gt; avr status</code></p>
+    <p class="close">You can close this tab now.</p>
+  </div>
+</body>
+</html>
+"""
+
+
+def login(public_api_url: str, *, provider: str = "github") -> str:
+    """
+    Perform browser OAuth login and return the API key.
+    Raises click.Abort on failure.
+    """
+    # Control plane 302s here after the upstream OAuth callback completes;
+    # localhost is not registered with the upstream provider directly —
+    # see oauth.py allowed_redirect_hosts.
+    port = 8765
+    callback_uri = f"http://localhost:{port}/callback"
+
+    # Handler class state must be cleared per-login: BaseHTTPRequestHandler
+    # is instantiated by HTTPServer per-request so we can't pass per-call
+    # values through the constructor, and a prior aborted run would
+    # otherwise leave stale session/csrf values behind.
+    OAuthCallbackHandler.session_cookie = None
+    OAuthCallbackHandler.csrf_token = None
+    OAuthCallbackHandler.public_api_url = public_api_url
+
+    try:
+        server = HTTPServer(("localhost", port), OAuthCallbackHandler)
+    except OSError as e:
+        click.echo(f"Error: Cannot bind to port {port}: {e}", err=True)
+        click.echo("Ensure no other process is using this port and try again.")
+        raise click.Abort() from None
+
+    if provider == "google":
+        auth_url = f"{public_api_url}/oauth/google/login?final_redirect={callback_uri}"
+    elif provider == "github":
+        auth_url = f"{public_api_url}/oauth/github/login?next={callback_uri}"
+    else:
+        raise click.ClickException(f"Unsupported auth provider '{provider}'")
+    click.echo(f"Opening browser to: {auth_url}")
+    click.echo("Waiting for authentication...")
+
+    # AVR_BROWSER takes precedence over BROWSER. Python's webbrowser honors
+    # BROWSER directly, so promote AVR_BROWSER into BROWSER for the open() call.
+    avr_browser = os.environ.get("AVR_BROWSER")
+    saved_browser = os.environ.get("BROWSER")
+    if avr_browser:
+        os.environ["BROWSER"] = avr_browser
+    try:
+        opened = webbrowser.open(auth_url)
+    finally:
+        if avr_browser:
+            if saved_browser is None:
+                os.environ.pop("BROWSER", None)
+            else:
+                os.environ["BROWSER"] = saved_browser
+
+    if not opened:
+        click.echo("Failed to open browser. Please visit:", err=True)
+        click.echo(auth_url)
+
+    server.timeout = 300
+    try:
+        server.handle_request()
+    finally:
+        # Release the listening socket so a retry in the same process (or a
+        # follow-up TUI flow) doesn't hit "Address already in use" while
+        # CPython GC catches up.
+        server.server_close()
+
+    if not OAuthCallbackHandler.session_cookie:
+        click.echo("Error: Authentication failed - no session received", err=True)
+        raise click.Abort()
+
+    # Security note: the session token arrives as a query parameter to localhost.
+    # Query parameters may appear in browser history. The session is short-lived
+    # and exchanged immediately for an API key, then invalidated below.
+    try:
+        headers = {}
+        if OAuthCallbackHandler.csrf_token:
+            headers["X-CSRF-Token"] = OAuthCallbackHandler.csrf_token
+        response = httpx.post(
+            f"{public_api_url}/users/me/api-keys",
+            cookies={"avrea_session": OAuthCallbackHandler.session_cookie},
+            headers=headers,
+            json={"name": f"CLI - {socket.gethostname()}", "expires_days": 90},
+            timeout=10.0,
+        )
+        response.raise_for_status()
+        api_key = response.json()["api_key"]
+
+        try:
+            logout_headers: dict[str, str] = {}
+            if OAuthCallbackHandler.csrf_token:
+                logout_headers["X-CSRF-Token"] = OAuthCallbackHandler.csrf_token
+            httpx.post(
+                f"{public_api_url}/users/me/logout",
+                cookies={"avrea_session": OAuthCallbackHandler.session_cookie},
+                headers=logout_headers,
+                timeout=5.0,
+            )
+        except httpx.HTTPError:
+            pass  # Best-effort; the session will expire on its own
+
+        return api_key
+    except httpx.HTTPError as e:
+        click.echo(f"Error: Failed to create API key: {e}", err=True)
+        raise click.Abort() from None