epjdZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl m Z ddl m Z ddlmZddlmZmZmZmZmZmZ ddlZn #e$rdZYnwxYwddlmZdd lmZdd Zeje Z!Gd d e"Z#d Z$dZ%dZ&dZ'dZ(dZ)dZ*ej+dZ,ddZ-ddZ.ddZ/ddZ0dd!Z1dd"Z2dd$Z3dd&Z4dd'Z5ddd(dd-Z6ddddd.dd2Z7dd3Z8e Gd4d5Z9e d67Gd8d9Z:dd:Z;dd;ZddBZ?ddDZ@e$e%dEddHZAe$ddddIddPZBddQddVZCddXZDddYZEdd[ZFdd\ZGdd^ZHddaZIe$d6ddbddfZJddgZKddiZLddjZMddlZNe(dmdnddpZOddqZPddsZQddtZRdduZSddddvdwdd|ZTdddd}ddZUddZVddZWddZXddZYddZZddZ[ddddZ\d6dddZ]e^fddZ_ddZ`dS)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)AnyCallableDictListOptionalTuple)UnscopedSecretError) get_secretcz t||}n$#t$rtj|}YnwxYw||n|S)aScope-aware credential read with the default-profile startup fallback. Secondary profiles construct their adapters under a profile secret scope -- the scope is authoritative and a scoped miss returns ``default`` (no cross-profile borrow from ``os.environ``, which may hold another profile's value). The DEFAULT profile's adapter constructs and sends *unscoped* under multiplexing, where a bare ``get_secret`` would raise ``UnscopedSecretError`` and crash this path; there ``os.environ`` is that profile's own value, so fall back to it. Same pattern as the Slack ``SLACK_APP_TOKEN`` read (#59739) and ``gateway/platforms/whatsapp_common.py::_get_wsecret``. )_scoped_get_secret_UnscopedSecretErrorosgetenv)namedefaultvals C/home/thesage/.hermes/hermes-agent/plugins/platforms/photon/auth.py_get_scoped_secretr<sR w// ioo/33w.s 44ceZdZdZdS)PhotonDashboardAuthErrorzERaised when Photon rejects a device-flow token for the dashboard API.N)__name__ __module__ __qualname____doc__rrrSsOOOOr rz 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_constantsr%r Exceptionrpath expanduserr$s r_auth_json_pathr*rs}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)r(fhes r _load_authr;{s   D ;;==  YYsWY - - '9R==&B ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' T) *6a@@@ s@A-A  A- A$$A-'A$(A--B+B& B+&B+dataNonect}|jdd||jdt jdtjj }t j t|t j t j zt jztjtjz} t j|dd}n[#t&$rN t j|n#t*$rYnwxYw |n#t*$rYnwxYwwxYw |5t/j||dd |t j|dddn #1swxYwY||dS#t&$r( |n#t*$rYnwxYwwxYw) NT)parentsexist_okz.tmp..wr.r/)indent sort_keys)r*parentmkdir with_namerrgetpiduuiduuid4hexr2strO_WRONLYO_CREATO_EXCLstatS_IRUSRS_IWUSRfdopen BaseExceptioncloser5unlinkr3dumpflushfsyncfilenoreplace)r<r(tmpfdr9s r _save_authr_sJ   DKdT222 ..DILLBIKKLL$*,,:JLL M MC  C bj 29, t|#  B  Yr3 1 1 1      HRLLLL    D   JJLLLL    D      " " IdBqD 9 9 9 9 HHJJJ HRYY[[ ! ! ! " " " " " " " " " " " " " " " D   JJLLLL    D  sC++ E6D  E DEDED10E1 D>;E=D>>EG AF( G (F,,G /F,0G G<G*)G<* G74G<6G77G< 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)r;get isinstancelistrM)authpoolrelegacys rload_photon_tokenrms <BD$$Q N++CtAw{{7/C/C  u::  XXk2 & & * *8R 8 8F zz.!!+6.)*** 4r rerMcddlm}|5t}|tt jdg|did<t |ddddS#1swxYwYdS)zBPersist a dashboard bearer token under ``credential_pool.photon``.r_auth_store_lock)rd issued_atrbrcNhermes_cli.authrpr;inttime setdefaultr_)rerprjs rstore_photon_tokenrws000000    ||"TY[[1A1A B B< )2..x8 4 sAA77A;>A;c0t}|di}|dg}t|tr|rg|d<t ||di}d|vri|d<t |dSdS)zRemove any stored Photon dashboard token from auth.json. Used to discard a stale/expired token before re-authentication. rbrcrfN)r;rgrhrir_)rjrkrcrfs rclear_photon_tokenrys < "  D.CF* +  ( 'F9   B-AF) *AG)2..}=4                  sA6BB!Bc 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 writeNrrz1photon: could not write project creds to .env: %s)hermes_cli.configr ImportErrorr7r8r')rrrr:s rrrds4444444 VWWWO*,?@@@.????? OOOJANNNNNNNNNOs# $11A A?A::A?cLeZdZUded<ded<ded<ded<ded<ded <d S) DeviceCoderM device_code user_codeverification_urir`verification_uri_completert expires_inintervalN)rrr__annotations__rr rrrzsONNN,,,,OOOMMMMMr rT)frozenc(eZdZUdZded<ded<dS)_DeviceTokenCandidatez@r3timeoutrrrrrr)rrrrrr) httpxrrpostraise_for_statusr3rrgrtDEFAULT_POLL_TIMEOUTDEFAULT_POLL_INTERVAL)rrurlbodyrr<s rrequest_device_coders }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)rrrrurrrrsleeprr RequestErrorr7r8rr3rhr TypeError ValueErrorr6!_device_response_token_candidatesrre_safergr TimeoutError)rrrrrrdeadlinerrr:rdecoded candidateserrs rpoll_for_tokenrsS& }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. rrMvaluerr"r=ct|}|r|vrdS|t||dS)Nrre)_clean_bearer_tokenaddappendr)rrrerseens rrz._device_response_token_candidates..add2s\#E**  F /vUKKKLLLLLr rd accessTokensessionzsession.access_tokenr<zdata.access_tokenzdata.accessTokenzset-auth-token)rrMrrr"r=)setrgrhr _header_value)rrrrr<rrs @@rrr#sDJDMMMMMMMC00111C txx ..///hhy!!G'4  A  "GKK$?$?@@@ 88F  D$9  .!9!9:::   7 7888C-1ABBCCC r rct|tsdS|}|dr|dd}|pdS)Nzbearer )rhrMstriplower startswith)rres rrrFse eS ! !t KKMME {{}} **"abb !! =Dr c|sdS ||}|rt|Sn#t$rYnwxYw t|D]O\}}t||kr|rt|cSPn#t tf$rYdSwxYwdSN)rgrMAttributeErrorritemsrrr)rrrrs rr r Os t  D!!  u::        w----// " "JC3xx~~4::<<//E/5zz!!! " z "tt 4s$%- ::A/B0.B00CCr(cttdt|}tj|dd|idS)Nrrrrrr)rrrrg)r(rers r_dashboard_getras\ }FGGG    & & &C 9  "3E"3"34   r ctd|}|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.)rrrrr3rhrrg)rerr<r projects_resps rr|r|ls 15 9 9D :%%&      99;;D)$55 ?488F   4D dD ! !  & $   ##3U;;M J..& +   ""$$$ Kr rcf|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$99AH999999r nonez@ Device login returned no project-valid dashboard token (tried: z).z.Photon did not return a usable dashboard token)rr|rerr'join)rdashboard_error last_error candidateexcsourcess r_validated_dashboard_tokenr(s9      ;?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')r)s rrrs8        s  )r open_browser on_user_coder,r-(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..sll4((r rNrC)newpollr) rr webbrowserrrr2r'rrr(rw) rr,r-r4target first_tokenrrers ` @rlogin_device_flowr7s  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 Photonrrr)rrrrgrrr3rerrs r get_sessionr;sk }9:::    5 5 5C 9S'%..$ ? ? ?D 99;; "r List[Dict[str, Any]]cXt|tr|St|tr}dD]z}||}t|tr|cSt|tr5dD]2}||}t|tr|ccS3{gS)N)r<projectsuserslinesr)r>r?r@r)rhrirrg)r<rinner nested_keynesteds r _unwrap_listrDs$ $ &B & &CHHSMME%&&  %&& &"I&&J"YYz22F!&$//&% & Ir cttdtd}tj|t |d}|t |S)u7GET ``/api/projects`` — return the caller's projects.Nr9 /api/projectsrrrrrrgrrrDr3r:s r list_projectsrHsn }9:::    - - -C 9S'%..$ ? ? ?D  $ $$r Optional[Dict[str, Any]]c|pd}t|D]E}|dpd|kr|cSFdS)z?Return the first project whose name matches (case-insensitive).rrN)r rrHrg)rerr5rs rfind_project_by_namerKsjb   ! ! ' ' ) )Fe$$ HHV   " ) ) + + 1 1 3 3v = =KKK > 4r z United States)rlocationrLcttdtd}||ddd}tj||t |d}||pi}t|tstd| d rtd |d | d dur'td | d p|| d }t|tr|n|}| dstd|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). Nz-httpx is required for Photon project creationrFF)rrLtemplate observabilityrr3rrz5Photon create-project returned an unexpected responserzPhoton create-project failed: succeedrr<idz1Photon create-project did not return a project id) rrrrrrr3rhrrg) rerrLrrrr<project_candidateprojects rcreate_projectrUsy }JKKK    - - -C D :cgennd K K KD 99;; "D dD ! !TRSSS xxMKDMKKLLL xx e## JTXXi-@-@-HD J J   ((3=>OQU3V3V`//\`G ;;t  PNOOO Nr cttdtd|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. Nr9rz/regenerate-secretrrPrz!Photon regenerate-secret failed: projectSecretz2Photon regenerate-secret returned no projectSecret) rrrrrrr3rgrM)rerrrr<secrets rregenerate_project_secretrY(s  }9:::    L Lj L L LC :cGENND I I ID 99;; "D xxPNtG}NNOOO XXo & &F QOPPP v;;r phonec2tjdd|pdS)z?Reduce a phone string to ``+`` and digits for dedup comparison.z[^\d+]r)resub)rZs r_normalize_phoner^?s 6)R" - --r cttdtd|d}tj|t ||d}t |dt |S)uDGET Spectrum Cloud ``/projects/{id}/users/`` → ``SpectrumUser[]``.Nr9 /projects//users/rrz list-users)rrrrgrrrDr3)rrrrs r list_usersrbDsx }9:::    < < < < 22    D dM*** 99;; "D xxJHgHHIII 88F   7txx// 74D$ K L LLr )rfrgrhTuple[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)rrfrgrhT)rerr)rrrrfrgrhexistingrs rregister_user_if_absentrvsW"*nlKKH !    D :r rcZ|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)rgrM)rrs ruser_assigned_linerys8 t ((( ) )C $3s888$r ct}|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.rbrrrrdrrxN)r;rgrhrirrM_configured_operator_phone)rj user_entriesrrZassigneds rload_user_numbersr~s < E: CCC C    NNOQR S S S44444  4sA B $BB emitc hi}trdnd|d<t\}}|r|nd|d<|rdnd|d<t\}}|r|nd|d<|r|nd|d <d d d |dzd |dzd|dzd|dzd|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 project_key3✗ missing (run `hermes photon setup --phone ...`)rrzPhoton iMessage statusuB──────────────────────z device token : z project id : z project secret : z my number : z assigned number :  N)rmrr~r")rlabelsrsecrZr}rowss rprint_credential_summaryrGs F)++ 7 6 >())HC#&833=F<,/BLL]F='))OE8QQ >K"K "# !L"VN%;;"VL%99"VM%::"VN%;;"V,C%DD D D4r cd d}d d}d d}d d}d d}|||||dS) zEReturn a fully pre-formatted credential status dict (no raw secrets).r"rMc&trdndS)Nrr)rmrr r_present_tokenz*credential_summary.._present_tokenos-// ;LL: r c,t\}}|pdS)Nrr)r_secs r_present_project_idz/credential_summary.._present_project_idus,.. T#m#r c0t\}}|rdndS)Nrrr)_sidrs r_present_secretz+credential_summary.._present_secretys ,.. c"5|| 5r c,t\}}|pdS)Nrr~)rZ _assigneds r_present_phonez*credential_summary.._present_phone}s,..yMMMr c,t\}}|pdS)Nrr)_phoner}s r_present_assigned_phonez3credential_summary.._present_assigned_phones,..DDDr )rrrrrr"rMr)rrrrrs rcredential_summaryrms    $$$$6666NNNNEEEE '(())++&((&((!8!8!:!:   r r)r"r)r"r+)r<r+r"r=)r"r`)rerMr"r=)r"r=)rerMr"rz)r"r) rrMrrMrr`rr`r"r=) rr`rr`rr`rr`r"r=)rrMrrMr"r=r)rerMr"r)rrMrrMr"r)rrr"rM)rrrrMr"r=)rrMrr`r"r) rrrrMrrrrrrr"rM)rr+rrr"ri)rrr"r`)rrrrMr"r`)r(rMrerMr"r)rerMr"r+)rrir"rM)r)r*r"r=)rrMr,rzr-r.r"rM)r<rr"r<)rerMr"r<)rerMrrMr"rI)rerMrrMrLrMr"r+)rerMrrMr"rM)rZrMr"rM)rrMrrMr"r<)rrMrrMrrMr"rI)rrMrrMrrMrfr`rgr`rhr`rirzr"r+)rrMrrMrrMrfr`rgr`rhr`r"rs)rrIr"r`)rrMrrMr"r)rrMr"r`)rerMrrMr"r<)rerMrrMrrMr"r+)rerMrrMrrzr"rI)rrr"r=)r"r)ar __future__rr3loggingrr\rQrurJbase64r dataclassesrpathlibrtypingrrr r r r rragent.secret_scoper rrrr getLoggerrr7rrDEFAULT_CLIENT_ID DEFAULT_SCOPErrDEFAULT_PROJECT_NAMErrcompileror*r;r_rmrwryr~rrrrrrrrrrrrrrrrrr rr|r(rr7r;rDrHrKrUrYr^rbrerrrvryr~rr{rrrrprintrrrr rrs##H#"""""  !!!!!!================LLLL EEEKJJJJJ??????////(  8 $ $PPPPP|PPP!& 37& "*) * * CCCC    ****Z        $0,8+/ >>>>>>H#'+/!*. 6OOOO,   $ VVVVTTTT0000//// 6 6 6 6*-4'!"/3 U8U8U8U8U8U8v"      F$@IIII>    '=A @     %%%%%# ######L..... %%%% !%#(M(M(M(M(M(M`!%#: % % % %....(....b*%%%%5?$$$$$$$?C.*/#####LsA AA