`gjݕ"dZddlmZddlZddlZddlZddlZddlZddlm Z ddl m Z ddl m Z ddlmZmZmZmZmZmZ ddlZej.eZGdd eZd Zd Zd Zd ZdZ dZ!dZ"ejFdZ$dUdZ%dVdZ&dWdZ'dXdZ(dYdZ)dZdZ*dXdZ+ddd d[dZ,ddddd d\dZ-d]dZ.e GddZ/e d !Gd"d#Z0d^d$Z1d^d%Z2d_d&Z3d`d'Z4dad(Z5dbd)Z6eed* dcd+Z7edddd, ddd-Z8dd. ded/Z9dfd0Z:dgd1Z;dhd2Zdkd5Z?ed dd6 dld7Z@did8ZAdmd9ZBdnd:ZCdod;ZDe dZEdqd?ZFdrd@ZGdsdAZH dtdBZIddddCdD dudEZJddddF dvdGZKdwdHZLdZdIZM dxdJZNdXdKZOdydLZPdzdMZQdNdO d{dPZRd dQ d|dRZSeTfd}dSZUd~dTZVy#e$rdZYwxYw)u Photon Dashboard API client + device-code login flow. This module is pure Python — it intentionally does not depend on ``spectrum-ts``. Every management-plane operation (login, find/create project, rotate the project secret, register a user, list the assigned iMessage line) talks to Photon's **Dashboard API** on a single host, exactly like the official Photon CLI (``photon-hq/cli``): Dashboard API https://app.photon.codes/api/... OAuth 2.0 device flow, Bearer access token A Photon project has a single identifier: the dashboard ``id`` *is* the Spectrum Cloud project id. They used to diverge (a separate ``spectrumProjectId`` field), but the dashboard unified them — every project is created with matching ids and the pre-existing diverged rows were backfilled so ``project.id == spectrumProjectId`` everywhere (dashboard ENG-1582). Spectrum is always enabled and provisioned at create-time, so there is no enable/toggle step anymore. The ``spectrum-ts`` SDK (run by the Node sidecar) authenticates to Spectrum Cloud with ``(id, projectSecret)`` — the same ``id`` used in Dashboard API paths — which we persist as ``PHOTON_PROJECT_ID`` for the runtime. Credential storage mirrors every other Hermes channel: * runtime SDK creds -> ``~/.hermes/.env`` (``PHOTON_PROJECT_ID`` = project id, ``PHOTON_PROJECT_SECRET``) via ``save_env_value`` * management metadata -> ``~/.hermes/auth.json`` under ``credential_pool.photon`` (device token), ``credential_pool.photon_project`` (dashboard id, spectrum id, name), and ``credential_pool.photon_user`` (operator number + assigned text line) Reference: https://github.com/photon-hq/cli and https://photon.codes/docs/api-reference/device-login/request-device-+-user-code ) annotationsN) b64encode) dataclass)Path)AnyCallableDictListOptionalTupleceZdZdZy)PhotonDashboardAuthErrorzERaised when Photon rejects a device-flow token for the dashboard API.N)__name__ __module__ __qualname____doc__P/root/.hermes/venv/lib/python3.12/site-packages/plugins/platforms/photon/auth.pyrr9sOrrz photon-clizopenid profile emailzhttps://app.photon.codeszhttps://spectrum.photon.codesz Hermes Agentiz^\+[1-9]\d{6,14}$c ddlm}t|dz S#t$r.ttj j ddz cYSwxYw)zDResolve ``~/.hermes/auth.json`` honouring the active Hermes profile.rget_hermes_homez auth.jsonz ~/.hermes)hermes_constantsrr Exceptionospath expanduserrs r_auth_json_pathrXsNC4O%&44 CBGG&&{34{BBCs4AAc>t}|jsiS |jdd5}tj|xsicdddS#1swYyxYw#t tj f$r#}tjd||icYd}~Sd}~wwxYw)Nrutf-8encodingzphoton: could not read %s: %s) rexistsopenjsonloadOSErrorJSONDecodeErrorloggerwarning)rfhes r _load_authr/as  D ;;=  YYsWY - '99R=&B ' ' ' T)) *6a@ s:A A A AA A B9BBBcdt}|jjdd|jd}|j dd5}t j ||ddddd tj|d |j|y#1swY2xYw#t$rY)wxYw) NT)parentsexist_okz .json.tmpwr"r#)indent sort_keysi) rparentmkdir with_suffixr&r'dumprchmodr)replace)datartmpr-s r _save_authr?ms  DKKdT2   ; 'C # (6B $156  eKK 66    s B/B#B # B/.B/cvt}|jdijdxsg}t|tr9|r7|djdxs|djd}|r t |S|jdijdi}|jdrt |dSy)zFReturn the device-flow bearer token stored by ``login()`` or ``None``.credential_poolphotonr access_tokentoken providersN)r/get isinstanceliststr)authpoolrDlegacys rload_photon_tokenrMzs BD$$Q N+CtAw{{7/C u:  XXk2 & * *8R 8F zz.!6.)** rct}|ttjdg|jdid<t |y)zBPersist a dashboard bearer token under ``credential_pool.photon``.)rC issued_atrArBNr/inttime setdefaultr?)rDrJs rstore_photon_tokenrTs> 8DOO%r*84trcxtjd}tjd}|r|r||fSt}|jdijdxsg}t |t rF|rD|d}|jdxs|jd}|xs||xs|jdfS||fS) atReturn the runtime SDK creds ``(spectrum_project_id, project_secret)``. Precedence: process env (``~/.hermes/.env`` is loaded into the gateway's environment at startup) wins, then ``auth.json`` for offline / status use. This is the pair the Node sidecar feeds to ``spectrum-ts``; the id is the unified project id (dashboard id == spectrumProjectId). PHOTON_PROJECT_IDPHOTON_PROJECT_SECRETrAphoton_projectrspectrum_project_id project_idproject_secretrgetenvr/rFrGrH)env_idenv_secrJprojentrysids rload_project_credentialsrcsYY* +Fii/0G 'w |r<|d}|jdxs$|jdxs|jdSy) aReturn the project id used for management API calls. Post-unification the dashboard id and the Spectrum id are the same value, so we prefer the stored ``spectrum_project_id``: for pre-backfill installs the old ``dashboard_project_id`` is the diverged id that the unification rewrote (it now 404s), while the Spectrum id always matches the live row. Falls back to the legacy keys for older records. PHOTON_DASHBOARD_PROJECT_IDrArXrrYdashboard_project_idrZNr\)r^rJr`ras rload_dashboard_project_idrgsYY4 5F  sD T=# .F |  &xr2H2N1OP r) client_idscopec t tdtd}d|i}|r||d<tj||d}|j |j }t |d|d|d |jd t|jd xstt|jd xst S)zBPOST ``/api/auth/device/code`` and return the device + user codes.)httpx is required for Photon device loginz/api/auth/device/coderr>@r'timeoutrzr{r|r~rr)rzr{r|r~rr) httpxrrpostraise_for_statusr'ryrFrQDEFAULT_POLL_TIMEOUTDEFAULT_POLL_INTERVAL)rrurlbodyrr=s rrequest_device_coderGs }FGG   4 5C'3D W ::cd 3D 99;D '{#01"&((+F"Gtxx -E1EFTXXj)B-BC  r)rrr on_pendingcvt tdtd}tj|xs|jxst z}||n|j xst}tj|krtj| tj|d|j|dd}|jd k(r_i} |jxsi} t!| t"r| ni} t+| t-|d i } | s td | d j.S|jdk(r|dz }|r t1||jdk(ri} |jxsi} | j3dxs| j3dxsd} | dk(r|r t1|F| dk(r|dz }|r t1|_| dvrtd| td| xs |j4tjd|j|j4dd tj|krt7d#tj$r!} tjd| Yd} ~ d} ~ wwxYw#t$t&tj(f$ri} YwxYw#tj($rYIwxYw)aPoll ``/api/auth/device/token`` until the user approves. Mirrors the official CLI's polling loop: sleep first, then poll; ``authorization_pending`` keeps the interval, ``slow_down`` adds 5s, HTTP 429 adds 10s, and ``access_denied`` / ``expired_token`` abort. The bearer token comes from the response body's top-level ``access_token`` (better-auth device-grant shape), with ``session.access_token`` and the ``set-auth-token`` header kept as fallbacks for API drift. Nrz/api/auth/device/tokenz,urn:ietf:params:oauth:grant-type:device_code) grant_typerzrrrz$photon: device-token poll failed: %srheadersrzPhoton returned 200 but no token candidate in the device-token response (expected access_token, data.access_token, accessToken, or set-auth-token).ri rrrrauthorization_pending slow_downr) expired_token access_deniedzPhoton login failed: zPhoton device token error: z-photon: device-token unexpected status %s: %szPhoton device login timed out)rrrrRrrrrsleeprrz RequestErrorr+r,rr'rGr TypeError ValueErrorr*!_device_response_token_candidatesrrD_saferFr TimeoutError)coderrrrrdeadlinerrr.rdecoded candidateserrs rpoll_for_tokenr^s& }FGG   5 6Cyy{gPP.adds:#E*  /vUKLrrC accessTokensessionzsession.access_tokenr=zdata.access_tokenzdata.accessTokenzset-auth-token)rrIrrreturnNone)setrFrGr _header_value)rrrrr=rrs @@rrrsJDM01 txx ./hhy!G'4  "GKK$?@ 88F D$ .!9:  78-1ABC rct|tsy|j}|jj dr|ddj}|xsdS)Nzbearer )rGrIstriplower startswith)rrDs rrrsJ eS ! KKME {{} *ab ! =DrcL|sy |j|}|r t|S t|j D]?\}}t|j |j k(s1|s4t|cS y#t$rYiwxYw#t tf$rYywxYwN)rFrIAttributeErrorritemsrrr)rrhrrs rrrs   D! u:  w---/ "JC3x~~4::</E5z! "     z "s5BA B/B2 B?B B BB#"B#czt tdt|}tj|dd|idS)Nrrrrrr)rrrrF)rrDrs r_dashboard_getrsK }FGG   v &C 99  GE7"34 rcztd|}|jdvr td|j|j }t |t r|jdnd}t |t r|s tdtd|}|jdvr td|j|S) acVerify a device-flow token is usable for dashboard project APIs. The device flow can return a token that authenticates the Better Auth session lookup but is rejected by the project APIs. Validate against ``/api/auth/get-session`` and ``/api/projects/`` so we fail loudly at login instead of saving a token that 404s/401s downstream. /api/auth/get-session)iizKPhoton issued a device token, but the dashboard session lookup rejected it.userNzTPhoton issued a device token, but the dashboard session lookup did not recognize it./api/projects/zXPhoton device token was accepted for the session lookup but rejected by the project API.)rrrrr'rGrrF)rDrr=r projects_resps rvalidate_photon_tokenrs 15 9D :%&     99;D)$5488F 4D dD !& $  ##3U;M  J.& +  ""$ KrcP|s tdd}d}|D]%} t|j|jcS|.dj d|Dxsd}t|d|d|||td#t$r}|}|}Yd}~yd}~wt$r }|}Yd}~d}~wwxYw) zBReturn the first candidate token that passes dashboard validation.zHPhoton returned 200 but no token candidate in the device-token response.Nz, c34K|]}|jywr)r).0cs r z-_validated_dashboard_token..4s9AHH9snonez@ Device login returned no project-valid dashboard token (tried: z).z.Photon did not return a usable dashboard token)rrrDrrjoin)rdashboard_error last_error candidateexcsourcess r_validated_dashboard_tokenrs    ;?O*.J    !)// 2?? " "))9j99CV& ''.ir 3   G HH( !OJ  J  s# A;; B%B  B%B  B%c2 |y#t$rYywxYwr)r)fns rrr>s      s  )r open_browser on_user_codec,t|rtfd|r2 ddl}jxs j}|j |dt|}td|g}t|}t||S#t $rY>wxYw) zRun the full device-code login flow and persist the token. Returns the bearer token. ``on_user_code`` receives the :class:`DeviceCode` so callers can print it + optionally open a browser. )rcSrr)rrsrz#login_device_flow..Rs l4(rrNr4)newpollr) rr webbrowserr~r|r&rrrrrT) rrrr target first_tokenrrDrs ` @rlogin_device_flowrEs  3D ()  33Lt7L7LF OOFO *!;K'v[IJJ &z 2Eu L   s1B BBct tdtd}tj|t |d}|j |j xsiS)uEGET ``/api/auth/get-session`` — confirm the token + fetch the user.httpx is required for Photonrrr)rrrrFrrr'rDrrs r get_sessionresW }9::   4 5C 99S'%.$ ?D 99; "rc t|tr|St|trkdD]f}|j|}t|tr|cSt|ts9dD])}|j|}t|ts%|ccShgS)N)r=projectsuserslinesr)rrrr)rGrHrrF)r=rinner nested_keynesteds r _unwrap_listrrs$ $B &CHHSME%& %&"I&J"YYz2F!&$/% &  & Irct tdtd}tj|t |d}|j t |jS)u7GET ``/api/projects`` — return the caller's projects.r /api/projectsrrrrrrFrrrr'rs r list_projectsrsV }9::   } -C 99S'%.$ ?D  $$rc|xsdjj}t|D]:}|jdxsdjj|k(s8|cSy)z?Return the first project whose name matches (case-insensitive).rrhN)rrrrF)rDrhr r`s rfind_project_by_namer scjb   ! ' ' )Fe$ HHV  " ) ) + 1 1 3v =K rz United States)rhlocationcXt tdtd}||ddd}tj||t |d}|j |j xsi}|jdrtd|d|jd s td |S) zPOST ``/api/projects`` and return ``{success, id}``. Spectrum is always provisioned at create-time, so the request body no longer carries a ``spectrum`` flag (the field was dropped from the API). z-httpx is required for Photon project creationrF)rhr!template observabilityrr'rrrzPhoton create-project failed: idz1Photon create-project did not return a project idrrrrrrr'rF)rDrhr!rrrr=s rcreate_projectr(s }JKK   } -C D ::cgend KD 99; "D xx;DM?KLL 88D>NOO Krcft tdtd|d}tj|it |d}|j |j xsi}|jdrtd|d|jd}|s td t|S) uPOST ``/api/projects/{id}/regenerate-secret`` → the new project secret. This is the only way to read a project secret (the dashboard shows it exactly once), so callers should persist the returned value immediately. rrz/regenerate-secretrr%rz!Photon regenerate-secret failed: projectSecretz2Photon regenerate-secret returned no projectSecret) rrrrrrr'rFrI)rDrZrrr=secrets rregenerate_project_secretr,s  }9::   ~j\9K LC ::cGEND ID 99; "D xx>tG}oNOO XXo &F OPP v;rc8tjdd|xsdS)z?Reduce a phone string to ``+`` and digits for dedup comparison.z[^\d+]r)resub)phones r_normalize_phoner1s 66)R" --rct tdtd|d}tj|t ||d}t |dt |jS)uDGET Spectrum Cloud ``/projects/{id}/users/`` → ``SpectrumUser[]``.r /projects//users/rrz list-users)rrrrFrrrr')rZr[rrs r list_usersr5s] }9::   j G 2  D dM* 99; "D xx8gHII 88F  7txx/ 74D$ K LLr)r9r:r;cRt|||}||dfSt||||||}|dfS)uIdempotently register a Spectrum user. Returns ``(user, created)`` — ``created`` is False when a user with the same phone number already exists (the official CLI does no dedup, so we add it here to make ``setup`` safely re-runnable). F)rnr9r:r;T)r8rE)rZr[rnr9r:r;existingrs rregister_user_if_absentrHsJ"*nlKH !  D :rcH|sy|jd}|r t|SdS)uReturn the iMessage number a Spectrum user is assigned to text on. This is the user's ``assignedPhoneNumber`` (the dashboard's "TEXTS ON" column) — i.e. the number to text to reach the agent, as opposed to the user's own ``phoneNumber``. On shared-number plans there is no dedicated entry in ``/lines``, so this per-user field is the source of truth. Returns ``None`` when unset (e.g. a freshly created, not-yet-assigned user). NassignedPhoneNumber)rFrI)rrs ruser_assigned_linerK,s*  ((( )C3s8$$rct}|jdijdxsg}t|tr|r|dxsi}t|trs|jdxs|jd}|jdxs|jd}|s|r'|r t |n t |r t |fSdfSt dfS) zEReturn ``(operator_phone_number, assigned_phone_number)`` for status.rArrrrnr7rorJN)r/rFrGrHrrI_configured_operator_phone)rJ user_entriesrar0assigneds rload_user_numbersrP;s ()HC#&3=F<,/L]F=')OE8Q >"K "# !L"VN%;;"VL%99"VM%::"VN%;;"V,C%DD D 4rcldd}dd}dd}dd}dd}|||||dS)zEReturn a fully pre-formatted credential status dict (no raw secrets).ctrdSdS)Nrrrs)rMrrr_present_tokenz*credential_summary.._present_tokens-/L : rc(t\}}|xsdS)Nrurc)rb_secs r_present_project_idz/credential_summary.._present_project_ids,. T#m#rc(t\}}|rdSdS)Nrrrur)_sidr{s r_present_secretz+credential_summary.._present_secrets,. c"|5 5rc(t\}}|xsdS)NrwrP)r0 _assigneds r_present_phonez*credential_summary.._present_phones,.yMMMrc(t\}}|xsdS)Nrsr)_phonerOs r_present_assigned_phonez3credential_summary.._present_assigned_phone s,.DDDr)rtrZrvrnrorrIr)rrrrrs rcredential_summaryrsG $6NE '()+&(&(!8!:  r)rr)rDict[str, Any])r=rrr)rr})rDrIrr)r#Tuple[Optional[str], Optional[str]]) rYrIr[rIrfr}rhr}rr) rnr}ror}rpr}rfr}rr)rYrIr[rIrrr)rDrIrDict[str, str])rZrIr[rIrr)rrrrI)rrrrIrr)rrIrr}rry) rryrrIr Optional[int]rrrzOptional[Callable[[], None]]rrI)rrr Optional[Any]rrH)rrrr})rrrhrIrr})rrIrDrIrr)rDrIrr)rrHrrI)rzCallable[[], None]rr)rrIrboolrz(Optional[Callable[['DeviceCode'], None]]rrI)r=rrList[Dict[str, Any]])rDrIrr)rDrIrhrIrOptional[Dict[str, Any]])rDrIrhrIr!rIrr)rDrIrZrIrrI)r0rIrrI)rZrIr[rIrr)rZrIr[rIrnrIrr)rZrIr[rIrnrIr9r}r:r}r;r}r<rrr)rZrIr[rIrnrIr9r}r:r}r;r}rzTuple[Dict[str, Any], bool])rrrr})rZrIr[rIrr)rrIrr})rDrIrZrIrr)rDrIrZrIrmrIrr)rDrIrZrIrTrrr)ryrrr)rr)Wr __future__rr'loggingrr.rRbase64r dataclassesrpathlibrtypingrrr r r r rrw getLoggerrr+rrDEFAULT_CLIENT_ID DEFAULT_SCOPErrDEFAULT_PROJECT_NAMErrcompilerBrr/r?rMrTrcrgrlrsrjryrrrrrrrrrrrrrrrrrrrrr r(r,r1r5r8rErHrKrPr\rMr`rjrorVprintr}rrrrrsz#H#  !==   8 $P|P!& 37& "**) * C   ,8+/ >>>( >  >  >B#'+/!*. )  (   0O,   $ VT0/ 6*-2?4'!"/3 U8 U8U8 U8  U8 - U8 U8v"     F$@I> '=A ;   @  %%#      <.. %%(8; !%#(M(M(M (M  (M  (M (M(M(M`!%#      !: %.(..%(.(.b*%5?$ $$.1$$$?C 7;.*/#LK EsHH H