)j8vdZddlmZddlZddlZddlZddlZddlZddlm Z ddl m Z ddl m Z ddlmZmZmZmZmZmZ ddlZn #e$rdZYnwxYwejeZGdd eZd Zd Zd Zd ZdZ dZ!dZ"ej#dZ$ddZ%ddZ&ddZ'ddZ(ddZ)dd Z*dd!Z+ddd"dd'Z,ddddd(dd,Z-dd-Z.e Gd.d/Z/e d01Gd2d3Z0dd4Z1dd5Z2dd7Z3dd9Z4dd<Z5dd>Z6eed?ddBZ7eddddCddJZ8ddKddPZ9ddRZ:ddSZ;ddUZdd[Z?ed0dd\ddaZ@ddbZAdddZBddeZCddgZDddhZEe didjddlZFddmZGddnZHddpZIddqZJddrZKddddsdtddyZLddddzdd|ZMdd~ZNddZOddZPddZQddZRddZSddddZTd0dddZUeVfddZWddZXdS)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, enable Spectrum, 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 carries two distinct identifiers: * ``id`` — the Dashboard project id (used in API paths) * ``spectrumProjectId`` — the Spectrum Cloud project id, populated when Spectrum is enabled on the project The ``spectrum-ts`` SDK (run by the Node sidecar) authenticates to Spectrum Cloud with ``(spectrumProjectId, projectSecret)`` — so the value we persist as ``PHOTON_PROJECT_ID`` for the runtime is the **spectrumProjectId**, not the Dashboard ``id``. The Dashboard ``id`` is kept only for management calls. Credential storage mirrors every other Hermes channel: * runtime SDK creds -> ``~/.hermes/.env`` (``PHOTON_PROJECT_ID`` = spectrumProjectId, ``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)AnyCallableDictListOptionalTupleceZdZdZdS)PhotonDashboardAuthErrorzERaised when Photon rejects a device-flow token for the dashboard API.N)__name__ __module__ __qualname____doc__B/home/ubuntu/.hermes/hermes-agent/plugins/platforms/photon/auth.pyrr9sOOOOrrz photon-clizopenid profile emailzhttps://app.photon.codeszhttps://spectrum.photon.codesz Hermes Agentiz^\+[1-9]\d{6,14}$returnrc ddlm}t|dz S#t$r2ttjddz cYSwxYw)zDResolve ``~/.hermes/auth.json`` honouring the active Hermes profile.rget_hermes_homez auth.jsonz ~/.hermes)hermes_constantsrr Exceptionospath expanduserrs r_auth_json_pathr Xs}C444444OO%%&&44 CCCBG&&{3344{BBBBCs"9AADict[str, Any]c\t}|siS |dd5}tj|picdddS#1swxYwYdS#t tjf$r(}td||icYd}~Sd}~wwxYw)Nrutf-8encodingzphoton: could not read %s: %s) r existsopenjsonloadOSErrorJSONDecodeErrorloggerwarning)rfhes r _load_authr1as   D ;;==  YYsWY - - '9R==&B ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' T) *6a@@@ s@A-A  A- A$$A-'A$(A--B+B& B+&B+dataNonect}|jdd|d}|dd5}t j||dddddn #1swxYwY tj|d n#t$rYnwxYw| |dS) NT)parentsexist_okz .json.tmpwr$r%)indent sort_keysi) r parentmkdir with_suffixr(r)dumprchmodr+replace)r2rtmpr/s r _save_authrBms   DKdT222   ; ' 'C # ( (6B $15555666666666666666  e      KKs$A<<BBB B+*B+ Optional[str]ct}|didpg}t|trI|rG|ddp|dd}|rt |S|didi}|drt |dSdS)zFReturn the device-flow bearer token stored by ``login()`` or ``None``.credential_poolphotonr access_tokentoken providersN)r1get isinstanceliststr)authpoolrHlegacys rload_photon_tokenrQzs <BD$$Q N++CtAw{{7/C/C  u::  XXk2 & & * *8R 8 8F zz.!!+6.)*** 4rrHrMct}|ttjdg|did<t |dS)zBPersist a dashboard bearer token under ``credential_pool.photon``.)rG issued_atrErFNr1inttime setdefaultrB)rHrNs rstore_photon_tokenrXsU <>8DOO%r**84tr#Tuple[Optional[str], Optional[str]]ctjd}tjd}|r|r||fSt}|didpg}t |t rO|rM|d}|dp|d}|p||p|dfS||fS) ulReturn 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 **spectrumProjectId**, not the Dashboard id. PHOTON_PROJECT_IDPHOTON_PROJECT_SECRETrEphoton_projectrspectrum_project_id project_idproject_secretrgetenvr1rJrKrL)env_idenv_secrNprojentrysids rload_project_credentialsrhsY* + +Fi/00G 'w <)=%& v@FxDOO%r**+;<t,n=====r phone_numberassigned_phone_numberuser_idrkrsrtruc|s|sdSt}dttji}|r||d<|r||d<|r||d<|r||d<|g|did<t |dS) zEPersist non-secret Photon user numbers for offline ``status`` output.NrSrsrtrurkrE photon_userrT)rsrtrurkrNrps rstore_user_numbersrxs  5 <)=%&=CHDOO%r**=9trc ddlm}n+#t$rtdYdSwxYw |d||d|dS#t $r&}td|Yd}~dSd}~wwxYw)u'Write the SDK creds to ``~/.hermes/.env`` (canonical runtime store). Isolated in its own helper so the secret value flows straight into ``save_env_value`` without ever being bound to a printable local in a caller — same CodeQL-clean-flow rationale as the rest of this module. r)save_env_valueu=photon: hermes_cli.config unavailable — skipping .env writeNr[r\z1photon: could not write project creds to .env: %s)hermes_cli.configrz ImportErrorr-r.r)r^r`rzr0s rroros4444444 VWWWO*,?@@@.????? OOOJANNNNNNNNNOs# $11A A?A::A?cLeZdZUded<ded<ded<ded<ded<ded <d S) DeviceCoderM device_code user_codeverification_urirCverification_uri_completerU expires_inintervalN)rrr__annotations__rrrr~r~sONNN,,,,OOOMMMMMrr~T)frozenc(eZdZUdZded<ded<dS)_DeviceTokenCandidatez@r)timeoutrrrrrr)rrrrrr) httpxrrpostraise_for_statusr)r~rJrUDEFAULT_POLL_TIMEOUTDEFAULT_POLL_INTERVAL)rrurlbodyrr2s rrequest_device_coder;s }FGGG    5 5 5C'3D W :cd 3 3 3D 99;;D '{#01"&((+F"G"Gtxx --E1EFFTXXj))B-BCC    r)rrr on_pendingcoder Optional[int]rrOptional[Callable[[], None]]cttdtd}tj|p |jpt z}||n |jpt}tj|krBtj| tj |d|j |dd}n7#tj $r%} t d| Yd} ~ }d} ~ wwxYw|jd kri} |pi} t!| t"r| ni} n$#t$t&tjf$ri} YnwxYwt+| t-|d i } | std | d jS|jdkr|dz }|rt1|H|jdkri} |pi} n#tj$rYnwxYw| dp| dpd} | dkr|rt1|| dkr|dz }|rt1|| dvrtd| td| p|jt d|j|jdd tj|kBt7d)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_typerrrrz$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)rrrrVrrrrsleeprr RequestErrorr-r.rr)rKr TypeError ValueErrorr,!_device_response_token_candidatesrrH_saferJr TimeoutError)rrrrrrdeadlinerrr0rdecoded candidateserrs rpoll_for_tokenrRsS& }FGGG    6 6 6Cy{{gPP|d |d|d|d |dt |dS)a}Extract de-duplicated token candidates from a device-token response. Photon's device-token endpoint has returned tokens under several keys across versions (``access_token``, ``accessToken``, ``data.*``) and the documented ``set-auth-token`` response header. We collect every shape so the caller can validate each against the dashboard API before trusting it. rrMvaluerrr3ct|}|r|vrdS|t||dS)NrrH)_clean_bearer_tokenaddappendr)rrrHrseens rrz._device_response_token_candidates..adds\#E**  F /vUKKKLLLLLrrG accessTokensessionzsession.access_tokenr2zdata.access_tokenzdata.accessTokenzset-auth-token)rrMrrrr3)setrJrKr _header_value)rrrrr2rrs @@rrrsDJDMMMMMMMC00111C txx ..///hhy!!G'4  A  "GKK$?$?@@@ 88F  D$9  .!9!9:::   7 7888C-1ABBCCC rrct|tsdS|}|dr|dd}|pdS)Nzbearer )rKrMstriplower startswith)rrHs rrrse eS ! !t KKMME {{}} **"abb !! =Drc|sdS ||}|rt|Sn#t$rYnwxYw t|D]O\}}t||kr|rt|cSPn#t tf$rYdSwxYwdSN)rJrMAttributeErrorritemsrrr)rrmrrs rrrs t  D!!  u::        w----// " "JC3xx~~4::<<//E/5zz!!! " z "tt 4s$%- ::A/B0.B00CCrcttdt|}tj|dd|idS)Nrrrrrr)rrrrJ)rrHrs r_dashboard_getrs\ }FGGG    & & &C 9  "3E"3"34   rctd|}|jdvrtd||}t |t r|dnd}t |t r|stdtd|}|jdvrtd||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)rKrrJ)rHrr2r projects_resps rvalidate_photon_tokenrs 15 9 9D :%%&      99;;D)$55 ?488F   4D dD ! !  & $   ##3U;;M J..& +   ""$$$ Krrcf|stdd}d}|D]N} t|j|jcS#t$r}|}|}Yd}~3d}~wt$r }|}Yd}~Gd}~wwxYw|7dd|Dpd}t|d|d|||td) zBReturn the first candidate token that passes dashboard validation.zHPhoton returned 200 but no token candidate in the device-token response.Nz, c3$K|] }|jV dSr)r).0cs r z-_validated_dashboard_token..(s$99AH999999rnonez@ Device login returned no project-valid dashboard token (tried: z).z.Photon did not return a usable dashboard token)rrrHrrjoin)rdashboard_error last_error candidateexcsourcess r_validated_dashboard_tokenrs9      ;?O*.J     !)/ 2 2 2? " " "'   !OJ HHHH   J HHHH "))99j99999CV& 3 3'. 3 3 3    G H HHs!8 A$A  A$AA$fnCallable[[], None]c> |dS#t$rYdSwxYwr)r)rs rrr2s8        s  )r open_browser on_user_coder boolr (Optional[Callable[['DeviceCode'], None]]cPt|rtfd|r; ddl}jpj}||dn#t $rYnwxYwt|}td|g}t|}t||S) 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)rr srz#login_device_flow..Fsll4((rrNr8)newpollr) rr webbrowserrrr(rrrrrX) rr r rtarget first_tokenrrHrs ` @rlogin_device_flowr9s  3 3 3D* ((((()))     3Lt7LF OOFO * * * *    D  !;;;K'v[IIIJJ &z 2 2Eu Ls)A A"!A"cttdtd}tj|t |d}||piS)uEGET ``/api/auth/get-session`` — confirm the token + fetch the user.Nhttpx is required for PhotonrrrrrrrJrrr)rHrrs r get_sessionrYsk }9:::    5 5 5C 9S'%..$ ? ? ?D 99;; "rList[Dict[str, Any]]cXt|tr|St|tr}dD]z}||}t|tr|cSt|tr5dD]2}||}t|tr|ccS3{gS)N)r2projectsuserslinesr)rr r!r)rKrLrrJ)r2rinner nested_keynesteds r _unwrap_listr%fs$ $ &B & &CHHSMME%&&  %&& &"I&&J"YYz22F!&$//&% & Ircttdtd}tj|t |d}|t |S)u7GET ``/api/projects`` — return the caller's projects.Nr /api/projectsrrrrrrJrrr%r)rs r list_projectsr)vsn }9:::    - - -C 9S'%..$ ? ? ?D  $ $$rOptional[Dict[str, Any]]c|pd}t|D]E}|dpd|kr|cSFdS)z?Return the first project whose name matches (case-insensitive).rrmN)rrr)rJ)rHrmrres rfind_project_by_namer,sjb   ! ! ' ' ) )Fe$$ HHV   " ) ) + + 1 1 3 3v = =KKK > 4rcttdtd|}tj|t |d}||piS)uMGET ``/api/projects/{id}`` — includes ``spectrum`` + ``spectrumProjectId``.NrrrrrrHr_rrs r get_projectr/sp }9:::    : :j : :C 9S'%..$ ? ? ?D 99;; "rz United States)rmlocationr0cttdtd}||dddd}tj||t |d}||pi}|d rtd |d |d std |S) zLPOST ``/api/projects`` with ``spectrum: true`` and return ``{success, id}``.Nz-httpx is required for Photon project creationr'TF)rmr0spectrumtemplate observabilityrr)rrrzPhoton create-project failed: idz1Photon create-project did not return a project idrrrrrrr)rJ)rHrmr0rrrr2s rcreate_projectr8s }JKKK    - - -C D :cgennd K K KD 99;; "D xxMKDMKKLLL 88D>>PNOOO Krc~ttdt||}|ds]t d|d}tj|it |d}|t||}|dstd |S) zEnable Spectrum on the project if needed; return the project dict. The dashboard exposes Spectrum as a toggle, so we only flip it when ``spectrum`` is currently false, then re-fetch to pick up the freshly populated ``spectrumProjectId``. Nrr2rz/spectrum/togglerr5spectrumProjectIdu~Spectrum is enabled but the project has no spectrumProjectId yet — retry in a moment, or enable Spectrum from the dashboard.)rrr/rJrrrr)rHr_rerrs rensure_spectrum_enabledr;s }9::: uj ) )D 88J  . ""NN*NNNz#BMMM 5*-- 88' ( (  H    Krcttdtd|d}tj|it |d}||pi}|drtd|d|d }|std 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. Nrrz/regenerate-secretrr5rz!Photon regenerate-secret failed: projectSecretz2Photon regenerate-secret returned no projectSecret) rrrrrrr)rJrM)rHr_rrr2secrets rregenerate_project_secretr?s  }9:::    L Lj L L LC :cGENND I I ID 99;; "D xxPNtG}NNOOO XXo & &F QOPPP v;;rphonec2tjdd|pdS)z?Reduce a phone string to ``+`` and digits for dedup comparison.z[^\d+]r)resub)r@s r_normalize_phonerDs 6)R" - --rcttdtd|d}tj|t ||d}t |dt |S)uDGET Spectrum Cloud ``/projects/{id}/users/`` → ``SpectrumUser[]``.Nr /projects//users/rrz list-users)rrrrJrrr%r))r_r`rrs r list_usersrHsx }9:::    < < < < 22    D dM*** 99;; "D xxJHgHHIII 88F   7txx// 74D$ K L LLr)rLrMrNTuple[Dict[str, Any], bool]cbt|||}||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). NF)rsrLrMrNT)rKrX)r_r`rsrLrMrNexistingrs rregister_user_if_absentr\!sW"*nlKKH !    D :rrcZ|sdS|d}|rt|ndS)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)rJrM)rrs ruser_assigned_liner_>s8 t ((( ) )C $3s888$rct}|didpg}t|tr|r|dpi}t|tr|dp|d}|dp|d}|s|r2|rt |n t |rt |ndfSt dfS) zEReturn ``(operator_phone_number, assigned_phone_number)`` for status.rErwrrsrJrtr^N)r1rJrKrLrrM_configured_operator_phone)rN user_entriesrfr@assigneds rload_user_numbersrdMs < E: CCC C    NNOQR S S S44444  4sA B $BB emitc i}trdnd|d<t\}}|r|nd|d<tpd|d<|rdnd|d<t\}}|r|nd |d <|r|nd|d <d d d|dzd|dzd|dzd|dzd|d zd|d zg}|d|dS)uRPretty-print the credential status table via the *emit* callback. Every secret-bearing read is reduced to a display literal inside this function (``"✓ stored"`` / ``"✗ missing"`` / a non-secret id); the callback only ever receives the assembled banner string, so no tainted value escapes into the caller's scope. ✓ stored'✗ missing (run `hermes photon setup`) device_token ✗ missingr^—rk project_key3✗ missing (run `hermes photon setup --phone ...`)rsrtzPhoton iMessage statusuB──────────────────────z device token : z dashboard project : z spectrum project id : z project secret : z my number : z assigned number :  N)rQrhrlrdr)rlabelsrgsecr@rcrowss rprint_credential_summaryrs8 F)++ 7 6 >())HC+.$ACCMF !%>%@%@%IEF !",/BLL]F='))OE8QQ >K"K "# !L"VN%;;"V,B%CC"V,A%BB"VM%::"VN%;;"V,C%DD D D4rcd d}d d}d d}d d}d d}|tpd||||d S) zEReturn a fully pre-formatted credential status dict (no raw secrets).rrMc&trdndS)Nrr)rQrrr_present_tokenz*credential_summary.._present_token s-// ;LL: rc,t\}}|pdS)Nrrh)rg_secs r_present_spectrum_idz0credential_summary.._present_spectrum_ids,.. T#m#rc0t\}}|rdndS)Nrrr)_sidrs r_present_secretz+credential_summary.._present_secrets ,.. c"5|| 5rc,t\}}|pdS)Nrrd)r@ _assigneds r_present_phonez*credential_summary.._present_phones,..yMMMrc,t\}}|pdS)Nrr)_phonercs r_present_assigned_phonez3credential_summary.._present_assigned_phones,..DDDrr)rrkr^rrsrtrrM)rl)rrrrrs rcredential_summaryr s    $$$$6666NNNNEEEE '(( 9 ; ; Du3355&((&((!8!8!:!:   r)rr)rr!)r2r!rr3)rrC)rHrMrr3)rrY) r^rMr`rMrkrCrmrCrr3) rsrCrtrCrurCrkrCrr3)r^rMr`rMrr3r)rHrMrr)r_rMr`rMrr)rrrrM)rrrrMrr3)rrMrrCrr~) rr~rrMrrrrrrrrM)rr!rrrrL)rrrrC)rrrmrMrrC)rrMrHrMrr)rHrMrr!)rrLrrM)rr rr3)rrMr r r rrrM)r2rrr)rHrMrr)rHrMrmrMrr*)rHrMr_rMrr!)rHrMrmrMr0rMrr!)rHrMr_rMrrM)r@rMrrM)r_rMr`rMrr)r_rMr`rMrsrMrr*)r_rMr`rMrsrMrLrCrMrCrNrCrOr rr!)r_rMr`rMrsrMrLrCrMrCrNrCrrY)rr*rrC)r_rMr`rMrrY)rrMrrC)rHrMr_rMrr)rHrMr_rMrrMrr!)rHrMr_rMrhr rr*)rrrr3)rr)Yr __future__rr)loggingrrBrVbase64r dataclassesrpathlibrtypingrrr r r r rr| getLoggerrr-rrDEFAULT_CLIENT_ID DEFAULT_SCOPErrDEFAULT_PROJECT_NAMErrcompilerUr r1rBrQrXrhrlrqrxror~rrrrrrrrrrrrrrrrrrr%r)r,r/r8r;r?rDrHrKrXr\r_rdrprartr~rrjprintrrrrrrs##H#"""""  !!!!!!================LLLL EEE  8 $ $PPPPP|PPP!& 37& "*) * * CCCC            ,     +/ >>>>>>B#'+/!*. 0OOOO,   $ VVVVTTTT0000//// 6 6 6 6*-4'!"/3 U8U8U8U8U8U8v"      F$@IIII>    '=A @     %%%%%# 6...... %%%% !%#(M(M(M(M(M(M`!%#: % % % %....(....b*%%%%5?$$$$$$$?C.*/#####LsAAA